wyrm-mcp 5.3.0 → 5.4.0

package/dist/context-ranking.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Combined-score computation for context-build candidates (spec 014).
+ *
+ * Combines four signals into a single score in [0, 1]:
+ *
+ *   confidence × wC + recency × wR + relevance × wU + usefulness × wU
+ *
+ * Weights load from WYRM_RANK_WEIGHTS env (JSON) with sane defaults.
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ * @license Proprietary
+ */
+export interface RankWeights {
+    confidence: number;
+    recency: number;
+    relevance: number;
+    usefulness: number;
+}
+export declare const DEFAULT_WEIGHTS: Readonly<RankWeights>;
+/**
+ * Load weights from WYRM_RANK_WEIGHTS env var. Falls back to defaults
+ * on any parse/validation error. Logs the active weights at startup.
+ */
+export declare function loadWeightsFromEnv(env?: NodeJS.ProcessEnv): RankWeights;
+export interface ScoreableItem {
+    /** [0, 1] — confidence the item is correct/true */
+    confidence?: number;
+    /** ISO timestamp — used for recency decay */
+    updatedAt?: string;
+    /** [0, 1] — pre-computed relevance (FTS5 rank / vector score) */
+    relevance?: number;
+    /** [0, 1] — usefulness inferred from wyrm_feedback signals */
+    usefulness?: number;
+}
+/**
+ * Compute the combined score in [0, 1].
+ *
+ * Recency uses exponential decay over 30 days from updatedAt to now.
+ * Missing signals default to neutral (0.5 confidence, 0.5 relevance, 0.5
+ * usefulness; recency to 0 if no updatedAt).
+ */
+export declare function score(item: ScoreableItem, weights: RankWeights, now?: Date): number;
+//# sourceMappingURL=context-ranking.d.ts.map

package/dist/context-ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-ranking.d.ts","sourceRoot":"","sources":["../src/context-ranking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,WAAW,CAKjD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,WAAW,CAgBpF;AAOD,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CACnB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,WAAW,EACpB,GAAG,GAAE,IAAiB,GACrB,MAAM,CAgBR"}

package/dist/context-ranking.js

@@ -0,0 +1,69 @@
+/**
+ * Combined-score computation for context-build candidates (spec 014).
+ *
+ * Combines four signals into a single score in [0, 1]:
+ *
+ *   confidence × wC + recency × wR + relevance × wU + usefulness × wU
+ *
+ * Weights load from WYRM_RANK_WEIGHTS env (JSON) with sane defaults.
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd. All Rights Reserved.
+ * @license Proprietary
+ */
+import { logger } from './logger.js';
+export const DEFAULT_WEIGHTS = {
+    confidence: 0.4,
+    recency: 0.2,
+    relevance: 0.3,
+    usefulness: 0.1,
+};
+/**
+ * Load weights from WYRM_RANK_WEIGHTS env var. Falls back to defaults
+ * on any parse/validation error. Logs the active weights at startup.
+ */
+export function loadWeightsFromEnv(env = process.env) {
+    const raw = env.WYRM_RANK_WEIGHTS;
+    if (!raw)
+        return { ...DEFAULT_WEIGHTS };
+    try {
+        const parsed = JSON.parse(raw);
+        const w = {
+            confidence: clamp01(parsed.confidence ?? DEFAULT_WEIGHTS.confidence),
+            recency: clamp01(parsed.recency ?? DEFAULT_WEIGHTS.recency),
+            relevance: clamp01(parsed.relevance ?? DEFAULT_WEIGHTS.relevance),
+            usefulness: clamp01(parsed.usefulness ?? DEFAULT_WEIGHTS.usefulness),
+        };
+        return w;
+    }
+    catch (e) {
+        logger.warn(`Invalid WYRM_RANK_WEIGHTS, using defaults: ${e.message}`);
+        return { ...DEFAULT_WEIGHTS };
+    }
+}
+function clamp01(x) {
+    if (!Number.isFinite(x))
+        return 0;
+    return Math.max(0, Math.min(1, x));
+}
+/**
+ * Compute the combined score in [0, 1].
+ *
+ * Recency uses exponential decay over 30 days from updatedAt to now.
+ * Missing signals default to neutral (0.5 confidence, 0.5 relevance, 0.5
+ * usefulness; recency to 0 if no updatedAt).
+ */
+export function score(item, weights, now = new Date()) {
+    const c = clamp01(item.confidence ?? 0.5);
+    const u = clamp01(item.usefulness ?? 0.5);
+    const r = clamp01(item.relevance ?? 0.5);
+    const ageDays = item.updatedAt
+        ? Math.max(0, (now.getTime() - new Date(item.updatedAt).getTime()) / (24 * 60 * 60 * 1000))
+        : Infinity;
+    const recency = Number.isFinite(ageDays) ? Math.exp(-ageDays / 30) : 0;
+    const total = c * weights.confidence +
+        recency * weights.recency +
+        r * weights.relevance +
+        u * weights.usefulness;
+    return clamp01(total);
+}
+//# sourceMappingURL=context-ranking.js.map

