fix(runtime): group parallel tool calls into one summarizer assistant message

[UncertaintyDeterminesYou4ndMe]

Summary

Fixes #3030.

replayPlanItemsToModelMessages mapped every tool_call replay item to its own assistant message, so a step with parallel tool calls produced

assistant [tool-call A]
assistant [tool-call B]   ← rejected: A's tool_calls not yet answered
tool      [tool-result A]
tool      [tool-result B]

Strict OpenAI-compatible providers 400 on that shape, so mid-turn history compaction could never succeed on such providers — the provider_error fail-open loop that preceded the #3029 incident.

What changed: grouping is step-based with results buffered to the step boundary, mirroring the step-merge invariant the primary replay path gets from the materializer (model-history.ts). Membership follows the stamped stepId when both sides carry one; legacy items without a stepId join while the open step still has unsettled calls, and a call arriving after the open step fully settled opens its own message. Results for calls in the open step are deferred and emitted in arrival order at the step boundary, so interleaved orderings like call A, call B, result A, call C, result B, result C materialize as assistant [A, B, C] → tool A → tool B → tool C. Skipped thinking items do not break a step. The primary replay path is untouched.

Verification

• Regression tests: parallel calls produce exactly one assistant message with the tool-call parts followed by the tool messages; the interleaved ordering from the primary materializer's fixture; distinct settled steps never merged; stamped step ids deciding membership over settledness.
• Full @maka/runtime suite passes locally (re-verified after rebasing onto main past feat(runtime): add Codex server-side history compaction #2993).
• Cross-checked against the fix(runtime): history compaction accepts truncated/unstructured LLM summaries without validation #3029 incident repro by @me2seeks (review on this PR); the parallel draft in fix(runtime): validate history-compact summaries at the write gates (#3029) #3040 was withdrawn in favor of this fix.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code authored the fix, the tests, and this description under human direction and review; commits carry Generated-by: Claude Code trailers.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

Thanks for fixing the strict-provider failure at the shared summarizer replay seam. Grouping parallel calls here is the right direction, but the current grouping still ends too early when calls and results are interleaved.

The Runtime history can legitimately contain:

call A
call B
result A
call C
result B
result C

There is already a production-seam fixture for this ordering in ai-sdk-backend.test.ts (replays interleaved parallel RuntimeEvent tool calls as one provider tool-call block).

Because openToolCalls is cleared on the first result, this PR materializes that history as:

assistant [A, B]
tool [result A]
assistant [C]
tool [result B]
tool [result C]

A strict OpenAI-compatible provider can still reject this: the second assistant message appears before every call from the first assistant message has a result.

Could we keep the entire assistant step open and buffer its results until the step boundary, using stepId and the set of unsettled calls rather than adjacency alone? The cleanest long-term shape would be to share the primary replay materializer’s step-grouping invariant, so the summarizer does not maintain a second, weaker interpretation of the same history.

The new test is useful; extending it with the existing interleaved ordering, plus a case proving that different steps are not merged, should cover the missing behavior.

中文对照

感谢在共享的 summarizer replay 边界修复严格 provider 的失败问题。在这里合并并行调用的方向是正确的，但当调用和结果交错出现时，当前分组仍会过早结束。

Runtime 历史可能合法地按以下顺序记录：

call A
call B
result A
call C
result B
result C

ai-sdk-backend.test.ts 已有命中生产调用链的测试覆盖这种顺序：replays interleaved parallel RuntimeEvent tool calls as one provider tool-call block。

由于代码在第一个 result 出现时就清空 openToolCalls，这个 PR 会把上述历史转换成：

assistant [A, B]
tool [result A]
assistant [C]
tool [result B]
tool [result C]

严格的 OpenAI-compatible provider 仍可能拒绝该序列，因为第一条 assistant message 中的全部调用得到结果前，第二条 assistant message 已经出现。

建议保持整个 assistant step 打开并缓存结果，使用 stepId 和尚未完成的调用集合判断边界，而不是仅依赖事件是否相邻。长期更干净的方案是复用 primary replay materializer 的 step grouping invariant，避免 summarizer 维护另一套更弱的历史解释。

新增测试是有价值的；建议加入现有的交错顺序，并补充不同 step 不应被合并的用例。

AI-assisted review disclosure: Codex helped inspect the diff and reproduce the message sequence. I reviewed the source, evidence, and severity and made the final judgment.

[UncertaintyDeterminesYou4ndMe]

Addressed in c9d7112. Grouping is now step-based with results buffered to the step boundary, as you suggested:

• Membership follows the stamped stepId when both sides carry one; legacy items without a stepId join while the open step still has unsettled calls — which is exactly the interleaving case — and a call arriving after the open step fully settled opens its own message.
• Results for calls in the open step are deferred and emitted in arrival order at the step boundary (text, a foreign result, a different step, or end of items), so the interleaved ordering materializes as assistant [A, B, C] → tool A → tool B → tool C.

Tests added per your list: the interleaved ordering from the primary materializer's fixture (call A, call B, result A, call C, result B, result C → one assistant block, results in order), distinct settled steps never merged, and stamped step ids deciding membership over settledness (same stepId joins across a settled boundary; a different stepId never merges).

Agreed the cleanest long-term shape is sharing the primary materializer's step-grouping invariant instead of a second interpretation here — that refactor (extracting the step merge out of the materializer's flush) felt out of proportion for this fix, so I kept it as a mirror with the same semantics and would follow up if you want the extraction.

