@hachej/boring-execution 0.0.0-stage → 0.2.1

package/dist/remote-files.js

@@ -0,0 +1,238 @@
+import { z } from 'zod';
+import { awaitWithContext, withAbortSignal } from '@earendil-works/chord/context';
+import { FileError, ok, err } from '@earendil-works/pi-durable/env';
+import { bytes, fileInfo, line, nothing, envelope, streamFrame, schema, version, nativeVersion, streamType, identity, sameIdentity, positiveLimit, result, wireCall, requestInput } from './remote-files-protocol.js';
+import { frameReader, readJson } from './remote-files-io.js';
+import { randomUUID } from '@hachej/boring-files/platform';
+import { maxWatchExcludeNames, maxWatchTargets } from './remote-files-protocol.js';
+import { remoteReaders } from './remote-files-positional.js';
+import { watcherFromFrames } from './remote-files-watch.js';
+export { createRemoteFileSystemHandler } from './remote-files-handler.js';
+export function createRemoteFileSystemLease(options) {
+    const selected = identity(options.identity), filesystemId = z.string().min(1).parse(options.filesystemId);
+    const endpoint = new URL(options.endpoint), fetch = options.fetch;
+    if (!['https:', 'http:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash)
+        throw new TypeError('Expected an HTTP endpoint without credentials or fragment');
+    let cwd = z.string().parse(options.cwd), closed = false;
+    const maxRequestBytes = positiveLimit(options.maxRequestBytes ?? 1_048_576), maxResponseBytes = positiveLimit(options.maxResponseBytes ?? 4_194_304);
+    const maxFrameBytes = positiveLimit(options.maxFrameBytes ?? 1_048_576), active = new Set();
+    const unavailable = (message) => new FileError('unknown', message + '; prior remote effects may remain');
+    const connect = async (call, context) => {
+        if (closed)
+            return err(new FileError('invalid', 'Remote filesystem lease is closed'));
+        if (context.abortSignal?.aborted)
+            return err(new FileError('aborted', 'Filesystem operation aborted before dispatch'));
+        const abort = new AbortController(), requestId = randomUUID();
+        const onAbort = () => abort.abort(), detach = () => context.abortSignal?.removeEventListener('abort', onAbort);
+        const local = withAbortSignal(abort.signal, context);
+        let response, closeFrames, dispatched = false;
+        const dispose = async () => {
+            detach();
+            abort.abort();
+            active.delete(dispose);
+            if (closeFrames)
+                await closeFrames();
+            else if (response?.body)
+                void response.body.cancel().catch(() => { });
+        };
+        active.add(dispose);
+        context.abortSignal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            const body = JSON.stringify({ schema, version, nativeVersion, requestId, identity: selected, filesystemId, cwd, call: wireCall(call) });
+            requestInput(JSON.parse(body));
+            if (new TextEncoder().encode(body).length > maxRequestBytes)
+                throw new TypeError('Filesystem request byte limit exceeded');
+            if (context.abortSignal?.aborted || closed) {
+                await dispose();
+                return err(new FileError('aborted', 'Filesystem operation aborted before dispatch'));
+            }
+            const request = new Request(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, body, signal: abort.signal, redirect: 'error' });
+            dispatched = true;
+            const pending = fetch(request);
+            void pending.then(value => { if (abort.signal.aborted)
+                void value.body?.cancel().catch(() => { }); }, () => { });
+            response = await awaitWithContext(pending, local);
+            if (response.redirected || response.status !== 200 || !response.body)
+                throw new TypeError('Filesystem response unavailable');
+            return ok({ response, requestId, local, abort, detach, dispose, setFrames: (close) => { closeFrames = close; } });
+        }
+        catch {
+            const cancelled = context.abortSignal?.aborted === true;
+            await dispose();
+            if (cancelled)
+                return err(new FileError('aborted', dispatched ? 'Filesystem operation aborted; prior remote effects may remain' : 'Filesystem operation aborted before dispatch'));
+            return err(dispatched ? unavailable('Filesystem acknowledgement was not received') : new FileError('invalid', 'Invalid remote filesystem request'));
+        }
+    };
+    const matches = (value, requestId) => value.requestId === requestId && sameIdentity(value.identity, selected) && value.filesystemId === filesystemId;
+    const invoke = async (call, output, context) => {
+        const connected = await connect(call, context);
+        if (!connected.ok)
+            return connected;
+        const connection = connected.value;
+        try {
+            if (connection.response.headers.get('content-type')?.split(';')[0]?.trim() !== 'application/json')
+                throw new TypeError('Invalid filesystem response type');
+            const value = envelope.parse(await readJson(connection.response.body, connection.local, maxResponseBytes));
+            if (!matches(value, connection.requestId) || connection.abort.signal.aborted)
+                throw new TypeError('Filesystem response identity mismatch');
+            return result(value.result, output);
+        }
+        catch {
+            if (context.abortSignal?.aborted)
+                return err(new FileError('aborted', 'Filesystem operation aborted; prior remote effects may remain'));
+            return err(unavailable('Filesystem acknowledgement was invalid or interrupted'));
+        }
+        finally {
+            await connection.dispose();
+        }
+    };
+    const open = async (path, context) => {
+        const connected = await connect({ method: 'openTextLineReader', args: [path] }, context);
+        if (!connected.ok)
+            return connected;
+        const connection = connected.value;
+        let retained = false;
+        try {
+            if (connection.response.headers.get('content-type')?.split(';')[0]?.trim() === 'application/json') {
+                const value = envelope.parse(await readJson(connection.response.body, connection.local, maxResponseBytes));
+                if (!matches(value, connection.requestId))
+                    throw new TypeError('Filesystem response identity mismatch');
+                return result(value.result, z.never());
+            }
+            if (connection.response.headers.get('content-type')?.split(';')[0]?.trim() !== streamType || !connection.response.body)
+                throw new TypeError('Invalid filesystem stream type');
+            const frames = frameReader(connection.response.body, maxFrameBytes);
+            connection.setFrames(frames.close);
+            const first = streamFrame.parse(await awaitWithContext(frames.next(), connection.local));
+            if (first.type !== 'opened' || !matches(first, connection.requestId) || connection.abort.signal.aborted)
+                throw new TypeError('Filesystem stream identity mismatch');
+            connection.detach();
+            let sequence = 1, pending, busy = false, ended = false, readerClosed = false;
+            const close = async () => { if (readerClosed)
+                return; readerClosed = true; await connection.dispose(); };
+            const reader = {
+                close,
+                readLine: async (readContext) => {
+                    if (readContext.abortSignal?.aborted)
+                        return err(new FileError('aborted', 'Read wait was cancelled; the line has not been consumed'));
+                    if (readerClosed || closed)
+                        return err(new FileError('invalid', 'Remote line reader is closed'));
+                    if (ended)
+                        return ok(undefined);
+                    if (connection.abort.signal.aborted)
+                        return err(new FileError('invalid', 'Remote line reader is closed'));
+                    if (busy)
+                        return err(new FileError('invalid', 'A line read is already pending'));
+                    busy = true;
+                    try {
+                        pending ??= frames.next();
+                        const value = await awaitWithContext(pending, withAbortSignal(connection.abort.signal, readContext));
+                        if (readContext.abortSignal?.aborted)
+                            return err(new FileError('aborted', 'Read wait was cancelled; the line has not been consumed'));
+                        if (readerClosed || connection.abort.signal.aborted)
+                            throw new TypeError('Reader closed during read');
+                        const frame = streamFrame.parse(value);
+                        if (frame.requestId !== connection.requestId || frame.sequence !== sequence || frame.type === 'opened' || frame.type === 'change')
+                            throw new TypeError('Filesystem line sequence mismatch');
+                        if (frame.type === 'end') {
+                            pending = frames.next().then(tail => { if (tail !== undefined)
+                                throw new TypeError('Data after filesystem EOF'); return value; });
+                            await awaitWithContext(pending, withAbortSignal(connection.abort.signal, readContext));
+                            if (readContext.abortSignal?.aborted)
+                                return err(new FileError('aborted', 'Read wait was cancelled; the line has not been consumed'));
+                            pending = undefined;
+                            ended = true;
+                            await connection.dispose();
+                            return ok(undefined);
+                        }
+                        const decoded = result(frame.result, line);
+                        pending = undefined;
+                        sequence++;
+                        return decoded;
+                    }
+                    catch {
+                        if (readContext.abortSignal?.aborted && !connection.abort.signal.aborted)
+                            return err(new FileError('aborted', 'Read wait was cancelled; the line has not been consumed'));
+                        await close();
+                        return err(unavailable('Remote line observation was interrupted'));
+                    }
+                    finally {
+                        busy = false;
+                    }
+                },
+            };
+            retained = true;
+            return ok(reader);
+        }
+        catch {
+            return err(unavailable('Remote line reader could not be opened'));
+        }
+        finally {
+            if (!retained)
+                await connection.dispose();
+        }
+    };
+    const release = async () => { closed = true; await Promise.all([...active].map(close => close())); };
+    // Pi's readers and watcher travel as request-bound positional calls and one streamed watch request, never as whole-file reads.
+    const readers = remoteReaders(invoke, maxResponseBytes);
+    const watch = async (targets, onChange, context) => {
+        if (targets.length < 1 || targets.length > maxWatchTargets)
+            return err(new FileError('invalid', `A watch needs between 1 and ${maxWatchTargets} targets`));
+        if (targets.some(target => (target.exclude?.names?.length ?? 0) > maxWatchExcludeNames))
+            return err(new FileError('invalid', `A watch target excludes at most ${maxWatchExcludeNames} names`));
+        const connected = await connect({ method: 'watch', args: [targets] }, context);
+        if (!connected.ok)
+            return connected;
+        const connection = connected.value;
+        let retained = false;
+        try {
+            if (connection.response.headers.get('content-type')?.split(';')[0]?.trim() === 'application/json') {
+                const value = envelope.parse(await readJson(connection.response.body, connection.local, maxResponseBytes));
+                if (!matches(value, connection.requestId))
+                    throw new TypeError('Filesystem response identity mismatch');
+                return result(value.result, z.never());
+            }
+            if (connection.response.headers.get('content-type')?.split(';')[0]?.trim() !== streamType || !connection.response.body)
+                throw new TypeError('Invalid filesystem stream type');
+            const frames = frameReader(connection.response.body, maxFrameBytes);
+            connection.setFrames(frames.close);
+            const first = streamFrame.parse(await awaitWithContext(frames.next(), connection.local));
+            if (first.type !== 'opened' || first.mode === undefined || !matches(first, connection.requestId) || connection.abort.signal.aborted)
+                throw new TypeError('Filesystem stream identity mismatch');
+            connection.detach();
+            retained = true;
+            return ok(watcherFromFrames({ mode: first.mode, next: frames.next, requestId: connection.requestId, onChange, dispose: connection.dispose }));
+        }
+        catch {
+            return err(unavailable('Remote file watcher could not be opened'));
+        }
+        finally {
+            if (!retained)
+                await connection.dispose();
+        }
+    };
+    const environment = {
+        ...readers, watch, id: filesystemId, get cwd() { return cwd; }, set cwd(value) { cwd = value; }, cleanup: release,
+        absolutePath: (path, context) => invoke({ method: 'absolutePath', args: [path] }, z.string(), context),
+        joinPath: (parts, context) => invoke({ method: 'joinPath', args: [parts] }, z.string(), context),
+        readTextFile: (path, context) => invoke({ method: 'readTextFile', args: [path] }, z.string(), context),
+        openTextLineReader: open,
+        readTextLines: (path, options, context) => invoke({ method: 'readTextLines', args: [path, options] }, z.array(z.string()), context),
+        readBinaryFile: (path, context) => invoke({ method: 'readBinaryFile', args: [path] }, bytes, context),
+        writeFile: (path, content, context) => invoke({ method: 'writeFile', args: [path, content] }, nothing, context),
+        appendFile: (path, content, context) => invoke({ method: 'appendFile', args: [path, content] }, nothing, context),
+        truncateFile: (path, size, context) => invoke({ method: 'truncateFile', args: [path, size] }, nothing, context),
+        flushFile: (path, context) => invoke({ method: 'flushFile', args: [path] }, nothing, context),
+        renameFile: (from, to, context) => invoke({ method: 'renameFile', args: [from, to] }, nothing, context),
+        fileInfo: (path, context) => invoke({ method: 'fileInfo', args: [path] }, fileInfo, context),
+        listDir: (path, context) => invoke({ method: 'listDir', args: [path] }, z.array(fileInfo), context),
+        canonicalPath: (path, context) => invoke({ method: 'canonicalPath', args: [path] }, z.string(), context),
+        exists: (path, context) => invoke({ method: 'exists', args: [path] }, z.boolean(), context),
+        createDir: (path, options, context) => invoke({ method: 'createDir', args: [path, options] }, nothing, context),
+        remove: (path, options, context) => invoke({ method: 'remove', args: [path, options] }, nothing, context),
+        createTempDir: (prefix, context) => invoke({ method: 'createTempDir', args: [prefix] }, z.string(), context),
+        createTempFile: (options, context) => invoke({ method: 'createTempFile', args: [options] }, z.string(), context),
+    };
+    return { identity: selected, environment, ownership: 'borrowed', release };
+}

