open-multi-agent-kit 0.80.7 → 0.80.8

package/dist/core/context-budget-governor.js

@@ -0,0 +1,224 @@
+import { createHash } from "node:crypto";
+import { createFallbackTokenCounter } from "./context-budget-token-counter.js";
+export const CONTEXT_BUDGET_POLICY_VERSION = "context-budget-v1";
+export function planContextBudget(input) {
+    const tokenCounter = input.tokenCounter ?? createFallbackTokenCounter();
+    const modelId = input.modelId ?? "unknown";
+    const diagnostics = [];
+    const maxTokens = normalizeBudgetTokens("maxTokens", input.maxTokens, diagnostics);
+    const responseReserveTokens = normalizeBudgetTokens("responseReserveTokens", input.responseReserveTokens ?? 0, diagnostics);
+    const availableTokens = Math.max(0, maxTokens - responseReserveTokens);
+    const plannedItems = input.items.map((item) => planItem(item, tokenCounter, modelId, diagnostics));
+    const includedIds = new Set();
+    let usedTokens = 0;
+    for (const item of plannedItems) {
+        if (item.priority !== "hard") {
+            continue;
+        }
+        includedIds.add(item.id);
+        usedTokens += item.estimatedTokens;
+    }
+    if (usedTokens > availableTokens) {
+        diagnostics.push({
+            reason: "hard_pin_over_capacity",
+            detail: `hard-pinned context uses ${usedTokens} tokens against ${availableTokens} available tokens`,
+        });
+    }
+    const selectedRedundancyKeys = new Set();
+    const remainingOptionalItems = plannedItems.filter((item) => item.priority !== "hard");
+    while (remainingOptionalItems.length > 0) {
+        const rankedItems = remainingOptionalItems
+            .map((item) => applyRedundancyPenalty(item, selectedRedundancyKeys))
+            .sort(comparePlannedItemsForSelection);
+        const selected = rankedItems.find((item) => usedTokens + item.estimatedTokens <= availableTokens);
+        if (!selected) {
+            break;
+        }
+        includedIds.add(selected.id);
+        usedTokens += selected.estimatedTokens;
+        if (selected.redundancyKey) {
+            selectedRedundancyKeys.add(selected.redundancyKey);
+        }
+        const selectedIndex = remainingOptionalItems.findIndex((item) => item.id === selected.id);
+        remainingOptionalItems.splice(selectedIndex, 1);
+    }
+    const includedItems = plannedItems.filter((item) => includedIds.has(item.id));
+    const omittedItems = plannedItems.filter((item) => !includedIds.has(item.id));
+    for (const item of omittedItems) {
+        diagnostics.push({ reason: "item_omitted", itemId: item.id, detail: `${item.kind} omitted from context budget` });
+    }
+    const omittedTokens = omittedItems.reduce((sum, item) => sum + item.estimatedTokens, 0);
+    const omittedHighPriority = omittedItems.some((item) => item.priority === "high");
+    const emergency = usedTokens > availableTokens || diagnostics.some((diagnostic) => diagnostic.reason === "invalid_budget");
+    const policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION;
+    const planWithoutHash = {
+        policyVersion,
+        maxTokens,
+        responseReserveTokens,
+        availableTokens,
+        usedTokens,
+        omittedTokens,
+        emergency,
+        omittedHighPriority,
+        included: includedItems.map((item) => [item.id, item.estimatedTokens, item.score]),
+        omitted: omittedItems.map((item) => [item.id, item.estimatedTokens, item.score]),
+    };
+    const planHash = createHash("sha256").update(JSON.stringify(planWithoutHash), "utf8").digest("hex");
+    const observability = buildObservability({
+        availableTokens,
+        diagnostics,
+        includedItems,
+        omittedItems,
+        omittedTokens,
+        planHash,
+        usedTokens,
+    });
+    return {
+        policyVersion,
+        maxTokens,
+        responseReserveTokens,
+        availableTokens,
+        usedTokens,
+        omittedTokens,
+        emergency,
+        omittedHighPriority,
+        includedItems,
+        omittedItems,
+        diagnostics,
+        planHash,
+        observability,
+    };
+}
+export function scoreContextBudgetItem(item, estimatedTokens) {
+    const priorityScore = priorityWeight(item.priority);
+    const relevance = clampScore(item.relevance) * 20;
+    const recency = clampScore(item.recency) * 10;
+    const evidence = clampScore(item.evidenceValue) * 15;
+    // G1: costPenalty 비례화 — sqrt 기반으로 대항목에 더 큰 불이익 부여.
+    // log2(t)*2는 1000토큰에서 ~19.9점으로 relevance(20점)와 동급 → 대항목 생존.
+    // sqrt(t)*0.5는 1000토큰 15.8점, 5000토큰 35.4점, 10000토큰 50점 → 비례적 증가.
+    const costPenalty = Math.sqrt(normalizeTokenCount(estimatedTokens)) * 0.5;
+    return priorityScore + relevance + recency + evidence - costPenalty;
+}
+function planItem(item, tokenCounter, modelId, diagnostics) {
+    const rawEstimate = item.tokenEstimate ?? tokenCounter.countText(item.text, modelId).tokens;
+    const estimatedTokens = normalizeItemTokenEstimate(item.id, rawEstimate, diagnostics);
+    return {
+        ...item,
+        estimatedTokens,
+        score: item.priority === "hard" ? Number.POSITIVE_INFINITY : scoreContextBudgetItem(item, estimatedTokens),
+    };
+}
+const REDUNDANCY_PENALTY_FLOOR = 10;
+const REDUNDANCY_PENALTY_SCALE = 0.8;
+/**
+ * W4: Adaptive redundancy penalty — proportional to token count.
+ * Large duplicates waste more budget so deserve higher penalty.
+ * Formula: max(floor, sqrt(tokens) * scale)
+ * - 200 tokens → 11.3   (near floor — minimal waste)
+ * - 1000 tokens → 25.3  (moderate waste)
+ * - 5000 tokens → 56.6  (heavy waste — strongly penalized)
+ * Floor ensures small duplicates are still penalized meaningfully.
+ * Scale (0.8) tuned to score medium=50 so large duplicates go negative.
+ */
+function redundancyPenalty(estimatedTokens) {
+    return Math.max(REDUNDANCY_PENALTY_FLOOR, Math.sqrt(estimatedTokens) * REDUNDANCY_PENALTY_SCALE);
+}
+function applyRedundancyPenalty(item, selectedRedundancyKeys) {
+    if (!item.redundancyKey || !selectedRedundancyKeys.has(item.redundancyKey)) {
+        return item;
+    }
+    return { ...item, score: item.score - redundancyPenalty(item.estimatedTokens) };
+}
+function comparePlannedItemsForSelection(a, b) {
+    // G2: 우선순위 티어 내부에서 밀도(score/tokens) 기반 정렬.
+    // 단위 토큰당 가치가 높은 항목을 우선 선택 → 예산 활용률 극대화.
+    const aTier = priorityTier(a.priority);
+    const bTier = priorityTier(b.priority);
+    if (aTier !== bTier) {
+        return aTier - bTier;
+    }
+    const aDensity = a.score > 0 ? a.score / Math.max(a.estimatedTokens, 1) : 0;
+    const bDensity = b.score > 0 ? b.score / Math.max(b.estimatedTokens, 1) : 0;
+    if (aDensity !== bDensity) {
+        return bDensity - aDensity;
+    }
+    if (a.estimatedTokens !== b.estimatedTokens) {
+        return a.estimatedTokens - b.estimatedTokens;
+    }
+    return a.id.localeCompare(b.id);
+}
+function priorityTier(priority) {
+    switch (priority) {
+        case "hard":
+            return 0;
+        case "high":
+            return 1;
+        case "medium":
+            return 2;
+        case "low":
+            return 3;
+    }
+}
+function priorityWeight(priority) {
+    switch (priority) {
+        case "hard":
+            return 1_000_000;
+        case "high":
+            return 100;
+        case "medium":
+            return 50;
+        case "low":
+            return 10;
+    }
+}
+function clampScore(value) {
+    if (value === undefined || !Number.isFinite(value)) {
+        return 0;
+    }
+    return Math.max(0, Math.min(1, value));
+}
+function normalizeBudgetTokens(field, value, diagnostics) {
+    if (!Number.isFinite(value) || value < 0) {
+        diagnostics.push({
+            reason: "invalid_budget",
+            detail: `${field} must be a non-negative finite number, got ${value}`,
+        });
+        return 0;
+    }
+    return Math.floor(value);
+}
+function normalizeItemTokenEstimate(itemId, value, diagnostics) {
+    if (!Number.isFinite(value) || value < 0) {
+        diagnostics.push({
+            reason: "invalid_budget",
+            itemId,
+            detail: `tokenEstimate must be a non-negative finite number, got ${value}`,
+        });
+        return 0;
+    }
+    return Math.ceil(value);
+}
+function normalizeTokenCount(value) {
+    if (!Number.isFinite(value) || value < 0) {
+        return 0;
+    }
+    return value;
+}
+function buildObservability(input) {
+    return {
+        counts: {
+            selected: input.includedItems.length,
+            omitted: input.omittedItems.length,
+        },
+        diagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),
+        tokens: {
+            available: input.availableTokens,
+            used: input.usedTokens,
+            omitted: input.omittedTokens,
+            tokenSavings: input.omittedTokens,
+        },
+        planHash: input.planHash,
+    };
+}
+//# sourceMappingURL=context-budget-governor.js.map

package/dist/core/context-budget-governor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-governor.js","sourceRoot":"","sources":["../../src/core/context-budget-governor.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\n\nexport type ContextBudgetItemKind =\n\t| \"system\"\n\t| \"context-pointer\"\n\t| \"context-full\"\n\t| \"skill-header\"\n\t| \"skill\"\n\t| \"mcp\"\n\t| \"history\"\n\t| \"tool-result\"\n\t| \"subagent-evidence\"\n\t| \"budget-note\";\n\nexport type ContextBudgetPriority = \"hard\" | \"high\" | \"medium\" | \"low\";\nexport type ContextBudgetDiagnosticReason = \"hard_pin_over_capacity\" | \"item_omitted\" | \"invalid_budget\";\n\nexport interface ContextBudgetItem {\n\treadonly id: string;\n\treadonly kind: ContextBudgetItemKind;\n\treadonly text: string;\n\treadonly priority: ContextBudgetPriority;\n\treadonly tokenEstimate?: number;\n\treadonly relevance?: number;\n\treadonly recency?: number;\n\treadonly evidenceValue?: number;\n\treadonly redundancyKey?: string;\n}\n\nexport interface ContextBudgetGovernorInput {\n\treadonly maxTokens: number;\n\treadonly responseReserveTokens?: number;\n\treadonly modelId?: string;\n\treadonly policyVersion?: string;\n\treadonly items: readonly ContextBudgetItem[];\n\treadonly tokenCounter?: TokenCounterAdapter;\n}\n\nexport interface ContextBudgetPlannedItem extends ContextBudgetItem {\n\treadonly estimatedTokens: number;\n\treadonly score: number;\n}\n\nexport interface ContextBudgetDiagnostic {\n\treadonly reason: ContextBudgetDiagnosticReason;\n\treadonly itemId?: string;\n\treadonly detail: string;\n}\n\nexport interface ContextBudgetObservabilityCounts {\n\treadonly selected: number;\n\treadonly omitted: number;\n}\n\nexport interface ContextBudgetObservabilityTokens {\n\treadonly available: number;\n\treadonly used: number;\n\treadonly omitted: number;\n\treadonly tokenSavings: number;\n}\n\nexport interface ContextBudgetObservability {\n\treadonly counts: ContextBudgetObservabilityCounts;\n\treadonly diagnosticReasons: readonly ContextBudgetDiagnosticReason[];\n\treadonly tokens: ContextBudgetObservabilityTokens;\n\treadonly planHash: string;\n}\n\nexport interface ContextBudgetPlan {\n\treadonly policyVersion: string;\n\treadonly maxTokens: number;\n\treadonly responseReserveTokens: number;\n\treadonly availableTokens: number;\n\treadonly usedTokens: number;\n\treadonly omittedTokens: number;\n\treadonly emergency: boolean;\n\treadonly omittedHighPriority: boolean;\n\treadonly includedItems: readonly ContextBudgetPlannedItem[];\n\treadonly omittedItems: readonly ContextBudgetPlannedItem[];\n\treadonly diagnostics: readonly ContextBudgetDiagnostic[];\n\treadonly planHash: string;\n\treadonly observability: ContextBudgetObservability;\n}\n\nexport const CONTEXT_BUDGET_POLICY_VERSION = \"context-budget-v1\";\n\nexport function planContextBudget(input: ContextBudgetGovernorInput): ContextBudgetPlan {\n\tconst tokenCounter = input.tokenCounter ?? createFallbackTokenCounter();\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst diagnostics: ContextBudgetDiagnostic[] = [];\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserveTokens = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst availableTokens = Math.max(0, maxTokens - responseReserveTokens);\n\tconst plannedItems = input.items.map((item) => planItem(item, tokenCounter, modelId, diagnostics));\n\tconst includedIds = new Set<string>();\n\tlet usedTokens = 0;\n\n\tfor (const item of plannedItems) {\n\t\tif (item.priority !== \"hard\") {\n\t\t\tcontinue;\n\t\t}\n\t\tincludedIds.add(item.id);\n\t\tusedTokens += item.estimatedTokens;\n\t}\n\n\tif (usedTokens > availableTokens) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${availableTokens} available tokens`,\n\t\t});\n\t}\n\n\tconst selectedRedundancyKeys = new Set<string>();\n\tconst remainingOptionalItems = plannedItems.filter((item) => item.priority !== \"hard\");\n\n\twhile (remainingOptionalItems.length > 0) {\n\t\tconst rankedItems = remainingOptionalItems\n\t\t\t.map((item) => applyRedundancyPenalty(item, selectedRedundancyKeys))\n\t\t\t.sort(comparePlannedItemsForSelection);\n\t\tconst selected = rankedItems.find((item) => usedTokens + item.estimatedTokens <= availableTokens);\n\t\tif (!selected) {\n\t\t\tbreak;\n\t\t}\n\n\t\tincludedIds.add(selected.id);\n\t\tusedTokens += selected.estimatedTokens;\n\t\tif (selected.redundancyKey) {\n\t\t\tselectedRedundancyKeys.add(selected.redundancyKey);\n\t\t}\n\n\t\tconst selectedIndex = remainingOptionalItems.findIndex((item) => item.id === selected.id);\n\t\tremainingOptionalItems.splice(selectedIndex, 1);\n\t}\n\n\tconst includedItems = plannedItems.filter((item) => includedIds.has(item.id));\n\tconst omittedItems = plannedItems.filter((item) => !includedIds.has(item.id));\n\tfor (const item of omittedItems) {\n\t\tdiagnostics.push({ reason: \"item_omitted\", itemId: item.id, detail: `${item.kind} omitted from context budget` });\n\t}\n\tconst omittedTokens = omittedItems.reduce((sum, item) => sum + item.estimatedTokens, 0);\n\tconst omittedHighPriority = omittedItems.some((item) => item.priority === \"high\");\n\tconst emergency =\n\t\tusedTokens > availableTokens || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\");\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION;\n\n\tconst planWithoutHash = {\n\t\tpolicyVersion,\n\t\tmaxTokens,\n\t\tresponseReserveTokens,\n\t\tavailableTokens,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\temergency,\n\t\tomittedHighPriority,\n\t\tincluded: includedItems.map((item) => [item.id, item.estimatedTokens, item.score]),\n\t\tomitted: omittedItems.map((item) => [item.id, item.estimatedTokens, item.score]),\n\t};\n\tconst planHash = createHash(\"sha256\").update(JSON.stringify(planWithoutHash), \"utf8\").digest(\"hex\");\n\tconst observability = buildObservability({\n\t\tavailableTokens,\n\t\tdiagnostics,\n\t\tincludedItems,\n\t\tomittedItems,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\tusedTokens,\n\t});\n\n\treturn {\n\t\tpolicyVersion,\n\t\tmaxTokens,\n\t\tresponseReserveTokens,\n\t\tavailableTokens,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\temergency,\n\t\tomittedHighPriority,\n\t\tincludedItems,\n\t\tomittedItems,\n\t\tdiagnostics,\n\t\tplanHash,\n\t\tobservability,\n\t};\n}\n\nexport function scoreContextBudgetItem(item: ContextBudgetItem, estimatedTokens: number): number {\n\tconst priorityScore = priorityWeight(item.priority);\n\tconst relevance = clampScore(item.relevance) * 20;\n\tconst recency = clampScore(item.recency) * 10;\n\tconst evidence = clampScore(item.evidenceValue) * 15;\n\t// G1: costPenalty 비례화 — sqrt 기반으로 대항목에 더 큰 불이익 부여.\n\t// log2(t)*2는 1000토큰에서 ~19.9점으로 relevance(20점)와 동급 → 대항목 생존.\n\t// sqrt(t)*0.5는 1000토큰 15.8점, 5000토큰 35.4점, 10000토큰 50점 → 비례적 증가.\n\tconst costPenalty = Math.sqrt(normalizeTokenCount(estimatedTokens)) * 0.5;\n\treturn priorityScore + relevance + recency + evidence - costPenalty;\n}\n\nfunction planItem(\n\titem: ContextBudgetItem,\n\ttokenCounter: TokenCounterAdapter,\n\tmodelId: string,\n\tdiagnostics: ContextBudgetDiagnostic[],\n): ContextBudgetPlannedItem {\n\tconst rawEstimate = item.tokenEstimate ?? tokenCounter.countText(item.text, modelId).tokens;\n\tconst estimatedTokens = normalizeItemTokenEstimate(item.id, rawEstimate, diagnostics);\n\treturn {\n\t\t...item,\n\t\testimatedTokens,\n\t\tscore: item.priority === \"hard\" ? Number.POSITIVE_INFINITY : scoreContextBudgetItem(item, estimatedTokens),\n\t};\n}\n\nconst REDUNDANCY_PENALTY_FLOOR = 10;\nconst REDUNDANCY_PENALTY_SCALE = 0.8;\n\n/**\n * W4: Adaptive redundancy penalty — proportional to token count.\n * Large duplicates waste more budget so deserve higher penalty.\n * Formula: max(floor, sqrt(tokens) * scale)\n * - 200 tokens → 11.3   (near floor — minimal waste)\n * - 1000 tokens → 25.3  (moderate waste)\n * - 5000 tokens → 56.6  (heavy waste — strongly penalized)\n * Floor ensures small duplicates are still penalized meaningfully.\n * Scale (0.8) tuned to score medium=50 so large duplicates go negative.\n */\nfunction redundancyPenalty(estimatedTokens: number): number {\n\treturn Math.max(REDUNDANCY_PENALTY_FLOOR, Math.sqrt(estimatedTokens) * REDUNDANCY_PENALTY_SCALE);\n}\n\nfunction applyRedundancyPenalty(\n\titem: ContextBudgetPlannedItem,\n\tselectedRedundancyKeys: Set<string>,\n): ContextBudgetPlannedItem {\n\tif (!item.redundancyKey || !selectedRedundancyKeys.has(item.redundancyKey)) {\n\t\treturn item;\n\t}\n\treturn { ...item, score: item.score - redundancyPenalty(item.estimatedTokens) };\n}\n\nfunction comparePlannedItemsForSelection(a: ContextBudgetPlannedItem, b: ContextBudgetPlannedItem): number {\n\t// G2: 우선순위 티어 내부에서 밀도(score/tokens) 기반 정렬.\n\t// 단위 토큰당 가치가 높은 항목을 우선 선택 → 예산 활용률 극대화.\n\tconst aTier = priorityTier(a.priority);\n\tconst bTier = priorityTier(b.priority);\n\tif (aTier !== bTier) {\n\t\treturn aTier - bTier;\n\t}\n\tconst aDensity = a.score > 0 ? a.score / Math.max(a.estimatedTokens, 1) : 0;\n\tconst bDensity = b.score > 0 ? b.score / Math.max(b.estimatedTokens, 1) : 0;\n\tif (aDensity !== bDensity) {\n\t\treturn bDensity - aDensity;\n\t}\n\tif (a.estimatedTokens !== b.estimatedTokens) {\n\t\treturn a.estimatedTokens - b.estimatedTokens;\n\t}\n\treturn a.id.localeCompare(b.id);\n}\n\nfunction priorityTier(priority: ContextBudgetPriority): number {\n\tswitch (priority) {\n\t\tcase \"hard\":\n\t\t\treturn 0;\n\t\tcase \"high\":\n\t\t\treturn 1;\n\t\tcase \"medium\":\n\t\t\treturn 2;\n\t\tcase \"low\":\n\t\t\treturn 3;\n\t}\n}\n\nfunction priorityWeight(priority: ContextBudgetPriority): number {\n\tswitch (priority) {\n\t\tcase \"hard\":\n\t\t\treturn 1_000_000;\n\t\tcase \"high\":\n\t\t\treturn 100;\n\t\tcase \"medium\":\n\t\t\treturn 50;\n\t\tcase \"low\":\n\t\t\treturn 10;\n\t}\n}\n\nfunction clampScore(value: number | undefined): number {\n\tif (value === undefined || !Number.isFinite(value)) {\n\t\treturn 0;\n\t}\n\treturn Math.max(0, Math.min(1, value));\n}\n\nfunction normalizeBudgetTokens(\n\tfield: \"maxTokens\" | \"responseReserveTokens\",\n\tvalue: number,\n\tdiagnostics: ContextBudgetDiagnostic[],\n): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction normalizeItemTokenEstimate(itemId: string, value: number, diagnostics: ContextBudgetDiagnostic[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\titemId,\n\t\t\tdetail: `tokenEstimate must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.ceil(value);\n}\n\nfunction normalizeTokenCount(value: number): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\treturn 0;\n\t}\n\treturn value;\n}\n\nfunction buildObservability(input: {\n\treadonly availableTokens: number;\n\treadonly diagnostics: readonly ContextBudgetDiagnostic[];\n\treadonly includedItems: readonly ContextBudgetPlannedItem[];\n\treadonly omittedItems: readonly ContextBudgetPlannedItem[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly usedTokens: number;\n}): ContextBudgetObservability {\n\treturn {\n\t\tcounts: {\n\t\t\tselected: input.includedItems.length,\n\t\t\tomitted: input.omittedItems.length,\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.availableTokens,\n\t\t\tused: input.usedTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: input.omittedTokens,\n\t\t},\n\t\tplanHash: input.planHash,\n\t};\n}\n"]}

package/dist/core/context-budget-headroom-candidates.d.ts

@@ -0,0 +1,3 @@
+import { type ContextBudgetItemV2, type ContextRepresentationCandidateV2, type HeadroomQualityPolicyV2 } from "./context-budget-headroom-types.ts";
+export declare function deriveRepresentationCandidates(item: ContextBudgetItemV2, policy?: HeadroomQualityPolicyV2): readonly ContextRepresentationCandidateV2[];
+//# sourceMappingURL=context-budget-headroom-candidates.d.ts.map

package/dist/core/context-budget-headroom-candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-headroom-candidates.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-headroom-candidates.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,gCAAgC,EAMrC,KAAK,uBAAuB,EAC5B,MAAM,oCAAoC,CAAC;AAK5C,wBAAgB,8BAA8B,CAC7C,IAAI,EAAE,mBAAmB,EACzB,MAAM,GAAE,uBAAyD,GAC/D,SAAS,gCAAgC,EAAE,CA0D7C","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextRepresentationCandidateV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n\testimatePointerTokens,\n\tfnv1aHex,\n\tfullTextTokens,\n\ttype HeadroomQualityPolicyV2,\n} from \"./context-budget-headroom-types.ts\";\n\nconst SUMMARY_HEAD_CHARS = 160;\nconst HEADROOM_HEAD_CHARS = 120;\n\nexport function deriveRepresentationCandidates(\n\titem: ContextBudgetItemV2,\n\tpolicy: HeadroomQualityPolicyV2 = DEFAULT_HEADROOM_QUALITY_POLICY,\n): readonly ContextRepresentationCandidateV2[] {\n\tconst full = fullTextTokens(item);\n\tconst sourceRef = item.sourceRef;\n\tconst retrievable = sourceRef?.retrievable === true;\n\tconst candidates: ContextRepresentationCandidateV2[] = [];\n\n\tcandidates.push({\n\t\tkind: \"full\",\n\t\ttext: item.text,\n\t\testimatedTokens: full,\n\t\tfidelity: item.tokenEstimate !== undefined ? \"exact\" : \"bounded\",\n\t\tsourceRef,\n\t});\n\n\tif (retrievable && sourceRef) {\n\t\tcandidates.push({\n\t\t\tkind: \"pointer\",\n\t\t\ttext: formatPointer(sourceRef),\n\t\t\testimatedTokens: estimatePointerTokens(sourceRef),\n\t\t\tfidelity: \"bounded\",\n\t\t\tsourceRef,\n\t\t});\n\t}\n\n\tconst summaryTokens = Math.ceil(full * 0.15) + 8;\n\tif (isSummaryEligible(item, full, policy) && summaryTokens < full) {\n\t\tcandidates.push({\n\t\t\tkind: \"summary\",\n\t\t\ttext: summarizeText(item.text),\n\t\t\testimatedTokens: summaryTokens,\n\t\t\tfidelity: \"lossy\",\n\t\t\tsummaryHash: fnv1aHex(item.text),\n\t\t});\n\t}\n\n\tconst headroomTokens = Math.ceil(full * 0.35) + 16;\n\tif (full > policy.headroomThresholdTokens && retrievable && headroomTokens < full) {\n\t\tcandidates.push({\n\t\t\tkind: \"headroom-compressed\",\n\t\t\ttext: formatHeadroom(item.text, sourceRef),\n\t\t\testimatedTokens: headroomTokens,\n\t\t\tfidelity: \"reversible\",\n\t\t\tsourceRef,\n\t\t\tcompressorId: \"headroom-shadow\",\n\t\t});\n\t}\n\n\tif (policy.allowOmit) {\n\t\tcandidates.push({\n\t\t\tkind: \"omit\",\n\t\t\ttext: \"\",\n\t\t\testimatedTokens: 0,\n\t\t\tfidelity: \"lossy\",\n\t\t\tsourceRef,\n\t\t});\n\t}\n\n\treturn candidates;\n}\n\nfunction isSummaryEligible(item: ContextBudgetItemV2, fullTokens: number, policy: HeadroomQualityPolicyV2): boolean {\n\treturn (\n\t\titem.tier === \"history\" ||\n\t\titem.tier === \"evidence\" ||\n\t\titem.tier === \"scratch\" ||\n\t\t(item.ageTurns ?? 0) >= policy.summaryMaxAgeTurns ||\n\t\tfullTokens > policy.headroomThresholdTokens\n\t);\n}\n\nfunction formatPointer(ref: ContextSourceRefV2): string {\n\tconst parts: string[] = [`uri=${ref.uri}`];\n\tif (ref.symbol) parts.push(`symbol=${ref.symbol}`);\n\tif (ref.range) parts.push(`lines=${ref.range.startLine}-${ref.range.endLine}`);\n\tparts.push(`hash=${ref.contentHash}`);\n\treturn `<pointer ${parts.join(\" \")} />`;\n}\n\nfunction summarizeText(text: string): string {\n\tif (text.length <= SUMMARY_HEAD_CHARS) {\n\t\treturn text;\n\t}\n\treturn `${text.slice(0, SUMMARY_HEAD_CHARS)} …[summary]`;\n}\n\nfunction formatHeadroom(text: string, ref?: ContextSourceRefV2): string {\n\tconst head = text.slice(0, HEADROOM_HEAD_CHARS);\n\tconst hash = fnv1aHex(text);\n\tconst where = ref ? ` uri=${ref.uri}` : \"\";\n\treturn `${head} …[headroom-compressed${where} hash=${hash}]`;\n}\n"]}

