@jini-ai/daemon 0.3.8 → 0.5.1

package/dist/agent-executor/mcp-bridge.d.ts

@@ -0,0 +1,338 @@
+import { type AcpMcpServerInput, type RuntimeAgentDef } from '@jini-ai/agent-runtime';
+import { type McpJsonInjectionOptions, type McpJsonServerEntry, type McpBridgeDelivery, type PreparedCodexHome, type PreparedClaudeConfigDir, type ClaudeConfigDirIsolationOptions, type FailBeforeSpawn } from './contracts.js';
+/** The run-error code a run gets when its CLI reports the injected `jini` bridge as anything but connected. */
+export declare const MCP_BRIDGE_UNAVAILABLE = "MCP_BRIDGE_UNAVAILABLE";
+/**
+ * Judges a CLI's startup report of the injected bridge. Returns the bridge's status (`'missing'`
+ * when the list omits it) when it is not `'connected'`, and `undefined` when it is connected or
+ * when `rawEvent` is not an init status carrying an MCP server list (nothing to judge).
+ *
+ * `'pending'` counts as a failure on purpose: the CLI decides which MCP tools a session has at
+ * startup, so a bridge that is not connected by then never joins this run.
+ * @param rawEvent - One parsed stream event, as `@jini-ai/agent-runtime`'s parser emits it.
+ * @complexity O(n) in the number of reported servers.
+ */
+export declare function unavailableJiniBridgeStatus({ rawEvent }: {
+    readonly rawEvent: unknown;
+}): string | undefined;
+/** The user-readable reason a run stopped because its bridge did not connect. */
+export declare function bridgeUnavailableMessage(status: string): string;
+/**
+ * Builds this run's `mcpServers.jini` entry — pure and synchronous, so every field mapping is
+ * directly assertable without touching the filesystem. The credential arrives already resolved:
+ * `McpJsonInjectionOptions.credential` is a possibly-async per-run resolver, and awaiting it is
+ * `writeMcpJsonForRun`'s job, which keeps the effect out of this function.
+ *
+ * @param runId - The run this entry scopes its child to.
+ * @param options - `command`/`args`/`daemonUrl`/`env` from the host's injection options.
+ * @param credential - The already-resolved bearer token, or `undefined` to omit `JINI_DAEMON_TOKEN`
+ * entirely. Omitting produces byte-identical output to before this parameter existed.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function buildMcpJsonServerEntry({ runId, options }: {
+    readonly runId: string;
+    readonly options: Pick<McpJsonInjectionOptions, 'command' | 'args' | 'daemonUrl' | 'env'>;
+}, { credential }?: {
+    readonly credential?: string;
+}): McpJsonServerEntry;
+/**
+ * Merges {@link JINI_MCP_SERVER_KEY} into an existing `.mcp.json`'s `mcpServers` map, preserving
+ * every other key and every other registered server untouched. A missing (`existingRaw ===
+ * undefined`), empty, or unparseable-as-a-JSON-object existing file all degrade to "start from an
+ * empty document" rather than throwing — an unparseable project `.mcp.json` is a pre-existing
+ * problem this driver did not create and cannot safely repair, so it is deliberately overwritten
+ * with a fresh, valid file containing just this run's bridge entry rather than left broken or
+ * left blocking the run. Pure — no I/O — so every branch is directly assertable.
+ * @complexity O(1) plus `JSON.parse`/`JSON.stringify`'s own cost on a small config file.
+ * @overallScore 100/100
+ */
+export declare function mergeMcpJsonContent({ existingRaw, serverEntry }: {
+    readonly existingRaw: string | undefined;
+    readonly serverEntry: McpJsonServerEntry;
+}): string;
+/**
+ * Mechanism 2 of 5 — `'acp-merge'`. Re-shapes the same bridge entry into the `mcpServers` element
+ * an ACP `session/new` call carries, for the 9 ACP-native defs declaring this strategy (amr, devin,
+ * hermes, kilo, kimi, kiro, reasonix, trae-cli, vibe). Pure.
+ *
+ * `env` is emitted as a plain object on purpose: `@jini-ai/agent-runtime`'s
+ * `buildAcpSessionNewParams` already normalises a plain-object `env` into either the
+ * `[{name, value}]` array form or the `{"KEY": "val"}` map form according to each def's own
+ * `acpMcpEnvFormat`, so the per-vendor wire-shape difference stays in the one place that already
+ * owns it rather than being re-decided here.
+ *
+ * **The credential travels in `env`, never in `args`.** An ACP agent spawns this server itself and
+ * applies `env` to that child's environment; a token in `args` would land in the child's process
+ * arguments, readable by any other local user via `ps`. Same rule as the `.mcp.json` path.
+ *
+ * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
+ * @returns A single-element list — this driver contributes exactly its own bridge server and never
+ * removes or rewrites servers a def or host added by other means.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function buildAcpMcpBridgeServers({ entry }: {
+    readonly entry: McpJsonServerEntry;
+}): AcpMcpServerInput[];
+/**
+ * Serialises the bridge entry into the OpenCode-schema config JSON that `OPENCODE_CONFIG_CONTENT`
+ * / `MIMOCODE_CONFIG_CONTENT` carries, merging into whatever the host already put in that variable
+ * rather than replacing it — the same "merge, never clobber" discipline
+ * {@link mergeMcpJsonContent} applies to `.mcp.json`, and for the same reason: a host may already
+ * be handing the CLI the *user's* configured MCP servers through this exact variable, and
+ * overwriting it would silently delete them.
+ *
+ * A missing, empty, or unparseable-as-a-JSON-object existing value degrades to "start from an empty
+ * document". Overwriting an unparseable value is deliberate and matches `mergeMcpJsonContent`: this
+ * driver did not create it, cannot safely repair it, and must not block the run on it.
+ *
+ * Emitted per server: `{type: 'local', command: [<command>, ...<args>], environment: {...},
+ * enabled: true}` — the shape `@jini-ai/mcp`'s own `buildOpenCodeMcpConfigContent` emits for a
+ * stdio server, so both producers stay schema-compatible.
+ *
+ * **The credential lands in `environment`, i.e. the MCP child's env — never in `command`.** OpenCode
+ * spawns the bridge from `command`, so a token placed there would be visible in `ps` output to
+ * every other local user. This is the same constraint that keeps `JINI_DAEMON_TOKEN` out of argv on
+ * the `.mcp.json` and ACP paths.
+ *
+ * @param existingRaw - Whatever the spawn env already held for this variable, or `undefined`.
+ * @param entry - The shared bridge entry from {@link buildMcpJsonServerEntry}.
+ * @returns The full JSON string to set as the env var's value.
+ * @complexity O(1) plus `JSON.parse`/`JSON.stringify` over a small config document.
+ * @overallScore 100/100
+ */
+export declare function mergeEnvContentMcpConfig({ existingRaw, entry }: {
+    readonly existingRaw: string | undefined;
+    readonly entry: McpJsonServerEntry;
+}): string;
+/**
+ * Merges a staged system-prompt overlay file's path into the `instructions` array of the same
+ * OpenCode-schema config document {@link mergeEnvContentMcpConfig} writes `mcp` into — for a
+ * `systemPromptDelivery: { strategy: 'config-instructions-file' }` def (`opencode` today).
+ *
+ * Confirmed live (2026-09-01, opencode-cli 1.17.10), not inferred from docs alone:
+ *   1. `instructions` is honored — a run configured with it visibly followed the file's directive
+ *      (a required exact-token prefix), while an identical run without it did not.
+ *   2. It appends, never replaces: the same run that followed the custom instruction ALSO still
+ *      answered correctly using opencode's own baked-in environment-context system prompt (asked
+ *      for its cwd, with nothing about cwd anywhere in the custom instructions file) — proof
+ *      opencode's own defaults survive alongside a custom `instructions` entry, not just proof the
+ *      file was read at all.
+ *   3. Adding this key alongside `mcp` in the same `OPENCODE_CONFIG_CONTENT` document disturbs
+ *      neither: in one combined run, the MCP bridge still got its connection attempt (logged
+ *      `key=jini type=local`) AND the custom instruction was still followed — same as running each
+ *      key alone.
+ *   4. `instructions` is re-read fresh from the env on every spawn, including a `-s <id>`-resumed
+ *      turn (proved by swapping in a second instructions file between two turns of one resumed
+ *      session and seeing the second turn immediately reflect it while still recalling
+ *      conversation memory from turn one) — so this mechanism is safe to redeliver every turn like
+ *      `'append-flag'`/`'env-var'`, exempt from the prompt-prefix fallback's create-only gating
+ *      (see {@link resolveSystemPromptOverlayDelivery}'s doc): nothing here is ever baked into
+ *      opencode's own persisted session state the way re-injecting fallback prompt text would be.
+ *
+ * @param existingRaw - Whatever the spawn env already held for this variable (already possibly
+ * carrying `mcp`, if `mergeEnvContentMcpConfig` ran first on the same value — order between the two
+ * doesn't matter, each only touches its own top-level key), or `undefined`.
+ * @param instructionsFilePath - The staged overlay file's absolute path (see
+ * {@link prepareSystemPromptOverlayFileIfNeeded}).
+ * @returns The full JSON string to set as the env var's value. Appends to, never clobbers, any
+ * `instructions` entries already present — the same "merge, never clobber" discipline
+ * {@link mergeEnvContentMcpConfig} applies to `mcp`, in case a host is already using this same
+ * config-content variable to carry the operator's own instruction files.
+ * @complexity O(1) plus `JSON.parse`/`JSON.stringify` over a small config document.
+ * @overallScore 100/100
+ */
+export declare function mergeEnvContentInstructions({ existingRaw, instructionsFilePath }: {
+    readonly existingRaw: string | undefined;
+    readonly instructionsFilePath: string;
+}): string;
+/**
+ * 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 declare function buildCodexMcpServerToml({ entry }: {
+    readonly entry: McpJsonServerEntry;
+}): string;
+/**
+ * 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
+ * ever removed, via the narrow line-oriented scan above, never a full TOML parse.
+ * @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 declare function buildCodexHomeConfigToml({ existingRaw, entry }: {
+    readonly existingRaw: string | undefined;
+    readonly entry: McpJsonServerEntry;
+}): string;
+/**
+ * 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 declare function resolveSourceCodexHomeDir({ hostEnv }: {
+    readonly hostEnv: NodeJS.ProcessEnv;
+}): string;
+/**
+ * **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
+ * resolved, so every strategy's mapping is directly assertable without touching the filesystem,
+ * the environment, or a keystore.
+ *
+ * Keyed off the declared *strategy*, never off `def.id`: a def gets a working bridge by declaring a
+ * mechanism, not by being named in this file. That is what makes the 9 `'acp-merge'` defs work
+ * without any of their own files being touched.
+ *
+ * @param input.cwd - The run's working directory; only `'claude-mcp-json'` uses it, to place this
+ * run's own config file (see {@link mcpJsonPathForRun}) — never `cwd/.mcp.json` itself.
+ * @param input.runId - Scopes the bridge child to this run.
+ * @param input.strategy - The def's declared `externalMcpInjection`, or `undefined` for a def with no native MCP transport.
+ * @param input.options - The host's bridge options, or `undefined` when the host never configured injection.
+ * @param input.credential - Already-resolved bearer token, or `undefined` to omit `JINI_DAEMON_TOKEN` entirely.
+ * @returns `null` when this run delivers nothing — an unconfigured host, or a def declaring no
+ * strategy — which is byte-identical to this feature not existing.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function buildMcpBridgeDelivery(input: {
+    readonly cwd: string;
+    readonly runId: string;
+    readonly strategy: RuntimeAgentDef['externalMcpInjection'];
+    readonly options: McpJsonInjectionOptions | undefined;
+    readonly credential: string | undefined;
+}): McpBridgeDelivery | null;
+export declare function defaultRemoveMcpJsonFile({ path }: {
+    readonly path: string;
+}): Promise<void>;
+/**
+ * Where `claude`'s own config resolution reads the operator's REAL config from, to seed a run's
+ * scratch copy — never where it writes. Mirrors {@link resolveSourceCodexHomeDir}'s exact reasoning
+ * and resolution order: `CLAUDE_CONFIG_DIR` is not in `BASELINE_AGENT_ENV_KEYS`, so a spawned child
+ * never inherits it anyway — the whole point is finding wherever the *operator's actual* Claude Code
+ * install lives, a host-machine fact resolved against the daemon HOST process's own environment.
+ * @param hostEnv - The daemon process's own environment.
+ * @returns `hostEnv.CLAUDE_CONFIG_DIR` when set to a non-blank value (matching Claude Code's own
+ * resolution order, confirmed against installed Claude Code 2.1.263), else the CLI's documented
+ * default, `~/.claude`.
+ * @complexity O(1).
+ */
+export declare function resolveSourceClaudeConfigDir({ hostEnv }: {
+    readonly hostEnv: NodeJS.ProcessEnv;
+}): string;
+/** Phase 5: resolves this run's MCP bridge delivery (credential resolution + {@link buildMcpBridgeDelivery}). */
+export declare function resolveMcpBridgeForRun({ input, deps }: {
+    readonly input: {
+        readonly runId: string;
+        readonly cwd: string;
+        readonly def: RuntimeAgentDef;
+    };
+    readonly deps: {
+        readonly mcpJsonInjection: McpJsonInjectionOptions | undefined;
+        readonly cleanupStagedFiles: () => Promise<void>;
+        readonly failBeforeSpawn: FailBeforeSpawn;
+    };
+}): Promise<McpBridgeDelivery | null>;
+/** Phase 10: mechanism 1 of 5's one effect — stages this run's own `.mcp.json`, returning the path `cleanupStagedFiles` should later remove (`undefined` for every other mechanism / unconfigured host). */
+export declare function writeMcpJsonIfNeeded({ input, deps }: {
+    readonly input: {
+        readonly runId: string;
+        readonly cwd: string;
+        readonly def: RuntimeAgentDef;
+        readonly mcpBridge: McpBridgeDelivery | null;
+    };
+    readonly deps: {
+        readonly mcpJsonInjection: McpJsonInjectionOptions | undefined;
+        readonly releaseStagedResources: () => Promise<void>;
+        readonly failBeforeSpawn: FailBeforeSpawn;
+    };
+}): Promise<string | undefined>;
+/**
+ * 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 declare function prepareCodexHomeIfNeeded({ input, deps }: {
+    readonly input: {
+        readonly runId: string;
+        readonly def: RuntimeAgentDef;
+        readonly mcpBridge: McpBridgeDelivery | null;
+    };
+    readonly deps: {
+        readonly mcpJsonInjection: McpJsonInjectionOptions | undefined;
+        readonly hostEnv: NodeJS.ProcessEnv;
+        readonly releaseStagedResources: () => Promise<void>;
+        readonly failBeforeSpawn: FailBeforeSpawn;
+    };
+}): Promise<PreparedCodexHome | null>;
+/**
+ * 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
+ * release (`null` for every def other than `claude` — see {@link prepareClaudeConfigDirForRun}'s
+ * own doc for why this is unconditional for `claude` runs, unlike {@link prepareCodexHomeIfNeeded}'s
+ * gate on a host-configured MCP bridge strategy).
+ *
+ * Gated on `def.id === 'claude'` directly rather than on `externalMcpInjection === 'claude-mcp-json'`
+ * (which `codebuddy` also declares): isolating the operator's personal `~/.claude` is specific to
+ * the real `claude` CLI's own config resolution, not to every def that happens to share its `.mcp.
+ * json` delivery shape. Matches the existing `USER`-for-claude-login special case already singled
+ * out by id in `BASELINE_AGENT_ENV_KEYS`'s own doc in `launch.ts`.
+ *
+ * ALSO gated on `deps.enabled` (`CreateAgentExecutorOptions.claudeConfigDirIsolationEnabled`, default
+ * `false`) since this task's own fix — see that field's doc for why it defaults off (Keychain login
+ * is `CLAUDE_CONFIG_DIR`-keyed and no caller was supplying a credential when this was unconditional).
+ * `def.id === 'claude'` is still checked first and independently: a host that flips this flag on
+ * should not suddenly stage a directory for `codebuddy` or any other def.
+ * @param input.def - Used for both the `id` gate and the failure message.
+ * @param deps.enabled - The isolation on/off switch — see this function's own doc above.
+ * @param deps.hostEnv - The daemon's own environment, threaded through to {@link resolveSourceClaudeConfigDir} rather than read from a module-level `process.env`, matching {@link prepareCodexHomeIfNeeded}'s identical testability reasoning.
+ * @complexity O(1) plus {@link prepareClaudeConfigDirForRun}'s own cost.
+ */
+export declare function prepareClaudeConfigDirIfNeeded({ input, deps }: {
+    readonly input: {
+        readonly runId: string;
+        readonly def: RuntimeAgentDef;
+    };
+    readonly deps: {
+        readonly enabled: boolean;
+        readonly claudeConfigDirIsolation: ClaudeConfigDirIsolationOptions | undefined;
+        readonly hostEnv: NodeJS.ProcessEnv;
+        readonly releaseStagedResources: () => Promise<void>;
+        readonly failBeforeSpawn: FailBeforeSpawn;
+    };
+}): Promise<PreparedClaudeConfigDir | null>;
+//# sourceMappingURL=mcp-bridge.d.ts.map