@mono-agent/agent-runtime 0.18.0 → 0.18.2

package/src/ai/runtime/router.js

@@ -85,6 +85,9 @@ import { instrumentLiveInputAppliedEvents } from "./live-input-events.js";
  * Returned options are never copied into router telemetry.
  * @property {AgentRuntimeInstance} [runtime]
  * @property {Object<string, *>} [options]
+ * @property {{allowedTools?: ReadonlyArray<string>, disallowedTools?: ReadonlyArray<string>, permissionMode?: string}} [policyOptions]
+ * Provider-specific projection of the logical tool policy. This deliberately
+ * cannot replace any other protected request field.
  * @property {() => (void|Promise<void>)} [cleanup]
  */
 
@@ -243,6 +246,7 @@ export function createRouterRuntime({ host = {}, chain = [], routeSafety = "unif
             attemptCleanup = resolution?.cleanup;
             if (resolveAttempt !== undefined) {
               callOptions = mergeAttemptOptions(callOptions, resolution?.options);
+              callOptions = mergeAttemptPolicyOptions(callOptions, resolution?.policyOptions);
             }
             if (routeSafety === "per-route-native") {
               callOptions = projectPerRouteNativeOptions(entry, callOptions);
@@ -804,6 +808,33 @@ function normalizeAttemptResolution(value) {
   if (value.cleanup !== undefined && typeof value.cleanup !== "function") {
     throw new Error("route attempt resolver cleanup must be a function");
   }
+  return {
+    ...value,
+    ...(value.policyOptions === undefined
+      ? {}
+      : { policyOptions: normalizeAttemptPolicyOptions(value.policyOptions) }),
+  };
+}
+
+const ATTEMPT_POLICY_OPTION_KEYS = new Set(["allowedTools", "disallowedTools", "permissionMode"]);
+
+function normalizeAttemptPolicyOptions(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("route attempt resolver policyOptions must be an object");
+  }
+  for (const key of Object.keys(value)) {
+    if (!ATTEMPT_POLICY_OPTION_KEYS.has(key)) {
+      throw new Error(`route attempt resolver policyOptions cannot override ${key}`);
+    }
+  }
+  for (const key of ["allowedTools", "disallowedTools"]) {
+    if (value[key] !== undefined && !Array.isArray(value[key])) {
+      throw new Error(`route attempt resolver policyOptions.${key} must be an array or undefined`);
+    }
+  }
+  if (value.permissionMode !== undefined && typeof value.permissionMode !== "string") {
+    throw new Error("route attempt resolver policyOptions.permissionMode must be a string or undefined");
+  }
   return value;
 }
 
@@ -826,6 +857,17 @@ function mergeAttemptOptions(base, resolved) {
   return merged;
 }
 
+function mergeAttemptPolicyOptions(base, policyOptions) {
+  if (policyOptions === undefined) return base;
+  const merged = { ...base };
+  for (const key of ATTEMPT_POLICY_OPTION_KEYS) {
+    if (!Object.hasOwn(policyOptions, key)) continue;
+    if (policyOptions[key] === undefined) delete merged[key];
+    else merged[key] = policyOptions[key];
+  }
+  return merged;
+}
+
 /**
  * @param {Object<string, *>} options
  * @returns {Object<string, *>}

package/src/ai/types.js

@@ -40,10 +40,80 @@
  */
 
 /**
- * @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 */
@@ -165,12 +235,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
@@ -182,7 +266,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
@@ -221,11 +305,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.
  */
 
 /**
@@ -281,7 +368,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
@@ -364,6 +453,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]

package/src/runtime.js

@@ -55,6 +55,7 @@ const HOST_KEYS = [
   "resolvePiApiKey",
   "resolveAcpProfile",
   "onAcpInteractionRequest",
+  "acpSessionTokenKey",
   "persistArtifact",
   "onCompactionRecorded",
   "onToolApprovalRequest",

package/types/agent/tools/web-controller.d.ts

@@ -1,6 +1,8 @@
 /**
  * One ephemeral web-tool controller for one model run. It owns in-memory
- * deduplication, result caches, anonymous browser namespaces, and cleanup.
+ * deduplication, the fetch result cache, anonymous browser namespaces, and
+ * cleanup. Search results are the exception: they live in the process-wide
+ * cache above so sibling subagents and later turns can reuse them.
  *
  * @param {{searchConfig?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any}} [options]
  */
@@ -18,3 +20,5 @@ export function createWebToolController({ searchConfig, fetchConfig, sandboxPoli
     fetch(params: any, execution?: {}): Promise<any>;
     close(): Promise<void>;
 };
+/** Test hook: the shared cache is module state and would leak between cases. */
+export function __resetSharedSearchCacheForTests(): void;

package/types/agent/tools/web-search.d.ts

@@ -68,9 +68,22 @@ export function performWebSearch({ query, limit, alternate_queries, domains, exc
         truncated: boolean;
         resultCount: number;
         providerFailureCount: number;
+        rateLimited: boolean;
+        cooldownBackends: string[];
     };
     error: boolean;
 }>;
+/**
+ * Test hook: restores the shipped throttle values and clears cooldown/spacing
+ * state. Module-scoped state would otherwise leak between test cases.
+ *
+ * @param {{maxConcurrency?: number, minSpacingMs?: number, cooldownMs?: number}} [overrides]
+ */
+export function __resetWebSearchThrottleForTests(overrides?: {
+    maxConcurrency?: number;
+    minSpacingMs?: number;
+    cooldownMs?: number;
+}): void;
 export function parseDuckDuckGoResults(html: any): {
     title: string;
     url: string;

package/types/ai/providers/acp-client.d.ts

@@ -214,6 +214,10 @@ export type AcpClientHostOptions = {
     cwd?: string;
     signal?: AbortSignal;
     context?: Record<string, unknown>;
+    /**
+     * Host-owned 32-byte key required by operations that emit or consume opaque session handles.
+     */
+    acpSessionTokenKey?: Uint8Array;
 };
 import { AcpClientError } from "./acp-session-tokens.js";
 import { encodeAcpProviderSessionId } from "./acp-session-tokens.js";

package/types/ai/providers/acp-session-tokens.d.ts

@@ -1,9 +1,15 @@
 /** @param {string} profileId @returns {string} */
 export function validateAcpProfileId(profileId: string): string;
-/** @param {string} profileId @param {string} sessionId */
-export function encodeAcpProviderSessionId(profileId: string, sessionId: string): string;
-/** Internal protocol-state decoder. This module is not a package export. @param {string} providerSessionId */
-export function decodeAcpProviderSessionId(providerSessionId: string): {
+/** @param {unknown} key @returns {Buffer} */
+export function validateAcpSessionTokenKey(key: unknown): Buffer;
+/** @param {string} profileId @param {string} sessionId @param {Uint8Array} key */
+export function encodeAcpProviderSessionId(profileId: string, sessionId: string, key: Uint8Array): string;
+/**
+ * Internal protocol-state decoder. This module is not a package export.
+ * @param {string} providerSessionId
+ * @param {Uint8Array} key
+ */
+export function decodeAcpProviderSessionId(providerSessionId: string, key: Uint8Array): {
     profileId: string;
     sessionId: string;
 };
@@ -13,13 +19,14 @@ export function decodeAcpProviderSessionId(providerSessionId: string): {
  *
  * @param {string} providerSessionId
  * @param {string} expectedProfileId
+ * @param {Uint8Array} key Host-owned 32-byte ACP session-token key.
  * @returns {string}
  */
-export function validateAcpProviderSessionId(providerSessionId: string, expectedProfileId: string): string;
-/** @param {string} profileId @param {string} cursor */
-export function encodeAcpSessionCursor(profileId: string, cursor: string): string;
-/** @param {string} profileId @param {unknown} cursor */
-export function decodeAcpSessionCursor(profileId: string, cursor: unknown): string;
+export function validateAcpProviderSessionId(providerSessionId: string, expectedProfileId: string, key: Uint8Array): string;
+/** @param {string} profileId @param {string} cursor @param {Uint8Array} key */
+export function encodeAcpSessionCursor(profileId: string, cursor: string, key: Uint8Array): string;
+/** @param {string} profileId @param {unknown} cursor @param {Uint8Array} key */
+export function decodeAcpSessionCursor(profileId: string, cursor: unknown, key: Uint8Array): string;
 export class AcpClientError extends Error {
     /**
      * @param {string} code

package/types/ai/providers/acp-transport.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Open one SDK connection inside an async context that strips payload-bearing
+ * SDK console arguments. The SDK starts its detached receive loop during
+ * `connect`, so descendants retain this scope without muting concurrent host
+ * work or other ACP connections.
+ *
+ * @template {{closed: Promise<unknown>}} T
+ * @param {() => T} connect
+ * @returns {T}
+ */
+export function connectWithSafeAcpSdkDiagnostics<T extends {
+    closed: Promise<unknown>;
+}>(connect: () => T): T;
 /**
  * @param {unknown} value
  * @param {number} [fallback]

package/types/ai/providers/claude-subagent-activity.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Correlate Claude's live native-agent stream into provider-neutral
+ * `subagent_activity` events.
+ *
+ * `observe()` returns `consumed: true` for every event owned by a native
+ * subagent. Provider bridges must not additionally forward or interpret those
+ * records as parent events. Non-agent background tasks are consumed without
+ * creating activity.
+ */
+export function createClaudeSubagentActivityNormalizer(): {
+    observe: (raw: Record<string, any>) => {
+        consumed: boolean;
+        events: {
+            type: string;
+            subagent: {
+                label?: any;
+                nativeId?: any;
+                id: any;
+                name: any;
+                callIndex: any;
+            };
+        }[];
+        forwarded?: undefined;
+    } | {
+        consumed: boolean;
+        events: {
+            type: string;
+            subagent: {
+                label?: any;
+                nativeId?: any;
+                id: any;
+                name: any;
+                callIndex: any;
+            };
+        }[];
+        forwarded: {
+            message: any;
+        };
+    };
+    /** Close every still-open child and its tools exactly once. */
+    drain(reason?: string): {
+        type: string;
+        subagent: {
+            label?: any;
+            nativeId?: any;
+            id: any;
+            name: any;
+            callIndex: any;
+        };
+    }[];
+    subagentInvoked: () => boolean;
+    nativeSubagentsUsed: () => any[];
+};

package/types/ai/runtime/router.d.ts

@@ -73,5 +73,14 @@ export type RouterAttemptResolution = {
     options?: {
         [x: string]: any;
     };
+    /**
+     * Provider-specific projection of the logical tool policy. This deliberately
+     * cannot replace any other protected request field.
+     */
+    policyOptions?: {
+        allowedTools?: ReadonlyArray<string>;
+        disallowedTools?: ReadonlyArray<string>;
+        permissionMode?: string;
+    };
     cleanup?: () => (void | Promise<void>);
 };