@warmdrift/kgauto-check 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @warmdrift/kgauto-check
+
+**Point your AI at your project.**
+
+If you're the human: copy the block below to your coding agent (Claude Code, Cursor, or any MCP-capable agent). That's your whole job.
+
+```
+Add the kgauto check MCP server and run the check on this project:
+  claude mcp add kgauto-check -- npx -y @warmdrift/kgauto-check
+Then call its start_check tool and follow the instructions.
+```
+
+Everything below is for the agent.
+
+---
+
+## What this is (for you, the agent)
+
+A local, **fully offline** MCP server that checks a project's AI call surface against kgauto's doc-verified model catalog — lifecycle statuses, prices with verification dates, context/output/tool limits, capability flags (parallel tool calls, structured output), and known quality cliffs that the kgauto compiler executes in production.
+
+**The trust boundary:** you read the project's code (you already have access); kgauto reads nothing. The extract you build carries identifiers and counts only — never prompt text, source code, or secrets. This check ran locally against kgauto's bundled model catalog. Nothing is uploaded; no rows are written anywhere. There is no code path that could make that sentence false: the server makes no network calls.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `start_check` | Call first. Returns extraction instructions — what to read from the project and how to build the extract. |
+| `run_check` | Runs the deterministic check on your extract. Returns a findings card grouped by confidence tier — present it to your human **verbatim**. |
+| `get_model_facts` | One model id → status, verified prices, limits, capabilities, known cliffs. Honest miss on unknown models. |
+| `get_observe_day_plan` | Rung 2: what a one-day observe-only run on real traffic would measure, and the two honesty requirements any setup must carry. |
+
+## The confidence tiers (why the card is grouped)
+
+- **certain** — a catalog or code fact. Stated flatly.
+- **likely** — priced from your token estimates against verified prices.
+- **measurable-only** — honestly unknowable from a code read: actual failure rates, actual input-waste, spend distribution, quality-at-cheaper-price. Each of these is exactly what the one-day observe run answers.
+
+kgauto refuses to fabricate verdicts: unknown models get an honest "no measured evidence", and cheaper candidates are named with their price arithmetic only — never with an unmeasured quality claim.
+
+## Client setup variants
+
+```bash
+# Claude Code
+claude mcp add kgauto-check -- npx -y @warmdrift/kgauto-check
+```
+
+```json
+// Cursor / generic mcpServers config
+{
+  "mcpServers": {
+    "kgauto-check": { "command": "npx", "args": ["-y", "@warmdrift/kgauto-check"] }
+  }
+}
+```
+
+## What's underneath
+
+The catalog is `@warmdrift/kgauto-compiler`'s bundled roster — the same executable model knowledge (cliffs, prices, capabilities) that kgauto's prompt compiler runs in production for its consumer apps. This package is a real dependency on it, not a copy: the check and the compiler cannot drift apart.

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import {
+  startStdio
+} from "./chunk-WJEKN4BL.js";
+
+// src/bin.ts
+startStdio().catch((err) => {
+  console.error("kgauto-check-mcp failed to start:", err);
+  process.exit(1);
+});

package/dist/chunk-WJEKN4BL.js

