@mono-agent/agent-runtime 0.18.0 → 0.18.2

package/types/ai/types.d.ts

@@ -20,10 +20,75 @@
  * @property {string} [provider]          Pi/OpenCode provider id when sdk === "pi" | "opencode".
  */
 /**
- * @typedef {{type: string, [key: string]: *}} RuntimeEvent
- * Structured runtime/telemetry event. `type` is the only required field;
- * every event kind (tool_approval_pending, provider_failover_started,
- * context_compaction_applied, ...) adds its own extra fields.
+ * @typedef {Object} RuntimeNativeSubagentDefinition
+ * One caller-defined Claude native `Task` profile. Codex collaboration-agent
+ * definitions are owned by Codex and are not represented by this type.
+ * @property {string} name
+ * @property {string} [displayName]
+ * @property {string} [description]
+ * @property {string} [helperSystemPrompt]
+ * @property {string} [instructions]
+ * @property {ReadonlyArray<string>} [allowedTools]
+ * @property {ReadonlyArray<string>} [disallowedTools]
+ * @property {string | RuntimeModelRef} [modelRef]
+ * @property {RuntimeModelRef} [model]
+ * @property {string} [effort]
+ * @property {Object<string, Object>} [mcpServers]
+ */
+/**
+ * @typedef {Object} RuntimeNativeSubagentsOptions
+ * Caller-defined native profiles are supported only by the Claude bridges.
+ * Codex owns its collaboration agents; use `codexLoadProjectDocs` when those
+ * agents should receive repository instructions.
+ * @property {"claude"} provider
+ * @property {ReadonlyArray<RuntimeNativeSubagentDefinition>} teammates
+ */
+/**
+ * @typedef {Object} RuntimeSubagentIdentity
+ * Provider-neutral identity attached to every `subagent_activity` event.
+ * @property {string} id The canonical parent attachment key: the initiating
+ *   parent tool-use id when the provider exposes it, or a stable synthetic key
+ *   for an orphan lifecycle record. A provider-native task/thread id never replaces it.
+ * @property {string} [nativeId] Provider-native task or thread id, retained only
+ *   as diagnostic/correlation metadata.
+ * @property {string} name Provider-neutral profile/agent name.
+ * @property {number} callIndex Provider call-order ordinal; consumers must not
+ *   use it as an identity key.
+ * @property {string} [label] Short task label or description.
+ * @property {string} [agentPath] Provider-reported ancestry for a
+ *   nested native agent. Informational only; `id` remains the attachment key.
+ * @property {number} [costUsd] Priced delegation cost, when the runtime can
+ *   attribute it to this subagent.
+ */
+/**
+ * @typedef {"agent_started"|"started"|"completed"|"message"|"agent_completed"} RuntimeSubagentActivityPhase
+ * `agent_started`/`agent_completed` bracket the delegation; `started`/`completed`
+ * bracket one child tool call; `message` carries optional child-only prose or
+ * thinking and must never be treated as parent answer text or a completed tool.
+ */
+/**
+ * @typedef {Object} RuntimeSubagentActivityEvent
+ * One normalized native or in-process subagent activity event.
+ * @property {"subagent_activity"} type
+ * @property {RuntimeSubagentIdentity} subagent
+ * @property {RuntimeSubagentActivityPhase} phase
+ * @property {string} id Unique activity-row id, namespaced from the canonical
+ *   `subagent.id` for lifecycle and tool rows.
+ * @property {string} [name]
+ * @property {*} [arguments]
+ * @property {*} [content]
+ * @property {"text"|"thinking"|"status"|"warning"|"error"} [kind] Present on a
+ *   `message` phase when known.
+ * @property {"assistant"|"user"} [role] Present on a `message` phase when known.
+ * @property {boolean} [isError]
+ * @property {number} [executionMs]
+ * @property {number} [totalTokens]
+ */
+/**
+ * @typedef {RuntimeSubagentActivityEvent | {type: string, [key: string]: *}} RuntimeEvent
+ * Structured runtime/telemetry event. Subagent activity uses the normalized
+ * shape above; every other event kind (tool_approval_pending,
+ * provider_failover_started, context_compaction, ...) adds its own fields.
  */
 /** @typedef {"uniform"|"per-route-native"} RuntimeRouteSafetyMode */
 /**
@@ -136,12 +201,26 @@
  * @property {RuntimePromptOverrides} [prompts] Per-run prompt-fragment overrides (run wins over the host default).
  * @property {import('./providers/acp-client.js').AcpClientHostOptions["resolveAcpProfile"]} [resolveAcpProfile] Per-run ACP profile resolver; wins over the host default.
  * @property {import('./providers/acp-client.js').AcpClientHostOptions["onAcpInteractionRequest"]} [onAcpInteractionRequest] Per-run ACP permission/elicitation callback; wins over the host default.
+ * @property {Uint8Array} [acpSessionTokenKey] Host-owned 32-byte key for confidential authenticated ACP session handles. Required for every ACP task run.
  * @property {{backend?: "auto"|"searxng"|"keyless", endpoint?: string}} [webSearchConfig] Run-scoped WebSearch backend configuration.
  * @property {{render?: "never"|"auto", browserCommand?: string}} [webFetchConfig] Run-scoped WebFetch extraction/render configuration.
  * @property {"sequential"|"safe-parallel"} [piToolExecutionMode] Pi built-in tool scheduling mode. Safe parallelism is the default.
  * @property {"one-at-a-time"|"all"} [piToolParallelismMode] DEPRECATED. Compatibility alias mapped to piToolExecutionMode.
  * @property {Object} [settings] DEPRECATED. Legacy flat settings bag; consumed only as a per-group FALLBACK when the corresponding typed object (`toolLimits` / `compaction`) is absent. Consuming any key emits one `deprecated_settings_option` runtime_warning per run. Migrate via resolveRuntimePolicies (@mono-agent/runtime-adapter).
- * @property {Object} [nativeSubagents] Same-runtime teammate helpers exposed through native provider subagent surfaces.
+ * @property {ReadonlyArray<"user" | "project" | "local">} [settingSources] Claude Agent SDK only. Filesystem
+ *   settings the SDK may load for this run. Omitted/empty disables user, project, and local sources, including their
+ *   CLAUDE.md, hooks, plugins, and on-disk agent profiles. Anthropic managed settings remain in force and may still
+ *   configure hooks or plugins; this option is not a managed-policy bypass. Each opted-in source may execute configured
+ *   hooks and plugins, so enable only trusted settings and avoid these sources in an untrusted checkout. Include
+ *   `"project"`/`"user"` to let the native `Task` tool discover `.claude/agents` definitions. Unrecognized entries are
+ *   dropped. The Claude Code CLI bridge does not take this option: that binary performs its own settings discovery and
+ *   mono-agent passes no `--setting-sources`, so a CLI run already reads the host config regardless of this value.
+ * @property {boolean} [codexLoadProjectDocs] Codex app-server only. Omitted/false starts the managed app-server with
+ *   `project_doc_max_bytes=0`, preventing automatic repository-instruction discovery. True restores Codex's native
+ *   project-doc loading defaults. An explicit `codexAppServerArgs` array wins over this convenience option.
+ * @property {RuntimeNativeSubagentsOptions} [nativeSubagents] Caller-defined Claude native `Task` profiles. Direct
+ *   Codex owns its collaboration agents and rejects configured teammate definitions; `codexLoadProjectDocs` controls
+ *   whether Codex loads repository instructions for its own agents.
  * @property {RuntimeSubagentsOptions} [subagents] In-process `Agent` built-in: profiles, caps, and the nested-run callback.
  * @property {Object} [diagnosticsSeed] Set by createRouterRuntime (ai/runtime/router.js) with a `resume_snapshot` when
  *   failing over mid-chain; a host-level coordinator may relay it forward (see agent/transcript.js), not read by any
@@ -152,7 +231,7 @@
  */
 /**
  * @typedef {RuntimeRunOptions
- *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools">
+ *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "acpSessionTokenKey" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools">
  *   & {runtimeBrand: import('../runtime-brand.js').RuntimeBrand, toolContext?: import('../agent/tools/shared/tool-context.js').ToolContext, observerHub: {emit: (event: RuntimeEvent) => void, flush: () => Promise<void>}}
  * } RuntimeRequest
  * The request shape a bridge's `execute(systemPrompt, req)` receives as its
@@ -188,11 +267,14 @@
  */
 /**
  * @typedef {Object} RuntimeInlineSubagentsOptions
- * Policy for subagents the model authors at call time rather than picking from
- * `definitions`. Absent suppresses authoring entirely.
+ * Policy for the runtime-owned general-purpose helper and subagents the model
+ * authors at call time rather than picking from `definitions`. Absent
+ * suppresses authoring entirely and leaves general-purpose on its safe default.
  * @property {boolean} [enabled] Only `false` turns authoring off.
- * @property {ReadonlyArray<string>} [allowedTools] Ceiling on what an authored subagent may
- *   request. Absent means the safe read-only default set, never every built-in.
+ * @property {ReadonlyArray<string>} [allowedTools] Ceiling on general-purpose's
+ *   read-only tools and what an authored subagent may request. Configured
+ *   definitions keep their explicit contracts. Absent means the safe read-only
+ *   default set, never every built-in.
  */
 /**
  * @typedef {Object} RuntimeSubagentsOptions
@@ -245,7 +327,9 @@
  * @property {boolean} [supports_skills]
  * @property {boolean} [supports_builtin_tools]
  * @property {boolean} [supports_live_input]
- * @property {boolean} [supports_native_subagents]
+ * @property {boolean} [supports_native_subagents] Whether the bridge exposes provider-native subagent surfaces and
+ *   normalized activity. This does not imply it accepts caller-defined `nativeSubagents`: Codex owns its collaboration
+ *   agents, while only the Claude bridges project caller-defined profiles.
  * @property {boolean} [supports_request_tool_environment]
  * @property {boolean} [supports_fast_mode]
  * @property {"projected"|"allow_all_only"} [tool_policy] Whether the bridge can
@@ -322,6 +406,7 @@
  * @property {import('../pi-auth.js').PiApiKeyResolver} [resolvePiApiKey] See createPiOAuthApiKeyResolver (pi-auth.js) for a ready-made implementation.
  * @property {import('./providers/acp-client.js').AcpClientHostOptions["resolveAcpProfile"]} [resolveAcpProfile] Default ACP profile resolver; a per-run callback wins.
  * @property {import('./providers/acp-client.js').AcpClientHostOptions["onAcpInteractionRequest"]} [onAcpInteractionRequest] Default ACP interaction callback; a per-run callback wins.
+ * @property {Uint8Array} [acpSessionTokenKey] Default host-owned 32-byte key for confidential authenticated ACP session handles.
  * @property {(artifact: {filename: string, buffer: Buffer, toolName: string, toolUseId: (string|null)}) => (string|null)} [persistArtifact]
  * @property {(record: CompactionRecordedPayload) => void} [onCompactionRecorded]
  * @property {(payload: ApprovalRequestPayload) => Promise<ApprovalDecision>} [onToolApprovalRequest]
@@ -388,11 +473,112 @@ export type RuntimeModelRef = {
     provider?: string;
 };
 /**
- * Structured runtime/telemetry event. `type` is the only required field;
- * every event kind (tool_approval_pending, provider_failover_started,
- * context_compaction_applied, ...) adds its own extra fields.
+ * One caller-defined Claude native `Task` profile. Codex collaboration-agent
+ * definitions are owned by Codex and are not represented by this type.
+ */
+export type RuntimeNativeSubagentDefinition = {
+    name: string;
+    displayName?: string;
+    description?: string;
+    helperSystemPrompt?: string;
+    instructions?: string;
+    allowedTools?: ReadonlyArray<string>;
+    disallowedTools?: ReadonlyArray<string>;
+    modelRef?: string | RuntimeModelRef;
+    model?: RuntimeModelRef;
+    effort?: string;
+    mcpServers?: {
+        [x: string]: any;
+    };
+};
+/**
+ * Caller-defined native profiles are supported only by the Claude bridges.
+ * Codex owns its collaboration agents; use `codexLoadProjectDocs` when those
+ * agents should receive repository instructions.
  */
