Automattic / Automattic/agents-api
feat: add canonical conversation session read-state ability
- Dominant language
- PHP
- Stars
- 33
- Forks
- 8
- Avg merge
- 1h 36m
- Merged PRs (30d)
- 31
Description
## Problem
Generic conversation-session clients can create, list, get, title, and delete principal-owned sessions through `agents/*` abilities, but cannot persist read state. The canonical session row exposes `last_read_at`, while `WP_Agent_Conversation_Store` explicitly excludes read-state mutation and no canonical ability owns it.
This leaves frontend adapters with two bad options: call a product-specific ability/store directly, violating layer purity, or return a successful mark-read response without persisting anything.
## Evidence
- `src/Transcripts/register-agents-conversation-session-abilities.php` registers list/get/create/update-title/delete only.
- `src/Transcripts/class-wp-agent-conversation-store.php` documents `last_read_at` in the canonical row but says read-state is outside the transcript store contract.
- The built-in CPT store persists `_agents_api_last_read_at` but exposes no generic mutation path.
- Automattic/frontend-agent-chat#123 needs workspace- and principal-scoped read-state behavior across the same lifecycle as the existing session abilities.
## Required contract
- Add an optional generic read-state capability for stores that own it, rather than forcing it into every transcript store.
- Add a canonical ability such as `agents/mark-conversation-session-read` scoped by the existing workspace and resolved principal/session owner semantics.
- Verify ownership and workspace exactly as get/update-title/delete do.
- Return a truthful result including whether state was persisted and the canonical `last_read_at`; unsupported stores must fail explicitly rather than report success.
- Keep storage and UI policy out of the substrate.
## Tests
- Create sessions with the same owner in two workspaces and prove marking one read cannot mutate or resolve the other workspace's session.
- Cover user and non-user principal owners through a principal-aware store.
- Cover unsupported stores with an explicit error.
- Confirm a subsequent get/list reflects the updated `last_read_at` and unread projection when the store supplies one.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with src/Transcripts/register-agents-conversation-session-abilities.php and src/Transcripts/class-wp-agent-conversation-store.php, then inspect the existing get, update-title, and delete ownership checks. Trace the built-in CPT store's _agents_api_last_read_at handling and the store contract. Done means workspace- and principal-scoped marking, explicit unsupported-store errors, and tests covering isolation, principal types, and updated get/list state.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100