Skip to content

feat: usage_update, thinking level max (agent and extension), auto_compact, max_turn_requests - #131

Merged
zy1233 merged 4 commits into
mainfrom
feat/acp-usage-update
Nov 16, 2026
Merged

zy1233 merged 4 commits into
mainfrom
feat/acp-usage-update

Conversation

@zy1233

@zy1233 zy1233 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Summary

Four changes, one commit each. This PR publishes nothing.

  1. 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 of docs/specs/2026-11-13-agent-context-usage.md.
  2. The max thinking 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 of docs/specs/2026-11-16-thinking-max-and-turn-limit.md.
  3. max_turns and compaction (27a853d): a key auto_compact, the stop reason max_turn_requests, and a higher example value. Same record.
  4. The extension offers max (the last commit): the Thinking menu lists max, only for an agent that knows it.

1. usage_update

agent.toml   [model] / [[models]]   context_window = 200000      (a whole number; never inherited)
  config.py         ModelChoice.context_window     a value that cannot be used is dropped, with a note at session start
    factory.py      model_for_choice               Model.context_window only when declared
                    compaction_settings            limits fit small windows
    agent.py        sends UsageUpdate(used, size)  (new: _report_context_use and 3 helpers)
      turn_end                used = number of the provider + estimate for the tool results
      session_compact         used = estimate for the messages that remain
      session/load, /resume   used = count of the saved history, only if it is still true
      set_config_option       last count again, with the window of the new model
    context_usage.py (new)    the pure part: how `used` is found

When the agent sends nothing:

Case usage_update
The model has no context_window (the 128,000 of the core is a placeholder) none
The provider gives no usage (some gateways), or the turn ends with error or aborted none
A compaction, in a session that has no count yet none
A change to a model with no window (ACP cannot clear the numbers of a client) none
cost never (the agent has no price table)

2. The max thinking level

thinking_level = "max"   (agent.toml)
  types.py              ThinkingLevel has a seventh value
  config.py             the valid levels come from the type
                        a value that is not a level: "off", and a note at session start (it was silent)
  langchain_stream.py   one key more in each of the three tables
    OpenAI format (gateways too)   reasoning_effort = "max"       (xhigh stays "high")
    DeepSeek's own API             reasoning_effort = "max"       (the same as xhigh)
    Anthropic                      budget_tokens = 40000          (the same as xhigh: a budget has no step above)

No table of levels per model (as pi has): max is 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_turns and compaction

agent.toml   auto_compact = true | false                       (new, optional)
  factory.auto_compact_enabled(config, choice)
    the key is set                  -> the key
    the key is not set              -> a declared context_window  OR  max_turns >= 30
    after a change of model         -> decided again for the new model
  agent.py  _stop_reason            -> "max_turn_requests" when the error text holds MAX_TURNS_MESSAGE
                                       (it was "end_turn"; any other error is still "end_turn")
  agent.example.toml                -> max_turns = 200 (was 50); context_window = 1000000 (was 128000)

The default of max_turns in the code is still None (no limit): the 50 was only the example value.

4. The extension offers max

An agent that does not know max reads it as off and says nothing. So the menu must not offer max to it. The extension reads the agent version from initialize, and the file before the agent starts, so the two now meet after initialize:

 vscode/src/core/
   thinking.ts
+    MAX_LEVEL_SINCE = "1.0.0"            the first agent release that knows max
+    thinkingLevelsFor(agentVersion)      max on top, only from that version on
     readThinking(text, levels)           a level that is not in `levels` is `invalidLevel` (the agent uses off)
   version.ts
+    agentVersionAtLeast(version, min)    PEP 440: "1.0.0rc1" and a version that cannot be read do not count
   chat-controller.ts
     start()
-      read agent.toml and parse it        (before the agent starts)
+      read the text of agent.toml         (before the agent starts, as before)
       initialize                          -> agentInfo.version
+      parse the text for that version     -> max in the file: "max" (new agent) | "off" + note (old agent)
     applyThinkingLevel("max")
+      dropped when the running agent does not know it
 vscode/src/core/protocol.ts, src/webview/main.ts    the page takes "max"

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.

Step Before (main) After
One prompt, context_window = 128000 none: usage_update occurs 0 times in packages/pi-agent-cli/pi_agent_cli one {"used": 5, "size": 128000, "sessionUpdate": "usage_update"}, after the answer, no cost
session/load in a new process none the same message, after the replay
A prompt after a change to a model with no window none none

1. Through the extension. A throwaway test (not in this PR) ran the real agent with the real ChatController of vscode/. With context_window = 128000, the state had usage {"used": 5, "size": 128000} after one prompt. With no context_window, usage was undefined.

2 and 3. The agent, with the change taken out.

thinking_level = "max"      before: "off", no word     after: "max"; reasoning_effort "max" (OpenAI format, DeepSeek), budget 40000 (Anthropic)
thinking_level = "ultra"    before: "off", no word     after: "off", and a note at session start
max_turns = 3 reached       before: end_turn           after: max_turn_requests
context_window, no max_turns   before: never compacts  after: compacts (auto_compact = false turns it off)
  • Before: with the source of the max commit taken out and its tests kept, 12 of them fail. The tests of auto_compact and max_turn_requests fail on the code of main (the stop reason is end_turn, and auto_compact_enabled does not exist).
  • After: all pass. Five deliberate faults, one at a time (the stop reason branch, the rule for a declared window, the rule that the key wins, the decision after a change of model, the text of the error), each fail a test.

4. The extension. The controller runs against the fake agent (FAKE_AGENT_VERSION), the file is a real agent.toml in a temporary folder:

agent 0.9.1   menu: xhigh high medium low minimal off          (six)
              request for "max"  -> no question, the file is not changed
              file has max       -> shows "off" and the note 'thinking_level in agent.toml is "max", which the agent does not know. It uses off.'
agent 1.0.0   menu: max xhigh high medium low minimal off      (seven)
              request for "max"  -> modal, thinking_level = "max" in the file, the agent restarts at max, the next turn says level:max
              file has max       -> shows "max", no note
  • Before: the page test for max fails when the guard in webview/main.ts is taken out (posted is empty: the page drops the choice).
  • After: npm run check (typecheck, lint, vitest): 351 passed. The 18 skipped are 16 tests of the real agent (they need ZYCODE_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.ts and vscode/test/webview.test.ts (item 4).

Check Result
pytest, Windows (Python 3.12.7) 6250 passed, 87 skipped, 31 deselected
pytest, Linux (WSL, Python 3.12.3) 6127 passed, 18 skipped, 31 deselected
ruff check . and ruff format --check . All checks passed; 329 files formatted
npm run check in vscode/ (Windows, Node 24, with Chrome for the page tests) typecheck and lint clean; 351 passed, 18 skipped

zypi. A small Rust program with the crate versions of tui/Cargo.lock (agent-client-protocol 0.10.4) parses the usage_update of the wire check when the feature unstable is on (it is on in tui/Cargo.toml). Without the feature it fails with unknown 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. For max_turn_requests the 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_compact and the level max are then public config values, so a later rename needs an alias.

What a user sees, and who:

  • context_window set: the agent sends usage_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_window set and no max_turns: the agent now compacts by itself (before: never). auto_compact = false turns it off. context_window is not released yet, so nobody depends on the old behaviour.
  • thinking_level with a value that is not a level: still off, and now a note says so at the start of the session.
  • A prompt that hits max_turns: the stop reason is max_turn_requests (before: end_turn). The VS Code extension shows "The turn ended: max_turn_requests." and zypi says "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 is None.
  • The VS Code menu: nothing changes until the extension bundles an agent of 1.0.0 or later (the pin in vscode/agent-assets.json is 0.9.1). Then max appears by itself.

A model with no context_window and no max_turns does not change.

Blast Radius: users who write context_window, auto_compact, max_turns or thinking_level in agent.toml (compaction timing, one new session update, one new stop reason). The menu of the extension after the next pin.

The number MAX_LEVEL_SINCE is 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 has max, or a later one. If #130 releases 1.0.0 before this PR is in, 1.0.0 has no max, and the number must go up before the extension bundles that agent. A number that is too low shows max to an agent that reads it as off, with no note. A number that is too high only hides max. 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 max in agent.toml and runs the new agent sees off in the menu and a note that is wrong for that agent. Nothing breaks (read from vscode/src/core/thinking.ts of 1.0.0; not run).

Known limits:

  • The count of usage_update is 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.
  • A window that is too small can show more than 100 %. A change to a model with no window leaves the old numbers on the client.
  • zypi ignores the update only because tui/Cargo.toml turns on the feature unstable. Do not remove that feature without a new check.
  • max is 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.md and docs/TUI-AND-CODE-AGENT.md. git merge-tree against the head of #130 (d2b729b) showed no conflict for the first commit; the commits after it were not tried. CHANGELOG.md is 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 in vscode/README.md, vscode/CHANGELOG.md and design 7d that say the bundled agent sends no usage_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 with effort: 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_anthropic is not installed in the dev environment); macOS; zypi against this agent end to end (only the parse check above); the menu with max in a real VS Code window (the tests use a fake agent that reports a version).

…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
zy1233 force-pushed the feat/acp-usage-update branch from bb51715 to 5971c2b Compare November 16, 2026 07:38
… 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 zy1233 changed the title feat(cli): send ACP usage_update for models with a declared context_window feat: usage_update, thinking level max (agent and extension), auto_compact, max_turn_requests Nov 16, 2026
@zy1233
zy1233 merged commit bfc5f38 into main Nov 16, 2026
21 checks passed
@zy1233
zy1233 deleted the feat/acp-usage-update branch November 16, 2026 08:50
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant