@agentrysh/mcp 0.0.14 → 0.0.15

package/dist/tools.js

@@ -6,13 +6,38 @@ import { api } from "./api.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { getOnboardingHint } from "./onboarding.js";
 import { getMemoryPath, readCaseSection, upsertCaseSection, MEMORY_FILENAME, } from "./memory.js";
+import * as frictionTracker from "./friction-tracker.js";
 import * as fs from "node:fs";
 export const TOOL_DESCRIPTORS = [
     {
         name: "agentry_status",
         description: "Show what's set up locally and what to do next. Always safe to call. " +
-            "Use this first if you don't know whether the user has signed up or has a project.",
-        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            "Use this first if you don't know whether the user has signed up or has a project. " +
+            "" +
+            "If shapes + flags are passed (same vocabulary as agentry_recipe_requirements), the " +
+            "response also includes a coverage_gap report — applicable_count, runnable_count, and " +
+            "the events / event-properties still missing for full recipe runnability. Useful for " +
+            "re-installs and post-install audits: 'ready, but seat-utilization is one property " +
+            "away from working' is a more honest status than just 'ready'.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                shapes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional. App shapes for coverage check (e.g. ['b2b-saas', 'devtools-api']). " +
+                        "When passed, response includes coverage_gap. Without it, status is project-only.",
+                },
+                has_revenue: { type: "boolean" },
+                is_b2b: { type: "boolean" },
+                is_two_sided: { type: "boolean" },
+                project_id: {
+                    type: "string",
+                    description: "Project id for the coverage check. Defaults to default_project_id.",
+                },
+            },
+            additionalProperties: false,
+        },
     },
     {
         name: "agentry_login",
@@ -986,13 +1011,16 @@ export const TOOL_DESCRIPTORS = [
     },
     {
         name: "agentry_verify_install",
-        description: "Comprehensive sanity check: fires a synthetic error, a synthetic analytics event, and a synthetic " +
-            "deploy event, then reports which signal types reached agentry. Run this AFTER walking through " +
-            "agentry_install_guide. " +
-            "MUST be run with NO skipped signal types on a first-time install — the install is not done until " +
-            "all three return OK. If any signal returns FAIL, the corresponding wire_* step was skipped or " +
-            "wired incorrectly; the agent must go back and fix it before declaring the install complete. Do not " +
-            "report 'installed' to the user with one or two ✅s and a ❌; that's a half-install.",
+        description: "Comprehensive sanity check. Fires a synthetic error, analytics event, and deploy event AND " +
+            "— if shapes are provided — checks PostHog for the events the user's applicable recipes need. " +
+            "Run this AFTER walking through agentry_install_guide. " +
+            "" +
+            "MUST be run with NO skipped signal types on a first-time install. The install is not done " +
+            "until all three signals are OK AND every event from `required_events` (derived from the app's " +
+            "shape via agentry_recipe_requirements) is actually firing in PostHog. " +
+            "" +
+            "Do not report 'installed' to the user with one or two ✅s and a ❌, or with synthetic ✅s but " +
+            "missing recipe events — that's a half-install.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1003,6 +1031,26 @@ export const TOOL_DESCRIPTORS = [
                     description: "ONLY for re-runs after a partial install has already been verified. On a first install, " +
                         "leave this empty — all three signal types must verify before the install counts as done.",
                 },
+                shapes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "App shape(s) the agent detected during investigate_app_structure (e.g. ['b2b-saas', " +
+                        "'devtools-api']). When passed, verify_install also queries PostHog for the events the " +
+                        "applicable docs recipes need and reports which recipes are blocked. Strongly recommended " +
+                        "on first install — without it you only know the pipe works, not that the recipes will run.",
+                },
+                has_revenue: {
+                    type: "boolean",
+                    description: "Payment processor detected. Used with shapes to filter applicable recipes.",
+                },
+                is_b2b: {
+                    type: "boolean",
+                    description: "Workspace/account/seat model present. Used with shapes to filter applicable recipes.",
+                },
+                is_two_sided: {
+                    type: "boolean",
+                    description: "Two-sided marketplace. Used with shapes to filter applicable recipes.",
+                },
             },
             additionalProperties: false,
         },
