fix: exclude image bytes from compaction token estimates (#255)

[Zheng-Lu]

Summary

Fixes #255.

Replace whole-input JSON serialization in Responses compaction token estimation with a borrowed, typed traversal of the effective model-facing input.

The new estimator:

• Counts textual fields using the existing four UTF-8 bytes-per-token approximation.
• Adds deterministic structural allowances for Responses items and content parts.
• Assigns each image a documented fixed allowance of 1,024 tokens.
• Excludes image URLs, file IDs, and inline base64 bytes from textual token estimates.
• Covers user messages, function and custom tool call outputs, function arguments, reasoning content, and compacted windows.
• Reuses a borrowed model-item iterator so estimation does not clone large image payloads.
• Preserves retained image-bearing user messages during compaction.

The Responses compaction guide now documents the heuristic and its model-specific limitations.

Test Plan

• cargo fmt --all -- --check
• cargo clippy --all-targets -- -D warnings
• cargo test
• cargo test -p agentic-server-core
• cargo test -p agentic-server-core --test compaction_cassette_test

Added coverage verifies:

• 100 KiB and 5 MiB inline encodings produce the same estimate.
• Each additional image adds exactly 1,024 estimated tokens.
• User messages and structured view_image tool call outputs use the same image policy.
• Text growth across messages, tool calls, tool call outputs, and reasoning increases estimates.
• Large image payloads alone do not trigger automatic compaction.
• Genuine long text still triggers compaction.
• Retained image content survives compaction unchanged.
• Text-only estimates remain comparable to the previous JSON-size heuristic.

[LOGO127]

AI-assisted integration check for merge sequencing, not a blocker for this PR against current main.

I checked a3eabb1 alongside the signed core-session proposal #257 (51c3613) and typed-file validation #258 (fab52ff) in an isolated local stack. Two additional combination-only adaptations were needed in compaction.rs:

• fix: reject unsupported message files on typed Responses paths #258 adds InputContent::InputFile, so add_message_content needs an explicit arm (I retained the same non-image field accounting used for tool-output files).
• feat: add bounded transient response sessions to core #257 adds RequestContext::continuation, so context_with_threshold needs continuation: None in its test fixture.

With #258's validation placed in the shared rehydrate_with_continuation path and both documentation sections retained, the stack passed 985 tests / 9 ignored, plus strict all-target/all-feature Clippy. This is a combined-stack result, not a claim about your standalone CI.

Four extra session checks passed: image-preserving source/fork continuations; text-triggered compaction followed by durable promotion and fresh-session restoration; real serialized image bytes still exceeding the retention budget; and file rejection releasing the session before a valid image retry. These same cases fail with the original image-byte estimator.

I had a separate local #255 prototype, but will not open a competing implementation. Happy to contribute the focused session regressions once the shared base is settled. Validation used SQLite/disabled storage and local HTTP substitutes; no live model/GPU or full PostgreSQL claim.

[Zheng-Lu]

AI-assisted integration check for merge sequencing, not a blocker for this PR against current main.

I checked a3eabb1 alongside the signed core-session proposal #257 (51c3613) and typed-file validation #258 (fab52ff) in an isolated local stack. Two additional combination-only adaptations were needed in compaction.rs:

• fix: reject unsupported message files on typed Responses paths #258 adds InputContent::InputFile, so add_message_content needs an explicit arm (I retained the same non-image field accounting used for tool-output files).
• feat: add bounded transient response sessions to core #257 adds RequestContext::continuation, so context_with_threshold needs continuation: None in its test fixture.

With #258's validation placed in the shared rehydrate_with_continuation path and both documentation sections retained, the stack passed 985 tests / 9 ignored, plus strict all-target/all-feature Clippy. This is a combined-stack result, not a claim about your standalone CI.

Four extra session checks passed: image-preserving source/fork continuations; text-triggered compaction followed by durable promotion and fresh-session restoration; real serialized image bytes still exceeding the retention budget; and file rejection releasing the session before a valid image retry. These same cases fail with the original image-byte estimator.

I had a separate local #255 prototype, but will not open a competing implementation. Happy to contribute the focused session regressions once the shared base is settled. Validation used SQLite/disabled storage and local HTTP substitutes; no live model/GPU or full PostgreSQL claim.

Thanks for the thorough integration check and the positive feedback! It's great to hear that the estimator holds up well across those multi-turn session and image-continuation edge cases.

The two adaptations for #257 and #258 look very straightforward. If either of those lands before this PR, I'm happy to rebase and add the InputFile arm and test fixture update. Looking forward to your session regression tests once the base lands!