specforge-mcp 0.11.1 → 0.12.1

package/dist/engine/context-budget/checkpoint.d.ts

@@ -0,0 +1,8 @@
+import type { ContextBudgetStatus, SessionCheckpoint } from '../../types/index.js';
+/** Build a session checkpoint from available data. */
+export declare function generateCheckpoint(projectId: string, contextUsage: ContextBudgetStatus, options?: Partial<Omit<SessionCheckpoint, 'timestamp' | 'projectId' | 'contextUsage'>>): SessionCheckpoint;
+/** Format a checkpoint as human-readable Markdown. */
+export declare function formatCheckpoint(cp: SessionCheckpoint): string;
+/** Extract a one-line summary from a checkpoint. */
+export declare function parseCheckpointSummary(cp: SessionCheckpoint): string;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/engine/context-budget/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../../src/engine/context-budget/checkpoint.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAGlB,MAAM,sBAAsB,CAAC;AAa9B,sDAAsD;AACtD,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,mBAAmB,EACjC,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC,CAAC,GACrF,iBAAiB,CAcnB;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,iBAAiB,GAAG,MAAM,CA0D9D;AAED,oDAAoD;AACpD,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,iBAAiB,GAAG,MAAM,CAYpE"}

package/dist/engine/context-budget/checkpoint.js

