Skip to content

agy-cli 0.1.67: add opt-in report_client_context option for client compaction - #1187

Closed
huangzt wants to merge 2 commits into
magpie-community:mainfrom
huangzt:feat/agy-cli-report-client-context
Closed

huangzt wants to merge 2 commits into
magpie-community:mainfrom
huangzt:feat/agy-cli-report-client-context

Conversation

@huangzt

@huangzt huangzt commented Nov 15, 2026

Copy link
Copy Markdown

Why

When agy trims or compacts history on replay, the usage reported back by agy reflects agy's internal trimmed context window rather than the full request sent by the client. For clients such as Codex that watch reported input_tokens + cache_read_input_tokens + cache_creation_input_tokens to decide when to compact history, the reported context size drops unexpectedly and client-side compaction does not trigger on time.

What changed

  • Opt-in plugin option & env override (packages/agy-cli/index.mjs):
    • Declare report_client_context under auth.options (default: false, with en / zh / zh-TW / ja / de labels and descriptions).
    • Resolve reportClientContextEnabled(magpie) with AGY_BRIDGE_REPORT_CLIENT_CONTEXT (1/true/on/yes or 0/false/off/no/disabled) taking precedence over magpie?.option?.("agy-cli", "report_client_context").
    • Use defensive input = {} in AntigravityBridgePlugin so OpenCode 1.x/2.x callers without a magpie context continue working unchanged.
  • Client-reported usage padding without polluting internal calibration (packages/agy-cli/index.mjs):
    • Store clientInputEstimate (estimateInputTokens(body)) on each Turn.registerResponse step.
    • Add clientReportedUsage(step, usage, final, enabled) to pad cache_read_input_tokens up to clientInputEstimate only on the outgoing message_delta payload, while:
      • skipping non-final agy_same_generation intermediate tool steps (keeping their reported usage at zero),
      • never clamping downward when agy already reports more tokens than clientInputEstimate, and
      • passing the unpadded usage to turn.recordResponseUsage(...) so internal window calibration remains faithful to agy.
    • Route all streamResponse call sites (tool continuation, stale-turn replay recovery, and normal turns) through a shared respond helper, covering both streaming and stream: false JSON responses.
  • Docs, version bump, and tests:
    • Update packages/agy-cli/README.md and packages/agy-cli/README.en.md (Features and environment variables table).
    • Bump packages/agy-cli/package.json from 0.1.66 to 0.1.67 (for scripts/bumped.mjs).
    • Add pluginContext injection in packages/agy-cli/test/testkit.mjs and tests in packages/agy-cli/test/usage-settlement.mjs covering replay-trim padding, internal calibration isolation, option metadata validation, agy_same_generation multi-tool steps, stream: false, no-downward-clamp guard, env override precedence, and pluginContext: null.

Verification

  • HOME=$(mktemp -d) bun test packages/agy-cli/test/usage-settlement.mjs — 43 pass, 0 fail (run locally via magpie-bun)
  • HOME=$(mktemp -d) bun test inside packages/agy-cli — 35 pass, 0 fail (235 assertions)
  • Verified packages/agy-cli/opencode2.mjs matches HEAD:scripts/opencode2.mjs, OpenCode 1.x/2.x plugin export/loader check without magpie context, npm pack --dry-run (magpie-community-opencode-agy-cli-auth-0.1.67.tgz), and git diff --check

…mpaction

When agy trims or compacts replay history, its reported input and cached read
tokens reflect agy's smaller internal context rather than the client's full
request payload. Clients like Codex that trigger compaction from reported
input/cache usage then see context shrink and fail to compact on time.

Add an opt-in `report_client_context` plugin option (default false) and
`AGY_BRIDGE_REPORT_CLIENT_CONTEXT` env override (env takes precedence):
- Capture `clientInputEstimate` (`estimateInputTokens(body)`) per response step
  and pad `cache_read_input_tokens` in outgoing `message_delta.usage` up to
  that estimate when enabled, keeping `agy` actual > client estimate intact and
  preserving zero usage on intermediate `agy_same_generation` tool steps.
- Keep `Turn.recordResponseUsage` unpadded so internal window calibration stays
  faithful to agy, and apply the option consistently across SSE and
  `stream: false` responses.
- Document the option and env var in README.md / README.en.md and bump version
  to 0.1.67.

Tested on macOS with temp HOME (`magpie-bun test`):
- `test/usage-settlement.mjs`: 43 pass, 0 fail
- `agy-cli.test.mjs`, `cloak.test.mjs`, `install.test.mjs`: 35 pass, 0 fail
@yetone

yetone commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Harm scan: clean. The only new input is AGY_BRIDGE_REPORT_CLIENT_CONTEXT or the plugin option. There's no new network call, file access or child process, and the switch is off by default.

One thing to say in the option's text: magpie's Usage page prices cache_read_input_tokens, so with this switch on, the padded tokens show up there as spent cache reads, not just in what Codex sees. The README says it "inflates reported cached read usage". Saying that the cost shown in Magpie goes up too would make the trade-off clear before someone turns it on.

@huangzt

huangzt commented Nov 15, 2026

Copy link
Copy Markdown
Author

Thanks for pointing that out! I've updated the report_client_context option description (including all localized variants) as well as README.md and README.en.md to explicitly note that Magpie's Usage page prices cache_read_input_tokens, so enabling this option will also increase the cost shown in Magpie. Pushed in 7930b27.

@huangzt

huangzt commented Nov 15, 2026

Copy link
Copy Markdown
Author

Closing this PR — we'll keep this as a local patch for our own workflow instead. Thanks for reviewing!

@huangzt huangzt closed this Nov 15, 2026
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.

2 participants