@nimbus-sh/core 0.1.0

package/dist/runtime/port-registry.js

@@ -0,0 +1,265 @@
+/**
+ * port-registry.ts — Maps virtual ports to facet stubs.
+ *
+ * When a facet calls http.createServer().listen(3000), it notifies the
+ * supervisor via SupervisorRPC.registerPort(3000). The supervisor stores
+ * the facet stub here. When the DO receives a request to /port/3000/*,
+ * it looks up the facet and forwards the request.
+ *
+ * Transport (audit C2):
+ *   The proxy forwards a real Request and returns a real Response.
+ *   Workers RPC natively transfers Request/Response values between
+ *   isolates with streaming bodies and flow control (they are NOT
+ *   structured-cloneable — RPC has its own transfer mechanism for
+ *   these types). Binary payloads (images, wasm, gzip, multipart
+ *   uploads, audio/video) go through byte-for-byte with no UTF-8
+ *   coercion or JSON envelope anywhere in the path.
+ *
+ *   Facet contract for handleHttpRequest:
+ *     async handleHttpRequest(request: Request): Promise<Response>
+ *
+ *   where `request.url` is the inner URL the user's HTTP server
+ *   expects (pathname + search, absolute against a synthetic origin),
+ *   `request.method` and application headers mirror the outer request,
+ *   Nimbus credentials/internal headers are removed, and
+ *   `request.body` is a ReadableStream (or null for GET/HEAD) that
+ *   the facet can consume once. The returned Response is returned
+ *   to the outer fetch as-is; its body is streamed directly.
+ */
+import { sanitizeUntrustedHeaders } from '../_shared/untrusted-request.js';
+export class PortRegistry {
+    ports = new Map();
+    facetStubsByPid = new Map();
+    portWaitersByPid = new Map();
+    /** Remember the available facet capabilities for a running process. */
+    bindFacetStub(pid, facetStub) {
+        const target = routeableFacetTarget(facetStub);
+        if (!target)
+            return;
+        this.facetStubsByPid.set(pid, target);
+        this.attachFacetStubByPid(pid, target);
+        this.notifyPortWaiters(pid);
+    }
+    /**
+     * Register a process as listening on a port. The route target comes from
+     * the pid's binding — one target per process, owned by whoever started it —
+     * so a port announced by the facet itself and one reserved by the spawn
+     * resolve to the same handler.
+     */
+    register(port, pid) {
+        const target = this.facetStubsByPid.get(pid) ?? null;
+        this.ports.set(port, { port, pid, facetStub: target, registeredAt: Date.now() });
+        this.notifyPortWaiters(pid);
+    }
+    /** Unregister a port. */
+    unregister(port) {
+        return this.ports.delete(port);
+    }
+    /** Unregister all ports owned by a specific PID. */
+    unregisterByPid(pid) {
+        let count = 0;
+        for (const [port, entry] of this.ports) {
+            if (entry.pid === pid) {
+                this.ports.delete(port);
+                count++;
+            }
+        }
+        this.facetStubsByPid.delete(pid);
+        return count;
+    }
+    /** Look up a port entry. */
+    get(port) {
+        return this.ports.get(port);
+    }
+    /** Attach a normalized route target to ports previously reserved by a PID. */
+    attachFacetStubByPid(pid, target) {
+        const ports = [];
+        for (const entry of this.ports.values()) {
+            if (entry.pid !== pid || entry.facetStub)
+                continue;
+            entry.facetStub = target;
+            ports.push(entry.port);
+        }
+        if (ports.length > 0)
+            this.notifyPortWaiters(pid);
+        return ports;
+    }
+    getRouteablePortsByPid(pid) {
+        return [...this.ports.values()]
+            .filter((entry) => entry.pid === pid && entry.facetStub)
+            .map((entry) => entry.port);
+    }
+    async waitForRouteablePortsByPid(pid, timeoutMs) {
+        const immediate = this.getRouteablePortsByPid(pid);
+        if (immediate.length > 0)
+            return immediate;
+        await this.waitForPidPortChange(pid, timeoutMs);
+        return this.getRouteablePortsByPid(pid);
+    }
+    /** Check if a port is registered. */
+    has(port) {
+        return this.ports.has(port);
+    }
+    /** Get all registered ports. */
+    getAll() {
+        return [...this.ports.values()];
+    }
+    /**
+     * Forward an HTTP request to the facet owning a port.
+     *
+     * Returns null if no facet is listening on this port (or if a port
+     * is registered but its stub is not yet attached — see PortEntry).
+     *
+     * The Request passed to the facet has a rewritten URL whose pathname
+     * is the inner path (without the `/port/<n>` prefix) and whose origin
+     * matches the outer request, so user code reading `request.url`
+     * sees a URL shape consistent with "my server is running at this
+     * port". Application headers and the body are forwarded; Nimbus
+     * credentials and internal routing headers are removed before crossing
+     * the user-code trust boundary. The body remains a ReadableStream so
+     * binary payloads aren't materialised in memory.
+     *
+     * Binary safety: Workers RPC transfers Request/Response values with
+     * their streaming bodies; it does not structured-clone them. No UTF-8
+     * round-trip occurs anywhere.
+     * A user-facet serving a PNG will return the exact same bytes the
+     * client receives.
+     */
+    async routeRequest(port, request, pathname) {
+        const entry = this.ports.get(port);
+        // Honour the documented contract: no entry at all → null, so callers
+        // report "no process listening". (Pre-fix this fell into the 501 below,
+        // which mislabelled a wiped/unregistered port as a half-registered one.)
+        if (!entry)
+            return null;
+        // Some short-lived/foreground paths can reserve a port through
+        // SupervisorRPC.registerPort before a routeable WorkerEntrypoint
+        // exists. Explicit long-running processes (for example
+        // `node --watch server.js`) register a non-null facet stub and route
+        // below. For a null-stub reservation, return an honest 501 instead
+        // of a misleading "no process listening" 502.
+        if (!entry.facetStub) {
+            return new Response(JSON.stringify({
+                error: 'port is registered but has no routeable facet handler',
+                port,
+            }), {
+                status: 501,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+        try {
+            const outerUrl = new URL(request.url);
+            // Preserve query; replace the pathname with the inner path so
+            // the user's HTTP server sees its own URL shape. (Fragments
+            // never make it onto the wire, so there's nothing to forward.)
+            const innerUrl = new URL(pathname + outerUrl.search, outerUrl.origin);
+            // Rebuild a Request targeting the inner URL. Body is forwarded as
+            // a stream — we do NOT await `.text()`/`.arrayBuffer()`, which
+            // would corrupt any binary payload and block large uploads.
+            //
+            // Construct via (url, init) so we can override the URL while
+            // inheriting method/headers/body from the original. For GET/HEAD
+            // we must omit `body` entirely — the Request constructor throws
+            // if a body is supplied on those methods.
+            const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+            const headers = new Headers(request.headers);
+            sanitizeUntrustedHeaders(headers);
+            headers.set('X-Nimbus-Port', String(port));
+            // `duplex: 'half'` is required by workerd when body is a
+            // ReadableStream — otherwise `new Request(…)` throws. It's not
+            // part of the published @cloudflare/workers-types RequestInit,
+            // so extend the type locally rather than casting the whole
+            // init — that keeps typos in other fields caught by the compiler.
+            const init = {
+                method: request.method,
+                headers,
+                body: hasBody ? request.body : undefined,
+            };
+            if (hasBody)
+                init.duplex = 'half';
+            const forwarded = new Request(innerUrl.toString(), init);
+            // RPC: the facet receives the Request and returns a Response.
+            // Both cross the isolate boundary via Workers RPC's native
+            // Request/Response transport — bytes are streamed with
+            // flow-control, never materialised.
+            const response = await entry.facetStub.handleHttpRequest(forwarded);
+            if (!(response instanceof Response)) {
+                // Defensive: if a facet ever returns something else (JSON
+                // envelope, string, etc.), treat it as a 502 so the client
+                // sees a clear signal rather than a confusing surprise.
+                return new Response(JSON.stringify({
+                    error: 'port proxy: facet returned non-Response value',
+                    type: typeof response,
+                }), {
+                    status: 502,
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+            // Return the facet's Response as-is. Body is streamed; headers,
+            // status, and status-text pass through unchanged. We do NOT
+            // inject Access-Control-Allow-Origin — a port proxy forwards
+            // whatever CORS policy the user's HTTP server chose (audit C3
+            // discourages gratuitous wildcards on non-static routes).
+            return response;
+        }
+        catch (error) {
+            // Server-side triage — users see only the 502 body, operators
+            // see the full error + stack in Worker logs.
+            console.error('[port-registry] routeRequest failed for port', port, ':', error);
+            return new Response(JSON.stringify({ error: errorMessage(error) }), {
+                status: 502,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+    }
+    get stats() {
+        return {
+            activePorts: this.ports.size,
+            ports: [...this.ports.entries()].map(([port, e]) => ({ port, pid: e.pid })),
+        };
+    }
+    waitForPidPortChange(pid, timeoutMs) {
+        return new Promise((resolve) => {
+            let done = false;
+            let timeout;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timeout);
+                const waiters = this.portWaitersByPid.get(pid);
+                if (waiters) {
+                    waiters.delete(finish);
+                    if (waiters.size === 0)
+                        this.portWaitersByPid.delete(pid);
+                }
+                resolve();
+            };
+            timeout = setTimeout(finish, timeoutMs);
+            const waiters = this.portWaitersByPid.get(pid) || new Set();
+            waiters.add(finish);
+            this.portWaitersByPid.set(pid, waiters);
+        });
+    }
+    notifyPortWaiters(pid) {
+        const waiters = this.portWaitersByPid.get(pid);
+        if (!waiters)
+            return;
+        this.portWaitersByPid.delete(pid);
+        for (const resolve of waiters)
+            resolve();
+    }
+}
+function routeableFacetTarget(value) {
+    if ((typeof value !== 'object' && typeof value !== 'function') || value === null)
+        return null;
+    const method = Reflect.get(value, 'fetch') || Reflect.get(value, 'handleHttpRequest');
+    if (typeof method !== 'function')
+        return null;
+    return {
+        handleHttpRequest: method.bind(value),
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/runtime/process-input-routing.d.ts

@@ -0,0 +1,33 @@
+/**
+ * process-input-routing.ts — the single zod-validated protocol path for
+ * process-terminal client frames (`input` / `stdin-end` / `resize` /
+ * `signal`). Both WebSocket surfaces (the `/api/logs/<pid>` upgrade
+ * handler and the hibernatable `webSocketMessage` dispatcher) and the
+ * programmatic SDK RPCs route through these helpers.
+ */
+import type { SessionProcessSupervisor } from './session-process-supervisor.js';
+import type { ProcessLogClientFrame } from './process-io-protocol.js';
+/** The slice of the process supervisor the frame router drives. */
+export type ProcessInputController = Pick<SessionProcessSupervisor, 'writeInput' | 'endInput' | 'resize' | 'signal'>;
+export declare function writeProcessInput(processes: ProcessInputController, pid: number, data: string): Promise<{
+    ok: boolean;
+    pid: number;
+}>;
+export declare function endProcessInput(processes: ProcessInputController, pid: number): Promise<{
+    ok: boolean;
+    pid: number;
+}>;
+export declare function resizeProcess(processes: ProcessInputController, pid: number, columns: number, rows: number): Promise<{
+    ok: boolean;
+    pid: number;
+}>;
+export declare function signalProcess(processes: ProcessInputController, pid: number, signal: string): Promise<{
+    ok: boolean;
+    pid: number;
+}>;
+export declare function applyProcessClientFrame(processes: ProcessInputController, pid: number, frame: ProcessLogClientFrame): Promise<{
+    ok: boolean;
+    pid: number;
+    type: ProcessLogClientFrame['type'];
+}>;
+//# sourceMappingURL=process-input-routing.d.ts.map

package/dist/runtime/process-input-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-input-routing.d.ts","sourceRoot":"","sources":["../../src/runtime/process-input-routing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAOtE,mEAAmE;AACnE,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,wBAAwB,EACxB,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAChD,CAAC;AAOF,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,sBAAsB,EACjC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAMvC;AAED,wBAAsB,eAAe,CACnC,SAAS,EAAE,sBAAsB,EACjC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAKvC;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,sBAAsB,EACjC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAOvC;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,sBAAsB,EACjC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAOvC;AAED,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,sBAAsB,EACjC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAW5E"}

package/dist/runtime/process-input-routing.js

@@ -0,0 +1,59 @@
+/**
+ * process-input-routing.ts — the single zod-validated protocol path for
+ * process-terminal client frames (`input` / `stdin-end` / `resize` /
+ * `signal`). Both WebSocket surfaces (the `/api/logs/<pid>` upgrade
+ * handler and the hibernatable `webSocketMessage` dispatcher) and the
+ * programmatic SDK RPCs route through these helpers.
+ */
+import { parseProcessPid, parseProcessSignalName, parseProcessTerminalSize, } from './process-io-protocol.js';
+function rejectedPid(value) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : 0;
+}
+export async function writeProcessInput(processes, pid, data) {
+    const n = parseProcessPid(pid);
+    if (n === null)
+        return { ok: false, pid: rejectedPid(pid) };
+    const text = String(data ?? '');
+    const queued = processes.writeInput(n, text);
+    return { ok: queued.ok, pid: n };
+}
+export async function endProcessInput(processes, pid) {
+    const n = parseProcessPid(pid);
+    if (n === null)
+        return { ok: false, pid: rejectedPid(pid) };
+    processes.endInput(n);
+    return { ok: true, pid: n };
+}
+export async function resizeProcess(processes, pid, columns, rows) {
+    const n = parseProcessPid(pid);
+    if (n === null)
+        return { ok: false, pid: rejectedPid(pid) };
+    const size = parseProcessTerminalSize({ columns, rows });
+    if (!size)
+        return { ok: false, pid: n };
+    const resized = processes.resize(n, size.columns, size.rows);
+    return { ok: resized.ok, pid: n };
+}
+export async function signalProcess(processes, pid, signal) {
+    const n = parseProcessPid(pid);
+    if (n === null)
+        return { ok: false, pid: rejectedPid(pid) };
+    const parsed = parseProcessSignalName(signal);
+    if (!parsed)
+        return { ok: false, pid: n };
+    const signaled = processes.signal(n, parsed);
+    return { ok: signaled.ok, pid: n };
+}
+export async function applyProcessClientFrame(processes, pid, frame) {
+    if (frame.type === 'input') {
+        return { ...(await writeProcessInput(processes, pid, frame.data)), type: frame.type };
+    }
+    if (frame.type === 'stdin-end') {
+        return { ...(await endProcessInput(processes, pid)), type: frame.type };
+    }
+    if (frame.type === 'resize') {
+        return { ...(await resizeProcess(processes, pid, frame.columns, frame.rows)), type: frame.type };
+    }
+    return { ...(await signalProcess(processes, pid, frame.signal)), type: frame.type };
+}

package/dist/runtime/process-input.d.ts

@@ -0,0 +1,39 @@
+import type { ProcessSignalName } from './process-io-protocol.js';
+export interface ProcessInputPacket {
+    data: string;
+    ended: boolean;
+    resize?: {
+        columns: number;
+        rows: number;
+    };
+    signal?: ProcessSignalName;
+}
+export interface ProcessInputStoreOptions {
+    maxQueuedBytes?: number;
+}
+export declare class ProcessInputStore {
+    private readonly maxQueuedBytes;
+    private pids;
+    constructor(options?: ProcessInputStoreOptions);
+    private createState;
+    open(pid: number): void;
+    has(pid: number): boolean;
+    write(pid: number, data: string): {
+        ok: boolean;
+    };
+    resize(pid: number, columns: number, rows: number): {
+        ok: boolean;
+    };
+    signal(pid: number, signal: ProcessSignalName): {
+        ok: boolean;
+    };
+    terminalSize(pid: number): {
+        columns: number;
+        rows: number;
+    } | null;
+    private enqueue;
+    end(pid: number): void;
+    close(pid: number): void;
+    read(pid: number, waitMs?: number): Promise<ProcessInputPacket>;
+}
+//# sourceMappingURL=process-input.d.ts.map

package/dist/runtime/process-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-input.d.ts","sourceRoot":"","sources":["../../src/runtime/process-input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAOlE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAWD,MAAM,WAAW,wBAAwB;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAQD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,IAAI,CAAiC;gBAEjC,OAAO,GAAE,wBAA6B;IAIlD,OAAO,CAAC,WAAW;IAInB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE;IAYjD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE;IAUnE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE;IAQ/D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAKnE,OAAO,CAAC,OAAO;IAmBf,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAUtB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKlB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAwBpE"}

package/dist/runtime/process-input.js

@@ -0,0 +1,117 @@
+const DEFAULT_MAX_QUEUED_BYTES = 256 * 1024;
+function isValidPid(pid) {
+    return Number.isSafeInteger(pid) && pid > 0;
+}
+export class ProcessInputStore {
+    maxQueuedBytes;
+    pids = new Map();
+    constructor(options = {}) {
+        this.maxQueuedBytes = options.maxQueuedBytes ?? DEFAULT_MAX_QUEUED_BYTES;
+    }
+    createState() {
+        return { packets: [], closed: false, bytes: 0, waiters: [], columns: 80, rows: 24 };
+    }
+    open(pid) {
+        if (!isValidPid(pid) || this.pids.has(pid))
+            return;
+        this.pids.set(pid, this.createState());
+    }
+    has(pid) {
+        return this.pids.has(pid);
+    }
+    write(pid, data) {
+        if (!isValidPid(pid))
+            return { ok: false };
+        const state = this.pids.get(pid);
+        if (!state)
+            return { ok: false };
+        if (state.closed)
+            return { ok: false };
+        const text = String(data);
+        if (state.bytes + text.length > this.maxQueuedBytes)
+            return { ok: false };
+        return this.enqueue(state, { data: text, ended: false }, text.length);
+    }
+    resize(pid, columns, rows) {
+        if (!isValidPid(pid))
+            return { ok: false };
+        const state = this.pids.get(pid);
+        if (!state)
+            return { ok: false };
+        if (state.closed)
+            return { ok: false };
+        state.columns = columns;
+        state.rows = rows;
+        return this.enqueue(state, { data: '', ended: false, resize: { columns, rows } }, 0);
+    }
+    signal(pid, signal) {
+        if (!isValidPid(pid))
+            return { ok: false };
+        const state = this.pids.get(pid);
+        if (!state)
+            return { ok: false };
+        if (state.closed)
+            return { ok: false };
+        return this.enqueue(state, { data: '', ended: false, signal }, 0);
+    }
+    terminalSize(pid) {
+        const state = this.pids.get(pid);
+        return state ? { columns: state.columns, rows: state.rows } : null;
+    }
+    enqueue(state, packet, bytes) {
+        const waiter = state.waiters.shift();
+        if (waiter) {
+            clearTimeout(waiter.timer);
+            waiter.resolve(packet);
+            return { ok: true };
+        }
+        const last = state.packets[state.packets.length - 1];
+        if (packet.resize && last?.resize && !last.data && !last.ended && !last.signal) {
+            state.packets[state.packets.length - 1] = packet;
+            return { ok: true };
+        }
+        state.packets.push(packet);
+        state.bytes += bytes;
+        return { ok: true };
+    }
+    end(pid) {
+        const state = this.pids.get(pid);
+        if (!state || state.closed)
+            return;
+        state.closed = true;
+        for (const waiter of state.waiters.splice(0)) {
+            clearTimeout(waiter.timer);
+            waiter.resolve({ data: '', ended: true });
+        }
+    }
+    close(pid) {
+        this.end(pid);
+        this.pids.delete(pid);
+    }
+    async read(pid, waitMs = 1000) {
+        if (!isValidPid(pid))
+            return { data: '', ended: true };
+        const state = this.pids.get(pid);
+        if (!state)
+            return { data: '', ended: true };
+        const next = state.packets.shift();
+        if (next !== undefined) {
+            state.bytes -= next.data.length;
+            return next;
+        }
+        if (state.closed)
+            return { data: '', ended: true };
+        return new Promise((resolve) => {
+            const waiter = {
+                resolve,
+                timer: setTimeout(() => {
+                    const idx = state.waiters.indexOf(waiter);
+                    if (idx >= 0)
+                        state.waiters.splice(idx, 1);
+                    resolve({ data: '', ended: false });
+                }, Math.max(0, Math.min(waitMs, 5000))),
+            };
+            state.waiters.push(waiter);
+        });
+    }
+}

package/dist/runtime/process-io-protocol.d.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod/v4';
+declare const ProcessTerminalSizeSchema: z.ZodObject<{
+    columns: z.ZodCoercedNumber<unknown>;
+    rows: z.ZodCoercedNumber<unknown>;
+}, z.core.$strip>;
+export declare const ProcessSignalNameSchema: z.ZodEnum<{
+    SIGHUP: "SIGHUP";
+    SIGINT: "SIGINT";
+    SIGQUIT: "SIGQUIT";
+    SIGILL: "SIGILL";
+    SIGTRAP: "SIGTRAP";
+    SIGABRT: "SIGABRT";
+    SIGBUS: "SIGBUS";
+    SIGFPE: "SIGFPE";
+    SIGKILL: "SIGKILL";
+    SIGUSR1: "SIGUSR1";
+    SIGSEGV: "SIGSEGV";
+    SIGUSR2: "SIGUSR2";
+    SIGPIPE: "SIGPIPE";
+    SIGALRM: "SIGALRM";
+    SIGTERM: "SIGTERM";
+    SIGCHLD: "SIGCHLD";
+    SIGCONT: "SIGCONT";
+    SIGSTOP: "SIGSTOP";
+    SIGTSTP: "SIGTSTP";
+    SIGTTIN: "SIGTTIN";
+    SIGTTOU: "SIGTTOU";
+    SIGURG: "SIGURG";
+    SIGXCPU: "SIGXCPU";
+    SIGXFSZ: "SIGXFSZ";
+    SIGVTALRM: "SIGVTALRM";
+    SIGPROF: "SIGPROF";
+    SIGWINCH: "SIGWINCH";
+    SIGIO: "SIGIO";
+    SIGPWR: "SIGPWR";
+    SIGSYS: "SIGSYS";
+}>;
+export type ProcessTerminalSize = z.infer<typeof ProcessTerminalSizeSchema>;
+export type ProcessSignalName = z.infer<typeof ProcessSignalNameSchema>;
+export declare function parseProcessPid(value: unknown): number | null;
+export declare function parseProcessTerminalSize(value: unknown): ProcessTerminalSize | null;
+export declare function parseProcessSignalName(value: string): ProcessSignalName | null;
+export declare const ProcessLogClientFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"input">;
+    data: z.ZodPipe<z.ZodOptional<z.ZodUnknown>, z.ZodTransform<string, unknown>>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"stdin-end">;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"resize">;
+    columns: z.ZodCoercedNumber<unknown>;
+    rows: z.ZodCoercedNumber<unknown>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"signal">;
+    signal: z.ZodEnum<{
+        SIGHUP: "SIGHUP";
+        SIGINT: "SIGINT";
+        SIGQUIT: "SIGQUIT";
+        SIGILL: "SIGILL";
+        SIGTRAP: "SIGTRAP";
+        SIGABRT: "SIGABRT";
+        SIGBUS: "SIGBUS";
+        SIGFPE: "SIGFPE";
+        SIGKILL: "SIGKILL";
+        SIGUSR1: "SIGUSR1";
+        SIGSEGV: "SIGSEGV";
+        SIGUSR2: "SIGUSR2";
+        SIGPIPE: "SIGPIPE";
+        SIGALRM: "SIGALRM";
+        SIGTERM: "SIGTERM";
+        SIGCHLD: "SIGCHLD";
+        SIGCONT: "SIGCONT";
+        SIGSTOP: "SIGSTOP";
+        SIGTSTP: "SIGTSTP";
+        SIGTTIN: "SIGTTIN";
+        SIGTTOU: "SIGTTOU";
+        SIGURG: "SIGURG";
+        SIGXCPU: "SIGXCPU";
+        SIGXFSZ: "SIGXFSZ";
+        SIGVTALRM: "SIGVTALRM";
+        SIGPROF: "SIGPROF";
+        SIGWINCH: "SIGWINCH";
+        SIGIO: "SIGIO";
+        SIGPWR: "SIGPWR";
+        SIGSYS: "SIGSYS";
+    }>;
+}, z.core.$loose>], "type">;
+export type ProcessLogClientFrame = z.infer<typeof ProcessLogClientFrameSchema>;
+export declare function parseProcessLogClientFrame(raw: string): ProcessLogClientFrame | null;
+export {};
+//# sourceMappingURL=process-io-protocol.d.ts.map

package/dist/runtime/process-io-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-io-protocol.d.ts","sourceRoot":"","sources":["../../src/runtime/process-io-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAI3B,QAAA,MAAM,yBAAyB;;;iBAG7B,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BlC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAC5E,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG7D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,GAAG,IAAI,CAGnF;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAG9E;AAoBD,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAKtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CASpF"}