@@ -0,0 +1,443 @@
+// src/extract.ts
+import { z } from "zod";
+var CallSiteSchema = z.object({
+  /** Agent-chosen stable label, e.g. "api/summarize.ts:42" or "hunt loop". */
+  id: z.string().min(1),
+  /** Model id exactly as configured in the project. */
+  model: z.string().min(1),
+  /** How the model id is selected at this site. */
+  modelSelection: z.enum(["hardcoded", "config", "env", "dynamic"]).optional(),
+  /**
+   * Best-guess intent archetype from kgauto's dialect (ask, classify,
+   * critique, extract, generate, hunt, plan, summarize, transform).
+   * Free-form here; validated softly against the roster's dialect.
+   */
+  archetype: z.string().optional(),
+  /** Typical input size in tokens (estimate is fine; ~4 chars/token). */
+  estInputTokens: z.number().nonnegative().optional(),
+  /** Worst-case input size in tokens, if larger than typical. */
+  maxInputTokens: z.number().nonnegative().optional(),
+  /** Typical output size in tokens. */
+  estOutputTokens: z.number().nonnegative().optional(),
+  /** Number of tool definitions sent with the call. */
+  toolCount: z.number().int().nonnegative().optional(),
+  /** Does the site rely on the model making parallel tool calls? */
+  usesParallelToolCalls: z.boolean().optional(),
+  /** Does the site parse the response as JSON / expect schema output? */
+  expectsStructuredOutput: z.boolean().optional(),
+  streaming: z.boolean().optional(),
+  /** What happens when the call fails. */
+  retry: z.enum(["none", "same-model", "fallback-chain", "unknown"]).optional(),
+  /** Fallback model ids, when retry is 'fallback-chain'. */
+  fallbackModels: z.array(z.string()).optional(),
+  /** Rough call volume, if inferable (cron cadence, traffic, logs). */
+  estCallsPerMonth: z.number().positive().optional(),
+  /** Anything structural the agent thinks matters. Never prompt text. */
+  notes: z.string().max(500).optional()
+});
+var ExtractSchema = z.object({
+  project: z.object({
+    name: z.string().min(1),
+    description: z.string().max(500).optional()
+  }),
+  callSites: z.array(CallSiteSchema).min(1),
+  notes: z.string().max(1e3).optional()
+});
+
+// src/engine.ts
+import {
+  allProfiles,
+  tryGetProfile,
+  resolveModelAlias,
+  isArchetype,
+  LIBRARY_VERSION
+} from "@warmdrift/kgauto-compiler";
+var DESTINATION_SENTENCE = "This check ran locally against kgauto\u2019s bundled model catalog. Nothing was uploaded; no rows were written anywhere.";
+var defaultResolve = (id) => {
+  const canonical = resolveModelAlias(id);
+  return { canonical, profile: tryGetProfile(id) };
+};
+function perCallCostUsd(p, inTok, outTok) {
+  return inTok / 1e6 * p.costInputPer1m + outTok / 1e6 * p.costOutputPer1m;
+}
+function runCheck(extract, opts = {}) {
+  const resolve = opts.resolve ?? defaultResolve;
+  const roster = opts.roster ?? allProfiles;
+  const findings = [];
+  let n = 0;
+  const add = (f) => {
+    findings.push({ id: `F${++n}`, ...f });
+  };
+  const unknownModels = /* @__PURE__ */ new Set();
+  for (const site of extract.callSites) {
+    const { canonical, profile } = resolve(site.model);
+    const at = [site.id];
+    if (canonical !== site.model) {
+      add({
+        severity: "yellow",
+        confidence: "certain",
+        title: `\`${site.model}\` is a provider compat alias for \`${canonical}\``,
+        detail: `The provider silently serves a different model than the id you configured. Aliases hide capability and price drift \u2014 the served model's context window and prices can differ by 10\u201350\xD7 from what the alias name suggests, with no error.`,
+        basis: "kgauto alias table (verified against provider docs)",
+        callSites: at
+      });
+    }
+    if (!profile) {
+      unknownModels.add(site.model);
+      add({
+        severity: "info",
+        confidence: "certain",
+        title: `\`${site.model}\` is not in kgauto's verified catalog`,
+        detail: `kgauto has no measured evidence for this model and will not fabricate a verdict on it. Checks below skip this site. (If it's a new release, the catalog gains models through doc-verified onboarding, never from training-data guesses.)`,
+        basis: "catalog lookup",
+        callSites: at
+      });
+      continue;
+    }
+    if (profile.status === "legacy") {
+      add({
+        severity: "yellow",
+        confidence: "certain",
+        title: `\`${canonical}\` is a legacy model`,
+        detail: `The provider lists it as superseded. Legacy models are the deprecation-risk tier: they can start 404ing for whole account cohorts with no code change on your side. A current-generation successor exists in the same family.`,
+        basis: `catalog status: legacy${profile.verifiedAgainstDocs ? ` (verified ${profile.verifiedAgainstDocs})` : ""}`,
+        callSites: at
+      });
+    } else if (profile.status === "preview") {
+      add({
+        severity: "info",
+        confidence: "certain",
+        title: `\`${canonical}\` is a preview model`,
+        detail: `Preview pricing and limits are not yet doc-verified; both can change at GA.`,
+        basis: "catalog status: preview",
+        callSites: at
+      });
+    }
+    const worstIn = site.maxInputTokens ?? site.estInputTokens;
+    if (worstIn !== void 0 && worstIn > profile.maxContextTokens) {
+      add({
+        severity: "red",
+        confidence: site.maxInputTokens !== void 0 ? "certain" : "likely",
+        title: `input can exceed \`${canonical}\`'s context window`,
+        detail: `Your ${site.maxInputTokens !== void 0 ? "worst-case" : "typical"} input estimate (${worstIn.toLocaleString()} tokens) exceeds the model's ${profile.maxContextTokens.toLocaleString()}-token window. Those calls fail outright or silently truncate, depending on the provider.`,
+        basis: `your estimate vs catalog maxContextTokens=${profile.maxContextTokens}`,
+        callSites: at
+      });
+    }
+    if (site.estOutputTokens !== void 0 && site.estOutputTokens > profile.maxOutputTokens) {
+      add({
+        severity: "red",
+        confidence: "likely",
+        title: `expected output exceeds \`${canonical}\`'s output cap`,
+        detail: `You expect ~${site.estOutputTokens.toLocaleString()} output tokens; the model caps at ${profile.maxOutputTokens.toLocaleString()}. Responses will be cut mid-generation \u2014 on JSON output this is the classic unparseable-tail failure.`,
+        basis: `your estimate vs catalog maxOutputTokens=${profile.maxOutputTokens}`,
+        callSites: at
+      });
+    }
+    if (site.toolCount !== void 0 && site.toolCount > profile.maxTools) {
+      add({
+        severity: "red",
+        confidence: "certain",
+        title: `${site.toolCount} tools exceeds \`${canonical}\`'s ceiling of ${profile.maxTools}`,
+        detail: `Calls with more tool definitions than the model supports are rejected or degrade hard.`,
+        basis: `extract toolCount vs catalog maxTools=${profile.maxTools}`,
+        callSites: at
+      });
+    }
+    if (site.usesParallelToolCalls && !profile.parallelToolCalls) {
+      add({
+        severity: "red",
+        confidence: "certain",
+        title: `\`${canonical}\` does not make parallel tool calls`,
+        detail: `This site relies on parallel tool use, but the model calls tools sequentially \u2014 measured at roughly 10\xD7 fewer operations per step on agentic workloads. The work still "succeeds", just slowly and shallowly, which is why this rarely shows up as an error.`,
+        basis: "catalog parallelToolCalls=false (measured, not vendor-claimed)",
+        callSites: at
+      });
+    }
+    if (site.expectsStructuredOutput && profile.structuredOutput === "none") {
+      add({
+        severity: "red",
+        confidence: "certain",
+        title: `\`${canonical}\` has no structured-output support, but this site parses JSON`,
+        detail: `Output-shape failures here land on your parser as intermittent exceptions. Models with native or grammar-constrained output move that failure from runtime to the request.`,
+        basis: "catalog structuredOutput=none",
+        callSites: at
+      });
+    }
+    const archetype = site.archetype && isArchetype(site.archetype) ? site.archetype : void 0;
+    for (const cliff of profile.cliffs) {
+      if (cliff.whenIntent && cliff.whenIntent !== archetype) continue;
+      const metricValue = cliff.metric === "input_tokens" ? worstIn : cliff.metric === "tool_count" ? site.toolCount : void 0;
+      if (metricValue === void 0 || metricValue < cliff.threshold) continue;
+      add({
+        severity: "yellow",
+        confidence: "likely",
+        title: `\`${canonical}\` has a known ${cliff.metric.replaceAll("_", " ")} cliff at ${cliff.threshold.toLocaleString()} \u2014 this site crosses it`,
+        detail: `Above this threshold${cliff.whenIntent ? ` on ${cliff.whenIntent} work` : ""}, quality degrades in a measured, repeatable way (compiler action when routed through kgauto: ${cliff.action.replaceAll("_", " ")}). Your estimate of ${metricValue.toLocaleString()} sits over the line.`,
+        basis: `catalog cliff rule vs your estimate; the same rule the kgauto compiler executes`,
+        callSites: at
+      });
+    }
+    if (site.retry === "none") {
+      add({
+        severity: "yellow",
+        confidence: "certain",
+        title: `no fallback path \u2014 a single ${profile.provider} incident takes this surface to raw errors`,
+        detail: `Provider outages are routine and undramatic: billing exhaustion, quota, silent deprecations. With no cross-provider fallback, every one of them reaches your users directly.`,
+        basis: "extract retry=none",
+        callSites: at
+      });
+    }
+    if (site.estInputTokens !== void 0 && site.estOutputTokens !== void 0 && site.estInputTokens + site.estOutputTokens > 0) {
+      const perCall = perCallCostUsd(profile, site.estInputTokens, site.estOutputTokens);
+      const monthly = site.estCallsPerMonth !== void 0 ? perCall * site.estCallsPerMonth : void 0;
+      const inputShare = site.estInputTokens / (site.estInputTokens + site.estOutputTokens);
+      add({
+        severity: "info",
+        confidence: "likely",
+        title: `~$${perCall.toFixed(4)}/call on \`${canonical}\`${monthly !== void 0 ? ` (~$${monthly.toFixed(2)}/month at your volume)` : ""}`,
+        detail: `From your token estimates and doc-verified prices ($${profile.costInputPer1m}/M in, $${profile.costOutputPer1m}/M out${profile.verifiedAgainstDocs ? `, verified ${profile.verifiedAgainstDocs}` : ""}).`,
+        basis: "arithmetic on your estimates \xD7 verified catalog prices",
+        callSites: at
+      });
+      if (inputShare > 0.85) {
+        add({
+          severity: "yellow",
+          confidence: "likely",
+          title: `${Math.round(inputShare * 100)}% of this site's tokens are input`,
+          detail: `Above ~85% input share, spend is dominated by context rather than answers \u2014 the single strongest signal of a leaking prompt. What's actually IN that context, and how much of it each call needed, is measurable, not guessable.`,
+          basis: "your token estimates; the >85% threshold is a measured portfolio heuristic",
+          callSites: at
+        });
+      }
+      if (archetype) {
+        const cheaper = roster().filter(
+          (p) => p.status === "current" && p.id !== canonical && perCallCostUsd(p, site.estInputTokens, site.estOutputTokens) < perCall * 0.5
+        ).sort(
+          (a, b) => perCallCostUsd(a, site.estInputTokens, site.estOutputTokens) - perCallCostUsd(b, site.estInputTokens, site.estOutputTokens)
+        );
+        const cheapest = cheaper[0];
+        if (cheapest) {
+          add({
+            severity: "info",
+            confidence: "measurable-only",
+            title: `${cheaper.length} current model(s) price under half of \`${canonical}\` on ${archetype} work`,
+            detail: `Cheapest: \`${cheapest.id}\` at ~$${perCallCostUsd(cheapest, site.estInputTokens, site.estOutputTokens).toFixed(4)}/call. The price is arithmetic; whether any of them holds YOUR quality bar on ${archetype} work is exactly what a one-day observe run plus kgauto's judged eval measures. kgauto never promotes a model on price alone.`,
+            basis: "verified catalog prices; quality deliberately unclaimed",
+            callSites: at
+          });
+        }
+      }
+    }
+  }
+  add({
+    severity: "info",
+    confidence: "measurable-only",
+    title: "what a code read cannot tell you (and a one-day observe run can)",
+    detail: `Your actual failure rate per model (walkaway failures look like green health checks); your actual input-waste ratio per call; which call sites dominate spend; whether a cheaper model holds quality on your real traffic. These need one day of observed calls \u2014 observe-only, your keys, no routing changes.`,
+    basis: "the honest limit of static analysis",
+    callSites: extract.callSites.map((s) => s.id)
+  });
+  const merged = [];
+  const byKey = /* @__PURE__ */ new Map();
+  for (const f of findings) {
+    const key = `${f.severity}|${f.confidence}|${f.title}`;
+    const existing = byKey.get(key);
+    if (existing) {
+      for (const cs of f.callSites) {
+        if (!existing.callSites.includes(cs)) existing.callSites.push(cs);
+      }
+    } else {
+      const copy = { ...f, callSites: [...f.callSites] };
+      byKey.set(key, copy);
+      merged.push(copy);
+    }
+  }
+  return {
+    findings: merged,
+    card: renderCard(extract, merged, unknownModels),
+    catalogVersion: LIBRARY_VERSION
+  };
+}
+var TIER_ORDER = ["certain", "likely", "measurable-only"];
+var TIER_HEADING = {
+  certain: "Certain \u2014 read from your code and kgauto\u2019s verified catalog",
+  likely: "Likely \u2014 priced from your estimates",
+  "measurable-only": "Only measurable \u2014 what the observe day answers"
+};
+var SEV_MARK = { red: "\u{1F534}", yellow: "\u{1F7E1}", info: "\u2139\uFE0F" };
+function renderCard(extract, findings, unknownModels = /* @__PURE__ */ new Set()) {
+  const lines = [];
+  lines.push(`# kgauto check \u2014 ${extract.project.name}`);
+  lines.push("");
+  const models = [...new Set(extract.callSites.map((s) => s.model))];
+  lines.push(
+    `${extract.callSites.length} AI call site(s), ${models.length} model(s): ${models.map((m) => `\`${m}\``).join(", ")}` + (unknownModels.size > 0 ? ` (${unknownModels.size} unknown to the catalog)` : "")
+  );
+  for (const tier of TIER_ORDER) {
+    const group = findings.filter((f) => f.confidence === tier);
+    if (group.length === 0) continue;
+    lines.push("");
+    lines.push(`## ${TIER_HEADING[tier]}`);
+    lines.push("");
+    for (const f of group) {
+      lines.push(`- ${SEV_MARK[f.severity]} **${f.title}** \u2014 ${f.detail}`);
+      lines.push(`  <sub>${f.callSites.join(", ")} \xB7 basis: ${f.basis}</sub>`);
+    }
+  }
+  lines.push("");
+  lines.push("---");
+  lines.push(`*${DESTINATION_SENTENCE}*`);
+  return lines.join("\n");
+}
+
+// src/instructions.ts
+var SERVER_INSTRUCTIONS = `You are talking to kgauto-check, a local, offline checker for AI call surfaces.
+
+Flow: (1) call start_check to get extraction instructions, (2) read THIS project's code yourself and build the extract, (3) call run_check with it, (4) present the returned card to your human verbatim (it is grouped by confidence tier on purpose), (5) if they want measured numbers, call get_observe_day_plan.
+
+Privacy contract, which you should relay to your human: the extract contains identifiers and counts only \u2014 never prompt text, never source code, never secrets. ${DESTINATION_SENTENCE}
+
+get_model_facts answers one-off questions about any model id from the same verified catalog.`;
+var START_CHECK_INSTRUCTIONS = `# kgauto check \u2014 extraction instructions (for you, the agent)
+
+Your job: read this project's code and build an extract of its AI call surface. You have repo access; kgauto does not, by design.
+
+## What to find
+Scan for LLM API usage: provider SDK imports (anthropic, openai, @google/generative-ai / @google/genai, ai-sdk, litellm, langchain, ...), raw HTTPS calls to provider endpoints, and any internal wrapper around them. Each distinct place the project sends a prompt to a model is one call site.
+
+## What to collect per call site (identifiers and counts ONLY)
+- id: a stable label you choose, e.g. "api/summarize.ts:42"
+- model: the model id exactly as configured
+- modelSelection: hardcoded | config | env | dynamic
+- archetype: your best guess at the work's intent \u2014 one of: ask, classify, critique, extract, generate, hunt, plan, summarize, transform
+- estInputTokens / maxInputTokens / estOutputTokens: estimate from the code (what gets concatenated into the prompt; ~4 chars per token). Worst case matters \u2014 find the biggest thing that can flow in.
+- toolCount, usesParallelToolCalls: from the tools array and how results are consumed
+- expectsStructuredOutput: true if the response is JSON.parse'd or schema-validated
+- streaming, retry (none | same-model | fallback-chain | unknown), fallbackModels
+- estCallsPerMonth: only if genuinely inferable (cron cadence, obvious traffic); omit rather than invent
+
+## Privacy contract (relay this to your human)
+Do NOT put prompt text, source code, file contents, or secrets in the extract. Identifiers and counts only. ${DESTINATION_SENTENCE}
+
+## Then
+Call run_check with { extract }. Present the returned card verbatim \u2014 the confidence tiers (certain / likely / measurable-only) are the point: they tell your human exactly how much to trust each line, and the measurable-only section is what a one-day observe run would answer.
+
+## Honesty rules you inherit while presenting
+- Do not soften "certain" findings or upgrade "likely" ones.
+- If a model was unknown to the catalog, say so \u2014 kgauto refuses to fabricate verdicts, and so should you.
+- Estimates you made are estimates: if a finding hinges on your token guess, say it can be firmed up by measuring.`;
+
+// src/observe-plan.ts
+var OBSERVE_DAY_PLAN = `# The one-day observe run (for you, the agent \u2014 decision stays with your human)
+
+## What it is
+One day of your project's normal traffic, observed. No routing changes: every call still goes to exactly the model your code chooses today. The observation records, per call: model, token counts in/out, cost at verified prices, latency, success/failure with a classified error code, and per-attempt rows when retries happen. Identifiers and counts \u2014 prompt text is never required.
+
+## What it answers (the measurable-only tier of your check card)
+- actual failure rate per model \u2014 including walkaway failures that green health checks miss
+- actual input-waste ratio per call site (the >85% input-share signal, measured instead of estimated)
+- which call sites dominate spend
+- the evidence base for whether a cheaper model could hold quality here (kgauto's judged eval runs on real captured cases, never on price alone)
+
+## The two honesty requirements (non-negotiable, relay both)
+1. **Destination, named before anything runs.** Your human gets one plain sentence stating exactly where outcome rows land and what is in them, BEFORE the first row is written. "Nothing is uploaded" was true of the check because it writes nothing; the observe day writes rows, so it must say where.
+2. **Observation never intervenes.** If your project uses fallback chains, observing must not pin a model and silently disable the chain \u2014 a forced pin is an intervention sold as observation. Rows are recorded per attempt, so the chain's real behaviour is what gets measured.
+
+## How to proceed
+The integration is small (the kgauto compiler's call/record path with your existing keys), but because rows now land somewhere, the wiring starts with that destination sentence and your human's explicit yes. Next step: have your human reply to whoever pointed them at kgauto \u2014 the observe day is set up per-project, together.`;
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z2 } from "zod";
+import { tryGetProfile as tryGetProfile2, resolveModelAlias as resolveModelAlias2, LIBRARY_VERSION as LIBRARY_VERSION2 } from "@warmdrift/kgauto-compiler";
+var CHECK_VERSION = "0.1.0";
+var text = (t) => ({ content: [{ type: "text", text: t }] });
+function buildServer() {
+  const server = new McpServer(
+    { name: "kgauto-check", version: CHECK_VERSION },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
+  server.registerTool(
+    "start_check",
+    {
+      title: "Start a kgauto check",
+      description: "Call this FIRST. Returns extraction instructions: what to read from this project and how to build the extract for run_check. The extract carries identifiers and counts only \u2014 never prompt text, code, or secrets.",
+      inputSchema: {}
+    },
+    async () => text(START_CHECK_INSTRUCTIONS)
+  );
+  server.registerTool(
+    "run_check",
+    {
+      title: "Run the check",
+      description: "Runs the deterministic kgauto check on your extract, fully offline against the bundled verified model catalog. Returns a findings card grouped by confidence tier (certain / likely / measurable-only) \u2014 present it to your human verbatim.",
+      inputSchema: { extract: ExtractSchema }
+    },
+    async ({ extract }) => {
+      const result = runCheck(extract);
+      return text(result.card);
+    }
+  );
+  server.registerTool(
+    "get_model_facts",
+    {
+      title: "Model facts",
+      description: "What kgauto's verified catalog knows about one model id: lifecycle status, doc-verified prices and limits, capability flags, known quality cliffs. Honest miss when the model is unknown \u2014 no fabricated verdicts.",
+      inputSchema: { model: z2.string().min(1) }
+    },
+    async ({ model }) => {
+      const canonical = resolveModelAlias2(model);
+      const p = tryGetProfile2(model);
+      if (!p) {
+        return text(
+          `\`${model}\` is not in kgauto's verified catalog (lib ${LIBRARY_VERSION2}). No measured evidence exists for it here, and kgauto does not fabricate verdicts. New models enter the catalog through doc-verified onboarding.`
+        );
+      }
+      const lines = [
+        `# ${canonical}${canonical !== model ? ` (you asked for \`${model}\`, a provider alias)` : ""}`,
+        "",
+        `- provider: ${p.provider} \xB7 status: **${p.status}**${p.verifiedAgainstDocs ? ` \xB7 capability data verified against provider docs ${p.verifiedAgainstDocs}` : ""}`,
+        `- price: $${p.costInputPer1m}/M input \xB7 $${p.costOutputPer1m}/M output`,
+        `- limits: ${p.maxContextTokens.toLocaleString()} context \xB7 ${p.maxOutputTokens.toLocaleString()} max output \xB7 ${p.maxTools} tools`,
+        `- capabilities: parallel tool calls ${p.parallelToolCalls ? "yes" : "NO (sequential \u2014 ~10\xD7 fewer ops/step on agentic work)"} \xB7 structured output: ${p.structuredOutput} \xB7 streaming: ${p.streaming ? "yes" : "no"}`,
+        p.cliffs.length > 0 ? `- known cliffs (executable in the kgauto compiler):
+${p.cliffs.map(
+          (c) => `  - ${c.metric.replaceAll("_", " ")} \u2265 ${c.threshold.toLocaleString()}${c.whenIntent ? ` on ${c.whenIntent}` : ""} \u2192 ${c.action.replaceAll("_", " ")}`
+        ).join("\n")}` : "- known cliffs: none recorded",
+        p.notes ? `- notes: ${p.notes}` : "",
+        "",
+        `_Catalog: @warmdrift/kgauto-compiler ${LIBRARY_VERSION2}, bundled locally \u2014 this lookup made no network call._`
+      ].filter(Boolean);
+      return text(lines.join("\n"));
+    }
+  );
+  server.registerTool(
+    "get_observe_day_plan",
+    {
+      title: "The one-day observe run",
+      description: "Rung 2: what a one-day, observe-only run on this project's real traffic would measure, and the two honesty requirements any setup must carry (named row destination; observation never intervenes). Ends in a human decision by design.",
+      inputSchema: {}
+    },
+    async () => text(OBSERVE_DAY_PLAN)
+  );
+  return server;
+}
+async function startStdio() {
+  const server = buildServer();
+  await server.connect(new StdioServerTransport());
+}
+
+export {
+  CallSiteSchema,
+  ExtractSchema,
+  DESTINATION_SENTENCE,
+  runCheck,
+  renderCard,
+  SERVER_INSTRUCTIONS,
+  START_CHECK_INSTRUCTIONS,
+  OBSERVE_DAY_PLAN,
+  buildServer,
+  startStdio
+};

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+import { ModelProfile } from '@warmdrift/kgauto-compiler';
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * The extract contract — what a consumer's coding agent collects from the
+ * project it is checking. IDENTIFIERS AND COUNTS ONLY, by design: no prompt
+ * text, no source code, no secrets ever enter the extract. The agent reads
+ * the repo (it already has access); kgauto reads nothing.
+ */
+
+declare const CallSiteSchema: z.ZodObject<{
+    /** Agent-chosen stable label, e.g. "api/summarize.ts:42" or "hunt loop". */
+    id: z.ZodString;
+    /** Model id exactly as configured in the project. */
+    model: z.ZodString;
+    /** How the model id is selected at this site. */
+    modelSelection: z.ZodOptional<z.ZodEnum<["hardcoded", "config", "env", "dynamic"]>>;
+    /**
+     * Best-guess intent archetype from kgauto's dialect (ask, classify,
+     * critique, extract, generate, hunt, plan, summarize, transform).
+     * Free-form here; validated softly against the roster's dialect.
+     */
+    archetype: z.ZodOptional<z.ZodString>;
+    /** Typical input size in tokens (estimate is fine; ~4 chars/token). */
+    estInputTokens: z.ZodOptional<z.ZodNumber>;
+    /** Worst-case input size in tokens, if larger than typical. */
+    maxInputTokens: z.ZodOptional<z.ZodNumber>;
+    /** Typical output size in tokens. */
+    estOutputTokens: z.ZodOptional<z.ZodNumber>;
+    /** Number of tool definitions sent with the call. */
+    toolCount: z.ZodOptional<z.ZodNumber>;
+    /** Does the site rely on the model making parallel tool calls? */
+    usesParallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+    /** Does the site parse the response as JSON / expect schema output? */
+    expectsStructuredOutput: z.ZodOptional<z.ZodBoolean>;
+    streaming: z.ZodOptional<z.ZodBoolean>;
+    /** What happens when the call fails. */
+    retry: z.ZodOptional<z.ZodEnum<["none", "same-model", "fallback-chain", "unknown"]>>;
+    /** Fallback model ids, when retry is 'fallback-chain'. */
+    fallbackModels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Rough call volume, if inferable (cron cadence, traffic, logs). */
+    estCallsPerMonth: z.ZodOptional<z.ZodNumber>;
+    /** Anything structural the agent thinks matters. Never prompt text. */
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    model: string;
+    modelSelection?: "hardcoded" | "config" | "env" | "dynamic" | undefined;
+    archetype?: string | undefined;
+    estInputTokens?: number | undefined;
+    maxInputTokens?: number | undefined;
+    estOutputTokens?: number | undefined;
+    toolCount?: number | undefined;
+    usesParallelToolCalls?: boolean | undefined;
+    expectsStructuredOutput?: boolean | undefined;
+    streaming?: boolean | undefined;
+    retry?: "none" | "same-model" | "fallback-chain" | "unknown" | undefined;
+    fallbackModels?: string[] | undefined;
+    estCallsPerMonth?: number | undefined;
+    notes?: string | undefined;
+}, {
+    id: string;
+    model: string;
+    modelSelection?: "hardcoded" | "config" | "env" | "dynamic" | undefined;
+    archetype?: string | undefined;
+    estInputTokens?: number | undefined;
+    maxInputTokens?: number | undefined;
+    estOutputTokens?: number | undefined;
+    toolCount?: number | undefined;
+    usesParallelToolCalls?: boolean | undefined;
+    expectsStructuredOutput?: boolean | undefined;
+    streaming?: boolean | undefined;
+    retry?: "none" | "same-model" | "fallback-chain" | "unknown" | undefined;
+    fallbackModels?: string[] | undefined;
+    estCallsPerMonth?: number | undefined;
+    notes?: string | undefined;
+}>;
+declare const ExtractSchema: z.ZodObject<{
+    project: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description?: string | undefined;
+    }, {
+        name: string;
+        description?: string | undefined;
+    }>;
+    callSites: z.ZodArray<z.ZodObject<{
+        /** Agent-chosen stable label, e.g. "api/summarize.ts:42" or "hunt loop". */
+        id: z.ZodString;
+        /** Model id exactly as configured in the project. */
+        model: z.ZodString;
+        /** How the model id is selected at this site. */
+        modelSelection: z.ZodOptional<z.ZodEnum<["hardcoded", "config", "env", "dynamic"]>>;
+        /**
+         * Best-guess intent archetype from kgauto's dialect (ask, classify,
+         * critique, extract, generate, hunt, plan, summarize, transform).
+         * Free-form here; validated softly against the roster's dialect.
+         */
+        archetype: z.ZodOptional<z.ZodString>;
+        /** Typical input size in tokens (estimate is fine; ~4 chars/token). */
+        estInputTokens: z.ZodOptional<z.ZodNumber>;
+        /** Worst-case input size in tokens, if larger than typical. */
+        maxInputTokens: z.ZodOptional<z.ZodNumber>;
+        /** Typical output size in tokens. */
+        estOutputTokens: z.ZodOptional<z.ZodNumber>;
+        /** Number of tool definitions sent with the call. */
+        toolCount: z.ZodOptional<z.ZodNumber>;
+        /** Does the site rely on the model making parallel tool calls? */
+        usesParallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+        /** Does the site parse the response as JSON / expect schema output? */
+        expectsStructuredOutput: z.ZodOptional<z.ZodBoolean>;
+        streaming: z.ZodOptional<z.ZodBoolean>;
+        /** What happens when the call fails. */
+        retry: z.ZodOptional<z.ZodEnum<["none", "same-model", "fallback-chain", "unknown"]>>;
+        /** Fallback model ids, when retry is 'fallback-chain'. */
+        fallbackModels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** Rough call volume, if inferable (cron cadence, traffic, logs). */
+        estCallsPerMonth: z.ZodOptional<z.ZodNumber>;
+        /** Anything structural the agent thinks matters. Never prompt text. */
+        notes: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        model: string;
+        modelSelection?: "hardcoded" | "config" | "env" | "dynamic" | undefined;
+        archetype?: string | undefined;
+        estInputTokens?: number | undefined;
+        maxInputTokens?: number | undefined;
+        estOutputTokens?: number | undefined;
+        toolCount?: number | undefined;
+        usesParallelToolCalls?: boolean | undefined;
+        expectsStructuredOutput?: boolean | undefined;
+        streaming?: boolean | undefined;
+        retry?: "none" | "same-model" | "fallback-chain" | "unknown" | undefined;
+        fallbackModels?: string[] | undefined;
+        estCallsPerMonth?: number | undefined;
+        notes?: string | undefined;
+    }, {
+        id: string;
+        model: string;
+        modelSelection?: "hardcoded" | "config" | "env" | "dynamic" | undefined;
+        archetype?: string | undefined;
+        estInputTokens?: number | undefined;
+        maxInputTokens?: number | undefined;
+        estOutputTokens?: number | undefined;
+        toolCount?: number | undefined;
+        usesParallelToolCalls?: boolean | undefined;
+        expectsStructuredOutput?: boolean | undefined;
+        streaming?: boolean | undefined;
+        retry?: "none" | "same-model" | "fallback-chain" | "unknown" | undefined;
+        fallbackModels?: string[] | undefined;
+        estCallsPerMonth?: number | undefined;
+        notes?: string | undefined;
+    }>, "many">;
+    notes: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    project: {
+        name: string;
+        description?: string | undefined;
+    };
+    callSites: {
+        id: string;
+        model: string;
+        modelSelection?: "hardcoded" | "config" | "env" | "dynamic" | undefined;
+        archetype?: string | undefined;
+        estInputTokens?: number | undefined;
+        maxInputTokens?: number | undefined;
+        estOutputTokens?: number | undefined;
+        toolCount?: number | undefined;
+        usesParallelToolCalls?: boolean | undefined;
+        expectsStructuredOutput?: boolean | undefined;
+        streaming?: boolean | undefined;
+        retry?: "none" | "same-model" | "fallback-chain" | "unknown" | undefined;
+        fallbackModels?: string[] | undefined;
+        estCallsPerMonth?: number | undefined;
+        notes?: string | undefined;
+    }[];
+    notes?: string | undefined;
+}, {
+    project: {
+        name: string;
+        description?: string | undefined;
+    };
+    callSites: {
+        id: string;
+        model: string;
+        modelSelection?: "hardcoded" | "config" | "env" | "dynamic" | undefined;
+        archetype?: string | undefined;
+        estInputTokens?: number | undefined;
+        maxInputTokens?: number | undefined;
+        estOutputTokens?: number | undefined;
+        toolCount?: number | undefined;
+        usesParallelToolCalls?: boolean | undefined;
+        expectsStructuredOutput?: boolean | undefined;
+        streaming?: boolean | undefined;
+        retry?: "none" | "same-model" | "fallback-chain" | "unknown" | undefined;
+        fallbackModels?: string[] | undefined;
+        estCallsPerMonth?: number | undefined;
+        notes?: string | undefined;
+    }[];
+    notes?: string | undefined;
+}>;
+type CallSite = z.infer<typeof CallSiteSchema>;
+type Extract = z.infer<typeof ExtractSchema>;
+
+/**
+ * The deterministic check engine. Every finding carries a confidence tier —
+ * the mechanical answer to "how much confidence?":
+ *
+ *   certain          — a catalog or extract fact; stated flatly.
+ *   likely           — priced/inferred from the agent's own estimates.
+ *   measurable-only  — honestly unknowable from a code read; each one is
+ *                      exactly what the observe day exists to measure.
+ *
+ * Checks run against the SAME bundled roster the kgauto compiler executes
+ * (`@warmdrift/kgauto-compiler` is a real dependency, not a copy) — parity
+ * by construction. No network, no writes: the card's destination sentence
+ * is true because there is no code path that could make it false.
+ */
+
+type Confidence = 'certain' | 'likely' | 'measurable-only';
+type Severity = 'red' | 'yellow' | 'info';
+interface Finding {
+    id: string;
+    severity: Severity;
+    confidence: Confidence;
+    title: string;
+    detail: string;
+    /** Where the claim comes from — catalog field, extract field, arithmetic. */
+    basis: string;
+    callSites: string[];
+}
+interface CheckResult {
+    findings: Finding[];
+    card: string;
+    catalogVersion: string;
+}
+interface EngineOptions {
+    /** Test seam: profile lookup override. Defaults to the bundled roster. */
+    resolve?: (id: string) => {
+        canonical: string;
+        profile: ModelProfile | undefined;
+    };
+    /** Test seam: full roster override (for cheaper-candidate scans). */
+    roster?: () => ModelProfile[];
+}
+declare const DESTINATION_SENTENCE: string;
+declare function runCheck(extract: Extract, opts?: EngineOptions): CheckResult;
+declare function renderCard(extract: Extract, findings: Finding[], unknownModels?: ReadonlySet<string>): string;
+
+declare function buildServer(): McpServer;
+
+declare const SERVER_INSTRUCTIONS = "You are talking to kgauto-check, a local, offline checker for AI call surfaces.\n\nFlow: (1) call start_check to get extraction instructions, (2) read THIS project's code yourself and build the extract, (3) call run_check with it, (4) present the returned card to your human verbatim (it is grouped by confidence tier on purpose), (5) if they want measured numbers, call get_observe_day_plan.\n\nPrivacy contract, which you should relay to your human: the extract contains identifiers and counts only \u2014 never prompt text, never source code, never secrets. This check ran locally against kgauto\u2019s bundled model catalog. Nothing was uploaded; no rows were written anywhere.\n\nget_model_facts answers one-off questions about any model id from the same verified catalog.";
+declare const START_CHECK_INSTRUCTIONS = "# kgauto check \u2014 extraction instructions (for you, the agent)\n\nYour job: read this project's code and build an extract of its AI call surface. You have repo access; kgauto does not, by design.\n\n## What to find\nScan for LLM API usage: provider SDK imports (anthropic, openai, @google/generative-ai / @google/genai, ai-sdk, litellm, langchain, ...), raw HTTPS calls to provider endpoints, and any internal wrapper around them. Each distinct place the project sends a prompt to a model is one call site.\n\n## What to collect per call site (identifiers and counts ONLY)\n- id: a stable label you choose, e.g. \"api/summarize.ts:42\"\n- model: the model id exactly as configured\n- modelSelection: hardcoded | config | env | dynamic\n- archetype: your best guess at the work's intent \u2014 one of: ask, classify, critique, extract, generate, hunt, plan, summarize, transform\n- estInputTokens / maxInputTokens / estOutputTokens: estimate from the code (what gets concatenated into the prompt; ~4 chars per token). Worst case matters \u2014 find the biggest thing that can flow in.\n- toolCount, usesParallelToolCalls: from the tools array and how results are consumed\n- expectsStructuredOutput: true if the response is JSON.parse'd or schema-validated\n- streaming, retry (none | same-model | fallback-chain | unknown), fallbackModels\n- estCallsPerMonth: only if genuinely inferable (cron cadence, obvious traffic); omit rather than invent\n\n## Privacy contract (relay this to your human)\nDo NOT put prompt text, source code, file contents, or secrets in the extract. Identifiers and counts only. This check ran locally against kgauto\u2019s bundled model catalog. Nothing was uploaded; no rows were written anywhere.\n\n## Then\nCall run_check with { extract }. Present the returned card verbatim \u2014 the confidence tiers (certain / likely / measurable-only) are the point: they tell your human exactly how much to trust each line, and the measurable-only section is what a one-day observe run would answer.\n\n## Honesty rules you inherit while presenting\n- Do not soften \"certain\" findings or upgrade \"likely\" ones.\n- If a model was unknown to the catalog, say so \u2014 kgauto refuses to fabricate verdicts, and so should you.\n- Estimates you made are estimates: if a finding hinges on your token guess, say it can be firmed up by measuring.";
+
+/**
+ * Rung 2 of the ladder: the one-day observe run. v1 of this tool hands the
+ * agent the PLAN — what the day is, what it answers, and the two honesty
+ * requirements any implementation must carry (both came out of cold-read
+ * testing with simulated skeptical founders). The concrete wiring involves
+ * consent about where rows land, so it ends in a human decision by design.
+ */
+declare const OBSERVE_DAY_PLAN = "# The one-day observe run (for you, the agent \u2014 decision stays with your human)\n\n## What it is\nOne day of your project's normal traffic, observed. No routing changes: every call still goes to exactly the model your code chooses today. The observation records, per call: model, token counts in/out, cost at verified prices, latency, success/failure with a classified error code, and per-attempt rows when retries happen. Identifiers and counts \u2014 prompt text is never required.\n\n## What it answers (the measurable-only tier of your check card)\n- actual failure rate per model \u2014 including walkaway failures that green health checks miss\n- actual input-waste ratio per call site (the >85% input-share signal, measured instead of estimated)\n- which call sites dominate spend\n- the evidence base for whether a cheaper model could hold quality here (kgauto's judged eval runs on real captured cases, never on price alone)\n\n## The two honesty requirements (non-negotiable, relay both)\n1. **Destination, named before anything runs.** Your human gets one plain sentence stating exactly where outcome rows land and what is in them, BEFORE the first row is written. \"Nothing is uploaded\" was true of the check because it writes nothing; the observe day writes rows, so it must say where.\n2. **Observation never intervenes.** If your project uses fallback chains, observing must not pin a model and silently disable the chain \u2014 a forced pin is an intervention sold as observation. Rows are recorded per attempt, so the chain's real behaviour is what gets measured.\n\n## How to proceed\nThe integration is small (the kgauto compiler's call/record path with your existing keys), but because rows now land somewhere, the wiring starts with that destination sentence and your human's explicit yes. Next step: have your human reply to whoever pointed them at kgauto \u2014 the observe day is set up per-project, together.";
+
+export { type CallSite, CallSiteSchema, type CheckResult, type Confidence, DESTINATION_SENTENCE, type EngineOptions, type Extract, ExtractSchema, type Finding, OBSERVE_DAY_PLAN, SERVER_INSTRUCTIONS, START_CHECK_INSTRUCTIONS, type Severity, buildServer, renderCard, runCheck };

package/dist/index.js

@@ -0,0 +1,22 @@
+import {
+  CallSiteSchema,
+  DESTINATION_SENTENCE,
+  ExtractSchema,
+  OBSERVE_DAY_PLAN,
+  SERVER_INSTRUCTIONS,
+  START_CHECK_INSTRUCTIONS,
+  buildServer,
+  renderCard,
+  runCheck
+} from "./chunk-WJEKN4BL.js";
+export {
+  CallSiteSchema,
+  DESTINATION_SENTENCE,
+  ExtractSchema,
+  OBSERVE_DAY_PLAN,
+  SERVER_INSTRUCTIONS,
+  START_CHECK_INSTRUCTIONS,
+  buildServer,
+  renderCard,
+  runCheck
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@warmdrift/kgauto-check",
+  "version": "0.1.0",
+  "description": "Point your AI at your project — kgauto's local MCP check. Your coding agent extracts your AI surface (identifiers and counts, never code) and this server checks it against kgauto's verified model catalog: statuses, prices, cliffs, capability mismatches, resilience. Runs fully offline; nothing is uploaded, no rows are written anywhere.",
+  "type": "module",
+  "bin": {
+    "kgauto-check-mcp": "dist/bin.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/bin.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "smoke": "npm run build && node scripts/smoke-stdio.mjs",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "kgauto",
+    "llm",
+    "model-catalog",
+    "ai-cost",
+    "prompt-compiler"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stue/kgauto.git",
+    "directory": "check-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@warmdrift/kgauto-compiler": "^2.0.0-alpha.88",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}