@mono-agent/agent-runtime 0.19.0 → 0.20.0

package/src/runtime.js

@@ -41,6 +41,7 @@ import { createToolContext, updateToolContext } from "./agent/tools/shared/tool-
 import { resolveRuntimeBrand } from "./runtime-brand.js";
 import { retireDurableNativeSession } from "./ai/providers/pi-native/session-lifecycle.js";
 import { instrumentLiveInputAppliedEvents } from "./ai/runtime/live-input-events.js";
+import { createToolLifecycleEventGate } from "./ai/tool-lifecycle.js";
 
 /**
  * @typedef {import('./ai/types.js').AgentRuntimeHostOptions} AgentRuntimeHostOptions
@@ -210,9 +211,16 @@ export function createRuntime(host = {}) {
       const callObservers = Array.isArray(options.observers) ? options.observers : [];
       const hub = createObserverHub({
         observers: [...hostObservers, ...callObservers],
+      });
+      const lifecycleGate = createToolLifecycleEventGate({
+        sink: options.toolLifecycleSink,
+        // Observer delivery keeps the runtime's synchronous contract. Only the
+        // client-facing lifecycle event waits for its serialized persistence.
+        onObserve: (event) => hub.emit(event),
         onEvent: options.onEvent,
+        abortSignal: options.abortSignal,
       });
-      const liveInput = instrumentLiveInputAppliedEvents(options.liveInput, hub.emit);
+      const liveInput = instrumentLiveInputAppliedEvents(options.liveInput, lifecycleGate.emit);
       const prompts = resolvePrompts(host.prompts, options.prompts);
       // A request-scoped environment must never mutate the long-lived runtime's
       // shared ToolContext. Clone only for this call, preserving configureTools
@@ -226,26 +234,32 @@ export function createRuntime(host = {}) {
       const subagents = options.subagents === undefined
         ? undefined
         : { ...options.subagents, run: options.subagents.run ?? defaultSubagentRun };
-      const result = await bridge.execute(systemPrompt, {
-        ...hostDefaults,
-        ...options,
-        ...(subagents === undefined ? {} : { subagents }),
-        // `...options` alone doesn't carry the `options.model` narrowing above
-        // (spread reads the parameter's declared — Partial — type); re-assert
-        // the already-validated model so the request satisfies RuntimeRequest.
-        model: options.model,
-        executionMode,
-        runtimeBrand,
-        toolContext: runToolContext,
-        observerHub: hub,
-        onEvent: hub.emit,
-        ...(liveInput === undefined ? {} : { liveInput }),
-        // Merged AFTER the spreads so the per-field run>host>default precedence
-        // wins over either bag's whole-object `prompts`.
-        ...(prompts === undefined ? {} : { prompts }),
-      });
-      await hub.flush();
-      return result;
+      try {
+        return await bridge.execute(systemPrompt, {
+          ...hostDefaults,
+          ...options,
+          ...(subagents === undefined ? {} : { subagents }),
+          // `...options` alone doesn't carry the `options.model` narrowing above
+          // (spread reads the parameter's declared — Partial — type); re-assert
+          // the already-validated model so the request satisfies RuntimeRequest.
+          model: options.model,
+          executionMode,
+          runtimeBrand,
+          toolContext: runToolContext,
+          observerHub: hub,
+          onEvent: lifecycleGate.emit,
+          // The host gate is the sole persistence owner. Provider subscribe
+          // callbacks are synchronous and must never await the storage sink.
+          toolLifecycleSink: undefined,
+          ...(liveInput === undefined ? {} : { liveInput }),
+          // Merged AFTER the spreads so the per-field run>host>default precedence
+          // wins over either bag's whole-object `prompts`.
+          ...(prompts === undefined ? {} : { prompts }),
+        });
+      } finally {
+        await lifecycleGate.flush();
+        await hub.flush();
+      }
     },
     configureTools(next = {}) {
       updateToolContext(toolContext, pickPresent(next, TOOL_RUNTIME_KEYS));

package/types/agent/sandbox-seam.d.ts

@@ -4,16 +4,20 @@ export type SandboxCommandSpec = {
     command: string;
     args?: ReadonlyArray<string>;
     cwd?: string;
-    env?: {
-        [x: string]: string;
-    };
+    env?: Record<string, string | undefined>;
     /**
      * Trusted per-command capability.
      */
     allowLocalBinding?: boolean;
 };
