@welluable/orch 1.0.0

package/lib/agent-claude.js

@@ -0,0 +1,66 @@
+import { Agent } from './agent.js';
+import { normalizeClaudeToolEvent } from './tool-status.js';
+
+export class AgentClaude extends Agent {
+    getSpawnConfig(promptToSend) {
+        const args = this.readOnly
+            ? [
+                  '-p',
+                  '--output-format',
+                  'stream-json',
+                  '--verbose',
+                  '--permission-mode',
+                  'plan',
+                  promptToSend,
+              ]
+            : [
+                  '-p',
+                  '--output-format',
+                  'stream-json',
+                  '--verbose',
+                  '--dangerously-skip-permissions',
+                  promptToSend,
+              ];
+        return {
+            command: 'claude',
+            args,
+            options: {
+                cwd: this.cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: process.env,
+            },
+        };
+    }
+
+    handleStreamEvent(event, { finish }) {
+        switch (event.type) {
+            case 'system': {
+                if (event.subtype === 'init') {
+                    this.setStatus('connected');
+                }
+                break;
+            }
+            case 'assistant': {
+                const toolEvents = normalizeClaudeToolEvent(event);
+                if (toolEvents.length > 0) {
+                    toolEvents.forEach((toolEvent) => this.onToolEvent(toolEvent));
+                } else if (this.activeTools.size === 0) {
+                    this.setStatus('composing response…');
+                }
+                break;
+            }
+            case 'user': {
+                const toolEvents = normalizeClaudeToolEvent(event);
+                toolEvents.forEach((toolEvent) => this.onToolEvent(toolEvent));
+                break;
+            }
+            case 'result': {
+                this.settleResult(event, finish);
+                break;
+            }
+            // Ignore rate_limit_event and other non-UI events for v1
+            default:
+                break;
+        }
+    }
+}

package/lib/agent-cursor.js

@@ -0,0 +1,59 @@
+import { Agent } from './agent.js';
+import { normalizeCursorToolEvent } from './tool-status.js';
+
+export class AgentCursor extends Agent {
+    getSpawnConfig(promptToSend) {
+        const args = this.readOnly
+            ? ['-p', '--mode', 'ask', '--output-format', 'stream-json', promptToSend]
+            : ['-p', '--force', '--output-format', 'stream-json', promptToSend];
+        return {
+            command: 'agent',
+            args,
+            options: {
+                cwd: this.cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: process.env,
+            },
+        };
+    }
+
+    handleStreamEvent(event, { verbose, finish }) {
+        switch (event.type) {
+            case 'system': {
+                this.setStatus('connected');
+                break;
+            }
+            case 'thinking': {
+                switch (event.subtype) {
+                    case 'delta': {
+                        if (verbose) {
+                            process.stderr.write(event.text ?? '');
+                        } else if (this.activeTools.size === 0) {
+                            this.setStatus('thinking…');
+                        }
+                        break;
+                    }
+                    case 'completed': {
+                        break;
+                    }
+                }
+                break;
+            }
+            case 'tool_call': {
+                const toolEvent = normalizeCursorToolEvent(event);
+                if (toolEvent) this.onToolEvent(toolEvent);
+                break;
+            }
+            case 'assistant': {
+                if (this.activeTools.size === 0) {
+                    this.setStatus('composing response…');
+                }
+                break;
+            }
+            case 'result': {
+                this.settleResult(event, finish);
+                break;
+            }
+        }
+    }
+}

package/lib/agent.js