package/dist/core/context-budget-headroom-candidates.js

@@ -0,0 +1,85 @@
+import { DEFAULT_HEADROOM_QUALITY_POLICY, estimatePointerTokens, fnv1aHex, fullTextTokens, } from "./context-budget-headroom-types.js";
+const SUMMARY_HEAD_CHARS = 160;
+const HEADROOM_HEAD_CHARS = 120;
+export function deriveRepresentationCandidates(item, policy = DEFAULT_HEADROOM_QUALITY_POLICY) {
+    const full = fullTextTokens(item);
+    const sourceRef = item.sourceRef;
+    const retrievable = sourceRef?.retrievable === true;
+    const candidates = [];
+    candidates.push({
+        kind: "full",
+        text: item.text,
+        estimatedTokens: full,
+        fidelity: item.tokenEstimate !== undefined ? "exact" : "bounded",
+        sourceRef,
+    });
+    if (retrievable && sourceRef) {
+        candidates.push({
+            kind: "pointer",
+            text: formatPointer(sourceRef),
+            estimatedTokens: estimatePointerTokens(sourceRef),
+            fidelity: "bounded",
+            sourceRef,
+        });
+    }
+    const summaryTokens = Math.ceil(full * 0.15) + 8;
+    if (isSummaryEligible(item, full, policy) && summaryTokens < full) {
+        candidates.push({
+            kind: "summary",
+            text: summarizeText(item.text),
+            estimatedTokens: summaryTokens,
+            fidelity: "lossy",
+            summaryHash: fnv1aHex(item.text),
+        });
+    }
+    const headroomTokens = Math.ceil(full * 0.35) + 16;
+    if (full > policy.headroomThresholdTokens && retrievable && headroomTokens < full) {
+        candidates.push({
+            kind: "headroom-compressed",
+            text: formatHeadroom(item.text, sourceRef),
+            estimatedTokens: headroomTokens,
+            fidelity: "reversible",
+            sourceRef,
+            compressorId: "headroom-shadow",
+        });
+    }
+    if (policy.allowOmit) {
+        candidates.push({
+            kind: "omit",
+            text: "",
+            estimatedTokens: 0,
+            fidelity: "lossy",
+            sourceRef,
+        });
+    }
+    return candidates;
+}
+function isSummaryEligible(item, fullTokens, policy) {
+    return (item.tier === "history" ||
+        item.tier === "evidence" ||
+        item.tier === "scratch" ||
+        (item.ageTurns ?? 0) >= policy.summaryMaxAgeTurns ||
+        fullTokens > policy.headroomThresholdTokens);
+}
+function formatPointer(ref) {
+    const parts = [`uri=${ref.uri}`];
+    if (ref.symbol)
+        parts.push(`symbol=${ref.symbol}`);
+    if (ref.range)
+        parts.push(`lines=${ref.range.startLine}-${ref.range.endLine}`);
+    parts.push(`hash=${ref.contentHash}`);
+    return `<pointer ${parts.join(" ")} />`;
+}
+function summarizeText(text) {
+    if (text.length <= SUMMARY_HEAD_CHARS) {
+        return text;
+    }
+    return `${text.slice(0, SUMMARY_HEAD_CHARS)} …[summary]`;
+}
+function formatHeadroom(text, ref) {
+    const head = text.slice(0, HEADROOM_HEAD_CHARS);
+    const hash = fnv1aHex(text);
+    const where = ref ? ` uri=${ref.uri}` : "";
+    return `${head} …[headroom-compressed${where} hash=${hash}]`;
+}
+//# sourceMappingURL=context-budget-headroom-candidates.js.map

