@rivet-dev/agentos-core 0.0.0-nathan-binding-workspace.dd41c31 → 0.0.0-nathan-binding-workspace.806210d

package/README.md

@@ -25,10 +25,10 @@ npm install @rivet-dev/agentos-pi @mariozechner/pi-coding-agent
 ```
 
 ```typescript
-import { AgentOS } from "@rivet-dev/agentos-core";
+import { AgentOs } from "@rivet-dev/agentos-core";
 
 // 1. Create a VM
-const vm = await AgentOS.create();
+const vm = await AgentOs.create();
 
 // 2. Create an agent session
 const { sessionId } = await vm.createSession("pi");
@@ -47,17 +47,17 @@ await vm.dispose();
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `create` | `static create(options?: AgentOSOptions): Promise<AgentOS>` | Create and boot a new VM |
-| `getSharedSidecar` | `static getSharedSidecar(options?: AgentOSSharedSidecarOptions): Promise<AgentOSSidecar>` | Get or create a shared sidecar handle for a pool |
-| `createSidecar` | `static createSidecar(options?: AgentOSCreateSidecarOptions): Promise<AgentOSSidecar>` | Create an explicit sidecar handle |
+| `create` | `static create(options?: AgentOsOptions): Promise<AgentOs>` | Create and boot a new VM |
+| `getSharedSidecar` | `static getSharedSidecar(options?: AgentOsSharedSidecarOptions): Promise<AgentOsSidecar>` | Get or create a shared sidecar handle for a pool |
+| `createSidecar` | `static createSidecar(options?: AgentOsCreateSidecarOptions): Promise<AgentOsSidecar>` | Create an explicit sidecar handle |
 | `dispose` | `dispose(): Promise<void>` | Shut down the VM and all sessions |
 
 ### Sidecars
 
 | Surface | Signature | Description |
 |--------|-----------|-------------|
-| `sidecar` | `AgentOSSidecar` | Sidecar handle backing the VM |
-| `describe` | `sidecar.describe(): AgentOSSidecarDescription` | Inspect sidecar placement, state, and active VM count |
+| `sidecar` | `AgentOsSidecar` | Sidecar handle backing the VM |
+| `describe` | `sidecar.describe(): AgentOsSidecarDescription` | Inspect sidecar placement, state, and active VM count |
 | `dispose` | `sidecar.dispose(): Promise<void>` | Dispose the sidecar handle and any active VMs leased from it |
 
 ### Filesystem
@@ -142,14 +142,14 @@ await vm.dispose();
 ### Exported Types
 
 **VM & Options**
-- `AgentOSOptions` — VM creation options (commandDirs, loopbackExemptPorts, mounts, additionalInstructions). Use `nodeModulesMount(...)` in `mounts` to expose a host `node_modules` tree at `/root/node_modules`.
-- `AgentOSSidecarConfig` — shared-pool or explicit-handle sidecar selection for VM creation
-- `AgentOSSharedSidecarOptions` — shared sidecar pool selection
-- `AgentOSCreateSidecarOptions` — explicit sidecar handle creation options
+- `AgentOsOptions` — VM creation options (commandDirs, loopbackExemptPorts, mounts, additionalInstructions). Use `nodeModulesMount(...)` in `mounts` to expose a host `node_modules` tree at `/root/node_modules`.
+- `AgentOsSidecarConfig` — shared-pool or explicit-handle sidecar selection for VM creation
+- `AgentOsSharedSidecarOptions` — shared sidecar pool selection
+- `AgentOsCreateSidecarOptions` — explicit sidecar handle creation options
 - `CreateSessionOptions` — Session options (cwd, env, mcpServers, skipOsInstructions, additionalInstructions)
 
 **Sidecar**
-- `AgentOSSidecarDescription` — Sidecar identity, placement, lifecycle state, and active VM count
+- `AgentOsSidecarDescription` — Sidecar identity, placement, lifecycle state, and active VM count
 
 **Mount Configurations**
 - `MountConfig` — Union of all mount types

package/dist/{agentos.d.ts → agent-os.d.ts}

@@ -1,6 +1,6 @@
 import type { NativeMountPluginDescriptor } from "@secure-exec/core/descriptors";
 import type { AgentCapabilities, AgentInfo, PermissionReply, PermissionRequestHandler, SessionConfigOption, SessionEventHandler, SessionModeState } from "./agent-session-types.js";
-import { type Bindings } from "./bindings.js";
+import { type ToolKit } from "./host-tools.js";
 import type { JsonRpcResponse } from "./json-rpc.js";
 import type { ConnectTerminalOptions, Kernel, KernelExecOptions, KernelExecResult, ProcessInfo as KernelProcessInfo, KernelSpawnOptions, OpenShellOptions, Permissions, VirtualFileSystem, VirtualStat } from "./runtime-compat.js";
 export type { MountConfigJsonObject, MountConfigJsonPrimitive, MountConfigJsonValue, NativeMountPluginDescriptor, } from "@secure-exec/core/descriptors";
