@botcord/daemon 0.1.1

package/dist/gateway/index.js

@@ -0,0 +1,15 @@
+export * from "./types.js";
+export * from "./log.js";
+export * from "./runtimes/registry.js";
+export * from "./channels/index.js";
+export { sanitizeUntrustedContent, sanitizeSenderName } from "./channels/sanitize.js";
+export { sessionKey, SessionStore } from "./session-store.js";
+export { resolveRoute, matchesRoute } from "./router.js";
+export { ChannelManager } from "./channel-manager.js";
+export { Dispatcher } from "./dispatcher.js";
+export { Gateway } from "./gateway.js";
+export { ClaudeCodeAdapter, probeClaude, resolveClaudeCommand, } from "./runtimes/claude-code.js";
+export { CodexAdapter, probeCodex, resolveCodexCommand } from "./runtimes/codex.js";
+export { GeminiAdapter, probeGemini, resolveGeminiCommand } from "./runtimes/gemini.js";
+export { NdjsonStreamAdapter, } from "./runtimes/ndjson-stream.js";
+export { firstExistingPath, readCommandVersion, resolveCommandOnPath, resolveHomePath, } from "./runtimes/probe.js";

package/dist/gateway/log.d.ts

@@ -0,0 +1,9 @@
+/** Structured logger interface used across the gateway core and adapters. */
+export interface GatewayLogger {
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+    debug(msg: string, meta?: Record<string, unknown>): void;
+}
+/** Default logger that writes JSON lines to stderr; debug lines gated by BOTCORD_GATEWAY_DEBUG. */
+export declare const consoleLogger: GatewayLogger;

package/dist/gateway/log.js

@@ -0,0 +1,20 @@
+function write(level, msg, meta) {
+    const line = JSON.stringify({
+        ts: new Date().toISOString(),
+        level,
+        msg,
+        ...(meta ?? {}),
+    });
+    // Always write to stderr so stdout stays clean for NDJSON-style channel output.
+    process.stderr.write(line + "\n");
+}
+/** Default logger that writes JSON lines to stderr; debug lines gated by BOTCORD_GATEWAY_DEBUG. */
+export const consoleLogger = {
+    info: (msg, meta) => write("info", msg, meta),
+    warn: (msg, meta) => write("warn", msg, meta),
+    error: (msg, meta) => write("error", msg, meta),
+    debug: (msg, meta) => {
+        if (process.env.BOTCORD_GATEWAY_DEBUG)
+            write("debug", msg, meta);
+    },
+};

package/dist/gateway/router.d.ts

@@ -0,0 +1,10 @@
+import type { GatewayConfig, GatewayInboundMessage, GatewayRoute, RouteMatch } from "./types.js";
+/** Returns true if every provided field of `match` matches `message`; undefined match matches all. */
+export declare function matchesRoute(message: GatewayInboundMessage, match: RouteMatch | undefined): boolean;
+/**
+ * Picks the first matching route in priority order:
+ *   1. `config.routes[]` (user-authored)
+ *   2. `managedRoutes` (daemon-synthesized per-agent)
+ *   3. `config.defaultRoute`
+ */
+export declare function resolveRoute(message: GatewayInboundMessage, config: Pick<GatewayConfig, "defaultRoute" | "routes">, managedRoutes?: readonly GatewayRoute[]): GatewayRoute;

package/dist/gateway/router.js

