@xdelivered/emberflow 0.2.0

package/dist/server/agents/claudeParse.js

@@ -0,0 +1,162 @@
+/** Best-effort extraction of a shell command from a Bash tool_use input. */
+function bashCommandFrom(block) {
+    const input = block.input;
+    if (!input)
+        return undefined;
+    const command = input.command;
+    return typeof command === 'string' ? command : undefined;
+}
+/** Fallback label for a tool whose input we don't format specially (or that's
+ *  missing its expected field): `<name> <compact-json>` capped at 80 chars. */
+function compactLabel(name, input) {
+    const json = JSON.stringify(input ?? {});
+    return `${name} ${json.length > 80 ? json.slice(0, 80) : json}`;
+}
+/**
+ * Human label for a non-mcp tool_use block, used as a `command` event's
+ * `command` string so Read/Edit/Grep/… fold into the UI's "Ran N commands"
+ * group instead of leaking as reasoning prose. Bash keeps its raw shell command;
+ * the common Claude tools get a purpose-built one-liner; anything else gets the
+ * compact `<name> <json>` fallback.
+ */
+function commandLabelFor(block) {
+    const name = block.name ?? 'tool';
+    const input = (block.input ?? {});
+    const str = (v) => (typeof v === 'string' ? v : undefined);
+    switch (name) {
+        case 'Bash':
+            return bashCommandFrom(block) ?? compactLabel(name, input);
+        case 'Read': {
+            const fp = str(input.file_path);
+            if (!fp)
+                return compactLabel(name, input);
+            const bits = [];
+            if (typeof input.offset === 'number')
+                bits.push(`offset ${input.offset}`);
+            if (typeof input.limit === 'number')
+                bits.push(`limit ${input.limit}`);
+            return `Read ${fp}${bits.length ? ` (${bits.join(', ')})` : ''}`;
+        }
+        case 'Edit':
+        case 'Write': {
+            const fp = str(input.file_path);
+            return fp ? `${name} ${fp}` : compactLabel(name, input);
+        }
+        case 'Grep': {
+            const pattern = str(input.pattern);
+            if (!pattern)
+                return compactLabel(name, input);
+            const path = str(input.path);
+            return `Grep ${pattern}${path ? ` ${path}` : ''}`;
+        }
+        case 'Glob': {
+            const pattern = str(input.pattern);
+            return pattern ? `Glob ${pattern}` : compactLabel(name, input);
+        }
+        case 'TodoWrite':
+            return 'update todos';
+        default:
+            return compactLabel(name, input);
+    }
+}
+/** Flattens a tool_result's `content` (string, or array of text blocks) to plain text. */
+function toolResultTextFrom(block) {
+    const content = block.content;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((c) => c.type === 'text' && typeof c.text === 'string')
+            .map((c) => c.text)
+            .join('');
+    }
+    return '';
+}
+export function parseClaudeLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return [];
+    }
+    switch (parsed.type) {
+        case 'system': {
+            if (parsed.subtype === 'init')
+                return [{ type: 'started' }];
+            // hook_started / hook_response and any other system noise — ignore.
+            return [];
+        }
+        case 'assistant': {
+            const blocks = parsed.message?.content ?? [];
+            // Claude routinely emits multiple content blocks per message (e.g.
+            // explain-then-call `[text, tool_use]`, or parallel tool calls) — emit
+            // one AgentEvent per meaningful block, in order, so the console shows the
+            // full picture. `thinking` and other block types are skipped.
+            const events = [];
+            for (const block of blocks) {
+                if (block.type === 'text' && block.text) {
+                    events.push({ type: 'message', text: block.text });
+                }
+                else if (block.type === 'tool_use') {
+                    // MCP tools surface as `mcp__<server>__<tool>` — show them as MCP calls.
+                    if (block.name?.startsWith('mcp__')) {
+                        const [, server, ...toolParts] = block.name.split('__');
+                        events.push({
+                            type: 'mcp',
+                            mcpServer: server || 'mcp',
+                            mcpTool: toolParts.join('__') || 'tool',
+                            mcpStatus: 'in_progress',
+                            ...(block.id ? { toolUseId: block.id } : {}),
+                        });
+                        continue;
+                    }
+                    // Every other tool (Bash, Read, Edit, Grep, Glob, TodoWrite, …) is a
+                    // `command` event with a human label, correlated by tool_use_id like
+                    // Bash always was — so it folds into the UI's "Ran N commands" group
+                    // instead of leaking as reasoning prose.
+                    events.push({
+                        type: 'command',
+                        command: commandLabelFor(block),
+                        commandStatus: 'in_progress',
+                        ...(block.id ? { toolUseId: block.id } : {}),
+                    });
+                }
+            }
+            return events;
+        }
+        case 'user': {
+            // Tool results. Emit a partial completion carrying the tool_use_id +
+            // output text + status; the adapter looks up the original command text
+            // by id (it isn't repeated in the tool_result line) and skips gracefully
+            // if the id doesn't correspond to a command it's tracking (e.g. a
+            // non-Bash tool result).
+            const blocks = parsed.message?.content ?? [];
+            const events = [];
+            for (const block of blocks) {
+                if (block.type === 'tool_result' && block.tool_use_id) {
+                    events.push({
+                        type: 'command',
+                        toolUseId: block.tool_use_id,
+                        commandStatus: block.is_error ? 'failed' : 'completed',
+                        output: toolResultTextFrom(block),
+                    });
+                }
+            }
+            return events;
+        }
+        case 'result': {
+            if (parsed.subtype === 'error' || parsed.is_error) {
+                return [{ type: 'error', text: parsed.result ?? 'error' }];
+            }
+            return [{ type: 'done', usage: parsed.usage }];
+        }
+        case 'rate_limit_event':
+            return [];
+        default:
+            return [];
+    }
+}

