@rivet-dev/agentos-core 0.0.0-main.2f99c77 → 0.0.0-main.5ac5a14

package/dist/agent-os.d.ts

@@ -1,15 +1,16 @@
 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 { ConnectTerminalOptions, Kernel, KernelExecOptions, KernelExecResult, ProcessInfo as KernelProcessInfo, KernelSpawnOptions, OpenShellOptions, Permissions, VirtualFileSystem, VirtualStat } from "./runtime-compat.js";
+import type { VmUserConfig } from "@rivet-dev/agentos-runtime-core/vm-config";
+import { type Bindings } from "./bindings.js";
+import type { CodeEvaluationResult, CodeExecutionResult, ContextDescriptor, ExecutionSignal, InlineExecutionOptions, JavaScriptEvaluationOptions, JavaScriptExecutionOptions, LanguageExecutionOptions, LanguageSpawnOptions, NpmPackageInstallOptions, NpmProjectInstallOptions, OutputReplay, ProcessDescriptor, ProcessExit, PythonInstallOptions, SpawnOptions, TypeScriptCheckOptions, TypeScriptCheckResult, TypeScriptEvaluationOptions, TypeScriptExecutionOptions, TypeScriptFileExecutionOptions } from "./language-execution.js";
+import type { ConnectTerminalOptions, Kernel, KernelExecOptions, KernelExecResult, OpenShellOptions, Permissions, VirtualFileSystem, VirtualStat } from "./runtime-compat.js";
+import { type AgentOsSandboxInput } from "./sandbox.js";
+import type { CancelPromptResult, PromptResult as DurablePromptResult, SessionInfo as DurableSessionInfo, HistoryPage, JsonValue, ListSessionsInput, OpenSessionInput, PermissionResponse, PermissionResponseResult, PromptInput, ReadHistoryInput, SessionAgentInfo, SessionCapabilities, SessionConfig, SessionPage, SessionStreamEntry, SessionTarget, SetSessionConfigOptionInput } from "./session-api.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 {
+export type * from "./session-api.js";
+/** Process tree node using the same descriptor shape as process.get/list. */
+export interface ProcessTreeNode extends ProcessDescriptor {
+    ppid?: number;
     children: ProcessTreeNode[];
 }
 /** A directory entry with metadata. */
