@frmwrkd/snag-mcp 0.1.0

package/dist/tools.js

@@ -0,0 +1,868 @@
+/**
+ * The five tools. Not fifty.
+ *
+ * doc 02 §9.2:
+ *
+ * > **Five tools. Not fifty.** Chrome DevTools MCP ships ~17,000 tokens of tool
+ * > definitions before a single call; that cost is paid on every turn. Stay lean.
+ *
+ * | Tool | Signature | Returns |
+ * |---|---|---|
+ * | `snag_list` | `(status?, wave?, limit=20)` | compact task list — id, title, severity, wave, first suspect file |
+ * | `snag_get` | `(id)` | full task via `structuredContent` + `resource_link`s to screenshots on disk |
+ * | `snag_claim` | `(id)` | marks `claimed`, returns the full task |
+ * | `snag_resolve` | `(id, commit?, note?)` | asks snagd's verify preflight, then marks `verifying` and queues a verify run — **never `resolved` directly** |
+ * | `snag_screenshot` | `(id)` | image content — **only when explicitly called** |
+ *
+ * ## Three rules encoded here, each with a test guarding it
+ *
+ * 1. **`TOOLS.length === 5`.** A sixth tool costs every turn of every session
+ *    in this repo forever. `test/tools.test.ts` fails loudly if one appears.
+ * 2. **`snag_get` never inlines base64** (locked decision D13). Screenshots go
+ *    out as `resource_link`s with `file://` paths; Claude Code can `Read` a
+ *    local PNG directly, which sidesteps the 25,000-token output cap entirely.
+ * 3. **`snag_resolve` never sets `resolved`** while Verify is enabled (doc 02
+ *    §5.3: "`resolved` is **only ever set by Verify**, never by the agent
+ *    directly"). The one documented exception — `plan.verify_on_resolve:
+ *    false` — is what snagd's verify preflight reports as `verify_disabled`,
+ *    and it stamps `verified: false` through the daemon's transition table.
+ *
+ * ## Why `content` is not a JSON copy of `structuredContent`
+ *
+ * The MCP spec says a tool returning structured content SHOULD also return the
+ * serialised JSON as a text block, for clients that predate `structuredContent`.
+ * Doing that doubles every payload, and doubling payloads is the exact failure
+ * mode this package exists to avoid. So `content` instead carries a short,
+ * denser text block containing the parts an agent acts on **verbatim** — the
+ * `suspect_files` paths and line ranges — plus a pointer to
+ * `.snag/tasks/<label> - <title>.md`, which has the rest with no cap, no
+ * protocol overhead, and full prompt-cache benefit (doc 02 §9.1).
+ */
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SeveritySchema, TASK_STATUSES, TaskSchema, TaskStatusSchema, VISUAL_KINDS, findTransition, isTaskLabel, isTaskUid, isTerminalStatus, toInlineJsonSchema, } from '@frmwrkd/snag-core';
+import { z } from 'zod';
+import { DaemonRequestError, DaemonUnavailableError } from './client.js';
+import { IMAGE_VISUAL_TOKENS_STANDARD } from './tokens.js';
+/* ------------------------------------------------------------ shared bits */
+/**
+ * `SNAG-<n>` or `tsk_<ulid>` — the daemon's `GET /tasks/:id` accepts either.
+ *
+ * Validated with `.refine` rather than `.regex` on purpose: a `refine` leaves
+ * the emitted JSON Schema as a bare `{"type":"string"}` while still rejecting
+ * malformed ids server-side. The format belongs in the tool description, which
+ * the model reads anyway; a `pattern` keyword would be ~50 characters of
+ * always-on cost for a hint the description already gives.
+ */
+const TaskRefSchema = z
+    .string()
+    .min(1)
+    .refine((value) => isTaskLabel(value) || isTaskUid(value), {
+    message: 'Expected a task label (SNAG-<n>) or a task uid (tsk_<ulid>)',
+});
+/** Belt-and-braces on the list size. 50 summaries is ~2,400 tokens. */
+export const LIST_LIMIT_DEFAULT = 20;
+export const LIST_LIMIT_MAX = 50;
+/**
+ * Refuse to inline a screenshot larger than this. doc 03 §4.4 records that the
+ * MCP spec gives **no** explicit byte limit on image content and marks the real
+ * binding constraint **[U]**; the provider limit is 10 MB of base64. 3.5 MB of
+ * PNG is ~4.7 MB base64, comfortably inside that, and anything bigger is a
+ * full-page capture that the agent should `Read` from disk instead.
+ */
+export const SCREENSHOT_MAX_INLINE_BYTES = 3_500_000;
+/* ---------------------------------------------------- compact projections */
+/**
+ * doc 02 §9.2: "compact task list — id, title, severity, wave, first suspect
+ * file". `uid` is deliberately absent: it is 30 characters × every row, and
+ * every tool here accepts the `SNAG-<n>` label instead. `kind` is one token and
+ * tells the agent whether `snag_screenshot` is worth calling at all.
+ */
+const TaskSummarySchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    severity: SeveritySchema,
+    kind: z.string(),
+    wave: z.number().int().nonnegative(),
+    status: TaskStatusSchema,
+    /** VERBATIM. The first `suspect_files` entry — never paraphrased. */
+    suspect_file: z.string().nullable(),
+    suspect_lines: z.tuple([z.number().int(), z.number().int()]).nullable(),
+});
+export function summarise(task) {
+    const first = task.suspect_files[0];
+    return {
+        id: task.id,
+        title: task.title,
+        severity: task.severity,
+        kind: task.kind,
+        wave: task.wave,
+        status: task.status,
+        suspect_file: first?.path ?? null,
+        suspect_lines: first?.lines ?? null,
+    };
+}
+const SourceSchema = z.enum(['daemon', 'files']);
+/* ----------------------------------------------------------- I/O schemas */
+const ListInputSchema = z.object({
+    status: TaskStatusSchema.optional(),
+    wave: z.number().int().nonnegative().optional(),
+    limit: z.number().int().positive().max(LIST_LIMIT_MAX).default(LIST_LIMIT_DEFAULT),
+});
+const ListOutputSchema = z.object({
+    tasks: z.array(TaskSummarySchema),
+    returned: z.number().int().nonnegative(),
+    /** How many matched before `limit` was applied. */
+    total: z.number().int().nonnegative(),
+    source: SourceSchema,
+    /** One line. Which expensive call is worth making next. */
+    hint: z.string(),
+});
+const GetInputSchema = z.object({ id: TaskRefSchema });
+/**
+ * `GET /verify/:taskId`, projected. Present on `snag_get` once Verify has been
+ * involved — the task is `verifying`, a run is in flight, or one has settled
+ * since snagd started. `reason` is the daemon's, verbatim.
+ */
+const VerifySummarySchema = z.object({
+    running: z.boolean(),
+    outcome: z.string().nullable(),
+    reason: z.string().nullable(),
+    last_at: z.string().nullable(),
+});
+const TaskDetailSchema = z.object({
+    task: TaskSchema,
+    /** Repo-relative markdown path — `Read` this, it has no output cap. */
+    markdown_file: z.string().nullable(),
+    /** Repo-relative screenshot paths. Also emitted as `resource_link`s. */
+    screenshots: z.array(z.string()),
+    source: SourceSchema,
+    /** Jam's `getDetails` pattern: which expensive calls are worth making. */
+    next_actions: z.array(z.string()),
+    verify: VerifySummarySchema.optional(),
+});
+const ClaimOutputSchema = TaskDetailSchema.extend({
+    previous_status: TaskStatusSchema,
+});
+const ResolveInputSchema = z.object({
+    id: TaskRefSchema,
+    /**
+     * A sha you already committed, or `true` to have snagd commit the fix now.
+     *
+     * doc 02 §9.2 forbids a sixth tool — the toolset is a permanent per-turn tax —
+     * so committing is a parameter of the call that already records a commit,
+     * rather than a `snag_commit` of its own.
+     */
+    commit: z.union([z.string(), z.boolean()]).optional(),
+    /** With `commit: true`: the repo-relative paths you edited for this task. */
+    files: z.array(z.string().min(1)).optional(),
+    note: z.string().optional(),
+});
+const ResolveOutputSchema = z.object({
+    id: z.string(),
+    uid: z.string(),
+    /**
+     * `verifying` — or `resolved` **only** when snagd has Verify disabled, or
+     * where it was left (`in_progress`, usually) when Verify cannot run on it.
+     */
+    status: TaskStatusSchema,
+    verify_queued: z.boolean(),
+    /** `false` records a resolve taken on trust with Verify disabled (doc 02 §5.3). */
+    verified: z.boolean().nullable(),
+    detail: z.string(),
+});
+const ScreenshotInputSchema = z.object({
+    id: TaskRefSchema,
+    /** Which screenshot, when a task merged several captures. */
+    index: z.number().int().nonnegative().default(0),
+});
+const READ_ONLY = {
+    readOnlyHint: true,
+    openWorldHint: false,
+};
+const MUTATING = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+/* ------------------------------------------------------------- helpers */
+function textBlock(text) {
+    return { type: 'text', text };
+}
+function errorResult(message) {
+    return { content: [textBlock(message)], isError: true };
+}
+/** Turn a thrown daemon error into an `isError` result the agent can act on. */
+function daemonErrorResult(error) {
+    if (error instanceof DaemonUnavailableError)
+        return errorResult(error.message);
+    if (error instanceof DaemonRequestError) {
+        return errorResult(`snagd refused (${error.status} ${error.code}): ${error.message}`);
+    }
+    throw error;
+}
+function notFound(id) {
+    return errorResult(`No task ${id}. Call snag_list first, or Read .snag/tasks/ — ids look like SNAG-3 or tsk_<ulid>.`);
+}
+/** Repo-relative screenshot paths that actually exist on disk. */
+function existingScreenshots(task, backend) {
+    const present = [];
+    const missing = [];
+    for (const relative of task.evidence_refs.screenshots) {
+        const absolute = backend.files.resolveInsideRoot(relative);
+        if (absolute !== null && backend.files.readBytes(relative) !== null)
+            present.push(relative);
+        else
+            missing.push(relative);
+    }
+    return { present, missing };
+}
+function resourceLink(backend, relative) {
+    const absolute = backend.files.resolveInsideRoot(relative);
+    if (absolute === null)
+        return null;
+    return {
+        type: 'resource_link',
+        uri: pathToFileURL(absolute).href,
+        name: path.basename(relative),
+        mimeType: 'image/png',
+        description: `Screenshot on disk — Read it directly (~${IMAGE_VISUAL_TOKENS_STANDARD} visual tokens).`,
+    };
+}
+const isVisualKind = (kind) => VISUAL_KINDS.includes(kind);
+/**
+ * Jam's `getDetails` pattern (doc 02 §9.2): one cheap call tells the agent which
+ * expensive calls are worth making. D13 is the rule being applied — a
+ * screenshot is ~1,568 visual tokens ≈ 1,200 words, worth it for a layout bug
+ * and wasteful for "button does nothing".
+ */
+function nextActions(task, markdownFile, screenshots, verify = null) {
+    const actions = [];
+    if (verify !== null) {
+        const action = verifyAction(task, verify);
+        if (action !== null)
+            actions.push(action);
+    }
+    if (markdownFile !== null) {
+        actions.push(`Read ${markdownFile} — full repro/expected/actual/acceptance, no output cap.`);
+    }
+    if (task.status === 'open') {
+        actions.push(`snag_claim("${task.id}") before you edit anything.`);
+    }
+    if (task.depends_on.length > 0) {
+        actions.push(`Blocked by ${task.depends_on.length} task(s): ${task.depends_on.join(', ')} — snag_get accepts uids.`);
+    }
+    if (screenshots.length > 0) {
+        actions.push(isVisualKind(task.kind)
+            ? `snag_screenshot("${task.id}") — kind is "${task.kind}", the pixels are the evidence.`
+            : `Screenshot exists but kind is "${task.kind}"; the anchors above are cheaper than ~${IMAGE_VISUAL_TOKENS_STANDARD} visual tokens.`);
+    }
+    if (task.suspect_files.length > 0) {
+        actions.push('Open the suspect_files at the given line ranges. Do not Grep for a file already named there.');
+    }
+    return actions;
+}
+/**
+ * What to do about Verify, given where it left the task. The retry advice is
+ * reserved for the cases a retry can fix: nothing queued, or a run that could
+ * not drive the browser. A task Verify could not judge goes to a human.
+ */
+function verifyAction(task, verify) {
+    if (verify.running) {
+        return `Verify is running in Chrome — snag_get("${task.id}") again in ~30 s. It is not done yet.`;
+    }
+    if (task.status === 'verifying') {
+        if (verify.outcome === null) {
+            return `No verify run is in flight and none has finished since snagd started — snag_resolve("${task.id}") queues one.`;
+        }
+        if (verify.outcome === 'error') {
+            return `The last verify run could not finish (reason above). Once that is fixed, snag_resolve("${task.id}") queues another.`;
+        }
+        return null;
+    }
+    if (task.status === 'needs_review') {
+        return `Verify could not judge this fix (reason above). A human reviews it — do not call snag_resolve on it again.`;
+    }
+    if (task.status === 'open' && verify.outcome === 'failed') {
+        return `Verify re-opened it (reason above) and attached fresh evidence to the task. Read that before editing again.`;
+    }
+    return null;
+}
+/** One line on Verify for the text block. Reason verbatim — it quotes console errors. */
+function verifyLine(verify) {
+    const last = verify.outcome === null
+        ? 'no run has finished since snagd started'
+        : `last run ${verify.outcome}${verify.last_at === null ? '' : ` at ${verify.last_at}`}${verify.reason === null ? '' : ` — ${verify.reason}`}`;
+    return `verify: ${verify.running ? 'a run is in flight; ' : ''}${last}`;
+}
+/** The dense text block that accompanies a task's `structuredContent`. */
+function taskTextBlock(task, markdownFile, source, verify = null) {
+    const lines = [
+        `${task.id} · ${task.severity} · ${task.kind} · wave ${task.wave} · ${task.status}`,
+        task.title,
+    ];
+    if (verify !== null)
+        lines.push(verifyLine(verify));
+    if (task.suspect_files.length > 0) {
+        lines.push('suspect_files (verbatim edit anchors):');
+        for (const file of task.suspect_files) {
+            // A path with no range still tells the agent which file to open, which is
+            // strictly better than omitting the entry — and it is honest about the
+            // precision it has, rather than inventing a range.
+            const where = file.lines === undefined ? file.path : `${file.path}:${file.lines[0]}-${file.lines[1]}`;
+            lines.push(`  ${where}  — ${file.why}`);
+        }
+    }
+    else {
+        lines.push('suspect_files: none — this task has no anchor yet.');
+    }
+    if (markdownFile !== null)
+        lines.push(`markdown: ${markdownFile}`);
+    if (source === 'files') {
+        lines.push('source: .snag/plan.json (snagd is not running) — status may lag the live index.');
+    }
+    return lines.join('\n');
+}
+function detailResult(task, markdownFile, source, backend, options = {}) {
+    const { extra = {}, leadingText, verify = null } = options;
+    const { present, missing } = existingScreenshots(task, backend);
+    const actions = nextActions(task, markdownFile, present, verify);
+    const content = [];
+    if (leadingText !== undefined)
+        content.push(textBlock(leadingText));
+    content.push(textBlock(taskTextBlock(task, markdownFile, source, verify)));
+    for (const relative of present) {
+        const link = resourceLink(backend, relative);
+        if (link !== null)
+            content.push(link);
+    }
+    if (missing.length > 0) {
+        content.push(textBlock(`Screenshot paths recorded but missing on disk: ${missing.join(', ')}`));
+    }
+    if (actions.length > 0)
+        content.push(textBlock(`Next: ${actions.join(' · ')}`));
+    return {
+        content,
+        structuredContent: {
+            task,
+            markdown_file: markdownFile,
+            screenshots: present,
+            source,
+            next_actions: actions,
+            ...(verify === null ? {} : { verify }),
+            ...extra,
+        },
+    };
+}
+/* ---------------------------------------------------------------- tools */
+const snagList = {
+    name: 'snag_list',
+    title: 'List Snag tasks',
+    description: 'Compact queue of Snag tasks: id, title, severity (p0 most severe), kind, wave, status, and the first suspect file with its line range. Defaults to non-terminal tasks in wave order. Start here, then snag_get only the ones you will work.',
+    inputSchema: ListInputSchema,
+    outputSchema: ListOutputSchema,
+    annotations: READ_ONLY,
+    async handle(args, backend) {
+        const input = ListInputSchema.parse(args);
+        const limit = Math.min(input.limit, LIST_LIMIT_MAX);
+        let result;
+        try {
+            // The daemon filters on a single status; "everything not finished" is a
+            // set, so over-fetch and narrow here. The over-fetch is bounded.
+            result = await backend.listTasks({
+                ...(input.status === undefined ? {} : { status: input.status }),
+                ...(input.wave === undefined ? {} : { wave: input.wave }),
+                limit: input.status === undefined ? Math.min(limit * 3, 150) : limit,
+            });
+        }
+        catch (error) {
+            return daemonErrorResult(error);
+        }
+        const matched = input.status === undefined
+            ? result.tasks.filter((task) => !isTerminalStatus(task.status))
+            : result.tasks;
+        const tasks = matched.slice(0, limit).map(summarise);
+        const openInFirstWave = matched.filter((task) => task.wave === (matched[0]?.wave ?? 0) && task.status === 'open').length;
+        const hint = matched.length === 0
+            ? 'Queue is empty. Nothing to work.'
+            : `${openInFirstWave} open in wave ${matched[0]?.wave ?? 0}. snag_get one for repro + suspect_files, then snag_claim it.`;
+        const structuredContent = {
+            tasks,
+            returned: tasks.length,
+            total: matched.length,
+            source: result.source,
+            hint,
+        };
+        return {
+            content: [
+                textBlock(formatListText(tasks, structuredContent.total, result.source, hint, 
+                // Only ever non-null when plan.json is present AND unparseable, so
+                // this cannot turn a genuinely clear queue into a scary message.
+                tasks.length === 0 ? backend.files.emptyTasksReason() : null)),
+            ],
+            structuredContent,
+        };
+    },
+};
+function formatListText(tasks, total, source, hint, 
+/** Set when the list is empty *because the plan could not be read*. */
+emptyReason = null) {
+    if (tasks.length === 0) {
+        // An unreadable plan is not an empty queue, and must never be reported as
+        // one — that tells the agent to stop when it should be telling someone to
+        // look at the file.
+        if (emptyReason !== null)
+            return emptyReason;
+        return source === 'files'
+            ? 'No tasks in .snag/plan.json (snagd is not running). Run Merge & Plan, or Read .snag/tasks/.'
+            : 'No tasks match. The queue is clear.';
+    }
+    const rows = tasks.map((task) => {
+        const anchor = task.suspect_file === null
+            ? 'no anchor'
+            : `${task.suspect_file}${task.suspect_lines === null ? '' : `:${task.suspect_lines[0]}-${task.suspect_lines[1]}`}`;
+        return `${task.id}\t${task.severity}\tw${task.wave}\t${task.status}\t${task.title}\t${anchor}`;
+    });
+    const header = source === 'files'
+        ? `${tasks.length}/${total} tasks from .snag/plan.json (snagd is not running; statuses may lag)`
+        : `${tasks.length}/${total} tasks`;
+    return `${header}\nid\tsev\twave\tstatus\ttitle\tsuspect_file:lines\n${rows.join('\n')}\n${hint}`;
+}
+const snagGet = {
+    name: 'snag_get',
+    title: 'Get one Snag task',
+    description: 'One task in full, by SNAG-<n> or tsk_<ulid>: repro, expected, actual, acceptance criteria, and suspect_files with verbatim paths and line ranges. Screenshots come back as resource_links to files on disk, never inlined. After snag_resolve, `verify` says whether Verify is running and how its last run ended.',
+    inputSchema: GetInputSchema,
+    outputSchema: TaskDetailSchema,
+    annotations: READ_ONLY,
+    async handle(args, backend) {
+        const input = GetInputSchema.parse(args);
+        let found;
+        try {
+            found = await backend.getTask(input.id);
+        }
+        catch (error) {
+            return daemonErrorResult(error);
+        }
+        if (found === null)
+            return notFound(input.id);
+        // snag_resolve returns before Verify has run, and tells the agent to come
+        // back here. The status alone cannot say "still running" from "ran, and
+        // could not judge it", so ask the daemon, which keeps the last report.
+        // Shown only once Verify is involved: a task that never met it gets
+        // nothing, rather than a block of nulls.
+        let verify = null;
+        if (found.source === 'daemon') {
+            const status = await backend.verifyStatus(found.task.uid);
+            if (status !== null &&
+                (status.running || status.outcome !== null || found.task.status === 'verifying')) {
+                verify = status;
+            }
+        }
+        return detailResult(found.task, found.file, found.source, backend, { verify });
+    },
+};
+const snagClaim = {
+    name: 'snag_claim',
+    title: 'Claim a Snag task',
+    description: 'Take ownership of a task: status open -> claimed. Returns the full task. Claim before editing so a second agent in the same wave does not pick it up.',
+    inputSchema: GetInputSchema,
+    outputSchema: ClaimOutputSchema,
+    annotations: MUTATING,
+    async handle(args, backend) {
+        const input = GetInputSchema.parse(args);
+        let found;
+        try {
+            found = await backend.getTask(input.id);
+        }
+        catch (error) {
+            return daemonErrorResult(error);
+        }
+        if (found === null)
+            return notFound(input.id);
+        const previous = found.task.status;
+        if (previous === 'claimed' || previous === 'in_progress') {
+            return detailResult(found.task, found.file, found.source, backend, {
+                extra: { previous_status: previous },
+                leadingText: `${found.task.id} is already ${previous}; nothing to do.`,
+            });
+        }
+        let claimed;
+        try {
+            claimed = await backend.setStatus(found.task.id, 'claimed');
+        }
+        catch (error) {
+            return daemonErrorResult(error);
+        }
+        return detailResult(claimed, found.file, 'daemon', backend, {
+            extra: { previous_status: previous },
+        });
+    },
+};
+/**
+ * The transitions `snag_resolve` may take, in order, from wherever the task is.
+ *
+ * doc 02 §5.3's table only has `in_progress -> verifying`. The step into
+ * `in_progress` is normally made by the `PostToolUse` hook on the first
+ * `Edit`/`Write` of a `suspect_files` path — but the hook is optional, and a
+ * task stuck at `claimed` with the work already done must still be resolvable.
+ * So a `claimed` task is walked through `in_progress` first. Both hops go
+ * through the daemon, which enforces the table; nothing here bypasses it.
+ */
+function resolvePath(from, target) {
+    if (from === 'claimed')
+        return ['in_progress', target];
+    if (from === 'open')
+        return ['claimed', 'in_progress', target];
+    return [target];
+}
+/**
+ * Whether `resolvePath` from `from` reaches `target` using only edges an agent
+ * may take — in doc 02 §5.3's table, and neither `user_only` nor
+ * `verify_only`. A `condition` is left to the daemon, which owns the config.
+ * Asked *before* moving anything, so a walk that would stop half-way is never
+ * started.
+ */
+function agentCanReach(from, target) {
+    let at = from;
+    for (const step of resolvePath(from, target)) {
+        if (step === at)
+            continue;
+        const transition = findTransition(at, step);
+        if (transition === undefined || transition.user_only === true || transition.verify_only === true) {
+            return false;
+        }
+        at = step;
+    }
+    return at === target;
+}
+/** Walk `task` along `resolvePath` through the daemon. Throws what `setStatus` throws. */
+async function walkTo(task, target, backend) {
+    let current = task;
+    for (const step of resolvePath(current.status, target)) {
+        if (current.status === step)
+            continue;
+        current = await backend.setStatus(current.id, step);
+    }
+    return current;
+}
+function resolveResult(task, verifyQueued, detail) {
+    return {
+        content: [textBlock(detail)],
+        structuredContent: {
+            id: task.id,
+            uid: task.uid,
+            status: task.status,
+            verify_queued: verifyQueued,
+            verified: task.verified ?? null,
+            detail,
+        },
+    };
+}
+/**
+ * doc 02 §5.3: "If Verify is disabled in config, `snag_resolve` moves straight
+ * to `resolved` and records `verified: false`." That is the ONLY path on which
+ * this tool may name `resolved`, it is taken only on snagd's own word that
+ * Verify is off, and the daemon still gates the edge on
+ * `plan.verify_on_resolve === false`.
+ */
+async function resolveWithoutVerify(task, preflight, backend) {
+    if (!agentCanReach(task.status, 'resolved')) {
+        return resolveResult(task, false, `${task.id} is ${task.status} and was left there. snagd has Verify disabled (${preflight.message}), ` +
+            `and without Verify a task is resolved directly only from in_progress (doc 02 §5.3). ` +
+            `Verify cannot run for this task, so a human must resolve it.`);
+    }
+    const was = task.status;
+    let resolved;
+    try {
+        resolved = await walkTo(task, 'resolved', backend);
+    }
+    catch (error) {
+        return daemonErrorResult(error);
+    }
+    return resolveResult(resolved, false, `${resolved.id} ${was === 'resolved' ? 'was already' : 'is now'} resolved, without Verify: snagd has it disabled (${preflight.message}). ` +
+        `It is recorded verified: false — taken on trust, not checked.`);
+}
+const snagResolve = {
+    name: 'snag_resolve',
+    title: 'Mark a Snag task fixed',
+    description: 'Claim that a task is fixed: status -> verifying, and a verify run is queued. It does NOT mark the task resolved: only Verify does, after re-opening the page, re-resolving the anchor and checking the console errors the capture recorded. A fix Verify cannot judge goes to needs_review; a task Verify cannot run on is left for a human. Pass commit: true with files: [paths you edited] and snagd commits them first — exactly those paths, never `git add -A`, never a push — and records the sha against the task. Pass a sha instead if you committed yourself.',
+    inputSchema: ResolveInputSchema,
+    outputSchema: ResolveOutputSchema,
+    annotations: MUTATING,
+    async handle(args, backend) {
+        const input = ResolveInputSchema.parse(args);
+        let found;
+        try {
+            found = await backend.getTask(input.id);
+        }
+        catch (error) {
+            return daemonErrorResult(error);
+        }
+        if (found === null)
+            return notFound(input.id);
+        // Ask snagd whether Verify can run on this task at all, BEFORE any
+        // transition. `verifying` has no exit an agent can take: a task parked
+        // there with no URL to re-visit — an authored task — or with Verify
+        // switched off stays there forever, looking like progress.
+        let preflight;
+        try {
+            preflight = await backend.verifyPreflight(found.task.uid);
+        }
+        catch (error) {
+            return daemonErrorResult(error);
+        }
+        let task = found.task;
+        if (!preflight.ok) {
+            if (preflight.code === 'verify_disabled') {
+                return resolveWithoutVerify(task, preflight, backend);
+            }
+            if (preflight.code === 'no_capture_url') {
+                // The work is done as far as the agent knows, so a claimed task moves
+                // on to in_progress — and no further. Retrying cannot conjure a URL.
+                if (agentCanReach(task.status, 'in_progress')) {
+                    try {
+                        task = await walkTo(task, 'in_progress', backend);
+                    }
+                    catch (error) {
+                        return daemonErrorResult(error);
+                    }
+                }
+                return resolveResult(task, false, `${task.id} is ${task.status}, not verifying: Verify cannot run for this task — ${preflight.message}. ` +
+                    `Calling snag_resolve again will not change that; a human must check the fix and resolve it.`);
+            }
+            if (preflight.code !== 'verify_unavailable') {
+                return errorResult(`snagd refused the verify preflight (${preflight.status} ${preflight.code}): ${preflight.message} — ` +
+                    `${task.id} was left ${task.status}; nothing changed.`);
+            }
+            // `verify_unavailable` is the one refusal time fixes: no extension is
+            // attached *yet*. The task moves on and the run is asked for anyway —
+            // a tab may have reconnected since the preflight.
+        }
+        try {
+            task = await walkTo(task, 'verifying', backend);
+        }
+        catch (error) {
+            return daemonErrorResult(error);
+        }
+        // Commit before Verify, so the sha recorded against the task is the one
+        // that contains the fix Verify is about to judge.
+        let sha = typeof input.commit === 'string' ? input.commit : undefined;
+        let committed = '';
+        if (input.commit === true) {
+            let answer;
+            try {
+                answer = await backend.commit({
+                    task: task.id,
+                    ...(input.files === undefined ? {} : { files: input.files }),
+                });
+            }
+            catch (error) {
+                return daemonErrorResult(error);
+            }
+            if (answer.sha !== undefined)
+                sha = answer.sha;
+            // snagd's own sentence either way: `main is in git.protected_branches …`
+            // names the fix; "could not commit" would not.
+            committed =
+                answer.code === 'committed'
+                    ? ` Committed ${answer.sha?.slice(0, 8) ?? ''} — ${answer.files.join(', ')}.`
+                    : ` Not committed: ${answer.message}.`;
+        }
+        const verify = await backend.queueVerify(task.uid, {
+            ...(sha === undefined ? {} : { commit: sha }),
+            ...(input.note === undefined ? {} : { note: input.note }),
+        });
+        const alreadyVerifying = found.task.status === 'verifying' && task.status === 'verifying';
+        const verifyingNow = `${task.id} ${alreadyVerifying ? 'was already' : 'is now'} verifying.`;
+        let detail;
+        if (verify.code === 'verify_unavailable') {
+            // The daemon's message names the fix (reload a tab, call again). Nothing
+            // is lost: the task stays `verifying` until a run can happen.
+            detail = `${verifyingNow} Verify could not start: ${verify.detail}`;
+        }
+        else if (verify.queued) {
+            detail = `${verifyingNow} ${verify.detail}. It is not done until Verify says so.`;
+        }
+        else if (verify.code === undefined) {
+            // snagd itself stopped answering between the transition and the queue —
+            // the same kind of absence as no extension, and fixed the same way.
+            detail = `${verifyingNow} ${verify.detail}. It stays verifying; once snagd answers again, snag_resolve queues the run.`;
+        }
+        else {
+            detail = `${verifyingNow} ${verify.detail}. No verify run was queued, so it stays verifying until a human looks at it.`;
+        }
+        return resolveResult(task, verify.queued, `${detail}${committed}`);
+    },
+};
+const snagScreenshot = {
+    name: 'snag_screenshot',
+    title: 'Fetch a Snag screenshot',
+    description: `Return a task's screenshot as an image. Costs ~${IMAGE_VISUAL_TOKENS_STANDARD} visual tokens (about 1,200 words), so call it only when the bug is visual — layout, spacing, contrast. For "button does nothing" the anchor and console text in snag_get are strictly better.`,
+    inputSchema: ScreenshotInputSchema,
+    annotations: READ_ONLY,
+    async handle(args, backend) {
+        const input = ScreenshotInputSchema.parse(args);
+        let found;
+        try {
+            found = await backend.getTask(input.id);
+        }
+        catch (error) {
+            return daemonErrorResult(error);
+        }
+        if (found === null)
+            return notFound(input.id);
+        const { present } = existingScreenshots(found.task, backend);
+        const relative = present[input.index];
+        if (relative === undefined) {
+            return errorResult(present.length === 0
+                ? `${found.task.id} has no screenshot on disk. evidence_refs.screenshots: ${JSON.stringify(found.task.evidence_refs.screenshots)}`
+                : `${found.task.id} has ${present.length} screenshot(s); index ${input.index} is out of range.`);
+        }
+        const bytes = backend.files.readBytes(relative);
+        if (bytes === null)
+            return errorResult(`Could not read ${relative}.`);
+        if (bytes.byteLength > SCREENSHOT_MAX_INLINE_BYTES) {
+            const link = resourceLink(backend, relative);
+            return {
+                content: [
+                    textBlock(`${relative} is ${bytes.byteLength} bytes, over the ${SCREENSHOT_MAX_INLINE_BYTES}-byte inline limit. Read the file directly instead.`),
+                    ...(link === null ? [] : [link]),
+                ],
+            };
+        }
+        return {
+            content: [
+                { type: 'image', data: bytes.toString('base64'), mimeType: 'image/png' },
+                textBlock(`${relative} — ${found.task.id}: ${found.task.title}`),
+            ],
+        };
+    },
+};
+/* ------------------------------------------------------------- registry */
+/**
+ * ⚠️ EXACTLY FIVE. doc 02 §9.2 and doc 03 §1.3: Chrome DevTools MCP ships
+ * ~17,000 tokens of tool definitions before a single call and pays that on
+ * every turn; Vercel measured a 3.5× speed-up and 37% fewer tokens from cutting
+ * an agent's toolset by 80%. Adding a sixth tool taxes every turn of every
+ * session in every repo that installs this server. If you need one more verb,
+ * add a parameter to an existing tool or put the data in `.snag/`, which has no
+ * cap at all.
+ */
+export const TOOLS = [
+    snagList,
+    snagGet,
+    snagClaim,
+    snagResolve,
+    snagScreenshot,
+];
+export const TOOL_COUNT = 5;
+export function findTool(name) {
+    return TOOLS.find((tool) => tool.name === name);
+}
+/**
+ * The wire form of a tool definition — this is what costs tokens on every turn.
+ *
+ * `$schema` and `title` are stripped from the generated documents: the MCP spec
+ * fixes tool schemas at JSON Schema 2020-12, so the `$schema` keyword is
+ * redundant, and the tool already carries a `title`. Together they are ~135
+ * tokens across the nine schemas here, paid on every turn, for zero
+ * information.
+ */
+function wireSchema(schema, name) {
+    const document = toInlineJsonSchema(schema, name);
+    delete document['$schema'];
+    delete document['title'];
+    return openTupleTail(document);
+}
+/**
+ * Drop the redundant `items: false` from a length-pinned tuple.
+ *
+ * `@frmwrkd/snag-core`'s `toInlineJsonSchema` correctly rewrites a draft-7 tuple into
+ * the 2020-12 form:
+ *
+ * ```json
+ * { "type": "array", "minItems": 2, "maxItems": 2,
+ *   "prefixItems": [{"type":"integer"},{"type":"integer"}], "items": false }
+ * ```
+ *
+ * That is exactly right per the spec — and the MCP TypeScript SDK v1.30.0
+ * rejects it. Its default validator is `AjvJsonSchemaValidator`, which
+ * constructs `new Ajv(...)` from `ajv`'s **draft-07** entry point. Draft-07 has
+ * no `prefixItems` keyword, so Ajv ignores it and applies `items: false` to
+ * every element, and a client validating `structuredContent` against the
+ * declared `outputSchema` fails a perfectly valid `[80, 96]` with:
+ *
+ * > MCP error -32602: Structured content does not match the tool's output
+ * > schema: data/tasks/0/suspect_lines/0 boolean schema is false
+ *
+ * Verified against `ajv@8.20.0` and reproduced end to end over stdio, which is
+ * the only place it shows up — the server-side path never sees it.
+ *
+ * When `maxItems === prefixItems.length`, `items` is vacuous in 2020-12 (there
+ * can be no element past the prefix), so deleting it changes nothing for a
+ * 2020-12 validator and makes a draft-07 validator fall back to `minItems` /
+ * `maxItems`, which still pin the arity. Where the arity is *not* pinned,
+ * `items: false` is load-bearing and is left alone.
+ *
+ * `Task.suspect_files[].lines` is the tuple that hits this, and it is the one
+ * field an agent uses to open a file at the right place. Losing it to a
+ * validation error would be a silent, total failure of `snag_get`.
+ */
+export function openTupleTail(node) {
+    if (Array.isArray(node))
+        return node.map(openTupleTail);
+    if (typeof node !== 'object' || node === null)
+        return node;
+    const source = node;
+    const out = {};
+    const prefixItems = source['prefixItems'];
+    const pinned = Array.isArray(prefixItems) &&
+        source['items'] === false &&
+        typeof source['maxItems'] === 'number' &&
+        source['maxItems'] === prefixItems.length;
+    for (const [key, value] of Object.entries(source)) {
+        if (pinned && key === 'items')
+            continue;
+        out[key] = openTupleTail(value);
+    }
+    return out;
+}
+export function toolDefinitions() {
+    return TOOLS.map((tool) => {
+        const definition = {
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            inputSchema: wireSchema(tool.inputSchema, `${tool.name}_input`),
+            annotations: tool.annotations,
+        };
+        if (tool.outputSchema !== undefined) {
+            definition.outputSchema = wireSchema(tool.outputSchema, `${tool.name}_output`);
+        }
+        return definition;
+    });
+}
+/** Dispatch a `tools/call`. Unknown names are an error result, not a throw. */
+export async function callTool(name, args, backend) {
+    const tool = findTool(name);
+    if (tool === undefined) {
+        return errorResult(`Unknown tool ${name}. This server has exactly ${TOOL_COUNT}: ${TOOLS.map((t) => t.name).join(', ')}.`);
+    }
+    try {
+        return await tool.handle(args ?? {}, backend);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            return errorResult(`Bad arguments for ${name}: ${error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+        }
+        if (error instanceof DaemonUnavailableError || error instanceof DaemonRequestError) {
+            return daemonErrorResult(error);
+        }
+        return errorResult(`${name} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Exposed for the regression test that pins the status vocabulary. */
+export const KNOWN_TASK_STATUSES = TASK_STATUSES;
+//# sourceMappingURL=tools.js.map