@@ -0,0 +1,326 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import ora from 'ora';
+import { formatActiveTools } from './tool-status.js';
+
+/**
+ * Every child process spawned by an agent, tracked so we can reap them all
+ * when the orchestrator is interrupted (Ctrl+C) or otherwise exits.
+ */
+const liveChildren = new Set();
+
+/**
+ * Terminate a child and everything it spawned. Children are launched
+ * `detached`, so each is its own process-group leader and `-pid` targets the
+ * whole group (agent CLI + any grandchildren). Falls back to killing just the
+ * child if the group is already gone.
+ */
+function killChildGroup(child, signal) {
+    try {
+        process.kill(-child.pid, signal);
+    } catch {
+        try {
+            child.kill(signal);
+        } catch {
+            // already dead
+        }
+    }
+}
+
+let shuttingDown = false;
+
+/** Conventional shell status: 128 + signal number. */
+export function exitCodeForSignal(signal) {
+    if (signal === 'SIGINT') return 130;
+    if (signal === 'SIGHUP') return 129;
+    return 143; // SIGTERM (and any other mapped interrupt)
+}
+
+/**
+ * Reap every tracked child group, then exit. `exit` is injectable so tests can
+ * assert without tearing down the runner.
+ */
+export function shutdown(signal, { exit = (code) => process.exit(code) } = {}) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    for (const child of liveChildren) killChildGroup(child, 'SIGTERM');
+
+    const exitCode = exitCodeForSignal(signal);
+
+    let poll;
+    // …or force-kill any stragglers after a short grace period.
+    const forceKill = setTimeout(() => {
+        clearInterval(poll);
+        for (const child of liveChildren) killChildGroup(child, 'SIGKILL');
+        exit(exitCode);
+    }, 2000);
+    forceKill.unref();
+
+    // Exit as soon as every child is gone…
+    poll = setInterval(() => {
+        if (liveChildren.size === 0) {
+            clearInterval(poll);
+            clearTimeout(forceKill);
+            exit(exitCode);
+        }
+    }, 50);
+}
+
+/** Track a child the way Agent.run does — for interrupt/reap tests. */
+export function trackLiveChild(child) {
+    liveChildren.add(child);
+    child.once('close', () => liveChildren.delete(child));
+    child.once('error', () => liveChildren.delete(child));
+}
+
+/** Reset shutdown latch + child set between tests. */
+export function resetShutdownState() {
+    shuttingDown = false;
+    liveChildren.clear();
+}
+
+/**
+ * Tracks whether the `model:` banner line has been printed yet. A shared,
+ * mutable object (rather than a plain flag) so tests can reset it between cases.
+ */
+export const modelPrintState = { printed: false };
+
+/**
+ * If `event` is the first `system`/`init` stream event carrying a `model`,
+ * print an aligned `model: <event.model>` line (pausing/resuming `spinner` so
+ * ora doesn't garble it) and latch `modelPrintState.printed`. No-op otherwise,
+ * including on every event after the first one printed.
+ */
+export function maybePrintModelLine(event, spinner) {
+    if (
+        modelPrintState.printed ||
+        event.type !== 'system' ||
+        event.subtype !== 'init' ||
+        typeof event.model !== 'string' ||
+        !event.model
+    ) {
+        return;
+    }
+    modelPrintState.printed = true;
+    const wasSpinning = spinner?.isSpinning;
+    if (wasSpinning) spinner.stop();
+    console.log(`model: ${event.model}`);
+    if (wasSpinning) spinner.start();
+}
+
+let handlersRegistered = false;
+
+function registerShutdownHandlers() {
+    if (handlersRegistered) return;
+    handlersRegistered = true;
+
+    process.once('SIGINT', () => shutdown('SIGINT'));
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+    process.once('SIGHUP', () => shutdown('SIGHUP'));
+    // Last-resort reap on any exit path we didn't handle explicitly.
+    process.on('exit', () => {
+        for (const child of liveChildren) killChildGroup(child, 'SIGKILL');
+    });
+}
+
+/** Format milliseconds as `{s}s` or `{m}m {s}s` (whole seconds, no leading 0m). */
+export function formatElapsed(ms) {
+    const totalSec = Math.floor(ms / 1000);
+    const m = Math.floor(totalSec / 60);
+    const s = totalSec % 60;
+    return m > 0 ? `${m}m ${s}s` : `${s}s`;
+}
+
+export class Agent {
+    constructor(name, instructions, prompt, { cwd, readOnly = false } = {}) {
+        this.name = name;
+        this.instructions = instructions;
+        this.prompt = prompt;
+        this.cwd = cwd ? path.resolve(cwd) : process.cwd();
+        this.readOnly = Boolean(readOnly);
+        this.process = null;
+        this.spinner = null;
+        this.startedAt = 0;
+        this.statusText = '';
+        this.elapsedTimer = null;
+        /** @type {Map<string, { name: string, args: Record<string, unknown> }>} */
+        this.activeTools = new Map();
+    }
+
+    setStatus(text) {
+        this.statusText = text;
+        this.refreshSpinnerText();
+    }
+
+    /** @param {{ name: string, args: Record<string, unknown>, phase: 'started'|'completed', callId: string }} toolEvent */
+    onToolEvent({ name, args, phase, callId }) {
+        if (phase === 'started') {
+            this.activeTools.set(callId, { name, args });
+        } else if (phase === 'completed') {
+            this.activeTools.delete(callId);
+        }
+        this.refreshToolStatus();
+    }
+
+    refreshToolStatus() {
+        if (this.activeTools.size === 0) {
+            this.setStatus('working…');
+            return;
+        }
+        this.setStatus(formatActiveTools(this.activeTools));
+    }
+
+    refreshSpinnerText() {
+        if (!this.spinner) return;
+        const elapsed = formatElapsed(Date.now() - this.startedAt);
+        this.spinner.text = `[${this.name}] ${this.statusText} · ${elapsed}`;
+    }
+
+    startElapsedTimer() {
+        this.stopElapsedTimer();
+        if (!process.stdout.isTTY) return;
+        this.elapsedTimer = setInterval(() => this.refreshSpinnerText(), 1000);
+    }
+
+    stopElapsedTimer() {
+        if (this.elapsedTimer != null) {
+            clearInterval(this.elapsedTimer);
+            this.elapsedTimer = null;
+        }
+    }
+
+    /** @returns {{ command: string, args: string[], options: object }} */
+    getSpawnConfig(_promptToSend) {
+        throw new Error('getSpawnConfig must be implemented by subclass');
+    }
+
+    /**
+     * @param {object} event
+     * @param {{ verbose: boolean, finish: (err: Error|null, value?: object) => void }} ctx
+     */
+    handleStreamEvent(_event, _ctx) {
+        throw new Error('handleStreamEvent must be implemented by subclass');
+    }
+
+    settleResult(event, finish) {
+        this.stopElapsedTimer();
+        this.activeTools.clear();
+        const ok = !event.is_error;
+        const durationMs = event.duration_ms;
+        this.ok = ok;
+        const elapsed = formatElapsed(Date.now() - this.startedAt);
+        const msg = ok
+            ? `[${this.name}] done in ${elapsed}`
+            : `[${this.name}] failed in ${elapsed}`;
+        if (ok) this.spinner.succeed(msg);
+        else this.spinner.fail(msg);
+        finish(null, { ok, result: event.result, durationMs });
+    }
+
+    async run({ verbose = false } = {}) {
+        const promptToSend = `
+            [SYSTEM INSTRUCTIONS]
+            ${this.instructions}
+            [/SYSTEM INSTRUCTIONS]
+
+            [USER PROMPT]
+            ${this.prompt}
+            [/USER PROMPT]
+        `;
+
+        registerShutdownHandlers();
+
+        const { command, args, options } = this.getSpawnConfig(promptToSend);
+        // `detached` makes the child its own process-group leader so we can kill
+        // it and any grandchildren it spawns as a group on shutdown.
+        this.process = spawn(command, args, { ...options, detached: true });
+        const child = this.process;
+        liveChildren.add(child);
+
+        this.startedAt = Date.now();
+        this.statusText = 'starting…';
+        // discardStdin: false keeps stdin cooked so Ctrl+C delivers a real SIGINT
+        // (ora's default raw-mode discarder swallows it in some IDEs / PTYs).
+        this.spinner = ora({
+            text: `[${this.name}] starting…`,
+            isEnabled: process.stdout.isTTY,
+            discardStdin: false,
+        }).start();
+        this.refreshSpinnerText();
+        this.startElapsedTimer();
+
+        let buf = '';
+        let settled = false;
+
+        return new Promise((resolve, reject) => {
+            const finish = (err, value) => {
+                if (settled) return;
+                settled = true;
+                if (err) reject(err);
+                else resolve(value);
+            };
+
+            this.process.stdout.on('data', (chunk) => {
+                buf += chunk;
+                const lines = buf.split('\n');
+                buf = lines.pop();
+
+                lines.forEach((line) => {
+                    if (!line.trim()) return;
+
+                    let event;
+                    try {
+                        event = JSON.parse(line);
+                    } catch {
+                        return;
+                    }
+
+                    if (process.env.ORCH_DEBUG) {
+                        process.stderr.write(JSON.stringify(event) + '\n');
+                    }
+
+                    maybePrintModelLine(event, this.spinner);
+
+                    this.handleStreamEvent(event, { verbose, finish });
+                });
+            });
+
+            this.process.on('error', (err) => {
+                liveChildren.delete(child);
+                this.process = null;
+                this.stopElapsedTimer();
+                if (this.spinner?.isSpinning) {
+                    this.spinner.fail(`[${this.name}] failed`);
+                }
+                finish(err);
+            });
+
+            this.process.on('close', (code) => {
+                liveChildren.delete(child);
+                this.process = null;
+                if (!settled) {
+                    this.stopElapsedTimer();
+                    if (this.spinner?.isSpinning) {
+                        this.spinner.fail(`[${this.name}] exited ${code}`);
+                    }
+                    finish(new Error(`[${this.name}] exited ${code} before result`));
+                }
+            });
+        });
+    }
+
+    async stop() {
+        if (!this.process) return;
+        const proc = this.process;
+        killChildGroup(proc, 'SIGTERM');
+        await new Promise((resolve) => proc.once('close', resolve));
+        liveChildren.delete(proc);
+        this.process = null;
+    }
+
+    async restart() {
+        this.stop();
+        this.run();
+    }
+}

package/lib/commit.js

@@ -0,0 +1,35 @@
+import { execFileSync as nodeExecFileSync } from 'node:child_process';
+
+function defaultExecFile(command, args, options = {}) {
+    return nodeExecFileSync(command, args, { encoding: 'utf8', ...options });
+}
+
+function runGit(execFile, args) {
+    try {
+        return execFile('git', args);
+    } catch (err) {
+        const detail = err.stderr || err.message;
+        throw new Error(`git ${args.join(' ')} failed: ${detail}`);
+    }
+}
+
+/**
+ * Commits all changes in a run's worktree as a single, deterministic commit
+ * owned by orch (never the agent). Skips committing when the tree is clean
+ * so no empty commit is created. Does not bypass hooks (`--no-verify`) and
+ * does not attempt destructive recovery (`reset`/`clean`) on failure;
+ * `execFile` is injectable and defaults to a `child_process.execFileSync`
+ * wrapper.
+ */
+export function commitWorktree({ worktreePath, branch, message, execFile = defaultExecFile }) {
+    const status = runGit(execFile, ['-C', worktreePath, 'status', '--porcelain']);
+    if (status.trim() === '') {
+        return { committed: false, sha: null, branch };
+    }
+
+    runGit(execFile, ['-C', worktreePath, 'add', '-A']);
+    runGit(execFile, ['-C', worktreePath, 'commit', '-m', message]);
+    const sha = runGit(execFile, ['-C', worktreePath, 'rev-parse', 'HEAD']).trim();
+
+    return { committed: true, sha, branch };
+}

