@rivet-dev/agentos-core 0.2.22 → 0.4.0

package/README.md

@@ -1,15 +1,15 @@
-# AgentOS runtime internals
+# agentOS embedded Core
 
-`@rivet-dev/agentos-core` is the shared runtime implementation used by the
-public AgentOS packages. It is published only as a transitive dependency and is
-not a supported user-facing install target.
+`@rivet-dev/agentos-core` embeds an agentOS VM in a Node.js application. The
+embedding process owns VM lifecycle and may supply trusted host bindings,
+host-backed mounts, and local `.aospkg` paths.
 
-Install the public package instead:
+Install Core directly for embedded use:
 
 ```sh
-# Actors, sessions, and the complete AgentOS SDK
-pnpm add @rivet-dev/agentos
+pnpm add @rivet-dev/agentos-core
 ```
 
-See the [AgentOS documentation](https://rivet.dev/agentos/docs) for supported
-APIs.
+Managed services can wrap Core with a transport-specific client. Those adapters
+live outside this repository and intentionally expose a smaller trusted-host
+surface.

package/dist/agent-os.d.ts

@@ -1,13 +1,12 @@
 import type { NativeMountPluginDescriptor } from "@rivet-dev/agentos-runtime-core/descriptors";
-import type { VmUserConfig } from "@rivet-dev/agentos-runtime-core/vm-config";
+import type { CreateVmConfig, VmUserConfig } from "@rivet-dev/agentos-runtime-core/vm-config";
 import { type HostFunctionCollections, type HostFunctionSchemas } from "@rivet-dev/agentos-runtime-core/host-functions";
-import type { CodeEvaluationResult, CodeExecutionResult, ContextDescriptor, ExecutionSignal, InlineExecutionOptions, JavaScriptEvaluationOptions, JavaScriptExecutionOptions, LanguageExecutionOptions, LanguageSpawnOptions, NpmPackageInstallOptions, NpmProjectInstallOptions, OutputReplay, ProcessDescriptor, ProcessExit, PythonInstallOptions, SpawnOptions, TypeScriptCheckOptions, TypeScriptCheckResult, TypeScriptEvaluationOptions, TypeScriptExecutionOptions, TypeScriptFileExecutionOptions } from "./language-execution.js";
+import type { CodeEvaluationResult, CodeExecutionResult, ContextDescriptor, ExecutionSignal, InlineExecutionOptions, JavaScriptEvaluationOptions, JavaScriptExecutionOptions, JsonValue, LanguageExecutionOptions, LanguageSpawnOptions, NpmPackageInstallOptions, NpmProjectInstallOptions, OutputReplay, ProcessDescriptor, ProcessExit, PythonInstallOptions, SpawnOptions, TypeScriptCheckOptions, TypeScriptCheckResult, TypeScriptEvaluationOptions, TypeScriptExecutionOptions, TypeScriptFileExecutionOptions } from "./language-execution.js";
 import type { ConnectTerminalOptions, Kernel, KernelExecOptions, KernelExecResult, OpenShellOptions, Permissions, VirtualFileSystem, VirtualStat } from "./runtime-compat.js";
 import { type AgentOsSandboxInput } from "./sandbox.js";
-import type { CancelPromptResult, PromptResult as DurablePromptResult, SessionInfo as DurableSessionInfo, HistoryPage, JsonValue, ListSessionsInput, OpenSessionInput, PermissionResponse, PermissionResponseResult, PromptInput, ReadHistoryInput, SessionAgentInfo, SessionCapabilities, SessionConfig, SessionPage, SessionStreamEntry, SessionTarget, SetSessionConfigOptionInput } from "./session-api.js";
+import { type ReplayReadOptions } from "./output-replay.js";
 export type { MountConfigJsonObject, MountConfigJsonPrimitive, MountConfigJsonValue, NativeMountPluginDescriptor, } from "@rivet-dev/agentos-runtime-core/descriptors";
 export type { ConnectTerminalOptions } from "./runtime-compat.js";
-export type * from "./session-api.js";
 /** Process tree node using the same descriptor shape as process.get/list. */
 export interface ProcessTreeNode extends ProcessDescriptor {
     ppid?: number;
@@ -45,6 +44,9 @@ export interface ProcessOutput {
     pid: number;
     stream: "stdout" | "stderr";
     data: Uint8Array;
+    /** Sidecar replay identity, absent when output retention is disabled. */
+    sequence?: number;
+    timestampMs?: number;
 }
 export interface ShellData {
     shellId: string;
@@ -96,10 +98,23 @@ export interface BatchReadResult {
     content: Uint8Array | null;
     error?: string;
 }
-/** Entry in the agent registry, describing an available agent type. */
-export interface AgentRegistryEntry {
-    id: string;
-    installed: boolean;
+/** The hosted actor accepts only URL sources; embedded Core also accepts trusted paths. */
+export type SoftwarePackageSource = {
+    type: "url";
+    url: string;
+    expectedDigest?: string;
+} | {
+    type: "path";
+    path: string;
+    expectedDigest?: string;
+};
+export interface InstalledSoftware {
+    packageId: string;
+    digest: string;
+    sizeBytes: bigint;
+    packageName: string;
+    version: string;
+    commands: string[];
 }
 import { type PackageDescriptor } from "./agentos-package.js";
 import type { ScheduleDriver } from "./cron/schedule-driver.js";
@@ -152,11 +167,8 @@ export interface NativeRootFilesystemConfig {
     readOnly?: boolean;
 }
 export type RootFilesystemConfig = OverlayRootFilesystemConfig | NativeRootFilesystemConfig;
-/** VM-scoped SQLite storage shared by VFS and AgentOS durable state. */
+/** Temporary local VM-scoped SQLite storage. */
 export type VmSqliteConfig = {
-    type: "actor_uds";
-    path: string;
-} | {
     type: "sqlite_file";
     path: string;
 };
@@ -204,6 +216,10 @@ export type MountConfig = PlainMountConfig | NativeMountConfig | OverlayMountCon
  * non-integer values are rejected by the sidecar before VM construction.
  */
 export interface AgentOsLimits {
+    /** Maximum package-owned filesystem leaves projected into one VM. */
+    agentosPackages?: {
+        maxMounts?: number;
+    };
     /** Kernel resource limits (processes, FDs, sockets, filesystem bytes, WASM caps, etc.). */
     resources?: {
         cpuCount?: number;
@@ -252,21 +268,7 @@ export interface AgentOsLimits {
         maxPersistedManifestBytes?: number;
         maxPersistedManifestFileBytes?: number;
     };
-    /** ACP adapter, active-turn, history-retention, and page limits. */
-    acp?: {
-        maxReadLineBytes?: number;
-        stdoutBufferByteLimit?: number;
-        maxCompletedMessageBytes?: number;
-        maxTurnOutputBytes?: number;
-        maxPromptBytes?: number;
-        maxPromptBlocks?: number;
-        maxFallbackContinuationBytes?: number;
-        maxSessionHistoryBytes?: number;
-        maxSessionHistoryEvents?: number;
-        maxHistoryPageEntries?: number;
-        maxSessionListEntries?: number;
-    };
-    /** Shared local-file/actor-UDS SQLite result materialization limit. */
+    /** Local SQLite result materialization limit. */
     sqlite?: {
         maxResultBytes?: number;
     };
@@ -298,6 +300,12 @@ export interface AgentOsLimits {
         runnerHeapLimitMb?: number;
         runnerCpuTimeLimitMs?: number;
     };
+    /** Completed language-execution retention and live execution warning threshold. */
+    execution?: {
+        completedTtlMs?: number;
+        maxCompletedExecutions?: number;
+        liveExecutionWarningThreshold?: number;
+    };
     /** Process spawn, I/O, and lifecycle-event backlog limits. */
     process?: {
         maxSpawnFileActions?: number;
@@ -307,40 +315,6 @@ export interface AgentOsLimits {
         pendingEventBytes?: number;
     };
 }
-export interface AgentStderrEvent {
-    sessionId: string;
-    agentType: string;
-    processId: string;
-    pid: number | null;
-    chunk: Uint8Array;
-}
-export type AgentStderrHandler = (event: AgentStderrEvent) => void;
-/**
- * Restart disposition reported on an {@link AgentExitEvent}. AgentOS never
- * respawns an adapter or replays an interrupted request implicitly.
- */
-export type AgentRestartOutcome = "not_attempted";
-/**
- * An unexpected ACP adapter process exit — a crash from the host's
- * perspective (any spontaneous exit before `unloadSession()`, including exit
- * code 0). The live route is evicted and must be restored explicitly.
- */
-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;
-    /** Always `"not_attempted"`; AgentOS does not restart adapters implicitly. */
-    restart: AgentRestartOutcome;
-    /** Always zero. */
-    restartCount: number;
-    /** Always zero. */
-    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
@@ -370,14 +344,19 @@ export type LimitWarningHandler = (warning: LimitWarning) => void;
 export interface AgentOsOptions<HOST_FUNCTIONS extends HostFunctionSchemas = HostFunctionSchemas> {
     /** Initial virtual Linux credentials and account record. Defaults to `1000:1000` (`agentos`). */
     user?: VmUserConfig;
+    /**
+     * Complete initial VM environment. Omission selects Core's base environment;
+     * an explicit empty object starts with an empty environment.
+     */
+    environment?: Record<string, string>;
     /**
      * 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[];
     /**
-     * Whether to auto-include the default software bundle (`@agentos-software/common`
-     * — `sh` + coreutils + the standard CLI tools agents rely on) in addition to
+     * Whether to auto-include Core's vendored default software bundle (`sh`,
+     * coreutils, and the standard CLI tools programs 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.
@@ -398,7 +377,7 @@ export interface AgentOsOptions<HOST_FUNCTIONS extends HostFunctionSchemas = Hos
      * profiling workloads.
      */
     highResolutionTime?: boolean;
-    /** Durable SQLite storage for VM-owned filesystem and session state. */
+    /** Durable SQLite storage for VM-owned filesystem and runtime state. */
     database?: VmSqliteConfig;
     /** Root filesystem configuration. Defaults to an overlay with the bundled base snapshot as its deepest lower. */
     rootFilesystem?: RootFilesystemConfig;
@@ -408,13 +387,14 @@ export interface AgentOsOptions<HOST_FUNCTIONS extends HostFunctionSchemas = Hos
     sandbox?: AgentOsSandboxInput;
     /** Custom schedule driver for cron jobs. Defaults to TimerScheduleDriver. */
     scheduleDriver?: ScheduleDriver;
-    /** Host functions available to agents inside the VM. */
+    /** Trusted host functions available to programs inside the VM. */
     hostFunctions?: HostFunctionCollections<HOST_FUNCTIONS>;
     /**
      * Permission policy for the kernel. By default the guest behaves like a
      * sandboxed machine: its virtual filesystem, processes, environment, listeners,
-     * and loopback networking work, while external network access is denied. Your
-     * policy is merged over that default, so an omitted scope keeps it.
+     * and loopback networking work. External network access is limited to the
+     * sidecar-owned agentOS service allowlist. Your policy is merged over that
+     * default, so an omitted scope keeps it.
      */
     permissions?: Permissions;
     /**
@@ -427,20 +407,6 @@ export interface AgentOsOptions<HOST_FUNCTIONS extends HostFunctionSchemas = Hos
      * runtime's historical constants, so omitting this leaves behavior unchanged.
      */
     limits?: AgentOsLimits;
-    /**
-     * Called with stderr chunks from the top-level ACP-speaking agent process.
-     * The agent process uses stdout for ACP JSON-RPC protocol traffic, so only
-     * stderr is forwarded through this hook. Defaults to writing chunks to
-     * `process.stderr`.
-     */
-    onAgentStderr?: AgentStderrHandler;
-    /**
-     * Called when the ACP adapter process behind a session exits unexpectedly.
-     * The sidecar evicts the live
-     * route and never retries the adapter or interrupted request implicitly.
-     * 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
@@ -457,20 +423,21 @@ export interface AgentOsRuntimeAdmin {
 export declare class AgentOs {
     #private;
     readonly sidecar: AgentOsSidecar;
-    private _durableSessionEventHandlers;
-    private _agentExitHandlers;
     private _processes;
     private _languageProcesses;
     private _languageProcessIds;
+    private _pendingProcessRegistrations;
     private _executionOutputHandlers;
     private _executionCompletedHandlers;
+    private _pendingCompletionRejects;
     private _shells;
     private _closedShellIds;
+    private _closedShellErrors;
     private _pendingShellExitPromises;
     private _shellCounter;
-    private _acpTerminals;
-    private _acpTerminalCounter;
     private _softwareRoots;
+    private readonly _installedSoftware;
+    private _vmMutationActive;
     private _cronManager;
     private _hostFunctions;
     private _hostFunctionReference;
@@ -482,8 +449,7 @@ export declare class AgentOs {
     private readonly _sidecarSession;
     private readonly _sidecarVm;
     private readonly _disposeSidecarEventListener;
-    private readonly _agentStderrHandler?;
-    private readonly _agentExitHandler?;
+    private readonly _disposeSidecarCloseListener;
     private readonly _limitWarningHandler?;
     private readonly _disposeHooks;
     /**
@@ -508,9 +474,7 @@ export declare class AgentOs {
             cols: number;
             rows: number;
         }) => Promise<void>;
-        readOutput: (pid: number, options?: {
-            after?: number;
-        }) => Promise<OutputReplay>;
+        readOutput: (pid: number, options?: ReplayReadOptions) => Promise<OutputReplay>;
     };
     readonly javascript: {
         execute: (source: string, options?: JavaScriptExecutionOptions) => Promise<CodeExecutionResult>;
@@ -597,24 +561,9 @@ export declare class AgentOs {
             commands: string[];
         }[]>;
         link: (descriptor: PackageDescriptor) => Promise<void>;
-    };
-    readonly agents: {
-        list: () => Promise<AgentRegistryEntry[]>;
-    };
-    readonly sessions: {
-        open: (input: OpenSessionInput) => Promise<void>;
-        get: (input?: SessionTarget) => Promise<DurableSessionInfo>;
-        list: (input?: ListSessionsInput) => Promise<SessionPage>;
-        delete: (input?: SessionTarget) => Promise<void>;
-        unload: (input?: SessionTarget) => Promise<void>;
-        prompt: (input: PromptInput) => Promise<DurablePromptResult>;
-        cancelPrompt: (input?: SessionTarget) => Promise<CancelPromptResult>;
-        respondPermission: (input: PermissionResponse) => Promise<PermissionResponseResult>;
-        readHistory: (input?: ReadHistoryInput) => Promise<HistoryPage>;
-        getConfig: (input?: SessionTarget) => Promise<SessionConfig>;
-        setConfigOption: (input: SetSessionConfigOptionInput) => Promise<SessionConfig>;
-        getCapabilities: (input?: SessionTarget) => Promise<SessionCapabilities | null>;
-        getAgentInfo: (input?: SessionTarget) => Promise<SessionAgentInfo | null>;
+        install: (source: SoftwarePackageSource) => Promise<InstalledSoftware>;
+        uninstall: (packageId: string) => Promise<InstalledSoftware>;
+        installed: () => InstalledSoftware[];
     };
     readonly cron: {
         schedule: (options: CronJobOptions) => CronJob;
@@ -624,7 +573,9 @@ export declare class AgentOs {
     private constructor();
     static createSidecar(options?: AgentOsCreateSidecarOptions): Promise<AgentOsSidecar>;
     static getSharedSidecar(options?: AgentOsSharedSidecarOptions): Promise<AgentOsSidecar>;
-    static create<HOST_FUNCTIONS extends HostFunctionSchemas>(callerOptions?: AgentOsOptions<HOST_FUNCTIONS>): Promise<AgentOs>;
+    static create(options?: AgentOsOptions, 
+    /** @internal Product wrappers select a sidecar-owned default profile here. */
+    defaultsProfile?: NonNullable<CreateVmConfig["defaultsProfile"]>): Promise<AgentOs>;
     createContext(contextId: string): Promise<void>;
     private _executionOperation;
     private _spawnLanguageOperation;
@@ -671,8 +622,13 @@ export declare class AgentOs {
     private _resizeExecutionPty;
     private _readExecutionOutput;
     private _onExecutionOutput;
+    /** A completion signal that rejects if the sidecar exits before it resolves. */
+    private _pendingCompletion;
     private _onExecutionCompleted;
     private _trackProcess;
+    private _recordProcessExit;
+    private _reserveProcessRegistrySlot;
+    private _pruneExitedProcesses;
     private _spawnProcess;
     spawn(command: string, args?: string[], options?: SpawnOptions): Promise<ProcessDescriptor>;
     /** Write data to a process's stdin. */
@@ -753,8 +709,8 @@ export declare class AgentOs {
     httpRequest(request: HttpRequest): Promise<HttpResponse>;
     /**
      * Fetch an HTTP endpoint inside the VM while preserving duplicate response
-     * headers and arbitrary binary bodies. agentOS Apps uses this compatibility
-     * surface for its direct actor API.
+     * headers and arbitrary binary bodies. This compatibility surface supports
+     * fetch-like callers that proxy requests into a guest VM.
      */
     fetch(port: number, request: Request): Promise<Response>;
     fetchStreamStart(port: number, request: Request): Promise<{
@@ -818,62 +774,12 @@ export declare class AgentOs {
     private _killProcess;
     private _resizeProcessPty;
     private _readProcessOutput;
-    private _openSession;
-    private _getSession;
-    private _listSessions;
-    private _deleteSession;
-    private _unloadSession;
-    private _prompt;
-    private _cancelPrompt;
-    private _respondPermission;
-    private _readHistory;
-    private _getSessionConfig;
-    private _setSessionConfigOption;
-    private _getSessionCapabilities;
-    private _getSessionAgentInfo;
-    /** @deprecated Use `sessions.open()`. */
-    openSession(input: OpenSessionInput): Promise<void>;
-    /** @deprecated Use `sessions.get()`. */
-    getSession(input?: SessionTarget): Promise<DurableSessionInfo>;
-    /** @deprecated Use `sessions.list()`. */
-    listSessions(input?: ListSessionsInput): Promise<SessionPage>;
-    /** @deprecated Use `sessions.delete()`. */
-    deleteSession(input?: SessionTarget): Promise<void>;
-    /** @deprecated Use `sessions.unload()`. */
-    unloadSession(input?: SessionTarget): Promise<void>;
-    /** @deprecated Use `sessions.prompt()`. */
-    prompt(input: PromptInput): Promise<DurablePromptResult>;
-    /** @deprecated Use `sessions.cancelPrompt()`. */
-    cancelPrompt(input?: SessionTarget): Promise<CancelPromptResult>;
-    /** @deprecated Use `sessions.respondPermission()`. */
-    respondPermission(input: PermissionResponse): Promise<PermissionResponseResult>;
-    /** @deprecated Use `sessions.readHistory()`. */
-    readHistory(input?: ReadHistoryInput): Promise<HistoryPage>;
-    /** @deprecated Use `sessions.getConfig()`. */
-    getSessionConfig(input?: SessionTarget): Promise<SessionConfig>;
-    /** @deprecated Use `sessions.setConfigOption()`. */
-    setSessionConfigOption(input: SetSessionConfigOptionInput): Promise<SessionConfig>;
-    /** @deprecated Use `sessions.getCapabilities()`. */
-    getSessionCapabilities(input?: SessionTarget): Promise<SessionCapabilities | null>;
-    /** @deprecated Use `sessions.getAgentInfo()`. */
-    getSessionAgentInfo(input?: SessionTarget): Promise<SessionAgentInfo | null>;
-    /**
-     * 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 `openSession({ agent: name })`. Persists for the VM's
-     * lifetime (and across a snapshot iff the volume persists).
-     */
+    private _withVmMutation;
     private _linkSoftware;
+    private _installSoftware;
+    private _uninstallSoftware;
+    private _installedSoftwareList;
     private _listSoftware;
-    /**
-     * 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`.
-     */
-    private _listAgents;
     /** @deprecated Use `software.link()`. */
     linkSoftware(descriptor: PackageDescriptor): Promise<void>;
     /** @deprecated Use `software.list()`. */
@@ -881,42 +787,9 @@ export declare class AgentOs {
         packageName: string;
         commands: string[];
     }[]>;
-    /** @deprecated Use `agents.list()`. */
-    listAgents(): Promise<AgentRegistryEntry[]>;
-    private _recordAgentStderr;
-    private _recordAgentExit;
     private _handleSidecarEvent;
     private _handleLimitWarning;
-    private _handleAcpExtEvent;
-    private _emitDurableSessionEvent;
-    private _sendAcpRequest;
     private _installSidecarRequestHandler;
-    private _handleAcpExtSidecarRequest;
-    private _dispatchAcpSidecarRequest;
-    private _handleSupportedAcpSidecarRequest;
-    private _acpParams;
-    private _requireAcpStringParam;
-    private _optionalAcpStringParam;
-    private _optionalAcpNumberParam;
-    private _optionalAcpStringArrayParam;
-    private _optionalAcpEnvParam;
-    private _requireAcpTerminal;
-    private _appendAcpTerminalOutput;
-    private _handleAcpReadFile;
-    private _handleAcpWriteFile;
-    private _handleAcpReadDir;
-    private _handleAcpCreateTerminal;
-    private _handleAcpWriteTerminal;
-    private _handleAcpReadTerminal;
-    private _handleAcpWaitForTerminalExit;
-    private _handleAcpKillTerminal;
-    private _handleAcpReleaseTerminal;
-    private _handleAcpResizeTerminal;
-    onSessionEvent(handler: (entry: SessionStreamEntry) => void): () => void;
-    onSessionEvent(sessionId: string | undefined, handler: (entry: SessionStreamEntry) => void): () => void;
-    /** Subscribe to unexpected adapter exits without changing session liveness. */
-    onAgentExit(handler: AgentExitHandler): () => void;
-    onAgentExit(sessionId: string | undefined, handler: AgentExitHandler): () => void;
     /** Schedule a cron job. Returns a handle with the job ID and a cancel method. */
     private _scheduleCron;
     /** List all registered cron jobs. */