-export type PreparedSandboxCommand = SandboxCommandSpec & {
+export type PreparedSandboxCommand = {
+    command: string;
+    args: ReadonlyArray<string>;
+    cwd: string;
+    env?: Record<string, string | undefined>;
+    allowLocalBinding?: boolean;
     sandboxed: boolean;
+    sandboxSettingsPath?: string;
     cleanup?: () => Promise<void>;
 };
 export type SandboxNetworkPolicyLike = {
@@ -88,11 +92,19 @@ export class SandboxUnavailableError extends Error {
  * @property {string} command
  * @property {ReadonlyArray<string>} [args]
  * @property {string} [cwd]
- * @property {Object<string, string|undefined>} [env]
+ * @property {Record<string, string|undefined>} [env]
  * @property {boolean} [allowLocalBinding] Trusted per-command capability.
  */
 /**
- * @typedef {SandboxCommandSpec & {sandboxed: boolean, cleanup?: () => Promise<void>}} PreparedSandboxCommand
+ * @typedef {Object} PreparedSandboxCommand
+ * @property {string} command
+ * @property {ReadonlyArray<string>} args
+ * @property {string} cwd
+ * @property {Record<string, string|undefined>} [env]
+ * @property {boolean} [allowLocalBinding]
+ * @property {boolean} sandboxed
+ * @property {string} [sandboxSettingsPath]
+ * @property {() => Promise<void>} [cleanup]
  */
 /**
  * @typedef {Object} SandboxNetworkPolicyLike
@@ -114,6 +126,7 @@ export class SandboxUnavailableError extends Error {
  * @property {SandboxNetworkPolicyLike} [network]
  * @property {ReadonlyArray<string>} [readableRoots]
  * @property {ReadonlyArray<string>} [writableRoots]
+ * @property {ReadonlyArray<string>} [protectedRoots] Host-internal roots denied for both reads and writes.
  * @property {ReadonlyArray<string>} [denyWrite]
  * @property {string} [root]
  */

package/types/agent/tools/bash.d.ts

@@ -10,8 +10,8 @@ export function normalizeProcessTimeoutMs(value: any, fallback?: number): any;
 /**
  * Compatibility wrapper retained for direct callers and tests.
  *
- * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
 export function bashToolImpl(params: {
     command: string;
@@ -19,46 +19,31 @@ export function bashToolImpl(params: {
     timeout_ms?: number;
     max_output_chars?: number;
     workdir?: string;
+    background?: boolean;
 }, options?: {
     signal?: AbortSignal;
     sandboxPolicy?: any;
     sandboxEngine?: any;
     ctx?: any;
+    processJobsController?: import("./shared/process-jobs.js").ProcessJobsController;
 }): Promise<any>;
 /**
  * Structured Bash execution used by the Pi bridge.
  *
- * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
-export function bashToolRun({ command, timeout, timeout_ms, max_output_chars, workdir, }: {
+export function bashToolRun({ command, timeout, timeout_ms, max_output_chars, workdir, background, }: {
     command: string;
     timeout?: number;
     timeout_ms?: number;
     max_output_chars?: number;
     workdir?: string;
-}, { signal, sandboxPolicy, sandboxEngine, ctx, }?: {
+    background?: boolean;
+}, { signal, sandboxPolicy, sandboxEngine, ctx, processJobsController, }?: {
     signal?: AbortSignal;
     sandboxPolicy?: any;
     sandboxEngine?: any;
     ctx?: any;
-}): Promise<{
-    text: any;
-    outcome: {
-        status: string;
-        code: any;
-        retryable: boolean;
-        attempts: number;
-        durationMs: number;
-        bytes: number;
-        truncated: boolean;
-        exitCode: any;
-        signal: any;
-        timedOut: boolean;
-    };
-    error: boolean;
-} | {
-    text: string;
-    outcome: any;
-    error: boolean;
-}>;
+    processJobsController?: import("./shared/process-jobs.js").ProcessJobsController;
+}): Promise<any>;

package/types/agent/tools/edit.d.ts

@@ -1,6 +1,6 @@
 /**
  * @param {{file_path: string, old_string: string, new_string: string, replace_all?: boolean, workdir?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
  */
 export function editToolImpl({ file_path, old_string, new_string, replace_all, workdir }: {
     file_path: string;
@@ -8,7 +8,8 @@ export function editToolImpl({ file_path, old_string, new_string, replace_all, w
     new_string: string;
     replace_all?: boolean;
     workdir?: string;
-}, { sandboxPolicy, ctx }?: {
+}, { sandboxPolicy, sandboxEngine, ctx }?: {
     sandboxPolicy?: any;
+    sandboxEngine?: any;
     ctx?: any;
 }): Promise<string>;

package/types/agent/tools/exec.d.ts

@@ -1,6 +1,7 @@
+/** @typedef {import("./shared/process-jobs.js").ProcessJobsController} ProcessJobsController */
 /**
- * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number}} params
- * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
 export function execToolImpl(params: {
     executable: string;
@@ -8,46 +9,32 @@ export function execToolImpl(params: {
     workdir?: string;
     timeout_ms?: number;
     max_output_chars?: number;
+    background?: boolean;
 }, options?: {
     signal?: AbortSignal;
     sandboxPolicy?: any;
     sandboxEngine?: any;
     ctx?: any;
+    processJobsController?: ProcessJobsController;
 }): Promise<any>;
 /**
  * Execute an argv vector directly, without shell parsing.
  *
- * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number}} params
- * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
-export function execToolRun({ executable, args, workdir, timeout_ms, max_output_chars, }: {
+export function execToolRun({ executable, args, workdir, timeout_ms, max_output_chars, background, }: {
     executable: string;
     args?: string[];
     workdir?: string;
     timeout_ms?: number;
     max_output_chars?: number;
-}, { signal, sandboxPolicy, sandboxEngine, ctx, }?: {
+    background?: boolean;
+}, { signal, sandboxPolicy, sandboxEngine, ctx, processJobsController, }?: {
     signal?: AbortSignal;
     sandboxPolicy?: any;
     sandboxEngine?: any;
     ctx?: any;
-}): Promise<{
-    text: any;
-    outcome: {
-        status: string;
-        code: any;
-        retryable: boolean;
-        attempts: number;
-        durationMs: number;
-        bytes: number;
-        truncated: boolean;
-        exitCode: any;
-        signal: any;
-        timedOut: boolean;
-    };
-    error: boolean;
-} | {
-    text: string;
-    outcome: any;
-    error: any;
-}>;
+    processJobsController?: ProcessJobsController;
+}): Promise<any>;
+export type ProcessJobsController = import("./shared/process-jobs.js").ProcessJobsController;

package/types/agent/tools/glob.d.ts

@@ -1,6 +1,6 @@
 /**
  * @param {{pattern: string, path?: string, limit?: number, offset?: number, max_matches?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
  */
 export function globToolImpl({ pattern, path, limit, offset, max_matches, max_output_chars, workdir }: {
     pattern: string;
@@ -10,7 +10,8 @@ export function globToolImpl({ pattern, path, limit, offset, max_matches, max_ou
     max_matches?: number;
     max_output_chars?: number;
     workdir?: string;
-}, { sandboxPolicy, ctx }?: {
+}, { sandboxPolicy, sandboxEngine, ctx }?: {
     sandboxPolicy?: any;
+    sandboxEngine?: any;
     ctx?: any;
 }): Promise<string>;

package/types/agent/tools/grep.d.ts

@@ -1,6 +1,6 @@
 /**
  * @param {{pattern: string, path?: string, glob?: string, type?: string, output_mode?: string, context?: number, case_insensitive?: boolean, multiline?: boolean, head_limit?: number, offset?: number, max_matches?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
  */
 export function grepToolImpl({ pattern, path, glob, type, output_mode, context, case_insensitive, multiline, head_limit, offset, max_matches, max_output_chars, workdir, }: {
     pattern: string;
@@ -16,7 +16,8 @@ export function grepToolImpl({ pattern, path, glob, type, output_mode, context,
     max_matches?: number;
     max_output_chars?: number;
     workdir?: string;
-}, { sandboxPolicy, ctx }?: {
+}, { sandboxPolicy, sandboxEngine, ctx }?: {
     sandboxPolicy?: any;
+    sandboxEngine?: any;
     ctx?: any;
 }): Promise<string>;

package/types/agent/tools/pi-bridge.d.ts

@@ -35,9 +35,9 @@ export function createStructuredOutputTool(outputSchema: any, onStructuredOutput
 };
 /**
  * @param {any} allowedTools
- * @param {{disallowedTools?: any[], skillNames?: any[], skills?: any[], skillsRoot?: any, dataDir?: any, cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, persistArtifact?: any, onTruncate?: any, toolPayloadMaxBytes?: number, imageInlineMaxBytes?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, approvalManager?: any, approvalModel?: any, nodeReplController?: any, webController?: any, toolExecutionMode?: "sequential"|"safe-parallel", subagents?: any, subagentContext?: any, ctx?: any}} [options]
+ * @param {{disallowedTools?: any[], skillNames?: any[], skills?: any[], skillsRoot?: any, dataDir?: any, cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, persistArtifact?: any, onTruncate?: any, toolPayloadMaxBytes?: number, imageInlineMaxBytes?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, approvalManager?: any, approvalModel?: any, nodeReplController?: any, webController?: any, processJobsController?: any, toolExecutionMode?: "sequential"|"safe-parallel", subagents?: any, subagentContext?: any, ctx?: any}} [options]
  */
-export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNames, skills, skillsRoot, dataDir, cwd, onEvent, toolLimits, persistArtifact, onTruncate, toolPayloadMaxBytes, imageInlineMaxBytes, toolPolicy, sandboxPolicy, sandboxEngine, approvalManager, approvalModel, nodeReplController, webController, subagents, subagentContext, toolExecutionMode, ctx, }?: {
+export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNames, skills, skillsRoot, dataDir, cwd, onEvent, toolLimits, persistArtifact, onTruncate, toolPayloadMaxBytes, imageInlineMaxBytes, toolPolicy, sandboxPolicy, sandboxEngine, approvalManager, approvalModel, nodeReplController, webController, processJobsController, subagents, subagentContext, toolExecutionMode, ctx, }?: {
     disallowedTools?: any[];
     skillNames?: any[];
     skills?: any[];
@@ -57,6 +57,7 @@ export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNam
     approvalModel?: any;
     nodeReplController?: any;
     webController?: any;
+    processJobsController?: any;
     toolExecutionMode?: "sequential" | "safe-parallel";
     subagents?: any;
     subagentContext?: any;
@@ -80,9 +81,9 @@ export function coerceMcpContent(out: any, { textLimit, imageInlineMaxBytes, per
 /**
  * @param {any} mcpConfig
  * @param {Set<any>} [reservedNames]
- * @param {{limits?: any, cwd?: any, persistArtifact?: any, qaOutputDir?: any, onTruncate?: any, toolPayloadMaxBytes?: number, sandboxPolicy?: any, sandboxEngine?: any, onToolProgress?: any, ctx?: any}} [options]
+ * @param {{limits?: any, cwd?: any, persistArtifact?: any, qaOutputDir?: any, onTruncate?: any, toolPayloadMaxBytes?: number, sandboxPolicy?: any, sandboxEngine?: any, onToolProgress?: any, ctx?: any, mcpApps?: any, runId?: string}} [options]
  */
-export function initPiMcpTools(mcpConfig: any, reservedNames?: Set<any>, { limits, cwd, persistArtifact, qaOutputDir, onTruncate, toolPayloadMaxBytes, sandboxPolicy, sandboxEngine, onToolProgress, ctx, }?: {
+export function initPiMcpTools(mcpConfig: any, reservedNames?: Set<any>, { limits, cwd, persistArtifact, qaOutputDir, onTruncate, toolPayloadMaxBytes, sandboxPolicy, sandboxEngine, onToolProgress, ctx, mcpApps, runId, }?: {
     limits?: any;
     cwd?: any;
     persistArtifact?: any;
@@ -93,6 +94,8 @@ export function initPiMcpTools(mcpConfig: any, reservedNames?: Set<any>, { limit
     sandboxEngine?: any;
     onToolProgress?: any;
     ctx?: any;
+    mcpApps?: any;
+    runId?: string;
 }): Promise<{
     clients: {
         name: any;
@@ -131,6 +134,10 @@ export function initPiMcpTools(mcpConfig: any, reservedNames?: Set<any>, { limit
             };
         }>;
         transport: StreamableHTTPClientTransport | SSEClientTransport | StdioClientTransport;
+        connectionId: `${string}-${string}-${string}-${string}-${string}`;
+        retainedByMcpApps: boolean;
+        privateCapabilityUrl: boolean;
+        closed: boolean;
     }[];
     tools: any[];
     warnings: {

package/types/agent/tools/read.d.ts

@@ -1,6 +1,6 @@
 /**
  * @param {{file_path: string, offset?: number, start_line?: number, limit?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
  */
 export function readToolImpl({ file_path, offset, start_line, limit, max_output_chars, workdir }: {
     file_path: string;
@@ -9,8 +9,9 @@ export function readToolImpl({ file_path, offset, start_line, limit, max_output_
     limit?: number;
     max_output_chars?: number;
     workdir?: string;
-}, { sandboxPolicy, ctx }?: {
+}, { sandboxPolicy, sandboxEngine, ctx }?: {
     sandboxPolicy?: any;
+    sandboxEngine?: any;
     ctx?: any;
 }): Promise<string | {
     kind: string;

package/types/agent/tools/shared/path-resolver.d.ts

@@ -2,5 +2,13 @@ export function workspaceRoot(workdir: any, ctx: any): string;
 export function resolveToolPath(path: any, workdir: any, ctx: any): any;
 export function isPathAllowed(path: any, workdir: any, options?: {}): boolean;
 export function isWritablePathAllowed(path: any, workdir: any, options?: {}): boolean;
+export function isPathLexicallyAllowed(path: any, workdir: any, options?: {}): boolean;
+export function isWritablePathLexicallyAllowed(path: any, workdir: any, options?: {}): boolean;
 export function isWorkdirAllowed(workdir: any, options?: {}): boolean;
+/**
+ * Protected descendants of one search root, as normalized relative paths.
+ * Search tools use these both as ripgrep exclusions and as a defensive output
+ * filter; actual reads still cross the native sandbox boundary.
+ */
+export function protectedRelativePaths(directory: any, options?: {}): any[];
 export function isInsidePath(root: any, target: any): boolean;

package/types/agent/tools/shared/process-jobs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Kernel-local structural controller seam. The typed public interface lives in
+ * runtime-adapter; this package deliberately has no workspace dependencies.
+ *
+ * @typedef {Object} ProcessJobsController
+ * @property {(request: {
+ *   tool: "Exec"|"Bash",
+ *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
+ *   summary: string,
+ *   timeoutMs?: number,
+ *   maxOutputChars?: number,
+ *   launch: (options?: {timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}) => ReturnType<typeof startPreparedProcess>,
+ * }) => Promise<{jobId: string, state: "queued"|"starting"|"running", startedAt: string|null}>} start
+ */
+/**
+ * Transfer one prepared command to the injected host controller. From the
+ * instant `start()` is invoked, the controller owns cleanup on every path.
+ *
+ * @param {{
+ *   controller: ProcessJobsController,
+ *   tool: "Exec"|"Bash",
+ *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
+ *   summary: string,
+ *   timeoutMs?: number,
+ *   maxOutputChars?: number,
+ *   startedAt: number,
+ *   failed: (text: string, code: string, startedAt: number) => any,
+ * }} input
+ */
+export function handOffProcessJob({ controller, tool, prepared, summary, timeoutMs, maxOutputChars, startedAt, failed, }: {
+    controller: ProcessJobsController;
+    tool: "Exec" | "Bash";
+    prepared: import("../../sandbox-seam.js").PreparedSandboxCommand;
+    summary: string;
+    timeoutMs?: number;
+    maxOutputChars?: number;
+    startedAt: number;
+    failed: (text: string, code: string, startedAt: number) => any;
+}): Promise<any>;
+/**
+ * Kernel-local structural controller seam. The typed public interface lives in
+ * runtime-adapter; this package deliberately has no workspace dependencies.
+ */
+export type ProcessJobsController = {
+    start: (request: {
+        tool: "Exec" | "Bash";
+        prepared: import("../../sandbox-seam.js").PreparedSandboxCommand;
+        summary: string;
+        timeoutMs?: number;
+        maxOutputChars?: number;
+        launch: (options?: {
+            timeoutMs?: number;
+            signal?: AbortSignal;
+            maxBufferBytes?: number;
+            onStdout?: (chunk: Buffer) => void;
+            onStderr?: (chunk: Buffer) => void;
+        }) => ReturnType<typeof startPreparedProcess>;
+    }) => Promise<{
+        jobId: string;
+        state: "queued" | "starting" | "running";
+        startedAt: string | null;
+    }>;
+};
+import { startPreparedProcess } from "./process-runner.js";

package/types/agent/tools/shared/process-runner.d.ts

@@ -6,23 +6,65 @@
  * or exceeds that cap.
  *
  * @param {{command: string, args?: string[], cwd?: string, env?: Record<string, string|undefined>}} commandSpec
- * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number}} [options]
+ * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, input?: string|Buffer}} [options]
  */
 export function runPreparedProcess(commandSpec: {
     command: string;
     args?: string[];
     cwd?: string;
     env?: Record<string, string | undefined>;
-}, { timeoutMs, signal, maxBufferBytes, }?: {
+}, { timeoutMs, signal, maxBufferBytes, input, }?: {
     timeoutMs?: number;
     signal?: AbortSignal;
     maxBufferBytes?: number;
+    input?: string | Buffer;
 }): Promise<any>;
+/**
+ * Start one already-prepared executable and expose its process-group handle.
+ *
+ * `waitForProcessGroup` is deliberately opt-in so existing foreground tools
+ * retain their exact leader/stdio completion semantics. Process jobs enable it
+ * through their bound launcher: sandbox cleanup must not run while a detached
+ * descendant in the owned group is still alive.
+ *
+ * @param {{command: string, args?: string[], cwd?: string, env?: Record<string, string|undefined>}} commandSpec
+ * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, input?: string|Buffer, waitForProcessGroup?: boolean, exactEnvironment?: boolean, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}} [options]
+ * For process jobs, `release()` is the persistence fence: the target cannot
+ * spawn until the host has durably recorded the returned ownership metadata.
+ * Foreground handles expose a harmless no-op release for one structural shape.
+ *
+ * @returns {{pid: number|null, pgid: number|null, startedAt: string, completion: Promise<any>, release: () => Promise<void>, cancel: () => void}}
+ */
+export function startPreparedProcess(commandSpec: {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}, { timeoutMs, signal, maxBufferBytes, input, waitForProcessGroup, exactEnvironment, onStdout, onStderr, }?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    maxBufferBytes?: number;
+    input?: string | Buffer;
+    waitForProcessGroup?: boolean;
+    exactEnvironment?: boolean;
+    onStdout?: (chunk: Buffer) => void;
+    onStderr?: (chunk: Buffer) => void;
+}): {
+    pid: number | null;
+    pgid: number | null;
+    startedAt: string;
+    completion: Promise<any>;
+    release: () => Promise<void>;
+    cancel: () => void;
+};
 /**
  * @param {import("node:child_process").ChildProcess} child
  * @param {NodeJS.Signals} signal
+ * @param {{fallbackToChildPid?: boolean}} [options]
  */
-export function killProcessGroup(child: import("node:child_process").ChildProcess, signal: NodeJS.Signals): void;
+export function killProcessGroup(child: import("node:child_process").ChildProcess, signal: NodeJS.Signals, { fallbackToChildPid }?: {
+    fallbackToChildPid?: boolean;
+}): void;
 /**
  * @param {{stdout?: string, stderr?: string}} result
  */

package/types/agent/tools/shared/protected-filesystem.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @param {{command: string, args?: string[], cwd?: string, env?: Record<string, string|undefined>}} command
+ * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, input?: string|Buffer, maxBufferBytes?: number}} [options]
+ * @returns {Promise<any|null>}
+ */
+export function runProtectedFilesystemCommand(command: {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}, { sandboxPolicy, sandboxEngine, ctx, input, maxBufferBytes, }?: {
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    ctx?: any;
+    input?: string | Buffer;
+    maxBufferBytes?: number;
+}): Promise<any | null>;
+/**
+ * Build a metadata-free operation plan rooted at a configured policy path.
+ * Search tools keep the model-controlled target as an argument; file helpers
+ * use the stable cwd with their absolute target. In both cases the host avoids
+ * target metadata and target-derived cwd resolution before SRT enforces policy.
+ *
+ * @param {string} target
+ * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * @returns {{cwd: string, searchTarget: string}|null}
+ */
+export function protectedFilesystemTargetPlan(target: string, { sandboxPolicy, ctx }?: {
+    sandboxPolicy?: any;
+    ctx?: any;
+}): {
+    cwd: string;
+    searchTarget: string;
+} | null;
+/** @param {string} searchTarget */
+export function protectedDirectorySearchTarget(searchTarget: string): string;
+/**
+ * Scope a target-relative user glob to ripgrep's stable host cwd.
+ * @param {string} pattern
+ * @param {string} searchTarget
+ */
+export function scopeProtectedSearchGlob(pattern: string, searchTarget: string): string;
+/**
+ * Restore the historical target-relative search output after ripgrep runs from
+ * the stable policy root.
+ * @param {string} line
+ * @param {string} searchTarget
+ */
+export function normalizeProtectedSearchLine(line: string, searchTarget: string): string;
+/** @param {any} result */
+export function protectedCommandSucceeded(result: any): boolean;

package/types/agent/tools/write.d.ts

@@ -1,12 +1,13 @@
 /**
  * @param {{file_path: string, content?: string, workdir?: string}} params
- * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
  */
 export function writeToolImpl({ file_path, content, workdir }: {
     file_path: string;
     content?: string;
     workdir?: string;
-}, { sandboxPolicy, ctx }?: {
+}, { sandboxPolicy, sandboxEngine, ctx }?: {
     sandboxPolicy?: any;
+    sandboxEngine?: any;
     ctx?: any;
 }): Promise<string>;

package/types/ai/providers/pi-native/stream-subscriber.d.ts

@@ -7,6 +7,7 @@
  * @property {Set<unknown>} textDeltaIndexes
  * @property {Set<unknown>} thinkingDeltaIndexes
  * @property {Map<string, number>} toolStartTimes
+ * @property {Map<string, any>} toolApprovals
  * @property {number} turnCount
  * @property {number} toolResultsSeen
  * @property {string|null} lastToolName
@@ -38,6 +39,7 @@ export type StreamSubscriberState = {
     textDeltaIndexes: Set<unknown>;
     thinkingDeltaIndexes: Set<unknown>;
     toolStartTimes: Map<string, number>;
+    toolApprovals: Map<string, any>;
     turnCount: number;
     toolResultsSeen: number;
     lastToolName: string | null;

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

@@ -5,6 +5,7 @@ export namespace COMMON_CAPABILITIES {
     export let supports_session_resume: boolean;
     export let native_runtime_config: any;
     export let supports_mcp: boolean;
+    export let supports_mcp_apps: boolean;
     export let supports_skills: boolean;
     export let supports_builtin_tools: boolean;
     export let supports_live_input: boolean;
@@ -26,6 +27,8 @@ export namespace RUNTIME_CAPABILITIES {
         export { supports_native_subagents_1 as supports_native_subagents };
         let supports_request_tool_environment_1: boolean;
         export { supports_request_tool_environment_1 as supports_request_tool_environment };
+        let supports_mcp_apps_1: boolean;
+        export { supports_mcp_apps_1 as supports_mcp_apps };
         let runtime_1: string;
         export { runtime_1 as runtime };
     }

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

@@ -26,6 +26,7 @@ export function normalizeCodexItemEvent(raw: any, context?: {}): {
             tool_use_id: any;
             content: any;
             is_error: boolean;
+            tool_lifecycle: any;
         }[];
     };
 } | {