@rivet-dev/agentos-core 0.0.0-agentos-dylib-plugin.473700e

package/README.md

@@ -0,0 +1,204 @@
+# @rivet-dev/agent-os-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).
+
+Agents run inside isolated VMs with their own filesystem, process table, and network stack. The host only communicates through well-defined APIs, keeping agent execution fully contained.
+
+## Features
+
+- **VM lifecycle** — create, configure, and dispose isolated virtual machines
+- **Sidecar placement** — reuse the default shared sidecar or inject an explicit sidecar handle
+- **Agent sessions (ACP)** — launch coding agents (Pi, Pi CLI, OpenCode, Claude) via JSON-RPC over stdio
+- **Filesystem operations** — read, write, mkdir, stat, move, delete, recursive listing, batch read/write
+- **Process management** — spawn, exec, stop, kill processes; inspect process trees across all runtimes
+- **Agent registry** — discover available agents and their installation status
+- **Networking** — reach services running inside the VM via `fetch()`
+- **Shell access** — open interactive shells with PTY support
+- **Mount backends** — memory, native host directory mounts, S3, overlay (copy-on-write), or custom VirtualFileSystem
+
+## Quick Start
+
+```bash
+npm install @rivet-dev/agent-os-core
+# Install an agent adapter + its underlying agent
+npm install @rivet-dev/agent-os-pi @mariozechner/pi-coding-agent
+```
+
+```typescript
+import { AgentOs } from "@rivet-dev/agent-os-core";
+
+// 1. Create a VM
+const vm = await AgentOs.create();
+
+// 2. Create an agent session
+const { sessionId } = await vm.createSession("pi");
+
+// 3. Send a prompt
+const response = await vm.prompt(sessionId, "Write a hello world in TypeScript");
+
+// 4. Clean up
+vm.closeSession(sessionId);
+await vm.dispose();
+```
+
+## API Reference
+
+### Lifecycle
+
+| 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 |
+| `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 |
+| `dispose` | `sidecar.dispose(): Promise<void>` | Dispose the sidecar handle and any active VMs leased from it |
+
+### Filesystem
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `readFile` | `readFile(path: string): Promise<Uint8Array>` | Read a file |
+| `writeFile` | `writeFile(path: string, content: string \| Uint8Array): Promise<void>` | Write a file |
+| `readFiles` | `readFiles(paths: string[]): Promise<BatchReadResult[]>` | Batch read multiple files |
+| `writeFiles` | `writeFiles(entries: BatchWriteEntry[]): Promise<BatchWriteResult[]>` | Batch write multiple files (creates parent dirs) |
+| `mkdir` | `mkdir(path: string): Promise<void>` | Create a directory |
+| `readdir` | `readdir(path: string): Promise<string[]>` | List directory entries |
+| `readdirRecursive` | `readdirRecursive(path: string, options?: ReaddirRecursiveOptions): Promise<DirEntry[]>` | Recursively list directory contents with metadata |
+| `stat` | `stat(path: string): Promise<VirtualStat>` | Get file/directory metadata |
+| `exists` | `exists(path: string): Promise<boolean>` | Check if a path exists |
+| `move` | `move(from: string, to: string): Promise<void>` | Rename/move a file or directory |
+| `delete` | `delete(path: string, options?: { recursive?: boolean }): Promise<void>` | Delete a file or directory |
+| `mountFs` | `mountFs(path: string, driver: VirtualFileSystem, options?: { readOnly?: boolean }): void` | Mount a filesystem driver at the given path |
+| `unmountFs` | `unmountFs(path: string): void` | Unmount a filesystem |
+
+### Process Management
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `exec` | `exec(command: string, options?: ExecOptions): Promise<ExecResult>` | Execute a shell command and wait for completion |
+| `spawn` | `spawn(command: string, args: string[], options?: SpawnOptions): { pid: number }` | Spawn a long-running process |
+| `listProcesses` | `listProcesses(): SpawnedProcessInfo[]` | List processes started via `spawn()` |
+| `allProcesses` | `allProcesses(): ProcessInfo[]` | List all kernel processes across all runtimes |
+| `processTree` | `processTree(): ProcessTreeNode[]` | Get processes organized as a parent-child tree |
+| `getProcess` | `getProcess(pid: number): SpawnedProcessInfo` | Get info about a specific spawned process |
+| `stopProcess` | `stopProcess(pid: number): void` | Send SIGTERM to a process |
+| `killProcess` | `killProcess(pid: number): void` | Send SIGKILL to a process |
+
+### Network
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `fetch` | `fetch(port: number, request: Request): Promise<Response>` | Send an HTTP request to a service running inside the VM |
+
+### Shell
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `connectTerminal` | `connectTerminal(options?: ConnectTerminalOptions): Promise<number>` | Attach a shell directly to the host terminal and wait for exit |
+| `openShell` | `openShell(options?: OpenShellOptions): { shellId: string }` | Open an interactive shell with PTY support |
+| `writeShell` | `writeShell(shellId: string, data: string \| Uint8Array): void` | Write data to a shell's PTY input |
+| `onShellData` | `onShellData(shellId: string, handler: (data: Uint8Array) => void): () => void` | Subscribe to shell output data |
+| `resizeShell` | `resizeShell(shellId: string, cols: number, rows: number): void` | Notify terminal resize |
+| `closeShell` | `closeShell(shellId: string): void` | Kill the shell process |
+
+### Agent Sessions
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `createSession` | `createSession(agentType: AgentType \| string, options?: CreateSessionOptions): Promise<{ sessionId: string }>` | Launch an agent and return a session ID |
+| `listSessions` | `listSessions(): SessionInfo[]` | List active sessions |
+| `destroySession` | `destroySession(sessionId: string): Promise<void>` | Gracefully cancel and close a session |
+
+### Agent Registry
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `listAgents` | `listAgents(): AgentRegistryEntry[]` | List registered agents with installation status |
+
+### Agent Session Operations
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `prompt` | `prompt(sessionId: string, text: string): Promise<PromptResult>` | Send a prompt and collect the agent text |
+| `cancelSession` | `cancelSession(sessionId: string): Promise<JsonRpcResponse>` | Cancel ongoing agent work |
+| `closeSession` | `closeSession(sessionId: string): void` | Kill the agent process and clean up |
+| `onSessionEvent` | `onSessionEvent(sessionId: string, handler: SessionEventHandler): () => void` | Subscribe to session update notifications |
+| `onPermissionRequest` | `onPermissionRequest(sessionId: string, handler: PermissionRequestHandler): () => void` | Subscribe to permission requests |
+| `respondPermission` | `respondPermission(sessionId: string, permissionId: string, reply: PermissionReply): Promise<JsonRpcResponse>` | Reply to a permission request |
+| `setSessionMode` | `setSessionMode(sessionId: string, modeId: string): Promise<JsonRpcResponse>` | Set the session mode |
+| `getSessionModes` | `getSessionModes(sessionId: string): SessionModeState \| null` | Get available modes |
+| `setSessionModel` | `setSessionModel(sessionId: string, model: string): Promise<JsonRpcResponse>` | Set the model |
+| `setSessionThoughtLevel` | `setSessionThoughtLevel(sessionId: string, level: string): Promise<JsonRpcResponse>` | Set reasoning level |
+| `getSessionConfigOptions` | `getSessionConfigOptions(sessionId: string): SessionConfigOption[]` | Get available config options |
+| `rawSend` | `rawSend(sessionId: string, method: string, params?: Record<string, unknown>): Promise<JsonRpcResponse>` | Send an arbitrary ACP request |
+
+### 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
+- `CreateSessionOptions` — Session options (cwd, env, mcpServers, skipOsInstructions, additionalInstructions)
+
+**Sidecar**
+- `AgentOsSidecarDescription` — Sidecar identity, placement, lifecycle state, and active VM count
+
+**Mount Configurations**
+- `MountConfig` — Union of all mount types
+- `MountConfigMemory` — In-memory filesystem
+- `MountConfigCustom` — Caller-provided VirtualFileSystem
+- `NativeMountConfig` — Declarative sidecar mount plugin configuration
+- `MountConfigOverlay` — Copy-on-write overlay (lower + upper layers)
+
+**Companion Filesystem Packages**
+- `createGoogleDriveBackend()` — Declarative Google Drive native mount helper from `@secure-exec/google-drive`
+- `createS3Backend()` — Declarative S3-compatible native mount helper from `@secure-exec/s3`
+
+**MCP Servers**
+- `McpServerConfig` — Union of local and remote MCP configs
+- `McpServerConfigLocal` — Local MCP server (command, args, env)
+- `McpServerConfigRemote` — Remote MCP server (url, headers)
+
+**Process**
+- `ProcessInfo` — Kernel process info (pid, ppid, pgid, sid, driver, command, args, cwd, status, exitCode, startTime, exitTime)
+- `SpawnedProcessInfo` — Info for processes created via `spawn()` (pid, command, args, running, exitCode)
+- `ProcessTreeNode` — ProcessInfo with `children: ProcessTreeNode[]`
+
+**Filesystem**
+- `DirEntry` — Directory entry (path, type, size)
+- `ReaddirRecursiveOptions` — Options for recursive listing (maxDepth, exclude)
+- `BatchWriteEntry` — Entry for batch writes (path, content)
+- `BatchWriteResult` — Result of a batch write (path, success, error?)
+- `BatchReadResult` — Result of a batch read (path, content, error?)
+
+**Agent**
+- `AgentType` — `"pi" | "pi-cli" | "opencode" | "claude"`
+- `AgentConfig` — Agent configuration (acpAdapter, agentPackage, prepareInstructions)
+- `AgentRegistryEntry` — Registry entry (id, acpAdapter, agentPackage, installed)
+
+**Session**
+- `SessionInfo` — Session summary (sessionId, agentType)
+- `SessionInitData` — Data from ACP initialize response
+- `SessionMode` — A mode the agent supports
+- `SessionModeState` — Current mode and available modes
+- `SessionConfigOption` — A configuration option the agent supports
+- `AgentCapabilities` — Boolean capability flags from the agent
+- `AgentInfo` — Agent identity (name, version)
+- `PermissionRequest` — Permission request from an agent
+- `PermissionReply` — `"once" | "always" | "reject"`
+- `PermissionRequestHandler` — Handler for permission requests
+- `SessionEventHandler` — Handler for live session update events
+
+**Protocol**
+- `JsonRpcRequest`, `JsonRpcResponse`, `JsonRpcNotification`, `JsonRpcError`
+
+**Backends**
+- `HostDirBackendOptions` — Options for the `createHostDirBackend()` native host-dir plugin helper