package/dist/core/context-budget-headroom-candidates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-headroom-candidates.js","sourceRoot":"","sources":["../../src/core/context-budget-headroom-candidates.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextRepresentationCandidateV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n\testimatePointerTokens,\n\tfnv1aHex,\n\tfullTextTokens,\n\ttype HeadroomQualityPolicyV2,\n} from \"./context-budget-headroom-types.ts\";\n\nconst SUMMARY_HEAD_CHARS = 160;\nconst HEADROOM_HEAD_CHARS = 120;\n\nexport function deriveRepresentationCandidates(\n\titem: ContextBudgetItemV2,\n\tpolicy: HeadroomQualityPolicyV2 = DEFAULT_HEADROOM_QUALITY_POLICY,\n): readonly ContextRepresentationCandidateV2[] {\n\tconst full = fullTextTokens(item);\n\tconst sourceRef = item.sourceRef;\n\tconst retrievable = sourceRef?.retrievable === true;\n\tconst candidates: ContextRepresentationCandidateV2[] = [];\n\n\tcandidates.push({\n\t\tkind: \"full\",\n\t\ttext: item.text,\n\t\testimatedTokens: full,\n\t\tfidelity: item.tokenEstimate !== undefined ? \"exact\" : \"bounded\",\n\t\tsourceRef,\n\t});\n\n\tif (retrievable && sourceRef) {\n\t\tcandidates.push({\n\t\t\tkind: \"pointer\",\n\t\t\ttext: formatPointer(sourceRef),\n\t\t\testimatedTokens: estimatePointerTokens(sourceRef),\n\t\t\tfidelity: \"bounded\",\n\t\t\tsourceRef,\n\t\t});\n\t}\n\n\tconst summaryTokens = Math.ceil(full * 0.15) + 8;\n\tif (isSummaryEligible(item, full, policy) && summaryTokens < full) {\n\t\tcandidates.push({\n\t\t\tkind: \"summary\",\n\t\t\ttext: summarizeText(item.text),\n\t\t\testimatedTokens: summaryTokens,\n\t\t\tfidelity: \"lossy\",\n\t\t\tsummaryHash: fnv1aHex(item.text),\n\t\t});\n\t}\n\n\tconst headroomTokens = Math.ceil(full * 0.35) + 16;\n\tif (full > policy.headroomThresholdTokens && retrievable && headroomTokens < full) {\n\t\tcandidates.push({\n\t\t\tkind: \"headroom-compressed\",\n\t\t\ttext: formatHeadroom(item.text, sourceRef),\n\t\t\testimatedTokens: headroomTokens,\n\t\t\tfidelity: \"reversible\",\n\t\t\tsourceRef,\n\t\t\tcompressorId: \"headroom-shadow\",\n\t\t});\n\t}\n\n\tif (policy.allowOmit) {\n\t\tcandidates.push({\n\t\t\tkind: \"omit\",\n\t\t\ttext: \"\",\n\t\t\testimatedTokens: 0,\n\t\t\tfidelity: \"lossy\",\n\t\t\tsourceRef,\n\t\t});\n\t}\n\n\treturn candidates;\n}\n\nfunction isSummaryEligible(item: ContextBudgetItemV2, fullTokens: number, policy: HeadroomQualityPolicyV2): boolean {\n\treturn (\n\t\titem.tier === \"history\" ||\n\t\titem.tier === \"evidence\" ||\n\t\titem.tier === \"scratch\" ||\n\t\t(item.ageTurns ?? 0) >= policy.summaryMaxAgeTurns ||\n\t\tfullTokens > policy.headroomThresholdTokens\n\t);\n}\n\nfunction formatPointer(ref: ContextSourceRefV2): string {\n\tconst parts: string[] = [`uri=${ref.uri}`];\n\tif (ref.symbol) parts.push(`symbol=${ref.symbol}`);\n\tif (ref.range) parts.push(`lines=${ref.range.startLine}-${ref.range.endLine}`);\n\tparts.push(`hash=${ref.contentHash}`);\n\treturn `<pointer ${parts.join(\" \")} />`;\n}\n\nfunction summarizeText(text: string): string {\n\tif (text.length <= SUMMARY_HEAD_CHARS) {\n\t\treturn text;\n\t}\n\treturn `${text.slice(0, SUMMARY_HEAD_CHARS)} …[summary]`;\n}\n\nfunction formatHeadroom(text: string, ref?: ContextSourceRefV2): string {\n\tconst head = text.slice(0, HEADROOM_HEAD_CHARS);\n\tconst hash = fnv1aHex(text);\n\tconst where = ref ? ` uri=${ref.uri}` : \"\";\n\treturn `${head} …[headroom-compressed${where} hash=${hash}]`;\n}\n"]}

package/dist/core/context-budget-headroom-types.d.ts

@@ -0,0 +1,67 @@
+export type ContextBudgetTierV2 = "system" | "active-goal" | "current-files" | "tools" | "skills" | "mcp" | "history" | "evidence" | "scratch";
+export type ContextBudgetPriorityV2 = "hard" | "high" | "medium" | "low";
+export type ContextEvidenceKindV2 = "test" | "command" | "file" | "decision" | "lane" | "user" | "none";
+export type ContextRepresentationKindV2 = "full" | "pointer" | "summary" | "headroom-compressed" | "omit";
+export interface ContextSourceRefV2 {
+    readonly uri: string;
+    readonly symbol?: string;
+    readonly range?: {
+        readonly startLine: number;
+        readonly endLine: number;
+    };
+    readonly contentHash: string;
+    readonly retrievable: boolean;
+}
+export type ContextRepresentationFidelityV2 = "exact" | "bounded" | "lossy" | "reversible";
+export interface ContextRepresentationCandidateV2 {
+    readonly kind: ContextRepresentationKindV2;
+    readonly text: string;
+    readonly estimatedTokens: number;
+    readonly fidelity: ContextRepresentationFidelityV2;
+    readonly sourceRef?: ContextSourceRefV2;
+    readonly summaryHash?: string;
+    readonly compressorId?: string;
+}
+export interface ContextBudgetItemV2 {
+    readonly id: string;
+    readonly tier: ContextBudgetTierV2;
+    readonly priority: ContextBudgetPriorityV2;
+    readonly text: string;
+    readonly tokenEstimate?: number;
+    readonly relevance?: number;
+    readonly recency?: number;
+    readonly evidenceValue?: number;
+    readonly evidenceKind?: ContextEvidenceKindV2;
+    readonly ageTurns?: number;
+    readonly redundancyKey?: string;
+    readonly required?: boolean;
+    readonly pinReason?: string;
+    readonly sourceRef?: ContextSourceRefV2;
+    readonly representations?: readonly ContextRepresentationCandidateV2[];
+}
+export interface HeadroomQualityPolicyV2 {
+    readonly preferFullForHighPriority: boolean;
+    readonly preferPointerForRetrievable: boolean;
+    readonly summaryMaxAgeTurns: number;
+    readonly headroomThresholdTokens: number;
+    readonly allowOmit: boolean;
+}
+export declare const DEFAULT_HEADROOM_QUALITY_POLICY: HeadroomQualityPolicyV2;
+export interface HeadroomRuntimeStatusV2 {
+    readonly policyId: string;
+    readonly selector: string;
+    readonly headroomThresholdTokens: number;
+    readonly summaryMaxAgeTurns: number;
+    readonly representations: readonly ContextRepresentationKindV2[];
+}
+export declare function getHeadroomRuntimeStatus(policy?: HeadroomQualityPolicyV2): HeadroomRuntimeStatusV2;
+export interface RepresentationBudgetContext {
+    readonly tierUsedTokens: number;
+    readonly tierCeilingTokens: number;
+    readonly remainingGlobalTokens: number;
+}
+export declare function heuristicTokenCount(text: string): number;
+export declare function fullTextTokens(item: ContextBudgetItemV2): number;
+export declare function estimatePointerTokens(ref: ContextSourceRefV2): number;
+export declare function fnv1aHex(input: string): string;
+//# sourceMappingURL=context-budget-headroom-types.d.ts.map

