@anureo/sdk 0.2.0 → 0.3.0

package/src/process.js

@@ -0,0 +1,331 @@
+// Owns harness subprocess I/O, exit observation, and process-tree cleanup.
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+/** Process failure category for adapters; native causes are reduced to a format-checked code. */
+export class ProcessPortError extends Error {
+    /**
+     * Construct a failure using caller-supplied safe message text, which is retained verbatim.
+     * Supply a native cause to retain only its format-checked error code.
+     */
+    constructor(code, message, options) {
+        // Native spawn errors contain spawnargs. Never retain their raw cause in a public error.
+        super(message);
+        this.name = 'ProcessPortError';
+        this.code = code;
+        const nativeCode = readNativeErrorCode(options?.cause);
+        if (nativeCode !== undefined)
+            this.nativeCode = nativeCode;
+    }
+    /** Stable category for adapter startup, input, or disposal failures. */
+    code;
+    /**
+     * Native code of 1 to 64 characters, beginning with an uppercase letter and containing only
+     * uppercase letters, digits, and underscores.
+     */
+    nativeCode;
+}
+/**
+ * Launch a harness executable directly with piped I/O and literal arguments, without a shell.
+ * Resolve after the spawn event provides a process handle. The caller handles protocol readiness.
+ * Invalid inputs or launch failures reject with HARNESS_UNAVAILABLE. Failed startup releases any
+ * local pipes it acquired. Drain output and await disposal even after child exit.
+ *
+ * ACP's processStream awaits launch to wire the pipes into its channel, propagates launch
+ * rejection, and delegates channel disposal to the handle.
+ */
+export async function spawnHarnessProcess(options) {
+    const timeoutMs = validateProcessOptions(options);
+    const owned = options.owned ?? true;
+    const child = launchProcess({ options, owned });
+    const initialPid = child.pid;
+    const exit = observeProcessExit(child);
+    // Prevent an unhandled pipe error if a peer closes while the caller isn't writing.
+    child.stdin.on('error', () => { });
+    const pid = await waitForSpawn(child, initialPid);
+    return createProcessHandle({ child, pid, owned, timeoutMs, ...exit });
+}
+/**
+ * Return the validated grace period for disposal. Throw HARNESS_UNAVAILABLE for an empty
+ * executable, NUL bytes in the executable or arguments, or an invalid timeout. spawnHarnessProcess
+ * calls this before launching the child.
+ */
+function validateProcessOptions(options) {
+    if (!options.command || options.command.includes('\0') || options.args?.some((arg) => arg.includes('\0'))) {
+        throw new ProcessPortError('HARNESS_UNAVAILABLE', 'Invalid harness executable or argument');
+    }
+    const timeoutMs = options.shutdownTimeoutMs ?? 1000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 60_000) {
+        throw new ProcessPortError('HARNESS_UNAVAILABLE', 'Invalid process shutdown timeout');
+    }
+    return timeoutMs;
+}
+/**
+ * Open piped stdio for a shell-free launch. Detach owned POSIX children so teardown can signal
+ * their whole group. Convert synchronous spawn failures to HARNESS_UNAVAILABLE. spawnHarnessProcess
+ * installs the event observers after this returns.
+ */
+function launchProcess({ options, owned }) {
+    try {
+        return spawn(options.command, [...(options.args ?? [])], {
+            cwd: options.cwd, env: options.env, stdio: ['pipe', 'pipe', 'pipe'],
+            detached: owned && process.platform !== 'win32', shell: false, windowsHide: true,
+        });
+    }
+    catch (cause) {
+        throw new ProcessPortError('HARNESS_UNAVAILABLE', 'Unable to start harness executable', { cause });
+    }
+}
+/**
+ * Register child exit and error listeners before spawnHarnessProcess awaits startup. Update the exit
+ * flag before resolving so writes and teardown can consult the observation immediately.
+ */
+function observeProcessExit(child) {
+    let didExit = false;
+    const exited = new Promise((resolve) => {
+        child.once('exit', (code, signal) => {
+            didExit = true;
+            resolve({ code, signal });
+        });
+        child.once('error', (error) => {
+            if (!child.pid) {
+                didExit = true;
+                resolve({ code: null, signal: null, errorCode: error.code });
+            }
+        });
+    });
+    return { exited, didExit: () => didExit };
+}
+/**
+ * Wait for the spawn event and retain its PID before the runtime can clear it on exit. Fall back
+ * to the initial PID if the event provides no usable PID. On failure, release the pipes and
+ * reject with HARNESS_UNAVAILABLE so spawnHarnessProcess never publishes a partial handle.
+ */
+async function waitForSpawn(child, initialPid) {
+    let pid = initialPid;
+    try {
+        await new Promise((resolve, reject) => {
+            child.once('spawn', () => {
+                const spawnPid = child.pid;
+                if (spawnPid !== undefined && spawnPid > 1)
+                    pid = spawnPid;
+                resolve();
+            });
+            child.once('error', reject);
+        });
+    }
+    catch (cause) {
+        return failProcessStartup(child, cause);
+    }
+    if (pid === undefined || pid <= 1)
+        return failProcessStartup(child);
+    return pid;
+}
+/** Release startup's local pipes before rejecting launch with a privacy-safe error. */
+function failProcessStartup(child, cause) {
+    destroyProcessStreams(child);
+    throw new ProcessPortError('HARNESS_UNAVAILABLE', 'Unable to start harness executable', { cause });
+}
+/** Close all three local pipes after failed startup or after disposal, even if termination failed. */
+function destroyProcessStreams(child) {
+    child.stdin.destroy();
+    child.stdout.destroy();
+    child.stderr.destroy();
+}
+/**
+ * Give spawnHarnessProcess's callers the pipes and exit observation. Keep stdin write admission
+ * and the teardown promise together so disposing closes admission and shares the cleanup outcome.
+ */
+function createProcessHandle(resources) {
+    const { child, pid, owned, didExit, exited } = resources;
+    const { stdin, stdout, stderr } = child;
+    let disposePromise;
+    return {
+        pid, owned, stdout, stderr, exited,
+        write(chunk) {
+            if (disposePromise || isInputClosed(stdin) || didExit()) {
+                return Promise.reject(new ProcessPortError('PROCESS_WRITE_FAILED', 'Harness process input is closed'));
+            }
+            return runInputOperation('Unable to write harness input', (complete) => {
+                stdin.write(chunk, complete);
+            });
+        },
+        closeInput() {
+            return runInputOperation('Unable to close harness input', (complete) => {
+                if (isInputClosed(stdin))
+                    complete();
+                else
+                    stdin.end(complete);
+            });
+        },
+        dispose() {
+            return disposePromise ??= disposeProcess(resources);
+        },
+    };
+}
+/** Treat ending as closed for writes and redundant close requests. */
+function isInputClosed(stdin) {
+    return stdin.destroyed || stdin.writableEnded;
+}
+/**
+ * Settle the handle's write or close promise from the callback passed to stdin. Convert callback
+ * errors to PROCESS_WRITE_FAILED and let synchronous exceptions reject through the promise executor.
+ */
+function runInputOperation(failureMessage, start) {
+    return new Promise((resolve, reject) => {
+        start((error) => {
+            if (error)
+                reject(new ProcessPortError('PROCESS_WRITE_FAILED', failureMessage, { cause: error }));
+            else
+                resolve();
+        });
+    });
+}
+/**
+ * createProcessHandle's dispose method caches this promise. Terminate owned trees or unref
+ * external processes, then destroy local pipes even on failure. Convert native termination or
+ * unref errors to a ProcessPortError containing only safe error details.
+ */
+async function disposeProcess({ child, pid, owned, timeoutMs, didExit, exited }) {
+    try {
+        if (owned) {
+            await terminateTree(pid, timeoutMs, didExit);
+            if (!didExit())
+                await waitForTerminatedProcessExit(didExit, exited);
+        }
+        else {
+            child.unref();
+        }
+    }
+    catch (cause) {
+        if (cause instanceof ProcessPortError)
+            throw cause;
+        throw new ProcessPortError('PROCESS_DISPOSE_FAILED', 'Unable to dispose harness process', { cause });
+    }
+    finally {
+        destroyProcessStreams(child);
+    }
+}
+/**
+ * After tree termination, disposeProcess allows 1000 ms for any pending child exit observation.
+ * A vanished group can precede the child exit event. Reject PROCESS_DISPOSE_FAILED if exit still
+ * has not been observed.
+ */
+async function waitForTerminatedProcessExit(didExit, exited) {
+    await Promise.race([exited, delay(1000)]);
+    if (!didExit())
+        throw new ProcessPortError('PROCESS_DISPOSE_FAILED', 'Harness process did not exit after termination');
+}
+/**
+ * disposeProcess awaits this only for owned children and sanitizes failures before rejecting its
+ * public dispose promise. Validate the retained PID, then delegate platform cleanup; callers retain
+ * ownership of exit observation and pipe destruction.
+ */
+async function terminateTree(pid, timeoutMs, didExit) {
+    // Bun may clear/change ChildProcess.pid after exit. Only use the original positive PID.
+    if (!Number.isSafeInteger(pid) || pid <= 1)
+        throw new ProcessPortError('PROCESS_DISPOSE_FAILED', 'Invalid original harness PID');
+    if (process.platform === 'win32')
+        return terminateWindowsTree(pid, timeoutMs, didExit);
+    return terminatePosixTree(pid, timeoutMs);
+}
+/**
+ * terminateTree delegates here on POSIX; exit observation and pipe destruction remain in
+ * disposeProcess. Stop the detached POSIX group and force remaining descendants after the grace
+ * period.
+ */
+async function terminatePosixTree(pid, timeoutMs) {
+    // Descendants can keep inherited pipes open after the direct child has exited.
+    const group = -pid;
+    await signalGroupWithExitRace(group, 'SIGTERM');
+    const deadline = Date.now() + timeoutMs;
+    while (processOrGroupExists(group) && Date.now() < deadline)
+        await delay(10);
+    if (processOrGroupExists(group))
+        await signalGroupWithExitRace(group, 'SIGKILL');
+}
+/**
+ * Signal the negative group PID for terminatePosixTree. A vanished group completes the attempt.
+ * Retry a short exit-time EPERM race up to four times, then propagate the failure to disposal.
+ */
+async function signalGroupWithExitRace(group, signal) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            process.kill(group, signal);
+            return;
+        }
+        catch (error) {
+            const { code } = error;
+            if (code === 'ESRCH')
+                return;
+            if (code !== 'EPERM' || attempt >= 4)
+                throw error;
+            await delay(10);
+        }
+    }
+}
+/**
+ * Stop the Windows tree for terminateTree. Attempt graceful taskkill while the child is still
+ * running. Escalate immediately if that attempt fails and exit is still pending, or after the
+ * grace period if the child remains alive. Forced taskkill failures reject teardown.
+ */
+async function terminateWindowsTree(pid, timeoutMs, didExit) {
+    if (!didExit()) {
+        try {
+            await windowsKillTree(pid, 'graceful');
+        }
+        catch {
+            // Console-less Windows children may reject non-forced taskkill, so retry while alive.
+            if (!didExit())
+                await windowsKillTree(pid, 'force');
+        }
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (!didExit() && Date.now() < deadline)
+        await delay(10);
+    if (!didExit())
+        await windowsKillTree(pid, 'force');
+}
+/**
+ * Run shell-free taskkill for terminateWindowsTree. Reject if the tool fails to start or exits
+ * unsuccessfully while the original PID is still present.
+ */
+async function windowsKillTree(pid, mode) {
+    await new Promise((resolve, reject) => {
+        const killer = spawn('taskkill.exe', ['/PID', String(pid), '/T', ...(mode === 'force' ? ['/F'] : [])], {
+            stdio: 'ignore', windowsHide: true, shell: false,
+        });
+        killer.once('error', reject);
+        killer.once('exit', (code) => {
+            // taskkill reports a nonzero result if the process exited during the call.
+            if (code === 0 || !processOrGroupExists(pid))
+                resolve();
+            else
+                reject(new ProcessPortError('PROCESS_DISPOSE_FAILED', 'Unable to terminate harness process tree'));
+        });
+    });
+}
+/**
+ * terminatePosixTree uses this for POSIX polling; windowsKillTree uses it to distinguish a taskkill
+ * failure from concurrent child exit. Probe a PID or negative POSIX group without signalling it; EPERM
+ * counts as existing so cleanup still escalates.
+ */
+function processOrGroupExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * Extract only a bounded uppercase code for ProcessPortError; a native cause may contain private
+ * spawn arguments and must never become part of the public error.
+ */
+function readNativeErrorCode(cause) {
+    if (!cause || typeof cause !== 'object' || !('code' in cause))
+        return undefined;
+    if (typeof cause.code !== 'string' || !/^[A-Z][A-Z0-9_]{0,63}$/.test(cause.code))
+        return undefined;
+    return cause.code;
+}

package/src/queue.d.ts

@@ -0,0 +1,143 @@
+/** Queue budgets for producers and event subscriptions. Each resolved budget must be a positive safe integer. */
+export interface QueueLimits {
+    /** Maximum buffered regular events; defaults to 2048. Direct delivery to a waiting reader consumes no slot. */
+    maxEvents?: number;
+    /** Maximum bytes buffered by regular events; defaults to 16 MiB. Controls have a separate count budget. */
+    maxBytes?: number;
+    /** Maximum bytes per regular or control event; defaults to 8 MiB. Each event must also fit maxBytes. */
+    maxFrameBytes?: number;
+    /** Maximum suspended write calls. Defaults to 32. */
+    maxWaitingWriters?: number;
+    /** Maximum buffered controls; defaults to 33. They drain after regular events and use separate capacity. */
+    maxControlEvents?: number;
+}
+/**
+ * Buffer a producer stream within event and byte budgets, or await capacity with write.
+ * One iterator owns reads at a time. Returning it releases ownership while the producer stays open.
+ * Producers own closure and consumers own iterator release. Buffered regular events drain before
+ * buffered controls, then readers observe completion or failure. Values are retained by reference;
+ * keep their measured size stable while queued. EventHub uses a private queue per observer to
+ * isolate overflow, while adapter transports use queues for incoming frames or native input.
+ */
+export declare class BoundedEventQueue<T> implements AsyncIterable<T> {
+    private readonly sizeOf;
+    /**
+     * Configure storage without claiming a reader. Invalid resolved budgets throw INVALID_PARAMS.
+     * Omitted or nullish budget fields select the QueueLimits defaults. The queue calls sizeOf during
+     * admission and propagates measurement failures. It defaults to measuring the UTF-8 byte length
+     * of the JSON serialization. A custom measurement must return a consistent, nonnegative byte
+     * count because a value can be measured more than once.
+     */
+    constructor(limits?: QueueLimits, sizeOf?: (value: T) => number);
+    /** Resolved construction-time budgets exposed for producers; callers must treat this object as read-only. */
+    readonly limits: Required<QueueLimits>;
+    /** Count regular events and controls currently in the buffer. */
+    get bufferedEvents(): number;
+    /** Count bytes reserved by buffered regular events. Controls consume their own event budget. */
+    get bufferedBytes(): number;
+    /**
+     * Check regular-event admission without reserving capacity. A later push can still fail.
+     * Throw the stored non-nullish closure cause (or STREAM_CLOSED), FRAME_TOO_LARGE, a measurement
+     * failure, or BACKPRESSURE_EXCEEDED for a full regular buffer.
+     */
+    assertWritable(value: T): void;
+    /**
+     * Deliver to a waiting read or buffer synchronously, throwing on closure, capacity or
+     * size/measurement failure without evicting data. Producers handle failures and own closure.
+     * EventHub.publish ends only the affected observer on failure. The message listener in
+     * createSocketTransport also closes the native socket.
+     */
+    push(value: T): void;
+    /**
+     * Await capacity and resolve once delivered or buffered, without waiting for consumption.
+     * Reject on closure, size/measurement failure or exhausted writer capacity.
+     * Waking writers compete for capacity and recheck it before admitting a value. Pass accepted
+     * to run a synchronous callback after admission. If it throws, the promise rejects and the value
+     * remains admitted. Producers can end the queue to wake all blocked writers and reject admission.
+     */
+    write(value: T, accepted?: () => void): Promise<void>;
+    /**
+     * Admit a control event even when the regular buffer is full. Each event still obeys
+     * maxFrameBytes and maxBytes; buffered controls have a separate maxControlEvents limit
+     * and do not contribute to bufferedBytes.
+     * Buffered regular events are delivered before buffered control events. Throws on closure,
+     * measurement/size failure or exhausted control capacity; callers still own producer closure.
+     */
+    pushControl(value: T): void;
+    /**
+     * Admit a final control under the usual control budget, then close admission. Readers can
+     * receive the control before completion. Already-ended queues ignore the value. If admission
+     * throws, the producer still owns recovery or closure.
+     */
+    endWithControl(value: T): void;
+    /**
+     * Idempotently close admission, wake blocked writers so they can reject, and settle any pending read.
+     * Buffered values drain before a truthy cause rejects reads; falsy causes complete reads normally.
+     * Closure checks throw a non-nullish stored cause, otherwise STREAM_CLOSED.
+     * Reader ownership remains until next observes drained closure or the consumer calls return or
+     * throw on the iterator. The caller still owns stopping any native producer.
+     */
+    end(cause?: unknown): void;
+    /**
+     * Claim exclusive reader ownership, throwing EVENT_STREAM_ALREADY_OWNED until the prior reader
+     * releases it. next drains regular values then controls before terminal completion or rejection.
+     * A second next while a read is blocked rejects with CONCURRENT_EVENT_READ. return and throw
+     * release ownership and complete a blocked read while leaving the producer open. throw also
+     * rejects its own promise with the supplied cause. A pending read settled by end still needs
+     * a subsequent next, return or throw to release ownership.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    private readonly entries;
+    private bytes;
+    private activeReaderToken?;
+    private pendingRead?;
+    private controls;
+    private ended;
+    private failure?;
+    private waitingWriterResumes;
+    /**
+     * end, readBuffered and readNext wake blocked writers when they close the queue, free capacity
+     * or register a reader for direct delivery. Writers recheck admission on resumption.
+     */
+    private resumeWaitingWriters;
+    /**
+     * assertWritable and write share this admission rule. A pending read permits direct delivery even
+     * at the buffer budget; checking capacity neither reserves a slot nor wakes a producer.
+     */
+    private isRegularBufferFull;
+    /**
+     * push and pushControl try direct delivery after checking size. Report whether this settled
+     * a pending read so the caller can skip buffering.
+     */
+    private deliverToWaitingReader;
+    /** Remove the pending read before its caller delivers a value, completes it or rejects it. */
+    private takePendingRead;
+    /**
+     * Producer admission uses this to check for closure. A closed queue throws the stored
+     * non-nullish cause or STREAM_CLOSED and keeps the reader attached.
+     */
+    private assertOpen;
+    /**
+     * assertWritable, push, write and pushControl call before admission. Measure without reserving
+     * capacity; throw FRAME_TOO_LARGE above either single-frame or regular-byte limits, including for
+     * controls. Propagate sizeOf failures unchanged so the producer can handle admission failure.
+     */
+    private checkedSize;
+    /**
+     * Settle the iterator's next call from buffered data or drained closure. Otherwise register a
+     * pending read and wake writers because they can now deliver directly. A detached reader
+     * completes immediately, and an overlapping blocked read rejects without replacing the first.
+     */
+    private readNext;
+    /**
+     * readNext on drained closure and the iterator's return and throw release ownership here.
+     * createSubscription also calls return when cancelled. Only the active reader can have a pending
+     * read, so checking its token protects a replacement reader from stale calls.
+     */
+    private detachReader;
+    /**
+     * Give readNext regular values before controls and release regular bytes before waking writers.
+     * Return undefined only when neither buffer has data, leaving terminal settlement to readNext.
+     */
+    private readBuffered;
+}