feat: add canonical conversation session read-state ability
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 48/100
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.
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.phpregisters list/get/create/update-title/delete only.src/Transcripts/class-wp-agent-conversation-store.phpdocumentslast_read_atin the canonical row but says read-state is outside the transcript store contract.- The built-in CPT store persists
_agents_api_last_read_atbut 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-readscoped 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_atand unread projection when the store supplies one.
- Dominant language
- PHP
- Stars
- 33
- Forks
- 8
- Avg merge
- 1h 39m
- Merged PRs (30d)
- 30
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from Automattic/agents-api
-
enhancement
Difficulty 4/5 3-5 days Newbie friendliness 45/100
Automattic/agents-api#552 ·
-
enhancement
Difficulty 5/5 Over a week Newbie friendliness 45/100
Automattic/agents-api#551 ·
-
enhancement
Difficulty 4/5 3-5 days Newbie friendliness 68/100
Automattic/agents-api#550 ·
-
enhancement
Difficulty 5/5 Over a week Newbie friendliness 45/100
Automattic/agents-api#549 ·
-
Difficulty 5/5 Over a week Newbie friendliness 28/100
Automattic/agents-api#529 ·
All issues in Automattic/agents-api
Similar issues
-
priority: p3
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
googleapis/librarian#7636 ·
-
0. Needs triage bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
nextcloud/fulltextsearch#1011 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
phpstan/phpstan-doctrine#794 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
Automattic/static-site-importer#1767 ·