package/dist/core/context-budget-headroom-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-headroom-types.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-headroom-types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAC5B,QAAQ,GACR,aAAa,GACb,eAAe,GACf,OAAO,GACP,QAAQ,GACR,KAAK,GACL,SAAS,GACT,UAAU,GACV,SAAS,CAAC;AAEb,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEzE,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAExG,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,qBAAqB,GAAG,MAAM,CAAC;AAE1G,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,+BAA+B,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,CAAC;AAE3F,MAAM,WAAW,gCAAgC;IAChD,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,+BAA+B,CAAC;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,gCAAgC,EAAE,CAAC;CACvE;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;IAC5C,QAAQ,CAAC,2BAA2B,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC5B;AAED,eAAO,MAAM,+BAA+B,EAAE,uBAM7C,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,SAAS,2BAA2B,EAAE,CAAC;CACjE;AAED,wBAAgB,wBAAwB,CACvC,MAAM,GAAE,uBAAyD,GAC/D,uBAAuB,CAQzB;AAED,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACvC;AAID,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAKhE;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAKrE;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO9C","sourcesContent":["export type ContextBudgetTierV2 =\n\t| \"system\"\n\t| \"active-goal\"\n\t| \"current-files\"\n\t| \"tools\"\n\t| \"skills\"\n\t| \"mcp\"\n\t| \"history\"\n\t| \"evidence\"\n\t| \"scratch\";\n\nexport type ContextBudgetPriorityV2 = \"hard\" | \"high\" | \"medium\" | \"low\";\n\nexport type ContextEvidenceKindV2 = \"test\" | \"command\" | \"file\" | \"decision\" | \"lane\" | \"user\" | \"none\";\n\nexport type ContextRepresentationKindV2 = \"full\" | \"pointer\" | \"summary\" | \"headroom-compressed\" | \"omit\";\n\nexport interface ContextSourceRefV2 {\n\treadonly uri: string;\n\treadonly symbol?: string;\n\treadonly range?: { readonly startLine: number; readonly endLine: number };\n\treadonly contentHash: string;\n\treadonly retrievable: boolean;\n}\n\nexport type ContextRepresentationFidelityV2 = \"exact\" | \"bounded\" | \"lossy\" | \"reversible\";\n\nexport interface ContextRepresentationCandidateV2 {\n\treadonly kind: ContextRepresentationKindV2;\n\treadonly text: string;\n\treadonly estimatedTokens: number;\n\treadonly fidelity: ContextRepresentationFidelityV2;\n\treadonly sourceRef?: ContextSourceRefV2;\n\treadonly summaryHash?: string;\n\treadonly compressorId?: string;\n}\n\nexport interface ContextBudgetItemV2 {\n\treadonly id: string;\n\treadonly tier: ContextBudgetTierV2;\n\treadonly priority: ContextBudgetPriorityV2;\n\treadonly text: string;\n\treadonly tokenEstimate?: number;\n\treadonly relevance?: number;\n\treadonly recency?: number;\n\treadonly evidenceValue?: number;\n\treadonly evidenceKind?: ContextEvidenceKindV2;\n\treadonly ageTurns?: number;\n\treadonly redundancyKey?: string;\n\treadonly required?: boolean;\n\treadonly pinReason?: string;\n\treadonly sourceRef?: ContextSourceRefV2;\n\treadonly representations?: readonly ContextRepresentationCandidateV2[];\n}\n\nexport interface HeadroomQualityPolicyV2 {\n\treadonly preferFullForHighPriority: boolean;\n\treadonly preferPointerForRetrievable: boolean;\n\treadonly summaryMaxAgeTurns: number;\n\treadonly headroomThresholdTokens: number;\n\treadonly allowOmit: boolean;\n}\n\nexport const DEFAULT_HEADROOM_QUALITY_POLICY: HeadroomQualityPolicyV2 = {\n\tpreferFullForHighPriority: true,\n\tpreferPointerForRetrievable: true,\n\tsummaryMaxAgeTurns: 4,\n\theadroomThresholdTokens: 400,\n\tallowOmit: true,\n};\n\nexport interface HeadroomRuntimeStatusV2 {\n\treadonly policyId: string;\n\treadonly selector: string;\n\treadonly headroomThresholdTokens: number;\n\treadonly summaryMaxAgeTurns: number;\n\treadonly representations: readonly ContextRepresentationKindV2[];\n}\n\nexport function getHeadroomRuntimeStatus(\n\tpolicy: HeadroomQualityPolicyV2 = DEFAULT_HEADROOM_QUALITY_POLICY,\n): HeadroomRuntimeStatusV2 {\n\treturn {\n\t\tpolicyId: \"context-budget-v2\",\n\t\tselector: \"headroom-selector\",\n\t\theadroomThresholdTokens: policy.headroomThresholdTokens,\n\t\tsummaryMaxAgeTurns: policy.summaryMaxAgeTurns,\n\t\trepresentations: [\"full\", \"pointer\", \"summary\", \"headroom-compressed\", \"omit\"],\n\t};\n}\n\nexport interface RepresentationBudgetContext {\n\treadonly tierUsedTokens: number;\n\treadonly tierCeilingTokens: number;\n\treadonly remainingGlobalTokens: number;\n}\n\nconst CHARS_PER_TOKEN_HEURISTIC = 4;\n\nexport function heuristicTokenCount(text: string): number {\n\tif (text.length === 0) {\n\t\treturn 0;\n\t}\n\treturn Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN_HEURISTIC));\n}\n\nexport function fullTextTokens(item: ContextBudgetItemV2): number {\n\tif (item.tokenEstimate !== undefined) {\n\t\treturn Math.max(0, Math.floor(item.tokenEstimate));\n\t}\n\treturn heuristicTokenCount(item.text);\n}\n\nexport function estimatePointerTokens(ref: ContextSourceRefV2): number {\n\tlet total = ref.uri.length + (ref.contentHash?.length ?? 0) + 16;\n\tif (ref.symbol) total += ref.symbol.length;\n\tif (ref.range) total += 8;\n\treturn Math.max(8, Math.ceil(total / CHARS_PER_TOKEN_HEURISTIC));\n}\n\nexport function fnv1aHex(input: string): string {\n\tlet hash = 0x811c9dc5;\n\tfor (let i = 0; i < input.length; i++) {\n\t\thash ^= input.charCodeAt(i);\n\t\thash = Math.imul(hash, 0x01000193) >>> 0;\n\t}\n\treturn hash.toString(16).padStart(8, \"0\");\n}\n"]}

package/dist/core/context-budget-headroom-types.js

@@ -0,0 +1,46 @@
+export const DEFAULT_HEADROOM_QUALITY_POLICY = {
+    preferFullForHighPriority: true,
+    preferPointerForRetrievable: true,
+    summaryMaxAgeTurns: 4,
+    headroomThresholdTokens: 400,
+    allowOmit: true,
+};
+export function getHeadroomRuntimeStatus(policy = DEFAULT_HEADROOM_QUALITY_POLICY) {
+    return {
+        policyId: "context-budget-v2",
+        selector: "headroom-selector",
+        headroomThresholdTokens: policy.headroomThresholdTokens,
+        summaryMaxAgeTurns: policy.summaryMaxAgeTurns,
+        representations: ["full", "pointer", "summary", "headroom-compressed", "omit"],
+    };
+}
+const CHARS_PER_TOKEN_HEURISTIC = 4;
+export function heuristicTokenCount(text) {
+    if (text.length === 0) {
+        return 0;
+    }
+    return Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN_HEURISTIC));
+}
+export function fullTextTokens(item) {
+    if (item.tokenEstimate !== undefined) {
+        return Math.max(0, Math.floor(item.tokenEstimate));
+    }
+    return heuristicTokenCount(item.text);
+}
+export function estimatePointerTokens(ref) {
+    let total = ref.uri.length + (ref.contentHash?.length ?? 0) + 16;
+    if (ref.symbol)
+        total += ref.symbol.length;
+    if (ref.range)
+        total += 8;
+    return Math.max(8, Math.ceil(total / CHARS_PER_TOKEN_HEURISTIC));
+}
+export function fnv1aHex(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+}
+//# sourceMappingURL=context-budget-headroom-types.js.map

