@jini-ai/daemon 0.6.11 → 0.6.15-rc.1

package/dist/agent-executor/mcp-bridge.js

@@ -3,9 +3,9 @@ import { randomBytes } from 'node:crypto';
 import { supportsMessageRelay } from './message-relay.js';
 import { ensureAntigravityMcpPermission } from './antigravity-permissions.js';
 import { homedir, tmpdir, } from 'node:os';
-import { join, resolve, } from 'node:path';
+import { join, } from 'node:path';
 import { isRecord, errorMessage, } from './values.js';
-const JINI_MCP_SERVER_KEY = 'jini';
+export const JINI_MCP_SERVER_KEY = 'jini';
 /** The run-error code a run gets when its CLI reports the injected `jini` bridge as anything but connected. */
 export const MCP_BRIDGE_UNAVAILABLE = 'MCP_BRIDGE_UNAVAILABLE';
 /**
@@ -238,225 +238,6 @@ export function mergeEnvContentInstructions({ existingRaw, instructionsFilePath
         : [];
     return JSON.stringify({ ...doc, instructions: [...existingInstructions, instructionsFilePath] });
 }
-/**
- * TOML basic-string escaping for the narrow value shapes {@link buildCodexMcpServerToml} emits (a
- * command name, an argv token, an env var value — never multi-line or control-character-heavy
- * text). Escapes exactly what TOML's basic-string grammar requires: backslash first (so it is not
- * re-escaped by a later replacement), then the quote delimiter, then the three whitespace control
- * characters a real command/argv/env value could plausibly contain.
- *
- * A hand-rolled minimal escaper rather than a TOML dependency — this mechanism never needs to
- * *parse* TOML (the real install's existing `config.toml` is appended after, never rewritten — see
- * {@link buildCodexHomeConfigToml}), so pulling in a full TOML library for one serialization shape
- * would be substantially more surface than the problem needs. Checked against the repo's existing
- * dependency graph first — no package here already depends on a TOML library.
- * @param value - The raw string to embed inside TOML `"..."` delimiters.
- * @returns The escaped text, WITHOUT the surrounding quotes — {@link tomlString} adds those.
- * @complexity O(n) in the string's length.
- */
-function escapeTomlBasicString(value) {
-    return value
-        .replace(/\\/g, '\\\\')
-        .replace(/"/g, '\\"')
-        .replace(/\n/g, '\\n')
-        .replace(/\r/g, '\\r')
-        .replace(/\t/g, '\\t');
-}
-/** Wraps {@link escapeTomlBasicString}'s output in the TOML basic-string delimiters. */
-function tomlString(value) {
-    return `"${escapeTomlBasicString(value)}"`;
-}
-/** A TOML key: bare when TOML allows it, quoted otherwise — host-supplied bridge env names are not guaranteed bare-safe. */
-function tomlKey(key) {
-    return /^[A-Za-z0-9_-]+$/.test(key) ? key : tomlString(key);
-}
-/**
- * Codex's per-tool deadline for the Jini bridge, in seconds: `@jini-ai/mcp`'s
- * `DEFAULT_DELEGATED_TOOL_TIMEOUT_MS` (6 min, mirrored because this package does not depend on
- * that one) plus 40 s. Codex's own default (60 s) is shorter than a delegated call parked on a
- * human dialog, and when Codex abandons a call the dialog stayed answerable, so a late click ran
- * an action the model had been told failed. Outlasting the bridge's deadline means the bridge
- * times out first, drops its daemon request, and the daemon expires the dialog. Codex does not
- * pass the parent env through to MCP servers, so the bridge under Codex always runs at its default.
- */
-const CODEX_TOOL_TIMEOUT_SEC = 6 * 60 + 40;
-/**
- * Mechanism 5 of 5 — `'codex-toml'`'s serialization step. Builds the `[mcp_servers.jini]` TOML
- * table (plus, when the entry carries any env vars, a separate `[mcp_servers.jini.env]` table)
- * Codex's own config schema expects.
- *
- * Confirmed against a real installed Codex CLI (0.151.0), not assumed from docs: round-tripping
- * `codex mcp add <name> --env K=V -- <cmd> <args>` against a scratch `CODEX_HOME` and reading back
- * `config.toml` produced exactly this shape (`command`/`args` as TOML strings/array in the main
- * table, env vars in a nested `.env` table) — see `archived provenance ledger` for the transcript.
- * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
- * @returns A TOML fragment with no leading/trailing blank-line padding — {@link buildCodexHomeConfigToml} owns spacing when combining it with existing content.
- * @complexity O(n) in the number of argv/env entries.
- * @overallScore 100/100
- */
-export function buildCodexMcpServerToml({ entry }) {
-    const argsLiteral = entry.args.map(tomlString).join(', ');
-    const serverTable = `[mcp_servers.${JINI_MCP_SERVER_KEY}]\ncommand = ${tomlString(entry.command)}\nargs = [${argsLiteral}]\n` +
-        `tool_timeout_sec = ${CODEX_TOOL_TIMEOUT_SEC}\n`;
-    const envLines = Object.entries(entry.env)
-        .filter((pair) => typeof pair[1] === 'string')
-        .map(([key, value]) => `${tomlKey(key)} = ${tomlString(value)}`);
-    if (envLines.length === 0)
-        return serverTable;
-    return `${serverTable}\n[mcp_servers.${JINI_MCP_SERVER_KEY}.env]\n${envLines.join('\n')}\n`;
-}
-/**
- * Splits a TOML table header's dotted key into its individual segments, honoring quoted parts
- * (`"basic"` or `'literal'`) that may themselves contain a literal `.` — a bare `.` only
- * separates segments outside of quotes. Each segment is trimmed and, if quoted, unwrapped.
- *
- * Not a full TOML parser: it does not resolve escape sequences (`\"`, `\u...`) inside basic
- * strings. That is deliberately out of scope — see {@link stripExistingJiniMcpServerTable}'s doc
- * for why it is safe to skip for this specific comparison.
- * @param rawKey - The raw text between a table header's `[` and `]`.
- * @returns The dotted key's segments, dequoted and trimmed.
- * @complexity O(n) in the length of `rawKey`.
- */
-function splitTomlDottedKey(rawKey) {
-    const scan = { segments: [], current: '', quote: null };
-    for (const ch of rawKey) {
-        if (scan.quote === null)
-            scanBareTomlKeyChar(scan, ch);
-        else if (ch === scan.quote)
-            scan.quote = null;
-        else
-            scan.current += ch;
-    }
-    scan.segments.push(scan.current.trim());
-    return scan.segments;
-}
-/** One key character outside quotes: opens a quote, ends the open segment at a `.`, or extends it. */
-function scanBareTomlKeyChar(scan, ch) {
-    if (ch === '"' || ch === "'")
-        scan.quote = ch;
-    else if (ch === '.') {
-        scan.segments.push(scan.current.trim());
-        scan.current = '';
-    }
-    else
-        scan.current += ch;
-}
-// An inline or dotted root `mcp_servers` declaration, which the table scanner below cannot rewrite.
-const INLINE_MCP_SERVERS = /^\s*(?:mcp_servers|"mcp_servers"|'mcp_servers')\s*(?:\.|=)/;
-// `[<key>]` optionally followed only by a `# comment`; `[[...]]` never matches (see below).
-const TOML_TABLE_HEADER = /^\s*\[([^[\]]+)\]\s*(#.*)?$/;
-/**
- * Whether {@link stripExistingJiniMcpServerTable} drops the table named `key`: always the jini
- * table and its subtables; with `allServers` every MCP table; with `mcpOnly` every non-MCP table.
- */
-function dropsTomlTable(key, optional) {
-    const jiniTableKey = `mcp_servers.${JINI_MCP_SERVER_KEY}`;
-    if (key === jiniTableKey || key.startsWith(`${jiniTableKey}.`))
-        return true;
-    const isMcp = key === 'mcp_servers' || key.startsWith('mcp_servers.');
-    return (optional.allServers === true && isMcp) || (optional.mcpOnly === true && !isMcp);
-}
-/**
- * Removes any pre-existing `[mcp_servers.{@link JINI_MCP_SERVER_KEY}]` table — and its
- * `[mcp_servers.{@link JINI_MCP_SERVER_KEY}.*]` subtables (e.g. `.env`) — from a real Codex
- * `config.toml`'s raw text, so {@link buildCodexHomeConfigToml} can append this run's own table
- * without producing the duplicate TOML key Codex's parser rejects at startup.
- *
- * Line-oriented, not a real TOML parser (matching {@link buildCodexMcpServerToml}'s own
- * no-TOML-dependency constraint), but wide enough to survive a hand-edited config, which is the
- * scenario this whole function exists for. A table header line is recognized when, after
- * trimming, it is `[<key>]` optionally followed only by a `# comment` (TOML's own grammar allows
- * nothing else there) — so it tolerates leading indentation, whitespace inside the brackets, a
- * trailing line comment, and a dotted key written with quoted segments (`["mcp_servers"."jini"]`),
- * via {@link splitTomlDottedKey}. Once such a header's key matches the jini table or one of its
- * subtables, every following line is dropped until the next table header (of any name) or EOF.
- * Every other table, key, comment-only, and blank line is passed through untouched.
- *
- * Deliberately unhandled, and why it is safe to leave that way:
- * - **Escape sequences inside quoted key segments** (e.g. a segment containing `\"`) — neither
- *   `mcp_servers` nor {@link JINI_MCP_SERVER_KEY} ever needs escaping, and this driver's own
- *   writer ({@link buildCodexMcpServerToml}) never emits a quoted form at all, so no real
- *   `config.toml` this driver produced can exercise this gap; a hand-edit that goes out of its
- *   way to escape a character inside a key that is supposed to spell "jini" would fail to match
- *   and fall back to today's pre-fix behavior (append a duplicate) rather than silently doing
- *   something worse.
- * - **`[[array-of-tables]]` syntax** — Codex's schema has no array-of-tables shape for
- *   `mcp_servers`, and the header regex's `[^[\]]+` capture cannot match a line starting with a
- *   second `[`, so `[[mcp_servers.jini]]` is not recognized as a header before or after this fix
- *   — unchanged, not a new gap.
- * - **A single quoted segment that happens to spell the same characters with the dot included**
- *   (e.g. `["mcp_servers.jini"]`, which in real TOML names one key literally containing a `.`,
- *   not two nested tables) — this collapses to the same joined string as the real nested-table
- *   spelling and is therefore treated as a match. This is a false positive in the conservative
- *   direction the reported bug calls for: a missed detection duplicates a key and crashes Codex,
- *   so on this axis over-matching a spelling nobody would plausibly hand-write for an MCP server
- *   table is preferable to under-matching the real one.
- * @param existingRaw - The real Codex home's `config.toml` content, already known to be defined
- * (callers pass `''` for a missing file).
- * @returns `existingRaw` with any jini table/subtable removed.
- * @complexity O(n) in the number of lines.
- */
-function stripExistingJiniMcpServerTable(existingRaw, optional = {}) {
-    const kept = [];
-    let skipping = optional.mcpOnly === true;
-    for (const line of existingRaw.split('\n')) {
-        // The existing table scanner cannot safely rewrite inline/dotted root server values. Refuse
-        // that uncommon shape when isolating servers rather than accidentally preserving a grant.
-        if (optional.allServers && INLINE_MCP_SERVERS.test(line)) {
-            throw new Error('Cannot turn off personal MCP servers: the Codex config.toml declares mcp_servers inline (a dotted key or `mcp_servers = {...}`), which cannot be removed safely; move each server into its own [mcp_servers.<name>] table.');
-        }
-        const header = TOML_TABLE_HEADER.exec(line);
-        // The header's key capture group is not optional, so `header[1]` is always set on a match.
-        if (header)
-            skipping = dropsTomlTable(splitTomlDottedKey(header[1]).join('.'), optional);
-        if (!skipping)
-            kept.push(line);
-    }
-    return kept.join('\n');
-}
-/**
- * Builds the full `config.toml` a run's scratch `CODEX_HOME` gets: the real Codex home's own
- * config, with any pre-existing `[mcp_servers.jini]` table removed (see
- * {@link stripExistingJiniMcpServerTable}), then this run's own table appended.
- *
- * **Append-only by design, not a parse-and-merge, for everything but the jini table itself.**
- * `mergeMcpJsonContent`/`mergeEnvContentMcpConfig` above can safely parse-merge-reserialize because
- * their formats have a JS-native parser (`JSON.parse`); this driver has no general TOML parser in
- * its dependency graph (see `buildCodexMcpServerToml`'s doc), and every other setting a real Codex
- * install carries — model choice, sandbox policy, the trusted-project list, the operator's own
- * other MCP servers — must survive a spawn byte-for-byte. Only the one table this driver itself
- * owns (`jini` is this integration's own reserved server name — see {@link JINI_MCP_SERVER_KEY}) is
- * removed by default, via the narrow line-oriented scan above, never a full TOML parse. Explicit
- * per-run OFF choices additionally omit personal MCP tables or retain only those tables when
- * user settings are off. Inline root MCP declarations fail closed when isolation is requested.
- * @param existingRaw - The real Codex home's `config.toml` content, or `undefined` when it does not
- * exist (a fresh Codex install — degrades to "start from just this run's block", matching
- * {@link mergeMcpJsonContent}'s own "missing file" handling).
- * @param entry - The shared bridge entry.
- * @returns The full text to write to the scratch `CODEX_HOME`'s `config.toml`.
- * @complexity O(n) in the existing config's length.
- */
-export function buildCodexHomeConfigToml({ existingRaw, entry, inheritUserMcp = true, inheritUserSettings = true }, _optional = {}) {
-    const base = stripExistingJiniMcpServerTable(existingRaw ?? '', { allServers: !inheritUserMcp, mcpOnly: !inheritUserSettings });
-    const separator = base.length === 0 ? '' : base.endsWith('\n') ? '\n' : '\n\n';
-    return `${base}${separator}${buildCodexMcpServerToml({ entry: entry })}`;
-}
-/**
- * Where `'codex-toml'` reads the operator's REAL Codex config from, to seed a run's scratch copy —
- * never where it writes. Resolved against the daemon HOST process's own environment (`hostEnv`,
- * `process.env` at the real call site), not a run's sandboxed spawn env: `CODEX_HOME` is not in
- * `BASELINE_AGENT_ENV_KEYS`, so a spawned child never inherits it anyway, and the whole point here
- * is finding wherever the *operator's actual* Codex install lives, which is a host-machine fact.
- * @param hostEnv - The daemon process's own environment.
- * @returns `hostEnv.CODEX_HOME` when set to a non-blank value (matching Codex's own resolution
- * order), else the CLI's documented default, `~/.codex`.
- * @complexity O(1).
- * @overallScore 100/100
- */
-export function resolveSourceCodexHomeDir({ hostEnv }) {
-    const override = hostEnv.CODEX_HOME;
-    return override !== undefined && override.trim().length > 0 ? override : join(homedir(), '.codex');
-}
 /**
  * **The single dispatch point from an `externalMcpInjection` strategy to its delivery mechanism.**
  * Pure and synchronous — the one effectful input (the per-run bearer credential) arrives already
@@ -500,10 +281,10 @@ export function buildMcpBridgeDelivery(input) {
             return { kind: 'env-passthrough', serverEntry };
     }
 }
-function defaultReadMcpJsonFile({ path }) {
+export function defaultReadMcpJsonFile({ path }) {
     return fsPromises.readFile(path, 'utf8');
 }
-function defaultWriteMcpJsonFile({ path, content }) {
+export function defaultWriteMcpJsonFile({ path, content }) {
     return fsPromises.writeFile(path, content, 'utf8');
 }
 export function defaultRemoveMcpJsonFile({ path }) {
@@ -575,105 +356,6 @@ async function writeMcpJsonForRun(cwd, delivery, options, inheritUserConfig = tr
     }
     await writeFileFn({ path: delivery.mcpJsonPath, content: mergeMcpJsonContent({ existingRaw: existingRaw, serverEntry: delivery.serverEntry }) });
 }
-function defaultMkdtempCodexHome({ prefix }) {
-    return fsPromises.mkdtemp(join(tmpdir(), prefix));
-}
-function defaultRemoveCodexHomeDir({ path }) {
-    return fsPromises.rm(path, { recursive: true, force: true });
-}
-/** Config credentials stay run-scoped, but rollouts must survive both completion and cancellation.
- * Native links keep Codex as the sole writer of sessions and refreshed authentication.
- * Parity also links skills/rules/plugins and other home entries; config.toml alone stays staged
- * so run-scoped bearer tokens never reach the real config. Cleanup removes links, not targets.
- * O(h) I/O for h top-level home entries; locked runs link only sessions and authentication. */
-async function defaultLinkCodexSessionStore({ runHome, sourceHome }, optional = {}) {
-    for (const name of ['sessions', 'archived_sessions']) {
-        const target = resolve(sourceHome, name);
-        await fsPromises.mkdir(target, { recursive: true, mode: 0o700 });
-        await fsPromises.symlink(target, join(runHome, name), 'junction');
-    }
-    await fsPromises.symlink(join(sourceHome, 'auth.json'), join(runHome, 'auth.json'), 'file');
-    if (optional.inheritUserConfig !== false) {
-        for (const entry of await fsPromises.readdir(sourceHome, { withFileTypes: true })) {
-            if (['config.toml', 'auth.json', 'sessions', 'archived_sessions'].includes(entry.name))
-                continue;
-            await fsPromises.symlink(join(sourceHome, entry.name), join(runHome, entry.name), entry.isDirectory() ? 'junction' : 'file');
-        }
-    }
-}
-function resolveCodexHomeSeams(options) {
-    return {
-        mkdtemp: options.mkdtemp ?? defaultMkdtempCodexHome,
-        readFile: options.readFile ?? defaultReadMcpJsonFile,
-        writeFile: options.writeFile ?? defaultWriteMcpJsonFile,
-        removeDir: options.removeDir ?? defaultRemoveCodexHomeDir,
-        linkSessionStore: options.linkSessionStore ?? defaultLinkCodexSessionStore,
-    };
-}
-/**
- * Mechanism 5 of 5 — `'codex-toml'`'s one effect. Stages a fresh, randomly-named `CODEX_HOME`
- * directory (see {@link McpJsonInjectionOptions.mkdtemp}'s doc for why non-deterministic naming is
- * load-bearing here, not cosmetic) carrying:
- *   - `config.toml`: the real Codex home's own config (read best-effort — see
- *     {@link buildCodexHomeConfigToml}'s "missing file" handling) with this run's
- *     `[mcp_servers.jini]` table appended.
- *   - `auth.json`: a link to the real Codex home's stored login, so the spawned CLI is
- *     still authenticated. Best-effort is safe here, not merely convenient: a real headless spawn
- *     against a `CODEX_HOME` with no `auth.json` at all was confirmed (against installed Codex CLI
- *     0.151.0) to fail fast with a structured `401 Unauthorized` stream event, never an interactive
- *     login prompt or a hang — see `defs/codex.ts`'s module doc for the full transcript summary.
- *
- * Never changes the real config. Authentication is linked so a CLI token refresh survives cleanup;
- * copying rotating credentials lost refreshes and could log the operator out. Deleting scratch
- * state must not erase linked native state. The run-bound MCP credential stays in scratch config.
- *
- * A failure after the directory is created (a rejecting `writeFile`, most plausibly) does not leak
- * it: the directory may already hold a partial `config.toml` or a copied credential, so the
- * `catch` below best-effort-removes it before rethrowing, exactly the "partial-failure state leak"
- * class of bug this package's own adversarial-test-design guidance calls out.
- * @param runId - Embedded in the temp-dir prefix for traceability, sanitized the same way
- * `@jini-ai/agent-runtime`'s `prepareAgentLogFile`'s `label` is.
- * @param entry - The shared bridge entry.
- * @param sourceCodexHomeDir - Where to read the real install's `config.toml`/`auth.json` from — see {@link resolveSourceCodexHomeDir}.
- * @param seams - Injectable mkdtemp/readFile/writeFile/removeDir/linkSessionStore, real filesystem by default.
- * @throws Whatever staging rejects with — the caller ({@link prepareCodexHomeIfNeeded}) turns that into a pre-spawn `AGENT_SPAWN_FAILED` failure, matching {@link writeMcpJsonForRun}'s own contract.
- * @complexity O(h) filesystem operations for h top-level user-home entries; one staged config write.
- * @overallScore 100/100
- */
-async function prepareCodexHomeForRun(runId, entry, sourceCodexHomeDir, seams, inheritUserConfig = true, inheritUserMcp = true) {
-    // Stricter than `@jini-ai/agent-runtime`'s `prepareAgentLogFile`/`preparePromptFileForAgent`
-    // labels (which keep dots): this prefix stages a directory that ends up holding a copied Codex
-    // login credential, so it gets `mcpJsonPathForRun`'s tighter discipline instead — dots stripped
-    // too, not just path separators, so a run id like `../../etc/evil` cannot leave even a cosmetic
-    // `..` substring in the mkdtemp prefix.
-    const safeRunId = runId.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 80) || 'run';
-    const dir = await seams.mkdtemp({ prefix: `jini-codex-home-${safeRunId}-` });
-    try {
-        let existingConfigRaw;
-        try {
-            existingConfigRaw = inheritUserConfig || inheritUserMcp ? await seams.readFile({ path: join(sourceCodexHomeDir, 'config.toml') }) : undefined;
-        }
-        catch {
-            // No config yet (fresh Codex install) or unreadable — start from just this run's block,
-            // matching writeMcpJsonForRun's identical "missing file" handling.
-            existingConfigRaw = undefined;
-        }
-        await seams.writeFile({ path: join(dir, 'config.toml'), content: buildCodexHomeConfigToml({ existingRaw: existingConfigRaw, entry: entry, inheritUserMcp, inheritUserSettings: inheritUserConfig }) });
-        await seams.linkSessionStore({ runHome: dir, sourceHome: sourceCodexHomeDir }, { inheritUserConfig });
-    }
-    catch (err) {
-        await seams.removeDir({ path: dir }).catch(() => {
-            // Best-effort only — the original error below is what the caller must see either way.
-        });
-        throw err;
-    }
-    return {
-        path: dir,
-        cleanup: async () => {
-            await seams.removeDir({ path: dir });
-        },
-    };
-}
 function defaultMkdtempClaudeConfigDir({ prefix }) {
     return fsPromises.mkdtemp(join(tmpdir(), prefix));
 }
@@ -827,39 +509,6 @@ export async function writeMcpJsonIfNeeded({ input, deps }) {
         return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not write .mcp.json for agent "${input.def.id}": ${errorMessage(err)}` });
     }
 }
-/** True when a Codex run turns off the operator's personal MCP servers or settings, which only a staged home can do. */
-function codexTurnsOffPersonalConfig(input) {
-    const capabilities = input.nativeCapabilities;
-    return input.def.id === 'codex' && (capabilities?.userMcp === false || capabilities?.userSettings === false);
-}
-/**
- * Phase 10b: mechanism 5 of 5's one effect — stages this run's scratch `CODEX_HOME` directory,
- * returning the prepared handle `cleanupStagedFiles` should later release (`null` for every other
- * mechanism, or for an unconfigured host — matching {@link writeMcpJsonIfNeeded}'s identical gate).
- * @param input.def - Only used for its `id`, in the failure message.
- * @param input.mcpBridge - This run's resolved bridge delivery — a no-op unless its `kind` is `'codex-toml'`.
- * @param deps.hostEnv - The daemon's own environment, threaded through to {@link resolveSourceCodexHomeDir} rather than read from a module-level `process.env` so this phase stays testable with an injected env.
- * @complexity O(1) plus {@link prepareCodexHomeForRun}'s own cost.
- * @overallScore 100/100
- */
-export async function prepareCodexHomeIfNeeded({ input, deps }) {
-    if (input.mcpBridge?.kind !== 'codex-toml' || deps.mcpJsonInjection === undefined) {
-        if (codexTurnsOffPersonalConfig(input)) {
-            await deps.releaseStagedResources();
-            return deps.failBeforeSpawn({ runId: input.runId, code: 'NATIVE_TOOL_POLICY_UNSUPPORTED',
-                message: 'AgentExecutor: disabling personal Codex configuration requires run-scoped home staging.' });
-        }
-        return null;
-    }
-    const nativeAllowed = input.nativeToolAccess !== false;
-    try {
-        return await prepareCodexHomeForRun(input.runId, input.mcpBridge.serverEntry, resolveSourceCodexHomeDir({ hostEnv: deps.hostEnv }), resolveCodexHomeSeams(deps.mcpJsonInjection), nativeAllowed && input.nativeCapabilities?.userSettings !== false, nativeAllowed && input.nativeCapabilities?.userMcp !== false);
-    }
-    catch (err) {
-        await deps.releaseStagedResources();
-        return deps.failBeforeSpawn({ runId: input.runId, code: 'AGENT_SPAWN_FAILED', message: `AgentExecutor: could not stage a CODEX_HOME for agent "${input.def.id}": ${errorMessage(err)}` });
-    }
-}
 /**
  * Finding 1 of SEC-assistant-env-isolation-2026-09-07's one effect — stages this run's scratch
  * `CLAUDE_CONFIG_DIR` directory, returning the prepared handle `cleanupStagedFiles` should later

package/dist/ai-trace-lifecycle.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module ai-trace-lifecycle
+ *
+ * Wraps a {@link RunLifecycle} so every run it drives is also recorded as an AI trace. This is
+ * the single tap for every provider path: child stream parsers (Claude Code, Copilot, Qoder,
+ * Codex/OpenCode/Cursor/Kimi JSON streams), ACP sessions and pi-rpc all publish their normalized
+ * events through `lifecycle.emit({ event: 'agent' })`. Observing the committed stream also sees
+ * watchdog-driven terminal transitions, which call the base lifecycle's closed-over `finish()`.
+ * Hosts that pass no sink never call this, so tracing off costs nothing.
+ *
+ * What it cannot see: the user prompt (the kernel only holds an opaque `contextRef`) — hosts that
+ * want prompt capture call `noteRunInput` with the text they sent. Resumed runs keep their
+ * original trace closed; a resume is not re-traced in this prototype.
+ */
+import { type AiTraceRecorderOptions, type AiTraceSink } from '@jini-ai/agent-runtime';
+import type { RunLifecycle } from './run-lifecycle.js';
+export interface AiTracingOptions extends Pick<AiTraceRecorderOptions, 'capture' | 'exactSecrets' | 'maxCapturedChars' | 'priceUsage' | 'onSinkError' | 'now'> {
+    /** Maps an agent id (`claude`, `codex`, `gemini`, …) to the provider label a backend groups by. Default: the agent id. */
+    readonly providerOf?: (args: {
+        agentId: string;
+    }) => string | null;
+    /** Host session/chat id for a run's opaque `contextRef`. Default: the contextRef itself. */
+    readonly sessionOf?: (args: {
+        contextRef: string;
+    }) => string | null;
+}
+export interface TracedRunLifecycle extends RunLifecycle {
+    /** Records the prompt text for a run's trace (subject to the capture mode). No-op for unknown runs. */
+    noteRunInput(args: {
+        runId: string;
+        input: string;
+    }): void;
+    /** Host teardown: releases every open trace WITHOUT finishing it (no terminal outcome is invented)
+     * and cancels background terminal waits, so a retained lifecycle keeps no recorder or waiter. Never throws. */
+    dispose(): void;
+}
+/**
+ * Records the lifecycle's committed stream, including internal terminal transitions.
+ * @param required - Existing lifecycle owner and vendor-neutral sink.
+ * @param options - Capture policy, mappings, clock, pricing, and guarded error reporting.
+ * @returns The lifecycle with traced starts and prompt capture; run results and errors are preserved.
+ * @complexity O(1) per live event; initial replay uses the lifecycle's O(e) stream for e committed events.
+ */
+export declare function withAiTracing({ lifecycle, sink }: {
+    lifecycle: RunLifecycle;
+    sink: AiTraceSink;
+}, options?: AiTracingOptions): TracedRunLifecycle;
+//# sourceMappingURL=ai-trace-lifecycle.d.ts.map

package/dist/ai-trace-lifecycle.js

@@ -0,0 +1,116 @@
+/**
+ * @module ai-trace-lifecycle
+ *
+ * Wraps a {@link RunLifecycle} so every run it drives is also recorded as an AI trace. This is
+ * the single tap for every provider path: child stream parsers (Claude Code, Copilot, Qoder,
+ * Codex/OpenCode/Cursor/Kimi JSON streams), ACP sessions and pi-rpc all publish their normalized
+ * events through `lifecycle.emit({ event: 'agent' })`. Observing the committed stream also sees
+ * watchdog-driven terminal transitions, which call the base lifecycle's closed-over `finish()`.
+ * Hosts that pass no sink never call this, so tracing off costs nothing.
+ *
+ * What it cannot see: the user prompt (the kernel only holds an opaque `contextRef`) — hosts that
+ * want prompt capture call `noteRunInput` with the text they sent. Resumed runs keep their
+ * original trace closed; a resume is not re-traced in this prototype.
+ */
+import { createAiTraceRecorder } from '@jini-ai/agent-runtime';
+/**
+ * Records the lifecycle's committed stream, including internal terminal transitions.
+ * @param required - Existing lifecycle owner and vendor-neutral sink.
+ * @param options - Capture policy, mappings, clock, pricing, and guarded error reporting.
+ * @returns The lifecycle with traced starts and prompt capture; run results and errors are preserved.
+ * @complexity O(1) per live event; initial replay uses the lifecycle's O(e) stream for e committed events.
+ */
+export function withAiTracing({ lifecycle, sink }, options = {}) {
+    const recorders = new Map();
+    const { providerOf = ({ agentId }) => agentId, sessionOf = ({ contextRef }) => contextRef, ...recorderOptions } = options;
+    const teardown = new AbortController();
+    /** Only tracing effects are contained; the underlying lifecycle's errors still propagate. */
+    function safely({ action }) {
+        try {
+            action();
+        }
+        catch (error) {
+            try {
+                options.onSinkError?.(error);
+            }
+            catch { /* Reporting must not change committed run behavior. */ }
+        }
+    }
+    function close({ runId, outcome }) {
+        const entry = recorders.get(runId);
+        if (!entry)
+            return;
+        try {
+            safely({ action: () => entry.recorder.finish({ outcome }) });
+        }
+        finally {
+            recorders.delete(runId);
+            safely({ action: () => entry.unsubscribe?.() });
+        }
+    }
+    function observe({ event }) {
+        if (event.kind === 'end') {
+            const { status } = event.payload;
+            return close({ runId: event.runId, outcome: status === 'canceled' ? 'cancelled' : status ?? 'failed' });
+        }
+        const recorder = recorders.get(event.runId)?.recorder;
+        if (event.kind === 'agent')
+            recorder?.observe(event.payload);
+        if (event.kind === 'error')
+            recorder?.observe({ type: 'error', message: event.payload.message, code: event.payload.error?.code });
+    }
+    async function open({ runId, contextRef, agentId }) {
+        const recorder = createAiTraceRecorder({ sink, runId, agentId }, { ...recorderOptions, provider: providerOf({ agentId }), sessionId: sessionOf({ contextRef }) });
+        const entry = { recorder };
+        recorders.set(runId, entry);
+        recorder.start({});
+        const subscription = await lifecycle.stream({ runId, onEvent: (event) => safely({ action: () => observe({ event }) }) });
+        if (subscription.kind !== 'ok')
+            throw new Error(`AI trace subscription refused: ${subscription.kind}`);
+        // A terminal event can arrive during replay, before stream returns its unsubscribe handle.
+        if (!recorders.has(runId))
+            subscription.unsubscribe();
+        else
+            entry.unsubscribe = subscription.unsubscribe;
+    }
+    /** A failed subscription has already recorded run_started: finish the trace from the run's real
+     * terminal state instead of dropping it. Background only, so tracing never affects the run; when
+     * the outcome cannot be read (or `dispose` cancels the wait) it is not invented and the recorder
+     * is just released. */
+    function finishWhenTerminal({ runId }) {
+        // waitForTerminal resolves only terminal states, whose labels are exactly AiRunOutcome's.
+        void Promise.resolve().then(() => lifecycle.waitForTerminal({ runId }, { signal: teardown.signal }))
+            .then((status) => close({ runId, outcome: status.state }))
+            .catch(() => { recorders.delete(runId); });
+    }
+    return {
+        ...lifecycle,
+        async start(required, optional = {}) {
+            const result = await lifecycle.start(required, optional);
+            // dispose() may run while the underlying start is pending; opening afterwards would leave a
+            // recorder and subscription behind that no teardown will ever release.
+            if (result.started && !teardown.signal.aborted) {
+                // Not awaited: a slow or hung event-log replay must not delay the committed start. The
+                // recorder is registered synchronously; replay delivers anything emitted before subscribing.
+                void open({ runId: result.run.id, contextRef: required.contextRef, agentId: optional.agentId ?? 'unknown' }).catch((error) => {
+                    safely({ action: () => { throw error; } });
+                    finishWhenTerminal({ runId: result.run.id });
+                });
+            }
+            return result;
+        },
+        // start() has already opened the trace by the time a host knows the run id, so the prompt
+        // rides the first model turn (where backends show a generation's input) rather than run_started.
+        noteRunInput({ runId, input }) {
+            safely({ action: () => recorders.get(runId)?.recorder.noteInput({ input }) });
+        },
+        dispose() {
+            teardown.abort();
+            for (const [runId, entry] of recorders) {
+                recorders.delete(runId);
+                safely({ action: () => entry.unsubscribe?.() });
+            }
+        },
+    };
+}
+//# sourceMappingURL=ai-trace-lifecycle.js.map

package/dist/core/read-only-tools.js

@@ -9,7 +9,9 @@ export const defaultDaemonMessages = {
     readOnly: {
         unverifiableMessage: 'this host cannot verify read-only tools — POST /api/delegated-tool-calls was mounted without DelegatedToolsHttpDeps.toolRegistry, so a requireReadOnly call cannot be checked and is refused',
         toolRefusalMessage: ({ toolId }) => `tool "${toolId}" is not registered as read-only — this gateway executes only tools whose registration declares readOnly; call it through execute_delegated_tool instead`,
-        unknownToolMessage: ({ toolId, candidates }) => `no tool "${toolId}" is registered; use search_tools${candidates.length > 0 ? ` — did you mean ${candidates.join(', ')}?` : ''}`,
+        unknownToolMessage: ({ toolId, candidates }) => toolId === 'check_messages'
+            ? 'check_messages is an MCP-local tool; call check_messages directly, never as toolId in a delegated gateway'
+            : `no tool "${toolId}" is registered; use search_tools${candidates.length > 0 ? ` — did you mean ${candidates.join(', ')}?` : ''}`,
     },
 };
 /** @returns A copied, attenuated principal; its roles are unchanged. */

package/dist/delegated-tool-bridge.js

@@ -38,6 +38,24 @@ function correlationFor(channel, toolUseId) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * `@jini-ai/chat`'s `UNKNOWN_MUTATION_ERROR`, copied because chat is only a dev dependency here.
+ * A test pins the two equal.
+ */
+const UNKNOWN_MUTATION_ERROR = "This operation may already be done. Its earlier outcome is unknown; verify the current state before repeating it.";
+/**
+ * Model-facing text for a remote tool-call failure, keyed by the `ToolRpcError` `code` string the
+ * remote executor throws. Matched by name and code, not by import, so this file shares nothing with
+ * the executor. An unknown outcome is marked so the durable run blocks a blind repeat.
+ */
+const TOOL_RPC_RESULTS = {
+    TOOL_NOT_DISPATCHED: { content: 'The site did not receive this call; nothing ran. You may retry it.' },
+    TOOL_OUTCOME_UNKNOWN: { content: UNKNOWN_MUTATION_ERROR, outcome: 'unknown' },
+};
+function failedResult({ error }, _optional = {}) {
+    const code = error instanceof Error && error.name === 'ToolRpcError' ? error.code : undefined;
+    return (typeof code === 'string' && Object.hasOwn(TOOL_RPC_RESULTS, code) ? TOOL_RPC_RESULTS[code] : undefined) ?? { content: errorMessage(error) };
+}
 export { serializeDelegatedToolOutput, resultContent } from './tool-result-media.js';
 /**
  * Builds the abort controller handed to `ToolExecutor`, aborted by either a run cancellation or the
@@ -206,7 +224,7 @@ export function createDelegatedToolBridge(requiredArgs, optionalArgs = {}) {
                 seam.settle();
                 await lifecycle.emit({ runId: runId, input: {
                         event: 'agent',
-                        data: { type: 'tool_result', toolUseId, content: errorMessage(error), isError: true },
+                        data: { type: 'tool_result', toolUseId, ...failedResult({ error }, {}), isError: true },
                     } });
                 throw error;
             }

package/dist/http/attachment-lookup-routes.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module attachment-lookup-routes
+ *
+ * `POST /internal/attachment-lookup` — lets another local process (a site server running the
+ * attachment tools) read this daemon's `AttachmentStore` without owning a second copy of it. The
+ * store stays the sole owner of upload records; the caller gets exactly what the store's own two
+ * read methods return, including the store's non-disclosing rejection for a ref another run owns.
+ *
+ * Body: `{ op: "resolveForRun", ref, runId }` or `{ op: "listPendingForOwner", ownerId, runId? }`.
+ * Answer: `200 { value }` (`value: null` for an unknown ref), `400 ATTACHMENT_REJECTED` with
+ * `details.reason` for a store rejection, `400 BAD_REQUEST` for a malformed body, and a redacted
+ * `500` for anything else.
+ *
+ * Authentication is the host's: mount this behind the daemon's own bearer middleware. Run and owner
+ * ids come from the authenticated caller's execution context, never from model input — the store
+ * scopes by them (see `AttachmentStore.listPendingForOwner`).
+ */
+import { type RequestHandler } from 'express';
+import { type AttachmentStore } from './attachments.js';
+export declare const ATTACHMENT_LOOKUP_ROUTE_PATH = "/internal/attachment-lookup";
+/** The two read operations the lookup proxies. */
+export type AttachmentLookupRequest = {
+    readonly op: 'resolveForRun';
+    readonly ref: string;
+    readonly runId: string;
+} | {
+    readonly op: 'listPendingForOwner';
+    readonly ownerId: string;
+    readonly runId?: string;
+};
+/** The read half of `AttachmentStore` a remote caller gets. */
+export type AttachmentLookup = Pick<AttachmentStore, 'resolveForRun' | 'listPendingForOwner'>;
+export interface AttachmentLookupRoutesRequired {
+    readonly app: {
+        post(path: string, ...handlers: RequestHandler[]): unknown;
+    };
+    readonly store: AttachmentLookup;
+}
+/**
+ * Mounts the lookup route. It brings a small JSON parser of its own, which is a no-op when the host
+ * already parsed the body upstream.
+ */
+export declare function registerAttachmentLookupRoutes({ app, store }: AttachmentLookupRoutesRequired, _optional?: Record<string, never>): void;
+//# sourceMappingURL=attachment-lookup-routes.d.ts.map