@papyruslabsai/seshat-mcp 0.3.2 → 0.3.3

package/dist/index.d.ts

@@ -13,7 +13,7 @@
  * Single-project mode (default):
  *   When SESHAT_PROJECTS is not set, loads from CWD. No `project` param needed.
  *
- * Tools (8 core + 8 interpretation functors + 1 meta):
+ * Tools (8 core + 9 interpretation functors + 1 meta):
  *   list_projects       — Show loaded projects with entity counts
  *   query_entities      — Search entities by name, layer, module, language
  *   get_entity          — Full 9D coordinate dump for one entity
@@ -31,6 +31,7 @@
  *   get_test_coverage     — Entities exercised by tests vs uncovered
  *   get_optimal_context   — Greedy knapsack: max relevance per token for LLM context
  *   estimate_task_cost    — Pre-work token burn projection from blast radius + source tokens
+ *   report_actual_burn    — Close calibration loop: actual tokens vs prediction, drift stats
  *
  * Usage:
  *   npx @papyruslabs/seshat-mcp                           # single project (CWD)

package/dist/index.js

@@ -13,7 +13,7 @@
  * Single-project mode (default):
  *   When SESHAT_PROJECTS is not set, loads from CWD. No `project` param needed.
  *
- * Tools (8 core + 8 interpretation functors + 1 meta):
+ * Tools (8 core + 9 interpretation functors + 1 meta):
  *   list_projects       — Show loaded projects with entity counts
  *   query_entities      — Search entities by name, layer, module, language
  *   get_entity          — Full 9D coordinate dump for one entity
@@ -31,6 +31,7 @@
  *   get_test_coverage     — Entities exercised by tests vs uncovered
  *   get_optimal_context   — Greedy knapsack: max relevance per token for LLM context
  *   estimate_task_cost    — Pre-work token burn projection from blast radius + source tokens
+ *   report_actual_burn    — Close calibration loop: actual tokens vs prediction, drift stats
  *
  * Usage:
  *   npx @papyruslabs/seshat-mcp                           # single project (CWD)
@@ -44,7 +45,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { MultiLoader } from './loader.js';
 import { initTools, queryEntities, getEntity, getDependencies, getDataFlow, findByConstraint, getBlastRadius, listModules, getTopology, } from './tools/index.js';
