@xdelivered/emberflow 0.2.0 → 0.5.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/engine/registry.sourceRef.test.ts

@@ -0,0 +1,112 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterAll, describe, expect, it } from 'vitest';
+import { NodeRegistry } from './registry';
+
+// realpath: tmpdir() on macOS returns a /var/folders symlink; module loaders
+// report the resolved /private/var path, so compare against the real path.
+const tmp = realpathSync(mkdtempSync(join(tmpdir(), 'registry-sourceref-')));
+afterAll(() => rmSync(tmp, { recursive: true, force: true }));
+
+describe('NodeRegistry sourceRef capture', () => {
+  it('does not capture by default (browser registries never pay)', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'A', label: 'A' }, async () => ({}));
+    expect(r.getSourceRef('A')).toBeUndefined();
+  });
+
+  it('explicit opts.sourceRef wins over automatic capture', () => {
+    const r = new NodeRegistry({ captureSourceRefs: true });
+    r.register({ type: 'B', label: 'B' }, async () => ({}), {
+      sourceRef: { file: '/x/custom.ts', line: 7 },
+    });
+    expect(r.getSourceRef('B')).toEqual({ file: '/x/custom.ts', line: 7 });
+  });
+
+  it('explicit opts.sourceRef is stored even when capture is off', () => {
+    const r = new NodeRegistry();
+    r.register({ type: 'B2', label: 'B2' }, async () => ({}), {
+      sourceRef: { file: '/x/other.mjs', line: 2 },
+    });
+    expect(r.getSourceRef('B2')).toEqual({ file: '/x/other.mjs', line: 2 });
+  });
+
+  it('captures the exact caller file and line from an imported .mjs module (real loader)', () => {
+    // Runs under a child tsx process: vitest's vite-node transform wraps
+    // dynamically imported modules and shifts line numbers, so in-process
+    // assertions would test the transform, not the capture. tsx/node load
+    // a plain .mjs verbatim — that is what production does.
+    const fixture = join(tmp, 'nodes.mjs');
+    writeFileSync(
+      fixture,
+      [
+        '// fixture module that registers a node — the register() call is on line 3',
+        'export function registerFixtureNodes(registry) {',
+        '  registry.register({ type: "FixtureNode", label: "Fixture" }, async () => ({ ok: true }));',
+        '}',
+        '',
+      ].join('\n'),
+    );
+    const registryPath = fileURLToPath(new URL('./registry.ts', import.meta.url));
+    const driver = join(tmp, 'driver.mjs');
+    writeFileSync(
+      driver,
+      [
+        `import { NodeRegistry } from ${JSON.stringify(pathToFileURL(registryPath).href)};`,
+        `import { registerFixtureNodes } from ${JSON.stringify(pathToFileURL(fixture).href)};`,
+        'const r = new NodeRegistry({ captureSourceRefs: true });',
+        'registerFixtureNodes(r);',
+        "console.log(JSON.stringify(r.getSourceRef('FixtureNode') ?? null));",
+        '',
+      ].join('\n'),
+    );
+    const out = execFileSync('npx', ['tsx', driver], {
+      cwd: fileURLToPath(new URL('../..', import.meta.url)),
+      encoding: 'utf8',
+      timeout: 30_000,
+    });
+    const ref = JSON.parse(out.trim().split('\n').pop()!) as { file: string; line?: number } | null;
+    expect(ref).not.toBeNull();
+    expect(ref!.file).toBe(fixture);
+    expect(ref!.line).toBe(3);
+  }, 40_000);
+
+  it('captures a plain path (no file:// prefix, no query string) from TS caller frames', () => {
+    const r = new NodeRegistry({ captureSourceRefs: true });
+    r.register({ type: 'C', label: 'C' }, async () => ({}));
+    const ref = r.getSourceRef('C');
+    expect(ref).toBeDefined();
+    expect(ref!.file).toContain('registry.sourceRef.test');
+    expect(ref!.file.startsWith('file://')).toBe(false);
+    expect(ref!.file).not.toContain('?');
+    expect(typeof ref!.line).toBe('number');
+  });
+
+  it('restores Error.prepareStackTrace after capture', () => {
+    const sentinel = (): string => 'sentinel';
+    const original = Error.prepareStackTrace;
+    Error.prepareStackTrace = sentinel as unknown as typeof Error.prepareStackTrace;
+    try {
+      const r = new NodeRegistry({ captureSourceRefs: true });
+      r.register({ type: 'D', label: 'D' }, async () => ({}));
+      expect(Error.prepareStackTrace).toBe(sentinel);
+    } finally {
+      Error.prepareStackTrace = original;
+    }
+  });
+
+  it('adopt() and withSameNodes() carry sourceRefs', () => {
+    const a = new NodeRegistry({ captureSourceRefs: true });
+    a.register({ type: 'E', label: 'E' }, async () => ({}), {
+      sourceRef: { file: '/p/e.mjs', line: 1 },
+    });
+    const shared = a.withSameNodes();
+    expect(shared.getSourceRef('E')).toEqual({ file: '/p/e.mjs', line: 1 });
+    const b = new NodeRegistry();
+    b.adopt(a);
+    expect(b.getSourceRef('E')).toEqual({ file: '/p/e.mjs', line: 1 });
+  });
+});

package/src/engine/registry.ts

@@ -5,15 +5,98 @@ export interface RegisteredNode {
   implementation: NodeImplementation;
 }
 
