Skip to content

refactor(gateway): deepen ACP event normalization into event_encoder module - #155

Merged
DIodide merged 1 commit into
stagingfrom
refactor/deepen-event-encoder
Jun 30, 2026
Merged

refactor(gateway): deepen ACP event normalization into event_encoder module#155
DIodide merged 1 commit into
stagingfrom
refactor/deepen-event-encoder

Conversation

@DIodide

@DIodide DIodide commented Jun 30, 2026

Copy link
Copy Markdown
Owner

Applies the improve-codebase-architecture skill's top deepening recommendation (chosen from 30 surfaced candidates).

What

The pure ACP-update→SSE normalization — the highest-churn encoding surface (it shifts with every agent/model update) — was buried in the 3179-line session_manager.py god module, interleaved with the stateful session lifecycle, relay, permission, and provisioning machinery. This moves the stateless dict→dict encoding rules into a new sibling module app/services/agents/event_encoder.py behind a small interface:

  • normalize_session_update, normalize_sdk_task_message, parse_sdk_compaction, parse_elicitation_fields (+ the SDK_TASK_MESSAGE_FILTERS list and COMPACTION_SUMMARY_PREAMBLE marker the session meta/replay builders still reference).
  • The 8 leading-underscore helpers + regex/phase constants become private internals of the module (internal seam, not part of the interface).

session_manager.py shrinks 3179 → 2595 lines and imports the public entry points.

Why

  • locality: all update-to-SSE encoding rules concentrate in one named module instead of scattered through a 3k-line file.
  • leverage: the encoding rules are reusable by any transport without touching session state.
  • navigability: a maintainer reasons about encoding without scrolling the god module.
  • The deletion test passes: deleting event_encoder would scatter the rules back across the session module.

Pure relocation — behaviour-preserving

No callsite logic changed. Per "the interface is the test surface" / "replace, don't layer", the existing tests (test_agent_normalize, test_agent_questions, test_agent_usage_gateway) re-point to the real seam (event_encoder) rather than session_manager re-exporting.

Verified: a 5-agent adversarial pass confirmed the moved code is byte-identical (diff exit 0), no circular import, callsites unchanged, no test weakened — and an xhigh code-review returned 0 findings. fastapi 362 passed, ruff clean.

No user-facing change → no CHANGELOG entry.

…module

Applies the improve-codebase-architecture skill's top deepening
recommendation. The pure ACP-update -> SSE normalization (the highest-churn
encoding surface — it shifts with every agent/model update) was buried in the
3179-line session_manager god module, interleaved with the stateful session
lifecycle, relay, permission and provisioning machinery.

Move the stateless dict->dict encoding rules into a new sibling module
app/services/agents/event_encoder.py behind a small interface:
normalize_session_update, normalize_sdk_task_message, parse_sdk_compaction,
parse_elicitation_fields (+ the SDK_TASK_MESSAGE_FILTERS list and
COMPACTION_SUMMARY_PREAMBLE marker the session meta/replay builders still
use). The 8 leading-underscore helpers + regex/phase constants become private
internals of the module.

Pure relocation — byte-identical behaviour. session_manager imports the public
entry points; it shrinks 3179 -> 2595 lines. Per "the interface is the test
surface" / "replace, don't layer", the existing tests (test_agent_normalize,
test_agent_questions, test_agent_usage_gateway) re-point to the real seam
(event_encoder) rather than session_manager re-exporting.

Wins — locality: encoding rules concentrate in one named module; leverage:
reusable by any transport without touching session state; navigability: a
maintainer reasons about encoding without scrolling a 3k-line file.

fastapi 362 passed, ruff clean. Behaviour unchanged (no callsite logic touched).
@DIodide
DIodide merged commit ccbefb4 into staging Jun 30, 2026
4 checks passed
@DIodide
DIodide deleted the refactor/deepen-event-encoder branch June 30, 2026 02:28
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