@xdelivered/emberflow 0.2.0

package/server/agents/runManager.test.ts

@@ -0,0 +1,251 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AgentRunManager } from './runManager';
+import type { AgentEvent } from './types';
+import type { AgentIntent } from './prompt';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fakeCodexWriterPath = join(__dirname, '__fixtures__', 'fake-codex-writer.mjs');
+const fakeClaudeWriterPath = join(__dirname, '__fixtures__', 'fake-claude-writer.mjs');
+
+function git(dir: string, args: string[]): string {
+  return execFileSync('git', args, { cwd: dir, encoding: 'utf8' });
+}
+
+async function collectUntilDone(
+  manager: AgentRunManager,
+  id: string,
+  timeoutMs = 5000,
+): Promise<AgentEvent[]> {
+  return new Promise((resolve, reject) => {
+    const events: AgentEvent[] = [];
+    const timer = setTimeout(() => reject(new Error('timed out waiting for done')), timeoutMs);
+    const unsubscribe = manager.subscribe(id, (event) => {
+      events.push(event);
+      if (event.type === 'done' || event.type === 'error') {
+        clearTimeout(timer);
+        unsubscribe?.();
+        resolve(events);
+      }
+    });
+  });
+}
+
+describe('AgentRunManager', () => {
+  let projectDir: string;
+  let flowsDir: string;
+
+  beforeEach(() => {
+    projectDir = mkdtempSync(join(tmpdir(), 'agent-run-manager-'));
+    git(projectDir, ['init']);
+    git(projectDir, ['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '--allow-empty', '-m', 'init']);
+
+    flowsDir = join(projectDir, 'flows');
+    mkdirSync(flowsDir, { recursive: true });
+    writeFileSync(join(flowsDir, 'hello.json'), JSON.stringify({ id: 'hello', name: 'Hello', nodes: [] }));
+    git(projectDir, ['add', '-A']);
+    git(projectDir, ['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'add flow']);
+
+    process.env.EMBERFLOW_CODEX_BIN = fakeCodexWriterPath;
+  });
+
+  afterEach(() => {
+    delete process.env.EMBERFLOW_CODEX_BIN;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  const intent: AgentIntent = { action: 'edit-flow', flowId: 'hello', instruction: 'do a thing' };
+  const pathOf = (id: string): string | undefined => (id === 'hello' ? 'hello' : undefined);
+
+  it('starts a run, streams events to done, diffs the real change, and reverts it', async () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+
+    const id = manager.start(intent);
+    expect(typeof id).toBe('string');
+    expect(id.length).toBeGreaterThan(0);
+
+    const events = await collectUntilDone(manager, id);
+    expect(events[0]).toEqual({ type: 'started' });
+    expect(events[events.length - 1].type).toBe('done');
+
+    const { diff, files } = manager.diff(id)!;
+    expect(files).toContain('flows/hello.json');
+    expect(diff).toContain('agent was here');
+    expect(readFileSync(join(projectDir, 'flows', 'hello.json'), 'utf8')).toBe('agent was here\n');
+
+    const { reverted } = manager.revert(id)!;
+    expect(reverted).toContain('flows/hello.json');
+    expect(readFileSync(join(projectDir, 'flows', 'hello.json'), 'utf8')).not.toBe('agent was here\n');
+  });
+
+  it('rejects a second concurrent start while a run is active', async () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+
+    // Use a slow-ish fake so the first run is still "active" when we try the second.
+    // fake-codex-writer exits synchronously fast, so start a run and immediately
+    // try again before draining events — the manager must still consider it busy
+    // until the run reaches a terminal state.
+    manager.start(intent);
+    expect(() => manager.start(intent)).toThrow(/busy|active/i);
+  });
+
+  it('rejects starting against a non-git project dir', () => {
+    const nonRepo = mkdtempSync(join(tmpdir(), 'agent-run-manager-nongit-'));
+    try {
+      const manager = new AgentRunManager(nonRepo, flowsDir, pathOf);
+      expect(() => manager.start(intent)).toThrow(/not a git repo/i);
+    } finally {
+      rmSync(nonRepo, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects starting for an unknown flow', () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    const badIntent: AgentIntent = { action: 'edit-flow', flowId: 'nope', instruction: 'x' };
+    expect(() => manager.start(badIntent)).toThrow(/unknown flow/i);
+  });
+
+  it('allows a new run once the previous one has finished', async () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    const id1 = manager.start(intent);
+    await collectUntilDone(manager, id1);
+    manager.revert(id1);
+
+    const id2 = manager.start(intent);
+    expect(id2).not.toBe(id1);
+    await collectUntilDone(manager, id2);
+  });
+
+  it('cancel calls through to the adapter without throwing', async () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    const id = manager.start(intent);
+    expect(() => manager.cancel(id)).not.toThrow();
+    await collectUntilDone(manager, id);
+  });
+
+  it('rejects a flowId that tries to escape flowsDir', () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    const badIntent: AgentIntent = { action: 'edit-flow', flowId: '../../etc/passwd', instruction: 'x' };
+    expect(() => manager.start(badIntent)).toThrow(/invalid flowId/i);
+  });
+
+  it('rejects a flowId with a ".." segment even when mixed with safe segments', () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    const badIntent: AgentIntent = { action: 'edit-flow', flowId: 'a/../b', instruction: 'x' };
+    expect(() => manager.start(badIntent)).toThrow(/invalid flowId/i);
+  });
+
+  it('accepts an availableNodes getter and still starts/completes a run normally', async () => {
+    const availableNodes = (): Array<{ type: string; label?: string; description?: string }> => [
+      { type: 'Input' },
+      { type: 'Response' },
+      { type: 'FetchUser', label: 'Fetch User', description: 'Looks up a user by id.' },
+    ];
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf, availableNodes);
+
+    const id = manager.start(intent);
+    const events = await collectUntilDone(manager, id);
+    expect(events[events.length - 1].type).toBe('done');
+  });
+
+  it('allows a slash-separated path-style flowId (operation ids are on-disk paths) to pass the id-safety check', () => {
+    // billing/charge is a legitimate nested operation id — pathOf resolves it,
+    // so start() must get past the id-safety check and fail later for an
+    // unrelated reason (no such file), not with "invalid flowId".
+    const nestedPathOf = (id: string): string | undefined => (id === 'billing/charge' ? 'billing/charge' : undefined);
+    const manager = new AgentRunManager(projectDir, flowsDir, nestedPathOf);
+    const nestedIntent: AgentIntent = { action: 'edit-flow', flowId: 'billing/charge', instruction: 'x' };
+    expect(() => manager.start(nestedIntent)).not.toThrow(/invalid flowId/i);
+  });
+
+  it('prunes old terminal runs beyond the cap while keeping the active run', async () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+
+    const completedIds: string[] = [];
+    for (let i = 0; i < 25; i++) {
+      const id = manager.start(intent);
+      await collectUntilDone(manager, id);
+      completedIds.push(id);
+    }
+
+    // The manager only prunes on the *next* start(), so start one more run
+    // to trigger the sweep, then inspect via `has()` since there's no direct
+    // size getter.
+    const activeId = manager.start(intent);
+    const remaining = [...completedIds, activeId].filter((id) => manager.has(id));
+    // 20 terminal runs kept + the newly-started active run.
+    expect(remaining.length).toBeLessThanOrEqual(21);
+    expect(manager.has(activeId)).toBe(true);
+    await collectUntilDone(manager, activeId);
+  }, 20000);
+
+  it('starts a new-operation run for a valid location without the unknown-flow check', async () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    const newOpIntent: AgentIntent = {
+      action: 'new-operation',
+      location: 'billing',
+      instruction: 'Let a customer request a refund.',
+    };
+
+    const id = manager.start(newOpIntent);
+    expect(typeof id).toBe('string');
+
+    const events = await collectUntilDone(manager, id);
+    expect(events[0]).toEqual({ type: 'started' });
+    expect(events[events.length - 1].type).toBe('done');
+  });
+
+  it('rejects a new-operation with a location that tries to escape apisDir', () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    const badIntent: AgentIntent = {
+      action: 'new-operation',
+      location: '../../etc',
+      instruction: 'x',
+    };
+    expect(() => manager.start(badIntent)).toThrow(/invalid location/i);
+  });
+
+  it('starts a cover-operation run for a known flowId, resolving relPath like edit-flow', async () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    const coverIntent: AgentIntent = {
+      action: 'cover-operation',
+      flowId: 'hello',
+      instruction: 'Cover every branch with scenarios.',
+    };
+
+    const id = manager.start(coverIntent);
+    expect(typeof id).toBe('string');
+
+    const events = await collectUntilDone(manager, id);
+    expect(events[0]).toEqual({ type: 'started' });
+    expect(events[events.length - 1].type).toBe('done');
+  });
+
+  it('rejects a cover-operation run for an unknown flow', () => {
+    const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+    const badIntent: AgentIntent = { action: 'cover-operation', flowId: 'nope', instruction: 'x' };
+    expect(() => manager.start(badIntent)).toThrow(/unknown flow/i);
+  });
+
+  it('routes to spawnClaude when agent is "claude", using EMBERFLOW_CLAUDE_BIN', async () => {
+    process.env.EMBERFLOW_CLAUDE_BIN = fakeClaudeWriterPath;
+    try {
+      const manager = new AgentRunManager(projectDir, flowsDir, pathOf);
+      const id = manager.start(intent, { agent: 'claude' });
+
+      const events = await collectUntilDone(manager, id);
+      expect(events[0]).toEqual({ type: 'started' });
+      expect(events[events.length - 1].type).toBe('done');
+
+      const { files } = manager.diff(id)!;
+      expect(files).toContain('flows/hello.json');
+      expect(readFileSync(join(projectDir, 'flows', 'hello.json'), 'utf8')).toBe('agent was here\n');
+    } finally {
+      delete process.env.EMBERFLOW_CLAUDE_BIN;
+    }
+  });
+});