package/dist/server/agents/codexAdapter.d.ts

@@ -0,0 +1,13 @@
+import type { AgentEvent } from './types.js';
+export interface SpawnedAgent {
+    events: AsyncIterable<AgentEvent>;
+    cancel(): void;
+}
+export interface CodexOptions {
+    model?: string;
+    reasoning?: 'low' | 'medium' | 'high';
+    bin?: string;
+    /** Grace period (ms) between SIGTERM and the SIGKILL escalation in cancel(). Test hook. */
+    killGraceMs?: number;
+}
+export declare function spawnCodex(prompt: string, projectDir: string, opts?: CodexOptions): SpawnedAgent;

package/dist/server/agents/codexAdapter.js

@@ -0,0 +1,174 @@
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+import { parseCodexLine } from './codexParse.js';
+import { modelRejectionHint } from './modelRejectionHint.js';
+const STDERR_TAIL_BYTES = 2048;
+export function spawnCodex(prompt, projectDir, opts = {}) {
+    const bin = opts.bin ?? 'codex';
+    const args = [
+        // Never ask for per-call approval — the studio runs codex non-interactively,
+        // so an approval prompt has no one to answer it and codex cancels the call
+        // ("user cancelled MCP tool call"). This is a top-level flag (before `exec`).
+        // The sandbox (-s workspace-write, below) still constrains what can run.
+        '-a',
+        'never',
+        'exec',
+        '-C',
+        projectDir,
+        '-s',
+        'workspace-write',
+        // Keep the workspace-write FILE sandbox, but allow network — the agent's CLI
+        // ops (node bin/emberflow.mjs run/get-workflow/…) must reach the runner on
+        // 127.0.0.1; workspace-write blocks all network by default (curl → 000).
+        '-c',
+        'sandbox_workspace_write.network_access=true',
+        '-c',
+        `model_reasoning_effort=${opts.reasoning ?? 'low'}`,
+        '--json',
+        ...(opts.model ? ['-m', opts.model] : []),
+        prompt,
+    ];
+    // detached: give codex its own process group so cancel() can tree-kill any
+    // subprocesses it spawns (workspace-write), not just the top-level process.
+    // stdio ['ignore','pipe','pipe'] → stdin is null, stdout/stderr are Readable.
+    const child = bin.endsWith('.mjs')
+        ? spawn(process.execPath, [bin, ...args], { stdio: ['ignore', 'pipe', 'pipe'], detached: true })
+        : spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+    // Buffer only the last ~2KB of stderr — non-fatal in general (e.g. the user's
+    // global MCP servers spew auth errors there), but useful as a diagnostic tail
+    // when the process dies without a terminal event (see maybeFinalize below).
+    let stderrTail = '';
+    child.stderr.on('data', (chunk) => {
+        stderrTail = (stderrTail + chunk.toString('utf8')).slice(-STDERR_TAIL_BYTES);
+    });
+    const queue = [];
+    const resolvers = [];
+    let done = false;
+    let sawTerminal = false;
+    function push(event) {
+        queue.push(event);
+        const resolve = resolvers.shift();
+        if (resolve)
+            resolve();
+    }
+    function finish() {
+        done = true;
+        while (resolvers.length) {
+            const resolve = resolvers.shift();
+            if (resolve)
+                resolve();
+        }
+    }
+    const rl = readline.createInterface({ input: child.stdout });
+    rl.on('line', (line) => {
+        const event = parseCodexLine(line);
+        if (event) {
+            if (event.type === 'done' || event.type === 'error')
+                sawTerminal = true;
+            push(event);
+        }
+    });
+    // Finalize only once BOTH the stdout stream is fully drained (readline 'close')
+    // AND the process has exited ('close', which fires after all stdio is flushed —
+    // unlike 'exit', which can fire while trailing stdout lines are still buffered).
+    let rlClosed = false;
+    let procClosed = false;
+    let exitCode = null;
+    let escalateTimer;
+    function clearEscalation() {
+        if (escalateTimer) {
+            clearTimeout(escalateTimer);
+            escalateTimer = undefined;
+        }
+    }
+    function maybeFinalize() {
+        if (!rlClosed || !procClosed)
+            return;
+        clearEscalation();
+        if (!sawTerminal) {
+            if (exitCode === 0) {
+                // Clean exit but the model never emitted turn.completed — synthesize a done.
+                push({ type: 'done' });
+            }
+            else {
+                const hint = modelRejectionHint('codex', stderrTail);
+                const text = hint ? `codex exited with code ${exitCode} (${hint})` : `codex exited with code ${exitCode}`;
+                push({ type: 'error', text });
+            }
+            sawTerminal = true;
+        }
+        finish();
+    }
+    rl.on('close', () => {
+        rlClosed = true;
+        maybeFinalize();
+    });
+    child.on('close', (code) => {
+        procClosed = true;
+        exitCode = code;
+        maybeFinalize();
+    });
+    // A failed spawn (missing binary, bad EMBERFLOW_*_BIN, permissions, ...) emits
+    // an 'error' event on the child instead of ever exiting/closing normally. Left
+    // unhandled, Node rethrows it and crashes the whole runner process — so we
+    // must handle it and finalize the stream ourselves. 'close' still fires after
+    // a spawn error (with code null), so guard against double-finalizing there.
+    let spawnFailed = false;
+    child.on('error', (err) => {
+        if (spawnFailed)
+            return;
+        spawnFailed = true;
+        clearEscalation();
+        push({ type: 'error', text: `failed to start codex: ${err.message}` });
+        sawTerminal = true;
+        rlClosed = true;
+        procClosed = true;
+        finish();
+    });
+    async function* generate() {
+        while (true) {
+            if (queue.length > 0) {
+                yield queue.shift();
+                continue;
+            }
+            if (done)
+                return;
+            await new Promise((resolve) => resolvers.push(resolve));
+        }
+    }
+    // Kill the whole process group (negative pid) so codex's own subprocesses die
+    // too; fall back to a plain kill if the group signal fails (e.g. already gone
+    // or no group). Used by both the initial SIGTERM and the SIGKILL escalation.
+    function killGroup(signal) {
+        try {
+            if (child.pid != null) {
+                process.kill(-child.pid, signal);
+                return;
+            }
+        }
+        catch {
+            // group kill failed — fall through to a direct kill
+        }
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // process already gone — nothing to do
+        }
+    }
+    return {
+        events: { [Symbol.asyncIterator]: generate },
+        cancel() {
+            killGroup('SIGTERM');
+            // If the process (or a stubborn grandchild/MCP server) ignores SIGTERM,
+            // escalate to SIGKILL after a grace period so a hung agent can't
+            // permanently lock the run slot. Cleared once close/error finalizes.
+            clearEscalation();
+            escalateTimer = setTimeout(() => {
+                escalateTimer = undefined;
+                killGroup('SIGKILL');
+            }, opts.killGraceMs ?? 3000);
+            escalateTimer.unref?.();
+        },
+    };
+}

