dsh-agy-cli 0.0.0-stage → 0.12.1

package/lib/agy/experimental-transport.js

@@ -0,0 +1,612 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+export class PersistentTransportError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'PersistentTransportError';
+    }
+}
+const DEFAULT_MAX_WORKERS = 8;
+const DEFAULT_MAX_FRAME_BYTES = 256 * 1024;
+const DEFAULT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+const DEFAULT_MAX_STDERR_BYTES = 64 * 1024;
+const DEFAULT_IDLE_TTL_MS = 30_000;
+const DEFAULT_READY_TIMEOUT_MS = 5_000;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+function validateInteger(name, value, minimum, maximum) {
+    if (!Number.isInteger(value) || value < minimum || value > maximum) {
+        throw new RangeError(`${name} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return value;
+}
+function normalizeOptions(options) {
+    if (options.executable.trim().length === 0) {
+        throw new RangeError('executable must not be empty');
+    }
+    return {
+        executable: options.executable,
+        args: options.args ?? [],
+        cwd: options.cwd,
+        env: options.env,
+        maxWorkers: validateInteger('maxWorkers', options.maxWorkers ?? DEFAULT_MAX_WORKERS, 1, 64),
+        maxFrameBytes: validateInteger('maxFrameBytes', options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES, 128, 16 * 1024 * 1024),
+        maxOutputBytes: validateInteger('maxOutputBytes', options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES, 1, 64 * 1024 * 1024),
+        maxStderrBytes: validateInteger('maxStderrBytes', options.maxStderrBytes ?? DEFAULT_MAX_STDERR_BYTES, 1, 8 * 1024 * 1024),
+        idleTtlMs: validateInteger('idleTtlMs', options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS, 0, 3_600_000),
+        readyTimeoutMs: validateInteger('readyTimeoutMs', options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS, 1, 60_000),
+        shutdownTimeoutMs: validateInteger('shutdownTimeoutMs', options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS, 1, 60_000),
+        defaultRequestTimeoutMs: validateInteger('defaultRequestTimeoutMs', options.defaultRequestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, 1, 3_600_000),
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function byteLength(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+/** Encode one bounded NDJSON frame, including its trailing newline. */
+export function encodePersistentFrame(frame, maxFrameBytes) {
+    const line = JSON.stringify(frame);
+    if (line === undefined) {
+        throw new PersistentTransportError('Persistent transport frame could not be encoded', 'PROTOCOL_ERROR');
+    }
+    const encoded = `${line}\n`;
+    if (byteLength(encoded) > maxFrameBytes) {
+        throw new PersistentTransportError('Persistent transport input frame exceeds the configured limit', 'FRAME_TOO_LARGE');
+    }
+    return encoded;
+}
+/** Parse and validate the small protocol envelope; payload remains opaque. */
+export function parsePersistentFrame(line) {
+    if (line.trim().length === 0) {
+        throw new PersistentTransportError('Persistent transport emitted an empty frame', 'PROTOCOL_ERROR');
+    }
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch (error) {
+        throw new PersistentTransportError('Persistent transport emitted malformed JSON', 'PROTOCOL_ERROR', {
+            cause: error,
+        });
+    }
+    if (!isRecord(value) || typeof value.kind !== 'string'
+        || !['ready', 'event', 'complete', 'error'].includes(value.kind)) {
+        throw new PersistentTransportError('Persistent transport emitted an invalid frame envelope', 'PROTOCOL_ERROR');
+    }
+    if (value.requestId !== undefined && typeof value.requestId !== 'string') {
+        throw new PersistentTransportError('Persistent transport frame requestId is invalid', 'PROTOCOL_ERROR');
+    }
+    if (value.sessionId !== undefined && typeof value.sessionId !== 'string') {
+        throw new PersistentTransportError('Persistent transport frame sessionId is invalid', 'PROTOCOL_ERROR');
+    }
+    return {
+        kind: value.kind,
+        ...(value.requestId === undefined ? {} : { requestId: value.requestId }),
+        ...(value.sessionId === undefined ? {} : { sessionId: value.sessionId }),
+        ...(Object.hasOwn(value, 'payload') ? { payload: value.payload } : {}),
+        ...(value.message === undefined ? {} : { message: String(value.message).slice(0, 256) }),
+    };
+}
+function terminateWorkerTree(child) {
+    const pid = child.pid;
+    if (pid === undefined) {
+        child.kill();
+        return;
+    }
+    if (process.platform === 'win32') {
+        const killer = spawn('taskkill', ['/pid', String(pid), '/t', '/f'], {
+            shell: false,
+            windowsHide: true,
+            stdio: 'ignore',
+        });
+        const fallback = setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch {
+                // The child may have exited while taskkill was traversing the tree.
+            }
+        }, 250);
+        try {
+            // Ask the direct child to close immediately so the parent can finish
+            // its lifecycle without waiting for taskkill's process to exit.
+            child.kill();
+        }
+        catch {
+            // taskkill remains responsible for descendants and the close handler
+            // still completes the worker state transition.
+        }
+        killer.once('error', () => {
+            clearTimeout(fallback);
+            try {
+                child.kill();
+            }
+            catch {
+                // The child may already be closed.
+            }
+        });
+        killer.once('close', () => clearTimeout(fallback));
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        child.kill('SIGKILL');
+    }
+}
+function errorFromUnknown(error, fallbackCode, fallbackMessage) {
+    if (error instanceof PersistentTransportError)
+        return error;
+    return new PersistentTransportError(fallbackMessage, fallbackCode, {
+        cause: error instanceof Error ? error : new Error(String(error)),
+    });
+}
+class PersistentAgyWorker {
+    options;
+    sessionId;
+    onStopped;
+    state = 'starting';
+    child;
+    active;
+    idleTimer;
+    startPromise;
+    closePromise = Promise.resolve();
+    closeResolve;
+    closed = true;
+    notifiedStopped = false;
+    stdoutBuffer = '';
+    stderrBytes = 0;
+    readyResolve;
+    readyReject;
+    readySettled = false;
+    constructor(sessionId, options, onStopped) {
+        this.sessionId = sessionId;
+        this.options = options;
+        this.onStopped = onStopped;
+    }
+    getState() {
+        return this.state;
+    }
+    async start() {
+        if (this.state === 'stopped' || this.state === 'stopping') {
+            throw new PersistentTransportError('Persistent AGY worker is stopped', 'WORKER_STOPPED');
+        }
+        if (this.state === 'idle' || this.state === 'busy')
+            return;
+        if (this.startPromise !== undefined)
+            return this.startPromise;
+        this.startPromise = this.spawnAndWaitForReady();
+        try {
+            await this.startPromise;
+        }
+        finally {
+            this.startPromise = undefined;
+        }
+    }
+    async request(input) {
+        await this.start();
+        if (this.state !== 'idle') {
+            throw new PersistentTransportError('Persistent AGY worker already has an active request', 'WORKER_BUSY');
+        }
+        if (input.signal?.aborted) {
+            await this.stop('reset');
+            throw new PersistentTransportError('Persistent AGY request aborted before write', 'ABORTED');
+        }
+        const timeoutMs = input.timeoutMs ?? this.options.defaultRequestTimeoutMs;
+        validateInteger('timeoutMs', timeoutMs, 1, 3_600_000);
+        const maxOutputBytes = Math.min(input.maxOutputBytes ?? this.options.maxOutputBytes, this.options.maxOutputBytes);
+        validateInteger('maxOutputBytes', maxOutputBytes, 1, this.options.maxOutputBytes);
+        this.clearIdleTimer();
+        this.state = 'busy';
+        return new Promise((resolve, reject) => {
+            const active = {
+                requestId: randomUUID(),
+                sessionId: this.sessionId,
+                startedAt: Date.now(),
+                maxOutputBytes,
+                events: [],
+                onEvent: input.onEvent,
+                signal: input.signal,
+                resolve,
+                reject,
+                outputBytes: 0,
+                firstEventAt: undefined,
+                timer: undefined,
+                abortListener: undefined,
+            };
+            this.active = active;
+            active.abortListener = () => this.failActiveAndReset(new PersistentTransportError('Persistent AGY request aborted', 'ABORTED'));
+            input.signal?.addEventListener('abort', active.abortListener, { once: true });
+            active.timer = setTimeout(() => this.failActiveAndReset(new PersistentTransportError('Persistent AGY request exceeded its timeout', 'TIMEOUT')), timeoutMs);
+            void this.sendRequest(active, input.payload);
+        });
+    }
+    async stop(reason = 'dispose') {
+        if (this.state === 'stopped')
+            return;
+        if (this.state === 'stopping') {
+            await this.closePromise;
+            return;
+        }
+        this.clearIdleTimer();
+        if (this.state === 'starting') {
+            this.rejectReady(reason === 'dispose'
+                ? new PersistentTransportError('Persistent AGY transport was disposed during worker startup', 'DISPOSED')
+                : new PersistentTransportError('Persistent AGY worker stopped before startup completed', 'WORKER_STOPPED'));
+        }
+        if (this.active !== undefined) {
+            this.settleActiveError(new PersistentTransportError(reason === 'dispose'
+                ? 'Persistent AGY transport was disposed'
+                : 'Persistent AGY worker was stopped before request completion', reason === 'dispose' ? 'DISPOSED' : 'WORKER_STOPPED'));
+        }
+        this.state = 'stopping';
+        const child = this.child;
+        if (child === undefined || this.closed) {
+            this.state = 'stopped';
+            this.notifyStopped();
+            return;
+        }
+        if (reason === 'dispose' || reason === 'idle') {
+            try {
+                child.stdin.end(encodePersistentFrame({ kind: 'shutdown' }, this.options.maxFrameBytes));
+            }
+            catch {
+                // The close handler below still performs the final state transition.
+            }
+            await Promise.race([this.closePromise, delay(this.options.shutdownTimeoutMs)]);
+        }
+        if (!this.closed)
+            terminateWorkerTree(child);
+        await this.closePromise;
+    }
+    async spawnAndWaitForReady() {
+        this.state = 'starting';
+        this.closed = false;
+        this.stdoutBuffer = '';
+        this.stderrBytes = 0;
+        this.readySettled = false;
+        this.closePromise = new Promise(resolve => { this.closeResolve = resolve; });
+        const readyPromise = new Promise((resolve, reject) => {
+            this.readyResolve = resolve;
+            this.readyReject = reject;
+        });
+        try {
+            const child = spawn(this.options.executable, [...this.options.args], {
+                cwd: this.options.cwd,
+                env: {
+                    ...process.env,
+                    ...this.options.env,
+                    DSH_AGY_EXPERIMENTAL_SESSION: this.sessionId,
+                },
+                shell: false,
+                detached: process.platform !== 'win32',
+                windowsHide: true,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            this.child = child;
+            this.attachChild(child);
+            const timeout = setTimeout(() => {
+                this.rejectReady(new PersistentTransportError('Persistent AGY worker did not become ready in time', 'WORKER_START_FAILED'));
+            }, this.options.readyTimeoutMs);
+            try {
+                await readyPromise;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+            const stateAfterReady = this.getState();
+            if (stateAfterReady === 'stopped' || stateAfterReady === 'stopping') {
+                throw new PersistentTransportError('Persistent AGY worker stopped during startup', 'WORKER_START_FAILED');
+            }
+            this.state = 'idle';
+            this.armIdleTimer();
+        }
+        catch (error) {
+            const mapped = errorFromUnknown(error, 'WORKER_START_FAILED', 'Persistent AGY worker failed to start');
+            await this.stop('reset');
+            throw mapped;
+        }
+        finally {
+            this.readyResolve = undefined;
+            this.readyReject = undefined;
+        }
+    }
+    attachChild(child) {
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => this.handleStdout(chunk));
+        child.stderr.on('data', (chunk) => {
+            this.stderrBytes += byteLength(chunk);
+            if (this.stderrBytes > this.options.maxStderrBytes) {
+                this.failActiveAndReset(new PersistentTransportError('Persistent AGY worker stderr exceeded its capture limit', 'OUTPUT_LIMIT'));
+            }
+        });
+        child.once('error', error => {
+            const code = this.state === 'starting'
+                ? 'WORKER_START_FAILED'
+                : 'WORKER_CRASHED';
+            const mapped = new PersistentTransportError(code === 'WORKER_START_FAILED'
+                ? 'Persistent AGY worker could not be started'
+                : 'Persistent AGY worker process failed', code, { cause: error });
+            this.rejectReady(mapped);
+            if (this.active !== undefined)
+                this.settleActiveError(mapped);
+        });
+        child.once('close', (exitCode, signal) => {
+            this.closed = true;
+            this.clearIdleTimer();
+            if (!this.readySettled) {
+                this.rejectReady(new PersistentTransportError('Persistent AGY worker exited before ready', 'WORKER_START_FAILED'));
+            }
+            if (this.active !== undefined) {
+                this.settleActiveError(new PersistentTransportError(`Persistent AGY worker exited before request completion (${exitCode ?? 'signal'})`, 'WORKER_CRASHED', { cause: signal === null ? undefined : new Error(signal) }));
+            }
+            this.state = 'stopped';
+            this.closeResolve?.();
+            this.closeResolve = undefined;
+            this.notifyStopped();
+        });
+    }
+    handleStdout(chunk) {
+        this.stdoutBuffer += chunk;
+        // Same runaway-line guard as the persistent transport: the byte valve only
+        // runs on completed lines, so an unsplit endless line would grow freely.
+        if (this.stdoutBuffer.length > this.options.maxFrameBytes) {
+            this.failActiveAndReset(new PersistentTransportError('Persistent AGY emitted a stdout line beyond the frame limit', 'OUTPUT_LIMIT'));
+            this.stdoutBuffer = '';
+            return;
+        }
+        let newlineIndex = this.stdoutBuffer.indexOf('\n');
+        while (newlineIndex >= 0) {
+            const rawLine = this.stdoutBuffer.slice(0, newlineIndex);
+            this.stdoutBuffer = this.stdoutBuffer.slice(newlineIndex + 1);
+            this.handleLine(rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine);
+            newlineIndex = this.stdoutBuffer.indexOf('\n');
+        }
+    }
+    handleLine(line) {
+        let frame;
+        try {
+            frame = parsePersistentFrame(line);
+        }
+        catch (error) {
+            this.failActiveAndReset(errorFromUnknown(error, 'PROTOCOL_ERROR', 'Persistent AGY worker emitted an invalid frame'));
+            return;
+        }
+        if (frame.kind === 'ready') {
+            if (frame.sessionId !== undefined && frame.sessionId !== this.sessionId) {
+                this.rejectReady(new PersistentTransportError('Persistent AGY worker ready frame belongs to another session', 'PROTOCOL_ERROR'));
+                this.failActiveAndReset(new PersistentTransportError('Persistent AGY worker session ownership check failed', 'PROTOCOL_ERROR'));
+                return;
+            }
+            this.resolveReady();
+            return;
+        }
+        const active = this.active;
+        if (active === undefined) {
+            this.failActiveAndReset(new PersistentTransportError('Persistent AGY worker emitted a response without an active request', 'PROTOCOL_ERROR'));
+            return;
+        }
+        active.outputBytes += byteLength(`${line}\n`);
+        if (active.outputBytes > active.maxOutputBytes) {
+            this.failActiveAndReset(new PersistentTransportError('Persistent AGY worker response exceeded its capture limit', 'OUTPUT_LIMIT'));
+            return;
+        }
+        if (frame.requestId !== active.requestId || frame.sessionId !== this.sessionId) {
+            this.failActiveAndReset(new PersistentTransportError('Persistent AGY worker response correlation failed', 'PROTOCOL_ERROR'));
+            return;
+        }
+        if (frame.kind === 'event') {
+            active.firstEventAt ??= Date.now();
+            active.events.push(frame.payload);
+            try {
+                active.onEvent?.(frame.payload);
+            }
+            catch (error) {
+                this.failActiveAndReset(new PersistentTransportError('Persistent AGY worker event handler failed', 'EVENT_HANDLER_FAILED', { cause: error instanceof Error ? error : new Error(String(error)) }));
+            }
+            return;
+        }
+        if (frame.kind === 'error') {
+            this.failActiveAndReset(new PersistentTransportError('Persistent AGY worker returned an error frame', 'WORKER_ERROR'));
+            return;
+        }
+        this.settleActiveSuccess();
+    }
+    async sendRequest(active, payload) {
+        try {
+            const frame = encodePersistentFrame({
+                kind: 'request',
+                requestId: active.requestId,
+                sessionId: active.sessionId,
+                payload,
+            }, this.options.maxFrameBytes);
+            await this.writeFrame(frame);
+        }
+        catch (error) {
+            if (this.active !== active)
+                return;
+            this.failActiveAndReset(errorFromUnknown(error, 'PROTOCOL_ERROR', 'Persistent AGY request could not be written'));
+        }
+    }
+    async writeFrame(frame) {
+        const stdin = this.child?.stdin;
+        if (stdin === undefined || !stdin.writable) {
+            throw new PersistentTransportError('Persistent AGY worker stdin is closed', 'WORKER_STOPPED');
+        }
+        if (stdin.write(frame))
+            return;
+        await new Promise((resolve, reject) => {
+            const onDrain = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            const cleanup = () => {
+                stdin.removeListener('drain', onDrain);
+                stdin.removeListener('error', onError);
+            };
+            stdin.once('drain', onDrain);
+            stdin.once('error', onError);
+        });
+    }
+    settleActiveSuccess() {
+        const active = this.active;
+        if (active === undefined)
+            return;
+        this.active = undefined;
+        this.clearActive(active);
+        this.state = 'idle';
+        this.armIdleTimer();
+        active.resolve({
+            requestId: active.requestId,
+            sessionId: active.sessionId,
+            events: [...active.events],
+            durationMs: Date.now() - active.startedAt,
+            ...(active.firstEventAt === undefined ? {} : { firstEventMs: active.firstEventAt - active.startedAt }),
+        });
+    }
+    settleActiveError(error) {
+        const active = this.active;
+        if (active === undefined)
+            return;
+        this.active = undefined;
+        this.clearActive(active);
+        active.reject(error);
+    }
+    clearActive(active) {
+        if (active.timer !== undefined)
+            clearTimeout(active.timer);
+        if (active.abortListener !== undefined)
+            active.signal?.removeEventListener('abort', active.abortListener);
+        active.abortListener = undefined;
+    }
+    failActiveAndReset(error) {
+        this.settleActiveError(error);
+        void this.stop('reset');
+    }
+    resolveReady() {
+        if (this.readySettled)
+            return;
+        this.readySettled = true;
+        this.readyResolve?.();
+    }
+    rejectReady(error) {
+        if (this.readySettled)
+            return;
+        this.readySettled = true;
+        this.readyReject?.(error);
+    }
+    armIdleTimer() {
+        this.clearIdleTimer();
+        if (this.options.idleTtlMs === 0 || this.state !== 'idle')
+            return;
+        this.idleTimer = setTimeout(() => { void this.stop('idle'); }, this.options.idleTtlMs);
+    }
+    clearIdleTimer() {
+        if (this.idleTimer !== undefined)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = undefined;
+    }
+    notifyStopped() {
+        if (this.notifiedStopped)
+            return;
+        this.notifiedStopped = true;
+        this.onStopped(this);
+    }
+}
+/**
+ * Experimental worker-per-session transport. It is intentionally not wired
+ * into AgyAdapter; callers must opt into this prototype directly.
+ */
+export class ExperimentalAgyTransport {
+    options;
+    workers = new Map();
+    disposed = false;
+    constructor(options) {
+        this.options = normalizeOptions(options);
+    }
+    async request(input) {
+        if (this.disposed) {
+            throw new PersistentTransportError('Persistent AGY transport is disposed', 'DISPOSED');
+        }
+        if (input.sessionId.trim().length === 0) {
+            throw new RangeError('sessionId must not be empty');
+        }
+        let worker = this.workers.get(input.sessionId);
+        if (worker?.getState() === 'stopped') {
+            this.workers.delete(input.sessionId);
+            worker = undefined;
+        }
+        if (worker === undefined) {
+            if (this.workers.size >= this.options.maxWorkers) {
+                throw new PersistentTransportError('Persistent AGY worker limit reached', 'WORKER_LIMIT');
+            }
+            worker = new PersistentAgyWorker(input.sessionId, this.options, stoppedWorker => {
+                if (this.workers.get(input.sessionId) === stoppedWorker)
+                    this.workers.delete(input.sessionId);
+            });
+            this.workers.set(input.sessionId, worker);
+        }
+        try {
+            return await worker.request(input);
+        }
+        catch (error) {
+            if (worker.getState() === 'stopped')
+                this.workers.delete(input.sessionId);
+            throw error;
+        }
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const workers = [...this.workers.values()];
+        await Promise.all(workers.map(worker => worker.stop('dispose')));
+        this.workers.clear();
+    }
+    getStats() {
+        let startingWorkers = 0;
+        let idleWorkers = 0;
+        let busyWorkers = 0;
+        let stoppingWorkers = 0;
+        for (const worker of this.workers.values()) {
+            switch (worker.getState()) {
+                case 'starting':
+                    startingWorkers += 1;
+                    break;
+                case 'idle':
+                    idleWorkers += 1;
+                    break;
+                case 'busy':
+                    busyWorkers += 1;
+                    break;
+                case 'stopping':
+                    stoppingWorkers += 1;
+                    break;
+                case 'stopped': break;
+            }
+        }
+        return {
+            totalWorkers: this.workers.size,
+            startingWorkers,
+            idleWorkers,
+            busyWorkers,
+            stoppingWorkers,
+            maxWorkers: this.options.maxWorkers,
+            disposed: this.disposed,
+        };
+    }
+}
+//# sourceMappingURL=experimental-transport.js.map