@rivet-dev/agentos-runtime-core 0.0.0-agent-acp-codex-session-benchmark.62b1f46

package/dist/protocol-client.js

@@ -0,0 +1,270 @@
+import { normalizeSidecarEventMatcher, SidecarEventBuffer, SidecarEventBufferOverflow, sidecarEventWaitAbortError, } from "./event-buffer.js";
+import { FrameRpcTransport } from "./frame-rpc.js";
+import { ownershipMatchesSelector, ownershipSelectorKey, } from "./ownership.js";
+import { classifySidecarWrittenProtocolFrame, decodeProtocolFramePayload, encodeProtocolFramePayload, HostProtocolFrameFactory, resolveSidecarRequestFramePayload, } from "./protocol-frames.js";
+import { SidecarRequestRejected, 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();
+    silenceTimeoutMs;
+    silenceTimer = null;
+    lastInboundAtMs = 0;
+    payloadCodec;
+    stderrText;
+    hostFrameFactory = new HostProtocolFrameFactory();
+    frameTransport;
+    closedError = null;
+    eventWaiters = new Set();
+    sidecarRequestHandlers = new Map();
+    constructor(options) {
+        this.silenceTimeoutMs =
+            options.silenceTimeoutMs ?? DEFAULT_SIDECAR_SILENCE_TIMEOUT_MS;
+        this.eventBuffer = new SidecarEventBuffer(options.eventBufferCapacity);
+        this.payloadCodec = options.payloadCodec ?? "bare";
+        this.stderrText = options.stderrText ?? (() => "");
+        this.frameTransport = new FrameRpcTransport({
+            frameTransport: options.frameTransport,
+            stdin: options.stdin,
+            stdout: options.stdout,
+            encodeFrame: (frame) => encodeProtocolFramePayload(frame, this.payloadCodec),
+            decodeFrame: (payload) => decodeProtocolFramePayload(payload, this.payloadCodec),
+            classifyFrame: classifySidecarWrittenProtocolFrame,
+        });
+        this.frameTransport.onEvent((event) => {
+            this.dispatchEvent(event);
+        });
+        this.frameTransport.onSidecarRequest((request) => {
+            void this.dispatchSidecarRequest(request);
+        });
+        this.frameTransport.onError((error) => {
+            this.failPermanently(options.frameError?.(error) ?? error);
+        });
+        this.frameTransport.onEnd(() => {
+            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;
+        }
+    }
+    registerSidecarRequestHandler(ownership, handler) {
+        const key = ownershipSelectorKey(ownership);
+        if (this.sidecarRequestHandlers.has(key)) {
+            throw new Error(`sidecar request handler already registered for ${key}`);
+        }
+        const registration = { ownership, handler };
+        this.sidecarRequestHandlers.set(key, registration);
+        return () => {
+            if (this.sidecarRequestHandlers.get(key) === registration) {
+                this.sidecarRequestHandlers.delete(key);
+            }
+        };
+    }
+    onEvent(handler, ownership) {
+        const registration = { handler, ownership };
+        this.eventListeners.add(registration);
+        return () => {
+            this.eventListeners.delete(registration);
+        };
+    }
+    async sendRequest(input) {
+        if (this.closedError) {
+            throw this.closedError;
+        }
+        const request = this.hostFrameFactory.createRequestFrame(input);
+        // 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, (frame) => {
+            this.validateResponse(frame);
+            input.onResponse?.(frame);
+        });
+        this.validateResponse(response);
+        return response;
+    }
+    validateResponse(response) {
+        if (response.payload.type === "rejected") {
+            throw new SidecarRequestRejected({
+                code: response.payload.code,
+                message: response.payload.message,
+                response,
+            });
+        }
+    }
+    async waitForEvent(matcher, timeoutMs, options) {
+        if (this.closedError instanceof SidecarEventBufferOverflow) {
+            throw this.closedError;
+        }
+        const normalizedMatcher = normalizeSidecarEventMatcher(matcher);
+        const bufferedEvent = this.eventBuffer.take(normalizedMatcher);
+        if (bufferedEvent) {
+            return bufferedEvent;
+        }
+        if (this.closedError) {
+            throw this.closedError;
+        }
+        if (options?.signal?.aborted) {
+            throw sidecarEventWaitAbortError(options.signal.reason);
+        }
+        return await new Promise((resolve, reject) => {
+            let abortListener = null;
+            const waiter = {
+                matches: normalizedMatcher.matches,
+                resolve: (event) => {
+                    if (waiter.timer !== null) {
+                        clearTimeout(waiter.timer);
+                    }
+                    if (abortListener) {
+                        options?.signal?.removeEventListener("abort", abortListener);
+                        abortListener = null;
+                    }
+                    this.eventWaiters.delete(waiter);
+                    resolve(event);
+                },
+                reject: (error) => {
+                    if (waiter.timer !== null) {
+                        clearTimeout(waiter.timer);
+                    }
+                    if (abortListener) {
+                        options?.signal?.removeEventListener("abort", abortListener);
+                        abortListener = null;
+                    }
+                    this.eventWaiters.delete(waiter);
+                    reject(error);
+                },
+                timer: timeoutMs === undefined
+                    ? null
+                    : setTimeout(() => {
+                        this.eventWaiters.delete(waiter);
+                        reject(new Error(`timed out waiting for sidecar event\nstderr:\n${this.stderrText()}`));
+                    }, timeoutMs),
+            };
+            if (options?.signal) {
+                abortListener = () => {
+                    waiter.reject(sidecarEventWaitAbortError(options.signal?.reason));
+                };
+                options.signal.addEventListener("abort", abortListener, { once: true });
+            }
+            this.eventWaiters.add(waiter);
+        });
+    }
+    failPermanently(error, options) {
+        if (this.closedError) {
+            if (!options?.replaceExisting?.(this.closedError, error)) {
+                return;
+            }
+        }
+        this.closedError = error;
+        this.stopSilenceWatchdog();
+        this.rejectPending(error);
+    }
+    dispose() {
+        this.stopSilenceWatchdog();
+        this.sidecarRequestHandlers.clear();
+        this.eventListeners.clear();
+        this.frameTransport.dispose();
+    }
+    async writeFrame(frame) {
+        await this.frameTransport.writeFrame(frame);
+    }
+    async dispatchSidecarRequest(request) {
+        const handler = this.sidecarRequestHandlers.get(ownershipSelectorKey(request.ownership))?.handler;
+        const payload = await resolveSidecarRequestFramePayload(request, handler ?? null);
+        try {
+            await this.writeFrame(this.hostFrameFactory.createSidecarResponseFrame({
+                request,
+                payload,
+            }));
+        }
+        catch (error) {
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            this.failPermanently(normalized);
+        }
+    }
+    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) {
+            if (!ownershipMatchesSelector(listener.ownership, event.ownership)) {
+                continue;
+            }
+            try {
+                listener.handler(event);
+            }
+            catch {
+                // Event listeners are best-effort observers and must not break framing.
+            }
+        }
+        for (const waiter of this.eventWaiters) {
+            if (!waiter.matches(event)) {
+                continue;
+            }
+            waiter.resolve(event);
+            return;
+        }
+        this.bufferEvent(event);
+    }
+    bufferEvent(event) {
+        const overflow = this.eventBuffer.buffer(event);
+        if (overflow) {
+            this.failPermanently(overflow);
+        }
+    }
+    rejectPending(error) {
+        this.frameTransport.rejectAll(error);
+        for (const waiter of this.eventWaiters) {
+            waiter.reject(error);
+        }
+        this.eventWaiters.clear();
+    }
+}

