@xdelivered/emberflow 0.2.0

package/server/agents/codexParse.ts

@@ -0,0 +1,126 @@
+import type { AgentEvent } from './types';
+
+interface CodexCommandExecutionItem {
+  type: 'command_execution';
+  command: string;
+  status?: 'in_progress' | 'completed' | 'failed';
+  exit_code?: number | null;
+  aggregated_output?: string;
+}
+
+interface CodexAgentMessageItem {
+  type: 'agent_message';
+  text: string;
+}
+
+interface CodexErrorItem {
+  type: 'error';
+  // Codex has shipped both field names for the human-readable detail.
+  text?: string;
+  message?: string;
+}
+
+/** An MCP tool call codex made (e.g. the Emberflow MCP server's run_operation).
+ *  Field names are read defensively — codex's shape may nest server/tool under
+ *  `invocation` or expose them flat, and the result may arrive as result/output. */
+interface CodexMcpToolCallItem {
+  type: 'mcp_tool_call';
+  status?: 'in_progress' | 'completed' | 'failed';
+  server?: string;
+  tool?: string;
+  name?: string;
+  invocation?: { server?: string; tool?: string };
+  result?: unknown;
+  output?: unknown;
+  error?: string;
+}
+
+type CodexItem =
+  | CodexCommandExecutionItem
+  | CodexAgentMessageItem
+  | CodexErrorItem
+  | CodexMcpToolCallItem
+  | { type: string };
+
+/** Map a codex mcp_tool_call item → an 'mcp' AgentEvent, tolerating shape drift. */
+function mcpEventFrom(item: CodexMcpToolCallItem): AgentEvent {
+  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 } : {}) };
+}
+
+interface CodexLine {
+  type: string;
+  item?: CodexItem;
+  usage?: Record<string, number>;
+}
+
+export function parseCodexLine(line: string): AgentEvent | null {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  let parsed: CodexLine;
+  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 as CodexCommandExecutionItem;
+        return {
+          type: 'command',
+          command: commandItem.command,
+          commandStatus: commandItem.status,
+        };
+      }
+      if (item && item.type === 'mcp_tool_call') return mcpEventFrom(item as CodexMcpToolCallItem);
+      return null;
+    }
+
+    case 'item.completed': {
+      const item = parsed.item;
+      if (!item) return null;
+      if (item.type === 'command_execution') {
+        const commandItem = item as CodexCommandExecutionItem;
+        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 as CodexMcpToolCallItem);
+      if (item.type === 'agent_message') {
+        const messageItem = item as CodexAgentMessageItem;
+        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 as CodexErrorItem;
+        return { type: 'message', text: `⚠ ${errorItem.text ?? errorItem.message ?? 'error'}` };
+      }
+      return null;
+    }
+
+    case 'turn.completed':
+      return { type: 'done', usage: parsed.usage };
+
+    default:
+      return null;
+  }
+}

package/server/agents/detect.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectAgents, probe } from './detect';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fixture = (name: string) => path.join(__dirname, '__fixtures__', name);
+
+describe('detectAgents', () => {
+  it('returns only the CLIs the injected probe reports as present, with parsed versions', () => {
+    expect(detectAgents((bin) => (bin === 'codex' ? { version: '0.142.5' } : undefined))).toEqual([
+      { kind: 'codex', version: '0.142.5' },
+    ]);
+    expect(detectAgents((bin) => (bin === 'claude' ? { version: '1.2.3' } : undefined))).toEqual([
+      { kind: 'claude', version: '1.2.3' },
+    ]);
+  });
+
+  it('returns both when both are present', () => {
+    expect(detectAgents(() => ({ version: '1.0.0' }))).toEqual([
+      { kind: 'codex', version: '1.0.0' },
+      { kind: 'claude', version: '1.0.0' },
+    ]);
+  });
+
+  it('returns [] when neither is present', () => {
+    expect(detectAgents(() => undefined)).toEqual([]);
+  });
+
+  it('reports null version when present but the output has no parseable semver token', () => {
+    expect(detectAgents((bin) => (bin === 'codex' ? { version: null } : undefined))).toEqual([
+      { kind: 'codex', version: null },
+    ]);
+  });
+
+  it('defaults to a real PATH probe that returns an array', () => {
+    expect(Array.isArray(detectAgents())).toBe(true);
+  });
+});
+
+describe('probe (real spawnSync path)', () => {
+  it('parses the first semver-ish token out of well-formed --version output', () => {
+    expect(probe(fixture('fake-version-good.mjs'))).toEqual({ version: '0.142.5' });
+  });
+
+  it('returns a null version when the output is garbage with no semver token', () => {
+    expect(probe(fixture('fake-version-garbage.mjs'))).toEqual({ version: null });
+  });
+
+  it('returns a null version when the output is empty', () => {
+    expect(probe(fixture('fake-version-empty.mjs'))).toEqual({ version: null });
+  });
+
+  it('returns undefined when the binary does not exist', () => {
+    expect(probe('/nonexistent/nope-agent-cli')).toBeUndefined();
+  });
+
+  it('returns undefined when the binary exits nonzero', () => {
+    expect(probe(fixture('fake-version-fail.mjs'))).toBeUndefined();
+  });
+
+  it('returns undefined when the binary hangs past the timeout', () => {
+    expect(probe(fixture('fake-version-hang.mjs'))).toBeUndefined();
+  }, 10000);
+});