package/dist/server/agents/codexParse.d.ts

@@ -0,0 +1,2 @@
+import type { AgentEvent } from './types.js';
+export declare function parseCodexLine(line: string): AgentEvent | null;

package/dist/server/agents/codexParse.js

@@ -0,0 +1,74 @@
+/** Map a codex mcp_tool_call item → an 'mcp' AgentEvent, tolerating shape drift. */
+function mcpEventFrom(item) {
+    const server = item.server ?? item.invocation?.server ?? 'mcp';
+    const tool = item.tool ?? item.name ?? item.invocation?.tool ?? 'tool';
+    const raw = item.error ?? item.result ?? item.output;
+    const output = raw === undefined ? undefined : typeof raw === 'string' ? raw : JSON.stringify(raw, null, 2);
+    return { type: 'mcp', mcpServer: server, mcpTool: tool, mcpStatus: item.status, ...(output !== undefined ? { output } : {}) };
+}
+export function parseCodexLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    switch (parsed.type) {
+        case 'thread.started':
+        case 'turn.started':
+            return { type: 'started' };
+        case 'item.started': {
+            const item = parsed.item;
+            if (item && item.type === 'command_execution') {
+                const commandItem = item;
+                return {
+                    type: 'command',
+                    command: commandItem.command,
+                    commandStatus: commandItem.status,
+                };
+            }
+            if (item && item.type === 'mcp_tool_call')
+                return mcpEventFrom(item);
+            return null;
+        }
+        case 'item.completed': {
+            const item = parsed.item;
+            if (!item)
+                return null;
+            if (item.type === 'command_execution') {
+                const commandItem = item;
+                return {
+                    type: 'command',
+                    command: commandItem.command,
+                    exitCode: commandItem.exit_code,
+                    output: commandItem.aggregated_output,
+                    commandStatus: commandItem.status,
+                };
+            }
+            if (item.type === 'mcp_tool_call')
+                return mcpEventFrom(item);
+            if (item.type === 'agent_message') {
+                const messageItem = item;
+                return { type: 'message', text: messageItem.text };
+            }
+            if (item.type === 'error') {
+                // A codex `error` ITEM is a non-fatal diagnostic (e.g. an MCP server
+                // failing to auth) — NOT the run failing. Surface it as a message so it
+                // stays visible without terminating the run. A real failure is signalled
+                // by the process exiting non-zero with no `done` (see codexAdapter),
+                // which is the ONLY thing that yields a terminal AgentEvent 'error'.
+                const errorItem = item;
+                return { type: 'message', text: `⚠ ${errorItem.text ?? errorItem.message ?? 'error'}` };
+            }
+            return null;
+        }
+        case 'turn.completed':
+            return { type: 'done', usage: parsed.usage };
+        default:
+            return null;
+    }
+}

