Automattic / Automattic/agents-api

Stable item identity shared by run events and stored transcripts

Open
#551 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.