@@ -0,0 +1,48 @@
+/** Returns true if every provided field of `match` matches `message`; undefined match matches all. */
+export function matchesRoute(message, match) {
+    if (!match)
+        return true;
+    if (match.channel !== undefined && match.channel !== message.channel)
+        return false;
+    if (match.accountId !== undefined && match.accountId !== message.accountId)
+        return false;
+    if (match.conversationId !== undefined && match.conversationId !== message.conversation.id) {
+        return false;
+    }
+    if (match.conversationPrefix !== undefined &&
+        !message.conversation.id.startsWith(match.conversationPrefix)) {
+        return false;
+    }
+    if (match.conversationKind !== undefined &&
+        match.conversationKind !== message.conversation.kind) {
+        return false;
+    }
+    if (match.senderId !== undefined && match.senderId !== message.sender.id)
+        return false;
+    if (match.mentioned !== undefined) {
+        const actual = message.mentioned ?? false;
+        if (match.mentioned !== actual)
+            return false;
+    }
+    return true;
+}
+/**
+ * Picks the first matching route in priority order:
+ *   1. `config.routes[]` (user-authored)
+ *   2. `managedRoutes` (daemon-synthesized per-agent)
+ *   3. `config.defaultRoute`
+ */
+export function resolveRoute(message, config, managedRoutes) {
+    const routes = config.routes ?? [];
+    for (const route of routes) {
+        if (matchesRoute(message, route.match))
+            return route;
+    }
+    if (managedRoutes) {
+        for (const route of managedRoutes) {
+            if (matchesRoute(message, route.match))
+                return route;
+        }
+    }
+    return config.defaultRoute;
+}

package/dist/gateway/runtimes/claude-code.d.ts

@@ -0,0 +1,30 @@
+import { NdjsonStreamAdapter, type NdjsonEventCtx } from "./ndjson-stream.js";
+import { type ProbeDeps } from "./probe.js";
+import type { RuntimeProbeResult, RuntimeRunOptions } from "../types.js";
+/** Resolve the Claude Code CLI path on PATH or the macOS desktop bundle fallback. */
+export declare function resolveClaudeCommand(deps?: ProbeDeps): string | null;
+/** Probe whether the Claude Code CLI is installed and report its version. */
+export declare function probeClaude(deps?: ProbeDeps): RuntimeProbeResult;
+/**
+ * Claude Code adapter — spawns `claude -p "<text>" --output-format stream-json`
+ * (with `--resume <sid>` when available) and parses the ndjson stream.
+ *
+ * stream-json shape (abridged):
+ *   {type:"system", subtype:"init", session_id:"...", ...}
+ *   {type:"assistant", message:{content:[{type:"text", text:"..."} | {type:"tool_use", ...}]}}
+ *   {type:"user", message:{content:[{type:"tool_result", ...}]}}
+ *   {type:"result", subtype:"success", session_id:"...", total_cost_usd: 0.01, result:"final text"}
+ */
+export declare class ClaudeCodeAdapter extends NdjsonStreamAdapter {
+    readonly id: "claude-code";
+    private readonly explicitBinary;
+    private resolvedBinary;
+    constructor(opts?: {
+        binary?: string;
+    });
+    probe(): RuntimeProbeResult;
+    run(opts: RuntimeRunOptions): Promise<import("../types.js").RuntimeRunResult>;
+    protected resolveBinary(): string;
+    protected buildArgs(opts: RuntimeRunOptions): string[];
+    protected handleEvent(raw: unknown, ctx: NdjsonEventCtx): void;
+}

