@mono-agent/agent-runtime 0.19.0 → 0.20.0

package/types/ai/streaming/opencode-events.d.ts

@@ -17,6 +17,7 @@ export function toolResultEvent(part: any): {
             tool_use_id: any;
             content: any;
             is_error: boolean;
+            tool_lifecycle: any;
         }[];
     };
 };

package/types/ai/tool-lifecycle.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @param {{sink?: (event: any) => Promise<any>, onObserve?: (event: any) => void, onEvent?: (event: any) => void, abortSignal?: AbortSignal}} options
+ */
+export function createToolLifecycleEventGate({ sink, onObserve, onEvent, abortSignal }: {
+    sink?: (event: any) => Promise<any>;
+    onObserve?: (event: any) => void;
+    onEvent?: (event: any) => void;
+    abortSignal?: AbortSignal;
+}): {
+    emit: (event: any) => void;
+    flush(): Promise<void>;
+};
+/**
+ * Pi-native exact classifier. It consumes structured tool result details, not
+ * error text, so timeout/signal/non-zero/cancellation fidelity cannot drift
+ * with provider wording.
+ * @param {{result?: any,isError?: boolean,aborted?: boolean,approval?: any}} input
+ */
+export function classifyPiToolResult(input: {
+    result?: any;
+    isError?: boolean;
+    aborted?: boolean;
+    approval?: any;
+}): {
+    detailCode?: string;
+    failureKind?: string;
+    state: string;
+};
+/** @param {any} persisted @param {string|undefined} terminalStateValue */
+export function historyMetadata(persisted: any, terminalStateValue: string | undefined): {
+    untrusted: boolean;
+    errorCode?: any;
+    artifactReferences?: any;
+    retainedBytes?: number;
+    originalBytes?: number;
+    truncated?: any;
+    terminalState?: string;
+    persistence: string;
+    sequence?: number;
+    recordId?: any;
+};
+/** Mark a provider adapter's host-derived structured outcome as trusted input to the gate. @param {any} value */
+export function toolLifecycleMetadata(value: any): any;

package/types/ai/types.d.ts

@@ -34,6 +34,7 @@
  * @property {RuntimeModelRef} [model]
  * @property {string} [effort]
  * @property {Object<string, Object>} [mcpServers]
+ * @property {Object} [mcpApps] App-owned exact-connection MCP Apps registry (Pi-native only).
  */
 /**
  * @typedef {Object} RuntimeNativeSubagentsOptions
@@ -90,6 +91,49 @@
  * shape above; every other event kind (tool_approval_pending,
  * provider_failover_started, context_compaction, ...) adds its own fields.
  */