package/dist/server/agents/detect.d.ts

@@ -0,0 +1,23 @@
+import type { AgentKind } from './types.js';
+export interface DetectedAgent {
+    kind: AgentKind;
+    version: string | null;
+}
+/**
+ * Real PATH probe: runs `<bin> --version` and parses the first semver-ish
+ * token out of stdout. Returns `undefined` when the binary isn't present/
+ * runnable (spawn error, timeout, or nonzero exit); `null` version when it
+ * ran but produced no parseable version string.
+ */
+export declare function probe(bin: string): {
+    version: string | null;
+} | undefined;
+/**
+ * Detects which coding-agent CLIs are available on PATH, and the version
+ * each reports (null when present but unparseable). `probeBin` is
+ * injectable so tests can stub PATH presence/version without shelling out
+ * for real binaries.
+ */
+export declare function detectAgents(probeBin?: (bin: string) => {
+    version: string | null;
+} | undefined): DetectedAgent[];

package/dist/server/agents/detect.js

@@ -0,0 +1,35 @@
+import { spawnSync } from 'node:child_process';
+const CANDIDATES = ['codex', 'claude'];
+const VERSION_RE = /\d+\.\d+\.\d+/;
+/**
+ * Real PATH probe: runs `<bin> --version` and parses the first semver-ish
+ * token out of stdout. Returns `undefined` when the binary isn't present/
+ * runnable (spawn error, timeout, or nonzero exit); `null` version when it
+ * ran but produced no parseable version string.
+ */
+export function probe(bin) {
+    const result = spawnSync(bin, ['--version'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 3000,
+        encoding: 'utf8',
+    });
+    if (result.error !== undefined || result.status !== 0)
+        return undefined;
+    const match = result.stdout?.match(VERSION_RE);
+    return { version: match ? match[0] : null };
+}
+/**
+ * Detects which coding-agent CLIs are available on PATH, and the version
+ * each reports (null when present but unparseable). `probeBin` is
+ * injectable so tests can stub PATH presence/version without shelling out
+ * for real binaries.
+ */
+export function detectAgents(probeBin = probe) {
+    const found = [];
+    for (const kind of CANDIDATES) {
+        const result = probeBin(kind);
+        if (result)
+            found.push({ kind, version: result.version });
+    }
+    return found;
+}

