Skip to content

feat(protocol): define missing rollout turn items#30282

Merged
owenlin0 merged 6 commits into
mainfrom
owen/add_projection_friendly_turn_items
Jun 26, 2026
Merged

feat(protocol): define missing rollout turn items#30282
owenlin0 merged 6 commits into
mainfrom
owen/add_projection_friendly_turn_items

Conversation

@owenlin0

@owenlin0 owenlin0 commented Jun 26, 2026

Copy link
Copy Markdown
Collaborator

Description

This PR adds canonical core TurnItem shapes for command execution, dynamic tool calls, collab agent tool calls, and sub-agent activity, to be stored in the rollout file soon.

It also teaches app-server protocol / ThreadHistoryBuilder how to render those items, and adds the small legacy fanout helpers needed for existing event-based consumers. No core producer or rollout persistence behavior changes here, that will be done in a followup.

Making ThreadHistoryBuilder stateless

This is the first PR in a stack to make ThreadHistoryBuilder stateless enough that we can materialize app-server ThreadItems from only a given slice of RolloutItem history, without ever needing to replay the whole thread from the beginning.

The persisted legacy RolloutItem::EventMsg records are mostly shaped like live UI events, not like materialized ThreadItems. They work if we replay the full rollout in order, but they often do not contain enough stable identity or complete item state to project an arbitrary suffix on its own.

A few examples:

  • UserMessageEvent and AgentMessageEvent have content, but historically do not carry the persisted app-server item ID that should become the SQLite primary key.
  • AgentReasoningEvent and AgentReasoningRawContentEvent are fragments. ThreadHistoryBuilder currently merges them into the last reasoning item, which means a slice starting in the middle of reasoning cannot know whether to append to an earlier item or create a new one.
  • WebSearchEndEvent, McpToolCallEndEvent, collab end events, and similar legacy events can often render a final-looking item, but they usually rely on prior replay state to know which turn owns the item.
  • Begin/end legacy events are partial views of one logical item. The builder correlates them by call_id and mutates prior state to synthesize the final ThreadItem.

That is the problem this direction fixes. A persisted canonical lifecycle record looks much closer to the read model we actually want later:

ItemCompletedEvent {
    turn_id,
    item: TurnItem { id, ...full snapshot... },
    completed_at_ms,
}

Once rollout has explicit turn_id, stable item.id, and a canonical completed item snapshot, the future SQLite projector can reduce only the new rollout suffix and upsert the affected thread_items rows. It no longer needs to synthesize item-N, infer item ownership from the active turn, or replay earlier events just to reconstruct the current item snapshot.

What changed

  • Added core TurnItem variants and item structs for command execution, dynamic tool calls, collab agent tool calls, and sub-agent activity.
  • Added conversions from those canonical items back into the legacy event shapes where current consumers still need them.
  • Added app-server v2 ThreadItem conversion for the new core item variants.
  • Taught ThreadHistoryBuilder and rollout persistence metrics to recognize the new item variants.

Follow-up

The next PR #30283 switches the live core producers for these item families onto canonical ItemStarted / ItemCompleted events.

owenlin0 added a commit that referenced this pull request Jun 26, 2026
@owenlin0 owenlin0 changed the title feat(protocol): add projection-friendly turn items feat(protocol): define missing rollout turn items Jun 26, 2026
@owenlin0 owenlin0 force-pushed the owen/add_projection_friendly_turn_items branch from 883f6f7 to 2d0b556 Compare June 26, 2026 21:22
@owenlin0 owenlin0 marked this pull request as ready for review June 26, 2026 21:22
@owenlin0 owenlin0 requested a review from wiltzius-openai June 26, 2026 21:22

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2d0b5567ff

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread codex-rs/app-server-protocol/src/protocol/thread_history.rs Outdated
Comment thread codex-rs/protocol/src/items.rs
Comment thread codex-rs/protocol/src/items.rs
@wiltzius-openai

Copy link
Copy Markdown
Contributor

Need to consider how to modify the rollout persistence policy for these new types

@owenlin0 owenlin0 force-pushed the owen/add_projection_friendly_turn_items branch from 4304fa3 to d2d5882 Compare June 26, 2026 23:16
@owenlin0 owenlin0 enabled auto-merge (squash) June 26, 2026 23:22
@owenlin0 owenlin0 requested a review from a team as a code owner June 26, 2026 23:31
@owenlin0 owenlin0 merged commit a107b84 into main Jun 26, 2026
35 checks passed
@owenlin0 owenlin0 deleted the owen/add_projection_friendly_turn_items branch June 26, 2026 23:44
@github-actions github-actions Bot locked and limited conversation to collaborators Jun 26, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants