@euqns/nudge-mcp 0.14.0 → 0.16.0

package/dist/codex-companion.js

@@ -10,6 +10,23 @@ import { NUDGE_MCP_VERSION } from "./version.js";
 const DEFAULT_APP_URL = "https://funjitsu-nudge.vercel.app";
 const DEFAULT_PORT = 47653;
 const MAX_BODY_BYTES = 64 * 1024;
+const PROVIDERS = {
+    codex: {
+        displayName: "Codex",
+        binary: process.platform === "win32" ? "codex.cmd" : "codex",
+        loginCommand: "codex login",
+    },
+    claude: {
+        displayName: "Claude Code",
+        binary: process.platform === "win32" ? "claude.cmd" : "claude",
+        loginCommand: "claude auth login",
+    },
+    cursor: {
+        displayName: "Cursor",
+        binary: process.platform === "win32" ? "cursor-agent.cmd" : "cursor-agent",
+        loginCommand: "cursor-agent login",
+    },
+};
 const require = createRequire(import.meta.url);
 const REASONING_EFFORTS = new Set([
     "none",
@@ -73,7 +90,7 @@ class CodexMetadataClient {
         await this.rawRequest("initialize", {
             clientInfo: {
                 name: "nudge-companion",
-                title: "Nudge Local Codex",
+                title: "Nudge Agent",
                 version: NUDGE_MCP_VERSION,
             },
             capabilities: {
@@ -227,6 +244,7 @@ function parseArgs(argv) {
     let openBrowserOnStart = true;
     let port = DEFAULT_PORT;
     let portWasExplicit = false;
+    let provider = "codex";
     for (let index = 0; index < argv.length; index++) {
         const arg = argv[index];
         const next = argv[index + 1];
@@ -256,8 +274,22 @@ function parseArgs(argv) {
         else if (arg === "--no-open") {
             openBrowserOnStart = false;
         }
+        else if (arg === "--provider" && next) {
+            if (!(next in PROVIDERS)) {
+                throw new Error("--provider must be codex, claude, or cursor");
+            }
+            provider = next;
+            index++;
+        }
+        else if (arg.startsWith("--provider=")) {
+            const value = arg.slice("--provider=".length);
+            if (!(value in PROVIDERS)) {
+                throw new Error("--provider must be codex, claude, or cursor");
+            }
+            provider = value;
+        }
         else {
-            throw new Error(`Unknown codex companion option: ${arg}`);
+            throw new Error(`Unknown agent companion option: ${arg}`);
         }
     }
     if (!Number.isInteger(port) || port < 1024 || port > 65535) {
@@ -269,6 +301,7 @@ function parseArgs(argv) {
         openBrowser: openBrowserOnStart,
         port,
         portWasExplicit,
+        provider,
     };
 }
 async function listenOnLoopback(server, preferredPort, allowFallback) {
@@ -332,7 +365,7 @@ function writeJson(res, status, value, headers) {
     res.writeHead(status, { ...headers, "Content-Type": "application/json" });
     res.end(JSON.stringify(value));
 }
-function buildPrompt(prompt, context) {
+export function buildCompanionPrompt(prompt, context) {
     const pathname = typeof context?.pathname === "string" ? context.pathname.slice(0, 500) : undefined;
     const routeContext = pathname
         ? `The user opened this chat from the Nudge route ${JSON.stringify(pathname)}.`
@@ -347,21 +380,52 @@ function buildPrompt(prompt, context) {
                 source: context.boardSource === "cloud" || context.boardSource === "local"
                     ? context.boardSource
                     : undefined,
+                role: context.boardRole === "owner" ||
+                    context.boardRole === "editor" ||
+                    context.boardRole === "viewer"
+                    ? context.boardRole
+                    : undefined,
                 view: typeof context.view === "string" ? context.view.slice(0, 50) : undefined,
                 canvasId: typeof context.canvasId === "string"
                     ? context.canvasId.slice(0, 200)
                     : undefined,
                 cardId: typeof context.cardId === "string" ? context.cardId.slice(0, 200) : undefined,
+                cardTitle: typeof context.cardTitle === "string"
+                    ? context.cardTitle.slice(0, 500)
+                    : undefined,
+                cardDescription: typeof context.cardDescription === "string"
+                    ? context.cardDescription.slice(0, 4_000)
+                    : undefined,
+                cardHref: typeof context.cardHref === "string"
+                    ? context.cardHref.slice(0, 1_000)
+                    : undefined,
+                listId: typeof context.listId === "string" ? context.listId.slice(0, 200) : undefined,
+                listTitle: typeof context.listTitle === "string"
+                    ? context.listTitle.slice(0, 500)
+                    : undefined,
+                selectionSource: typeof context.selectionSource === "string"
+                    ? context.selectionSource.slice(0, 50)
+                    : undefined,
+                repository: context.repository && typeof context.repository === "object"
+                    ? context.repository
+                    : undefined,
                 listCount: typeof context.listCount === "number" ? context.listCount : undefined,
                 cardCount: typeof context.cardCount === "number" ? context.cardCount : undefined,
             }),
             "Use this exact board id for Nudge MCP calls unless the user names another board.",
+            context.cardId
+                ? "Treat the selected card as the subject when the user says this task, this card, or it."
+                : "No card is selected; do not guess which card the user means.",
         ]
         : [];
     return [
         routeContext,
         ...boardContext,
         "Use the configured Nudge MCP tools when the request needs board or card data.",
+        "Board mutations use a two-step confirmation workflow. First inspect enough data to show a concise preview naming every item and field that will change. Do not call a write tool until a later user message explicitly confirms that preview. A request such as 'create this' starts the preview; it is not confirmation. After execution, report success and include the returned Nudge link so the result opens in chat.",
+        "Call out deletes, replacement descriptions, membership changes, and terminal status moves as irreversible or potentially disruptive before confirmation. If permissions reject an operation, explain the required board role and offer a retry after access changes.",
+        "Local boards cannot be changed through Nudge MCP, and viewer-role cloud boards are read-only. Explain that permission state before proposing a write and do not attempt the mutation.",
+        "For a coding-agent handoff, use the nudge.agent-handoff/v1 sections: task brief, acceptance criteria, relevant links, repository context, and return path. The format must work for Claude Code, Codex, and Cursor. Runner output should be summarized back to the originating card with add_comment, after the same write preview and confirmation.",
         "Be concise about progress and return a clear final answer for the Nudge chat UI.",
         "The local filesystem is read-only. Nudge MCP tools may update boards when requested; do not claim that local files were changed.",
         "",
@@ -386,13 +450,34 @@ export function assertChatGptLogin() {
         ].join("\n"));
     }
 }
-export function subscriptionEnvironment() {
+export function assertCompanionProvider(provider) {
+    if (provider === "codex") {
+        assertChatGptLogin();
+        return;
+    }
+    const definition = PROVIDERS[provider];
+    const args = provider === "claude" ? ["auth", "status"] : ["status"];
+    const result = spawnSync(definition.binary, args, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error) {
+        throw new Error(`${definition.displayName} CLI was not found. Install it, then run \`${definition.loginCommand}\`.`);
+    }
+    if (result.status !== 0) {
+        const detail = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim();
+        throw new Error(`${definition.displayName} is not authenticated. Run \`${definition.loginCommand}\`.${detail ? `\nCurrent status: ${detail}` : ""}`);
+    }
+}
+export function subscriptionEnvironment(environment = process.env) {
     const blocked = new Set([
+        "ANTHROPIC_API_KEY",
+        "CURSOR_API_KEY",
         "CODEX_ACCESS_TOKEN",
         "CODEX_API_KEY",
         "OPENAI_API_KEY",
     ]);
-    return Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined && !blocked.has(entry[0])));
+    return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined && !blocked.has(entry[0])));
 }
 export function companionMcpTransport() {
     const companionFile = fileURLToPath(import.meta.url);
@@ -432,6 +517,186 @@ export function companionCodexConfig(env) {
         },
     };
 }
+function companionClaudeConfig() {
+    const transport = companionMcpTransport();
+    return JSON.stringify({
+        mcpServers: {
+            nudge: {
+                command: transport.command,
+                args: transport.args,
+            },
+        },
+    });
+}
+export function companionCliInvocation(provider, prompt, threadId) {
+    const definition = PROVIDERS[provider];
+    if (provider === "claude") {
+        return {
+            command: definition.binary,
+            args: [
+                "-p",
+                "--output-format",
+                "stream-json",
+                "--verbose",
+                "--permission-mode",
+                "bypassPermissions",
+                "--disallowedTools",
+                "Edit",
+                "Write",
+                "NotebookEdit",
+                "Bash",
+                "--mcp-config",
+                companionClaudeConfig(),
+                "--strict-mcp-config",
+                ...(threadId ? ["--resume", threadId] : []),
+            ],
+            stdin: prompt,
+        };
+    }
+    return {
+        command: definition.binary,
+        args: [
+            "-p",
+            "--mode=ask",
+            "--output-format",
+            "stream-json",
+            ...(threadId ? ["--resume", threadId] : []),
+            prompt,
+        ],
+        stdin: null,
+    };
+}
+export function companionPairingUrl(appUrl, pairing) {
+    return `${appUrl}/#nudge-agent=${pairing}`;
+}
+function syntheticUsage(usage) {
+    return {
+        input_tokens: typeof usage?.input_tokens === "number" ? usage.input_tokens : 0,
+        cached_input_tokens: typeof usage?.cache_read_input_tokens === "number"
+            ? usage.cache_read_input_tokens
+            : 0,
+        cache_write_input_tokens: typeof usage?.cache_creation_input_tokens === "number"
+            ? usage.cache_creation_input_tokens
+            : 0,
+        output_tokens: typeof usage?.output_tokens === "number" ? usage.output_tokens : 0,
+        reasoning_output_tokens: 0,
+    };
+}
+function cliActivity(provider, event) {
+    if (provider === "cursor" && event.type === "tool_call") {
+        const call = event.tool_call;
+        if (!call || typeof call !== "object")
+            return "Used a Cursor tool";
+        const name = Object.keys(call)[0];
+        return name ? `Used ${name.replace(/ToolCall$/, "")}` : "Used a Cursor tool";
+    }
+    if (provider === "claude" && event.type === "assistant") {
+        const message = event.message;
+        const blocks = Array.isArray(message?.content) ? message.content : [];
+        const tool = blocks.find((block) => !!block &&
+            typeof block === "object" &&
+            block.type === "tool_use");
+        return tool?.name ? `Used ${String(tool.name)}` : null;
+    }
+    return null;
+}
+async function runSubscriptionCliTurn({ provider, prompt, cwd, threadId, signal, send, }) {
+    const definition = PROVIDERS[provider];
+    const invocation = companionCliInvocation(provider, prompt, threadId);
+    send({ type: "agent", event: { type: "turn.started" } });
+    return await new Promise((resolve, reject) => {
+        const child = spawn(invocation.command, invocation.args, {
+            cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: subscriptionEnvironment(),
+        });
+        let stderr = "";
+        let activeThreadId = threadId;
+        let finalText = "";
+        let usage;
+        const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+        lines.on("line", (line) => {
+            if (!line.trim())
+                return;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (typeof event.session_id === "string") {
+                activeThreadId = event.session_id;
+                if (event.type === "system") {
+                    send({
+                        type: "agent",
+                        event: { type: "thread.started", thread_id: activeThreadId },
+                    });
+                }
+            }
+            const activity = cliActivity(provider, event);
+            if (activity) {
+                const id = typeof event.call_id === "string"
+                    ? event.call_id
+                    : `tool-${Date.now().toString(36)}`;
+                send({
+                    type: "agent",
+                    event: {
+                        type: event.subtype === "completed" ? "item.completed" : "item.started",
+                        item: { id, type: "reasoning", text: activity },
+                    },
+                });
+            }
+            if (event.type === "result") {
+                if (typeof event.result === "string")
+                    finalText = event.result;
+                if (event.usage && typeof event.usage === "object") {
+                    usage = event.usage;
+                }
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr = `${stderr}${chunk.toString("utf8")}`.slice(-8_000);
+        });
+        const onAbort = () => child.kill("SIGTERM");
+        signal.addEventListener("abort", onAbort, { once: true });
+        child.once("error", (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+        child.once("close", (code) => {
+            signal.removeEventListener("abort", onAbort);
+            if (signal.aborted) {
+                resolve(activeThreadId);
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(`${definition.displayName} exited ${code}: ${stderr.trim().slice(-800) || "no error detail"}`));
+                return;
+            }
+            send({
+                type: "agent",
+                event: {
+                    type: "item.completed",
+                    item: {
+                        id: `message-${Date.now().toString(36)}`,
+                        type: "agent_message",
+                        text: finalText,
+                    },
+                },
+            });
+            send({
+                type: "agent",
+                event: { type: "turn.completed", usage: syntheticUsage(usage) },
+            });
+            resolve(activeThreadId);
+        });
+        if (invocation.stdin !== null) {
+            child.stdin.write(invocation.stdin);
+        }
+        child.stdin.end();
+    });
+}
 function companionThreadOptions(cwd, model, effort) {
     return {
         approvalPolicy: "never",
@@ -444,17 +709,23 @@ function companionThreadOptions(cwd, model, effort) {
         modelReasoningEffort: effort,
     };
 }
-export async function runCodexCompanion(argv) {
+export async function runAgentCompanion(argv) {
     const options = parseArgs(argv);
+    const provider = PROVIDERS[options.provider];
     const allowedOrigin = new URL(options.appUrl).origin;
     const token = crypto.randomBytes(32).toString("base64url");
-    assertChatGptLogin();
-    const codex = new Codex({
-        config: companionCodexConfig(),
-        env: subscriptionEnvironment(),
-    });
-    const metadataClient = new CodexMetadataClient();
+    assertCompanionProvider(options.provider);
+    const codex = options.provider === "codex"
+        ? new Codex({
+            config: companionCodexConfig(),
+            env: subscriptionEnvironment(),
+        })
+        : null;
+    const metadataClient = options.provider === "codex"
+        ? new CodexMetadataClient()
+        : null;
     let thread = null;
+    let cliThreadId = null;
     let selectedModel = null;
     let selectedEffort = null;
     let activeAbort = null;
@@ -491,18 +762,45 @@ export async function runCodexCompanion(argv) {
                     ok: true,
                     cwd: options.cwd,
                     running: activeAbort !== null,
-                    threadId: thread?.id ?? null,
+                    threadId: options.provider === "codex" ? thread?.id ?? null : cliThreadId,
                     model: selectedModel,
                     effort: selectedEffort,
+                    provider: { id: options.provider, displayName: provider.displayName },
                 }, headers);
                 return;
             }
             if (req.method === "GET" && req.url === "/v1/metadata") {
+                if (!metadataClient) {
+                    writeJson(res, 200, {
+                        currentModel: options.provider,
+                        currentReasoningEffort: "none",
+                        models: [
+                            {
+                                model: options.provider,
+                                displayName: `${provider.displayName} default`,
+                                description: `Uses the model selected by your ${provider.displayName} CLI account.`,
+                                isDefault: true,
+                                defaultReasoningEffort: "none",
+                                supportedReasoningEfforts: [],
+                            },
+                        ],
+                        planType: "subscription",
+                        rateLimits: [],
+                        updatedAt: Date.now(),
+                        provider: { id: options.provider, displayName: provider.displayName },
+                        capabilities: { modelSelection: false, effortSelection: false },
+                    }, headers);
+                    return;
+                }
                 try {
                     const metadata = await metadataClient.metadata(selectedModel, selectedEffort);
                     selectedModel = metadata.currentModel;
                     selectedEffort = metadata.currentReasoningEffort;
-                    writeJson(res, 200, metadata, headers);
+                    writeJson(res, 200, {
+                        ...metadata,
+                        provider: { id: options.provider, displayName: provider.displayName },
+                        capabilities: { modelSelection: true, effortSelection: true },
+                    }, headers);
                 }
                 catch (error) {
                     writeJson(res, 503, {
@@ -514,6 +812,10 @@ export async function runCodexCompanion(argv) {
                 return;
             }
             if (req.method === "POST" && req.url === "/v1/model") {
+                if (!metadataClient) {
+                    writeJson(res, 400, { error: `${provider.displayName} controls model selection in its own CLI.` }, headers);
+                    return;
+                }
                 if (activeAbort) {
                     writeJson(res, 409, { error: "A Codex turn is still running" }, headers);
                     return;
@@ -540,6 +842,10 @@ export async function runCodexCompanion(argv) {
                 return;
             }
             if (req.method === "POST" && req.url === "/v1/effort") {
+                if (!metadataClient) {
+                    writeJson(res, 400, { error: `${provider.displayName} controls reasoning settings in its own CLI.` }, headers);
+                    return;
+                }
                 if (activeAbort) {
                     writeJson(res, 409, { error: "A Codex turn is still running" }, headers);
                     return;
@@ -563,6 +869,7 @@ export async function runCodexCompanion(argv) {
                 selectedModel = metadata.currentModel;
                 selectedEffort = effort;
                 thread = null;
+                cliThreadId = null;
                 writeJson(res, 200, { ok: true, model: selectedModel, effort }, headers);
                 return;
             }
@@ -572,6 +879,7 @@ export async function runCodexCompanion(argv) {
                     return;
                 }
                 thread = null;
+                cliThreadId = null;
                 writeJson(res, 200, { ok: true }, headers);
                 return;
             }
@@ -590,7 +898,12 @@ export async function runCodexCompanion(argv) {
                 }
                 const threadId = typeof parsed.threadId === "string" ? parsed.threadId.trim() : "";
                 if (!/^[a-zA-Z0-9-]{10,100}$/.test(threadId)) {
-                    writeJson(res, 400, { error: "Invalid Codex thread id" }, headers);
+                    writeJson(res, 400, { error: "Invalid coding-agent session id" }, headers);
+                    return;
+                }
+                if (!metadataClient || !codex) {
+                    cliThreadId = threadId;
+                    writeJson(res, 200, { ok: true, threadId }, headers);
                     return;
                 }
                 const requestedModel = typeof parsed.model === "string" ? parsed.model.trim() : "";
@@ -628,7 +941,7 @@ export async function runCodexCompanion(argv) {
                 return;
             }
             if (activeAbort) {
-                writeJson(res, 409, { error: "A Codex turn is already running" }, headers);
+                writeJson(res, 409, { error: `A ${provider.displayName} turn is already running` }, headers);
                 return;
             }
             let parsed;
@@ -644,7 +957,9 @@ export async function runCodexCompanion(argv) {
                 writeJson(res, 400, { error: "prompt is required" }, headers);
                 return;
             }
-            thread ??= codex.startThread(companionThreadOptions(options.cwd, selectedModel, selectedEffort));
+            if (codex) {
+                thread ??= codex.startThread(companionThreadOptions(options.cwd, selectedModel, selectedEffort));
+            }
             const abort = new AbortController();
             activeAbort = abort;
             let responseFinished = false;
@@ -662,14 +977,28 @@ export async function runCodexCompanion(argv) {
                     res.write(`${JSON.stringify(value)}\n`);
             };
             try {
-                send({ type: "connected", cwd: options.cwd, threadId: thread.id });
-                const streamed = await thread.runStreamed(buildPrompt(prompt, parsed.context), {
-                    signal: abort.signal,
-                });
-                for await (const event of streamed.events) {
-                    send({ type: "codex", event: event });
+                const currentThreadId = codex ? thread?.id ?? null : cliThreadId;
+                send({ type: "connected", cwd: options.cwd, threadId: currentThreadId });
+                const contextualPrompt = buildCompanionPrompt(prompt, parsed.context);
+                if (codex && thread) {
+                    const streamed = await thread.runStreamed(contextualPrompt, {
+                        signal: abort.signal,
+                    });
+                    for await (const event of streamed.events) {
+                        send({ type: "agent", event: event });
+                    }
+                }
+                else {
+                    cliThreadId = await runSubscriptionCliTurn({
+                        provider: options.provider,
+                        prompt: contextualPrompt,
+                        cwd: options.cwd,
+                        threadId: cliThreadId,
+                        signal: abort.signal,
+                        send,
+                    });
                 }
-                send({ type: "done", threadId: thread.id });
+                send({ type: "done", threadId: codex ? thread?.id ?? null : cliThreadId });
             }
             catch (error) {
                 send({
@@ -692,10 +1021,15 @@ export async function runCodexCompanion(argv) {
         });
     });
     const port = await listenOnLoopback(server, options.port, !options.portWasExplicit);
-    const pairing = Buffer.from(JSON.stringify({ port, token }), "utf8").toString("base64url");
-    const url = `${options.appUrl}/#nudge-codex=${pairing}`;
+    const pairing = Buffer.from(JSON.stringify({
+        port,
+        token,
+        provider: { id: options.provider, displayName: provider.displayName },
+    }), "utf8").toString("base64url");
+    const url = companionPairingUrl(options.appUrl, pairing);
     console.log("");
-    console.log("Nudge Codex companion is running");
+    console.log("Nudge Agent companion is running");
+    console.log(`  Agent:     ${provider.displayName}`);
     console.log(`  App:       ${options.appUrl}`);
     console.log(`  Workspace: ${options.cwd}`);
     console.log(`  Listener:  http://127.0.0.1:${port}`);
@@ -704,7 +1038,7 @@ export async function runCodexCompanion(argv) {
     }
     console.log("  Files:     read-only");
     console.log("");
-    console.log("Codex will reuse the account from `codex login`.");
+    console.log(`${provider.displayName} will reuse the account from \`${provider.loginCommand}\`.`);
     console.log("Keep this terminal open while using Nudge chat.");
     console.log("");
     if (options.openBrowser)
@@ -714,11 +1048,15 @@ export async function runCodexCompanion(argv) {
     await new Promise((resolve) => {
         const shutdown = () => {
             activeAbort?.abort();
-            metadataClient.stop();
+            metadataClient?.stop();
             server.close(() => resolve());
         };
         process.once("SIGINT", shutdown);
         process.once("SIGTERM", shutdown);
     });
 }
+/** Backward-compatible alias for the original Codex-only command. */
+export async function runCodexCompanion(argv) {
+    await runAgentCompanion(["--provider", "codex", ...argv]);
+}
 //# sourceMappingURL=codex-companion.js.map