@rivet-dev/agentos-core 0.0.0-abc-fixes-1.d8c4d95 → 0.0.0-agent-acp-codex-session-benchmark.d578a31

package/dist/agent-os.d.ts

@@ -1,17 +1,12 @@
-import type { NativeMountPluginDescriptor } from "@secure-exec/core/descriptors";
+import type { NativeMountPluginDescriptor } from "@rivet-dev/agentos-runtime-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 { 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";
+import type { Kernel, KernelExecOptions, KernelExecResult, ProcessInfo as KernelProcessInfo, KernelSpawnOptions, OpenShellOptions, Permissions, VirtualFileSystem, VirtualStat } from "./runtime.js";
+export type { MountConfigJsonObject, MountConfigJsonPrimitive, MountConfigJsonValue, NativeMountPluginDescriptor, } from "@rivet-dev/agentos-runtime-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. */
@@ -23,39 +18,20 @@ export interface DirEntry {
 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;
+    /** Guest entrypoint the sidecar launches for this agent (`/opt/agentos/bin/<acpEntrypoint>`). */
+    adapterEntrypoint: string;
 }
-import { type AgentType } from "./agents.js";
-import type { ScheduleDriver } from "./cron/schedule-driver.js";
+import type { PackageRef, SoftwarePackageRef } from "./agentos-package.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 { SoftwareInput } from "./packages.js";
 import { type AgentOsSidecarPlacement } from "./sidecar/rpc-client.js";
+import type { AgentType } from "./types.js";
 export interface AgentOsSharedSidecarOptions {
     pool?: string;
 }
