Repository navigation
feat: usage_update, thinking level max (agent and extension), auto_compact, max_turn_requests - #131
Merged
Merged
Conversation
…indow The agent sent no context use to a client, so the Context row of the VS Code extension had nothing to show. Plan A of docs/specs/2026-11-13-agent-context-usage.md is built. A model that has `context_window` (a whole number of tokens) in `[model]` or in a `[[models]]` entry of agent.toml gets `usage_update(used, size)`: - at each turn_end: the number of the provider plus an estimate for the tool results of the turn; - after a compaction: an estimate of the messages that remain (the kept messages still carry the usage of the context from before); - after session/load and session/resume: the count of the saved history, only when a provider number follows the last compaction; - after a change of model: the last count with the new window. Nothing is sent for a model with no window (the 128,000 of the core is a placeholder), for a provider that gives no usage, or for a turn that ended with error or aborted. There is no `cost`. The key is never inherited: a [[models]] entry has its own value or none. A value that cannot be used is dropped, and the agent says so at the start of the session. Compaction now uses the real window of a model that declares one, and its limits fit small windows (reserve_tokens and keep_recent_tokens are cut to a quarter and a third of the window when that is less). A model with no window does not change. 51 tests in packages/pi-agent-cli/tests/test_context_usage.py.
zy1233
force-pushed
the
feat/acp-usage-update
branch
from
November 16, 2026 07:38
bb51715 to
5971c2b
Compare
… an unknown level Providers now name their highest effort `max` (DeepSeek V4, OpenAI GPT-5.6 and later, Anthropic adaptive models, Kimi K3, GLM 5.x), and the reference `pi` has a level of its own for it since v0.80.6. The agent had six levels. With `provider = "openai"` (the way to reach a gateway) the level `xhigh` is sent as "high", so a gateway that serves a DeepSeek V4 model could never be asked for "max". `ThinkingLevel` has a seventh value, `max`: - OpenAI format (gateways too): `reasoning_effort = "max"`, as it is. A model that does not take it answers with an error, and nothing is lowered here. - DeepSeek's own API: "max", the same as `xhigh`. - Anthropic: the budget of `xhigh` (40000). A budget has no step above. The three mapping tables must name every level: a level that a table lacks sends no parameter, and the model then silently does not think. A test checks it. `thinking_level` in agent.toml that is not one of the levels was silently `off`, so a typo looked like "off". It is `off` still, and the user is now told at the start of the session (the same note channel as `context_window`). A list as the value used to stop the loading with a TypeError. The valid levels now come from the type, so a new level of the core is valid in the CLI at once. Not done: a table of levels per model, as `pi` has (`thinkingLevelMap`), so `max` is open for every model. Not changed: Anthropic's budget form, which the documentation of Anthropic says that Claude 4.7 and later refuse (not verified against the live API; noted in docs/DESIGN.md). The VS Code extension has six levels in its menu. It needs an agent that knows `max`, so it follows after the agent release.
…the example `max_turns` The default of `max_turns` is `None` (no limit) in the core, the harness and the CLI. The 50 that a user sees is the value in `agent.example.toml`. Three small changes make a high limit and a window of 1M tokens work. `auto_compact` (a key at the top of agent.toml, `true` or `false`) Compaction by the agent was on only when `max_turns >= 30`, so a user with no `max_turns` (every user of `--setup`) never compacted, and a user who wanted a high limit and no compaction could not have it. `factory.auto_compact_enabled` decides now. The key wins. When it is not set, compaction is on for a model with a declared `context_window` and for `max_turns >= 30` (the old rule, which the benchmark path uses), and off otherwise. After a change of model the rule decides again for the new model. A value that is not a boolean is ignored, with a note. `auto_compact = true` for a model with no window assumes the placeholder of 128,000 tokens, so a model with a window of 1M needs its real `context_window`: with the placeholder, compaction starts above 111,616 tokens, which is 11.2 % of that window. `max_turn_requests` A prompt that hit `max_turns` ended with the stop reason `end_turn` and a line of error text. ACP has a stop reason for it, and now the agent sends it. `MAX_TURNS_MESSAGE` is the one source of the text of `MaxTurnsExceededError`, and `_stop_reason` finds the failure by it. Any other error is still `end_turn`. The VS Code extension shows "The turn ended: max_turn_requests." for it without a change, and `zypi` takes it as "done". `agent.example.toml` `max_turns` is 200 (it was 50), with a comment that says it guards against a loop that does not end and does not limit the context. In the benchmark a long task used up to 100 calls, and the official `pi` ran one task for 334. The example `context_window` is 1000000 (it was 128000, which is wrong for a model with 1M). The default in the code stays `None`: a finite default would put a limit that nobody can see on every user who has no `max_turns`. Test helper: `make_config` in test_context_usage.py sets `auto_compact=False` unless a test says otherwise, so that a window of 40 tokens does not compact after every answer of the tests that start a compaction themselves. Five rules were broken one at a time, and each break made a test fail. Record: docs/specs/2026-11-16-thinking-max-and-turn-limit.md.
The agent has the thinking level `max` (b688701). An agent that does not know it reads `thinking_level = "max"` as `off` and says nothing. So the Thinking menu lists `max` only for an agent of MAX_LEVEL_SINCE (1.0.0) or later. The version is `agentInfo.version` of `initialize`. The numbers are compared as PEP 440: a pre-release of 1.0.0 (`1.0.0rc1`) and a version that cannot be read do not count. The extension read agent.toml before it started the agent. It still reads the text there (the agent reads it at its start), and now decides what the text says after `initialize`, because only then it has the version. So `max` in the file is `max` for a new agent, and `off` with the note "which the agent does not know" for an old one. The page takes `max`. The controller drops a request for `max` when the running agent does not know it. Tests: - version.test.ts: agentVersionAtLeast (numbers as numbers, pre-releases, post-releases, versions that cannot be read). - thinking.test.ts: the levels per version, read and write of `max`, and the controller with the fake agent at 0.9.1 and at 1.0.0 (menu, request, file, restart, note). - webview.test.ts: the page sends `max`. Without the guard in webview/main.ts this test fails (posted is empty). README.md and CHANGELOG.md of the extension stay as they are until the extension release: their sentences are true for the agent 0.9.1 that it bundles today. PACKAGING.md has a new step: check MAX_LEVEL_SINCE when the pin moves.
zy1233
added a commit
that referenced
this pull request
Nov 16, 2026
…the known issues to 1.0.0 The merge of the 1.0.0 branch had dropped the heading of 0.9.1, so the release notes of v1.0.0 (cut by awk from one heading to the next) would have held the text of 0.9.1. Also: the 1.0.0 section now lists usage_update, the max thinking level, auto_compact and max_turn_requests (all from #131), moves the removal of the Python fallback of zypi to Changed as a behaviour change with the one-line fix, says what the Omarchy item really is (a draft with two known defects), and has its own Known issues. Date 2026-11-16.
This was referenced Nov 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Four changes, one commit each. This PR publishes nothing.
usage_update(5971c2b): the agent tells an ACP client how full the context window is. The VS Code extension already reads it (design 7d), so its Context row shows for a model that has a window. Plan A ofdocs/specs/2026-11-13-agent-context-usage.md.maxthinking level (b688701): the highest effort of DeepSeek V4, OpenAI GPT-5.6 and later, Anthropic adaptive models, Kimi K3 and GLM 5.x. Plan A ofdocs/specs/2026-11-16-thinking-max-and-turn-limit.md.max_turnsand compaction (27a853d): a keyauto_compact, the stop reasonmax_turn_requests, and a higher example value. Same record.max(the last commit): the Thinking menu listsmax, only for an agent that knows it.1.
usage_updateWhen the agent sends nothing:
usage_updatecontext_window(the 128,000 of the core is a placeholder)errororabortedcost2. The
maxthinking levelNo table of levels per model (as
pihas):maxis open for every model, and a model that does not take it answers with an error. A test checks that each table names every level: a level that a table lacks sends no parameter, and the model then silently does not think.3.
max_turnsand compactionThe default of
max_turnsin the code is stillNone(no limit): the 50 was only the example value.4. The extension offers
maxAn agent that does not know
maxreads it asoffand says nothing. So the menu must not offermaxto it. The extension reads the agent version frominitialize, and the file before the agent starts, so the two now meet afterinitialize:Evidence
1. On the wire (Windows). The real agent process (
python -m pi_agent_cli) on stdio, a fake OpenAI-format model server, raw ACP JSON lines.main)context_window = 128000usage_updateoccurs 0 times inpackages/pi-agent-cli/pi_agent_cli{"used": 5, "size": 128000, "sessionUpdate": "usage_update"}, after the answer, nocostsession/loadin a new process1. Through the extension. A throwaway test (not in this PR) ran the real agent with the real
ChatControllerofvscode/. Withcontext_window = 128000, the state hadusage{"used": 5, "size": 128000}after one prompt. With nocontext_window,usagewasundefined.2 and 3. The agent, with the change taken out.
maxcommit taken out and its tests kept, 12 of them fail. The tests ofauto_compactandmax_turn_requestsfail on the code ofmain(the stop reason isend_turn, andauto_compact_enableddoes not exist).4. The extension. The controller runs against the fake agent (
FAKE_AGENT_VERSION), the file is a realagent.tomlin a temporary folder:maxfails when the guard inwebview/main.tsis taken out (postedis empty: the page drops the choice).npm run check(typecheck, lint, vitest): 351 passed. The 18 skipped are 16 tests of the real agent (they needZYCODE_REAL_AGENT=1) and 2 that do not run on Windows.The new tests are in
packages/pi-agent-cli/tests/test_context_usage.py(item 1: 51 tests; item 3: 23 more),vscode/test/version.test.ts,vscode/test/thinking.test.tsandvscode/test/webview.test.ts(item 4).pytest, Windows (Python 3.12.7)pytest, Linux (WSL, Python 3.12.3)ruff check .andruff format --check .npm run checkinvscode/(Windows, Node 24, with Chrome for the page tests)zypi. A small Rust program with the crate versions oftui/Cargo.lock(agent-client-protocol0.10.4) parses theusage_updateof the wire check when the featureunstableis on (it is on intui/Cargo.toml). Without the feature it fails withunknown variant usage_update. The pager has a catch-all arm for the variants that it does not use (acp/tracker.rs), so it ignores the update. Formax_turn_requeststhe pager already says "done" (turn_completion.rs).Merge Danger
Door: two-way. This PR changes code and docs only. Nothing publishes on merge. A revert undoes it. One exception once a release has it:
context_window,auto_compactand the levelmaxare then public config values, so a later rename needs an alias.What a user sees, and who:
context_windowset: the agent sendsusage_update. Compaction uses the real window (before: the 128,000 placeholder), with limits cut for small windows. A window under 128,000 compacts earlier, and a larger one later. Test:test_compaction_uses_the_window_that_the_user_declared.context_windowset and nomax_turns: the agent now compacts by itself (before: never).auto_compact = falseturns it off.context_windowis not released yet, so nobody depends on the old behaviour.thinking_levelwith a value that is not a level: stilloff, and now a note says so at the start of the session.max_turns: the stop reason ismax_turn_requests(before:end_turn). The VS Code extension shows "The turn ended: max_turn_requests." andzypisays "done". Another client may show it as a failure: not checked.agent.example.toml:max_turns = 200. It is an example: the default in the code isNone.vscode/agent-assets.jsonis 0.9.1). Thenmaxappears by itself.A model with no
context_windowand nomax_turnsdoes not change.Blast Radius: users who write
context_window,auto_compact,max_turnsorthinking_levelinagent.toml(compaction timing, one new session update, one new stop reason). The menu of the extension after the next pin.The number
MAX_LEVEL_SINCEis a guess about a release. It is 1.0.0, because #130 promotes the agent to 1.0.0. It must be the first release that hasmax, or a later one. If #130 releases 1.0.0 before this PR is in, 1.0.0 has nomax, and the number must go up before the extension bundles that agent. A number that is too low showsmaxto an agent that reads it asoff, with no note. A number that is too high only hidesmax.vscode/PACKAGING.md("Change the agent version", step 3) has a check for it, and a test keeps the number above 0.9.1.A user of the released extension 1.0.0 who writes
maxinagent.tomland runs the new agent seesoffin the menu and a note that is wrong for that agent. Nothing breaks (read fromvscode/src/core/thinking.tsof 1.0.0; not run).Known limits:
usage_updateis partly an estimate: the tool results of a turn, and the whole count after a compaction (4 characters for 1 token is too low for CJK text). The next model call gives an exact number.zypiignores the update only becausetui/Cargo.tomlturns on the featureunstable. Do not remove that feature without a new check.maxis open for every model: an older OpenAI model answers with an error.With #130 (1.0.0). Two files changed in both PRs when this was written:
packages/pi-agent-cli/AGENTS.mdanddocs/TUI-AND-CODE-AGENT.md.git merge-treeagainst the head of #130 (d2b729b) showed no conflict for the first commit; the commits after it were not tried.CHANGELOG.mdis not in this PR on purpose: its entry goes in the release PR.Not in this PR: a CHANGELOG entry. The pin and sha256 in
vscode/agent-assets.json. The sentences invscode/README.md,vscode/CHANGELOG.mdand design 7d that say the bundled agent sends nousage_update, and the ones that say the menu has six levels: they are true for the agent 0.9.1 that the extension bundles today, and change at the extension release. Anthropic's adaptive thinking witheffort: the budget form that the agent sends is, by the documentation of Anthropic, refused by Claude 4.7 and later (not verified). A table of levels per model.Not verified: a real VS Code window with the new agent; a live provider or gateway that gets
reasoning_effort = "max"(the tests use scripted models and a fake OpenAI-format server); the Anthropic path (langchain_anthropicis not installed in the dev environment); macOS;zypiagainst this agent end to end (only the parse check above); the menu withmaxin a real VS Code window (the tests use a fake agent that reports a version).