package/dist/context-ranking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-ranking.js","sourceRoot":"","sources":["../src/context-ranking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AASrC,MAAM,CAAC,MAAM,eAAe,GAA0B;IACpD,UAAU,EAAE,GAAG;IACf,OAAO,EAAE,GAAG;IACZ,SAAS,EAAE,GAAG;IACd,UAAU,EAAE,GAAG;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,MAAM,GAAG,GAAG,GAAG,CAAC,iBAAiB,CAAC;IAClC,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,GAAG,eAAe,EAAE,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QACvD,MAAM,CAAC,GAAgB;YACrB,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,IAAI,eAAe,CAAC,UAAU,CAAC;YACpE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC;YAC3D,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,eAAe,CAAC,SAAS,CAAC;YACjE,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,IAAI,eAAe,CAAC,UAAU,CAAC;SACrE,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC,IAAI,CAAC,8CAA+C,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,GAAG,eAAe,EAAE,CAAC;IAChC,CAAC;AACH,CAAC;AAED,SAAS,OAAO,CAAC,CAAS;IACxB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAaD;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CACnB,IAAmB,EACnB,OAAoB,EACpB,MAAY,IAAI,IAAI,EAAE;IAEtB,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC;IAC1C,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC;IAC1C,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS;QAC5B,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC3F,CAAC,CAAC,QAAQ,CAAC;IACb,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEvE,MAAM,KAAK,GACT,CAAC,GAAG,OAAO,CAAC,UAAU;QACtB,OAAO,GAAG,OAAO,CAAC,OAAO;QACzB,CAAC,GAAG,OAAO,CAAC,SAAS;QACrB,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAEzB,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;AACxB,CAAC"}

package/dist/index.js

@@ -61,6 +61,9 @@ import { AgentDaemon } from "./agent-daemon.js";
 import { getUpdateStatus, emitStartupVersionBanner } from "./version-check.js";
 import { getCapabilities, renderCapabilityBriefing } from "./capabilities.js";
 import { spawn as cpSpawn } from "child_process";
+import { makeEstimator, applyBudget, resolveBudget } from "./token-budget.js";
+import { loadWeightsFromEnv, score as rankScore } from "./context-ranking.js";
+import { SessionSeen } from "./session-seen.js";
 import { fileURLToPath as _versionFileURLToPath } from "url";
 import { dirname as _versionDirname, join as _versionJoin } from "path";
 import { readFileSync as _versionReadFile, existsSync as _versionExists } from "fs";
@@ -68,6 +71,149 @@ import { readFileSync as _versionReadFile, existsSync as _versionExists } from "
 // The ListToolsRequestSchema handler is the single source of truth at runtime —
 // this constant is just for the self-description and the postinstall pitch.
 const WYRM_TOOL_COUNT = 114;
