feat(runtime): implement mid-turn guidance injection with continuation pass

[sunheyi6]

Summary

This feature allows users to inject new steering instructions while the AI is still generating a response — the model will persistently perceive the guidance across subsequent steps, and auto-trigger a follow-up generation if the guidance arrives after a text-only reply.

Key Changes

Runtime Core

• Switch pendingGuidance (one-shot) → injectedGuidance (persistent across steps)
• Add continuation pass loop — guidance arriving after text-only reply triggers a follow-up model call
• Expose injectGuidance() on RuntimeKernel and SessionManager
• Add onThinkingComplete callback to ModelAdapter
• Record guidance events to session store in real-time via agent-run.ts

Events

• Add guidance event type to events.ts

UI/Materialize

• materializeTurns supports multiple user/assistant messages per turn: first = prompt/answer, subsequent = steers / assistantFollowups
• Chat view renders guidance injection badges and follow-up responses
• Composer supports sending guidance mid-turn
• New MessageCircleQuestion icon for guidance indicators

Desktop Integration

• AppShell handles session-events for guidance, updates chat store
• IPC exposes injectGuidance channel via main/preload
• Composer CSS styles for guidance UI

Tests

• Added guidance tests for composer-helpers, materialize, session-manager
• Updated model-adapter and streaming-handoff test fixtures

Files Changed

25 files modified across 4 packages (core, runtime, ui, desktop)

[Astro-Han]

Approved. I like the shape of the mid-turn guidance path. I found a few follow-ups that I think are worth fixing, but I’m leaving this as an approval rather than a blocker.

• P2: The desktop renderer exposes sessions.injectGuidance, but AppShell does not pass onInjectGuidance into Composer. Because of that, the “Now” action in the queued composer path falls back to a normal send instead of steering the running turn. Wiring onInjectGuidance to window.maka.sessions.injectGuidance(activeId, text) should close the loop.
• P2: shellRunContextSummary no longer gets merged into the current user turn tail. The helper and input contract are still there, but send() now only uses resolveTurnTailPrompt(). Restoring the joinPromptFragments([turnTail, shellRunContextSummary]) path would keep live shell context visible to the model.
• P3: Guidance continuation calls are not counted in token_usage or recordLlmCall. That means the new follow-up generation path can underreport usage and cost. This can be handled either by accumulating continuation usage into the final usage event or by emitting separate usage for each continuation.

[Astro-Han]

Also rebase is needed!

[Astro-Han]

CI failed and need repair.

[jackwener]

Deep review done. The feature is worth having and the abort interplay + sessionSendChain serialization are solid, but there's one bug that blocks merge outright:

BLOCKER — guidance injected during a tool window corrupts next-turn replay (provider 400). The guidance event is appended to the ledger in stream order, so injecting while a tool is executing (or parked on a permission prompt — the single most natural moment to steer) lands it between function_call and function_response. On the next turn, materializeRuntimeReplayPlan hits the user-role guidance, flushes the pending calls via pushToolResults before the result has been iterated, and emits a tool_use with no matching tool_result → Anthropic 400, session wedged. Simplest fix: buffer guidance and append to the ledger only at the next step boundary (never between a call and its result); alternatively defer the user message in the replay materializer until buffered calls' results flush.

Also required:

• RuntimeKernel.injectGuidance fans out to every active child subagent sharing the sessionId — one steer click injects into the parent AND all running subagents (duplicate 引导已注入 rows, stray user messages in subagent transcripts). Target the top-level run only.
• The injection UI is unreachable exactly when steering matters most: during a permission park the status is waiting_for_user, isComposerResponseBusy says not-busy, so sends bypass injection and queue as a new turn. Treat waiting_for_user as busy for injection (after the blocker is fixed).
• Continuation passes drop token usage entirely (the :1252 comment concedes it) — every pass re-sends the full history uncounted. Accumulate totalUsage across passes into the turn's token_usage.
• guidanceConsumedCount is racy: a steer arriving during the last prepareStep's async body can be counted consumed without being delivered (and never triggers continuation). Track a monotonic delivered-index instead of a count both sides mutate.
• Test coverage doesn't touch any hard path: the only runtime test uses a fake backend yielding a canned guidance event. Need real-AiSdkBackend (mock model) tests for: mid-tool-step injection → well-formed next-turn replay (no orphan tool_use); text-only turn + late steer → exactly one continuation; loop termination under repeated injection; abort during continuation.

Minor: hasSteer keys on user-row count alone, so a steer consumed inline (no continuation) still fragments a normal multi-step answer into 引导跟进 blocks — distinguish steer-with-continuation from steer-consumed-inline. And please drop the cosmetic quote-style comment churn + BrowserPanelFallback block move from the diff.

The core idea and most of the plumbing are right — fix the ledger-ordering blocker and the fan-out, add the replay tests, and this merges.

[sunheyi6]

关闭原因 / Why this PR is being closed

This PR is superseded and closed in favour of #2222 — the same fix rebuilt on top of what upstream shipped since this PR was created.

Timeline:

• This PR (07-07) implemented mid-turn guidance with its own injectGuidance runtime (GuidanceEvent, buffered guidance events, sumNormalizedAiSdkUsage continuation accounting, …).
• Upstream merged feat: mid-turn steering and queued follow-up messages in the TUI #1087 / feat(runtime-host): establish message authority foundation #1357 (07-16): a mature, already-merged steering runtime — runtime.steer / sessions:steer, steering_message events with durable-consume ack, the <user_query> envelope, event-id dedupe, retract/queue semantics, TUI support.
• fix(desktop): mid-turn send opens a parallel root turn on the embedded runtime — should route through the steering queue #1954 (08-03) reported the exact bug this PR targeted, still present on Desktop: mid-turn sends open a parallel root turn on the embedded runtime instead of routing through the steering queue.

Why not rebase this PR: its runtime (injectGuidance, guidance events, continuation accounting) would duplicate the steering mechanism upstream already ships in #1087/#1357. The reviewer feedback on this PR (buffer guidance to step boundaries, no subagent fan-out, waiting_for_user treated as busy, real-backend tests) is fully addressed in #2222 — using the upstream steering queue instead of a second, parallel mechanism.

#2222 reuses the upstream steering queue and adds only what was missing:

• Desktop main sessions:send routes plain-text sends through runtime.steer (converged for chat/bot/voice/goal entrypoints), returning { ok, steered }.
• Live-transcript rendering of the injected steer at its step boundary (via the live turn projection), including a bounded same-turn continuation pass for steers that arrive while the model is streaming its final text.
• Composer queue UI (public Token chips, aligned to the input card width) with an immediate “立即发送” action and idle auto-drain.

Please direct further review/effort to #2222 (fixes #1954).