package/dist/core/context-budget-headroom-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-headroom-types.js","sourceRoot":"","sources":["../../src/core/context-budget-headroom-types.ts"],"names":[],"mappings":"AA+DA,MAAM,CAAC,MAAM,+BAA+B,GAA4B;IACvE,yBAAyB,EAAE,IAAI;IAC/B,2BAA2B,EAAE,IAAI;IACjC,kBAAkB,EAAE,CAAC;IACrB,uBAAuB,EAAE,GAAG;IAC5B,SAAS,EAAE,IAAI;CACf,CAAC;AAUF,MAAM,UAAU,wBAAwB,CACvC,MAAM,GAA4B,+BAA+B,EACvC;IAC1B,OAAO;QACN,QAAQ,EAAE,mBAAmB;QAC7B,QAAQ,EAAE,mBAAmB;QAC7B,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;QACvD,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,eAAe,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,CAAC;KAC9E,CAAC;AAAA,CACF;AAQD,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAEpC,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAU;IACzD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,CAAC;IACV,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,yBAAyB,CAAC,CAAC,CAAC;AAAA,CACvE;AAED,MAAM,UAAU,cAAc,CAAC,IAAyB,EAAU;IACjE,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CACtC;AAED,MAAM,UAAU,qBAAqB,CAAC,GAAuB,EAAU;IACtE,IAAI,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;IACjE,IAAI,GAAG,CAAC,MAAM;QAAE,KAAK,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;IAC3C,IAAI,GAAG,CAAC,KAAK;QAAE,KAAK,IAAI,CAAC,CAAC;IAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,yBAAyB,CAAC,CAAC,CAAC;AAAA,CACjE;AAED,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAU;IAC/C,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAAA,CAC1C","sourcesContent":["export type ContextBudgetTierV2 =\n\t| \"system\"\n\t| \"active-goal\"\n\t| \"current-files\"\n\t| \"tools\"\n\t| \"skills\"\n\t| \"mcp\"\n\t| \"history\"\n\t| \"evidence\"\n\t| \"scratch\";\n\nexport type ContextBudgetPriorityV2 = \"hard\" | \"high\" | \"medium\" | \"low\";\n\nexport type ContextEvidenceKindV2 = \"test\" | \"command\" | \"file\" | \"decision\" | \"lane\" | \"user\" | \"none\";\n\nexport type ContextRepresentationKindV2 = \"full\" | \"pointer\" | \"summary\" | \"headroom-compressed\" | \"omit\";\n\nexport interface ContextSourceRefV2 {\n\treadonly uri: string;\n\treadonly symbol?: string;\n\treadonly range?: { readonly startLine: number; readonly endLine: number };\n\treadonly contentHash: string;\n\treadonly retrievable: boolean;\n}\n\nexport type ContextRepresentationFidelityV2 = \"exact\" | \"bounded\" | \"lossy\" | \"reversible\";\n\nexport interface ContextRepresentationCandidateV2 {\n\treadonly kind: ContextRepresentationKindV2;\n\treadonly text: string;\n\treadonly estimatedTokens: number;\n\treadonly fidelity: ContextRepresentationFidelityV2;\n\treadonly sourceRef?: ContextSourceRefV2;\n\treadonly summaryHash?: string;\n\treadonly compressorId?: string;\n}\n\nexport interface ContextBudgetItemV2 {\n\treadonly id: string;\n\treadonly tier: ContextBudgetTierV2;\n\treadonly priority: ContextBudgetPriorityV2;\n\treadonly text: string;\n\treadonly tokenEstimate?: number;\n\treadonly relevance?: number;\n\treadonly recency?: number;\n\treadonly evidenceValue?: number;\n\treadonly evidenceKind?: ContextEvidenceKindV2;\n\treadonly ageTurns?: number;\n\treadonly redundancyKey?: string;\n\treadonly required?: boolean;\n\treadonly pinReason?: string;\n\treadonly sourceRef?: ContextSourceRefV2;\n\treadonly representations?: readonly ContextRepresentationCandidateV2[];\n}\n\nexport interface HeadroomQualityPolicyV2 {\n\treadonly preferFullForHighPriority: boolean;\n\treadonly preferPointerForRetrievable: boolean;\n\treadonly summaryMaxAgeTurns: number;\n\treadonly headroomThresholdTokens: number;\n\treadonly allowOmit: boolean;\n}\n\nexport const DEFAULT_HEADROOM_QUALITY_POLICY: HeadroomQualityPolicyV2 = {\n\tpreferFullForHighPriority: true,\n\tpreferPointerForRetrievable: true,\n\tsummaryMaxAgeTurns: 4,\n\theadroomThresholdTokens: 400,\n\tallowOmit: true,\n};\n\nexport interface HeadroomRuntimeStatusV2 {\n\treadonly policyId: string;\n\treadonly selector: string;\n\treadonly headroomThresholdTokens: number;\n\treadonly summaryMaxAgeTurns: number;\n\treadonly representations: readonly ContextRepresentationKindV2[];\n}\n\nexport function getHeadroomRuntimeStatus(\n\tpolicy: HeadroomQualityPolicyV2 = DEFAULT_HEADROOM_QUALITY_POLICY,\n): HeadroomRuntimeStatusV2 {\n\treturn {\n\t\tpolicyId: \"context-budget-v2\",\n\t\tselector: \"headroom-selector\",\n\t\theadroomThresholdTokens: policy.headroomThresholdTokens,\n\t\tsummaryMaxAgeTurns: policy.summaryMaxAgeTurns,\n\t\trepresentations: [\"full\", \"pointer\", \"summary\", \"headroom-compressed\", \"omit\"],\n\t};\n}\n\nexport interface RepresentationBudgetContext {\n\treadonly tierUsedTokens: number;\n\treadonly tierCeilingTokens: number;\n\treadonly remainingGlobalTokens: number;\n}\n\nconst CHARS_PER_TOKEN_HEURISTIC = 4;\n\nexport function heuristicTokenCount(text: string): number {\n\tif (text.length === 0) {\n\t\treturn 0;\n\t}\n\treturn Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN_HEURISTIC));\n}\n\nexport function fullTextTokens(item: ContextBudgetItemV2): number {\n\tif (item.tokenEstimate !== undefined) {\n\t\treturn Math.max(0, Math.floor(item.tokenEstimate));\n\t}\n\treturn heuristicTokenCount(item.text);\n}\n\nexport function estimatePointerTokens(ref: ContextSourceRefV2): number {\n\tlet total = ref.uri.length + (ref.contentHash?.length ?? 0) + 16;\n\tif (ref.symbol) total += ref.symbol.length;\n\tif (ref.range) total += 8;\n\treturn Math.max(8, Math.ceil(total / CHARS_PER_TOKEN_HEURISTIC));\n}\n\nexport function fnv1aHex(input: string): string {\n\tlet hash = 0x811c9dc5;\n\tfor (let i = 0; i < input.length; i++) {\n\t\thash ^= input.charCodeAt(i);\n\t\thash = Math.imul(hash, 0x01000193) >>> 0;\n\t}\n\treturn hash.toString(16).padStart(8, \"0\");\n}\n"]}

package/dist/core/context-budget-headroom.d.ts

@@ -0,0 +1,5 @@
+import { type ContextBudgetItemV2, type ContextRepresentationCandidateV2, type HeadroomQualityPolicyV2, type RepresentationBudgetContext } from "./context-budget-headroom-types.ts";
+export declare function chooseHeadroomRepresentation(item: ContextBudgetItemV2, budget: RepresentationBudgetContext, policy?: HeadroomQualityPolicyV2): ContextRepresentationCandidateV2;
+export { deriveRepresentationCandidates } from "./context-budget-headroom-candidates.ts";
+export { type ContextBudgetItemV2, type ContextBudgetPriorityV2, type ContextBudgetTierV2, type ContextEvidenceKindV2, type ContextRepresentationCandidateV2, type ContextRepresentationFidelityV2, type ContextRepresentationKindV2, type ContextSourceRefV2, DEFAULT_HEADROOM_QUALITY_POLICY, estimatePointerTokens, fnv1aHex, fullTextTokens, getHeadroomRuntimeStatus, type HeadroomQualityPolicyV2, type HeadroomRuntimeStatusV2, heuristicTokenCount, type RepresentationBudgetContext, } from "./context-budget-headroom-types.ts";
+//# sourceMappingURL=context-budget-headroom.d.ts.map