package/dist/protocol-frames.d.ts

@@ -0,0 +1,68 @@
+import { type TransportPayloadCodec } from "./frame-payload-codec.js";
+import type { ClassifiedFrame } from "./frame-rpc.js";
+import { type LiveSidecarRequestPayload, type LiveSidecarResponsePayload } from "./callbacks.js";
+import { type LiveSidecarEventPayload } from "./event-buffer.js";
+import * as protocol from "./generated-protocol.js";
+import { type LiveOwnershipScope } from "./ownership.js";
+import { SIDECAR_PROTOCOL_SCHEMA } from "./protocol-schema.js";
+import { type LiveRequestPayload } from "./request-payloads.js";
+import { type LiveResponsePayload } from "./response-payloads.js";
+export interface LiveRequestFrame {
+    frame_type: "request";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    request_id: number;
+    ownership: LiveOwnershipScope;
+    payload: LiveRequestPayload;
+}
+export interface LiveEventFrame {
+    frame_type: "event";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    ownership: LiveOwnershipScope;
+    payload: LiveSidecarEventPayload;
+}
+export interface LiveSidecarRequestFrame {
+    frame_type: "sidecar_request";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    request_id: number;
+    ownership: LiveOwnershipScope;
+    payload: LiveSidecarRequestPayload;
+}
+export interface LiveResponseFrame {
+    frame_type: "response";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    request_id: number;
+    ownership: LiveOwnershipScope;
+    payload: LiveResponsePayload;
+}
+export interface LiveSidecarResponseFrame {
+    frame_type: "sidecar_response";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    request_id: number;
+    ownership: LiveOwnershipScope;
+    payload: LiveSidecarResponsePayload;
+}
+export type LiveProtocolFrame = LiveRequestFrame | LiveResponseFrame | LiveEventFrame | LiveSidecarRequestFrame | LiveSidecarResponseFrame;
+export type LiveSidecarWrittenProtocolFrame = LiveResponseFrame | LiveEventFrame | LiveSidecarRequestFrame;
+export type ProtocolFramePayloadCodec = TransportPayloadCodec;
+export type ClassifiedSidecarWrittenProtocolFrame = ClassifiedFrame<LiveResponseFrame, LiveEventFrame, LiveSidecarRequestFrame>;
+export type LiveSidecarRequestHandler = (request: LiveSidecarRequestFrame) => Promise<LiveSidecarResponsePayload> | LiveSidecarResponsePayload;
+export declare class HostProtocolFrameFactory {
+    private nextRequestId;
+    createRequestFrame(input: {
+        ownership: LiveOwnershipScope;
+        payload: LiveRequestPayload;
+    }): LiveRequestFrame;
+    createSidecarResponseFrame(input: {
+        request: LiveSidecarRequestFrame;
+        payload: LiveSidecarResponsePayload;
+    }): LiveSidecarResponseFrame;
+}
+export declare function resolveSidecarRequestFramePayload(request: LiveSidecarRequestFrame, handler: LiveSidecarRequestHandler | null): Promise<LiveSidecarResponsePayload>;
+export declare function toGeneratedProtocolFrame(frame: LiveProtocolFrame): protocol.ProtocolFrame;
+export declare function encodeBareProtocolFrame(frame: LiveProtocolFrame): Uint8Array;
+export declare function decodeBareProtocolFrame(payload: Uint8Array): LiveSidecarWrittenProtocolFrame;
+export declare function encodeProtocolFramePayload(frame: LiveProtocolFrame, codec: ProtocolFramePayloadCodec): Uint8Array;
+export declare function decodeProtocolFramePayload(payload: Uint8Array, codec: ProtocolFramePayloadCodec): LiveSidecarWrittenProtocolFrame;
+export declare function classifySidecarWrittenProtocolFrame(frame: LiveSidecarWrittenProtocolFrame): ClassifiedSidecarWrittenProtocolFrame;
+export declare function fromGeneratedSidecarWrittenProtocolFrame(frame: protocol.ProtocolFrame): LiveSidecarWrittenProtocolFrame;
+export declare function toLiveProtocolSchema(schema: protocol.ProtocolSchema): typeof SIDECAR_PROTOCOL_SCHEMA;

package/dist/protocol-frames.js

@@ -0,0 +1,139 @@
+import { toExactUint8Array } from "./bytes.js";
+import { decodeJsonFramePayload, encodeJsonFramePayload, } from "./frame-payload-codec.js";
+import { errorSidecarResponsePayload, fromGeneratedSidecarRequestPayload, isMatchingSidecarResponsePayload, toGeneratedSidecarResponsePayload, } from "./callbacks.js";
+import { fromGeneratedEventPayload, } from "./event-buffer.js";
+import * as protocol from "./generated-protocol.js";
+import { bigIntToSafeNumber } from "./numbers.js";
+import { fromGeneratedOwnershipScope, toGeneratedOwnershipScope, } from "./ownership.js";
+import { SIDECAR_PROTOCOL_SCHEMA, validateSidecarProtocolSchema, } from "./protocol-schema.js";
+import { toGeneratedRequestPayload, } from "./request-payloads.js";
+import { fromGeneratedResponsePayload, } from "./response-payloads.js";
+export class HostProtocolFrameFactory {
+    nextRequestId = 1;
+    createRequestFrame(input) {
+        return {
+            frame_type: "request",
+            schema: SIDECAR_PROTOCOL_SCHEMA,
+            request_id: this.nextRequestId++,
+            ownership: input.ownership,
+            payload: input.payload,
+        };
+    }
+    createSidecarResponseFrame(input) {
+        return {
+            frame_type: "sidecar_response",
+            schema: SIDECAR_PROTOCOL_SCHEMA,
+            request_id: input.request.request_id,
+            ownership: input.request.ownership,
+            payload: input.payload,
+        };
+    }
+}
+export async function resolveSidecarRequestFramePayload(request, handler) {
+    try {
+        if (!handler) {
+            throw new Error(`no sidecar request handler registered for ${request.payload.type}`);
+        }
+        const payload = await handler(request);
+        if (!isMatchingSidecarResponsePayload(request.payload, payload)) {
+            throw new Error(`sidecar handler returned ${payload.type} for ${request.payload.type}`);
+        }
+        return payload;
+    }
+    catch (error) {
+        return errorSidecarResponsePayload(request.payload, error);
+    }
+}
+export function toGeneratedProtocolFrame(frame) {
+    switch (frame.frame_type) {
+        case "request":
+            return {
+                tag: "RequestFrame",
+                val: {
+                    schema: frame.schema,
+                    requestId: BigInt(frame.request_id),
+                    ownership: toGeneratedOwnershipScope(frame.ownership),
+                    payload: toGeneratedRequestPayload(frame.payload),
+                },
+            };
+        case "sidecar_response":
+            return {
+                tag: "SidecarResponseFrame",
+                val: {
+                    schema: frame.schema,
+                    requestId: BigInt(frame.request_id),
+                    ownership: toGeneratedOwnershipScope(frame.ownership),
+                    payload: toGeneratedSidecarResponsePayload(frame.payload),
+                },
+            };
+        case "response":
+        case "event":
+        case "sidecar_request":
+            throw new Error(`BARE encoding is only implemented for host-written frames, received ${frame.frame_type}`);
+    }
+}
+export function encodeBareProtocolFrame(frame) {
+    return protocol.encodeProtocolFrame(toGeneratedProtocolFrame(frame));
+}
+export function decodeBareProtocolFrame(payload) {
+    return fromGeneratedSidecarWrittenProtocolFrame(protocol.decodeProtocolFrame(toExactUint8Array(payload)));
+}
+export function encodeProtocolFramePayload(frame, codec) {
+    if (codec === "json") {
+        return encodeJsonFramePayload(frame);
+    }
+    return encodeBareProtocolFrame(frame);
+}
+export function decodeProtocolFramePayload(payload, codec) {
+    if (codec === "json") {
+        return decodeJsonFramePayload(payload);
+    }
+    return decodeBareProtocolFrame(payload);
+}
+export function classifySidecarWrittenProtocolFrame(frame) {
+    switch (frame.frame_type) {
+        case "response":
+            return {
+                kind: "response",
+                requestId: frame.request_id,
+                frame,
+            };
+        case "event":
+            return { kind: "event", frame };
+        case "sidecar_request":
+            return { kind: "sidecarRequest", frame };
+    }
+}
+export function fromGeneratedSidecarWrittenProtocolFrame(frame) {
+    switch (frame.tag) {
+        case "ResponseFrame":
+            return {
+                frame_type: "response",
+                schema: toLiveProtocolSchema(frame.val.schema),
+                request_id: bigIntToSafeNumber(frame.val.requestId, "response request id"),
+                ownership: fromGeneratedOwnershipScope(frame.val.ownership),
+                payload: fromGeneratedResponsePayload(frame.val.payload),
+            };
+        case "EventFrame":
+            return {
+                frame_type: "event",
+                schema: toLiveProtocolSchema(frame.val.schema),
+                ownership: fromGeneratedOwnershipScope(frame.val.ownership),
+                payload: fromGeneratedEventPayload(frame.val.payload),
+            };
+        case "SidecarRequestFrame":
+            return {
+                frame_type: "sidecar_request",
+                schema: toLiveProtocolSchema(frame.val.schema),
+                request_id: bigIntToSafeNumber(frame.val.requestId, "sidecar request id"),
+                ownership: fromGeneratedOwnershipScope(frame.val.ownership),
+                payload: fromGeneratedSidecarRequestPayload(frame.val.payload),
+            };
+        case "RequestFrame":
+        case "SidecarResponseFrame":
+            throw new Error(`unsupported BARE protocol frame tag: ${frame.tag}`);
+    }
+}
+export function toLiveProtocolSchema(schema) {
+    return validateSidecarProtocolSchema(schema);
+}

