vibe-splain 3.0.0 → 3.2.0

package/dist/mcp/BudgetGuard.d.ts

@@ -0,0 +1,13 @@
+export interface BudgetExceededResult {
+    pointerId: string;
+    contentHash: string;
+    sizeBytes: number;
+    summary: string;
+    hydrators: string[];
+}
+export declare function applyBudgetGuard(projectRoot: string, scanId: string, artifactName: string, output: unknown): Promise<unknown>;
+/** Verify a pointer exists, is unexpired, and its blob hash matches */
+export declare function hydratePointer(projectRoot: string, pointerId: string): Promise<{
+    content: Buffer;
+    row: import('../store/PointerStore.js').PointerRow;
+}>;

package/dist/mcp/BudgetGuard.js

@@ -0,0 +1,55 @@
+import { BlobStore } from '../store/BlobStore.js';
+import { PointerStore } from '../store/PointerStore.js';
+import { v4 as uuidv4 } from 'uuid';
+/** ~2000 tokens ≈ 8000 chars */
+const BUDGET_CHARS = 8000;
+export async function applyBudgetGuard(projectRoot, scanId, artifactName, output) {
+    const serialized = JSON.stringify(output, null, 2);
+    if (serialized.length <= BUDGET_CHARS)
+        return output;
+    const blobStore = new BlobStore(projectRoot);
+    const pointerStore = PointerStore.open(projectRoot);
+    const { contentHash, blobPath } = await blobStore.writeAtomic(serialized);
+    const pointerId = `ptr_${uuidv4().replace(/-/g, '').slice(0, 16)}`;
+    await pointerStore.insertPointer({
+        pointerId,
+        scanId,
+        artifactName,
+        contentHash,
+        blobPath,
+        schemaVersion: '1.0.0',
+        createdAt: Date.now(),
+        expiresAt: null,
+    });
+    const result = {
+        pointerId,
+        contentHash,
+        sizeBytes: serialized.length,
+        summary: `Output exceeded context budget (${serialized.length} chars). Written to artifact blob.`,
+        hydrators: ['get_evidence_slice', 'get_start_here', 'get_project_summary'],
+    };
+    return result;
+}
+/** Verify a pointer exists, is unexpired, and its blob hash matches */
+export async function hydratePointer(projectRoot, pointerId) {
+    const pointerStore = PointerStore.open(projectRoot);
+    const row = pointerStore.getPointer(pointerId);
+    if (!row) {
+        throw new Error(`ArtifactNotFound: pointer ${pointerId} does not exist`);
+    }
+    if (row.expiresAt !== null && row.expiresAt < Date.now()) {
+        throw new Error(`ArtifactCollectedError: pointer ${pointerId} has expired`);
+    }
+    const SUPPORTED_VERSIONS = ['1.0.0', '2.0.0'];
+    if (!SUPPORTED_VERSIONS.includes(row.schemaVersion)) {
+        throw new Error(`UnsupportedSchema: pointer ${pointerId} has schema version ${row.schemaVersion}`);
+    }
+    const blobStore = new BlobStore(projectRoot);
+    const content = await blobStore.readBlob(row.blobPath);
+    const valid = await blobStore.verifyIntegrity(row.blobPath, row.contentHash);
+    if (!valid) {
+        throw new Error(`IntegrityError: blob for pointer ${pointerId} failed hash verification`);
+    }
+    return { content, row };
+}
+//# sourceMappingURL=BudgetGuard.js.map

package/dist/mcp/SessionScope.d.ts