+/** @typedef {"success"|"rejected"|"error"|"exit_nonzero"|"timeout"|"signal"|"cancelled"|"interrupted"} RuntimeToolLifecycleTerminalState */
+/**
+ * @typedef {Readonly<{
+ *   phase: "invocation",
+ *   toolCallId: string,
+ *   toolName: string,
+ *   arguments?: unknown,
+ * }>} RuntimeToolLifecycleInvocationEvent
+ * Provider-neutral invocation half sent to the host-owned lifecycle sink.
+ */
+/**
+ * @typedef {Readonly<{
+ *   phase: "result",
+ *   toolCallId: string,
+ *   toolName?: string,
+ *   content?: unknown,
+ *   state: RuntimeToolLifecycleTerminalState,
+ *   failureKind?: string,
+ *   detailCode?: string,
+ *   executionMs?: number,
+ *   artifacts?: ReadonlyArray<Readonly<{path: string, available?: boolean}>>,
+ * }>} RuntimeToolLifecycleResultEvent
+ * Provider-neutral terminal half sent to the host-owned lifecycle sink.
+ */
+/** @typedef {RuntimeToolLifecycleInvocationEvent | RuntimeToolLifecycleResultEvent} RuntimeToolLifecycleEvent */
+/**
+ * @typedef {Readonly<{
+ *   recordId?: string,
+ *   sequence?: number,
+ *   persistence: "persisted"|"failed",
+ *   truncated?: boolean,
+ *   originalBytes?: number,
+ *   retainedBytes?: number,
+ *   artifactReferences?: ReadonlyArray<Readonly<{id: string, available: boolean}>>,
+ *   errorCode?: string,
+ * }>} RuntimeToolLifecyclePersistence
+ * Bounded metadata returned after one lifecycle half becomes durable.
+ */
+/**
+ * @callback RuntimeToolLifecycleSink
+ * @param {RuntimeToolLifecycleEvent} event
+ * @returns {Promise<RuntimeToolLifecyclePersistence|undefined>}
+ */
 /** @typedef {"uniform"|"per-route-native"} RuntimeRouteSafetyMode */
 /**
  * @typedef {"mono-agent-monotonic"|"disabled"|"mono-agent-srt"|"mono-agent-srt-unsafe-host-fallback"|"provider-native"|"codex-native"|"unsupported"} RuntimeRouteSandboxContract
@@ -178,6 +222,7 @@
  * @property {AsyncIterable<{body: string, id?: string, receivedAt?: string, acknowledge?: () => void, reject?: (error?: unknown) => void}>} [liveInput] Stream of in-flight user messages for steering an active run. Providers acknowledge only after accepting a message into the active turn.
  * @property {ReadonlyArray<*>} [observers]               Per-call observers (see RuntimeObserver) merged with host-level (createRuntime) observers.
  * @property {(event: RuntimeEvent) => void} [onEvent]
+ * @property {RuntimeToolLifecycleSink} [toolLifecycleSink] Awaited host-owned incremental lifecycle persistence boundary.
  * @property {ReadonlyArray<Object>} [messages]
  * @property {string} [effort]
  * @property {boolean} [fastMode]
@@ -218,10 +263,17 @@
  * @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 {boolean} [codexSandboxNetworkAccess] Codex app-server only, code-only. Strict `true` enables native
+ *   network access for plan/read-only and default/acceptEdits/workspace-write turns; omitted or any other runtime
+ *   value denies it. No-tool probes always deny network access, and bypass/danger-full-access remains unchanged. This
+ *   is unrelated to `RuntimeRunOptions.sandboxPolicy`, which controls mono-agent's own sandbox and is not consumed by
+ *   Codex's provider-owned tool loop. Default/acceptEdits workspace-write plus network true grants repository read and
+ *   network egress in the same turn; prefer plan when only read-only browsing is needed.
  * @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 {import('../agent/tools/shared/process-jobs.js').ProcessJobsController} [processJobs] Pi-native-only structural process-job controller. When absent, Exec/Bash schemas and foreground behavior are unchanged.
  * @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
  *   bridge in this package today.
@@ -490,6 +542,10 @@ export type RuntimeNativeSubagentDefinition = {
     mcpServers?: {
         [x: string]: any;
     };
+    /**
+     * App-owned exact-connection MCP Apps registry (Pi-native only).
+     */
+    mcpApps?: any;
 };
 /**
  * Caller-defined native profiles are supported only by the Claude bridges.
@@ -582,6 +638,51 @@ export type RuntimeEvent = RuntimeSubagentActivityEvent | {
     type: string;
     [key: string]: any;
 };
+export type RuntimeToolLifecycleTerminalState = "success" | "rejected" | "error" | "exit_nonzero" | "timeout" | "signal" | "cancelled" | "interrupted";
+/**
+ * Provider-neutral invocation half sent to the host-owned lifecycle sink.
+ */
+export type RuntimeToolLifecycleInvocationEvent = Readonly<{
+    phase: "invocation";
+    toolCallId: string;
+    toolName: string;
+    arguments?: unknown;
+}>;
+/**
+ * Provider-neutral terminal half sent to the host-owned lifecycle sink.
+ */
+export type RuntimeToolLifecycleResultEvent = Readonly<{
+    phase: "result";
+    toolCallId: string;
+    toolName?: string;
+    content?: unknown;
+    state: RuntimeToolLifecycleTerminalState;
+    failureKind?: string;
+    detailCode?: string;
+    executionMs?: number;
+    artifacts?: ReadonlyArray<Readonly<{
+        path: string;
+        available?: boolean;
+    }>>;
+}>;
+export type RuntimeToolLifecycleEvent = RuntimeToolLifecycleInvocationEvent | RuntimeToolLifecycleResultEvent;
+/**
+ * Bounded metadata returned after one lifecycle half becomes durable.
+ */
+export type RuntimeToolLifecyclePersistence = Readonly<{
+    recordId?: string;
+    sequence?: number;
+    persistence: "persisted" | "failed";
+    truncated?: boolean;
+    originalBytes?: number;
+    retainedBytes?: number;
+    artifactReferences?: ReadonlyArray<Readonly<{
+        id: string;
+        available: boolean;
+    }>>;
+    errorCode?: string;
+}>;
+export type RuntimeToolLifecycleSink = (event: RuntimeToolLifecycleEvent) => Promise<RuntimeToolLifecyclePersistence | undefined>;
 export type RuntimeRouteSafetyMode = "uniform" | "per-route-native";
 /**
  * Fixed telemetry vocabulary for a route's sandbox posture. The
@@ -763,6 +864,10 @@ export type RuntimeRunOptions = {
      */
     observers?: ReadonlyArray<any>;
     onEvent?: (event: RuntimeEvent) => void;
+    /**
+     * Awaited host-owned incremental lifecycle persistence boundary.
+     */
+    toolLifecycleSink?: RuntimeToolLifecycleSink;
     messages?: ReadonlyArray<any>;
     effort?: string;
     fastMode?: boolean;
@@ -875,6 +980,15 @@ export type RuntimeRunOptions = {
      * project-doc loading defaults. An explicit `codexAppServerArgs` array wins over this convenience option.
      */
     codexLoadProjectDocs?: boolean;
+    /**
+     * Codex app-server only, code-only. Strict `true` enables native
+     * network access for plan/read-only and default/acceptEdits/workspace-write turns; omitted or any other runtime
+     * value denies it. No-tool probes always deny network access, and bypass/danger-full-access remains unchanged. This
+     * is unrelated to `RuntimeRunOptions.sandboxPolicy`, which controls mono-agent's own sandbox and is not consumed by
+     * Codex's provider-owned tool loop. Default/acceptEdits workspace-write plus network true grants repository read and
+     * network egress in the same turn; prefer plan when only read-only browsing is needed.
+     */
+    codexSandboxNetworkAccess?: boolean;
     /**
      * Caller-defined Claude native `Task` profiles. Direct
      * Codex owns its collaboration agents and rejects configured teammate definitions; `codexLoadProjectDocs` controls
@@ -885,6 +999,10 @@ export type RuntimeRunOptions = {
      * In-process `Agent` built-in: profiles, caps, and the nested-run callback.
      */
     subagents?: RuntimeSubagentsOptions;
+    /**
+     * Pi-native-only structural process-job controller. When absent, Exec/Bash schemas and foreground behavior are unchanged.
+     */
+    processJobs?: import("../agent/tools/shared/process-jobs.js").ProcessJobsController;
     /**
      * 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