@frmwrkd/snag-mcp 0.1.0

package/dist/tokens.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Token accounting — the single number that shapes this entire package.
+ *
+ * doc 03 §4.3 **[V]**:
+ *
+ * > **MCP tool output: warns at 10,000 tokens, hard-capped at 25,000**
+ * > (`MAX_MCP_OUTPUT_TOKENS`). This is the single most important number for
+ * > handoff design — it's why `.snag/` files, not MCP, carry the bulk.
+ *
+ * And 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.
+ *
+ * The estimator here is deliberately the crude `chars / 4` heuristic rather
+ * than a real tokenizer: no tokenizer is installed, and the point of these
+ * numbers is to fail a regression test when a response grows by an order of
+ * magnitude, not to bill anyone. It over-estimates on JSON (punctuation-heavy
+ * text tokenizes denser than 4 chars/token), which is the safe direction.
+ */
+/** Claude Code prints a warning above this many tokens of tool output. */
+export declare const MCP_OUTPUT_WARN_TOKENS = 10000;
+/** `MAX_MCP_OUTPUT_TOKENS` — Claude Code truncates above this. */
+export declare const MCP_OUTPUT_HARD_CAP_TOKENS = 25000;
+/**
+ * doc 02 §9.3: the `SessionStart` hook injects a **≤400-token** digest via
+ * `hookSpecificOutput.additionalContext`.
+ */
+export declare const SESSION_START_DIGEST_MAX_TOKENS = 400;
+/**
+ * doc 03 §4.3: "auto-compaction re-attaches only the first 5,000 tokens of each
+ * skill within a 25,000-token combined budget. Keep bodies under ~1,500 tokens."
+ */
+export declare const SKILL_BODY_MAX_TOKENS = 1500;
+/**
+ * doc 03 §4.4 **[V]**: the standard tier downscales an image to a 1568px long
+ * edge, so a screenshot costs **at most** 1,568 visual tokens — roughly 1,200
+ * words of prose. A 1440×900 shot lands almost exactly on that ceiling.
+ *
+ * Used as the per-image charge when estimating a tool result, because the real
+ * charge depends on pixel dimensions this package never decodes.
+ */
+export declare const IMAGE_VISUAL_TOKENS_STANDARD = 1568;
+/** Characters per token in the heuristic. */
+export declare const CHARS_PER_TOKEN = 4;
+export declare function estimateTokens(text: string): number;
+export declare function estimateJsonTokens(value: unknown): number;
+/** The minimum shape of a `CallToolResult` this estimator understands. */
+export interface EstimableResult {
+    content?: readonly unknown[];
+    structuredContent?: unknown;
+}
+/**
+ * Approximate what a tool result costs the client's output budget.
+ *
+ * Image blocks are charged at `IMAGE_VISUAL_TOKENS_STANDARD` rather than at
+ * the length of their base64 payload: doc 03 §4.4 records that Claude
+ * tokenizes images in 28×28 patches after downscaling, so the base64 length is
+ * not the cost. **[U]** — the appendix also notes the MCP spec gives no
+ * explicit byte limit on image content and that the binding constraint is the
+ * client's own accounting, which is not published. If a client charged base64
+ * length instead, a single screenshot would blow the cap; that is exactly why
+ * `snag_get` never inlines one (D13) and `snag_screenshot` caps the bytes it
+ * will inline (see `tools.ts`).
+ */
+export declare function estimateResultTokens(result: EstimableResult): number;
+/** Cut `text` to at most `maxTokens`, on a word boundary, with an ellipsis. */
+export declare function truncateToTokens(text: string, maxTokens: number): string;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,kEAAkE;AAClE,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAElD,6CAA6C;AAC7C,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEzD;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiBpE;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAMxE"}

package/dist/tokens.js

