You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by as...@apache.org on 2026/08/23 07:32:46 UTC
(maka) 02/02: refactor: remove context policy environment overrides
This is an automated email from the ASF dual-hosted git repository.
Astro-Han pushed a commit to branch fix/3542-unify-context-compaction
in repository https://gitbox.apache.org/repos/asf/maka.git
commit 152d87f1ed9cd06642fb846e8fa381406a0958b2
Author: AstroHan <le...@outlook.com>
AuthorDate: Sun Aug 23 15:32:27 2026 +0800
refactor: remove context policy environment overrides
Make context management a fixed Runtime-owned policy derived from model facts, remove unsupported configuration states, and document on-demand ArchiveRead behavior.
Generated-by: Codex
---
CHANGELOG.md | 4 +
.../llm-compaction-events-log-projection-draft.md | 36 ++---
...compaction-events-log-projection-draft.zh-CN.md | 36 ++---
.../context-budget-mid-turn-policy.test.ts | 137 ++++++----------
.../__tests__/context-budget-model-facts.test.ts | 5 +-
.../context-budget-retired-settings.test.ts | 49 ------
.../__tests__/mid-turn-capacity-backend.test.ts | 58 +------
packages/runtime/src/context-budget-policy.ts | 175 +++------------------
8 files changed, 105 insertions(+), 395 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 355478484..d612438ee 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,10 @@
- Added `/transcript` to browse long TUI sessions without depending on terminal
scrollback, with line, page, and first/last navigation.
+### Changed
+
+- Unified context management under one Runtime-owned policy. `MAKA_CONTEXT_*` environment overrides no longer tune or disable compaction and Tool Result pruning; model-visible archive placeholders are read on demand through bounded `ArchiveRead` calls instead of eager hydration.
+
## 0.1.11 - 2026-08-18
### Highlights
diff --git a/docs/architecture/llm-compaction-events-log-projection-draft.md b/docs/architecture/llm-compaction-events-log-projection-draft.md
index 6c0d696dd..9070ed180 100644
--- a/docs/architecture/llm-compaction-events-log-projection-draft.md
+++ b/docs/architecture/llm-compaction-events-log-projection-draft.md
@@ -175,30 +175,26 @@ First, compaction happens inside **model-history projection**, not inside the Ru
Second, the checkpoint is not itself a canonical RuntimeEvent. Coverage and tail selection return the selected checkpoint explicitly alongside the projected RuntimeEvents. A V2 checkpoint also materializes as the familiar system-authored text block so ordinary replay planning can consume it. A compatible V3 checkpoint creates no synthetic text: the provider materializer prepends its assistant `openai.compaction` custom part directly. Neither representation is written back to the RuntimeE [...]
-## Triggering: high water decides when to project
+## Triggering ends before compaction begins
-Automatic history compaction is governed by `ContextBudgetPolicy`. The current default policy:
+Runtime derives one capacity from the selected model's metadata. For a known context window it reserves one quarter of the window, capped at 16,384 tokens; most providers without a known window use a 32,000-token history budget plus the classic 16,384-token reserve.
-- derives the prior-history budget from the selected model's context window and reserves 16,384 tokens by default;
-- uses a 32,000-token history budget for most providers when no context window can be resolved;
-- enters compaction when compactable history exceeds `maxHistoryEstimatedTokens × highWaterRatio`;
-- defaults `highWaterRatio` to `1`;
-- targets a raw tail of no more than 16,384 estimated tokens;
-- asks for at least three recent Turns, while token-capped tail selection may retain fewer when a Turn is very large;
-- defaults to at most 1,024 estimated tokens for one checkpoint and 2,048 for the compact-projection budget.
+Trigger owners use that capacity but do not participate in compaction:
-These numbers are current policy defaults, not protocol constants. Environment variables and model metadata may change them. The stable semantics are:
+- the pre-turn and active-turn evaluators emit a Compact command when the projected request crosses the derived capacity;
+- provider-overflow recovery emits the same command after a real overflow;
+- manual `context.compact` emits it directly, without manufacturing a high-water crossing.
+
+Once emitted, the command always enters the same transaction. The planner receives no force flag, context window, reserve, next-request estimate, high-water ratio, or minimum-recent-Turn policy:
```text
-source log grows past high water
- → select an older prefix to fold
- → preserve a recent raw tail
- → accept projection only if checkpoint + tail fits current limits
+trigger owner emits Compact command
+ → select the largest safe completed prefix
+ → generate and validate one rolling replacement
+ → append one checkpoint or leave durable state unchanged
```
-Tail selection works backward over complete Turns to avoid splitting an ordinary Tool Call/Result pair. If the newest Turn alone exceeds the tail budget, the current implementation falls back to the latest complete function call/response pair in that Turn. If no pair exists, it retains at least the final event.
-
-This boundary matters: `minRecentTurns` is a preference, not permission to violate the context cap.
+Safe-prefix selection never crosses a partial event, pinned live event, or Tool Call/Result pair. Trigger-specific callers may reserve a small verbatim successor tail, but one completed Turn remains compactable regardless of how many Agent Loop steps it contains. Context management has no environment-variable policy surface; model facts and these Runtime invariants are the only inputs.
## What the LLM does—and does not do
@@ -416,7 +412,7 @@ Desktop `sessions:compact` does not silently rewrite a database. It creates a Tu
- the Run ends through normal terminal events and completed/cancelled state;
- a new checkpoint still commits through the same `history_compact_checkpoint_recorded` path.
-The manual policy lowers high water to almost zero and reduces the retained-tail target so even a small history can produce a projection. It changes the trigger, not source, coverage, durability, or replay invariants.
+Manual compaction emits the same Compact command directly. It does not create a special policy or alter a high-water threshold; only the trigger differs from automatic and overflow recovery.
## V2 and V3: one bounded checkpoint with two projection values
@@ -446,6 +442,8 @@ Both preserve canonical source, but they do not create parallel compaction autho
Active Tool Result Prune remains a deterministic non-LLM rewrite. It archives an eligible raw Tool Result before replacing that result in the current provider request. It neither summarizes a span nor creates a checkpoint, and the later history-compaction planner reads the canonical RuntimeEvents rather than treating prune placeholders as source authority.
+The placeholder carries a bounded `maka://archive/...` address and instructions for `ArchiveRead`; model replay deterministically reconstructs that address for legacy placeholders. Runtime does not eagerly expand the archived body back into every request. The model calls `ArchiveRead` only when it needs the detail, and the Host validates the Session, hash, and byte size before returning a bounded inspect or query result. A later checkpoint replaces covered placeholders with its summary a [...]
+
## What compaction is not
### It is not Memory
@@ -511,7 +509,7 @@ Read the current implementation from these locations:
6. `packages/runtime/src/history-compact-ledger.ts`: bounded-projection lookup, ledger recovery, and checkpoint selection;
7. `packages/runtime/src/runtime-kernel.ts`: serialized checkpoint writes and manual-compaction lifecycle;
8. `packages/storage/src/agent-run-store.ts`: commit ordering between canonical append and bounded event projection;
-9. `packages/runtime/src/context-budget-policy.ts`: default budgets, environment controls, and the manual lookup overlay;
+9. `packages/runtime/src/context-budget-policy.ts`: model-capacity derivation and fixed Runtime policy;
10. `packages/runtime/src/openai-codex-history-compactor.ts`: Codex compact-output validation and rolling provider-state input;
11. `packages/runtime-host/src/server/execution-model-composition.ts`: default provider-specific compactor selection.
diff --git a/docs/architecture/llm-compaction-events-log-projection-draft.zh-CN.md b/docs/architecture/llm-compaction-events-log-projection-draft.zh-CN.md
index 920d43f92..8fc9f520d 100644
--- a/docs/architecture/llm-compaction-events-log-projection-draft.zh-CN.md
+++ b/docs/architecture/llm-compaction-events-log-projection-draft.zh-CN.md
@@ -175,30 +175,26 @@ V2 中模型主要看到 `summary`;V3 中 provider 看到自己的 opaque comp
第二,checkpoint 也不是 canonical RuntimeEvent。coverage 与 tail selection 会把选中的 checkpoint 和投影后的 RuntimeEvents 一起显式返回。V2 checkpoint 还会物化为熟悉的 system-authored 文本块,供普通 replay planning 使用;兼容的 V3 checkpoint 不创建任何 synthetic 文本,由 provider materializer 直接在请求头部加入 assistant `openai.compaction` custom part。两种表示都不会伪装成原始交互事件写回 RuntimeEvent ledger。
-## 什么时候触发:High water 决定是否投影
+## Trigger 在 compaction 开始前结束
-自动 history compaction 由 `ContextBudgetPolicy` 驱动。当前默认策略会:
+Runtime 从所选模型的 metadata 推导唯一 capacity。已知 context window 时,reserve 取 window 的四分之一且上限为 16,384 tokens;无法得到 window 时,多数 provider 使用 32,000-token history budget 加经典的 16,384-token reserve。
-- 根据所选模型 context window 计算 prior-history budget,并默认预留 16,384 tokens;
-- 无法得到 context window 时,多数 provider 使用 32,000 tokens 的默认 history budget;
-- 当可 compact 的历史估算超过 `maxHistoryEstimatedTokens × highWaterRatio` 时进入 compaction;
-- 默认 `highWaterRatio = 1`;
-- 默认希望保留不超过 16,384 estimated tokens 的 raw tail;
-- 请求至少保留 3 个最近 Turn,但 tail selection 以 token cap 为先,极大 Turn 可能使实际保留更少;
-- 单个 checkpoint 默认最多 1,024 estimated tokens,compact projection 总预算默认最多 2,048。
+Trigger owner 使用这个 capacity,但不参与 compaction:
-这些数字是当前默认 policy,不是协议常量。环境变量和模型 metadata 可以改变它们。真正稳定的是触发语义:
+- pre-turn 与 active-turn evaluator 在 projected request 越过推导出的 capacity 时发出 Compact command;
+- provider-overflow recovery 在真实 overflow 后发出同一 command;
+- 手动 `context.compact` 直接发出 command,不伪造 high-water crossing。
+
+Command 一旦发出就进入同一个 transaction。Planner 不再接收 force flag、context window、reserve、next-request estimate、high-water ratio 或 minimum-recent-Turn policy:
```text
-source log grows past high water
- → select an older prefix to fold
- → preserve a recent raw tail
- → accept projection only if checkpoint + tail fits current limits
+trigger owner emits Compact command
+ → select the largest safe completed prefix
+ → generate and validate one rolling replacement
+ → append one checkpoint or leave durable state unchanged
```
-Tail selection 按完整 Turn 从新到旧选择,避免把普通 tool call/result pair 从中间劈开。如果单个最新 Turn 本身已经超过 tail budget,当前实现会退而保留该 Turn 中最新的完整 function call/response pair;找不到 pair 时至少保留最后一条事件。
-
-这是一条重要边界:`minRecentTurns` 是期望,不是允许突破上下文上限的承诺。
+Safe-prefix selection 不会跨越 partial event、pinned live event 或 Tool Call/Result pair。Trigger-specific caller 可以保留一小段 verbatim successor tail,但一个 completed Turn 无论包含多少 Agent Loop steps 都可以 compact。Context management 不再提供环境变量 policy surface;模型事实与这些 Runtime invariant 是唯一输入。
## LLM 在这里做什么,也不做什么
@@ -416,7 +412,7 @@ Compaction 跨越 token estimation、LLM call、schema construction、durable ap
- Run 最终以正常 terminal event 与 completed/cancelled 状态收尾;
- 新 checkpoint 仍通过同一 `history_compact_checkpoint_recorded` durable path 提交。
-Manual policy 把 high-water 降到接近零并把 retained tail 目标降到最小,使小历史也能主动产生 projection。它改变触发条件,不改变 source、coverage、durability 和 replay invariants。
+Manual compaction 直接发出同一个 Compact command。它不创建特殊 policy,也不修改 high-water threshold;与 automatic 和 overflow recovery 的差别只在 trigger。
## V2 与 V3:一种 bounded checkpoint、两种 projection value
@@ -446,6 +442,8 @@ Maka 只有一套 LLM compaction 机制,以及一个相邻的 current-request
Active Tool Result Prune 仍是 deterministic、非 LLM 的 rewrite。它先归档 eligible raw Tool Result,再替换 current provider request 中的该结果。它既不总结 span,也不创建 checkpoint;后续 history-compaction planner 读取 canonical RuntimeEvents,不会把 prune placeholder 当成 source authority。
+Placeholder 携带 bounded `maka://archive/...` 地址和 `ArchiveRead` 指令;model replay 会为 legacy placeholder 确定性补回这个地址。Runtime 不再把 archived body eager-expand 回每次请求。只有模型确实需要细节时才调用 `ArchiveRead`,Host 在返回 bounded inspect/query 结果前校验 Session、hash 与 byte size。后续 checkpoint 会用 summary 替换已覆盖的 placeholder,并且有意不携带 archive roots。完整 Tool Result 仍在 canonical RuntimeEvent ledger 中,但 model reachability 不会变成永久的 cross-checkpoint authority。
+
## Compaction 不是什么
### 它不是 Memory
@@ -511,7 +509,7 @@ LLM 在 summary 中写“测试已通过”仍然只是对 source events 的概
6. `packages/runtime/src/history-compact-ledger.ts`:bounded projection lookup、ledger recovery 与 checkpoint selection;
7. `packages/runtime/src/runtime-kernel.ts`:checkpoint write serialization 与 manual compaction lifecycle;
8. `packages/storage/src/agent-run-store.ts`:canonical append 与 bounded event projection 的提交顺序;
-9. `packages/runtime/src/context-budget-policy.ts`:默认预算、环境开关与 manual lookup overlay;
+9. `packages/runtime/src/context-budget-policy.ts`:model-capacity derivation 与固定 Runtime policy;
10. `packages/runtime/src/openai-codex-history-compactor.ts`:Codex compact output 校验与 rolling provider-state input;
11. `packages/runtime-host/src/server/execution-model-composition.ts`:默认 provider-specific compactor 选择。
diff --git a/packages/runtime/src/__tests__/context-budget-mid-turn-policy.test.ts b/packages/runtime/src/__tests__/context-budget-mid-turn-policy.test.ts
index afa0099b7..ef483bedb 100644
--- a/packages/runtime/src/__tests__/context-budget-mid-turn-policy.test.ts
+++ b/packages/runtime/src/__tests__/context-budget-mid-turn-policy.test.ts
@@ -25,43 +25,43 @@ import {
resolveContextBudgetCapacity,
} from '../context-budget-policy.js';
-describe('mid-turn history compact policy env plumbing', () => {
- test('defaults on with no compaction env at all (the runtime, not the surface, owns it)', () => {
- const policy = buildDefaultContextBudgetPolicy(connection(), { env: {} });
- assert.equal(policy?.historyCompact?.enabled, true);
- assert.deepEqual(policy?.historyCompact?.midTurn, { enabled: true, reserveTokens: 16_384 });
- });
-
- test('honors explicit reserve and tail-event overrides', () => {
- const policy = buildDefaultContextBudgetPolicy(connection(), {
- env: {
- MAKA_CONTEXT_HISTORY_COMPACT_RESERVE_TOKENS: '8000',
- MAKA_CONTEXT_HISTORY_COMPACT_MID_TURN_TAIL_EVENTS: '2',
- },
- });
- assert.deepEqual(policy?.historyCompact?.midTurn, {
- enabled: true,
- reserveTokens: 8_000,
- reserveTailEvents: 2,
- });
- });
+test('context policy is independent of process environment overrides', () => {
+ const overrides = {
+ MAKA_CONTEXT_BUDGET: 'off',
+ MAKA_CONTEXT_HISTORY_COMPACT: 'off',
+ MAKA_CONTEXT_HISTORY_COMPACT_HIGH_WATER_NAME: 'custom-high-water',
+ MAKA_CONTEXT_HISTORY_COMPACT_MID_TURN: 'off',
+ MAKA_CONTEXT_HISTORY_COMPACT_MID_TURN_TAIL_EVENTS: '99',
+ MAKA_CONTEXT_HISTORY_COMPACT_RESERVE_TOKENS: '1',
+ MAKA_CONTEXT_STALE_TOOL_RESULT_PRUNE: 'off',
+ MAKA_CONTEXT_STALE_TOOL_RESULT_MAX_TOKENS: '1',
+ MAKA_CONTEXT_STALE_TOOL_RESULT_MIN_RECENT_TURNS: '99',
+ MAKA_CONTEXT_ACTIVE_TOOL_RESULT_PRUNE: 'off',
+ MAKA_CONTEXT_ACTIVE_TOOL_RESULT_MAX_ESTIMATED_TOKENS: '1',
+ MAKA_CONTEXT_ACTIVE_TOOL_RESULT_MIN_STEP_NUMBER: '99',
+ MAKA_CONTEXT_ACTIVE_TOOL_RESULT_MIN_SUPERSEDED_TOKENS: '1',
+ } as const;
+ const previous = Object.fromEntries(
+ Object.keys(overrides).map((name) => [name, process.env[name]]),
+ );
+ try {
+ for (const name of Object.keys(overrides)) delete process.env[name];
+ const baseline = buildDefaultContextBudgetPolicy(connection());
+ Object.assign(process.env, overrides);
+ assert.deepEqual(buildDefaultContextBudgetPolicy(connection()), baseline);
+ } finally {
+ for (const [name, value] of Object.entries(previous)) {
+ if (value === undefined) delete process.env[name];
+ else process.env[name] = value;
+ }
+ }
+});
- test('MAKA_CONTEXT_HISTORY_COMPACT_MID_TURN=off is the escape hatch even with history compact on', () => {
- const policy = buildDefaultContextBudgetPolicy(connection(), {
- env: {
- MAKA_CONTEXT_HISTORY_COMPACT: 'on',
- MAKA_CONTEXT_HISTORY_COMPACT_MID_TURN: 'off',
- },
- });
+describe('mid-turn history compact policy', () => {
+ test('is owned by the runtime default', () => {
+ const policy = buildDefaultContextBudgetPolicy(connection());
assert.equal(policy?.historyCompact?.enabled, true);
- assert.equal(policy?.historyCompact?.midTurn, undefined);
- });
-
- test('an explicit MAKA_CONTEXT_HISTORY_COMPACT=off disables history compaction and midTurn with it', () => {
- const policy = buildDefaultContextBudgetPolicy(connection(), {
- env: { MAKA_CONTEXT_HISTORY_COMPACT: 'off' },
- });
- assert.equal(policy?.historyCompact, undefined);
+ assert.deepEqual(policy?.historyCompact?.midTurn, { enabled: true, reserveTokens: 16_384 });
});
});
@@ -73,13 +73,13 @@ describe('window-bounded reserve derivation (issue #882 PR 3 review P2)', () =>
// summarizer for a checkpoint that could never pass the replay gate.
// The default reserve must be bounded by the KNOWN window: a quarter of
// the window, capped at the classic 16384.
- const policy = buildDefaultContextBudgetPolicy(gpt4Connection(), { env: {}, modelId: 'gpt-4' });
+ const policy = buildDefaultContextBudgetPolicy(gpt4Connection(), { modelId: 'gpt-4' });
assert.equal(policy?.maxHistoryEstimatedTokens, 8192 - 2048);
assert.deepEqual(policy?.historyCompact?.midTurn, { enabled: true, reserveTokens: 2048 });
});
test('uses the official Agent Plan default-model window instead of the unknown-model fallback', () => {
- const policy = buildDefaultContextBudgetPolicy(agentPlanConnection(), { env: {} });
+ const policy = buildDefaultContextBudgetPolicy(agentPlanConnection());
assert.equal(policy?.maxHistoryEstimatedTokens, 256_000 - 16_384);
assert.deepEqual(policy?.historyCompact?.midTurn, { enabled: true, reserveTokens: 16_384 });
});
@@ -91,7 +91,7 @@ describe('window-bounded reserve derivation (issue #882 PR 3 review P2)', () =>
defaultModel: 'custom-model',
models: [{ id: 'custom-model' }],
} as LlmConnection,
- { env: {}, modelId: 'custom-model' },
+ { modelId: 'custom-model' },
);
// No window: the flat 32_000 fallback budget and the classic reserve.
assert.equal(policy?.maxHistoryEstimatedTokens, 32_000);
@@ -109,20 +109,11 @@ describe('window-bounded reserve derivation (issue #882 PR 3 review P2)', () =>
{ tokens: 48_384, source: 'policy_fallback' },
);
});
-
- test('respects an explicit reserve override verbatim even on a small window', () => {
- const policy = buildDefaultContextBudgetPolicy(gpt4Connection(), {
- env: { MAKA_CONTEXT_HISTORY_COMPACT_RESERVE_TOKENS: '6000' },
- modelId: 'gpt-4',
- });
- assert.equal(policy?.maxHistoryEstimatedTokens, 8192 - 6000);
- assert.deepEqual(policy?.historyCompact?.midTurn, { enabled: true, reserveTokens: 6000 });
- });
});
-describe('tool-result prune policy env plumbing', () => {
- test('provides bounded active and stale defaults', () => {
- const policy = buildDefaultContextBudgetPolicy(connection(), { env: {} });
+describe('tool-result prune policy', () => {
+ test('uses bounded runtime defaults', () => {
+ const policy = buildDefaultContextBudgetPolicy(connection());
assert.deepEqual(policy?.activeToolResultPrune, {
enabled: true,
maxCurrentResultEstimatedTokens: 2_048,
@@ -135,45 +126,6 @@ describe('tool-result prune policy env plumbing', () => {
minRecentTurnsFull: 2,
});
});
-
- test('applies explicit active and stale tool-result bounds', () => {
- const policy = buildDefaultContextBudgetPolicy(connection(), {
- env: {
- MAKA_CONTEXT_ACTIVE_TOOL_RESULT_MAX_ESTIMATED_TOKENS: '4096',
- MAKA_CONTEXT_ACTIVE_TOOL_RESULT_MIN_SUPERSEDED_TOKENS: '384',
- MAKA_CONTEXT_ACTIVE_TOOL_RESULT_MIN_STEP_NUMBER: '3',
- MAKA_CONTEXT_STALE_TOOL_RESULT_MAX_TOKENS: '8192',
- MAKA_CONTEXT_STALE_TOOL_RESULT_MIN_RECENT_TURNS: '5',
- },
- });
- assert.equal(policy?.activeToolResultPrune?.maxCurrentResultEstimatedTokens, 4_096);
- assert.equal(policy?.activeToolResultPrune?.minSupersededResultEstimatedTokens, 384);
- assert.equal(policy?.activeToolResultPrune?.minStepNumber, 3);
- assert.equal(policy?.staleToolResultPrune?.maxResultEstimatedTokens, 8_192);
- assert.equal(policy?.staleToolResultPrune?.minRecentTurnsFull, 5);
- });
-
- test('honors explicit disablement and rejects malformed booleans', () => {
- const disabled = buildDefaultContextBudgetPolicy(connection(), {
- env: {
- MAKA_CONTEXT_ACTIVE_TOOL_RESULT_PRUNE: 'false',
- MAKA_CONTEXT_STALE_TOOL_RESULT_PRUNE: 'off',
- },
- });
- assert.equal(disabled?.activeToolResultPrune, undefined);
- assert.equal(disabled?.staleToolResultPrune, undefined);
- assert.equal(
- buildDefaultContextBudgetPolicy(connection(), { env: { MAKA_CONTEXT_BUDGET: 'off' } }),
- undefined,
- );
- assert.throws(
- () =>
- buildDefaultContextBudgetPolicy(connection(), {
- env: { MAKA_CONTEXT_STALE_TOOL_RESULT_PRUNE: 'maybe' },
- }),
- /MAKA_CONTEXT_STALE_TOOL_RESULT_PRUNE must be a boolean/,
- );
- });
});
function gpt4Connection(): LlmConnection {
@@ -215,7 +167,7 @@ describe('declared relay context window', () => {
models: [{ id: 'reasoner-32k', contextWindow: 8_192 }],
relayModelProfiles: { 'reasoner-32k': { contextWindow: 131_072 } },
};
- const policy = buildDefaultContextBudgetPolicy(relay, { env: {}, modelId: 'reasoner-32k' });
+ const policy = buildDefaultContextBudgetPolicy(relay, { modelId: 'reasoner-32k' });
// Declared 131_072 wins: reserve 131_072/4 caps at 16_384. The fetched
// 8_192 row would have yielded 8_192 − 2_048, and no declaration at all
// would have fallen to the 32_000 unknown-model default.
@@ -223,7 +175,6 @@ describe('declared relay context window', () => {
// Clearing the declaration falls back to the fetched row's window.
const undeclared: LlmConnection = { ...relay, relayModelProfiles: undefined };
const fallback = buildDefaultContextBudgetPolicy(undeclared, {
- env: {},
modelId: 'reasoner-32k',
});
assert.equal(fallback?.maxHistoryEstimatedTokens, 8_192 - 2_048);
@@ -247,12 +198,12 @@ describe('declared relay context window', () => {
models: [{ id: 'reasoner-32k', contextWindow: 8_192 }],
relayModelProfiles: { 'reasoner-32k': { contextWindow: 131_072 } },
};
- const policy = buildDefaultContextBudgetPolicy(other, { env: {}, modelId: 'reasoner-32k' });
+ const policy = buildDefaultContextBudgetPolicy(other, { modelId: 'reasoner-32k' });
assert.equal(policy?.maxHistoryEstimatedTokens, 131_072 - 16_384);
// Absent stays absent: an undeclared model still reads the stored row.
const undeclared: LlmConnection = { ...other, relayModelProfiles: undefined };
assert.equal(
- buildDefaultContextBudgetPolicy(undeclared, { env: {}, modelId: 'reasoner-32k' })
+ buildDefaultContextBudgetPolicy(undeclared, { modelId: 'reasoner-32k' })
?.maxHistoryEstimatedTokens,
8_192 - 2_048,
);
diff --git a/packages/runtime/src/__tests__/context-budget-model-facts.test.ts b/packages/runtime/src/__tests__/context-budget-model-facts.test.ts
index 0208f14a8..d472ad935 100644
--- a/packages/runtime/src/__tests__/context-budget-model-facts.test.ts
+++ b/packages/runtime/src/__tests__/context-budget-model-facts.test.ts
@@ -33,10 +33,7 @@ test('context budgeting prefers a model input limit over its context window', ()
};
assert.equal(resolveSelectedModelContextWindow(connection, undefined), 600);
- assert.equal(
- buildDefaultContextBudgetPolicy(connection, { env: {} })?.maxHistoryEstimatedTokens,
- 450,
- );
+ assert.equal(buildDefaultContextBudgetPolicy(connection)?.maxHistoryEstimatedTokens, 450);
});
test('invalid zero input limits do not disable the context-window fallback', () => {
diff --git a/packages/runtime/src/__tests__/context-budget-retired-settings.test.ts b/packages/runtime/src/__tests__/context-budget-retired-settings.test.ts
deleted file mode 100644
index d45245c49..000000000
--- a/packages/runtime/src/__tests__/context-budget-retired-settings.test.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-
-import assert from 'node:assert/strict';
-import { describe, test } from 'node:test';
-import type { LlmConnection } from '@maka/core/llm-connections';
-import { buildDefaultContextBudgetPolicy } from '../context-budget-policy.js';
-
-describe('retired context policy settings', () => {
- test('retired semantic compact environment settings do not change the runtime policy', () => {
- const baseline = buildDefaultContextBudgetPolicy(connection(), { env: {} });
- const configured = buildDefaultContextBudgetPolicy(connection(), {
- env: {
- MAKA_CONTEXT_SEMANTIC_COMPACT: 'on',
- MAKA_CONTEXT_SEMANTIC_COMPACT_MODE: 'replace',
- MAKA_CONTEXT_SEMANTIC_COMPACT_MAX_ACTIVE_ESTIMATED_TOKENS: '4096',
- },
- });
- assert.deepEqual(configured, baseline);
- });
-});
-
-function connection(): LlmConnection {
- return {
- slug: 'anthropic-main',
- name: 'Anthropic',
- providerType: 'anthropic',
- defaultModel: 'claude-sonnet-4-5-20250929',
- enabled: true,
- createdAt: 1,
- updatedAt: 1,
- };
-}
diff --git a/packages/runtime/src/__tests__/mid-turn-capacity-backend.test.ts b/packages/runtime/src/__tests__/mid-turn-capacity-backend.test.ts
index e909c9b4b..e747d512e 100644
--- a/packages/runtime/src/__tests__/mid-turn-capacity-backend.test.ts
+++ b/packages/runtime/src/__tests__/mid-turn-capacity-backend.test.ts
@@ -107,10 +107,8 @@ interface MidTurnFixtureOptions {
/**
* Derive the policy from the runtime default (buildDefaultContextBudgetPolicy)
* instead of the hand-built one, so a test can exercise the shipped default.
- */
+ */
useRuntimeDefaultPolicy?: boolean;
- /** Exercise the supported explicit history-compaction escape hatch. */
- historyCompactOff?: boolean;
reserveTokens?: number;
summarize?: (
input: HistoryCompactSummaryInput,
@@ -488,18 +486,6 @@ function buildFixture(options: MidTurnFixtureOptions = {}): MidTurnFixture {
{
name: 'runtime-default-mid-turn',
modelId: 'mock-model-id',
- // Every value is the shipped runtime default (including the
- // default-on midTurn derivation and the window-bounded reserve
- // under test); a test may still size the reserve to its toy window
- // through the first-class env knob by passing reserveTokens.
- env: {
- ...(options.reserveTokens !== undefined
- ? {
- MAKA_CONTEXT_HISTORY_COMPACT_RESERVE_TOKENS: String(options.reserveTokens),
- }
- : {}),
- ...(options.historyCompactOff ? { MAKA_CONTEXT_HISTORY_COMPACT: 'off' } : {}),
- },
},
)
: {
@@ -1587,52 +1573,10 @@ describe('mid-turn capacity default-on safety guards (issue #882 PR 3)', () => {
assert.equal(promptJson(fixture, 0).includes('OVERSIZED_TOOL_RESULT_'), false);
});
- test('rejects an oversized prior turn when history compaction is disabled', async () => {
- const fixture = buildFixture({
- useRuntimeDefaultPolicy: true,
- withoutContextWindow: true,
- historyCompactOff: true,
- priorChars: 180_000,
- priorShape: 'tool_heavy',
- });
- await runFixtureTurn(fixture);
-
- assert.equal(fixture.summarizerCalls, 0);
- assert.equal(fixture.model.doStreamCalls.length, 0);
- const complete = fixture.events.find((event) => event.type === 'complete');
- assert.equal(complete?.type, 'complete');
- if (complete?.type !== 'complete') return;
- assert.equal(complete.stopReason, 'context_budget_exhausted');
- assert.equal(complete.contextBudgetExhaustedDetail, 'no_safe_completed_span');
- });
-
- test('rejects an oversized penultimate turn when history compaction is disabled', async () => {
- const fixture = buildFixture({
- useRuntimeDefaultPolicy: true,
- withoutContextWindow: true,
- historyCompactOff: true,
- priorChars: 180_000,
- priorShape: 'tool_heavy',
- });
- fixture.priorEvents.push(
- runtimeTextEvent('latest-user', 'turn-latest', 'user', 'small latest question'),
- runtimeTextEvent('latest-model', 'turn-latest', 'model', 'small latest answer'),
- );
- await runFixtureTurn(fixture);
-
- assert.equal(fixture.model.doStreamCalls.length, 0);
- const complete = fixture.events.find((event) => event.type === 'complete');
- assert.equal(complete?.type, 'complete');
- if (complete?.type !== 'complete') return;
- assert.equal(complete.stopReason, 'context_budget_exhausted');
- assert.equal(complete.contextBudgetExhaustedDetail, 'no_safe_completed_span');
- });
-
test('keeps multiple bounded recent turns below the model capacity', async () => {
const fixture = buildFixture({
useRuntimeDefaultPolicy: true,
contextWindow: 100_000,
- historyCompactOff: true,
priorChars: 40_000,
});
fixture.priorEvents.push(
diff --git a/packages/runtime/src/context-budget-policy.ts b/packages/runtime/src/context-budget-policy.ts
index 1c44bdd7a..2c210c7fd 100644
--- a/packages/runtime/src/context-budget-policy.ts
+++ b/packages/runtime/src/context-budget-policy.ts
@@ -25,18 +25,15 @@ import { finitePositive } from './context-budget-helpers.js';
export interface BuildDefaultContextBudgetPolicyOptions {
name?: string;
- env?: Record<string, string | undefined>;
modelId?: string;
}
export function buildDefaultContextBudgetPolicy(
connection: RuntimeExecutionConnection,
options: BuildDefaultContextBudgetPolicyOptions = {},
-): ContextBudgetPolicy | undefined {
- const env = options.env ?? process.env;
- if (env.MAKA_CONTEXT_BUDGET === 'off') return undefined;
+): ContextBudgetPolicy {
const contextWindow = resolveSelectedModelContextWindow(connection, options.modelId);
- const reserveTokens = defaultCompactReserveTokens(env, contextWindow);
+ const reserveTokens = defaultCompactReserveTokens(contextWindow);
const maxHistoryEstimatedTokens = defaultHistoryBudgetTokens(
connection,
contextWindow,
@@ -46,111 +43,25 @@ export function buildDefaultContextBudgetPolicy(
/-default-history-budget$/,
'',
);
- const staleToolResultPrune = buildStaleToolResultPrunePolicy(env);
- const historyCompact = buildHistoryCompactPolicy(
- env,
- `${surfaceName}-history-compact`,
- reserveTokens,
- );
- const activeToolResultPrune = buildActiveToolResultPrunePolicy(env);
- if (
- maxHistoryEstimatedTokens === undefined &&
- staleToolResultPrune === undefined &&
- historyCompact === undefined &&
- activeToolResultPrune === undefined
- ) {
- return undefined;
- }
return {
name: options.name ?? 'default-history-budget',
...(maxHistoryEstimatedTokens !== undefined ? { maxHistoryEstimatedTokens } : {}),
- ...(staleToolResultPrune !== undefined ? { staleToolResultPrune } : {}),
- ...(historyCompact !== undefined ? { historyCompact } : {}),
- ...(activeToolResultPrune !== undefined ? { activeToolResultPrune } : {}),
- };
-}
-
-function buildStaleToolResultPrunePolicy(
- env: Record<string, string | undefined>,
-): NonNullable<ContextBudgetPolicy['staleToolResultPrune']> | undefined {
- const enabled = parseOptionalBoolean(
- env.MAKA_CONTEXT_STALE_TOOL_RESULT_PRUNE,
- 'MAKA_CONTEXT_STALE_TOOL_RESULT_PRUNE',
- );
- if (enabled === false) return undefined;
- return {
- enabled: true,
- maxResultEstimatedTokens: parsePositiveInt(env.MAKA_CONTEXT_STALE_TOOL_RESULT_MAX_TOKENS, 2048),
- minRecentTurnsFull: parsePositiveInt(env.MAKA_CONTEXT_STALE_TOOL_RESULT_MIN_RECENT_TURNS, 2),
- };
-}
-
-function buildActiveToolResultPrunePolicy(
- env: Record<string, string | undefined>,
-): NonNullable<ContextBudgetPolicy['activeToolResultPrune']> | undefined {
- const enabled = parseOptionalBoolean(
- env.MAKA_CONTEXT_ACTIVE_TOOL_RESULT_PRUNE,
- 'MAKA_CONTEXT_ACTIVE_TOOL_RESULT_PRUNE',
- );
- if (enabled === false) return undefined;
- return {
- enabled: true,
- maxCurrentResultEstimatedTokens: parsePositiveInt(
- env.MAKA_CONTEXT_ACTIVE_TOOL_RESULT_MAX_ESTIMATED_TOKENS,
- 2048,
- ),
- minSupersededResultEstimatedTokens: parsePositiveInt(
- env.MAKA_CONTEXT_ACTIVE_TOOL_RESULT_MIN_SUPERSEDED_TOKENS,
- 256,
- ),
- minStepNumber:
- parseOptionalNonNegativeInt(env.MAKA_CONTEXT_ACTIVE_TOOL_RESULT_MIN_STEP_NUMBER) ?? 1,
- };
-}
-
-function buildHistoryCompactPolicy(
- env: Record<string, string | undefined>,
- defaultHighWaterName: string,
- reserveTokens: number,
-): NonNullable<ContextBudgetPolicy['historyCompact']> | undefined {
- const enabled = parseOptionalBoolean(
- env.MAKA_CONTEXT_HISTORY_COMPACT,
- 'MAKA_CONTEXT_HISTORY_COMPACT',
- );
- if (enabled === false) return undefined;
- const midTurn = buildHistoryCompactMidTurnPolicy(env, reserveTokens);
- return {
- enabled: true,
- highWaterName: env.MAKA_CONTEXT_HISTORY_COMPACT_HIGH_WATER_NAME ?? defaultHighWaterName,
- ...(midTurn !== undefined ? { midTurn } : {}),
- };
-}
-
-// Mid-turn capacity compaction is a runtime-owned default (issue #882 PR 3):
-// whenever history compaction is enabled, the runtime derives midTurn from the
-// selected model's window (`contextWindow - reserveTokens`, the same reserve as
-// the turn-boundary budget) so every surface inherits the invariant without
-// copying config. `MAKA_CONTEXT_HISTORY_COMPACT_MID_TURN=off` stays as the
-// explicit escape hatch. The backend still gates activation on the checkpoint
-// seams, the persisted head anchor, and a KNOWN context window, so a session
-// without model metadata (or a child with no anchor seam) never misfires even
-// though the default is on.
-function buildHistoryCompactMidTurnPolicy(
- env: Record<string, string | undefined>,
- reserveTokens: number,
-): NonNullable<NonNullable<ContextBudgetPolicy['historyCompact']>['midTurn']> | undefined {
- const enabled = parseOptionalBoolean(
- env.MAKA_CONTEXT_HISTORY_COMPACT_MID_TURN,
- 'MAKA_CONTEXT_HISTORY_COMPACT_MID_TURN',
- );
- if (enabled === false) return undefined;
- const reserveTailEvents = parseOptionalNonNegativeInt(
- env.MAKA_CONTEXT_HISTORY_COMPACT_MID_TURN_TAIL_EVENTS,
- );
- return {
- enabled: true,
- reserveTokens,
- ...(reserveTailEvents !== undefined ? { reserveTailEvents } : {}),
+ staleToolResultPrune: {
+ enabled: true,
+ maxResultEstimatedTokens: 2_048,
+ minRecentTurnsFull: 2,
+ },
+ historyCompact: {
+ enabled: true,
+ highWaterName: `${surfaceName}-history-compact`,
+ midTurn: { enabled: true, reserveTokens },
+ },
+ activeToolResultPrune: {
+ enabled: true,
+ maxCurrentResultEstimatedTokens: 2_048,
+ minSupersededResultEstimatedTokens: 256,
+ minStepNumber: 1,
+ },
};
}
@@ -160,15 +71,9 @@ function buildHistoryCompactMidTurnPolicy(
// summarizer for a checkpoint the replay gate could never admit. The default
// is therefore bounded by the KNOWN window (a quarter of it, capped at 16384;
// peers bound the same way: opencode caps its buffer by the model's output
-// limit, gemini-cli triggers at a window fraction). An explicit
-// MAKA_CONTEXT_HISTORY_COMPACT_RESERVE_TOKENS is respected verbatim, and an
-// unknown window keeps the classic constant.
-function defaultCompactReserveTokens(
- env: Record<string, string | undefined>,
- contextWindow: number | undefined,
-): number {
- const explicit = parseOptionalPositiveInt(env.MAKA_CONTEXT_HISTORY_COMPACT_RESERVE_TOKENS);
- if (explicit !== undefined) return explicit;
+// limit, gemini-cli triggers at a window fraction). An unknown window keeps
+// the classic constant.
+function defaultCompactReserveTokens(contextWindow: number | undefined): number {
if (contextWindow === undefined) return 16_384;
return Math.min(16_384, Math.max(1, Math.floor(contextWindow / 4)));
}
@@ -235,41 +140,3 @@ export function resolveContextBudgetCapacity(
if (historyBudget === undefined || reserveTokens === undefined) return undefined;
return { tokens: historyBudget + reserveTokens, source: 'policy_fallback' };
}
-
-function parsePositiveInt(value: string | undefined, fallback: number): number {
- const parsed = parseOptionalPositiveInt(value);
- return parsed ?? fallback;
-}
-
-function parseOptionalPositiveInt(value: string | undefined): number | undefined {
- if (!value) return undefined;
- const parsed = Number.parseInt(value, 10);
- return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
-}
-
-function parseOptionalNonNegativeInt(value: string | undefined): number | undefined {
- if (!value) return undefined;
- const parsed = Number.parseInt(value, 10);
- return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
-}
-
-function parseOptionalBoolean(value: string | undefined, name: string): boolean | undefined {
- const normalized = value?.trim().toLowerCase();
- if (!normalized) return undefined;
- switch (normalized) {
- case '1':
- case 'true':
- case 'yes':
- case 'on':
- case 'enabled':
- return true;
- case '0':
- case 'false':
- case 'no':
- case 'off':
- case 'disabled':
- return false;
- default:
- throw new Error(`${name} must be a boolean, got ${JSON.stringify(value)}`);
- }
-}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org