@rivet-dev/agentos-runtime-core 0.2.8-rc.1 → 0.2.8-rc.3

package/dist/protocol-schema.d.ts

@@ -1,6 +1,6 @@
 export declare const SIDECAR_PROTOCOL_SCHEMA: {
     readonly name: "agentos-native-sidecar";
-    readonly version: 7;
+    readonly version: 8;
 };
 export type LiveProtocolSchema = typeof SIDECAR_PROTOCOL_SCHEMA;
 export type ProtocolSchemaLike = {

package/dist/protocol-schema.js

@@ -1,6 +1,6 @@
 export const SIDECAR_PROTOCOL_SCHEMA = {
     name: "agentos-native-sidecar",
-    version: 7,
+    version: 8,
 };
 export function validateSidecarProtocolSchema(schema) {
     if (schema.name !== SIDECAR_PROTOCOL_SCHEMA.name ||

package/dist/request-payloads.d.ts

@@ -42,7 +42,7 @@ export type LiveRequestPayload = {
     packages?: LivePackageDescriptor[];
     packages_mount_at?: string;
     bootstrap_commands?: string[];
-    tool_shim_commands?: string[];
+    binding_shim_commands?: string[];
 } | {
     type: "link_package";
     package: LivePackageDescriptor;
@@ -79,6 +79,9 @@ export type LiveRequestPayload = {
     lower_layer_ids: string[];
 } | {
     type: "snapshot_root_filesystem";
+    max_bytes: number;
+} | {
+    type: "list_mounts";
 } | {
     type: "guest_kernel_call";
     execution_id: string;

package/dist/request-payloads.js

@@ -58,7 +58,7 @@ export function toGeneratedRequestPayload(payload) {
                     packages: (payload.packages ?? []).map(toGeneratedPackageDescriptor),
                     packagesMountAt: payload.packages_mount_at ?? "",
                     bootstrapCommands: payload.bootstrap_commands ?? [],
-                    toolShimCommands: payload.tool_shim_commands ?? [],
+                    bindingShimCommands: payload.binding_shim_commands ?? [],
                 },
             };
         case "link_package":
@@ -153,7 +153,12 @@ export function toGeneratedRequestPayload(payload) {
                 },
             };
         case "snapshot_root_filesystem":
-            return { tag: "SnapshotRootFilesystemRequest", val: null };
+            return {
+                tag: "SnapshotRootFilesystemRequest",
+                val: { maxBytes: BigInt(payload.max_bytes) },
+            };
+        case "list_mounts":
+            return { tag: "ListMountsRequest", val: null };
         case "execute":
             return {
                 tag: "ExecuteRequest",

package/dist/response-payloads.d.ts

@@ -1,5 +1,5 @@
-import { type LiveRootFilesystemEntry, type LiveRootFilesystemEntryEncoding } from "./filesystem.js";
 import { type LiveExtEnvelope } from "./ext.js";
+import { type LiveRootFilesystemEntry, type LiveRootFilesystemEntryEncoding } from "./filesystem.js";
 import type * as protocol from "./generated-protocol.js";
 import { type LiveFilesystemOperation, type LiveGuestFilesystemOperation, type LiveSignalDispositionAction } from "./protocol-maps.js";
 import { type LiveGuestFilesystemStat, type LiveProcessSnapshotEntry, type LiveSocketStateEntry } from "./state.js";
@@ -49,6 +49,11 @@ export interface LivePackageCommands {
     package_name: string;
     commands: string[];
 }
+export interface LiveMountInfo {
+    path: string;
+    kind: string;
+    read_only: boolean;
+}
 export interface LiveAgentosProjectedAgent {
     id: string;
     acp_entrypoint: string;
@@ -79,6 +84,9 @@ export type LiveResponsePayload = {
 } | {
     type: "provided_commands_response";
     packages: LivePackageCommands[];
+} | {
+    type: "mounts_listed";
+    mounts: LiveMountInfo[];
 } | {
     type: "host_callbacks_registered";
     registration: string;
@@ -179,6 +187,19 @@ export type LiveResponsePayload = {
     type: "rejected";
     code: string;
     message: string;
+    limit_name: string | null;
+    configured_limit: number | null;
+    current_usage: number | null;
+    requested: number | null;
+    unit: string | null;
+    scope: string | null;
+    vm_id: string | null;
+    session_generation: number | null;
+    capability_id: number | null;
+    operation: string | null;
+    configuration_path: string | null;
+    retryable: boolean | null;
+    errno: string | null;
 } | {
     type: "ext_result";
     envelope: LiveExtEnvelope;

package/dist/response-payloads.js

@@ -1,5 +1,5 @@
-import { fromGeneratedRootFilesystemEntry, } from "./filesystem.js";
 import { fromGeneratedExtEnvelope } from "./ext.js";
+import { fromGeneratedRootFilesystemEntry, } from "./filesystem.js";
 import { bigIntToSafeNumber } from "./numbers.js";
 import { fromGeneratedFilesystemOperation, fromGeneratedGuestFilesystemOperation, fromGeneratedRootFilesystemEntryEncoding, fromGeneratedSignalDispositionAction, } from "./protocol-maps.js";
 import { fromGeneratedGuestFilesystemStat, fromGeneratedProcessSnapshotEntry, fromGeneratedSocketStateEntry, } from "./state.js";
@@ -55,6 +55,15 @@ export function fromGeneratedResponsePayload(payload) {
                     commands: [...pkg.commands],
                 })),
             };
+        case "ListMountsResponse":
+            return {
+                type: "mounts_listed",
+                mounts: payload.val.mounts.map((mount) => ({
+                    path: mount.path,
+                    kind: mount.kind,
+                    read_only: mount.readOnly,
+                })),
+            };
         case "HostCallbacksRegisteredResponse":
             return {
                 type: "host_callbacks_registered",
@@ -228,6 +237,29 @@ export function fromGeneratedResponsePayload(payload) {
                 type: "rejected",
                 code: payload.val.code,
                 message: payload.val.message,
+                limit_name: payload.val.limitName,
+                configured_limit: payload.val.configuredLimit === null
+                    ? null
+                    : bigIntToSafeNumber(payload.val.configuredLimit, "rejected.configured_limit"),
+                current_usage: payload.val.currentUsage === null
+                    ? null
+                    : bigIntToSafeNumber(payload.val.currentUsage, "rejected.current_usage"),
+                requested: payload.val.requested === null
+                    ? null
+                    : bigIntToSafeNumber(payload.val.requested, "rejected.requested"),
+                unit: payload.val.unit,
+                scope: payload.val.scope,
+                vm_id: payload.val.vmId,
+                session_generation: payload.val.sessionGeneration === null
+                    ? null
+                    : bigIntToSafeNumber(payload.val.sessionGeneration, "rejected.session_generation"),
+                capability_id: payload.val.capabilityId === null
+                    ? null
+                    : bigIntToSafeNumber(payload.val.capabilityId, "rejected.capability_id"),
+                operation: payload.val.operation,
+                configuration_path: payload.val.configurationPath,
+                retryable: payload.val.retryable,
+                errno: payload.val.errno,
             };
         case "VmFetchResponse":
             return {

package/dist/sidecar-errors.d.ts

@@ -1,3 +1,25 @@
+export interface SidecarRejectionDetail {
+    code: string;
+    message: string;
+    limit_name: string | null;
+    configured_limit: number | null;
+    current_usage: number | null;
+    requested: number | null;
+    unit: string | null;
+    scope: string | null;
+    vm_id: string | null;
+    session_generation: number | null;
+    capability_id: number | null;
+    operation: string | null;
+    configuration_path: string | null;
+    retryable: boolean | null;
+    errno: string | null;
+}
+export declare class SidecarRejectedError extends Error {
+    readonly requestId: number;
+    readonly detail: SidecarRejectionDetail;
+    constructor(requestId: number, detail: SidecarRejectionDetail);
+}
 export declare class SidecarProcessExited extends Error {
     readonly exitCode: number | null;
     readonly signal: string | null;

package/dist/sidecar-errors.js

@@ -1,6 +1,16 @@
 function formatSidecarStderrSuffix(stderr) {
     return stderr ? `\nstderr:\n${stderr}` : "";
 }
+export class SidecarRejectedError extends Error {
+    requestId;
+    detail;
+    constructor(requestId, detail) {
+        super(`sidecar rejected request ${requestId}: ${detail.code}: ${detail.message}`);
+        this.name = "SidecarRejectedError";
+        this.requestId = requestId;
+        this.detail = detail;
+    }
+}
 export class SidecarProcessExited extends Error {
     exitCode;
     signal;

package/dist/sidecar-process.d.ts

@@ -105,6 +105,8 @@ export interface SidecarSpawnOptions {
     command?: string;
     args?: string[];
     eventBufferCapacity?: number;
+    gracefulExitMs?: number;
+    forceExitMs?: number;
     payloadCodec?: NativeTransportPayloadCodec;
     /**
      * Override the sidecar silence watchdog window (default 30s). Tests only —
@@ -150,6 +152,8 @@ export interface SidecarMountPluginDescriptor {
 }
 export interface SidecarMountDescriptor {
     guestPath: string;
+    guestSource?: string;
+    guestFstype?: string;
     readOnly: boolean;
     plugin: SidecarMountPluginDescriptor;
 }
@@ -242,7 +246,7 @@ export declare class SidecarProcess {
         packages?: SidecarPackageDescriptor[];
         packagesMountAt?: string;
         bootstrapCommands?: string[];
-        toolShimCommands?: string[];
+        bindingShimCommands?: string[];
     }): Promise<SidecarVmConfiguredResponse>;
     /**
      * Runtime dynamic `linkSoftware`: project one package into the live
@@ -270,10 +274,16 @@ export declare class SidecarProcess {
         lowerLayerIds: string[];
     }): Promise<string>;
     bootstrapRootFilesystem(session: AuthenticatedSession, vm: CreatedVm, entries: RootFilesystemEntry[]): Promise<void>;
-    snapshotRootFilesystem(session: AuthenticatedSession, vm: CreatedVm): Promise<RootFilesystemEntry[]>;
+    snapshotRootFilesystem(session: AuthenticatedSession, vm: CreatedVm, maxBytes: number): Promise<RootFilesystemEntry[]>;
+    listMounts(session: AuthenticatedSession, vm: CreatedVm): Promise<Array<{
+        path: string;
+        kind: string;
+        readOnly: boolean;
+    }>>;
     readFile(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<Uint8Array>;
     pread(session: AuthenticatedSession, vm: CreatedVm, path: string, offset: number, length: number): Promise<Uint8Array>;
     writeFile(session: AuthenticatedSession, vm: CreatedVm, path: string, content: string | Uint8Array): Promise<void>;
+    pwrite(session: AuthenticatedSession, vm: CreatedVm, path: string, offset: number, content: Uint8Array): Promise<void>;
     mkdir(session: AuthenticatedSession, vm: CreatedVm, path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;

package/dist/sidecar-process.js

@@ -32,8 +32,8 @@ export class SidecarProcess {
             cwd: options.cwd,
             silenceTimeoutMs: options.silenceTimeoutMs,
             eventBufferCapacity: options.eventBufferCapacity ?? DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY,
-            gracefulExitMs: DEFAULT_SIDECAR_GRACEFUL_EXIT_MS,
-            forceExitMs: DEFAULT_SIDECAR_FORCE_EXIT_MS,
+            gracefulExitMs: options.gracefulExitMs ?? DEFAULT_SIDECAR_GRACEFUL_EXIT_MS,
+            forceExitMs: options.forceExitMs ?? DEFAULT_SIDECAR_FORCE_EXIT_MS,
             disposedErrorMessage: "native sidecar disposed",
             payloadCodec: options.payloadCodec ?? "bare",
         });
@@ -147,7 +147,7 @@ export class SidecarProcess {
                     ? { packages_mount_at: options.packagesMountAt }
                     : {}),
                 bootstrap_commands: options.bootstrapCommands ?? [],
-                tool_shim_commands: options.toolShimCommands ?? [],
+                binding_shim_commands: options.bindingShimCommands ?? [],
             },
         });
         if (response.payload.type !== "vm_configured") {
@@ -361,7 +361,7 @@ export class SidecarProcess {
             throw new Error(`unexpected bootstrap_root_filesystem response: ${response.payload.type}`);
         }
     }
-    async snapshotRootFilesystem(session, vm) {
+    async snapshotRootFilesystem(session, vm, maxBytes) {
         const response = await this.sendRequest({
             ownership: {
                 scope: "vm",
@@ -371,6 +371,7 @@ export class SidecarProcess {
             },
             payload: {
                 type: "snapshot_root_filesystem",
+                max_bytes: maxBytes,
             },
         });
         if (response.payload.type !== "root_filesystem_snapshot") {
@@ -378,6 +379,25 @@ export class SidecarProcess {
         }
         return response.payload.entries;
     }
+    async listMounts(session, vm) {
+        const response = await this.sendRequest({
+            ownership: {
+                scope: "vm",
+                connection_id: session.connectionId,
+                session_id: session.sessionId,
+                vm_id: vm.vmId,
+            },
+            payload: { type: "list_mounts" },
+        });
+        if (response.payload.type !== "mounts_listed") {
+            throw new Error(`unexpected list_mounts response: ${response.payload.type}`);
+        }
+        return response.payload.mounts.map((mount) => ({
+            path: mount.path,
+            kind: mount.kind,
+            readOnly: mount.read_only,
+        }));
+    }
     async readFile(session, vm, path) {
         const response = await this.guestFilesystemCall(session, vm, {
             operation: "read_file",
@@ -403,6 +423,16 @@ export class SidecarProcess {
             encoding: encoded.encoding,
         });
     }
+    async pwrite(session, vm, path, offset, content) {
+        const encoded = encodeGuestFilesystemContent(content);
+        await this.guestFilesystemCall(session, vm, {
+            operation: "pwrite",
+            path,
+            offset,
+            content: encoded.content,
+            encoding: encoded.encoding,
+        });
+    }
     async mkdir(session, vm, path, options) {
         await this.guestFilesystemCall(session, vm, {
             operation: options?.recursive ? "mkdir" : "create_dir",
@@ -840,33 +870,66 @@ export class SidecarProcess {
     }
     async hostFilesystemCall(session, vm, request) {
         const response = await this.sendRequest({
-            ownership: { scope: "vm", connection_id: session.connectionId, session_id: session.sessionId, vm_id: vm.vmId },
-            payload: { type: "host_filesystem_call", operation: request.operation, path: request.path, payload_size_bytes: request.payloadSizeBytes },
+            ownership: {
+                scope: "vm",
+                connection_id: session.connectionId,
+                session_id: session.sessionId,
+                vm_id: vm.vmId,
+            },
+            payload: {
+                type: "host_filesystem_call",
+                operation: request.operation,
+                path: request.path,
+                payload_size_bytes: request.payloadSizeBytes,
+            },
         });
         if (response.payload.type !== "filesystem_result") {
             throw new Error(`unexpected host_filesystem_call response: ${response.payload.type}`);
         }
-        return { operation: response.payload.operation, status: response.payload.status, payloadSizeBytes: response.payload.payload_size_bytes };
+        return {
+            operation: response.payload.operation,
+            status: response.payload.status,
+            payloadSizeBytes: response.payload.payload_size_bytes,
+        };
     }
     async persistenceLoad(session, key) {
         const response = await this.sendRequest({
-            ownership: { scope: "session", connection_id: session.connectionId, session_id: session.sessionId },
+            ownership: {
+                scope: "session",
+                connection_id: session.connectionId,
+                session_id: session.sessionId,
+            },
             payload: { type: "persistence_load", key },
         });
         if (response.payload.type !== "persistence_state") {
             throw new Error(`unexpected persistence_load response: ${response.payload.type}`);
         }
-        return { key: response.payload.key, found: response.payload.found, payloadSizeBytes: response.payload.payload_size_bytes };
+        return {
+            key: response.payload.key,
+            found: response.payload.found,
+            payloadSizeBytes: response.payload.payload_size_bytes,
+        };
     }
     async persistenceFlush(session, request) {
         const response = await this.sendRequest({
-            ownership: { scope: "session", connection_id: session.connectionId, session_id: session.sessionId },
-            payload: { type: "persistence_flush", key: request.key, payload_size_bytes: request.payloadSizeBytes },
+            ownership: {
+                scope: "session",
+                connection_id: session.connectionId,
+                session_id: session.sessionId,
+            },
+            payload: {
+                type: "persistence_flush",
+                key: request.key,
+                payload_size_bytes: request.payloadSizeBytes,
+            },
         });
         if (response.payload.type !== "persistence_flushed") {
             throw new Error(`unexpected persistence_flush response: ${response.payload.type}`);
         }
-        return { key: response.payload.key, committedBytes: response.payload.committed_bytes };
+        return {
+            key: response.payload.key,
+            committedBytes: response.payload.committed_bytes,
+        };
     }
     async waitForEvent(matcher, timeoutMs, options) {
         return await this.protocolClient.waitForEvent(matcher, timeoutMs, options);
@@ -961,6 +1024,8 @@ function toWireRootFilesystemEntry(entry) {
 function toWireMountDescriptor(descriptor) {
     return {
         guest_path: descriptor.guestPath,
+        guest_source: descriptor.guestSource ?? descriptor.plugin.id,
+        guest_fstype: descriptor.guestFstype ?? descriptor.plugin.id,
         read_only: descriptor.readOnly,
         plugin: {
             id: descriptor.plugin.id,

package/dist/test-runtime.d.ts

@@ -1,6 +1,8 @@
 import "./native-client.js";
-import { SidecarProcess } from "./kernel-proxy.js";
 import type { JsRuntimeConfig } from "./generated/JsRuntimeConfig.js";
+import type { VmLimitsConfig } from "./generated/VmLimitsConfig.js";
+import type { VmUserConfig } from "./generated/VmUserConfig.js";
+import { SidecarProcess } from "./kernel-proxy.js";
 export declare const AF_INET = 2;
 export declare const AF_UNIX = 1;
 export declare const SOCK_STREAM = 1;
@@ -61,7 +63,9 @@ export interface VirtualFileSystem {
     lstat(path: string): Promise<VirtualStat>;
     link(oldPath: string, newPath: string): Promise<void>;
     chmod(path: string, mode: number): Promise<void>;
-    chown(path: string, uid: number, gid: number): Promise<void>;
+    chown(path: string, uid: number, gid: number, options?: {
+        followSymlinks?: boolean;
+    }): Promise<void>;
     utimes(path: string, atime: number, mtime: number): Promise<void>;
     truncate(path: string, length: number): Promise<void>;
     pread(path: string, offset: number, length: number): Promise<Uint8Array>;
@@ -118,6 +122,7 @@ export interface ManagedProcess {
 export interface ShellHandle {
     pid: number;
     write(data: Uint8Array | string): void;
+    /** Ordered PTY output containing stdout and stderr exactly once. */
     onData: ((data: Uint8Array) => void) | null;
     resize(cols: number, rows: number): void;
     kill(signal?: number): void;
@@ -130,6 +135,7 @@ export interface OpenShellOptions {
     cwd?: string;
     cols?: number;
     rows?: number;
+    /** Optional stderr-only diagnostic tap; do not render it alongside `onData`. */
     onStderr?: (data: Uint8Array) => void;
 }
 export interface ConnectTerminalOptions extends OpenShellOptions {
@@ -182,7 +188,7 @@ export interface Permissions {
     binding?: BindingPermissions;
 }
 /** A worked example shown alongside a registered binding. */
-export interface HostToolExample {
+export interface BindingExample {
     /** What this example demonstrates. */
     description: string;
     /** Example input matching the binding's input schema. */
@@ -204,7 +210,7 @@ export interface BindingDefinition {
     /** Abort the invocation after this many milliseconds. */
     timeoutMs?: number;
     /** Worked examples shown alongside the binding. */
-    examples?: HostToolExample[];
+    examples?: BindingExample[];
     /**
      * Extra command names the guest can use to invoke this binding, in addition
      * to the key it is registered under.
@@ -329,6 +335,7 @@ export interface Kernel extends KernelInterface {
     removeFile(path: string): Promise<void>;
     removeDir(path: string): Promise<void>;
     rename(oldPath: string, newPath: string): Promise<void>;
+    pwrite(path: string, offset: number, data: Uint8Array): Promise<void>;
     vmFetch(request: {
         port: number;
         method: string;
@@ -336,7 +343,7 @@ export interface Kernel extends KernelInterface {
         headersJson: string;
         body?: string;
     }): Promise<string>;
-    registerHostTools(tools: Record<string, BindingDefinition>): Promise<void>;
+    registerBindings(bindings: Record<string, BindingDefinition>): Promise<void>;
     getResourceSnapshot(): Promise<{
         runningProcesses: number;
         exitedProcesses: number;
@@ -453,7 +460,9 @@ export declare class InMemoryFileSystem implements VirtualFileSystem {
     lstat(targetPath: string): Promise<VirtualStat>;
     link(oldPath: string, newPath: string): Promise<void>;
     chmod(targetPath: string, mode: number): Promise<void>;
-    chown(targetPath: string, uid: number, gid: number): Promise<void>;
+    chown(targetPath: string, uid: number, gid: number, options?: {
+        followSymlinks?: boolean;
+    }): Promise<void>;
     utimes(targetPath: string, atime: number, mtime: number): Promise<void>;
     truncate(targetPath: string, length: number): Promise<void>;
     pread(targetPath: string, offset: number, length: number): Promise<Uint8Array>;
@@ -491,7 +500,9 @@ export declare class NodeFileSystem implements VirtualFileSystem {
     lstat(targetPath: string): Promise<VirtualStat>;
     link(oldPath: string, newPath: string): Promise<void>;
     chmod(targetPath: string, mode: number): Promise<void>;
-    chown(targetPath: string, uid: number, gid: number): Promise<void>;
+    chown(targetPath: string, uid: number, gid: number, options?: {
+        followSymlinks?: boolean;
+    }): Promise<void>;
     utimes(targetPath: string, atime: number, mtime: number): Promise<void>;
     truncate(targetPath: string, length: number): Promise<void>;
     pread(targetPath: string, offset: number, length: number): Promise<Uint8Array>;
@@ -550,12 +561,14 @@ export declare function createKernel(options: {
     permissions?: Permissions;
     env?: Record<string, string>;
     cwd?: string;
+    user?: VmUserConfig;
     sidecar?: SidecarProcess;
     onBootTiming?: (timing: KernelBootTiming) => void;
     maxProcesses?: number;
     hostNetworkAdapter?: unknown;
     loopbackExemptPorts?: number[];
     jsRuntime?: Partial<JsRuntimeConfig>;
+    limits?: VmLimitsConfig;
     logger?: unknown;
     mounts?: Array<{
         path: string;
@@ -563,4 +576,5 @@ export declare function createKernel(options: {
         readOnly?: boolean;
     }>;
     syncFilesystemOnDispose?: boolean;
+    maxFilesystemBytes?: number;
 }): Kernel;