wyrm-mcp 7.3.2 → 7.3.3

package/dist/tasks.js

@@ -1 +1,282 @@
-import{randomUUID as u}from"node:crypto";import{renderErrorResponse as p}from"./render.js";const l=300*1e3,f=3600*1e3,k=500,_=256;function h(e){return e!=null&&typeof e=="object"}function m(e){const t=e&&typeof e=="object"?e.task:void 0;if(t==null||typeof t!="object")return{requested:!1};const s=t.ttl;let a=l;return typeof s=="number"&&Number.isFinite(s)&&s>0&&(a=Math.min(Math.floor(s),f)),{requested:!0,ttlMs:a}}class w{tasks=new Map;create(t,s,a=Date.now()){this.evictExpired(a),this.tasks.size>=_&&this.evictOldest();const i=new Date(a).toISOString(),n={taskId:u(),status:"working",ttl:s,createdAt:i,lastUpdatedAt:i,pollInterval:k,tool:t,_createdAtMs:a};return this.tasks.set(n.taskId,n),n}settle(t,s,a,i,n=Date.now()){const r=this.tasks.get(t);r&&(r.status=s,r.lastUpdatedAt=new Date(n).toISOString(),a!==void 0&&(r.result=a),i!==void 0&&(r.statusMessage=i))}get(t,s=Date.now()){return this.evictExpired(s),this.tasks.get(t)}list(t=Date.now()){return this.evictExpired(t),[...this.tasks.values()].sort((s,a)=>a._createdAtMs-s._createdAtMs)}cancel(t,s=Date.now()){const a=this.tasks.get(t);return!a||a.status!=="working"?!1:(a.status="cancelled",a.lastUpdatedAt=new Date(s).toISOString(),!0)}size(){return this.tasks.size}evictExpired(t){for(const[s,a]of this.tasks)a.ttl!=null&&t-a._createdAtMs>a.ttl&&this.tasks.delete(s)}evictOldest(){const t=this.tasks.keys().next();t.done||this.tasks.delete(t.value)}}function A(e){const t={taskId:e.taskId,status:e.status,ttl:e.ttl,createdAt:e.createdAt,lastUpdatedAt:e.lastUpdatedAt};return e.pollInterval!==void 0&&(t.pollInterval=e.pollInterval),e.statusMessage!==void 0&&(t.statusMessage=e.statusMessage),t}function I(e,t){const s=h(e),a=m(t);return a.requested?{asTask:!0,ttlMs:a.ttlMs,capabilityNegotiated:s}:{asTask:!1,ttlMs:l,capabilityNegotiated:s}}async function g(e,t,s,a,i=Date.now()){if(!t.asTask)return{kind:"inline",result:await a()};const n=s.create(e,t.ttlMs,i);let r;try{r=await a()}catch(o){throw s.settle(n.taskId,"failed",void 0,String(o)),o}s.settle(n.taskId,r?.isError?"failed":"completed",r);const d=s.get(n.taskId,i)??n;return{kind:"task",createTask:{task:A(d)}}}function D(e,t,s=Date.now()){return e.get(t,s)?.result}const c=new Set(["wyrm_maintenance","wyrm_reindex","wyrm_vector_setup"]),y=new Set([...c,"wyrm_harvest","wyrm_auto_capture"]),T="WYRM_ADMIN_REQUIRED";function x(e=process.env){const t=e.WYRM_ADMIN;return t==="1"||t==="true"||t==="yes"}function S(e,t=process.env){return c.has(e)&&!x(t)}function E(e){return p({error:{code:T,message:`${e} is an admin-gated maintenance op (it rebuilds or vacuums the local memory store) and is disabled by default.`,retryable:!1},expected:`Set the WYRM_ADMIN=1 environment variable on the Wyrm MCP server process to enable ${e}, then call it again. This rejection is deterministic \u2014 do NOT retry unchanged. The operator controls this flag, not the agent: it exists so a stray fleet call cannot vacuum/reindex the store. The equivalent local CLI (\`wyrm maintenance\` / \`wyrm index rebuild\`) is always available.`})}export{c as ADMIN_GATED_TOOLS,k as DEFAULT_POLL_INTERVAL_MS,l as DEFAULT_TASK_TTL_MS,y as LONG_OP_TOOLS,_ as MAX_RETAINED_TASKS,f as MAX_TASK_TTL_MS,w as TaskStore,T as WYRM_ADMIN_REQUIRED_CODE,E as adminDeniedResponse,S as adminGateBlocks,x as adminGateOpen,h as clientSupportsTasks,m as readTaskAugmentation,I as resolveTaskGate,g as runLongOp,D as taskPayload,A as toWireTask};
+/**
+ * MCP Tasks (T037) — capability-gated, SYNCHRONOUS-fallback task lifecycle for
+ * the long ops of the tools that REMAIN on MCP (Article V: vendor-neutral,
+ * capability-gated; Article VII: admin-gated long ops are off by default).
+ *
+ * WHY this exists. Two of Wyrm's retained tools have ops that can run long on a
+ * large corpus and are the ones a curated client NEEDS on the MCP wire:
+ *   - wyrm_maintenance / wyrm_reindex / wyrm_vector_setup — the admin upkeep +
+ *     vector (re)build. This is the fix for the curated-client "can't reindex
+ *     the last 17% of vectors" wound — these stay on MCP precisely so a
+ *     resource-constrained client CAN drive a backfill from the agent.
+ *   - harvest / auto_capture extraction (modes of wyrm_capture) — corpus scans.
+ *
+ * HOW it composes with the SDK. The MCP Tasks RC's server-side `tools/call`
+ * augmentation works like this (server/index.js): when the request carries a
+ * `task` param, the SDK REQUIRES the CallTool handler to return a
+ * `CreateTaskResult` (`{task:{taskId,status,…}}`) — NOT a CallToolResult — and
+ * the actual payload is fetched later via `tasks/result`. That deferred-result
+ * machinery is the part the spec flags as not-yet-stable. Wyrm's faithful,
+ * "synchronous fallback until the RC stabilizes" implementation runs the op
+ * IMMEDIATELY and never truly defers:
+ *   1. Detect the client's `tasks` capability (negotiated at initialize) AND the
+ *      request's `task` augmentation param (`TaskAugmentedRequestParamsSchema`).
+ *   2. When BOTH are present: run the op SYNCHRONOUSLY, store the completed
+ *      CallToolResult, and return a `CreateTaskResult` whose task is already
+ *      `completed` (or `failed`). The client fetches the payload via
+ *      `tasks/result` (served from the store). No work is deferred — the op
+ *      already ran — so a client that never polls still triggered the op.
+ *   3. Otherwise (the default for every client today, and any client that omits
+ *      `task`): run the op inline and return the CallToolResult directly. This
+ *      is the synchronous fallback and the always-correct path; no data lost.
+ *
+ * The whole module is deterministic and no-network (Article III): the only
+ * non-determinism is the task id + timestamps, confined to the task record and
+ * the CreateTaskResult envelope — never the stored CallToolResult bytes.
+ */
+import { randomUUID } from 'node:crypto';
+import { renderErrorResponse } from './render.js';
+/** Default retention for a completed task record (ms). */
+export const DEFAULT_TASK_TTL_MS = 5 * 60 * 1000; // 5 minutes
+/** Hard cap so a hostile/buggy `task.ttl` can never pin memory (Article VII). */
+export const MAX_TASK_TTL_MS = 60 * 60 * 1000; // 1 hour
+/** Suggested client poll cadence advertised on the task record (ms). */
+export const DEFAULT_POLL_INTERVAL_MS = 500;
+/** Hard cap on retained task records — bounds memory; oldest evicted first. */
+export const MAX_RETAINED_TASKS = 256;
+/**
+ * True when the connected client advertised the `tasks` capability. Vendor-
+ * neutral (Article V): reads the negotiated capability, never a client name.
+ */
+export function clientSupportsTasks(tasksCapability) {
+    return tasksCapability != null && typeof tasksCapability === 'object';
+}
+/**
+ * The `task` augmentation a client attaches to a CallTool request when it wants
+ * a task created (`TaskAugmentedRequestParamsSchema.task`). Reads it off the
+ * raw request params; returns the requested ttl (clamped) or null when absent.
+ * Total on adversarial input — never throws (an invalid ttl degrades to the
+ * default, a missing augmentation yields null = synchronous path).
+ */
+export function readTaskAugmentation(params) {
+    const task = params && typeof params === 'object' ? params.task : undefined;
+    if (task == null || typeof task !== 'object')
+        return { requested: false };
+    const rawTtl = task.ttl;
+    let ttlMs = DEFAULT_TASK_TTL_MS;
+    if (typeof rawTtl === 'number' && Number.isFinite(rawTtl) && rawTtl > 0) {
+        ttlMs = Math.min(Math.floor(rawTtl), MAX_TASK_TTL_MS);
+    }
+    return { requested: true, ttlMs };
+}
+/**
+ * In-memory task store. Single-process (the stdio server is one process); the
+ * MCP RC has no persistence requirement and a restarted server starts clean.
+ * Bounded by MAX_RETAINED_TASKS with oldest-first eviction.
+ */
+export class TaskStore {
+    tasks = new Map();
+    /** Create a `working` task record and return its id. */
+    create(tool, ttlMs, nowMs = Date.now()) {
+        this.evictExpired(nowMs);
+        if (this.tasks.size >= MAX_RETAINED_TASKS)
+            this.evictOldest();
+        const iso = new Date(nowMs).toISOString();
+        const record = {
+            taskId: randomUUID(),
+            status: 'working',
+            ttl: ttlMs,
+            createdAt: iso,
+            lastUpdatedAt: iso,
+            pollInterval: DEFAULT_POLL_INTERVAL_MS,
+            tool,
+            _createdAtMs: nowMs,
+        };
+        this.tasks.set(record.taskId, record);
+        return record;
+    }
+    /** Mark a task terminal (completed/failed/cancelled) with its result. */
+    settle(taskId, status, result, statusMessage, nowMs = Date.now()) {
+        const record = this.tasks.get(taskId);
+        if (!record)
+            return;
+        record.status = status;
+        record.lastUpdatedAt = new Date(nowMs).toISOString();
+        if (result !== undefined)
+            record.result = result;
+        if (statusMessage !== undefined)
+            record.statusMessage = statusMessage;
+    }
+    /** Read a task record (after evicting any whose ttl has elapsed). */
+    get(taskId, nowMs = Date.now()) {
+        this.evictExpired(nowMs);
+        return this.tasks.get(taskId);
+    }
+    /** List the live task records, newest first (after eviction). */
+    list(nowMs = Date.now()) {
+        this.evictExpired(nowMs);
+        return [...this.tasks.values()].sort((a, b) => b._createdAtMs - a._createdAtMs);
+    }
+    /** Cancel a still-working task; no-op if unknown or already terminal. */
+    cancel(taskId, nowMs = Date.now()) {
+        const record = this.tasks.get(taskId);
+        if (!record || record.status !== 'working')
+            return false;
+        record.status = 'cancelled';
+        record.lastUpdatedAt = new Date(nowMs).toISOString();
+        return true;
+    }
+    size() {
+        return this.tasks.size;
+    }
+    /** Drop records whose (createdAt + ttl) is in the past. */
+    evictExpired(nowMs) {
+        for (const [id, rec] of this.tasks) {
+            if (rec.ttl != null && nowMs - rec._createdAtMs > rec.ttl)
+                this.tasks.delete(id);
+        }
+    }
+    /** Drop the single oldest record (Map preserves insertion order). */
+    evictOldest() {
+        const oldest = this.tasks.keys().next();
+        if (!oldest.done)
+            this.tasks.delete(oldest.value);
+    }
+}
+/** Project a TaskRecord to the on-wire shape (strips Wyrm internals). */
+export function toWireTask(record) {
+    const wire = {
+        taskId: record.taskId,
+        status: record.status,
+        ttl: record.ttl,
+        createdAt: record.createdAt,
+        lastUpdatedAt: record.lastUpdatedAt,
+    };
+    if (record.pollInterval !== undefined)
+        wire.pollInterval = record.pollInterval;
+    if (record.statusMessage !== undefined)
+        wire.statusMessage = record.statusMessage;
+    return wire;
+}
+/**
+ * Resolve whether a given CallTool should run as a task.
+ *
+ * The decisive signal is the request's `task` augmentation, because the MCP SDK
+ * (server/index.js) UNCONDITIONALLY requires the CallTool handler to return a
+ * `CreateTaskResult` whenever `params.task` is present — it does NOT consult the
+ * negotiated client capability. So a request bearing `task` MUST run the task
+ * path or the SDK rejects the response with -32602. The negotiated `tasks`
+ * capability is recorded as advisory context (a well-behaved client only sends
+ * `task` after negotiating it), not a suppressor — suppressing it here would
+ * desync from the SDK and crash the very clients the gate is meant to serve.
+ *
+ * No `task` augmentation → the synchronous fallback (a normal CallToolResult),
+ * the default for every client today.
+ */
+export function resolveTaskGate(tasksCapability, params) {
+    const capabilityNegotiated = clientSupportsTasks(tasksCapability);
+    const aug = readTaskAugmentation(params);
+    if (aug.requested)
+        return { asTask: true, ttlMs: aug.ttlMs, capabilityNegotiated };
+    return { asTask: false, ttlMs: DEFAULT_TASK_TTL_MS, capabilityNegotiated };
+}
+/**
+ * Run a long op under the task gate. ALWAYS runs the op SYNCHRONOUSLY (no
+ * deferral) regardless of the gate — the op having run is the spine.
+ *
+ *  - gate.asTask=false → returns {kind:'inline'} with the CallToolResult; the
+ *    dispatcher returns it directly. This is the synchronous fallback.
+ *  - gate.asTask=true  → stores the completed CallToolResult and returns
+ *    {kind:'task'} with a CreateTaskResult whose task is already `completed`
+ *    (or `failed`). The dispatcher returns the CreateTaskResult on the wire;
+ *    the client fetches the payload via tasks/result (served from the store).
+ *
+ * A throwing op records a `failed` task and re-throws (the dispatcher's error
+ * boundary owns the wire error shape — we never swallow it).
+ */
+export async function runLongOp(tool, gate, store, run, nowMs = Date.now()) {
+    if (!gate.asTask) {
+        return { kind: 'inline', result: await run() };
+    }
+    const record = store.create(tool, gate.ttlMs, nowMs);
+    let result;
+    try {
+        result = await run();
+    }
+    catch (err) {
+        store.settle(record.taskId, 'failed', undefined, String(err));
+        throw err;
+    }
+    store.settle(record.taskId, result?.isError ? 'failed' : 'completed', result);
+    // re-read so the wire task reflects the settled status/timestamp
+    const settled = store.get(record.taskId, nowMs) ?? record;
+    return { kind: 'task', createTask: { task: toWireTask(settled) } };
+}
+/**
+ * Fetch the stored CallToolResult payload for a completed task (the
+ * tasks/result backend). Returns undefined for an unknown/expired/unsettled id.
+ */
+export function taskPayload(store, taskId, nowMs = Date.now()) {
+    return store.get(taskId, nowMs)?.result;
+}
+// ── Admin gate (Article VII: destructive long ops off by default) ───────────
+//
+// `wyrm_maintenance` is destructiveHint:true and `wyrm_reindex`/
+// `wyrm_vector_setup` rebuild the embedding store — operations a stray fleet
+// agent should not be able to trigger over MCP unless the operator has opted
+// in. The gate is a single off-by-default env flag (`WYRM_ADMIN=1`), evaluated
+// per call so it can be flipped without a restart in tests. The tools STILL
+// remain on MCP (that is the whole point of T037 — the curated client must be
+// able to drive a reindex); the gate just requires the operator's intent.
+/** The admin-gated tools — the destructive/rebuild long ops on the wire. */
+export const ADMIN_GATED_TOOLS = new Set([
+    'wyrm_maintenance',
+    'wyrm_reindex',
+    'wyrm_vector_setup',
+]);
+/**
+ * The RESOLVED dispatcher names the MCP-Tasks affordance TARGETS — the long ops
+ * of tools that REMAIN on MCP (spec T037): the admin upkeep/vector tools (also
+ * WYRM_ADMIN-gated) + the extraction modes of wyrm_capture, which resolve
+ * through the noun shim to wyrm_harvest (mode=artifacts) / wyrm_auto_capture
+ * (mode=extract). Note: a task augmentation on ANY tool is still honored by the
+ * dispatcher (the SDK forces a CreateTaskResult whenever params.task is set) —
+ * this set documents where a task is actually USEFUL, not the only place the
+ * shape is produced.
+ */
+export const LONG_OP_TOOLS = new Set([
+    ...ADMIN_GATED_TOOLS,
+    'wyrm_harvest',
+    'wyrm_auto_capture',
+]);
+/** Machine-readable code for an admin-gate rejection (SEP-1303 family). */
+export const WYRM_ADMIN_REQUIRED_CODE = 'WYRM_ADMIN_REQUIRED';
+/** True when the operator has opted into admin-gated long ops. */
+export function adminGateOpen(env = process.env) {
+    const v = env.WYRM_ADMIN;
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/** True when `tool` is admin-gated and the operator has NOT opted in. */
+export function adminGateBlocks(tool, env = process.env) {
+    return ADMIN_GATED_TOOLS.has(tool) && !adminGateOpen(env);
+}
+/**
+ * The structured (SEP-1303-shaped) response for an admin-gate rejection.
+ * `isError:true` with a non-retryable {error,expected} body so a fleet subagent
+ * does not loop — the operator must set WYRM_ADMIN, not the agent.
+ */
+export function adminDeniedResponse(tool) {
+    return renderErrorResponse({
+        error: {
+            code: WYRM_ADMIN_REQUIRED_CODE,
+            message: `${tool} is an admin-gated maintenance op (it rebuilds or vacuums the local memory store) ` +
+                `and is disabled by default.`,
+            retryable: false,
+        },
+        expected: `Set the WYRM_ADMIN=1 environment variable on the Wyrm MCP server process to enable ${tool}, ` +
+            `then call it again. This rejection is deterministic — do NOT retry unchanged. The operator ` +
+            `controls this flag, not the agent: it exists so a stray fleet call cannot vacuum/reindex the ` +
+            `store. The equivalent local CLI (\`wyrm maintenance\` / \`wyrm index rebuild\`) is always available.`,
+    });
+}
+//# sourceMappingURL=tasks.js.map

package/dist/token-budget.js

@@ -1 +1,143 @@
-function h(){return{source:"approx-4cpt",count(t){return t?Math.ceil(t.length/4):0}}}function g(t,e){const c=e.alreadySeen??new Set,l=Math.max(0,e.reserved??0),d=Math.max(0,e.budget-l),a=[...t].sort((n,f)=>f.score-n.score),i=[],r=[];let u=0,s=0;for(const n of a){if(c.has(n.key)){r.push({item:n.item,key:n.key,reason:"seen",stubCost:n.stubCost}),s+=n.stubCost;continue}u+n.inlineCost<=d?(i.push(n.item),u+=n.inlineCost):(r.push({item:n.item,key:n.key,reason:"budget",stubCost:n.stubCost}),s+=n.stubCost)}return{inline:i,elided:r,tokensInline:u,tokensStubs:s,budget:e.budget}}const o=4096;function b(t){if(!t)return o;const e=t.toLowerCase();return e.includes("mythos")||e.includes("opus")?4096:e.includes("sonnet")?8192:e.includes("haiku")?12288:e==="claude-code"||e.startsWith("claude-code")||e==="claude-desktop"||e.startsWith("claude-desktop")?4096:e==="cursor"||e.includes("cursor")||e==="windsurf"||e.includes("windsurf")||e==="zed"||e.includes("zed")||e==="continue"||e.includes("continue")||e==="copilot"||e.includes("copilot")?8192:o}function k(t){if(t.callArg&&t.callArg>0)return t.callArg;if(t.envValue){const e=parseInt(t.envValue,10);if(!Number.isNaN(e)&&e>0)return e}return b(t.clientName)}export{g as applyBudget,b as budgetForClient,h as makeEstimator,k as resolveBudget};
+/**
+ * Token budget primitive (spec 014).
+ *
+ * Pure functions over typed items. No DB, no I/O. Two responsibilities:
+ *
+ * 1. Estimate the token cost of a string. Phase 1 uses a deterministic
+ *    4-characters-per-token approximation (round up — slightly
+ *    over-counts so we stay under budget). A future spec replaces this
+ *    with `tiktoken` for exact `cl100k_base` counts.
+ *
+ * 2. Apply a token budget to a ranked list of items: rank-by-score,
+ *    fill until budget, elide the rest as stubs. Items already shown in
+ *    the session are demoted to a "seen" elision bucket.
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ */
+export function makeEstimator() {
+    // Phase 1: 4-chars-per-token approximation. English averages ~4 cpt
+    // in cl100k_base; code is closer to 3. Wyrm content is mixed; rounding
+    // up keeps us under budget rather than over.
+    return {
+        source: 'approx-4cpt',
+        count(text) {
+            if (!text)
+                return 0;
+            return Math.ceil(text.length / 4);
+        },
+    };
+}
+/**
+ * Apply a token budget to a list of candidate items.
+ *
+ * Algorithm:
+ *   1. Sort by score desc (stable on tie).
+ *   2. For each item:
+ *        - If key is in `alreadySeen`, elide with reason='seen', count stubCost.
+ *        - Else if inlineCost fits in remaining budget, render inline.
+ *        - Else elide with reason='budget', count stubCost.
+ *   3. Return both lists + token totals.
+ *
+ * Stubs are always emitted (operator can deref via wyrm_recall). The
+ * `reserved` knob lets callers carve out budget for a stable preamble
+ * block before items start consuming.
+ */
+export function applyBudget(items, opts) {
+    const seen = opts.alreadySeen ?? new Set();
+    const reserved = Math.max(0, opts.reserved ?? 0);
+    const usable = Math.max(0, opts.budget - reserved);
+    // Stable sort by score desc. JavaScript Array.prototype.sort is stable
+    // since ES2019 — relied on here for tie-break determinism.
+    const sorted = [...items].sort((a, b) => b.score - a.score);
+    const inline = [];
+    const elided = [];
+    let tokensInline = 0;
+    let tokensStubs = 0;
+    for (const candidate of sorted) {
+        if (seen.has(candidate.key)) {
+            elided.push({
+                item: candidate.item,
+                key: candidate.key,
+                reason: 'seen',
+                stubCost: candidate.stubCost,
+            });
+            tokensStubs += candidate.stubCost;
+            continue;
+        }
+        if (tokensInline + candidate.inlineCost <= usable) {
+            inline.push(candidate.item);
+            tokensInline += candidate.inlineCost;
+        }
+        else {
+            elided.push({
+                item: candidate.item,
+                key: candidate.key,
+                reason: 'budget',
+                stubCost: candidate.stubCost,
+            });
+            tokensStubs += candidate.stubCost;
+        }
+    }
+    return {
+        inline,
+        elided,
+        tokensInline,
+        tokensStubs,
+        budget: opts.budget,
+    };
+}
+// -----------------------------------------------------------------------------
+// Model-tier defaults (D1: auto-detect from MCP clientInfo.name; spec 014)
+// -----------------------------------------------------------------------------
+const FALLBACK_BUDGET = 4096;
+/**
+ * Map a known MCP client name to its sensible default context budget.
+ * Precedence at call site: call-arg > env > auto > fallback.
+ */
+export function budgetForClient(clientName) {
+    if (!clientName)
+        return FALLBACK_BUDGET;
+    const n = clientName.toLowerCase();
+    // Anthropic surfaces
+    if (n.includes('mythos'))
+        return 4096; // future-proof — same as opus until we know
+    if (n.includes('opus'))
+        return 4096;
+    if (n.includes('sonnet'))
+        return 8192;
+    if (n.includes('haiku'))
+        return 12288;
+    if (n === 'claude-code' || n.startsWith('claude-code'))
+        return 4096; // assume opus
+    if (n === 'claude-desktop' || n.startsWith('claude-desktop'))
+        return 4096;
+    // Other clients — assume mid-tier
+    if (n === 'cursor' || n.includes('cursor'))
+        return 8192;
+    if (n === 'windsurf' || n.includes('windsurf'))
+        return 8192;
+    if (n === 'zed' || n.includes('zed'))
+        return 8192;
+    if (n === 'continue' || n.includes('continue'))
+        return 8192;
+    if (n === 'copilot' || n.includes('copilot'))
+        return 8192;
+    return FALLBACK_BUDGET;
+}
+/**
+ * Resolve the effective budget for a context_build call.
+ *
+ *   call-arg > WYRM_CONTEXT_TOKEN_BUDGET env > clientName-derived > FALLBACK
+ */
+export function resolveBudget(opts) {
+    if (opts.callArg && opts.callArg > 0)
+        return opts.callArg;
+    if (opts.envValue) {
+        const n = parseInt(opts.envValue, 10);
+        if (!Number.isNaN(n) && n > 0)
+            return n;
+    }
+    return budgetForClient(opts.clientName);
+}
+//# sourceMappingURL=token-budget.js.map

package/dist/tool-analytics.js

@@ -1,8 +1,84 @@
-class _{db;constructor(t){this.db=t}static summarizeArgs(t){if(t==null)return"";if(typeof t!="object")return String(t).slice(0,100);try{const s=t,e={};for(const[a,o]of Object.entries(s)){if(o==null){e[a]=null;continue}typeof o=="string"?e[a]=o.length>100?`<${o.length}ch>`:o:typeof o=="number"||typeof o=="boolean"?e[a]=o:Array.isArray(o)?e[a]=`<array:${o.length}>`:typeof o=="object"&&(e[a]="<object>")}return JSON.stringify(e).slice(0,500)}catch{return"<unserializable>"}}log(t){try{this.db.prepare(`
+/**
+ * Tool Call Analytics — Wyrm watches Wyrm.
+ *
+ * Every wyrm_* tool call gets logged here: tool name, args summary,
+ * success/failure, latency, optional project context. From this stream
+ * we derive:
+ *
+ *  - usage histogram (which tools are most-called)
+ *  - error rate per tool
+ *  - p50/p95 latency per tool
+ *  - args-pattern summarisation (what args do callers pass)
+ *  - recall→action correlation (was a returned memory followed by an action?)
+ *
+ * Operators see "Claude calls wyrm_recall 80% of the time but the result
+ * is unused 60% of the time → ranking is bad → tune retrieval".
+ *
+ * Privacy: args_summary is truncated and stripped of values longer than
+ * 100 chars per field — we keep keys and short values for pattern
+ * analysis, never full payloads.
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ */
+export class ToolAnalytics {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** Truncate args for logging — drop long values, keep keys + short values. */
+    static summarizeArgs(args) {
+        if (args == null)
+            return '';
+        if (typeof args !== 'object')
+            return String(args).slice(0, 100);
+        try {
+            const o = args;
+            const out = {};
+            for (const [k, v] of Object.entries(o)) {
+                if (v == null) {
+                    out[k] = null;
+                    continue;
+                }
+                if (typeof v === 'string') {
+                    out[k] = v.length > 100 ? `<${v.length}ch>` : v;
+                }
+                else if (typeof v === 'number' || typeof v === 'boolean') {
+                    out[k] = v;
+                }
+                else if (Array.isArray(v)) {
+                    out[k] = `<array:${v.length}>`;
+                }
+                else if (typeof v === 'object') {
+                    out[k] = `<object>`;
+                }
+            }
+            return JSON.stringify(out).slice(0, 500);
+        }
+        catch {
+            return '<unserializable>';
+        }
+    }
+    /** Log a single tool call. Designed to be fire-and-forget — swallows errors
+     * so logging never breaks the tool's own response path. */
+    log(input) {
+        try {
+            this.db.prepare(`
         INSERT INTO tool_call_log
           (tool_name, project_id, args_summary, success, error_message, latency_ms)
         VALUES (?, ?, ?, ?, ?, ?)
-      `).run(t.tool_name,t.project_id??null,t.args!==void 0?_.summarizeArgs(t.args):null,t.success?1:0,t.error_message??null,Math.max(0,Math.round(t.latency_ms)))}catch{}}usageStats(t){const s=t?.days??30,e=t?.limit??100,a=this.db.prepare(`
+      `).run(input.tool_name, input.project_id ?? null, input.args !== undefined ? ToolAnalytics.summarizeArgs(input.args) : null, input.success ? 1 : 0, input.error_message ?? null, Math.max(0, Math.round(input.latency_ms)));
+        }
+        catch {
+            // Logging must never break the tool path.
+        }
+    }
+    /** Per-tool usage statistics over the last `days` days (default 30). */
+    usageStats(opts) {
+        const days = opts?.days ?? 30;
+        const limit = opts?.limit ?? 100;
+        // Get aggregate stats per tool
+        const aggregates = this.db.prepare(`
       SELECT
         tool_name,
         COUNT(*) AS total,
@@ -14,18 +90,49 @@ class _{db;constructor(t){this.db=t}static summarizeArgs(t){if(t==null)return"";
       GROUP BY tool_name
       ORDER BY total DESC
       LIMIT ?
-    `).all(s,e),o=[];for(const l of a){const c=this.db.prepare(`
+    `).all(days, limit);
+        // For each tool, compute p50/p95 latency (small enough to do in-process)
+        const results = [];
+        for (const a of aggregates) {
+            const latencies = this.db.prepare(`
         SELECT latency_ms FROM tool_call_log
         WHERE tool_name = ?
           AND called_at >= datetime('now', '-' || ? || ' days')
         ORDER BY latency_ms
-      `).all(l.tool_name,s).map(r=>r.latency_ms),n=(r,u)=>{if(r.length===0)return 0;const i=Math.min(r.length-1,Math.floor((r.length-1)*u));return r[i]};o.push({tool_name:l.tool_name,total:l.total,success_count:l.success_count,error_count:l.error_count,error_rate:l.total>0?Math.round(l.error_count/l.total*1e3)/1e3:0,p50_ms:n(c,.5),p95_ms:n(c,.95),last_called:l.last_called})}return o}recentErrors(t,s=10){return this.db.prepare(`
+      `).all(a.tool_name, days).map(r => r.latency_ms);
+            const p = (arr, pct) => {
+                if (arr.length === 0)
+                    return 0;
+                const idx = Math.min(arr.length - 1, Math.floor((arr.length - 1) * pct));
+                return arr[idx];
+            };
+            results.push({
+                tool_name: a.tool_name,
+                total: a.total,
+                success_count: a.success_count,
+                error_count: a.error_count,
+                error_rate: a.total > 0 ? Math.round((a.error_count / a.total) * 1000) / 1000 : 0,
+                p50_ms: p(latencies, 0.5),
+                p95_ms: p(latencies, 0.95),
+                last_called: a.last_called,
+            });
+        }
+        return results;
+    }
+    /** Recent error sample for a tool — useful when error_rate > 0. */
+    recentErrors(toolName, limit = 10) {
+        return this.db.prepare(`
       SELECT called_at, error_message, args_summary
       FROM tool_call_log
       WHERE tool_name = ? AND success = 0
       ORDER BY called_at DESC
       LIMIT ?
-    `).all(t,s)}overview(t){const s=t?.days??30,e=this.db.prepare(`
+    `).all(toolName, limit);
+    }
+    /** Total volume + success rate over the whole window. */
+    overview(opts) {
+        const days = opts?.days ?? 30;
+        const row = this.db.prepare(`
       SELECT
         COUNT(*) AS total,
         SUM(success) AS success_count,
@@ -33,7 +140,22 @@ class _{db;constructor(t){this.db=t}static summarizeArgs(t){if(t==null)return"";
         COUNT(DISTINCT tool_name) AS distinct_tools
       FROM tool_call_log
       WHERE called_at >= datetime('now', '-' || ? || ' days')
-    `).get(s);return{days:s,total_calls:e.total||0,success_count:e.success_count||0,error_count:e.error_count||0,success_rate:e.total>0?Math.round(e.success_count/e.total*1e3)/1e3:0,distinct_tools:e.distinct_tools||0}}prune(t=90){return this.db.prepare(`
+    `).get(days);
+        return {
+            days,
+            total_calls: row.total || 0,
+            success_count: row.success_count || 0,
+            error_count: row.error_count || 0,
+            success_rate: row.total > 0 ? Math.round((row.success_count / row.total) * 1000) / 1000 : 0,
+            distinct_tools: row.distinct_tools || 0,
+        };
+    }
+    /** Prune rows older than N days. Returns count deleted. Run via maintenance. */
+    prune(olderThanDays = 90) {
+        return this.db.prepare(`
       DELETE FROM tool_call_log
       WHERE called_at < datetime('now', '-' || ? || ' days')
-    `).run(t).changes}}export{_ as ToolAnalytics};
+    `).run(olderThanDays).changes;
+    }
+}
+//# sourceMappingURL=tool-analytics.js.map