@rivet-dev/agentos-core 0.0.0-codex-darwin-ci-publish.61a7af3 → 0.0.0-nathan-binding-workspace.13eb4d4

package/README.md

@@ -1,4 +1,4 @@
-# @rivet-dev/agent-os-core
+# @rivet-dev/agentos-core
 
 A high-level SDK for running coding agents in isolated VMs. agentOS manages the full lifecycle of virtual machines -- from filesystem setup and process management to launching AI agents via the Agent Communication Protocol (ACP).
 
@@ -19,16 +19,16 @@ Agents run inside isolated VMs with their own filesystem, process table, and net
 ## Quick Start
 
 ```bash
-npm install @rivet-dev/agent-os-core
+npm install @rivet-dev/agentos-core
 # Install an agent adapter + its underlying agent
-npm install @rivet-dev/agent-os-pi @mariozechner/pi-coding-agent
+npm install @rivet-dev/agentos-pi @mariozechner/pi-coding-agent
 ```
 
 ```typescript
-import { AgentOs } from "@rivet-dev/agent-os-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/{agent-os.d.ts → agentos.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 ToolKit } from "./host-tools.js";
+import { type Bindings } from "./bindings.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,23 +190,15 @@ 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.,
-     * registry packages like @agent-os-pkgs/coreutils) is treated
+     * registry packages like @agentos-software/coreutils) is treated
      * as a WASM command source automatically. Arrays are flattened, so
      * meta-packages that export arrays of sub-packages work directly.
      */
     software?: SoftwareInput[];
-    /**
-     * Whether to auto-include the default software bundle (`@agent-os-pkgs/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[];
     /**
@@ -218,12 +210,17 @@ export interface AgentOsOptions {
     rootFilesystem?: RootFilesystemConfig;
     /** Filesystems to mount at boot time. */
     mounts?: MountConfig[];
+    /**
+     * @deprecated Use `mounts: [nodeModulesMount(path)]` instead.
+     * Compatibility alias for mounting `<moduleAccessCwd>/node_modules` at `/root/node_modules`.
+     */
+    moduleAccessCwd?: string;
     /** Additional instructions appended to the base OS system prompt injected at session start. */
     additionalInstructions?: string;
     /** Custom schedule driver for cron jobs. Defaults to TimerScheduleDriver. */
     scheduleDriver?: ScheduleDriver;
-    /** Host-side toolkits available to agents inside the VM. */
-    toolKits?: ToolKit[];
+    /** Host-side bindings available to agents inside the VM. */
+    bindings?: Bindings[];
     /**
      * Custom permission policy for the kernel. Controls access to filesystem,
      * network, child process, and environment operations. Defaults to allowAll.
@@ -233,12 +230,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 {
@@ -259,11 +256,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. */
@@ -277,49 +274,18 @@ 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;
@@ -327,9 +293,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;
@@ -344,7 +310,7 @@ export declare class AgentOs {
     private _softwareRoots;
     private _softwareAgentConfigs;
     private _cronManager;
-    private _toolKits;
+    private _bindings;
     private _toolReference;
     private _permissions;
     private _hostMounts;
@@ -356,10 +322,11 @@ 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;
     spawn(command: string, args: string[], options?: KernelSpawnOptions): {
         pid: number;
@@ -456,22 +423,6 @@ 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
@@ -551,17 +502,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.
  */