@@ -1025,6 +1073,49 @@ export const TOOL_DESCRIPTORS = [
             additionalProperties: false,
         },
     },
+    {
+        name: "agentry_recipe_requirements",
+        description: "Recipe-driven install gate. Given the user's detected app shape(s) and revenue/B2B/two-sided " +
+            "flags, returns the *applicable* docs recipes and the UNION of events they need. The install guide " +
+            "uses this output as the canonical event inventory: every event in `required_events` MUST be wired, " +
+            "with the listed `required_event_properties` attached, before agentry_verify_install passes. " +
+            "" +
+            "CALL THIS during agentry_install_guide's inventory step, AFTER categorizing the app, BEFORE writing " +
+            "any track() calls. Don't hand-build an AARRR inventory — let the recipe catalog drive what to " +
+            "instrument so the user can actually run the recipes a week / month later. " +
+            "" +
+            "shapes: comma-sep app shapes from the install-guide vocabulary (b2c-saas, b2b-saas, ecommerce, " +
+            "marketplace, content-media, devtools-api, games, internal-tool, single-purchase, open-source, " +
+            "enterprise-sales, mobile-app). 'universal' recipes always match. " +
+            "has_revenue: true if the app has a payment processor (stripe/paddle/etc.) — gates revenue recipes. " +
+            "is_b2b: true if the app has workspaces/accounts/seats — gates B2B recipes. " +
+            "is_two_sided: true if the app is a marketplace with supply/demand — gates marketplace recipes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                shapes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "App shape(s) detected during investigate_app_structure. Apps can straddle (e.g. a B2B SaaS " +
+                        "that's also a devtools API). Pass every shape that fits — applicable recipes are the union.",
+                },
+                has_revenue: {
+                    type: "boolean",
+                    description: "Payment processor present in the codebase. Gates trial/subscription/churn recipes.",
+                },
+                is_b2b: {
+                    type: "boolean",
+                    description: "Workspace/account/seat model present. Gates account-health, seat-utilization, etc.",
+                },
+                is_two_sided: {
+                    type: "boolean",
+                    description: "Two-sided marketplace. Gates supply-side/liquidity recipes.",
+                },
+            },
+            required: ["shapes"],
+            additionalProperties: false,
+        },
+    },
     {
         name: "agentry_run_recipe",
         description: "Run a recipe by id. Returns rows + a render_hint the agent uses to format the answer " +
@@ -1264,12 +1355,19 @@ export const TOOL_DESCRIPTORS = [
     {
         name: "agentry_send_feedback",
         description: "File feedback for the agentry team when something doesn't work or is missing. " +
-            "Call this in exactly two situations: " +
+            "Call this in three situations: " +
             "(1) the user explicitly asks for a feature that doesn't exist or expresses frustration that agentry " +
             "isn't doing what they want ('I wish it could…', 'why doesn't it…', 'this doesn't work', " +
             "'feature request: …'); " +
             "(2) you have made 2+ failed attempts at the same task — same MCP tool returning errors, or repeatedly " +
-            "failing to find a recipe/route for what the user asked. " +
+            "failing to find a recipe/route for what the user asked; " +
+            "(3) RECIPE PROPOSAL — during agentry_install_guide's plan-confirmation step, the user named a " +
+            "question they want to be able to ask that ISN'T in the docs recipe catalog. Use " +
+            "`kind: 'recipe_proposal'`, quote the user's question in `message`, and put a structured " +
+            "proposal in `agent_note` (the JSON shape described under that field). This is the only path " +
+            "from a customer's install back into the recipe catalog — without it, every novel question " +
+            "stays stranded in chat history. " +
+            "" +
             "File it ONCE per distinct issue per session — don't spam. Quote the user verbatim in `message` where " +
             "possible. Don't apologize repeatedly to the user; just tell them you've logged it.",
         inputSchema: {
@@ -1277,9 +1375,13 @@ export const TOOL_DESCRIPTORS = [
             properties: {
                 kind: {
                     type: "string",
-                    enum: ["missing_feature", "bug", "ux_friction", "other"],
+                    enum: ["missing_feature", "bug", "ux_friction", "recipe_proposal", "other"],
                     description: "missing_feature = capability doesn't exist; bug = something behaves wrong; " +
-                        "ux_friction = works but is awkward/confusing; other = anything else.",
+                        "ux_friction = works but is awkward/confusing; " +
+                        "recipe_proposal = user named a question to ask that no docs recipe covers — " +
+                        "use during install flow; agent_note MUST include the proposed applies_to / " +
+                        "required_events / required_event_properties so the catalog can absorb it; " +
+                        "other = anything else.",
                 },
                 message: {
                     type: "string",
@@ -1289,7 +1391,17 @@ export const TOOL_DESCRIPTORS = [
                 agent_note: {
                     type: "string",
                     description: "Optional: what YOU (the agent) were trying to do, which tools you called, what failed. " +
-                        "Helps the agentry team reproduce.",
+                        "Helps the agentry team reproduce. " +
+                        "" +
+                        "FOR kind='recipe_proposal' THIS FIELD IS REQUIRED and must be JSON-shaped, e.g.: " +
+                        "{\"applies_to\": [\"b2b-saas\"], \"requires_revenue\": true, \"required_events\": " +
+                        "[\"workspace_created\", \"template_first_action\"], \"required_event_properties\": " +
+                        "{\"workspace_created\": [\"starter_template\"]}, \"category\": \"growth\", " +
+                        "\"suggested_title\": \"Which starter template has the highest 30-day retention?\", " +
+                        "\"detected_shape_evidence\": \"workspaces.starter_template column present at " +
+                        "db/schema.ts:23\", \"new_events_wired\": [\"workspace_created.starter_template\", " +
+                        "\"template_first_action\"]}. " +
+                        "The catalog maintainers paste this shape into a new recipe.md with minimal editing.",
                 },
                 tool_name: {
                     type: "string",
@@ -1498,10 +1610,49 @@ function buildSyntheticEvent() {
 }
 export async function dispatchTool(name, args) {
     const a = args ?? {};
+    let result;
+    try {
+        result = await dispatchToolInner(name, a);
+    }
+    catch (err) {
+        frictionTracker.recordCall({
+            tool: name,
+            ts: Date.now(),
+            ok: false,
+            errorCode: err instanceof Error ? err.message.slice(0, 80) : String(err).slice(0, 80),
+        });
+        // Repeated-failure detector — fires when same tool errors N times in a row.
+        try {
+            frictionTracker.detectRepeatedFailure(loadConfig(), name);
+        }
+        catch { /* swallow — observability never breaks the request */ }
+        return summarizeApiError(err);
+    }
+    // Record success/failure outcome. `error` shape on the result means handler
+    // returned an error envelope without throwing.
+    const ok = !("error" in (result ?? {}));
+    frictionTracker.recordCall({ tool: name, ts: Date.now(), ok });
+    try {
+        if (!ok)
+            frictionTracker.detectRepeatedFailure(loadConfig(), name);
+        if (name === "agentry_install_guide") {
+            frictionTracker.detectGuideRefetched(loadConfig());
+        }
+    }
+    catch { /* swallow */ }
+    return result;
+}
+async function dispatchToolInner(name, a) {
     try {
         switch (name) {
             case "agentry_status":
-                return handleStatus();
+                return await handleStatus({
+                    shapes: Array.isArray(a.shapes) ? a.shapes.map(String) : undefined,
+                    has_revenue: a.has_revenue === true,
+                    is_b2b: a.is_b2b === true,
+                    is_two_sided: a.is_two_sided === true,
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
             case "agentry_login":
                 return await handleLogin({
                     mode: a.mode === "start_only" || a.mode === "poll_once"
@@ -1784,9 +1935,20 @@ export async function dispatchTool(name, args) {
                 return await handleVerifyInstall({
                     project_id: a.project_id ? String(a.project_id) : undefined,
                     skip: Array.isArray(a.skip) ? a.skip.map(String) : [],
+                    shapes: Array.isArray(a.shapes) ? a.shapes.map(String) : undefined,
+                    has_revenue: a.has_revenue === true,
+                    is_b2b: a.is_b2b === true,
+                    is_two_sided: a.is_two_sided === true,
                 });
             case "agentry_list_recipes":
                 return await handleListRecipes(a.category ? String(a.category) : undefined);
+            case "agentry_recipe_requirements":
+                return await handleRecipeRequirements({
+                    shapes: Array.isArray(a.shapes) ? a.shapes.map(String) : [],
+                    has_revenue: a.has_revenue === true,
+                    is_b2b: a.is_b2b === true,
+                    is_two_sided: a.is_two_sided === true,
+                });
             case "agentry_run_recipe":
                 return await handleRunRecipe({
                     recipe_id: String(a.recipe_id ?? ""),
@@ -1908,14 +2070,15 @@ export async function dispatchTool(name, args) {
         return summarizeApiError(err);
     }
 }
+// dispatchToolInner is closed above. Below: handlers.
 // ---------------------------------------------------------------------------
 // Tool handlers
 // ---------------------------------------------------------------------------
-function handleStatus() {
+async function handleStatus(input) {
     const cfg = loadConfig();
     const hint = getOnboardingHint(cfg);
     const projectIds = Object.keys(cfg.projects);
-    return {
+    const baseResult = {
         server_url: cfg.server_url,
         has_api_key: Boolean(cfg.api_key),
         api_key_prefix: cfg.api_key ? `${cfg.api_key.slice(0, 8)}…` : null,
@@ -1932,8 +2095,90 @@ function handleStatus() {
             };
         }),
         onboarding: hint,
-        next_steps: [hint.message, hint.next_action],
     };
+    // Coverage check — only runs when shapes are passed AND we have a project + api key.
+    // Independent of the onboarding hint above: status can be "ready" (synthetic signals
+    // verified) while still having coverage gaps (events firing without required props).
+    if (input?.shapes && input.shapes.length > 0 && cfg.api_key) {
+        const projectId = input.project_id ?? cfg.default_project_id;
+        if (projectId) {
+            try {
+                const reqs = await api.recipeRequirements(cfg, {
+                    shapes: input.shapes,
+                    has_revenue: input.has_revenue === true,
+                    is_b2b: input.is_b2b === true,
+                    is_two_sided: input.is_two_sided === true,
+                });
+                const events = await api.listEventNames(cfg, projectId);
+                const eventNames = new Set([
+                    ...(events.server_emitted ?? []),
+                    ...(events.analytics_events ?? []).map((e) => e.event),
+                ]);
+                // Sample property keys for events that ARE present and have required props.
+                const checkProps = new Set();
+                for (const rec of reqs.applicable) {
+                    for (const ev of Object.keys(rec.required_event_properties || {})) {
+                        if (eventNames.has(ev))
+                            checkProps.add(ev);
+                    }
+                }
+                let sampledKeys = {};
+                if (checkProps.size > 0) {
+                    try {
+                        const r = await api.eventPropertyKeys(cfg, projectId, [...checkProps]);
+                        sampledKeys = r.keys ?? {};
+                    }
+                    catch { /* best-effort */ }
+                }
+                const blocked = [];
+                const runnableIds = [];
+                for (const rec of reqs.applicable) {
+                    const missingEv = rec.required_events.filter((e) => !eventNames.has(e));
+                    const missingProp = {};
+                    for (const [ev, props] of Object.entries(rec.required_event_properties || {})) {
+                        if (!eventNames.has(ev))
+                            continue;
+                        const present = new Set(sampledKeys[ev] ?? []);
+                        const m = props.filter((p) => !present.has(p));
+                        if (m.length > 0)
+                            missingProp[ev] = m;
+                    }
+                    if (missingEv.length === 0 && Object.keys(missingProp).length === 0)
+                        runnableIds.push(rec.id);
+                    else
+                        blocked.push({ id: rec.id, title: rec.title, missing_events: missingEv, missing_properties: missingProp });
+                }
+                const missingEvUnion = new Set();
+                const missingPropUnion = new Set();
+                for (const b of blocked) {
+                    for (const e of b.missing_events)
+                        missingEvUnion.add(e);
+                    for (const [ev, props] of Object.entries(b.missing_properties))
+                        for (const p of props)
+                            missingPropUnion.add(`${ev}.${p}`);
+                }
+                baseResult.coverage_gap = {
+                    shapes: input.shapes,
+                    applicable_count: reqs.applicable_count,
+                    runnable_count: runnableIds.length,
+                    missing_events: [...missingEvUnion].sort(),
+                    missing_event_properties: [...missingPropUnion].sort(),
+                    blocked_recipes: blocked.map((b) => b.id),
+                    summary: `${runnableIds.length}/${reqs.applicable_count} applicable recipes runnable. ` +
+                        (missingEvUnion.size > 0 ? `Missing events: ${[...missingEvUnion].sort().join(", ")}. ` : "") +
+                        (missingPropUnion.size > 0 ? `Missing properties: ${[...missingPropUnion].sort().join(", ")}.` : ""),
+                };
+            }
+            catch (err) {
+                baseResult.coverage_gap = {
+                    error: err instanceof Error ? err.message : String(err),
+                    note: "coverage_gap requires logged-in api key + an existing project. Skipping.",
+                };
+            }
+        }
+    }
+    baseResult.next_steps = [hint.message, hint.next_action];
+    return baseResult;
 }
 async function handleLogin(input) {
     const cfg = loadConfig();
@@ -3297,10 +3542,21 @@ async function handleAnalyticsQuery(input) {
         };
     }
     const resp = await api.analyticsQuery(cfg, projectId, input.query);
+    // Friction: query references a named event in WHERE and got 0 rows back.
+    // Heuristic-driven (detector inspects the query string); fires only when
+    // a specific event name returned empty — most likely a missing-instrumentation
+    // or wrong-event-name signal worth flagging for AI review.
+    const rowsReturned = Array.isArray(resp.results) ? resp.results.length : 0;
+    const frictionFp = frictionTracker.detectEmptyAnalyticsQuery(cfg, {
+        query: input.query,
+        project_id: projectId,
+        rows_returned: rowsReturned,
+    });
     return {
         project_id: projectId,
         ...resp,
-        next_action: "Interpret the rows. If you suspect a regression, call agentry_list_deploys to see if a deploy correlates.",
+        next_action: "Interpret the rows. If you suspect a regression, call agentry_list_deploys to see if a deploy correlates." +
+            frictionTracker.frictionNoticeSuffix(frictionFp),
     };
 }
 // ---------------------------------------------------------------------------
@@ -3433,22 +3689,151 @@ async function handleVerifyInstall(input) {
                         "call agentry_repair_analytics, then re-run verify. "
                     : "") +
                 "For each failed type, re-read its corresponding step in agentry_install_guide and fix.";
+    // ── Recipe runnability check ───────────────────────────────────────────
+    // If the agent passed shapes, derive the required-events set and check
+    // PostHog for each. Report per-recipe runnability so the agent knows
+    // which docs recipes the user will actually be able to run.
+    let recipeCheck = {
+        requested: false,
+        applicable_count: 0,
+        runnable_count: 0,
+        runnable: [],
+        blocked: [],
+        missing_events: [],
+        missing_event_properties: [],
+    };
+    if (input.shapes && input.shapes.length > 0 && checks.analytics?.ok) {
+        try {
+            const cfg2 = loadConfig();
+            const reqs = await api.recipeRequirements(cfg2, {
+                shapes: input.shapes,
+                has_revenue: input.has_revenue === true,
+                is_b2b: input.is_b2b === true,
+                is_two_sided: input.is_two_sided === true,
+            });
+            // Snapshot the distinct event names currently firing in this project.
+            // listEventNames returns both server-emitted (PostHog $events) and analytics_events
+            // (PostHog person events with counts). Union them — recipes can need either.
+            const events = await api.listEventNames(cfg2, r.id);
+            const eventNames = new Set([
+                ...(events.server_emitted ?? []),
+                ...(events.analytics_events ?? []).map((e) => e.event),
+            ]);
+            // Sample property keys for the union of required events present, so we
+            // can confirm not just event presence but that the properties recipes
+            // depend on are actually being attached.
+            const eventsNeedingProps = [];
+            const propsByEvent = {};
+            for (const rec of reqs.applicable) {
+                for (const [ev, props] of Object.entries(rec.required_event_properties || {})) {
+                    if (!eventNames.has(ev))
+                        continue; // event missing entirely; separate check handles
+                    eventsNeedingProps.push(ev);
+                    for (const p of props) {
+                        propsByEvent[ev] = propsByEvent[ev] || [];
+                        if (!propsByEvent[ev].includes(p))
+                            propsByEvent[ev].push(p);
+                    }
+                }
+            }
+            let sampledKeys = {};
+            if (eventsNeedingProps.length > 0) {
+                try {
+                    const resp = await api.eventPropertyKeys(cfg2, r.id, [...new Set(eventsNeedingProps)]);
+                    sampledKeys = resp.keys ?? {};
+                }
+                catch {
+                    // best-effort — if property sampling fails, fall back to event-presence-only
+                }
+            }
+            const runnable = [];
+            const blocked = [];
+            for (const rec of reqs.applicable) {
+                const missingEvents = rec.required_events.filter((ev) => !eventNames.has(ev));
+                const missingProps = {};
+                for (const [ev, props] of Object.entries(rec.required_event_properties || {})) {
+                    if (!eventNames.has(ev))
+                        continue;
+                    const present = new Set(sampledKeys[ev] ?? []);
+                    const missing = props.filter((p) => !present.has(p));
+                    if (missing.length > 0)
+                        missingProps[ev] = missing;
+                }
+                if (missingEvents.length === 0 && Object.keys(missingProps).length === 0) {
+                    runnable.push(rec.id);
+                }
+                else {
+                    blocked.push({
+                        id: rec.id,
+                        title: rec.title,
+                        missing_events: missingEvents,
+                        missing_properties: missingProps,
+                    });
+                }
+            }
+            const missingUnion = new Set();
+            const missingPropUnion = new Set();
+            for (const b of blocked) {
+                for (const m of b.missing_events)
+                    missingUnion.add(m);
+                for (const [ev, props] of Object.entries(b.missing_properties)) {
+                    for (const p of props)
+                        missingPropUnion.add(`${ev}.${p}`);
+                }
+            }
+            recipeCheck = {
+                requested: true,
+                applicable_count: reqs.applicable_count,
+                runnable_count: runnable.length,
+                runnable,
+                blocked,
+                missing_events: [...missingUnion].sort(),
+                missing_event_properties: [...missingPropUnion].sort(),
+            };
+        }
+        catch (err) {
+            recipeCheck.skipped_reason = err instanceof Error ? err.message : String(err);
+        }
+    }
+    else if (input.shapes && input.shapes.length > 0) {
+        recipeCheck.skipped_reason = "analytics signal failed — fix analytics first, then re-run verify with shapes";
+    }
+    else {
+        recipeCheck.skipped_reason =
+            "no shapes provided — pass shapes/has_revenue/is_b2b/is_two_sided to verify recipe runnability";
+    }
+    const recipeFailing = recipeCheck.requested && recipeCheck.runnable_count < recipeCheck.applicable_count;
+    const allOk = failed.length === 0 && !recipeFailing;
     return {
-        ok: failed.length === 0,
-        summary: `${passed.length}/${Object.keys(checks).length} signal types verified`,
+        ok: allOk,
+        summary: `${passed.length}/${Object.keys(checks).length} signal types verified` +
+            (recipeCheck.requested
+                ? `; ${recipeCheck.runnable_count}/${recipeCheck.applicable_count} applicable recipes runnable`
+                : ""),
         passed,
         failed,
         checks,
+        recipe_check: recipeCheck,
         suggested_next_steps: nextSuggestions,
-        next_action: failed.length === 0 && nextSuggestions.length > 0
-            ? baseAction +
-                " Now offer the user this menu of post-install prompts:\n" +
-                nextSuggestions
-                    .slice(0, 5)
-                    .map((s, i) => `  ${i + 1}. ${s.title} — ${s.description}`)
-                    .join("\n") +
-                "\nWhen the user picks one, paste its `prompt_template` as their next prompt (or just execute the listed `uses`)."
-            : baseAction,
+        next_action: recipeFailing
+            ? `Install is HALF-DONE. Synthetic signals work, but ${recipeCheck.applicable_count - recipeCheck.runnable_count} of ${recipeCheck.applicable_count} applicable recipes are blocked.` +
+                (recipeCheck.missing_events.length > 0
+                    ? ` Missing events: ${recipeCheck.missing_events.join(", ")}.`
+                    : "") +
+                (recipeCheck.missing_event_properties.length > 0
+                    ? ` Missing required properties (event.property): ${recipeCheck.missing_event_properties.join(", ")} — events fire but lack required properties.`
+                    : "") + " " +
+                `Go back to the install-guide step \`track_comprehensively_for_this_app\` and wire the missing events. ` +
+                `Re-run agentry_verify_install with the same shapes when done. Do NOT tell the user 'installed' until this is 0 missing.`
+            : failed.length === 0 && nextSuggestions.length > 0
+                ? baseAction +
+                    " Now offer the user this menu of post-install prompts:\n" +
+                    nextSuggestions
+                        .slice(0, 5)
+                        .map((s, i) => `  ${i + 1}. ${s.title} — ${s.description}`)
+                        .join("\n") +
+                    "\nWhen the user picks one, paste its `prompt_template` as their next prompt (or just execute the listed `uses`)."
+                : baseAction,
     };
 }
 // ---------------------------------------------------------------------------
@@ -3464,6 +3849,20 @@ async function handleListRecipes(category) {
             "If nothing matches, call `agentry_query_docs` to compose ad-hoc HogQL via `agentry_analytics_query`.",
     };
 }
+async function handleRecipeRequirements(input) {
+    if (input.shapes.length === 0) {
+        return {
+            error: {
+                code: "missing_shapes",
+                message: "shapes is required (e.g. ['b2c-saas'], ['devtools-api', 'b2b-saas'])",
+                next_action: "Re-call agentry_recipe_requirements with the app shape(s) detected during " +
+                    "investigate_app_structure. See the description for the allowed vocabulary.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    return await api.recipeRequirements(cfg, input);
+}
 async function handleRunRecipe(input) {
     if (!input.recipe_id) {
         return {
@@ -3495,9 +3894,19 @@ async function handleRunRecipe(input) {
         };
     }
     const resp = await api.runRecipe(cfg, projectId, input.recipe_id, input.params);
+    // Aggressive friction detection: a recipe that runs without errors but
+    // returns 0 rows almost always means required events aren't firing. Fire
+    // feedback to the agentry team for AI review.
+    const rowsReturned = Array.isArray(resp.rows) ? resp.rows.length : 0;
+    const frictionFp = frictionTracker.detectEmptyRecipe(cfg, {
+        recipe_id: input.recipe_id,
+        project_id: projectId,
+        rows_returned: rowsReturned,
+    });
     return {
         project_id: projectId,
         ...resp,
+        next_action: (resp.next_action ?? "") + frictionTracker.frictionNoticeSuffix(frictionFp),
     };
 }
 async function handleQueryDocs() {