@xdelivered/emberflow 0.2.0

package/server/agents/claudeParse.ts

@@ -0,0 +1,193 @@
+import type { AgentEvent } from './types';
+
+interface ClaudeToolResultTextBlock {
+  type: string;
+  text?: string;
+}
+
+interface ClaudeContentBlock {
+  type: string;
+  text?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  id?: string; // tool_use id (assistant tool_use blocks)
+  tool_use_id?: string; // correlates a tool_result back to its tool_use
+  content?: string | ClaudeToolResultTextBlock[]; // tool_result payload
+  is_error?: boolean; // tool_result failure flag
+}
+
+interface ClaudeLine {
+  type: string;
+  subtype?: string;
+  is_error?: boolean;
+  message?: {
+    content?: ClaudeContentBlock[];
+  };
+  result?: string;
+  usage?: Record<string, number>;
+}
+
+/** Best-effort extraction of a shell command from a Bash tool_use input. */
+function bashCommandFrom(block: ClaudeContentBlock): string | undefined {
+  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: string, input: Record<string, unknown>): string {
+  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: ClaudeContentBlock): string {
+  const name = block.name ?? 'tool';
+  const input = (block.input ?? {}) as Record<string, unknown>;
+  const str = (v: unknown): string | undefined => (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: string[] = [];
+      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: ClaudeContentBlock): string {
+  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: string): AgentEvent[] {
+  const trimmed = line.trim();
+  if (!trimmed) return [];
+
+  let parsed: ClaudeLine;
+  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: AgentEvent[] = [];
+      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: AgentEvent[] = [];
+      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/server/agents/codexAdapter.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawnCodex } from './codexAdapter';
+import type { AgentEvent } from './types';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fakeCodexPath = path.join(__dirname, '__fixtures__', 'fake-codex.mjs');
+
+async function collect(events: AsyncIterable<AgentEvent>): Promise<AgentEvent[]> {
+  const out: AgentEvent[] = [];
+  for await (const e of events) {
+    out.push(e);
+  }
+  return out;
+}
+
+describe('spawnCodex', () => {
+  it('normalizes fake-codex stdout into [started, command, message, done]', async () => {
+    const agent = spawnCodex('do the thing', os.tmpdir(), { bin: fakeCodexPath });
+    const events = await collect(agent.events);
+    expect(events).toEqual([
+      { type: 'started' },
+      { type: 'command', command: 'ls', commandStatus: 'in_progress' },
+      { type: 'message', text: 'Done listing files' },
+      { type: 'done', usage: { output_tokens: 5 } },
+    ]);
+  });
+
+  it('yields a terminal error event when the process exits non-zero without a done event', async () => {
+    process.env.FAKE_CODEX_FAIL = '1';
+    try {
+      const agent = spawnCodex('do the thing', os.tmpdir(), { bin: fakeCodexPath });
+      const events = await collect(agent.events);
+      expect(events[0]).toEqual({ type: 'started' });
+      expect(events[1]).toEqual({ type: 'command', command: 'ls', commandStatus: 'in_progress' });
+      expect(events[2]).toEqual({ type: 'message', text: 'Done listing files' });
+      const last = events[events.length - 1];
+      expect(last.type).toBe('error');
+      expect(last.text).not.toContain('hint:');
+    } finally {
+      delete process.env.FAKE_CODEX_FAIL;
+    }
+  });
+
+  it('appends an actionable hint to the terminal error when stderr looks like a model-rejection', async () => {
+    process.env.FAKE_CODEX_MODEL_REJECT = '1';
+    try {
+      const agent = spawnCodex('do the thing', os.tmpdir(), { bin: fakeCodexPath });
+      const events = await collect(agent.events);
+      const last = events[events.length - 1];
+      expect(last.type).toBe('error');
+      expect(last.text).toContain(
+        'hint: your codex CLI may be too old for the selected model — upgrade it or switch backend in Settings.',
+      );
+    } finally {
+      delete process.env.FAKE_CODEX_MODEL_REJECT;
+    }
+  });
+
+  it('delivers every event including the trailing done when the child emits many lines then exits (no event-loss race)', async () => {
+    process.env.FAKE_CODEX_MANY = '1';
+    try {
+      const agent = spawnCodex('do the thing', os.tmpdir(), { bin: fakeCodexPath });
+      const events = await collect(agent.events);
+      // started + command + message + 27 filler messages + done = 31 events
+      expect(events.length).toBe(31);
+      expect(events[0]).toEqual({ type: 'started' });
+      expect(events[events.length - 1]).toEqual({ type: 'done', usage: { output_tokens: 5 } });
+      const fillers = events.filter((e) => e.type === 'message' && e.text?.startsWith('filler '));
+      expect(fillers.length).toBe(27);
+    } finally {
+      delete process.env.FAKE_CODEX_MANY;
+    }
+  });
+
+  it('yields a terminal error (and does not crash) when the binary cannot be spawned', async () => {
+    const agent = spawnCodex('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 = spawnCodex('do the thing', os.tmpdir(), { bin: fakeCodexPath });
+    expect(() => agent.cancel()).not.toThrow();
+    await collect(agent.events);
+  });
+
+  it('cancel() escalates to SIGKILL if the process ignores SIGTERM', async () => {
+    process.env.FAKE_CODEX_HANG = '1';
+    try {
+      const agent = spawnCodex('do the thing', os.tmpdir(), { bin: fakeCodexPath, 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_CODEX_HANG;
+    }
+  }, 10000);
+
+  it('synthesizes a terminal done when the process exits 0 without a turn.completed', async () => {
+    process.env.FAKE_CODEX_NODONE = '1';
+    try {
+      const agent = spawnCodex('do the thing', os.tmpdir(), { bin: fakeCodexPath });
+      const events = await collect(agent.events);
+      expect(events).toEqual([
+        { type: 'started' },
+        { type: 'command', command: 'ls', commandStatus: 'in_progress' },
+        { type: 'message', text: 'Done listing files' },
+        { type: 'done' },
+      ]);
+    } finally {
+      delete process.env.FAKE_CODEX_NODONE;
+    }
+  });
+});

package/server/agents/codexAdapter.ts

@@ -0,0 +1,198 @@
+import { spawn, type ChildProcessByStdio } from 'node:child_process';
+import type { Readable } from 'node:stream';
+import readline from 'node:readline';
+import { parseCodexLine } from './codexParse';
+import { modelRejectionHint } from './modelRejectionHint';
+import type { AgentEvent } from './types';
+
+const STDERR_TAIL_BYTES = 2048;
+
+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 function spawnCodex(prompt: string, projectDir: string, opts: CodexOptions = {}): SpawnedAgent {
+  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: ChildProcessByStdio<null, Readable, Readable> = 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: 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();
+    }
+  }
+
+  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: 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 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(): 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 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: 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?.();
+    },
+  };
+}

