@xdelivered/emberflow 0.2.0

package/server/agents/__fixtures__/fake-claude-writer.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Test fixture for runManager tests: behaves like fake-claude.mjs (prints a
+// started/message/command/done sequence) but ALSO mutates a real tracked
+// file in the project dir. spawnClaude runs the child with cwd=projectDir
+// (unlike codex, which passes -C explicitly), so this fixture just writes
+// relative to process.cwd().
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+writeFileSync(join(process.cwd(), 'flows', 'hello.json'), 'agent was here\n');
+
+const lines = [
+  { type: 'system', subtype: 'init', session_id: 'fake-session' },
+  { type: 'assistant', message: { content: [{ type: 'text', text: 'Working on it' }] } },
+  { type: 'assistant', message: { content: [{ type: 'tool_use', name: 'Bash', input: { command: 'ls' } }] } },
+  { type: 'result', subtype: 'success', usage: { output_tokens: 5 } },
+];
+
+for (const line of lines) {
+  process.stdout.write(JSON.stringify(line) + '\n');
+}
+
+process.exit(0);

package/server/agents/__fixtures__/fake-claude.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// Test fixture: fakes `claude -p ... --output-format stream-json` output. Ignores all args.
+// Prints fixture stream-json JSONL lines to stdout, then exits.
+// Modes (env vars):
+//   default                     → system/init, assistant text, assistant Bash tool_use, result/success; exit 0
+//   FAKE_CLAUDE_FAIL=1           → system/init, assistant text + stderr noise; exit 1 (no result)
+//   FAKE_CLAUDE_NODONE=1         → system/init, assistant text; exit 0 (no result event)
+//   FAKE_CLAUDE_MODEL_REJECT=1   → system/init, assistant text + stderr "unknown model"; exit 1 (no result)
+//   FAKE_CLAUDE_HANG=1           → system/init, assistant text; ignores SIGTERM and hangs
+//                                 until killed (SIGKILL), to exercise cancel() escalation
+
+const lines = [
+  { type: 'system', subtype: 'init', session_id: 'fake-session' },
+  {
+    type: 'assistant',
+    message: { content: [{ type: 'text', text: 'Working on it' }] },
+  },
+  {
+    type: 'assistant',
+    message: { content: [{ type: 'tool_use', id: 't1', name: 'Bash', input: { command: 'ls' } }] },
+  },
+  {
+    type: 'user',
+    message: { content: [{ type: 'tool_result', tool_use_id: 't1', content: 'file1\nfile2' }] },
+  },
+];
+
+for (const line of lines) {
+  process.stdout.write(JSON.stringify(line) + '\n');
+}
+
+if (process.env.FAKE_CLAUDE_HANG === '1') {
+  process.on('SIGTERM', () => {
+    // Simulate a stuck child that ignores SIGTERM — only SIGKILL (uncatchable)
+    // will end it.
+  });
+  setInterval(() => {}, 100000);
+} else {
+  if (process.env.FAKE_CLAUDE_FAIL === '1') {
+    process.stderr.write('some non-fatal noise\n');
+    process.exit(1);
+  }
+
+  if (process.env.FAKE_CLAUDE_MODEL_REJECT === '1') {
+    process.stderr.write('Error: unknown model "claude-9000"\n');
+    process.exit(1);
+  }
+
+  if (process.env.FAKE_CLAUDE_NODONE === '1') {
+    process.exit(0);
+  }
+
+  process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', usage: { output_tokens: 5 } }) + '\n');
+  process.exit(0);
+}

package/server/agents/__fixtures__/fake-codex-writer.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Test fixture for runManager tests: behaves like fake-codex.mjs (prints a
+// started/command/message/done sequence) but ALSO mutates a real tracked
+// file in the project dir it was invoked with `-C <dir>`, so diff/revert
+// against a real git snapshot can be exercised end-to-end. `git diff` never
+// shows untracked files, so this must touch a file that's already committed
+// (unlike a brand-new file) for the diff assertion to see real content.
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const cIndex = process.argv.indexOf('-C');
+const projectDir = cIndex !== -1 ? process.argv[cIndex + 1] : process.cwd();
+
+writeFileSync(join(projectDir, 'flows', 'hello.json'), 'agent was here\n');
+
+const lines = [
+  { type: 'thread.started' },
+  { type: 'item.started', item: { id: 'i1', type: 'command_execution', command: 'ls', status: 'in_progress' } },
+  { type: 'item.completed', item: { type: 'agent_message', text: 'Done listing files' } },
+  { type: 'turn.completed', usage: { output_tokens: 5 } },
+];
+
+for (const line of lines) {
+  process.stdout.write(JSON.stringify(line) + '\n');
+}
+
+process.exit(0);

package/server/agents/__fixtures__/fake-codex.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Test fixture: fakes `codex exec --json` output. Ignores all args.
+// Prints fixture JSONL lines to stdout, then exits.
+// Modes (env vars):
+//   default                    → started, command, message, turn.completed; exit 0
+//   FAKE_CODEX_FAIL=1          → started, command, message + stderr noise; exit 1 (no done)
+//   FAKE_CODEX_MANY=1          → started, command, message, 27 filler, turn.completed; exit 0 (race test)
+//   FAKE_CODEX_NODONE=1        → started, command, message; exit 0 (no turn.completed)
+//   FAKE_CODEX_MODEL_REJECT=1  → started, command, message + stderr "unsupported model"; exit 1 (no done)
+//   FAKE_CODEX_HANG=1          → started, command, message; ignores SIGTERM and hangs
+//                                until killed (SIGKILL), to exercise cancel() escalation
+
+const lines = [
+  { type: 'thread.started' },
+  { type: 'item.started', item: { id: 'i1', type: 'command_execution', command: 'ls', status: 'in_progress' } },
+  { type: 'item.completed', item: { type: 'agent_message', text: 'Done listing files' } },
+];
+
+if (process.env.FAKE_CODEX_MANY === '1') {
+  for (let i = 0; i < 27; i++) {
+    lines.push({ type: 'item.completed', item: { type: 'agent_message', text: `filler ${i}` } });
+  }
+}
+
+for (const line of lines) {
+  process.stdout.write(JSON.stringify(line) + '\n');
+}
+
+if (process.env.FAKE_CODEX_HANG === '1') {
+  process.on('SIGTERM', () => {
+    // Simulate a stuck child that ignores SIGTERM — only SIGKILL (uncatchable)
+    // will end it.
+  });
+  setInterval(() => {}, 100000);
+} else {
+  if (process.env.FAKE_CODEX_FAIL === '1') {
+    process.stderr.write('some non-fatal mcp auth error\n');
+    process.exit(1);
+  }
+
+  if (process.env.FAKE_CODEX_MODEL_REJECT === '1') {
+    process.stderr.write('Error: unsupported model \'gpt-5.6-sol\'\n');
+    process.exit(1);
+  }
+
+  if (process.env.FAKE_CODEX_NODONE === '1') {
+    process.exit(0);
+  }
+
+  process.stdout.write(JSON.stringify({ type: 'turn.completed', usage: { output_tokens: 5 } }) + '\n');
+  process.exit(0);
+}

package/server/agents/__fixtures__/fake-version-empty.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Test fixture for detect.test.ts: exits clean with empty stdout.
+process.exit(0);

package/server/agents/__fixtures__/fake-version-fail.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Test fixture for detect.test.ts: exits nonzero (binary present but --version unsupported/broken).
+process.stderr.write('unknown flag --version\n');
+process.exit(1);

package/server/agents/__fixtures__/fake-version-garbage.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Test fixture for detect.test.ts: exits clean but prints no parseable semver token.
+process.stdout.write('some unversioned build\n');
+process.exit(0);

package/server/agents/__fixtures__/fake-version-good.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Test fixture for detect.test.ts: well-formed --version output.
+process.stdout.write('fake-agent-cli 0.142.5\n');
+process.exit(0);

package/server/agents/__fixtures__/fake-version-hang.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Test fixture for detect.test.ts: never exits — exercises the probe() timeout.
+setInterval(() => {}, 100000);

package/server/agents/claudeAdapter.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawnClaude } from './claudeAdapter';
+import type { AgentEvent } from './types';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fakeClaudePath = path.join(__dirname, '__fixtures__', 'fake-claude.mjs');
+
+async function collect(events: AsyncIterable<AgentEvent>): Promise<AgentEvent[]> {
+  const out: AgentEvent[] = [];
+  for await (const e of events) {
+    out.push(e);
+  }
+  return out;
+}
+
+describe('spawnClaude', () => {
+  it('normalizes fake-claude stdout into [started, message, command in_progress, command completed, done]', async () => {
+    const agent = spawnClaude('do the thing', os.tmpdir(), { bin: fakeClaudePath });
+    const events = await collect(agent.events);
+    expect(events).toEqual([
+      { type: 'started' },
+      { type: 'message', text: 'Working on it' },
+      { type: 'command', command: 'ls', commandStatus: 'in_progress', toolUseId: 't1' },
+      { type: 'command', command: 'ls', commandStatus: 'completed', output: 'file1\nfile2', toolUseId: 't1' },
+      { type: 'done', usage: { output_tokens: 5 } },
+    ]);
+  });
+
+  it('resolves a Bash command group to completed with output when the tool_result arrives (AgentConsole dedup fixture)', async () => {
+    const agent = spawnClaude('do the thing', os.tmpdir(), { bin: fakeClaudePath });
+    const events = await collect(agent.events);
+    const inProgress = events.find((e) => e.type === 'command' && e.commandStatus === 'in_progress');
+    const completed = events.find((e) => e.type === 'command' && e.commandStatus === 'completed');
+    expect(inProgress).toEqual({ type: 'command', command: 'ls', commandStatus: 'in_progress', toolUseId: 't1' });
+    // Same `command` text as the in_progress event — this is what lets
+    // AgentConsole's existing dedup (in_progress + same command text →
+    // replaced by completed) resolve the group to "Ran" + output.
+    expect(completed).toEqual({
+      type: 'command',
+      command: 'ls',
+      commandStatus: 'completed',
+      output: 'file1\nfile2',
+      toolUseId: 't1',
+    });
+  });
+
+  it('yields a terminal error event when the process exits non-zero without a result event', async () => {
+    process.env.FAKE_CLAUDE_FAIL = '1';
+    try {
+      const agent = spawnClaude('do the thing', os.tmpdir(), { bin: fakeClaudePath });
+      const events = await collect(agent.events);
+      expect(events[0]).toEqual({ type: 'started' });
+      const last = events[events.length - 1];
+      expect(last.type).toBe('error');
+      expect(last.text).not.toContain('hint:');
+    } finally {
+      delete process.env.FAKE_CLAUDE_FAIL;
+    }
+  });
+
+  it('appends an actionable hint to the terminal error when stderr looks like a model-rejection', async () => {
+    process.env.FAKE_CLAUDE_MODEL_REJECT = '1';
+    try {
+      const agent = spawnClaude('do the thing', os.tmpdir(), { bin: fakeClaudePath });
+      const events = await collect(agent.events);
+      const last = events[events.length - 1];
+      expect(last.type).toBe('error');
+      expect(last.text).toContain(
+        'hint: your claude CLI may be too old for the selected model — upgrade it or switch backend in Settings.',
+      );
+    } finally {
+      delete process.env.FAKE_CLAUDE_MODEL_REJECT;
+    }
+  });
+
+  it('yields a terminal error (and does not crash) when the binary cannot be spawned', async () => {
+    const agent = spawnClaude('do the thing', os.tmpdir(), { bin: '/nonexistent/nope' });
+    const events = await collect(agent.events);
+    expect(events.length).toBeGreaterThan(0);
+    const last = events[events.length - 1];
+    expect(last.type).toBe('error');
+    expect(events.filter((e) => e.type === 'done')).toEqual([]);
+  });
+
+  it('cancel() sends SIGTERM and does not throw', async () => {
+    const agent = spawnClaude('do the thing', os.tmpdir(), { bin: fakeClaudePath });
+    expect(() => agent.cancel()).not.toThrow();
+    await collect(agent.events);
+  });
+
+  it('cancel() escalates to SIGKILL if the process ignores SIGTERM', async () => {
+    process.env.FAKE_CLAUDE_HANG = '1';
+    try {
+      const agent = spawnClaude('do the thing', os.tmpdir(), { bin: fakeClaudePath, killGraceMs: 50 });
+      // Let the fixture install its SIGTERM handler before we cancel.
+      await new Promise((r) => setTimeout(r, 100));
+      agent.cancel();
+      const events = await collect(agent.events);
+      const last = events[events.length - 1];
+      // SIGKILL can't be caught, so the process dies without emitting its
+      // own terminal event — the adapter must synthesize an error.
+      expect(last.type).toBe('error');
+    } finally {
+      delete process.env.FAKE_CLAUDE_HANG;
+    }
+  }, 10000);
+
+  it('synthesizes a terminal done when the process exits 0 without a result event', async () => {
+    process.env.FAKE_CLAUDE_NODONE = '1';
+    try {
+      const agent = spawnClaude('do the thing', os.tmpdir(), { bin: fakeClaudePath });
+      const events = await collect(agent.events);
+      expect(events).toEqual([
+        { type: 'started' },
+        { type: 'message', text: 'Working on it' },
+        { type: 'command', command: 'ls', commandStatus: 'in_progress', toolUseId: 't1' },
+        { type: 'command', command: 'ls', commandStatus: 'completed', output: 'file1\nfile2', toolUseId: 't1' },
+        { type: 'done' },
+      ]);
+    } finally {
+      delete process.env.FAKE_CLAUDE_NODONE;
+    }
+  });
+});

package/server/agents/claudeAdapter.ts

@@ -0,0 +1,212 @@
+import { spawn, type ChildProcessByStdio } from 'node:child_process';
+import type { Readable } from 'node:stream';
+import readline from 'node:readline';
+import { parseClaudeLine } from './claudeParse';
+import { modelRejectionHint } from './modelRejectionHint';
+import type { AgentEvent } from './types';
+import type { SpawnedAgent } from './codexAdapter';
+
+const STDERR_TAIL_BYTES = 2048;
+
+export interface ClaudeOptions {
+  model?: string;
+  bin?: string;
+  /** Grace period (ms) between SIGTERM and the SIGKILL escalation in cancel(). Test hook. */
+  killGraceMs?: number;
+}
+
+export function spawnClaude(prompt: string, projectDir: string, opts: ClaudeOptions = {}): SpawnedAgent {
+  const bin = opts.bin ?? 'claude';
+  const args = [
+    '-p',
+    prompt,
+    '--output-format',
+    'stream-json',
+    '--verbose',
+    // Never ask for per-call approval — the studio runs claude non-interactively
+    // (-p + SSE panel), so an approval prompt has no one to answer it and the
+    // command simply fails ("This command requires approval"), which broke even
+    // our own CLI calls (list-environments). Mirrors the codex adapter's
+    // never-ask contract; the --add-dir working-directory sandbox still fences
+    // file reads/edits to the project.
+    '--permission-mode',
+    'bypassPermissions',
+    '--add-dir',
+    projectDir,
+    ...(opts.model ? ['--model', opts.model] : []),
+  ];
+
+  // detached: give claude its own process group so cancel() can tree-kill any
+  // subprocesses it spawns, not just the top-level process.
+  // stdio ['ignore','pipe','pipe'] → stdin is null, stdout/stderr are Readable.
+  const child: ChildProcessByStdio<null, Readable, Readable> = bin.endsWith('.mjs')
+    ? spawn(process.execPath, [bin, ...args], { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], detached: true })
+    : spawn(bin, args, { cwd: projectDir, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+
+  // Buffer only the last ~2KB of stderr — non-fatal in general, but useful as
+  // a diagnostic tail when the process dies without a terminal event (see
+  // maybeFinalize below).
+  let stderrTail = '';
+  child.stderr.on('data', (chunk: Buffer) => {
+    stderrTail = (stderrTail + chunk.toString('utf8')).slice(-STDERR_TAIL_BYTES);
+  });
+
+  const queue: AgentEvent[] = [];
+  const resolvers: Array<() => void> = [];
+  let done = false;
+  let sawTerminal = false;
+
+  function push(event: AgentEvent) {
+    queue.push(event);
+    const resolve = resolvers.shift();
+    if (resolve) resolve();
+  }
+
+  function finish() {
+    done = true;
+    while (resolvers.length) {
+      const resolve = resolvers.shift();
+      if (resolve) resolve();
+    }
+  }
+
+  // Tracks in-flight Bash commands by their tool_use id, so that when the
+  // matching tool_result (a separate 'user' stream-json line) arrives we can
+  // recover the original command text — the tool_result line only carries the
+  // id + output, not the command. AgentConsole dedups an in_progress command
+  // event with a later completed one by matching `command` text, so the
+  // completed event we emit here must reuse the same text.
+  const pendingCommands = new Map<string, string>();
+
+  const rl = readline.createInterface({ input: child.stdout });
+  rl.on('line', (line) => {
+    for (const event of parseClaudeLine(line)) {
+      if (event.type === 'done' || event.type === 'error') sawTerminal = true;
+
+      if (event.type === 'command' && event.commandStatus === 'in_progress' && event.toolUseId && event.command) {
+        pendingCommands.set(event.toolUseId, event.command);
+        push(event);
+        continue;
+      }
+
+      if (event.type === 'command' && event.commandStatus !== 'in_progress' && event.toolUseId) {
+        // A tool_result — only surface it if it corresponds to a Bash command
+        // we're tracking; skip gracefully otherwise (e.g. a non-Bash tool).
+        const command = pendingCommands.get(event.toolUseId);
+        if (!command) continue;
+        pendingCommands.delete(event.toolUseId);
+        push({ ...event, command });
+        continue;
+      }
+
+      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: number | null = null;
+  let escalateTimer: NodeJS.Timeout | undefined;
+
+  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 a result event — synthesize a done.
+        push({ type: 'done' });
+      } else {
+        const hint = modelRejectionHint('claude', stderrTail);
+        const text = hint ? `claude exited with code ${exitCode} (${hint})` : `claude 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 claude: ${err.message}` });
+    sawTerminal = true;
+    rlClosed = true;
+    procClosed = true;
+    finish();
+  });
+
+  async function* generate(): AsyncGenerator<AgentEvent> {
+    while (true) {
+      if (queue.length > 0) {
+        yield queue.shift()!;
+        continue;
+      }
+      if (done) return;
+      await new Promise<void>((resolve) => resolvers.push(resolve));
+    }
+  }
+
+  // Kill the whole process group (negative pid) so claude'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: NodeJS.Signals) {
+    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?.();
+    },
+  };
+}