@@ -124,6 +100,8 @@ export interface AgentOsLimits {
     resources?: {
         cpuCount?: number;
         maxProcesses?: number;
+        /** Aggregate bytes retained by all active captured processes in this VM. Default: 32 MiB. */
+        maxCapturedOutputBytes?: number;
         maxOpenFds?: number;
         maxPipes?: number;
         maxPtys?: number;
@@ -172,15 +150,17 @@ export interface AgentOsLimits {
     /** Guest JavaScript runtime buffering limits. */
     jsRuntime?: {
         v8HeapLimitMb?: number;
+        syncRpcWaitTimeoutMs?: number;
+        cpuTimeLimitMs?: number;
+        wallClockLimitMs?: number;
+        importCacheMaterializeTimeoutMs?: number;
         capturedOutputLimitBytes?: number;
-        stdinBufferLimitBytes?: number;
-        eventPayloadLimitBytes?: number;
-        v8IpcMaxFrameBytes?: number;
     };
     /** Guest Python runtime limits. */
     python?: {
         outputBufferMaxBytes?: number;
         executionTimeoutMs?: number;
+        maxOldSpaceMb?: number;
         vfsRpcTimeoutMs?: number;
     };
     /** Guest WASM runtime limits. */
@@ -188,15 +168,81 @@ export interface AgentOsLimits {
         maxModuleFileBytes?: number;
         capturedOutputLimitBytes?: number;
         syncReadLimitBytes?: number;
+        prewarmTimeoutMs?: number;
+        runnerHeapLimitMb?: number;
     };
 }
+export interface AgentStderrEvent {
+    sessionId: string;
+    agentType: string;
+    processId: string;
+    pid: number | null;
+    chunk: Uint8Array;
+}
+export type AgentStderrHandler = (event: AgentStderrEvent) => void;
+/**
+ * Auto-restart outcome reported on an {@link AgentExitEvent}. Mirrors the
+ * sidecar's `AcpAgentExitedEvent.restart` strings:
+ * - `"restarted"` — the adapter was respawned and the session was natively
+ *   re-attached under the same session id; the session stays usable.
+ * - `"unsupported"` — the adapter does not advertise a native resume
+ *   capability (`loadSession`/`resume`); the session was evicted.
+ * - `"failed"` — the respawn or re-attach errored; the session was evicted.
+ * - `"exhausted"` — the per-session restart budget was already spent; evicted.
+ */
+export type AgentRestartOutcome = "restarted" | "unsupported" | "failed" | "exhausted";
+/**
+ * An unexpected ACP adapter process exit — a crash from the host's
+ * perspective (any spontaneous exit without `closeSession()`, including exit
+ * code 0) — plus the sidecar's bounded auto-restart outcome.
+ */
+export interface AgentExitEvent {
+    sessionId: string;
+    agentType: string;
+    /** Sidecar process id of the adapter that exited. */
+    processId: string;
+    pid: number | null;
+    /** Adapter exit code; `null` when the exit was observed indirectly. */
+    exitCode: number | null;
+    /** Auto-restart outcome; only `"restarted"` leaves the session usable. */
+    restart: AgentRestartOutcome;
+    /** Restarts consumed for this session so far. */
+    restartCount: number;
+    /** Per-session restart budget. */
+    maxRestarts: number;
+}
+export type AgentExitHandler = (event: AgentExitEvent) => void;
+/**
+ * A near-capacity warning for one bounded limit (a queue/buffer, a saturating
+ * resource cap, or a memory envelope) inside the VM runtime. Delivered the moment
+ * usage crosses the runtime's warning threshold (~80%), once per crossing — the
+ * runtime applies edge-triggering + hysteresis, so this never spams.
+ */
+export interface LimitWarning {
+    /** Stable limit name, e.g. `"javascript_event_channel"` or `"vm_open_fds"`. */
+    limit: string;
+    /** Limit class: `"queue"`, `"resource"`, or `"memory"`. */
+    category: string;
+    /** Current observed usage. */
+    observed: number;
+    /** Configured capacity. */
+    capacity: number;
+    /** Observed fill as a percentage of capacity (0–100). */
+    fillPercent: number;
+}
+export type LimitWarningHandler = (warning: LimitWarning) => void;
+/**
+ * Public core VM options.
+ *
+ * Keep this interface in sync with
+ * `packages/core/src/options-schema.ts::agentOsOptionsSchema`. The Rivet
+ * native actor intentionally accepts only a subset via
+ * `packages/agentos/src/config.ts::nativeAgentOsOptionsSchema`.
+ */
 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 @agentos-software/coreutils) is treated
-     * as a WASM command source automatically. Arrays are flattened, so
-     * meta-packages that export arrays of sub-packages work directly.
+     * Software to install in the VM. Each entry is a package-dir ref. Arrays are
+     * flattened, so meta-packages that export arrays of sub-packages work directly.
      */
     software?: SoftwareInput[];
     /**
@@ -214,24 +260,26 @@ export interface AgentOsOptions {
      * Defaults to the hardened builtin set used by the native sidecar bridge.
      */
     allowedNodeBuiltins?: string[];
+    /**
+     * Opt in to a high-resolution monotonic guest clock (microsecond class)
+     * for guest Node processes. Default `false` keeps the security-oriented
+     * 1ms timer resolution — untrusted guest code should not get a precise
+     * timer (timing side channels). Enable only for trusted benchmarking or
+     * profiling workloads.
+     */
+    highResolutionTime?: boolean;
     /** 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[];
-    /**
-     * @deprecated Use `mounts: [nodeModulesMount(path)]` instead.
-     * Compatibility alias for mounting `<moduleAccessCwd>/node_modules` at `/root/node_modules`.
-     */
-    moduleAccessCwd?: string;
     /** 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.
+     * network, child process, and environment operations. When omitted, the
+     * sidecar defaults every category to allow.
      */
     permissions?: Permissions;
     /**
@@ -244,6 +292,28 @@ export interface AgentOsOptions {
      * runtime's historical constants, so omitting this leaves behavior unchanged.
      */
     limits?: AgentOsLimits;
+    /**
+     * Called with stderr chunks from the top-level ACP-speaking agent process.
+     * The agent process uses stdout for ACP JSON-RPC protocol traffic, so only
+     * stderr is forwarded through this hook. Defaults to writing chunks to
+     * `process.stderr`.
+     */
+    onAgentStderr?: AgentStderrHandler;
+    /**
+     * Called when the ACP adapter process behind a session exits without
+     * `closeSession()` — i.e. an adapter crash. The sidecar auto-restarts the
+     * adapter (bounded per session, natively re-attaching the same session id)
+     * and reports the outcome on the event; only `restart === "restarted"`
+     * leaves the session usable. Defaults to writing a warning line to
+     * `process.stderr`.
+     */
+    onAgentExit?: AgentExitHandler;
+    /**
+     * Called when a bounded limit inside the VM runtime approaches capacity
+     * (~80%, edge-triggered with hysteresis so it does not spam). Use it to alert
+     * on a slow consumer or a runaway guest before the limit is actually hit.
+     */
+    onLimitWarning?: LimitWarningHandler;
 }
 /** Configuration for a local MCP server (spawned as a child process). */
 export interface McpServerConfigLocal {
@@ -336,44 +406,37 @@ 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 _disposed;
+    private _disposePromise;
     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 _disposeSidecarRequestHandler;
+    private readonly _agentStderrHandler?;
+    private readonly _agentExitHandler?;
+    private readonly _limitWarningHandler?;
     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>;
     execArgv(command: string, args?: readonly string[], options?: KernelExecOptions): Promise<KernelExecResult>;
+    private _pruneCompletedProcessRoutes;
     private _trackProcess;
-    spawn(command: string, args: string[], options?: KernelSpawnOptions): {
+    spawn(command: string, args: string[], options?: KernelSpawnOptions): Promise<{
         pid: number;
-    };
+    }>;
     /** Write data to a process's stdin. */
-    writeProcessStdin(pid: number, data: string | Uint8Array): void;
+    writeProcessStdin(pid: number, data: string | Uint8Array): Promise<void>;
     /** Close a process's stdin stream. */
-    closeProcessStdin(pid: number): void;
+    closeProcessStdin(pid: number): Promise<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. */
@@ -382,16 +445,8 @@ export declare class AgentOs {
     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>;
@@ -400,66 +455,107 @@ export declare class AgentOs {
     stat(path: string): Promise<VirtualStat>;
     exists(path: string): Promise<boolean>;
     snapshotRootFilesystem(): Promise<RootSnapshotExport>;
+    /**
+     * Mount a filesystem into the running VM. Resolves once the mount has been
+     * delivered to the native sidecar, so guest code can use it immediately
+     * after the returned promise settles; a delivery failure rejects instead of
+     * leaving the mount silently host-only.
+     */
     mountFs(path: string, driver: VirtualFileSystem, options?: {
         readOnly?: boolean;
-    }): void;
-    unmountFs(path: string): void;
+    }): Promise<void>;
+    unmountFs(path: string): Promise<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): {
+    openShell(options?: OpenShellOptions): Promise<{
         shellId: string;
-    };
-    connectTerminal(options?: ConnectTerminalOptions): Promise<number>;
+    }>;
     /** Write data to a shell's PTY input. */
