edsger 0.57.0 → 0.58.0

package/dist/phases/output-contracts.js

@@ -897,46 +897,57 @@ You MUST end your response with a JSON object containing the code refine results
 \`\`\`
 `,
     'screen-flow': `
-**CRITICAL — Output Format**:
+**CRITICAL — How to return the result**:
 
-After finishing your investigation, emit a single fenced code block tagged \`screen_flow\` containing the structured extraction. Do not emit any other JSON blocks.
+Return the extraction by calling the MCP tool
+\`mcp__screen-flow__submit_screen_flow\` **exactly once** with three arguments:
 
-\`\`\`screen_flow
-{
-  "summary": "1-3 sentence narrative of what kind of app this is and its primary user flows",
-  "nodes": [
-    {
-      "slug": "login",
-      "name": "Login",
-      "route": "/signin",
-      "file": "src/pages/Login.tsx",
-      "kind": "page",
-      "layout": "centered",
-      "header": { "title": "Sign in", "actions": [{ "label": "Sign up", "variant": "ghost" }] },
-      "body": [
-        {
-          "type": "form",
-          "submitLabel": "Sign in",
-          "fields": [
-            { "label": "Email", "kind": "email", "required": true },
-            { "label": "Password", "kind": "password", "required": true }
-          ]
-        }
-      ]
-    }
+- \`summary\` — 1-3 sentence narrative of what kind of app this is and its primary user flows
+- \`nodes\` — array of ScreenSchema objects (every user-facing screen, modal, drawer, tab, or named state)
+- \`edges\` — array of ScreenEdge objects (transitions between screens)
+
+The tool validates the arguments against the schema. If it returns an error,
+fix the issue it describes and call the tool again. After a successful call,
+end your turn — do not also paste the same data as a fenced text block.
+
+You can also call \`mcp__screen-flow__record_progress({ phase, message })\` at
+each phase boundary (detection / routing / screens / transitions / submission)
+to keep the user informed during long runs. This is observability only — it
+does not affect the extraction.
+
+ScreenSchema fields:
+- \`slug\` (unique within the flow), \`name\`, \`route?\`, \`file?\`
+- \`kind\`: one of \`page\`, \`modal\`, \`drawer\`, \`tab\`, \`state\`
+- \`layout\`: one of \`centered\`, \`sidebar\`, \`split\`, \`list-detail\`, \`tabs\`, \`stacked\`
+- \`header?\`: \`{ title, subtitle?, back?, actions?: [{ label, variant?, icon? }] }\`
+- \`body\`: array of sections; each section \`type\` is one of \`form\`, \`list\`, \`card-grid\`, \`table\`, \`kanban\`, \`text\`, \`image\`, \`chart\`, \`stats\`, \`empty-state\`, \`tabs\`, \`custom\`
+
+ScreenEdge fields:
+- \`fromSlug\`, \`toSlug\` (both MUST appear in nodes), \`triggerLabel\`, \`triggerFile?\`
+- \`kind\`: one of \`navigate\`, \`modal\`, \`redirect\`, \`back\`
+
+Schematic example of the tool call:
+
+\`\`\`
+submit_screen_flow({
+  summary: "Two-screen demo: sign in then land on home.",
+  nodes: [
+    { slug: "login", name: "Login", route: "/signin", file: "src/pages/Login.tsx",
+      kind: "page", layout: "centered",
+      header: { title: "Sign in", actions: [{ label: "Sign up", variant: "ghost" }] },
+      body: [{ type: "form", submitLabel: "Sign in", fields: [
+        { label: "Email", kind: "email", required: true },
+        { label: "Password", kind: "password", required: true }
+      ]}]
+    },
+    { slug: "home", name: "Home", route: "/", file: "src/pages/Home.tsx",
+      kind: "page", layout: "sidebar", body: [] }
   ],
-  "edges": [
-    {
-      "fromSlug": "login",
-      "toSlug": "home",
-      "triggerLabel": "Submit credentials",
-      "triggerFile": "src/pages/Login.tsx",
-      "kind": "navigate"
-    }
+  edges: [
+    { fromSlug: "login", toSlug: "home", triggerLabel: "Submit credentials",
+      triggerFile: "src/pages/Login.tsx", kind: "navigate" }
   ]
-}
+})
 \`\`\`
-
-All node \`slug\` values must be unique. Every \`fromSlug\` / \`toSlug\` in edges must reference a slug that appears in \`nodes\`. Section \`type\` values are restricted to: \`form\`, \`list\`, \`card-grid\`, \`table\`, \`kanban\`, \`text\`, \`image\`, \`chart\`, \`stats\`, \`empty-state\`, \`tabs\`, \`custom\`. Edge \`kind\` values are restricted to: \`navigate\`, \`modal\`, \`redirect\`, \`back\`.
 `,
 };

