@rivet-dev/agentos-core 0.0.0-agentos-dylib-plugin.473700e

package/dist/agent-os.d.ts

@@ -0,0 +1,560 @@
+import type { NativeMountPluginDescriptor } from "@secure-exec/core/descriptors";
+import type { AgentCapabilities, AgentInfo, PermissionReply, PermissionRequestHandler, SessionConfigOption, SessionEventHandler, SessionModeState } from "./agent-session-types.js";
+import { type ToolKit } from "./host-tools.js";
+import type { JsonRpcResponse } from "./json-rpc.js";
+import type { ConnectTerminalOptions, Kernel, KernelExecOptions, KernelExecResult, ProcessInfo as KernelProcessInfo, KernelSpawnOptions, OpenShellOptions, Permissions, VirtualFileSystem, VirtualStat } from "./runtime-compat.js";
+export type { MountConfigJsonObject, MountConfigJsonPrimitive, MountConfigJsonValue, NativeMountPluginDescriptor, } from "@secure-exec/core/descriptors";
+export type { AgentCapabilities, AgentInfo, PermissionReply, PermissionRequest, PermissionRequestHandler, SessionConfigOption, SessionEventHandler, SessionInitData, SessionMode, SessionModeState, } from "./agent-session-types.js";
+export type { AcpTimeoutErrorData, JsonRpcError, JsonRpcErrorData, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, } from "./json-rpc.js";
+export { isAcpTimeoutErrorData } from "./json-rpc.js";
+export type { ConnectTerminalOptions } from "./runtime-compat.js";
+/** Process tree node: extends kernel ProcessInfo with child references. */
+export interface ProcessTreeNode extends KernelProcessInfo {
+    children: ProcessTreeNode[];
+}
+/** A directory entry with metadata. */
+export interface DirEntry {
+    /** Absolute path to the entry. */
+    path: string;
+    type: "file" | "directory" | "symlink";
+    size: number;
+}
+/** Options for readdirRecursive(). */
+export interface ReaddirRecursiveOptions {
+    /** Maximum depth to recurse (0 = only immediate children). */
+    maxDepth?: number;
+    /** Directory names to skip. */
+    exclude?: string[];
+}
+/** Entry for batch write operations. */
+export interface BatchWriteEntry {
+    path: string;
+    content: string | Uint8Array;
+}
+/** Result of a single file in a batch write. */
+export interface BatchWriteResult {
+    path: string;
+    success: boolean;
+    error?: string;
+}
+/** Result of a single file in a batch read. */
+export interface BatchReadResult {
+    path: string;
+    content: Uint8Array | null;
+    error?: string;
+}
+/** Entry in the agent registry, describing an available agent type. */
+export interface AgentRegistryEntry {
+    id: string;
+    acpAdapter: string;
+    agentPackage: string;
+    installed: boolean;
+}
+import { type AgentType } from "./agents.js";
+import type { ScheduleDriver } from "./cron/schedule-driver.js";
+import type { CronEventHandler, CronJob, CronJobInfo, CronJobOptions } from "./cron/types.js";
+import { type LayerStore, type OverlayFilesystemMode, type RootSnapshotExport, type SnapshotLayerHandle } from "./layers.js";
+import { type SoftwareInput } from "./packages.js";
+import { type AgentOsSidecarPlacement } from "./sidecar/rpc-client.js";
+export interface AgentOsSharedSidecarOptions {
+    pool?: string;
+}
+export interface AgentOsCreateSidecarOptions {
+    sidecarId?: string;
+}
+export type AgentOsSidecarConfig = {
+    kind: "shared";
+    pool?: string;
+} | {
+    kind: "explicit";
+    handle: AgentOsSidecar;
+};
+export interface AgentOsSidecarDescription {
+    sidecarId: string;
+    placement: AgentOsSidecarPlacement;
+    state: "ready" | "disposing" | "disposed";
+    activeVmCount: number;
+}
+export type RootLowerInput = {
+    kind: "bundled-base-filesystem";
+} | RootSnapshotExport;
+export interface RootFilesystemConfig {
+    type?: "overlay";
+    mode?: OverlayFilesystemMode;
+    disableDefaultBaseLayer?: boolean;
+    lowers?: RootLowerInput[];
+}
+/**
+ * Compatibility path for arbitrary caller-supplied filesystems.
+ * This maps to the sidecar `js_bridge` plugin during the migration.
+ */
+export interface PlainMountConfig {
+    /** Path inside the VM to mount at. */
+    path: string;
+    /** The filesystem driver to mount. */
+    driver: VirtualFileSystem;
+    /** If true, write operations throw EROFS. */
+    readOnly?: boolean;
+}
+/** Declarative native mount configuration that the sidecar can serialize. */
+export interface NativeMountConfig {
+    path: string;
+    plugin: NativeMountPluginDescriptor;
+    readOnly?: boolean;
+}
+export interface OverlayMountConfig {
+    path: string;
+    filesystem: {
+        type: "overlay";
+        store: LayerStore;
+        mode?: OverlayFilesystemMode;
+        lowers: SnapshotLayerHandle[];
+    };
+}
+export type MountConfig = PlainMountConfig | NativeMountConfig | OverlayMountConfig;
+/**
+ * Operator-tunable runtime limits for a VM. Every field is optional; unset fields fall back to
+ * built-in defaults that match the runtime's historical hardcoded constants, so behavior is
+ * unchanged unless a value is overridden. All values are JSON-serializable integers and are
+ * forwarded to the native sidecar in the typed create-VM JSON config. Unknown, negative, or
+ * non-integer values are rejected by the sidecar before VM construction.
+ */
+export interface AgentOsLimits {
+    /** Kernel resource limits (processes, FDs, sockets, filesystem bytes, WASM caps, etc.). */
+    resources?: {
+        cpuCount?: number;
+        maxProcesses?: number;
+        maxOpenFds?: number;
+        maxPipes?: number;
+        maxPtys?: number;
+        maxSockets?: number;
+        maxConnections?: number;
+        maxSocketBufferedBytes?: number;
+        maxSocketDatagramQueueLen?: number;
+        maxFilesystemBytes?: number;
+        maxInodeCount?: number;
+        maxBlockingReadMs?: number;
+        maxPreadBytes?: number;
+        maxFdWriteBytes?: number;
+        maxProcessArgvBytes?: number;
+        maxProcessEnvBytes?: number;
+        maxReaddirEntries?: number;
+        maxWasmFuel?: number;
+        maxWasmMemoryBytes?: number;
+        maxWasmStackBytes?: number;
+    };
+    /** HTTP body buffering limits. */
+    http?: {
+        /** Cap on `vm.fetch()` buffered response bodies. Must be <= the sidecar wire frame cap. */
+        maxFetchResponseBytes?: number;
+    };
+    /** Host-tool registration and invocation limits. */
+    tools?: {
+        defaultToolTimeoutMs?: number;
+        maxToolTimeoutMs?: number;
+        maxRegisteredToolkits?: number;
+        maxRegisteredToolsPerVm?: number;
+        maxToolsPerToolkit?: number;
+        maxToolSchemaBytes?: number;
+        maxToolExamplesPerTool?: number;
+        maxToolExampleInputBytes?: number;
+    };
+    /** Mount plugin manifest size limits. */
+    plugins?: {
+        maxPersistedManifestBytes?: number;
+        maxPersistedManifestFileBytes?: number;
+    };
+    /** ACP adapter buffering limits. */
+    acp?: {
+        maxReadLineBytes?: number;
+        stdoutBufferByteLimit?: number;
+    };
+    /** Guest JavaScript runtime buffering limits. */
+    jsRuntime?: {
+        v8HeapLimitMb?: number;
+        capturedOutputLimitBytes?: number;
+        stdinBufferLimitBytes?: number;
+        eventPayloadLimitBytes?: number;
+        v8IpcMaxFrameBytes?: number;
+    };
+    /** Guest Python runtime limits. */
+    python?: {
+        outputBufferMaxBytes?: number;
+        executionTimeoutMs?: number;
+        vfsRpcTimeoutMs?: number;
+    };
+    /** Guest WASM runtime limits. */
+    wasm?: {
+        maxModuleFileBytes?: number;
+        capturedOutputLimitBytes?: number;
+        syncReadLimitBytes?: number;
+    };
+}
+export interface AgentOsOptions {
+    /**
+     * Software to install in the VM. Each entry provides agents, tools,
+     * or WASM commands. Any object with a `commandDir` property (e.g.,
+     * registry packages like @agent-os-pkgs/coreutils) is treated
+     * as a WASM command source automatically. Arrays are flattened, so
+     * meta-packages that export arrays of sub-packages work directly.
+     */
+    software?: SoftwareInput[];
+    /** Loopback ports to exempt from SSRF checks (for testing with host-side mock servers). */
+    loopbackExemptPorts?: number[];
+    /**
+     * Allowed Node.js builtins for guest Node processes.
+     * Defaults to the hardened builtin set used by the native sidecar bridge.
+     */
+    allowedNodeBuiltins?: string[];
+    /** Root filesystem configuration. Defaults to an overlay with the bundled base snapshot as its deepest lower. */
+    rootFilesystem?: RootFilesystemConfig;
+    /** Filesystems to mount at boot time. */
+    mounts?: MountConfig[];
+    /** Additional instructions appended to the base OS system prompt injected at session start. */
+    additionalInstructions?: string;
+    /** Custom schedule driver for cron jobs. Defaults to TimerScheduleDriver. */
+    scheduleDriver?: ScheduleDriver;
+    /** Host-side toolkits available to agents inside the VM. */
+    toolKits?: ToolKit[];
+    /**
+     * Custom permission policy for the kernel. Controls access to filesystem,
+     * network, child process, and environment operations. Defaults to allowAll.
+     */
+    permissions?: Permissions;
+    /**
+     * Sidecar placement for the VM. Defaults to the shared `default` pool.
+     * Pass an explicit sidecar handle to pin the VM to a caller-managed sidecar.
+     */
+    sidecar?: AgentOsSidecarConfig;
+    /**
+     * Operator-tunable runtime limits. Unset fields use built-in defaults that match the
+     * runtime's historical constants, so omitting this leaves behavior unchanged.
+     */
+    limits?: AgentOsLimits;
+}
+/** Configuration for a local MCP server (spawned as a child process). */
+export interface McpServerConfigLocal {
+    type: "local";
+    /** Command to launch the MCP server. */
+    command: string;
+    /** Arguments for the command. */
+    args?: string[];
+    /** Environment variables for the server process. */
+    env?: Record<string, string>;
+}
+/** Configuration for a remote MCP server (connected via URL). */
+export interface McpServerConfigRemote {
+    type: "remote";
+    /** URL of the remote MCP server. */
+    url: string;
+    /** HTTP headers to include in requests to the server. */
+    headers?: Record<string, string>;
+}
+export type McpServerConfig = McpServerConfigLocal | McpServerConfigRemote;
+export interface AgentOsRuntimeAdmin {
+    kernel: Kernel;
+    rootView: VirtualFileSystem;
+    env: Record<string, string>;
+    sidecar: AgentOsSidecar;
+}
+export interface CreateSessionOptions {
+    /** Working directory for the agent session inside the VM. */
+    cwd?: string;
+    /** Environment variables to pass to the agent process. */
+    env?: Record<string, string>;
+    /** MCP servers to make available to the agent during the session. */
+    mcpServers?: McpServerConfig[];
+    /** Skip OS instructions injection entirely (default false). */
+    skipOsInstructions?: boolean;
+    /** Additional instructions appended to the base OS instructions. */
+    additionalInstructions?: string;
+}
+/**
+ * Options for {@link AgentOs.resumeSession}.
+ *
+ * Resume depends on a durable root: after a Rivet actor sleeps (VM destroyed) and
+ * wakes (fresh VM, actor SQLite intact) the caller can keep prompting an existing
+ * session. On a non-durable (default in-memory) root there is no surviving store,
+ * so the sidecar's universal fallback tier always runs and the transcript pointer
+ * is the only continuity mechanism.
+ */
+export interface ResumeSessionOptions {
+    /**
+     * Guest-readable path to the reconstructed transcript. When present, the
+     * fallback tier arms a continuation preamble pointing the agent at it.
+     */
+    transcriptPath?: string;
+    /** Working directory for the resumed agent session (default `/home/user`). */
+    cwd?: string;
+    /** Environment variables to pass to the resumed agent process. */
+    env?: Record<string, string>;
+}
+/** Result from {@link AgentOs.resumeSession}. */
+export interface ResumeSessionResult {
+    /**
+     * The live ACP session id in the fresh VM: equal to the requested id for
+     * native loads, or a freshly assigned id for the fallback tier — the caller
+     * remaps `external -> live`.
+     */
+    sessionId: string;
+    /** `"native"` (session/load|resume) or `"fallback"` (session/new + preamble). */
+    mode: string;
+}
+export interface SessionInfo {
+    sessionId: string;
+    agentType: string;
+}
+/** Result from AgentOs.prompt(). */
+export interface PromptResult {
+    /** Raw JSON-RPC response from the ACP adapter. */
+    response: JsonRpcResponse;
+    /** Accumulated agent text output from streamed message chunks. */
+    text: string;
+}
+/** Information about a process spawned via AgentOs.spawn(). */
+export interface SpawnedProcessInfo {
+    pid: number;
+    command: string;
+    args: string[];
+    running: boolean;
+    exitCode: number | null;
+}
+export declare class AgentOs {
+    #private;
+    readonly sidecar: AgentOsSidecar;
+    private _sessions;
+    private _closedSessionIds;
+    private _sessionClosePromises;
+    private _pendingSessionRequestResolvers;
+    private _processes;
+    private _shells;
+    private _closedShellIds;
+    private _pendingShellExitPromises;
+    private _shellCounter;
+    private _acpTerminals;
+    private _acpTerminalCounter;
+    private _softwareRoots;
+    private _softwareAgentConfigs;
+    private _cronManager;
+    private _toolKits;
+    private _toolReference;
+    private _permissions;
+    private _hostMounts;
+    private _env;
+    private _rootFilesystem;
+    private _sidecarLease;
+    private readonly _sidecarClient;
+    private readonly _sidecarSession;
+    private readonly _sidecarVm;
+    private readonly _disposeSidecarEventListener;
+    private constructor();
+    static createSidecar(options?: AgentOsCreateSidecarOptions): Promise<AgentOsSidecar>;
+    static getSharedSidecar(options?: AgentOsSharedSidecarOptions): Promise<AgentOsSidecar>;
+    static create(options?: AgentOsOptions): Promise<AgentOs>;
+    exec(command: string, options?: KernelExecOptions): Promise<KernelExecResult>;
+    private _trackProcess;
+    spawn(command: string, args: string[], options?: KernelSpawnOptions): {
+        pid: number;
+    };
+    /** Write data to a process's stdin. */
+    writeProcessStdin(pid: number, data: string | Uint8Array): void;
+    /** Close a process's stdin stream. */
+    closeProcessStdin(pid: number): void;
+    /** Subscribe to stdout data from a process. Returns an unsubscribe function. */
+    onProcessStdout(pid: number, handler: (data: Uint8Array) => void): () => void;
+    /** Subscribe to stderr data from a process. Returns an unsubscribe function. */
+    onProcessStderr(pid: number, handler: (data: Uint8Array) => void): () => void;
+    /** Subscribe to process exit. Returns an unsubscribe function. */
+    onProcessExit(pid: number, handler: (exitCode: number) => void): () => void;
+    /** Wait for a process to exit. Returns the exit code. */
+    waitProcess(pid: number): Promise<number>;
+    private _assertSafeAbsolutePath;
+    private _assertWritableAbsolutePath;
+    private _vfs;
+    private _copyPath;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    writeFiles(entries: BatchWriteEntry[]): Promise<BatchWriteResult[]>;
+    readFiles(paths: string[]): Promise<BatchReadResult[]>;
+    /** Recursively create directories (mkdir -p). */
+    private _mkdirp;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readdirRecursive(path: string, options?: ReaddirRecursiveOptions): Promise<DirEntry[]>;
+    stat(path: string): Promise<VirtualStat>;
+    exists(path: string): Promise<boolean>;
+    snapshotRootFilesystem(): Promise<RootSnapshotExport>;
+    mountFs(path: string, driver: VirtualFileSystem, options?: {
+        readOnly?: boolean;
+    }): void;
+    unmountFs(path: string): void;
+    move(from: string, to: string): Promise<void>;
+    delete(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    fetch(port: number, request: Request): Promise<Response>;
+    openShell(options?: OpenShellOptions): {
+        shellId: string;
+    };
+    connectTerminal(options?: ConnectTerminalOptions): Promise<number>;
+    /** Write data to a shell's PTY input. */
+    writeShell(shellId: string, data: string | Uint8Array): void;
+    /** Subscribe to data output from a shell. Returns an unsubscribe function. */
+    onShellData(shellId: string, handler: (data: Uint8Array) => void): () => void;
+    /** Notify a shell of terminal resize. */
+    resizeShell(shellId: string, cols: number, rows: number): void;
+    /** Kill a shell process and remove it from tracking. */
+    closeShell(shellId: string): void;
+    private _resolveVmPathToHostPath;
+    /** Returns info about all processes spawned via spawn(). */
+    listProcesses(): SpawnedProcessInfo[];
+    /** Returns all kernel processes across all active runtimes (WASM and Node). */
+    allProcesses(): KernelProcessInfo[];
+    /** Returns processes organized as a tree using ppid relationships. */
+    processTree(): ProcessTreeNode[];
+    /** Returns info about a specific process by PID. Throws if not found. */
+    getProcess(pid: number): SpawnedProcessInfo;
+    /** Send SIGTERM to gracefully stop a process. No-op if already exited. */
+    stopProcess(pid: number): void;
+    /** Send SIGKILL to force-kill a process. No-op if already exited. */
+    killProcess(pid: number): void;
+    /** Returns all active sessions with their IDs and agent types. */
+    listSessions(): SessionInfo[];
+    /** Internal helper: retrieve a session or throw. */
+    private _requireSession;
+    /** Returns all registered agents with their installation status. */
+    listAgents(): AgentRegistryEntry[];
+    private _syncSessionState;
+    private _applySessionUpdate;
+    private _recordSessionNotification;
+    private _dispatchSessionEvent;
+    private _subscribeSessionEvents;
+    private _applySyntheticConfigOverrides;
+    private _handleSidecarEvent;
+    private _handleAcpExtEvent;
+    private _unsupportedConfigResponse;
+    private _sendAcpRequest;
+    private _sendSessionRequest;
+    private _setSessionConfigByCategory;
+    private _removeSession;
+    private _abortPendingSessionRequests;
+    private _cancelPendingPromptRequests;
+    private _rejectPendingPermissionReplies;
+    private _rejectPendingPermissionRepliesFromSession;
+    private _closeSessionInternal;
+    private _hydrateSessionState;
+    createSession(agentType: AgentType | string, options?: CreateSessionOptions): Promise<{
+        sessionId: string;
+    }>;
+    /**
+     * Resume a session that exists in durable storage but is not live in this VM
+     * (e.g. after a Rivet actor slept and woke with a fresh VM). Thin forwarder:
+     * resolves the agent config + adapter entrypoint exactly as {@link createSession}
+     * does, then forwards a single `AcpResumeSessionRequest` to the sidecar, which
+     * owns the resume state machine (native `session/load` when the agent supports
+     * it, else `session/new` + a transcript-continuation preamble). The returned
+     * `sessionId` is the live id in this VM (equal to the requested id for native
+     * loads, freshly assigned for the fallback); the caller remaps `external -> live`.
+     * The new live session is registered + hydrated locally so subsequent prompts
+     * route to it.
+     *
+     * Resume depends on a durable root; on a non-durable (default in-memory) root
+     * there is no surviving store and the fallback tier always runs.
+     */
+    resumeSession(sessionId: string, agentType: AgentType | string, options?: ResumeSessionOptions): Promise<ResumeSessionResult>;
+    /**
+     * Resolve the VM bin entry point of an ACP adapter package.
+     * Reads from the host filesystem since kernel.readFile() resolves through
+     * mounts; adapter package.json is read directly off the host dir backing
+     * the relevant mount.
+     */
+    private _resolveAdapterBin;
+    /**
+     * Parent of the host directory backing the `/root/node_modules` mount, if
+     * the caller supplied one (e.g. via `nodeModulesMount(...)`). Used as the
+     * `resolvePackageDir` start dir for adapter/agent package resolution when no
+     * software root matches. `nodeModulesMount` mounts `<dir>/node_modules`, so
+     * the start dir is `<dir>` (one level above the node_modules tree).
+     */
+    private _nodeModulesHostRoot;
+    private _resolvePackageBin;
+    private _installSidecarRequestHandler;
+    private _handleAcpExtSidecarRequest;
+    private _dispatchAcpSidecarRequest;
+    private _handleSupportedAcpSidecarRequest;
+    private _normalizeAcpPermissionOptionId;
+    private _buildAcpPermissionResult;
+    private _handleAcpPermissionRequest;
+    private _acpParams;
+    private _requireAcpStringParam;
+    private _optionalAcpStringParam;
+    private _optionalAcpNumberParam;
+    private _optionalAcpStringArrayParam;
+    private _optionalAcpEnvParam;
+    private _requireAcpTerminal;
+    private _appendAcpTerminalOutput;
+    private _handleAcpReadFile;
+    private _handleAcpWriteFile;
+    private _handleAcpReadDir;
+    private _handleAcpCreateTerminal;
+    private _handleAcpWriteTerminal;
+    private _handleAcpReadTerminal;
+    private _handleAcpWaitForTerminalExit;
+    private _handleAcpKillTerminal;
+    private _handleAcpReleaseTerminal;
+    private _handleAcpResizeTerminal;
+    private _handleAcpPermissionCallback;
+    /**
+     * Resolve an agent config by ID. Package-provided configs take
+     * precedence over the hardcoded AGENT_CONFIGS.
+     */
+    private _resolveAgentConfig;
+    /**
+     * Gracefully destroy a session: cancel any pending work, close the client,
+     * and remove from tracking. Unlike close() which is abrupt, this attempts
+     * a graceful shutdown sequence.
+     */
+    destroySession(sessionId: string): Promise<void>;
+    prompt(sessionId: string, text: string): Promise<PromptResult>;
+    /** Cancel ongoing agent work for a session. */
+    cancelSession(sessionId: string): Promise<JsonRpcResponse>;
+    closeSession(sessionId: string): void;
+    respondPermission(sessionId: string, permissionId: string, reply: PermissionReply): Promise<JsonRpcResponse>;
+    setSessionMode(sessionId: string, modeId: string): Promise<JsonRpcResponse>;
+    getSessionModes(sessionId: string): SessionModeState | null;
+    setSessionModel(sessionId: string, model: string): Promise<JsonRpcResponse>;
+    setSessionThoughtLevel(sessionId: string, level: string): Promise<JsonRpcResponse>;
+    getSessionConfigOptions(sessionId: string): SessionConfigOption[];
+    getSessionCapabilities(sessionId: string): AgentCapabilities | null;
+    getSessionAgentInfo(sessionId: string): AgentInfo | null;
+    rawSessionSend(sessionId: string, method: string, params?: Record<string, unknown>): Promise<JsonRpcResponse>;
+    rawSend(sessionId: string, method: string, params?: Record<string, unknown>): Promise<JsonRpcResponse>;
+    onSessionEvent(sessionId: string, handler: SessionEventHandler): () => void;
+    onPermissionRequest(sessionId: string, handler: PermissionRequestHandler): () => void;
+    /** Schedule a cron job. Returns a handle with the job ID and a cancel method. */
+    scheduleCron(options: CronJobOptions): CronJob;
+    /** List all registered cron jobs. */
+    listCronJobs(): CronJobInfo[];
+    /** Cancel a cron job by ID. */
+    cancelCronJob(id: string): void;
+    /** Subscribe to cron lifecycle events (fire, complete, error). */
+    onCronEvent(handler: CronEventHandler): void;
+    dispose(): Promise<void>;
+}
+export declare function getAgentOsRuntimeAdmin(vm: AgentOs): AgentOsRuntimeAdmin;
+export declare function getAgentOsKernel(vm: AgentOs): Kernel;
+export declare class AgentOsSidecar {
+    constructor(sidecarId: string, placement: AgentOsSidecarPlacement, sharedPool?: string);
+    describe(): AgentOsSidecarDescription;
+    dispose(): Promise<void>;
+}
+/**
+ * Test-only escape hatch: dispose every cached shared sidecar so vitest
+ * workers can exit cleanly. The shared sidecar is normally process-global and
+ * keeps its native subprocess alive across `AgentOs.create()` calls; without
+ * this hook the vitest worker can hold open piped stdio handles after the
+ * test suite finishes and stall `pnpm test` indefinitely.
+ */
+export declare function __disposeAllSharedSidecarsForTesting(): Promise<void>;