Full @maka/runtime suite: 2835 pass.

[me2seeks]

Reviewed against the #3029 incident repro. Step-based grouping with results deferred to the step boundary is the correct invariant and strictly stronger than the adjacency-based draft we had in #3040 (which missed the interleaved-result ordering). The stamped-stepId / legacy-settledness membership logic matches the primary materializer. No blocking issues found.

One non-blocking observation: a cross-step call arriving while a previous step still has unsettled calls (with differing stamped stepIds) would flush the previous step's partial results and open a new assistant message. That ordering is already-malformed replay input that the primary path rejects as well, so it is out of scope for this fix.

FYI: we are removing our own #3030 fix from #3040 and deferring to this PR.

[UncertaintyDeterminesYou4ndMe]

Thanks for cross-checking against the incident repro and for deferring #3040's variant. Confirming your non-blocking observation matches what my probe pass found: a cross-step call with a differing stamped stepId arriving while the previous step is unsettled flushes the partial results and opens a new message — that input is already-malformed replay (the primary path rejects it too), and the pre-fix code produced an equally invalid shape for it, so it stays out of scope here.

Generated-by: Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c9871dd6-1398-4d0b-a832-6974c7cec656

📥 Commits

Reviewing files that changed from the base of the PR and between 9fbdc99 and 99ce715.

📒 Files selected for processing (2)

• packages/runtime/src/__tests__/history-compact-summarizer.test.ts
• packages/runtime/src/history-compact-summarizer.ts

Included review availability: Your plan includes up to 3 reviews per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Summary

This PR fixes history summarization for parallel tool calls. replayPlanItemsToModelMessages now groups tool calls from one assistant step into one assistant message. It emits each tool result as a following tool message. It also supports interleaved call and result ordering by buffering results until the step ends.

The primary replay path remains unchanged. This change extends the existing history summarization path instead of creating a parallel replay path.

The solution is coherent and targeted. stepId membership handles stamped items. Unsettled-call tracking preserves grouping for legacy items without stepId. Result buffering is necessary to support sequences such as call A, call B, result A, call C, result B, result C.

Regression tests cover parallel calls, interleaved calls, separate settled steps, stamped stepId values, and skipped thinking items. No source or public declarations require deletion or simplification based on the current diff.

The main risk is changed message grouping in summarized histories. This improves compatibility with strict OpenAI-compatible providers but may affect consumers that depend on the previous message shape. The full @maka/runtime suite passed with 2,835 tests. Required checks are otherwise unverified from the available evidence.

Review-relevant risks

The current diff changes user-visible model-message history behavior. Material changes in this area require independent human review under repository policy.

No public API, security, licensing, release, or governance effect was identified in the current diff.

The person performing the merge must review the final diff. A maintainer makes the final determination.

Walkthrough

The history summarizer now groups tool calls by assistant step, buffers related results, supports interleaved calls, and preserves separate legacy steps. Tests cover parallel calls, explicit step IDs, and result ordering.

Changes

Tool-call history grouping

Layer / File(s)	Summary
Step-aware replay grouping packages/runtime/src/history-compact-summarizer.ts	The replay logic groups calls by step ID or unsettled-call state, buffers results, flushes completed steps, and emits typed ToolCallPart values.
Tool-step grouping validation packages/runtime/src/__tests__/history-compact-summarizer.test.ts	Tests cover parallel calls, interleaved calls and results, sequential legacy steps, and explicit step ID grouping.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 99ce7

The change groups parallel tool calls into one assistant message so compacted histories remain acceptable to strict providers. It is localized and covered by regression tests, with no actionable merge-blocking risk remaining beyond normal checks.

Sequence Diagram(s)

sequenceDiagram
  participant PlanItems
  participant replayPlanItemsToModelMessages
  participant ModelMessages
  PlanItems->>replayPlanItemsToModelMessages: replay tool calls and results
  replayPlanItemsToModelMessages->>replayPlanItemsToModelMessages: group calls and buffer results
  replayPlanItemsToModelMessages->>ModelMessages: emit one assistant tool-call message
  replayPlanItemsToModelMessages->>ModelMessages: emit ordered tool-result messages

Loading

Possibly related PRs

• maka-agent/maka-agent#3040: Both changes modify tool-call grouping in history-compact-summarizer.ts.
• maka-agent/maka-agent#3049: This change extends its tool-call grouping logic with interleaved results and explicit step IDs.

Suggested reviewers: astro-han, m4n5ter, are404

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: grouping parallel tool calls into one summarizer assistant message.
Description check	✅ Passed	The description follows the template and documents the problem, implementation, verification, AI use, checklist, and behavior change.
Linked Issues check	✅ Passed	The changes satisfy issue #3030 by grouping parallel and interleaved tool calls, preserving tool results, leaving the primary replay path unchanged, and adding regression tests.
Out of Scope Changes check	✅ Passed	The implementation and tests remain within the scope of issue #3030 and the stated objectives.
Ai Use Disclosure	✅ Passed	The PR selects generative use, names Claude Code and its scope, and both introduced commits contain standalone Generated-by: Claude Code trailers.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[M4n5ter]

LGTM. I have manually reviewed the final diff and the validation evidence, and I approve this change.