package/dist/phases/pr-shared/agent-utils.d.ts

@@ -24,16 +24,24 @@ export declare function createPromptGenerator(prompt: string): AsyncGenerator<{
 }>;
 /**
  * Extract text content from assistant message content array.
+ *
+ * When `verbose`, also surfaces tool_use / tool_result blocks via
+ * logDebug so it's visible whether the agent is making MCP / file /
+ * bash calls — without these, a long-running session looks frozen
+ * between text emissions.
  */
 export declare function extractTextFromContent(content: any[], verbose?: boolean): string;
 /**
  * Try to parse a JSON result from agent response text.
- * Looks for ```json code blocks first, then falls back to raw JSON parsing.
- * Returns the parsed object or null on failure.
+ * Tries a custom fenceTag (e.g. ```screen_flow) first when provided, then
+ * ```json, then falls back to raw JSON parsing. Returns the parsed object or
+ * null on failure.
  */
-export declare function tryParseJsonFromResponse(responseText: string): unknown | null;
+export declare function tryParseJsonFromResponse(responseText: string, fenceTag?: string): unknown | null;
 /**
  * Extract a specific keyed result from agent response.
  * e.g., tryExtractResult(text, 'review_result') extracts the review_result key.
+ * The key is also tried as the fenced code-block tag so phases whose output
+ * contract uses a custom fence (e.g. ```screen_flow) parse correctly.
  */
 export declare function tryExtractResult(responseText: string, key: string): unknown | null;

package/dist/phases/pr-shared/agent-utils.js

@@ -23,6 +23,11 @@ export async function* createPromptGenerator(prompt) {
 }
 /**
  * Extract text content from assistant message content array.
+ *
+ * When `verbose`, also surfaces tool_use / tool_result blocks via
+ * logDebug so it's visible whether the agent is making MCP / file /
+ * bash calls — without these, a long-running session looks frozen
+ * between text emissions.
  */
 export function extractTextFromContent(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -33,16 +38,50 @@ content, verbose) {
             text += `${item.text}\n`;
             logDebug(item.text, verbose);
         }
+        else if (verbose && item.type === 'tool_use') {
+            logDebug(`→ ${item.name}(${previewJson(item.input)})`, verbose);
+        }
+        else if (verbose && item.type === 'tool_result') {
+            const preview = Array.isArray(item.content)
+                ? item.content
+                    .filter((c) => c?.type === 'text')
+                    .map((c) => c.text ?? '')
+                    .join(' ')
+                : String(item.content ?? '');
+            const flag = item.is_error ? '✗' : '←';
+            logDebug(`${flag} ${truncate(preview, 200)}`, verbose);
+        }
     }
     return text;
 }
+function previewJson(value, max = 200) {
+    try {
+        return truncate(JSON.stringify(value), max);
+    }
+    catch {
+        return truncate(String(value), max);
+    }
+}
+function truncate(text, max) {
+    if (text.length <= max) {
+        return text;
+    }
+    return `${text.slice(0, max - 1)}…`;
+}
 /**
  * Try to parse a JSON result from agent response text.
- * Looks for ```json code blocks first, then falls back to raw JSON parsing.
- * Returns the parsed object or null on failure.
+ * Tries a custom fenceTag (e.g. ```screen_flow) first when provided, then
+ * ```json, then falls back to raw JSON parsing. Returns the parsed object or
+ * null on failure.
  */