+/** Where a node was registered from: absolute file path + 1-based line of the register() call. */
+export interface SourceRef {
+  file: string;
+  line?: number;
+}
+
+export interface RegisterOptions {
+  /** Explicit provenance escape hatch — wins over automatic capture. */
+  sourceRef?: SourceRef;
+}
+
+/**
+ * V8 stack-frame shape (structural — this module must stay browser-safe, so
+ * no @types/node CallSite import).
+ */
+interface V8CallSite {
+  getFileName?: () => string | null | undefined;
+  getLineNumber?: () => number | null | undefined;
+}
+
+/**
+ * Read the CALLER's file:line via a one-frame V8 stack capture.
+ * `Error.prepareStackTrace` is swapped for the duration of a single `new
+ * Error()` and restored in `finally`, so source-map hooks installed by
+ * tsx/vitest are back in place immediately. Frames arrive either as
+ * `file:///abs/path.ts` URLs (ESM) or plain absolute paths (CJS/transpilers);
+ * both normalize to a plain path. Returns undefined on any non-V8 runtime or
+ * anonymous/eval frames — capture is best-effort by design.
+ */
+function captureCallerSourceRef(skip: (...args: never[]) => unknown): SourceRef | undefined {
+  if (typeof Error.captureStackTrace !== 'function') return undefined;
+  const original = Error.prepareStackTrace;
+  try {
+    Error.prepareStackTrace = (_err, frames) => frames;
+    const holder: { stack?: unknown } = {};
+    Error.captureStackTrace(holder as Error, skip);
+    const frames = holder.stack;
+    if (!Array.isArray(frames) || frames.length === 0) return undefined;
+    const frame = frames[0] as V8CallSite;
+    const raw = typeof frame.getFileName === 'function' ? frame.getFileName() : undefined;
+    if (typeof raw !== 'string' || raw.length === 0) return undefined;
+    const lineRaw = typeof frame.getLineNumber === 'function' ? frame.getLineNumber() : undefined;
+    const line = typeof lineRaw === 'number' && lineRaw > 0 ? lineRaw : undefined;
+    let file = raw;
+    if (file.startsWith('file://')) {
+      // No node:url here (browser-safe module): URL parsing covers the
+      // file:///abs/path form these frames take on POSIX platforms.
+      try {
+        file = decodeURIComponent(new URL(file).pathname);
+      } catch {
+        return undefined;
+      }
+    }
+    // Loaders (vite-node hot imports) may suffix ?t=... cache-busters.
+    const q = file.indexOf('?');
+    if (q !== -1) file = file.slice(0, q);
+    return line !== undefined ? { file, line } : { file };
+  } catch {
+    return undefined;
+  } finally {
+    Error.prepareStackTrace = original;
+  }
+}
+
 export class NodeRegistry {
   nodes = new Map<string, RegisteredNode>();
   sources = new Map<string, string>();
+  /** Registration provenance per node type. Populated only when capture is on or opts.sourceRef given. */
+  sourceRefs = new Map<string, SourceRef>();
+  /** Types the RUNNER flagged builtin (registered from the package, not the project). */
+  builtinTypes = new Set<string>();
+  /** Automatic caller capture is opt-in (server registries only) so browser registries never pay/leak. */
+  private captureSourceRefs: boolean;
+
+  constructor(opts?: { captureSourceRefs?: boolean }) {
+    this.captureSourceRefs = opts?.captureSourceRefs ?? false;
+  }
 
-  register(definition: NodeDefinition, implementation: NodeImplementation): void {
+  register(definition: NodeDefinition, implementation: NodeImplementation, opts?: RegisterOptions): void {
     if (this.nodes.has(definition.type)) {
       throw new Error(`Node type already registered: ${definition.type}`);
     }
     this.nodes.set(definition.type, { definition, implementation });
+    const ref =
+      opts?.sourceRef ??
+      (this.captureSourceRefs ? captureCallerSourceRef(this.register) : undefined);
+    if (ref) this.sourceRefs.set(definition.type, ref);
+  }
+
+  /** Where `type` was registered from, when known. */
+  getSourceRef(type: string): SourceRef | undefined {
+    return this.sourceRefs.get(type);
   }
 
   get(type: string): RegisteredNode {
@@ -36,6 +119,13 @@ export class NodeRegistry {
   adopt(other: NodeRegistry): void {
     this.nodes = other.nodes;
     this.sources = other.sources;
+    this.sourceRefs = other.sourceRefs;
+    this.builtinTypes = other.builtinTypes;
+  }
+
+  /** Whether the runner flagged `type` as a package built-in (no servable source file). */
+  isBuiltin(type: string): boolean {
+    return this.builtinTypes.has(type);
   }
 
   list(): NodeDefinition[] {
@@ -47,7 +137,16 @@ export class NodeRegistry {
    * implementation is a stub that fails loudly if browser-executed — such
    * nodes run on the server. Never overwrites a real registration.
    */
-  registerDefinition(definition: NodeDefinition, source?: string): void {
+  registerDefinition(
+    definition: NodeDefinition,
+    source?: string,
+    opts?: { sourceRef?: SourceRef; builtin?: boolean },
+  ): void {
+    // Provenance is recorded even for already-registered types: the studio's
+    // bundled built-ins are real registrations, and the runner's builtin flag
+    // (or a project sourceRef shadowing one) must still land on them.
+    if (opts?.sourceRef) this.sourceRefs.set(definition.type, opts.sourceRef);
+    if (opts?.builtin) this.builtinTypes.add(definition.type);
     if (this.nodes.has(definition.type)) return;
     this.nodes.set(definition.type, {
       definition,
@@ -75,6 +174,8 @@ export class NodeRegistry {
     const next = new NodeRegistry();
     next.nodes = this.nodes;
     next.sources = this.sources;
+    next.sourceRefs = this.sourceRefs;
+    next.builtinTypes = this.builtinTypes;
     return next;
   }
 }

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');
+}