@@ -0,0 +1,26 @@
+import type { WorkOrderRow, ProofDescriptor } from '../store/PointerStore.js';
+export interface ScopePolicy {
+    workOrderId: string;
+    allowedFiles: string[];
+    allowedGlobs: string[];
+    deniedGlobs: string[];
+    requiredProof: ProofDescriptor[];
+}
+export declare class ScopeViolation extends Error {
+    readonly path: string;
+    readonly workOrderId: string;
+    constructor(path: string, workOrderId: string, reason: string);
+}
+export declare const SessionScope: {
+    set(policy: ScopePolicy): void;
+    clear(): void;
+    get(): ScopePolicy | null;
+    /**
+     * Enforce scope for a file path.
+     * Throws ScopeViolation if:
+     *  - a scope is active AND the path is not allowed
+     * If no scope is active, all paths are permitted.
+     */
+    enforce(filePath: string): void;
+    fromWorkOrderRow(row: WorkOrderRow): ScopePolicy;
+};

package/dist/mcp/SessionScope.js

@@ -0,0 +1,56 @@
+import { minimatch } from 'minimatch';
+export class ScopeViolation extends Error {
+    path;
+    workOrderId;
+    constructor(path, workOrderId, reason) {
+        super(`ScopeViolation [${workOrderId}]: ${reason} — path: ${path}`);
+        this.path = path;
+        this.workOrderId = workOrderId;
+        this.name = 'ScopeViolation';
+    }
+}
+let activeScope = null;
+export const SessionScope = {
+    set(policy) {
+        activeScope = policy;
+    },
+    clear() {
+        activeScope = null;
+    },
+    get() {
+        return activeScope;
+    },
+    /**
+     * Enforce scope for a file path.
+     * Throws ScopeViolation if:
+     *  - a scope is active AND the path is not allowed
+     * If no scope is active, all paths are permitted.
+     */
+    enforce(filePath) {
+        if (!activeScope)
+            return;
+        const { workOrderId, allowedFiles, allowedGlobs, deniedGlobs } = activeScope;
+        // Explicit file list match (exact suffix or relative path)
+        const inAllowedFiles = allowedFiles.some(f => filePath === f || filePath.endsWith('/' + f) || filePath.endsWith(f));
+        // Glob match
+        const inAllowedGlobs = allowedGlobs.some(g => minimatch(filePath, g, { matchBase: true }));
+        if (!inAllowedFiles && !inAllowedGlobs) {
+            throw new ScopeViolation(filePath, workOrderId, 'path not in allowedFiles or allowedGlobs');
+        }
+        // Deny globs have priority over allow
+        const isDenied = deniedGlobs.some(g => minimatch(filePath, g, { matchBase: true }));
+        if (isDenied) {
+            throw new ScopeViolation(filePath, workOrderId, 'path matches deniedGlobs');
+        }
+    },
+    fromWorkOrderRow(row) {
+        return {
+            workOrderId: row.workOrderId,
+            allowedFiles: JSON.parse(row.allowedFiles),
+            allowedGlobs: JSON.parse(row.allowedGlobs),
+            deniedGlobs: JSON.parse(row.deniedGlobs),
+            requiredProof: JSON.parse(row.requiredProof),
+        };
+    },
+};
+//# sourceMappingURL=SessionScope.js.map

package/dist/mcp/server.js

@@ -12,6 +12,16 @@ import { handleInspectPillar, inspectPillarTool } from './tools/inspect_pillar.j
 import { handleGetWildDiscoveries, getWildDiscoveriesTool } from './tools/get_wild_discoveries.js';
 import { handleMarkStale, markStaleTool } from './tools/mark_stale.js';
 import { handleGetCallChain, getCallChainTool } from './tools/get_call_chain.js';
