@welluable/orch 1.2.0 → 1.4.0

package/lib/agent-cursor.js

@@ -1,4 +1,4 @@
-import { Agent } from './agent.js';
+import { Agent, appendVerbose } from './agent.js';
 import { normalizeCursorToolEvent } from './tool-status.js';
 
 export class AgentCursor extends Agent {
@@ -26,8 +26,10 @@ export class AgentCursor extends Agent {
             case 'thinking': {
                 switch (event.subtype) {
                     case 'delta': {
+                        const text = event.text ?? '';
+                        appendVerbose(text);
                         if (verbose) {
-                            process.stderr.write(event.text ?? '');
+                            process.stderr.write(text);
                         } else if (this.activeTools.size === 0) {
                             this.setStatus('thinking…');
                         }

package/lib/agent-opencode.js

@@ -0,0 +1,177 @@
+import { Agent, modelPrintState, appendVerbose } from './agent.js';
+import { normalizeOpencodeToolEvent } from './tool-status.js';
+
+const OPENCODE_DENY_PERMISSION = '{"edit":"deny","bash":"deny"}';
+
+export class AgentOpencode extends Agent {
+    #textBuffer = '';
+    #sawStepStart = false;
+    #pendingStop = false;
+    #settled = false;
+
+    getSpawnConfig(promptToSend) {
+        if (this.readOnly) {
+            return {
+                command: 'opencode',
+                args: ['run', '--format', 'json', '--auto', '--thinking', '--agent', 'plan', promptToSend],
+                options: {
+                    cwd: this.cwd,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    env: { ...process.env, OPENCODE_PERMISSION: OPENCODE_DENY_PERMISSION },
+                },
+            };
+        }
+
+        return {
+            command: 'opencode',
+            args: ['run', '--format', 'json', '--auto', '--thinking', promptToSend],
+            options: {
+                cwd: this.cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: process.env,
+            },
+        };
+    }
+
+    #printModelOnce(modelId) {
+        if (modelPrintState.printed || typeof modelId !== 'string' || !modelId) return;
+        modelPrintState.printed = true;
+        const wasSpinning = this.spinner?.isSpinning;
+        if (wasSpinning) this.spinner.stop?.();
+        console.log(`model: ${modelId}`);
+        if (wasSpinning) this.spinner.start?.();
+    }
+
+    #printUsageLine(part) {
+        const tokens = part?.tokens;
+        if (!tokens || typeof tokens !== 'object') return;
+        const input = tokens.input ?? tokens.in;
+        const output = tokens.output ?? tokens.out;
+        if (typeof input !== 'number' && typeof output !== 'number') return;
+
+        let line = `  tokens: in=${input ?? 0} out=${output ?? 0}`;
+        const cost = part.cost;
+        if (typeof cost === 'number' && cost > 0) {
+            line += ` · cost=$${cost}`;
+        }
+        process.stderr.write(`${line}\n`);
+    }
+
+    #settleOk(finish, { verbose = false, part = null } = {}) {
+        if (this.#settled) return;
+        this.#settled = true;
+        this.#pendingStop = false;
+        this.settleResult(
+            {
+                is_error: false,
+                result: this.#textBuffer,
+                duration_ms: undefined,
+            },
+            finish,
+        );
+        if (verbose && part) this.#printUsageLine(part);
+    }
+
+    #recordApplyPatchFiles(toolEvent) {
+        if (toolEvent.name !== 'apply_patch' || !this.fileTracker) return;
+        const entries = this.fileTracker.recordApplyPatch(toolEvent.args?.patchText);
+        for (const entry of entries) {
+            if (!entry.isNew) continue;
+            const wasSpinning = this.spinner?.isSpinning;
+            if (wasSpinning) this.spinner.stop();
+            console.log(`  ${entry.marker} ${entry.path}`);
+            if (wasSpinning) this.spinner.start();
+            this.onFileChange?.(entry);
+        }
+    }
+
+    handleStreamEvent(event, { verbose, finish }) {
+        switch (event.type) {
+            case 'message.updated': {
+                this.#printModelOnce(event.properties?.info?.modelID);
+                break;
+            }
+            case 'step_start': {
+                if (!this.#sawStepStart) {
+                    this.#sawStepStart = true;
+                    this.setStatus('connected');
+                } else if (this.activeTools.size === 0) {
+                    this.setStatus('thinking…');
+                }
+                break;
+            }
+            case 'tool_use': {
+                const toolEvent = normalizeOpencodeToolEvent(event);
+                if (!toolEvent) break;
+                this.onToolEvent({ ...toolEvent, phase: 'started' });
+                this.onToolEvent(toolEvent);
+                this.#recordApplyPatchFiles(toolEvent);
+                break;
+            }
+            case 'reasoning': {
+                const text = event.part?.text ?? '';
+                appendVerbose(text);
+                if (verbose) {
+                    process.stderr.write(text);
+                } else if (this.activeTools.size === 0) {
+                    this.setStatus('thinking…');
+                }
+                break;
+            }
+            case 'text': {
+                const text = event.part?.text ?? '';
+                this.#textBuffer += text;
+                appendVerbose(text);
+                if (verbose) {
+                    process.stderr.write(text);
+                } else if (this.activeTools.size === 0) {
+                    this.setStatus('composing response…');
+                }
+                if (this.#pendingStop && this.#textBuffer !== '') {
+                    this.#settleOk(finish, { verbose });
+                }
+                break;
+            }
+            case 'step_finish': {
+                const reason = event.part?.reason;
+                if (reason === 'tool-calls') break;
+                if (reason === 'stop' || reason == null) {
+                    if (this.#textBuffer !== '') {
+                        this.#settleOk(finish, { verbose, part: event.part });
+                    } else {
+                        this.#pendingStop = true;
+                    }
+                }
+                break;
+            }
+            case 'error': {
+                if (this.#settled) break;
+                this.#settled = true;
+                this.#pendingStop = false;
+                const message =
+                    event.error?.data?.message ||
+                    event.error?.name ||
+                    'OpenCode error';
+                this.settleResult(
+                    {
+                        is_error: true,
+                        result: message,
+                    },
+                    finish,
+                );
+                break;
+            }
+            default:
+                break;
+        }
+    }
+
+    handleProcessClose(code, finish) {
+        if (this.#settled) return;
+        if (code === 0 && this.#textBuffer !== '') {
+            this.#settleOk(finish);
+            return;
+        }
+        super.handleProcessClose(code, finish);
+    }
+}

package/lib/agent.js

@@ -1,8 +1,13 @@
 import { spawn } from 'child_process';
 import path from 'path';
 import ora from 'ora';
-import { formatActiveTools } from './tool-status.js';
-import { patchJob } from './jobs.js';
+import { formatActiveTools, toolPath } from './tool-status.js';
+import { patchJob, buildLastOutcome, jobPaths, readJob } from './jobs.js';
+import {
+    appendFailureLog,
+    failureLogPointer,
+    formatFailureSection,
+} from './failure-log.js';
 
 /**
  * Every child process spawned by an agent, tracked so we can reap them all
@@ -43,6 +48,116 @@ export function setJobSlug(slug) {
     activeJobSlug = slug;
 }
 
+/** Active job slug: env (detached child) wins over in-process foreground slug. */
+export function getActiveJobSlug() {
+    return process.env.ORCH_JOB_SLUG ?? activeJobSlug;
+}
+
+/** Current stage capture + prior-stage ring for failure.log (independent of -v). */
+let currentCapture = null;
+/** @type {{ phase: *, stage: *, round: *, verbose: string }[]} */
+let priorCaptures = [];
+const PRIOR_RING_MAX = 8;
+
+/** Clear failure-log buffers (also invoked from `resetShutdownState`). */
+export function resetFailureLogState() {
+    currentCapture = null;
+    priorCaptures = [];
+}
+
+/**
+ * Start capturing verbose for a stage. Rotates a non-empty current buffer into
+ * the prior-stage ring so recover can see more than the final frame.
+ */
+export function beginStageCapture({ phase = null, stage = null, round = null } = {}) {
+    if (currentCapture && currentCapture.verbose) {
+        priorCaptures.push({
+            phase: currentCapture.phase,
+            stage: currentCapture.stage,
+            round: currentCapture.round,
+            verbose: currentCapture.verbose,
+        });
+        if (priorCaptures.length > PRIOR_RING_MAX) {
+            priorCaptures.splice(0, priorCaptures.length - PRIOR_RING_MAX);
+        }
+    }
+    currentCapture = { phase, stage, round, verbose: '' };
+}
+
+/**
+ * Append a verbose chunk when a job slug is active. Never gated on `-v`
+ * (stderr streaming stays verbose-gated in the backends).
+ */
+export function appendVerbose(chunk) {
+    if (!getActiveJobSlug()) return;
+    if (chunk == null || chunk === '') return;
+    if (!currentCapture) {
+        currentCapture = { phase: null, stage: null, round: null, verbose: '' };
+    }
+    currentCapture.verbose += String(chunk);
+}
+
+/**
+ * Append one `=== orch failure ===` section to `.orch/<slug>/failure.log`,
+ * patch `run.json.failureLogPath`, and return a pointer string. No-op when
+ * `slug` is falsy.
+ */
+export function flushFailureLog({
+    cwd,
+    slug,
+    state,
+    exitCode = null,
+    finishedAt,
+    task = null,
+    error = null,
+} = {}) {
+    if (!slug) return null;
+
+    const resolvedCwd = cwd ?? process.cwd();
+    let phase = currentCapture?.phase ?? null;
+    let stage = currentCapture?.stage ?? null;
+    let round = currentCapture?.round ?? null;
+    let resolvedTask = task;
+
+    if (phase == null || stage == null || round == null || resolvedTask == null) {
+        try {
+            const record = readJob(resolvedCwd, slug);
+            if (record) {
+                if (phase == null) phase = record.phase ?? null;
+                if (stage == null) stage = record.stage ?? null;
+                if (round == null) round = record.round ?? null;
+                if (resolvedTask == null) resolvedTask = record.task ?? null;
+            }
+        } catch {
+            // Best-effort cursor fill from run.json.
+        }
+    }
+
+    const { failureLogPath } = jobPaths(resolvedCwd, slug);
+    const section = formatFailureSection({
+        slug,
+        state,
+        phase,
+        stage,
+        round,
+        exitCode,
+        finishedAt,
+        task: resolvedTask,
+        error,
+        stageVerbose: currentCapture?.verbose ?? '',
+        priorStages: priorCaptures,
+    });
+    appendFailureLog(failureLogPath, section);
+
+    try {
+        patchJob(resolvedCwd, slug, { failureLogPath });
+    } catch {
+        // Best-effort: file is already on disk even if the patch fails.
+    }
+
+    return failureLogPointer(slug);
+}
+
 /** Conventional shell status: 128 + signal number. */
 export function exitCodeForSignal(signal) {
     if (signal === 'SIGINT') return 130;
@@ -67,11 +182,32 @@ export function shutdown(signal, { exit = (code) => process.exit(code), jobCwd =
     const jobSlug = process.env.ORCH_JOB_SLUG ?? activeJobSlug;
     if (jobSlug) {
         try {
-            patchJob(jobCwd, jobSlug, {
+            const exitCode = exitCodeForSignal(signal);
+            const finishedAt = new Date().toISOString();
+            const pointer = flushFailureLog({
+                cwd: jobCwd,
+                slug: jobSlug,
                 state: 'stopped',
-                exitCode: exitCodeForSignal(signal),
-                finishedAt: new Date().toISOString(),
+                exitCode,
+                finishedAt,
+                error: signal,
             });
+            patchJob(jobCwd, jobSlug, (current) => ({
+                state: 'stopped',
+                exitCode,
+                finishedAt,
+                lastOutcome: buildLastOutcome({
+                    state: 'stopped',
+                    phase: current.phase,
+                    stage: current.stage,
+                    round: current.round,
+                    exitCode,
+                    finishedAt,
+                    task: current.task,
+                    summary: '',
+                    error: pointer,
+                }),
+            }));
         } catch {
             // Best-effort: don't let a job-state write failure block shutdown.
         }
@@ -112,6 +248,7 @@ export function resetShutdownState() {
     shuttingDown = false;
     liveChildren.clear();
     activeJobSlug = null;
+    resetFailureLogState();
 }
 
 /**
@@ -196,10 +333,14 @@ export class Agent {
         this.refreshSpinnerText();
     }
 
-    /** @param {{ name: string, args: Record<string, unknown>, phase: 'started'|'completed', callId: string }} toolEvent */
-    onToolEvent({ name, args, phase, callId }) {
+    /** @param {{ name: string, args: Record<string, unknown>, phase: 'started'|'completed', callId: string, title?: string }} toolEvent */
+    onToolEvent({ name, args, phase, callId, title }) {
         if (phase === 'started') {
-            this.activeTools.set(callId, { name, args });
+            this.activeTools.set(callId, {
+                name,
+                args,
+                ...(typeof title === 'string' && title ? { title } : {}),
+            });
             this.fileTracker?.record({ name, args, phase, callId });
         } else if (phase === 'completed') {
             // Recall before delete — Claude/agn completions often have empty args.
@@ -207,7 +348,7 @@ export class Agent {
             this.activeTools.delete(callId);
 
             if (this.fileTracker) {
-                const hasPath = Boolean(args?.path || args?.file_path);
+                const hasPath = Boolean(toolPath(args));
                 const entry = this.fileTracker.record({
                     name: name || prior?.name || '',
                     args: hasPath ? args : (prior?.args ?? args ?? {}),
@@ -266,6 +407,20 @@ export class Agent {
         throw new Error('handleStreamEvent must be implemented by subclass');
     }
 
+    /**
+     * Called when the child exits before a settling stream event.
+     * Subclasses may override (e.g. defensive success on exit 0 + buffered text).
+     * @param {number|null} code
+     * @param {(err: Error|null, value?: object) => void} finish
+     */
+    handleProcessClose(code, finish) {
+        this.stopElapsedTimer();
+        if (this.spinner?.isSpinning) {
+            this.spinner.fail(`[${this.name}] exited ${code}`);
+        }
+        finish(new Error(`[${this.name}] exited ${code} before result`));
+    }
+
     settleResult(event, finish) {
         this.stopElapsedTimer();
         this.activeTools.clear();
@@ -363,11 +518,7 @@ export class Agent {
                 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`));
+                    this.handleProcessClose(code, finish);
                 }
             });
         });

package/lib/config.js

@@ -0,0 +1,190 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const VALID_AGENTS = new Set(['cursor', 'claude', 'agn', 'opencode']);
+
+/** Absolute path to the global orch config file. */
+export function globalConfigPath({ homedir = os.homedir() } = {}) {
+    return path.join(homedir, '.orch', 'config');
+}
+
+/** Absolute path to the project-local orch config file under `cwd`. */
+export function localConfigPath(cwd) {
+    return path.join(cwd, '.orch', 'config');
+}
+
+/**
+ * Read a config file. Missing file → `{}`. Bad JSON, unreadable file, or
+ * invalid `agent` / `notify` → throws with a message suitable for `Error: …`
+ * on stderr. Unknown keys are ignored; `agent` is case-sensitive.
+ */
+export function loadConfig(configPath, displayPath = configPath) {
+    if (!fs.existsSync(configPath)) return {};
+
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, 'utf8');
+    } catch (err) {
+        throw new Error(`could not parse ${displayPath}: ${err.message}`);
+    }
+
+    let data;
+    try {
+        data = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(`could not parse ${displayPath}: ${err.message}`);
+    }
+
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        throw new Error(`could not parse ${displayPath}: expected a JSON object`);
+    }
+
+    const out = {};
+
+    if (Object.prototype.hasOwnProperty.call(data, 'agent') && data.agent !== undefined) {
+        if (!VALID_AGENTS.has(data.agent)) {
+            throw new Error(
+                `invalid agent in ${displayPath}: ${JSON.stringify(data.agent)} (expected "cursor", "claude", "agn", or "opencode")`,
+            );
+        }
+        out.agent = data.agent;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(data, 'notify') && data.notify !== undefined) {
+        if (typeof data.notify !== 'boolean') {
+            throw new Error(
+                `invalid notify in ${displayPath}: ${JSON.stringify(data.notify)} (expected true or false)`,
+            );
+        }
+        out.notify = data.notify;
+    }
+
+    return out;
+}
+
+/**
+ * Effective agent for a run: `--agent` > local > global > `cursor`.
+ * Reads local then global when `cliAgent` is omitted; throws on bad files.
+ */
+export function resolveAgent({ cliAgent, cwd, homedir = os.homedir() } = {}) {
+    if (cliAgent) return cliAgent;
+
+    const local = loadConfig(localConfigPath(cwd), '.orch/config');
+    if (local.agent) return local.agent;
+
+    const global = loadConfig(globalConfigPath({ homedir }), '~/.orch/config');
+    if (global.agent) return global.agent;
+
+    return 'cursor';
+}
+
+/**
+ * Effective notify for a run: CLI > local > global > `true`.
+ * `cliNotify` is `true` | `false` | `undefined` (flag omitted).
+ */
+export function resolveNotify({ cliNotify, cwd, homedir = os.homedir() } = {}) {
+    if (cliNotify === true || cliNotify === false) return cliNotify;
+
+    const local = loadConfig(localConfigPath(cwd), '.orch/config');
+    if (typeof local.notify === 'boolean') return local.notify;
+
+    const global = loadConfig(globalConfigPath({ homedir }), '~/.orch/config');
+    if (typeof global.notify === 'boolean') return global.notify;
+
+    return true;
+}
+
+/**
+ * Create parent dirs if needed, merge `agent` / `notify` into the existing
+ * config object (preserve the other key), overwrite with pretty-printed JSON,
+ * return the path written.
+ */
+export function writeConfig(configPath, { agent, notify } = {}) {
+    if (agent !== undefined && !VALID_AGENTS.has(agent)) {
+        throw new Error(
+            `invalid agent: ${JSON.stringify(agent)} (expected "cursor", "claude", "agn", or "opencode")`,
+        );
+    }
+    if (notify !== undefined && typeof notify !== 'boolean') {
+        throw new Error(
+            `invalid notify: ${JSON.stringify(notify)} (expected true or false)`,
+        );
+    }
+
+    let existing = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+                existing = raw;
+            }
+        } catch {
+            // Corrupt file: start fresh; caller already validated inputs.
+            existing = {};
+        }
+    }
+
+    const next = { ...existing };
+    if (agent !== undefined) next.agent = agent;
+    if (notify !== undefined) next.notify = notify;
+
+    // Persist only known keys (drop unknown junk from a prior merge? Spec says
+    // unknown keys are ignored on load but does not require stripping on write.
+    // Keep agent/notify; preserve other keys already present.)
+    const out = {};
+    if (next.agent !== undefined) out.agent = next.agent;
+    if (next.notify !== undefined) out.notify = next.notify;
+    for (const [k, v] of Object.entries(next)) {
+        if (k === 'agent' || k === 'notify') continue;
+        out[k] = v;
+    }
+
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, `${JSON.stringify(out, null, 2)}\n`);
+    return configPath;
+}
+
+/**
+ * Print effective agent/notify and which file(s) contributed (stdout). Throws
+ * on invalid existing files — same fail-fast contract as a run.
+ */
+export function printConfig({
+    cwd,
+    homedir = os.homedir(),
+    log = console.log,
+} = {}) {
+    const localPath = localConfigPath(cwd);
+    const globalPath = globalConfigPath({ homedir });
+    const local = loadConfig(localPath, '.orch/config');
+    const global = loadConfig(globalPath, '~/.orch/config');
+
+    let agent = 'cursor';
+    let source = 'default (builtin)';
+    if (local.agent) {
+        agent = local.agent;
+        source = `local (${localPath})`;
+    } else if (global.agent) {
+        agent = global.agent;
+        source = `global (${globalPath})`;
+    }
+
+    let notify = true;
+    let notifySource = 'default (builtin)';
+    if (typeof local.notify === 'boolean') {
+        notify = local.notify;
+        notifySource = `local (${localPath})`;
+    } else if (typeof global.notify === 'boolean') {
+        notify = global.notify;
+        notifySource = `global (${globalPath})`;
+    }
+
+    log(`agent=${agent}`);
+    log(`source=${source}`);
+    log(`global=${global.agent ?? 'unset'} (${globalPath})`);
+    log(`local=${local.agent ?? 'unset'} (${localPath})`);
+    log(`notify=${notify}`);
+    log(`notifySource=${notifySource}`);
+    log(`notifyGlobal=${typeof global.notify === 'boolean' ? global.notify : 'unset'} (${globalPath})`);
+    log(`notifyLocal=${typeof local.notify === 'boolean' ? local.notify : 'unset'} (${localPath})`);
+}