-import { findDeadCode, findLayerViolations, getCouplingMetrics, getAuthMatrix, findErrorGaps, getTestCoverage, getOptimalContext, estimateTaskCost, } from './tools/functors.js';
+import { findDeadCode, findLayerViolations, getCouplingMetrics, getAuthMatrix, findErrorGaps, getTestCoverage, getOptimalContext, estimateTaskCost, reportActualBurn, } from './tools/functors.js';
 // ─── Project Discovery ───────────────────────────────────────────
 /**
  * Discover project directories from SESHAT_PROJECTS env var.
@@ -358,6 +359,45 @@ const TOOLS = [
             required: ['target_entities'],
         },
     },
+    {
+        name: 'report_actual_burn',
+        description: 'Close the calibration feedback loop: report actual token usage against a prior prediction from estimate_task_cost. Computes drift (actual - predicted) / predicted. Also supports listing recent predictions with aggregate calibration stats, or abandoning predictions for cancelled tasks.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                prediction_id: {
+                    type: 'string',
+                    description: 'The prediction ID returned by estimate_task_cost. Required for complete/abandon actions.',
+                },
+                actual_input_tokens: {
+                    type: 'number',
+                    description: 'Actual input tokens consumed (from LLM usage metadata).',
+                },
+                actual_output_tokens: {
+                    type: 'number',
+                    description: 'Actual output tokens consumed (from LLM usage metadata).',
+                },
+                actual_total_tokens: {
+                    type: 'number',
+                    description: 'Actual total tokens consumed (input + output).',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Model used (e.g. claude-opus-4-6, claude-sonnet-4-6).',
+                },
+                action: {
+                    type: 'string',
+                    enum: ['complete', 'abandon', 'list'],
+                    description: 'Action: "complete" reports actuals (default), "abandon" marks prediction as cancelled, "list" shows recent predictions with calibration stats.',
+                },
+                project: projectParam,
+                notes: {
+                    type: 'string',
+                    description: 'Optional notes about the task outcome.',
+                },
+            },
+        },
+    },
 ];
 // ─── Server Setup ─────────────────────────────────────────────────
 async function main() {
@@ -388,7 +428,7 @@ async function main() {
     }
     const server = new Server({
         name: serverLabel,
-        version: '0.3.2',
+        version: '0.3.3',
     }, {
         capabilities: {
             tools: {},
@@ -473,7 +513,10 @@ async function main() {
                     result = getOptimalContext(args);
                     break;
                 case 'estimate_task_cost':
-                    result = estimateTaskCost(args);
+                    result = await estimateTaskCost(args);
+                    break;
+                case 'report_actual_burn':
+                    result = await reportActualBurn(args);
                     break;
                 default:
                     result = { error: `Unknown tool: ${name}` };

package/dist/supabase.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Lightweight Supabase REST client for the calibration feedback loop.
+ *
+ * Uses Node 20+ native fetch — zero external dependencies.
+ * Gracefully degrades: if SESHAT_SUPABASE_URL / SESHAT_SUPABASE_KEY are not set,
+ * all operations silently no-op so the MCP server works offline.
+ *
+ * Environment variables (checks both prefixed and standard names):
+ *   SUPABASE_URL                — e.g. https://nlsrjceluztfllbqfpkm.supabase.co
+ *   SUPABASE_SERVICE_ROLE_KEY   — service_role key (preferred)
+ *   SESHAT_SUPABASE_URL         — override (optional)
+ *   SESHAT_SUPABASE_KEY         — override (optional)
+ */
+/** Whether Supabase logging is available. */
+export declare function isSupabaseConfigured(): boolean;
+export interface TokenPredictionInsert {
+    project: string;
+    target_entities: string[];
+    predicted_context_load: number;
+    predicted_iteration_mult: number;
+    predicted_total: number;
+    affected_entities: number;
+    affected_files: number;
+    affected_layers: string[];
+    estimator_used: 'syntactic' | 'charDiv4' | 'heuristic';
+    context_budget: number;
+    session_id?: string;
+}
+export interface ActualBurnUpdate {
+    actual_input_tokens: number;
+    actual_output_tokens: number;
+    actual_total_tokens: number;
+    model: string;
+    notes?: string;
+}
+export interface TokenPredictionRow {
+    id: string;
+    created_at: string;
+    project: string;
+    target_entities: string[];
+    predicted_context_load: number;
+    predicted_iteration_mult: number;
+    predicted_total: number;
+    affected_entities: number;
+    affected_files: number;
+    affected_layers: string[];
+    estimator_used: string;
+    context_budget: number;
+    actual_input_tokens: number | null;
+    actual_output_tokens: number | null;
+    actual_total_tokens: number | null;
+    model: string | null;
+    drift_ratio: number | null;
+    status: string;
+    session_id: string | null;
+    notes: string | null;
+}
+/**
+ * Insert a prediction row. Returns the row ID or null on failure.
+ */
+export declare function insertPrediction(row: TokenPredictionInsert): Promise<string | null>;
+/**
+ * Report actual token burn for a prediction. Computes drift and sets status=completed.
+ */
+export declare function updateActualBurn(predictionId: string, actual: ActualBurnUpdate): Promise<TokenPredictionRow | null>;
+/**
+ * Abandon a prediction (task was cancelled or not completed).
+ */
+export declare function abandonPrediction(predictionId: string): Promise<boolean>;
+/**
+ * List recent predictions for a project (for calibration analysis).
+ */
+export declare function listPredictions(project?: string, limit?: number): Promise<TokenPredictionRow[]>;

package/dist/supabase.js

