@trygocode/notify 0.1.6 → 0.3.1

package/dist/src/doctor.js

@@ -0,0 +1,262 @@
+// `gocode-notify doctor` — self-diagnostic checklist (PRD §8.6 R10 / T-COV4).
+//
+// Prints a human-readable checklist of the installation health so users know
+// immediately what is missing and how to fix it.  Checks (in order):
+//
+//   1. Paired?        credentials exist and are valid.
+//   2. Server reachable?  the bound (or default) server answers.
+//   3. Runner hooks installed?  Claude Code Stop/Notification + Cursor stop.
+//   4. `gocode-notify` on PATH?  resolvable in non-login shells.
+//
+// Every ✗ check prints the EXACT fix command so users never have to guess.
+// Always exits 0 — it is a report, not a gate.
+//
+// The gather / format split mirrors `status.ts`:
+//   `gatherDoctor`  → pure async data collection (injectable deps, fully testable)
+//   `formatDoctor`  → pure sync rendering to string lines
+//   `cmdDoctor`     → thin CLI wire-up in `cli.ts`
+//
+// Zero runtime deps — Node built-ins only, matching the package's zero-dep rule.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readCredentials, resolveServerUrl } from "./creds.js";
+import { probeServer, DEFAULT_PROBE_TIMEOUT_MS, UNPAIRED_WARNING } from "./status.js";
+// Re-export UNPAIRED_WARNING so existing `from "./doctor.js"` imports keep
+// working after the constant moved to status.ts (T-COV1).
+export { UNPAIRED_WARNING } from "./status.js";
+// ─── Hook markers ──────────────────────────────────────────────────────────
+// We detect our hook entries by looking for these stable tokens in the command
+// strings.  The same tokens are used by claude.ts / cursor.ts for idempotent
+// install / uninstall (kept in sync via the HOOK_SOURCE comments there).
+/** Tokens that identify a gocode-notify Claude Code hook in settings.json. */
+const CLAUDE_HOOK_TOKEN = "--source claude_code";
+/** Token that identifies our Cursor stop hook in hooks.json. */
+const CURSOR_HOOK_TOKEN = "--source cursor";
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function resolveHomeDir(opts) {
+    return opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? "~";
+}
+/** Read a JSON file; returns null on any error (absent, bad JSON, bad perms). */
+async function readJsonFile(p) {
+    try {
+        const raw = await fs.readFile(p, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `cmd` appears on any entry in `pathEnv` (colon-separated). */
+async function commandOnPath(cmd, pathEnv) {
+    if (!pathEnv)
+        return false;
+    const names = process.platform === "win32" ? [cmd, `${cmd}.exe`, `${cmd}.cmd`, `${cmd}.bat`] : [cmd];
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const name of names) {
+            try {
+                await fs.stat(path.join(dir, name));
+                return true;
+            }
+            catch {
+                // not in this dir — keep looking
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Recursively extract all `command` strings from a Claude/Cursor hooks value.
+ *
+ * Claude settings.json hook events have this shape:
+ *   hooks.Stop = [ { matcher: string, hooks: [ { type: "command", command: string } ] } ]
+ *
+ * Cursor hooks.json stop entries have this shape:
+ *   stop = [ { command: string } ]
+ *
+ * This walks the structure recursively so both formats are handled without
+ * needing a per-runtime parser.
+ */
+function extractCommands(value) {
+    if (!value)
+        return [];
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value)) {
+        const cmds = [];
+        for (const item of value)
+            cmds.push(...extractCommands(item));
+        return cmds;
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const cmds = [];
+        // If this object has a `command` string field, it's a hook entry.
+        if (typeof obj.command === "string")
+            cmds.push(obj.command);
+        // Recurse into `hooks` sub-array (Claude Code's two-level nesting).
+        if (obj.hooks)
+            cmds.push(...extractCommands(obj.hooks));
+        return cmds;
+    }
+    return [];
+}
+/** Extract all hook command strings from a hooks event value (array or object). */
+function flattenHookCommands(hooksValue) {
+    return extractCommands(hooksValue);
+}
+// ─── Core gather ────────────────────────────────────────────────────────────
+/**
+ * Collect the full {@link DoctorReport}. Never throws — errors are surfaced as
+ * failing checks with actionable fix commands.
+ */
+export async function gatherDoctor(opts = {}) {
+    const checks = [];
+    const home = resolveHomeDir(opts);
+    // ── 1. Paired? ─────────────────────────────────────────────────────────
+    let pairedOk = false;
+    let pairedDetail = "not paired";
+    try {
+        const creds = await readCredentials({ home: opts.home });
+        if (creds) {
+            pairedOk = true;
+            pairedDetail = `paired as ${creds.user_id} (${creds.label})`;
+        }
+    }
+    catch {
+        pairedDetail = "credentials file unreadable";
+    }
+    checks.push({
+        key: "paired",
+        label: "Paired?",
+        ok: pairedOk,
+        detail: pairedDetail,
+        fixCmd: pairedOk ? undefined : "gocode-notify login",
+    });
+    // ── 2. Server reachable? ───────────────────────────────────────────────
+    const serverUrl = await resolveServerUrl(opts.serverFlag, { home: opts.home });
+    const probe = await probeServer(serverUrl, {
+        fetchImpl: opts.fetchImpl,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,
+    });
+    checks.push({
+        key: "server",
+        label: "Server reachable?",
+        ok: probe.reachable,
+        detail: `${serverUrl} (${probe.detail})`,
+        fixCmd: probe.reachable
+            ? undefined
+            : "# Check your network or run: gocode-notify login --server <url>",
+    });
+    // ── 3a. Claude Code Stop hook ──────────────────────────────────────────
+    const claudeSettingsPath = path.join(home, ".claude", "settings.json");
+    const claudeSettings = await readJsonFile(claudeSettingsPath);
+    const claudeHooks = claudeSettings &&
+        typeof claudeSettings === "object" &&
+        "hooks" in claudeSettings
+        ? claudeSettings.hooks
+        : null;
+    const claudeStopCommands = flattenHookCommands(claudeHooks &&
+        typeof claudeHooks === "object" &&
+        "Stop" in claudeHooks
+        ? claudeHooks.Stop
+        : null);
+    const claudeStopInstalled = claudeStopCommands.some((c) => c.includes(CLAUDE_HOOK_TOKEN));
+    checks.push({
+        key: "hook:claude-stop",
+        label: "Claude Code Stop hook installed?",
+        ok: claudeStopInstalled,
+        detail: claudeStopInstalled
+            ? `found in ${claudeSettingsPath}`
+            : claudeHooks === null
+                ? "~/.claude/settings.json not found or no hooks"
+                : "hook not found",
+        fixCmd: claudeStopInstalled ? undefined : "gocode-notify setup",
+    });
+    // ── 3b. Claude Code Notification hook ──────────────────────────────────
+    const claudeNotifyCommands = flattenHookCommands(claudeHooks &&
+        typeof claudeHooks === "object" &&
+        "Notification" in claudeHooks
+        ? claudeHooks.Notification
+        : null);
+    const claudeNotifyInstalled = claudeNotifyCommands.some((c) => c.includes(CLAUDE_HOOK_TOKEN));
+    checks.push({
+        key: "hook:claude-notification",
+        label: "Claude Code Notification hook installed?",
+        ok: claudeNotifyInstalled,
+        detail: claudeNotifyInstalled
+            ? `found in ${claudeSettingsPath}`
+            : "hook not found",
+        fixCmd: claudeNotifyInstalled ? undefined : "gocode-notify setup",
+    });
+    // ── 3c. Cursor stop hook ───────────────────────────────────────────────
+    const cursorHooksPath = path.join(home, ".cursor", "hooks.json");
+    const cursorHooks = await readJsonFile(cursorHooksPath);
+    // Pass the stop array directly (not wrapped in an object) so extractCommands
+    // can find the {command: ...} entries inside it.
+    const cursorStopValue = cursorHooks &&
+        typeof cursorHooks === "object" &&
+        "stop" in cursorHooks
+        ? cursorHooks.stop
+        : null;
+    const cursorStopEntries = flattenHookCommands(cursorStopValue);
+    const cursorStopInstalled = cursorStopEntries.some((c) => c.includes(CURSOR_HOOK_TOKEN));
+    checks.push({
+        key: "hook:cursor-stop",
+        label: "Cursor stop hook installed?",
+        ok: cursorStopInstalled,
+        detail: cursorStopInstalled
+            ? `found in ${cursorHooksPath}`
+            : cursorHooks === null
+                ? "~/.cursor/hooks.json not found"
+                : "hook not found",
+        fixCmd: cursorStopInstalled ? undefined : "gocode-notify setup",
+    });
+    // ── 4. gocode-notify on PATH? ──────────────────────────────────────────
+    const pathEnv = opts.pathEnv ?? process.env.PATH;
+    const onPath = await commandOnPath("gocode-notify", pathEnv);
+    checks.push({
+        key: "path",
+        label: "gocode-notify on PATH (non-login shells)?",
+        ok: onPath,
+        detail: onPath
+            ? "gocode-notify is resolvable"
+            : "not found on PATH — hooks may fail in non-login shells",
+        fixCmd: onPath
+            ? undefined
+            : "# Add npm global bin to PATH, e.g.:\n  echo 'export PATH=\"$(npm root -g)/../.bin:$PATH\"' >> ~/.bashrc",
+    });
+    return { checks };
+}
+// ─── Formatting ─────────────────────────────────────────────────────────────
+function mark(ok) {
+    return ok ? "✓" : "✗";
+}
+// UNPAIRED_WARNING is defined in status.ts and re-exported above (T-COV1).
+/**
+ * Render a {@link DoctorReport} as human-readable lines. Each failing check
+ * includes the exact fix command. Always friendly — never emits an error tone
+ * for passing checks.
+ */
+export function formatDoctor(report) {
+    const lines = ["gocode-notify doctor", ""];
+    for (const check of report.checks) {
+        lines.push(`${mark(check.ok)} ${check.label}`);
+        lines.push(`    ${check.detail}`);
+        if (!check.ok && check.fixCmd) {
+            lines.push(`    Fix: ${check.fixCmd}`);
+        }
+        lines.push("");
+    }
+    // Surface the unpaired warning loudly (T-COV1 requirement: "surface ⚠️ loop
+    // completion pushes will NOT reach your phone" when not paired).
+    const pairedCheck = report.checks.find((c) => c.key === "paired");
+    if (pairedCheck && !pairedCheck.ok) {
+        lines.push(UNPAIRED_WARNING);
+        lines.push("");
+    }
+    const allOk = report.checks.every((c) => c.ok);
+    lines.push(allOk ? "All checks passed." : "Some checks failed — see fix commands above.");
+    return lines;
+}

package/dist/src/launch.js

@@ -0,0 +1,218 @@
+// Internal launch() — the single code path every desktop trigger (CLI / MCP)
+// funnels through to POST `/api/v1/notify/launch`, which starts a server-side
+// Autopilot loop for the `gck_` key's bound user (Remote Autopilot Launch PRD
+// §4.1). It mirrors `send()` as the shared core (PRD §4 "all three funnel
+// through the same internal launch()").
+//
+// Contract (PRD §4.2 / §4.3 "launch is explicit, not fire-and-forget"):
+//   - Reads the `gck_` key from `~/.gocode/credentials` (same path as `send()`).
+//   - Resolves the server URL with full precedence (flag → env → creds →
+//     default) via `resolveServerUrl`.
+//   - Auto-detects the IDE label (best-effort, label only, falls back to "ide").
+//   - POSTs the task/PRD; on success returns the 202 projection
+//     `{ ok, loop_id?, project_id?, conversation_id?, prd_title?, origin?,
+//     deep_link? }`; on any failure returns `{ ok: false, error }`.
+//   - NEVER throws / rejects — always resolves to a {@link LaunchResult}. The
+//     CLI/MCP layer decides the exit code / how to relay it (unlike `send`,
+//     launch reports real failures with a non-zero exit, but the *core* still
+//     returns a result rather than throwing).
+//   - Does NOT queue to the offline outbox — a stale launch surfacing hours
+//     later would be surprising and could duplicate work (PRD §4.2).
+//
+// Failures are appended to `~/.gocode/notify.log` (the same trail `send` uses).
+// Zero runtime deps — Node built-ins only, matching the package rule.
+import { builtinDefaultServer, readCredentials, resolveServerUrl, } from "./creds.js";
+import { appendLog } from "./send.js";
+/** The launch endpoint path on the notify router (PRD §3.2). */
+export const LAUNCH_PATH = "/api/v1/notify/launch";
+/**
+ * Default request timeout. Longer than `send`'s 5s hard cap because the server
+ * may run a PRD-synthesis turn before spawning the loop (PRD §3.2 step 5). Still
+ * bounded so a wedged server can never hang the desktop agent indefinitely.
+ */
+export const DEFAULT_LAUNCH_TIMEOUT_MS = 30_000;
+/**
+ * Canonical IDE labels the server understands (PRD §3.2). The label is sanitized
+ * + capped server-side; this is just the best-effort client classification.
+ */
+export const IDE_LABEL_FALLBACK = "ide";
+function errMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/** Strip trailing slashes so `${server}${path}` is always clean. */
+function normalizeServer(url) {
+    return url.trim().replace(/\/+$/, "");
+}
+/** True when `env` has any key beginning with `prefix` (case-sensitive). */
+function hasEnvPrefix(env, prefix) {
+    for (const key of Object.keys(env)) {
+        if (key.startsWith(prefix) && env[key] !== undefined && env[key] !== "") {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Best-effort classify the IDE the agent runs in from its environment (PRD
+ * §4.1). Cursor exports `CURSOR_*`, Claude Code `CLAUDECODE`/`CLAUDE_*`, OpenCode
+ * `OPENCODE_*`. Returns one of the canonical labels (`cursor` / `claude_code` /
+ * `opencode`) or {@link IDE_LABEL_FALLBACK} when none is recognised. Never throws.
+ */
+export function detectIdeLabel(env = process.env) {
+    // Claude Code sets CLAUDECODE=1 plus assorted CLAUDE_* vars.
+    if (env.CLAUDECODE || hasEnvPrefix(env, "CLAUDE_CODE") || hasEnvPrefix(env, "CLAUDE")) {
+        return "claude_code";
+    }
+    if (hasEnvPrefix(env, "CURSOR"))
+        return "cursor";
+    if (hasEnvPrefix(env, "OPENCODE"))
+        return "opencode";
+    return IDE_LABEL_FALLBACK;
+}
+/**
+ * Build the JSON request body for `/notify/launch`. Exactly one of `message` /
+ * `prd_markdown` is included; `prd_markdown` is base64-encoded from the raw
+ * input. Optional fields are dropped when unset. The server forces `origin`
+ * itself (its schema is `extra="forbid"`), so we never send it — including it
+ * would be rejected with a 422.
+ */
+function buildBody(input, ide) {
+    const body = {};
+    if (input.message && input.message.trim() !== "") {
+        body.message = input.message;
+    }
+    else if (input.prdMarkdown && input.prdMarkdown !== "") {
+        body.prd_markdown = Buffer.from(input.prdMarkdown, "utf8").toString("base64");
+    }
+    const optional = [
+        ["prdFilename", "prd_filename"],
+        ["selectedRepository", "selected_repository"],
+        ["branchSuffix", "branch_suffix"],
+        ["runnerKind", "runner_kind"],
+        ["modelOverride", "model_override"],
+    ];
+    for (const [from, to] of optional) {
+        const v = input[from];
+        if (typeof v === "string" && v.trim() !== "")
+            body[to] = v;
+    }
+    if (ide && ide.trim() !== "")
+        body.ide = ide;
+    return body;
+}
+async function failure(reason, opts, extra = {}) {
+    await appendLog(`LAUNCH FAIL: ${reason}`, opts);
+    return { ok: false, error: reason, ...extra };
+}
+/** Pull a readable reason out of a FastAPI error body (`{detail: ...}`). */
+function extractDetail(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const detail = parsed.detail;
+    if (typeof detail === "string")
+        return detail;
+    if (detail && typeof detail === "object") {
+        const reason = detail.reason;
+        const text = detail.detail;
+        const parts = [reason, text].filter((p) => typeof p === "string");
+        if (parts.length)
+            return parts.join(": ");
+        try {
+            return JSON.stringify(detail);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Launch a server-side Autopilot loop. Resolves (never rejects) to a
+ * {@link LaunchResult}. The caller is responsible for exit code / messaging.
+ */
+export async function launch(input, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_LAUNCH_TIMEOUT_MS;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const env = opts.env ?? process.env;
+    // Local exactly-one-of guard — gives the CLI/MCP a clear error before any
+    // network round-trip (the server enforces the same rule with a 422).
+    const hasMessage = !!(input.message && input.message.trim() !== "");
+    const hasPrd = !!(input.prdMarkdown && input.prdMarkdown !== "");
+    if (hasMessage === hasPrd) {
+        const reason = hasMessage
+            ? "provide either a task message OR a PRD, not both"
+            : "a task message or PRD is required";
+        return failure(reason, opts);
+    }
+    let creds;
+    try {
+        creds = await readCredentials(opts);
+    }
+    catch (err) {
+        return failure(`credentials unreadable: ${errMessage(err)}`, opts);
+    }
+    if (!creds) {
+        return failure("not paired — run `gocode-notify login` first", opts);
+    }
+    const server = normalizeServer(opts.server ?? (await resolveServerUrl(opts.serverFlag, opts)) ?? builtinDefaultServer());
+    const url = `${server}${LAUNCH_PATH}`;
+    const ide = input.ide && input.ide.trim() !== "" ? input.ide.trim() : detectIdeLabel(env);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${creds.api_key}`,
+            },
+            body: JSON.stringify(buildBody(input, ide)),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            let detail;
+            try {
+                detail = extractDetail(await res.json());
+            }
+            catch {
+                // Non-JSON / empty error body — fall back to the bare status.
+            }
+            const suffix = detail ? `: ${detail}` : "";
+            return failure(`server responded ${res.status}${suffix}`, opts, {
+                status: res.status,
+            });
+        }
+        let parsed = {};
+        try {
+            parsed = (await res.json());
+        }
+        catch {
+            // A 2xx with an unparseable body still counts as launched, but we have no
+            // ids to relay — surface that rather than pretending we got the projection.
+            return { ok: true, status: res.status, ide };
+        }
+        const str = (k) => typeof parsed[k] === "string" ? parsed[k] : undefined;
+        return {
+            ok: true,
+            status: res.status,
+            loop_id: str("loop_id"),
+            project_id: str("project_id"),
+            conversation_id: str("conversation_id"),
+            prd_title: str("prd_title"),
+            origin: str("origin"),
+            deep_link: str("deep_link"),
+            ide,
+        };
+    }
+    catch (err) {
+        const reason = controller.signal.aborted
+            ? `timeout after ${timeoutMs}ms`
+            : `request failed: ${errMessage(err)}`;
+        return failure(reason, opts);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/mcp.js

@@ -1,13 +1,15 @@
 // gocode-notify MCP server mode (`gocode-notify mcp`) — PRD §4.3.
 //
-// A minimal stdio MCP server exposing EXACTLY two tools (keep it tiny — more
-// tools = more agent confusion):
-//   - gocode_notify         → on-demand push (thin wrapper over internal send())
-//   - gocode_notify_status  → creds-present + server-reachable self-diagnosis
+// A minimal stdio MCP server exposing THREE tools (keep it tiny + the
+// descriptions sharp — more tools = more agent confusion):
+//   - gocode_notify           → on-demand push (thin wrapper over internal send())
+//   - gocode_notify_status    → creds-present + server-reachable self-diagnosis
+//   - gocode_launch_autopilot → hand a BIG task off to the user's GoCode server
+//                               to run as a server-side Autopilot loop (launch())
 //
-// Both handlers funnel through the SAME internals as the CLI (`send()` /
-// `gatherStatus()`), so behaviour is identical across every trigger (hook /
-// loop / MCP / CLI). We use the official MCP TypeScript SDK low-level `Server`
+// All handlers funnel through the SAME internals as the CLI (`send()` /
+// `gatherStatus()` / `launch()`), so behaviour is identical across every trigger
+// (hook / loop / MCP / CLI). We use the official MCP TypeScript SDK low-level `Server`
 // with raw JSON-Schema tool definitions — no zod in our OWN code — so the
 // package's direct dependency stays just `@modelcontextprotocol/sdk`.
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -17,17 +19,21 @@ import { VERSION } from "./version.js";
 import { resolveServerUrl } from "./creds.js";
 import { send, isNotifyKind, NOTIFY_KINDS, } from "./send.js";
 import { gatherStatus } from "./status.js";
+import { launch } from "./launch.js";
 /** Server identity advertised in the MCP `initialize` handshake. */
 export const SERVER_NAME = "gocode-notify";
 /** Tool name an agent calls to send an on-demand push. */
 export const NOTIFY_TOOL = "gocode_notify";
 /** Tool name an agent calls to self-diagnose pairing/reachability. */
 export const STATUS_TOOL = "gocode_notify_status";
+/** Tool name an agent calls to offload a big task to the user's server. */
+export const LAUNCH_TOOL = "gocode_launch_autopilot";
 /**
- * The two tools this server exposes (PRD §4.3). Declared as a plain constant so
+ * The three tools this server exposes (PRD §4.3). Declared as a plain constant so
  * the handshake smoke test can assert the exact shape without spinning the
  * transport. `gocode_notify`'s schema mirrors the documented args
- * `{ kind?, title, body?, project? }`; only `title` is required.
+ * `{ kind?, title, body?, project? }` (only `title` is required);
+ * `gocode_launch_autopilot`'s schema is `{ task(req), repo?, branch? }`.
  */
 export const TOOLS = [
     {
@@ -70,6 +76,38 @@ export const TOOLS = [
             additionalProperties: false,
         },
     },
+    {
+        name: LAUNCH_TOOL,
+        description: "Hand a LARGE, multi-step coding task off to the user's GoCode server to run " +
+            "as an autonomous Autopilot loop — so it keeps running after the user closes " +
+            "their laptop, and their phone is notified when it's done. Call this ONLY " +
+            "when the user EXPLICITLY asks to offload/hand-off work to their server or to " +
+            "run something in the background / overnight / after they close their machine " +
+            '(e.g. "run this on the server", "do this overnight", "hand this off so I ' +
+            'can shut down"). Do NOT call it for normal tasks you can do right here — ' +
+            "those stay in this IDE session. The server loop is a FRESH agent with NO " +
+            "access to this IDE's open files / unsaved state, so pass a self-contained " +
+            "task description (and a repo) it can act on from a clean checkout.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task: {
+                    type: "string",
+                    description: "Plain-language task for the server loop to build. Required.",
+                },
+                repo: {
+                    type: "string",
+                    description: "Optional owner/repo context for the loop.",
+                },
+                branch: {
+                    type: "string",
+                    description: "Optional branch suffix the loop pushes to.",
+                },
+            },
+            required: ["task"],
+            additionalProperties: false,
+        },
+    },
 ];
 function textResult(text) {
     return { content: [{ type: "text", text }] };
@@ -143,7 +181,49 @@ export async function handleStatus(deps = {}) {
     return { content: [{ type: "text", text: lines.join("\n") }], isError: !ok };
 }
 /**
- * Build the MCP {@link Server} with the two tools registered. Pure (does not
+ * Handle a `gocode_launch_autopilot` tool call. Validates `task` (required,
+ * non-empty), then funnels through the shared internal {@link launch} — the SAME
+ * code path as the CLI `launch` command — to start a server-side Autopilot loop
+ * for the `gck_` key's bound user. The `origin: ide-launch` + detected `ide`
+ * label are set inside `launch()`/server-side, so the agent never smuggles them.
+ * Like the notify tool, it does NOT queue offline — a remote launch is explicit
+ * and must report real failures back so the agent can re-pair / retry.
+ */
+export async function handleLaunch(args, deps = {}) {
+    const a = args ?? {};
+    const task = typeof a.task === "string" ? a.task.trim() : "";
+    if (task === "") {
+        return errorResult("gocode_launch_autopilot: `task` is required.");
+    }
+    const input = { message: task };
+    if (typeof a.repo === "string" && a.repo.trim() !== "") {
+        input.selectedRepository = a.repo.trim();
+    }
+    if (typeof a.branch === "string" && a.branch.trim() !== "") {
+        input.branchSuffix = a.branch.trim();
+    }
+    const result = await launch(input, {
+        home: deps.home,
+        fetchImpl: deps.fetchImpl,
+        timeoutMs: deps.timeoutMs,
+        serverFlag: deps.serverFlag,
+    });
+    if (!result.ok) {
+        return errorResult(`Could not launch Autopilot loop: ${result.error}. ` +
+            "If this machine is not paired, ask the user to run `gocode-notify login`.");
+    }
+    const loop = result.loop_id ?? "(id pending)";
+    const lines = [
+        `Autopilot launched on your GoCode server (loop ${loop}).`,
+    ];
+    if (result.deep_link)
+        lines.push(`Open in the app: ${result.deep_link}`);
+    lines.push("It's running on your server — you can close your laptop; your phone will " +
+        "buzz when it's done or needs you.");
+    return textResult(lines.join("\n"));
+}
+/**
+ * Build the MCP {@link Server} with the three tools registered. Pure (does not
  * touch the network or connect a transport) so the handshake smoke test can
  * drive it over an in-memory transport.
  */
@@ -158,6 +238,9 @@ export function createMcpServer(deps = {}) {
         if (name === STATUS_TOOL) {
             return handleStatus(deps);
         }
+        if (name === LAUNCH_TOOL) {
+            return handleLaunch(args, deps);
+        }
         return errorResult(`Unknown tool: ${name}`);
     });
     return server;