-export function tryParseJsonFromResponse(responseText) {
+export function tryParseJsonFromResponse(responseText, fenceTag = 'json') {
     try {
+        if (fenceTag !== 'json') {
+            const taggedMatch = responseText.match(new RegExp(`\`\`\`${escapeRegExp(fenceTag)}\\s*\\n([\\s\\S]*?)\\n\\s*\`\`\``));
+            if (taggedMatch) {
+                return JSON.parse(taggedMatch[1]);
+            }
+        }
         const jsonBlockMatch = responseText.match(/```json\s*\n([\s\S]*?)\n\s*```/);
         return jsonBlockMatch
             ? JSON.parse(jsonBlockMatch[1])
@@ -55,9 +94,11 @@ export function tryParseJsonFromResponse(responseText) {
 /**
  * Extract a specific keyed result from agent response.
  * e.g., tryExtractResult(text, 'review_result') extracts the review_result key.
+ * The key is also tried as the fenced code-block tag so phases whose output
+ * contract uses a custom fence (e.g. ```screen_flow) parse correctly.
  */
 export function tryExtractResult(responseText, key) {
-    const parsed = tryParseJsonFromResponse(responseText);
+    const parsed = tryParseJsonFromResponse(responseText, key);
     if (parsed &&
         typeof parsed === 'object' &&
         key in parsed) {
@@ -66,3 +107,6 @@ export function tryExtractResult(responseText, key) {
     // If top-level has the expected shape, return the whole thing
     return parsed;
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/phases/screen-flow/index.js

@@ -15,6 +15,7 @@ import { logError, logInfo, logSuccess, logWarning } from '../../utils/logger.js
 import { cleanupIssueRepo, cloneIssueRepo, ensureWorkspaceDir, } from '../../workspace/workspace-manager.js';
 import { fetchProductBasics } from '../find-shared/mcp.js';
 import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { createScreenFlowCaptureState, createScreenFlowMcpServer, validateConsistency, } from './mcp-server.js';
 import { createScreenFlowSystemPrompt, createScreenFlowUserPrompt, } from './prompts.js';
 import { extractTheme } from './theme.js';
 import { isScreenFlowExtraction, } from './types.js';
@@ -61,6 +62,17 @@ export async function runScreenFlowPhase(options) {
             guidance,
         });
         logInfo('Running Claude screen-flow extraction...');
+        // The agent submits the extraction by calling submit_screen_flow on the
+        // in-process MCP server. The handler validates with Zod + cross-field
+        // checks and stores the result in `captureState.captured`. If the agent
+        // never calls the tool, we fall back to parsing a fenced screen_flow
+        // block out of the assistant text.
+        const captureState = createScreenFlowCaptureState();
+        const mcpServer = createScreenFlowMcpServer(captureState, {
+            onProgress: ({ phase, message }) => {
+                logInfo(`[${phase}] ${message}`);
+            },
+        });
         let lastAssistantResponse = '';
         let extraction = null;
         for await (const message of query({
@@ -75,28 +87,19 @@ export async function runScreenFlowPhase(options) {
                 maxTurns: MAX_TURNS,
                 permissionMode: 'bypassPermissions',
                 cwd: repoPath,
+                mcpServers: {
+                    'screen-flow': mcpServer,
+                },
             },
         })) {
-            if (message.type === 'assistant') {
-                lastAssistantResponse += extractTextFromContent(message.message?.content ?? [], verbose);
-                continue;
-            }
-            if (message.type !== 'result') {
-                continue;
-            }
-            const responseText = message.subtype === 'success'
-                ? message.result || lastAssistantResponse
-                : lastAssistantResponse;
-            const parsed = tryExtractResult(responseText, 'screen_flow');
-            if (isScreenFlowExtraction(parsed)) {
-                extraction = parsed;
-            }
-            else if (message.subtype !== 'success') {
-                logError(`Extraction incomplete: ${message.subtype}`);
+            const { assistantBuffer, extraction: nextExtraction } = processSdkMessage(message, lastAssistantResponse, captureState, verbose);
+            lastAssistantResponse = assistantBuffer;
+            if (nextExtraction) {
+                extraction = nextExtraction;
             }
         }
         if (!extraction) {
-            const msg = 'Screen flow extraction failed: could not parse a screen_flow result from the agent';
+            const msg = 'Screen flow extraction failed: agent did not call submit_screen_flow and no parseable screen_flow block was found in the response';
             await markFlowFailed(supabase, flowId, msg);
             return { status: 'error', message: msg };
         }
@@ -125,6 +128,59 @@ export async function runScreenFlowPhase(options) {
         }
     }
 }
+// Per-message handler — extracted out of the SDK loop to keep
+// runScreenFlowPhase under the eslint complexity ceiling.
+//
+function processSdkMessage(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+message, assistantBuffer, captureState, verbose) {
+    if (message.type === 'assistant') {
+        const next = assistantBuffer +
+            extractTextFromContent(message.message?.content ?? [], verbose);
+        return { assistantBuffer: next, extraction: null };
+    }
+    if (message.type === 'user' && verbose) {
+        // Surface tool_result blocks (incl. submit_screen_flow validation
+        // errors) so verbose mode shows the round-trip.
+        const userContent = message.message?.content;
+        if (Array.isArray(userContent)) {
+            extractTextFromContent(userContent, verbose);
+        }
+        return { assistantBuffer, extraction: null };
+    }
+    if (message.type !== 'result') {
+        return { assistantBuffer, extraction: null };
+    }
+    if (captureState.captured) {
+        return { assistantBuffer, extraction: captureState.captured };
+    }
+    const fallback = tryFallbackParse(message, assistantBuffer);
+    if (fallback) {
+        logWarning('Agent emitted a fenced screen_flow block instead of calling submit_screen_flow; using the parsed text as a fallback.');
+        return { assistantBuffer, extraction: fallback };
+    }
+    if (message.subtype !== 'success') {
+        logError(`Extraction incomplete: ${message.subtype}`);
+    }
+    return { assistantBuffer, extraction: null };
+}
+// Fallback parser: extract a screen_flow JSON block from the final assistant
+// text if the agent skipped the submit_screen_flow tool call.
+function tryFallbackParse(resultMessage, assistantText) {
+    const responseText = resultMessage.subtype === 'success'
+        ? resultMessage.result || assistantText
+        : assistantText;
+    const parsed = tryExtractResult(responseText, 'screen_flow');
+    if (!isScreenFlowExtraction(parsed)) {
+        return null;
+    }
+    const { error } = validateConsistency(parsed);
+    if (error) {
+        logWarning(`Fallback extraction failed consistency check: ${error}`);
+        return null;
+    }
+    return parsed;
+}
 // ============================================================================
 // Persistence
 // ============================================================================

package/dist/phases/screen-flow/mcp-server.d.ts

@@ -0,0 +1,195 @@
+/**
+ * In-process MCP server exposing a single tool — `submit_screen_flow` —
+ * that the Claude Agent SDK session calls to return the structured
+ * extraction.
+ *
+ * Using a tool call instead of parsing a fenced text block lets the SDK
+ * enforce the schema (via Zod) and lets the agent self-correct when
+ * validation fails — the validation error is returned to the agent as
+ * the tool result and it can re-call the tool with corrected data.
+ *
+ * The capture pattern: callers pass in a `ScreenFlowCaptureState`. The
+ * tool handler stores the validated args on `state.captured` and the
+ * orchestrator reads it after the SDK loop ends. If the agent never
+ * calls the tool, `state.captured` stays null and the caller can fall
+ * back to parsing the assistant text.
+ */
+import { z } from 'zod';
+import type { ScreenFlowExtraction } from './types.js';
+export interface ScreenFlowCaptureState {
+    captured: ScreenFlowExtraction | null;
+}
+export declare function createScreenFlowCaptureState(): ScreenFlowCaptureState;
+/** Optional sink for streaming progress messages from the agent. */
+export type ScreenFlowProgressSink = (event: {
+    phase: 'detection' | 'routing' | 'screens' | 'transitions' | 'submission';
+    message: string;
+}) => void;
+export declare function validateConsistency(extraction: ScreenFlowExtraction): {
+    error: string | null;
+};
+/**
+ * Build the `submit_screen_flow` tool. Exported separately from the server
+ * so tests can exercise the handler directly without going through the
+ * MCP transport.
+ */
+export declare function createSubmitScreenFlowTool(state: ScreenFlowCaptureState): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    summary: z.ZodString;
+    nodes: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+        route: z.ZodOptional<z.ZodString>;
+        file: z.ZodOptional<z.ZodString>;
+        kind: z.ZodEnum<{
+            page: "page";
+            modal: "modal";
+            drawer: "drawer";
+            tab: "tab";
+            state: "state";
+        }>;
+        layout: z.ZodEnum<{
+            split: "split";
+            centered: "centered";
+            sidebar: "sidebar";
+            "list-detail": "list-detail";
+            tabs: "tabs";
+            stacked: "stacked";
+        }>;
+        header: z.ZodOptional<z.ZodObject<{
+            title: z.ZodString;
+            subtitle: z.ZodOptional<z.ZodString>;
+            back: z.ZodOptional<z.ZodBoolean>;
+            actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                variant: z.ZodOptional<z.ZodEnum<{
+                    primary: "primary";
+                    secondary: "secondary";
+                    ghost: "ghost";
+                    destructive: "destructive";
+                }>>;
+                icon: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        body: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"form">;
+            fields: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                kind: z.ZodEnum<{
+                    number: "number";
+                    text: "text";
+                    date: "date";
+                    select: "select";
+                    email: "email";
+                    password: "password";
+                    textarea: "textarea";
+                    checkbox: "checkbox";
+                }>;
+                placeholder: z.ZodOptional<z.ZodString>;
+                value: z.ZodOptional<z.ZodString>;
+                required: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>;
+            submitLabel: z.ZodString;
+            secondaryLabel: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"list">;
+            items: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                subtitle: z.ZodOptional<z.ZodString>;
+                meta: z.ZodOptional<z.ZodString>;
+                icon: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            emptyMessage: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"card-grid">;
+            cards: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                subtitle: z.ZodOptional<z.ZodString>;
+                meta: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"table">;
+            columns: z.ZodArray<z.ZodString>;
+            rows: z.ZodArray<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"kanban">;
+            columns: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                cards: z.ZodArray<z.ZodObject<{
+                    title: z.ZodString;
+                    meta: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            content: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            alt: z.ZodString;
+            aspect: z.ZodOptional<z.ZodEnum<{
+                video: "video";
+                square: "square";
+                wide: "wide";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"chart">;
+            chartKind: z.ZodEnum<{
+                line: "line";
+                bar: "bar";
+                pie: "pie";
+            }>;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"stats">;
+            items: z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                value: z.ZodString;
+                delta: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"empty-state">;
+            title: z.ZodString;
+            message: z.ZodOptional<z.ZodString>;
+            cta: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"tabs">;
+            tabs: z.ZodArray<z.ZodString>;
+            activeIndex: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"custom">;
+            label: z.ZodString;
+        }, z.core.$strip>], "type">>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        fromSlug: z.ZodString;
+        toSlug: z.ZodString;
+        triggerLabel: z.ZodString;
+        triggerFile: z.ZodOptional<z.ZodString>;
+        kind: z.ZodEnum<{
+            modal: "modal";
+            navigate: "navigate";
+            redirect: "redirect";
+            back: "back";
+        }>;
+    }, z.core.$strip>>;
+}>;
+/**
+ * Build the `record_progress` tool. A side-channel that lets the agent
+ * push a human-readable status message to the CLI / desktop UI so a
+ * multi-minute extraction doesn't look frozen between text emissions.
+ * Returning `{ ok: true }` keeps it cheap — it has no semantic effect
+ * on the extraction.
+ */
+export declare function createRecordProgressTool(sink?: ScreenFlowProgressSink): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    phase: z.ZodEnum<{
+        detection: "detection";
+        routing: "routing";
+        screens: "screens";
+        transitions: "transitions";
+        submission: "submission";
+    }>;
+    message: z.ZodString;
+}>;
+export declare function createScreenFlowMcpServer(state: ScreenFlowCaptureState, options?: {
+    onProgress?: ScreenFlowProgressSink;
+}): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/phases/screen-flow/mcp-server.js

@@ -0,0 +1,262 @@
+/**
+ * In-process MCP server exposing a single tool — `submit_screen_flow` —
+ * that the Claude Agent SDK session calls to return the structured
+ * extraction.
+ *
+ * Using a tool call instead of parsing a fenced text block lets the SDK
+ * enforce the schema (via Zod) and lets the agent self-correct when
+ * validation fails — the validation error is returned to the agent as
+ * the tool result and it can re-call the tool with corrected data.
+ *
+ * The capture pattern: callers pass in a `ScreenFlowCaptureState`. The
+ * tool handler stores the validated args on `state.captured` and the
+ * orchestrator reads it after the SDK loop ends. If the agent never
+ * calls the tool, `state.captured` stays null and the caller can fall
+ * back to parsing the assistant text.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+export function createScreenFlowCaptureState() {
+    return { captured: null };
+}
+// ---------------------------------------------------------------------------
+// Zod schemas (mirror types.ts — kept in sync by tests)
+// ---------------------------------------------------------------------------
+const formFieldSchema = z.object({
+    label: z.string(),
+    kind: z.enum([
+        'text',
+        'email',
+        'password',
+        'textarea',
+        'select',
+        'checkbox',
+        'date',
+        'number',
+    ]),
+    placeholder: z.string().optional(),
+    value: z.string().optional(),
+    required: z.boolean().optional(),
+});
+const listItemSchema = z.object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    meta: z.string().optional(),
+    icon: z.string().optional(),
+});
+const cardItemSchema = z.object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    meta: z.string().optional(),
+});
+const kanbanColumnSchema = z.object({
+    title: z.string(),
+    cards: z.array(z.object({ title: z.string(), meta: z.string().optional() })),
+});
+const sectionSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('form'),
+        fields: z.array(formFieldSchema),
+        submitLabel: z.string(),
+        secondaryLabel: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('list'),
+        items: z.array(listItemSchema),
+        emptyMessage: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('card-grid'),
+        cards: z.array(cardItemSchema),
+        columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).optional(),
+    }),
+    z.object({
+        type: z.literal('table'),
+        columns: z.array(z.string()),
+        rows: z.array(z.array(z.string())),
+    }),
+    z.object({
+        type: z.literal('kanban'),
+        columns: z.array(kanbanColumnSchema),
+    }),
+    z.object({
+        type: z.literal('text'),
+        content: z.string(),
+    }),
+    z.object({
+        type: z.literal('image'),
+        alt: z.string(),
+        aspect: z.enum(['video', 'square', 'wide']).optional(),
+    }),
+    z.object({
+        type: z.literal('chart'),
+        chartKind: z.enum(['line', 'bar', 'pie']),
+        label: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('stats'),
+        items: z.array(z.object({
+            label: z.string(),
+            value: z.string(),
+            delta: z.string().optional(),
+        })),
+    }),
+    z.object({
+        type: z.literal('empty-state'),
+        title: z.string(),
+        message: z.string().optional(),
+        cta: z.string().optional(),
+    }),
+    z.object({
+        type: z.literal('tabs'),
+        tabs: z.array(z.string()),
+        activeIndex: z.number().optional(),
+    }),
+    z.object({
+        type: z.literal('custom'),
+        label: z.string(),
+    }),
+]);
+const screenActionSchema = z.object({
+    label: z.string(),
+    variant: z.enum(['primary', 'secondary', 'ghost', 'destructive']).optional(),
+    icon: z.string().optional(),
+});
+const screenHeaderSchema = z.object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    back: z.boolean().optional(),
+    actions: z.array(screenActionSchema).optional(),
+});
+const screenNodeSchema = z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    route: z.string().optional(),
+    file: z.string().optional(),
+    kind: z.enum(['page', 'modal', 'drawer', 'tab', 'state']),
+    layout: z.enum([
+        'centered',
+        'sidebar',
+        'split',
+        'list-detail',
+        'tabs',
+        'stacked',
+    ]),
+    header: screenHeaderSchema.optional(),
+    body: z.array(sectionSchema),
+});
+const screenEdgeSchema = z.object({
+    fromSlug: z.string().min(1),
+    toSlug: z.string().min(1),
+    triggerLabel: z.string(),
+    triggerFile: z.string().optional(),
+    kind: z.enum(['navigate', 'modal', 'redirect', 'back']),
+});
+// ---------------------------------------------------------------------------
+// Cross-field consistency (Zod can't express this)
+// ---------------------------------------------------------------------------
+export function validateConsistency(extraction) {
+    const slugs = new Set();
+    for (const node of extraction.nodes) {
+        if (slugs.has(node.slug)) {
+            return {
+                error: `Duplicate node slug "${node.slug}". Each node.slug MUST be unique within the flow. Re-call submit_screen_flow with deduplicated nodes.`,
+            };
+        }
+        slugs.add(node.slug);
+    }
+    for (const edge of extraction.edges) {
+        if (!slugs.has(edge.fromSlug)) {
+            return {
+                error: `Edge fromSlug "${edge.fromSlug}" → "${edge.toSlug}" does not match any node slug. Either add the missing node or drop the edge, then re-call submit_screen_flow.`,
+            };
+        }
+        if (!slugs.has(edge.toSlug)) {
+            return {
+                error: `Edge fromSlug "${edge.fromSlug}" → toSlug "${edge.toSlug}" does not match any node slug. Either add the missing node or drop the edge, then re-call submit_screen_flow.`,
+            };
+        }
+    }
+    return { error: null };
+}
+// ---------------------------------------------------------------------------
+// Tool factory + server factory
+// ---------------------------------------------------------------------------
+/**
+ * Build the `submit_screen_flow` tool. Exported separately from the server
+ * so tests can exercise the handler directly without going through the
+ * MCP transport.
+ */
+export function createSubmitScreenFlowTool(state) {
+    return tool('submit_screen_flow', [
+        'Submit the final screen flow extraction. Call this EXACTLY once,',
+        'when you have finished mapping every screen and transition. Pass the',
+        'full structured flow as the argument. After this call succeeds, end',
+        'your turn — do NOT also paste the same data as a fenced code block.',
+        'If validation fails, the error message tells you what to fix; call',
+        'the tool again with corrected data.',
+    ].join(' '), {
+        summary: z
+            .string()
+            .min(1)
+            .describe('1-3 sentence narrative of what kind of app this is and its primary user flows.'),
+        nodes: z
+            .array(screenNodeSchema)
+            .describe('Every user-facing screen, modal, drawer, tab, or named state. node.slug MUST be unique within the flow.'),
+        edges: z
+            .array(screenEdgeSchema)
+            .describe('Transitions between screens. Every fromSlug / toSlug MUST reference a slug present in nodes; drop edges whose endpoints you did not emit.'),
+    }, async (args) => {
+        const extraction = {
+            summary: args.summary,
+            nodes: args.nodes,
+            edges: args.edges,
+        };
+        const { error } = validateConsistency(extraction);
+        if (error) {
+            return {
+                content: [{ type: 'text', text: error }],
+                isError: true,
+            };
+        }
+        state.captured = extraction;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Captured ${extraction.nodes.length} screens / ${extraction.edges.length} transitions. End your turn now.`,
+                },
+            ],
+        };
+    });
+}
+/**
+ * Build the `record_progress` tool. A side-channel that lets the agent
+ * push a human-readable status message to the CLI / desktop UI so a
+ * multi-minute extraction doesn't look frozen between text emissions.
+ * Returning `{ ok: true }` keeps it cheap — it has no semantic effect
+ * on the extraction.
+ */
+export function createRecordProgressTool(sink) {
+    return tool('record_progress', 'Send a short status update to the user. Does not affect the extraction. Call it at each phase boundary (after detecting the framework, after enumerating routes, while mapping screens, when about to submit) so the user sees progress.', {
+        phase: z
+            .enum(['detection', 'routing', 'screens', 'transitions', 'submission'])
+            .describe('Which phase the message belongs to.'),
+        message: z.string().min(1).describe('Human-readable status update.'),
+    }, async (args) => {
+        sink?.({ phase: args.phase, message: args.message });
+        return {
+            content: [{ type: 'text', text: 'ok' }],
+        };
+    });
+}
+export function createScreenFlowMcpServer(state, options) {
+    return createSdkMcpServer({
+        name: 'screen-flow',
+        version: '1.0.0',
+        tools: [
+            createSubmitScreenFlowTool(state),
+            createRecordProgressTool(options?.onProgress),
+        ],
+    });
+}

package/dist/phases/screen-flow/prompts.js

@@ -35,5 +35,7 @@ export function createScreenFlowUserPrompt(args) {
 
 Start by detecting the framework (check package.json / pubspec.yaml / Package.swift), then locate the router definition or pages directory. Read just enough source per screen to fill in a useful ScreenSchema — do not need to read everything.
 
-When done, emit the single \`screen_flow\` JSON block.`;
+Call \`mcp__screen-flow__record_progress\` at each phase boundary so the user can see your progress (otherwise the CLI looks frozen).
+
+When you are done, return the result by **calling the \`mcp__screen-flow__submit_screen_flow\` tool exactly once** with \`summary\`, \`nodes\`, and \`edges\` as arguments. Do not paste the JSON as a fenced text block — the tool call is the deliverable. If the tool returns an error, fix the issue it describes and call the tool again.`;
 }

package/dist/phases/screen-flow/theme.js

@@ -94,19 +94,23 @@ function parseTailwindColors(source) {
     // either a single string ("primary: '#ff0066'") or an object containing
     // a 500 key (the Tailwind convention).
     const primaryString = matchColorEntry(source, 'primary');
-    if (primaryString)
+    if (primaryString) {
         theme.primary = primaryString;
+    }
     const neutralString = matchColorEntry(source, 'neutral');
-    if (neutralString)
+    if (neutralString) {
         theme.neutral = neutralString;
+    }
     // Pull a radius default if defined under theme.borderRadius
     const radiusMatch = source.match(/borderRadius\s*:\s*{[^}]*?(?:DEFAULT|md|lg)\s*:\s*['"]([^'"]+)['"]/);
-    if (radiusMatch)
+    if (radiusMatch) {
         theme.radius = radiusMatch[1];
+    }
     // Pull the default sans font family
     const fontMatch = source.match(/fontFamily\s*:\s*{[^}]*?sans\s*:\s*\[?\s*['"]([^'"]+)['"]/);
-    if (fontMatch)
+    if (fontMatch) {
         theme.font = fontMatch[1];
+    }
     return theme;
 }
 function matchColorEntry(source, key) {
@@ -132,22 +136,26 @@ function parseTokensJson(json) {
     const colors = (json.colors ?? json.color);
     if (colors && typeof colors === 'object') {
         const primary = colors.primary;
-        if (typeof primary === 'string')
+        if (typeof primary === 'string') {
             theme.primary = primary;
+        }
         else if (primary && typeof primary === 'object' && '500' in primary) {
             theme.primary = primary['500'];
         }
         const neutral = colors.neutral;
-        if (typeof neutral === 'string')
+        if (typeof neutral === 'string') {
             theme.neutral = neutral;
+        }
         else if (neutral && typeof neutral === 'object' && '500' in neutral) {
             theme.neutral = neutral['500'];
         }
     }
-    if (typeof json.radius === 'string')
+    if (typeof json.radius === 'string') {
         theme.radius = json.radius;
-    if (typeof json.font === 'string')
+    }
+    if (typeof json.font === 'string') {
         theme.font = json.font;
+    }
     return theme;
 }
 function parseGlobalCss(source) {
@@ -155,14 +163,17 @@ function parseGlobalCss(source) {
     const primaryMatch = source.match(/--primary\s*:\s*([^;]+);/);
     if (primaryMatch) {
         const value = primaryMatch[1].trim();
-        if (isColorish(value))
+        if (isColorish(value)) {
             theme.primary = value;
-        else
-            theme.primary = `hsl(${value})`; // common shadcn pattern
+        }
+        else {
+            theme.primary = `hsl(${value})`;
+        } // common shadcn pattern
     }
     const radiusMatch = source.match(/--radius\s*:\s*([^;]+);/);
-    if (radiusMatch)
+    if (radiusMatch) {
         theme.radius = radiusMatch[1].trim();
+    }
     return theme;
 }
 function isColorish(value) {

package/dist/phases/screen-flow/types.js

@@ -20,47 +20,62 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
 function isScreenSchema(value) {
-    if (!isRecord(value))
+    if (!isRecord(value)) {
         return false;
-    if (typeof value.slug !== 'string' || value.slug.length === 0)
+    }
+    if (typeof value.slug !== 'string' || value.slug.length === 0) {
         return false;
-    if (typeof value.name !== 'string' || value.name.length === 0)
+    }
+    if (typeof value.name !== 'string' || value.name.length === 0) {
         return false;
+    }
     if (typeof value.kind !== 'string' || !SCREEN_KINDS.has(value.kind)) {
         return false;
     }
-    if (typeof value.layout !== 'string')
+    if (typeof value.layout !== 'string') {
         return false;
-    if (!Array.isArray(value.body))
+    }
+    if (!Array.isArray(value.body)) {
         return false;
+    }
     return true;
 }
 function isScreenEdge(value) {
-    if (!isRecord(value))
+    if (!isRecord(value)) {
         return false;
-    if (typeof value.fromSlug !== 'string')
+    }
+    if (typeof value.fromSlug !== 'string') {
         return false;
-    if (typeof value.toSlug !== 'string')
+    }
+    if (typeof value.toSlug !== 'string') {
         return false;
-    if (typeof value.triggerLabel !== 'string')
+    }
+    if (typeof value.triggerLabel !== 'string') {
         return false;
+    }
     if (typeof value.kind !== 'string' || !EDGE_KINDS.has(value.kind)) {
         return false;
     }
     return true;
 }
 export function isScreenFlowExtraction(value) {
-    if (!isRecord(value))
+    if (!isRecord(value)) {
         return false;
-    if (typeof value.summary !== 'string')
+    }
+    if (typeof value.summary !== 'string') {
         return false;
-    if (!Array.isArray(value.nodes))
+    }
+    if (!Array.isArray(value.nodes)) {
         return false;
-    if (!Array.isArray(value.edges))
+    }
+    if (!Array.isArray(value.edges)) {
         return false;
-    if (!value.nodes.every(isScreenSchema))
+    }
+    if (!value.nodes.every(isScreenSchema)) {
         return false;
-    if (!value.edges.every(isScreenEdge))
+    }
+    if (!value.edges.every(isScreenEdge)) {
         return false;
+    }
     return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edsger",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "type": "module",
   "bin": {
     "edsger": "dist/index.js"