nanocoai/nanoclaw / .claude/skills/add-cursor
add-cursor
FlaggedUse Cursor (local Agent SDK) as a full agent provider — planning, tool orchestration, MCP tools, session resume — alongside or instead of Claude. Cursor-account sign-in or API key, held by the credential gateway. Per-group via `ncl groups config update --provider cursor`. Distinct from using Cursor as a cloud agent (those run on Cursor VMs and are not this provider).
payload/container/agent-runner/src/providers/cursor.ts
View on GitHub/**
* Cursor SDK agent provider — local runtime inside the container.
*
* Talks to `@cursor/sdk` (`Agent.create` / `resume` / `send`). Continuation is
* the Cursor `agentId`.
*
* Credentials never enter the container. The host passes
* `CURSOR_API_KEY=cursor_placeholder_nanoclaw` and this provider hands the
* same placeholder to the SDK, so every request the SDK authenticates with the
* user key carries `Authorization: Bearer cursor_placeholder_nanoclaw`; the
* credential gateway proxy (HTTPS_PROXY, set by the host at spawn) rewrites
* that header on its two vaulted routes — the user-key exchange
* (`api2.cursor.sh/auth/exchange_user_api_key`) and model discovery
* (`api.cursor.com/v1/models`). The exchange returns a short-lived access
* token the SDK holds in memory and sends on its Connect RPCs, which still
* transit the same proxy. How each network path reaches the proxy, and the
* one that cannot, is spelled out at `loadCursorSdk` below and proven by
* `cursor.gateway-proxy.test.ts`.
*
* This module never imports the runtime contract (provider-contracts/cursor.ts):
* registration is two-step. The contract attaches itself through
* registerProviderContract and reuses the section functions exported here.
*/
import { randomUUID } from 'crypto';
import fs from 'fs';
import http2 from 'http2';
import https from 'https';
import net from 'net';
import os from 'os';
import path from 'path';
import tls from 'tls';
import type {
AgentOptions,
McpServerConfig as CursorMcpServerConfig,
Run,
RunResult,
SDKMessage,
SettingSource,
} from '@cursor/sdk';
import { memoryContextForSessionStart, type MemorySessionHookRegistration } from '../memory/session-hook.js';
import { archiveProviderExchange } from '../provider-contracts/exchange-archive.js';
import { registerProvider } from './provider-registry.js';
import type {
AgentProvider,
AgentQuery,
McpServerConfig,
ProviderEvent,
ProviderExchange,
ProviderOptions,
QueryInput,
} from './types.js';
const CONTENT_LENGTH_FETCH = Symbol.for('nanoclaw.cursor.content-length-fetch');
type MarkedFetch = typeof fetch & { [CONTENT_LENGTH_FETCH]?: boolean };
function knownBodyLength(body: BodyInit | null | undefined): number | null {
if (body == null) return null;
if (typeof body === 'string') return new TextEncoder().encode(body).byteLength;
if (body instanceof URLSearchParams) return new TextEncoder().encode(body.toString()).byteLength;
if (body instanceof Blob) return body.size;
if (body instanceof ArrayBuffer) return body.byteLength;
if (ArrayBuffer.isView(body)) return body.byteLength;
return null;
}
/**
* Pin a Content-Length on every global-`fetch` request with a known body
* length. The SDK's user-key exchange and its cloud REST client go through
* global fetch, and those are the requests whose bearer header the credential
* gateway must rewrite; a body sent as a chunked stream is something the
* gateway has been observed to stall on rather than forward. Bun 1.3.14
* already sets Content-Length for string and byte bodies, so on a current Bun
* this is a no-op guard — it stays because the container pins its own Bun and
* the header is what the gateway needs, not the body shape. It does not reach
* the Connect RPCs: those leave through node:https (connect-node streams
* their bodies, so they arrive chunked) and carry the exchanged token, which
* the gateway forwards without rewriting.
*/
export function createContentLengthFetch(fetchImpl: typeof fetch): typeof fetch {
const wrapped = (async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
const length = knownBodyLength(init?.body);
// An init that carries headers replaces a Request's own, so start from those.
const base = init?.headers ?? (input instanceof Request ? input.headers : undefined);
const nextInit = length == null ? init : { ...init, headers: new Headers(base) };
if (length != null) {
const headers = (nextInit as RequestInit).headers as Headers;
if (!headers.has('content-length')) headers.set('content-length', String(length));
}
return fetchImpl(input, nextInit);
}) as MarkedFetch;
wrapped[CONTENT_LENGTH_FETCH] = true;
return wrapped;
}
const currentFetch = globalThis.fetch as MarkedFetch;
if ((process.env.HTTPS_PROXY || process.env.https_proxy) && !currentFetch[CONTENT_LENGTH_FETCH]) {
globalThis.fetch = createContentLengthFetch(currentFetch);
}
// ─── HTTP/2 proxy-bypass guard ──────────────────────────────────────────
const HTTP2_PROXY_GUARD = Symbol.for('nanoclaw.cursor.http2-proxy-guard');
type GuardMarked<T> = T & { [HTTP2_PROXY_GUARD]?: boolean };
export function http2ProxyBypassError(authority: string): Error {
return new Error(
`Cursor SDK attempted an HTTP/2 connection to ${authority} that would bypass the configured proxy; refusing (see /add-cursor troubleshooting)`,
);
}
interface ProxyPolicy {
/** null when HTTPS_PROXY is set but unparseable: nothing can match it. */
proxyHost: string | null;
proxyPort: string | null;
/** The proxy URL's scheme; the CONNECT tunnel speaks plain `http:` only. */
proxyProtocol: string | null;
/** Basic credentials from the proxy URL, when it has them. */
proxyAuthorization: string | null;
noProxy: string[];
}
function defaultPort(protocol: string): string {
return protocol === 'http:' ? '80' : '443';
}
function normalizeHost(host: string): string {
return host.toLowerCase().replace(/^\[(.*)\]$/, '$1');
}
/** URL userinfo is percent-encoded. Decode it so Basic matches what fetch sends. */
function proxyAuthorizationHeader(url: URL): string | null {
if (!url.username && !url.password) return null;
const decode = (value: string): string => {
try {
return decodeURIComponent(value);
} catch {
return value;
}
};
const token = Buffer.from(`${decode(url.username)}:${decode(url.password)}`, 'utf8').toString('base64');
return `Basic ${token}`;
}
function proxyPolicy(env: NodeJS.ProcessEnv): ProxyPolicy | null {
const raw = env.HTTPS_PROXY || env.https_proxy;
if (!raw) return null;
const noProxy = (env.NO_PROXY || env.no_proxy || '')
.split(',')
.map((entry) => entry.trim().toLowerCase())
.filter(Boolean);
try {
const url = new URL(raw);
return {
proxyHost: normalizeHost(url.hostname),
proxyPort: url.port || defaultPort(url.protocol),
proxyProtocol: url.protocol,
proxyAuthorization: proxyAuthorizationHeader(url),
noProxy,
};
} catch {
return { proxyHost: null, proxyPort: null, proxyProtocol: null, proxyAuthorization: null, noProxy };
}
}
/** `host`, `host:port`, `[v6]` or `[v6]:port`; a bare IPv6 address has no port. */
function noProxyEntry(entry: string): { host: string; port: string | null } {
const bracketed = /^\[([^\]]+)\](?::(\d+))?$/.exec(entry);
if (bracketed) return { host: bracketed[1], port: bracketed[2] ?? null };
const hostPort = /^([^:]+):(\d+)$/.exec(entry);
if (hostPort) return { host: hostPort[1], port: hostPort[2] };
return { host: entry, port: null };
}
/** Standard NO_PROXY semantics: `*`, exact host, or domain suffix (leading dot optional); a port limits the entry to it. */
function matchesNoProxy(host: string, port: string, noProxy: string[]): boolean {
return noProxy.some((entry) => {
if (entry === '*') return true;
const parsed = noProxyEntry(entry);
if (parsed.port !== null && parsed.port !== port) return false;
const bare = parsed.host.replace(/^\./, '');
return bare.length > 0 && (host === bare || host.endsWith(`.${bare}`));
});
}
function permitsDial(policy: ProxyPolicy, host: string, port: string | number): boolean {
const target = normalizeHost(host);
if (policy.proxyHost !== null && target === policy.proxyHost && String(port) === policy.proxyPort) return true;
return matchesNoProxy(target, String(port), policy.noProxy);
}
function wantsHttp2(protocols: unknown): boolean {
if (!Array.isArray(protocols)) return false;
return protocols.some(
(protocol) =>
(typeof protocol === 'string'
? protocol
: protocol instanceof Uint8Array
? new TextDecoder().decode(protocol)
: '') === 'h2',
);
}
/**
* Close the Cursor network paths the credential gateway would not see.
*
* Bun's `node:http2` client ignores HTTPS_PROXY, so an HTTP/2 Connect
* transport would carry the agent's runtime token straight to Cursor. While a
* proxy is configured, any HTTP/2 session to an origin other than the proxy
* itself (or a NO_PROXY host, which the operator has excluded from the proxy
* on purpose) throws `http2ProxyBypassError` instead of dialing. That path is
* not tunnelled: the refusal is the whole behaviour, and the SDK surfaces it
* as a run error.
*
* Bun 1.4's `node:https` agent has the same hole unless `NODE_USE_ENV_PROXY`
* was set when the process started, which the container does not do.
* `@connectrpc/connect-node` sends its HTTP/1.1 RPCs through that agent, and
* `https.Agent.createConnection` then calls `tls.connect` straight at the
* origin. While a proxy is configured, that one method is wrapped to open a
* CONNECT tunnel and start TLS on the tunnel socket, so those RPCs reach the
* gateway instead of Cursor's address.
*
* Three hooks, because of how Bun binds builtins:
*
* - `http2.connect` on the module object. A builtin's ESM namespace is a
* snapshot taken when the first `import` of it evaluates, so this wrap
* only reaches importers loaded after it. In the agent-runner the Claude
* SDK imports http2 before the provider barrel reaches this module, so
* `@connectrpc/connect-node` (the SDK's HTTP/2 session manager, the only
* `http2.connect` caller in the Cursor stack) keeps the original in
* production. Kept for the callers it does bind and for the clearest
* error at the earliest point.
* - `tls.connect`. Bun's http2 client resolves it from the module object at
* dial time with `ALPNProtocols: ['h2']`, so this hook holds whatever the
* load order, and a throw here propagates synchronously out of
* `http2.connect`. A handshake over a socket the caller already opened is
* left alone: that is the HTTP/1.1 tunnel finishing, not a new TCP dial.
* - `https.Agent.createConnection`. This is the Bun 1.4 `node:https` dial
* described above. It returns no socket of its own; the agent waits on
* the callback, which fires with a TLS socket only after CONNECT
* succeeds.
*
* Returns null when no proxy is configured (nothing installed, local runs
* without the gateway behave exactly as before), otherwise a restore function
* for tests. Idempotent: a marker symbol on each wrapped function prevents
* double wrapping.
*/
export function installHttp2ProxyGuard(env: NodeJS.ProcessEnv = process.env): (() => void) | null {
const policy = proxyPolicy(env);
if (!policy) return null;
const restores: Array<() => void> = [];
const http2Module = http2 as { connect: GuardMarked<typeof http2.connect> };
const originalConnect = http2Module.connect;
if (!originalConnect[HTTP2_PROXY_GUARD]) {
const guardedConnect = function (this: unknown, authority: string | URL, ...rest: unknown[]) {
const url = typeof authority === 'string' ? new URL(authority) : authority;
if (!permitsDial(policy, url.hostname, url.port || defaultPort(url.protocol))) {
throw http2ProxyBypassError(typeof authority === 'string' ? authority : authority.href);
}
return (originalConnect as unknown as (...args: unknown[]) => http2.ClientHttp2Session).apply(this, [
authority,
...rest,
]);
} as unknown as GuardMarked<typeof http2.connect>;
guardedConnect[HTTP2_PROXY_GUARD] = true;
http2Module.connect = guardedConnect;
restores.push(() => {
http2Module.connect = originalConnect;
});
}
const tlsModule = tls as { connect: GuardMarked<typeof tls.connect> };
const originalTlsConnect = tlsModule.connect;
if (!originalTlsConnect[HTTP2_PROXY_GUARD]) {
const guardedTlsConnect = function (this: unknown, ...args: unknown[]) {
const options = args.find((arg) => arg !== null && typeof arg === 'object' && !Array.isArray(arg)) as
| tls.ConnectionOptions
| undefined;
if (options?.socket) {
return (originalTlsConnect as unknown as (...connectArgs: unknown[]) => tls.TLSSocket).apply(this, args);
}
if (options && wantsHttp2(options.ALPNProtocols)) {
const host = options.host ?? (typeof args[1] === 'string' ? args[1] : 'localhost');
const port = options.port ?? (typeof args[0] === 'number' ? args[0] : '');
if (!permitsDial(policy, host, port)) throw http2ProxyBypassError(`https://${host}:${port}`);
}
return (originalTlsConnect as unknown as (...connectArgs: unknown[]) => tls.TLSSocket).apply(this, args);
} as unknown as GuardMarked<typeof tls.connect>;
guardedTlsConnect[HTTP2_PROXY_GUARD] = true;
tlsModule.connect = guardedTlsConnect;
restores.push(() => {
tlsModule.connect = originalTlsConnect;
});
}
// Bun 1.3's HTTPS agent has no `createConnection` and already honors
// HTTPS_PROXY. Bun 1.4 added the method and, without NODE_USE_ENV_PROXY at
// process start, it dials the origin. Wrap only the method that exists.
const httpsAgent = https.Agent.prototype as {
createConnection?: GuardMarked<typeof https.Agent.prototype.createConnection>;
};
const originalCreateConnection = httpsAgent.createConnection;
if (originalCreateConnection && !originalCreateConnection[HTTP2_PROXY_GUARD]) {
const guardedCreateConnection = function (this: https.Agent, ...args: unknown[]) {
const parsed = httpsConnectionArgs(args);
if (!parsed?.callback) return originalCreateConnection.apply(this, args as never);
const target = dialTarget(parsed.options);
if (permitsDial(policy, target.host, target.port)) return originalCreateConnection.apply(this, args as never);
if (!policy.proxyHost || !policy.proxyPort) {
parsed.callback(
new Error(
`Cursor SDK attempted an HTTPS connection to https://${target.host}:${target.port} that would bypass the configured proxy; refusing (see /add-cursor troubleshooting)`,
),
);
return undefined;
}
connectViaHttpProxy(policy, parsed.options, target, parsed.callback);
return undefined;
} as unknown as GuardMarked<typeof https.Agent.prototype.createConnection>;
guardedCreateConnection[HTTP2_PROXY_GUARD] = true;
httpsAgent.createConnection = guardedCreateConnection;
restores.push(() => {
httpsAgent.createConnection = originalCreateConnection;
});
}
return () => {
for (const restore of restores.reverse()) restore();
};
}
interface HttpsConnectArgs {
options: tls.ConnectionOptions & { hostname?: string };
callback: (err: Error | null, socket?: tls.TLSSocket) => void;
}
function httpsConnectionArgs(args: unknown[]): HttpsConnectArgs | null {
const last = args[args.length - 1];
if (typeof last !== 'function') return null;
const options = args.find((arg) => arg !== null && typeof arg === 'object' && !Array.isArray(arg)) as
| (tls.ConnectionOptions & { hostname?: string })
| undefined;
if (!options) return null;
return { options, callback: last as HttpsConnectArgs['callback'] };
}
function dialTarget(options: tls.ConnectionOptions & { hostname?: string }): { host: string; port: string } {
const host = options.host || options.hostname || options.servername || 'localhost';
const port = options.port == null ? '443' : String(options.port);
return { host, port };
}
/**
* Bun's HTTPS agent calls this instead of dialing. CONNECT to the proxy, then
* hand the agent a TLS socket over that tunnel. Returning no socket is what
* makes the agent wait: it only adopts the socket from the callback when
* `createConnection` returns nothing (or a socket marked as waiting on a
* tunnel). The callback fires once, after the proxy's `200`, with the TLS
* handshake still ahead of it.
*/
function connectViaHttpProxy(
policy: ProxyPolicy,
options: tls.ConnectionOptions,
target: { host: string; port: string },
callback: (err: Error | null, socket?: tls.TLSSocket) => void,
): void {
const authority = `${target.host}:${target.port}`;
if (policy.proxyProtocol !== 'http:') {
// CONNECT and any Proxy-Authorization would cross a TLS proxy's port in the clear.
const err = new Error(`Cursor SDK proxy tunnel to ${authority} needs an http:// proxy URL; refusing`);
process.nextTick(() => callback(err));
return;
}
const proxySocket = net.connect({ host: policy.proxyHost!, port: Number(policy.proxyPort) });
let settled = false;
const fail = (err: Error): void => {
if (settled) return;
settled = true;
proxySocket.destroy();
callback(err);
};
const onClose = (): void =>
fail(new Error(`Cursor SDK proxy tunnel to ${authority} closed before answering CONNECT`));
proxySocket.on('error', fail);
proxySocket.once('close', onClose);
let buffered = Buffer.alloc(0);
proxySocket.on('data', function onData(chunk: Buffer) {
buffered = Buffer.concat([buffered, chunk]);
const end = buffered.indexOf('\r\n\r\n');
if (end === -1) return;
proxySocket.off('data', onData);
const status = buffered.subarray(0, buffered.indexOf('\r\n')).toString('latin1');
if (!/^HTTP\/1\.[01] 200\b/.test(status)) {
fail(new Error(`Cursor SDK proxy tunnel to ${authority} failed: ${status}`));
return;
}
if (settled) return;
settled = true;
proxySocket.off('error', fail);
proxySocket.off('close', onClose);
const rest = buffered.subarray(end + 4);
if (rest.length > 0) proxySocket.unshift(rest);
const tlsOptions: tls.ConnectionOptions = {
socket: proxySocket,
servername: options.servername || target.host,
};
if (options.ALPNProtocols !== undefined) tlsOptions.ALPNProtocols = options.ALPNProtocols;
if (options.rejectUnauthorized !== undefined) tlsOptions.rejectUnauthorized = options.rejectUnauthorized;
if (options.ca !== undefined) tlsOptions.ca = options.ca;
if (options.cert !== undefined) tlsOptions.cert = options.cert;
if (options.key !== undefined) tlsOptions.key = options.key;
if (options.session !== undefined) tlsOptions.session = options.session;
if (options.checkServerIdentity !== undefined) tlsOptions.checkServerIdentity = options.checkServerIdentity;
try {
callback(null, tls.connect(tlsOptions));
} catch (err) {
proxySocket.destroy();
callback(err instanceof Error ? err : new Error(String(err)));
}
});
proxySocket.on('connect', () => {
// Bun's fetch sends the proxy URL's userinfo. This tunnel has to do the
// same, or an authenticating proxy rejects the agent RPC.
const lines = [`CONNECT ${authority} HTTP/1.1`, `Host: ${authority}`];
if (policy.proxyAuthorization) lines.push(`Proxy-Authorization: ${policy.proxyAuthorization}`);
proxySocket.write(`${lines.join('\r\n')}\r\n\r\n`);
});
}
let cursorSdkPromise: Promise<typeof import('@cursor/sdk')> | undefined;
/**
* How Cursor traffic reaches the credential gateway proxy (Bun runtime):
*
* - user-key exchange + cloud REST: the SDK calls global `fetch`, and Bun's
* fetch honors HTTPS_PROXY / https_proxy (CONNECT to the proxy) and the
* gateway's CA bundle (SSL_CERT_FILE / NODE_EXTRA_CA_CERTS).
* - Connect RPCs (agent runtime): `@connectrpc/connect-node` over
* HTTP/1.1, which is `node:https`. Bun 1.4's HTTPS agent dials the origin
* directly unless NODE_USE_ENV_PROXY was set at process start, so
* `installHttp2ProxyGuard` tunnels `https.Agent.createConnection` through
* the proxy before the TLS handshake.
* - Connect RPCs over HTTP/2: `node:http2` in Bun ignores HTTPS_PROXY and
* would dial the backend directly. The SDK already defaults to HTTP/1.1
* under Bun and `useHttp1ForAgent: true` pins that choice, but Cursor's
* server-side `http2Config` force flag is applied over the client setting
* and the SDK exports no transport factory to swap. So the path is closed
* client-side instead: `installHttp2ProxyGuard` runs here, before the SDK
* loads, and while a proxy is configured every HTTP/2 session to an
* origin other than the proxy is refused with a clear error rather than
* dialed (details on the guard). `cursor.gateway-proxy.test.ts` proves
* both the happy path and the refusal when the server forces HTTP/2.
*
* The client-side guard is one layer. The operator-side layer is core's
* `NANOCLAW_EGRESS_LOCKDOWN=true`: the container joins an internal Docker
* network whose only hop is the gateway, so any bypass attempt fails at the
* network as well.
*/
async function loadCursorSdk(): Promise<typeof import('@cursor/sdk')> {
cursorSdkPromise ??= (async () => {
installHttp2ProxyGuard();
const sdk = await import('@cursor/sdk');
sdk.Cursor.configure({ local: { useHttp1ForAgent: true } });
return sdk;
})();
return cursorSdkPromise;
}
/** Sentinel so the SDK always sends Authorization for the gateway to overwrite. */
export const CURSOR_API_KEY_PLACEHOLDER = 'cursor_placeholder_nanoclaw';
/**
* Built-in Cursor tools that stall a headless session or bypass NanoClaw
* `ask_user_question`. `task` is included because `disallowedTools` applies
* only to the main loop — subagents keep their own toolset and could still
* call `askQuestion`.
*/
export const CURSOR_DISALLOWED_TOOLS: Array<'askQuestion' | 'await' | 'task'> = ['askQuestion', 'await', 'task'];
export const CURSOR_DEFAULT_MODEL = 'composer-2.5';
export const CURSOR_MEMORY_HOOK_COMMAND = 'bun /app/src/providers/cursor-hook.ts';
const STALE_SESSION_RE = /agent not found|unknown agent|no conversation|session.*not found/i;
const ACTIVE_RUN_RE = /already has (?:an )?active run/i;
/**
* SDK entry points, overridable in unit tests so a fake Agent can drive
* event mapping without `mock.module` leaking into the barrel registration test.
*/
export const cursorAgentApi = {
create: async (options: AgentOptions) => (await loadCursorSdk()).Agent.create(options),
resume: async (agentId: string, options: AgentOptions) => (await loadCursorSdk()).Agent.resume(agentId, options),
};
function log(msg: string): void {
console.error(`[cursor-provider] ${msg}`);
}
function cursorHome(): string {
return path.join(process.env.HOME || os.homedir(), '.cursor');
}
function agentRoot(): string {
return process.env.NANOCLAW_AGENT_DIR || '/workspace/agent';
}
// ─── configuration sections ─────────────────────────────────────────────
// Per-capability plan functions. The runtime contract declares these same
// functions (or their constant results); the legacy path (a core without the
// contract seam) calls them from the constructor. Both land on the same
// AgentOptions.
export interface CursorExecutionPolicy {
disallowedTools: Array<'askQuestion' | 'await' | 'task'>;
/**
* Project + user layers. Container HOME is the per-group `.cursor-shared`
* mount, not a desktop Cursor install, so `"user"` loads persistent
* ~/.cursor/skills and hooks.json. Inline MCP still wins.
*/
settingSources: SettingSource[];
/** The container is the sandbox; Cursor's own is off. */
sandbox: { enabled: false };
}
export function cursorExecutionPolicySection(): CursorExecutionPolicy {
return {
disallowedTools: [...CURSOR_DISALLOWED_TOOLS],
settingSources: ['project', 'user'],
sandbox: { enabled: false },
};
}
export interface CursorInference {
model: { id: string };
}
/**
* Cursor's `ModelSelection` is `{ id, params? }` where `params` are
* per-model parameter values only discoverable from the live model catalogue,
* so the core `effort` and `speed` inputs have no honest mapping here and are
* ignored; the host contract declares no speed tiers for the same reason.
*/
export function cursorInferenceSection(input: { model?: string; effort?: string; speed?: string }): CursorInference {
return { model: { id: input.model || CURSOR_DEFAULT_MODEL } };
}
export interface CursorMemoryHooks {
version: 1;
hooks: {
sessionStart: Array<{ command: string }>;
preCompact: Array<{ command: string }>;
};
}
/**
* The Cursor-native hooks that feed shared memory into a session. They run
* `cursor-hook.ts`, which reads the memory tree directly, so they do not
* depend on the hook command core registers — a declared constant.
*/
export function cursorMemorySection(): CursorMemoryHooks {
return {
version: 1,
hooks: {
sessionStart: [{ command: CURSOR_MEMORY_HOOK_COMMAND }],
preCompact: [{ command: `${CURSOR_MEMORY_HOOK_COMMAND} --compact` }],
},
};
}
export function mapMcpServers(servers: Record<string, McpServerConfig>): Record<string, CursorMcpServerConfig> {
return Object.fromEntries(
Object.entries(servers).map(([name, server]) => {
if (server.type === 'http') {
return [name, { type: 'http' as const, url: server.url, headers: server.headers ?? {} }];
}
return [
name,
{
type: 'stdio' as const,
command: server.command,
args: server.args ?? [],
env: server.env ?? {},
...(server.cwd ? { cwd: server.cwd } : {}),
},
];
}),
);
}
export const cursorMcpServersSection = mapMcpServers;
/**
* Mixed-version ownership of the hooks.json writes. When the runtime contract
* module loads it flips this flag: core then runs the contract's
* memorySessionHookRegistration callback, so the provider's own write in
* registerMemorySessionHook stands down instead of writing the files twice.
*/
export const cursorRuntimeOwnership = { contractOwnsHookFiles: false };
// ─── stream helpers ─────────────────────────────────────────────────────
export function extractAssistantText(event: SDKMessage): string {
if (event.type !== 'assistant') return '';
const blocks = event.message?.content ?? [];
return blocks
.filter((block): block is { type: 'text'; text: string } => block.type === 'text' && typeof block.text === 'string')
.map((block) => block.text)
.join('');
}
export function toolProgressMessage(event: SDKMessage): string | null {
if (event.type !== 'tool_call') return null;
const name = event.name || 'tool';
if (event.status === 'running') return `${name}…`;
if (event.status === 'error') return `${name} failed`;
return null;
}
export async function* waitForRunWithActivity(
run: Pick<Run, 'wait'>,
heartbeatMs = 15_000,
): AsyncGenerator<ProviderEvent, RunResult> {
type WaitOutcome = { result: RunResult } | { error: unknown };
const completion: Promise<WaitOutcome> = run.wait().then(
(result): WaitOutcome => ({ result }),
(error: unknown): WaitOutcome => ({ error }),
);
while (true) {
let timer: ReturnType<typeof setTimeout> | undefined;
const heartbeat = new Promise<null>((resolve) => {
timer = setTimeout(() => resolve(null), heartbeatMs);
});
const outcome = await Promise.race([completion, heartbeat]);
if (outcome === null) {
yield { type: 'activity' };
continue;
}
if (timer) clearTimeout(timer);
if ('error' in outcome) throw outcome.error;
return outcome.result;
}
}
// ─── hooks.json ─────────────────────────────────────────────────────────
interface CursorHooksDocument {
version?: unknown;
hooks?: Record<string, unknown>;
[key: string]: unknown;
}
function readHooksDocument(filePath: string): CursorHooksDocument | null {
if (!fs.existsSync(filePath)) return {};
try {
const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8')) as unknown;
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed as CursorHooksDocument;
log(`Leaving non-object Cursor hooks document unchanged at ${filePath}`);
} catch (err) {
log(
`Leaving malformed Cursor hooks document unchanged at ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
);
}
return null;
}
function mergeMemoryHooks(filePath: string, memory: CursorMemoryHooks): void {
const payload = readHooksDocument(filePath);
if (!payload) return;
const hooks =
payload.hooks && typeof payload.hooks === 'object' && !Array.isArray(payload.hooks) ? payload.hooks : {};
for (const [name, entries] of Object.entries(memory.hooks)) {
const existing = Array.isArray(hooks[name]) ? hooks[name] : [];
const ours = new Set(entries.map((entry) => entry.command));
hooks[name] = [
...existing.filter(
(entry) =>
!entry ||
typeof entry !== 'object' ||
!('command' in entry) ||
!ours.has((entry as { command?: unknown }).command as string),
),
...entries,
];
}
payload.version = memory.version;
payload.hooks = hooks;
// Write into a fresh, unpredictable sibling and rename over the target: the
// hooks file is inside directories the agent can write, so the temp path
// must not be one an earlier process could have planted a symlink at.
const tempPath = `${filePath}.${randomUUID()}.tmp`;
try {
fs.writeFileSync(tempPath, JSON.stringify(payload, null, 2) + '\n', { flag: 'wx' });
fs.renameSync(tempPath, filePath);
} finally {
fs.rmSync(tempPath, { force: true });
}
}
/**
* Merge the shared-memory hooks into Cursor's project (`<agent>/.cursor`) and
* user (`~/.cursor`) hooks.json — idempotent, preserving unrelated hooks. The
* contract's memorySessionHookRegistration callback calls this on a contract
* core; the provider calls it itself on a pre-contract core.
*/
export function writeCursorMemoryHooks(memory: CursorMemoryHooks = cursorMemorySection()): void {
const projectDir = path.join(agentRoot(), '.cursor');
fs.mkdirSync(projectDir, { recursive: true });
mergeMemoryHooks(path.join(projectDir, 'hooks.json'), memory);
const userDir = cursorHome();
fs.mkdirSync(userDir, { recursive: true });
mergeMemoryHooks(path.join(userDir, 'hooks.json'), memory);
}
/**
* A failed turn. `error` is the channel notice on a core that has it;
* older cores type the result without that field, so it is attached
* without changing the declared event type. `text` stays model output.
*/
function failedResult(error: string, text: string | null = null): ProviderEvent {
return { type: 'result', text, isError: true, error } as ProviderEvent;
}
/**
* Cursor keeps its history in the SDK's local agent store, not a transcript,
* so each exchange is persisted into `conversations/` through the shared
* archive plan. The contract's afterExchange calls this with core's clock; the
* provider's own onExchangeComplete is the pre-contract fallback.
*/
export function archiveCursorExchange(exchange: ProviderExchange, timestamp?: Date): string | null {
try {
return archiveProviderExchange({
provider: 'cursor',
prompt: exchange.prompt,
result: exchange.result,
continuation: exchange.continuation,
status: exchange.status,
timestamp,
});
} catch (err) {
log(`Failed to archive exchange: ${err instanceof Error ? err.message : String(err)}`);
return null;
}
}
/**
* Structural mirror of the contract core's `ResolvedRuntimeConfiguration` —
* what `createProvider` hands the factory after running the contract's
* configuration resolves. Mirrored, not imported: the type lives in
* `provider-contracts/registry.ts`, which a pre-contract core does not have.
*/
export interface CursorResolvedConfiguration {
executionPolicy?: unknown;
inference?: unknown;
mcpServers?: unknown;
/**
* Core passes this when the contract declares `configuration.tone`.
* Cursor has no native tone control, so the provider declares none and
* ignores the field. It stays on the mirror so this factory still accepts
* the current resolved configuration.
*/
tone?: Record<string, unknown>;
}
export class CursorProvider implements AgentProvider {
readonly supportsNativeSlashCommands = false;
readonly emitsMidTurnText = true;
private readonly assistantName?: string;
private readonly additionalDirectories?: string[];
private readonly executionPolicy: CursorExecutionPolicy;
private readonly inference: CursorInference;
private readonly mcpServers: Record<string, CursorMcpServerConfig>;
private memorySessionHook?: MemorySessionHookRegistration;
/**
* `configuration` is present on a contract core: core has already run the
* contract's resolves and hands the results over, so they are consumed
* as-is. Without it (a pre-contract core) the provider derives the same
* values itself from the options, exactly as it always did.
*/
constructor(options: ProviderOptions = {}, configuration?: CursorResolvedConfiguration) {
this.assistantName = options.assistantName;
this.additionalDirectories = options.additionalDirectories;
if (configuration) {
this.executionPolicy = configuration.executionPolicy as CursorExecutionPolicy;
this.inference = configuration.inference as CursorInference;
this.mcpServers = configuration.mcpServers as Record<string, CursorMcpServerConfig>;
} else {
this.executionPolicy = cursorExecutionPolicySection();
// `speed` exists on ProviderOptions only from the contract core on; read
// it structurally so this compiles against the older options type too.
const { speed } = options as ProviderOptions & { speed?: string };
this.inference = cursorInferenceSection({ model: options.model, effort: options.effort, speed });
this.mcpServers = mapMcpServers(options.mcpServers ?? {});
}
}
registerMemorySessionHook(hook: MemorySessionHookRegistration): void {
// On a contract core the contract's memorySessionHookRegistration has
// already written both hooks.json files (see cursorRuntimeOwnership).
if (!cursorRuntimeOwnership.contractOwnsHookFiles) writeCursorMemoryHooks();
this.memorySessionHook = hook;
}
isSessionInvalid(err: unknown): boolean {
if (err instanceof Error && err.name === 'AgentNotFoundError') return true;
const msg = err instanceof Error ? err.message : String(err);
return STALE_SESSION_RE.test(msg);
}
// A contract core replaces this with the contract's afterExchange at the
// factory boundary; a pre-contract core calls it directly.
onExchangeComplete(exchange: ProviderExchange): void {
archiveCursorExchange(exchange);
}
// Protected so the gateway probe can tune the SDK options for its one run.
protected agentOptions(cwd: string): AgentOptions {
return {
apiKey: CURSOR_API_KEY_PLACEHOLDER,
name: this.assistantName,
model: this.inference.model,
mcpServers: this.mcpServers,
disallowedTools: [...this.executionPolicy.disallowedTools],
local: {
cwd,
dirs: this.additionalDirectories,
settingSources: [...this.executionPolicy.settingSources],
sandboxOptions: { enabled: this.executionPolicy.sandbox.enabled },
},
};
}
query(input: QueryInput): AgentQuery {
if (!this.memorySessionHook) throw new Error('Cursor memory session hook was not registered');
let aborted = false;
let currentRun: Run | null = null;
let cancelPromise: Promise<void> | null = null;
let acceptingInput = true;
const pendingPrompts = [input.prompt];
const options = this.agentOptions(input.cwd);
const isInvalidSession = (err: unknown): boolean => this.isSessionInvalid(err);
let injectedMemory = false;
const withSystemInstructions = (prompt: string): string => {
const parts: string[] = [];
if (input.systemContext?.instructions) parts.push(input.systemContext.instructions);
// Cursor's sessionStart hook is documented as fire-and-forget; live runs
// confirm additional_context does not land in the model. Prepend the
// shared memory index on the first send of a new session. Resumes already
// have that context, and follow-up pushes skip it.
if (!injectedMemory) {
const memory = memoryContextForSessionStart(input.continuation ? 'resume' : 'startup', input.cwd);
if (memory) parts.push(memory);
injectedMemory = true;
}
parts.push(prompt);
return parts.join('\n\n');
};
const cancelCurrentRun = (): Promise<void> => {
if (!currentRun?.supports('cancel')) return Promise.resolve();
if (cancelPromise) return cancelPromise;
try {
cancelPromise = currentRun.cancel().catch((err) => {
log(`Failed to cancel run: ${err instanceof Error ? err.message : String(err)}`);
});
} catch (err) {
log(`Failed to cancel run: ${err instanceof Error ? err.message : String(err)}`);
cancelPromise = Promise.resolve();
}
return cancelPromise;
};
async function* translateEvents(): AsyncGenerator<ProviderEvent> {
let agent: Awaited<ReturnType<(typeof cursorAgentApi)['create']>> | null = null;
try {
agent = input.continuation
? await cursorAgentApi.resume(input.continuation, options)
: await cursorAgentApi.create(options);
if (aborted) return;
yield { type: 'init', continuation: agent.agentId };
while (!aborted && pendingPrompts.length > 0) {
const prompt = pendingPrompts.shift()!;
yield { type: 'activity' };
if (aborted) return;
const preparedPrompt = withSystemInstructions(prompt);
let run: Run;
try {
run = await agent.send(preparedPrompt);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
if (!ACTIVE_RUN_RE.test(message)) throw err;
log('Expiring stale active Cursor run and retrying the message');
run = await agent.send(preparedPrompt, { local: { force: true } });
}
currentRun = run;
cancelPromise = null;
if (aborted) {
await cancelCurrentRun();
return;
}
let streamed = '';
if (run.supports('stream')) {
for await (const event of run.stream()) {
if (aborted) {
await cancelCurrentRun();
return;
}
yield { type: 'activity' };
const text = extractAssistantText(event);
streamed += text;
if (text) yield { type: 'text', text };
const progress = toolProgressMessage(event);
if (progress) yield { type: 'progress', message: progress };
}
}
const waitEvents = waitForRunWithActivity(run);
let result: RunResult;
while (true) {
const next = await waitEvents.next();
if (next.done) {
result = next.value;
break;
}
if (aborted) {
await cancelCurrentRun();
return;
}
yield next.value;
}
currentRun = null;
cancelPromise = null;
if (aborted) return;
if (result.status === 'cancelled') {
yield { type: 'error', message: 'Cancelled', retryable: false };
yield failedResult('Cancelled');
return;
} else if (result.status === 'error') {
// `text` is model output. The channel notice comes from `error`,
// which the poll-loop delivers as is, so model text (which may
// hold scratchpad) never becomes it.
const notice = result.error?.message || 'Cursor run failed';
yield failedResult(notice, result.result || streamed || null);
} else {
yield { type: 'result', text: result.result ?? (streamed || null) };
}
}
} catch (err) {
if (aborted) return;
if (input.continuation && isInvalidSession(err)) throw err;
const { CursorAgentError } = await loadCursorSdk();
if (err instanceof CursorAgentError) {
yield {
type: 'error',
message: err.message,
retryable: err.isRetryable,
classification: err.code,
};
yield failedResult(err.message);
return;
}
const message = err instanceof Error ? err.message : String(err);
yield {
type: 'error',
message,
retryable: false,
};
yield failedResult(message);
} finally {
acceptingInput = false;
currentRun = null;
try {
agent?.close();
} catch (err) {
log(`Failed to close agent: ${err instanceof Error ? err.message : String(err)}`);
}
}
}
return {
push(message) {
if (acceptingInput && !aborted) pendingPrompts.push(message);
},
end() {
acceptingInput = false;
},
events: translateEvents(),
abort() {
aborted = true;
void cancelCurrentRun();
},
};
}
}
// Function-form registration only — the one shape both core generations
// accept. A contract core passes the resolved configuration as the second
// argument; a pre-contract core passes nothing there.
registerProvider(
'cursor',
(opts, configuration?: CursorResolvedConfiguration) => new CursorProvider(opts, configuration),
);
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |