wyrm-mcp 7.3.2 → 7.3.3

package/dist/analytics.js

@@ -1,7 +1,43 @@
-const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;constructor(_){this.db=_,this.batchBuffer=[],this.initTables(),this.insertStmt=this.db.prepare(`
+/**
+ * Wyrm Analytics — Persistent Usage Tracking & Cost Monitoring
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ * @module analytics
+ * @version 3.2.0
+ */
+// ==================== CONSTANTS ====================
+/** Claude Sonnet pricing per 1M tokens */
+const COST_PER_MILLION_INPUT = 3;
+const COST_PER_MILLION_OUTPUT = 15;
+const BUFFER_FLUSH_THRESHOLD = 50;
+const FLUSH_INTERVAL_MS = 30_000;
+const DEFAULT_RETAIN_DAYS = 90;
+// ==================== ANALYTICS CLASS ====================
+export class WyrmAnalytics {
+    db;
+    insertStmt;
+    batchBuffer;
+    flushInterval;
+    constructor(db) {
+        this.db = db;
+        this.batchBuffer = [];
+        this.initTables();
+        this.insertStmt = this.db.prepare(`
       INSERT INTO usage_events (tool_name, tokens_in, tokens_out, cached, response_ms, success, error_message, timestamp)
       VALUES (@tool_name, @tokens_in, @tokens_out, @cached, @response_ms, @success, @error_message, @timestamp)
-    `),this.flushInterval=setInterval(()=>{this.flush()},3e4),this.flushInterval.unref&&this.flushInterval.unref()}initTables(){this.db.exec(`
+    `);
+        this.flushInterval = setInterval(() => {
+            this.flush();
+        }, FLUSH_INTERVAL_MS);
+        // Don't let the timer keep the process alive
+        if (this.flushInterval.unref) {
+            this.flushInterval.unref();
+        }
+    }
+    // ==================== SCHEMA ====================
+    initTables() {
+        this.db.exec(`
       CREATE TABLE IF NOT EXISTS usage_events (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         tool_name TEXT NOT NULL,
@@ -32,7 +68,59 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
       CREATE INDEX IF NOT EXISTS idx_usage_events_tool ON usage_events(tool_name);
       CREATE INDEX IF NOT EXISTS idx_usage_events_ts ON usage_events(timestamp);
       CREATE INDEX IF NOT EXISTS idx_cost_tracking_period ON cost_tracking(period);
-    `)}record(_){this.batchBuffer.push(_),this.batchBuffer.length>=50&&this.flush()}flush(){if(this.batchBuffer.length===0)return;const _=this.batchBuffer.splice(0);this.db.transaction(n=>{for(const o of n)this.insertStmt.run({tool_name:o.tool,tokens_in:o.tokens_in,tokens_out:o.tokens_out,cached:o.cached?1:0,response_ms:o.ms,success:o.success!==!1?1:0,error_message:o.error??null,timestamp:o.timestamp})})(_),this.updateCostTracking(_)}updateCostTracking(_){const s=new Map;for(const t of _){const e=t.timestamp.slice(0,7),r=`${e}:${t.tool}`;let a=s.get(r);a||(a={tool:t.tool,period:e,calls:0,tokens_in:0,tokens_out:0,cached:0,total_ms:0,errors:0},s.set(r,a)),a.calls++,a.tokens_in+=t.tokens_in,a.tokens_out+=t.tokens_out,t.cached&&a.cached++,a.total_ms+=t.ms,t.success===!1&&a.errors++}const n=this.db.prepare(`
+    `);
+    }
+    // ==================== RECORDING ====================
+    /** Record a single tool usage event */
+    record(event) {
+        this.batchBuffer.push(event);
+        if (this.batchBuffer.length >= BUFFER_FLUSH_THRESHOLD) {
+            this.flush();
+        }
+    }
+    /** Flush buffered events to disk */
+    flush() {
+        if (this.batchBuffer.length === 0)
+            return;
+        const events = this.batchBuffer.splice(0);
+        const insertMany = this.db.transaction((batch) => {
+            for (const event of batch) {
+                this.insertStmt.run({
+                    tool_name: event.tool,
+                    tokens_in: event.tokens_in,
+                    tokens_out: event.tokens_out,
+                    cached: event.cached ? 1 : 0,
+                    response_ms: event.ms,
+                    success: event.success !== false ? 1 : 0,
+                    error_message: event.error ?? null,
+                    timestamp: event.timestamp,
+                });
+            }
+        });
+        insertMany(events);
+        this.updateCostTracking(events);
+    }
+    /** Update cost_tracking aggregates from a batch of events */
+    updateCostTracking(events) {
+        const groups = new Map();
+        for (const event of events) {
+            const period = event.timestamp.slice(0, 7); // YYYY-MM
+            const key = `${period}:${event.tool}`;
+            let group = groups.get(key);
+            if (!group) {
+                group = { tool: event.tool, period, calls: 0, tokens_in: 0, tokens_out: 0, cached: 0, total_ms: 0, errors: 0 };
+                groups.set(key, group);
+            }
+            group.calls++;
+            group.tokens_in += event.tokens_in;
+            group.tokens_out += event.tokens_out;
+            if (event.cached)
+                group.cached++;
+            group.total_ms += event.ms;
+            if (event.success === false)
+                group.errors++;
+        }
+        const upsertStmt = this.db.prepare(`
       INSERT INTO cost_tracking (period, tool_name, call_count, total_tokens_in, total_tokens_out, cached_count, avg_response_ms, error_count, estimated_cost_usd, updated_at)
       VALUES (@period, @tool_name, @call_count, @total_tokens_in, @total_tokens_out, @cached_count, @avg_response_ms, @error_count, @estimated_cost_usd, datetime('now'))
       ON CONFLICT(period, tool_name) DO UPDATE SET
@@ -44,7 +132,35 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
         error_count = error_count + @error_count,
         estimated_cost_usd = estimated_cost_usd + @estimated_cost_usd,
         updated_at = datetime('now')
-    `);this.db.transaction(t=>{for(const e of t.values()){const r=this.estimateCost(e.tokens_in,e.tokens_out);n.run({period:e.period,tool_name:e.tool,call_count:e.calls,total_tokens_in:e.tokens_in,total_tokens_out:e.tokens_out,cached_count:e.cached,avg_response_ms:e.calls>0?e.total_ms/e.calls:0,error_count:e.errors,estimated_cost_usd:r})}})(s)}dashboard(_=30){this.flush();const s=new Date;s.setDate(s.getDate()-_);const n=s.toISOString().slice(0,10),o=new Date().toISOString().slice(0,10),t=this.db.prepare(`
+    `);
+        const upsertMany = this.db.transaction((entries) => {
+            for (const group of entries.values()) {
+                const cost = this.estimateCost(group.tokens_in, group.tokens_out);
+                upsertStmt.run({
+                    period: group.period,
+                    tool_name: group.tool,
+                    call_count: group.calls,
+                    total_tokens_in: group.tokens_in,
+                    total_tokens_out: group.tokens_out,
+                    cached_count: group.cached,
+                    avg_response_ms: group.calls > 0 ? group.total_ms / group.calls : 0,
+                    error_count: group.errors,
+                    estimated_cost_usd: cost,
+                });
+            }
+        });
+        upsertMany(groups);
+    }
+    // ==================== QUERIES ====================
+    /** Get dashboard summary for a time period */
+    dashboard(days = 30) {
+        // Ensure buffered data is included
+        this.flush();
+        const start = new Date();
+        start.setDate(start.getDate() - days);
+        const startStr = start.toISOString().slice(0, 10);
+        const endStr = new Date().toISOString().slice(0, 10);
+        const summary = this.db.prepare(`
       SELECT
         COUNT(*) AS total_calls,
         COUNT(DISTINCT tool_name) AS unique_tools,
@@ -61,7 +177,8 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
         END AS error_rate
       FROM usage_events
       WHERE timestamp >= @start
-    `).get({start:n}),e=this.db.prepare(`
+    `).get({ start: startStr });
+        const top_tools = this.db.prepare(`
       SELECT
         tool_name AS tool,
         COUNT(*) AS calls,
@@ -71,7 +188,8 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
       GROUP BY tool_name
       ORDER BY calls DESC
       LIMIT 10
-    `).all({start:n}),r=this.db.prepare(`
+    `).all({ start: startStr });
+        const daily = this.db.prepare(`
       SELECT
         DATE(timestamp) AS date,
         COUNT(*) AS calls,
@@ -81,7 +199,31 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
       WHERE timestamp >= @start
       GROUP BY DATE(timestamp)
       ORDER BY date ASC
-    `).all({start:n}),a=this.estimateCost(t.total_tokens_in,t.total_tokens_out);return{period:{start:n,end:o},summary:{total_calls:t.total_calls,unique_tools:t.unique_tools,total_tokens_in:t.total_tokens_in,total_tokens_out:t.total_tokens_out,cache_hit_rate:t.cache_hit_rate,avg_response_ms:t.avg_response_ms,error_rate:t.error_rate,estimated_cost_usd:a},top_tools:e,daily:r}}toolBreakdown(_,s=30){this.flush();const n=new Date;n.setDate(n.getDate()-s);const o=n.toISOString().slice(0,10),t=this.db.prepare(`
+    `).all({ start: startStr });
+        const estimated_cost_usd = this.estimateCost(summary.total_tokens_in, summary.total_tokens_out);
+        return {
+            period: { start: startStr, end: endStr },
+            summary: {
+                total_calls: summary.total_calls,
+                unique_tools: summary.unique_tools,
+                total_tokens_in: summary.total_tokens_in,
+                total_tokens_out: summary.total_tokens_out,
+                cache_hit_rate: summary.cache_hit_rate,
+                avg_response_ms: summary.avg_response_ms,
+                error_rate: summary.error_rate,
+                estimated_cost_usd,
+            },
+            top_tools,
+            daily,
+        };
+    }
+    /** Get per-tool breakdown */
+    toolBreakdown(toolName, days = 30) {
+        this.flush();
+        const start = new Date();
+        start.setDate(start.getDate() - days);
+        const startStr = start.toISOString().slice(0, 10);
+        const stats = this.db.prepare(`
       SELECT
         COUNT(*) AS total_calls,
         COALESCE(ROUND(AVG(tokens_in), 2), 0) AS avg_tokens_in,
@@ -97,7 +239,8 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
         END AS error_rate
       FROM usage_events
       WHERE tool_name = @tool AND timestamp >= @start
-    `).get({tool:_,start:o}),e=this.db.prepare(`
+    `).get({ tool: toolName, start: startStr });
+        const daily = this.db.prepare(`
       SELECT
         DATE(timestamp) AS date,
         COUNT(*) AS calls
@@ -105,7 +248,23 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
       WHERE tool_name = @tool AND timestamp >= @start
       GROUP BY DATE(timestamp)
       ORDER BY date ASC
-    `).all({tool:_,start:o});return{tool:_,total_calls:t.total_calls,avg_tokens_in:t.avg_tokens_in,avg_tokens_out:t.avg_tokens_out,avg_response_ms:t.avg_response_ms,cache_hit_rate:t.cache_hit_rate,error_rate:t.error_rate,daily:e}}costReport(_){this.flush();const s=_??new Date().toISOString().slice(0,7),n=this.db.prepare(`
+    `).all({ tool: toolName, start: startStr });
+        return {
+            tool: toolName,
+            total_calls: stats.total_calls,
+            avg_tokens_in: stats.avg_tokens_in,
+            avg_tokens_out: stats.avg_tokens_out,
+            avg_response_ms: stats.avg_response_ms,
+            cache_hit_rate: stats.cache_hit_rate,
+            error_rate: stats.error_rate,
+            daily,
+        };
+    }
+    /** Get cost estimate for a period */
+    costReport(period) {
+        this.flush();
+        const targetPeriod = period ?? new Date().toISOString().slice(0, 7);
+        const tools = this.db.prepare(`
       SELECT
         tool_name AS tool,
         call_count AS calls,
@@ -115,7 +274,35 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
       FROM cost_tracking
       WHERE period = @period
       ORDER BY estimated_cost_usd DESC
-    `).all({period:s}),o=n.reduce((d,T)=>d+T.cost_usd,0),t=new Date,e=parseInt(s.slice(0,4),10),r=parseInt(s.slice(5,7),10)-1,a=new Date(e,r,1),l=new Date(e,r+1,0).getDate(),u=Math.max(1,Math.ceil((t.getTime()-a.getTime())/(1e3*60*60*24))),E=Math.min(u,l),i=l>0?Math.round(o/E*l*100)/100:o;return{period:s,tools:n,total_cost_usd:Math.round(o*100)/100,projected_monthly_usd:i}}cleanup(_=90){this.flush();const s=new Date;s.setDate(s.getDate()-_);const n=s.toISOString().slice(0,10),o=this.db.prepare(`
+    `).all({ period: targetPeriod });
+        const total_cost_usd = tools.reduce((sum, t) => sum + t.cost_usd, 0);
+        // Project monthly cost based on days elapsed in the period
+        const now = new Date();
+        const periodYear = parseInt(targetPeriod.slice(0, 4), 10);
+        const periodMonth = parseInt(targetPeriod.slice(5, 7), 10) - 1;
+        const periodStart = new Date(periodYear, periodMonth, 1);
+        const periodEnd = new Date(periodYear, periodMonth + 1, 0); // last day of month
+        const totalDaysInMonth = periodEnd.getDate();
+        const elapsed = Math.max(1, Math.ceil((now.getTime() - periodStart.getTime()) / (1000 * 60 * 60 * 24)));
+        const daysToProject = Math.min(elapsed, totalDaysInMonth);
+        const projected_monthly_usd = totalDaysInMonth > 0
+            ? Math.round(((total_cost_usd / daysToProject) * totalDaysInMonth) * 100) / 100
+            : total_cost_usd;
+        return {
+            period: targetPeriod,
+            tools,
+            total_cost_usd: Math.round(total_cost_usd * 100) / 100,
+            projected_monthly_usd,
+        };
+    }
+    /** Clean up old events (retention policy) */
+    cleanup(retainDays = DEFAULT_RETAIN_DAYS) {
+        this.flush();
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - retainDays);
+        const cutoffStr = cutoff.toISOString().slice(0, 10);
+        // Aggregate old events into cost_tracking before deleting
+        const oldEvents = this.db.prepare(`
       SELECT
         STRFTIME('%Y-%m', timestamp) AS period,
         tool_name,
@@ -128,7 +315,8 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
       FROM usage_events
       WHERE timestamp < @cutoff
       GROUP BY STRFTIME('%Y-%m', timestamp), tool_name
-    `).all({cutoff:n}),t=this.db.prepare(`
+    `).all({ cutoff: cutoffStr });
+        const upsertStmt = this.db.prepare(`
       INSERT INTO cost_tracking (period, tool_name, call_count, total_tokens_in, total_tokens_out, cached_count, avg_response_ms, error_count, estimated_cost_usd, updated_at)
       VALUES (@period, @tool_name, @call_count, @total_tokens_in, @total_tokens_out, @cached_count, @avg_response_ms, @error_count, @estimated_cost_usd, datetime('now'))
       ON CONFLICT(period, tool_name) DO UPDATE SET
@@ -140,6 +328,41 @@ const S=3,p=15,h=50,A=3e4,N=90;class k{db;insertStmt;batchBuffer;flushInterval;c
         error_count = error_count + @error_count,
         estimated_cost_usd = estimated_cost_usd + @estimated_cost_usd,
         updated_at = datetime('now')
-    `);return{deleted:this.db.transaction(()=>{for(const c of o){const l=this.estimateCost(c.total_tokens_in,c.total_tokens_out);t.run({period:c.period,tool_name:c.tool_name,call_count:c.call_count,total_tokens_in:c.total_tokens_in,total_tokens_out:c.total_tokens_out,cached_count:c.cached_count,avg_response_ms:c.avg_response_ms,error_count:c.error_count,estimated_cost_usd:l})}return this.db.prepare(`
+    `);
+        const cleanupTxn = this.db.transaction(() => {
+            for (const row of oldEvents) {
+                const cost = this.estimateCost(row.total_tokens_in, row.total_tokens_out);
+                upsertStmt.run({
+                    period: row.period,
+                    tool_name: row.tool_name,
+                    call_count: row.call_count,
+                    total_tokens_in: row.total_tokens_in,
+                    total_tokens_out: row.total_tokens_out,
+                    cached_count: row.cached_count,
+                    avg_response_ms: row.avg_response_ms,
+                    error_count: row.error_count,
+                    estimated_cost_usd: cost,
+                });
+            }
+            const result = this.db.prepare(`
         DELETE FROM usage_events WHERE timestamp < @cutoff
-      `).run({cutoff:n}).changes})()}}shutdown(){clearInterval(this.flushInterval),this.flush()}estimateCost(_,s){const n=_/1e6*3,o=s/1e6*15;return Math.round((n+o)*1e6)/1e6}}export{k as WyrmAnalytics};
+      `).run({ cutoff: cutoffStr });
+            return result.changes;
+        });
+        const deleted = cleanupTxn();
+        return { deleted };
+    }
+    /** Shutdown: flush remaining buffer and clear timer */
+    shutdown() {
+        clearInterval(this.flushInterval);
+        this.flush();
+    }
+    // ==================== HELPERS ====================
+    /** Estimate USD cost from token counts (Claude Sonnet rates) */
+    estimateCost(tokensIn, tokensOut) {
+        const inputCost = (tokensIn / 1_000_000) * COST_PER_MILLION_INPUT;
+        const outputCost = (tokensOut / 1_000_000) * COST_PER_MILLION_OUTPUT;
+        return Math.round((inputCost + outputCost) * 1_000_000) / 1_000_000;
+    }
+}
+//# sourceMappingURL=analytics.js.map