package/lib/parse-triage-json.js

@@ -0,0 +1,33 @@
+/** Parse triage agent final message as JSON. Returns null on any failure. */
+export function parseTriageJson(result) {
+    if (typeof result !== 'string') return null;
+
+    const trimmed = result.trim();
+    if (!trimmed) return null;
+
+    const tryParse = (text) => {
+        try {
+            return JSON.parse(text);
+        } catch {
+            return null;
+        }
+    };
+
+    let parsed = tryParse(trimmed);
+    if (parsed && typeof parsed === 'object') return parsed;
+
+    const fenceMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fenceMatch) {
+        parsed = tryParse(fenceMatch[1].trim());
+        if (parsed && typeof parsed === 'object') return parsed;
+    }
+
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start !== -1 && end > start) {
+        parsed = tryParse(trimmed.slice(start, end + 1));
+        if (parsed && typeof parsed === 'object') return parsed;
+    }
+
+    return null;
+}

package/lib/parse-verdict.js

@@ -0,0 +1,25 @@
+import { parseTriageJson } from './parse-triage-json.js';
+
+const UNPARSEABLE = { passed: false, summary: 'unparseable verdict' };
+
+/**
+ * Parse a critic/runner final message as a pass/fail verdict.
+ * Reuses triage JSON extraction; requires `typeof passed === 'boolean'`.
+ */
+export function parseVerdict(result) {
+    const parsed = parseTriageJson(result);
+    if (!parsed || typeof parsed.passed !== 'boolean') {
+        return { ...UNPARSEABLE };
+    }
+
+    const verdict = {
+        passed: parsed.passed,
+        summary: typeof parsed.summary === 'string' ? parsed.summary : '',
+    };
+
+    if (Array.isArray(parsed.failures)) {
+        verdict.failures = parsed.failures;
+    }
+
+    return verdict;
+}

