@xdelivered/emberflow 0.2.0 → 0.4.0

package/src/engine/executor.ts

@@ -60,11 +60,12 @@ function envRefName(value: unknown): string | undefined {
 function resolveEnvRef(name: string, vars: Record<string, string>): string {
   if (!(name in vars)) {
     // The most common cause is not a missing key but a run with NO environment
-    // at all: the in-tab engine has no vars, so flows seeded with $env refs
-    // need the server runner. Say so, instead of a bare "missing".
+    // at all: an environment-less run (e.g. a scenario test) has no vars, so
+    // flows seeded with $env refs need a real environment. Say so, instead of a
+    // bare "missing".
     const hint =
       Object.keys(vars).length === 0
-        ? ' — this run has no environment variables (in-tab/browser runs never do; make sure the runner is online and the engine is set to Server or Auto)'
+        ? ' — this run has no environment variables; run it against an environment that defines them'
         : '';
     throw new Error(`Missing environment variable: ${name}${hint}`);
   }

package/src/lib/guidedQuestions.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it } from 'vitest';
+import {
+  composeAnsweredSubset,
+  extractGuidedQuestions,
+  resolveGuidedAnswers,
+} from './guidedQuestions';
+import type { GuidedQuestion } from './guidedQuestions';
+
+const block = (json: string) => '```emberflow-questions\n' + json + '\n```';
+
+describe('extractGuidedQuestions', () => {
+  it('happy path: strips a trailing block and normalizes string options', () => {
+    const text =
+      'Steps 1–4 are done.\n\n' +
+      block('{"questions":[{"id":"envs","text":"Which environments?","options":["dev + prod","dev + staging + prod"],"custom":true}]}');
+    const { stripped, questions } = extractGuidedQuestions(text);
+    expect(stripped).toBe('Steps 1–4 are done.');
+    expect(questions).toEqual([
+      {
+        id: 'envs',
+        text: 'Which environments?',
+        options: [{ label: 'dev + prod' }, { label: 'dev + staging + prod' }],
+        custom: true,
+      },
+    ]);
+  });
+
+  it('tolerates trailing whitespace/newlines after the closing fence', () => {
+    const text =
+      'Done.\n' + block('{"questions":[{"id":"a","text":"Q?","options":["x"]}]}') + '  \n\n';
+    const { stripped, questions } = extractGuidedQuestions(text);
+    expect(stripped).toBe('Done.');
+    expect(questions).toHaveLength(1);
+  });
+
+  it('no block: returns the text unchanged with null questions', () => {
+    const text = 'Just prose, with `inline code` and a ```js\nfence\n``` in the middle. The end.';
+    expect(extractGuidedQuestions(text)).toEqual({ stripped: text, questions: null });
+  });
+
+  it('malformed JSON: leaves the text untouched so nothing is silently lost', () => {
+    const text = 'Prose.\n' + block('{"questions": [oops');
+    expect(extractGuidedQuestions(text)).toEqual({ stripped: text, questions: null });
+  });
+
+  it('invalid shape (questions not an array / bad entries): text untouched, null', () => {
+    for (const json of [
+      '{"questions":"nope"}',
+      '{}',
+      '{"questions":[]}',
+      '{"questions":[{"id":"a","options":["x"]}]}', // missing text
+      '{"questions":[{"id":"a","text":"Q?","options":[42]}]}', // bad option
+      '{"questions":[{"id":"a","text":"Q?","options":[]}]}', // unanswerable
+    ]) {
+      const text = 'Prose.\n' + block(json);
+      expect(extractGuidedQuestions(text)).toEqual({ stripped: text, questions: null });
+    }
+  });
+
+  it('block not at the end: ignored (contract puts it last)', () => {
+    const text =
+      block('{"questions":[{"id":"a","text":"Q?","options":["x"]}]}') + '\nTrailing prose after.';
+    expect(extractGuidedQuestions(text)).toEqual({ stripped: text, questions: null });
+  });
+
+  it('mixed string and object options, including a finish action', () => {
+    const text = block(
+      '{"questions":[{"id":"first-build","text":"What first?","options":["An op",{"label":"Just look around","action":"finish"}],"custom":true}]}',
+    );
+    const { stripped, questions } = extractGuidedQuestions(text);
+    expect(stripped).toBe('');
+    expect(questions).toEqual([
+      {
+        id: 'first-build',
+        text: 'What first?',
+        options: [{ label: 'An op' }, { label: 'Just look around', action: 'finish' }],
+        custom: true,
+      },
+    ]);
+  });
+
+  it('drops unknown option actions rather than forwarding them', () => {
+    const { questions } = extractGuidedQuestions(
+      block('{"questions":[{"id":"a","text":"Q?","options":[{"label":"x","action":"explode"}]}]}'),
+    );
+    expect(questions).toEqual([{ id: 'a', text: 'Q?', options: [{ label: 'x' }] }]);
+  });
+
+  it('keeps a submit action on an option', () => {
+    const { questions } = extractGuidedQuestions(
+      block('{"questions":[{"id":"a","text":"Q?","options":[{"label":"Go","action":"submit"}]}]}'),
+    );
+    expect(questions).toEqual([
+      { id: 'a', text: 'Q?', options: [{ label: 'Go', action: 'submit' }] },
+    ]);
+  });
+
+  it('keeps a non-empty why (trimmed); drops empty/whitespace/non-string ones', () => {
+    const { questions } = extractGuidedQuestions(
+      block('{"questions":[{"id":"a","text":"Q?","options":["x"],"why":"  So mocks stay safe.  "}]}'),
+    );
+    expect(questions).toEqual([
+      { id: 'a', text: 'Q?', options: [{ label: 'x' }], why: 'So mocks stay safe.' },
+    ]);
+
+    for (const why of ['""', '"   "', '42', 'null', '["nope"]']) {
+      const { questions: qs } = extractGuidedQuestions(
+        block(`{"questions":[{"id":"a","text":"Q?","options":["x"],"why":${why}}]}`),
+      );
+      expect(qs).toEqual([{ id: 'a', text: 'Q?', options: [{ label: 'x' }] }]);
+    }
+  });
+});
+
+const QUESTIONS: GuidedQuestion[] = [
+  { id: 'envs', text: 'Which environments?', options: [{ label: 'dev + prod' }], custom: true },
+  {
+    id: 'first-build',
+    text: 'What do you want to build first?',
+    options: [{ label: 'Just look around', action: 'finish' }],
+    custom: true,
+  },
+];
+
+describe('resolveGuidedAnswers', () => {
+  it('incomplete until every question has a pill or custom text', () => {
+    expect(resolveGuidedAnswers(QUESTIONS, {})).toEqual({ kind: 'incomplete' });
+    expect(
+      resolveGuidedAnswers(QUESTIONS, { envs: { option: { label: 'dev + prod' } } }),
+    ).toEqual({ kind: 'incomplete' });
+    // Whitespace-only custom text does not count as an answer.
+    expect(
+      resolveGuidedAnswers(QUESTIONS, {
+        envs: { option: { label: 'dev + prod' } },
+        'first-build': { text: '   ' },
+      }),
+    ).toEqual({ kind: 'incomplete' });
+  });
+
+  it('composes one "<question>: <answer>" line per question', () => {
+    expect(
+      resolveGuidedAnswers(QUESTIONS, {
+        envs: { option: { label: 'dev + prod' } },
+        'first-build': { text: ' a health-check op ' },
+      }),
+    ).toEqual({
+      kind: 'send',
+      text: 'Which environments?: dev + prod\nWhat do you want to build first?: a health-check op',
+    });
+  });
+
+  it('any picked finish option resolves to finish — nothing is sent', () => {
+    expect(
+      resolveGuidedAnswers(QUESTIONS, {
+        envs: { option: { label: 'dev + prod' } },
+        'first-build': { option: { label: 'Just look around', action: 'finish' } },
+      }),
+    ).toEqual({ kind: 'finish' });
+  });
+
+  describe('first-build routing', () => {
+    const FIRST_BUILD_ONLY: GuidedQuestion[] = [QUESTIONS[1]];
+
+    it('sole first-build question answered with custom text routes to build', () => {
+      expect(
+        resolveGuidedAnswers(FIRST_BUILD_ONLY, {
+          'first-build': { text: ' an invoicing API ' },
+        }),
+      ).toEqual({ kind: 'build', text: 'an invoicing API' });
+    });
+
+    it('sole first-build question answered with a plain pill still sends', () => {
+      const q: GuidedQuestion[] = [
+        { id: 'first-build', text: 'What first?', options: [{ label: 'An op' }], custom: true },
+      ];
+      expect(resolveGuidedAnswers(q, { 'first-build': { option: { label: 'An op' } } })).toEqual({
+        kind: 'send',
+        text: 'What first?: An op',
+      });
+    });
+
+    it('first-build custom text alongside OTHER answers keeps the composed send', () => {
+      expect(
+        resolveGuidedAnswers(QUESTIONS, {
+          envs: { option: { label: 'dev + prod' } },
+          'first-build': { text: 'an invoicing API' },
+        }),
+      ).toEqual({
+        kind: 'send',
+        text: 'Which environments?: dev + prod\nWhat do you want to build first?: an invoicing API',
+      });
+    });
+
+    it('a sole non-first-build question with custom text still sends', () => {
+      expect(
+        resolveGuidedAnswers([QUESTIONS[0]], { envs: { text: 'dev only' } }),
+      ).toEqual({ kind: 'send', text: 'Which environments?: dev only' });
+    });
+  });
+});
+
+describe('composeAnsweredSubset', () => {
+  it('composes only the answered questions, skipping unanswered ones', () => {
+    expect(
+      composeAnsweredSubset(QUESTIONS, {
+        'first-build': { option: { label: 'Skip ahead', action: 'submit' } },
+      }),
+    ).toBe('What do you want to build first?: Skip ahead');
+  });
+
+  it('includes pill and trimmed custom-text answers in question order', () => {
+    expect(
+      composeAnsweredSubset(QUESTIONS, {
+        'first-build': { text: ' a health-check op ' },
+        envs: { option: { label: 'dev + prod' } },
+      }),
+    ).toBe('Which environments?: dev + prod\nWhat do you want to build first?: a health-check op');
+  });
+
+  it('whitespace-only custom text is not an answer; nothing answered composes empty', () => {
+    expect(composeAnsweredSubset(QUESTIONS, { envs: { text: '   ' } })).toBe('');
+    expect(composeAnsweredSubset(QUESTIONS, {})).toBe('');
+  });
+});

package/src/lib/guidedQuestions.ts

@@ -0,0 +1,181 @@
+/**
+ * The guided-setup agent ends messages that need the user's input with a fenced
+ * ```emberflow-questions block (see server/agents/prompt.ts, 'guided-setup'):
+ * JSON describing clickable questions the studio renders as a form instead of
+ * a raw code block. This module owns the contract's client side — extraction,
+ * defensive parsing/normalization, and turning the user's picks back into the
+ * plaintext continuation message the agent expects.
+ */
+
+export interface GuidedQuestionOption {
+  label: string;
+  /** 'finish' ends onboarding client-side instead of sending a run; 'submit'
+   *  records the answer and immediately sends whatever has been answered so
+   *  far (a subset — unanswered questions are simply skipped). */
+  action?: 'finish' | 'submit';
+}
+
+export interface GuidedQuestion {
+  id: string;
+  text: string;
+  options: GuidedQuestionOption[];
+  /** Also offer a free-text field alongside the clickable options. */
+  custom?: boolean;
+  /** One-line rationale rendered under the question text. */
+  why?: string;
+}
+
+/** Trailing fenced block: ```emberflow-questions\n<json>\n``` and then nothing
+ *  but whitespace. The prompt contract puts the block LAST; anything after the
+ *  closing fence means it's not the interactive form. */
+const TRAILING_BLOCK = /```emberflow-questions[ \t]*\n([\s\S]*?)\n?```\s*$/;
+
+function normalizeOption(raw: unknown): GuidedQuestionOption | null {
+  if (typeof raw === 'string') return { label: raw };
+  if (raw && typeof raw === 'object' && typeof (raw as { label?: unknown }).label === 'string') {
+    const { label, action } = raw as { label: string; action?: unknown };
+    // Unknown actions are dropped (the option stays clickable, just inert).
+    return action === 'finish' || action === 'submit' ? { label, action } : { label };
+  }
+  return null;
+}
+
+function normalizeQuestion(raw: unknown): GuidedQuestion | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const { id, text, options, custom, why } = raw as {
+    id?: unknown;
+    text?: unknown;
+    options?: unknown;
+    custom?: unknown;
+    why?: unknown;
+  };
+  if (typeof id !== 'string' || typeof text !== 'string' || !Array.isArray(options)) return null;
+  const normalized: GuidedQuestionOption[] = [];
+  for (const o of options) {
+    const opt = normalizeOption(o);
+    if (!opt) return null;
+    normalized.push(opt);
+  }
+  // A question with no options and no free-text field is unanswerable.
+  if (normalized.length === 0 && custom !== true) return null;
+  // `why` must be a non-empty string; anything else is dropped, not fatal.
+  const rationale = typeof why === 'string' && why.trim() !== '' ? why.trim() : undefined;
+  return {
+    id,
+    text,
+    options: normalized,
+    ...(custom === true ? { custom: true } : {}),
+    ...(rationale !== undefined ? { why: rationale } : {}),
+  };
+}
+
+/**
+ * Find and strip a trailing `emberflow-questions` fenced block. Malformed JSON
+ * or an invalid shape returns the text UNTOUCHED with `questions: null` —
+ * nothing is silently lost; the stream just shows the raw block as prose.
+ */
+export function extractGuidedQuestions(text: string): {
+  stripped: string;
+  questions: GuidedQuestion[] | null;
+} {
+  const match = TRAILING_BLOCK.exec(text);
+  if (!match) return { stripped: text, questions: null };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(match[1]);
+  } catch {
+    return { stripped: text, questions: null };
+  }
+  const rawQuestions = (parsed as { questions?: unknown } | null)?.questions;
+  if (!Array.isArray(rawQuestions) || rawQuestions.length === 0) {
+    return { stripped: text, questions: null };
+  }
+  const questions: GuidedQuestion[] = [];
+  for (const q of rawQuestions) {
+    const normalized = normalizeQuestion(q);
+    if (!normalized) return { stripped: text, questions: null };
+    questions.push(normalized);
+  }
+  return { stripped: text.slice(0, match.index).replace(/\s+$/, ''), questions };
+}
+
+/** One answer per question id: a picked option OR free text (never both). */
+export type GuidedAnswers = Record<
+  string,
+  { option?: GuidedQuestionOption; text?: string } | undefined
+>;
+
+/** The agent's closing "what do you want to build first?" question — a custom
+ *  answer to it (alone) routes into the real build flow, not a continuation. */
+export const FIRST_BUILD_QUESTION_ID = 'first-build';
+
+export type GuidedSubmit =
+  | { kind: 'incomplete' }
+  /** A selected option carried action 'finish' — end onboarding, send nothing. */
+  | { kind: 'finish' }
+  /** Composed plaintext continuation: one `<question>: <answer>` line each. */
+  | { kind: 'send'; text: string }
+  /** The ONLY answer is free text on the 'first-build' question — open the
+   *  create-API flow pre-filled with the description instead of sending a run. */
+  | { kind: 'build'; text: string };
+
+/**
+ * Resolve the form's submit: every question must be answered (pill or custom
+ * text); any picked 'finish' option wins over sending. When the form's sole
+ * question is 'first-build' and it was answered with custom text (not a pill),
+ * the submit routes to the build flow instead of a continuation run. Pure so
+ * the component test can exercise the submit path without DOM interactions.
+ */
+export function resolveGuidedAnswers(
+  questions: GuidedQuestion[],
+  answers: GuidedAnswers,
+): GuidedSubmit {
+  const lines: string[] = [];
+  let finish = false;
+  for (const q of questions) {
+    const a = answers[q.id];
+    const custom = a?.text?.trim();
+    if (a?.option) {
+      if (a.option.action === 'finish') finish = true;
+      lines.push(`${q.text}: ${a.option.label}`);
+    } else if (custom) {
+      lines.push(`${q.text}: ${custom}`);
+    } else {
+      return { kind: 'incomplete' };
+    }
+  }
+  if (finish) return { kind: 'finish' };
+  // The only answered question is 'first-build' with a typed description —
+  // that's a build request, not an interview answer. Alongside OTHER answers
+  // it stays part of the composed continuation.
+  const soleBuildText =
+    questions.length === 1 && questions[0].id === FIRST_BUILD_QUESTION_ID
+      ? answers[questions[0].id]?.text?.trim()
+      : undefined;
+  if (soleBuildText && !answers[questions[0].id]?.option) {
+    return { kind: 'build', text: soleBuildText };
+  }
+  return { kind: 'send', text: lines.join('\n') };
+}
+
+/**
+ * Compose ONLY the answered questions into the same `<question>: <answer>`
+ * plaintext the full resolver sends — unanswered questions are skipped, not
+ * required. Powers a 'submit' option: clicking it records the answer and sends
+ * immediately with whatever the user has answered so far. Pure for the same
+ * reason as `resolveGuidedAnswers`.
+ */
+export function composeAnsweredSubset(
+  questions: GuidedQuestion[],
+  answers: GuidedAnswers,
+): string {
+  const lines: string[] = [];
+  for (const q of questions) {
+    const a = answers[q.id];
+    const custom = a?.text?.trim();
+    if (a?.option) lines.push(`${q.text}: ${a.option.label}`);
+    else if (custom) lines.push(`${q.text}: ${custom}`);
+  }
+  return lines.join('\n');
+}

