@jini-ai/daemon 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Open Design contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/agent-executor.d.ts

@@ -0,0 +1,458 @@
+/**
+ * `AgentExecutor` — the driver `RunLifecycle`'s own module doc names as the
+ * missing piece: *"It does not spawn or signal a subprocess... A driver...
+ * calls `emit()` for agent/stdout/stderr/error events, observes cancellation
+ * via `onCancelRequested`, and calls `finish()` once it knows the real
+ * outcome."* This module is that driver — it wires `@jini-ai/agent-runtime`'s
+ * registry/launch-resolution/stream-parsers (previously a complete but
+ * disconnected library, zero callers anywhere outside its own package) into
+ * a real `node:child_process` spawn, feeding both `RunLifecycle.emit()` and
+ * this package's own `@jini-ai/protocol` event envelope.
+ *
+ * ## v1 scope: 23 of 24 registered agent defs
+ *
+ * `@jini-ai/agent-runtime`'s registry ships 24 built-in defs across four
+ * `streamFormat` families. The JSON-stream-parser family — the four
+ * `createXStreamHandler`-shaped parsers (`claude-stream-json`,
+ * `json-event-stream`, `copilot-stream-json`, `qoder-stream-json`), covering
+ * 9 defs (amp, codebuddy, claude, codex, cursor-agent, opencode, mimo,
+ * copilot, qoder) — plus all 9 `acp-json-rpc` defs, plus the one `pi-rpc`
+ * def (`pi`), are wired here. ACP and pi-rpc each own their own JSON-RPC
+ * prompt-delivery protocol, so each takes its own lifecycle branch rather
+ * than being treated as a stdout-tail parser; pi-rpc's events arrive through
+ * the exact same `{type, ...}` vocabulary `translateAgentRuntimeEvent`
+ * already handles for ACP/JSON-stream (confirmed by reading every
+ * `mapPiRpcEvent` `send()` call site — no new translation code was needed),
+ * so only the driver wiring (spawn → attach → cancel → finish) was new for it.
+ *
+ * 4 of the 5 `streamFormat: 'plain'` defs — grok-build, aider, deepseek,
+ * qwen — are also driven, per
+ * `ADS-memory/reports/proposals/PROP-plain-format-agent-driving-2026-07-21.md`'s
+ * recommended "Option B": no structured stream parser at all. Every raw
+ * `child.stdout` chunk is forwarded verbatim as a `text_delta` `'agent'`
+ * event, live, as it arrives — never buffered until close (see
+ * `wireChildLifecycle`'s `streamFormat === 'plain'` branch). Prompt delivery
+ * across the 4 is not uniform: qwen already fit the pre-existing stdin-only
+ * guard; grok-build stages the prompt to a temp file via
+ * `preparePromptFileForAgent` (its path threaded into `buildArgs` through a
+ * `RuntimeContext`, cleaned up after the child exits on every path,
+ * including pre-spawn/spawn-failure ones); aider/deepseek carry the prompt
+ * on argv and are guarded pre-spawn by `checkPromptArgvBudget` plus the two
+ * Windows CreateProcess command-line-expansion guards
+ * (`checkWindowsCmdShimCommandLineBudget`/`checkWindowsDirectExeCommandLineBudget`).
+ *
+ * The 5th plain def, **antigravity, is deliberately still rejected.** It
+ * needs two concerns unrelated to `streamFormat: 'plain'` itself — buffering
+ * stdout until close so a leaked OAuth URL can be suppressed before it
+ * reaches the client, and a cross-run lock serializing writes to its shared
+ * `settings.json` model-selection file — that the proposal doc explicitly
+ * scoped out to its own follow-up (see that doc's §2c/§3). `run()` guards it
+ * with its own `def.id === 'antigravity'` check, ahead of (and independent
+ * of) the generic plain-format prompt-delivery/dispatch logic. `run()`
+ * rejects cleanly (never a bare throw) with an `AgentExecutorError` for any
+ * def outside the supported 23 — see `isSupportedStreamFormat`.
+ *
+ * ## Invariant
+ *
+ * `RunLifecycle.start()` already transitions a run to `'running'` before
+ * `run()` is ever called. Every *pre-spawn* failure path in `run()` — unknown
+ * `agentId`, an unsupported `streamFormat`/prompt-delivery shape, an
+ * unresolvable binary, or a spawn error — calls `lifecycle.finish({status:
+ * 'failed', resumable: false, code: null, signal: null})` itself before
+ * rejecting, so a run can never get stuck `'running'` with no watchdog.
+ * `resumable` is unconditionally `false` on these paths — there is no spawned
+ * child, hence nothing a classifier could examine (see
+ * `FailureClassificationContext`'s own doc).
+ *
+ * For a run that *did* spawn and then failed, `resumable` is decided by
+ * `classifyFailure` (gap 4 — see `ClassifyFailure`'s own doc), an injectable
+ * port with no default of its own in this module (`undefined` stays
+ * byte-identical to pre-gap-4 behavior — every `'failed'` outcome
+ * resumable:false). OD's ~20-vendor-CLI text-matching failure classifier was
+ * deliberately never ported (see `run/core/failure-taxonomy.ts`'s own doc and
+ * `source-map.md`). The real zero-config classifier lives in `@jini-ai/daemon`'s
+ * `run/core/retry.ts` (`resumableFromProcessExit`/`classifyProcessExitFailure`)
+ * and is wired in by `@jini-ai/node-host`'s `createLocalNodeDaemon` — see that
+ * package's own source-map.md, and `run/core/retry.ts`'s own doc for the
+ * classification policy and its 2026-07-22 merge-time reconciliation against
+ * a second, independently-built (and rejected) classifier that once lived in
+ * this module.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { Principal } from '@jini-ai/core';
+import type { RunAgentPayload, RunErrorPayload } from '@jini-ai/protocol';
+import { applyAgentLaunchEnv, getAgentDef, resolveAgentLaunch, attachAcpSession, attachPiRpcSession, preparePromptFileForAgent, type AcpPermissionHandler } from '@jini-ai/agent-runtime';
+import { collectProcessTreePids, createCommandInvocation, listProcessSnapshots, stopProcesses } from '@jini-ai/platform';
+import type { RunByteJournal } from './continuation/journal.js';
+import type { RunRetrySideEffectState } from './run/core/index.js';
+import type { ToolExecutor } from './tool-executor.js';
+import type { RunLifecycle } from './run-lifecycle.js';
+declare const SUPPORTED_STREAM_FORMATS: readonly ["claude-stream-json", "json-event-stream", "copilot-stream-json", "qoder-stream-json", "acp-json-rpc", "pi-rpc", "plain"];
+/** The families of the registry's stream-format this driver implements — see module doc. */
+export type SupportedStreamFormat = (typeof SUPPORTED_STREAM_FORMATS)[number];
+/**
+ * Narrows a `RuntimeAgentDef.streamFormat` string to the supported
+ * families.
+ * @param value - The def's raw `streamFormat` string.
+ * @returns `true` when `value` is one of the JSON-stream-parser, ACP, pi-rpc, or plain formats this driver wires.
+ * @complexity O(1) — fixed membership check.
+ * @overallScore 100/100
+ */
+export declare function isSupportedStreamFormat(value: string): value is SupportedStreamFormat;
+/**
+ * Result of translating one parsed stream event into this engine's
+ * vocabulary. `'agent'` is the common case (forward as a `RunAgentPayload`
+ * via the `'agent'` run event); `'error'` and `'turn-end'` are the two
+ * type values `run()` handles specially rather than passing through (see
+ * module doc); `'ignored'` covers anything the 4 parsers never actually
+ * produce plus defensively malformed/non-record input.
+ *
+ * `'agent'`'s optional `sessionId` (gap 5, session resume — see
+ * `RunEndPayload.sessionRef`'s doc in `@jini-ai/protocol`) is a daemon-internal
+ * side channel, not part of the `RunAgentPayload` wire payload itself:
+ * OpenCode's `sessionID`/Codex's `thread_id`/Qoder's and Claude's
+ * `session_id` all arrive on a `'status'` event alongside fields
+ * `RunAgentPayload`'s `'status'` variant already models (`label`/`model`/
+ * `ttftMs`/`detail`) but has no room for a session id itself — surfacing it
+ * here lets a lifecycle-wiring function capture it into a local variable and
+ * thread it into its own terminal `finish()` call, without widening the
+ * public wire protocol just to carry a value that only this module reads.
+ *
+ * `'turn-end'`'s optional `stopReason` (gap 3, capability-routed
+ * continuation transport) is the same kind of internal side channel: the
+ * claude-stream parser deliberately emits `stopReason` *after* every
+ * `tool_use` block in the same assistant message has already been
+ * translated (so a caller can decide whether to keep stdin open before
+ * closing it), but v1 (pre-gap-3) discarded it and closed stdin
+ * unconditionally on any `turn-end` — see `packages/daemon/source-map.md`'s
+ * "Design decision 2" note. `wireChildLifecycle` now reads it to decide
+ * whether `stop_reason: 'tool_use'` means "inject a tool result and keep
+ * going" (gap 3, gated — see `ContinuationOptions`) or "close stdin as
+ * before" (the unconditional default when no continuation is configured).
+ */
+export type AgentRuntimeEventTranslation = {
+    readonly kind: 'agent';
+    readonly payload: RunAgentPayload;
+    readonly sessionId?: string;
+} | {
+    readonly kind: 'error';
+    readonly payload: RunErrorPayload;
+} | {
+    readonly kind: 'turn-end';
+    readonly stopReason?: string;
+} | {
+    readonly kind: 'ignored';
+};
+/**
+ * Narrows one parser-emitted `{type, ...}` record into this engine's
+ * `RunAgentPayload` union (or the `error`/`turn-end`/`ignored` routing
+ * `run()` special-cases). Pure — no I/O, no closure state — so every
+ * variant each of the 4 supported parsers can produce is directly
+ * assertable in isolation.
+ *
+ * Defensive by construction: several real parser emissions carry fields
+ * looser than `RunAgentPayload`'s types promise (e.g. copilot's
+ * `tool.execution_start` emits `id: data.toolCallId ?? null` — a literal
+ * `null`, not the `string` `RunAgentPayload['tool_use']['id']` demands).
+ * Every field read here is defensively coerced (`asString`/
+ * `asOptionalString`/`asOptionalNumber`) rather than trusted, so a
+ * malformed or null field degrades to a safe default instead of
+ * propagating `null`/`undefined` into a field typed as required, or
+ * throwing.
+ *
+ * @param rawEvent - One event as delivered to a stream parser's `onEvent` callback.
+ * @returns The routing + payload this event maps to.
+ * @complexity O(1) — one discriminant switch, no iteration.
+ * @overallScore 100/100
+ */
+export declare function translateAgentRuntimeEvent(rawEvent: unknown): AgentRuntimeEventTranslation;
+/** Machine-readable failure reasons `run()` can reject with — every one is preceded by a `lifecycle.finish({status:'failed'})` call (see module doc's Invariant section). */
+export type AgentExecutorErrorCode = 'AGENT_NOT_FOUND' | 'AGENT_RUNTIME_UNSUPPORTED' | 'AGENT_BINARY_NOT_RESOLVED' | 'AGENT_SPAWN_FAILED' | 'AGENT_PROMPT_TOO_LARGE';
+/** Thrown by `AgentExecutor.run()` on every failure path — never a bare `Error`, so callers can branch on `.code` instead of parsing `.message`. */
+export declare class AgentExecutorError extends Error {
+    readonly code: AgentExecutorErrorCode;
+    constructor(code: AgentExecutorErrorCode, message: string);
+}
+export interface AgentExecutorRunInput {
+    readonly runId: string;
+    readonly agentId: string;
+    readonly prompt: string;
+    readonly cwd: string;
+    /** Optional host-selected model id, forwarded to every runtime transport. */
+    readonly model?: string;
+    /** Optional host-selected reasoning effort, forwarded to runtime argv builders. */
+    readonly reasoning?: string;
+    /** Host-validated image files forwarded through argv, ACP, or pi-rpc. */
+    readonly imagePaths?: readonly string[];
+    /** Additional host-validated directories the runtime may read. */
+    readonly extraAllowedDirs?: readonly string[];
+    /** Trusted root that must contain pi-rpc image paths after realpath resolution. */
+    readonly uploadRoot?: string;
+    /**
+     * Credential(s) this run's selected agent/provider needs (e.g. `{ ANTHROPIC_API_KEY: '...' }`),
+     * delegated explicitly by the host and merged into the baseline-allowlisted env below. Never
+     * read implicitly from `process.env` — see SEC-001.
+     */
+    readonly credentialEnv?: Record<string, string>;
+    /**
+     * Explicit escape hatch: when supplied, used verbatim as the spawned subprocess's entire
+     * environment (no allowlist filtering) — for tests and hosts that have already done their own
+     * scoping. When omitted (the default), the subprocess gets only `BASELINE_AGENT_ENV_KEYS` from
+     * the host's real env plus `credentialEnv`, never a full `process.env` passthrough. A spawned
+     * coding-agent CLI is prompt-influenced and must be treated as potentially adversarial; it must
+     * not inherit secrets the daemon process happens to hold for unrelated reasons. See SEC-001
+     * (`ADS-memory/reports/proposals/PROP-agent-subprocess-env-allowlist-2026-07-21.md`) and locked
+     * architecture decision C8 (`foundry/docs/jini-port/extraction-plan.md`).
+     */
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface AgentExecutor {
+    /**
+     * Spawns `agentId`'s CLI for `runId`, wires its stdout/stderr into
+     * `lifecycle.emit()`, and resolves once the child process is confirmed
+     * spawned (fire-and-forget from there — see module doc). Callers await
+     * `lifecycle.waitForTerminal(runId)` separately for completion.
+     * @throws {@link AgentExecutorError} on every failure path — the
+     * underlying run is always already transitioned to `'failed'` via
+     * `lifecycle.finish()` before this rejects (see module doc's Invariant).
+     */
+    run(input: AgentExecutorRunInput): Promise<void>;
+}
+/** Which caller invoked {@link terminateChildTreeBestEffort} — carried through to `onCleanupFailure` (SEC-007) for diagnosis. */
+export type AgentCleanupFailurePhase = 'cancel' | 'acp-attach-failure' | 'pi-rpc-attach-failure';
+export interface AgentCleanupFailureContext {
+    readonly runId: string;
+    readonly phase: AgentCleanupFailurePhase;
+    readonly pid: number;
+    readonly error: unknown;
+}
+/**
+ * Gap 3 (capability-routed continuation transport) — host-owned config for the
+ * `'stdin-injection'` transport (claude/codebuddy only; see
+ * `resolveContinuationTransport`'s doc). **Absent by default, and absent means
+ * zero behavior change**: with no `ContinuationOptions`, every `turn_end`
+ * closes stdin exactly as it always has (v1 behavior, unconditionally).
+ *
+ * `autonomousToolNames` is this task's answer to the debate's Unresolved
+ * Delta (how does the loop distinguish "the agent is continuing
+ * autonomously" from "the agent is waiting on a human"): rather than
+ * inferring intent from the stream, the *host* pre-declares which tool
+ * names are safe to auto-resolve and re-inject without a human in the loop.
+ * A `tool_use` whose name is not in this set is left exactly as it was
+ * before gap 3 — stdin closes, the run proceeds to its normal terminal
+ * state — even though a `stopReason: 'tool_use'` was observed. This sidesteps
+ * building unproven intent-detection: nothing auto-continues unless a host
+ * has explicitly vetted that specific tool as autonomous-safe. A
+ * human-facing "ask the user a question" tool is simply never added to this
+ * set; `packages/chat-core/src/question-form.ts`'s existing text-tag
+ * mechanism (a new `Run` per turn, not mid-turn injection) already covers
+ * that case without needing this transport at all.
+ */
+export interface ContinuationOptions {
+    /** Injected tool results are authorized through this — the same deny-by-default gate every other tool execution path in this codebase uses. No parallel authorization path. */
+    readonly toolExecutor: ToolExecutor;
+    /** The principal an injected tool call is authorized as. */
+    readonly principal: Principal;
+    /** Tool names this host has pre-classified as safe to auto-resolve without human involvement. See this interface's own doc for why this — not stream-inferred intent — is gap 3's answer to the human-in-the-loop pause question. */
+    readonly autonomousToolNames: ReadonlySet<string>;
+}
+/**
+ * Gap 3, part 2 (MCP-callback continuation transport — the spawn-time half the spike's own
+ * commit message named as undone: "Item 4 ... NOT done yet"). `resolveContinuationTransport`
+ * already resolves `'mcp-callback'` for every def with `externalMcpInjection !== undefined`, but
+ * nothing in this file ever *acted* on that resolution — `execute_delegated_tool`
+ * (`@jini-ai/mcp`'s `../server/tools/delegated-tool.ts`) only does anything useful once the spawned
+ * CLI's own client actually launches `jini-mcp` as its MCP server subprocess, and the only
+ * `externalMcpInjection` strategy that mechanism is wired for here is `'claude-mcp-json'`
+ * (`claude`/`codebuddy` — see `@jini-ai/agent-runtime`'s `types.ts` doc on the other three
+ * strategies: `'acp-merge'` delivers `mcpServers` through the ACP `session/new` params
+ * `wireAcpLifecycle`/`attachAcpSession` already carry, and `'opencode-env-content'`/
+ * `'mimo-env-content'` deliver through spawn-env content, neither of which needs or wants a
+ * written file — a future task wiring those two would extend `wireAcpLifecycle`'s existing
+ * `envFormat`/`mcpServers` passthrough or `applyAgentLaunchEnv`'s env composition respectively,
+ * not this function).
+ *
+ * **Host-resolved, not this package's to know.** `command`/`daemonUrl` have no default the way
+ * `journal`/`continuation`/`classifyFailure` don't either — there is no "real" install layout or
+ * loopback URL this package could assume on a caller's behalf (matching every other seam on this
+ * interface that defaults to *nothing* rather than a real implementation).
+ */
+export interface McpJsonInjectionOptions {
+    /** Absolute path (or PATH-resolvable name) to the `jini-mcp` bin entry (`packages/mcp/src/bin/serve.ts`) this driver tells the spawned CLI to launch as its own MCP server subprocess. */
+    readonly command: string;
+    /** Extra argv for `command`. @default [] */
+    readonly args?: readonly string[];
+    /** The daemon's own loopback base URL the spawned `jini-mcp` process calls back into via `JINI_DAEMON_URL` (see `packages/mcp/src/bin/serve.ts`'s `DAEMON_URL_ENV_VAR`). */
+    readonly daemonUrl: string;
+    /** Reads an existing `.mcp.json` at the given absolute path so this driver merges rather than clobbers a project's own file. Rejecting (ENOENT or otherwise) is treated as "no existing file" — see `writeMcpJsonForRun`. @default the real `fs.promises.readFile` (utf8) */
+    readonly readFile?: (path: string) => Promise<string>;
+    /** Writes the merged `.mcp.json` content back out. @default the real `fs.promises.writeFile` (utf8) */
+    readonly writeFile?: (path: string, content: string) => Promise<void>;
+}
+/** One `.mcp.json` `mcpServers` entry — the shape Claude Code's own config schema expects. */
+interface McpJsonServerEntry {
+    readonly command: string;
+    readonly args: string[];
+    readonly env: {
+        readonly JINI_RUN_ID: string;
+        readonly JINI_DAEMON_URL: string;
+    };
+}
+/**
+ * Builds this run's `mcpServers.jini` entry — pure, so every field mapping is directly
+ * assertable without touching the filesystem.
+ * @complexity O(1).
+ * @overallScore 100/100
+ */
+export declare function buildMcpJsonServerEntry(runId: string, options: Pick<McpJsonInjectionOptions, 'command' | 'args' | 'daemonUrl'>): 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: string | undefined, serverEntry: McpJsonServerEntry): string;
+/**
+ * Gap 4 of the run/chat orchestration Final Recommendation: what
+ * `classifyFailure` (see `CreateAgentExecutorOptions.classifyFailure`) is
+ * given to decide whether a `'failed'` run is `resumable`. `code`/`signal`
+ * are the only *content-level* signals cheaply available at every one of the
+ * three lifecycle-wiring close handlers without new stderr/stdout buffering
+ * machinery (a host wanting output-pattern-based classification, the way
+ * OD's own ~20-vendor text-matching classifier worked, would need its own
+ * listener for that — an honest scope limit, not an oversight).
+ *
+ * `sideEffects` (2026-07-22) carries the two `RunRetrySideEffectState` fields
+ * every `wire*Lifecycle` driver already tracks live from the translated
+ * agent-event stream it's processing anyway — `userVisibleOutputSeen` (a
+ * non-empty `text_delta`/`thinking_delta`) and `toolCallSeen` (a `tool_use`)
+ * — so `decideSafeRunRetry`'s matching suppression guards are genuinely
+ * exercised, not permanently dead code. Two related fields are deliberately
+ * absent: `cancelRequested` is never included because it's structurally
+ * always `false` by the time a classifier runs at all (a cancelled run's
+ * status already routes to `'cancelled'` before `classifyFailure` is ever
+ * consulted — see each `wire*Lifecycle` close handler); `artifactWriteSeen`/
+ * `liveArtifactSeen` have no real signal to derive them from at all —
+ * `@jini-ai/protocol`'s `RunAgentEventPayload` union (`events.ts`) has no
+ * `'artifact'`/`'live_artifact'` event kind yet (Jini's own generalized
+ * GenUI/artifact surface isn't built — see this repo's "A2UI full protocol
+ * deferred" scope note), unlike OD, which `RunRetrySideEffectState`'s shape
+ * was carried over from.
+ */
+export interface FailureClassificationContext {
+    readonly runId: string;
+    readonly agentId: string;
+    readonly code: number | null;
+    readonly signal: string | null;
+    readonly sideEffects: Pick<RunRetrySideEffectState, 'userVisibleOutputSeen' | 'toolCallSeen'>;
+}
+/**
+ * Host-owned failure classifier — gap 4. Decides, for one specific
+ * `'failed'` run, whether `RunLifecycle.finish()`'s `resumable` flag should
+ * be `true`. Never consulted for `'succeeded'`/`'cancelled'` outcomes, and
+ * never consulted for a pre-spawn failure (`failBeforeSpawn`'s call sites) —
+ * those represent failures where no child process ever ran, so there is
+ * nothing a classifier could meaningfully examine.
+ */
+export type ClassifyFailure = (context: FailureClassificationContext) => boolean | Promise<boolean>;
+export interface CreateAgentExecutorOptions {
+    readonly lifecycle: RunLifecycle;
+    /** @default the real `@jini-ai/agent-runtime` registry lookup */
+    readonly getAgentDef?: typeof getAgentDef;
+    /** @default the real `@jini-ai/agent-runtime` launch resolver */
+    readonly resolveAgentLaunch?: typeof resolveAgentLaunch;
+    /** @default the real `@jini-ai/agent-runtime` PATH-env composer */
+    readonly applyAgentLaunchEnv?: typeof applyAgentLaunchEnv;
+    /** @default the real `@jini-ai/platform` cross-platform invocation builder */
+    readonly createCommandInvocation?: typeof createCommandInvocation;
+    /** @default `node:child_process`'s `spawn` */
+    readonly spawn?: typeof nodeSpawn;
+    /** @default the real `@jini-ai/agent-runtime` ACP session transport */
+    readonly attachAcpSession?: typeof attachAcpSession;
+    /**
+     * Host-owned policy for ACP agents' native tool calls. The ACP agent still
+     * executes its own selected option; Jini-registered tool execution belongs
+     * to `createDelegatedToolBridge`, not this permission callback.
+     */
+    readonly acpPermissionHandler?: AcpPermissionHandler;
+    /** @default the real `@jini-ai/agent-runtime` pi-rpc session transport */
+    readonly attachPiRpcSession?: typeof attachPiRpcSession;
+    /**
+     * Stages a `promptViaFile` def's (grok-build) composed prompt to a temp
+     * file before `buildArgs` runs. Touches the real filesystem by default
+     * (`fs.mkdtemp`/`fs.writeFile`/`fs.rm`) — injectable so tests can drive
+     * it without real disk I/O, matching this factory's "no real subprocess,
+     * filesystem, or PATH lookup by default in tests" convention.
+     * @default the real `@jini-ai/agent-runtime` prompt-file stager
+     */
+    readonly preparePromptFileForAgent?: typeof preparePromptFileForAgent;
+    /** @default the real `@jini-ai/platform` process-snapshot enumerator */
+    readonly listProcessSnapshots?: typeof listProcessSnapshots;
+    /** @default the real `@jini-ai/platform` descendant-PID collector */
+    readonly collectProcessTreePids?: typeof collectProcessTreePids;
+    /** @default the real `@jini-ai/platform` SIGTERM→SIGKILL escalator */
+    readonly stopProcesses?: typeof stopProcesses;
+    /** Host-owned sink for a process-tree cleanup failure (SEC-007) — e.g. EPERM stopping descendants. @default logs a redacted diagnostic via `console.error` */
+    readonly onCleanupFailure?: (context: AgentCleanupFailureContext) => void;
+    /**
+     * Gap 1's byte-journal (`packages/daemon/src/continuation/journal.ts`) — records every byte
+     * this driver sends to or receives from a child agent process, independent of and prior to any
+     * parsed/translated event. Covers `writePromptToStdin` (sent) and every `child.stdout`/
+     * `child.stderr` `'data'` handler this driver owns (received); does not cover ACP/pi-rpc's own
+     * prompt delivery, which happens inside their respective attach functions' own transport, out
+     * of this driver's direct view — see `WireAcpLifecycleContext.journal`'s doc.
+     * @default no journal — recording is entirely opt-in, unlike every other seam on this
+     * interface (which default to a real implementation): there is no generic "real" journal
+     * storage this package can default to without a caller-supplied `EventLog` instance.
+     */
+    readonly journal?: RunByteJournal;
+    /**
+     * Gap 3's stdin-tool-result injection config — see `ContinuationOptions`'s own doc, especially
+     * on why `autonomousToolNames` (not stream-inferred intent) is this task's answer to the
+     * human-in-the-loop pause question.
+     * @default undefined — every `turn_end` closes stdin unconditionally, byte-identical to
+     * pre-gap-3 behavior. Opt-in only, like `journal`: there is no safe default allowlist of
+     * "tools okay to auto-continue without a human" this package can supply on a caller's behalf.
+     */
+    readonly continuation?: ContinuationOptions;
+    /**
+     * Gap 4's failure classifier — see `ClassifyFailure`'s own doc.
+     * @default undefined — every `'failed'` run stays `resumable: false`, byte-identical to
+     * pre-gap-4 behavior. No default classifier exists: OD's own ~20-vendor-CLI text-matching
+     * failure classifier was deliberately never ported (see this module's own doc), so there is no
+     * generic "real" classification logic this package could supply on a caller's behalf.
+     */
+    readonly classifyFailure?: ClassifyFailure;
+    /**
+     * Gap 3, part 2's spawn-time `.mcp.json` injection — see {@link McpJsonInjectionOptions}'s own
+     * doc for the full design (why only `'claude-mcp-json'`-injection defs, why host-resolved).
+     * @default undefined — no `.mcp.json` is written and no filesystem access beyond what already
+     * happened (prompt-file staging) occurs on this path, byte-identical to pre-this-task behavior.
+     * Opt-in only, like `journal`/`continuation`/`classifyFailure`: there is no safe default
+     * `command`/`daemonUrl` this package could assume on a caller's behalf.
+     */
+    readonly mcpJsonInjection?: McpJsonInjectionOptions;
+}
+/**
+ * Creates the `AgentExecutor` reference implementation: an in-process
+ * `RunLifecycle` driver over real (by default) `@jini-ai/agent-runtime`
+ * registry lookup, launch resolution, and stream parsing, plus a real
+ * `node:child_process.spawn`. Every collaborator is an injectable seam
+ * (matching this package's established convention — see
+ * `tool-executor.ts`/`run-lifecycle.ts`) so tests can drive a fake child
+ * process and a fake registry without touching the filesystem or spawning
+ * a real subprocess.
+ *
+ * @param options.lifecycle - The `RunLifecycle` this executor drives — its `start()` must already have been called for any `runId` passed to `run()`.
+ * @returns An `AgentExecutor` whose `run()` never bare-throws (see module doc's Invariant).
+ * @complexity `run()`'s own setup is O(1); steady-state cost is the chosen stream parser's.
+ * @overallScore 100/100
+ */
+export declare function createAgentExecutor(options: CreateAgentExecutorOptions): AgentExecutor;
+export {};
+//# sourceMappingURL=agent-executor.d.ts.map