package/lib/run-context.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { generateSlug as defaultGenerateSlug } from './slug.js';
+
+/**
+ * Creates `<cwd>/.orch/<slug>/` for a new run and returns absolute paths to
+ * its artifacts. Retries with a fresh slug a bounded number of times if the
+ * generated directory already exists; throws once attempts are exhausted
+ * rather than reusing or repairing an existing directory.
+ */
+export function createRunContext({ cwd, generateSlug = defaultGenerateSlug, maxAttempts = 5 } = {}) {
+    const absCwd = path.resolve(cwd);
+    const orchDir = path.join(absCwd, '.orch');
+
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const slug = generateSlug();
+        const artifactDir = path.join(orchDir, slug);
+
+        if (fs.existsSync(artifactDir)) continue;
+
+        fs.mkdirSync(artifactDir, { recursive: true });
+
+        return {
+            slug,
+            artifactDir,
+            researchPath: path.join(artifactDir, 'research.md'),
+            taskPath: path.join(artifactDir, 'task.md'),
+            statusPath: path.join(artifactDir, 'status.md'),
+        };
+    }
+
+    throw new Error(`createRunContext: exhausted ${maxAttempts} attempts to allocate a unique run directory under ${orchDir}`);
+}

package/lib/slug.js

@@ -0,0 +1,47 @@
+import crypto from 'node:crypto';
+
+const ADJECTIVES = [
+    'calm', 'bright', 'quiet', 'brave', 'swift', 'gentle', 'bold', 'clever',
+    'eager', 'fuzzy', 'lively', 'merry', 'noble', 'plucky', 'quirky', 'rapid',
+    'sunny', 'tidy', 'vivid', 'wise',
+];
+
+const NOUNS = [
+    'otter', 'pine', 'falcon', 'meadow', 'harbor', 'ember', 'boulder', 'cedar',
+    'delta', 'forest', 'glacier', 'heron', 'island', 'jasper', 'kestrel',
+    'lagoon', 'marsh', 'nectar', 'oasis', 'pebble',
+];
+
+/** Pure formatter: joins the parts with hyphens, no normalization. */
+export function formatSlug(adjective, noun, hex) {
+    return `${adjective}-${noun}-${hex}`;
+}
+
+/** Default random source: uniform float in [0, 1), backed by node:crypto. */
+function defaultRandom() {
+    return crypto.randomBytes(4).readUInt32BE(0) / 0x100000000;
+}
+
+function pick(list, random) {
+    return list[Math.floor(random() * list.length)];
+}
+
+function randomHex(random) {
+    let hex = '';
+    for (let i = 0; i < 4; i += 1) {
+        hex += Math.floor(random() * 16).toString(16);
+    }
+    return hex;
+}
+
+/**
+ * Generates an `<adjective>-<noun>-<4-lowercase-hex>` slug. `random` follows
+ * the `Math.random()`-style `() => number in [0, 1)` contract and defaults to
+ * a node:crypto-backed source.
+ */
+export function generateSlug({ random = defaultRandom } = {}) {
+    const adjective = pick(ADJECTIVES, random);
+    const noun = pick(NOUNS, random);
+    const hex = randomHex(random);
+    return formatSlug(adjective, noun, hex);
+}

package/lib/stage-summary.js

@@ -0,0 +1,34 @@
+const SUMMARY_DELIMITER = '<<<SUMMARY>>>';
+
+/**
+ * Split a stage's final message into its required content and the optional
+ * natural-language summary paragraph appended after the last `<<<SUMMARY>>>`
+ * delimiter. Falls back to treating the whole input as content (with an
+ * empty summary) when the delimiter is absent or the input isn't a string,
+ * so older/unmodified agent output degrades gracefully instead of crashing.
+ */
+export function splitStageSummary(raw) {
+    if (typeof raw !== 'string') {
+        return { content: raw, summary: '' };
+    }
+
+    const idx = raw.lastIndexOf(SUMMARY_DELIMITER);
+    if (idx === -1) {
+        return { content: raw, summary: '' };
+    }
+
+    return {
+        content: raw.slice(0, idx).trim(),
+        summary: raw.slice(idx + SUMMARY_DELIMITER.length).trim(),
+    };
+}
+
+/**
+ * Print a blank line followed by `[label] summary: <summary>`. No-op when
+ * summary is empty so stages that return no summary don't print a broken line.
+ */
+export function printStageSummary(label, summary) {
+    if (!summary) return;
+    console.log();
+    console.log(`[${label}] summary: ${summary}`);
+}