package/server/agents/detect.ts

@@ -0,0 +1,43 @@
+import { spawnSync } from 'node:child_process';
+import type { AgentKind } from './types';
+
+const CANDIDATES: AgentKind[] = ['codex', 'claude'];
+
+const VERSION_RE = /\d+\.\d+\.\d+/;
+
+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 function probe(bin: string): { version: string | null } | undefined {
+  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: (bin: string) => { version: string | null } | undefined = probe): DetectedAgent[] {
+  const found: DetectedAgent[] = [];
+  for (const kind of CANDIDATES) {
+    const result = probeBin(kind);
+    if (result) found.push({ kind, version: result.version });
+  }
+  return found;
+}

package/server/agents/gitScope.test.ts

@@ -0,0 +1,129 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { changedFiles, diffSince, isGitRepo, revert, snapshot } from './gitScope';
+
+function git(dir: string, args: string[]): string {
+  return execFileSync('git', args, { cwd: dir, encoding: 'utf8' });
+}
+
+describe('gitScope', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'gitscope-'));
+    git(dir, ['init']);
+    git(dir, ['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '--allow-empty', '-m', 'init']);
+    writeFileSync(join(dir, 'tracked.txt'), 'original content\n');
+    git(dir, ['add', 'tracked.txt']);
+    git(dir, ['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'add tracked file']);
+    // pre-existing untracked file that must survive revert untouched
+    writeFileSync(join(dir, 'pre-existing-untracked.txt'), 'do not touch\n');
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('isGitRepo returns true for a git repo and false otherwise', () => {
+    expect(isGitRepo(dir)).toBe(true);
+    const nonRepo = mkdtempSync(join(tmpdir(), 'not-a-repo-'));
+    try {
+      expect(isGitRepo(nonRepo)).toBe(false);
+    } finally {
+      rmSync(nonRepo, { recursive: true, force: true });
+    }
+  });
+
+  it('changedFiles lists a mutated tracked file and a newly-added file, diffSince shows the mutation', () => {
+    const snap = snapshot(dir);
+
+    writeFileSync(join(dir, 'tracked.txt'), 'mutated content\n');
+    writeFileSync(join(dir, 'new-file.txt'), 'brand new\n');
+
+    const files = changedFiles(dir, snap);
+    expect(files).toContain('tracked.txt');
+    expect(files).toContain('new-file.txt');
+    expect(files).not.toContain('pre-existing-untracked.txt');
+
+    const diff = diffSince(dir, snap);
+    expect(diff).toContain('mutated content');
+  });
+
+  it('revert restores the tracked file, removes the new file, and leaves pre-existing untracked files alone', () => {
+    const snap = snapshot(dir);
+
+    writeFileSync(join(dir, 'tracked.txt'), 'mutated content\n');
+    writeFileSync(join(dir, 'new-file.txt'), 'brand new\n');
+
+    const files = changedFiles(dir, snap);
+    revert(dir, snap, files);
+
+    expect(readFileSync(join(dir, 'tracked.txt'), 'utf8')).toBe('original content\n');
+    expect(existsSync(join(dir, 'new-file.txt'))).toBe(false);
+    expect(existsSync(join(dir, 'pre-existing-untracked.txt'))).toBe(true);
+  });
+
+  it('revert restores a file that was mutated AND staged (git add) since the snapshot', () => {
+    const snap = snapshot(dir);
+
+    writeFileSync(join(dir, 'tracked.txt'), 'mutated content\n');
+    git(dir, ['add', 'tracked.txt']);
+
+    const files = changedFiles(dir, snap);
+    expect(files).toContain('tracked.txt');
+
+    revert(dir, snap, files);
+
+    // Must be the snapshot content, not the staged (mutated) content.
+    expect(readFileSync(join(dir, 'tracked.txt'), 'utf8')).toBe('original content\n');
+  });
+
+  it('changedFiles/revert exclude a tracked file that was already dirty (WIP) at snapshot time', () => {
+    // Simulate the user having uncommitted WIP on tracked.txt *before* the agent runs.
+    writeFileSync(join(dir, 'tracked.txt'), 'user wip content\n');
+
+    const snap = snapshot(dir);
+    expect(snap.dirty).toContain('tracked.txt');
+
+    // Agent runs: creates a new file, does NOT touch tracked.txt.
+    writeFileSync(join(dir, 'new.txt'), 'agent created\n');
+
+    const files = changedFiles(dir, snap);
+    expect(files).toEqual(['new.txt']);
+    expect(files).not.toContain('tracked.txt');
+
+    revert(dir, snap, files);
+
+    // The user's WIP edit must survive untouched.
+    expect(readFileSync(join(dir, 'tracked.txt'), 'utf8')).toBe('user wip content\n');
+    // The agent's new file must be gone.
+    expect(existsSync(join(dir, 'new.txt'))).toBe(false);
+  });
+
+  it('snapshot / changedFiles / revert work on a fresh repo with no commits', () => {
+    const fresh = mkdtempSync(join(tmpdir(), 'gitscope-empty-'));
+    try {
+      git(fresh, ['init']);
+      writeFileSync(join(fresh, 'a.txt'), 'hello\n');
+
+      const snap = snapshot(fresh);
+      expect(snap.head).toBeNull();
+
+      // Add a new file after the snapshot.
+      writeFileSync(join(fresh, 'b.txt'), 'new\n');
+
+      const files = changedFiles(fresh, snap);
+      expect(files).toContain('b.txt');
+      expect(files).not.toContain('a.txt'); // pre-existing untracked, not a change
+
+      revert(fresh, snap, files);
+      expect(existsSync(join(fresh, 'b.txt'))).toBe(false);
+      expect(existsSync(join(fresh, 'a.txt'))).toBe(true); // left alone
+    } finally {
+      rmSync(fresh, { recursive: true, force: true });
+    }
+  });
+});

package/server/agents/gitScope.ts

@@ -0,0 +1,110 @@
+import { execFileSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface GitSnapshot {
+  head: string | null;
+  dirty: string[];
+}
+
+function git(dir: string, args: string[]): string {
+  return execFileSync('git', args, { cwd: dir, encoding: 'utf8' });
+}
+
+/** Untracked (non-ignored) files, relative to `dir`. */
+function untrackedFiles(dir: string): string[] {
+  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: string, head: string | null): string[] {
+  if (!head) return [];
+  const out = git(dir, ['diff', '--name-only', head]);
+  return out.split('\n').filter((line) => line.length > 0);
+}
+
+export function isGitRepo(dir: string): boolean {
+  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: string): GitSnapshot {
+  let head: string | null = 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: string, snap: GitSnapshot): string {
+  if (snap.head) {
+    return git(dir, ['diff', snap.head]);
+  }
+  return git(dir, ['diff']);
+}
+
+export function changedFiles(dir: string, snap: GitSnapshot): string[] {
+  // 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: string, snap: GitSnapshot, files: string[]): void {
+  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/server/agents/modelRejectionHint.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { modelRejectionHint } from './modelRejectionHint';
+
+describe('modelRejectionHint', () => {
+  it('returns undefined for unrelated stderr', () => {
+    expect(modelRejectionHint('codex', 'some non-fatal mcp auth error')).toBeUndefined();
+  });
+
+  it('returns undefined for empty stderr', () => {
+    expect(modelRejectionHint('codex', '')).toBeUndefined();
+  });
+
+  it.each([
+    'Error: unknown model "gpt-5.6-sol"',
+    "Error: unsupported model 'gpt-5.6-sol'",
+    'invalid model specified',
+    'model gpt-5.6-sol not found',
+    'the requested model is not supported',
+  ])('matches known model-rejection shapes: %s', (stderr) => {
+    expect(modelRejectionHint('codex', stderr)).toBe(
+      'hint: your codex CLI may be too old for the selected model — upgrade it or switch backend in Settings.',
+    );
+  });
+
+  it('names the given agent kind in the hint text', () => {
+    expect(modelRejectionHint('claude', 'unknown model')).toBe(
+      'hint: your claude CLI may be too old for the selected model — upgrade it or switch backend in Settings.',
+    );
+  });
+});

package/server/agents/modelRejectionHint.ts

@@ -0,0 +1,14 @@
+import type { AgentKind } from './types';
+
+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: AgentKind, stderrTail: string): string | undefined {
+  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.`;
+}