package/dist/gateway/runtimes/claude-code.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+import { NdjsonStreamAdapter } from "./ndjson-stream.js";
+import { firstExistingPath, readCommandVersion, resolveCommandOnPath, resolveHomePath, } from "./probe.js";
+const CLAUDE_DESKTOP_CLI_RELATIVE_PATH = path.join("Applications", "Claude Code URL Handler.app", "Contents", "MacOS", "claude");
+const CLAUDE_DESKTOP_CLI_SYSTEM_PATH = "/Applications/Claude Code URL Handler.app/Contents/MacOS/claude";
+function isValidClaudeSessionId(sessionId) {
+    if (sessionId.length === 0 || sessionId.length > 512)
+        return false;
+    if (sessionId.startsWith("-"))
+        return false;
+    for (const ch of sessionId) {
+        const code = ch.codePointAt(0);
+        if (code === undefined || code < 0x20 || code === 0x7f)
+            return false;
+    }
+    return true;
+}
+function invalidClaudeSessionIdError() {
+    return "claude-code: invalid sessionId (expected non-control text not starting with '-')";
+}
+/** Resolve the Claude Code CLI path on PATH or the macOS desktop bundle fallback. */
+export function resolveClaudeCommand(deps = {}) {
+    const onPath = resolveCommandOnPath("claude", deps);
+    if (onPath)
+        return onPath;
+    if ((deps.platform ?? process.platform) !== "darwin")
+        return null;
+    return firstExistingPath([resolveHomePath(CLAUDE_DESKTOP_CLI_RELATIVE_PATH, deps), CLAUDE_DESKTOP_CLI_SYSTEM_PATH], deps);
+}
+/** Probe whether the Claude Code CLI is installed and report its version. */
+export function probeClaude(deps = {}) {
+    const command = resolveClaudeCommand(deps);
+    if (!command)
+        return { available: false };
+    return {
+        available: true,
+        path: command,
+        version: readCommandVersion(command, [], deps) ?? undefined,
+    };
+}
+/**
+ * Claude Code adapter — spawns `claude -p "<text>" --output-format stream-json`
+ * (with `--resume <sid>` when available) and parses the ndjson stream.
+ *
+ * stream-json shape (abridged):
+ *   {type:"system", subtype:"init", session_id:"...", ...}
+ *   {type:"assistant", message:{content:[{type:"text", text:"..."} | {type:"tool_use", ...}]}}
+ *   {type:"user", message:{content:[{type:"tool_result", ...}]}}
+ *   {type:"result", subtype:"success", session_id:"...", total_cost_usd: 0.01, result:"final text"}
+ */
+export class ClaudeCodeAdapter extends NdjsonStreamAdapter {
+    id = "claude-code";
+    explicitBinary;
+    resolvedBinary = null;
+    constructor(opts) {
+        super();
+        this.explicitBinary = opts?.binary ?? process.env.BOTCORD_CLAUDE_BIN;
+    }
+    probe() {
+        return probeClaude();
+    }
+    async run(opts) {
+        if (opts.sessionId && !isValidClaudeSessionId(opts.sessionId)) {
+            return { text: "", newSessionId: "", error: invalidClaudeSessionIdError() };
+        }
+        return super.run(opts);
+    }
+    resolveBinary() {
+        if (this.explicitBinary)
+            return this.explicitBinary;
+        if (this.resolvedBinary)
+            return this.resolvedBinary;
+        // Falls back to the macOS Claude Code URL Handler bundle when not on PATH.
+        this.resolvedBinary = resolveClaudeCommand() ?? "claude";
+        return this.resolvedBinary;
+    }
+    buildArgs(opts) {
+        const args = ["-p", opts.text, "--output-format", "stream-json", "--verbose"];
+        if (opts.sessionId) {
+            if (!isValidClaudeSessionId(opts.sessionId))
+                throw new Error(invalidClaudeSessionIdError());
+            args.push("--resume", opts.sessionId);
+        }
+        // Permission-mode policy:
+        //  - owner: acceptEdits (owner trusts their own agent).
+        //  - non-owner (trusted/public): default (let Claude Code prompt / reject edits per its own rules).
+        // `extraArgs` still wins — operators who know what they're doing can override either.
+        if (!opts.extraArgs?.some((a) => a.startsWith("--permission-mode"))) {
+            if (opts.trustLevel === "owner") {
+                args.push("--permission-mode", "acceptEdits");
+            }
+            else {
+                args.push("--permission-mode", "default");
+            }
+        }
+        // Claude Code's `--append-system-prompt` is applied per invocation and NOT
+        // persisted in the resumed session transcript — ideal for memory / digest
+        // content that should re-evaluate every turn.
+        if (opts.systemContext && !opts.extraArgs?.includes("--append-system-prompt")) {
+            args.push("--append-system-prompt", opts.systemContext);
+        }
+        if (opts.extraArgs?.length)
+            args.push(...opts.extraArgs);
+        return args;
+    }
+    handleEvent(raw, ctx) {
+        const obj = raw;
+        ctx.emitBlock(normalizeBlock(obj, ctx.seq));
+        if (obj.type === "system" && obj.session_id) {
+            ctx.state.newSessionId = String(obj.session_id);
+            return;
+        }
+        if (obj.type === "assistant" && Array.isArray(obj.message?.content)) {
+            for (const c of obj.message.content) {
+                if (c?.type === "text" && typeof c.text === "string") {
+                    ctx.appendAssistantText(c.text);
+                }
+            }
+            return;
+        }
+        if (obj.type === "result") {
+            if (typeof obj.total_cost_usd === "number")
+                ctx.state.costUsd = obj.total_cost_usd;
+            if (obj.subtype === "success") {
+                if (typeof obj.session_id === "string")
+                    ctx.state.newSessionId = obj.session_id;
+                if (typeof obj.result === "string")
+                    ctx.state.finalText = obj.result;
+            }
+            else {
+                // Non-success result (e.g. resume targeted a missing UUID). Claude Code
+                // still emits a fresh `session_id` for the just-spawned empty session —
+                // persisting it would trap us into resuming a useless UUID forever.
+                // Wipe newSessionId so the dispatcher deletes the stale entry instead.
+                // The CLI also exits non-zero, so the base adapter synthesizes errorText
+                // from stderr if `obj.result` is missing.
+                ctx.state.newSessionId = "";
+                if (typeof obj.result === "string")
+                    ctx.state.errorText = obj.result;
+            }
+        }
+    }
+}
+function normalizeBlock(obj, seq) {
+    let kind = "other";
+    if (obj?.type === "assistant") {
+        const contents = Array.isArray(obj.message?.content) ? obj.message.content : [];
+        if (contents.some((c) => c?.type === "tool_use"))
+            kind = "tool_use";
+        else if (contents.some((c) => c?.type === "text"))
+            kind = "assistant_text";
+    }
+    else if (obj?.type === "user") {
+        const contents = Array.isArray(obj.message?.content) ? obj.message.content : [];
+        if (contents.some((c) => c?.type === "tool_result"))
+            kind = "tool_result";
+    }
+    else if (obj?.type === "system") {
+        kind = "system";
+    }
+    return { raw: obj, kind, seq };
+}