package/dist/remote-shell-handler.d.ts

@@ -0,0 +1,25 @@
+import type { Context } from '@earendil-works/chord';
+import type { Shell, ShellExecOptions } from '@earendil-works/pi-durable/env';
+import type { WorkspaceIdentity } from './contracts.js';
+export interface RemoteShellAccess {
+    readonly identity: WorkspaceIdentity;
+    readonly shell: Shell;
+    readonly context: Context;
+    /** Abort on authorization/identity changes, including while the command is silent. */
+    readonly revoked: AbortSignal;
+    readonly authorize: (command: string, options: Readonly<Omit<ShellExecOptions, 'onOutput'>>) => boolean | Promise<boolean>;
+    /** Host qualification of the selected native Shell. Spill paths remain in that workspace. */
+    readonly supports: {
+        readonly timeout: boolean;
+        readonly spill: boolean;
+    };
+}
+export interface RemoteShellHandlerOptions {
+    /** Authenticate, enforce origin/CSRF policy, and select an existing borrowed workspace. */
+    readonly authenticate: (request: Request) => Promise<RemoteShellAccess | null>;
+    readonly maxRequestBytes?: number;
+    readonly maxFrameBytes?: number;
+    readonly maxQueuedBytes?: number;
+}
+export declare function createRemoteShellHandler(options: RemoteShellHandlerOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=remote-shell-handler.d.ts.map

package/dist/remote-shell-handler.js

@@ -0,0 +1,131 @@
+import { awaitWithContext, withAbortSignal } from '@earendil-works/chord/context';
+import { ExecutionError, err } from '@earendil-works/pi-durable/env';
+import { guardStatus, hasJsonContentType, readJsonBody } from '@hachej/boring-files/request-guard';
+import { windowedOutput } from './remote-shell-window.js';
+import { contentType, identity, nativeVersion, positiveLimit, requestInput, sameIdentity, schema, version, wireResult } from './remote-shell-protocol.js';
+function failure(status) {
+    return new Response(null, { status, headers: { 'cache-control': 'no-store' } });
+}
+export function createRemoteShellHandler(options) {
+    const maxRequestBytes = positiveLimit(options.maxRequestBytes ?? 65_536), maxFrameBytes = positiveLimit(options.maxFrameBytes ?? 1_048_576);
+    const maxQueuedBytes = positiveLimit(options.maxQueuedBytes ?? 4_194_304);
+    if (maxQueuedBytes < maxFrameBytes)
+        throw new TypeError('Remote shell queue must hold one maximum-sized frame');
+    return async (request) => {
+        if (request.method !== 'POST')
+            return failure(405);
+        if (!hasJsonContentType(request.headers))
+            return failure(415);
+        let access;
+        try {
+            access = await options.authenticate(request);
+        }
+        catch {
+            return failure(503);
+        }
+        if (!access)
+            return failure(401);
+        const { shell, authorize, revoked, supports } = access;
+        const selected = identity(access.identity), stop = new AbortController();
+        const context = withAbortSignal(AbortSignal.any([request.signal, revoked, stop.signal]), access.context);
+        const signal = context.abortSignal;
+        let input;
+        try {
+            input = requestInput(await readJsonBody(request, maxRequestBytes, signal));
+        }
+        catch (error) {
+            return failure(guardStatus(error));
+        }
+        if (!sameIdentity(input.identity, selected))
+            return failure(409);
+        if (input.options.timeout !== undefined && supports.timeout !== true || input.options.spill !== undefined && supports.spill !== true)
+            return failure(422);
+        try {
+            if (signal?.aborted || await awaitWithContext(Promise.resolve(authorize(input.command, structuredClone(input.options))), context) !== true || signal?.aborted)
+                return failure(403);
+        }
+        catch {
+            return failure(503);
+        }
+        let ended = false, sequence = 0;
+        let controller;
+        function fail() {
+            if (ended)
+                return;
+            ended = true;
+            signal?.removeEventListener('abort', fail);
+            controller.error(new Error('Remote shell stream interrupted; command outcome is unconfirmed'));
+            stop.abort();
+        }
+        function send(value) {
+            if (ended || signal?.aborted)
+                throw new Error('Remote shell transport closed');
+            const bytes = new TextEncoder().encode(JSON.stringify({ ...value, requestId: input.requestId, sequence: sequence++ }) + '\n');
+            if (bytes.byteLength > maxFrameBytes || (controller.desiredSize ?? 0) < bytes.byteLength) {
+                fail();
+                throw new Error('Remote shell output limit exceeded');
+            }
+            controller.enqueue(bytes);
+        }
+        async function execute() {
+            try {
+                if (signal?.aborted || ended)
+                    return;
+                const emit = (chunk) => send({ type: 'output', text: chunk.text, stream: chunk.stream, ...(chunk.skipped === undefined ? {} : { skipped: chunk.skipped }) });
+                const windowed = input.output && input.options.window !== undefined ? windowedOutput(input.options.window, emit) : undefined;
+                const onOutput = !input.output ? undefined : windowed ? (text, _context, info) => windowed.push(text, info)
+                    : (text, _context, info) => emit({ text, stream: info.stream, ...(info.skipped === undefined ? {} : { skipped: info.skipped }) });
+                let result;
+                try {
+                    result = await shell.exec(input.command, { ...input.options, ...(onOutput ? { onOutput } : {}) }, context);
+                    windowed?.finish();
+                }
+                finally {
+                    windowed?.cancel();
+                }
+                if (await awaitWithContext(Promise.resolve(authorize(input.command, structuredClone(input.options))), context) !== true || signal?.aborted || ended) {
+                    fail();
+                    return;
+                }
+                send({ type: 'result', result: wireResult(result) });
+                ended = true;
+                signal?.removeEventListener('abort', fail);
+                controller.close();
+            }
+            catch {
+                if (!ended && !signal?.aborted) {
+                    try {
+                        send({ type: 'result', result: wireResult(err(new ExecutionError('unknown', 'Remote provider failed; prior effects may remain'))) });
+                    }
+                    catch {
+                        fail();
+                        return;
+                    }
+                    ended = true;
+                    signal?.removeEventListener('abort', fail);
+                    controller.close();
+                }
+            }
+        }
+        const body = new ReadableStream({
+            start(value) {
+                controller = value;
+                signal?.addEventListener('abort', fail, { once: true });
+                if (signal?.aborted) {
+                    fail();
+                    return;
+                }
+                try {
+                    send({ type: 'header', schema, version, nativeVersion, identity: selected });
+                }
+                catch {
+                    fail();
+                    return;
+                }
+                void execute();
+            },
+            cancel() { fail(); },
+        }, { highWaterMark: maxQueuedBytes, size: bytes => bytes.byteLength });
+        return new Response(body, { headers: { 'content-type': contentType, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' } });
+    };
+}

package/dist/remote-shell-protocol.d.ts

@@ -0,0 +1,50 @@
+import { ExecutionError } from '@earendil-works/pi-durable/env';
+import type { Shell, ShellExecOptions, ShellOutputSkip, ExecutionErrorCode } from '@earendil-works/pi-durable/env';
+import type { WorkspaceIdentity } from './contracts.js';
+export declare const schema = "boring.remote-shell";
+export declare const version = 2;
+export declare const nativeVersion = "pi-durable@1.1.0";
+export declare const contentType = "application/x-ndjson";
+export type WireOptions = Omit<ShellExecOptions, 'onOutput'>;
+export type ShellResult = Awaited<ReturnType<Shell['exec']>>;
+export declare function identity(value: unknown): WorkspaceIdentity;
+export declare function sameIdentity(left: WorkspaceIdentity, right: WorkspaceIdentity): boolean;
+export declare function wireOptions(value: unknown): WireOptions;
+/** Output the native environment omitted before a chunk (Pi `ShellOutputSkip`), validated off the wire. */
+export declare function skipped(value: unknown): ShellOutputSkip;
+export declare function requestInput(value: unknown): {
+    requestId: string;
+    identity: WorkspaceIdentity;
+    command: string;
+    options: WireOptions;
+    output: boolean;
+};
+export declare function wireResult(value: ShellResult): {
+    ok: true;
+    value: import("@earendil-works/pi-durable/env").ShellExecResult;
+} | {
+    ok: boolean;
+    error: {
+        spillPath?: string;
+        code: ExecutionErrorCode;
+        message: string;
+    };
+};
+export declare function frame(value: unknown, requestId: string, sequence: number): {
+    readonly type: "header";
+    readonly identity: WorkspaceIdentity;
+    readonly result?: never;
+} | {
+    readonly skipped?: ShellOutputSkip;
+    readonly type: "output";
+    readonly text: string;
+    readonly stream: "stdout" | "stderr";
+    readonly identity?: never;
+    readonly result?: never;
+} | {
+    readonly type: "result";
+    readonly result: import("@earendil-works/pi-durable/env").Result<import("@earendil-works/pi-durable/env").ShellExecResult, ExecutionError>;
+    readonly identity?: never;
+};
+export declare function positiveLimit(value: number): number;
+//# sourceMappingURL=remote-shell-protocol.d.ts.map

package/dist/remote-shell-protocol.js

@@ -0,0 +1,163 @@
+import { ExecutionError, ok, err } from '@earendil-works/pi-durable/env';
+export const schema = 'boring.remote-shell';
+export const version = 2;
+export const nativeVersion = 'pi-durable@1.1.0';
+export const contentType = 'application/x-ndjson';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function record(value) {
+    if (!isRecord(value))
+        throw new Error('Expected an object');
+    return value;
+}
+function keys(value, allowed) {
+    if (Object.keys(value).some(key => !allowed.includes(key)))
+        throw new Error('Unexpected protocol field');
+}
+function string(value) {
+    if (typeof value !== 'string')
+        throw new Error('Expected a string');
+    return value;
+}
+export function identity(value) {
+    const data = record(value);
+    keys(data, ['providerId', 'instanceId', 'incarnation', 'viewId']);
+    const result = { providerId: string(data['providerId']), instanceId: string(data['instanceId']), incarnation: string(data['incarnation']), viewId: string(data['viewId']) };
+    if (Object.values(result).some(value => !value || /[\x00-\x1f]/.test(value)))
+        throw new Error('Invalid workspace identity');
+    return Object.freeze(result);
+}
+export function sameIdentity(left, right) {
+    return left.providerId === right.providerId && left.instanceId === right.instanceId && left.incarnation === right.incarnation && left.viewId === right.viewId;
+}
+export function wireOptions(value) {
+    const data = record(value);
+    keys(data, ['cwd', 'env', 'inheritEnv', 'timeout', 'spill', 'window']);
+    const result = {};
+    if (data['cwd'] !== undefined)
+        result.cwd = string(data['cwd']);
+    if (data['env'] !== undefined) {
+        const entries = [];
+        for (const [key, value] of Object.entries(record(data['env'])))
+            entries.push([key, string(value)]);
+        result.env = Object.fromEntries(entries);
+    }
+    if (data['inheritEnv'] !== undefined) {
+        if (typeof data['inheritEnv'] !== 'boolean')
+            throw new Error('Invalid inheritEnv');
+        result.inheritEnv = data['inheritEnv'];
+    }
+    if (data['timeout'] !== undefined) {
+        if (typeof data['timeout'] !== 'number' || (!Number.isFinite(data['timeout']) || data['timeout'] <= 0))
+            throw new Error('Invalid timeout');
+        result.timeout = data['timeout'];
+    }
+    if (data['spill'] !== undefined) {
+        const spill = record(data['spill']);
+        keys(spill, ['afterBytes', 'afterLines']);
+        const afterBytes = spill['afterBytes'], afterLines = spill['afterLines'];
+        if (typeof afterBytes !== 'number' || !Number.isSafeInteger(afterBytes) || afterBytes < 0
+            || typeof afterLines !== 'number' || !Number.isSafeInteger(afterLines) || afterLines < 0)
+            throw new Error('Invalid spill thresholds');
+        result.spill = { afterBytes, afterLines };
+    }
+    if (data['window'] !== undefined) {
+        const window = record(data['window']);
+        keys(window, ['maxBytes', 'maxLines', 'minIntervalMs', 'bytesPerSecond']);
+        const limits = {};
+        for (const key of ['maxBytes', 'maxLines', 'minIntervalMs', 'bytesPerSecond']) {
+            const limit = window[key];
+            if (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < 0)
+                throw new Error('Invalid output window');
+            limits[key] = limit;
+        }
+        result.window = { maxBytes: limits['maxBytes'], maxLines: limits['maxLines'], minIntervalMs: limits['minIntervalMs'], bytesPerSecond: limits['bytesPerSecond'] };
+    }
+    return result;
+}
+/** Output the native environment omitted before a chunk (Pi `ShellOutputSkip`), validated off the wire. */
+export function skipped(value) {
+    const data = record(value);
+    keys(data, ['bytes', 'newlines', 'endsWithNewline']);
+    const bytes = data['bytes'], newlines = data['newlines'], endsWithNewline = data['endsWithNewline'];
+    if (typeof bytes !== 'number' || !Number.isSafeInteger(bytes) || bytes < 0 || typeof newlines !== 'number' || !Number.isSafeInteger(newlines) || newlines < 0 || typeof endsWithNewline !== 'boolean')
+        throw new Error('Invalid skipped output');
+    return { bytes, newlines, endsWithNewline };
+}
+export function requestInput(value) {
+    const data = record(value);
+    keys(data, ['schema', 'version', 'nativeVersion', 'requestId', 'identity', 'command', 'options', 'output']);
+    if (data['schema'] !== schema || data['version'] !== version || data['nativeVersion'] !== nativeVersion)
+        throw new Error('Unsupported remote shell protocol');
+    const requestId = string(data['requestId']);
+    if (!requestId || requestId.length > 128)
+        throw new Error('Invalid request identity');
+    if (typeof data['output'] !== 'boolean')
+        throw new Error('Invalid output selection');
+    return { requestId, identity: identity(data['identity']), command: string(data['command']), options: wireOptions(data['options']), output: data['output'] };
+}
+function errorCode(value) {
+    switch (value) {
+        case 'aborted':
+        case 'timeout':
+        case 'shell_unavailable':
+        case 'spawn_error':
+        case 'callback_error':
+        case 'unknown': return value;
+        default: throw new Error('Invalid native execution error');
+    }
+}
+function result(value) {
+    const data = record(value);
+    if (data['ok'] === true) {
+        keys(data, ['ok', 'value']);
+        const value = record(data['value']);
+        keys(value, ['exitCode', 'spillPath']);
+        const exitCode = value['exitCode'];
+        if (typeof exitCode !== 'number' || !Number.isSafeInteger(exitCode))
+            throw new Error('Invalid exit code');
+        return ok({ exitCode, ...(value['spillPath'] === undefined ? {} : { spillPath: string(value['spillPath']) }) });
+    }
+    if (data['ok'] === false) {
+        keys(data, ['ok', 'error']);
+        const value = record(data['error']);
+        keys(value, ['code', 'message', 'spillPath']);
+        const error = new ExecutionError(errorCode(value['code']), string(value['message']));
+        if (value['spillPath'] !== undefined)
+            error.spillPath = string(value['spillPath']);
+        return err(error);
+    }
+    throw new Error('Invalid native execution result');
+}
+export function wireResult(value) {
+    if (value.ok)
+        return value;
+    return { ok: false, error: { code: value.error.code, message: value.error.message, ...(value.error.spillPath === undefined ? {} : { spillPath: value.error.spillPath }) } };
+}
+export function frame(value, requestId, sequence) {
+    const data = record(value);
+    if (data['requestId'] !== requestId || data['sequence'] !== sequence)
+        throw new Error('Remote shell frame binding mismatch');
+    switch (data['type']) {
+        case 'header':
+            keys(data, ['type', 'requestId', 'sequence', 'schema', 'version', 'nativeVersion', 'identity']);
+            if (data['schema'] !== schema || data['version'] !== version || data['nativeVersion'] !== nativeVersion)
+                throw new Error('Unsupported remote shell protocol');
+            return { type: 'header', identity: identity(data['identity']) };
+        case 'output':
+            keys(data, ['type', 'requestId', 'sequence', 'text', 'stream', 'skipped']);
+            if (data['stream'] !== 'stdout' && data['stream'] !== 'stderr')
+                throw new Error('Invalid remote shell output stream');
+            return { type: 'output', text: string(data['text']), stream: data['stream'], ...(data['skipped'] === undefined ? {} : { skipped: skipped(data['skipped']) }) };
+        case 'result':
+            keys(data, ['type', 'requestId', 'sequence', 'result']);
+            return { type: 'result', result: result(data['result']) };
+        default: throw new Error('Unknown remote shell frame');
+    }
+}
+export function positiveLimit(value) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new TypeError('Remote shell limits must be positive safe integers');
+    return value;
+}

package/dist/remote-shell-window.d.ts

@@ -0,0 +1,14 @@
+import type { ShellOutputInfo, ShellOutputSkip, ShellOutputWindow } from '@earendil-works/pi-durable/env';
+export interface WindowedOutput {
+    readonly text: string;
+    readonly stream: 'stdout' | 'stderr';
+    readonly skipped?: ShellOutputSkip;
+}
+/** Collects output, drops what the window cannot keep, and flushes no faster than `minIntervalMs`. */
+export declare function windowedOutput(window: ShellOutputWindow, emit: (chunk: WindowedOutput) => void): {
+    push(chunk: string, info: ShellOutputInfo): void;
+    /** Deliver what is buffered before the terminal result. */
+    finish: () => void;
+    cancel(): void;
+};
+//# sourceMappingURL=remote-shell-window.d.ts.map