package/src/lib/runbookModel.ts

@@ -1,6 +1,6 @@
-import type { WorkflowDefinition, WorkflowEdge } from '../engine';
-import { computeLoopRegions, topoSort, type LoopRegion } from '../engine';
-import type { NodeRegistry } from '../engine';
+import type { WorkflowDefinition, WorkflowEdge } from '../engine/types';
+import { computeLoopRegions, topoSort, type LoopRegion } from '../engine/validation';
+import type { NodeRegistry } from '../engine/registry';
 import { firstSentence, simpleNodeDescription } from './registerLens';
 
 export interface RunbookStep {

package/src/lib/runbookProjection.test.ts

@@ -209,6 +209,49 @@ describe('projectRunbook', () => {
     expect(proj.steps.get('onStep')!.tech).toBe(`#2 Http · 50ms · ERROR: ${'x'.repeat(80)}`);
   });
 
+  it('drilled view: outcome and receipt match caller-prefixed child log ids (`caller/nodeId`); undrilled does not', () => {
+    const doc = makeDoc();
+    const run = makeRun({
+      nodeStates: {
+        onStep: {
+          status: 'succeeded',
+          startedAt: '2026-01-01T00:00:00.000Z',
+          completedAt: '2026-01-01T00:00:00.100Z',
+          input: { a: 1 },
+          output: { x: 1 },
+        },
+      },
+    });
+    // How a drilled subflow child's logs arrive: nodeId prefixed with the
+    // caller chain (`sub/onStep`, nested per level).
+    const logs: LogLine[] = [
+      { timestamp: 't1', level: 'debug', runId: 'run-1', nodeId: 'sub/onStep', message: '#4 ▶ execute' },
+      { timestamp: 't2', level: 'info', runId: 'run-1', nodeId: 'sub/onStep', message: 'child outcome' },
+    ];
+
+    const drilled = projectRunbook(doc, run, logs, [], FLOW_ID, true);
+    expect(drilled.steps.get('onStep')!.outcome).toBe('child outcome');
+    expect(drilled.steps.get('onStep')!.tech).toBe('#4 Http · 100ms · in[a] → out[x]');
+
+    // Undrilled: suffix matching stays off so a parent node can never pick
+    // up a same-named child's prefixed lines.
+    const plain = projectRunbook(doc, run, logs, [], FLOW_ID);
+    expect(plain.steps.get('onStep')!.outcome).toBe('');
+    expect(plain.steps.get('onStep')!.tech).toBe('Http · 100ms · in[a] → out[x]');
+  });
+
+  it('drilled view: a plain (unprefixed) id must not suffix-match another node ending with the same segment', () => {
+    const doc = makeDoc();
+    const logs: LogLine[] = [
+      // `sub/onStep` ends with `/onStep` but NOT with `/Step` etc.; also an
+      // exact-id line for a different node must not bleed over.
+      { timestamp: 't1', level: 'info', runId: 'run-1', nodeId: 'cond', message: 'cond outcome' },
+    ];
+    const drilled = projectRunbook(doc, makeRun(), logs, [], FLOW_ID, true);
+    expect(drilled.steps.get('onStep')!.outcome).toBe('');
+    expect(drilled.steps.get('cond')!.outcome).toBe('cond outcome');
+  });
+
   it('tech line: no receipt yet means no #N prefix', () => {
     const doc = makeDoc();
     const run = makeRun({ nodeStates: { onStep: { status: 'idle' } } });

package/src/lib/runbookProjection.ts

@@ -56,10 +56,24 @@ function fieldList(value: unknown, label: string): string {
   return `${label}[${shown.join(',')}]`;
 }
 
-function lastInfoOutcome(logs: LogLine[], nodeId: string): string {
+/**
+ * Whether a log line belongs to the given node. A drilled-in subflow child's
+ * log lines carry nodeIds prefixed with the caller chain
+ * (`${callerNodeId}/${childNodeId}`, nested per level — see subflowRunner),
+ * while the drilled view's runbook uses the raw child ids, so when projecting
+ * a drilled child flow a suffix match after a slash also counts. Kept behind
+ * `drilled` so an undriled parent view can never match a child's prefixed
+ * line against a same-named parent node.
+ */
+function lineIsFor(line: LogLine, nodeId: string, drilled: boolean): boolean {
+  if (line.nodeId === nodeId) return true;
+  return drilled && !!line.nodeId && line.nodeId.endsWith(`/${nodeId}`);
+}
+
+function lastInfoOutcome(logs: LogLine[], nodeId: string, drilled: boolean): string {
   for (let i = logs.length - 1; i >= 0; i--) {
     const line = logs[i];
-    if (line.nodeId === nodeId && line.level === 'info') return line.message;
+    if (lineIsFor(line, nodeId, drilled) && line.level === 'info') return line.message;
   }
   return '';
 }
@@ -72,10 +86,10 @@ function lastInfoOutcome(logs: LogLine[], nodeId: string): string {
  * iteration); null when the node has no receipt yet (never executed).
  */
 const RECEIPT_RE = /^#(\d+) ▶ execute/;
-function receiptSeq(logs: LogLine[], nodeId: string): string | null {
+function receiptSeq(logs: LogLine[], nodeId: string, drilled: boolean): string | null {
   for (let i = logs.length - 1; i >= 0; i--) {
     const line = logs[i];
-    if (line.nodeId === nodeId && line.level === 'debug') {
+    if (lineIsFor(line, nodeId, drilled) && line.level === 'debug') {
       const match = RECEIPT_RE.exec(line.message);
       if (match) return match[1];
     }
@@ -152,6 +166,9 @@ export function projectRunbook(
   logs: LogLine[],
   history: RunHistoryEntry[],
   flowId: string,
+  /** True when projecting a drilled-in subflow child view: log lines then
+   *  also match by `…/${nodeId}` suffix (child log ids are caller-prefixed). */
+  drilled = false,
 ): RunbookProjection {
   // ── steps ──
   const steps = new Map<string, StepProjection>();
@@ -160,10 +177,13 @@ export function projectRunbook(
     const status = statusOf(state);
     // A failed node's outcome line is its error, not the last info log (which
     // may be stale from a prior successful attempt or simply absent).
-    const outcome = status === 'failed' ? state?.error || lastInfoOutcome(logs, nodeId) : lastInfoOutcome(logs, nodeId);
+    const outcome =
+      status === 'failed'
+        ? state?.error || lastInfoOutcome(logs, nodeId, drilled)
+        : lastInfoOutcome(logs, nodeId, drilled);
     const durationMs = durationOf(state);
     // `#N` receipt prefix once the node has executed; bare type name before that.
-    const seq = receiptSeq(logs, nodeId);
+    const seq = receiptSeq(logs, nodeId, drilled);
     const prefix = seq ? `#${seq} ` : '';
     const ms = `${durationMs ?? 0}ms`;
     let tech: string;

package/src/store/agentClient.ts

@@ -40,6 +40,7 @@ export type AgentIntent =
   | { action: 'setup-auth'; environment: string; instruction: string }
   | { action: 'setup-environments'; instruction: string }
   | { action: 'scout-infrastructure'; instruction: string }
+  | { action: 'guided-setup'; instruction: string }
   | { action: 'cover-operation'; flowId: string; instruction: string }
   | { action: 'ask'; flowId?: string; instruction: string };
 
@@ -63,11 +64,18 @@ export async function fetchAvailableAgents(): Promise<DetectedAgent[]> {
 
 /** POST /agent — start an agent run, returns its id. */
 export async function startAgent(intent: AgentIntent, opts?: StartAgentOptions): Promise<string> {
-  const response = await fetch(`${BASE}/agent`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ intent, ...opts }),
-  });
+  let response: Response;
+  try {
+    response = await fetch(`${BASE}/agent`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ intent, ...opts }),
+    });
+  } catch {
+    // fetch rejects with a bare "Failed to fetch" on network errors — say what
+    // that actually means here and what to do about it.
+    throw new Error('Could not reach the runner — check it is still running, then try again.');
+  }
   if (!response.ok) {
     const body = (await response.json().catch(() => ({}))) as { error?: string };
     throw new Error(body.error ?? `Failed to start agent (HTTP ${response.status})`);
@@ -84,16 +92,27 @@ export async function startAgent(intent: AgentIntent, opts?: StartAgentOptions):
  */
 export function streamAgent(agentRunId: string, onEvent: (event: AgentEvent) => void): () => void {
   const source = new EventSource(`${BASE}/agent/${agentRunId}/events`);
+  // Set once the server delivers the run's terminal event — from then on any
+  // connection-level error (the server closing the response right after) is
+  // expected, not a lost stream, so onerror must stay quiet.
+  let sawTerminal = false;
   const types: AgentEvent['type'][] = ['started', 'message', 'command', 'mcp', 'approval-request', 'done', 'error'];
   for (const type of types) {
     source.addEventListener(type, (event) => {
-      const data = JSON.parse((event as MessageEvent).data) as AgentEvent;
+      // EventSource dispatches its CONNECTION errors as `error` events too —
+      // those carry no data, unlike the server's named `event: error` payloads.
+      const raw = (event as MessageEvent).data as string | undefined;
+      if (raw === undefined) return;
+      const data = JSON.parse(raw) as AgentEvent;
       onEvent(data);
-      if (type === 'done' || type === 'error') source.close();
+      if (type === 'done' || type === 'error') {
+        sawTerminal = true;
+        source.close();
+      }
     });
   }
   source.onerror = () => {
-    if (source.readyState === EventSource.CLOSED) {
+    if (!sawTerminal && source.readyState === EventSource.CLOSED) {
       onEvent({ type: 'error', text: 'Lost connection to the agent event stream' });
     }
   };

package/src/store/apiTree.ts

@@ -71,3 +71,15 @@ export function buildApiTree(ops: OpInput[]): ApiTreeNode[] {
   tree.sort((a, b) => a.name.localeCompare(b.name));
   return tree;
 }
+
+/** Flatten an API tree into every API/folder path (e.g. 'default', 'billing', 'billing/charges'). */
+export function flattenLocations(tree: ApiTreeNode[]): string[] {
+  const paths: string[] = [];
+  const walk = (node: ApiTreeNode, prefix: string) => {
+    const path = prefix ? `${prefix}/${node.name}` : node.name;
+    paths.push(path);
+    for (const folder of node.folders) walk(folder, path);
+  };
+  for (const api of tree) walk(api, '');
+  return paths;
+}