@@ -55,23 +55,23 @@ import type { ScheduleDriver } from "./cron/schedule-driver.js";
 import type { CronEventHandler, CronJob, CronJobInfo, CronJobOptions } from "./cron/types.js";
 import { type LayerStore, type OverlayFilesystemMode, type RootSnapshotExport, type SnapshotLayerHandle } from "./layers.js";
 import { type SoftwareInput } from "./packages.js";
-import { type AgentOSSidecarPlacement } from "./sidecar/rpc-client.js";
-export interface AgentOSSharedSidecarOptions {
+import { type AgentOsSidecarPlacement } from "./sidecar/rpc-client.js";
+export interface AgentOsSharedSidecarOptions {
     pool?: string;
 }
-export interface AgentOSCreateSidecarOptions {
+export interface AgentOsCreateSidecarOptions {
     sidecarId?: string;
 }
-export type AgentOSSidecarConfig = {
+export type AgentOsSidecarConfig = {
     kind: "shared";
     pool?: string;
 } | {
     kind: "explicit";
-    handle: AgentOSSidecar;
+    handle: AgentOsSidecar;
 };
-export interface AgentOSSidecarDescription {
+export interface AgentOsSidecarDescription {
     sidecarId: string;
-    placement: AgentOSSidecarPlacement;
+    placement: AgentOsSidecarPlacement;
     state: "ready" | "disposing" | "disposed";
     activeVmCount: number;
 }
@@ -119,7 +119,7 @@ export type MountConfig = PlainMountConfig | NativeMountConfig | OverlayMountCon
  * forwarded to the native sidecar in the typed create-VM JSON config. Unknown, negative, or
  * non-integer values are rejected by the sidecar before VM construction.
  */
-export interface AgentOSLimits {
+export interface AgentOsLimits {
     /** Kernel resource limits (processes, FDs, sockets, filesystem bytes, WASM caps, etc.). */
     resources?: {
         cpuCount?: number;
@@ -190,7 +190,7 @@ export interface AgentOSLimits {
         syncReadLimitBytes?: number;
     };
 }
-export interface AgentOSOptions {
+export interface AgentOsOptions {
     /**
      * Software to install in the VM. Each entry provides agents, tools,
      * or WASM commands. Any object with a `commandDir` property (e.g.,
@@ -199,6 +199,14 @@ export interface AgentOSOptions {
      * meta-packages that export arrays of sub-packages work directly.
      */
     software?: SoftwareInput[];
+    /**
+     * Whether to auto-include the default software bundle (`@agentos-software/common`
+     * — `sh` + coreutils + the standard CLI tools agents rely on) in addition to
+     * any `software` you pass. Defaults to `true`; set `false` for a bare VM with
+     * only the software you list explicitly. Entries already present in `software`
+     * are not duplicated.
+     */
+    defaultSoftware?: boolean;
     /** Loopback ports to exempt from SSRF checks (for testing with host-side mock servers). */
     loopbackExemptPorts?: number[];
     /**
@@ -219,8 +227,8 @@ export interface AgentOSOptions {
     additionalInstructions?: string;
     /** Custom schedule driver for cron jobs. Defaults to TimerScheduleDriver. */
     scheduleDriver?: ScheduleDriver;
-    /** Host-side bindings available to agents inside the VM. */
-    bindings?: Bindings[];
+    /** Host-side toolkits available to agents inside the VM. */
+    toolKits?: ToolKit[];
     /**
      * Custom permission policy for the kernel. Controls access to filesystem,
      * network, child process, and environment operations. Defaults to allowAll.
@@ -230,12 +238,12 @@ export interface AgentOSOptions {
      * Sidecar placement for the VM. Defaults to the shared `default` pool.
      * Pass an explicit sidecar handle to pin the VM to a caller-managed sidecar.
      */
-    sidecar?: AgentOSSidecarConfig;
+    sidecar?: AgentOsSidecarConfig;
     /**
      * Operator-tunable runtime limits. Unset fields use built-in defaults that match the
      * runtime's historical constants, so omitting this leaves behavior unchanged.
      */
-    limits?: AgentOSLimits;
+    limits?: AgentOsLimits;
 }
 /** Configuration for a local MCP server (spawned as a child process). */
 export interface McpServerConfigLocal {
@@ -256,11 +264,11 @@ export interface McpServerConfigRemote {
     headers?: Record<string, string>;
 }
 export type McpServerConfig = McpServerConfigLocal | McpServerConfigRemote;
-export interface AgentOSRuntimeAdmin {
+export interface AgentOsRuntimeAdmin {
     kernel: Kernel;
     rootView: VirtualFileSystem;
     env: Record<string, string>;
-    sidecar: AgentOSSidecar;
+    sidecar: AgentOsSidecar;
 }
 export interface CreateSessionOptions {
     /** Working directory for the agent session inside the VM. */
@@ -274,18 +282,49 @@ export interface CreateSessionOptions {
     /** 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(). */
+/** 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(). */
+/** Information about a process spawned via AgentOs.spawn(). */
 export interface SpawnedProcessInfo {
     pid: number;
     command: string;
@@ -293,9 +332,9 @@ export interface SpawnedProcessInfo {
     running: boolean;
     exitCode: number | null;
 }
-export declare class AgentOS {
+export declare class AgentOs {
     #private;
-    readonly sidecar: AgentOSSidecar;
+    readonly sidecar: AgentOsSidecar;
     private _sessions;
     private _closedSessionIds;
     private _sessionClosePromises;
@@ -310,7 +349,7 @@ export declare class AgentOS {
     private _softwareRoots;
     private _softwareAgentConfigs;
     private _cronManager;
-    private _bindings;
+    private _toolKits;
     private _toolReference;
     private _permissions;
     private _hostMounts;
@@ -322,9 +361,9 @@ export declare class AgentOS {
     private readonly _sidecarVm;
     private readonly _disposeSidecarEventListener;
     private constructor();
-    static createSidecar(options?: AgentOSCreateSidecarOptions): Promise<AgentOSSidecar>;
-    static getSharedSidecar(options?: AgentOSSharedSidecarOptions): Promise<AgentOSSidecar>;
-    static create(options?: AgentOSOptions): Promise<AgentOS>;
+    static createSidecar(options?: AgentOsCreateSidecarOptions): Promise<AgentOsSidecar>;
+    static getSharedSidecar(options?: AgentOsSharedSidecarOptions): Promise<AgentOsSidecar>;
+    static create(options?: AgentOsOptions): Promise<AgentOs>;
     exec(command: string, options?: KernelExecOptions): Promise<KernelExecResult>;
     execArgv(command: string, args?: readonly string[], options?: KernelExecOptions): Promise<KernelExecResult>;
     private _trackProcess;
@@ -423,6 +462,22 @@ export declare class AgentOS {
     createSession(agentType: AgentType | string, options?: CreateSessionOptions): Promise<{
         sessionId: string;
     }>;
+    /**
+     * Resume a session that exists in durable storage but is not live in this VM
+     * (e.g. after a Rivet actor slept and woke with a fresh VM). Thin forwarder:
+     * resolves the agent config + adapter entrypoint exactly as {@link createSession}
+     * does, then forwards a single `AcpResumeSessionRequest` to the sidecar, which
+     * owns the resume state machine (native `session/load` when the agent supports
+     * it, else `session/new` + a transcript-continuation preamble). The returned
+     * `sessionId` is the live id in this VM (equal to the requested id for native
+     * loads, freshly assigned for the fallback); the caller remaps `external -> live`.
+     * The new live session is registered + hydrated locally so subsequent prompts
+     * route to it.
+     *
+     * Resume depends on a durable root; on a non-durable (default in-memory) root
+     * there is no surviving store and the fallback tier always runs.
+     */
+    resumeSession(sessionId: string, agentType: AgentType | string, options?: ResumeSessionOptions): Promise<ResumeSessionResult>;
     /**
      * Resolve the VM bin entry point of an ACP adapter package.
      * Reads from the host filesystem since kernel.readFile() resolves through
@@ -502,17 +557,17 @@ export declare class AgentOS {
     onCronEvent(handler: CronEventHandler): void;
     dispose(): Promise<void>;
 }
-export declare function getAgentOSRuntimeAdmin(vm: AgentOS): AgentOSRuntimeAdmin;
-export declare function getAgentOSKernel(vm: AgentOS): Kernel;
-export declare class AgentOSSidecar {
-    constructor(sidecarId: string, placement: AgentOSSidecarPlacement, sharedPool?: string);
-    describe(): AgentOSSidecarDescription;
+export declare function getAgentOsRuntimeAdmin(vm: AgentOs): AgentOsRuntimeAdmin;
+export declare function getAgentOsKernel(vm: AgentOs): Kernel;
+export declare class AgentOsSidecar {
+    constructor(sidecarId: string, placement: AgentOsSidecarPlacement, sharedPool?: string);
+    describe(): AgentOsSidecarDescription;
     dispose(): Promise<void>;
 }
 /**
  * Test-only escape hatch: dispose every cached shared sidecar so vitest
  * workers can exit cleanly. The shared sidecar is normally process-global and
- * keeps its native subprocess alive across `AgentOS.create()` calls; without
+ * keeps its native subprocess alive across `AgentOs.create()` calls; without
  * this hook the vitest worker can hold open piped stdio handles after the
  * test suite finishes and stall `pnpm test` indefinitely.
  */