@papyruslabsai/seshat-mcp 0.3.2 → 0.4.0

package/dist/bootstrap.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Auto-Bootstrap — extract a .seshat/ bundle on first run.
+ *
+ * When the MCP server starts and finds no .seshat/_bundle.json, this module
+ * spawns `npx @papyruslabsai/seshat-extract` to generate one on the fly.
+ *
+ * CI continues to regenerate the bundle on every merge to main, overwriting
+ * the bootstrap result. The bootstrap only runs when .seshat/ doesn't exist.
+ *
+ * Env vars:
+ *   SESHAT_BOOTSTRAP_TIMEOUT — spawn timeout in ms (default: 120000)
+ */
+export interface BootstrapResult {
+    success: boolean;
+    entityCount: number;
+    languages: string[];
+    durationMs: number;
+    error?: string;
+}
+/**
+ * Auto-bootstrap: extract a .seshat/ bundle for the given project directory.
+ *
+ * Spawns `npx @papyruslabsai/seshat-extract <dir> <dir>/.seshat <name>`
+ * and waits for it to complete.
+ *
+ * @param projectDir - Absolute path to the project root
+ * @returns Bootstrap result with entity count, languages, duration, and any error
+ */
+export declare function bootstrap(projectDir: string): Promise<BootstrapResult>;

package/dist/bootstrap.js

@@ -0,0 +1,187 @@
+/**
+ * Auto-Bootstrap — extract a .seshat/ bundle on first run.
+ *
+ * When the MCP server starts and finds no .seshat/_bundle.json, this module
+ * spawns `npx @papyruslabsai/seshat-extract` to generate one on the fly.
+ *
+ * CI continues to regenerate the bundle on every merge to main, overwriting
+ * the bootstrap result. The bootstrap only runs when .seshat/ doesn't exist.
+ *
+ * Env vars:
+ *   SESHAT_BOOTSTRAP_TIMEOUT — spawn timeout in ms (default: 120000)
+ */
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+// Project marker files — presence of any means "this is a code project"
+const PROJECT_MARKERS = [
+    '.git',
+    'package.json',
+    'go.mod',
+    'Cargo.toml',
+    'pyproject.toml',
+    'pom.xml',
+    'build.gradle',
+    'Makefile',
+    'CMakeLists.txt',
+];
+/**
+ * Check if a directory looks like a code project.
+ */
+function isCodeProject(dir) {
+    for (const marker of PROJECT_MARKERS) {
+        const markerPath = path.join(dir, marker);
+        if (fs.existsSync(markerPath))
+            return true;
+    }
+    // Also check for *.sln files (C# solutions)
+    try {
+        const entries = fs.readdirSync(dir);
+        if (entries.some(e => e.endsWith('.sln')))
+            return true;
+    }
+    catch { }
+    return false;
+}
+/**
+ * Infer a project name from the directory.
+ * Priority: package.json name → git remote → directory basename
+ */
+function inferProjectName(dir) {
+    // 1. Try package.json
+    try {
+        const pkgPath = path.join(dir, 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (pkg.name) {
+            return pkg.name.replace(/^@[^/]+\//, '');
+        }
+    }
+    catch { }
+    // 2. Try git remote
+    try {
+        const remote = execSync('git remote get-url origin', {
+            cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+        const match = remote.match(/\/([^/]+?)(?:\.git)?$/);
+        if (match)
+            return match[1];
+    }
+    catch { }
+    // 3. Fallback: directory basename
+    return path.basename(dir);
+}
+/**
+ * Auto-bootstrap: extract a .seshat/ bundle for the given project directory.
+ *
+ * Spawns `npx @papyruslabsai/seshat-extract <dir> <dir>/.seshat <name>`
+ * and waits for it to complete.
+ *
+ * @param projectDir - Absolute path to the project root
+ * @returns Bootstrap result with entity count, languages, duration, and any error
+ */
+export async function bootstrap(projectDir) {
+    const startTime = Date.now();
+    const timeoutMs = parseInt(process.env.SESHAT_BOOTSTRAP_TIMEOUT || '120000', 10);
+    // Sanity checks
+    if (!isCodeProject(projectDir)) {
+        return {
+            success: false,
+            entityCount: 0,
+            languages: [],
+            durationMs: Date.now() - startTime,
+            error: `${projectDir} does not appear to be a code project (no package.json, .git, go.mod, etc.)`,
+        };
+    }
+    const seshatDir = path.join(projectDir, '.seshat');
+    const projectName = inferProjectName(projectDir);
+    process.stderr.write(`[seshat-mcp] Auto-bootstrap: extracting ${projectName} from ${projectDir}\n`);
+    return new Promise((resolve) => {
+        // On Windows, npx is npx.cmd
+        const isWindows = process.platform === 'win32';
+        const npxCmd = isWindows ? 'npx.cmd' : 'npx';
+        const child = spawn(npxCmd, ['-y', '@papyruslabsai/seshat-extract', projectDir, seshatDir, projectName], {
+            cwd: projectDir,
+            shell: isWindows, // Windows needs shell: true for .cmd files
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: timeoutMs,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr?.on('data', (data) => {
+            const text = data.toString();
+            stderr += text;
+            // Forward progress to parent stderr
+            process.stderr.write(`[seshat-extract] ${text}`);
+        });
+        child.on('error', (err) => {
+            resolve({
+                success: false,
+                entityCount: 0,
+                languages: [],
+                durationMs: Date.now() - startTime,
+                error: `Failed to spawn seshat-extract: ${err.message}`,
+            });
+        });
+        child.on('close', (code) => {
+            const durationMs = Date.now() - startTime;
+            if (code !== 0) {
+                resolve({
+                    success: false,
+                    entityCount: 0,
+                    languages: [],
+                    durationMs,
+                    error: `seshat-extract exited with code ${code}. stderr: ${stderr.slice(-500)}`,
+                });
+                return;
+            }
+            // Parse the JSON result from stdout
+            try {
+                const result = JSON.parse(stdout.trim());
+                if (result.ok) {
+                    process.stderr.write(`[seshat-mcp] Bootstrap complete: ${result.entities} entities, ${result.languages?.join(', ')} in ${(durationMs / 1000).toFixed(1)}s\n`);
+                    resolve({
+                        success: true,
+                        entityCount: result.entities || 0,
+                        languages: result.languages || [],
+                        durationMs,
+                    });
+                }
+                else {
+                    resolve({
+                        success: false,
+                        entityCount: 0,
+                        languages: [],
+                        durationMs,
+                        error: result.error || 'Unknown extraction error',
+                    });
+                }
+            }
+            catch {
+                // JSON parse failed — check if bundle was written anyway
+                const bundlePath = path.join(seshatDir, '_bundle.json');
+                if (fs.existsSync(bundlePath)) {
+                    process.stderr.write(`[seshat-mcp] Bootstrap produced bundle but JSON result was malformed. Proceeding.\n`);
+                    resolve({
+                        success: true,
+                        entityCount: 0,
+                        languages: [],
+                        durationMs,
+                    });
+                }
+                else {
+                    resolve({
+                        success: false,
+                        entityCount: 0,
+                        languages: [],
+                        durationMs,
+                        error: `seshat-extract succeeded but produced no parseable result. stdout: ${stdout.slice(-200)}`,
+                    });
+                }
+            }
+        });
+    });
+}

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)
@@ -43,8 +44,9 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { MultiLoader } from './loader.js';
+import { bootstrap } from './bootstrap.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,18 +360,82 @@ 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() {
     // Discover and load projects
     const projectDirs = discoverProjects();
-    const loader = new MultiLoader(projectDirs);
+    let loader = new MultiLoader(projectDirs);
     try {
         loader.load();
     }
     catch (err) {
         process.stderr.write(`Warning: ${err.message}\n`);
     }
+    // Auto-bootstrap: if no projects loaded, try to extract from CWD
+    if (!loader.isLoaded() && !process.env.SESHAT_PROJECTS) {
+        const cwd = process.cwd();
+        const seshatDir = path.join(cwd, '.seshat');
+        // Only bootstrap when .seshat/ doesn't exist at all (not corruption)
+        if (!fs.existsSync(seshatDir)) {
+            process.stderr.write(`[seshat-mcp] No .seshat/ found — attempting auto-bootstrap...\n`);
+            const result = await bootstrap(cwd);
+            if (result.success) {
+                // Re-create loader and retry
+                loader = new MultiLoader([cwd]);
+                try {
+                    loader.load();
+                    process.stderr.write(`[seshat-mcp] Auto-bootstrap succeeded: ${loader.totalEntities()} entities loaded\n`);
+                }
+                catch (err) {
+                    process.stderr.write(`[seshat-mcp] Auto-bootstrap produced files but load failed: ${err.message}\n`);
+                }
+            }
+            else {
+                process.stderr.write(`[seshat-mcp] Auto-bootstrap failed: ${result.error || 'unknown error'}\n`);
+                process.stderr.write(`[seshat-mcp] Starting with 0 entities. Run extraction manually or push to trigger CI.\n`);
+            }
+        }
+    }
     initTools(loader);
     // Build server name
     const projectNames = loader.getProjectNames();
@@ -388,7 +454,7 @@ async function main() {
     }
     const server = new Server({
         name: serverLabel,
-        version: '0.3.2',
+        version: '0.4.0',
     }, {
         capabilities: {
             tools: {},
@@ -473,7 +539,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.4.0",
   "description": "Semantic MCP server — exposes a codebase's 9D JSTF-T coordinate space as queryable tools",
   "type": "module",
   "bin": {