package/dist/gateway/runtimes/codex.d.ts

@@ -0,0 +1,83 @@
+import { NdjsonStreamAdapter, type NdjsonEventCtx } from "./ndjson-stream.js";
+import { type ProbeDeps } from "./probe.js";
+import type { RuntimeProbeResult, RuntimeRunOptions } from "../types.js";
+/** Resolve the Codex CLI executable via PATH or macOS desktop bundle. */
+export declare function resolveCodexCommand(deps?: ProbeDeps): string | null;
+/** Probe whether the Codex CLI is installed and report its version. */
+export declare function probeCodex(deps?: ProbeDeps): RuntimeProbeResult;
+/**
+ * Codex adapter — spawns `codex exec [resume <sid>] --json ...` and parses the
+ * JSONL event stream.
+ *
+ * Event shape (abridged):
+ *   {"type":"thread.started","thread_id":"<uuid>"}
+ *   {"type":"turn.started"}
+ *   {"type":"item.started","item":{"type":"command_execution", ...}}
+ *   {"type":"item.completed","item":{"type":"agent_message","text":"..."}}
+ *   {"type":"turn.completed","usage":{...}}
+ *
+ * `codex exec` does not report USD cost — only token usage — so `costUsd` is
+ * not populated from this adapter.
+ *
+ * ## systemContext injection: per-agent CODEX_HOME + AGENTS.md
+ *
+ * Codex has no `--append-system-prompt` equivalent. Its documented way to
+ * inject instructions that do NOT land in the stored transcript is the
+ * `AGENTS.md` loaded from `<CODEX_HOME>/AGENTS.md` (alongside the user-global
+ * `~/.codex/AGENTS.md` and the cwd's `<cwd>/AGENTS.md`).
+ *
+ * This adapter therefore:
+ *   1. Points `CODEX_HOME` at a per-agent directory:
+ *      `~/.botcord/agents/<accountId>/codex-home/`
+ *   2. Writes `opts.systemContext` to `<CODEX_HOME>/AGENTS.md` atomically
+ *      (tmp + rename) before spawning the child.
+ *   3. Leaves the positional prompt as just `opts.text` — no more prepending
+ *      systemContext to the transcript.
+ *
+ * With the transcript no longer accumulating systemContext, resume is safe to
+ * turn back on: `thread.started.thread_id` is persisted as `newSessionId`, and
+ * when the next turn arrives with a sessionId the adapter runs `exec resume
+ * <sid>` instead of `exec`. The per-agent CODEX_HOME also isolates codex's
+ * `sessions/` directory from `~/.codex/sessions/`, so daemon-owned sessions
+ * don't pollute the user's interactive session picker.
+ *
+ * ## `exec resume` flag quirk
+ *
+ * `codex exec resume` accepts a smaller flag set than `codex exec` — notably
+ * `-s / --sandbox` is NOT accepted on `resume`. We therefore express sandbox
+ * policy as `-c sandbox_mode="..."` (a `-c` override works on both
+ * subcommands) and the same tail of flags applies to both paths.
+ */
+export declare class CodexAdapter extends NdjsonStreamAdapter {
+    readonly id: "codex";
+    private readonly explicitBinary;
+    private resolvedBinary;
+    constructor(opts?: {
+        binary?: string;
+    });
+    probe(): RuntimeProbeResult;
+    /**
+     * Validate the sessionId shape and materialize the per-agent CODEX_HOME +
+     * AGENTS.md before handing off to the base adapter's spawn loop. Both steps
+     * must run BEFORE `super.run()` because `spawnEnv()` and `buildArgs()` are
+     * called synchronously from inside it and read the filesystem state we set
+     * up here.
+     */
+    run(opts: RuntimeRunOptions): Promise<import("../types.js").RuntimeRunResult>;
+    protected resolveBinary(): string;
+    /**
+     * `extraArgs` are passed as Codex CLI flags (inserted before `--`), not
+     * prompt text. Use the route config's `extraArgs` for flags like
+     * `-c model="..."`, not for extra prompt content.
+     *
+     * Layout for fresh session:  `exec   <tail> -- <prompt>`
+     * Layout for resume:         `exec resume <sid> <tail> -- <prompt>`
+     *
+     * Both paths share the same `<tail>`: sandbox/approval policy (as `-c`
+     * overrides so `resume` accepts them), `--skip-git-repo-check`, `--json`,
+     * and operator `extraArgs`.
+     */
+    protected buildArgs(opts: RuntimeRunOptions): string[];
+    protected spawnEnv(opts: RuntimeRunOptions): NodeJS.ProcessEnv;
+    protected handleEvent(raw: unknown, ctx: NdjsonEventCtx): void;
+}