+// Spec 014 — token budgeting subsystem. Lazy-init on first use.
+const tokenEstimator = makeEstimator();
+const rankWeights = loadWeightsFromEnv();
+let _sessionSeen = null;
+function sessionSeen() {
+    if (!_sessionSeen)
+        _sessionSeen = new SessionSeen(db.getDatabase());
+    return _sessionSeen;
+}
+/**
+ * Spec 014 budgeted wyrm_context_build path.
+ *
+ * Renders a stable preamble (ground truths) + dynamic body (memory
+ * artifacts, scaffold). Items below the token-budget cutoff elide to
+ * one-line stubs the AI can recall via wyrm_recall.
+ */
+function runBudgetedContextBuild(opts) {
+    // Resolve effective budget per spec 014 D1 precedence: call > env > fallback.
+    const budget = resolveBudget({
+        callArg: opts.maxTokens,
+        envValue: process.env.WYRM_CONTEXT_TOKEN_BUDGET,
+        clientName: null, // clientInfo wiring is a follow-up; env override is the lever today
+    });
+    const seen = opts.sessionId ? sessionSeen().getSeen(opts.sessionId) : new Set();
+    // --- Stable preamble (ground truths) ---
+    const truthsText = groundTruths.formatForContext(opts.project.id);
+    const truthsTokens = tokenEstimator.count(truthsText ?? '');
+    // Strict budget mode (D3) elides truths if even the preamble overflows;
+    // default behavior is to warn-and-overflow per spec 014.
+    let preambleText = truthsText ?? '';
+    let preambleEmitted = truthsTokens;
+    if (truthsTokens > budget * 0.5 && !opts.strictBudget) {
+        process.stderr.write(`[wyrm_context_build] ground truths consume ${truthsTokens} of ${budget}-token budget — body will be heavily elided. Pass strict_budget:true to elide truths too.\n`);
+    }
+    if (opts.strictBudget && truthsTokens > budget * 0.5) {
+        // Strict mode: keep truths brief
+        preambleText = (truthsText ?? '').slice(0, budget * 2); // 2 chars/token rough cap on chars
+        preambleEmitted = tokenEstimator.count(preambleText);
+    }
+    // --- Build candidate body items: best scaffold + memory artifacts ---
+    const items = [];
+    // Scaffold (treated as a single candidate)
+    const scaffoldMatch = scaffoldLib.findBest(opts.task, opts.project.id);
+    if (scaffoldMatch) {
+        const sText = scaffoldLib.formatForContext(scaffoldMatch);
+        const sId = scaffoldMatch.scaffold.id;
+        items.push({
+            item: { kind: 'scaffold', id: sId, title: scaffoldMatch.scaffold.problem_type, body: sText },
+            key: `scaffold:${sId}`,
+            inlineCost: tokenEstimator.count(sText),
+            stubCost: 20,
+            // Scaffold is high-relevance by definition; assign generous score.
+            score: rankScore({ confidence: 0.9, relevance: 0.9, updatedAt: new Date().toISOString() }, rankWeights),
+        });
+    }
+    // Memory artifacts via recall (which returns id-level results with relevance scores)
+    const recalled = memory.recall(opts.project.id, opts.task, {
+        limit: 20,
+        minConfidence: opts.minConfidence ?? 0.2,
+    });
+    for (const r of recalled) {
+        const a = r.artifact;
+        // Skip kind filter mismatches if caller specified one
+        if (opts.kinds && opts.kinds.length > 0 && !opts.kinds.includes(a.kind))
+            continue;
+        const body = [
+            `**${a.kind.toUpperCase()}** · ${a.problem}`,
+            a.constraints ? `Constraints: ${a.constraints}` : '',
+            a.validated_fix ? `Fix: ${a.validated_fix}` : '',
+            a.why_it_worked ? `Why: ${a.why_it_worked}` : '',
+        ].filter(Boolean).join('\n');
+        items.push({
+            item: { kind: 'memory', id: a.id, title: a.problem.slice(0, 60), body },
+            key: `memory:${a.id}`,
+            inlineCost: tokenEstimator.count(body),
+            stubCost: 25,
+            score: rankScore({
+                confidence: a.confidence,
+                relevance: r.relevance_score,
+                updatedAt: a.updated_at,
+            }, rankWeights),
+        });
+    }
+    // --- Apply budget ---
+    const result = applyBudget(items, {
+        budget,
+        alreadySeen: seen,
+        reserved: opts.strictBudget ? 0 : preambleEmitted,
+    });
+    // --- Mark inlined items as seen for this session ---
+    if (opts.sessionId) {
+        sessionSeen().markBulk(opts.sessionId, result.inline.map((it) => ({ id: it.id, kind: it.kind, mode: 'inline' })));
+        sessionSeen().markBulk(opts.sessionId, result.elided.map((e) => ({ id: e.item.id, kind: e.item.kind, mode: 'stub' })));
+    }
+    // --- Render output ---
+    const lines = [];
+    lines.push(`🐉 **Context Brief** — "${opts.task}"`);
+    lines.push('');
+    lines.push('## Ground truths (stable preamble)');
+    lines.push('');
+    lines.push(preambleText || '_no ground truths set for this project yet_');
+    lines.push('');
+    lines.push('## Task-relevant memory');
+    lines.push('');
+    for (const it of result.inline) {
+        lines.push(`### [${it.kind}:${it.id}] ${it.title}`);
+        lines.push(it.body);
+        lines.push('');
+    }
+    if (result.elided.length > 0) {
+        lines.push('## Elided to stubs');
+        lines.push('');
+        lines.push('_Below the budget cutoff or already seen this session. Recall with `wyrm_recall(id)`:_');
+        lines.push('');
+        for (const e of result.elided) {
+            const tag = e.reason === 'seen' ? 'shown earlier in session' : `~${e.stubCost} tokens`;
+            lines.push(`- [${e.item.kind}:${e.item.id}] ${e.item.title} · ${tag}`);
+        }
+        lines.push('');
+    }
+    lines.push('---');
+    lines.push(`_Budget: ${result.tokensInline}/${budget} tokens inline · ${result.elided.length} stub${result.elided.length === 1 ? '' : 's'} · estimator: ${tokenEstimator.source}_`);
+    const text = lines.join('\n');
+    // Telemetry — fire-and-forget via the existing tool_call_log surface.
+    try {
+        toolAnalytics.log({
+            tool_name: 'wyrm_context_build',
+            project_id: opts.project.id,
+            args: {
+                budget,
+                items_total: items.length,
+                items_inline: result.inline.length,
+                items_elided: result.elided.length,
+                tokens_inline: result.tokensInline,
+                tokens_stubs: result.tokensStubs,
+            },
+            success: true,
+            latency_ms: 0,
+        });
+    }
+    catch { /* never fail context_build on telemetry */ }
+    return { content: [{ type: 'text', text }] };
+}
 // Resolve our own package.json once so wyrm_check_update knows what version we are.
 const WYRM_PACKAGE_VERSION = (() => {
     try {
@@ -1119,19 +1265,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "wyrm_context_build",
-            description: "Assemble an optimized memory brief for the current task — a formatted block of relevant patterns, lessons, reasoning traces, and anti-patterns from past sessions. Inject this at the start of complex tasks to give AI models the right context without bloating the whole conversation.",
+            description: "Assemble an optimized memory brief for the current task — a formatted block of relevant patterns, lessons, reasoning traces, and anti-patterns from past sessions. Inject this at the start of complex tasks to give AI models the right context without bloating the whole conversation. Pass max_tokens for budget-aware delivery (low-score items elide to recallable stubs); omit max_tokens for legacy unbounded behaviour.",
             inputSchema: {
                 type: "object",
                 properties: {
                     projectPath: { type: "string", description: "Project to build context from" },
                     task: { type: "string", description: "Describe the current task in detail — the more specific, the better the recall" },
-                    maxItems: { type: "number", description: "Max knowledge items to include (default: 10, max: 20)" },
+                    maxItems: { type: "number", description: "Max knowledge items to include (default: 10, max: 20). Ignored when max_tokens is set." },
                     kinds: {
                         type: "array",
                         items: { type: "string", enum: ["reasoning_trace", "lesson", "pattern", "anti_pattern", "heuristic"] },
                         description: "Limit to specific artifact kinds (default: all)",
                     },
                     minConfidence: { type: "number", description: "Minimum confidence threshold (default: 0.3)" },
+                    max_tokens: { type: "number", description: "Spec 014: token budget. Default per model tier auto-detected (Opus 4096 / Sonnet 8192 / Haiku 12288), env WYRM_CONTEXT_TOKEN_BUDGET, fallback 4096. Items below budget cutoff elide to stubs the AI can deref with wyrm_recall." },
+                    session_id: { type: "number", description: "Spec 014: session id for already-seen dedup. Items already shown in this session render as one-line references." },
+                    strict_budget: { type: "boolean", description: "Spec 014: if true, elide ground truths too when preamble exceeds budget. Default false — ground truths are foundation and never elided unless explicitly requested." },
                 },
                 required: ["projectPath", "task"],
             },
@@ -2910,10 +3059,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     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})` }] };
                 }
                 case "wyrm_context_build": {
-                    const { projectPath: cbPath, task: cbTask, maxItems: cbMax, kinds: cbKinds, minConfidence: cbMinConf } = args;
+                    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);
@@ -3306,6 +3469,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         db.vacuum();
                         text += `- Vacuumed database\n`;
                     }
+                    // Spec 014: prune session_seen_artifacts older than WYRM_SEEN_TTL_DAYS (default 7).
+                    try {
+                        const ttlDays = parseInt(process.env.WYRM_SEEN_TTL_DAYS ?? '7', 10);
+                        const pruned = sessionSeen().prune(Number.isFinite(ttlDays) && ttlDays > 0 ? ttlDays : 7);
+                        if (pruned > 0)
+                            text += `- Pruned ${pruned} session_seen_artifacts rows older than ${ttlDays}d\n`;
+                    }
+                    catch (e) { /* never fail maintenance on this */ }
                     db.checkpoint();
                     text += `- Checkpointed WAL\n`;
                     const stats = db.getStats();