+import { handleGetFileSkeleton, getFileSkeletonTool } from './tools/get_file_skeleton.js';
+import { handleReadFile, readFileTool } from './tools/read_file.js';
+import { handleApplyPatch, applyPatchTool } from './tools/apply_patch.js';
+import { handleCreateWorkOrder, createWorkOrderTool, handleSpawnWorker, spawnWorkerTool } from './tools/work_orders.js';
+import { handleSubmitReceipt, submitReceiptTool } from './tools/submit_receipt.js';
+import { handleSetSessionScope, setSessionScopeTool } from './tools/set_session_scope.js';
+import { handleYieldForScopeExpansion, yieldForScopeExpansionTool } from './tools/yield_for_scope_expansion.js';
+import { handleGetStartHere, getStartHereTool } from './tools/hydration/get_start_here.js';
+import { handleGetProjectSummary, getProjectSummaryTool } from './tools/hydration/get_project_summary.js';
+import { handleGetEvidenceSlice, getEvidenceSliceTool } from './tools/hydration/get_evidence_slice.js';
 // ⚠️ CRITICAL: Never use console.log() anywhere in this codebase.
 // stdout is owned by the MCP SDK for protocol messages.
 // Use console.error() for all diagnostic output.
@@ -26,6 +36,20 @@ const ALL_TOOLS = [
     inspectPillarTool,
     getWildDiscoveriesTool,
     markStaleTool,
+    // Phase 2: Skeletons + Hydration
+    getFileSkeletonTool,
+    readFileTool,
+    getStartHereTool,
+    getProjectSummaryTool,
+    getEvidenceSliceTool,
+    // Phase 3: Delegation & Proof
+    createWorkOrderTool,
+    spawnWorkerTool,
+    applyPatchTool,
+    submitReceiptTool,
+    // Phase 4: Scope & Escalation
+    setSessionScopeTool,
+    yieldForScopeExpansionTool,
 ];
 const TOOL_HANDLERS = {
     scan_project: handleScanProject,
@@ -38,6 +62,20 @@ const TOOL_HANDLERS = {
     inspect_pillar: handleInspectPillar,
     get_wild_discoveries: handleGetWildDiscoveries,
     mark_stale: handleMarkStale,
+    // Phase 2
+    get_file_skeleton: handleGetFileSkeleton,
+    read_file: handleReadFile,
+    get_start_here: handleGetStartHere,
+    get_project_summary: handleGetProjectSummary,
+    get_evidence_slice: handleGetEvidenceSlice,
+    // Phase 3
+    create_work_order: handleCreateWorkOrder,
+    spawn_worker: handleSpawnWorker,
+    apply_patch: handleApplyPatch,
+    submit_receipt: handleSubmitReceipt,
+    // Phase 4
+    set_session_scope: handleSetSessionScope,
+    yield_for_scope_expansion: handleYieldForScopeExpansion,
 };
 export async function startMCPServer(options = {}) {
     // Initialize Tree-Sitter WASM once at startup

package/dist/mcp/tools/apply_patch.d.ts

@@ -0,0 +1,37 @@
+export declare class StalePatchError extends Error {
+    readonly filePath: string;
+    readonly expectedHash: string;
+    readonly actualHash: string;
+    constructor(filePath: string, expectedHash: string, actualHash: string);
+}
+export declare const applyPatchTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            filePath: {
+                type: string;
+                description: string;
+            };
+            newContent: {
+                type: string;
+                description: string;
+            };
+            expectedPrePatchHash: {
+                type: string;
+                description: string;
+            };
+            scanId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleApplyPatch(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/apply_patch.js

@@ -0,0 +1,103 @@
+import { writeFile, rename, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { SessionScope, ScopeViolation } from '../SessionScope.js';
+import { hashFile, BlobStore } from '../../store/BlobStore.js';
+import { PointerStore } from '../../store/PointerStore.js';
+import { applyBudgetGuard } from '../BudgetGuard.js';
+import { v4 as uuidv4 } from 'uuid';
+export class StalePatchError extends Error {
+    filePath;
+    expectedHash;
+    actualHash;
+    constructor(filePath, expectedHash, actualHash) {
+        super(`StalePatchError: ${filePath} hash mismatch — expected ${expectedHash}, got ${actualHash}. ` +
+            'File was modified since the expectedPrePatchHash was computed. Re-read the file and regenerate the patch.');
+        this.filePath = filePath;
+        this.expectedHash = expectedHash;
+        this.actualHash = actualHash;
+        this.name = 'StalePatchError';
+    }
+}
+export const applyPatchTool = {
+    name: 'apply_patch',
+    description: 'Applies a text patch to a file within the active workOrder scope. Requires expectedPrePatchHash to prevent stale-patch corruption. Records pre- and post-patch hashes.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            filePath: { type: 'string', description: 'Path relative to projectRoot' },
+            newContent: { type: 'string', description: 'Full new content of the file after the patch' },
+            expectedPrePatchHash: {
+                type: 'string',
+                description: 'sha256:<hex> hash of the file BEFORE patching. Obtain via hashFile or the sourceHash from get_file_skeleton.',
+            },
+            scanId: { type: 'string', description: 'Current scan ID for pointer registration' },
+        },
+        required: ['projectRoot', 'filePath', 'newContent', 'expectedPrePatchHash', 'scanId'],
+    },
+};
+export async function handleApplyPatch(args) {
+    const projectRoot = args.projectRoot;
+    const filePath = args.filePath;
+    const newContent = args.newContent;
+    const expectedPrePatchHash = args.expectedPrePatchHash;
+    const scanId = args.scanId;
+    if (!projectRoot || !filePath || !newContent || !expectedPrePatchHash || !scanId) {
+        throw new Error('projectRoot, filePath, newContent, expectedPrePatchHash, and scanId are all required');
+    }
+    // 1. Scope enforcement
+    try {
+        SessionScope.enforce(filePath);
+    }
+    catch (e) {
+        if (e instanceof ScopeViolation)
+            throw e;
+        throw e;
+    }
+    const absolutePath = filePath.startsWith('/') ? filePath : join(projectRoot, filePath);
+    // 2. Preimage hash check
+    let actualPreHash;
+    try {
+        actualPreHash = await hashFile(absolutePath);
+    }
+    catch {
+        // File doesn't exist yet — for new files, expectedPrePatchHash must be 'sha256:new'
+        actualPreHash = 'sha256:new';
+    }
+    if (actualPreHash !== expectedPrePatchHash) {
+        throw new StalePatchError(filePath, expectedPrePatchHash, actualPreHash);
+    }
+    // 3. Atomic write
+    const dir = dirname(absolutePath);
+    await mkdir(dir, { recursive: true });
+    const tmpPath = absolutePath + `.tmp_${Date.now()}`;
+    await writeFile(tmpPath, newContent, 'utf8');
+    await rename(tmpPath, absolutePath);
+    // 4. Compute post-patch hash
+    const postPatchHash = await hashFile(absolutePath);
+    // 5. Record both hashes in blob store
+    const blobStore = new BlobStore(projectRoot);
+    const pointerStore = PointerStore.open(projectRoot);
+    const { blobPath } = await blobStore.writeAtomic(newContent);
+    const pointerId = `ptr_patch_${uuidv4().replace(/-/g, '').slice(0, 12)}`;
+    await pointerStore.insertPointer({
+        pointerId,
+        scanId,
+        artifactName: 'patch_record',
+        contentHash: postPatchHash,
+        blobPath,
+        schemaVersion: '1.0.0',
+        createdAt: Date.now(),
+        expiresAt: null,
+    });
+    const result = {
+        ok: true,
+        filePath,
+        prePatchHash: actualPreHash,
+        postPatchHash,
+        pointerId,
+        message: `Patch applied to ${filePath}`,
+    };
+    return await applyBudgetGuard(projectRoot, scanId, 'patch_record', result);
+}
+//# sourceMappingURL=apply_patch.js.map

package/dist/mcp/tools/get_file_skeleton.d.ts

@@ -0,0 +1,23 @@
+export declare const getFileSkeletonTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            filePath: {
+                type: string;
+                description: string;
+            };
+            scanId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGetFileSkeleton(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/get_file_skeleton.js

@@ -0,0 +1,124 @@
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { SessionScope, ScopeViolation } from '../SessionScope.js';
+import { BlobStore, hashFile } from '../../store/BlobStore.js';
+import { PointerStore } from '../../store/PointerStore.js';
+import { applyBudgetGuard } from '../BudgetGuard.js';
+import { v4 as uuidv4 } from 'uuid';
+export const getFileSkeletonTool = {
+    name: 'get_file_skeleton',
+    description: 'Returns a content-addressed skeleton view of a source file (function signatures, class names, exported symbols). Enforces active workOrder scope. Results are content-addressed — repeated calls on unchanged files return cached pointers.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            filePath: { type: 'string', description: 'Path relative to projectRoot' },
+            scanId: { type: 'string', description: 'Current scan ID for pointer registration' },
+        },
+        required: ['projectRoot', 'filePath', 'scanId'],
+    },
+};
+export async function handleGetFileSkeleton(args) {
+    const projectRoot = args.projectRoot;
+    const filePath = args.filePath;
+    const scanId = args.scanId;
+    if (!projectRoot || !filePath || !scanId) {
+        throw new Error('projectRoot, filePath, and scanId are required');
+    }
+    // 1. Scope enforcement
+    try {
+        SessionScope.enforce(filePath);
+    }
+    catch (e) {
+        if (e instanceof ScopeViolation)
+            throw e;
+        throw e;
+    }
+    const absolutePath = filePath.startsWith('/') ? filePath : join(projectRoot, filePath);
+    // 2. Compute preimage hash of source file
+    let currentHash;
+    try {
+        currentHash = await hashFile(absolutePath);
+    }
+    catch {
+        throw new Error(`FileNotFound: cannot read ${filePath}`);
+    }
+    // 3. Check cache: same hash + parser version = return existing pointer
+    const parserVersion = '1.0.0';
+    const cacheKey = `skeleton:${currentHash}:${parserVersion}`;
+    const pointerStore = PointerStore.open(projectRoot);
+    // Look up by contentHash in existing pointers for this scan
+    const existingPointers = pointerStore.listPointersByScan(scanId);
+    const cached = existingPointers.find(p => p.artifactName === 'file_skeleton' && p.contentHash === cacheKey);
+    if (cached) {
+        return {
+            pointerId: cached.pointerId,
+            contentHash: currentHash,
+            cached: true,
+            filePath,
+        };
+    }
+    // 4. Build skeleton
+    const source = await readFile(absolutePath, 'utf8');
+    const skeleton = extractSkeleton(source, filePath);
+    // 5. Record content hash
+    const skeletonPayload = {
+        filePath,
+        sourceHash: currentHash,
+        parserVersion,
+        skeleton,
+    };
+    // 6. Budget enforcement
+    const blobStore = new BlobStore(projectRoot);
+    const serialized = JSON.stringify(skeletonPayload, null, 2);
+    const { contentHash: skeletonHash, blobPath } = await blobStore.writeAtomic(serialized);
+    const pointerId = `ptr_skel_${uuidv4().replace(/-/g, '').slice(0, 12)}`;
+    await pointerStore.insertPointer({
+        pointerId,
+        scanId,
+        artifactName: 'file_skeleton',
+        contentHash: cacheKey, // cache key encodes source hash + parser version
+        blobPath,
+        schemaVersion: '1.0.0',
+        createdAt: Date.now(),
+        expiresAt: null,
+    });
+    const result = {
+        filePath,
+        sourceHash: currentHash,
+        pointerId,
+        skeleton,
+    };
+    return await applyBudgetGuard(projectRoot, scanId, 'file_skeleton', result);
+}
+function extractSkeleton(source, filePath) {
+    const lines = source.split('\n');
+    const skeleton = [];
+    const ext = filePath.split('.').pop() ?? '';
+    const isTS = ['ts', 'tsx'].includes(ext);
+    const isJS = ['js', 'jsx', 'mjs', 'cjs'].includes(ext);
+    if (isTS || isJS) {
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].trim();
+            // Exported declarations, function/class/interface/type/enum signatures
+            if (/^(export\s+)?(async\s+)?function\b/.test(line) ||
+                /^(export\s+)?(abstract\s+)?class\b/.test(line) ||
+                /^(export\s+)?interface\b/.test(line) ||
+                /^(export\s+)?type\s+\w+/.test(line) ||
+                /^(export\s+)?enum\b/.test(line) ||
+                /^(export\s+)?const\s+\w+\s*[:=(]/.test(line) ||
+                /^(export\s+)?let\s+\w+\s*[:=(]/.test(line) ||
+                /^(export\s+)?(default\s+)/.test(line) ||
+                /^\s*(public|private|protected|static|readonly|abstract)\s+/.test(line) ||
+                /^import\b/.test(line)) {
+                skeleton.push(`L${i + 1}: ${lines[i]}`);
+            }
+        }
+    }
+    else {
+        // Generic: return first 80 lines as skeleton for unsupported types
+        return lines.slice(0, 80).map((l, i) => `L${i + 1}: ${l}`);
+    }
+    return skeleton;
+}
+//# sourceMappingURL=get_file_skeleton.js.map

package/dist/mcp/tools/hydration/get_evidence_slice.d.ts

@@ -0,0 +1,31 @@
+export declare const getEvidenceSliceTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            pointerId: {
+                type: string;
+                description: string;
+            };
+            startLine: {
+                type: string;
+                description: string;
+            };
+            endLine: {
+                type: string;
+                description: string;
+            };
+            scanId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGetEvidenceSlice(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/hydration/get_evidence_slice.js

@@ -0,0 +1,59 @@
+import { hydratePointer, applyBudgetGuard } from '../../BudgetGuard.js';
+import { SessionScope } from '../../SessionScope.js';
+export const getEvidenceSliceTool = {
+    name: 'get_evidence_slice',
+    description: 'Raw fallback: returns a line-range slice from a blob artifact. Pointer must be valid and unexpired. Output is budgeted.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            pointerId: { type: 'string', description: 'Pointer ID for the target artifact' },
+            startLine: { type: 'number', description: 'Inclusive start line (1-based)' },
+            endLine: { type: 'number', description: 'Inclusive end line (1-based). Capped at startLine+200.' },
+            scanId: { type: 'string', description: 'Current scan ID for budget pointer registration' },
+        },
+        required: ['projectRoot', 'pointerId', 'startLine', 'endLine', 'scanId'],
+    },
+};
+export async function handleGetEvidenceSlice(args) {
+    const projectRoot = args.projectRoot;
+    const pointerId = args.pointerId;
+    const startLine = Number(args.startLine);
+    const endLine = Math.min(Number(args.endLine), startLine + 200);
+    const scanId = args.scanId;
+    if (!projectRoot || !pointerId || !scanId) {
+        throw new Error('projectRoot, pointerId, startLine, endLine, and scanId are required');
+    }
+    // 1. Verify pointer, lifetime, hash
+    const { content, row } = await hydratePointer(projectRoot, pointerId);
+    const rawText = content.toString('utf8');
+    // 2. Scope enforcement for file-type artifacts: if a Worker scope is active,
+    //    file_read and file_skeleton blobs embed the source filePath — enforce it.
+    const scope = SessionScope.get();
+    if (scope && (row.artifactName === 'file_read' || row.artifactName === 'file_skeleton')) {
+        try {
+            const parsed = JSON.parse(rawText);
+            if (parsed.filePath) {
+                SessionScope.enforce(parsed.filePath);
+            }
+        }
+        catch (e) {
+            // If it's a ScopeViolation, re-throw; JSON parse failures are ignored.
+            if (e.name === 'ScopeViolation')
+                throw e;
+        }
+    }
+    const lines = rawText.split('\n');
+    const sliced = lines.slice(startLine - 1, endLine);
+    const result = {
+        pointerId,
+        artifactName: row.artifactName,
+        startLine,
+        endLine,
+        totalLines: lines.length,
+        slice: sliced,
+    };
+    // 2. Budget query result
+    return await applyBudgetGuard(projectRoot, scanId, 'evidence_slice', result);
+}
+//# sourceMappingURL=get_evidence_slice.js.map