package/server/agents/runManager.ts

@@ -0,0 +1,286 @@
+import { randomUUID } from 'node:crypto';
+import { changedFiles, diffSince, isGitRepo, revert as gitRevert, snapshot, type GitSnapshot } from './gitScope';
+import { buildPrompt, type AgentIntent, type AvailableNode } from './prompt';
+import type { InfrastructureManifest } from '../infrastructure';
+import { spawnCodex, type SpawnedAgent } from './codexAdapter';
+import { spawnClaude } from './claudeAdapter';
+import type { AgentEvent, AgentKind } from './types';
+import { isPathWithin } from '../pathSafety';
+
+export interface StartAgentOptions {
+  agent?: AgentKind;
+  model?: string;
+  reasoning?: 'low' | 'medium' | 'high';
+}
+
+/** Thrown by `start()`; `status` maps directly onto the HTTP status the endpoint should return. */
+export class AgentStartError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = 'AgentStartError';
+  }
+}
+
+type Listener = (event: AgentEvent) => void;
+
+/** Max number of terminal (done/error) runs kept around for diff/revert/replay before eviction. */
+const MAX_TERMINAL_RUNS = 20;
+
+/**
+ * Rejects anything that isn't a safe flow id. Operation ids are path-style
+ * (e.g. `"billing/charge"`, the on-disk relative path), so a slash-separated
+ * id is legitimate and must be allowed — only traversal (`..` segments),
+ * absolute ids, backslashes, and empty segments are rejected, and the file it
+ * resolves to must stay inside `apisDir`. Defense in depth — the agent
+ * sandbox already confines actual writes — but it keeps a bogus flowId like
+ * `"../../etc/passwd"` from ever becoming an existence-probe against paths
+ * outside apisDir.
+ */
+function isSafeFlowId(flowId: string, apisDir: string): boolean {
+  if (!flowId) return false;
+  return isPathWithin(apisDir, `${flowId}.json`);
+}
+
+/**
+ * Resolves a `new-operation` intent's user-supplied `location` (a folder path
+ * under `apisDir`, e.g. `"billing"` or `"billing/charges"`) to the directory
+ * the new operation file should be created in. An empty string or `"default"`
+ * both mean "the default API".
+ */
+function resolveLocationDir(location: string): string {
+  const trimmed = location.trim();
+  return trimmed === '' ? 'default' : trimmed;
+}
+
+/** Same defense-in-depth as `isSafeFlowId`, but for a target *directory* rather than a flow file. */
+function isSafeLocationDir(dir: string, apisDir: string): boolean {
+  return isPathWithin(apisDir, dir);
+}
+
+interface Run {
+  id: string;
+  snapshot: GitSnapshot;
+  adapter: SpawnedAgent;
+  buffer: AgentEvent[];
+  listeners: Set<Listener>;
+  status: 'running' | 'done' | 'error';
+}
+
+/**
+ * Owns in-flight coding-agent runs for a single project: spawns the adapter,
+ * buffers its events for SSE replay + live subscribers, and exposes
+ * git-scoped diff/revert against the snapshot taken at run start. One active
+ * run per project at a time.
+ */
+export class AgentRunManager {
+  private readonly runs = new Map<string, Run>();
+  private activeRunId: string | null = null;
+
+  constructor(
+    private readonly projectDir: string,
+    private readonly apisDir: string,
+    private readonly pathOf: (id: string) => string | undefined,
+    /**
+     * Getter (not a static list) so the prompt always reflects the
+     * currently-registered node types, even if the registry is populated or
+     * changes after this manager is constructed.
+     */
+    private readonly availableNodes: () => AvailableNode[] = () => [],
+    /** The loaded project's authored language (`ProjectConfig.language`,
+     *  explicit-or-inferred), threaded into every prompt this manager builds.
+     *  Defaults to 'typescript' — the Emberflow repo itself, when constructed
+     *  without a loaded consumer project. */
+    private readonly projectLanguage: 'javascript' | 'typescript' = 'typescript',
+    /**
+     * Getter (not a static value) for the loaded `emberflow/infrastructure.json`
+     * manifest, so every prompt reflects the manifest currently on disk — a scout
+     * run mid-session updates what later runs see. Returns null when the project
+     * hasn't been scouted or the file is malformed. Injected as a prompt preamble
+     * so agents REUSE known infrastructure instead of inventing parallel config.
+     */
+    private readonly infrastructure: () => InfrastructureManifest | null = () => null,
+  ) {}
+
+  /** Validates the project + flow, snapshots git, spawns the adapter, and returns the new run's id. */
+  start(intent: AgentIntent, opts: StartAgentOptions = {}): string {
+    if (this.activeRunId) {
+      throw new AgentStartError('An agent run is already active for this project', 409);
+    }
+    if (!isGitRepo(this.projectDir)) {
+      throw new AgentStartError(`${this.projectDir} is not a git repository`, 400);
+    }
+
+    // `new-operation` creates a brand-new flow, so there's no existing
+    // flowId to validate against pathOf — it validates `location` instead.
+    // `setup-auth` targets an environment, not a flow file, and
+    // `setup-environments` targets the environments file itself, so
+    // neither has a relPath to resolve.
+    let relPath: string;
+    if (intent.action === 'new-operation') {
+      const dir = resolveLocationDir(intent.location);
+      if (!isSafeLocationDir(dir, this.apisDir)) {
+        throw new AgentStartError('Invalid location', 400);
+      }
+      relPath = dir;
+    } else if (
+      intent.action === 'setup-auth' ||
+      intent.action === 'setup-environments' ||
+      intent.action === 'scout-infrastructure'
+    ) {
+      // No flow file: setup-auth targets an environment, setup-environments the
+      // environments file, and scout-infrastructure reads the whole project and
+      // writes emberflow/infrastructure.json — none has a relPath to resolve.
+      relPath = '';
+    } else if (intent.action === 'ask') {
+      // `ask`'s flowId is optional: with one, resolve the op's relPath like
+      // edit-flow does; without, resolve to the apis root (empty relPath) —
+      // there's no specific operation file to point the prompt at.
+      if (intent.flowId) {
+        if (!isSafeFlowId(intent.flowId, this.apisDir)) {
+          throw new AgentStartError('Invalid flowId', 400);
+        }
+        const found = this.pathOf(intent.flowId);
+        if (!found) {
+          throw new AgentStartError(`Unknown flow: ${intent.flowId}`, 400);
+        }
+        relPath = found;
+      } else {
+        relPath = '';
+      }
+    } else {
+      if (!isSafeFlowId(intent.flowId, this.apisDir)) {
+        throw new AgentStartError('Invalid flowId', 400);
+      }
+      const found = this.pathOf(intent.flowId);
+      if (!found) {
+        throw new AgentStartError(`Unknown flow: ${intent.flowId}`, 400);
+      }
+      relPath = found;
+    }
+
+    this.pruneTerminalRuns();
+
+    const snap = snapshot(this.projectDir);
+    const prompt = buildPrompt(
+      intent,
+      this.apisDir,
+      relPath,
+      this.availableNodes(),
+      this.projectLanguage,
+      this.infrastructure(),
+    );
+    const adapter =
+      opts.agent === 'claude'
+        ? spawnClaude(prompt, this.projectDir, {
+            model: opts.model,
+            bin: process.env.EMBERFLOW_CLAUDE_BIN,
+          })
+        : spawnCodex(prompt, this.projectDir, {
+            model: opts.model,
+            reasoning: opts.reasoning ?? 'medium',
+            bin: process.env.EMBERFLOW_CODEX_BIN,
+          });
+
+    const id = randomUUID();
+    const run: Run = { id, snapshot: snap, adapter, buffer: [], listeners: new Set(), status: 'running' };
+    this.runs.set(id, run);
+    this.activeRunId = id;
+
+    void this.consume(run);
+
+    return id;
+  }
+
+  /** Drains the adapter's events into the run's buffer, fanning each out to live subscribers. */
+  private async consume(run: Run): Promise<void> {
+    const emit = (event: AgentEvent): void => {
+      run.buffer.push(event);
+      for (const listener of run.listeners) listener(event);
+    };
+
+    try {
+      for await (const event of run.adapter.events) {
+        // Clear the busy slot as soon as a terminal event is *observed*, not
+        // once the adapter's generator fully drains — a subscriber reacting
+        // synchronously to `done`/`error` (e.g. by starting a new run) must
+        // not race against this loop's own bookkeeping.
+        if (event.type === 'done') {
+          run.status = 'done';
+          this.clearActive(run.id);
+        } else if (event.type === 'error') {
+          run.status = 'error';
+          this.clearActive(run.id);
+        }
+        emit(event);
+      }
+    } catch (err) {
+      run.status = 'error';
+      this.clearActive(run.id);
+      emit({ type: 'error', text: err instanceof Error ? err.message : String(err) });
+    } finally {
+      this.clearActive(run.id);
+    }
+  }
+
+  private clearActive(id: string): void {
+    if (this.activeRunId === id) this.activeRunId = null;
+  }
+
+  /** Replay the buffer to the listener, then stream live events. Returns an unsubscribe fn. */
+  subscribe(id: string, listener: Listener): (() => void) | undefined {
+    const run = this.runs.get(id);
+    if (!run) return undefined;
+    for (const event of run.buffer) listener(event);
+    run.listeners.add(listener);
+    return () => run.listeners.delete(listener);
+  }
+
+  has(id: string): boolean {
+    return this.runs.has(id);
+  }
+
+  diff(id: string): { diff: string; files: string[] } | undefined {
+    const run = this.runs.get(id);
+    if (!run) return undefined;
+    return {
+      diff: diffSince(this.projectDir, run.snapshot),
+      files: changedFiles(this.projectDir, run.snapshot),
+    };
+  }
+
+  revert(id: string): { reverted: string[] } | undefined {
+    const run = this.runs.get(id);
+    if (!run) return undefined;
+    const files = changedFiles(this.projectDir, run.snapshot);
+    gitRevert(this.projectDir, run.snapshot, files);
+    return { reverted: files };
+  }
+
+  cancel(id: string): boolean {
+    const run = this.runs.get(id);
+    if (!run) return false;
+    run.adapter.cancel();
+    return true;
+  }
+
+  /**
+   * Evicts oldest terminal (done|error) runs beyond MAX_TERMINAL_RUNS so the
+   * `runs` map — and each run's full event buffer — doesn't grow unbounded
+   * over a long-lived server process. The active run (if any) is never
+   * evicted; insertion order on the Map gives us oldest-first for free.
+   */
+  private pruneTerminalRuns(): void {
+    const terminalIds: string[] = [];
+    for (const [id, run] of this.runs) {
+      if (run.status === 'done' || run.status === 'error') terminalIds.push(id);
+    }
+    const excess = terminalIds.length - MAX_TERMINAL_RUNS;
+    if (excess <= 0) return;
+    for (const id of terminalIds.slice(0, excess)) {
+      this.runs.delete(id);
+    }
+  }
+}

package/server/agents/types.ts

@@ -0,0 +1,17 @@
+export type AgentKind = 'codex' | 'claude';
+
+export interface AgentEvent {
+  type: 'started' | 'message' | 'command' | 'mcp' | 'approval-request' | 'done' | 'error';
+  text?: string; // message/error text
+  command?: string; // for 'command'
+  commandStatus?: 'in_progress' | 'completed' | 'failed';
+  exitCode?: number | null; // for 'command'
+  output?: string; // command aggregated output OR an mcp call's result
+  toolUseId?: string; // for 'command'/'mcp' (Claude) — correlates a tool_use with its later tool_result
+  approvalId?: string; // for 'approval-request' (Claude)
+  usage?: Record<string, number>; // for 'done'
+  // ── 'mcp': the agent called an Emberflow MCP tool (run/list/delete/etc.) ──
+  mcpServer?: string; // e.g. 'emberflow'
+  mcpTool?: string; // e.g. 'run_operation'
+  mcpStatus?: 'in_progress' | 'completed' | 'failed';
+}