@rivet-dev/agentos-core 0.0.0-codex-actor-plugin-contract-coverage.c7d8f87 → 0.0.0-fix-main-wasm-ownership.150c49a

package/dist/agent-os.d.ts

@@ -1,13 +1,11 @@
 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 { JsonRpcResponse } from "./json-rpc.js";
+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 "@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";
+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). */
@@ -47,15 +103,12 @@ export interface BatchReadResult {
 export interface AgentRegistryEntry {
     id: string;
     installed: boolean;
-    /** Guest entrypoint the sidecar launches for this agent (`/opt/agentos/bin/<acpEntrypoint>`). */
-    adapterEntrypoint: string;
 }
-import type { AgentType } from "./types.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 PackageRef, type SoftwarePackageRef } from "./agentos-package.js";
+import type { SoftwareInput } from "./packages.js";
 import { type AgentOsSidecarPlacement } from "./sidecar/rpc-client.js";
 export interface AgentOsSharedSidecarOptions {
     pool?: string;
@@ -79,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.
@@ -94,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;
 }
@@ -101,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 {
@@ -146,29 +223,42 @@ 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?: {
@@ -196,6 +286,15 @@ export interface AgentOsLimits {
         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 {
@@ -207,20 +306,14 @@ export interface AgentStderrEvent {
 }
 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.
+ * Restart disposition reported on an {@link AgentExitEvent}. AgentOS never
+ * respawns an adapter or replays an interrupted request implicitly.
  */
-export type AgentRestartOutcome = "restarted" | "unsupported" | "failed" | "exhausted";
+export type AgentRestartOutcome = "not_attempted";
 /**
  * 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.
+ * 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;
@@ -230,11 +323,11 @@ export interface AgentExitEvent {
     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. */
+    /** Always `"not_attempted"`; AgentOS does not restart adapters implicitly. */
     restart: AgentRestartOutcome;
-    /** Restarts consumed for this session so far. */
+    /** Always zero. */
     restartCount: number;
-    /** Per-session restart budget. */
+    /** Always zero. */
     maxRestarts: number;
 }
 export type AgentExitHandler = (event: AgentExitEvent) => void;
@@ -261,11 +354,12 @@ 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`.
+ * `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 is a package-dir ref. Arrays are
      * flattened, so meta-packages that export arrays of sub-packages work directly.
@@ -294,16 +388,16 @@ export interface AgentOsOptions {
      * 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[];
-    /** 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.
@@ -327,12 +421,10 @@ export interface AgentOsOptions {
      */
     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`.
+     * 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;
     /**
@@ -342,85 +434,12 @@ export interface AgentOsOptions {
      */
     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 `/workspace`). */
-    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;
@@ -432,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;
@@ -445,13 +462,12 @@ export declare class AgentOs {
     private _acpTerminalCounter;
     private _softwareRoots;
     private _cronManager;
-    private _toolKits;
-    private _toolReference;
+    private _bindings;
+    private _bindingReference;
     private _permissions;
     private _hostMounts;
     private _env;
     private _rootFilesystem;
-    private readonly _additionalInstructions;
     private _sidecarLease;
     private readonly _sidecarClient;
     private readonly _sidecarSession;
@@ -467,19 +483,17 @@ 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): Promise<void>;
     /** Close a process's stdin stream. */
     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. */
-    onProcessStderr(pid: number, handler: (data: Uint8Array) => void): () => 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;
@@ -495,27 +509,41 @@ 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): Promise<void>;
-    /** Subscribe to data output from a shell. Returns an unsubscribe function. */
-    onShellData(shellId: string, handler: (data: Uint8Array) => void): () => 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;
     /**
@@ -539,20 +567,29 @@ 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;
+    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>;
     /**
      * 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
+     * block registers the package for `openSession({ agent: name })`. Persists for the VM's
      * lifetime (and across a snapshot iff the volume persists).
      */
-    linkSoftware(descriptor: PackageRef | SoftwarePackageRef): Promise<void>;
-    providedCommands(): Promise<{
+    linkSoftware(descriptor: PackageDescriptor): Promise<void>;
+    listSoftware(): Promise<{
         packageName: string;
         commands: string[];
     }[]>;
@@ -563,71 +600,17 @@ export declare class AgentOs {
      * agent is a package materialized into the VM, so `installed` is always `true`.
      */
     listAgents(): Promise<AgentRegistryEntry[]>;
-    private _syncSessionState;
-    private _applySessionUpdate;
-    private _recordSessionNotification;
-    private _dispatchSessionEvent;
-    private _subscribeSessionEvents;
-    /**
-     * 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 _applySyntheticConfigOverrides;
     private _handleSidecarEvent;
     private _handleLimitWarning;
     private _handleAcpExtEvent;
-    private _unsupportedConfigResponse;
+    private _emitDurableSessionEvent;
     private _sendAcpRequest;
-    private _sendSessionRequest;
-    private _setSessionConfigByCategory;
-    private _removeSession;
-    private _abortPendingSessionRequests;
-    private _cancelPendingPromptRequests;
-    private _rejectPendingPermissionReplies;
-    private _rejectPendingPermissionRepliesFromSession;
-    private _closeSessionInternal;
-    private _hydrateSessionState;
-    createSession(agentType: AgentType, 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, options?: ResumeSessionOptions): Promise<ResumeSessionResult>;
     private _installSidecarRequestHandler;
     private _handleAcpExtSidecarRequest;
     private _dispatchAcpSidecarRequest;
     private _handleSupportedAcpSidecarRequest;
-    private _normalizeAcpPermissionOptionId;
-    private _buildAcpPermissionResult;
-    private _handleAcpPermissionRequest;
     private _acpParams;
     private _requireAcpStringParam;
     private _optionalAcpStringParam;
@@ -646,29 +629,11 @@ export declare class AgentOs {
     private _handleAcpKillTerminal;
     private _handleAcpReleaseTerminal;
     private _handleAcpResizeTerminal;
-    private _handleAcpPermissionCallback;
-    /**
-     * 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. */