@rivet-dev/agentos-core 0.0.0-nathan-agentos-package-resolution.3785b9a → 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 |
 
@@ -177,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,20 +46,14 @@ export interface BatchReadResult {
 /** Entry in the agent registry, describing an available agent type. */
 export interface AgentRegistryEntry {
     id: string;
-    /** npm adapter package (legacy agents) — absent for `/opt/agentos` packages. */
-    acpAdapter?: string;
-    /** npm agent package (legacy agents) — absent for `/opt/agentos` packages. */
-    agentPackage?: string;
-    /** Pre-resolved adapter command path for an `/opt/agentos` agent package. */
-    adapterEntrypoint?: 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 PackageDescriptor } from "./agentos-package.js";
+import { type PackageRef, type SoftwarePackageRef } from "./agentos-package.js";
 import { type AgentOsSidecarPlacement } from "./sidecar/rpc-client.js";
 export interface AgentOsSharedSidecarOptions {
     pool?: string;
@@ -177,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;
@@ -186,6 +184,7 @@ export interface AgentOsLimits {
     python?: {
         outputBufferMaxBytes?: number;
         executionTimeoutMs?: number;
+        maxOldSpaceMb?: number;
         vfsRpcTimeoutMs?: number;
     };
     /** Guest WASM runtime limits. */
@@ -193,6 +192,8 @@ export interface AgentOsLimits {
         maxModuleFileBytes?: number;
         capturedOutputLimitBytes?: number;
         syncReadLimitBytes?: number;
+        prewarmTimeoutMs?: number;
+        runnerHeapLimitMb?: number;
     };
 }
 export interface AgentStderrEvent {
@@ -203,6 +204,38 @@ 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
@@ -232,11 +265,8 @@ export type LimitWarningHandler = (warning: LimitWarning) => 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[];
     /**
@@ -254,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. */
@@ -291,6 +324,15 @@ 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
@@ -397,12 +439,9 @@ export declare class AgentOs {
     private _closedShellIds;
     private _pendingShellExitPromises;
     private _shellCounter;
-    /** Command names linked into `/opt/agentos/bin` at runtime (via the sidecar). */
-    private _linkedCommands;
     private _acpTerminals;
     private _acpTerminalCounter;
     private _softwareRoots;
-    private _softwareAgentConfigs;
     private _cronManager;
     private _toolKits;
     private _toolReference;
@@ -417,6 +456,7 @@ export declare class AgentOs {
     private readonly _sidecarVm;
     private readonly _disposeSidecarEventListener;
     private readonly _agentStderrHandler?;
+    private readonly _agentExitHandler?;
     private readonly _limitWarningHandler?;
     private constructor();
     static createSidecar(options?: AgentOsCreateSidecarOptions): Promise<AgentOsSidecar>;
@@ -443,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[]>;
@@ -477,7 +516,11 @@ export declare class AgentOs {
     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. */
+    /**
+     * 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;
@@ -506,9 +549,18 @@ export declare class AgentOs {
      * block registers the package for `createSession(name)`. Persists for the VM's
      * lifetime (and across a snapshot iff the volume persists).
      */
-    linkSoftware(descriptor: PackageDescriptor): Promise<void>;
-    /** Returns all registered agents with their installation status. */
-    listAgents(): AgentRegistryEntry[];
+    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;
@@ -532,6 +584,7 @@ export declare class AgentOs {
      */
     private _emitSessionWarning;
     private _recordAgentStderr;
+    private _recordAgentExit;
     private _applySyntheticConfigOverrides;
     private _handleSidecarEvent;
     private _handleLimitWarning;
@@ -547,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;
     }>;
     /**
@@ -565,7 +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>;
+    resumeSession(sessionId: string, agentType: AgentType, options?: ResumeSessionOptions): Promise<ResumeSessionResult>;
     private _installSidecarRequestHandler;
     private _handleAcpExtSidecarRequest;
     private _dispatchAcpSidecarRequest;
@@ -592,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