edsger 0.56.3 → 0.58.0

package/dist/phases/product-test-cases/prompts.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Prompts for the product-level test cases phase.
+ *
+ * Agent's job: explore the cloned product repo and propose a regression-suite
+ * worth of test cases for the whole product (not a single issue). Existing
+ * test cases — both approved (locked) and unapproved (replaceable) — are
+ * included in the context so the agent doesn't duplicate work and so the
+ * unapproved set can be refreshed when the codebase has drifted.
+ */
+export interface ExistingProductTestCase {
+    id: string;
+    name: string;
+    description: string;
+    is_critical: boolean;
+    status: string;
+}
+export interface ProductTestCasesPromptContext {
+    productName: string;
+    productDescription?: string;
+    approvedTestCases: ExistingProductTestCase[];
+    replaceableTestCases: ExistingProductTestCase[];
+}
+export declare function createProductTestCasesSystemPrompt(): string;
+export declare function createProductTestCasesUserPrompt(context: ProductTestCasesPromptContext): string;

package/dist/phases/product-test-cases/prompts.js

@@ -0,0 +1,80 @@
+/**
+ * Prompts for the product-level test cases phase.
+ *
+ * Agent's job: explore the cloned product repo and propose a regression-suite
+ * worth of test cases for the whole product (not a single issue). Existing
+ * test cases — both approved (locked) and unapproved (replaceable) — are
+ * included in the context so the agent doesn't duplicate work and so the
+ * unapproved set can be refreshed when the codebase has drifted.
+ */
+export function createProductTestCasesSystemPrompt() {
+    return `You are a senior QA engineer drafting a product-level regression test suite.
+
+The current working directory is a fresh clone of the product's repository. Use Glob/Grep/Read to explore it and understand the surface area: entry points, public APIs, user-facing flows, critical paths. Look at recent commits with Bash if it helps.
+
+Output a single JSON result of the form:
+\`\`\`json
+{
+  "test_cases_result": {
+    "summary": "Short 1-2 sentence summary of what you covered",
+    "created_test_cases": [
+      {
+        "name": "Concise name (max 200 chars)",
+        "description": "Markdown describing Given/When/Then steps + expected result",
+        "is_critical": true
+      }
+    ],
+    "deleted_test_case_ids": [
+      "uuid-of-replaceable-test-case-you-want-removed"
+    ],
+    "deletion_reasons": {
+      "uuid": "Why this test case is no longer relevant"
+    }
+  }
+}
+\`\`\`
+
+Rules:
+- DO NOT duplicate any test case in the "Approved test cases" or "Replaceable test cases" sections. If an existing case already covers a behaviour, skip it.
+- You MAY propose deletions ONLY for entries in the "Replaceable test cases" list. Approved test cases are locked by the human reviewer and cannot be touched.
+- Mark \`is_critical: true\` only for must-pass flows (auth, payments, data loss risks, primary user journeys).
+- Aim for 5-30 high-signal cases total. Quality over quantity.
+- Each test case must be executable by a human tester reading the description alone.
+- The "deleted_test_case_ids" and "deletion_reasons" fields are optional; omit or use [] / {} when you have nothing to delete.
+- Wrap the final JSON in a single \`\`\`json fenced block. No extra prose after it.`;
+}
+export function createProductTestCasesUserPrompt(context) {
+    const lines = [];
+    lines.push(`# Product: ${context.productName}`);
+    if (context.productDescription) {
+        lines.push('');
+        lines.push(`## Description`);
+        lines.push(context.productDescription);
+    }
+    lines.push('');
+    lines.push('## Approved test cases (locked — do not duplicate, cannot delete)');
+    if (context.approvedTestCases.length === 0) {
+        lines.push('_(none)_');
+    }
+    else {
+        for (const tc of context.approvedTestCases) {
+            lines.push(`- **${tc.name}**${tc.is_critical ? ' [critical]' : ''}`);
+            lines.push(`  ${tc.description.replace(/\n/g, '\n  ')}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Replaceable test cases (draft / pending_approval — may be deleted if obsolete or duplicated)');
+    if (context.replaceableTestCases.length === 0) {
+        lines.push('_(none)_');
+    }
+    else {
+        for (const tc of context.replaceableTestCases) {
+            lines.push(`- \`${tc.id}\` (${tc.status})${tc.is_critical ? ' [critical]' : ''} — **${tc.name}**`);
+            lines.push(`  ${tc.description.replace(/\n/g, '\n  ')}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Task');
+    lines.push('Explore the repository (Glob/Grep/Read/Bash) and propose product-level regression test cases. Follow the JSON output contract in your system prompt.');
+    return lines.join('\n');
+}

package/dist/phases/product-test-cases/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Wire shape for the product-test-cases agent output. The agent is asked to
+ * emit `{ test_cases_result: { ... } }`; we validate it loosely so a single
+ * stray field doesn't kill an otherwise-good run.
+ */
+export interface ProductTestCaseDraft {
+    name: string;
+    description: string;
+    is_critical?: boolean;
+}
+export interface ProductTestCasesAgentResult {
+    summary: string;
+    created_test_cases: ProductTestCaseDraft[];
+    deleted_test_case_ids?: string[];
+    deletion_reasons?: Record<string, string>;
+}
+export declare function isProductTestCasesAgentResult(value: unknown): value is ProductTestCasesAgentResult;

package/dist/phases/product-test-cases/types.js

@@ -0,0 +1,27 @@
+/**
+ * Wire shape for the product-test-cases agent output. The agent is asked to
+ * emit `{ test_cases_result: { ... } }`; we validate it loosely so a single
+ * stray field doesn't kill an otherwise-good run.
+ */
+export function isProductTestCasesAgentResult(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const v = value;
+    if (typeof v.summary !== 'string') {
+        return false;
+    }
+    if (!Array.isArray(v.created_test_cases)) {
+        return false;
+    }
+    for (const tc of v.created_test_cases) {
+        if (!tc || typeof tc !== 'object') {
+            return false;
+        }
+        const t = tc;
+        if (typeof t.name !== 'string' || typeof t.description !== 'string') {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/phases/screen-flow/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * screen-flow phase: clone the product's repo, ask Claude to map every
+ * user-facing screen and the transitions between them into a structured
+ * ScreenFlowExtraction, then persist the result to screen_flows /
+ * screen_flow_nodes / screen_flow_edges via the Supabase SDK.
+ *
+ * Companion to find-architecture / find-bugs / find-features. Same workspace
+ * pattern, but writes to its own tables rather than filing issues.
+ */
+export interface ScreenFlowOptions {
+    productId: string;
+    flowId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export interface ScreenFlowResult {
+    status: 'success' | 'error';
+    message: string;
+    nodesCreated?: number;
+    edgesCreated?: number;
+    summary?: string;
+}
+export declare function runScreenFlowPhase(options: ScreenFlowOptions): Promise<ScreenFlowResult>;

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

@@ -0,0 +1,285 @@
+/**
+ * screen-flow phase: clone the product's repo, ask Claude to map every
+ * user-facing screen and the transitions between them into a structured
+ * ScreenFlowExtraction, then persist the result to screen_flows /
+ * screen_flow_nodes / screen_flow_edges via the Supabase SDK.
+ *
+ * Companion to find-architecture / find-bugs / find-features. Same workspace
+ * pattern, but writes to its own tables rather than filing issues.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { getGitHubConfigByProduct } from '../../api/github.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getSupabase } from '../../supabase/client.js';
+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';
+const WORKSPACE_KEY = 'screen-flow';
+const MAX_TURNS = 150;
+// Auto-layout: simple grid; users can drag afterwards and we persist positions.
+const COLUMN_WIDTH = 380;
+const ROW_HEIGHT = 480;
+const COLUMNS = 4;
+export async function runScreenFlowPhase(options) {
+    const { productId, flowId, guidance, verbose } = options;
+    logInfo(`Starting screen-flow generation for product ${productId}`);
+    const supabase = getSupabase();
+    await markFlowRunning(supabase, flowId);
+    const githubConfig = await getGitHubConfigByProduct(productId, verbose);
+    if (!githubConfig.configured ||
+        !githubConfig.token ||
+        !githubConfig.owner ||
+        !githubConfig.repo) {
+        const msg = githubConfig.message ||
+            'GitHub repository not configured for this product. Connect a repo first.';
+        await markFlowFailed(supabase, flowId, msg);
+        return { status: 'error', message: msg };
+    }
+    let repoPath;
+    let succeeded = false;
+    try {
+        const workspaceRoot = ensureWorkspaceDir();
+        const repoKey = `${WORKSPACE_KEY}-${productId}`;
+        ({ repoPath } = cloneIssueRepo(workspaceRoot, repoKey, githubConfig.owner, githubConfig.repo, githubConfig.token));
+        const product = await fetchProductBasics(productId);
+        const theme = extractTheme(repoPath);
+        if (Object.keys(theme).length > 0) {
+            logInfo(`Extracted theme: ${Object.entries(theme).map(([k, v]) => `${k}=${v}`).join(', ')}`);
+            await persistTheme(supabase, flowId, theme);
+        }
+        const systemPrompt = await createScreenFlowSystemPrompt({
+            projectDir: repoPath,
+            hasCodebase: true,
+        });
+        const userPrompt = createScreenFlowUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            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({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: repoPath,
+                mcpServers: {
+                    'screen-flow': mcpServer,
+                },
+            },
+        })) {
+            const { assistantBuffer, extraction: nextExtraction } = processSdkMessage(message, lastAssistantResponse, captureState, verbose);
+            lastAssistantResponse = assistantBuffer;
+            if (nextExtraction) {
+                extraction = nextExtraction;
+            }
+        }
+        if (!extraction) {
+            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 };
+        }
+        logInfo(`Extraction produced ${extraction.nodes.length} screens / ${extraction.edges.length} transitions`);
+        const { nodesCreated, edgesCreated } = await persistFlow(supabase, flowId, extraction);
+        await markFlowSuccess(supabase, flowId, extraction.summary);
+        succeeded = true;
+        logSuccess(`Screen flow generated: ${nodesCreated} screens, ${edgesCreated} transitions`);
+        return {
+            status: 'success',
+            message: `Screen flow generated (${nodesCreated} screens, ${edgesCreated} transitions)`,
+            nodesCreated,
+            edgesCreated,
+            summary: extraction.summary,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Screen flow failed: ${errorMessage}`);
+        await markFlowFailed(supabase, flowId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(repoPath);
+        }
+    }
+}
+// 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
+// ============================================================================
+async function markFlowRunning(supabase, flowId) {
+    const { error } = await supabase
+        .from('screen_flows')
+        .update({ status: 'running', error: null })
+        .eq('id', flowId);
+    if (error) {
+        logWarning(`Could not mark flow as running: ${error.message}`);
+    }
+}
+async function markFlowFailed(supabase, flowId, errorMessage) {
+    await supabase
+        .from('screen_flows')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', flowId);
+}
+async function persistTheme(supabase, flowId, theme) {
+    const { error } = await supabase
+        .from('screen_flows')
+        .update({ theme })
+        .eq('id', flowId);
+    if (error) {
+        logWarning(`Could not persist extracted theme: ${error.message}`);
+    }
+}
+async function markFlowSuccess(supabase, flowId, summary) {
+    await supabase
+        .from('screen_flows')
+        .update({
+        status: 'success',
+        summary,
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', flowId);
+}
+async function persistFlow(supabase, flowId, extraction) {
+    // Re-runs replace prior content for the same flow row.
+    await supabase.from('screen_flow_edges').delete().eq('flow_id', flowId);
+    await supabase.from('screen_flow_nodes').delete().eq('flow_id', flowId);
+    if (extraction.nodes.length === 0) {
+        return { nodesCreated: 0, edgesCreated: 0 };
+    }
+    const nodeRows = extraction.nodes.map((n, i) => buildNodeRow(flowId, n, i));
+    const { data: insertedNodes, error: nodesError } = await supabase
+        .from('screen_flow_nodes')
+        .insert(nodeRows)
+        .select('id, slug');
+    if (nodesError) {
+        throw new Error(`Failed to insert nodes: ${nodesError.message}`);
+    }
+    const slugToId = new Map((insertedNodes ?? []).map((n) => [n.slug, n.id]));
+    const edgeRows = extraction.edges
+        .map((e) => buildEdgeRow(flowId, e, slugToId))
+        .filter((e) => e !== null);
+    if (edgeRows.length > 0) {
+        const { error: edgesError } = await supabase
+            .from('screen_flow_edges')
+            .insert(edgeRows);
+        if (edgesError) {
+            throw new Error(`Failed to insert edges: ${edgesError.message}`);
+        }
+    }
+    return {
+        nodesCreated: insertedNodes?.length ?? 0,
+        edgesCreated: edgeRows.length,
+    };
+}
+function buildNodeRow(flowId, node, index) {
+    return {
+        flow_id: flowId,
+        slug: node.slug,
+        name: node.name,
+        route: node.route ?? null,
+        file: node.file ?? null,
+        kind: node.kind,
+        schema: node,
+        position_x: (index % COLUMNS) * COLUMN_WIDTH,
+        position_y: Math.floor(index / COLUMNS) * ROW_HEIGHT,
+    };
+}
+function buildEdgeRow(flowId, edge, slugToId) {
+    const fromId = slugToId.get(edge.fromSlug);
+    const toId = slugToId.get(edge.toSlug);
+    if (!fromId || !toId) {
+        return null;
+    }
+    return {
+        flow_id: flowId,
+        from_node_id: fromId,
+        to_node_id: toId,
+        trigger_label: edge.triggerLabel,
+        trigger_file: edge.triggerFile ?? null,
+        kind: edge.kind,
+    };
+}

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;