wyrm-mcp 7.3.2 → 7.3.3

package/dist/handlers/intelligence.js

@@ -1,126 +1,681 @@
-import{TOOL_ANNOTATIONS as b}from"../tool-annotations.js";import{currentReadCacheKey as I}from"./boundary.js";import{autoConfigureAll as B,findWyrmServerPath as U,getDefaultDbPath as N,getStatusSummary as V,removeFromAll as W}from"../autoconfig.js";import{daemonOr as K}from"../daemon-writer.js";import{renderFailureStats as q}from"../failure-patterns.js";import{computeStaleness as H}from"../intelligence.js";import{logger as z}from"../logger.js";import{runMaintenance as G}from"../maintenance.js";import{cache as $}from"../performance.js";import{createProvider as Y}from"../providers/embedding-provider.js";import{reindexProjects as Q}from"../reindex.js";import{requireString as Z}from"../validate.js";import{createVectorStore as J}from"../vectors.js";const ue=[{name:"wyrm_feedback",description:"Record whether a recalled knowledge artifact was useful. Adjusts confidence over time \u2014 successful reuse boosts it, failure lowers it. Call after applying a recalled pattern or lesson.",inputSchema:{type:"object",properties:{artifactId:{type:"number",description:"ID of the memory artifact (from wyrm_recall results)"},success:{type:"boolean",description:"Was this artifact helpful for the task?"}},required:["artifactId","success"]},annotations:b.wyrm_feedback,aliases:[],handler:async(u,f)=>{const{memory:d}=f,{artifactId:c,success:i}=u,a=d.get(c);if(!a)return{content:[{type:"text",text:`Artifact #${c} not found.`}],isError:!0};d.recordFeedback(c,i);const t=d.get(c);return{content:[{type:"text",text:`\u{F115D} Feedback recorded ${i?"\u2705":"\u274C"}
-
-- Artifact #${c}: "${a.problem.slice(0,60)}"
-- New confidence: ${(t.confidence*100).toFixed(0)}%
-- Total uses: ${t.reuse_count} (\u2705 ${t.reuse_success_count} / \u274C ${t.reuse_failure_count})`}]}}},{name:"wyrm_context_build",description:"Use to build a compact context brief for the current task under a token budget - relevant patterns, lessons, and truths in one formatted block; max_tokens elides low-score items to recallable stubs.",inputSchema:{type:"object",properties:{projectPath:{type:"string"},task:{type:"string",description:"The current task"},maxItems:{type:"number",description:"Default 10, max 20"},kinds:{type:"array",items:{type:"string"},description:"Artifact kinds (see wyrm_recall)"},minConfidence:{type:"number",description:"Default 0.3"},max_tokens:{type:"number",description:"Token budget; low-score items elide to stubs"},session_id:{type:"number",description:"Already-seen dedup"},strict_budget:{type:"boolean",description:"Also elide truths over budget"}},required:["projectPath","task"]},annotations:b.wyrm_context_build,aliases:[],handler:async(u,f)=>{const{cachedResponse:d,db:c,groundTruths:i,memory:a,runBudgetedContextBuild:t,scaffoldLib:s}=f,o=u||{},r=I(),{projectPath:e,task:n,maxItems:m,kinds:l,minConfidence:p,max_tokens:y,session_id:g,strict_budget:j}=u,h=c.getProject(e);if(!h)return{content:[{type:"text",text:`Project not found: ${e}`}],isError:!0};if(y!=null&&!process.env.WYRM_DISABLE_TOKEN_BUDGET)return t({project:h,task:n,maxTokens:y,sessionId:g,strictBudget:j===!0,kinds:l,minConfidence:p});const x=[],w=i.formatForContext(h.id);w&&x.push(w.slice(0,1200));const v=s.findBest(n,h.id);if(v){const k=s.formatForContext(v);x.push(k.slice(0,1500))}const S=a.buildContextBrief(h.id,n,{maxItems:Math.min(m??10,20),kinds:l,minConfidence:p});if(S.sections.length>0){const k=S.text.slice(0,2e3);x.push(k)}if(x.length===0)return{content:[{type:"text",text:`\u{F115D} **Context Brief**
-
-No relevant memory found for this task yet.
-
-As you work, use \`wyrm_remember\` to store:
-- \u2705 Patterns that work
-- \u26A0\uFE0F Anti-patterns to avoid
-- \u{1F4A1} Heuristics and shortcuts
-- \u{1F9E0} Reasoning traces from complex problems
-
-Future context briefs will become richer over time.`}]};const P=a.getStats(h.id),T=i.getStats(h.id),E=`\u{F115D} **Context Brief** \u2014 "${n}"
-
-`,C=[];w&&C.push(w.slice(0,1200)),v&&C.push(s.formatForContext(v).slice(0,1500));const A=C.length>0?`<!-- cache-stable -->
-${C.join(`
-
----
-
-`)}
-<!-- /cache-stable -->
-
----
-
-`:"",M=S.sections.length>0?S.text.slice(0,2e3):"";let R=`${E}${A}${M}`;R+=`
-
-_Brief: ${T.current} ground truth${T.current!==1?"s":""}, scaffold: ${v?v.scaffold.problem_type:"none"}, ${P.total} memory artifact${P.total!==1?"s":""}.`,S.sourceIds.length>0?R+=` Memory IDs: [${S.sourceIds.join(", ")}] \u2014 use \`wyrm_feedback\` to rate._`:R+="_";try{const{logSavings:k}=await import("../statusline.js"),O=c.getDatabase(),L=O.prepare("SELECT id FROM sessions WHERE project_id = ? ORDER BY created_at DESC LIMIT 1").get(h.id),D=Math.round(A.length/4);D>0&&k(O,"wyrm_context_build","cached_preamble",Math.round(D*.9),L?.id)}catch{}const F=d(R);return r&&$.set(r,F,1e4),F}},{name:"wyrm_truth_set",description:"Use to lock in a confirmed fact or constraint as project ground truth - architecture, conventions, key decisions. Injected first into every brief; re-setting the same category+key supersedes (history kept).",inputSchema:{type:"object",properties:{projectPath:{type:"string"},category:{type:"string",description:"e.g. architecture, conventions"},key:{type:"string",description:"snake_case key"},value:{type:"string",description:"The statement"},rationale:{type:"string",description:"Why this is true"},source:{type:"string",description:"'user'|'derived'|'observed'|'confirmed'"},confidence:{type:"number",description:"0-1 (default 1.0)"},ttl_days:{type:"number",description:"Stale after N days"}},required:["projectPath","category","key","value"]},annotations:b.wyrm_truth_set,aliases:[],handler:async(u,f)=>{const{db:d,groundTruths:c,presence:i}=f,{projectPath:a,category:t,key:s,value:o,rationale:r,source:e,confidence:n,ttl_days:m}=u,l=Z("category",t,{maxLen:200}),p=d.getProject(a);if(!p)return{content:[{type:"text",text:`Project not found: ${a}`}],isError:!0};const y={category:l,key:s,value:o,rationale:r,source:e,confidence:n??1,ttl_days:m},g=await K("truth_set",p.id,y,()=>c.set(p.id,y));return $.invalidate("wyrm_truth_get"),$.invalidate("wyrm_context_build"),{content:[{type:"text",text:`\u{F115D} **Ground Truth Set** \u2705
-
-- **Category:** ${t}
-- **Key:** ${s}
-- **Value:** ${o}${r?`
-- **Rationale:** ${r}`:""}${m?`
-- **TTL:** ${m} days`:""}
-- **ID:** ${g.id}
-
-This truth will be injected at the top of every \`wyrm_context_build\` response for this project.`}]}}},{name:"wyrm_truth_get",description:"Use to read the established facts and ground rules for a codebase - validated truths the AI should treat as baseline, optionally filtered by category.",inputSchema:{type:"object",properties:{projectPath:{type:"string"},category:{type:"string",description:"Category filter"}},required:["projectPath"]},annotations:b.wyrm_truth_get,aliases:[],handler:async(u,f)=>{const{cachedResponse:d,db:c,groundTruths:i}=f,a=I(),{projectPath:t,category:s}=u,o=c.getProject(t);if(!o)return{content:[{type:"text",text:`Project not found: ${t}`}],isError:!0};const r=i.getCurrent(o.id,s);if(r.length===0)return{content:[{type:"text",text:`\u{F115D} **Ground Truths**
-
-${s?`No ground truths in category "${s}" for this project.`:"No ground truths stored yet. Use `wyrm_truth_set` to add validated facts."}`}]};const e=new Map;for(const l of r)e.has(l.category)||e.set(l.category,[]),e.get(l.category).push(l);let n=`\u{F115D} **Ground Truths** \u2014 ${r.length} active
-
-`;for(const[l,p]of e){n+=`### ${l}
-`;for(const y of p){const g=H(y),h=g!==null&&g>.7?"[\u26A0\uFE0F STALE] ":"";n+=`- ${h}**${y.key}:** ${y.value}`,y.confidence<1&&(n+=` _(confidence: ${(y.confidence*100).toFixed(0)}%)_`),y.rationale&&(n+=`
-  _${y.rationale}_`),g!==null&&(n+=`
-  _staleness: ${(g*100).toFixed(0)}% (TTL: ${y.ttl_days}d)_`),n+=`
-`}n+=`
-`}const m=d(n);return a&&$.set(a,m,15e3),m}},{name:"wyrm_scaffold_get",description:"Find the best reasoning scaffold for a task description. Returns the most relevant structured checklist, or null if no match meets the confidence threshold.",inputSchema:{type:"object",properties:{projectPath:{type:"string",description:"Project path (searches project + global)"},task:{type:"string",description:"Task description to match against scaffolds"},minConfidence:{type:"number",description:"Minimum match confidence 0-1 (default: 0.3)"}},required:["task"]},annotations:b.wyrm_scaffold_get,aliases:[],handler:async(u,f)=>{const{cachedResponse:d,db:c,scaffoldLib:i}=f,a=I(),{projectPath:t,task:s,minConfidence:o}=u,r=t?c.getProject(t)?.id??void 0:void 0,e=i.findBest(s,r,o);if(!e)return{content:[{type:"text",text:`\u{F115D} **Reasoning Scaffold**
-
-No scaffold matched for: "${s}"
-
-Use \`wyrm_scaffold_save\` to add scaffolds for this problem type.`}]};const n=i.formatForContext(e),m=d(`\u{F115D} **Reasoning Scaffold Match** (${(e.matchScore*100).toFixed(0)}% confidence)
-
-${n}`);return a&&$.set(a,m,15e3),m}},{name:"wyrm_sync",description:"Sync database with .wyrm folders in all projects",inputSchema:{type:"object",properties:{projectPath:{type:"string",description:"Sync specific project, or all if not specified"},direction:{type:"string",enum:["import","export","both"],description:"Sync direction"}}},annotations:b.wyrm_sync,aliases:[],handler:async(u,f)=>{const{db:d,sync:c}=f,{projectPath:i,direction:a}=u,t=a||"both";let s=0;if(i)d.getProject(i)&&((t==="import"||t==="both")&&c.importFromFolder(i),(t==="export"||t==="both")&&c.exportToFolder(i),s=1);else{const o=d.getAllProjects(1e3);for(const r of o)try{(t==="import"||t==="both")&&c.importFromFolder(r.path),(t==="export"||t==="both")&&c.exportToFolder(r.path),s++}catch{}}return{content:[{type:"text",text:`\u{F115D} Synced ${s} project(s)`}]}}},{name:"wyrm_stats",description:"Use for a health snapshot of the memory database - row counts, vector index coverage, usage.",inputSchema:{type:"object",properties:{view:{type:"string",enum:["failures"],description:"'failures' = prevented-repeat analytics"},projectPath:{type:"string",description:"failures view scope"}}},annotations:b.wyrm_stats,aliases:[],handler:async(u,f)=>{const{WRITE_TOOLS:d,analytics:c,cachedResponse:i,db:a,failures:t,getUsageStats:s,orchestrator:o,vectorStore:r}=f,e=u||{},n=I(),{view:m,projectPath:l}=u;if(m==="failures"){const _=l?a.getProject(l):null,x=t.failureStats({projectId:_?.id??null});return{content:[{type:"text",text:q(x)}],structuredContent:x}}const p=a.getStats(),y=$.stats(),g=s();let j="";if(r){const _=r.getStats(),x=_.byType||{},w=(x.artifact||0)+(x.quest||0)+(x.session||0),v=p.artifacts+p.quests+p.sessions,S=v>0?Math.min(100,w/v*100).toFixed(1):"0";j=`
-**Vectors:**
-- **Provider:** ${_.provider} (${_.model})
-- **Embeddings:** ${_.total} vectors
-- **Coverage:** ${S}% of embeddable content
-- **By Type:** ${Object.entries(_.byType).map(([P,T])=>`${P}: ${T}`).join(", ")}
-`}const h=i(`\u{F115D} **Wyrm Statistics**
-
-- **Projects:** ${p.projects}
-- **Sessions:** ${p.sessions}
-- **Quests:** ${p.quests}
-- **Data Points:** ${p.dataPoints}
-- **Active Tokens:** ~${p.totalTokens.toLocaleString()}
-- **Database Size:** ${p.dbSize}
-`+j+`
-**Cache:** ${y.size} entries | Hit rate: ${g.cacheHitRate}
-**Usage:** ${g.totalCalls} calls | ~${g.tokensSaved.toLocaleString()} tokens saved by cache`);return n&&$.set(n,h,15e3),h}},{name:"wyrm_vector_setup",description:"Configure embedding provider and download models. Supports local, OpenAI, and Ollama.",inputSchema:{type:"object",properties:{provider:{type:"string",enum:["auto","local","openai","ollama","none"],description:"Provider: auto-detect, local hash, OpenAI API, Ollama, or none"},model:{type:"string",description:"Model name (e.g., 'text-embedding-3-small' for OpenAI, 'nomic-embed-text' for Ollama)"},apiKey:{type:"string",description:"OpenAI API key (if using openai provider)"},ollamaUrl:{type:"string",description:"Ollama URL (default: http://localhost:11434)"}}},annotations:b.wyrm_vector_setup,aliases:[],handler:async(u,f)=>{const{db:d,indexingPipeline:c,memory:i,setVectorStore:a,vectorStore:t}=f,{provider:s,model:o,apiKey:r,ollamaUrl:e}=u,n={provider:s||"auto",model:o,apiKey:r,ollamaUrl:e};try{const m=Y(n),l=await m.isReady();if(!l&&n.provider!=="none")return{content:[{type:"text",text:`\u274C **Provider Not Ready**
-
-Couldn't connect to ${m.name}. Check your configuration and try again.`}],isError:!0};const p=J(n,d.getDatabase());a(p),i.setVectorStore(p),c&&c.updateStore(p);const y=p.getStats();return{content:[{type:"text",text:`\u2705 **Vector Setup Complete**
-
-- **Provider:** ${m.name}
-- **Model:** ${m.model}
-- **Dimensions:** ${m.dimensions}
-- **Status:** ${l?"Ready":"Ready (will auto-connect)"}
-
-_Reindex your projects with wyrm_reindex to generate embeddings._`}]}}catch(m){return{content:[{type:"text",text:`\u274C **Vector Setup Failed**
-
-${String(m)}`}],isError:!0}}}},{name:"wyrm_reindex",description:"Rebuild embeddings for a project or all projects. Regenerates vectors for sessions, quests, data, and memory artifacts (the latter power hybrid recall).",inputSchema:{type:"object",properties:{projectPath:{type:"string",description:"Project to reindex, or leave empty for all projects"},dryRun:{type:"boolean",description:"Show what would be indexed without making changes"}}},annotations:b.wyrm_reindex,aliases:[],handler:async(u,f)=>{const{db:d,failures:c,vectorStore:i}=f,{projectPath:a,dryRun:t}=u;if(!i)return{content:[{type:"text",text:`\u274C **Vector Indexing Disabled**
-
-Run wyrm_vector_setup first to enable vector search.`}],isError:!0};let s=[];if(a){const e=d.getProject(a);if(!e)return{content:[{type:"text",text:`\u274C **Project Not Found:** ${a}`}],isError:!0};s=[e.id]}else s=d.getAllProjects(1e3).map(n=>n.id);const{indexed:o,skipped:r}=await Q(d.getDatabase(),i,s,{dryRun:t,onError:(e,n)=>z.error(e,n)});return{content:[{type:"text",text:`\u{F115D} **Reindexing ${t?"(Dry Run)":"Complete"}**
-
-- **Projects:** ${s.length}
-- **Indexed:** ${o}
-- **Skipped:** ${r}
-
-`+(t?"_Run without dryRun to actually index._":"_Vectors are now up to date._")}]}}},{name:"wyrm_maintenance",description:"Use for periodic upkeep of the memory store - archive old sessions, vacuum, prune stale events, sweep run quarantine, rebuild vector embeddings (reindex). Admin-gated, destructive; fleets run it between waves.",inputSchema:{type:"object",properties:{vacuum:{type:"boolean",description:"Reclaim space"},archiveDays:{type:"number",description:"Archive sessions > N days"}}},annotations:b.wyrm_maintenance,aliases:[],handler:async(u,f)=>{const{db:d,failures:c,presence:i,sessionSeen:a}=f,t=u||{},{vacuum:s,archiveDays:o}=u,r=G({db:d,sessionSeen:a(),failures:c,presence:i},{vacuum:s,archiveDays:o});return{content:[{type:"text",text:`\u{F115D} **Maintenance Complete**
-
-`+r.lines.map(n=>`- ${n}
-`).join("")+`
-**New Database Size:** ${r.dbSize}`}]}}},{name:"wyrm_setup",description:"Auto-detect installed AI clients (VS Code, Claude Desktop, Cursor, Windsurf, Zed) and configure Wyrm's MCP server in all of them. Run this to connect Wyrm to a new AI or after switching providers.",inputSchema:{type:"object",properties:{action:{type:"string",enum:["configure","check","remove"],description:"Action: configure (default), check status, or remove from all"},serverPath:{type:"string",description:"Override Wyrm server path (auto-detected if empty)"},dbPath:{type:"string",description:"Override database path (default: ~/.wyrm/wyrm.db)"}}},annotations:b.wyrm_setup,aliases:[],handler:async(u,f)=>{const{action:d,serverPath:c,dbPath:i}=u,a=d||"configure";if(a==="check")return{content:[{type:"text",text:V()}]};if(a==="remove"){const e=W();return{content:[{type:"text",text:`\u{F115D} **Wyrm Removed**
-
-Removed from ${e.filter(l=>l.action==="configured").length} AI client(s):
-`+e.map(l=>`- ${l.client.icon} ${l.client.name}: ${l.message}`).join(`
-`)+`
-
-Run wyrm_setup again to reconnect.`}]}}const t=B({serverPath:c||void 0,dbPath:i||void 0}),s=t.filter(e=>e.action==="configured"||e.action==="updated"),o=t.filter(e=>e.action==="failed");let r=`\u{F115D} **Wyrm Auto-Configure Complete**
-
-`;r+=`Connected to ${s.length} AI client(s):
-`;for(const e of t){const n=e.action==="configured"?"\u2705":e.action==="updated"?"\u{1F504}":e.action==="skipped"?"\u25CB":"\u274C";r+=`- ${n} ${e.client.icon} ${e.client.name}: ${e.message}
-`}return o.length>0&&(r+=`
-\u26A0\uFE0F ${o.length} client(s) failed. Check errors above.`),r+=`
-
-Server: ${U()}
-DB: ${N()}`,r+=`
-
-_Switch AIs anytime \u2014 run wyrm_setup again to reconnect._`,{content:[{type:"text",text:r}]}}},{name:"wyrm_usage",description:"View token usage stats, cache hit rates, and estimated cost savings. Helps monitor and optimize AI credit consumption.",inputSchema:{type:"object",properties:{last:{type:"number",description:"Show stats for last N calls (default: all)"},reset:{type:"boolean",description:"Reset usage counters"}}},annotations:b.wyrm_usage,aliases:[],handler:async(u,f)=>{const{cachedResponse:d,getUsageStats:c,responseFingerprints:i,usageLog:a}=f,{last:t,reset:s}=u;if(s)return a.length=0,i.clear(),$.invalidate(),{content:[{type:"text",text:"\u{F115D} Usage counters reset, caches cleared."}]};const o=c(t),r=$.stats();let e=`\u{F115D} **Wyrm Usage Report**
-
-`;if(e+=`## Overview${t?` (last ${t} calls)`:""}
-`,e+=`- **Total Calls:** ${o.totalCalls}
-`,e+=`- **Cache Hits:** ${o.cachedCalls} (${o.cacheHitRate})
-`,e+=`- **Tokens In:** ~${o.totalTokensIn.toLocaleString()}
-`,e+=`- **Tokens Out:** ~${o.totalTokensOut.toLocaleString()}
-`,e+=`- **Tokens Saved (cache):** ~${o.tokensSaved.toLocaleString()}
-`,e+=`- **Avg Response:** ${o.avgResponseMs}ms
-`,e+=`- **Active Cache Entries:** ${r.size}
-
-`,o.topTools.length>0){e+=`## Top Tools by Token Usage
-`;for(const p of o.topTools)e+=`- **${p.tool}:** ${p.calls} calls, ~${p.tokens.toLocaleString()} tokens
-`;e+=`
-`}const n=o.totalTokensIn/1e6*15,m=o.totalTokensOut/1e6*75,l=o.tokensSaved/1e6*75;return e+=`## Estimated Cost (Claude Opus rates)
-`,e+=`- **Input:** $${n.toFixed(4)}
-`,e+=`- **Output:** $${m.toFixed(4)}
-`,e+=`- **Saved by cache:** $${l.toFixed(4)}
-`,e+=`- **Net cost:** $${(n+m-l).toFixed(4)}`,d(e,!0)}}];export{ue as intelligenceToolSpecs};
+/**
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ */
+import { TOOL_ANNOTATIONS } from "../tool-annotations.js";
+import { currentReadCacheKey } from "./boundary.js";
+import { autoConfigureAll, findWyrmServerPath, getDefaultDbPath, getStatusSummary, removeFromAll } from "../autoconfig.js";
+import { daemonOr } from "../daemon-writer.js";
+import { renderFailureStats } from "../failure-patterns.js";
+import { computeStaleness } from "../intelligence.js";
+import { logger } from "../logger.js";
+import { runMaintenance } from "../maintenance.js";
+import { cache } from "../performance.js";
+import { createProvider } from "../providers/embedding-provider.js";
+import { reindexProjects } from "../reindex.js";
+import { requireString } from "../validate.js";
+import { createVectorStore } from "../vectors.js";
+export const intelligenceToolSpecs = [
+    {
+        name: "wyrm_feedback",
+        description: "Record whether a recalled knowledge artifact was useful. Adjusts confidence over time — successful reuse boosts it, failure lowers it. Call after applying a recalled pattern or lesson.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                artifactId: { type: "number", description: "ID of the memory artifact (from wyrm_recall results)" },
+                success: { type: "boolean", description: "Was this artifact helpful for the task?" },
+            },
+            required: ["artifactId", "success"],
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_feedback"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { memory } = ctx;
+            const { artifactId, success } = args;
+            const artifact = memory.get(artifactId);
+            if (!artifact)
+                return { content: [{ type: "text", text: `Artifact #${artifactId} not found.` }], isError: true };
+            memory.recordFeedback(artifactId, success);
+            const updated = memory.get(artifactId);
+            const icon = success ? '✅' : '❌';
+            return { content: [{ type: "text", text: `󱅝 Feedback recorded ${icon}\n\n- Artifact #${artifactId}: "${artifact.problem.slice(0, 60)}"\n- New confidence: ${(updated.confidence * 100).toFixed(0)}%\n- Total uses: ${updated.reuse_count} (✅ ${updated.reuse_success_count} / ❌ ${updated.reuse_failure_count})` }] };
+        },
+    },
+    {
+        name: "wyrm_context_build",
+        description: "Use to build a compact context brief for the current task under a token budget - relevant patterns, lessons, and truths in one formatted block; max_tokens elides low-score items to recallable stubs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                // v7 F3 (T026): property prose compressed to fund the hot-path
+                // outputSchemas under the 8K default-surface pin (T022/T025 trade).
+                projectPath: { type: "string" },
+                task: { type: "string", description: "The current task" },
+                maxItems: { type: "number", description: "Default 10, max 20" },
+                kinds: { type: "array", items: { type: "string" }, description: "Artifact kinds (see wyrm_recall)" },
+                minConfidence: { type: "number", description: "Default 0.3" },
+                max_tokens: { type: "number", description: "Token budget; low-score items elide to stubs" },
+                session_id: { type: "number", description: "Already-seen dedup" },
+                strict_budget: { type: "boolean", description: "Also elide truths over budget" },
+            },
+            required: ["projectPath", "task"],
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_context_build"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { cachedResponse, db, groundTruths, memory, runBudgetedContextBuild, scaffoldLib } = ctx;
+            const a = args || {};
+            const cacheKey = currentReadCacheKey();
+            const { projectPath: cbPath, task: cbTask, maxItems: cbMax, kinds: cbKinds, minConfidence: cbMinConf, max_tokens: cbMaxTokens, session_id: cbSessionId, strict_budget: cbStrictBudget, } = args;
+            const cbProject = db.getProject(cbPath);
+            if (!cbProject)
+                return { content: [{ type: "text", text: `Project not found: ${cbPath}` }], isError: true };
+            // Spec 014 budgeted path — only when max_tokens is supplied (backwards compat: criterion 7).
+            // Kill switch: WYRM_DISABLE_TOKEN_BUDGET=1 routes everything to legacy.
+            const wantsBudget = cbMaxTokens != null && !process.env.WYRM_DISABLE_TOKEN_BUDGET;
+            if (wantsBudget) {
+                return runBudgetedContextBuild({
+                    project: cbProject,
+                    task: cbTask,
+                    maxTokens: cbMaxTokens,
+                    sessionId: cbSessionId,
+                    strictBudget: cbStrictBudget === true,
+                    kinds: cbKinds,
+                    minConfidence: cbMinConf,
+                });
+            }
+            const sections = [];
+            // Section 1: Ground truths (~1200 char budget)
+            const truthsText = groundTruths.formatForContext(cbProject.id);
+            if (truthsText) {
+                sections.push(truthsText.slice(0, 1200));
+            }
+            // Section 2: Best reasoning scaffold (~1500 char budget)
+            const scaffoldMatch = scaffoldLib.findBest(cbTask, cbProject.id);
+            if (scaffoldMatch) {
+                const scaffoldText = scaffoldLib.formatForContext(scaffoldMatch);
+                sections.push(scaffoldText.slice(0, 1500));
+            }
+            // Section 3: Memory artifacts brief (~2000 char budget)
+            const brief = memory.buildContextBrief(cbProject.id, cbTask, {
+                maxItems: Math.min(cbMax ?? 10, 20),
+                kinds: cbKinds,
+                minConfidence: cbMinConf,
+            });
+            if (brief.sections.length > 0) {
+                const truncated = brief.text.slice(0, 2000);
+                sections.push(truncated);
+            }
+            if (sections.length === 0) {
+                return { content: [{ type: "text", text: `󱅝 **Context Brief**\n\nNo relevant memory found for this task yet.\n\nAs you work, use \`wyrm_remember\` to store:\n- ✅ Patterns that work\n- ⚠️ Anti-patterns to avoid\n- 💡 Heuristics and shortcuts\n- 🧠 Reasoning traces from complex problems\n\nFuture context briefs will become richer over time.` }] };
+            }
+            const stats = memory.getStats(cbProject.id);
+            const truthStats = groundTruths.getStats(cbProject.id);
+            // Spec 018 phase 4: cache-stable preamble wrapped in marker
+            // comments. Anthropic prompt-caching keys off prefix stability;
+            // ground truths + scaffold rarely change between calls, so we
+            // segregate them into a stable preamble and put per-call data
+            // (memory artifacts) after the marker. The markdown comment is
+            // a fallback until MCP standardises a structured annotation.
+            const stableHeader = `󱅝 **Context Brief** — "${cbTask}"\n\n`;
+            const stableParts = [];
+            if (truthsText)
+                stableParts.push(truthsText.slice(0, 1200));
+            if (scaffoldMatch)
+                stableParts.push(scaffoldLib.formatForContext(scaffoldMatch).slice(0, 1500));
+            const stablePreamble = stableParts.length > 0
+                ? `<!-- cache-stable -->\n${stableParts.join('\n\n---\n\n')}\n<!-- /cache-stable -->\n\n---\n\n`
+                : '';
+            const volatileBody = brief.sections.length > 0 ? brief.text.slice(0, 2000) : '';
+            let text = `${stableHeader}${stablePreamble}${volatileBody}`;
+            text += `\n\n_Brief: ${truthStats.current} ground truth${truthStats.current !== 1 ? 's' : ''}, scaffold: ${scaffoldMatch ? scaffoldMatch.scaffold.problem_type : 'none'}, ${stats.total} memory artifact${stats.total !== 1 ? 's' : ''}.`;
+            if (brief.sourceIds.length > 0) {
+                text += ` Memory IDs: [${brief.sourceIds.join(', ')}] — use \`wyrm_feedback\` to rate._`;
+            }
+            else {
+                text += `_`;
+            }
+            // Log cached-preamble savings (best-effort).
+            try {
+                const { logSavings } = await import('../statusline.js');
+                const rawDb = db.getDatabase();
+                const sess = rawDb.prepare(`SELECT id FROM sessions WHERE project_id = ? ORDER BY created_at DESC LIMIT 1`).get(cbProject.id);
+                // Tokens saved by caching = preamble size * 0.9 (Anthropic cached pricing is 10% of base)
+                const preambleTokens = Math.round(stablePreamble.length / 4);
+                if (preambleTokens > 0)
+                    logSavings(rawDb, 'wyrm_context_build', 'cached_preamble', Math.round(preambleTokens * 0.9), sess?.id);
+            }
+            catch { /* best-effort */ }
+            const response = cachedResponse(text);
+            if (cacheKey)
+                cache.set(cacheKey, response, 10000);
+            return response;
+        },
+    },
+    {
+        name: "wyrm_truth_set",
+        description: "Use to lock in a confirmed fact or constraint as project ground truth - architecture, conventions, key decisions. Injected first into every brief; re-setting the same category+key supersedes (history kept).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectPath: { type: "string" },
+                category: { type: "string", description: "e.g. architecture, conventions" },
+                key: { type: "string", description: "snake_case key" },
+                value: { type: "string", description: "The statement" },
+                rationale: { type: "string", description: "Why this is true" },
+                source: { type: "string", description: "'user'|'derived'|'observed'|'confirmed'" },
+                confidence: { type: "number", description: "0-1 (default 1.0)" },
+                ttl_days: { type: "number", description: "Stale after N days" },
+            },
+            required: ["projectPath", "category", "key", "value"],
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_truth_set"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { db, groundTruths, presence } = ctx;
+            const { projectPath: tPath, category: tCat, key: tKey, value: tVal, rationale: tRat, source: tSrc, confidence: tConf, ttl_days: tTtl } = args;
+            // Truth categories are an OPEN vocabulary at the storage layer:
+            // ground_truths.category carries no schema CHECK, the wire schema
+            // documents free-form values ('conventions', 'decisions', ...), and
+            // the renderer passes unknown categories through with their own
+            // label. Closed-enum rejection here would invalidate legal stored
+            // data — so the boundary enforces presence/type only (there is no
+            // CHECK-violation path for this field in either write mode).
+            const tSafeCat = requireString('category', tCat, { maxLen: 200 });
+            const tProject = db.getProject(tPath);
+            if (!tProject)
+                return { content: [{ type: "text", text: `Project not found: ${tPath}` }], isError: true };
+            // v7 F2 (T012): canonical write seam — truth_set.
+            const tInput = {
+                category: tSafeCat,
+                key: tKey,
+                value: tVal,
+                rationale: tRat,
+                source: tSrc,
+                confidence: tConf ?? 1.0,
+                ttl_days: tTtl,
+            };
+            const truth = await daemonOr('truth_set', tProject.id, tInput, () => groundTruths.set(tProject.id, tInput));
+            cache.invalidate('wyrm_truth_get');
+            cache.invalidate('wyrm_context_build');
+            return { content: [{ type: "text", text: `󱅝 **Ground Truth Set** ✅\n\n- **Category:** ${tCat}\n- **Key:** ${tKey}\n- **Value:** ${tVal}${tRat ? `\n- **Rationale:** ${tRat}` : ''}${tTtl ? `\n- **TTL:** ${tTtl} days` : ''}\n- **ID:** ${truth.id}\n\nThis truth will be injected at the top of every \`wyrm_context_build\` response for this project.` }] };
+        },
+    },
+    {
+        name: "wyrm_truth_get",
+        description: "Use to read the established facts and ground rules for a codebase - validated truths the AI should treat as baseline, optionally filtered by category.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectPath: { type: "string" },
+                category: { type: "string", description: "Category filter" },
+            },
+            required: ["projectPath"],
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_truth_get"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { cachedResponse, db, groundTruths } = ctx;
+            const cacheKey = currentReadCacheKey();
+            const { projectPath: tgPath, category: tgCat } = args;
+            const tgProject = db.getProject(tgPath);
+            if (!tgProject)
+                return { content: [{ type: "text", text: `Project not found: ${tgPath}` }], isError: true };
+            const truths = groundTruths.getCurrent(tgProject.id, tgCat);
+            if (truths.length === 0) {
+                const msg = tgCat
+                    ? `No ground truths in category "${tgCat}" for this project.`
+                    : `No ground truths stored yet. Use \`wyrm_truth_set\` to add validated facts.`;
+                return { content: [{ type: "text", text: `󱅝 **Ground Truths**\n\n${msg}` }] };
+            }
+            const byCategory = new Map();
+            for (const t of truths) {
+                if (!byCategory.has(t.category))
+                    byCategory.set(t.category, []);
+                byCategory.get(t.category).push(t);
+            }
+            let text = `󱅝 **Ground Truths** — ${truths.length} active\n\n`;
+            for (const [cat, items] of byCategory) {
+                text += `### ${cat}\n`;
+                for (const t of items) {
+                    const staleness = computeStaleness(t);
+                    const stale = staleness !== null && staleness > 0.7;
+                    const stalePrefix = stale ? '[⚠️ STALE] ' : '';
+                    text += `- ${stalePrefix}**${t.key}:** ${t.value}`;
+                    if (t.confidence < 1)
+                        text += ` _(confidence: ${(t.confidence * 100).toFixed(0)}%)_`;
+                    if (t.rationale)
+                        text += `\n  _${t.rationale}_`;
+                    if (staleness !== null)
+                        text += `\n  _staleness: ${(staleness * 100).toFixed(0)}% (TTL: ${t.ttl_days}d)_`;
+                    text += '\n';
+                }
+                text += '\n';
+            }
+            const response = cachedResponse(text);
+            if (cacheKey)
+                cache.set(cacheKey, response, 15000);
+            return response;
+        },
+    },
+    {
+        name: "wyrm_scaffold_get",
+        description: "Find the best reasoning scaffold for a task description. Returns the most relevant structured checklist, or null if no match meets the confidence threshold.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectPath: { type: "string", description: "Project path (searches project + global)" },
+                task: { type: "string", description: "Task description to match against scaffolds" },
+                minConfidence: { type: "number", description: "Minimum match confidence 0-1 (default: 0.3)" },
+            },
+            required: ["task"],
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_scaffold_get"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { cachedResponse, db, scaffoldLib } = ctx;
+            const cacheKey = currentReadCacheKey();
+            const { projectPath: sgPath, task: sgTask, minConfidence: sgConf } = args;
+            const sgProjectId = sgPath ? db.getProject(sgPath)?.id ?? undefined : undefined;
+            const match = scaffoldLib.findBest(sgTask, sgProjectId, sgConf);
+            if (!match) {
+                return { content: [{ type: "text", text: `󱅝 **Reasoning Scaffold**\n\nNo scaffold matched for: "${sgTask}"\n\nUse \`wyrm_scaffold_save\` to add scaffolds for this problem type.` }] };
+            }
+            const text = scaffoldLib.formatForContext(match);
+            const response = cachedResponse(`󱅝 **Reasoning Scaffold Match** (${(match.matchScore * 100).toFixed(0)}% confidence)\n\n${text}`);
+            if (cacheKey)
+                cache.set(cacheKey, response, 15000);
+            return response;
+        },
+    },
+    {
+        name: "wyrm_sync",
+        description: "Sync database with .wyrm folders in all projects",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectPath: { type: "string", description: "Sync specific project, or all if not specified" },
+                direction: { type: "string", enum: ["import", "export", "both"], description: "Sync direction" },
+            },
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_sync"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { db, sync } = ctx;
+            const { projectPath, direction } = args;
+            const dir = direction || 'both';
+            let count = 0;
+            if (projectPath) {
+                const project = db.getProject(projectPath);
+                if (project) {
+                    if (dir === 'import' || dir === 'both')
+                        sync.importFromFolder(projectPath);
+                    if (dir === 'export' || dir === 'both')
+                        sync.exportToFolder(projectPath);
+                    count = 1;
+                }
+            }
+            else {
+                const projects = db.getAllProjects(1000);
+                for (const p of projects) {
+                    try {
+                        if (dir === 'import' || dir === 'both')
+                            sync.importFromFolder(p.path);
+                        if (dir === 'export' || dir === 'both')
+                            sync.exportToFolder(p.path);
+                        count++;
+                    }
+                    catch {
+                        // Skip failed syncs
+                    }
+                }
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: `󱅝 Synced ${count} project(s)`
+                    }]
+            };
+        },
+    },
+    {
+        name: "wyrm_stats",
+        description: "Use for a health snapshot of the memory database - row counts, vector index coverage, usage.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                view: { type: "string", enum: ["failures"], description: "'failures' = prevented-repeat analytics" },
+                projectPath: { type: "string", description: "failures view scope" },
+            },
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_stats"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { WRITE_TOOLS, analytics, cachedResponse, db, failures, getUsageStats, orchestrator, vectorStore } = ctx;
+            const a = args || {};
+            const cacheKey = currentReadCacheKey();
+            // v7 F2 (T017): prevented-repeat analytics view (spec FR-2). NOT
+            // cached on purpose: the failure_blocks ledger is written by
+            // wyrm_failure_check, which is not in WRITE_TOOLS, so the stats cache
+            // invalidation never fires for it — a 15s-stale "repeats blocked this
+            // run" would lie to an orchestrator polling mid-fleet, and the view is
+            // a handful of indexed COUNTs (cheap enough to stay fresh). "this run"
+            // resolves from the ambient actor envelope (failureStats → getActor()).
+            const { view: statsViewArg, projectPath: statsProjectPath } = args;
+            if (statsViewArg === "failures") {
+                const statsProject = statsProjectPath ? db.getProject(statsProjectPath) : null;
+                const failuresView = failures.failureStats({ projectId: statsProject?.id ?? null });
+                return {
+                    content: [{ type: "text", text: renderFailureStats(failuresView) }],
+                    // Pre-T019 dual-emit (the T011/T014 precedent): structuredContent
+                    // carries the canonical view; outputSchema lands with F3 ToolSpec.
+                    structuredContent: failuresView,
+                };
+            }
+            const stats = db.getStats();
+            const cacheStats = cache.stats();
+            const usage = getUsageStats();
+            // Vector coverage stats
+            let vectorStatsText = '';
+            if (vectorStore) {
+                const vectorStats = vectorStore.getStats();
+                // Coverage compares vectors against the SAME content kinds that get
+                // embedded — artifacts/quests/sessions — NOT dataPoints (never
+                // embedded), and clamps at 100%. The old denominator omitted
+                // artifacts entirely while the numerator counted artifact vectors,
+                // so it read >1000% once the corpus was embedded.
+                const bt = (vectorStats.byType || {});
+                const embeddedTracked = (bt.artifact || 0) + (bt.quest || 0) + (bt.session || 0);
+                const totalEmbeddable = stats.artifacts + stats.quests + stats.sessions;
+                const vectorCoverage = totalEmbeddable > 0
+                    ? Math.min(100, (embeddedTracked / totalEmbeddable) * 100).toFixed(1)
+                    : '0';
+                vectorStatsText =
+                    `\n**Vectors:**\n` +
+                        `- **Provider:** ${vectorStats.provider} (${vectorStats.model})\n` +
+                        `- **Embeddings:** ${vectorStats.total} vectors\n` +
+                        `- **Coverage:** ${vectorCoverage}% of embeddable content\n` +
+                        `- **By Type:** ${Object.entries(vectorStats.byType).map(([t, c]) => `${t}: ${c}`).join(', ')}\n`;
+            }
+            const response = cachedResponse(`󱅝 **Wyrm Statistics**\n\n` +
+                `- **Projects:** ${stats.projects}\n` +
+                `- **Sessions:** ${stats.sessions}\n` +
+                `- **Quests:** ${stats.quests}\n` +
+                `- **Data Points:** ${stats.dataPoints}\n` +
+                `- **Active Tokens:** ~${stats.totalTokens.toLocaleString()}\n` +
+                `- **Database Size:** ${stats.dbSize}\n` +
+                vectorStatsText +
+                `\n**Cache:** ${cacheStats.size} entries | Hit rate: ${usage.cacheHitRate}\n` +
+                `**Usage:** ${usage.totalCalls} calls | ~${usage.tokensSaved.toLocaleString()} tokens saved by cache`);
+            if (cacheKey)
+                cache.set(cacheKey, response, 15000);
+            return response;
+        },
+    },
+    {
+        name: "wyrm_vector_setup",
+        description: "Configure embedding provider and download models. Supports local, OpenAI, and Ollama.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: { type: "string", enum: ["auto", "local", "openai", "ollama", "none"], description: "Provider: auto-detect, local hash, OpenAI API, Ollama, or none" },
+                model: { type: "string", description: "Model name (e.g., 'text-embedding-3-small' for OpenAI, 'nomic-embed-text' for Ollama)" },
+                apiKey: { type: "string", description: "OpenAI API key (if using openai provider)" },
+                ollamaUrl: { type: "string", description: "Ollama URL (default: http://localhost:11434)" },
+            },
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_vector_setup"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { db, indexingPipeline, memory, setVectorStore, vectorStore } = ctx;
+            const { provider: prov, model: mod, apiKey: key, ollamaUrl: url } = args;
+            // Build new provider config
+            const providerConfig = {
+                provider: (prov || 'auto'),
+                model: mod,
+                apiKey: key,
+                ollamaUrl: url,
+            };
+            try {
+                // Create new provider to test
+                const testProvider = createProvider(providerConfig);
+                const isReady = await testProvider.isReady();
+                if (!isReady && providerConfig.provider !== 'none') {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `❌ **Provider Not Ready**\n\nCouldn't connect to ${testProvider.name}. Check your configuration and try again.`
+                            }],
+                        isError: true
+                    };
+                }
+                // Update global vector store
+                const __vs = createVectorStore(providerConfig, db.getDatabase());
+                setVectorStore(__vs);
+                memory.setVectorStore(__vs); // keep hybrid recall pointed at the live store
+                if (indexingPipeline)
+                    indexingPipeline.updateStore(__vs);
+                const stats = __vs.getStats();
+                return {
+                    content: [{
+                            type: "text",
+                            text: `✅ **Vector Setup Complete**\n\n` +
+                                `- **Provider:** ${testProvider.name}\n` +
+                                `- **Model:** ${testProvider.model}\n` +
+                                `- **Dimensions:** ${testProvider.dimensions}\n` +
+                                `- **Status:** ${isReady ? 'Ready' : 'Ready (will auto-connect)'}\n\n` +
+                                `_Reindex your projects with wyrm_reindex to generate embeddings._`
+                        }]
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `❌ **Vector Setup Failed**\n\n${String(err)}`
+                        }],
+                    isError: true
+                };
+            }
+        },
+    },
+    {
+        name: "wyrm_reindex",
+        description: "Rebuild embeddings for a project or all projects. Regenerates vectors for sessions, quests, data, and memory artifacts (the latter power hybrid recall).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectPath: { type: "string", description: "Project to reindex, or leave empty for all projects" },
+                dryRun: { type: "boolean", description: "Show what would be indexed without making changes" },
+            },
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_reindex"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { db, failures, vectorStore } = ctx;
+            const { projectPath: ppath, dryRun } = args;
+            if (!vectorStore) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `❌ **Vector Indexing Disabled**\n\nRun wyrm_vector_setup first to enable vector search.`
+                        }],
+                    isError: true
+                };
+            }
+            let projectIds = [];
+            if (ppath) {
+                const proj = db.getProject(ppath);
+                if (!proj) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `❌ **Project Not Found:** ${ppath}`
+                            }],
+                        isError: true
+                    };
+                }
+                projectIds = [proj.id];
+            }
+            else {
+                const allProjs = db.getAllProjects(1000);
+                projectIds = allProjs.map(p => p.id);
+            }
+            // v7 F3 (T023): the project loop moved VERBATIM to src/reindex.ts
+            // (reindexProjects) so the new `wyrm index rebuild` CLI subcommand and
+            // this tool run the SAME code path. Per-row failures still log here.
+            const { indexed, skipped } = await reindexProjects(db.getDatabase(), vectorStore, projectIds, {
+                dryRun,
+                onError: (message, context) => logger.error(message, context),
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: `󱅝 **Reindexing ${dryRun ? '(Dry Run)' : 'Complete'}**\n\n` +
+                            `- **Projects:** ${projectIds.length}\n` +
+                            `- **Indexed:** ${indexed}\n` +
+                            `- **Skipped:** ${skipped}\n\n` +
+                            (dryRun ? '_Run without dryRun to actually index._' : '_Vectors are now up to date._')
+                    }]
+            };
+        },
+    },
+    {
+        name: "wyrm_maintenance",
+        description: "Use for periodic upkeep of the memory store - archive old sessions, vacuum, prune stale events, sweep run quarantine, rebuild vector embeddings (reindex). Admin-gated, destructive; fleets run it between waves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                vacuum: { type: "boolean", description: "Reclaim space" },
+                archiveDays: { type: "number", description: "Archive sessions > N days" },
+            },
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_maintenance"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { db, failures, presence, sessionSeen } = ctx;
+            const a = args || {};
+            const { vacuum, archiveDays } = args;
+            // v7 F3 (T023): the step sequence moved VERBATIM to
+            // src/maintenance.ts (runMaintenance) so the new `wyrm maintenance`
+            // CLI subcommand and this tool run the SAME code path. The 6.x text
+            // is reassembled byte-identically below (every line carried "- " and
+            // a trailing newline).
+            // v7 F3 (T029): + presence — stale-claim/presence eviction now rides
+            // maintenance (reap previously ran only inline at claim time).
+            const report = runMaintenance({ db, sessionSeen: sessionSeen(), failures, presence }, { vacuum, archiveDays });
+            const text = '󱅝 **Maintenance Complete**\n\n' +
+                report.lines.map((line) => `- ${line}\n`).join('') +
+                `\n**New Database Size:** ${report.dbSize}`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    {
+        name: "wyrm_setup",
+        description: "Auto-detect installed AI clients (VS Code, Claude Desktop, Cursor, Windsurf, Zed) and configure Wyrm's MCP server in all of them. Run this to connect Wyrm to a new AI or after switching providers.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                action: { type: "string", enum: ["configure", "check", "remove"], description: "Action: configure (default), check status, or remove from all" },
+                serverPath: { type: "string", description: "Override Wyrm server path (auto-detected if empty)" },
+                dbPath: { type: "string", description: "Override database path (default: ~/.wyrm/wyrm.db)" },
+            },
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_setup"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { action, serverPath, dbPath } = args;
+            const setupAction = action || 'configure';
+            if (setupAction === 'check') {
+                return {
+                    content: [{
+                            type: "text",
+                            text: getStatusSummary()
+                        }]
+                };
+            }
+            if (setupAction === 'remove') {
+                const results = removeFromAll();
+                const removed = results.filter(r => r.action === 'configured');
+                const text = `󱅝 **Wyrm Removed**\n\n` +
+                    `Removed from ${removed.length} AI client(s):\n` +
+                    results.map(r => `- ${r.client.icon} ${r.client.name}: ${r.message}`).join('\n') +
+                    `\n\nRun wyrm_setup again to reconnect.`;
+                return { content: [{ type: "text", text }] };
+            }
+            // Default: configure
+            const results = autoConfigureAll({
+                serverPath: serverPath || undefined,
+                dbPath: dbPath || undefined,
+            });
+            const configured = results.filter(r => r.action === 'configured' || r.action === 'updated');
+            const failed = results.filter(r => r.action === 'failed');
+            let text = `󱅝 **Wyrm Auto-Configure Complete**\n\n`;
+            text += `Connected to ${configured.length} AI client(s):\n`;
+            for (const r of results) {
+                const icon = r.action === 'configured' ? '✅' :
+                    r.action === 'updated' ? '🔄' :
+                        r.action === 'skipped' ? '○' : '❌';
+                text += `- ${icon} ${r.client.icon} ${r.client.name}: ${r.message}\n`;
+            }
+            if (failed.length > 0) {
+                text += `\n⚠️ ${failed.length} client(s) failed. Check errors above.`;
+            }
+            text += `\n\nServer: ${findWyrmServerPath()}\nDB: ${getDefaultDbPath()}`;
+            text += `\n\n_Switch AIs anytime — run wyrm_setup again to reconnect._`;
+            return { content: [{ type: "text", text }] };
+        },
+    },
+    {
+        name: "wyrm_usage",
+        description: "View token usage stats, cache hit rates, and estimated cost savings. Helps monitor and optimize AI credit consumption.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                last: { type: "number", description: "Show stats for last N calls (default: all)" },
+                reset: { type: "boolean", description: "Reset usage counters" },
+            },
+        },
+        annotations: TOOL_ANNOTATIONS["wyrm_usage"],
+        aliases: [],
+        handler: async (args, ctx) => {
+            const { cachedResponse, getUsageStats, responseFingerprints, usageLog } = ctx;
+            const { last, reset } = args;
+            if (reset) {
+                usageLog.length = 0;
+                responseFingerprints.clear();
+                cache.invalidate();
+                return { content: [{ type: "text", text: "󱅝 Usage counters reset, caches cleared." }] };
+            }
+            const usage = getUsageStats(last);
+            const cacheStats = cache.stats();
+            let text = `󱅝 **Wyrm Usage Report**\n\n`;
+            text += `## Overview${last ? ` (last ${last} calls)` : ''}\n`;
+            text += `- **Total Calls:** ${usage.totalCalls}\n`;
+            text += `- **Cache Hits:** ${usage.cachedCalls} (${usage.cacheHitRate})\n`;
+            text += `- **Tokens In:** ~${usage.totalTokensIn.toLocaleString()}\n`;
+            text += `- **Tokens Out:** ~${usage.totalTokensOut.toLocaleString()}\n`;
+            text += `- **Tokens Saved (cache):** ~${usage.tokensSaved.toLocaleString()}\n`;
+            text += `- **Avg Response:** ${usage.avgResponseMs}ms\n`;
+            text += `- **Active Cache Entries:** ${cacheStats.size}\n\n`;
+            if (usage.topTools.length > 0) {
+                text += `## Top Tools by Token Usage\n`;
+                for (const t of usage.topTools) {
+                    text += `- **${t.tool}:** ${t.calls} calls, ~${t.tokens.toLocaleString()} tokens\n`;
+                }
+                text += '\n';
+            }
+            // Cost estimate (Claude Opus pricing: $15/M input, $75/M output)
+            const costInput = (usage.totalTokensIn / 1_000_000) * 15;
+            const costOutput = (usage.totalTokensOut / 1_000_000) * 75;
+            const costSaved = (usage.tokensSaved / 1_000_000) * 75;
+            text += `## Estimated Cost (Claude Opus rates)\n`;
+            text += `- **Input:** $${costInput.toFixed(4)}\n`;
+            text += `- **Output:** $${costOutput.toFixed(4)}\n`;
+            text += `- **Saved by cache:** $${costSaved.toFixed(4)}\n`;
+            text += `- **Net cost:** $${(costInput + costOutput - costSaved).toFixed(4)}`;
+            return cachedResponse(text, true); // ephemeral — don't cache the usage report itself
+        },
+    },
+];
+//# sourceMappingURL=intelligence.js.map