-    writeShell(shellId: string, data: string | Uint8Array): void;
+    writeShell(shellId: string, data: string | Uint8Array): Promise<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[];
+    /** Notify a shell of terminal resize and await the sidecar response. */
+    resizeShell(shellId: string, cols: number, rows: number): Promise<void>;
+    /**
+     * Wait for a shell to exit and return its sidecar-authoritative exit code.
+     * A late wait reads the retained sidecar process snapshot.
+     */
+    waitShell(shellId: string): Promise<number>;
+    /** Kill a shell process, await the sidecar response, and remove it from tracking. */
+    closeShell(shellId: string): Promise<void>;
+    /** Returns sidecar-authoritative info for processes spawned via spawn(). */
+    listProcesses(): Promise<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[];
+    allProcesses(): Promise<KernelProcessInfo[]>;
     /** Returns info about a specific process by PID. Throws if not found. */
-    getProcess(pid: number): SpawnedProcessInfo;
+    getProcess(pid: number): Promise<SpawnedProcessInfo>;
     /** Send SIGTERM to gracefully stop a process. No-op if already exited. */
-    stopProcess(pid: number): void;
+    stopProcess(pid: number): Promise<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[];
+    killProcess(pid: number): Promise<void>;
+    /** Returns the sidecar's authoritative active-session list. */
+    listSessions(): Promise<SessionInfo[]>;
     /** Internal helper: retrieve a session or throw. */
     private _requireSession;
-    /** Returns all registered agents with their installation status. */
-    listAgents(): AgentRegistryEntry[];
-    private _syncSessionState;
-    private _applySessionUpdate;
+    /**
+     * Dynamically link a software package into the RUNNING VM. The package's
+     * `bin/` commands appear under `/opt/agentos/bin` (on `$PATH`) and its `share/man`
+     * pages under MANPATH immediately — the `/opt/agentos` mount is host-backed, so
+     * writing into its staging dir is reflected live with no reboot. An `agent`
+     * block registers the package for `createSession(name)`. Persists for the VM's
+     * lifetime (and across a snapshot iff the volume persists).
+     */
+    linkSoftware(descriptor: PackageRef | SoftwarePackageRef): Promise<void>;
+    providedCommands(): Promise<{
+        packageName: string;
+        commands: string[];
+    }[]>;
+    /**
+     * Returns all registered agents with their installation status. Thin forwarder:
+     * sends `AcpListAgentsRequest` and maps the response. The sidecar enumerates the
+     * projected `/opt/agentos` packages (the client parses no manifests). Every such
+     * agent is a package materialized into the VM, so `installed` is always `true`.
+     */
+    listAgents(): Promise<AgentRegistryEntry[]>;
     private _recordSessionNotification;
     private _dispatchSessionEvent;
     private _subscribeSessionEvents;
