@rivet-dev/agentos-core 0.0.0-nathan-agentos-combined.e833bb7 → 0.0.0-provided-commands.1847f3b

package/README.md

@@ -112,7 +112,7 @@ await vm.dispose();
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `createSession` | `createSession(agentType: AgentType \| string, options?: CreateSessionOptions): Promise<{ sessionId: string }>` | Launch an agent and return a session ID |
+| `createSession` | `createSession(agentType: AgentType, 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 |
 
@@ -157,10 +157,7 @@ await vm.dispose();
 - `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`
+- `chunkedS3MountPlugin()` — Declarative S3-compatible native mount plugin descriptor (from `@secure-exec/core/descriptors`)
 
 **MCP Servers**
 - `McpServerConfig` — Union of local and remote MCP configs
@@ -180,8 +177,8 @@ await vm.dispose();
 - `BatchReadResult` — Result of a batch read (path, content, error?)
 
 **Agent**
-- `AgentType` — `"pi" | "pi-cli" | "opencode" | "claude"`
-- `AgentConfig` — Agent configuration (acpAdapter, agentPackage, prepareInstructions)
+- `AgentType` — `string` (a package manifest `name`, e.g. `"pi"`, `"claude"`); agents are resolved dynamically from the configured `/opt/agentos` package manifests, so any manifest `name` is valid
+- `AgentConfig` — Agent configuration (adapterEntrypoint, launchArgs, defaultEnv)
 - `AgentRegistryEntry` — Registry entry (id, acpAdapter, agentPackage, installed)
 
 **Session**

package/dist/agent-os.d.ts

@@ -46,15 +46,14 @@ export interface BatchReadResult {
 /** Entry in the agent registry, describing an available agent type. */
 export interface AgentRegistryEntry {
     id: string;
-    acpAdapter: string;
-    agentPackage: string;
     installed: boolean;
 }
-import { type AgentType } from "./agents.js";
+import type { AgentType } from "./types.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 AgentOsSidecarPlacement } from "./sidecar/rpc-client.js";
 export interface AgentOsSharedSidecarOptions {
     pool?: string;
@@ -172,6 +171,10 @@ export interface AgentOsLimits {
     /** Guest JavaScript runtime buffering limits. */
     jsRuntime?: {
         v8HeapLimitMb?: number;
+        syncRpcWaitTimeoutMs?: number;
+        cpuTimeLimitMs?: number;
+        wallClockLimitMs?: number;
+        importCacheMaterializeTimeoutMs?: number;
         capturedOutputLimitBytes?: number;
         stdinBufferLimitBytes?: number;
         eventPayloadLimitBytes?: number;
@@ -181,6 +184,7 @@ export interface AgentOsLimits {
     python?: {
         outputBufferMaxBytes?: number;
         executionTimeoutMs?: number;
+        maxOldSpaceMb?: number;
         vfsRpcTimeoutMs?: number;
     };
     /** Guest WASM runtime limits. */
@@ -188,6 +192,8 @@ export interface AgentOsLimits {
         maxModuleFileBytes?: number;
         capturedOutputLimitBytes?: number;
         syncReadLimitBytes?: number;
+        prewarmTimeoutMs?: number;
+        runnerHeapLimitMb?: number;
     };
 }
 export interface AgentStderrEvent {
@@ -198,6 +204,57 @@ export interface AgentStderrEvent {
     chunk: Uint8Array;
 }
 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.
+ */
+export type AgentRestartOutcome = "restarted" | "unsupported" | "failed" | "exhausted";
+/**
+ * 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.
+ */
+export interface AgentExitEvent {
+    sessionId: string;
+    agentType: string;
+    /** Sidecar process id of the adapter that exited. */
+    processId: string;
+    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. */
+    restart: AgentRestartOutcome;
+    /** Restarts consumed for this session so far. */
+    restartCount: number;
+    /** Per-session restart budget. */
+    maxRestarts: number;
+}
+export type AgentExitHandler = (event: AgentExitEvent) => void;
+/**
+ * A near-capacity warning for one bounded limit (a queue/buffer, a saturating
+ * resource cap, or a memory envelope) inside the VM runtime. Delivered the moment
+ * usage crosses the runtime's warning threshold (~80%), once per crossing — the
+ * runtime applies edge-triggering + hysteresis, so this never spams.
+ */
+export interface LimitWarning {
+    /** Stable limit name, e.g. `"javascript_event_channel"` or `"vm_open_fds"`. */
+    limit: string;
+    /** Limit class: `"queue"`, `"resource"`, or `"memory"`. */
+    category: string;
+    /** Current observed usage. */
+    observed: number;
+    /** Configured capacity. */
+    capacity: number;
+    /** Observed fill as a percentage of capacity (0–100). */
+    fillPercent: number;
+}
+export type LimitWarningHandler = (warning: LimitWarning) => void;
 /**
  * Public core VM options.
  *
@@ -208,11 +265,8 @@ export type AgentStderrHandler = (event: AgentStderrEvent) => void;
  */
 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 @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 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.
      */
     software?: SoftwareInput[];
     /**
@@ -230,15 +284,18 @@ export interface AgentOsOptions {
      * Defaults to the hardened builtin set used by the native sidecar bridge.
      */
     allowedNodeBuiltins?: string[];
+    /**
+     * Opt in to a high-resolution monotonic guest clock (microsecond class)
+     * for guest Node processes. Default `false` keeps the security-oriented
+     * 1ms timer resolution — untrusted guest code should not get a precise
+     * timer (timing side channels). Enable only for trusted benchmarking or
+     * profiling workloads.
+     */
+    highResolutionTime?: boolean;
     /** 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[];
-    /**
-     * @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. */
@@ -267,6 +324,21 @@ export interface AgentOsOptions {
      * `process.stderr`.
      */
     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`.