@@ -0,0 +1,90 @@
+/**
+ * Token accounting — the single number that shapes this entire package.
+ *
+ * doc 03 §4.3 **[V]**:
+ *
+ * > **MCP tool output: warns at 10,000 tokens, hard-capped at 25,000**
+ * > (`MAX_MCP_OUTPUT_TOKENS`). This is the single most important number for
+ * > handoff design — it's why `.snag/` files, not MCP, carry the bulk.
+ *
+ * And 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.
+ *
+ * The estimator here is deliberately the crude `chars / 4` heuristic rather
+ * than a real tokenizer: no tokenizer is installed, and the point of these
+ * numbers is to fail a regression test when a response grows by an order of
+ * magnitude, not to bill anyone. It over-estimates on JSON (punctuation-heavy
+ * text tokenizes denser than 4 chars/token), which is the safe direction.
+ */
+/** Claude Code prints a warning above this many tokens of tool output. */
+export const MCP_OUTPUT_WARN_TOKENS = 10_000;
+/** `MAX_MCP_OUTPUT_TOKENS` — Claude Code truncates above this. */
+export const MCP_OUTPUT_HARD_CAP_TOKENS = 25_000;
+/**
+ * doc 02 §9.3: the `SessionStart` hook injects a **≤400-token** digest via
+ * `hookSpecificOutput.additionalContext`.
+ */
+export const SESSION_START_DIGEST_MAX_TOKENS = 400;
+/**
+ * doc 03 §4.3: "auto-compaction re-attaches only the first 5,000 tokens of each
+ * skill within a 25,000-token combined budget. Keep bodies under ~1,500 tokens."
+ */
+export const SKILL_BODY_MAX_TOKENS = 1_500;
+/**
+ * doc 03 §4.4 **[V]**: the standard tier downscales an image to a 1568px long
+ * edge, so a screenshot costs **at most** 1,568 visual tokens — roughly 1,200
+ * words of prose. A 1440×900 shot lands almost exactly on that ceiling.
+ *
+ * Used as the per-image charge when estimating a tool result, because the real
+ * charge depends on pixel dimensions this package never decodes.
+ */
+export const IMAGE_VISUAL_TOKENS_STANDARD = 1_568;
+/** Characters per token in the heuristic. */
+export const CHARS_PER_TOKEN = 4;
+export function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+export function estimateJsonTokens(value) {
+    return estimateTokens(JSON.stringify(value) ?? '');
+}
+/**
+ * Approximate what a tool result costs the client's output budget.
+ *
+ * Image blocks are charged at `IMAGE_VISUAL_TOKENS_STANDARD` rather than at
+ * the length of their base64 payload: doc 03 §4.4 records that Claude
+ * tokenizes images in 28×28 patches after downscaling, so the base64 length is
+ * not the cost. **[U]** — the appendix also notes the MCP spec gives no
+ * explicit byte limit on image content and that the binding constraint is the
+ * client's own accounting, which is not published. If a client charged base64
+ * length instead, a single screenshot would blow the cap; that is exactly why
+ * `snag_get` never inlines one (D13) and `snag_screenshot` caps the bytes it
+ * will inline (see `tools.ts`).
+ */
+export function estimateResultTokens(result) {
+    let total = 0;
+    for (const block of result.content ?? []) {
+        if (typeof block === 'object' &&
+            block !== null &&
+            block.type === 'image') {
+            total += IMAGE_VISUAL_TOKENS_STANDARD;
+            continue;
+        }
+        total += estimateJsonTokens(block);
+    }
+    if (result.structuredContent !== undefined) {
+        total += estimateJsonTokens(result.structuredContent);
+    }
+    return total;
+}
+/** Cut `text` to at most `maxTokens`, on a word boundary, with an ellipsis. */
+export function truncateToTokens(text, maxTokens) {
+    const maxChars = maxTokens * CHARS_PER_TOKEN;
+    if (text.length <= maxChars)
+        return text;
+    const hard = text.slice(0, Math.max(0, maxChars - 1));
+    const lastSpace = hard.lastIndexOf(' ');
+    return `${lastSpace > maxChars / 2 ? hard.slice(0, lastSpace) : hard}…`;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C,kEAAkE;AAClE,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,KAAK,CAAC;AAElD,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AACrD,CAAC;AAQD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAuB;IAC1D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QACzC,IACE,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACb,KAA4B,CAAC,IAAI,KAAK,OAAO,EAC9C,CAAC;YACD,KAAK,IAAI,4BAA4B,CAAC;YACtC,SAAS;QACX,CAAC;QACD,KAAK,IAAI,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,MAAM,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QAC3C,KAAK,IAAI,kBAAkB,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,SAAiB;IAC9D,MAAM,QAAQ,GAAG,SAAS,GAAG,eAAe,CAAC;IAC7C,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;AAC1E,CAAC"}

package/dist/tools.d.ts

@@ -0,0 +1,115 @@
+import type { Task } from '@frmwrkd/snag-core';
+import type { CallToolResult, Tool, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import type { SnagBackend } from './client.js';
+/** Belt-and-braces on the list size. 50 summaries is ~2,400 tokens. */
+export declare const LIST_LIMIT_DEFAULT = 20;
+export declare 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 declare const SCREENSHOT_MAX_INLINE_BYTES = 3500000;
+/**
+ * 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.
+ */
+declare const TaskSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    severity: z.ZodEnum<["p0", "p1", "p2", "p3"]>;
+    kind: z.ZodString;
+    wave: z.ZodNumber;
+    status: z.ZodEnum<["open", "claimed", "in_progress", "verifying", "needs_review", "resolved", "wontfix"]>;
+    /** VERBATIM. The first `suspect_files` entry — never paraphrased. */
+    suspect_file: z.ZodNullable<z.ZodString>;
+    suspect_lines: z.ZodNullable<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    status: "open" | "resolved" | "claimed" | "in_progress" | "verifying" | "needs_review" | "wontfix";
+    kind: string;
+    severity: "p0" | "p1" | "p2" | "p3";
+    wave: number;
+    suspect_file: string | null;
+    suspect_lines: [number, number] | null;
+}, {
+    id: string;
+    title: string;
+    status: "open" | "resolved" | "claimed" | "in_progress" | "verifying" | "needs_review" | "wontfix";
+    kind: string;
+    severity: "p0" | "p1" | "p2" | "p3";
+    wave: number;
+    suspect_file: string | null;
+    suspect_lines: [number, number] | null;
+}>;
+export type TaskSummary = z.infer<typeof TaskSummarySchema>;
+export declare function summarise(task: Task): TaskSummary;
+export interface SnagToolDefinition {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly inputSchema: z.ZodTypeAny;
+    readonly outputSchema?: z.ZodTypeAny;
+    readonly annotations: ToolAnnotations;
+    handle(args: unknown, backend: SnagBackend): Promise<CallToolResult>;
+}
+/**
+ * ⚠️ 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 declare const TOOLS: readonly SnagToolDefinition[];
+export declare const TOOL_COUNT = 5;
+export declare function findTool(name: string): SnagToolDefinition | undefined;
+/**
+ * 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 declare function openTupleTail(node: unknown): unknown;
+export declare function toolDefinitions(): Tool[];
+/** Dispatch a `tools/call`. Unknown names are an error result, not a throw. */
+export declare function callTool(name: string, args: unknown, backend: SnagBackend): Promise<CallToolResult>;
+/** Exposed for the regression test that pins the status vocabulary. */
+export declare const KNOWN_TASK_STATUSES: readonly ["open", "claimed", "in_progress", "verifying", "needs_review", "resolved", "wontfix"];
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAsDA,OAAO,KAAK,EAAQ,IAAI,EAAc,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACV,WAAW,EAIZ,MAAM,aAAa,CAAC;AAqBrB,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,UAAY,CAAC;AAIrD;;;;;GAKG;AACH,QAAA,MAAM,iBAAiB;;;;;;;IAOrB,qEAAqE;;;;;;;;;;;;;;;;;;;;;EAGrE,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,CAYjD;AAyFD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACtE;AA8pBD;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,EAAE,SAAS,kBAAkB,EAM9C,CAAC;AAEF,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAErE;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAkBpD;AAED,wBAAgB,eAAe,IAAI,IAAI,EAAE,CAiBxC;AAED,+EAA+E;AAC/E,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAgBzB;AAED,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,iGAAgB,CAAC"}