@ai-codebot/daemon 0.1.0

package/dist/spawn/cli-runner.js

@@ -0,0 +1,180 @@
+/**
+ * PRIMARY executor: spawn a real coding-agent CLI (Claude Code / Codex) in
+ * `cwd=repo`, headless, talking to the broker, with the disallowed-tools blacklist
+ * applied (design §4 — R1-NEW / DR-6).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * OQ-3: the headless / JSON-output / disallowed-tools flag contract per shipped
+ * CLI. `claude` (Claude Code 2.1.169) flag NAMES are VERIFIED against the real
+ * binary (see the contract entry below); `codex` (codex-cli 0.137.0) is left
+ * `verified:false` because it has NO disallowed-tools concept — its sandbox /
+ * approval model does not map to the C5 tool blacklist, so enabling PRIMARY-codex
+ * needs a design decision and until then the runner FAILS FAST → N2. The runner
+ * NEVER emits a silent wrong invocation. The N2 fallback (n2-runner.ts) is the
+ * fully-tested path that covers "no verified CLI".
+ *
+ * NOTE: the live-model E2E spawn proof remains the MANUAL `verify-daemon.mjs`
+ * step — these unit tests pin the argv shape, not a real spawn against a model.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * To enable a CLI here: verify the real flag names against the shipped binary,
+ * flip the `verified: true` contract entry, and add an integration proof in
+ * `verify-daemon.mjs`. Until then this runner throws `CliContractUnverifiedError`
+ * and `launch.ts` routes to N2.
+ */
+import { spawn } from "node:child_process";
+import { log } from "../logging.js";
+import { DISALLOWED_TOOLS } from "./disallowed-tools.js";
+import { captureDiff, headSha } from "./git.js";
+const CLI_FLAG_CONTRACT = {
+    // Claude Code 2.1.169 — flag NAMES VERIFIED against the real binary. `--print`
+    // is headless; `--output-format stream-json`; `--permission-mode
+    // bypassPermissions`; `--disallowedTools <tools...>` is VARIADIC (one flag,
+    // space-separated tool list). Because the variadic list would greedily eat the
+    // trailing positional prompt as another tool name, buildCliArgv emits a `--`
+    // separator before the prompt (see below).
+    claude: {
+        verified: true,
+        subcommand: null,
+        headlessFlag: "--print",
+        jsonOutputFlag: "--output-format=stream-json",
+        bypassFlag: "--permission-mode=bypassPermissions",
+        disallowStyle: "variadic",
+        disallowFlag: "--disallowedTools",
+    },
+    // codex-cli 0.137.0 — non-interactive mode is the `exec` SUBCOMMAND
+    // (`codex exec [OPTIONS] [PROMPT]`); JSON via `--json`; sandbox via
+    // `-s/--sandbox <mode>` or `--dangerously-bypass-approvals-and-sandbox`.
+    // codex has NO disallowed-tools flag: it governs tools via sandbox/approval,
+    // which does NOT map to a tool blacklist. So `disallowStyle: "none"` and we
+    // KEEP `verified: false` — enabling PRIMARY-codex needs a design decision for
+    // how the C5 blacklist maps; until then the runner fails fast → N2.
+    codex: {
+        verified: false,
+        subcommand: "exec",
+        headlessFlag: "",
+        jsonOutputFlag: "--json",
+        bypassFlag: "--dangerously-bypass-approvals-and-sandbox",
+        disallowStyle: "none",
+        disallowFlag: "",
+    },
+};
+export class CliContractUnverifiedError extends Error {
+    constructor(cli) {
+        super(`CLI '${cli}' flag contract is UNVERIFIED (OQ-3) — refusing to spawn a possibly-wrong ` +
+            `invocation. Falling back to N2. Verify the real flag names and set verified:true.`);
+        this.name = "CliContractUnverifiedError";
+    }
+}
+/**
+ * Build the argv for a CLI invocation. PUBLIC for unit testing the argv shape
+ * (disallowed-tools present, bypass flag, headless+json) without spawning.
+ */
+export function buildCliArgv(cli, prompt) {
+    const contract = CLI_FLAG_CONTRACT[cli];
+    const args = [];
+    // Some CLIs put non-interactive mode behind a subcommand (codex's `exec`).
+    if (contract.subcommand !== null) {
+        args.push(contract.subcommand);
+    }
+    // headlessFlag may be empty when the subcommand itself IS the headless mode.
+    if (contract.headlessFlag !== "") {
+        args.push(contract.headlessFlag);
+    }
+    args.push(contract.jsonOutputFlag, contract.bypassFlag);
+    // The C5 blacklist mapping is per-CLI (see CliFlagContract.disallowStyle).
+    let emittedVariadic = false;
+    switch (contract.disallowStyle) {
+        case "variadic":
+            // ONE flag followed by every tool as a separate arg (claude). The list is
+            // variadic, so it would greedily consume the trailing positional prompt as
+            // another tool — guarded by the `--` separator emitted below.
+            args.push(contract.disallowFlag, ...DISALLOWED_TOOLS);
+            emittedVariadic = true;
+            break;
+        case "repeated":
+            for (const tool of DISALLOWED_TOOLS) {
+                args.push(contract.disallowFlag, tool);
+            }
+            break;
+        case "csv":
+            args.push(contract.disallowFlag, DISALLOWED_TOOLS.join(","));
+            break;
+        case "none":
+            // The CLI has no disallowed-tools concept (codex); nothing to emit.
+            break;
+    }
+    // Prompt passed positionally last. When a variadic flag precedes it, emit `--`
+    // first so the variadic list stops and the prompt is not eaten as a tool name.
+    if (emittedVariadic) {
+        args.push("--");
+    }
+    args.push(prompt);
+    return { command: cli, args, contract };
+}
+/**
+ * Run the PRIMARY CLI. Throws `CliContractUnverifiedError` if the flag contract is
+ * not verified (OQ-3 fail-fast) so the caller routes to N2 — NEVER a silent wrong
+ * invocation. On a verified contract, spawns, captures the BASE..HEAD diff, and
+ * maps the exit code to an outcome.
+ */
+export async function runCli(params) {
+    const { cli, repo, prompt, env, signal } = params;
+    const { command, args, contract } = buildCliArgv(cli, prompt);
+    if (!contract.verified) {
+        // OQ-3 fail-fast: do not spawn a possibly-wrong invocation.
+        throw new CliContractUnverifiedError(cli);
+    }
+    const base = await headSha(repo);
+    if (base === null) {
+        return { kind: "failed", error: `repo '${repo}' is not a git repository` };
+    }
+    log.info("spawn.cli.start", { cli, repo });
+    return new Promise((resolvePromise) => {
+        const child = spawn(command, args, {
+            cwd: repo,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+            signal,
+        });
+        let stderrTail = "";
+        let stdoutTail = "";
+        child.stdout?.on("data", (chunk) => {
+            stdoutTail = (stdoutTail + chunk.toString("utf8")).slice(-65536);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderrTail = (stderrTail + chunk.toString("utf8")).slice(-65536);
+        });
+        child.on("error", (err) => {
+            if (err.name === "AbortError") {
+                resolvePromise({ kind: "timed_out" });
+                return;
+            }
+            resolvePromise({
+                kind: "failed",
+                error: `failed to spawn ${cli}: ${err.message}`,
+            });
+        });
+        child.on("close", async (code, sigterm) => {
+            if (signal.aborted) {
+                resolvePromise({ kind: "timed_out" });
+                return;
+            }
+            const { diff, files } = await captureDiff(repo, base);
+            if (code === 0) {
+                resolvePromise({
+                    kind: "success",
+                    text: stdoutTail.trim() || null,
+                    diff: diff || null,
+                    files,
+                });
+                return;
+            }
+            resolvePromise({
+                kind: "failed",
+                error: `${cli} exited with code ${code ?? sigterm}: ${stderrTail.trim()}`,
+            });
+        });
+    });
+}
+//# sourceMappingURL=cli-runner.js.map