package/dist/core/context-budget-headroom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-headroom.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-headroom.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,mBAAmB,EAExB,KAAK,gCAAgC,EAGrC,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,MAAM,oCAAoC,CAAC;AAgB5C,wBAAgB,4BAA4B,CAC3C,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,2BAA2B,EACnC,MAAM,GAAE,uBAAyD,GAC/D,gCAAgC,CAiClC;AAsFD,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AACzF,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,gCAAgC,EACrC,KAAK,+BAA+B,EACpC,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,EACvB,+BAA+B,EAC/B,qBAAqB,EACrB,QAAQ,EACR,cAAc,EACd,wBAAwB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,mBAAmB,EACnB,KAAK,2BAA2B,GAChC,MAAM,oCAAoC,CAAC","sourcesContent":["import { deriveRepresentationCandidates } from \"./context-budget-headroom-candidates.ts\";\nimport {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetPriorityV2,\n\ttype ContextRepresentationCandidateV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n\tfullTextTokens,\n\ttype HeadroomQualityPolicyV2,\n\ttype RepresentationBudgetContext,\n} from \"./context-budget-headroom-types.ts\";\n\nconst PRIORITY_WEIGHT: Record<ContextBudgetPriorityV2, number> = {\n\thard: 1_000_000,\n\thigh: 120,\n\tmedium: 60,\n\tlow: 15,\n};\n\nconst FIDELITY_BONUS: Record<ContextRepresentationCandidateV2[\"fidelity\"], number> = {\n\texact: 6,\n\tbounded: 3,\n\treversible: 4,\n\tlossy: 0,\n};\n\nexport function chooseHeadroomRepresentation(\n\titem: ContextBudgetItemV2,\n\tbudget: RepresentationBudgetContext,\n\tpolicy: HeadroomQualityPolicyV2 = DEFAULT_HEADROOM_QUALITY_POLICY,\n): ContextRepresentationCandidateV2 {\n\tconst candidates = item.representations ?? deriveRepresentationCandidates(item, policy);\n\tconst full = fullTextTokens(item);\n\tconst tierOver = budget.tierUsedTokens >= budget.tierCeilingTokens;\n\tconst globalTight = budget.remainingGlobalTokens < full;\n\tconst tight = tierOver || globalTight;\n\n\tif (item.priority === \"hard\" || item.required) {\n\t\tconst fullCandidate = candidates.find((candidate) => candidate.kind === \"full\");\n\t\tif (fullCandidate) {\n\t\t\treturn fullCandidate;\n\t\t}\n\t}\n\n\tlet best: ContextRepresentationCandidateV2 | undefined;\n\tlet bestScore = Number.NEGATIVE_INFINITY;\n\tfor (const candidate of candidates) {\n\t\tif (isMoreExpensiveThanFull(candidate, full)) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (candidate.kind !== \"omit\" && candidate.estimatedTokens > budget.remainingGlobalTokens) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst score = representationPreference(candidate, item, policy, tight);\n\t\tif (\n\t\t\tscore > bestScore ||\n\t\t\t(score === bestScore && best !== undefined && compareCandidatesForChoice(candidate, best) < 0)\n\t\t) {\n\t\t\tbest = candidate;\n\t\t\tbestScore = score;\n\t\t}\n\t}\n\treturn best ?? candidates.find((candidate) => candidate.kind === \"omit\") ?? omitCandidate(item);\n}\n\nfunction omitCandidate(item: ContextBudgetItemV2): ContextRepresentationCandidateV2 {\n\treturn {\n\t\tkind: \"omit\",\n\t\ttext: \"\",\n\t\testimatedTokens: 0,\n\t\tfidelity: \"lossy\",\n\t\tsourceRef: item.sourceRef,\n\t};\n}\n\nfunction isMoreExpensiveThanFull(candidate: ContextRepresentationCandidateV2, fullTokens: number): boolean {\n\treturn candidate.kind !== \"full\" && candidate.kind !== \"omit\" && candidate.estimatedTokens >= fullTokens;\n}\n\nfunction representationPreference(\n\tcandidate: ContextRepresentationCandidateV2,\n\titem: ContextBudgetItemV2,\n\tpolicy: HeadroomQualityPolicyV2,\n\ttight: boolean,\n): number {\n\tconst priority = PRIORITY_WEIGHT[item.priority];\n\tconst cost = candidate.estimatedTokens;\n\tconst fidelity = FIDELITY_BONUS[candidate.fidelity];\n\tconst retrievable = item.sourceRef?.retrievable === true;\n\n\tswitch (candidate.kind) {\n\t\tcase \"full\": {\n\t\t\tlet score = priority + fidelity - cost * 0.05;\n\t\t\tif (tight) score -= 50;\n\t\t\tif (isHistoryLike(item) && (item.ageTurns ?? 0) >= policy.summaryMaxAgeTurns) {\n\t\t\t\tscore -= 40;\n\t\t\t}\n\t\t\treturn score;\n\t\t}\n\t\tcase \"pointer\": {\n\t\t\tif (!policy.preferPointerForRetrievable || !retrievable) {\n\t\t\t\treturn Number.NEGATIVE_INFINITY;\n\t\t\t}\n\t\t\tlet score = 40 + fidelity - cost * 0.2;\n\t\t\tif (tight) score += 20;\n\t\t\treturn score;\n\t\t}\n\t\tcase \"summary\": {\n\t\t\tconst base = isHistoryLike(item) ? 30 : 10;\n\t\t\tlet score = base + ageBonus(item) + fidelity - cost * 0.3;\n\t\t\tif (tight) score += 15;\n\t\t\treturn score;\n\t\t}\n\t\tcase \"headroom-compressed\": {\n\t\t\tif (!retrievable) {\n\t\t\t\treturn Number.NEGATIVE_INFINITY;\n\t\t\t}\n\t\t\tconst large = fullTextTokens(item) > policy.headroomThresholdTokens ? 35 : 5;\n\t\t\tlet score = large + 10 + fidelity - cost * 0.5;\n\t\t\tif (tight) score += 18;\n\t\t\treturn score;\n\t\t}\n\t\tcase \"omit\": {\n\t\t\tif (!policy.allowOmit) {\n\t\t\t\treturn Number.NEGATIVE_INFINITY;\n\t\t\t}\n\t\t\tif (tight && item.priority === \"low\" && retrievable) {\n\t\t\t\treturn 12;\n\t\t\t}\n\t\t\treturn Number.NEGATIVE_INFINITY;\n\t\t}\n\t}\n}\n\nfunction ageBonus(item: ContextBudgetItemV2): number {\n\treturn Math.min(20, (item.ageTurns ?? 0) * 3);\n}\n\nfunction isHistoryLike(item: ContextBudgetItemV2): boolean {\n\treturn item.tier === \"history\" || item.tier === \"evidence\" || item.tier === \"scratch\";\n}\n\nfunction compareCandidatesForChoice(a: ContextRepresentationCandidateV2, b: ContextRepresentationCandidateV2): number {\n\tif (a.estimatedTokens !== b.estimatedTokens) {\n\t\treturn a.estimatedTokens - b.estimatedTokens;\n\t}\n\treturn a.kind.localeCompare(b.kind);\n}\n\nexport { deriveRepresentationCandidates } from \"./context-budget-headroom-candidates.ts\";\nexport {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetPriorityV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextEvidenceKindV2,\n\ttype ContextRepresentationCandidateV2,\n\ttype ContextRepresentationFidelityV2,\n\ttype ContextRepresentationKindV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n\testimatePointerTokens,\n\tfnv1aHex,\n\tfullTextTokens,\n\tgetHeadroomRuntimeStatus,\n\ttype HeadroomQualityPolicyV2,\n\ttype HeadroomRuntimeStatusV2,\n\theuristicTokenCount,\n\ttype RepresentationBudgetContext,\n} from \"./context-budget-headroom-types.ts\";\n"]}