-    private _applySyntheticConfigOverrides;
+    /**
+     * Warn once per session (host-visible) that a tool-permission request was
+     * auto-denied because no `onPermissionRequest` handler is registered. Shared
+     * by both the bare-callback and JSON-RPC permission paths so the message and
+     * the once-per-session guard cannot drift between them.
+     */
+    private _warnNoPermissionHandlerOnce;
+    /** Best-effort human label for the tool named in a permission request. */
+    private _permissionToolLabel;
+    /**
+     * Emit a host-visible warning for a session through the same agent-process log
+     * channel that surfaces adapter stderr (`onAgentStderr`, default: process
+     * stderr). Used for agent-os-owned diagnostics — e.g. a permission request
+     * that was auto-denied because no host hook is registered — so they never fire
+     * silently inside the sidecar.
+     */
+    private _emitSessionWarning;
+    private _recordAgentStderr;
+    private _recordAgentExit;
     private _handleSidecarEvent;
+    private _handleLimitWarning;
     private _handleAcpExtEvent;
-    private _unsupportedConfigResponse;
+    private _decodeAcpResponseEnvelope;
     private _sendAcpRequest;
     private _sendSessionRequest;
+    private _sendSessionRequestWithText;
     private _setSessionConfigByCategory;
     private _removeSession;
-    private _abortPendingSessionRequests;
-    private _cancelPendingPromptRequests;
     private _rejectPendingPermissionReplies;
     private _rejectPendingPermissionRepliesFromSession;
     private _closeSessionInternal;
-    private _hydrateSessionState;
-    createSession(agentType: AgentType | string, options?: CreateSessionOptions): Promise<{
+    private _getSessionState;
+    createSession(agentType: AgentType, options?: CreateSessionOptions): Promise<{
         sessionId: string;
     }>;
     /**
@@ -471,60 +567,16 @@ export declare class AgentOs {
      * 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.
+     * The new live session is registered locally only for host callbacks/events;
+     * authoritative state remains in the sidecar.
      *
      * 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;
+    resumeSession(sessionId: string, agentType: AgentType, options?: ResumeSessionOptions): Promise<ResumeSessionResult>;
     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
@@ -534,28 +586,29 @@ export declare class AgentOs {
     prompt(sessionId: string, text: string): Promise<PromptResult>;
     /** Cancel ongoing agent work for a session. */
     cancelSession(sessionId: string): Promise<JsonRpcResponse>;
-    closeSession(sessionId: string): void;
+    closeSession(sessionId: string): Promise<void>;
     respondPermission(sessionId: string, permissionId: string, reply: PermissionReply): Promise<JsonRpcResponse>;
     setSessionMode(sessionId: string, modeId: string): Promise<JsonRpcResponse>;
-    getSessionModes(sessionId: string): SessionModeState | null;
+    getSessionModes(sessionId: string): Promise<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;
+    getSessionConfigOptions(sessionId: string): Promise<SessionConfigOption[]>;
+    getSessionCapabilities(sessionId: string): Promise<AgentCapabilities | null>;
+    getSessionAgentInfo(sessionId: string): Promise<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;
+    scheduleCron(options: CronJobOptions): Promise<CronJob>;
     /** List all registered cron jobs. */
-    listCronJobs(): CronJobInfo[];
+    listCronJobs(): Promise<CronJobInfo[]>;
     /** Cancel a cron job by ID. */
-    cancelCronJob(id: string): void;
+    cancelCronJob(id: string): Promise<void>;
     /** Subscribe to cron lifecycle events (fire, complete, error). */
     onCronEvent(handler: CronEventHandler): void;
     dispose(): Promise<void>;
+    private _disposeOnce;
 }
 export declare function getAgentOsRuntimeAdmin(vm: AgentOs): AgentOsRuntimeAdmin;
 export declare function getAgentOsKernel(vm: AgentOs): Kernel;
@@ -563,6 +616,7 @@ export declare class AgentOsSidecar {
     constructor(sidecarId: string, placement: AgentOsSidecarPlacement, sharedPool?: string);
     describe(): AgentOsSidecarDescription;
     dispose(): Promise<void>;
+    private disposeOnce;
 }
 /**
  * Test-only escape hatch: dispose every cached shared sidecar so vitest