@@ -19,6 +20,58 @@ 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 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 openShell API. */
+export type ShellOptions = Omit<OpenShellOptions, "onStderr">;
 /** Options for readdirRecursive(). */
 export interface ReaddirRecursiveOptions {
     /** Maximum depth to recurse (0 = only immediate children). */
@@ -47,15 +100,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 +129,27 @@ 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;
+} | {
+    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 +159,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 +170,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 +219,46 @@ 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;
+    /** TLS plaintext buffering limits. */
+    tls?: {
+        maxBufferedBytes?: number;
+    };
+    /** Host binding registration and invocation limits. */
+    bindings?: {
+        defaultBindingTimeoutMs?: number;
+        maxBindingTimeoutMs?: number;
+        maxRegisteredCollections?: number;
+        maxRegisteredBindingsPerVm?: 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,18 @@ 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;
+    /** External sandbox mounted into this VM with process bindings. */
+    sandbox?: AgentOsSandboxInput;
     /** 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 +423,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,101 +436,22 @@ 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;
-    command: string;
-    args: string[];
-    running: boolean;
-    exitCode: number | null;
-}
 export declare class AgentOs {
     #private;
     readonly sidecar: AgentOsSidecar;
-    private _sessions;
-    private _closedSessionIds;
-    private _sessionClosePromises;
-    private _pendingSessionRequestResolvers;
+    private _durableSessionEventHandlers;
+    private _agentExitHandlers;
     private _processes;
+    private _languageProcesses;
+    private _languageProcessIds;
+    private _executionOutputHandlers;
+    private _executionCompletedHandlers;
     private _shells;
     private _closedShellIds;
     private _pendingShellExitPromises;
@@ -445,13 +460,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;
@@ -460,180 +474,415 @@ export declare class AgentOs {
     private readonly _agentStderrHandler?;
     private readonly _agentExitHandler?;
     private readonly _limitWarningHandler?;
+    private readonly _disposeHooks;
+    /**
+     * Execute commands and manage child processes in the VM.
+     *
+     * `exec` evaluates a command with the configured shell, while `execFile`
+     * invokes an executable directly with an argv array.
+     */
+    readonly process: {
+        exec: (command: string, options?: LanguageExecutionOptions) => Promise<CodeExecutionResult>;
+        execFile: (command: string, args?: readonly string[], options?: Omit<LanguageExecutionOptions, "args">) => Promise<CodeExecutionResult>;
+        spawn: (command: string, args?: string[], options?: SpawnOptions) => Promise<ProcessDescriptor>;
+        get: (pid: number) => Promise<ProcessDescriptor>;
+        list: () => Promise<ProcessDescriptor[]>;
+        tree: () => Promise<ProcessTreeNode[]>;
+        wait: (pid: number) => Promise<ProcessExit>;
+        signal: (pid: number, signal: ExecutionSignal) => Promise<void>;
+        kill: (pid: number) => Promise<void>;
+        writeStdin: (pid: number, data: string | Uint8Array) => Promise<void>;
+        closeStdin: (pid: number) => Promise<void>;
+        resizePty: (pid: number, size: {
+            cols: number;
+            rows: number;
+        }) => Promise<void>;
+        readOutput: (pid: number, options?: {
+            after?: number;
+        }) => Promise<OutputReplay>;
+    };
+    readonly javascript: {
+        execute: (source: string, options?: JavaScriptExecutionOptions) => Promise<CodeExecutionResult>;
+        evaluate: <T = JsonValue>(expression: string, options?: JavaScriptEvaluationOptions) => Promise<CodeEvaluationResult<T>>;
+        executeFile: (path: string, options?: LanguageExecutionOptions) => Promise<CodeExecutionResult>;
+        spawn: (source: string, options?: LanguageSpawnOptions) => Promise<ProcessDescriptor>;
+        spawnFile: (path: string, options?: LanguageSpawnOptions) => Promise<ProcessDescriptor>;
+        npm: {
+            install: {
+                (options?: NpmProjectInstallOptions): Promise<CodeExecutionResult>;
+                (packages: string | string[], options?: NpmPackageInstallOptions): Promise<CodeExecutionResult>;
+            };
+            runScript: (script: string, options?: LanguageExecutionOptions) => Promise<CodeExecutionResult>;
+            runPackage: (packageSpec: string, options?: LanguageExecutionOptions & {
+                binary?: string;
+            }) => Promise<CodeExecutionResult>;
+        };
+    };
+    readonly typescript: {
+        execute: (source: string, options?: TypeScriptExecutionOptions) => Promise<CodeExecutionResult>;
+        evaluate: <T = JsonValue>(expression: string, options?: TypeScriptEvaluationOptions) => Promise<CodeEvaluationResult<T>>;
+        executeFile: (path: string, options?: TypeScriptFileExecutionOptions) => Promise<CodeExecutionResult>;
+        spawn: (source: string, options?: LanguageSpawnOptions) => Promise<ProcessDescriptor>;
+        spawnFile: (path: string, options?: LanguageSpawnOptions) => Promise<ProcessDescriptor>;
+        check: (source: string, options?: TypeScriptCheckOptions) => Promise<TypeScriptCheckResult>;
+        checkProject: (options?: Omit<TypeScriptCheckOptions, "filePath" | "compilerOptions">) => Promise<TypeScriptCheckResult>;
+    };
+    readonly python: {
+        execute: (source: string, options?: InlineExecutionOptions) => Promise<CodeExecutionResult>;
+        evaluate: <T = JsonValue>(expression: string, options?: InlineExecutionOptions) => Promise<CodeEvaluationResult<T>>;
+        executeFile: (path: string, options?: LanguageExecutionOptions) => Promise<CodeExecutionResult>;
+        executeModule: (module: string, options?: LanguageExecutionOptions) => Promise<CodeExecutionResult>;
+        spawn: (source: string, options?: LanguageSpawnOptions) => Promise<ProcessDescriptor>;
+        spawnFile: (path: string, options?: LanguageSpawnOptions) => Promise<ProcessDescriptor>;
+        spawnModule: (module: string, options?: LanguageSpawnOptions) => Promise<ProcessDescriptor>;
+        install: {
+            (options?: PythonInstallOptions): Promise<CodeExecutionResult>;
+            (packages: string | string[], options?: PythonInstallOptions): Promise<CodeExecutionResult>;
+        };
+    };
+    readonly contexts: {
+        get: (contextId: string) => Promise<ContextDescriptor>;
+        list: () => Promise<ContextDescriptor[]>;
+        reset: (contextId: string) => Promise<void>;
+        delete: (contextId: string) => Promise<void>;
+    };
+    readonly terminal: {
+        open: (options?: ShellOptions) => {
+            shellId: string;
+        };
+        write: (shellId: string, data: string | Uint8Array) => Promise<void>;
+        resize: (shellId: string, cols: number, rows: number) => void;
+        wait: (shellId: string) => Promise<number>;
+        close: (shellId: string) => void;
+    };
+    readonly filesystem: {
+        readFile: (path: string) => Promise<Uint8Array>;
+        writeFile: (path: string, content: string | Uint8Array) => Promise<void>;
+        readFiles: (paths: string[]) => Promise<BatchReadResult[]>;
+        writeFiles: (entries: BatchWriteEntry[]) => Promise<BatchWriteResult[]>;
+        stat: (path: string) => Promise<VirtualStat>;
+        mkdir: (path: string, options?: {
+            recursive?: boolean;
+        }) => Promise<void>;
+        readdir: (path: string) => Promise<string[]>;
+        readdirEntries: (path: string) => Promise<ReaddirEntry[]>;
+        readdirRecursive: (path: string, options?: ReaddirRecursiveOptions) => Promise<DirEntry[]>;
+        exists: (path: string) => Promise<boolean>;
+        move: (from: string, to: string) => Promise<void>;
+        remove: (path: string, options?: {
+            recursive?: boolean;
+        }) => Promise<void>;
+        export: (options: ExportRootFilesystemOptions) => Promise<RootSnapshotExport>;
+        mount: (descriptor: DynamicMountDescriptor) => Promise<void>;
+        unmount: (path: string) => Promise<void>;
+        listMounts: () => Promise<MountInfo[]>;
+    };
+    readonly network: {
+        httpRequest: (request: HttpRequest) => Promise<HttpResponse>;
+    };
+    readonly software: {
+        list: () => Promise<{
+            packageName: string;
+            commands: string[];
+        }[]>;
+        link: (descriptor: PackageDescriptor) => Promise<void>;
+    };
+    readonly agents: {
+        list: () => Promise<AgentRegistryEntry[]>;
+    };
+    readonly sessions: {
+        open: (input: OpenSessionInput) => Promise<void>;
+        get: (input?: SessionTarget) => Promise<DurableSessionInfo>;
+        list: (input?: ListSessionsInput) => Promise<SessionPage>;
+        delete: (input?: SessionTarget) => Promise<void>;
+        unload: (input?: SessionTarget) => Promise<void>;
+        prompt: (input: PromptInput) => Promise<DurablePromptResult>;
+        cancelPrompt: (input?: SessionTarget) => Promise<CancelPromptResult>;
+        respondPermission: (input: PermissionResponse) => Promise<PermissionResponseResult>;
+        readHistory: (input?: ReadHistoryInput) => Promise<HistoryPage>;
+        getConfig: (input?: SessionTarget) => Promise<SessionConfig>;
+        setConfigOption: (input: SetSessionConfigOptionInput) => Promise<SessionConfig>;
+        getCapabilities: (input?: SessionTarget) => Promise<SessionCapabilities | null>;
+        getAgentInfo: (input?: SessionTarget) => Promise<SessionAgentInfo | null>;
+    };
+    readonly cron: {
+        schedule: (options: CronJobOptions) => CronJob;
+        list: () => CronJobInfo[];
+        cancel: (id: string) => void;
+    };
     private constructor();
     static createSidecar(options?: AgentOsCreateSidecarOptions): Promise<AgentOsSidecar>;
     static getSharedSidecar(options?: AgentOsSharedSidecarOptions): Promise<AgentOsSidecar>;
     static create(options?: AgentOsOptions): Promise<AgentOs>;
+    createContext(contextId: string): Promise<void>;
+    private _executionOperation;
+    private _spawnLanguageOperation;
+    private _exec;
+    private _execFile;
+    /** @deprecated Use `process.exec()` for lifecycle-aware execution. */
     exec(command: string, options?: KernelExecOptions): Promise<KernelExecResult>;
+    /** @deprecated Use `process.execFile()` for lifecycle-aware execution. */
     execArgv(command: string, args?: readonly string[], options?: KernelExecOptions): Promise<KernelExecResult>;
+    private _executeJavaScript;
+    private _evaluationOperation;
+    private _evaluateJavaScript;
+    private _executeJavaScriptFile;
+    private _spawnJavaScript;
+    private _spawnJavaScriptFile;
+    private _executeTypeScript;
+    private _evaluateTypeScript;
+    private _executeTypeScriptFile;
+    private _spawnTypeScript;
+    private _spawnTypeScriptFile;
+    private _checkTypeScript;
+    private _checkTypeScriptProject;
+    private _installNpmPackages;
+    private _executeNpmScript;
+    private _executeNpmPackage;
+    private _executePython;
+    private _evaluatePython;
+    private _executePythonFile;
+    private _executePythonModule;
+    private _spawnPython;
+    private _spawnPythonFile;
+    private _spawnPythonModule;
+    private _installPythonPackages;
+    private _getContext;
+    private _listContexts;
+    private _waitExecutionResult;
+    private _cancelExecution;
+    private _signalExecution;
+    private _resetContext;
+    private _descriptorLifecycleRequest;
+    private _deleteContext;
+    private _writeExecutionStdin;
+    private _closeExecutionStdin;
+    private _resizeExecutionPty;
+    private _readExecutionOutput;
+    private _onExecutionOutput;
+    private _onExecutionCompleted;
     private _trackProcess;
-    spawn(command: string, args: string[], options?: KernelSpawnOptions): {
-        pid: number;
-    };
+    private _spawnProcess;
+    spawn(command: string, args?: string[], options?: SpawnOptions): Promise<ProcessDescriptor>;
     /** Write data to a process's stdin. */
-    writeProcessStdin(pid: number, data: string | Uint8Array): Promise<void>;
+    private _writeProcessStdin;
     /** 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;
+    private _closeProcessStdin;
+    /** 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 _waitProcess;
     private _assertSafeAbsolutePath;
     private _assertWritableAbsolutePath;
     private _vfs;
+    private _readFile;
+    private _writeFile;
+    private _writeFiles;
+    private _readFiles;
+    /** Recursively create directories (mkdir -p). */
+    private _mkdirp;
+    private _mkdir;
+    private _readdir;
+    private _readdirEntries;
+    private _readdirRecursive;
+    private _stat;
+    private _exists;
+    private _exportRootFilesystem;
+    /**
+     * 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.
+     */
+    private _mountFs;
+    private _unmountFs;
+    private _listMounts;
+    private _move;
+    private _remove;
+    /** @deprecated Use `filesystem.readFile()`. */
     readFile(path: string): Promise<Uint8Array>;
+    /** @deprecated Use `filesystem.writeFile()`. */
     writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    /** @deprecated Use `filesystem.writeFiles()`. */
     writeFiles(entries: BatchWriteEntry[]): Promise<BatchWriteResult[]>;
+    /** @deprecated Use `filesystem.readFiles()`. */
     readFiles(paths: string[]): Promise<BatchReadResult[]>;
-    /** Recursively create directories (mkdir -p). */
-    private _mkdirp;
+    /** @deprecated Use `filesystem.mkdir()`. */
     mkdir(path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
+    /** @deprecated Use `filesystem.readdir()`. */
     readdir(path: string): Promise<string[]>;
+    /** @deprecated Use `filesystem.readdirEntries()`. */
+    readdirEntries(path: string): Promise<ReaddirEntry[]>;
+    /** @deprecated Use `filesystem.readdirRecursive()`. */
     readdirRecursive(path: string, options?: ReaddirRecursiveOptions): Promise<DirEntry[]>;
+    /** @deprecated Use `filesystem.stat()`. */
     stat(path: string): Promise<VirtualStat>;
+    /** @deprecated Use `filesystem.exists()`. */
     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;
-    }): Promise<void>;
+    /** @deprecated Use `filesystem.export()`. */
+    exportRootFilesystem(options: ExportRootFilesystemOptions): Promise<RootSnapshotExport>;
+    /** @deprecated Use `filesystem.mount()`. */
+    mountFs(descriptor: DynamicMountDescriptor): Promise<void>;
+    /** @deprecated Use `filesystem.unmount()`. */
     unmountFs(path: string): Promise<void>;
+    /** @deprecated Use `filesystem.listMounts()`. */
+    listMounts(): Promise<MountInfo[]>;
+    /** @deprecated Use `filesystem.move()`. */
     move(from: string, to: string): Promise<void>;
-    delete(path: string, options?: {
+    /** @deprecated Use `filesystem.remove()`. */
+    remove(path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
+    private _httpRequest;
+    /** @deprecated Use `network.httpRequest()`. */
+    httpRequest(request: HttpRequest): Promise<HttpResponse>;
+    /**
+     * Fetch an HTTP endpoint inside the VM while preserving duplicate response
+     * headers and arbitrary binary bodies. agentOS Apps uses this compatibility
+     * surface for its direct actor API.
+     */
     fetch(port: number, request: Request): Promise<Response>;
-    openShell(options?: OpenShellOptions): {
-        shellId: string;
-    };
+    fetchStreamStart(port: number, request: Request): Promise<{
+        streamId: string;
+        status: number;
+        statusText: string;
+        headers: Array<[string, string]>;
+    }>;
+    fetchStreamRead(streamId: string, maxBytes?: number): Promise<{
+        body: Uint8Array;
+        done: boolean;
+    }>;
+    fetchStreamCancel(streamId: string): Promise<void>;
+    private _openTerminal;
     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;
+    private _writeTerminal;
+    /**
+     * 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;
+    private _resizeTerminal;
     /**
      * 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>;
+    private _waitTerminal;
     /** Kill a shell process and remove it from tracking. */
+    private _closeTerminal;
+    /** @deprecated Use `terminal.open()`. */
+    openShell(options?: ShellOptions): {
+        shellId: string;
+    };
+    /** @deprecated Use `terminal.write()`. */
+    writeShell(shellId: string, data: string | Uint8Array): Promise<void>;
+    /** @deprecated Use `terminal.resize()`. */
+    resizeShell(shellId: string, cols: number, rows: number): void;
+    /** @deprecated Use `terminal.wait()`. */
+    waitShell(shellId: string): Promise<number>;
+    /** @deprecated Use `terminal.close()`. */
     closeShell(shellId: string): void;
     private _resolveVmPathToHostPath;
     /** Returns info about all processes spawned via spawn(). */
-    listProcesses(): SpawnedProcessInfo[];
+    private _listProcesses;
     /** Returns all kernel processes across all active runtimes (WASM and Node). */
-    allProcesses(): KernelProcessInfo[];
+    private _listAllProcesses;
     /** Returns processes organized as a tree using ppid relationships. */
-    processTree(): ProcessTreeNode[];
+    private _processTree;
     /** Returns info about a specific process by PID. Throws if not found. */
-    getProcess(pid: number): SpawnedProcessInfo;
-    /** Send SIGTERM to gracefully stop a process. No-op if already exited. */
-    stopProcess(pid: number): void;
+    private _getProcess;
+    private _signalProcess;
     /** 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;
+    private _killProcess;
+    private _resizeProcessPty;
+    private _readProcessOutput;
+    private _openSession;
+    private _getSession;
+    private _listSessions;
+    private _deleteSession;
+    private _unloadSession;
+    private _prompt;
+    private _cancelPrompt;
+    private _respondPermission;
+    private _readHistory;
+    private _getSessionConfig;
+    private _setSessionConfigOption;
+    private _getSessionCapabilities;
+    private _getSessionAgentInfo;
+    /** @deprecated Use `sessions.open()`. */
+    openSession(input: OpenSessionInput): Promise<void>;
+    /** @deprecated Use `sessions.get()`. */
+    getSession(input?: SessionTarget): Promise<DurableSessionInfo>;
+    /** @deprecated Use `sessions.list()`. */
+    listSessions(input?: ListSessionsInput): Promise<SessionPage>;
+    /** @deprecated Use `sessions.delete()`. */
+    deleteSession(input?: SessionTarget): Promise<void>;
+    /** @deprecated Use `sessions.unload()`. */
+    unloadSession(input?: SessionTarget): Promise<void>;
+    /** @deprecated Use `sessions.prompt()`. */
+    prompt(input: PromptInput): Promise<DurablePromptResult>;
+    /** @deprecated Use `sessions.cancelPrompt()`. */
+    cancelPrompt(input?: SessionTarget): Promise<CancelPromptResult>;
+    /** @deprecated Use `sessions.respondPermission()`. */
+    respondPermission(input: PermissionResponse): Promise<PermissionResponseResult>;
+    /** @deprecated Use `sessions.readHistory()`. */
+    readHistory(input?: ReadHistoryInput): Promise<HistoryPage>;
+    /** @deprecated Use `sessions.getConfig()`. */
+    getSessionConfig(input?: SessionTarget): Promise<SessionConfig>;
+    /** @deprecated Use `sessions.setConfigOption()`. */
+    setSessionConfigOption(input: SetSessionConfigOptionInput): Promise<SessionConfig>;
+    /** @deprecated Use `sessions.getCapabilities()`. */
+    getSessionCapabilities(input?: SessionTarget): Promise<SessionCapabilities | null>;
+    /** @deprecated Use `sessions.getAgentInfo()`. */
+    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<{
-        packageName: string;
-        commands: string[];
-    }[]>;
+    private _linkSoftware;
+    private _listSoftware;
     /**
      * 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 _listAgents;
+    /** @deprecated Use `software.link()`. */
+    linkSoftware(descriptor: PackageDescriptor): Promise<void>;
+    /** @deprecated Use `software.list()`. */
+    listSoftware(): Promise<{
+        packageName: string;
+        commands: string[];
+    }[]>;
+    /** @deprecated Use `agents.list()`. */
     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;
@@ -652,34 +901,22 @@ 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;
+    private _scheduleCron;
     /** List all registered cron jobs. */
-    listCronJobs(): CronJobInfo[];
+    private _listCronJobs;
     /** Cancel a cron job by ID. */
+    private _cancelCronJob;
+    /** @deprecated Use `cron.schedule()`. */
+    scheduleCron(options: CronJobOptions): CronJob;
+    /** @deprecated Use `cron.list()`. */
+    listCronJobs(): CronJobInfo[];
+    /** @deprecated Use `cron.cancel()`. */
     cancelCronJob(id: string): void;
     /** Subscribe to cron lifecycle events (fire, complete, error). */
     onCronEvent(handler: CronEventHandler): void;