package/dist/spawn/cli-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-runner.js","sourceRoot":"","sources":["../../src/spawn/cli-runner.ts"],"names":[],"mappings":"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"}

package/dist/spawn/detect.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI detection (design §4). Decides whether a real coding-agent CLI is available
+ * on PATH for the requested `--cli` mode, or whether to fall back to N2.
+ *
+ * Detection is a `which`-style PATH probe (no execution of the CLI), so it is cheap
+ * and side-effect-free. The PRIMARY runner does the real fail-fast contract check
+ * (cli-runner.ts).
+ */
+import type { CliKind } from "../config.js";
+export type DetectedCli = "claude" | "codex" | null;
+/** True if `name` is found on PATH (POSIX `which` equivalent, no execution). */
+export declare function isOnPath(name: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve which CLI to use for the requested mode, or null to force N2.
+ *   - `auto`: prefer claude, then codex, else null.
+ *   - `claude` / `codex`: that one if present, else null (→ N2, never the wrong CLI).
+ */
+export declare function detectCli(mode: CliKind, env?: NodeJS.ProcessEnv): DetectedCli;

package/dist/spawn/detect.js

@@ -0,0 +1,46 @@
+/**
+ * CLI detection (design §4). Decides whether a real coding-agent CLI is available
+ * on PATH for the requested `--cli` mode, or whether to fall back to N2.
+ *
+ * Detection is a `which`-style PATH probe (no execution of the CLI), so it is cheap
+ * and side-effect-free. The PRIMARY runner does the real fail-fast contract check
+ * (cli-runner.ts).
+ */
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+const CLI_BINARIES = {
+    // On Windows these would be `.cmd`; the daemon targets Node 20 on POSIX hosts.
+    claude: ["claude"],
+    codex: ["codex"],
+};
+/** True if `name` is found on PATH (POSIX `which` equivalent, no execution). */
+export function isOnPath(name, env = process.env) {
+    const pathVar = env["PATH"] ?? "";
+    for (const dir of pathVar.split(delimiter)) {
+        if (!dir)
+            continue;
+        if (existsSync(join(dir, name)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve which CLI to use for the requested mode, or null to force N2.
+ *   - `auto`: prefer claude, then codex, else null.
+ *   - `claude` / `codex`: that one if present, else null (→ N2, never the wrong CLI).
+ */
+export function detectCli(mode, env = process.env) {
+    if (mode === "claude") {
+        return CLI_BINARIES.claude.some((b) => isOnPath(b, env)) ? "claude" : null;
+    }
+    if (mode === "codex") {
+        return CLI_BINARIES.codex.some((b) => isOnPath(b, env)) ? "codex" : null;
+    }
+    // auto
+    if (CLI_BINARIES.claude.some((b) => isOnPath(b, env)))
+        return "claude";
+    if (CLI_BINARIES.codex.some((b) => isOnPath(b, env)))
+        return "codex";
+    return null;
+}
+//# sourceMappingURL=detect.js.map

package/dist/spawn/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/spawn/detect.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAM5C,MAAM,YAAY,GAAyC;IACzD,+EAA+E;IAC/E,MAAM,EAAE,CAAC,QAAQ,CAAC;IAClB,KAAK,EAAE,CAAC,OAAO,CAAC;CACjB,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,QAAQ,CACtB,IAAY,EACZ,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3C,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,IAAa,EACb,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7E,CAAC;IACD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,CAAC;IACD,OAAO;IACP,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvE,IAAI,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC;IACrE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/spawn/disallowed-tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Disallowed-tools blacklist (design §4 — C5). SINGLE SOURCE OF TRUTH.
+ *
+ * These tool names must never be available to the spawned agent: for the real CLI
+ * they become `--disallowedTools` flags (stripped before spawn); for the N2 local
+ * tool-loop they are simply never registered.
+ *
+ * Rationale: the local runner executes one bounded launch. Tools that schedule
+ * future work, spawn sub-agents, or dispatch tasks would let the agent escape that
+ * bound (persistence / fan-out / lateral movement). The path allowlist + broker are
+ * the credential boundary; this list is the capability boundary.
+ */
+export declare const DISALLOWED_TOOLS: readonly string[];
+/** True if a tool name is on the blacklist (case-sensitive, exact match). */
+export declare function isDisallowed(toolName: string): boolean;

package/dist/spawn/disallowed-tools.js

@@ -0,0 +1,30 @@
+/**
+ * Disallowed-tools blacklist (design §4 — C5). SINGLE SOURCE OF TRUTH.
+ *
+ * These tool names must never be available to the spawned agent: for the real CLI
+ * they become `--disallowedTools` flags (stripped before spawn); for the N2 local
+ * tool-loop they are simply never registered.
+ *
+ * Rationale: the local runner executes one bounded launch. Tools that schedule
+ * future work, spawn sub-agents, or dispatch tasks would let the agent escape that
+ * bound (persistence / fan-out / lateral movement). The path allowlist + broker are
+ * the credential boundary; this list is the capability boundary.
+ */
+export const DISALLOWED_TOOLS = [
+    "EnterPlanMode",
+    "ExitPlanMode",
+    "ScheduleWakeup",
+    "Cron",
+    "CronCreate",
+    "CronDelete",
+    "CronList",
+    "Task",
+    "Agent",
+    "SpawnAgent",
+    "Dispatch",
+];
+/** True if a tool name is on the blacklist (case-sensitive, exact match). */
+export function isDisallowed(toolName) {
+    return DISALLOWED_TOOLS.includes(toolName);
+}
+//# sourceMappingURL=disallowed-tools.js.map

package/dist/spawn/disallowed-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disallowed-tools.js","sourceRoot":"","sources":["../../src/spawn/disallowed-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAsB;IACjD,eAAe;IACf,cAAc;IACd,gBAAgB;IAChB,MAAM;IACN,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,MAAM;IACN,OAAO;IACP,YAAY;IACZ,UAAU;CACF,CAAC;AAEX,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC7C,CAAC"}

package/dist/spawn/git.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Minimal git helpers for diff capture (design §4 — DR-6, mirrors the Python
+ * `agentic_backend` A2 contract: capture BASE..HEAD, the workspace is a real repo,
+ * never `git init`).
+ *
+ * All git runs via `execFile` (argv only, `shell=false`) — no model-supplied string
+ * ever reaches a shell.
+ */
+export interface GitDiff {
+    diff: string;
+    files: string[];
+}
+/** Resolve the current HEAD sha (the diff base, captured before the agent runs). */
+export declare function headSha(repo: string): Promise<string | null>;
+/**
+ * Capture the working-tree diff against `baseSha`. Stages all changes first (to
+ * include new files), then diffs `baseSha..` against the index + worktree.
+ */
+export declare function captureDiff(repo: string, baseSha: string): Promise<GitDiff>;

package/dist/spawn/git.js

@@ -0,0 +1,56 @@
+/**
+ * Minimal git helpers for diff capture (design §4 — DR-6, mirrors the Python
+ * `agentic_backend` A2 contract: capture BASE..HEAD, the workspace is a real repo,
+ * never `git init`).
+ *
+ * All git runs via `execFile` (argv only, `shell=false`) — no model-supplied string
+ * ever reaches a shell.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+async function git(repo, args) {
+    try {
+        const { stdout } = await execFileAsync("git", args, {
+            cwd: repo,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return { code: 0, stdout };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            code: typeof e.code === "number" ? e.code : 1,
+            stdout: e.stdout ?? "",
+        };
+    }
+}
+/** Resolve the current HEAD sha (the diff base, captured before the agent runs). */
+export async function headSha(repo) {
+    const { code, stdout } = await git(repo, ["rev-parse", "HEAD"]);
+    if (code !== 0)
+        return null;
+    const sha = stdout.trim();
+    return sha || null;
+}
+/**
+ * Capture the working-tree diff against `baseSha`. Stages all changes first (to
+ * include new files), then diffs `baseSha..` against the index + worktree.
+ */
+export async function captureDiff(repo, baseSha) {
+    // `git add -A` so new/untracked files show in the diff; this does not commit.
+    await git(repo, ["add", "-A"]);
+    const diffRes = await git(repo, ["diff", "--cached", baseSha]);
+    const filesRes = await git(repo, [
+        "diff",
+        "--cached",
+        "--name-only",
+        baseSha,
+    ]);
+    const files = filesRes.stdout
+        .split("\n")
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0);
+    return { diff: diffRes.stdout, files };
+}
+//# sourceMappingURL=git.js.map

package/dist/spawn/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/spawn/git.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAO1C,KAAK,UAAU,GAAG,CAChB,IAAY,EACZ,IAAc;IAEd,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE;YAClD,GAAG,EAAE,IAAI;YACT,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;SAC5B,CAAC,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAAyC,CAAC;QACpD,OAAO;YACL,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC7C,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE;SACvB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAY;IACxC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAChE,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC1B,OAAO,GAAG,IAAI,IAAI,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,OAAe;IAEf,8EAA8E;IAC9E,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE;QAC/B,MAAM;QACN,UAAU;QACV,aAAa;QACb,OAAO;KACR,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM;SAC1B,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;AACzC,CAAC"}

package/dist/spawn/llm-client.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Minimal OpenAI-compatible chat-completions client for the N2 tool-loop.
+ *
+ * It talks ONLY to the broker (`baseUrl` = the 127.0.0.1 broker URL) with the
+ * per-launch capability token — never the real provider directly. The broker
+ * injects the real key and forwards upstream. The model id is supplied by the
+ * launch / config; the daemon does not pick a provider.
+ *
+ * Kept deliberately tiny (one POST, tool-calls in/out) — the broker is the security
+ * boundary; this is just request shaping.
+ */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ToolDef {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface CompletionResult {
+    content: string;
+    toolCalls: ToolCall[];
+    finishReason: string;
+    model: string;
+}
+export interface LlmClientOptions {
+    /** Broker base URL (`http://127.0.0.1:<port>`). */
+    readonly baseUrl: string;
+    /** Per-launch capability token (NOT the real key). */
+    readonly token: string;
+    readonly model: string;
+    readonly maxTokens: number;
+}
+export declare class LlmClientError extends Error {
+}
+/** One chat-completion round-trip through the broker. */
+export declare function complete(opts: LlmClientOptions, messages: ChatMessage[], tools: ToolDef[], signal: AbortSignal): Promise<CompletionResult>;

package/dist/spawn/llm-client.js

@@ -0,0 +1,61 @@
+/**
+ * Minimal OpenAI-compatible chat-completions client for the N2 tool-loop.
+ *
+ * It talks ONLY to the broker (`baseUrl` = the 127.0.0.1 broker URL) with the
+ * per-launch capability token — never the real provider directly. The broker
+ * injects the real key and forwards upstream. The model id is supplied by the
+ * launch / config; the daemon does not pick a provider.
+ *
+ * Kept deliberately tiny (one POST, tool-calls in/out) — the broker is the security
+ * boundary; this is just request shaping.
+ */
+export class LlmClientError extends Error {
+}
+/** One chat-completion round-trip through the broker. */
+export async function complete(opts, messages, tools, signal) {
+    const url = `${opts.baseUrl.replace(/\/$/, "")}/v1/chat/completions`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${opts.token}`,
+            },
+            body: JSON.stringify({
+                model: opts.model,
+                messages,
+                tools,
+                tool_choice: "auto",
+                max_tokens: opts.maxTokens,
+            }),
+            signal,
+        });
+    }
+    catch (err) {
+        throw new LlmClientError(`model request failed: ${err.message}`);
+    }
+    if (!res.ok) {
+        throw new LlmClientError(`model returned HTTP ${res.status}`);
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch (err) {
+        throw new LlmClientError(`model returned invalid JSON: ${err.message}`);
+    }
+    const choice = body?.choices?.[0];
+    if (!choice || !choice.message) {
+        throw new LlmClientError("model response missing choices[0].message");
+    }
+    return {
+        content: choice.message.content ?? "",
+        toolCalls: Array.isArray(choice.message.tool_calls)
+            ? choice.message.tool_calls
+            : [],
+        finishReason: choice.finish_reason ?? "stop",
+        model: body.model ?? opts.model,
+    };
+}
+//# sourceMappingURL=llm-client.js.map

package/dist/spawn/llm-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-client.js","sourceRoot":"","sources":["../../src/spawn/llm-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyCH,MAAM,OAAO,cAAe,SAAQ,KAAK;CAAG;AAE5C,yDAAyD;AACzD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAsB,EACtB,QAAuB,EACvB,KAAgB,EAChB,MAAmB;IAEnB,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,sBAAsB,CAAC;IACrE,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YACrB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE;aACtC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,QAAQ;gBACR,KAAK;gBACL,WAAW,EAAE,MAAM;gBACnB,UAAU,EAAE,IAAI,CAAC,SAAS;aAC3B,CAAC;YACF,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,cAAc,CAAC,yBAA0B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,cAAc,CAAC,uBAAuB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,cAAc,CACtB,gCAAiC,GAAa,CAAC,OAAO,EAAE,CACzD,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAI,IAAgC,EAAE,OAAO,EAAE,CAAC,CAAC,CAKhD,CAAC;IACd,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAC/B,MAAM,IAAI,cAAc,CAAC,2CAA2C,CAAC,CAAC;IACxE,CAAC;IACD,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE;QACrC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;YACjD,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU;YAC3B,CAAC,CAAC,EAAE;QACN,YAAY,EAAE,MAAM,CAAC,aAAa,IAAI,MAAM;QAC5C,KAAK,EAAG,IAA2B,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK;KACxD,CAAC;AACJ,CAAC"}

package/dist/spawn/n2-runner.d.ts

@@ -0,0 +1,33 @@
+/**
+ * FALLBACK executor: the N2 local tool-loop (design §4 — ports
+ * `agentic_backend.py` A1/A2/A4/A5/A9 to TS). The fully-working, fully-tested path
+ * used when no verified CLI is available or `--cli` forces N2.
+ *
+ * Loop protocol (mirrors the Python backend):
+ *   1. Record HEAD as the diff base (A2 — workspace is a real repo, no `git init`).
+ *   2. system + user messages → model (through the broker) with the closed toolset.
+ *   3. Append ALL tool results before honoring `finish` (A4); `finish` ends the loop.
+ *   4. On `finish`: capture BASE..worktree diff; map to an outcome.
+ *
+ * `success` (Python) → `succeeded` (wire) happens in result-map.ts; this returns the
+ * internal `ExecOutcome`.
+ */
+import type { ExecOutcome } from "./result-map.js";
+export interface N2RunParams {
+    readonly repo: string;
+    readonly prompt: string;
+    readonly model: string;
+    /** Broker base URL. */
+    readonly brokerBaseUrl: string;
+    /** Per-launch capability token. */
+    readonly token: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly testTimeoutMs: number;
+    readonly signal: AbortSignal;
+    readonly maxTurns?: number;
+}
+/**
+ * Run the N2 tool-loop. Returns an internal `ExecOutcome`. NEVER throws on a
+ * model/tool error — that becomes a `failed` outcome (零静默: exactly one outcome).
+ */
+export declare function runN2(params: N2RunParams): Promise<ExecOutcome>;