spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/claude-headless.js

@@ -0,0 +1,307 @@
+import { rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { controlRequest, withTimeout } from './headless-controller.js';
+import { shQuote } from './sh.js';
+const PKG = fileURLToPath(new URL('..', import.meta.url));
+const SPEX = join(PKG, 'bin', 'spex.mjs');
+const CONTROL_TIMEOUT_MS = 60_000;
+const START_TIMEOUT_MS = 30_000;
+const INTERRUPT_TIMEOUT_MS = 10_000;
+const RESULT_WAIT_MS = 20_000;
+const RESULT_EXIT_GRACE_MS = 500;
+const TERM_EXIT_GRACE_MS = 500;
+const KILL_EXIT_GRACE_MS = 2_000;
+const userEvent = (text) => JSON.stringify({
+    type: 'user',
+    message: { role: 'user', content: [{ type: 'text', text }] },
+});
+export const claudeHeadlessSock = (id) => join(tmpdir(), `spexcode-ch-${id}.sock`);
+export function claudeHeadlessLaunchCommand(id, runtimeDir, claudeCmd) {
+    return [shQuote(SPEX), 'internal', 'claude-headless-run', shQuote(id), shQuote(runtimeDir), shQuote(claudeCmd), '--'].join(' ');
+}
+export const deliverViaClaudeHeadless = (rec, text) => controlRequest(claudeHeadlessSock(rec.session), { type: 'deliver', text, mode: rec.status === 'active' ? 'steer' : 'wake' }, {
+    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'claude-headless control rejected the request',
+});
+export const interruptClaudeHeadless = (rec) => controlRequest(claudeHeadlessSock(rec.session), { type: 'interrupt' }, {
+    name: 'claude-headless', session: rec.session, timeoutMs: CONTROL_TIMEOUT_MS,
+    rejected: 'claude-headless control rejected the request',
+});
+export class ClaudeHeadlessController {
+    id;
+    claudeCmd;
+    cwd;
+    server = null;
+    child = null;
+    controlQueue = Promise.resolve();
+    closing = false;
+    socketPath;
+    constructor(id, _runtimeDir, claudeCmd, cwd = process.cwd()) {
+        this.id = id;
+        this.claudeCmd = claudeCmd;
+        this.cwd = cwd;
+        this.socketPath = claudeHeadlessSock(id);
+    }
+    async start(initialPrompt) {
+        try {
+            rmSync(this.socketPath, { force: true });
+        }
+        catch { /* stale control socket is replaced at startup */ }
+        this.server = createServer((socket) => this.accept(socket));
+        await new Promise((resolve, reject) => {
+            const onError = (error) => { this.server?.off('listening', onListening); reject(error); };
+            const onListening = () => { this.server?.off('error', onError); resolve(); };
+            this.server.once('error', onError);
+            this.server.once('listening', onListening);
+            this.server.listen(this.socketPath);
+        });
+        if (initialPrompt)
+            void this.spawnTurn(initialPrompt, false).catch((error) => {
+                console.error(`[spex claude-headless] initial turn failed: ${error.message}`);
+            });
+    }
+    async close() {
+        if (this.closing)
+            return;
+        this.closing = true;
+        const child = this.child;
+        try {
+            if (child)
+                await this.ensureTurnExit(child);
+        }
+        finally {
+            await new Promise((resolve) => {
+                if (!this.server)
+                    return resolve();
+                this.server.close(() => resolve());
+            });
+            try {
+                rmSync(this.socketPath, { force: true });
+            }
+            catch { /* best-effort cleanup after close */ }
+        }
+    }
+    accept(socket) {
+        socket.setEncoding('utf8');
+        let buffer = '';
+        let handled = false;
+        socket.on('data', (chunk) => {
+            if (handled)
+                return;
+            buffer += chunk;
+            const nl = buffer.indexOf('\n');
+            if (nl < 0)
+                return;
+            handled = true;
+            let request;
+            try {
+                request = JSON.parse(buffer.slice(0, nl));
+            }
+            catch (error) {
+                socket.end(`${JSON.stringify({ ok: false, error: `invalid control request: ${error.message}` })}\n`);
+                return;
+            }
+            this.controlQueue = this.controlQueue.then(async () => {
+                const result = await this.handle(request).catch((error) => ({ ok: false, error: error.message }));
+                socket.end(`${JSON.stringify(result)}\n`);
+            });
+        });
+    }
+    async handle(request) {
+        if (request.type === 'deliver') {
+            if (!request.text)
+                return { ok: false, error: 'empty prompt - nothing to deliver' };
+            const current = this.child;
+            if (request.mode === 'steer' && current?.active && current.process.stdin.writable) {
+                await this.writeLine(current, userEvent(request.text));
+                return { ok: true };
+            }
+            if (current?.active) {
+                await Promise.race([
+                    withTimeout(current.result, RESULT_WAIT_MS, 'previous claude-headless turn did not reach its result before idle wake'),
+                    current.exited.then((code) => { throw new Error(`previous claude-headless turn exited before its result (code ${code ?? 'signal'})`); }),
+                ]);
+            }
+            if (current)
+                await this.ensureTurnExit(current);
+            await this.spawnTurn(request.text, true);
+            return { ok: true };
+        }
+        if (request.type === 'interrupt')
+            return this.interrupt();
+        return { ok: false, error: 'unknown claude-headless control request' };
+    }
+    async interrupt() {
+        const child = this.child;
+        if (!child?.active || !child.process.stdin.writable)
+            return { ok: true };
+        const requestId = randomUUID();
+        const ack = new Promise((resolve) => child.interruptAcks.set(requestId, resolve));
+        await this.writeLine(child, JSON.stringify({
+            type: 'control_request',
+            request_id: requestId,
+            request: { subtype: 'interrupt' },
+        }));
+        try {
+            await withTimeout(ack, INTERRUPT_TIMEOUT_MS, `claude-headless interrupt was not confirmed for session ${this.id}`);
+            return { ok: true };
+        }
+        finally {
+            child.interruptAcks.delete(requestId);
+        }
+    }
+    async spawnTurn(text, resume) {
+        if (this.closing)
+            throw new Error('claude-headless controller is closing');
+        const mode = resume ? ['--resume', this.id] : ['--session-id', this.id];
+        const args = ['-p', ...mode, '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose'];
+        const command = `exec ${this.claudeCmd} ${args.map(shQuote).join(' ')}`;
+        const childProcess = spawn('/bin/sh', ['-lc', command], {
+            cwd: this.cwd,
+            env: process.env,
+            detached: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let sawFirstEvent;
+        const firstEvent = new Promise((resolve) => { sawFirstEvent = resolve; });
+        let resolveExit;
+        const exited = new Promise((resolve) => { resolveExit = resolve; });
+        let sawResult;
+        const result = new Promise((resolve) => { sawResult = resolve; });
+        const turn = {
+            process: childProcess,
+            active: true,
+            completed: false,
+            exited,
+            teardown: null,
+            result,
+            sawResult,
+            firstEvent,
+            sawFirstEvent,
+            interruptAcks: new Map(),
+        };
+        this.child = turn;
+        let stdoutBuffer = '';
+        childProcess.stdout.setEncoding('utf8');
+        childProcess.stderr.pipe(process.stderr);
+        childProcess.stdout.on('data', (chunk) => {
+            stdoutBuffer += chunk;
+            for (;;) {
+                const nl = stdoutBuffer.indexOf('\n');
+                if (nl < 0)
+                    break;
+                const line = stdoutBuffer.slice(0, nl);
+                stdoutBuffer = stdoutBuffer.slice(nl + 1);
+                const nativeLine = `${line}\n`;
+                globalThis.process.stdout.write(nativeLine);
+                turn.sawFirstEvent();
+                this.observeEvent(turn, line);
+            }
+        });
+        childProcess.once('error', (error) => {
+            console.error(`[spex claude-headless] child spawn failed: ${error.message}`);
+        });
+        childProcess.once('close', (code) => {
+            turn.active = false;
+            if (stdoutBuffer)
+                console.error('[spex claude-headless] dropped a partial non-line stdout event');
+            if (this.child === turn)
+                this.child = null;
+            resolveExit(code);
+            if (!turn.completed && code !== 0 && !this.closing) {
+                void import('./harness.js').then(({ reportHeadlessTurnExit }) => reportHeadlessTurnExit(this.id, 'claude-headless', code, this.cwd));
+            }
+        });
+        await this.writeLine(turn, userEvent(text));
+        await Promise.race([
+            withTimeout(turn.firstEvent, START_TIMEOUT_MS, `claude-headless child produced no stream event for session ${this.id}`),
+            turn.exited.then((code) => { throw new Error(`claude-headless child exited before accepting the turn (code ${code ?? 'signal'})`); }),
+        ]);
+    }
+    observeEvent(turn, line) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (event?.type === 'control_response' && typeof event?.response?.request_id === 'string') {
+            turn.interruptAcks.get(event.response.request_id)?.();
+        }
+        if (event?.type === 'result' && !turn.completed) {
+            turn.completed = true;
+            turn.active = false;
+            turn.sawResult();
+            void this.ensureTurnExit(turn).catch((error) => {
+                console.error(`[spex claude-headless] completed turn teardown failed: ${error.message}`);
+            });
+        }
+    }
+    ensureTurnExit(turn) {
+        turn.teardown ??= this.terminateTurn(turn);
+        return turn.teardown;
+    }
+    async terminateTurn(turn) {
+        if (turn.completed) {
+            if (turn.process.stdin.writable)
+                turn.process.stdin.end();
+            if (await this.waitForTurnExit(turn, RESULT_EXIT_GRACE_MS))
+                return;
+            this.signalTurn(turn, 'SIGKILL');
+            await withTimeout(turn.exited, KILL_EXIT_GRACE_MS, `claude-headless completed turn process group ${turn.process.pid ?? 'unknown'} did not exit after SIGKILL`);
+            return;
+        }
+        this.signalTurn(turn, 'SIGTERM');
+        if (await this.waitForTurnExit(turn, TERM_EXIT_GRACE_MS))
+            return;
+        this.signalTurn(turn, 'SIGKILL');
+        await withTimeout(turn.exited, KILL_EXIT_GRACE_MS, `claude-headless turn process group ${turn.process.pid ?? 'unknown'} did not exit after SIGKILL`);
+    }
+    async waitForTurnExit(turn, timeoutMs) {
+        try {
+            await withTimeout(turn.exited, timeoutMs, 'turn exit grace elapsed');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    signalTurn(turn, signal) {
+        const pid = turn.process.pid;
+        try {
+            if (pid)
+                process.kill(-pid, signal);
+            else
+                turn.process.kill(signal);
+        }
+        catch (error) {
+            if (error.code !== 'ESRCH')
+                throw error;
+        }
+    }
+    writeLine(turn, line) {
+        return new Promise((resolve, reject) => {
+            if (!turn.process.stdin.writable)
+                return reject(new Error('claude-headless child stdin is not writable'));
+            turn.process.stdin.write(`${line}\n`, (error) => error ? reject(error) : resolve());
+        });
+    }
+}
+export async function runClaudeHeadlessController(id, runtimeDir, claudeCmd, tail) {
+    const controller = new ClaudeHeadlessController(id, runtimeDir, claudeCmd);
+    const resume = tail[0] === '--resume';
+    const prompt = resume ? undefined : tail[0] === '--session-id' ? tail.slice(2).join(' ') : tail.join(' ');
+    await controller.start(prompt);
+    await new Promise((resolve) => {
+        const stop = () => void controller.close().finally(resolve);
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        process.once('SIGHUP', stop);
+    });
+}

package/node_modules/@spexcode/spec-cli/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};