package/dist/attribution.js

@@ -1 +1,49 @@
-const e="legacy";function o(t){const n=typeof t=="string"?t.trim():"";return n!==""?n:e}function i(t){const n=t.agent_id??null,r=t.run_id??null;return{actor:n??o(t.actor),agent_id:n,run_id:r}}export{e as LEGACY_ACTOR,o as readActor,i as resolveAttribution};
+/**
+ * Wyrm attribution read helpers (v7 F2, T008).
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ *
+ * Migration 20 adds nullable `agent_id`/`run_id` attribution columns to 9
+ * tables. Every row written before v7 — and any v7 row written outside a fleet
+ * run — carries NULL attribution. Article VI: a v6.x DB must open under v7
+ * with 100% of its rows, and that history must stay legibly attributed, so at
+ * every READ SITE that surfaces attribution, NULL reads as actor='legacy'.
+ *
+ * Precedence when rendering "who did this" (the same order is documented in
+ * migration 20 next to the events.agent_id column):
+ *   1. agent_id     — machine identity (v7 fleet writes)
+ *   2. actor        — display identity (the existing 6.x column on
+ *                     events/audit_log; it is EXTENDED, never replaced)
+ *   3. LEGACY_ACTOR — 'legacy' (neither set: a pre-v7 row)
+ *
+ * Wire paths (eventsForPush, ingestRemoteEvent, replication) intentionally do
+ * NOT coalesce: NULL stays NULL in storage and on the wire so replication
+ * round-trips are byte-faithful. 'legacy' is a READ-TIME presentation value
+ * only — it is never written back to the database.
+ */
+/** What NULL attribution reads as at attribution-surfacing read sites. */
+export const LEGACY_ACTOR = 'legacy';
+/**
+ * Read a display actor from a nullable actor column.
+ * NULL/undefined/blank -> 'legacy'; anything else passes through trimmed.
+ */
+export function readActor(actor) {
+    const a = typeof actor === 'string' ? actor.trim() : '';
+    return a !== '' ? a : LEGACY_ACTOR;
+}
+/**
+ * Resolve the full attribution for one row using the documented precedence.
+ * Use this at any read site that surfaces who/which-run produced a row
+ * (failure_check verdicts, wyrm_stats view=failures, event displays).
+ */
+export function resolveAttribution(row) {
+    const agentId = row.agent_id ?? null;
+    const runId = row.run_id ?? null;
+    return {
+        actor: agentId ?? readActor(row.actor),
+        agent_id: agentId,
+        run_id: runId,
+    };
+}
+//# sourceMappingURL=attribution.js.map