@agentrysh/mcp 0.0.1

package/dist/tools.js

@@ -0,0 +1,1906 @@
+// MCP tool definitions + dispatch.
+// Each tool's response is shaped to give the calling agent enough context to
+// choose its next action without re-asking the user.
+import { parseDsn } from "@agentrysh/shared";
+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 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 },
+    },
+    {
+        name: "agentry_login",
+        description: "Authenticate the user via GitHub device flow. " +
+            "Starts the flow, shows the user a verification URL and a short code, then polls until they authorize. " +
+            "Returns an API key and stores it locally. " +
+            "By default the tool blocks until success or timeout; " +
+            "use `mode: 'start_only'` to return the verification details without polling, or `mode: 'poll_once'` with `device_code` to do a single non-blocking poll.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                mode: {
+                    type: "string",
+                    enum: ["full", "start_only", "poll_once"],
+                    description: "'full' (default) starts and polls until done. " +
+                        "'start_only' returns the verification URL + code + device_code immediately. " +
+                        "'poll_once' takes device_code and does a single poll.",
+                },
+                device_code: {
+                    type: "string",
+                    description: "Required when mode='poll_once'.",
+                },
+                timeout_seconds: {
+                    type: "number",
+                    description: "Cap on total polling time when mode='full'. Defaults to 180.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_rotate_key",
+        description: "Rotate the current API key. The old key is revoked. The new one is stored locally.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "agentry_list_projects",
+        description: "List all projects belonging to the authenticated user. " +
+            "Each entry is enriched with `local_path` from local config so the agent knows where to `cd`.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "agentry_create_project",
+        description: "Create a new project. Returns the DSN and SDK install snippet ready to paste. " +
+            "Pass `local_path` (the absolute path to the repo on disk) so future cases route back to the right directory.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Project name (e.g. 'musicvideogen-prod')" },
+                repo_url: { type: "string", description: "Optional git URL (e.g. https://github.com/user/repo)" },
+                local_path: { type: "string", description: "Absolute filesystem path to the repo on disk" },
+                default_branch: { type: "string", description: "Default branch (defaults to 'main')" },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_install_sdk",
+        description: "Get the SDK install snippet for a language. Returns code + env vars the user should paste into their app.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                language: {
+                    type: "string",
+                    description: "Language target. Defaults to 'node' (the only supported option in v0).",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_list_cases",
+        description: "List error cases for a project. Defaults to the local default project + status='open'. " +
+            "Each entry is enriched with `local_path` so the agent knows where to `cd` to investigate.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: {
+                    type: "string",
+                    description: "Project id. If omitted, uses the local default project.",
+                },
+                status: {
+                    type: "string",
+                    enum: ["open", "investigating", "resolved", "spurious", "ignored"],
+                    description: "Filter by status. Defaults to 'open'.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_get_case",
+        description: "Get full detail for a case — stack trace, deploy SHA, suppression hints, and `local_path`. " +
+            "Surface `next_actions` to the agent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                case_id: { type: "string", description: "Case id" },
+            },
+            required: ["case_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_resolve_case",
+        description: "Mark a case as resolved. Pass an optional summary and PR url so the team has audit trail.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                case_id: { type: "string" },
+                summary: { type: "string", description: "Short markdown summary of the fix" },
+                pr_url: { type: "string", description: "PR URL if you opened one" },
+            },
+            required: ["case_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_mark_spurious",
+        description: "Mark a case as spurious (not a real bug). Optionally provide `suppress_pattern` and a reason; " +
+            "if set, also records a suppression rule so future matching events are auto-ignored.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                case_id: { type: "string" },
+                reason: { type: "string", description: "Why this is noise" },
+                suppress_pattern: {
+                    type: "string",
+                    description: "Optional substring pattern to match the fingerprint, auto-ignoring future matches",
+                },
+            },
+            required: ["case_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_record_suppression",
+        description: "Record a noise-suppression rule for a project. Matches future events by fingerprint pattern. " +
+            "Actions: 'auto_ignore' (drop), 'auto_resolve' (mark resolved silently), 'prompt_hint' (attach hint to case).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: {
+                    type: "string",
+                    description: "Project id. If omitted, uses the local default project.",
+                },
+                fingerprint_pattern: {
+                    type: "string",
+                    description: "Substring match against the case fingerprint",
+                },
+                action: {
+                    type: "string",
+                    enum: ["auto_ignore", "auto_resolve", "prompt_hint"],
+                },
+                reason: { type: "string" },
+                hint_text: {
+                    type: "string",
+                    description: "Required when action is 'prompt_hint' — the hint surfaced via agentry_get_case",
+                },
+            },
+            required: ["fingerprint_pattern", "action"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_capture_test_event",
+        description: "Fire a synthetic Sentry-shaped event at the project's ingest endpoint to verify ingest works end-to-end. " +
+            "Returns the event id and (if the API surfaces it) the case id so you can immediately call agentry_get_case.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: {
+                    type: "string",
+                    description: "Project id. If omitted, uses the local default project.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_record_deploy",
+        description: "Record a deploy event. Useful when CI doesn't call the SDK directly. Cases ingested after this " +
+            "will surface the deploy in their `recent_deploys` so the agent can attribute regressions.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                sha: { type: "string", description: "Git SHA of the deployed commit" },
+                branch: { type: "string" },
+                environment: { type: "string", description: "e.g. 'production', 'staging'" },
+                message: { type: "string", description: "Commit / deploy message" },
+                url: { type: "string", description: "Deploy or commit URL" },
+                actor: { type: "string", description: "Person or service that triggered the deploy" },
+            },
+            required: ["sha"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_list_deploys",
+        description: "List recent deploys for a project. Useful for cross-referencing case timestamps with deploy timestamps.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                limit: { type: "number", description: "Defaults to 20" },
+                since: { type: "number", description: "Unix seconds — only return deploys after this" },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_track_test_event",
+        description: "Fire a synthetic analytics event through the agentry track endpoint to verify the PostHog forwarding " +
+            "is wired up. Returns whether the forwarding succeeded.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                event: {
+                    type: "string",
+                    description: "Event name. Defaults to 'agentry_verify'.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_analytics_query",
+        description: "Run a HogQL query against the user's PostHog project. The agent uses this to investigate funnels, " +
+            "retention, paths, anomalies — anything PostHog can express in HogQL. " +
+            "Examples: SELECT count() FROM events WHERE event = 'signup_completed' AND timestamp > now() - INTERVAL 7 DAY",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                query: { type: "string", description: "HogQL query string" },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_install_guide",
+        description: "Get the comprehensive, framework-aware install checklist. Returns ordered steps with file hints, " +
+            "code snippets, and validation criteria. The agent should read this BEFORE editing any customer code.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                framework: {
+                    type: "string",
+                    enum: ["node", "next", "express"],
+                    description: "Detected from package.json. Defaults to 'node'.",
+                },
+                signal_types: {
+                    type: "array",
+                    items: { type: "string", enum: ["errors", "analytics", "deploys"] },
+                    description: "Subset of signals to include. Defaults to all three.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_verify_install",
+        description: "Comprehensive sanity check: fires a synthetic error, a synthetic analytics event, and (if requested) " +
+            "a synthetic deploy event, then reports which signal types reached agentry. Run this AFTER walking " +
+            "through agentry_install_guide. Errors that don't error and analytics that don't fire aren't useful — " +
+            "this is the only proof the install actually works.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string" },
+                skip: {
+                    type: "array",
+                    items: { type: "string", enum: ["errors", "analytics", "deploys"] },
+                    description: "Signal types to skip (e.g. if the customer hasn't wired analytics yet)",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_list_recipes",
+        description: "List the canonical query recipes that answer common questions ('how many DAU?', " +
+            "'show me the funnel drop-off', 'errors after the last deploy?'). Each recipe has a " +
+            "HogQL/SQL template, parameters with defaults, expected columns, and a render_hint. " +
+            "Use this BEFORE composing ad-hoc HogQL — agentry has no dashboard, so the agent IS the dashboard.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    enum: ["users", "retention", "funnels", "events", "errors", "deploys"],
+                    description: "Optional category filter.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_run_recipe",
+        description: "Run a recipe by id. Returns rows + a render_hint the agent uses to format the answer " +
+            "(markdown table / ASCII bar chart / funnel breakdown / scalar). " +
+            "If no recipe fits the user's question, fall back to `agentry_analytics_query` with hand-rolled HogQL.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                recipe_id: { type: "string", description: "Recipe id from agentry_list_recipes." },
+                project_id: { type: "string", description: "Defaults to the local default project." },
+                params: {
+                    type: "object",
+                    description: "Parameter values keyed by name. Defaults are applied for any omitted.",
+                    additionalProperties: true,
+                },
+            },
+            required: ["recipe_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_query_docs",
+        description: "Return markdown documentation of the queryable schema (analytics events table, errors, " +
+            "deploys) plus a HogQL primer plus visualization hints. Read this when the user's question " +
+            "doesn't match any recipe and the agent needs to compose ad-hoc HogQL.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "agentry_project_health",
+        description: "Heartbeat / state-of-project view. Returns last_event_received_at, last_deploy_at, " +
+            "events_last_hour, open_cases count, usage_this_month with caps and percentages, and per-webhook " +
+            "last_status. Use this when the user asks 'is everything working?' or to detect ingest gaps " +
+            "('we shipped 2h ago and no events have come in — something broke').",
+        inputSchema: {
+            type: "object",
+            properties: { project_id: { type: "string" } },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_create_alert",
+        description: "Store an alert definition: a recipe + parameters + threshold + which webhook to fire. " +
+            "agentry doesn't run the schedule for you — your cron / GitHub Actions / Cloudflare Cron " +
+            "calls POST /alerts/:id/evaluate when you want the check run. On threshold cross, agentry " +
+            "fires the linked webhook so your endpoint reacts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                recipe_id: { type: "string", description: "Analytics-backend recipes only for v0." },
+                threshold_column: { type: "string" },
+                threshold_op: { type: "string", enum: ["gt", "gte", "lt", "lte", "eq"] },
+                threshold_value: { type: "number" },
+                params: { type: "object", additionalProperties: true },
+                description: { type: "string" },
+                webhook_id: { type: "string" },
+                project_id: { type: "string" },
+            },
+            required: ["name", "recipe_id", "threshold_column", "threshold_op", "threshold_value"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_list_alerts",
+        description: "List configured alerts with last_evaluated_at / last_triggered_at / last_value.",
+        inputSchema: {
+            type: "object",
+            properties: { project_id: { type: "string" } },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_evaluate_alert",
+        description: "Run an alert's recipe NOW, compare against the threshold, fire the linked webhook if crossed. " +
+            "Returns {triggered, fired, current_value}. Call this from your scheduler.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                alert_id: { type: "string" },
+                project_id: { type: "string" },
+            },
+            required: ["alert_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_delete_alert",
+        description: "Remove an alert definition.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                alert_id: { type: "string" },
+                project_id: { type: "string" },
+            },
+            required: ["alert_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_remember",
+        description: "Append/update a markdown section about a case in the local agentry_memory.md file at the project's local_path. " +
+            "Use this when you've learned something investigating a case (root cause, suspect deploy, the fix you applied, " +
+            "what to watch out for). Future investigations of similar cases will see these notes via the agent's file-reading " +
+            "tools — this is the agent's persistent memory. Safe to commit. " +
+            "If the case_id section already exists, it's overwritten.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                case_id: { type: "string" },
+                summary: {
+                    type: "string",
+                    description: "Markdown body — what was learned. Be specific: 'introduced by deploy abc123 which removed null guard from user.email; fixed in PR #91 by restoring guard + adding test'.",
+                },
+                fingerprint: { type: "string" },
+                status: { type: "string", description: "open / investigating / resolved / spurious" },
+                error_type: { type: "string" },
+                pr_url: { type: "string" },
+                watch_for: {
+                    type: "string",
+                    description: "Heuristic for spotting similar bugs in the future ('check notification_service.ts:142 for the same pattern').",
+                },
+                tags: { type: "array", items: { type: "string" } },
+                project_id: {
+                    type: "string",
+                    description: "Defaults to the local default project (the file lives in that project's local_path).",
+                },
+            },
+            required: ["case_id", "summary"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_recall",
+        description: "Read the current contents of `<local_path>/agentry_memory.md`. " +
+            "Useful when investigating a new case to see if a similar one was handled before. " +
+            "You can also use the standard file-reading tools directly — this is just a convenience.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                case_id: { type: "string", description: "If set, returns just this case's section." },
+                project_id: { type: "string" },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_register_webhook",
+        description: "Register a webhook URL to receive signed POSTs when interesting things happen. " +
+            "Events: 'case.created' (new error fingerprint), 'case.resolved' (case status flips to resolved), " +
+            "'deploy.recorded'. Returns the signing_secret ONCE — store it. The customer's endpoint must " +
+            "verify X-Agentry-Signature: t=<unix>,v1=<hex> using HMAC-SHA256(rawBody, signing_secret). " +
+            "This is the foundation for automation flows like auto-fix-on-error.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "https:// URL to receive deliveries" },
+                events: {
+                    type: "array",
+                    items: { type: "string", enum: ["case.created", "case.resolved", "deploy.recorded"] },
+                    description: "Defaults to all three.",
+                },
+                description: { type: "string" },
+                project_id: { type: "string", description: "Defaults to local default project." },
+            },
+            required: ["url"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_list_webhooks",
+        description: "List webhooks registered on a project, including last_status / last_error so the agent " +
+            "can tell if the customer's endpoint is healthy.",
+        inputSchema: {
+            type: "object",
+            properties: { project_id: { type: "string" } },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_test_webhook",
+        description: "Fire a synthetic test event to a registered webhook. Useful right after registration to " +
+            "confirm the signing secret + endpoint are wired up correctly.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                webhook_id: { type: "string" },
+                project_id: { type: "string" },
+            },
+            required: ["webhook_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_delete_webhook",
+        description: "Remove a webhook subscription. No further deliveries.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                webhook_id: { type: "string" },
+                project_id: { type: "string" },
+            },
+            required: ["webhook_id"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_automation_docs",
+        description: "Return markdown documentation showing common automation patterns built on agentry's webhooks: " +
+            "auto-fix-on-error, deploy regression alerts, weekly digests, etc. Each pattern includes a " +
+            "ready-to-deploy Cloudflare Worker / Vercel function template the agent can drop into the customer's repo.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "agentry_suggested_next_steps",
+        description: "After install/verify, surface this to the user: a curated list of 'what would you like to do " +
+            "next?' prompts with paste-ready templates ('Build a customized analytics dashboard', " +
+            "'Build an error monitoring dashboard', 'Generate this week's review post', etc.). " +
+            "Each suggestion lists the recipes/tools the agent will use, so the response is predictable. " +
+            "State-aware: only suggestions whose prerequisites are met (analytics configured, errors present, " +
+            "deploys recorded) are returned.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string", description: "Defaults to the local default project." },
+            },
+            additionalProperties: false,
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Helpers shared across tool handlers
+// ---------------------------------------------------------------------------
+function summarizeApiError(err) {
+    if (err && typeof err === "object" && "code" in err && "status" in err) {
+        const e = err;
+        return {
+            error: {
+                code: e.code,
+                message: e.message,
+                ...(e.next_action ? { next_action: e.next_action } : {}),
+                ...(e.details ? { details: e.details } : {}),
+            },
+        };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+        error: {
+            code: "client_error",
+            message: msg,
+            next_action: "This was a local/MCP-side error, not an API error. Check `agentry_status` and try again.",
+        },
+    };
+}
+function pickProject(cfg, projectId) {
+    const id = projectId ?? cfg.default_project_id;
+    if (!id)
+        return null;
+    const project = cfg.projects[id] ?? null;
+    return { id, project };
+}
+function projectByLookup(cfg, projectId) {
+    return cfg.projects[projectId] ?? null;
+}
+function persistKeyResponse(cfg, resp) {
+    const next = {
+        ...cfg,
+        api_key: resp.api_key,
+    };
+    saveConfig(next);
+    return next;
+}
+function requireProjectFromConfig(cfg, projectId) {
+    const picked = pickProject(cfg, projectId);
+    if (!picked || !picked.project) {
+        return {
+            error: {
+                error: {
+                    code: "no_project",
+                    message: "No project found locally. Either create one with agentry_create_project or pass project_id explicitly " +
+                        "(noting: this MCP only knows about projects it created locally — DSNs aren't fetched from the API).",
+                    next_action: "Call agentry_create_project first.",
+                },
+            },
+        };
+    }
+    return { id: picked.id, project: picked.project };
+}
+// Build a Sentry-shaped synthetic event suitable for hitting /v1/logs/:id/.
+function buildSyntheticEvent() {
+    const eventId = `agentrytest-${Date.now().toString(36)}`;
+    return {
+        event_id: eventId,
+        timestamp: Math.floor(Date.now() / 1000),
+        platform: "node",
+        level: "error",
+        environment: "agentry-mcp-test",
+        release: "agentry-mcp-test",
+        message: "Synthetic test event from agentry_capture_test_event",
+        exception: {
+            values: [
+                {
+                    type: "AgentryTestError",
+                    value: "This is a synthetic event triggered from the agentry MCP server.",
+                    stacktrace: {
+                        frames: [
+                            {
+                                filename: "agentry-mcp/src/tools.ts",
+                                function: "agentry_capture_test_event",
+                                lineno: 1,
+                                in_app: true,
+                            },
+                        ],
+                    },
+                },
+            ],
+        },
+        tags: { synthetic: "true" },
+    };
+}
+export async function dispatchTool(name, args) {
+    const a = args ?? {};
+    try {
+        switch (name) {
+            case "agentry_status":
+                return handleStatus();
+            case "agentry_login":
+                return await handleLogin({
+                    mode: a.mode === "start_only" || a.mode === "poll_once"
+                        ? a.mode
+                        : "full",
+                    device_code: a.device_code ? String(a.device_code) : undefined,
+                    timeout_seconds: typeof a.timeout_seconds === "number" ? a.timeout_seconds : undefined,
+                });
+            case "agentry_rotate_key":
+                return await handleRotateKey();
+            case "agentry_list_projects":
+                return await handleListProjects();
+            case "agentry_create_project":
+                return await handleCreateProject({
+                    name: String(a.name ?? ""),
+                    repo_url: a.repo_url ? String(a.repo_url) : undefined,
+                    local_path: a.local_path ? String(a.local_path) : undefined,
+                    default_branch: a.default_branch ? String(a.default_branch) : undefined,
+                });
+            case "agentry_install_sdk":
+                return await handleInstallSdk(a.language ? String(a.language) : "node");
+            case "agentry_list_cases":
+                return await handleListCases({
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    status: a.status ? String(a.status) : undefined,
+                });
+            case "agentry_get_case":
+                return await handleGetCase(String(a.case_id ?? ""));
+            case "agentry_resolve_case":
+                return await handleResolveCase({
+                    case_id: String(a.case_id ?? ""),
+                    summary: a.summary ? String(a.summary) : undefined,
+                    pr_url: a.pr_url ? String(a.pr_url) : undefined,
+                });
+            case "agentry_mark_spurious":
+                return await handleMarkSpurious({
+                    case_id: String(a.case_id ?? ""),
+                    reason: a.reason ? String(a.reason) : undefined,
+                    suppress_pattern: a.suppress_pattern ? String(a.suppress_pattern) : undefined,
+                });
+            case "agentry_record_suppression":
+                return await handleRecordSuppression({
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    fingerprint_pattern: String(a.fingerprint_pattern ?? ""),
+                    action: String(a.action ?? ""),
+                    reason: a.reason ? String(a.reason) : undefined,
+                    hint_text: a.hint_text ? String(a.hint_text) : undefined,
+                });
+            case "agentry_capture_test_event":
+                return await handleCaptureTestEvent(a.project_id ? String(a.project_id) : undefined);
+            case "agentry_record_deploy":
+                return await handleRecordDeploy({
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    sha: String(a.sha ?? ""),
+                    branch: a.branch ? String(a.branch) : undefined,
+                    environment: a.environment ? String(a.environment) : undefined,
+                    message: a.message ? String(a.message) : undefined,
+                    url: a.url ? String(a.url) : undefined,
+                    actor: a.actor ? String(a.actor) : undefined,
+                });
+            case "agentry_list_deploys":
+                return await handleListDeploys({
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    limit: typeof a.limit === "number" ? a.limit : undefined,
+                    since: typeof a.since === "number" ? a.since : undefined,
+                });
+            case "agentry_track_test_event":
+                return await handleTrackTestEvent({
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    event: a.event ? String(a.event) : "agentry_verify",
+                });
+            case "agentry_analytics_query":
+                return await handleAnalyticsQuery({
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    query: String(a.query ?? ""),
+                });
+            case "agentry_install_guide":
+                return await handleInstallGuide({
+                    framework: a.framework ? String(a.framework) : "node",
+                    signal_types: Array.isArray(a.signal_types)
+                        ? a.signal_types.map(String)
+                        : ["errors", "analytics", "deploys"],
+                });
+            case "agentry_verify_install":
+                return await handleVerifyInstall({
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    skip: Array.isArray(a.skip) ? a.skip.map(String) : [],
+                });
+            case "agentry_list_recipes":
+                return await handleListRecipes(a.category ? String(a.category) : undefined);
+            case "agentry_run_recipe":
+                return await handleRunRecipe({
+                    recipe_id: String(a.recipe_id ?? ""),
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    params: a.params && typeof a.params === "object"
+                        ? a.params
+                        : {},
+                });
+            case "agentry_query_docs":
+                return await handleQueryDocs();
+            case "agentry_suggested_next_steps":
+                return await handleSuggestedNextSteps(a.project_id ? String(a.project_id) : undefined);
+            case "agentry_project_health":
+                return await handleProjectHealth(a.project_id ? String(a.project_id) : undefined);
+            case "agentry_create_alert":
+                return await handleCreateAlert({
+                    name: String(a.name ?? ""),
+                    recipe_id: String(a.recipe_id ?? ""),
+                    threshold_column: String(a.threshold_column ?? ""),
+                    threshold_op: String(a.threshold_op ?? ""),
+                    threshold_value: typeof a.threshold_value === "number" ? a.threshold_value : Number(a.threshold_value),
+                    params: a.params && typeof a.params === "object" ? a.params : {},
+                    description: a.description ? String(a.description) : undefined,
+                    webhook_id: a.webhook_id ? String(a.webhook_id) : undefined,
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
+            case "agentry_list_alerts":
+                return await handleListAlerts(a.project_id ? String(a.project_id) : undefined);
+            case "agentry_evaluate_alert":
+                return await handleEvaluateAlert({
+                    alert_id: String(a.alert_id ?? ""),
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
+            case "agentry_delete_alert":
+                return await handleDeleteAlert({
+                    alert_id: String(a.alert_id ?? ""),
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
+            case "agentry_remember":
+                return await handleRemember({
+                    case_id: String(a.case_id ?? ""),
+                    summary: String(a.summary ?? ""),
+                    fingerprint: a.fingerprint ? String(a.fingerprint) : undefined,
+                    status: a.status ? String(a.status) : undefined,
+                    error_type: a.error_type ? String(a.error_type) : undefined,
+                    pr_url: a.pr_url ? String(a.pr_url) : undefined,
+                    watch_for: a.watch_for ? String(a.watch_for) : undefined,
+                    tags: Array.isArray(a.tags) ? a.tags.map(String) : undefined,
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
+            case "agentry_recall":
+                return handleRecall({
+                    case_id: a.case_id ? String(a.case_id) : undefined,
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
+            case "agentry_register_webhook":
+                return await handleRegisterWebhook({
+                    url: String(a.url ?? ""),
+                    events: Array.isArray(a.events) ? a.events.map(String) : undefined,
+                    description: a.description ? String(a.description) : undefined,
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
+            case "agentry_list_webhooks":
+                return await handleListWebhooks(a.project_id ? String(a.project_id) : undefined);
+            case "agentry_test_webhook":
+                return await handleTestWebhook({
+                    webhook_id: String(a.webhook_id ?? ""),
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
+            case "agentry_delete_webhook":
+                return await handleDeleteWebhook({
+                    webhook_id: String(a.webhook_id ?? ""),
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
+            case "agentry_automation_docs":
+                return await handleAutomationDocs();
+            default:
+                return {
+                    error: {
+                        code: "unknown_tool",
+                        message: `Unknown tool: ${name}`,
+                        next_action: "Call ListTools to see available tools.",
+                    },
+                };
+        }
+    }
+    catch (err) {
+        return summarizeApiError(err);
+    }
+}
+// ---------------------------------------------------------------------------
+// Tool handlers
+// ---------------------------------------------------------------------------
+function handleStatus() {
+    const cfg = loadConfig();
+    const hint = getOnboardingHint(cfg);
+    const projectIds = Object.keys(cfg.projects);
+    return {
+        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,
+        default_project_id: cfg.default_project_id,
+        project_count: projectIds.length,
+        projects: projectIds.map((id) => {
+            const p = cfg.projects[id];
+            return { id, name: p.name, local_path: p.local_path };
+        }),
+        onboarding: hint,
+        next_steps: [hint.message, hint.next_action],
+    };
+}
+async function handleLogin(input) {
+    const cfg = loadConfig();
+    if (input.mode === "start_only") {
+        const start = await api.startDeviceFlow(cfg);
+        return {
+            mode: "start_only",
+            verification_uri: start.verification_uri,
+            user_code: start.user_code,
+            device_code: start.device_code,
+            interval: start.interval,
+            expires_in: start.expires_in,
+            next_action: `Tell the user: "Open ${start.verification_uri} and enter the code ${start.user_code}." ` +
+                "Once they confirm they've authorized, call agentry_login again with mode='poll_once' and this device_code.",
+        };
+    }
+    if (input.mode === "poll_once") {
+        if (!input.device_code) {
+            return {
+                error: {
+                    code: "missing_device_code",
+                    message: "mode='poll_once' requires device_code from the start_only call.",
+                    next_action: "Either call agentry_login with mode='start_only' first, or use mode='full' and let the tool handle the loop.",
+                },
+            };
+        }
+        const result = await api.pollDeviceFlow(cfg, input.device_code);
+        if ("api_key" in result) {
+            const next = persistKeyResponse(cfg, result);
+            return {
+                ok: true,
+                user_id: result.user_id,
+                github: result.github,
+                api_key_prefix: result.prefix,
+                persisted_to: "local config",
+                server_url: next.server_url,
+                next_action: "Authenticated. Call `agentry_create_project` with a project name (and local_path of the repo) to mint a DSN.",
+            };
+        }
+        return {
+            ok: false,
+            status: result.status,
+            next_action: result.next_action ??
+                "Wait and call agentry_login again with mode='poll_once' and the same device_code.",
+        };
+    }
+    // mode === "full" — do the entire flow inside one tool call.
+    const start = await api.startDeviceFlow(cfg);
+    const intervalMs = Math.max(1, start.interval) * 1000;
+    const deadline = Date.now() + (input.timeout_seconds ?? 180) * 1000;
+    // We can't wait for the agent to confirm the user authorized, so the agent's
+    // calling convention here is "tell the user the code, then keep polling
+    // automatically." Surface the verification info up front in the response
+    // metadata via instructions so the calling agent can show it before the
+    // poll completes — the JSON we return at the end includes it as well.
+    let lastStatus = null;
+    while (Date.now() < deadline) {
+        const result = await api.pollDeviceFlow(cfg, start.device_code);
+        if ("api_key" in result) {
+            const next = persistKeyResponse(cfg, result);
+            return {
+                ok: true,
+                user_id: result.user_id,
+                github: result.github,
+                api_key_prefix: result.prefix,
+                persisted_to: "local config",
+                server_url: next.server_url,
+                verification_uri_used: start.verification_uri,
+                user_code_used: start.user_code,
+                next_action: "Authenticated. Call `agentry_create_project` with a project name (and local_path of the repo) to mint a DSN.",
+            };
+        }
+        lastStatus = result.status;
+        if (result.status === "expired" || result.status === "denied") {
+            return {
+                ok: false,
+                status: result.status,
+                verification_uri: start.verification_uri,
+                user_code: start.user_code,
+                next_action: result.next_action ??
+                    (result.status === "expired"
+                        ? "Device code expired. Call `agentry_login` again to start a fresh flow."
+                        : "User declined. Confirm with them and call `agentry_login` again if they want to proceed."),
+            };
+        }
+        const delay = result.status === "slow_down" ? intervalMs + 5000 : intervalMs;
+        await sleep(delay);
+    }
+    return {
+        ok: false,
+        status: "timeout",
+        last_status: lastStatus,
+        verification_uri: start.verification_uri,
+        user_code: start.user_code,
+        device_code: start.device_code,
+        next_action: `Timed out after ${input.timeout_seconds ?? 180}s. ` +
+            `Confirm the user opened ${start.verification_uri} and entered ${start.user_code}, then call agentry_login again with mode='poll_once' and device_code='${start.device_code}'.`,
+    };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function handleRotateKey() {
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return {
+            error: {
+                code: "no_key",
+                message: "No API key to rotate.",
+                next_action: "Call `agentry_login` to authenticate via GitHub first.",
+            },
+        };
+    }
+    const resp = await api.rotateKey(cfg);
+    persistKeyResponse(cfg, resp);
+    return {
+        ok: true,
+        user_id: resp.user_id,
+        api_key_prefix: resp.prefix,
+        next_action: resp.next_action ??
+            "New key stored locally. Old key is revoked — update any places it was pasted (CI envs, etc).",
+    };
+}
+async function handleListProjects() {
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return {
+            error: {
+                code: "no_key",
+                message: "No API key on file.",
+                next_action: "Call `agentry_login` first.",
+            },
+        };
+    }
+    const resp = await api.listProjects(cfg);
+    const enriched = resp.projects.map((p) => {
+        const local = cfg.projects[p.id];
+        return {
+            ...p,
+            local_path: local?.local_path ?? null,
+            dsn_known_locally: Boolean(local?.dsn),
+            is_default: cfg.default_project_id === p.id,
+        };
+    });
+    return {
+        projects: enriched,
+        default_project_id: cfg.default_project_id,
+        next_action: enriched.length === 0
+            ? "No projects yet. Call `agentry_create_project` to make one."
+            : "Pick a project and call `agentry_list_cases` to see open errors.",
+    };
+}
+async function handleCreateProject(input) {
+    if (!input.name) {
+        return {
+            error: {
+                code: "missing_name",
+                message: "name is required",
+                next_action: "Ask the user for a project name.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return {
+            error: {
+                code: "no_key",
+                message: "No API key on file.",
+                next_action: "Call `agentry_login` first.",
+            },
+        };
+    }
+    const resp = await api.createProject(cfg, {
+        name: input.name,
+        repo_url: input.repo_url,
+        local_path: input.local_path,
+        default_branch: input.default_branch,
+    });
+    // Persist DSN + local_path locally so subsequent tool calls can route back.
+    const projectConfig = {
+        id: resp.id,
+        name: resp.name,
+        dsn: resp.dsn,
+        local_path: input.local_path ?? null,
+        default_branch: resp.default_branch ?? input.default_branch ?? "main",
+    };
+    const nextCfg = {
+        ...cfg,
+        default_project_id: cfg.default_project_id ?? resp.id,
+        projects: { ...cfg.projects, [resp.id]: projectConfig },
+    };
+    saveConfig(nextCfg);
+    // Try to also pull the install snippet so the agent has it without a second roundtrip.
+    let install = null;
+    try {
+        install = await api.getInstallSnippet(cfg, "node");
+    }
+    catch {
+        // Non-fatal — the agent can call agentry_install_sdk separately.
+    }
+    return {
+        ok: true,
+        project: {
+            id: resp.id,
+            name: resp.name,
+            dsn: resp.dsn,
+            default_branch: projectConfig.default_branch,
+            local_path: projectConfig.local_path,
+            // First-party typed endpoints — agent should prefer these over /v1/log/.
+            // Same DSN authenticates all three. POST any-language HTTP client; no SDK.
+            logs_url: resp.logs_url,
+            analytics_url: resp.analytics_url,
+            deploys_url: resp.deploys_url,
+            // Sentry-DSN URL kept for drop-in into existing Sentry SDKs.
+            sentry_dsn_url: resp.sentry_dsn_url,
+        },
+        install_snippet: install,
+        next_action: resp.next_action ??
+            "DSN stored locally. Three typed endpoints (logs_url / analytics_url / deploys_url) " +
+                "all authenticate with this DSN. Paste the install snippet, set AGENTRY_DSN, then call " +
+                "`agentry_capture_test_event` to verify ingest.",
+    };
+}
+async function handleInstallSdk(language) {
+    const cfg = loadConfig();
+    const resp = await api.getInstallSnippet(cfg, language);
+    return {
+        language: resp.language,
+        code: resp.code,
+        env_vars: resp.env_vars,
+        next_action: "Paste `code` into the user's project, then set the env_vars (AGENTRY_DSN especially). " +
+            "Then call `agentry_capture_test_event` to verify ingest.",
+    };
+}
+async function handleListCases(input) {
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return {
+            error: {
+                code: "no_key",
+                message: "No API key on file.",
+                next_action: "Call `agentry_login` first.",
+            },
+        };
+    }
+    const picked = pickProject(cfg, input.project_id);
+    if (!picked) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project_id given and no default project set.",
+                next_action: "Either pass project_id, or call `agentry_create_project` to create one (which becomes default).",
+            },
+        };
+    }
+    const status = input.status ?? "open";
+    const resp = await api.listCases(cfg, picked.id, status);
+    const local = picked.project;
+    const enriched = resp.cases.map((c) => ({
+        ...c,
+        local_path: local?.local_path ?? null,
+    }));
+    return {
+        project_id: picked.id,
+        status,
+        cases: enriched,
+        next_action: enriched.length === 0
+            ? "No cases match. Either trigger one with `agentry_capture_test_event`, or wait for a real one."
+            : "For each case, `cd` to its `local_path` and call `agentry_get_case` for the stack + suppression hints.",
+    };
+}
+async function handleGetCase(caseId) {
+    if (!caseId) {
+        return {
+            error: {
+                code: "missing_case_id",
+                message: "case_id is required",
+                next_action: "Pass case_id from the output of `agentry_list_cases`.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    const detail = await api.getCase(cfg, caseId);
+    // Enrich with local_path looked up by project_id.
+    const localProject = projectByLookup(cfg, detail.project_id);
+    const localPath = localProject?.local_path ?? detail.local_path ?? null;
+    return {
+        ...detail,
+        local_path: localPath,
+        next_action: detail.next_actions && detail.next_actions.length > 0
+            ? detail.next_actions.join(" / ")
+            : `Investigate at ${localPath ?? "(local_path unknown — store it via agentry_create_project)"}.`,
+    };
+}
+async function handleResolveCase(input) {
+    if (!input.case_id) {
+        return {
+            error: { code: "missing_case_id", message: "case_id is required" },
+        };
+    }
+    const cfg = loadConfig();
+    const updated = await api.updateCase(cfg, input.case_id, {
+        status: "resolved",
+        agent_summary: input.summary,
+        pr_url: input.pr_url,
+    });
+    return {
+        ok: true,
+        case: updated,
+        next_action: "Case resolved. If this fingerprint is likely to recur and you want auto-suppression, " +
+            "call `agentry_record_suppression` with action 'auto_resolve' or 'auto_ignore'.",
+    };
+}
+async function handleMarkSpurious(input) {
+    if (!input.case_id) {
+        return { error: { code: "missing_case_id", message: "case_id is required" } };
+    }
+    const cfg = loadConfig();
+    const updated = await api.updateCase(cfg, input.case_id, {
+        status: "spurious",
+        agent_summary: input.reason,
+    });
+    let suppression_id = null;
+    if (input.suppress_pattern) {
+        try {
+            const r = await api.recordSuppression(cfg, updated.project_id, {
+                fingerprint_pattern: input.suppress_pattern,
+                action: "auto_ignore",
+                reason: input.reason,
+            });
+            suppression_id = r.id;
+        }
+        catch (err) {
+            // Surface the suppression failure but don't undo the spurious mark.
+            return {
+                ok: true,
+                case: updated,
+                suppression_error: summarizeApiError(err).error,
+                next_action: "Case marked spurious, but suppression rule failed to save. " +
+                    "Retry `agentry_record_suppression` independently.",
+            };
+        }
+    }
+    return {
+        ok: true,
+        case: updated,
+        suppression_id,
+        next_action: suppression_id
+            ? "Case is spurious and a noise rule is in place. Future matching events will be auto-ignored."
+            : "Case is spurious. To prevent future noise, call `agentry_record_suppression`.",
+    };
+}
+async function handleRecordSuppression(input) {
+    if (!input.fingerprint_pattern) {
+        return { error: { code: "missing_pattern", message: "fingerprint_pattern is required" } };
+    }
+    if (!input.action) {
+        return { error: { code: "missing_action", message: "action is required" } };
+    }
+    if (input.action === "prompt_hint" && !input.hint_text) {
+        return {
+            error: {
+                code: "missing_hint_text",
+                message: "hint_text is required when action is 'prompt_hint'",
+                next_action: "Provide hint_text — it's the message attached to future matching cases.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    const picked = pickProject(cfg, input.project_id);
+    if (!picked) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project_id given and no default project set.",
+                next_action: "Pass project_id or call `agentry_create_project` first.",
+            },
+        };
+    }
+    const resp = await api.recordSuppression(cfg, picked.id, {
+        fingerprint_pattern: input.fingerprint_pattern,
+        action: input.action,
+        reason: input.reason,
+        hint_text: input.hint_text,
+    });
+    return {
+        ok: true,
+        suppression_id: resp.id,
+        project_id: picked.id,
+        next_action: "Future matching events will follow the suppression rule.",
+    };
+}
+async function handleCaptureTestEvent(projectId) {
+    const cfg = loadConfig();
+    const picked = pickProject(cfg, projectId);
+    if (!picked || !picked.project) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project found locally. The DSN is stored locally only for projects created via this MCP — " +
+                    "if the project was created elsewhere, call `agentry_list_projects` and `agentry_install_sdk` first, " +
+                    "or recreate the project here.",
+                next_action: "Call `agentry_create_project` with a name to mint a fresh DSN.",
+            },
+        };
+    }
+    const dsn = picked.project.dsn;
+    const parsed = parseDsn(dsn);
+    if (!parsed) {
+        return {
+            error: {
+                code: "bad_dsn",
+                message: `Stored DSN for project ${picked.id} is not parseable.`,
+                next_action: "Recreate the project via `agentry_create_project`.",
+            },
+        };
+    }
+    const event = buildSyntheticEvent();
+    // Pass the full DSN as auth — the API accepts either the token alone or the full DSN form.
+    const resp = await api.storeEvent(cfg, parsed.projectId, dsn, event);
+    return {
+        ok: true,
+        project_id: picked.id,
+        event_id: resp.id,
+        case_id: resp.case_id ?? null,
+        next_action: resp.case_id
+            ? `Event ingested. Call \`agentry_get_case\` with case_id="${resp.case_id}" to see how it looks to the agent flow.`
+            : "Event ingested. The case may take a moment to materialize — call `agentry_list_cases` shortly.",
+    };
+}
+// ---------------------------------------------------------------------------
+// Deploy events
+// ---------------------------------------------------------------------------
+async function handleRecordDeploy(input) {
+    if (!input.sha) {
+        return {
+            error: {
+                code: "missing_sha",
+                message: "sha is required",
+                next_action: "Pass the git SHA of the deployed commit.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    const r = requireProjectFromConfig(cfg, input.project_id);
+    if ("error" in r)
+        return r.error;
+    const parsed = parseDsn(r.project.dsn);
+    if (!parsed) {
+        return {
+            error: {
+                code: "bad_dsn",
+                message: `Stored DSN for project ${r.id} is not parseable.`,
+                next_action: "Recreate the project via agentry_create_project.",
+            },
+        };
+    }
+    const resp = await api.recordDeploy(cfg, parsed.projectId, r.project.dsn, {
+        sha: input.sha,
+        ...(input.branch !== undefined ? { branch: input.branch } : {}),
+        ...(input.environment !== undefined ? { environment: input.environment } : {}),
+        ...(input.message !== undefined ? { message: input.message } : {}),
+        ...(input.url !== undefined ? { url: input.url } : {}),
+        ...(input.actor !== undefined ? { actor: input.actor } : {}),
+    });
+    return {
+        ok: true,
+        deploy_id: resp.id,
+        received_at: resp.received_at,
+        next_action: "Deploy recorded. Future cases ingested after this timestamp will surface this deploy in their recent_deploys.",
+    };
+}
+async function handleListDeploys(input) {
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return {
+            error: {
+                code: "no_key",
+                message: "No API key on file.",
+                next_action: "Call `agentry_login` first.",
+            },
+        };
+    }
+    const projectId = input.project_id ?? cfg.default_project_id;
+    if (!projectId) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project specified and no default project set.",
+                next_action: "Pass project_id, or set a default by creating a project.",
+            },
+        };
+    }
+    const optsArg = {};
+    if (input.limit !== undefined)
+        optsArg.limit = input.limit;
+    if (input.since !== undefined)
+        optsArg.since = input.since;
+    const resp = await api.listDeploys(cfg, projectId, optsArg);
+    return {
+        project_id: projectId,
+        ...resp,
+        next_action: "Cross-reference deploy received_at with case last_seen_at to attribute regressions.",
+    };
+}
+// ---------------------------------------------------------------------------
+// Analytics
+// ---------------------------------------------------------------------------
+async function handleTrackTestEvent(input) {
+    const cfg = loadConfig();
+    const r = requireProjectFromConfig(cfg, input.project_id);
+    if ("error" in r)
+        return r.error;
+    const parsed = parseDsn(r.project.dsn);
+    if (!parsed) {
+        return {
+            error: {
+                code: "bad_dsn",
+                message: `Stored DSN for project ${r.id} is not parseable.`,
+                next_action: "Recreate the project via agentry_create_project.",
+            },
+        };
+    }
+    const eventName = input.event || "agentry_verify";
+    const resp = await api.trackEvent(cfg, parsed.projectId, r.project.dsn, {
+        event: eventName,
+        distinct_id: "agentry-mcp-test",
+        properties: { source: "agentry_track_test_event", ts: Math.floor(Date.now() / 1000) },
+    });
+    return {
+        ok: resp.ok ?? true,
+        event: eventName,
+        next_action: "Event forwarded to PostHog. Use agentry_analytics_query to verify it landed " +
+            `(SELECT count() FROM events WHERE event='${eventName}' AND timestamp > now() - INTERVAL 5 MINUTE).`,
+    };
+}
+async function handleAnalyticsQuery(input) {
+    if (!input.query) {
+        return {
+            error: {
+                code: "missing_query",
+                message: "query (HogQL) is required",
+                next_action: "Pass a HogQL query string.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return {
+            error: {
+                code: "no_key",
+                message: "No API key on file.",
+                next_action: "Call `agentry_login` first.",
+            },
+        };
+    }
+    const projectId = input.project_id ?? cfg.default_project_id;
+    if (!projectId) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project specified and no default project set.",
+                next_action: "Pass project_id, or create a project.",
+            },
+        };
+    }
+    const resp = await api.analyticsQuery(cfg, projectId, input.query);
+    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.",
+    };
+}
+// ---------------------------------------------------------------------------
+// Install guide + comprehensive verification
+// ---------------------------------------------------------------------------
+async function handleInstallGuide(input) {
+    const cfg = loadConfig();
+    const guide = await api.getInstallGuide(cfg, input.framework);
+    // Filter steps if signal_types is a strict subset.
+    const wanted = new Set(input.signal_types);
+    const filteredSteps = guide.steps.filter((s) => {
+        // common + verify steps always shown
+        if (["install_sdk", "set_env_vars", "verify_install"].includes(s.id) ||
+            s.action === "verify")
+            return true;
+        if (s.id.startsWith("init_") || s.id.includes("error") || s.id.includes("uncaught") ||
+            s.id.includes("middleware") || s.id.includes("error_boundary"))
+            return wanted.has("errors");
+        if (s.id.startsWith("track_") || s.id.includes("analytics"))
+            return wanted.has("analytics");
+        if (s.id.startsWith("fire_deploy") || s.id.includes("deploy"))
+            return wanted.has("deploys");
+        return true;
+    });
+    return {
+        ...guide,
+        steps: filteredSteps,
+        next_action: "Read each step in order. For 'edit' steps, find the file matching `file_hint` in the customer's repo " +
+            "and apply `code`. For 'run' steps, execute `command`. After all steps, call agentry_verify_install — " +
+            "that's the only proof the install actually works.",
+    };
+}
+async function handleVerifyInstall(input) {
+    const cfg = loadConfig();
+    const r = requireProjectFromConfig(cfg, input.project_id);
+    if ("error" in r)
+        return r.error;
+    const skip = new Set(input.skip);
+    const checks = {};
+    if (!skip.has("errors")) {
+        try {
+            const resp = await handleCaptureTestEvent(r.id);
+            const ok = resp.ok === true;
+            checks.errors = {
+                ok,
+                detail: ok
+                    ? `synthetic error landed → case_id=${resp.case_id ?? "(pending)"}`
+                    : `failed: ${JSON.stringify(resp.error ?? resp)}`,
+            };
+        }
+        catch (err) {
+            checks.errors = { ok: false, detail: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    if (!skip.has("analytics")) {
+        try {
+            const resp = await handleTrackTestEvent({ project_id: r.id, event: "agentry_verify_install" });
+            const ok = resp.ok === true;
+            checks.analytics = {
+                ok,
+                detail: ok
+                    ? "synthetic analytics event forwarded to PostHog (verify with agentry_analytics_query if needed)"
+                    : `failed: ${JSON.stringify(resp.error ?? resp)}`,
+            };
+        }
+        catch (err) {
+            checks.analytics = { ok: false, detail: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    if (!skip.has("deploys")) {
+        try {
+            const resp = await handleRecordDeploy({
+                project_id: r.id,
+                sha: `agentry-verify-${Date.now().toString(36)}`,
+                branch: "agentry-verify",
+                environment: "agentry-verify",
+                message: "synthetic deploy from agentry_verify_install",
+            });
+            const ok = resp.ok === true;
+            checks.deploys = {
+                ok,
+                detail: ok
+                    ? "synthetic deploy recorded"
+                    : `failed: ${JSON.stringify(resp.error ?? resp)}`,
+            };
+        }
+        catch (err) {
+            checks.deploys = { ok: false, detail: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    const passed = Object.entries(checks).filter(([, v]) => v.ok).map(([k]) => k);
+    const failed = Object.entries(checks).filter(([, v]) => !v.ok).map(([k]) => k);
+    // Mark install_verified locally so the onboarding state machine moves to "ready".
+    if (failed.length === 0) {
+        const updated = loadConfig();
+        const proj = updated.projects[r.id];
+        if (proj) {
+            updated.projects[r.id] = { ...proj, install_verified: true };
+            saveConfig(updated);
+        }
+    }
+    // Pull in suggested next-steps so the agent can immediately surface a menu.
+    let nextSuggestions = [];
+    if (failed.length === 0) {
+        try {
+            const ns = await api.getNextSteps(loadConfig(), r.id);
+            nextSuggestions = ns.suggestions;
+        }
+        catch {
+            /* non-fatal */
+        }
+    }
+    const baseAction = failed.length === 0
+        ? "Install verified. Errors land in agentry_list_cases; analytics flow to PostHog; deploys via agentry_list_deploys."
+        : `Install incomplete. Failed signal types: ${failed.join(", ")}. ` +
+            "For each failed type, re-read its corresponding step in agentry_install_guide and fix.";
+    return {
+        ok: failed.length === 0,
+        summary: `${passed.length}/${Object.keys(checks).length} signal types verified`,
+        passed,
+        failed,
+        checks,
+        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,
+    };
+}
+// ---------------------------------------------------------------------------
+// Recipes / query docs
+// ---------------------------------------------------------------------------
+async function handleListRecipes(category) {
+    const cfg = loadConfig();
+    const resp = await api.listRecipes(cfg, category);
+    return {
+        ...resp,
+        next_action: "Pick a recipe whose `description` or `example_user_question` matches what the user asked. " +
+            "Then call `agentry_run_recipe` with its id and params (defaults are filled in if omitted). " +
+            "If nothing matches, call `agentry_query_docs` to compose ad-hoc HogQL via `agentry_analytics_query`.",
+    };
+}
+async function handleRunRecipe(input) {
+    if (!input.recipe_id) {
+        return {
+            error: {
+                code: "missing_recipe_id",
+                message: "recipe_id is required",
+                next_action: "Call `agentry_list_recipes` to see available recipes.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return {
+            error: {
+                code: "no_key",
+                message: "No API key on file.",
+                next_action: "Call `agentry_login` first.",
+            },
+        };
+    }
+    const projectId = input.project_id ?? cfg.default_project_id;
+    if (!projectId) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project_id specified and no default project set.",
+                next_action: "Pass project_id, or create a project first.",
+            },
+        };
+    }
+    const resp = await api.runRecipe(cfg, projectId, input.recipe_id, input.params);
+    return {
+        project_id: projectId,
+        ...resp,
+    };
+}
+async function handleQueryDocs() {
+    const cfg = loadConfig();
+    const md = await api.getQueryDocs(cfg);
+    return {
+        docs_markdown: md,
+        next_action: "Read the schema + HogQL primer. Compose your query, then call `agentry_analytics_query` " +
+            "with project_id and the HogQL string. For errors/deploys, use the relevant recipe or typed endpoints.",
+    };
+}
+async function handleSuggestedNextSteps(projectId) {
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return {
+            error: {
+                code: "no_key",
+                message: "No API key on file.",
+                next_action: "Call `agentry_login` first.",
+            },
+        };
+    }
+    const id = projectId ?? cfg.default_project_id;
+    if (!id) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project specified and no default project set.",
+                next_action: "Pass project_id, or create a project first.",
+            },
+        };
+    }
+    const resp = await api.getNextSteps(cfg, id);
+    return {
+        project_id: id,
+        ...resp,
+        next_action: "Surface these to the user as numbered options. Use this format:\n\n" +
+            "  Now that you're set up, want to:\n" +
+            "    1. <title> — <description>\n" +
+            "    2. <title> — <description>\n" +
+            "    3. <title> — <description>\n\n" +
+            "When the user picks one, paste the matching `prompt_template` as the user's next prompt " +
+            "(or just execute the listed `uses` directly).",
+    };
+}
+// ---------------------------------------------------------------------------
+// Webhooks
+// ---------------------------------------------------------------------------
+function pickProjectId(cfg, projectId) {
+    return projectId ?? cfg.default_project_id ?? null;
+}
+async function handleRegisterWebhook(input) {
+    if (!input.url || !/^https?:\/\//.test(input.url)) {
+        return {
+            error: {
+                code: "missing_url",
+                message: "url is required and must be http(s)",
+                next_action: "Ask the user for the receiving URL (their Worker / Function endpoint).",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return { error: { code: "no_key", message: "No API key on file.", next_action: "Call `agentry_login` first." } };
+    }
+    const pid = pickProjectId(cfg, input.project_id);
+    if (!pid) {
+        return { error: { code: "no_project", message: "No project specified.", next_action: "Pass project_id." } };
+    }
+    const body = { url: input.url };
+    if (input.events)
+        body.events = input.events;
+    if (input.description)
+        body.description = input.description;
+    const resp = await api.registerWebhook(cfg, pid, body);
+    return {
+        ...resp,
+        project_id: pid,
+        next_action: "STORE THE signing_secret NOW — it won't be shown again. " +
+            "Tell the user to add it to their endpoint's env. Then call agentry_test_webhook to verify the wiring.",
+    };
+}
+async function handleListWebhooks(projectId) {
+    const cfg = loadConfig();
+    if (!cfg.api_key) {
+        return { error: { code: "no_key", message: "No API key.", next_action: "Call `agentry_login`." } };
+    }
+    const pid = pickProjectId(cfg, projectId);
+    if (!pid)
+        return { error: { code: "no_project", message: "No project specified.", next_action: "Pass project_id." } };
+    const resp = await api.listWebhooks(cfg, pid);
+    return { project_id: pid, ...resp };
+}
+async function handleTestWebhook(input) {
+    if (!input.webhook_id) {
+        return { error: { code: "missing_webhook_id", message: "webhook_id is required.", next_action: "Pass webhook id from agentry_list_webhooks." } };
+    }
+    const cfg = loadConfig();
+    if (!cfg.api_key)
+        return { error: { code: "no_key", message: "No API key.", next_action: "Call `agentry_login`." } };
+    const pid = pickProjectId(cfg, input.project_id);
+    if (!pid)
+        return { error: { code: "no_project", message: "No project specified.", next_action: "Pass project_id." } };
+    const resp = await api.testWebhook(cfg, pid, input.webhook_id);
+    return {
+        ...resp,
+        project_id: pid,
+        next_action: "Test fired. Call agentry_list_webhooks to see last_status — should be 200 if your endpoint accepted it.",
+    };
+}
+async function handleDeleteWebhook(input) {
+    if (!input.webhook_id) {
+        return { error: { code: "missing_webhook_id", message: "webhook_id is required.", next_action: "Pass webhook id." } };
+    }
+    const cfg = loadConfig();
+    if (!cfg.api_key)
+        return { error: { code: "no_key", message: "No API key.", next_action: "Call `agentry_login`." } };
+    const pid = pickProjectId(cfg, input.project_id);
+    if (!pid)
+        return { error: { code: "no_project", message: "No project specified.", next_action: "Pass project_id." } };
+    const resp = await api.deleteWebhook(cfg, pid, input.webhook_id);
+    return { ...resp, project_id: pid };
+}
+async function handleAutomationDocs() {
+    const cfg = loadConfig();
+    const md = await api.getAutomationDocs(cfg);
+    return {
+        docs_markdown: md,
+        next_action: "Read the automation patterns. Each pattern includes a paste-ready Worker template the agent " +
+            "can drop into the customer's repo. After deploying their endpoint, call agentry_register_webhook " +
+            "with the URL, then agentry_test_webhook to confirm.",
+    };
+}
+// ---------------------------------------------------------------------------
+// Local memory file (agentry_memory.md)
+// ---------------------------------------------------------------------------
+function resolveLocalPath(cfg, projectId) {
+    const id = projectId ?? cfg.default_project_id;
+    if (!id)
+        return null;
+    const proj = cfg.projects[id];
+    if (!proj || !proj.local_path)
+        return null;
+    return { id, localPath: proj.local_path };
+}
+async function handleRemember(input) {
+    if (!input.case_id || !input.summary) {
+        return {
+            error: {
+                code: "missing_input",
+                message: "case_id and summary are required",
+                next_action: "Pass both. Use agentry_get_case to find case_id; summary should describe what you learned.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    const resolved = resolveLocalPath(cfg, input.project_id);
+    if (!resolved) {
+        return {
+            error: {
+                code: "no_local_path",
+                message: "No local_path stored for this project — agentry_memory.md needs a local repo to write into.",
+                next_action: "Recreate the project with `local_path` set (the absolute path to the repo on disk), then retry.",
+            },
+        };
+    }
+    const filePath = getMemoryPath(resolved.localPath);
+    if (!filePath) {
+        return { error: { code: "no_path", message: "Could not resolve memory file path.", next_action: "Check local_path." } };
+    }
+    const action = upsertCaseSection(filePath, {
+        case_id: input.case_id,
+        summary: input.summary,
+        ...(input.fingerprint !== undefined ? { fingerprint: input.fingerprint } : {}),
+        ...(input.status !== undefined ? { status: input.status } : {}),
+        ...(input.error_type !== undefined ? { error_type: input.error_type } : {}),
+        ...(input.pr_url !== undefined ? { pr_url: input.pr_url } : {}),
+        ...(input.watch_for !== undefined ? { watch_for: input.watch_for } : {}),
+        ...(input.tags !== undefined ? { tags: input.tags } : {}),
+    });
+    return {
+        ok: true,
+        file_path: filePath,
+        action,
+        next_action: "Memory updated. Future investigations can read this file directly (it's just markdown). " +
+            "Consider committing agentry_memory.md so the team and future agents see prior context.",
+    };
+}
+function handleRecall(input) {
+    const cfg = loadConfig();
+    const resolved = resolveLocalPath(cfg, input.project_id);
+    if (!resolved) {
+        return {
+            error: {
+                code: "no_local_path",
+                message: "No local_path stored for this project.",
+                next_action: "Recreate the project with `local_path` set.",
+            },
+        };
+    }
+    const filePath = getMemoryPath(resolved.localPath);
+    if (!fs.existsSync(filePath)) {
+        return {
+            file_path: filePath,
+            content: null,
+            next_action: `No ${MEMORY_FILENAME} yet. Call agentry_remember after your next investigation to start the memory file.`,
+        };
+    }
+    if (input.case_id) {
+        const section = readCaseSection(filePath, input.case_id);
+        return {
+            file_path: filePath,
+            case_id: input.case_id,
+            content: section,
+            next_action: section
+                ? "Read the section before investigating — prior knowledge is in there."
+                : "No prior memory for this case_id. Investigate fresh and call agentry_remember when done.",
+        };
+    }
+    const content = fs.readFileSync(filePath, "utf8");
+    return {
+        file_path: filePath,
+        content,
+        next_action: "Use this as context. For a specific case, pass case_id to filter. " +
+            "You can also Read/Grep this file directly with the agent's file tools.",
+    };
+}
+// ---------------------------------------------------------------------------
+// Project health + alerts
+// ---------------------------------------------------------------------------
+async function handleProjectHealth(projectId) {
+    const cfg = loadConfig();
+    if (!cfg.api_key)
+        return { error: { code: "no_key", message: "No API key.", next_action: "Call `agentry_login`." } };
+    const pid = projectId ?? cfg.default_project_id;
+    if (!pid)
+        return { error: { code: "no_project", message: "No project specified.", next_action: "Pass project_id." } };
+    const resp = await api.getProjectHealth(cfg, pid);
+    return resp;
+}
+async function handleCreateAlert(input) {
+    if (!input.name || !input.recipe_id || !input.threshold_column || !input.threshold_op || !Number.isFinite(input.threshold_value)) {
+        return {
+            error: {
+                code: "missing_input",
+                message: "name, recipe_id, threshold_column, threshold_op, threshold_value are required",
+                next_action: "Pass all five. Use agentry_list_recipes to find a recipe with the column you want to threshold.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    if (!cfg.api_key)
+        return { error: { code: "no_key", message: "No API key.", next_action: "Call `agentry_login`." } };
+    const pid = input.project_id ?? cfg.default_project_id;
+    if (!pid)
+        return { error: { code: "no_project", message: "No project specified.", next_action: "Pass project_id." } };
+    const body = {
+        name: input.name,
+        recipe_id: input.recipe_id,
+        threshold_column: input.threshold_column,
+        threshold_op: input.threshold_op,
+        threshold_value: input.threshold_value,
+        params: input.params,
+    };
+    if (input.description)
+        body.description = input.description;
+    if (input.webhook_id)
+        body.webhook_id = input.webhook_id;
+    const resp = await api.createAlert(cfg, pid, body);
+    return {
+        ...resp,
+        project_id: pid,
+        next_action: "Alert stored. Tell the user to call agentry_evaluate_alert from their cron / GitHub Actions / Cloudflare Cron " +
+            "(say every 5 minutes). When threshold crosses, agentry fires the linked webhook.",
+    };
+}
+async function handleListAlerts(projectId) {
+    const cfg = loadConfig();
+    if (!cfg.api_key)
+        return { error: { code: "no_key", message: "No API key.", next_action: "Call `agentry_login`." } };
+    const pid = projectId ?? cfg.default_project_id;
+    if (!pid)
+        return { error: { code: "no_project", message: "No project specified.", next_action: "Pass project_id." } };
+    const resp = await api.listAlerts(cfg, pid);
+    return { project_id: pid, ...resp };
+}
+async function handleEvaluateAlert(input) {
+    if (!input.alert_id) {
+        return { error: { code: "missing_alert_id", message: "alert_id is required.", next_action: "Pass alert id from agentry_list_alerts." } };
+    }
+    const cfg = loadConfig();
+    if (!cfg.api_key)
+        return { error: { code: "no_key", message: "No API key.", next_action: "Call `agentry_login`." } };
+    const pid = input.project_id ?? cfg.default_project_id;
+    if (!pid)
+        return { error: { code: "no_project", message: "No project specified.", next_action: "Pass project_id." } };
+    const resp = await api.evaluateAlert(cfg, pid, input.alert_id);
+    return { project_id: pid, ...resp };
+}
+async function handleDeleteAlert(input) {
+    if (!input.alert_id) {
+        return { error: { code: "missing_alert_id", message: "alert_id is required.", next_action: "Pass alert id." } };
+    }
+    const cfg = loadConfig();
+    if (!cfg.api_key)
+        return { error: { code: "no_key", message: "No API key.", next_action: "Call `agentry_login`." } };
+    const pid = input.project_id ?? cfg.default_project_id;
+    if (!pid)
+        return { error: { code: "no_project", message: "No project specified.", next_action: "Pass project_id." } };
+    const resp = await api.deleteAlert(cfg, pid, input.alert_id);
+    return { ...resp, project_id: pid };
+}
+//# sourceMappingURL=tools.js.map