@rivet-dev/agentos-core 0.2.4 → 0.2.5-rc.1

package/README.md

@@ -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

package/dist/agent-os.d.ts

@@ -46,15 +46,20 @@ export interface BatchReadResult {
 /** Entry in the agent registry, describing an available agent type. */
 export interface AgentRegistryEntry {
     id: string;
-    acpAdapter: string;
-    agentPackage: 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 "./agents.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;
@@ -198,6 +203,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
@@ -227,11 +264,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[];
     /**
@@ -249,6 +283,14 @@ 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. */
@@ -286,6 +328,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
@@ -392,6 +443,8 @@ 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;
@@ -410,6 +463,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>;
@@ -422,9 +476,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. */
@@ -465,11 +519,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;
@@ -489,6 +549,15 @@ export declare class AgentOs {
     listSessions(): SessionInfo[];
     /** Internal helper: retrieve a session or throw. */
     private _requireSession;
+    /**
+     * 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>;
     /** Returns all registered agents with their installation status. */
     listAgents(): AgentRegistryEntry[];
     private _syncSessionState;
@@ -496,7 +565,25 @@ export declare class AgentOs {
     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;
@@ -531,22 +618,6 @@ export declare class AgentOs {
      * 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;
     private _installSidecarRequestHandler;
     private _handleAcpExtSidecarRequest;
     private _dispatchAcpSidecarRequest;
@@ -574,8 +645,9 @@ export declare class AgentOs {
     private _handleAcpResizeTerminal;
     private _handleAcpPermissionCallback;
     /**
-     * Resolve an agent config by ID. Package-provided configs take
-     * precedence over the hardcoded AGENT_CONFIGS.
+     * Resolve an agent config by ID. Agents are /opt/agentos packages
+     * registered from their manifests (explicit software at create, or lazily
+     * linked dependency agents) — there is no hardcoded fallback config.
      */
     private _resolveAgentConfig;
     /**