@@ -0,0 +1,124 @@
+/**
+ * Lightweight Supabase REST client for the calibration feedback loop.
+ *
+ * Uses Node 20+ native fetch — zero external dependencies.
+ * Gracefully degrades: if SESHAT_SUPABASE_URL / SESHAT_SUPABASE_KEY are not set,
+ * all operations silently no-op so the MCP server works offline.
+ *
+ * Environment variables (checks both prefixed and standard names):
+ *   SUPABASE_URL                — e.g. https://nlsrjceluztfllbqfpkm.supabase.co
+ *   SUPABASE_SERVICE_ROLE_KEY   — service_role key (preferred)
+ *   SESHAT_SUPABASE_URL         — override (optional)
+ *   SESHAT_SUPABASE_KEY         — override (optional)
+ */
+const SUPABASE_URL = (process.env.SESHAT_SUPABASE_URL || process.env.SUPABASE_URL || '').replace(/\/$/, '');
+const SUPABASE_KEY = process.env.SESHAT_SUPABASE_KEY || process.env.SUPABASE_SERVICE_ROLE_KEY || '';
+/** Whether Supabase logging is available. */
+export function isSupabaseConfigured() {
+    return SUPABASE_URL.length > 0 && SUPABASE_KEY.length > 0;
+}
+// ─── REST helpers ────────────────────────────────────────────────
+const TABLE = 'mcp_token_predictions';
+async function supabaseRequest(method, path, body, headers) {
+    if (!isSupabaseConfigured()) {
+        return { ok: false, status: 0, error: 'Supabase not configured' };
+    }
+    const url = `${SUPABASE_URL}/rest/v1/${path}`;
+    const reqHeaders = {
+        'apikey': SUPABASE_KEY,
+        'Authorization': `Bearer ${SUPABASE_KEY}`,
+        'Content-Type': 'application/json',
+        'Prefer': 'return=representation',
+        ...headers,
+    };
+    try {
+        const res = await fetch(url, {
+            method,
+            headers: reqHeaders,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const text = await res.text();
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = text;
+        }
+        if (!res.ok) {
+            return { ok: false, status: res.status, error: `${res.status}: ${text}` };
+        }
+        return { ok: true, status: res.status, data };
+    }
+    catch (err) {
+        return { ok: false, status: 0, error: err.message };
+    }
+}
+// ─── Public API ──────────────────────────────────────────────────
+/**
+ * Insert a prediction row. Returns the row ID or null on failure.
+ */
+export async function insertPrediction(row) {
+    const result = await supabaseRequest('POST', TABLE, row);
+    if (!result.ok) {
+        process.stderr.write(`[seshat] Prediction log failed: ${result.error}\n`);
+        return null;
+    }
+    const rows = result.data;
+    return rows?.[0]?.id ?? null;
+}
+/**
+ * Report actual token burn for a prediction. Computes drift and sets status=completed.
+ */
+export async function updateActualBurn(predictionId, actual) {
+    // First fetch the prediction to compute drift
+    const fetchResult = await supabaseRequest('GET', `${TABLE}?id=eq.${predictionId}&select=predicted_total,status`);
+    if (!fetchResult.ok) {
+        process.stderr.write(`[seshat] Fetch prediction failed: ${fetchResult.error}\n`);
+        return null;
+    }
+    const rows = fetchResult.data;
+    if (!rows || rows.length === 0) {
+        return null; // not found
+    }
+    const predicted = rows[0];
+    if (predicted.status !== 'predicted') {
+        return null; // already completed or abandoned
+    }
+    // Compute drift ratio
+    const driftRatio = predicted.predicted_total > 0
+        ? Math.round(((actual.actual_total_tokens - predicted.predicted_total) / predicted.predicted_total) * 1000) / 1000
+        : null;
+    const updateBody = {
+        actual_input_tokens: actual.actual_input_tokens,
+        actual_output_tokens: actual.actual_output_tokens,
+        actual_total_tokens: actual.actual_total_tokens,
+        model: actual.model,
+        drift_ratio: driftRatio,
+        status: 'completed',
+        ...(actual.notes ? { notes: actual.notes } : {}),
+    };
+    const updateResult = await supabaseRequest('PATCH', `${TABLE}?id=eq.${predictionId}`, updateBody);
+    if (!updateResult.ok) {
+        process.stderr.write(`[seshat] Update actual burn failed: ${updateResult.error}\n`);
+        return null;
+    }
+    return updateResult.data?.[0] ?? null;
+}
+/**
+ * Abandon a prediction (task was cancelled or not completed).
+ */
+export async function abandonPrediction(predictionId) {
+    const result = await supabaseRequest('PATCH', `${TABLE}?id=eq.${predictionId}&status=eq.predicted`, { status: 'abandoned' });
+    return result.ok;
+}
+/**
+ * List recent predictions for a project (for calibration analysis).
+ */
+export async function listPredictions(project, limit = 20) {
+    const filter = project ? `&project=eq.${encodeURIComponent(project)}` : '';
+    const result = await supabaseRequest('GET', `${TABLE}?select=*${filter}&order=created_at.desc&limit=${limit}`);
+    if (!result.ok)
+        return [];
+    return result.data || [];
+}

package/dist/tools/functors.d.ts

@@ -42,9 +42,27 @@ export declare function getOptimalContext(args: {
 /**
  * Estimate token cost of a code change BEFORE starting work.
  * Computes blast radius, sums source token counts, and projects total burn.
+ * Logs prediction to Supabase when configured (for calibration feedback loop).
  */
 export declare function estimateTaskCost(args: {
     target_entities: string[];
     context_budget?: number;
     project?: string;
-}): unknown;
+}): Promise<unknown>;
+/**
+ * Close the calibration feedback loop by reporting actual token usage
+ * against a prior prediction from estimate_task_cost.
+ *
+ * Can also abandon a prediction (task was cancelled/not completed),
+ * or list recent predictions for calibration analysis.
+ */
+export declare function reportActualBurn(args: {
+    prediction_id?: string;
+    actual_input_tokens?: number;
+    actual_output_tokens?: number;
+    actual_total_tokens?: number;
+    model?: string;
+    action?: 'complete' | 'abandon' | 'list';
+    project?: string;
+    notes?: string;
+}): Promise<unknown>;

package/dist/tools/functors.js

@@ -7,6 +7,7 @@
  */
 import { computeBlastRadius } from '../graph.js';
 import { getLoader, getGraph, validateProject, entityLayer, entitySummary, } from './index.js';
+import { isSupabaseConfigured, insertPrediction, updateActualBurn, abandonPrediction, listPredictions, } from '../supabase.js';
 // ─── Layer ordering for violation detection ──────────────────────
 const LAYER_ORDER = {
     route: 0,
@@ -49,6 +50,36 @@ export function estimateTokens(e) {
     }
     return tokens;
 }
+/**
+ * Detect which estimator was used for an entity.
+ * Returns 'syntactic' if tree-sitter leaf node count was used,
+ * 'charDiv4' if chars/4 heuristic was used, 'heuristic' for 9D fallback.
+ */
+function detectEstimator(e) {
+    const raw = e;
+    const st = raw.sourceTokens;
+    if (!st?.estimated)
+        return 'heuristic';
+    if (st.syntactic && st.estimated === st.syntactic)
+        return 'syntactic';
+    if (st.charDiv4 && st.estimated === st.charDiv4)
+        return 'charDiv4';
+    return 'charDiv4'; // estimated present but can't distinguish → default to charDiv4
+}
+/**
+ * Determine the dominant estimator across a set of entities.
+ */
+function dominantEstimator(entities) {
+    const counts = { syntactic: 0, charDiv4: 0, heuristic: 0 };
+    for (const e of entities) {
+        counts[detectEstimator(e)]++;
+    }
+    if (counts.syntactic >= counts.charDiv4 && counts.syntactic >= counts.heuristic)
+        return 'syntactic';
+    if (counts.charDiv4 >= counts.heuristic)
+        return 'charDiv4';
+    return 'heuristic';
+}
 // ─── Functor 1: find_dead_code ───────────────────────────────────
 export function findDeadCode(args) {
     const projErr = validateProject(args.project);
@@ -571,8 +602,9 @@ export function getOptimalContext(args) {
 /**
  * Estimate token cost of a code change BEFORE starting work.
  * Computes blast radius, sums source token counts, and projects total burn.
+ * Logs prediction to Supabase when configured (for calibration feedback loop).
  */
-export function estimateTaskCost(args) {
+export async function estimateTaskCost(args) {
     const projErr = validateProject(args.project);
     if (projErr)
         return { error: projErr };
@@ -682,7 +714,10 @@ export function estimateTaskCost(args) {
         sourceTokens: estimateTokens(e),
     }));
     const affectedLayers = [...layerSet].sort();
-    return {
+    const estimator = dominantEstimator(affectedEntities);
+    // Resolve project name for logging
+    const projectName = args.project || loader.getProjectNames()[0] || 'unknown';
+    const result = {
         targets: targetSummaries,
         ...(unresolvedNames.length > 0 ? { unresolved: unresolvedNames } : {}),
         affectedEntities: allAffectedIds.size,
@@ -692,6 +727,7 @@ export function estimateTaskCost(args) {
             contextLoad,
             iterationMultiplier: Math.round(iterationMultiplier * 10) / 10,
             projectedTotal,
+            estimatorUsed: estimator,
         },
         feasibility: {
             contextBudget: context_budget,
@@ -701,4 +737,132 @@ export function estimateTaskCost(args) {
         breakdown: breakdown.slice(0, 30),
         _summary: `Changing ${target_entities.join(', ')} affects ${allAffectedIds.size} entities across ${fileTokens.size} files. Context load: ~${Math.round(contextLoad / 1000)}K tokens. Projected total with ${Math.round(iterationMultiplier * 10) / 10}x iteration: ~${Math.round(projectedTotal / 1000)}K tokens. ${fitsInSinglePass ? `Fits in ${Math.round(context_budget / 1000)}K budget (${passesRequired} pass).` : `Exceeds ${Math.round(context_budget / 1000)}K budget — needs ${passesRequired} passes.`}`,
     };
+    // Log prediction to Supabase if configured (calibration feedback loop)
+    if (isSupabaseConfigured()) {
+        try {
+            const predictionId = await insertPrediction({
+                project: projectName,
+                target_entities,
+                predicted_context_load: contextLoad,
+                predicted_iteration_mult: Math.round(iterationMultiplier * 10) / 10,
+                predicted_total: projectedTotal,
+                affected_entities: allAffectedIds.size,
+                affected_files: fileTokens.size,
+                affected_layers: affectedLayers,
+                estimator_used: estimator,
+                context_budget,
+            });
+            if (predictionId) {
+                result.predictionId = predictionId;
+                result._summary += ` Prediction logged (${predictionId.slice(0, 8)}…).`;
+            }
+        }
+        catch {
+            // Silently swallow — prediction logging is best-effort
+        }
+    }
+    return result;
+}
+// ─── Functor 9: report_actual_burn ───────────────────────────────
+/**
+ * Close the calibration feedback loop by reporting actual token usage
+ * against a prior prediction from estimate_task_cost.
+ *
+ * Can also abandon a prediction (task was cancelled/not completed),
+ * or list recent predictions for calibration analysis.
+ */
+export async function reportActualBurn(args) {
+    if (!isSupabaseConfigured()) {
+        return {
+            error: 'Supabase not configured. Set SESHAT_SUPABASE_URL and SESHAT_SUPABASE_KEY env vars.',
+            hint: 'The calibration feedback loop requires a Supabase connection to store predictions.',
+        };
+    }
+    const { action = 'complete' } = args;
+    // List mode: show recent predictions for calibration analysis
+    if (action === 'list') {
+        const rows = await listPredictions(args.project);
+        if (rows.length === 0) {
+            return { message: 'No predictions found.', predictions: [] };
+        }
+        const summary = rows.map((r) => ({
+            id: r.id,
+            project: r.project,
+            targets: r.target_entities,
+            predicted: r.predicted_total,
+            actual: r.actual_total_tokens,
+            drift: r.drift_ratio,
+            estimator: r.estimator_used,
+            status: r.status,
+            createdAt: r.created_at,
+        }));
+        // Compute aggregate calibration stats for completed predictions
+        const completed = rows.filter((r) => r.status === 'completed' && r.drift_ratio != null);
+        let calibration;
+        if (completed.length >= 3) {
+            const drifts = completed.map((r) => r.drift_ratio);
+            const meanDrift = drifts.reduce((a, b) => a + b, 0) / drifts.length;
+            const sortedDrifts = [...drifts].sort((a, b) => a - b);
+            const medianDrift = sortedDrifts[Math.floor(sortedDrifts.length / 2)];
+            const maxOvershoot = Math.max(...drifts);
+            const maxUndershoot = Math.min(...drifts);
+            calibration = {
+                completedSamples: completed.length,
+                meanDrift: Math.round(meanDrift * 1000) / 1000,
+                medianDrift: Math.round(medianDrift * 1000) / 1000,
+                maxOvershoot: Math.round(maxOvershoot * 1000) / 1000,
+                maxUndershoot: Math.round(maxUndershoot * 1000) / 1000,
+                _interpretation: meanDrift > 0.2
+                    ? 'Predictions underestimate — consider increasing iteration multiplier.'
+                    : meanDrift < -0.2
+                        ? 'Predictions overestimate — consider decreasing iteration multiplier.'
+                        : 'Predictions are well-calibrated (within 20% mean drift).',
+            };
+        }
+        return {
+            total: rows.length,
+            predictions: summary,
+            ...(calibration ? { calibration } : {}),
+        };
+    }
+    // Complete or abandon requires prediction_id
+    if (!args.prediction_id) {
+        return {
+            error: 'prediction_id is required for complete/abandon actions.',
+            hint: 'Use estimate_task_cost first to get a predictionId, then pass it here.',
+        };
+    }
+    // Abandon mode
+    if (action === 'abandon') {
+        const ok = await abandonPrediction(args.prediction_id);
+        return ok
+            ? { status: 'abandoned', predictionId: args.prediction_id }
+            : { error: `Failed to abandon prediction ${args.prediction_id}. It may already be completed or not exist.` };
+    }
+    // Complete mode: requires actual token counts
+    if (!args.actual_input_tokens || !args.actual_output_tokens || !args.actual_total_tokens || !args.model) {
+        return {
+            error: 'actual_input_tokens, actual_output_tokens, actual_total_tokens, and model are required to complete a prediction.',
+        };
+    }
+    const updated = await updateActualBurn(args.prediction_id, {
+        actual_input_tokens: args.actual_input_tokens,
+        actual_output_tokens: args.actual_output_tokens,
+        actual_total_tokens: args.actual_total_tokens,
+        model: args.model,
+        notes: args.notes,
+    });
+    if (!updated) {
+        return {
+            error: `Failed to update prediction ${args.prediction_id}. It may not exist or may already be completed.`,
+        };
+    }
+    return {
+        status: 'completed',
+        predictionId: updated.id,
+        predicted: updated.predicted_total,
+        actual: updated.actual_total_tokens,
+        drift: updated.drift_ratio,
+        _summary: `Prediction ${updated.id.slice(0, 8)}… closed. Predicted ${updated.predicted_total} tokens, actual ${updated.actual_total_tokens} tokens. Drift: ${updated.drift_ratio != null ? `${(updated.drift_ratio * 100).toFixed(1)}%` : 'N/A'}.`,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Semantic MCP server — exposes a codebase's 9D JSTF-T coordinate space as queryable tools",
   "type": "module",
   "bin": {