refactor(coding-agent): extract session action contract helpers

[snimu]

Summary

First PR of a five-PR stack refactoring session-input scheduling into a single typed action model. This PR changes no behavior: it extracts the duplicated prompt-processing pipelines into shared, policy-driven helpers and adds characterization tests that encode the exact per-entrypoint contracts the rest of the stack must preserve.

Stack: #572 contracts (this) <- #573 kernel <- #574 admission <- #575 protocol <- #576 cleanup

Motivation

AgentSession had (at least) three overlapping implementations of "take input, prepare it, hand it to the model": the ordinary direct prompt path (_promptUnserialized, ~365 lines), the injected-message path (_promptInjectedMessageUnserialized, ~175 lines), and the queued-prompt path (_startPreparedPromptItems). Each re-implemented normalization (slash parsing, extension commands, input handlers, skill/template expansion), commit preparation (model/auth validation, pre-turn compaction, before_agent_start, refinement barriers, system-prompt composition), and the dispatch/delivery fence. Before unifying ownership (PR 3), the shared pipeline steps need one implementation each, and the current timing needs to be pinned by tests so later PRs can prove they preserved it.

Code changes

• _normalizeSubmission() / SubmissionNormalizationPolicy: the admission-time pipeline (session-command parse, extension-command lookup/execute, input interception, skill/template expansion), extracted with per-entrypoint policy; timing bit-for-bit preserved.
• _prepareForCommit() / CommitPreparationPolicy + CommitPreparationSteps: the execution-time pipeline (validation, pending model-selection sync, pre-turn compaction, before_agent_start, refine barriers, final message+system-prompt composition), extracted from all three paths with caller differences kept explicit (compaction/model-selection order, bash flushing, empty-extension-prompt preservation).
• _dispatchPromptWithFence() / PromptDispatchFence: the shared dispatch fence (delivery observation, restart-checkpoint section, next-turn drain/restore identity).
• All five existing exactly-once mechanisms untouched: _activeSessionInput phases, _directPromptSectionCount, _directDispatchObservers, accepted-agent-message state, deliveredPendingNextTurnMessages.
• New characterization suite test/suite/agent-session-action-contracts.test.ts: prompt("/compact") parses as a session command while steer("/compact") stays model text; input handlers handle/transform before queue admission; deliverAs: "nextTurn" precedence over triggerTurn; restore methods bypass interception and idle wake.
• New lower-agent test proving there is no atomic batch-dispatch guarantee (a listener failure can commit a prefix of one Agent.prompt(messages) call) - this motivates the per-message two-edge delivery model in PR 2.

LOC: +426/-329 production (net +97), +139 tests.

Note

Extract session action contract helpers in AgentSession to centralize submission normalization and dispatch

• Introduces private helpers _normalizeSubmission, _prepareForCommit, _applyPreparedSystemPrompt, and _dispatchPromptWithFence in agent-session.ts to centralize logic that was previously scattered across prompt, _prompt, steer, followUp, and _startPreparedPromptItems.
• Extension input handlers now run before queue-admission decisions on direct prompts; steer and followUp explicitly reject extension commands and apply skill/template expansion via the shared normalization path.
• On dispatch failures, undelivered pending next-turn messages are restored to _pendingNextTurnMessages via the fence object returned by _dispatchPromptWithFence.
• Adds a new test suite agent-session-action-contracts.test.ts covering session command parsing provenance, input handler ordering, and next-turn delivery precedence.
• Behavioral Change: session slash commands are now parsed only on direct prompt provenance, not through steer/followUp queues.

^{Macroscope summarized 11a1f67.}

---

Note

Medium Risk
Touches core prompt/commit/dispatch timing across all session input entrypoints; mistakes could change ordering, queue admission, or partial-failure recovery despite characterization tests.

Overview
Refactors AgentSession prompt paths so normalization, commit prep, and dispatch share one implementation instead of three copy-pasted pipelines—intended as a no-behavior-change step before a larger scheduling refactor.

New shared helpers: _normalizeSubmission (slash commands, extension commands, input handlers, skill/template expansion, per-entrypoint policy), _prepareForCommit (refine barriers, bash flush, validation, compaction timing, before_agent_start, system prompt), _dispatchPromptWithFence (delivery observation, checkpoint fencing, restoring undelivered next-turn messages), and _applyPreparedSystemPrompt. Direct prompt, injected prompt, _prompt, queued batch (_startPreparedPromptItems), plus steer/followUp now call these with explicit policies (e.g. session-command parsing only on prompt, not on steer/followUp).

Tests: agent-session-action-contracts.test.ts pins those contracts (command parsing scope, input-handler order before queueing, nextTurn vs triggerTurn, restore bypassing handlers). Agent test documents that a batched prompt([m1, m2]) can leave only a prefix committed if a listener throws mid-batch.

^{Reviewed by Cursor Bugbot for commit 11a1f67. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 46d8cbf. Configure here.}

[alexzhang13]

I just added a few small changes to keep the behavior consistent with main.