package/dist/server/agents/gitScope.d.ts

@@ -0,0 +1,24 @@
+export interface GitSnapshot {
+    head: string | null;
+    dirty: string[];
+}
+export declare function isGitRepo(dir: string): boolean;
+export declare function snapshot(dir: string): GitSnapshot;
+export declare function diffSince(dir: string, snap: GitSnapshot): string;
+export declare function changedFiles(dir: string, snap: GitSnapshot): string[];
+/**
+ * Reverts the given files, which are expected to come from `changedFiles`
+ * (and therefore already exclude any untracked files that pre-date the
+ * snapshot).
+ *
+ * Tracked files are restored from the snapshot commit (`git checkout
+ * <snap.head> -- <file>`), NOT from the index — so a file that was `git add`ed
+ * after the snapshot is still restored to its snapshot content, not its staged
+ * (mutated) content. Files that are currently untracked (newly added since the
+ * snapshot) are deleted.
+ *
+ * If `snap.head` is null (a repo with no commits at snapshot time) there is no
+ * commit to restore tracked files from, so only the newly-added untracked files
+ * are deleted; any tracked-file changes are left in place.
+ */
+export declare function revert(dir: string, snap: GitSnapshot, files: string[]): void;

package/dist/server/agents/gitScope.js

@@ -0,0 +1,95 @@
+import { execFileSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+function git(dir, args) {
+    return execFileSync('git', args, { cwd: dir, encoding: 'utf8' });
+}
+/** Untracked (non-ignored) files, relative to `dir`. */
+function untrackedFiles(dir) {
+    const out = git(dir, ['ls-files', '--others', '--exclude-standard']);
+    return out.split('\n').filter((line) => line.length > 0);
+}
+/**
+ * Tracked files with uncommitted modifications (staged or unstaged), relative
+ * to `dir`. Diffs against the given commit; when `head` is null (a repo with no
+ * commits) there are no tracked-and-committed files, so returns [].
+ */
+function dirtyTrackedFiles(dir, head) {
+    if (!head)
+        return [];
+    const out = git(dir, ['diff', '--name-only', head]);
+    return out.split('\n').filter((line) => line.length > 0);
+}
+export function isGitRepo(dir) {
+    try {
+        const out = execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd: dir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return out === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+export function snapshot(dir) {
+    let head = null;
+    try {
+        head = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd: dir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        head = null;
+    }
+    const dirty = [...dirtyTrackedFiles(dir, head), ...untrackedFiles(dir)];
+    return { head, dirty };
+}
+export function diffSince(dir, snap) {
+    if (snap.head) {
+        return git(dir, ['diff', snap.head]);
+    }
+    return git(dir, ['diff']);
+}
+export function changedFiles(dir, snap) {
+    // Exclude any tracked file that was ALREADY dirty (uncommitted WIP) at
+    // snapshot time — mirrors the untracked filter below. We can't cleanly
+    // separate the user's pre-existing edits from the agent's own edits to the
+    // same file, so the safest choice is to leave such files out of
+    // `changedFiles` entirely: they won't be reported as agent changes, and
+    // (critically) `revert` won't touch them, preserving the user's WIP.
+    const trackedChanged = dirtyTrackedFiles(dir, snap.head).filter((f) => !snap.dirty.includes(f));
+    const newlyUntracked = untrackedFiles(dir).filter((f) => !snap.dirty.includes(f));
+    return [...new Set([...trackedChanged, ...newlyUntracked])];
+}
+/**
+ * Reverts the given files, which are expected to come from `changedFiles`
+ * (and therefore already exclude any untracked files that pre-date the
+ * snapshot).
+ *
+ * Tracked files are restored from the snapshot commit (`git checkout
+ * <snap.head> -- <file>`), NOT from the index — so a file that was `git add`ed
+ * after the snapshot is still restored to its snapshot content, not its staged
+ * (mutated) content. Files that are currently untracked (newly added since the
+ * snapshot) are deleted.
+ *
+ * If `snap.head` is null (a repo with no commits at snapshot time) there is no
+ * commit to restore tracked files from, so only the newly-added untracked files
+ * are deleted; any tracked-file changes are left in place.
+ */
+export function revert(dir, snap, files) {
+    if (files.length === 0)
+        return;
+    const currentUntracked = new Set(untrackedFiles(dir));
+    const toDelete = files.filter((f) => currentUntracked.has(f));
+    const toCheckout = files.filter((f) => !currentUntracked.has(f));
+    for (const file of toDelete) {
+        rmSync(join(dir, file), { force: true });
+    }
+    if (toCheckout.length > 0 && snap.head) {
+        git(dir, ['checkout', snap.head, '--', ...toCheckout]);
+    }
+}

package/dist/server/agents/modelRejectionHint.d.ts

@@ -0,0 +1,8 @@
+import type { AgentKind } from './types.js';
+/**
+ * When an agent CLI exits nonzero without ever emitting a terminal `done`,
+ * inspect its buffered stderr tail for known model-rejection shapes (a stale
+ * CLI that doesn't recognize the requested model). Returns an actionable
+ * hint to append to the error event text, or undefined when nothing matches.
+ */
+export declare function modelRejectionHint(kind: AgentKind, stderrTail: string): string | undefined;

package/dist/server/agents/modelRejectionHint.js

@@ -0,0 +1,12 @@
+const MODEL_REJECTION_RE = /unknown model|unsupported model|invalid model|model.*not.*(found|supported)/i;
+/**
+ * When an agent CLI exits nonzero without ever emitting a terminal `done`,
+ * inspect its buffered stderr tail for known model-rejection shapes (a stale
+ * CLI that doesn't recognize the requested model). Returns an actionable
+ * hint to append to the error event text, or undefined when nothing matches.
+ */
+export function modelRejectionHint(kind, stderrTail) {
+    if (!MODEL_REJECTION_RE.test(stderrTail))
+        return undefined;
+    return `hint: your ${kind} CLI may be too old for the selected model — upgrade it or switch backend in Settings.`;
+}