@papyruslabsai/seshat-mcp 0.3.1 → 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 + 7 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
@@ -30,6 +30,8 @@
  *   find_error_gaps       — Fallible callees whose callers lack try/catch
  *   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 + 7 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
@@ -30,6 +30,8 @@
  *   find_error_gaps       — Fallible callees whose callers lack try/catch
  *   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)
@@ -43,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, } 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.
@@ -337,6 +339,65 @@ const TOOLS = [
             required: ['target_entity'],
         },
     },
+    {
+        name: 'estimate_task_cost',
+        description: 'Estimate token cost of a code change BEFORE starting work. Computes blast radius, sums source token counts across affected entities, and projects total token burn including iteration cycles. Call this before planning to check if a task fits within your token budget.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                target_entities: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Entity IDs or names that will be modified',
+                },
+                context_budget: {
+                    type: 'number',
+                    description: 'LLM context window token budget (default: 200000)',
+                },
+            },
+            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() {
@@ -367,7 +428,7 @@ async function main() {
     }
     const server = new Server({
         name: serverLabel,
-        version: '0.3.1',
+        version: '0.3.3',
     }, {
         capabilities: {
             tools: {},
@@ -451,6 +512,12 @@ async function main() {
                 case 'get_optimal_context':
                     result = getOptimalContext(args);
                     break;
+                case 'estimate_task_cost':
+                    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

@@ -5,6 +5,13 @@
  * onto a domain-specific judgment. These are composite analyses built
  * from the primitive dimensions (sigma, epsilon, delta, kappa, chi, tau, rho).
  */
+import type { JstfEntity } from '../types.js';
+/**
+ * Estimate the token cost of loading an entity's source code into an LLM context.
+ * Uses real sourceTokens from the extraction pipeline when available (v0.3.2+),
+ * falls back to heuristic estimation from 9D coordinates for older bundles.
+ */
+export declare function estimateTokens(e: JstfEntity): number;
 export declare function findDeadCode(args: {
     include_tests?: boolean;
     project?: string;
@@ -32,3 +39,30 @@ export declare function getOptimalContext(args: {
     strategy?: 'bfs' | 'blast_radius';
     project?: string;
 }): unknown;
+/**
+ * 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;
+}): 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,
@@ -20,6 +21,65 @@ const LAYER_ORDER = {
     utility: 8,
     component: 1, // UI components are peers to controllers
 };
+// ─── Shared: Token estimation ────────────────────────────────────
+/**
+ * Estimate the token cost of loading an entity's source code into an LLM context.
+ * Uses real sourceTokens from the extraction pipeline when available (v0.3.2+),
+ * falls back to heuristic estimation from 9D coordinates for older bundles.
+ */
+export function estimateTokens(e) {
+    // Use real source token count from extraction pipeline
+    const raw = e;
+    const st = raw.sourceTokens;
+    if (st?.estimated)
+        return st.estimated;
+    // Fallback: heuristic from 9D coordinates (pre-v0.3.2 bundles)
+    let tokens = 50; // Base: name, id, layer
+    if (e.struct && typeof e.struct !== 'string') {
+        tokens += 20; // signature
+        tokens += (e.struct.params?.length || 0) * 10;
+    }
+    if (e.edges?.calls)
+        tokens += e.edges.calls.length * 8;
+    if (e.edges?.imports)
+        tokens += e.edges.imports.length * 6;
+    if (e.data?.inputs)
+        tokens += e.data.inputs.length * 10;
+    if (e.constraints && typeof e.constraints === 'object' && !Array.isArray(e.constraints)) {
+        tokens += 30;
+    }
+    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);
@@ -207,6 +267,7 @@ export function getCouplingMetrics(args) {
             cohesion: Math.round(cohesion * 1000) / 1000,
             coupling,
             instability: Math.round(instability * 1000) / 1000,
+            _summary: `${groupName}: ${internalEdges} internal / ${totalExternal} external edges, cohesion ${Math.round(cohesion * 1000) / 1000} (${size} entities)`,
         });
     }
     // Sort by coupling (most coupled first)
@@ -338,6 +399,7 @@ export function findErrorGaps(args) {
     return {
         totalFallible: fallibleIds.size,
         errorGaps: gaps.length,
+        _summary: `${gaps.length} error handling gaps across ${fallibleIds.size} fallible entities`,
         gaps: gaps.slice(0, 100),
     };
 }
@@ -384,14 +446,16 @@ export function getTestCoverage(args) {
     }
     const covered = productionEntities.filter(e => exercised.has(e.id));
     const uncovered = productionEntities.filter(e => !exercised.has(e.id));
+    const coveragePercent = productionEntities.length > 0
+        ? Math.round((covered.length / productionEntities.length) * 1000) / 10
+        : 0;
     const result = {
         totalProduction: productionEntities.length,
         totalTests: testIds.size,
         coveredCount: covered.length,
         uncoveredCount: uncovered.length,
-        coveragePercent: productionEntities.length > 0
-            ? Math.round((covered.length / productionEntities.length) * 1000) / 10
-            : 0,
+        coveragePercent,
+        _summary: `${testIds.size} test entities exercise ${covered.length} of ${productionEntities.length} production entities (${coveragePercent}% coverage)`,
     };
     if (weight_by_blast_radius && uncovered.length > 0) {
         // Compute blast radius for each uncovered entity to prioritize what to test
@@ -431,24 +495,6 @@ export function getOptimalContext(args) {
         return { error: `Entity not found: ${target_entity}` };
     }
     const targetId = entity.id;
-    // Estimate tokens for an entity based on its dimensions
-    function estimateTokens(e) {
-        let tokens = 50; // Base: name, id, layer
-        if (e.struct && typeof e.struct !== 'string') {
-            tokens += 20; // signature
-            tokens += (e.struct.params?.length || 0) * 10;
-        }
-        if (e.edges?.calls)
-            tokens += e.edges.calls.length * 8;
-        if (e.edges?.imports)
-            tokens += e.edges.imports.length * 6;
-        if (e.data?.inputs)
-            tokens += e.data.inputs.length * 10;
-        if (e.constraints && typeof e.constraints === 'object' && !Array.isArray(e.constraints)) {
-            tokens += 30;
-        }
-        return tokens;
-    }
     const candidates = [];
     if (strategy === 'blast_radius') {
         // Use blast radius to get all related entities with depth
@@ -552,3 +598,271 @@ export function getOptimalContext(args) {
         context: selected,
     };
 }
+// ─── Functor 8: estimate_task_cost ───────────────────────────────
+/**
+ * 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 async function estimateTaskCost(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const { target_entities, context_budget = 200000 } = args;
+    const loader = getLoader();
+    const g = getGraph(args.project);
+    // Resolve target entities
+    const resolvedTargets = [];
+    const unresolvedNames = [];
+    const changedIds = new Set();
+    for (const name of target_entities) {
+        const entity = loader.getEntityById(name, args.project)
+            || loader.getEntityByName(name, args.project);
+        if (entity) {
+            resolvedTargets.push(entity);
+            changedIds.add(entity.id);
+        }
+        else {
+            unresolvedNames.push(name);
+        }
+    }
+    if (resolvedTargets.length === 0) {
+        return {
+            error: `No entities resolved. Unresolved: ${unresolvedNames.join(', ')}`,
+            hint: 'Use query_entities to find the correct entity IDs.',
+        };
+    }
+    // Compute blast radius across all targets
+    const br = computeBlastRadius(g, changedIds);
+    // Collect all affected entities (targets + blast radius)
+    const allAffectedIds = new Set([...changedIds, ...br.affected]);
+    const affectedEntities = [];
+    for (const id of allAffectedIds) {
+        const e = g.entityById.get(id);
+        if (e)
+            affectedEntities.push(e);
+    }
+    // Sum token estimates
+    let contextLoad = 0;
+    const fileTokens = new Map();
+    const layerSet = new Set();
+    for (const e of affectedEntities) {
+        const tokens = estimateTokens(e);
+        contextLoad += tokens;
+        const file = e._sourceFile || 'unknown';
+        if (!fileTokens.has(file))
+            fileTokens.set(file, { entities: 0, tokens: 0 });
+        const ft = fileTokens.get(file);
+        ft.entities++;
+        ft.tokens += tokens;
+        layerSet.add(entityLayer(e));
+    }
+    // Compute iteration multiplier
+    let iterationMultiplier = 1.5; // base: read + write pass
+    // +0.5 if cross-cutting (3+ layers)
+    if (layerSet.size >= 3)
+        iterationMultiplier += 0.5;
+    // +0.5 if any affected module has high instability
+    const affectedModules = new Set();
+    for (const e of affectedEntities) {
+        if (e.context?.module)
+            affectedModules.add(e.context.module);
+    }
+    // Quick instability check: compute outgoing / (outgoing + incoming) for affected modules
+    for (const mod of affectedModules) {
+        let outgoing = 0;
+        let incoming = 0;
+        const entities = loader.getEntities(args.project);
+        const modIds = new Set(entities.filter(e => e.context?.module === mod).map(e => e.id));
+        for (const id of modIds) {
+            const calleeSet = g.callees.get(id);
+            if (calleeSet) {
+                for (const cid of calleeSet) {
+                    if (!modIds.has(cid))
+                        outgoing++;
+                }
+            }
+            const callerSet = g.callers.get(id);
+            if (callerSet) {
+                for (const cid of callerSet) {
+                    if (!modIds.has(cid))
+                        incoming++;
+                }
+            }
+        }
+        const total = outgoing + incoming;
+        if (total > 0 && outgoing / total > 0.8) {
+            iterationMultiplier += 0.5;
+            break; // only add once
+        }
+    }
+    // +0.5 if large blast radius
+    if (allAffectedIds.size > 50)
+        iterationMultiplier += 0.5;
+    // Cap at 4.0
+    iterationMultiplier = Math.min(4.0, iterationMultiplier);
+    const projectedTotal = Math.round(contextLoad * iterationMultiplier);
+    const fitsInSinglePass = contextLoad <= context_budget;
+    const passesRequired = fitsInSinglePass ? 1 : Math.ceil(contextLoad / context_budget);
+    // Build file breakdown sorted by token count
+    const breakdown = [...fileTokens.entries()]
+        .map(([file, data]) => ({ file, entities: data.entities, tokens: data.tokens }))
+        .sort((a, b) => b.tokens - a.tokens);
+    // Build target summaries with token estimates
+    const targetSummaries = resolvedTargets.map(e => ({
+        ...entitySummary(e),
+        sourceTokens: estimateTokens(e),
+    }));
+    const affectedLayers = [...layerSet].sort();
+    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,
+        affectedFiles: fileTokens.size,
+        affectedLayers,
+        tokenEstimate: {
+            contextLoad,
+            iterationMultiplier: Math.round(iterationMultiplier * 10) / 10,
+            projectedTotal,
+            estimatorUsed: estimator,
+        },
+        feasibility: {
+            contextBudget: context_budget,
+            fitsInSinglePass,
+            passesRequired,
+        },
+        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.1",
+  "version": "0.3.3",
   "description": "Semantic MCP server — exposes a codebase's 9D JSTF-T coordinate space as queryable tools",
   "type": "module",
   "bin": {