+     */
+    onAgentExit?: AgentExitHandler;
+    /**
+     * Called when a bounded limit inside the VM runtime approaches capacity
+     * (~80%, edge-triggered with hysteresis so it does not spam). Use it to alert
+     * on a slow consumer or a runaway guest before the limit is actually hit.
+     */
+    onLimitWarning?: LimitWarningHandler;
 }
 /** Configuration for a local MCP server (spawned as a child process). */
 export interface McpServerConfigLocal {
@@ -370,7 +442,6 @@ export declare class AgentOs {
     private _acpTerminals;
     private _acpTerminalCounter;
     private _softwareRoots;
-    private _softwareAgentConfigs;
     private _cronManager;
     private _toolKits;
     private _toolReference;
@@ -378,12 +449,15 @@ export declare class AgentOs {
     private _hostMounts;
     private _env;
     private _rootFilesystem;
+    private readonly _additionalInstructions;
     private _sidecarLease;
     private readonly _sidecarClient;
     private readonly _sidecarSession;
     private readonly _sidecarVm;
     private readonly _disposeSidecarEventListener;
     private readonly _agentStderrHandler?;
+    private readonly _agentExitHandler?;
+    private readonly _limitWarningHandler?;
     private constructor();
     static createSidecar(options?: AgentOsCreateSidecarOptions): Promise<AgentOsSidecar>;
     static getSharedSidecar(options?: AgentOsSharedSidecarOptions): Promise<AgentOsSidecar>;
@@ -395,9 +469,9 @@ export declare class AgentOs {
         pid: number;
     };
     /** Write data to a process's stdin. */
-    writeProcessStdin(pid: number, data: string | Uint8Array): void;
+    writeProcessStdin(pid: number, data: string | Uint8Array): Promise<void>;
     /** Close a process's stdin stream. */
-    closeProcessStdin(pid: number): void;
+    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. */
@@ -409,7 +483,6 @@ export declare class AgentOs {
     private _assertSafeAbsolutePath;
     private _assertWritableAbsolutePath;
     private _vfs;
-    private _copyPath;
     readFile(path: string): Promise<Uint8Array>;
     writeFile(path: string, content: string | Uint8Array): Promise<void>;
     writeFiles(entries: BatchWriteEntry[]): Promise<BatchWriteResult[]>;
@@ -438,11 +511,17 @@ export declare class AgentOs {
     };
     connectTerminal(options?: ConnectTerminalOptions): Promise<number>;
     /** Write data to a shell's PTY input. */
-    writeShell(shellId: string, data: string | Uint8Array): void;
+    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;
     /** Notify a shell of terminal resize. */
     resizeShell(shellId: string, cols: number, rows: number): void;
+    /**
+     * 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>;
     /** Kill a shell process and remove it from tracking. */
     closeShell(shellId: string): void;
     private _resolveVmPathToHostPath;
@@ -462,16 +541,53 @@ export declare class AgentOs {
     listSessions(): SessionInfo[];
     /** Internal helper: retrieve a session or throw. */
     private _requireSession;
-    /** Returns all registered agents with their installation status. */
-    listAgents(): AgentRegistryEntry[];
+    /**
+     * 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
+     * lifetime (and across a snapshot iff the volume persists).
+     */
+    linkSoftware(descriptor: PackageRef | SoftwarePackageRef): Promise<void>;
+    providedCommands(): Promise<{
+        packageName: string;
+        commands: string[];
+    }[]>;
+    /**
+     * 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`.
+     */
+    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 _sendAcpRequest;
@@ -484,7 +600,7 @@ export declare class AgentOs {
     private _rejectPendingPermissionRepliesFromSession;
     private _closeSessionInternal;
     private _hydrateSessionState;
-    createSession(agentType: AgentType | string, options?: CreateSessionOptions): Promise<{
+    createSession(agentType: AgentType, options?: CreateSessionOptions): Promise<{
         sessionId: string;
     }>;
     /**
@@ -502,23 +618,7 @@ export declare class AgentOs {
      * 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
-     * mounts; adapter package.json is read directly off the host dir backing
-     * the relevant mount.
-     */
-    private _resolveAdapterBin;
-    /**
-     * Parent of the host directory backing the `/root/node_modules` mount, if
-     * the caller supplied one (e.g. via `nodeModulesMount(...)`). Used as the
-     * `resolvePackageDir` start dir for adapter/agent package resolution when no
-     * software root matches. `nodeModulesMount` mounts `<dir>/node_modules`, so
-     * the start dir is `<dir>` (one level above the node_modules tree).
-     */
-    private _nodeModulesHostRoot;
-    private _resolvePackageBin;
+    resumeSession(sessionId: string, agentType: AgentType, options?: ResumeSessionOptions): Promise<ResumeSessionResult>;
     private _installSidecarRequestHandler;
     private _handleAcpExtSidecarRequest;
     private _dispatchAcpSidecarRequest;
@@ -545,11 +645,6 @@ export declare class AgentOs {
     private _handleAcpReleaseTerminal;
     private _handleAcpResizeTerminal;
     private _handleAcpPermissionCallback;
-    /**
-     * Resolve an agent config by ID. Package-provided configs take
-     * precedence over the hardcoded AGENT_CONFIGS.
-     */
-    private _resolveAgentConfig;
     /**
      * Gracefully destroy a session: cancel any pending work, close the client,
      * and remove from tracking. Unlike close() which is abrupt, this attempts