Automattic / Automattic/agents-api
Stable item identity shared by run events and stored transcripts
- Dominant language
- PHP
- Stars
- 33
- Forks
- 8
- Avg merge
- 1h 36m
- Merged PRs (30d)
- 31
Description
## Problem
A streamed run event and the stored transcript entry it describes share no identifier. Run events carry an `id` minted by the run-control adapter. Transcript entries carry an optional `id` only when the source that built the envelope happened to supply one.
So a client that streams a reply, loses the connection, and reloads the transcript cannot tell which stored entries it already has. It either shows the assistant message twice or drops it. Today every consumer works around this with timestamps or text matching, which breaks on retries and on repeated tool calls.
## Evidence
- `src/Runtime/class-wp-agent-run-control.php` — `normalize_event()` emits `id`, `type`, `created_at`, `metadata`. Nothing points at the transcript entry the event is about.
- `src/Runtime/class-wp-agent-message.php` — `buildEnvelope()` copies `id`, `created_at`, `updated_at` from the source only when present, so message identity is optional and store-dependent.
- `src/Transcripts/class-wp-agent-conversation-store.php` persists entries with no contract tying a stored row back to the events emitted while it was produced.
## Required contract
- Define a canonical item id on the runtime message and tool-call value objects, stable for the life of that item and unique within the session.
- Carry the item id on every run event that reports progress for that item, so deltas, the final text, and the terminal event all agree.
- Carry it through the transcript store contract, so reloading the transcript returns the same id the stream used.
- Treat ids as opaque strings. The substrate does not dictate how a store mints them, only that it keeps them stable.
## Tests
- Output deltas and the final assistant entry for one reply all carry the same item id, and the stored transcript returns that id.
- A tool call and its result share one item id across events and transcript.
- Merging a replayed event page with a reloaded transcript produces no duplicate and no missing entry.
- A store that cannot mint stable ids fails explicitly instead of returning changing ids.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by tracing the event and transcript paths in src/Runtime/class-wp-agent-run-control.php, src/Runtime/class-wp-agent-message.php, and src/Transcripts/class-wp-agent-conversation-store.php. Use the listed contract tests as the acceptance criteria: the same opaque item id must survive deltas, final and terminal events, tool calls, replay merging, and transcript reloads, with unsupported stable-id stores failing explicitly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- backend, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100