diff --git a/docs/default-stores-companion.md b/docs/default-stores-companion.md index e38a11d..6f7c263 100644 --- a/docs/default-stores-companion.md +++ b/docs/default-stores-companion.md @@ -1,9 +1,38 @@ # Default Stores Companion Proposal -Issue: https://github.com/Automattic/agents-api/issues/78 +Issues: https://github.com/Automattic/agents-api/issues/78, https://github.com/Automattic/agents-api/issues/235 `agents-api` remains the canonical substrate for contracts, value objects, and provider-neutral runtime seams. Concrete persistence policy belongs outside this repository unless the policy itself becomes a generic contract. +## Decision (resolves #235) + +#235 reopened the question of whether canonical should ship a default conversation +session store so that zero-store installs work out of the box. The decision is to +keep that store in **this companion package, not canonical**: + +- Canonical is on the WordPress core landing path (#77). A default CPT session store + in canonical would become a session post type that core ships to every site — a + much larger imposition than a Composer-required companion, and likely a core-review + blocker. The companion never carries that liability. +- The posts-table-bloat concern (Data Machine generating large post volumes) only + applies to consumers that do not override `wp_agent_conversation_store`. High-volume + adopters override and never touch the default; the remaining audience is low-volume + experiments for which a CPT is appropriate. +- The reference implementation already exists in + [`lezama/openclawp`](https://github.com/lezama/openclawp/blob/main/includes/class-openclawp-conversation-store.php) + (CPT + postmeta, `WP_Agent_Conversation_Store` + `WP_Agent_Conversation_Lock`). The + companion's CPT transcript store is an extraction + generalization of it, not a + from-scratch design. + +Canonical's contribution to the cold-start experience is limited to a more actionable +`agents_conversation_session_no_store` error that points at this companion. The error +code is unchanged. + +Note: openclawp's store is **user-keyed only**. The generalized companion store must +additionally implement `WP_Agent_Principal_Conversation_Store` so non-user principals +(audience/token) do not require a custom backend on day one; the legacy int-user +methods delegate to the `_for_owner` variants. + ## Boundary | Stays in `Automattic/agents-api` | Belongs in the companion package | diff --git a/src/Transcripts/register-agents-conversation-session-abilities.php b/src/Transcripts/register-agents-conversation-session-abilities.php index 3c8451b..f127b51 100644 --- a/src/Transcripts/register-agents-conversation-session-abilities.php +++ b/src/Transcripts/register-agents-conversation-session-abilities.php @@ -281,7 +281,7 @@ function agents_conversation_sessions_context( array $input ) { $store = WP_Agent_Conversation_Sessions::get_store( array( 'principal' => $principal ) + $input ); if ( ! $store instanceof WP_Agent_Conversation_Store ) { - return new \WP_Error( 'agents_conversation_session_no_store', 'No WP_Agent_Conversation_Store is registered. Provide one with the wp_agent_conversation_store filter.' ); + return new \WP_Error( 'agents_conversation_session_no_store', 'No conversation store is registered. Install the wordpress/agents-api-default-stores companion for a zero-config WordPress-native store, or register your own with the wp_agent_conversation_store filter.' ); } if ( ! $store instanceof WP_Agent_Principal_Conversation_Store && WP_Agent_Execution_Principal::OWNER_TYPE_USER !== $owner['type'] ) {