package/dist/protocol-maps.d.ts

@@ -0,0 +1,31 @@
+import * as protocol from "./generated-protocol.js";
+export type LiveGuestRuntimeKind = "java_script" | "python" | "web_assembly";
+export type LiveDisposeReason = "requested" | "connection_closed" | "host_shutdown";
+export type LiveRootFilesystemMode = "ephemeral" | "read_only";
+export type LiveRootFilesystemEntryKind = "file" | "directory" | "symlink";
+export type LiveRootFilesystemEntryEncoding = "utf8" | "base64";
+export type LiveWasmPermissionTier = "full" | "read-write" | "read-only" | "isolated";
+export type LivePermissionMode = "allow" | "ask" | "deny";
+export type LiveGuestFilesystemOperation = "read_file" | "write_file" | "create_dir" | "mkdir" | "exists" | "stat" | "lstat" | "read_dir" | "read_dir_recursive" | "remove_file" | "remove_dir" | "remove" | "copy" | "move" | "rename" | "realpath" | "symlink" | "read_link" | "link" | "chmod" | "chown" | "utimes" | "truncate" | "pread" | "pwrite";
+export type LiveFilesystemOperation = "read" | "write" | "stat" | "read_dir" | "mkdir" | "remove" | "rename";
+export type LiveVmLifecycleState = "creating" | "ready" | "disposing" | "disposed" | "failed";
+export type LiveStreamChannel = "stdout" | "stderr";
+export type LiveProcessSnapshotStatus = "running" | "exited" | "stopped";
+export type LiveSignalDispositionAction = "default" | "ignore" | "user";
+export declare function toGeneratedPermissionMode(mode: LivePermissionMode): protocol.PermissionMode;
+export declare function toGeneratedGuestRuntimeKind(runtime: LiveGuestRuntimeKind): protocol.GuestRuntimeKind;
+export declare function toGeneratedDisposeReason(reason: LiveDisposeReason): protocol.DisposeReason;
+export declare function toGeneratedRootFilesystemMode(mode: LiveRootFilesystemMode): protocol.RootFilesystemMode;
+export declare function toGeneratedRootFilesystemEntryKind(kind: LiveRootFilesystemEntryKind): protocol.RootFilesystemEntryKind;
+export declare function toGeneratedRootFilesystemEntryEncoding(encoding: LiveRootFilesystemEntryEncoding): protocol.RootFilesystemEntryEncoding;
+export declare function toGeneratedWasmPermissionTier(tier: LiveWasmPermissionTier): protocol.WasmPermissionTier;
+export declare function toGeneratedGuestFilesystemOperation(operation: LiveGuestFilesystemOperation): protocol.GuestFilesystemOperation;
+export declare function toGeneratedFilesystemOperation(operation: LiveFilesystemOperation): protocol.FilesystemOperation;
+export declare function fromGeneratedFilesystemOperation(operation: protocol.FilesystemOperation): LiveFilesystemOperation;
+export declare function fromGeneratedVmLifecycleState(state: protocol.VmLifecycleState): LiveVmLifecycleState;
+export declare function fromGeneratedStreamChannel(channel: protocol.StreamChannel): LiveStreamChannel;
+export declare function fromGeneratedProcessSnapshotStatus(status: protocol.ProcessSnapshotStatus): LiveProcessSnapshotStatus;
+export declare function fromGeneratedSignalDispositionAction(action: protocol.SignalDispositionAction): LiveSignalDispositionAction;
+export declare function fromGeneratedRootFilesystemEntryKind(kind: protocol.RootFilesystemEntryKind): LiveRootFilesystemEntryKind;
+export declare function fromGeneratedRootFilesystemEntryEncoding(encoding: protocol.RootFilesystemEntryEncoding): LiveRootFilesystemEntryEncoding;
+export declare function fromGeneratedGuestFilesystemOperation(operation: protocol.GuestFilesystemOperation): LiveGuestFilesystemOperation;