edsger 0.58.0 → 0.60.0

package/dist/phases/product-techniques/mcp-server.js

@@ -0,0 +1,96 @@
+/**
+ * In-process MCP server exposing a single tool — `submit_techniques` — that
+ * the Claude Agent SDK session calls to return the final markdown catalogue.
+ *
+ * Using a tool call instead of parsing a fenced JSON block lets the SDK
+ * enforce the schema (via Zod) and lets the agent self-correct when
+ * validation fails: the error message goes back as the tool result and the
+ * agent can re-call the tool with corrected data.
+ *
+ * The capture pattern: callers pass in a `TechniquesCaptureState`. The tool
+ * handler stores the validated args on `state.captured`. The orchestrator
+ * reads it after the SDK loop ends.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { TECHNIQUES_CONTENT_MAX, TECHNIQUES_SUMMARY_MAX, } from './types.js';
+export function createTechniquesCaptureState() {
+    return { captured: null };
+}
+/**
+ * Validation that goes beyond the basic Zod schema: enforce that the
+ * markdown actually has the H2 sections the prompt asks for. The agent gets
+ * an actionable error and can re-submit.
+ *
+ * We don't require ALL six sections — agents on tiny repos often legitimately
+ * collapse some. We require at least the first one ("Languages & Runtime")
+ * plus "Notable Techniques", which the prompt calls out as the whole point.
+ */
+export function validateContent(content) {
+    const required = [
+        /^##\s+Languages\s*&\s*Runtime\b/im,
+        /^##\s+Notable\s+Techniques\b/im,
+    ];
+    for (const re of required) {
+        if (!re.test(content)) {
+            return {
+                error: `content is missing the required section matching ${re.source}. Add the section and re-call submit_techniques.`,
+            };
+        }
+    }
+    return { error: null };
+}
+/**
+ * Build the `submit_techniques` tool. Exported separately from the server
+ * so tests can exercise the handler directly without going through MCP
+ * transport.
+ */
+export function createSubmitTechniquesTool(state) {
+    return tool('submit_techniques', [
+        'Submit the final techniques catalogue. Call this EXACTLY once, when',
+        'you have finished cataloguing every technique. Pass the summary and',
+        'the full markdown content as arguments. After this call succeeds, end',
+        'your turn — do NOT also paste the same content 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)
+            .max(TECHNIQUES_SUMMARY_MAX)
+            .describe('1-2 sentence summary suitable for a tab header. Plain text, no markdown.'),
+        content: z
+            .string()
+            .min(1)
+            .max(TECHNIQUES_CONTENT_MAX)
+            .describe('Full markdown body with H2 sections: Languages & Runtime, Frameworks & Libraries, Architecture Patterns, State & Data Techniques, Build & Deploy Techniques, Notable Techniques.'),
+    }, async (args) => {
+        const extraction = {
+            summary: args.summary,
+            content: args.content,
+        };
+        const { error } = validateContent(extraction.content);
+        if (error) {
+            return {
+                content: [{ type: 'text', text: error }],
+                isError: true,
+            };
+        }
+        state.captured = extraction;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Captured techniques catalogue (${extraction.content.length} chars). End your turn now.`,
+                },
+            ],
+        };
+    });
+}
+export function createTechniquesMcpServer(state) {
+    return createSdkMcpServer({
+        name: 'product-techniques',
+        version: '1.0.0',
+        tools: [createSubmitTechniquesTool(state)],
+    });
+}

package/dist/phases/product-techniques/prompts.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Prompts for the product-level techniques phase.
+ *
+ * Agent's job: explore the cloned product repo and write a markdown catalogue
+ * of the techniques it actually uses — languages, frameworks, patterns, state
+ * idioms, build/deploy choices, plus the clever non-obvious bits. Focused on
+ * what a new engineer needs to recognize and recreate, not feature lists.
+ *
+ * The final result is submitted via the `submit_techniques` MCP tool, NOT a
+ * fenced JSON block. Tool calls let the SDK enforce the schema with Zod and
+ * let the agent self-correct on validation errors. See mcp-server.ts.
+ */
+export interface ProductTechniquesPromptContext {
+    productName: string;
+    productDescription?: string;
+    guidance?: string;
+}
+export declare function createProductTechniquesSystemPrompt(): string;
+export declare function createProductTechniquesUserPrompt(context: ProductTechniquesPromptContext): string;

package/dist/phases/product-techniques/prompts.js

@@ -0,0 +1,66 @@
+/**
+ * Prompts for the product-level techniques phase.
+ *
+ * Agent's job: explore the cloned product repo and write a markdown catalogue
+ * of the techniques it actually uses — languages, frameworks, patterns, state
+ * idioms, build/deploy choices, plus the clever non-obvious bits. Focused on
+ * what a new engineer needs to recognize and recreate, not feature lists.
+ *
+ * The final result is submitted via the `submit_techniques` MCP tool, NOT a
+ * fenced JSON block. Tool calls let the SDK enforce the schema with Zod and
+ * let the agent self-correct on validation errors. See mcp-server.ts.
+ */
+export function createProductTechniquesSystemPrompt() {
+    return `You are a senior staff engineer cataloguing the techniques a product's codebase uses.
+
+The current working directory is a fresh clone of the product's repository. Use Glob/Grep/Read (and Bash for git/log when helpful) to explore it before writing.
+
+Your audience: a new engineer joining the team. They need to recognize WHICH techniques this repo employs — what frameworks, what patterns, what idioms — so they can read code without surprise and contribute in the codebase's existing style. This is not a feature list and not an architecture proposal. Anchor every technique in the actual code; reference real file paths.
+
+## Output protocol
+
+When you are ready to submit, call the \`submit_techniques\` tool EXACTLY ONCE with:
+- \`summary\` — 1-2 sentence summary suitable for a tab header (plain text, no markdown).
+- \`content\` — the full markdown body, structured as described below.
+
+Do NOT also paste the same content as a fenced code block — the tool call is the only channel for the result. If validation fails, the tool response tells you what to fix; call the tool again with corrected data.
+
+## Required sections in \`content\`
+
+The markdown body MUST contain these H2 sections, in this order:
+
+1. **## Languages & Runtime** — languages used (with versions if pinned), runtime targets (Node / Bun / Deno / browser / native / etc), package manager.
+2. **## Frameworks & Libraries** — the major frameworks and libraries this repo depends on, and what each one is doing here. Don't just list package names; explain the role. Group by area (UI, server, data, infra) if it helps.
+3. **## Architecture Patterns** — the architectural choices the code embodies: layering / module boundaries / dependency direction / how features are organised. Include one Mermaid \`flowchart TD\` showing the dominant pattern (≤ 10 nodes). Name the pattern when you can ("repository pattern", "feature-sliced design", "hexagonal", "BFF", etc.).
+4. **## State & Data Techniques** — state management, data fetching, caching, optimistic updates, validation, type-safety across boundaries. How is server state vs client state handled? How are forms managed? How is data flowing between server and client?
+5. **## Build & Deploy Techniques** — bundler / compiler choices, code-splitting, environment handling, monorepo tooling, CI/CD specifics, deployment target (edge / serverless / containers / static).
+6. **## Notable Techniques** — the genuinely interesting bits that aren't obvious from the stack: clever abstractions, performance optimizations, security hardening, custom hooks/utilities worth knowing, intentional deviations from defaults, surprising workarounds. Each one: what it is, where it lives (file path), why it matters. This section is the whole point — be specific and useful here.
+
+The validator will reject content missing the "Languages & Runtime" or "Notable Techniques" headings.
+
+## Rules
+
+- Use relative file paths from the repo root (e.g. \`src/services/auth.ts\`). Link to specific files where the technique is most visible.
+- Mermaid blocks must be valid (no unclosed quotes, no unsupported node shapes). Prefer simple \`flowchart TD\` syntax.
+- Don't invent or guess. If a section has nothing distinctive ("just a stock CRA app"), say so briefly — don't pad.
+- Focus on TECHNIQUES, not features. Bad: "the app has a login screen". Good: "uses next-auth's credentials provider with a custom JWT callback at src/lib/auth.ts:42".
+- The whole document should fit in one screen-readable scroll — aim for ~1500-3000 words of content. Less is fine for small repos.`;
+}
+export function createProductTechniquesUserPrompt(context) {
+    const lines = [];
+    lines.push(`# Product: ${context.productName}`);
+    if (context.productDescription) {
+        lines.push('');
+        lines.push('## Description');
+        lines.push(context.productDescription);
+    }
+    if (context.guidance && context.guidance.trim()) {
+        lines.push('');
+        lines.push('## Reviewer guidance (focus or exclusions)');
+        lines.push(context.guidance.trim());
+    }
+    lines.push('');
+    lines.push('## Task');
+    lines.push('Explore the cloned repository and produce the techniques catalogue, then submit it via the `submit_techniques` MCP tool as specified in your system prompt. Pay particular attention to the "Notable Techniques" section — that is the real value to the reader.');
+    return lines.join('\n');
+}

package/dist/phases/product-techniques/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shape returned by the agent via the `submit_techniques` MCP tool. Mirrors
+ * the Zod schema in `mcp-server.ts` — kept duplicated as a plain TS type so
+ * consumers (the phase orchestrator, persistence helpers, tests) don't have
+ * to inflate Zod into their dependency graph.
+ */
+export interface TechniquesExtraction {
+    summary: string;
+    content: string;
+}
+export declare function isTechniquesExtraction(v: unknown): v is TechniquesExtraction;
+export declare const TECHNIQUES_SUMMARY_MAX = 500;
+export declare const TECHNIQUES_CONTENT_MAX = 200000;

package/dist/phases/product-techniques/types.js

@@ -0,0 +1,13 @@
+export function isTechniquesExtraction(v) {
+    if (!v || typeof v !== 'object') {
+        return false;
+    }
+    const obj = v;
+    return typeof obj.summary === 'string' && typeof obj.content === 'string';
+}
+// Defensive caps mirroring the DB CHECK constraints from
+// 20260521000000_create_product_techniques.sql. Keeping the limits here
+// too lets the MCP tool reject oversized output with an actionable error
+// message instead of getting a Postgres constraint violation.
+export const TECHNIQUES_SUMMARY_MAX = 500;
+export const TECHNIQUES_CONTENT_MAX = 200_000;

package/dist/phases/recipes/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Recipes phase: clone the product's repo, ask Claude to identify each
+ * non-trivial capability the product implements, and persist HOW it's built
+ * via the recipes / product_recipes tables.
+ *
+ * Production-grade behaviours layered on top of the basic agent loop:
+ *
+ *   - Heartbeat: `last_heartbeat_at` on the recipe_scans row is refreshed
+ *     on every assistant message so the reader can detect stalled / crashed
+ *     runs (see desktop-app/.../services/db/recipe-scans.ts for the lazy
+ *     reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Per-call MCP writes: agent commits each create / update / link /
+ *     unlink as it goes. There is no "submit at the end" buffer — partial
+ *     progress survives even if the agent later errors out.
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { RecipeSummary } from './types.js';
+export interface RecipesPhaseOptions {
+    productId: string;
+    scanId: string;
+    guidance?: string;
+    verbose?: boolean;
+}
+export interface RecipesPhaseResult {
+    status: 'success' | 'error' | 'cancelled';
+    message: string;
+    counts?: {
+        created: number;
+        updated: number;
+        linked: number;
+        unlinked: number;
+    };
+}
+export declare function runRecipesPhase(options: RecipesPhaseOptions): Promise<RecipesPhaseResult>;
+export declare function getProductTeamId(supabase: SupabaseClient, productId: string): Promise<string | null>;
+export declare function getScanCreator(supabase: SupabaseClient, scanId: string): Promise<{
+    created_by: string;
+} | null>;
+export declare function listTeamRecipes(supabase: SupabaseClient, teamId: string): Promise<RecipeSummary[]>;
+export declare function listProductRecipeLinks(supabase: SupabaseClient, productId: string): Promise<{
+    recipe_id: string;
+    name: string;
+}[]>;
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export declare function markRunning(supabase: SupabaseClient, scanId: string): Promise<boolean>;
+export declare function heartbeat(supabase: SupabaseClient, scanId: string): Promise<void>;
+export declare function markFailed(supabase: SupabaseClient, scanId: string, errorMessage: string): Promise<boolean>;
+export declare function markSuccess(supabase: SupabaseClient, scanId: string): Promise<boolean>;

package/dist/phases/recipes/index.js

@@ -0,0 +1,301 @@
+/**
+ * Recipes phase: clone the product's repo, ask Claude to identify each
+ * non-trivial capability the product implements, and persist HOW it's built
+ * via the recipes / product_recipes tables.
+ *
+ * Production-grade behaviours layered on top of the basic agent loop:
+ *
+ *   - Heartbeat: `last_heartbeat_at` on the recipe_scans row is refreshed
+ *     on every assistant message so the reader can detect stalled / crashed
+ *     runs (see desktop-app/.../services/db/recipe-scans.ts for the lazy
+ *     reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Per-call MCP writes: agent commits each create / update / link /
+ *     unlink as it goes. There is no "submit at the end" buffer — partial
+ *     progress survives even if the agent later errors out.
+ */
+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, } from '../pr-shared/agent-utils.js';
+import { createRecipesMcpServer, createRecipesMutationCounts, } from './mcp-server.js';
+import { createRecipesSystemPrompt, createRecipesUserPrompt, } from './prompts.js';
+const WORKSPACE_KEY = 'recipes';
+const MAX_TURNS = 200;
+// Heartbeat cadence: at most one DB write per HEARTBEAT_MIN_INTERVAL_MS.
+// Triggered on every assistant message so a stalled agent (no messages
+// flowing) lets the row go stale and the reader can mark it failed.
+const HEARTBEAT_MIN_INTERVAL_MS = 15_000;
+export async function runRecipesPhase(options) {
+    const { productId, scanId, guidance, verbose } = options;
+    logInfo(`Starting recipes scan for product ${productId}`);
+    const supabase = getSupabase();
+    const claimed = await markRunning(supabase, scanId);
+    if (!claimed) {
+        return {
+            status: 'cancelled',
+            message: 'Recipe scan row is no longer in a runnable state (likely cancelled before the CLI started)',
+        };
+    }
+    const teamId = await getProductTeamId(supabase, productId);
+    if (!teamId) {
+        const msg = 'Product is not associated with a team; recipes are team-scoped and require one.';
+        await markFailed(supabase, scanId, msg);
+        return { status: 'error', message: msg };
+    }
+    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 markFailed(supabase, scanId, 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, scanMeta, teamRecipes, existingLinks] = await Promise.all([
+            fetchProductBasics(productId),
+            getScanCreator(supabase, scanId),
+            listTeamRecipes(supabase, teamId),
+            listProductRecipeLinks(supabase, productId),
+        ]);
+        if (!scanMeta) {
+            const msg = 'recipe_scans row vanished mid-run; aborting';
+            await markFailed(supabase, scanId, msg);
+            return { status: 'error', message: msg };
+        }
+        const systemPrompt = createRecipesSystemPrompt();
+        const userPrompt = createRecipesUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            guidance,
+            teamRecipes,
+            existingLinks: existingLinks.map((l) => ({
+                recipeId: l.recipe_id,
+                name: l.name,
+            })),
+        });
+        const counts = createRecipesMutationCounts();
+        const existingLinkIds = new Set(existingLinks.map((l) => l.recipe_id));
+        const mcpServer = createRecipesMcpServer({
+            supabase,
+            teamId,
+            productId,
+            createdBy: scanMeta.created_by,
+        }, counts, teamRecipes, existingLinkIds);
+        logInfo('Running Claude agent to identify recipes...');
+        let lastHeartbeatAt = 0;
+        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: {
+                    recipes: mcpServer,
+                },
+            },
+        })) {
+            if (message.type === 'assistant') {
+                extractTextFromContent(message.message?.content ?? [], verbose);
+                const now = Date.now();
+                if (now - lastHeartbeatAt >= HEARTBEAT_MIN_INTERVAL_MS) {
+                    lastHeartbeatAt = now;
+                    await heartbeat(supabase, scanId);
+                }
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            if (message.subtype !== 'success') {
+                const msg = `Recipes scan failed: agent ${message.subtype}`;
+                const written = await markFailed(supabase, scanId, msg);
+                return {
+                    status: written ? 'error' : 'cancelled',
+                    message: written
+                        ? msg
+                        : 'Scan was cancelled while the agent was running',
+                    counts,
+                };
+            }
+            const written = await markSuccess(supabase, scanId);
+            if (!written) {
+                return {
+                    status: 'cancelled',
+                    message: 'Scan was cancelled before the result could be written',
+                    counts,
+                };
+            }
+            succeeded = true;
+            const summary = `created ${counts.created}, updated ${counts.updated}, linked ${counts.linked}, unlinked ${counts.unlinked}`;
+            logSuccess(`Recipes scan complete — ${summary}`);
+            return {
+                status: 'success',
+                message: `Recipes scan complete (${summary})`,
+                counts,
+            };
+        }
+        const msg = 'Recipes scan ended without a result message';
+        await markFailed(supabase, scanId, msg);
+        return { status: 'error', message: msg, counts };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Recipes scan failed: ${errorMessage}`);
+        await markFailed(supabase, scanId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(repoPath);
+        }
+    }
+}
+// ============================================================================
+// DB helpers — exported for unit tests
+// ============================================================================
+export async function getProductTeamId(supabase, productId) {
+    const { data, error } = await supabase
+        .from('products')
+        .select('team_id')
+        .eq('id', productId)
+        .maybeSingle();
+    if (error || !data) {
+        return null;
+    }
+    return data.team_id ?? null;
+}
+export async function getScanCreator(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('recipe_scans')
+        .select('created_by')
+        .eq('id', scanId)
+        .maybeSingle();
+    if (error || !data) {
+        return null;
+    }
+    return data;
+}
+export async function listTeamRecipes(supabase, teamId) {
+    const { data, error } = await supabase
+        .from('recipes')
+        .select('id, name, summary, services')
+        .eq('team_id', teamId)
+        .order('updated_at', { ascending: false });
+    if (error || !data) {
+        return [];
+    }
+    return data.map((r) => ({
+        id: r.id,
+        name: r.name,
+        summary: r.summary,
+        services: Array.isArray(r.services) ? r.services : [],
+    }));
+}
+export async function listProductRecipeLinks(supabase, productId) {
+    const { data, error } = await supabase
+        .from('product_recipes')
+        .select('recipe_id, recipes(name)')
+        .eq('product_id', productId);
+    if (error || !data) {
+        return [];
+    }
+    const rows = data;
+    const out = [];
+    for (const r of rows) {
+        const recipe = Array.isArray(r.recipes) ? r.recipes[0] : r.recipes;
+        if (recipe) {
+            out.push({ recipe_id: r.recipe_id, name: recipe.name });
+        }
+    }
+    return out;
+}
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export async function markRunning(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('recipe_scans')
+        .update({
+        status: 'running',
+        error: null,
+        last_heartbeat_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as running: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function heartbeat(supabase, scanId) {
+    const { error } = await supabase
+        .from('recipe_scans')
+        .update({ last_heartbeat_at: new Date().toISOString() })
+        .eq('id', scanId)
+        .eq('status', 'running');
+    if (error) {
+        logWarning(`Heartbeat failed: ${error.message}`);
+    }
+}
+export async function markFailed(supabase, scanId, errorMessage) {
+    const { data, error } = await supabase
+        .from('recipe_scans')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as failed: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function markSuccess(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('recipe_scans')
+        .update({
+        status: 'success',
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as success: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}

package/dist/phases/recipes/mcp-server.d.ts

@@ -0,0 +1,63 @@
+/**
+ * In-process MCP server exposing the recipes toolkit. Five tools:
+ *
+ *   - get_recipe_detail  read-only: fetch full content of a team recipe
+ *   - create_recipe      INSERT recipe + INSERT product_recipe link
+ *   - update_recipe      UPDATE recipe (latest-wins overwrite) + UPSERT link
+ *   - link_recipe        UPSERT product_recipe link only (no content change)
+ *   - unlink_recipe      DELETE product_recipe link for a previously-linked
+ *                        recipe the agent confirmed is no longer present
+ *
+ * All writes are scoped to:
+ *   - the active recipe_scan's product_id (the link target)
+ *   - the team that owns that product (recipes are team-scoped)
+ *
+ * The handlers persist directly via the Supabase client passed in by the
+ * orchestrator — there is no captured-extraction buffer to flush at the
+ * end. Each tool call is its own committed effect.
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { z } from 'zod';
+import { type RecipeSummary } from './types.js';
+export interface RecipesToolContext {
+    supabase: SupabaseClient;
+    teamId: string;
+    productId: string;
+    createdBy: string;
+}
+/**
+ * Records how many of each kind of mutation the agent made — exported so the
+ * orchestrator can print a summary line at the end of the scan.
+ */
+export interface RecipesMutationCounts {
+    created: number;
+    updated: number;
+    linked: number;
+    unlinked: number;
+}
+export declare function createRecipesMutationCounts(): RecipesMutationCounts;
+export declare function createGetRecipeDetailTool(ctx: RecipesToolContext, teamRecipeIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    recipe_id: z.ZodString;
+}>;
+export declare function createCreateRecipeTool(ctx: RecipesToolContext, counts: RecipesMutationCounts, teamRecipeIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    name: z.ZodString;
+    summary: z.ZodString;
+    content: z.ZodString;
+    services: z.ZodArray<z.ZodString>;
+    evidence: z.ZodString;
+}>;
+export declare function createUpdateRecipeTool(ctx: RecipesToolContext, counts: RecipesMutationCounts, teamRecipeIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    recipe_id: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    services: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    evidence: z.ZodString;
+}>;
+export declare function createLinkRecipeTool(ctx: RecipesToolContext, counts: RecipesMutationCounts, teamRecipeIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    recipe_id: z.ZodString;
+    evidence: z.ZodString;
+}>;
+export declare function createUnlinkRecipeTool(ctx: RecipesToolContext, counts: RecipesMutationCounts, existingLinkIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    recipe_id: z.ZodString;
+}>;
+export declare function createRecipesMcpServer(ctx: RecipesToolContext, counts: RecipesMutationCounts, teamRecipes: RecipeSummary[], existingLinkIds: Set<string>): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;