@velum-labs/routekit-tool-cursor 0.9.0

package/dist/driver.js

@@ -0,0 +1,429 @@
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { z } from "zod";
+import { ClientSideConnection, PROTOCOL_VERSION, ndJsonStream } from "@zed-industries/agent-client-protocol";
+import { AsyncChannel, HarnessError, DEFAULT_AUTOMATION_APPROVAL_POLICY, PendingRequests, asHarnessError, buildChildEnv, createCachedHarnessDriver, decideApproval, probeCliVersion, resolveDriverEnv, terminate } from "@velum-labs/routekit-harness-core";
+const RESUME_CURSOR_VERSION = 1;
+const DEFAULT_COMMAND = "cursor-agent";
+const AUTH_METHOD_ID = "cursor_login";
+export const cursorDriverConfigSchema = z.object({
+    command: z.string().default(DEFAULT_COMMAND),
+    /** OpenAI-compatible endpoint cursor-agent's model calls route to (the gateway/bridge). */
+    endpoint: z.string().optional(),
+    model: z.string().optional()
+});
+function nowIso() {
+    return new Date().toISOString();
+}
+function cursorReasoningEffort(reasoning) {
+    if (reasoning === undefined || reasoning.mode === "auto")
+        return undefined;
+    if (reasoning.mode === "effort")
+        return reasoning.effort;
+    throw new HarnessError("invalid_config", `Cursor ACP cannot represent reasoning mode "${reasoning.mode}"`);
+}
+/** Map an ACP tool kind onto the canonical item type. */
+function itemTypeForToolKind(kind) {
+    switch (kind) {
+        case "execute":
+            return "command_execution";
+        case "edit":
+        case "delete":
+        case "move":
+            return "file_change";
+        case "search":
+        case "fetch":
+            return "web_search";
+        default:
+            return "dynamic_tool_call";
+    }
+}
+/** Map an ACP permission option kind onto our approval decision. */
+function decisionForOptionKind(kind) {
+    switch (kind) {
+        case "allow_always":
+            return "acceptForSession";
+        case "allow_once":
+            return "accept";
+        case "reject_always":
+        case "reject_once":
+            return "decline";
+        default:
+            return "decline";
+    }
+}
+/** The request type an ACP permission maps to, from its tool-call kind. */
+function requestTypeForToolKind(kind) {
+    switch (kind) {
+        case "execute":
+            return "exec_command_approval";
+        case "edit":
+        case "delete":
+        case "move":
+            return "file_change_approval";
+        default:
+            return "tool_approval";
+    }
+}
+class CursorSession {
+    #kind = "cursor";
+    #child;
+    #connection;
+    #pending = new PendingRequests();
+    #approvalPolicy;
+    #reasoning;
+    #optionKindById = new Map();
+    #sessionId;
+    #channel;
+    #turnId;
+    #openItems = new Set();
+    #stopped = false;
+    constructor(input) {
+        this.#child = input.child;
+        this.#connection = input.connection;
+        this.#sessionId = input.sessionId;
+        this.#approvalPolicy = input.approvalPolicy;
+        this.#reasoning = input.reasoning;
+    }
+    get sessionId() {
+        return this.#sessionId;
+    }
+    /** Fed by the ACP Client handler (see makeClient) for every session update. */
+    ingestUpdate(params) {
+        const channel = this.#channel;
+        if (channel === undefined)
+            return;
+        const update = params.update;
+        const base = {
+            kind: this.#kind,
+            sessionId: this.#sessionId,
+            at: nowIso(),
+            ...(this.#turnId !== undefined ? { turnId: this.#turnId } : {})
+        };
+        const raw = { source: "acp.session.update", method: update.sessionUpdate };
+        switch (update.sessionUpdate) {
+            case "agent_message_chunk":
+                if (update.content.type === "text") {
+                    channel.push({ ...base, type: "content.delta", stream: "assistant_text", text: update.content.text, raw });
+                }
+                return;
+            case "agent_thought_chunk":
+                if (update.content.type === "text") {
+                    channel.push({ ...base, type: "content.delta", stream: "reasoning_text", text: update.content.text, raw });
+                }
+                return;
+            case "tool_call": {
+                const itemType = itemTypeForToolKind(update.kind);
+                this.#openItems.add(update.toolCallId);
+                channel.push({
+                    ...base,
+                    type: "item.started",
+                    itemId: update.toolCallId,
+                    itemType,
+                    ...(update.title !== undefined ? { title: update.title } : {}),
+                    raw
+                });
+                return;
+            }
+            case "tool_call_update": {
+                if (update.status === "completed" || update.status === "failed") {
+                    if (this.#openItems.delete(update.toolCallId)) {
+                        channel.push({
+                            ...base,
+                            type: "item.completed",
+                            itemId: update.toolCallId,
+                            itemType: itemTypeForToolKind(update.kind),
+                            status: update.status === "failed" ? "failed" : "completed",
+                            raw
+                        });
+                    }
+                }
+                return;
+            }
+            case "user_message_chunk":
+            case "plan":
+            case "available_commands_update":
+            case "current_mode_update":
+                return;
+            default: {
+                const exhausted = update;
+                throw new Error(`unsupported ACP session update: ${String(exhausted)}`);
+            }
+        }
+    }
+    /** Fed by the ACP Client handler for permission requests. */
+    async requestPermission(params) {
+        const kind = params.toolCall.kind;
+        const requestType = requestTypeForToolKind(kind);
+        for (const option of params.options)
+            this.#optionKindById.set(option.optionId, option.kind);
+        const auto = decideApproval(this.#approvalPolicy, requestType);
+        const decision = auto ?? (await this.#surface(params, requestType));
+        if (decision === "decline" || decision === "cancel") {
+            const reject = params.options.find((option) => option.kind === "reject_once" || option.kind === "reject_always");
+            return reject !== undefined
+                ? { outcome: { outcome: "selected", optionId: reject.optionId } }
+                : { outcome: { outcome: "cancelled" } };
+        }
+        const preferredKind = decision === "acceptForSession" ? "allow_always" : "allow_once";
+        const option = params.options.find((entry) => entry.kind === preferredKind) ??
+            params.options.find((entry) => entry.kind === "allow_once" || entry.kind === "allow_always");
+        return option !== undefined
+            ? { outcome: { outcome: "selected", optionId: option.optionId } }
+            : { outcome: { outcome: "cancelled" } };
+    }
+    async #surface(params, requestType) {
+        const channel = this.#channel;
+        const request = this.#pending.open({
+            requestType,
+            ...(params.toolCall.title !== undefined && params.toolCall.title !== null
+                ? { detail: params.toolCall.title }
+                : {})
+        });
+        if (channel !== undefined) {
+            channel.push({
+                kind: this.#kind,
+                sessionId: this.#sessionId,
+                at: nowIso(),
+                ...(this.#turnId !== undefined ? { turnId: this.#turnId } : {}),
+                type: "request.opened",
+                requestId: request.requestId,
+                requestType,
+                ...(request.detail !== undefined ? { detail: request.detail } : {}),
+                raw: { source: "acp.request.permission" }
+            });
+        }
+        const decision = await request.decision;
+        if (channel !== undefined) {
+            channel.push({
+                kind: this.#kind,
+                sessionId: this.#sessionId,
+                at: nowIso(),
+                ...(this.#turnId !== undefined ? { turnId: this.#turnId } : {}),
+                type: "request.resolved",
+                requestId: request.requestId,
+                decision,
+                raw: { source: "acp.request.permission" }
+            });
+        }
+        return decision;
+    }
+    async *sendTurn(input) {
+        if (this.#stopped)
+            throw new HarnessError("session_closed", "cursor session is stopped");
+        const channel = new AsyncChannel();
+        this.#channel = channel;
+        this.#turnId = `${this.#sessionId}:turn:${Date.now()}`;
+        const turnId = this.#turnId;
+        const base = { kind: this.#kind, sessionId: this.#sessionId, at: nowIso(), turnId };
+        channel.push({ ...base, type: "turn.started" });
+        // An already-aborted turn never reaches the agent: settle it directly so
+        // it cannot resolve as completed off a prompt the agent ignored.
+        if (input.signal?.aborted === true) {
+            channel.push({ ...base, type: "turn.completed", endReason: "aborted" });
+            channel.close();
+            try {
+                yield* channel;
+            }
+            finally {
+                this.#channel = undefined;
+                this.#turnId = undefined;
+            }
+            return;
+        }
+        if (input.reasoning !== undefined &&
+            JSON.stringify(input.reasoning) !== JSON.stringify(this.#reasoning)) {
+            const effort = cursorReasoningEffort(input.reasoning);
+            if (effort !== undefined) {
+                await this.#connection.extMethod("session/set_config_option", {
+                    sessionId: this.#sessionId,
+                    configId: "reasoning",
+                    value: effort
+                });
+            }
+            this.#reasoning = input.reasoning;
+        }
+        const onAbort = () => {
+            this.#pending.settleAll("cancel");
+            void this.#connection.cancel({ sessionId: this.#sessionId }).catch(() => undefined);
+        };
+        if (input.signal !== undefined) {
+            input.signal.addEventListener("abort", onAbort, { once: true });
+        }
+        this.#connection
+            .prompt({
+            sessionId: this.#sessionId,
+            prompt: [{ type: "text", text: input.prompt }]
+        })
+            .then((response) => {
+            channel.push({
+                ...base,
+                type: "turn.completed",
+                endReason: response.stopReason === "cancelled" ? "aborted" : "completed",
+                raw: { source: "acp.prompt.response", payload: { stopReason: response.stopReason } }
+            });
+            channel.close();
+        })
+            .catch((error) => {
+            const harnessError = asHarnessError(error);
+            channel.push({
+                ...base,
+                type: "turn.failed",
+                errorCode: harnessError.code,
+                message: harnessError.message
+            });
+            channel.close();
+        });
+        try {
+            yield* channel;
+        }
+        finally {
+            input.signal?.removeEventListener("abort", onAbort);
+            this.#channel = undefined;
+            this.#turnId = undefined;
+            this.#openItems.clear();
+        }
+    }
+    async respondToRequest(requestId, decision) {
+        if (!this.#pending.resolve(requestId, decision)) {
+            throw new HarnessError("protocol_parse", `unknown pending request ${requestId}`);
+        }
+    }
+    async interrupt() {
+        this.#pending.settleAll("cancel");
+        await this.#connection.cancel({ sessionId: this.#sessionId }).catch(() => undefined);
+    }
+    resumeCursor() {
+        return {
+            version: RESUME_CURSOR_VERSION,
+            kind: this.#kind,
+            data: { sessionId: this.#sessionId }
+        };
+    }
+    async stop() {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        this.#pending.settleAll("cancel");
+        this.#channel?.close();
+        terminate(this.#child);
+    }
+}
+function resumeSessionId(resume) {
+    if (resume === undefined || resume.kind !== "cursor")
+        return undefined;
+    const data = resume.data;
+    return typeof data.sessionId === "string" ? data.sessionId : undefined;
+}
+class CursorInstance {
+    kind = "cursor";
+    #config;
+    #context;
+    #status;
+    #sessions = new Set();
+    constructor(config, context, status) {
+        this.#config = config;
+        this.#context = context;
+        this.#status = status;
+    }
+    status() {
+        return this.#status;
+    }
+    async startSession(options) {
+        const args = this.#config.endpoint !== undefined ? ["-e", this.#config.endpoint, "acp"] : ["acp"];
+        const child = spawn(this.#config.command, args, {
+            cwd: options.cwd,
+            env: buildChildEnv({ base: resolveDriverEnv(this.#context), allow: [/^CURSOR_/] }),
+            detached: true,
+            stdio: ["pipe", "pipe", "pipe"]
+        });
+        if (child.stdin === null || child.stdout === null) {
+            terminate(child);
+            throw new HarnessError("session_closed", "cursor-agent has no stdio");
+        }
+        let session;
+        const client = {
+            sessionUpdate: async (params) => {
+                session?.ingestUpdate(params);
+            },
+            requestPermission: async (params) => {
+                if (session === undefined)
+                    return { outcome: { outcome: "cancelled" } };
+                return session.requestPermission(params);
+            }
+        };
+        const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+        const connection = new ClientSideConnection(() => client, stream);
+        try {
+            await connection.initialize({
+                protocolVersion: PROTOCOL_VERSION,
+                clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false }
+            });
+            await connection.authenticate({ methodId: AUTH_METHOD_ID }).catch(() => undefined);
+            const resumedId = resumeSessionId(options.resume);
+            let sessionId;
+            if (resumedId !== undefined) {
+                await connection.loadSession({ sessionId: resumedId, cwd: options.cwd, mcpServers: [] });
+                sessionId = resumedId;
+            }
+            else {
+                const created = await connection.newSession({ cwd: options.cwd, mcpServers: [] });
+                sessionId = created.sessionId;
+            }
+            if (options.model ?? this.#config.model) {
+                await connection
+                    .setSessionModel({ sessionId, modelId: (options.model ?? this.#config.model) })
+                    .catch(() => undefined);
+            }
+            const reasoningEffort = cursorReasoningEffort(options.reasoning);
+            if (reasoningEffort !== undefined) {
+                await connection.extMethod("session/set_config_option", {
+                    sessionId,
+                    configId: "reasoning",
+                    value: reasoningEffort
+                });
+            }
+            session = new CursorSession({
+                child,
+                connection,
+                sessionId,
+                approvalPolicy: options.approvalPolicy ?? DEFAULT_AUTOMATION_APPROVAL_POLICY,
+                reasoning: options.reasoning
+            });
+            this.#sessions.add(session);
+            return session;
+        }
+        catch (error) {
+            terminate(child);
+            throw asHarnessError(error);
+        }
+    }
+    async dispose() {
+        for (const session of this.#sessions)
+            await session.stop();
+        this.#sessions.clear();
+    }
+}
+/** Probe cursor-agent: version via `cursor-agent --version`. */
+async function probeCursor(config, context) {
+    const env = buildChildEnv({ base: resolveDriverEnv(context), allow: [/^CURSOR_/] });
+    return probeCliVersion({
+        kind: "cursor",
+        command: config.command,
+        cliName: "cursor-agent",
+        env,
+        // Auth is verified by the ACP handshake at session start; the version
+        // probe cannot see login state cheaply.
+        auth: { status: "unknown" },
+        notInstalledMessage: `Cursor CLI "${config.command}" was not found on PATH.`
+    });
+}
+export function createCursorDriver() {
+    return createCachedHarnessDriver({
+        kind: "cursor",
+        configSchema: cursorDriverConfigSchema,
+        probeConfig: () => cursorDriverConfigSchema.parse({}),
+        probeStatus: probeCursor,
+        createInstance: (config, context, status) => new CursorInstance(config, context, status)
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { ToolIntegration } from "@velum-labs/routekit-tools";
+export declare const cursorTool: ToolIntegration;
+export { buildCursorAcpProducer } from "./acp.js";
+export { startCursorBridge } from "./bridge.js";
+export { CURSOR_AGENT_TOOL_MAX_ITERATIONS, CURSOR_AGENT_TOOL_POLICY, cursorBridgeEnv, cursorBridgeModelEnv, cursorIdeEnv, cursorIdeModelsJson } from "./bridge-config.js";
+export { resolveCursorkitCli } from "./cursorkit-path.js";
+export type { CursorkitCli } from "./cursorkit-path.js";
+export { cursorIdeInstructions, cursorInstructions, launchCursor } from "./launch.js";
+export { CURSOR_AGENTS_DIRNAME, cursorSubagentMarkdown, scaffoldCursorSubagents } from "./subagents.js";
+export { createCursorDriver, cursorDriverConfigSchema } from "./driver.js";
+export type { CursorDriverConfig } from "./driver.js";

package/dist/index.js

@@ -0,0 +1,32 @@
+import { createCursorDriver, cursorDriverConfigSchema } from "./driver.js";
+import { launchCursor } from "./launch.js";
+const driver = createCursorDriver();
+export const cursorTool = {
+    id: "cursor",
+    displayName: "Cursor",
+    pickerHint: "Cursor CLI or desktop",
+    binary: "cursor-agent",
+    packageName: "@velum-labs/routekit-tool-cursor",
+    installHint: "install the Cursor CLI: https://cursor.com/cli",
+    authSummary: "Cursor uses a logged-in cursor-agent CLI and a local bridge.",
+    setupSnippet: ({ gatewayUrl, model = "gateway-model", note }) => `cursor-agent --endpoint ${note === undefined || note.length === 0 ? gatewayUrl : note} --model ${model}`,
+    launch: launchCursor,
+    driver: {
+        kind: driver.kind,
+        driver,
+        configForRoute: (route) => cursorDriverConfigSchema.parse({ endpoint: route.gatewayUrl, model: route.model })
+    },
+    capabilities: {
+        streaming: "full",
+        tools: "full",
+        images: "degraded",
+        reasoning_controls: "degraded"
+    }
+};
+export { buildCursorAcpProducer } from "./acp.js";
+export { startCursorBridge } from "./bridge.js";
+export { CURSOR_AGENT_TOOL_MAX_ITERATIONS, CURSOR_AGENT_TOOL_POLICY, cursorBridgeEnv, cursorBridgeModelEnv, cursorIdeEnv, cursorIdeModelsJson } from "./bridge-config.js";
+export { resolveCursorkitCli } from "./cursorkit-path.js";
+export { cursorIdeInstructions, cursorInstructions, launchCursor } from "./launch.js";
+export { CURSOR_AGENTS_DIRNAME, cursorSubagentMarkdown, scaffoldCursorSubagents } from "./subagents.js";
+export { createCursorDriver, cursorDriverConfigSchema } from "./driver.js";

package/dist/launch.d.ts

@@ -0,0 +1,4 @@
+import type { ToolLaunchContext } from "@velum-labs/routekit-tools";
+export declare function cursorIdeInstructions(model: string): string;
+export declare function cursorInstructions(publicUrl: string, model: string, apiKey?: string): string;
+export declare function launchCursor(ctx: ToolLaunchContext): Promise<number>;

package/dist/launch.js

@@ -0,0 +1,118 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { definedEnv, spawnLogged, spawnTool, terminate, waitForOutput } from "@velum-labs/routekit-runtime";
+import { cursorIdeEnv } from "./bridge-config.js";
+import { startCursorBridge } from "./bridge.js";
+import { resolveCursorkitCli } from "./cursorkit-path.js";
+import { scaffoldCursorSubagents } from "./subagents.js";
+function bridgeModels(ctx) {
+    return ctx.spec.models.flatMap((model) => [
+        {
+            id: model.id,
+            ...(model.label !== undefined ? { displayName: model.label } : {}),
+            ...(model.reasoning !== undefined ? { reasoning: model.reasoning } : {})
+        },
+        ...(model.aliases ?? []).map((alias) => ({
+            id: alias,
+            ...(model.reasoning !== undefined ? { reasoning: model.reasoning } : {})
+        }))
+    ]);
+}
+export function cursorIdeInstructions(model) {
+    return `Cursor IDE is connected to the gateway. Choose "${model}" in the Agent model picker.`;
+}
+export function cursorInstructions(publicUrl, model, apiKey) {
+    return [
+        "In Cursor Settings -> Models, enable Override OpenAI Base URL and set:",
+        `  Override OpenAI Base URL : ${publicUrl}/v1/cursor`,
+        `  Model name               : ${model}`,
+        `  OpenAI API Key           : ${apiKey ?? "routekit-local"}`
+    ].join("\n");
+}
+function cursorCliAuthEnv(env = process.env) {
+    const apiKey = env.CURSOR_API_KEY;
+    const configDirectory = env.CURSOR_CONFIG_DIR;
+    return definedEnv({
+        CURSOR_API_KEY: typeof apiKey === "string" && apiKey.length > 0 ? apiKey : undefined,
+        CURSOR_CONFIG_DIR: typeof configDirectory === "string" && configDirectory.length > 0
+            ? configDirectory
+            : undefined
+    });
+}
+async function launchCursorCli(ctx) {
+    const started = await startCursorBridge({
+        gatewayUrl: ctx.spec.gatewayUrl,
+        modelLabel: ctx.spec.defaultModel,
+        models: bridgeModels(ctx),
+        ...(ctx.spec.auth?.token !== undefined
+            ? { apiKey: ctx.spec.auth.token }
+            : {}),
+        ...(ctx.spec.logsDir !== undefined
+            ? { logFile: join(ctx.spec.logsDir, "cursor-bridge.log") }
+            : {}),
+        ...(ctx.spec.tls?.caCertPath !== undefined
+            ? { caCertPath: ctx.spec.tls.caCertPath }
+            : {}),
+        log: ctx.log
+    });
+    const bridgeUrl = ctx.registerPort("cursor", started.port);
+    ctx.registerDisposer(() => {
+        ctx.unregisterPort("cursor");
+        terminate(started.child);
+    });
+    ctx.prepareForPassthrough();
+    return await spawnTool("cursor-agent", ["--endpoint", bridgeUrl, "--model", ctx.spec.defaultModel, ...ctx.spec.args], cursorCliAuthEnv(), ctx.spec.cwd);
+}
+async function launchCursorRemote(ctx) {
+    const publicUrl = ctx.spec.publicUrl;
+    if (publicUrl === undefined) {
+        throw new Error("Cursor remote configuration requires a public gateway URL");
+    }
+    ctx.log(cursorInstructions(publicUrl, ctx.spec.defaultModel, ctx.spec.auth?.token));
+    await new Promise(() => { });
+    return 0;
+}
+async function launchCursorIde(ctx) {
+    const { serveCli } = resolveCursorkitCli();
+    const repo = ctx.spec.cwd ?? process.cwd();
+    const stateDir = ctx.spec.logsDir !== undefined
+        ? join(ctx.spec.logsDir, "cursor-ide")
+        : join(repo, ".cursor-rpc-ide");
+    mkdirSync(stateDir, { recursive: true });
+    const proc = spawnLogged(process.execPath, [serveCli, "ck"], {
+        cwd: stateDir,
+        env: cursorIdeEnv({
+            repo,
+            gatewayUrl: ctx.spec.gatewayUrl,
+            modelLabel: ctx.spec.defaultModel,
+            models: bridgeModels(ctx),
+            ...(ctx.spec.auth?.token !== undefined ? { apiKey: ctx.spec.auth.token } : {}),
+            ...(ctx.spec.tls?.caCertPath !== undefined
+                ? { caCertPath: ctx.spec.tls.caCertPath }
+                : {})
+        }),
+        ...(ctx.spec.logsDir !== undefined
+            ? { logFile: join(ctx.spec.logsDir, "cursor-ide.log") }
+            : {})
+    });
+    await waitForOutput(proc, /ck ready|bridge listening/, {
+        timeoutMs: 60_000,
+        label: "Cursor desktop bridge"
+    });
+    ctx.registerDisposer(() => terminate(proc.child));
+    ctx.log(cursorIdeInstructions(ctx.spec.defaultModel));
+    return await new Promise((resolve) => {
+        proc.child.once("exit", (code) => resolve(code ?? 0));
+    });
+}
+export async function launchCursor(ctx) {
+    const profiles = ctx.spec.agentProfiles ?? [];
+    if (profiles.length > 0) {
+        scaffoldCursorSubagents(ctx.spec.cwd ?? process.cwd(), profiles, ctx.log);
+    }
+    if (ctx.spec.ide === true)
+        return launchCursorIde(ctx);
+    if (ctx.spec.publicUrl !== undefined)
+        return launchCursorRemote(ctx);
+    return launchCursorCli(ctx);
+}

package/dist/subagents.d.ts

@@ -0,0 +1,4 @@
+import type { AgentProfile } from "@velum-labs/routekit-tools";
+export declare const CURSOR_AGENTS_DIRNAME: string;
+export declare function cursorSubagentMarkdown(profile: AgentProfile): string;
+export declare function scaffoldCursorSubagents(repo: string, profiles: readonly AgentProfile[], log?: (line: string) => void): string[];

package/dist/subagents.js

@@ -0,0 +1,33 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const CURSOR_AGENTS_DIRNAME = join(".cursor", "agents");
+export function cursorSubagentMarkdown(profile) {
+    return [
+        "---",
+        `name: ${profile.id}`,
+        `description: ${profile.description}`,
+        `model: ${profile.model}`,
+        "---",
+        "",
+        profile.instructions,
+        ""
+    ].join("\n");
+}
+export function scaffoldCursorSubagents(repo, profiles, log) {
+    const written = [];
+    try {
+        const dir = join(repo, CURSOR_AGENTS_DIRNAME);
+        mkdirSync(dir, { recursive: true });
+        for (const profile of profiles) {
+            const path = join(dir, `${profile.id}.md`);
+            if (existsSync(path))
+                continue;
+            writeFileSync(path, cursorSubagentMarkdown(profile));
+            written.push(path);
+        }
+    }
+    catch (error) {
+        log?.(`could not scaffold Cursor agents (${error instanceof Error ? error.message : String(error)})`);
+    }
+    return written;
+}

package/dist/test/bridge-config.test.d.ts

@@ -0,0 +1 @@
+export {};