package/dist/gateway/runtimes/codex.js

@@ -0,0 +1,272 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { agentCodexHomeDir, ensureAgentCodexHome } from "../../agent-workspace.js";
+import { NdjsonStreamAdapter } from "./ndjson-stream.js";
+import { firstExistingPath, readCommandVersion, resolveCommandOnPath, } from "./probe.js";
+const CODEX_DESKTOP_BUNDLE_PATH = "/Applications/Codex.app/Contents/Resources/codex";
+/** Codex UUIDv7 / v4 session ids are 36-char dashed hex; reject anything else to keep argv safe. */
+const CODEX_SESSION_ID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** Resolve the Codex CLI executable via PATH or macOS desktop bundle. */
+export function resolveCodexCommand(deps = {}) {
+    const onPath = resolveCommandOnPath("codex", deps);
+    if (onPath)
+        return onPath;
+    return firstExistingPath([CODEX_DESKTOP_BUNDLE_PATH], deps);
+}
+function resolveCodexGlobalNpmEntry() {
+    try {
+        const globalRoot = execFileSync("npm", ["root", "-g"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        }).trim();
+        if (!globalRoot)
+            return null;
+        const candidate = path.join(globalRoot, "@openai", "codex", "bin", "codex.js");
+        return existsSync(candidate) ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Probe whether the Codex CLI is installed and report its version. */
+export function probeCodex(deps = {}) {
+    const command = resolveCodexCommand(deps);
+    if (command) {
+        return {
+            available: true,
+            path: command,
+            version: readCommandVersion(command, [], deps) ?? undefined,
+        };
+    }
+    const npmEntry = resolveCodexGlobalNpmEntry();
+    if (npmEntry) {
+        return {
+            available: true,
+            path: npmEntry,
+            version: readCommandVersion(process.execPath, [npmEntry], deps) ?? undefined,
+        };
+    }
+    return { available: false };
+}
+/**
+ * Codex adapter — spawns `codex exec [resume <sid>] --json ...` and parses the
+ * JSONL event stream.
+ *
+ * Event shape (abridged):
+ *   {"type":"thread.started","thread_id":"<uuid>"}
+ *   {"type":"turn.started"}
+ *   {"type":"item.started","item":{"type":"command_execution", ...}}
+ *   {"type":"item.completed","item":{"type":"agent_message","text":"..."}}
+ *   {"type":"turn.completed","usage":{...}}
+ *
+ * `codex exec` does not report USD cost — only token usage — so `costUsd` is
+ * not populated from this adapter.
+ *
+ * ## systemContext injection: per-agent CODEX_HOME + AGENTS.md
+ *
+ * Codex has no `--append-system-prompt` equivalent. Its documented way to
+ * inject instructions that do NOT land in the stored transcript is the
+ * `AGENTS.md` loaded from `<CODEX_HOME>/AGENTS.md` (alongside the user-global
+ * `~/.codex/AGENTS.md` and the cwd's `<cwd>/AGENTS.md`).
+ *
+ * This adapter therefore:
+ *   1. Points `CODEX_HOME` at a per-agent directory:
+ *      `~/.botcord/agents/<accountId>/codex-home/`
+ *   2. Writes `opts.systemContext` to `<CODEX_HOME>/AGENTS.md` atomically
+ *      (tmp + rename) before spawning the child.
+ *   3. Leaves the positional prompt as just `opts.text` — no more prepending
+ *      systemContext to the transcript.
+ *
+ * With the transcript no longer accumulating systemContext, resume is safe to
+ * turn back on: `thread.started.thread_id` is persisted as `newSessionId`, and
+ * when the next turn arrives with a sessionId the adapter runs `exec resume
+ * <sid>` instead of `exec`. The per-agent CODEX_HOME also isolates codex's
+ * `sessions/` directory from `~/.codex/sessions/`, so daemon-owned sessions
+ * don't pollute the user's interactive session picker.
+ *
+ * ## `exec resume` flag quirk
+ *
+ * `codex exec resume` accepts a smaller flag set than `codex exec` — notably
+ * `-s / --sandbox` is NOT accepted on `resume`. We therefore express sandbox
+ * policy as `-c sandbox_mode="..."` (a `-c` override works on both
+ * subcommands) and the same tail of flags applies to both paths.
+ */
+export class CodexAdapter extends NdjsonStreamAdapter {
+    id = "codex";
+    explicitBinary;
+    resolvedBinary = null;
+    constructor(opts) {
+        super();
+        this.explicitBinary = opts?.binary ?? process.env.BOTCORD_CODEX_BIN;
+    }
+    probe() {
+        return probeCodex();
+    }
+    /**
+     * Validate the sessionId shape and materialize the per-agent CODEX_HOME +
+     * AGENTS.md before handing off to the base adapter's spawn loop. Both steps
+     * must run BEFORE `super.run()` because `spawnEnv()` and `buildArgs()` are
+     * called synchronously from inside it and read the filesystem state we set
+     * up here.
+     */
+    async run(opts) {
+        if (opts.sessionId && !CODEX_SESSION_ID_RE.test(opts.sessionId)) {
+            throw new Error(`codex: invalid sessionId "${opts.sessionId}" (expected UUID)`);
+        }
+        if (opts.accountId) {
+            try {
+                ensureAgentCodexHome(opts.accountId);
+                writeCodexAgentsMd(opts.accountId, opts.systemContext);
+            }
+            catch (err) {
+                // Writing AGENTS.md should never abort the turn — log and fall
+                // through. The child will spawn without the dynamic systemContext,
+                // which degrades to "codex replies without this turn's memory
+                // snapshot" rather than silence.
+                // eslint-disable-next-line no-console
+                console.warn("codex: failed to prepare CODEX_HOME/AGENTS.md", err);
+            }
+        }
+        return super.run(opts);
+    }
+    resolveBinary() {
+        if (this.explicitBinary)
+            return this.explicitBinary;
+        if (this.resolvedBinary)
+            return this.resolvedBinary;
+        // Use the executable resolver only — probeCodex's npm-global fallback
+        // yields a `.js` path that can't be spawned directly.
+        this.resolvedBinary = resolveCodexCommand() ?? "codex";
+        return this.resolvedBinary;
+    }
+    /**
+     * `extraArgs` are passed as Codex CLI flags (inserted before `--`), not
+     * prompt text. Use the route config's `extraArgs` for flags like
+     * `-c model="..."`, not for extra prompt content.
+     *
+     * Layout for fresh session:  `exec   <tail> -- <prompt>`
+     * Layout for resume:         `exec resume <sid> <tail> -- <prompt>`
+     *
+     * Both paths share the same `<tail>`: sandbox/approval policy (as `-c`
+     * overrides so `resume` accepts them), `--skip-git-repo-check`, `--json`,
+     * and operator `extraArgs`.
+     */
+    buildArgs(opts) {
+        const tail = [];
+        // Sandbox / approval policy. Expressed as `-c` overrides because
+        // `codex exec resume` rejects `-s` / `--full-auto`. `-c` works on both
+        // the fresh `exec` and `exec resume` paths.
+        //  - owner turn: bypass approvals + sandbox (owner trusts their agent)
+        //  - non-owner turn: `workspace-write` sandbox + on-request approvals
+        const hasSandboxOverride = opts.extraArgs?.some((a) => a === "-s" ||
+            a.startsWith("--sandbox") ||
+            a === "--full-auto" ||
+            a === "--dangerously-bypass-approvals-and-sandbox" ||
+            a.startsWith("-c sandbox_mode=") ||
+            a.startsWith("-csandbox_mode=")) ?? false;
+        if (!hasSandboxOverride) {
+            if (opts.trustLevel === "owner") {
+                tail.push("-c", 'sandbox_mode="danger-full-access"', "-c", 'approval_policy="never"');
+            }
+            else {
+                tail.push("-c", 'sandbox_mode="workspace-write"', "-c", 'approval_policy="on-request"');
+            }
+        }
+        tail.push("--skip-git-repo-check", "--json");
+        if (opts.extraArgs?.length)
+            tail.push(...opts.extraArgs);
+        // `--` separates flags from positionals so a prompt starting with `-`
+        // can never be parsed as an option. `systemContext` is NOT prepended to
+        // the prompt any more — it lives in `<CODEX_HOME>/AGENTS.md` written by
+        // `run()` — so the transcript stays clean across resumes.
+        const prompt = opts.text;
+        if (opts.sessionId) {
+            return ["exec", "resume", opts.sessionId, ...tail, "--", prompt];
+        }
+        return ["exec", ...tail, "--", prompt];
+    }
+    spawnEnv(opts) {
+        const env = {
+            ...process.env,
+            // Keep JSONL free of ANSI codes regardless of user terminal settings.
+            FORCE_COLOR: "0",
+            NO_COLOR: "1",
+        };
+        if (opts.accountId) {
+            env.CODEX_HOME = agentCodexHomeDir(opts.accountId);
+        }
+        return env;
+    }
+    handleEvent(raw, ctx) {
+        const obj = raw;
+        ctx.emitBlock(normalizeBlock(obj, ctx.seq));
+        // Persist the thread_id so the next turn on this session key resumes
+        // instead of spawning fresh. Safe now that systemContext lives in
+        // AGENTS.md rather than the transcript.
+        if (obj.type === "thread.started") {
+            if (typeof obj.thread_id === "string") {
+                ctx.state.newSessionId = obj.thread_id;
+            }
+            return;
+        }
+        if (obj.type === "item.completed" && obj.item?.type === "agent_message") {
+            if (typeof obj.item.text === "string") {
+                ctx.appendAssistantText(obj.item.text);
+                // The last agent_message is the final reply.
+                ctx.state.finalText = obj.item.text;
+            }
+            return;
+        }
+        if (obj.type === "turn.completed" && obj.turn?.status === "failed") {
+            const msg = obj.turn.error?.message;
+            if (typeof msg === "string" && msg)
+                ctx.state.errorText = msg;
+            return;
+        }
+        if (obj.type === "error") {
+            ctx.state.errorText =
+                typeof obj.error === "string"
+                    ? obj.error
+                    : obj.error?.message ?? "codex error";
+        }
+    }
+}
+/**
+ * Atomically overwrite `<CODEX_HOME>/AGENTS.md` with `systemContext`. codex
+ * reads this file at process start, so the write must complete before spawn.
+ * An empty or missing systemContext writes an empty file — deleting would
+ * race with a prior turn's file still being readable; empty is simpler and
+ * codex treats it as "no user-global AGENTS.md".
+ */
+function writeCodexAgentsMd(accountId, systemContext) {
+    const dir = agentCodexHomeDir(accountId);
+    // ensureAgentCodexHome already mkdir's dir; defensive mkdir here too for
+    // code paths that invoke this helper directly (tests, future callers).
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = path.join(dir, "AGENTS.md");
+    const tmp = path.join(dir, `.AGENTS.md.${process.pid}.tmp`);
+    writeFileSync(tmp, systemContext ?? "", { mode: 0o600 });
+    renameSync(tmp, target);
+}
+function normalizeBlock(obj, seq) {
+    let kind = "other";
+    const type = obj?.type;
+    const itemType = obj?.item?.type;
+    if (type === "thread.started" || type === "turn.started" || type === "turn.completed") {
+        kind = "system";
+    }
+    else if (type === "item.completed" && itemType === "agent_message") {
+        kind = "assistant_text";
+    }
+    else if (type === "item.started" || type === "item.completed") {
+        if (itemType === "command_execution" ||
+            itemType === "file_change" ||
+            itemType === "mcp_tool_call" ||
+            itemType === "web_search") {
+            kind = "tool_use";
+        }
+    }
+    return { raw: obj, kind, seq };
+}

package/dist/gateway/runtimes/gemini.d.ts

@@ -0,0 +1,15 @@
+import { type ProbeDeps } from "./probe.js";
+import type { RuntimeAdapter, RuntimeProbeResult, RuntimeRunOptions, RuntimeRunResult } from "../types.js";
+/** Resolve the Gemini CLI executable on PATH. */
+export declare function resolveGeminiCommand(deps?: ProbeDeps): string | null;
+/** Probe whether the Gemini CLI is installed and report its version. */
+export declare function probeGemini(deps?: ProbeDeps): RuntimeProbeResult;
+/**
+ * Gemini adapter stub — probe() is wired up so `botcord-daemon doctor` can report it.
+ * run() is not implemented yet; routing a turn here will surface the error upstream.
+ */
+export declare class GeminiAdapter implements RuntimeAdapter {
+    readonly id: "gemini";
+    probe(): RuntimeProbeResult;
+    run(_opts: RuntimeRunOptions): Promise<RuntimeRunResult>;
+}