package/server/agents/codexParse.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { parseCodexLine } from './codexParse';
+
+describe('parseCodexLine', () => {
+  it('maps a command_execution start', () => {
+    const e = parseCodexLine('{"type":"item.started","item":{"id":"i3","type":"command_execution","command":"ls","status":"in_progress"}}');
+    expect(e).toEqual({ type: 'command', command: 'ls', commandStatus: 'in_progress' });
+  });
+  it('maps a completed (failed) command with exit code + output', () => {
+    const e = parseCodexLine('{"type":"item.completed","item":{"id":"i3","type":"command_execution","command":"curl x","exit_code":6,"aggregated_output":"000","status":"failed"}}');
+    expect(e).toEqual({ type: 'command', command: 'curl x', exitCode: 6, output: '000', commandStatus: 'failed' });
+  });
+  it('maps an agent_message to message', () => {
+    expect(parseCodexLine('{"type":"item.completed","item":{"type":"agent_message","text":"Updated file"}}'))
+      .toEqual({ type: 'message', text: 'Updated file' });
+  });
+
+  it('maps a non-fatal error ITEM to a warning message (NOT a terminal error)', () => {
+    // codex `error` items (e.g. an MCP server failing to auth) must not fail the
+    // whole run — only a non-zero process exit does. See codexParse.ts.
+    expect(parseCodexLine('{"type":"item.completed","item":{"type":"error","text":"mcp auth failed"}}'))
+      .toEqual({ type: 'message', text: '⚠ mcp auth failed' });
+  });
+  it('reads the error detail from `message` when `text` is absent — the shape current codex ships', () => {
+    // Without this, a fatal-cause diagnostic (e.g. "model requires a newer
+    // version of Codex") renders as a bare "⚠ error" and the user learns nothing.
+    expect(
+      parseCodexLine('{"type":"item.completed","item":{"type":"error","message":"model requires a newer version of Codex"}}'),
+    ).toEqual({ type: 'message', text: '⚠ model requires a newer version of Codex' });
+  });
+  it('maps an mcp_tool_call (flat server/tool) to an mcp event with status', () => {
+    expect(
+      parseCodexLine('{"type":"item.started","item":{"type":"mcp_tool_call","server":"emberflow","tool":"run_operation","status":"in_progress"}}'),
+    ).toEqual({ type: 'mcp', mcpServer: 'emberflow', mcpTool: 'run_operation', mcpStatus: 'in_progress' });
+  });
+  it('maps a completed mcp_tool_call, reading server/tool from invocation + result', () => {
+    expect(
+      parseCodexLine('{"type":"item.completed","item":{"type":"mcp_tool_call","invocation":{"server":"emberflow","tool":"run_operation"},"status":"completed","result":{"status":200}}}'),
+    ).toEqual({ type: 'mcp', mcpServer: 'emberflow', mcpTool: 'run_operation', mcpStatus: 'completed', output: '{\n  "status": 200\n}' });
+  });
+  it('tolerates missing fields on an mcp_tool_call (falls back to mcp/tool)', () => {
+    expect(parseCodexLine('{"type":"item.completed","item":{"type":"mcp_tool_call"}}'))
+      .toEqual({ type: 'mcp', mcpServer: 'mcp', mcpTool: 'tool', mcpStatus: undefined });
+  });
+  it('maps turn.completed to done with usage', () => {
+    expect(parseCodexLine('{"type":"turn.completed","usage":{"output_tokens":5}}'))
+      .toEqual({ type: 'done', usage: { output_tokens: 5 } });
+  });
+  it('maps thread.started/turn.started to started', () => {
+    expect(parseCodexLine('{"type":"thread.started"}')).toEqual({ type: 'started' });
+    expect(parseCodexLine('{"type":"turn.started"}')).toEqual({ type: 'started' });
+  });
+  it('ignores unknown and blank lines', () => {
+    expect(parseCodexLine('{"type":"whatever"}')).toBeNull();
+    expect(parseCodexLine('')).toBeNull();
+    expect(parseCodexLine('not json')).toBeNull();
+  });
+});