specforge-mcp 0.11.0 → 0.12.0

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/engine/doc-generator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=doc-generator.test.d.ts.map

package/dist/engine/doc-generator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-generator.test.d.ts","sourceRoot":"","sources":["../../src/engine/doc-generator.test.ts"],"names":[],"mappings":""}