@papyruslabsai/seshat-mcp 0.3.1 → 0.3.2

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 + 8 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,7 @@
  *   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
  *
  * 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 + 8 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,7 @@
  *   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
  *
  * Usage:
  *   npx @papyruslabs/seshat-mcp                           # single project (CWD)
@@ -43,7 +44,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, } from './tools/functors.js';
 // ─── Project Discovery ───────────────────────────────────────────
 /**
  * Discover project directories from SESHAT_PROJECTS env var.
@@ -337,6 +338,26 @@ 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'],
+        },
+    },
 ];
 // ─── Server Setup ─────────────────────────────────────────────────
 async function main() {
@@ -367,7 +388,7 @@ async function main() {
     }
     const server = new Server({
         name: serverLabel,
-        version: '0.3.1',
+        version: '0.3.2',
     }, {
         capabilities: {
             tools: {},
@@ -451,6 +472,9 @@ async function main() {
                 case 'get_optimal_context':
                     result = getOptimalContext(args);
                     break;
+                case 'estimate_task_cost':
+                    result = estimateTaskCost(args);
+                    break;
                 default:
                     result = { error: `Unknown tool: ${name}` };
             }

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,12 @@ 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.
+ */
+export declare function estimateTaskCost(args: {
+    target_entities: string[];
+    context_budget?: number;
+    project?: string;
+}): unknown;

package/dist/tools/functors.js

@@ -20,6 +20,35 @@ 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;
+}
 // ─── Functor 1: find_dead_code ───────────────────────────────────
 export function findDeadCode(args) {
     const projErr = validateProject(args.project);
@@ -207,6 +236,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 +368,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 +415,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 +464,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 +567,138 @@ 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.
+ */
+export 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();
+    return {
+        targets: targetSummaries,
+        ...(unresolvedNames.length > 0 ? { unresolved: unresolvedNames } : {}),
+        affectedEntities: allAffectedIds.size,
+        affectedFiles: fileTokens.size,
+        affectedLayers,
+        tokenEstimate: {
+            contextLoad,
+            iterationMultiplier: Math.round(iterationMultiplier * 10) / 10,
+            projectedTotal,
+        },
+        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.`}`,
+    };
+}

package/package.json

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