@rivet-dev/agentos-runtime-core 0.2.7 → 0.2.8-rc.2

package/dist/correlation.d.ts

@@ -1,9 +1,6 @@
 export declare class PendingResponseRegistry<TResponse> {
     private readonly pending;
-    waitForResponse(requestId: number, options: {
-        timeoutMs: number;
-        timeoutMessage: () => string;
-    }): Promise<TResponse>;
+    waitForResponse(requestId: number): Promise<TResponse>;
     resolve(requestId: number, frame: TResponse): boolean;
     reject(requestId: number, error: Error): boolean;
     rejectAll(error: Error): void;

package/dist/correlation.js

@@ -1,27 +1,24 @@
 export class PendingResponseRegistry {
     pending = new Map();
-    waitForResponse(requestId, options) {
+    // Deliberately no per-request timer: local framed stdio never loses frames,
+    // so a response is bounded by the transport's silence watchdog (a dead or
+    // wedged sidecar rejects all pending requests through `rejectAll`) rather
+    // than by guessing how long any one request should take.
+    waitForResponse(requestId) {
         if (this.pending.has(requestId)) {
             throw new Error(`response waiter already registered for request ${requestId}`);
         }
         return new Promise((resolve, reject) => {
-            const entry = {
+            this.pending.set(requestId, {
                 resolve: (frame) => {
-                    clearTimeout(entry.timer);
                     this.pending.delete(requestId);
                     resolve(frame);
                 },
                 reject: (error) => {
-                    clearTimeout(entry.timer);
                     this.pending.delete(requestId);
                     reject(error);
                 },
-                timer: setTimeout(() => {
-                    this.pending.delete(requestId);
-                    reject(new Error(options.timeoutMessage()));
-                }, options.timeoutMs),
-            };
-            this.pending.set(requestId, entry);
+            });
         });
     }
     resolve(requestId, frame) {

package/dist/frame-rpc.d.ts

@@ -24,15 +24,20 @@ export declare class FrameRpcTransport<TReadFrame, TWriteFrame, TResponseFrame,
     private readonly pendingResponses;
     private readonly eventListeners;
     private readonly sidecarRequestListeners;
+    private readonly frameActivityListeners;
     constructor(options: FrameRpcTransportOptions<TReadFrame, TWriteFrame, TResponseFrame, TEventFrame, TSidecarRequestFrame>);
     onEvent(handler: (event: TEventFrame) => void): () => void;
+    /**
+     * Observe every classified inbound frame (response, event, or sidecar
+     * request) before it is routed. This is the transport's liveness signal:
+     * the silence watchdog resets on each invocation, so ANY inbound traffic —
+     * not just heartbeats — proves the sidecar is alive.
+     */
+    onFrameActivity(handler: () => void): () => void;
     onSidecarRequest(handler: (request: TSidecarRequestFrame) => void): () => void;
     onError(handler: (error: Error) => void): () => void;
     onEnd(handler: () => void): () => void;
-    sendFrame(requestId: number, frame: TWriteFrame, options: {
-        timeoutMs: number;
-        timeoutMessage: () => string;
-    }): Promise<TResponseFrame>;
+    sendFrame(requestId: number, frame: TWriteFrame): Promise<TResponseFrame>;
     writeFrame(frame: TWriteFrame): Promise<void>;
     rejectAll(error: Error): void;
     dispose(): void;

package/dist/frame-rpc.js

@@ -5,6 +5,7 @@ export class FrameRpcTransport {
     pendingResponses = new PendingResponseRegistry();
     eventListeners = new Set();
     sidecarRequestListeners = new Set();
+    frameActivityListeners = new Set();
     constructor(options) {
         if (options.frameTransport) {
             this.frameTransport = options.frameTransport;
@@ -30,6 +31,18 @@ export class FrameRpcTransport {
             this.eventListeners.delete(handler);
         };
     }
+    /**
+     * Observe every classified inbound frame (response, event, or sidecar
+     * request) before it is routed. This is the transport's liveness signal:
+     * the silence watchdog resets on each invocation, so ANY inbound traffic —
+     * not just heartbeats — proves the sidecar is alive.
+     */
+    onFrameActivity(handler) {
+        this.frameActivityListeners.add(handler);
+        return () => {
+            this.frameActivityListeners.delete(handler);
+        };
+    }
     onSidecarRequest(handler) {
         this.sidecarRequestListeners.add(handler);
         return () => {
@@ -42,8 +55,8 @@ export class FrameRpcTransport {
     onEnd(handler) {
         return this.frameTransport.onEnd(handler);
     }
-    async sendFrame(requestId, frame, options) {
-        const response = this.pendingResponses.waitForResponse(requestId, options);
+    async sendFrame(requestId, frame) {
+        const response = this.pendingResponses.waitForResponse(requestId);
         void this.writeFrame(frame).catch((error) => {
             this.pendingResponses.reject(requestId, error instanceof Error ? error : new Error(String(error)));
         });
@@ -60,8 +73,12 @@ export class FrameRpcTransport {
         this.pendingResponses.rejectAll(new Error("frame rpc transport disposed"));
         this.eventListeners.clear();
         this.sidecarRequestListeners.clear();
+        this.frameActivityListeners.clear();
     }
     dispatchFrame(classified) {
+        for (const listener of this.frameActivityListeners) {
+            listener();
+        }
         switch (classified.kind) {
             case "response":
                 this.pendingResponses.resolve(classified.requestId, classified.frame);

package/dist/kernel-proxy.d.ts

@@ -163,4 +163,4 @@ export declare class NativeSidecarKernelProxy {
     private updateTrackedProcessSnapshot;
 }
 export type { AuthenticatedSession, CreatedVm, GuestFilesystemStat, SidecarSpawnOptions, RootFilesystemEntry, SidecarEventSelector, SidecarPermissionsPolicy, SidecarRegisteredHostCallbackDefinition, SidecarRequestFrame, SidecarRequestHandler, SidecarResponsePayload, SidecarSessionState, SidecarSignalHandlerRegistration, SidecarSocketStateEntry, } from "./sidecar-process.js";
-export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarProcess, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "./sidecar-process.js";
+export { SidecarProcess, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "./sidecar-process.js";

package/dist/kernel-proxy.js

@@ -506,7 +506,7 @@ export class NativeSidecarKernelProxy {
         return proc;
     }
     openShell(options) {
-        const stdoutHandlers = new Set();
+        const terminalHandlers = new Set();
         const stderrHandlers = new Set();
         const command = options?.command ?? "sh";
         const args = options?.args ??
@@ -565,7 +565,7 @@ export class NativeSidecarKernelProxy {
             const normalized = normalizeSyntheticTerminalText(text);
             updateSyntheticCursor(normalized);
             const chunk = textEncoder.encode(normalized);
-            for (const handler of stdoutHandlers) {
+            for (const handler of terminalHandlers) {
                 handler(chunk);
             }
         };
@@ -576,7 +576,7 @@ export class NativeSidecarKernelProxy {
             const normalized = normalizeSyntheticTerminalText(text);
             updateSyntheticCursor(normalized);
             const chunk = textEncoder.encode(normalized);
-            for (const handler of stdoutHandlers) {
+            for (const handler of terminalHandlers) {
                 handler(chunk);
             }
         };
@@ -621,7 +621,7 @@ export class NativeSidecarKernelProxy {
             commandInFlight = false;
             const promptPrefix = syntheticCursorAtLineStart ? "" : "\r\n";
             const promptChunk = textEncoder.encode(`${promptPrefix}${promptText}`);
-            for (const handler of stdoutHandlers) {
+            for (const handler of terminalHandlers) {
                 handler(promptChunk);
             }
             syntheticCursorAtLineStart = false;
@@ -658,7 +658,7 @@ export class NativeSidecarKernelProxy {
             }
         };
         let onData = null;
-        stdoutHandlers.add((data) => onData?.(data));
+        terminalHandlers.add((data) => onData?.(data));
         if (options?.onStderr) {
             stderrHandlers.add(options.onStderr);
         }
@@ -817,7 +817,7 @@ export class NativeSidecarKernelProxy {
             cwd: options?.cwd,
             streamStdin: true,
             onStdout: (chunk) => {
-                for (const handler of stdoutHandlers) {
+                for (const handler of terminalHandlers) {
                     handler(chunk);
                 }
                 if (commandInFlight) {
@@ -825,6 +825,11 @@ export class NativeSidecarKernelProxy {
                 }
             },
             onStderr: (chunk) => {
+                // `onData` is the ordered PTY rendering stream. `onStderr` remains an
+                // optional channel-specific diagnostic tap and must not also be rendered.
+                for (const handler of terminalHandlers) {
+                    handler(chunk);
+                }
                 for (const handler of stderrHandlers) {
                     handler(chunk);
                 }
@@ -878,13 +883,7 @@ export class NativeSidecarKernelProxy {
         const stdin = process.stdin;
         const stdout = process.stdout;
         const { onData, ...shellOptions } = options ?? {};
-        const shell = this.openShell({
-            ...shellOptions,
-            onStderr: shellOptions.onStderr ??
-                ((data) => {
-                    process.stderr.write(data);
-                }),
-        });
+        const shell = this.openShell(shellOptions);
         const outputHandler = onData ??
             ((data) => {
                 stdout.write(data);
@@ -985,6 +984,10 @@ export class NativeSidecarKernelProxy {
         }
         return this.client.rename(this.session, this.vm, oldPath, newPath);
     }
+    // Test-runtime only: runtime mounts registered here stay host-side local
+    // compat mounts and are not delivered to the sidecar. The production proxy
+    // in @rivet-dev/agentos-core reconfigures sidecar mounts on every
+    // mountFs/unmountFs.
     mountFs(path, driver, options) {
         this.localMounts.unshift({
             path: posixPath.normalize(path),
@@ -1727,21 +1730,27 @@ function isMissingHostProcessError(error) {
 function errnoError(code, message) {
     return Object.assign(new Error(`${code}: ${message}`), { code });
 }
+// VirtualStat is a numeric, Node-default-shaped view: u64 fields above
+// Number.MAX_SAFE_INTEGER lose precision here, same as Node's non-bigint
+// fs.stat on the host.
 function toVirtualStat(stat) {
     return {
         mode: stat.mode,
-        size: stat.size,
-        blocks: stat.blocks,
-        dev: stat.dev,
-        rdev: stat.rdev,
+        size: Number(stat.size),
+        sizeExact: stat.size,
+        blocks: Number(stat.blocks),
+        dev: Number(stat.dev),
+        rdev: Number(stat.rdev),
         isDirectory: stat.is_directory,
         isSymbolicLink: stat.is_symbolic_link,
         atimeMs: stat.atime_ms,
         mtimeMs: stat.mtime_ms,
         ctimeMs: stat.ctime_ms,
         birthtimeMs: stat.birthtime_ms,
-        ino: stat.ino,
-        nlink: stat.nlink,
+        ino: Number(stat.ino),
+        inoExact: stat.ino,
+        nlink: Number(stat.nlink),
+        nlinkExact: stat.nlink,
         uid: stat.uid,
         gid: stat.gid,
     };
@@ -1774,4 +1783,4 @@ function socketLookupKey(kind, request) {
         path: request.path ?? null,
     });
 }
-export { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, SidecarProcess, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "./sidecar-process.js";
+export { SidecarProcess, SidecarEventBufferOverflow, SidecarProcessError, SidecarProcessExited, } from "./sidecar-process.js";

package/dist/native-client.d.ts

@@ -4,7 +4,6 @@ import type { LiveEventFrame, LiveResponseFrame, LiveSidecarRequestHandler, Prot
 import type { LiveOwnershipScope } from "./ownership.js";
 import type { LiveRequestPayload } from "./request-payloads.js";
 import type { LiveSidecarEventSelector } from "./event-buffer.js";
-export declare const DEFAULT_SIDECAR_FRAME_TIMEOUT_MS = 120000;
 export declare const DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY = 4096;
 export declare const DEFAULT_SIDECAR_GRACEFUL_EXIT_MS = 5000;
 export declare const DEFAULT_SIDECAR_FORCE_EXIT_MS = 2000;
@@ -12,12 +11,17 @@ export interface StdioSidecarProtocolClientSpawnOptions {
     cwd?: string;
     command?: string;
     args?: string[];
-    frameTimeoutMs?: number;
     eventBufferCapacity?: number;
     gracefulExitMs?: number;
     forceExitMs?: number;
     disposedErrorMessage?: string;
     payloadCodec?: ProtocolFramePayloadCodec;
+    /**
+     * Override the silence watchdog window (default 30s). Tests only — the
+     * window is a fixed protocol constant paired with the sidecar's 10s
+     * heartbeat cadence, not an operator tunable.
+     */
+    silenceTimeoutMs?: number;
 }
 export declare class StdioSidecarProtocolClient implements SidecarProcessTransport {
     readonly child: StdioSidecarProcess["child"];

package/dist/native-client.js

@@ -2,7 +2,6 @@ import { resolvePublishedSidecarBinary } from "./binary.js";
 import { SidecarProcessExited, StdioSidecarProcess, } from "./process.js";
 import { SidecarProtocolClient } from "./protocol-client.js";
 import { registerSidecarProcessSpawnFactory } from "./sidecar-process.js";
-export const DEFAULT_SIDECAR_FRAME_TIMEOUT_MS = 120_000;
 export const DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY = 4_096;
 export const DEFAULT_SIDECAR_GRACEFUL_EXIT_MS = 5_000;
 export const DEFAULT_SIDECAR_FORCE_EXIT_MS = 2_000;
@@ -22,9 +21,20 @@ export class StdioSidecarProtocolClient {
         this.protocolClient = new SidecarProtocolClient({
             stdin: this.child.stdin,
             stdout: this.child.stdout,
-            frameTimeoutMs: options.frameTimeoutMs,
             eventBufferCapacity: options.eventBufferCapacity,
             payloadCodec: options.payloadCodec,
+            silenceTimeoutMs: options.silenceTimeoutMs,
+            // A silent sidecar is dead or wedged; reap the process so it cannot
+            // linger as a zombie holding VM resources. The watchdog then rejects
+            // all in-flight requests with `SidecarSilenceTimeout`.
+            onSilenceExpired: () => {
+                try {
+                    this.child.kill("SIGKILL");
+                }
+                catch {
+                    // The child may have exited between the check and the kill.
+                }
+            },
             stderrText: () => this.sidecarProcess.stderrText(),
             streamEndedError: () => this.sidecarProcess.currentExitError() ??
                 new SidecarProcessExited({
@@ -47,7 +57,7 @@ export class StdioSidecarProtocolClient {
             args: options.args ?? [],
             cwd: options.cwd,
         }), {
-            frameTimeoutMs: options.frameTimeoutMs ?? DEFAULT_SIDECAR_FRAME_TIMEOUT_MS,
+            silenceTimeoutMs: options.silenceTimeoutMs,
             eventBufferCapacity: options.eventBufferCapacity ??
                 DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY,
             gracefulExitMs: options.gracefulExitMs ?? DEFAULT_SIDECAR_GRACEFUL_EXIT_MS,

package/dist/protocol-client.d.ts

@@ -8,17 +8,25 @@ export interface SidecarProtocolClientOptions {
     frameTransport?: FrameTransport<LiveResponseFrame | LiveEventFrame | LiveSidecarRequestFrame, LiveProtocolFrame>;
     stdin?: Writable;
     stdout?: Readable;
-    frameTimeoutMs: number;
     eventBufferCapacity: number;
     payloadCodec?: ProtocolFramePayloadCodec;
     stderrText?: () => string;
     frameError?: (error: Error) => Error;
     streamEndedError?: () => Error;
+    /** Override the silence watchdog window. Tests only; production uses the default. */
+    silenceTimeoutMs?: number;
+    /**
+     * Runs when the silence watchdog fires, before pending work is rejected.
+     * The stdio layer uses it to SIGKILL the sidecar child.
+     */
+    onSilenceExpired?: () => void;
 }
 export declare class SidecarProtocolClient {
     private readonly eventBuffer;
     private readonly eventListeners;
-    private readonly frameTimeoutMs;
+    private readonly silenceTimeoutMs;
+    private silenceTimer;
+    private lastInboundAtMs;
     private readonly payloadCodec;
     private readonly stderrText;
     private readonly hostFrameFactory;
@@ -27,6 +35,15 @@ export declare class SidecarProtocolClient {
     private readonly eventWaiters;
     private sidecarRequestHandler;
     constructor(options: SidecarProtocolClientOptions);
+    /**
+     * Arm the silence watchdog: ANY inbound frame resets the clock (see the
+     * `onFrameActivity` tap above), and the sidecar heartbeats every 10s even
+     * while busy, so sustained silence for the full window means the process
+     * is dead or wedged — not slow. The check interval is unref'd so an idle
+     * host process can still exit naturally.
+     */
+    private startSilenceWatchdog;
+    private stopSilenceWatchdog;
     setSidecarRequestHandler(handler: LiveSidecarRequestHandler | null): void;
     onEvent(handler: (event: LiveEventFrame) => void): () => void;
     sendRequest(input: {

package/dist/protocol-client.js

@@ -1,10 +1,21 @@
 import { SidecarEventBuffer, SidecarEventBufferOverflow, normalizeSidecarEventMatcher, sidecarEventWaitAbortError, } from "./event-buffer.js";
 import { FrameRpcTransport } from "./frame-rpc.js";
 import { HostProtocolFrameFactory, classifySidecarWrittenProtocolFrame, decodeProtocolFramePayload, encodeProtocolFramePayload, resolveSidecarRequestFramePayload, } from "./protocol-frames.js";
+import { SidecarSilenceTimeout } from "./sidecar-errors.js";
+/**
+ * How long the host tolerates TOTAL inbound silence (no responses, events,
+ * sidecar requests, or heartbeats) before declaring the sidecar dead. The
+ * sidecar heartbeats every 10s from a dedicated thread, so this allows two
+ * missed beats plus margin; it bounds "sidecar is dead or wedged", never "this
+ * request is slow" — individual requests have no deadline of their own.
+ */
+const DEFAULT_SIDECAR_SILENCE_TIMEOUT_MS = 30_000;
 export class SidecarProtocolClient {
     eventBuffer;
     eventListeners = new Set();
-    frameTimeoutMs;
+    silenceTimeoutMs;
+    silenceTimer = null;
+    lastInboundAtMs = 0;
     payloadCodec;
     stderrText;
     hostFrameFactory = new HostProtocolFrameFactory();
@@ -13,7 +24,8 @@ export class SidecarProtocolClient {
     eventWaiters = new Set();
     sidecarRequestHandler = null;
     constructor(options) {
-        this.frameTimeoutMs = options.frameTimeoutMs;
+        this.silenceTimeoutMs =
+            options.silenceTimeoutMs ?? DEFAULT_SIDECAR_SILENCE_TIMEOUT_MS;
         this.eventBuffer = new SidecarEventBuffer(options.eventBufferCapacity);
         this.payloadCodec = options.payloadCodec ?? "bare";
         this.stderrText = options.stderrText ?? (() => "");
@@ -38,6 +50,45 @@ export class SidecarProtocolClient {
             this.failPermanently(options.streamEndedError?.() ??
                 new Error("sidecar protocol stream ended"));
         });
+        this.frameTransport.onFrameActivity(() => {
+            this.lastInboundAtMs = performance.now();
+        });
+        this.startSilenceWatchdog(options.onSilenceExpired);
+    }
+    /**
+     * Arm the silence watchdog: ANY inbound frame resets the clock (see the
+     * `onFrameActivity` tap above), and the sidecar heartbeats every 10s even
+     * while busy, so sustained silence for the full window means the process
+     * is dead or wedged — not slow. The check interval is unref'd so an idle
+     * host process can still exit naturally.
+     */
+    startSilenceWatchdog(onExpired) {
+        this.lastInboundAtMs = performance.now();
+        const checkIntervalMs = Math.max(Math.min(this.silenceTimeoutMs / 4, 1_000), 10);
+        this.silenceTimer = setInterval(() => {
+            const silenceMs = performance.now() - this.lastInboundAtMs;
+            if (silenceMs < this.silenceTimeoutMs) {
+                return;
+            }
+            this.stopSilenceWatchdog();
+            const error = new SidecarSilenceTimeout({
+                silenceMs,
+                stderr: this.stderrText(),
+            });
+            try {
+                onExpired?.();
+            }
+            finally {
+                this.failPermanently(error);
+            }
+        }, checkIntervalMs);
+        this.silenceTimer.unref?.();
+    }
+    stopSilenceWatchdog() {
+        if (this.silenceTimer !== null) {
+            clearInterval(this.silenceTimer);
+            this.silenceTimer = null;
+        }
     }
     setSidecarRequestHandler(handler) {
         this.sidecarRequestHandler = handler;
@@ -53,10 +104,10 @@ export class SidecarProtocolClient {
             throw this.closedError;
         }
         const request = this.hostFrameFactory.createRequestFrame(input);
-        const response = await this.frameTransport.sendFrame(request.request_id, request, {
-            timeoutMs: this.frameTimeoutMs,
-            timeoutMessage: () => `timed out waiting for sidecar protocol frame for ${input.payload.type}\nstderr:\n${this.stderrText()}`,
-        });
+        // No per-request deadline: only the caller knows whether an operation is
+        // legitimately long (a whole agent turn is one request). A dead or
+        // wedged sidecar rejects this via the silence watchdog instead.
+        const response = await this.frameTransport.sendFrame(request.request_id, request);
         if (response.payload.type === "rejected") {
             throw new Error(`sidecar rejected request ${request.request_id}: ${response.payload.code}: ${response.payload.message}`);
         }
@@ -126,9 +177,11 @@ export class SidecarProtocolClient {
             }
         }
         this.closedError = error;
+        this.stopSilenceWatchdog();
         this.rejectPending(error);
     }
     dispose() {
+        this.stopSilenceWatchdog();
         this.frameTransport.dispose();
     }
     async writeFrame(frame) {
@@ -148,6 +201,14 @@ export class SidecarProtocolClient {
         }
     }
     dispatchEvent(event) {
+        // Transport-level liveness beats from the sidecar. Their arrival already
+        // reset the silence watchdog at the frame layer; they carry no meaning
+        // for consumers and must never reach the bounded event buffer, where a
+        // long-idle VM would accumulate one every 10s until overflow.
+        if (event.payload.type === "structured" &&
+            event.payload.name === "heartbeat") {
+            return;
+        }
         for (const listener of this.eventListeners) {
             try {
                 listener(event);

package/dist/response-payloads.d.ts

@@ -9,7 +9,7 @@ export interface LiveGuestDirEntry {
     path: string;
     isDirectory: boolean;
     isSymbolicLink: boolean;
-    size: number;
+    size: bigint;
 }
 export interface LiveSignalHandlerRegistration {
     action: LiveSignalDispositionAction;

package/dist/response-payloads.js

@@ -95,7 +95,7 @@ export function fromGeneratedResponsePayload(payload) {
                             path: entry.path,
                             isDirectory: entry.isDirectory,
                             isSymbolicLink: entry.isSymbolicLink,
-                            size: bigIntToSafeNumber(entry.size, "guest dir entry size"),
+                            size: entry.size,
                         })),
                     }
                     : {}),

package/dist/sidecar-errors.d.ts

@@ -8,6 +8,21 @@ export declare class SidecarProcessExited extends Error {
         stderr: string;
     });
 }
+/**
+ * The silence watchdog fired: the sidecar produced no protocol frames at all —
+ * not even its 10s liveness heartbeats — for the full silence window, so the
+ * process is dead or wedged (not merely busy: a busy sidecar still heartbeats
+ * from a dedicated thread). The host kills the sidecar and rejects every
+ * in-flight request with this error.
+ */
+export declare class SidecarSilenceTimeout extends Error {
+    readonly silenceMs: number;
+    readonly stderr: string;
+    constructor(options: {
+        silenceMs: number;
+        stderr: string;
+    });
+}
 export declare class SidecarProcessError extends Error {
     readonly childError: Error;
     readonly stderr: string;

package/dist/sidecar-errors.js

@@ -18,6 +18,23 @@ export class SidecarProcessExited extends Error {
         this.stderr = options.stderr;
     }
 }
+/**
+ * The silence watchdog fired: the sidecar produced no protocol frames at all —
+ * not even its 10s liveness heartbeats — for the full silence window, so the
+ * process is dead or wedged (not merely busy: a busy sidecar still heartbeats
+ * from a dedicated thread). The host kills the sidecar and rejects every
+ * in-flight request with this error.
+ */
+export class SidecarSilenceTimeout extends Error {
+    silenceMs;
+    stderr;
+    constructor(options) {
+        super(`sidecar unresponsive: no protocol frames or heartbeats for ${Math.round(options.silenceMs)}ms; killing sidecar${formatSidecarStderrSuffix(options.stderr)}`);
+        this.name = "SidecarSilenceTimeout";
+        this.silenceMs = options.silenceMs;
+        this.stderr = options.stderr;
+    }
+}
 export class SidecarProcessError extends Error {
     childError;
     stderr;

package/dist/sidecar-process.d.ts

@@ -9,10 +9,9 @@ import type { LiveFilesystemOperation, LiveGuestRuntimeKind, LiveWasmPermissionT
 import { type LiveEventFrame, type LiveSidecarRequestHandler, type LiveSidecarRequestFrame, type LiveSidecarResponseFrame, type ProtocolFramePayloadCodec } from "./protocol-frames.js";
 import type { LiveGuestDirEntry } from "./response-payloads.js";
 import { type LiveGuestFilesystemStat } from "./state.js";
-export { SidecarProcessError, SidecarProcessExited, } from "./sidecar-errors.js";
+export { SidecarProcessError, SidecarProcessExited, SidecarSilenceTimeout, } from "./sidecar-errors.js";
 export { SidecarEventBufferOverflow } from "./event-buffer.js";
 export { SidecarProcess as Sidecar };
-export declare const NATIVE_SIDECAR_FRAME_TIMEOUT_MS = 120000;
 type GuestRuntimeKind = Extract<LiveGuestRuntimeKind, "java_script" | "python" | "web_assembly">;
 type WasmPermissionTier = LiveWasmPermissionTier;
 export interface RootFilesystemEntry extends LiveRootFilesystemEntry {
@@ -105,20 +104,25 @@ export interface SidecarSpawnOptions {
     cwd?: string;
     command?: string;
     args?: string[];
-    frameTimeoutMs?: number;
     eventBufferCapacity?: number;
     payloadCodec?: NativeTransportPayloadCodec;
+    /**
+     * Override the sidecar silence watchdog window (default 30s). Tests only —
+     * it is a fixed protocol constant paired with the sidecar's 10s heartbeat
+     * cadence, not an operator tunable.
+     */
+    silenceTimeoutMs?: number;
 }
 export interface ResolvedSidecarSpawnOptions {
     cwd?: string;
     command?: string;
     args: string[];
-    frameTimeoutMs: number;
     eventBufferCapacity: number;
     gracefulExitMs: number;
     forceExitMs: number;
     disposedErrorMessage: string;
     payloadCodec: NativeTransportPayloadCodec;
+    silenceTimeoutMs?: number;
 }
 type SidecarProcessSpawnFactory = (options: ResolvedSidecarSpawnOptions) => SidecarProcessTransport;
 export declare function registerSidecarProcessSpawnFactory(factory: SidecarProcessSpawnFactory): void;

package/dist/sidecar-process.js

@@ -1,13 +1,12 @@
 import { decodeGuestFilesystemContent, encodeGuestFilesystemContent, } from "./filesystem.js";
 import { SIDECAR_PROTOCOL_SCHEMA } from "./protocol-schema.js";
-export { SidecarProcessError, SidecarProcessExited, } from "./sidecar-errors.js";
+export { SidecarProcessError, SidecarProcessExited, SidecarSilenceTimeout, } from "./sidecar-errors.js";
 export { SidecarEventBufferOverflow } from "./event-buffer.js";
 // `Sidecar` is the public name for the native sidecar process client. The class
 // is `SidecarProcess` internally; consumers import it as `Sidecar` via the
 // `@rivet-dev/agentos-runtime-core/sidecar-client` subpath and the package root.
 export { SidecarProcess as Sidecar };
 const BRIDGE_CONTRACT_VERSION = 1;
-export const NATIVE_SIDECAR_FRAME_TIMEOUT_MS = 120_000;
 const DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY = 4_096;
 const DEFAULT_SIDECAR_GRACEFUL_EXIT_MS = 5_000;
 const DEFAULT_SIDECAR_FORCE_EXIT_MS = 2_000;
@@ -31,7 +30,7 @@ export class SidecarProcess {
             command: options.command,
             args: options.args ?? [],
             cwd: options.cwd,
-            frameTimeoutMs: options.frameTimeoutMs ?? NATIVE_SIDECAR_FRAME_TIMEOUT_MS,
+            silenceTimeoutMs: options.silenceTimeoutMs,
             eventBufferCapacity: options.eventBufferCapacity ?? DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY,
             gracefulExitMs: DEFAULT_SIDECAR_GRACEFUL_EXIT_MS,
             forceExitMs: DEFAULT_SIDECAR_FORCE_EXIT_MS,

package/dist/state.d.ts

@@ -1,18 +1,18 @@
 import * as protocol from "./generated-protocol.js";
 export interface LiveGuestFilesystemStat {
     mode: number;
-    size: number;
-    blocks: number;
-    dev: number;
-    rdev: number;
+    size: bigint;
+    blocks: bigint;
+    dev: bigint;
+    rdev: bigint;
     is_directory: boolean;
     is_symbolic_link: boolean;
     atime_ms: number;
     mtime_ms: number;
     ctime_ms: number;
     birthtime_ms: number;
-    ino: number;
-    nlink: number;
+    ino: bigint;
+    nlink: bigint;
     uid: number;
     gid: number;
 }

package/dist/state.js

@@ -1,20 +1,19 @@
-import { bigIntToSafeNumber } from "./numbers.js";
 import { fromGeneratedProcessSnapshotStatus } from "./protocol-maps.js";
 export function fromGeneratedGuestFilesystemStat(stat) {
     return {
         mode: stat.mode,
-        size: bigIntToSafeNumber(stat.size, "guest filesystem stat size"),
-        blocks: bigIntToSafeNumber(stat.blocks, "guest filesystem stat blocks"),
-        dev: bigIntToSafeNumber(stat.dev, "guest filesystem stat dev"),
-        rdev: bigIntToSafeNumber(stat.rdev, "guest filesystem stat rdev"),
+        size: stat.size,
+        blocks: stat.blocks,
+        dev: stat.dev,
+        rdev: stat.rdev,
         is_directory: stat.isDirectory,
         is_symbolic_link: stat.isSymbolicLink,
-        atime_ms: bigIntToSafeNumber(stat.atimeMs, "guest filesystem stat atime"),
-        mtime_ms: bigIntToSafeNumber(stat.mtimeMs, "guest filesystem stat mtime"),
-        ctime_ms: bigIntToSafeNumber(stat.ctimeMs, "guest filesystem stat ctime"),
-        birthtime_ms: bigIntToSafeNumber(stat.birthtimeMs, "guest filesystem stat birthtime"),
-        ino: bigIntToSafeNumber(stat.ino, "guest filesystem stat ino"),
-        nlink: bigIntToSafeNumber(stat.nlink, "guest filesystem stat nlink"),
+        atime_ms: Number(stat.atimeMs),
+        mtime_ms: Number(stat.mtimeMs),
+        ctime_ms: Number(stat.ctimeMs),
+        birthtime_ms: Number(stat.birthtimeMs),
+        ino: stat.ino,
+        nlink: stat.nlink,
         uid: stat.uid,
         gid: stat.gid,
     };

package/dist/test-runtime.d.ts

@@ -23,6 +23,7 @@ export interface VirtualDirEntry {
 export interface VirtualStat {
     mode: number;
     size: number;
+    sizeExact?: bigint;
     blocks: number;
     dev: number;
     rdev: number;
@@ -33,7 +34,9 @@ export interface VirtualStat {
     ctimeMs: number;
     birthtimeMs: number;
     ino: number;
+    inoExact?: bigint;
     nlink: number;
+    nlinkExact?: bigint;
     uid: number;
     gid: number;
 }
@@ -115,6 +118,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;
@@ -127,6 +131,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 {

package/dist/test-runtime.js

@@ -5,7 +5,7 @@ import * as path from "node:path";
 import * as posixPath from "node:path/posix";
 import { fileURLToPath } from "node:url";
 import "./native-client.js";
-import { NATIVE_SIDECAR_FRAME_TIMEOUT_MS, NativeSidecarKernelProxy, SidecarProcess, serializeMountConfigForSidecar, } from "./kernel-proxy.js";
+import { NativeSidecarKernelProxy, SidecarProcess, serializeMountConfigForSidecar, } from "./kernel-proxy.js";
 import { resolvePublishedSidecarBinary } from "./binary.js";
 import { findCargoBinary, resolveCargoBinary } from "./cargo.js";
 export const AF_INET = 2;
@@ -2062,7 +2062,6 @@ class NativeKernel {
                 cwd: REPO_ROOT,
                 command: ensureNativeSidecarBinary(),
                 args: [],
-                frameTimeoutMs: NATIVE_SIDECAR_FRAME_TIMEOUT_MS,
             }));
         const session = await this.measureBoot("session_open", () => client.authenticateAndOpenSession());
         const vm = await this.measureBoot("vm_create", () => client.createVm(session, {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rivet-dev/agentos-runtime-core",
-	"version": "0.2.7",
+	"version": "0.2.8-rc.2",
 	"type": "module",
 	"license": "Apache-2.0",
 	"main": "./dist/index.js",
@@ -192,7 +192,7 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@rivet-dev/agentos-runtime-sidecar": "0.2.7",
+		"@rivet-dev/agentos-runtime-sidecar": "0.2.8-rc.2",
 		"@rivetkit/bare-ts": "^0.6.2",
 		"zod": "^4.1.11"
 	},