feat: add canonical conversation session read-state ability

Open
#448 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Quiet
Tech stack
php
Domain
api, backend

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.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.
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Automattic/agents-api

All issues in Automattic/agents-api

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.