-export type RuntimeEvent = {
+export type RuntimeNativeSubagentsOptions = {
+    provider: "claude";
+    teammates: ReadonlyArray<RuntimeNativeSubagentDefinition>;
+};
+/**
+ * Provider-neutral identity attached to every `subagent_activity` event.
+ */
+export type RuntimeSubagentIdentity = {
+    /**
+     * The canonical parent attachment key: the initiating
+     * parent tool-use id when the provider exposes it, or a stable synthetic key
+     * for an orphan lifecycle record. A provider-native task/thread id never replaces it.
+     */
+    id: string;
+    /**
+     * Provider-native task or thread id, retained only
+     * as diagnostic/correlation metadata.
+     */
+    nativeId?: string;
+    /**
+     * Provider-neutral profile/agent name.
+     */
+    name: string;
+    /**
+     * Provider call-order ordinal; consumers must not
+     * use it as an identity key.
+     */
+    callIndex: number;
+    /**
+     * Short task label or description.
+     */
+    label?: string;
+    /**
+     * Provider-reported ancestry for a
+     * nested native agent. Informational only; `id` remains the attachment key.
+     */
+    agentPath?: string;
+    /**
+     * Priced delegation cost, when the runtime can
+     * attribute it to this subagent.
+     */
+    costUsd?: number;
+};
+/**
+ * `agent_started`/`agent_completed` bracket the delegation; `started`/`completed`
+ * bracket one child tool call; `message` carries optional child-only prose or
+ * thinking and must never be treated as parent answer text or a completed tool.
+ */
+export type RuntimeSubagentActivityPhase = "agent_started" | "started" | "completed" | "message" | "agent_completed";
+/**
+ * One normalized native or in-process subagent activity event.
+ */
+export type RuntimeSubagentActivityEvent = {
+    type: "subagent_activity";
+    subagent: RuntimeSubagentIdentity;
+    phase: RuntimeSubagentActivityPhase;
+    /**
+     * Unique activity-row id, namespaced from the canonical
+     * `subagent.id` for lifecycle and tool rows.
+     */
+    id: string;
+    name?: string;
+    arguments?: any;
+    content?: any;
+    /**
+     * Present on a
+     * `message` phase when known.
+     */
+    kind?: "text" | "thinking" | "status" | "warning" | "error";
+    /**
+     * Present on a `message` phase when known.
+     */
+    role?: "assistant" | "user";
+    isError?: boolean;
+    executionMs?: number;
+    totalTokens?: number;
+};
+/**
+ * Structured runtime/telemetry event. Subagent activity uses the normalized
+ * shape above; every other event kind (tool_approval_pending,
+ * provider_failover_started, context_compaction, ...) adds its own fields.
+ */
+export type RuntimeEvent = RuntimeSubagentActivityEvent | {
     type: string;
     [key: string]: any;
 };
@@ -642,6 +828,10 @@ export type RuntimeRunOptions = {
      * Per-run ACP permission/elicitation callback; wins over the host default.
      */
     onAcpInteractionRequest?: import("./providers/acp-client.js").AcpClientHostOptions["onAcpInteractionRequest"];
+    /**
+     * Host-owned 32-byte key for confidential authenticated ACP session handles. Required for every ACP task run.
+     */
+    acpSessionTokenKey?: Uint8Array;
     /**
      * Run-scoped WebSearch backend configuration.
      */
@@ -669,9 +859,28 @@ export type RuntimeRunOptions = {
      */
     settings?: any;
     /**
-     * Same-runtime teammate helpers exposed through native provider subagent surfaces.
+     * Claude Agent SDK only. Filesystem
+     * settings the SDK may load for this run. Omitted/empty disables user, project, and local sources, including their
+     * CLAUDE.md, hooks, plugins, and on-disk agent profiles. Anthropic managed settings remain in force and may still
+     * configure hooks or plugins; this option is not a managed-policy bypass. Each opted-in source may execute configured
+     * hooks and plugins, so enable only trusted settings and avoid these sources in an untrusted checkout. Include
+     * `"project"`/`"user"` to let the native `Task` tool discover `.claude/agents` definitions. Unrecognized entries are
+     * dropped. The Claude Code CLI bridge does not take this option: that binary performs its own settings discovery and
+     * mono-agent passes no `--setting-sources`, so a CLI run already reads the host config regardless of this value.
      */
-    nativeSubagents?: any;
+    settingSources?: ReadonlyArray<"user" | "project" | "local">;
+    /**
+     * Codex app-server only. Omitted/false starts the managed app-server with
+     * `project_doc_max_bytes=0`, preventing automatic repository-instruction discovery. True restores Codex's native
+     * project-doc loading defaults. An explicit `codexAppServerArgs` array wins over this convenience option.
+     */
+    codexLoadProjectDocs?: boolean;
+    /**
+     * Caller-defined Claude native `Task` profiles. Direct
+     * Codex owns its collaboration agents and rejects configured teammate definitions; `codexLoadProjectDocs` controls
+     * whether Codex loads repository instructions for its own agents.
+     */
+    nativeSubagents?: RuntimeNativeSubagentsOptions;
     /**
      * In-process `Agent` built-in: profiles, caps, and the nested-run callback.
      */
@@ -698,7 +907,7 @@ export type RuntimeRunOptions = {
  * createRuntime), and the per-run observerHub (onEvent is overridden to the
  * hub's emit). `systemPrompt` is passed positionally, not folded into this object.
  */
-export type RuntimeRequest = RuntimeRunOptions & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools"> & {
+export type RuntimeRequest = RuntimeRunOptions & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "acpSessionTokenKey" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools"> & {
     runtimeBrand: import("../runtime-brand.js").RuntimeBrand;
     toolContext?: import("../agent/tools/shared/tool-context.js").ToolContext;
     observerHub: {
@@ -746,8 +955,9 @@ export type RuntimeSubagentDefinition = {
  */
 export type RuntimeSubagentRun = (request: any) => Promise<RuntimeResult>;
 /**
- * Policy for subagents the model authors at call time rather than picking from
- * `definitions`. Absent suppresses authoring entirely.
+ * Policy for the runtime-owned general-purpose helper and subagents the model
+ * authors at call time rather than picking from `definitions`. Absent
+ * suppresses authoring entirely and leaves general-purpose on its safe default.
  */
 export type RuntimeInlineSubagentsOptions = {
     /**
@@ -755,8 +965,10 @@ export type RuntimeInlineSubagentsOptions = {
      */
     enabled?: boolean;
     /**
-     * Ceiling on what an authored subagent may
-     * request. Absent means the safe read-only default set, never every built-in.
+     * Ceiling on general-purpose's
+     * read-only tools and what an authored subagent may request. Configured
+     * definitions keep their explicit contracts. Absent means the safe read-only
+     * default set, never every built-in.
      */
     allowedTools?: ReadonlyArray<string>;
 };
@@ -858,6 +1070,11 @@ export type RuntimeCapabilities = {
     supports_skills?: boolean;
     supports_builtin_tools?: boolean;
     supports_live_input?: boolean;
+    /**
+     * Whether the bridge exposes provider-native subagent surfaces and
+     * normalized activity. This does not imply it accepts caller-defined `nativeSubagents`: Codex owns its collaboration
+     * agents, while only the Claude bridges project caller-defined profiles.
+     */
     supports_native_subagents?: boolean;
     supports_request_tool_environment?: boolean;
     supports_fast_mode?: boolean;
@@ -975,6 +1192,10 @@ export type AgentRuntimeHostOptions = {
      * Default ACP interaction callback; a per-run callback wins.
      */
     onAcpInteractionRequest?: import("./providers/acp-client.js").AcpClientHostOptions["onAcpInteractionRequest"];
+    /**
+     * Default host-owned 32-byte key for confidential authenticated ACP session handles.
+     */
+    acpSessionTokenKey?: Uint8Array;
     persistArtifact?: (artifact: {
         filename: string;
         buffer: Buffer;