package/dist/mcp/tools/hydration/get_project_summary.d.ts

@@ -0,0 +1,23 @@
+export declare const getProjectSummaryTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectRoot: {
+                type: string;
+                description: string;
+            };
+            manifestPointer: {
+                type: string;
+                description: string;
+            };
+            scanId: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGetProjectSummary(args: Record<string, unknown>): Promise<unknown>;

package/dist/mcp/tools/hydration/get_project_summary.js

@@ -0,0 +1,58 @@
+import { hydratePointer, applyBudgetGuard } from '../../BudgetGuard.js';
+export const getProjectSummaryTool = {
+    name: 'get_project_summary',
+    description: 'Returns high-level project metrics from a scan manifest pointer: file counts, pillar summary, stack. Token-safe. Pointer must be valid and unexpired.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectRoot: { type: 'string', description: 'Absolute project root' },
+            manifestPointer: { type: 'string', description: 'Pointer ID for the scan manifest' },
+            scanId: { type: 'string', description: 'Current scan ID for budget pointer registration' },
+        },
+        required: ['projectRoot', 'manifestPointer', 'scanId'],
+    },
+};
+export async function handleGetProjectSummary(args) {
+    const projectRoot = args.projectRoot;
+    const manifestPointer = args.manifestPointer;
+    const scanId = args.scanId;
+    if (!projectRoot || !manifestPointer || !scanId) {
+        throw new Error('projectRoot, manifestPointer, and scanId are required');
+    }
+    const { content, row } = await hydratePointer(projectRoot, manifestPointer);
+    const payload = JSON.parse(content.toString('utf8'));
+    if (row.artifactName === 'artifact_manifest') {
+        const manifest = payload;
+        const analysisEntry = manifest.artifacts.find(a => a.name === 'analysis' && a.indexes?.startHere);
+        let indexData = {};
+        if (analysisEntry?.indexes?.startHere) {
+            const { content: ic } = await hydratePointer(projectRoot, analysisEntry.indexes.startHere);
+            indexData = JSON.parse(ic.toString('utf8'));
+        }
+        const result = {
+            scanId: manifest.scanId,
+            generatedAt: manifest.generatedAt,
+            artifactCount: manifest.artifacts.length,
+            totalArtifactBytes: manifest.artifacts.reduce((s, a) => s + (a.sizeBytes ?? 0), 0),
+            startHere: indexData.startHere,
+            topHeat: indexData.topHeat,
+            pillarSummary: indexData.pillarSummary,
+            totalFiles: indexData.totalFiles,
+            realSourceFiles: indexData.realSourceFiles,
+        };
+        return await applyBudgetGuard(projectRoot, scanId, 'get_project_summary_result', result);
+    }
+    if (row.artifactName === 'analysis.index') {
+        const result = {
+            scanId: payload.scanId,
+            startHere: payload.startHere,
+            topHeat: payload.topHeat,
+            pillarSummary: payload.pillarSummary,
+            totalFiles: payload.totalFiles,
+            realSourceFiles: payload.realSourceFiles,
+        };
+        return await applyBudgetGuard(projectRoot, scanId, 'get_project_summary_result', result);
+    }
+    throw new Error(`Unsupported artifact type for get_project_summary: ${row.artifactName}`);
+}
+//# sourceMappingURL=get_project_summary.js.map