@rivet-dev/agentos-core 0.0.0-integrate-dylib-into-main.815fcda → 0.0.0-main.29b0797

package/dist/agent-os.d.ts

@@ -1,13 +1,11 @@
-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 { NativeMountPluginDescriptor } from "@rivet-dev/agentos-runtime-core/descriptors";
+import type { VmUserConfig } from "@rivet-dev/agentos-runtime-core/vm-config";
+import type { CancelPromptResult, HistoryPage, ListSessionsInput, OpenSessionInput, PermissionResponse, PermissionResponseResult, PromptInput, PromptResult as DurablePromptResult, ReadHistoryInput, SessionCapabilities, SessionAgentInfo, SessionConfig, SessionInfo as DurableSessionInfo, SessionPage, SessionStreamEntry, SessionTarget, SetSessionConfigOptionInput } from "./session-api.js";
+import { type Bindings } from "./bindings.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 { MountConfigJsonObject, MountConfigJsonPrimitive, MountConfigJsonValue, NativeMountPluginDescriptor, } from "@rivet-dev/agentos-runtime-core/descriptors";
 export type { ConnectTerminalOptions } from "./runtime-compat.js";
+export type * from "./session-api.js";
 /** Process tree node: extends kernel ProcessInfo with child references. */
 export interface ProcessTreeNode extends KernelProcessInfo {
     children: ProcessTreeNode[];
@@ -19,6 +17,64 @@ export interface DirEntry {
     type: "file" | "directory" | "symlink";
     size: number;
 }
+/** One immediate child returned by a single readdirEntries operation. */
+export interface ReaddirEntry {
+    name: string;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
+/** Fully buffered request to an HTTP service listening inside the VM. */
+export interface HttpRequest {
+    port: number;
+    path: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+}
+/** Fully buffered HTTP response from a service inside the VM. */
+export interface HttpResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: Uint8Array;
+}
+export interface ProcessOutput {
+    pid: number;
+    stream: "stdout" | "stderr";
+    data: Uint8Array;
+}
+export interface ProcessExit {
+    pid: number;
+    exitCode: number;
+}
+export interface ShellData {
+    shellId: string;
+    data: Uint8Array;
+}
+export interface ShellExit {
+    shellId: string;
+    exitCode: number;
+}
+/** Sanitized live mount metadata. Plugin configuration is never exposed. */
+export interface MountInfo {
+    path: string;
+    kind: string;
+    readOnly: boolean;
+}
+export interface ExportRootFilesystemOptions {
+    /** Maximum serialized snapshot bytes returned to this caller. */
+    maxBytes: number;
+}
+/** Portable, sidecar-owned dynamic mount descriptor. */
+export interface DynamicMountDescriptor {
+    path: string;
+    plugin: NativeMountPluginDescriptor;
+    readOnly?: boolean;
+}
+/** Callback-free options accepted by the portable spawn API. */
+export type SpawnOptions = Omit<KernelSpawnOptions, "onStdout" | "onStderr">;
+/** Callback-free options accepted by the portable openShell API. */
+export type ShellOptions = Omit<OpenShellOptions, "onStderr">;
 /** Options for readdirRecursive(). */
 export interface ReaddirRecursiveOptions {
     /** Maximum depth to recurse (0 = only immediate children). */
@@ -46,15 +102,13 @@ export interface BatchReadResult {
 /** 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 PackageDescriptor } from "./agentos-package.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 { SoftwareInput } from "./packages.js";
 import { type AgentOsSidecarPlacement } from "./sidecar/rpc-client.js";
 export interface AgentOsSharedSidecarOptions {
     pool?: string;
@@ -78,12 +132,28 @@ export interface AgentOsSidecarDescription {
 export type RootLowerInput = {
     kind: "bundled-base-filesystem";
 } | RootSnapshotExport;
-export interface RootFilesystemConfig {
+export interface OverlayRootFilesystemConfig {
     type?: "overlay";
     mode?: OverlayFilesystemMode;
     disableDefaultBaseLayer?: boolean;
     lowers?: RootLowerInput[];
 }
+/** Declarative sidecar-native root filesystem. */
+export interface NativeRootFilesystemConfig {
+    type: "native";
+    plugin: NativeMountPluginDescriptor;
+    readOnly?: boolean;
+}
+export type RootFilesystemConfig = OverlayRootFilesystemConfig | NativeRootFilesystemConfig;
+/** VM-scoped SQLite storage shared by VFS and AgentOS durable state. */
+export type VmSqliteConfig = {
+    type: "actor_uds";
+    path: string;
+    token: string;
+} | {
+    type: "sqlite_file";
+    path: string;
+};
 /**
  * Compatibility path for arbitrary caller-supplied filesystems.
  * This maps to the sidecar `js_bridge` plugin during the migration.
@@ -93,6 +163,10 @@ export interface PlainMountConfig {
     path: string;
     /** The filesystem driver to mount. */
     driver: VirtualFileSystem;
+    /** Filesystem type exposed through guest mount discovery. */
+    guestFstype?: string;
+    /** Source name exposed through guest mount discovery. */
+    guestSource?: string;
     /** If true, write operations throw EROFS. */
     readOnly?: boolean;
 }
@@ -100,6 +174,10 @@ export interface PlainMountConfig {
 export interface NativeMountConfig {
     path: string;
     plugin: NativeMountPluginDescriptor;
+    /** Filesystem type exposed through guest mount discovery. */
+    guestFstype?: string;
+    /** Source name exposed through guest mount discovery. */
+    guestSource?: string;
     readOnly?: boolean;
 }
 export interface OverlayMountConfig {
@@ -145,33 +223,50 @@ export interface AgentOsLimits {
     };
     /** HTTP body buffering limits. */
     http?: {
-        /** Cap on `vm.fetch()` buffered response bodies. Must be <= the sidecar wire frame cap. */
+        /** Cap on `vm.httpRequest()` 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;
+    /** Host binding registration and invocation limits. */
+    bindings?: {
+        defaultBindingTimeoutMs?: number;
+        maxBindingTimeoutMs?: number;
+        maxRegisteredCollections?: number;
+        maxRegisteredCollectionsPerVm?: number;
+        maxBindingsPerCollection?: number;
+        maxBindingSchemaBytes?: number;
+        maxExamplesPerBinding?: number;
+        maxBindingExampleInputBytes?: number;
     };
     /** Mount plugin manifest size limits. */
     plugins?: {
         maxPersistedManifestBytes?: number;
         maxPersistedManifestFileBytes?: number;
     };
-    /** ACP adapter buffering limits. */
+    /** ACP adapter, active-turn, history-retention, and page limits. */
     acp?: {
         maxReadLineBytes?: number;
         stdoutBufferByteLimit?: number;
+        maxCompletedMessageBytes?: number;
+        maxTurnOutputBytes?: number;
+        maxPromptBytes?: number;
+        maxPromptBlocks?: number;
+        maxFallbackContinuationBytes?: number;
+        maxSessionHistoryBytes?: number;
+        maxSessionHistoryEvents?: number;
+        maxHistoryPageEntries?: number;
+        maxSessionListEntries?: number;
+    };
+    /** Shared local-file/actor-UDS SQLite result materialization limit. */
+    sqlite?: {
+        maxResultBytes?: number;
     };
     /** Guest JavaScript runtime buffering limits. */
     jsRuntime?: {
         v8HeapLimitMb?: number;
+        syncRpcWaitTimeoutMs?: number;
+        cpuTimeLimitMs?: number;
+        wallClockLimitMs?: number;
+        importCacheMaterializeTimeoutMs?: number;
         capturedOutputLimitBytes?: number;
         stdinBufferLimitBytes?: number;
         eventPayloadLimitBytes?: number;
@@ -181,6 +276,7 @@ export interface AgentOsLimits {
     python?: {
         outputBufferMaxBytes?: number;
         executionTimeoutMs?: number;
+        maxOldSpaceMb?: number;
         vfsRpcTimeoutMs?: number;
     };
     /** Guest WASM runtime limits. */
@@ -188,15 +284,85 @@ export interface AgentOsLimits {
         maxModuleFileBytes?: number;
         capturedOutputLimitBytes?: number;
         syncReadLimitBytes?: number;
+        prewarmTimeoutMs?: number;
+        runnerHeapLimitMb?: number;
+        runnerCpuTimeLimitMs?: number;
     };
+    /** Process spawn, I/O, and lifecycle-event backlog limits. */
+    process?: {
+        maxSpawnFileActions?: number;
+        maxSpawnFileActionBytes?: number;
+        pendingStdinBytes?: number;
+        pendingEventCount?: number;
+        pendingEventBytes?: number;
+    };
+}
+export interface AgentStderrEvent {
+    sessionId: string;
+    agentType: string;
+    processId: string;
+    pid: number | null;
+    chunk: Uint8Array;
+}
+export type AgentStderrHandler = (event: AgentStderrEvent) => void;
+/**
+ * Restart disposition reported on an {@link AgentExitEvent}. AgentOS never
+ * respawns an adapter or replays an interrupted request implicitly.
+ */
+export type AgentRestartOutcome = "not_attempted";
+/**
+ * An unexpected ACP adapter process exit — a crash from the host's
+ * perspective (any spontaneous exit before `unloadSession()`, including exit
+ * code 0). The live route is evicted and must be restored explicitly.
+ */
+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;
+    /** Always `"not_attempted"`; AgentOS does not restart adapters implicitly. */
+    restart: AgentRestartOutcome;
+    /** Always zero. */
+    restartCount: number;
+    /** Always zero. */
+    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 TypeScript
+ * Rivet actor accepts this surface directly alongside ordinary actor options.
+ */
 export interface AgentOsOptions {
+    /** Initial virtual Linux credentials and account record. Defaults to `1000:1000` (`agentos`). */
+    user?: VmUserConfig;
     /**
-     * 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,21 +380,24 @@ 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;
+    /** Durable SQLite storage for VM-owned filesystem and session state. */
+    database?: VmSqliteConfig;
     /** 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[];
+    /** Host-side bindings available to agents inside the VM. */
+    bindings?: Bindings[];
     /**
      * Custom permission policy for the kernel. Controls access to filesystem,
      * network, child process, and environment operations. Defaults to allowAll.
@@ -244,86 +413,33 @@ 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 unexpectedly.
+     * The sidecar evicts the live
+     * route and never retries the adapter or interrupted request implicitly.
+     * 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 {
-    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;
@@ -335,10 +451,8 @@ export interface SpawnedProcessInfo {
 export declare class AgentOs {
     #private;
     readonly sidecar: AgentOsSidecar;
-    private _sessions;
-    private _closedSessionIds;
-    private _sessionClosePromises;
-    private _pendingSessionRequestResolvers;
+    private _durableSessionEventHandlers;
+    private _agentExitHandlers;
     private _processes;
     private _shells;
     private _closedShellIds;
@@ -347,10 +461,9 @@ export declare class AgentOs {
     private _acpTerminals;
     private _acpTerminalCounter;
     private _softwareRoots;
-    private _softwareAgentConfigs;
     private _cronManager;
-    private _toolKits;
-    private _toolReference;
+    private _bindings;
+    private _bindingReference;
     private _permissions;
     private _hostMounts;
     private _env;
@@ -360,6 +473,9 @@ export declare class AgentOs {
     private readonly _sidecarSession;
     private readonly _sidecarVm;
     private readonly _disposeSidecarEventListener;
+    private readonly _agentStderrHandler?;
+    private readonly _agentExitHandler?;
+    private readonly _limitWarningHandler?;
     private constructor();
     static createSidecar(options?: AgentOsCreateSidecarOptions): Promise<AgentOsSidecar>;
     static getSharedSidecar(options?: AgentOsSharedSidecarOptions): Promise<AgentOsSidecar>;
@@ -367,25 +483,22 @@ export declare class AgentOs {
     exec(command: string, options?: KernelExecOptions): Promise<KernelExecResult>;
     execArgv(command: string, args?: readonly string[], options?: KernelExecOptions): Promise<KernelExecResult>;
     private _trackProcess;
-    spawn(command: string, args: string[], options?: KernelSpawnOptions): {
+    spawn(command: string, args: string[], options?: SpawnOptions): {
         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;
-    /** 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;
+    closeProcessStdin(pid: number): Promise<void>;
+    /** Subscribe to stdout and stderr from a process. */
+    onProcessOutput(pid: number, handler: (event: ProcessOutput) => void): () => void;
     /** Subscribe to process exit. Returns an unsubscribe function. */
-    onProcessExit(pid: number, handler: (exitCode: number) => void): () => void;
+    onProcessExit(pid: number, handler: (event: ProcessExit) => 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[]>;
@@ -396,29 +509,49 @@ export declare class AgentOs {
         recursive?: boolean;
     }): Promise<void>;
     readdir(path: string): Promise<string[]>;
+    readdirEntries(path: string): Promise<ReaddirEntry[]>;
     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;
+    exportRootFilesystem(options: ExportRootFilesystemOptions): 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(descriptor: DynamicMountDescriptor): Promise<void>;
+    unmountFs(path: string): Promise<void>;
+    listMounts(): Promise<MountInfo[]>;
     move(from: string, to: string): Promise<void>;
-    delete(path: string, options?: {
+    remove(path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
-    fetch(port: number, request: Request): Promise<Response>;
-    openShell(options?: OpenShellOptions): {
+    httpRequest(request: HttpRequest): Promise<HttpResponse>;
+    openShell(options?: ShellOptions): {
         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;
+    writeShell(shellId: string, data: string | Uint8Array): Promise<void>;
+    /**
+     * Subscribe to ordered PTY output (stdout and stderr). Returns an unsubscribe
+     * function. `OpenShellOptions.onStderr` is a diagnostic tap for callers that
+     * need channel identity; do not render both surfaces.
+     */
+    onShellData(shellId: string, handler: (event: ShellData) => void): () => void;
+    /** Subscribe to the stderr-only diagnostic stream for a shell. */
+    onShellStderr(shellId: string, handler: (event: ShellData) => void): () => void;
+    /** Subscribe to shell exit. */
+    onShellExit(shellId: string, handler: (event: ShellExit) => void): () => void;
     /** Notify a shell of terminal resize. */
     resizeShell(shellId: string, cols: number, rows: number): void;
+    /**
+     * Wait for a shell to exit and return its process exit code. Resolves
+     * immediately for a shell that has already exited (within the closed-shell
+     * retention window).
+     */
+    waitShell(shellId: string): Promise<number>;
     /** Kill a shell process and remove it from tracking. */
     closeShell(shellId: string): void;
     private _resolveVmPathToHostPath;
@@ -434,73 +567,50 @@ export declare class AgentOs {
     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>;
+    openSession(input: OpenSessionInput): Promise<void>;
+    getSession(input?: SessionTarget): Promise<DurableSessionInfo>;
+    listSessions(input?: ListSessionsInput): Promise<SessionPage>;
+    deleteSession(input?: SessionTarget): Promise<void>;
+    unloadSession(input?: SessionTarget): Promise<void>;
+    prompt(input: PromptInput): Promise<DurablePromptResult>;
+    cancelPrompt(input?: SessionTarget): Promise<CancelPromptResult>;
+    respondPermission(input: PermissionResponse): Promise<PermissionResponseResult>;
+    readHistory(input?: ReadHistoryInput): Promise<HistoryPage>;
+    getSessionConfig(input?: SessionTarget): Promise<SessionConfig>;
+    setSessionConfigOption(input: SetSessionConfigOptionInput): Promise<SessionConfig>;
+    getSessionCapabilities(input?: SessionTarget): Promise<SessionCapabilities | null>;
+    getSessionAgentInfo(input?: SessionTarget): Promise<SessionAgentInfo | null>;
     /**
-     * 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.
+     * 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 `openSession({ agent: name })`. Persists for the VM's
+     * lifetime (and across a snapshot iff the volume persists).
      */
-    private _resolveAdapterBin;
+    linkSoftware(descriptor: PackageDescriptor): Promise<void>;
+    listSoftware(): Promise<{
+        packageName: string;
+        commands: string[];
+    }[]>;
     /**
-     * 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).
+     * 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`.
      */
-    private _nodeModulesHostRoot;
-    private _resolvePackageBin;
+    listAgents(): Promise<AgentRegistryEntry[]>;
+    private _recordAgentStderr;
+    private _recordAgentExit;
+    private _handleSidecarEvent;
+    private _handleLimitWarning;
+    private _handleAcpExtEvent;
+    private _emitDurableSessionEvent;
+    private _sendAcpRequest;
     private _installSidecarRequestHandler;
     private _handleAcpExtSidecarRequest;
     private _dispatchAcpSidecarRequest;
     private _handleSupportedAcpSidecarRequest;
-    private _normalizeAcpPermissionOptionId;
-    private _buildAcpPermissionResult;
-    private _handleAcpPermissionRequest;
     private _acpParams;
     private _requireAcpStringParam;
     private _optionalAcpStringParam;
@@ -519,34 +629,11 @@ export declare class AgentOs {
     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;
+    onSessionEvent(handler: (entry: SessionStreamEntry) => void): () => void;
+    onSessionEvent(sessionId: string | undefined, handler: (entry: SessionStreamEntry) => void): () => void;
+    /** Subscribe to unexpected adapter exits without changing session liveness. */
+    onAgentExit(handler: AgentExitHandler): () => void;
+    onAgentExit(sessionId: string | undefined, handler: AgentExitHandler): () => 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. */