@@ -0,0 +1,79 @@
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const EMPTY_GIT = { staged: [], unstaged: [], branch: 'unknown' };
+const EMPTY_PIPELINE = { typecheck: false, lint: false, tests: false };
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Build a session checkpoint from available data. */
+export function generateCheckpoint(projectId, contextUsage, options) {
+    return {
+        timestamp: new Date().toISOString(),
+        projectId,
+        summary: options?.summary ?? buildAutoSummary(contextUsage),
+        decisions: options?.decisions ?? [],
+        filesModified: options?.filesModified ?? [],
+        filesRead: options?.filesRead ?? [],
+        specsInProgress: options?.specsInProgress ?? [],
+        pendingWork: options?.pendingWork ?? [],
+        gitStatus: options?.gitStatus ?? EMPTY_GIT,
+        pipelineStatus: options?.pipelineStatus ?? EMPTY_PIPELINE,
+        contextUsage,
+    };
+}
+/** Format a checkpoint as human-readable Markdown. */
+export function formatCheckpoint(cp) {
+    const lines = [
+        `# Session Checkpoint`,
+        '',
+        `**Project:** ${cp.projectId}`,
+        `**Timestamp:** ${cp.timestamp}`,
+        `**Context usage:** ${String(cp.contextUsage.percentUsed)}% (${cp.contextUsage.alertLevel})`,
+        '',
+        `## Summary`,
+        cp.summary,
+        '',
+    ];
+    if (cp.decisions.length > 0) {
+        lines.push('## Decisions', ...cp.decisions.map((d) => `- ${d}`), '');
+    }
+    if (cp.filesModified.length > 0) {
+        lines.push('## Files Modified', ...cp.filesModified.map((f) => `- ${f}`), '');
+    }
+    if (cp.filesRead.length > 0) {
+        lines.push('## Files Read', ...cp.filesRead.map((f) => `- ${f}`), '');
+    }
+    if (cp.specsInProgress.length > 0) {
+        lines.push('## Specs In Progress', ...cp.specsInProgress.map((s) => `- ${s}`), '');
+    }
+    if (cp.pendingWork.length > 0) {
+        lines.push('## Pending Work', ...cp.pendingWork.map((w) => `- ${w}`), '');
+    }
+    lines.push('## Git Status', `Branch: ${cp.gitStatus.branch}`, `Staged: ${cp.gitStatus.staged.length > 0 ? cp.gitStatus.staged.join(', ') : 'none'}`, `Unstaged: ${cp.gitStatus.unstaged.length > 0 ? cp.gitStatus.unstaged.join(', ') : 'none'}`, '', '## Pipeline', `- Typecheck: ${cp.pipelineStatus.typecheck ? 'PASS' : 'PENDING'}`, `- Lint: ${cp.pipelineStatus.lint ? 'PASS' : 'PENDING'}`, `- Tests: ${cp.pipelineStatus.tests ? 'PASS' : 'PENDING'}`, '', '## Context Usage', `- Tokens used: ${String(cp.contextUsage.tokensEstimatedUsed)}`, `- Tokens available: ${String(cp.contextUsage.tokensEstimatedAvailable)}`, `- Operations: ${String(cp.contextUsage.operationCount)}`);
+    if (cp.contextUsage.topConsumers.length > 0) {
+        lines.push('- Top consumers:', ...cp.contextUsage.topConsumers.map((c) => `  - ${c.tool}: ${String(c.tokens)} tokens`));
+    }
+    return lines.join('\n');
+}
+/** Extract a one-line summary from a checkpoint. */
+export function parseCheckpointSummary(cp) {
+    const parts = [
+        `${String(cp.contextUsage.percentUsed)}% context`,
+        `${String(cp.contextUsage.operationCount)} ops`,
+    ];
+    if (cp.filesModified.length > 0) {
+        parts.push(`${String(cp.filesModified.length)} files modified`);
+    }
+    if (cp.specsInProgress.length > 0) {
+        parts.push(`specs: ${cp.specsInProgress.join(', ')}`);
+    }
+    return parts.join(' | ');
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function buildAutoSummary(usage) {
+    return `Auto-checkpoint at ${String(usage.percentUsed)}% context usage (${String(usage.operationCount)} operations, ${String(usage.tokensEstimatedUsed)} tokens estimated).`;
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/engine/context-budget/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../../src/engine/context-budget/checkpoint.ts"],"names":[],"mappings":"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"}

package/dist/engine/context-budget/compressor.d.ts

@@ -0,0 +1,20 @@
+import type { ResponseVerbosity } from '../../types/index.js';
+/**
+ * Determine the effective verbosity level, auto-degrading when context
+ * pressure exceeds the configured threshold.
+ */
+export declare function getEffectiveVerbosity(requested: ResponseVerbosity, percentUsed: number, autoCompressThreshold: number): {
+    verbosity: ResponseVerbosity;
+    autoCompressed: boolean;
+};
+/**
+ * Check whether the current context usage warrants auto-compression.
+ */
+export declare function shouldAutoCompress(percentUsed: number, threshold: number): boolean;
+/**
+ * Compress a tool response text based on the target verbosity level.
+ * - compact: strip code blocks, collapse bullet lists, shorten sections
+ * - minimal: return only first paragraph + structured summary
+ */
+export declare function compressResponse(text: string, targetVerbosity: ResponseVerbosity): string;
+//# sourceMappingURL=compressor.d.ts.map

package/dist/engine/context-budget/compressor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compressor.d.ts","sourceRoot":"","sources":["../../../src/engine/context-budget/compressor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAM9D;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,iBAAiB,EAC5B,WAAW,EAAE,MAAM,EACnB,qBAAqB,EAAE,MAAM,GAC5B;IAAE,SAAS,EAAE,iBAAiB,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,CAY3D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAElF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,iBAAiB,GAAG,MAAM,CAUzF"}

package/dist/engine/context-budget/compressor.js

@@ -0,0 +1,122 @@
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Determine the effective verbosity level, auto-degrading when context
+ * pressure exceeds the configured threshold.
+ */
+export function getEffectiveVerbosity(requested, percentUsed, autoCompressThreshold) {
+    const fraction = percentUsed / 100;
+    if (fraction < autoCompressThreshold) {
+        return { verbosity: requested, autoCompressed: false };
+    }
+    const degraded = degradeVerbosity(requested);
+    return {
+        verbosity: degraded,
+        autoCompressed: degraded !== requested,
+    };
+}
+/**
+ * Check whether the current context usage warrants auto-compression.
+ */
+export function shouldAutoCompress(percentUsed, threshold) {
+    return percentUsed / 100 >= threshold;
+}
+/**
+ * Compress a tool response text based on the target verbosity level.
+ * - compact: strip code blocks, collapse bullet lists, shorten sections
+ * - minimal: return only first paragraph + structured summary
+ */
+export function compressResponse(text, targetVerbosity) {
+    if (targetVerbosity === 'full') {
+        return text;
+    }
+    if (targetVerbosity === 'compact') {
+        return compactCompress(text);
+    }
+    return minimalCompress(text);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function degradeVerbosity(current) {
+    if (current === 'full') {
+        return 'compact';
+    }
+    if (current === 'compact') {
+        return 'minimal';
+    }
+    return 'minimal';
+}
+/** Compact: remove code blocks, trim long lists, keep structure. */
+function compactCompress(text) {
+    let result = text;
+    // Remove fenced code blocks
+    result = result.replace(/```[\s\S]*?```/g, '[code block omitted for brevity]');
+    // Collapse long bullet lists (>5 items) to first 3 + count
+    result = collapseListItems(result);
+    return result;
+}
+/** Minimal: extract first meaningful paragraph only. */
+function minimalCompress(text) {
+    const lines = text.split('\n');
+    const meaningful = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip empty lines and code blocks
+        if (trimmed === '' && meaningful.length > 0) {
+            break;
+        }
+        if (trimmed.startsWith('```')) {
+            break;
+        }
+        if (trimmed !== '') {
+            meaningful.push(trimmed);
+        }
+    }
+    return meaningful.length > 0 ? meaningful.join('\n') : text.slice(0, 200);
+}
+/** Collapse bullet lists with more than 5 items. */
+function collapseListItems(text) {
+    const lines = text.split('\n');
+    const result = [];
+    let bulletCount = 0;
+    let inBulletList = false;
+    let totalBullets = 0;
+    for (const line of lines) {
+        const isBullet = /^\s*[-*]\s/.test(line);
+        if (isBullet) {
+            if (!inBulletList) {
+                inBulletList = true;
+                bulletCount = 0;
+                totalBullets = countConsecutiveBullets(lines, lines.indexOf(line));
+            }
+            bulletCount++;
+            if (bulletCount <= 3) {
+                result.push(line);
+            }
+            else if (bulletCount === 4 && totalBullets > 5) {
+                result.push(`  ... and ${String(totalBullets - 3)} more items`);
+            }
+        }
+        else {
+            inBulletList = false;
+            bulletCount = 0;
+            result.push(line);
+        }
+    }
+    return result.join('\n');
+}
+function countConsecutiveBullets(lines, startIndex) {
+    let count = 0;
+    for (let i = startIndex; i < lines.length; i++) {
+        if (/^\s*[-*]\s/.test(lines[i] ?? '')) {
+            count++;
+        }
+        else {
+            break;
+        }
+    }
+    return count;
+}
+//# sourceMappingURL=compressor.js.map

package/dist/engine/context-budget/compressor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compressor.js","sourceRoot":"","sources":["../../../src/engine/context-budget/compressor.ts"],"names":[],"mappings":"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"}

package/dist/engine/context-budget/index.d.ts

@@ -0,0 +1,5 @@
+export { recordToolCall, getStatus, getWarning, setConfig, getConfig, getSessionOps, resetSession, estimateTokensFromText, DEFAULT_CONFIG, } from './tracker.js';
+export { generateCheckpoint, formatCheckpoint, parseCheckpointSummary } from './checkpoint.js';
+export { analyzeSession, generateDelegationHints, suggestExplorePrompt } from './optimizer.js';
+export { getEffectiveVerbosity, shouldAutoCompress, compressResponse } from './compressor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/context-budget/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/context-budget/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE/F,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE/F,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/engine/context-budget/index.js

@@ -0,0 +1,6 @@
+// engine/context-budget/index.ts — Barrel re-exports (SPEC-063)
+export { recordToolCall, getStatus, getWarning, setConfig, getConfig, getSessionOps, resetSession, estimateTokensFromText, DEFAULT_CONFIG, } from './tracker.js';
+export { generateCheckpoint, formatCheckpoint, parseCheckpointSummary } from './checkpoint.js';
+export { analyzeSession, generateDelegationHints, suggestExplorePrompt } from './optimizer.js';
+export { getEffectiveVerbosity, shouldAutoCompress, compressResponse } from './compressor.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/context-budget/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/context-budget/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,OAAO,EACL,cAAc,EACd,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE/F,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE/F,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/engine/context-budget/optimizer.d.ts

@@ -0,0 +1,8 @@
+import type { ContextBudgetStatus, ContextOptimizationResult, DelegationHint, SessionOperation } from '../../types/index.js';
+/** Analyze session operations and produce optimization recommendations. */
+export declare function analyzeSession(ops: SessionOperation[], status: ContextBudgetStatus): ContextOptimizationResult;
+/** Generate delegation hints based on session operation patterns. */
+export declare function generateDelegationHints(ops: SessionOperation[]): DelegationHint[];
+/** Build a ready-to-use Explore subagent prompt for batch file reading. */
+export declare function suggestExplorePrompt(files: string[]): string;
+//# sourceMappingURL=optimizer.d.ts.map

package/dist/engine/context-budget/optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../../../src/engine/context-budget/optimizer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAO9B,2EAA2E;AAC3E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,gBAAgB,EAAE,EACvB,MAAM,EAAE,mBAAmB,GAC1B,yBAAyB,CAO3B;AAED,qEAAqE;AACrE,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,cAAc,EAAE,CA6CjF;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAc5D"}

package/dist/engine/context-budget/optimizer.js

@@ -0,0 +1,87 @@
+import { recommendModel } from '../token-tracker.js';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Analyze session operations and produce optimization recommendations. */
+export function analyzeSession(ops, status) {
+    return {
+        currentUsage: status,
+        delegationHints: generateDelegationHints(ops),
+        filesAlreadyRead: extractFilesRead(ops),
+        topTokenConsumers: status.topConsumers,
+    };
+}
+/** Generate delegation hints based on session operation patterns. */
+export function generateDelegationHints(ops) {
+    const hints = [];
+    const toolCounts = countByTool(ops);
+    // Repeated reads → suggest Explore subagent
+    const readOps = toolCounts.consult_docs ?? 0;
+    if (readOps >= 3) {
+        hints.push({
+            operation: 'consult_docs',
+            reason: `Called ${String(readOps)} times — delegate batch lookups to an Explore subagent`,
+            suggestedModel: 'haiku',
+        });
+    }
+    // Heavy audit → suggest delegation
+    const auditOps = toolCounts.audit ?? 0;
+    if (auditOps >= 2) {
+        hints.push({
+            operation: 'audit',
+            reason: `${String(auditOps)} audit calls consume significant context — delegate to a dedicated subagent`,
+            suggestedModel: recommendModel('audit'),
+        });
+    }
+    // Many generate_tests calls
+    const testOps = toolCounts.generate_tests ?? 0;
+    if (testOps >= 2) {
+        hints.push({
+            operation: 'generate_tests',
+            reason: `${String(testOps)} test generation calls — consider batching in a subagent`,
+            suggestedModel: 'sonnet',
+        });
+    }
+    // Full-llm operations consuming too much
+    const fullLlmOps = ops.filter((op) => op.tokens >= 8000);
+    if (fullLlmOps.length >= 3) {
+        hints.push({
+            operation: 'full-llm-operations',
+            reason: `${String(fullLlmOps.length)} heavy operations detected — reduce by delegating to subagents with appropriate models`,
+            suggestedModel: 'sonnet',
+        });
+    }
+    return hints;
+}
+/** Build a ready-to-use Explore subagent prompt for batch file reading. */
+export function suggestExplorePrompt(files) {
+    if (files.length === 0) {
+        return '';
+    }
+    const fileList = files.map((f) => `- ${f}`).join('\n');
+    return [
+        'Read and summarize the following files. For each file, provide:',
+        '1. Purpose (one sentence)',
+        '2. Key exports (functions, types, constants)',
+        '3. Dependencies (imports from other project modules)',
+        '',
+        'Files:',
+        fileList,
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function countByTool(ops) {
+    const counts = {};
+    for (const op of ops) {
+        counts[op.tool] = (counts[op.tool] ?? 0) + 1;
+    }
+    return counts;
+}
+function extractFilesRead(ops) {
+    // Tools that typically involve reading files
+    const readTools = new Set(['consult_docs', 'audit', 'reverse_engineer', 'detect_drift']);
+    return ops.filter((op) => readTools.has(op.tool)).map((op) => op.tool);
+}
+//# sourceMappingURL=optimizer.js.map

package/dist/engine/context-budget/optimizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizer.js","sourceRoot":"","sources":["../../../src/engine/context-budget/optimizer.ts"],"names":[],"mappings":"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"}

package/dist/engine/context-budget/tracker.d.ts

@@ -0,0 +1,19 @@
+import type { ContextBudgetConfig, ContextBudgetStatus, ContextWarning, SessionOperation } from '../../types/index.js';
+export declare const DEFAULT_CONFIG: ContextBudgetConfig;
+/** Record a tool invocation with estimated token consumption. */
+export declare function recordToolCall(tool: string, responseLength?: number): void;
+/** Get the current context budget status. */
+export declare function getStatus(config?: ContextBudgetConfig): ContextBudgetStatus;
+/** Build a context warning if usage exceeds the warning threshold. */
+export declare function getWarning(config?: ContextBudgetConfig): ContextWarning | null;
+/** Update the active configuration. */
+export declare function setConfig(config: Partial<ContextBudgetConfig>): ContextBudgetConfig;
+/** Get the active configuration. */
+export declare function getConfig(): ContextBudgetConfig;
+/** Get the raw session operations list. */
+export declare function getSessionOps(): SessionOperation[];
+/** Reset all session state (for testing or new sessions). */
+export declare function resetSession(): void;
+/** Estimate tokens from text character length (chars × 0.25). */
+export declare function estimateTokensFromText(charCount: number): number;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/engine/context-budget/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../../src/engine/context-budget/tracker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,mBAAmB,EACnB,mBAAmB,EAEnB,cAAc,EACd,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAO9B,eAAO,MAAM,cAAc,EAAE,mBAM5B,CAAC;AAaF,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAK1E;AAED,6CAA6C;AAC7C,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,CAc3E;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,cAAc,GAAG,IAAI,CAe9E;AAED,uCAAuC;AACvC,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAGnF;AAED,oCAAoC;AACpC,wBAAgB,SAAS,IAAI,mBAAmB,CAE/C;AAED,2CAA2C;AAC3C,wBAAgB,aAAa,IAAI,gBAAgB,EAAE,CAElD;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,IAAI,IAAI,CAGnC;AAMD,iEAAiE;AACjE,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhE"}

package/dist/engine/context-budget/tracker.js

@@ -0,0 +1,113 @@
+import { estimateTokensForOperation } from '../token-tracker.js';
+// ---------------------------------------------------------------------------
+// Default configuration
+// ---------------------------------------------------------------------------
+export const DEFAULT_CONFIG = {
+    contextWindowSize: 200_000,
+    warningThreshold: 0.75,
+    criticalThreshold: 0.9,
+    autoCompressAbove: 0.75,
+    autoCheckpointAbove: 0.9,
+};
+// ---------------------------------------------------------------------------
+// In-memory session state (resets each server restart)
+// ---------------------------------------------------------------------------
+let sessionOps = [];
+let activeConfig = { ...DEFAULT_CONFIG };
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Record a tool invocation with estimated token consumption. */
+export function recordToolCall(tool, responseLength) {
+    const estimated = responseLength
+        ? estimateTokensFromText(responseLength)
+        : estimateTokensForOperation(tool);
+    sessionOps.push({ tool, tokens: estimated, timestamp: new Date().toISOString() });
+}
+/** Get the current context budget status. */
+export function getStatus(config) {
+    const cfg = config ?? activeConfig;
+    const totalUsed = sessionOps.reduce((sum, op) => sum + op.tokens, 0);
+    const available = Math.max(0, cfg.contextWindowSize - totalUsed);
+    const percent = cfg.contextWindowSize > 0 ? totalUsed / cfg.contextWindowSize : 0;
+    return {
+        tokensEstimatedUsed: totalUsed,
+        tokensEstimatedAvailable: available,
+        percentUsed: Math.round(percent * 100),
+        alertLevel: getAlertLevel(percent, cfg),
+        operationCount: sessionOps.length,
+        topConsumers: getTopConsumers(5),
+    };
+}
+/** Build a context warning if usage exceeds the warning threshold. */
+export function getWarning(config) {
+    const cfg = config ?? activeConfig;
+    const status = getStatus(cfg);
+    const percent = status.percentUsed / 100;
+    if (percent < cfg.warningThreshold) {
+        return null;
+    }
+    const recommendation = getRecommendation(percent, cfg);
+    return {
+        percentUsed: status.percentUsed,
+        tokensRemaining: status.tokensEstimatedAvailable,
+        recommendation,
+    };
+}
+/** Update the active configuration. */
+export function setConfig(config) {
+    activeConfig = { ...activeConfig, ...config };
+    return activeConfig;
+}
+/** Get the active configuration. */
+export function getConfig() {
+    return { ...activeConfig };
+}
+/** Get the raw session operations list. */
+export function getSessionOps() {
+    return [...sessionOps];
+}
+/** Reset all session state (for testing or new sessions). */
+export function resetSession() {
+    sessionOps = [];
+    activeConfig = { ...DEFAULT_CONFIG };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Estimate tokens from text character length (chars × 0.25). */
+export function estimateTokensFromText(charCount) {
+    return Math.ceil(charCount * 0.25);
+}
+function getAlertLevel(percent, cfg) {
+    if (percent >= cfg.criticalThreshold) {
+        return 'red';
+    }
+    if (percent >= cfg.warningThreshold) {
+        return 'orange';
+    }
+    if (percent >= 0.5) {
+        return 'yellow';
+    }
+    return 'green';
+}
+function getTopConsumers(limit) {
+    const byTool = {};
+    for (const op of sessionOps) {
+        byTool[op.tool] = (byTool[op.tool] ?? 0) + op.tokens;
+    }
+    return Object.entries(byTool)
+        .map(([tool, tokens]) => ({ tool, tokens }))
+        .sort((a, b) => b.tokens - a.tokens)
+        .slice(0, limit);
+}
+function getRecommendation(percent, cfg) {
+    if (percent >= cfg.criticalThreshold) {
+        return 'Context nearly exhausted. Generate a checkpoint immediately and start a new session.';
+    }
+    if (percent >= cfg.warningThreshold) {
+        return 'Context pressure high. Delegate remaining work to subagents or reduce response verbosity.';
+    }
+    return 'Context usage moderate. Consider delegating large reads to subagents.';
+}
+//# sourceMappingURL=tracker.js.map

package/dist/engine/context-budget/tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../../../src/engine/context-budget/tracker.ts"],"names":[],"mappings":"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"}

package/dist/storage/checkpoint-store.d.ts

@@ -0,0 +1,12 @@
+import type { SessionCheckpoint, ContextBudgetConfig, CheckpointSummary } from '../types/index.js';
+/** Save a checkpoint to disk. Returns the checkpoint filename (ID). */
+export declare function saveCheckpoint(projectId: string, checkpoint: SessionCheckpoint): Promise<string>;
+/** Load a specific checkpoint or the most recent one. */
+export declare function loadCheckpoint(projectId: string, checkpointId?: string): Promise<SessionCheckpoint | null>;
+/** List available checkpoints with summaries. */
+export declare function listCheckpoints(projectId: string, limit?: number): Promise<CheckpointSummary[]>;
+/** Load the context budget config for a project. */
+export declare function loadConfig(projectId: string): Promise<ContextBudgetConfig | null>;
+/** Save the context budget config for a project. */
+export declare function saveConfig(projectId: string, config: ContextBudgetConfig): Promise<void>;
+//# sourceMappingURL=checkpoint-store.d.ts.map

package/dist/storage/checkpoint-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../../src/storage/checkpoint-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAmBnG,uEAAuE;AACvE,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,iBAAiB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,yDAAyD;AACzD,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAkBnC;AAED,iDAAiD;AACjD,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkBjG;AAMD,oDAAoD;AACpD,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAEvF;AAED,oDAAoD;AACpD,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9F"}

package/dist/storage/checkpoint-store.js

@@ -0,0 +1,85 @@
+// storage/checkpoint-store.ts — Checkpoint persistence (SPEC-063)
+import { readdir, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readJson, writeJson, projectDataDir } from './base-store.js';
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+function checkpointsDir(projectId) {
+    return join(projectDataDir(projectId), 'checkpoints');
+}
+function configPath(projectId) {
+    return join(projectDataDir(projectId), 'context-budget.json');
+}
+// ---------------------------------------------------------------------------
+// Checkpoint CRUD
+// ---------------------------------------------------------------------------
+/** Save a checkpoint to disk. Returns the checkpoint filename (ID). */
+export async function saveCheckpoint(projectId, checkpoint) {
+    const dir = checkpointsDir(projectId);
+    await mkdir(dir, { recursive: true });
+    const id = checkpoint.timestamp.replace(/[:.]/g, '-');
+    const filePath = join(dir, `${id}.json`);
+    await writeFile(filePath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+    return id;
+}
+/** Load a specific checkpoint or the most recent one. */
+export async function loadCheckpoint(projectId, checkpointId) {
+    const dir = checkpointsDir(projectId);
+    if (checkpointId) {
+        return readJson(join(dir, `${checkpointId}.json`), null);
+    }
+    // Load most recent
+    const files = await listCheckpointFiles(dir);
+    if (files.length === 0) {
+        return null;
+    }
+    const latest = files[files.length - 1];
+    /* c8 ignore next 3 */
+    if (!latest) {
+        return null;
+    }
+    return readJson(join(dir, latest), null);
+}
+/** List available checkpoints with summaries. */
+export async function listCheckpoints(projectId, limit = 10) {
+    const dir = checkpointsDir(projectId);
+    const files = await listCheckpointFiles(dir);
+    const recent = files.slice(-limit);
+    const summaries = [];
+    for (const file of recent) {
+        const cp = await readJson(join(dir, file), null);
+        if (cp) {
+            summaries.push({
+                id: file.replace('.json', ''),
+                timestamp: cp.timestamp,
+                summary: cp.summary.slice(0, 120),
+            });
+        }
+    }
+    return summaries;
+}
+// ---------------------------------------------------------------------------
+// Config persistence
+// ---------------------------------------------------------------------------
+/** Load the context budget config for a project. */
+export async function loadConfig(projectId) {
+    return readJson(configPath(projectId), null);
+}
+/** Save the context budget config for a project. */
+export async function saveConfig(projectId, config) {
+    await writeJson(configPath(projectId), config);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function listCheckpointFiles(dir) {
+    try {
+        const entries = await readdir(dir);
+        return entries.filter((f) => f.endsWith('.json')).sort();
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=checkpoint-store.js.map