Use agent slugs in conversation store contract (#120)

Author: chubes4

README.md

@@ -382,6 +382,8 @@ $scope = new AgentsAPI\Core\FilesRepository\WP_Agent_Memory_Scope(
 
 Transcript sessions are also workspace-stamped. `WP_Agent_Conversation_Store::create_session()` and `::get_recent_pending_session()` both receive an `WP_Agent_Workspace_Scope`, and `WP_Agent_Conversation_Request` can carry a workspace so runtime persisters can stamp the session they materialize.
 
+Transcript sessions use registered agent slugs for runtime agent identity. `WP_Agent_Conversation_Store::create_session()` accepts `string $agent_slug = ''`, matching `wp_register_agent()` / `wp_get_agent()`. Concrete stores that materialize agents as posts can keep post IDs internally, but generic session arrays expose `agent_slug` rather than requiring a WordPress post ID.
+
 Transcript stores preserve provider continuity metadata as part of the complete session state. `WP_Agent_Conversation_Store::update_session()` accepts an optional opaque `provider_response_id`, and `::get_session()` returns the same key alongside `provider` and `model`. Consumers using provider-side state, such as the OpenAI Responses API `previous_response_id` flow, can pass the provider's response ID through this field without encoding per-consumer metadata keys. A `null` value means no provider-side response ID is associated with the current transcript state.
 
 ## Retrieved Context Authority

docs/default-stores-companion.md

@@ -68,7 +68,7 @@ The class names above are placeholders for the companion repository. They are no
 
 - Implements `AgentsAPI\Core\Database\Chat\WP_Agent_Conversation_Store`.
 - Stores transcript sessions in a companion-owned CPT or table chosen by the companion.
-- Preserves `WP_Agent_Workspace_Scope`, `user_id`, `agent_id`, title, metadata, provider, model, `provider_response_id`, timestamps, and pending-session dedup fields from the contract.
+- Preserves `WP_Agent_Workspace_Scope`, `user_id`, `agent_slug`, title, metadata, provider, model, `provider_response_id`, timestamps, and pending-session dedup fields from the contract.
 - Leaves chat UI listing, read state, retention scheduling, and analytics outside the generic store unless a future contract promotes them.
 
 ## Interop Tests

src/Transcripts/class-wp-agent-conversation-store.php

@@ -19,53 +19,31 @@
 
 interface WP_Agent_Conversation_Store {
 
-	/**
-	 * Convention key for storing the agent's registered slug inside session
-	 * `metadata`.
-	 *
-	 * Agents are slug-keyed in this substrate (`wp_register_agent`,
-	 * `wp_get_agent`, `wp_has_agent` all take strings) but the conversation
-	 * store contract carries `int $agent_id`. Until the contract is widened
-	 * to a string identifier, callers that registered an agent via
-	 * `wp_register_agent` should mirror its slug into the session metadata
-	 * under this key so that downstream consumers can resolve the agent the
-	 * same way the registry does. The value is a `WP_Agent::get_slug()`
-	 * string; recommended reading path is
-	 * `$session['metadata'][ WP_Agent_Conversation_Store::META_KEY_AGENT_SLUG ]`.
-	 *
-	 * Tracking issue: https://github.com/Automattic/agents-api/issues/95
-	 */
-	public const META_KEY_AGENT_SLUG = 'agent_slug';
-
 	/**
 	 * Create a new conversation transcript session and return its ID.
 	 *
-	 * `$agent_id` is an opaque integer; consumers without an integer agent
-	 * identifier should pass `0` and mirror the slug into `$metadata` under
-	 * {@see self::META_KEY_AGENT_SLUG}. See #95 for context on the slug-vs-int gap.
+	 * `$agent_slug` is the registered agent slug used by `wp_register_agent()`,
+	 * `wp_get_agent()`, and related registry functions. Consumers that materialize
+	 * agents as posts may store post IDs in their concrete backend, but the generic
+	 * transcript contract keys runtime agent identity by slug.
 	 *
 	 * @param WP_Agent_Workspace_Scope $workspace Workspace owning the session.
 	 * @param int                      $user_id   WordPress user ID owning the session.
-	 * @param int                      $agent_id  Agent ID (0 = agent-less or slug-only session).
-	 * @param array                    $metadata  Arbitrary session metadata (JSON-serializable). When the
-	 *                                            session belongs to a slug-registered agent, callers should
-	 *                                            include `[ self::META_KEY_AGENT_SLUG => $slug ]`.
+	 * @param string                   $agent_slug Registered agent slug, or empty string for agent-less sessions.
+	 * @param array                    $metadata  Arbitrary session metadata (JSON-serializable).
 	 * @param string                   $context   Execution mode ('chat', 'pipeline', 'system').
 	 * @return string Session ID (UUIDv4), or empty string on failure.
 	 */
-	public function create_session( WP_Agent_Workspace_Scope $workspace, int $user_id, int $agent_id = 0, array $metadata = array(), string $context = 'chat' ): string;
+	public function create_session( WP_Agent_Workspace_Scope $workspace, int $user_id, string $agent_slug = '', array $metadata = array(), string $context = 'chat' ): string;
 
 	/**
 	 * Retrieve a transcript session by ID.
 	 *
 	 * Returns the session as an associative array with keys:
-	 * session_id, workspace_type, workspace_id, user_id, agent_id, title, messages (decoded array),
+	 * session_id, workspace_type, workspace_id, user_id, agent_slug, title, messages (decoded array),
 	 * metadata (decoded array), provider, model, provider_response_id, context/mode, created_at,
 	 * updated_at, last_read_at, expires_at.
 	 *
-	 * The agent slug, when present, lives at
-	 * `$session['metadata'][ self::META_KEY_AGENT_SLUG ]`.
-	 *
 	 * @param string $session_id Session UUID.
 	 * @return array|null Session data or null if not found.
 	 */
@@ -76,8 +54,7 @@ public function get_session( string $session_id ): ?array;
 	 *
 	 * @param string      $session_id           Session UUID.
 	 * @param array       $messages             Complete messages array (not a delta).
-	 * @param array       $metadata             Updated metadata. Slug-registered agents should keep
-	 *                                          the {@see self::META_KEY_AGENT_SLUG} entry in sync.
+	 * @param array       $metadata             Updated metadata.
 	 * @param string      $provider             Optional AI provider identifier.
 	 * @param string      $model                Optional AI model identifier.
 	 * @param string|null $provider_response_id Opaque provider-side response/state ID, or null when none.

tests/workspace-scope-smoke.php

@@ -86,6 +86,9 @@
 
 agents_api_smoke_assert_equals( 'workspace', $create_params[0]->getName(), 'create_session first parameter is workspace', $failures, $passes );
 agents_api_smoke_assert_equals( $workspace_class, $create_params[0]->getType()->getName(), 'create_session workspace parameter is typed', $failures, $passes );
+agents_api_smoke_assert_equals( 'agent_slug', $create_params[2]->getName(), 'create_session accepts registered agent slug', $failures, $passes );
+agents_api_smoke_assert_equals( 'string', $create_params[2]->getType()->getName(), 'create_session agent slug is string typed', $failures, $passes );
+agents_api_smoke_assert_equals( '', $create_params[2]->getDefaultValue(), 'create_session agent slug defaults to agent-less session', $failures, $passes );
 agents_api_smoke_assert_equals( 'provider_response_id', $update_params[5]->getName(), 'update_session accepts provider response ID', $failures, $passes );
 agents_api_smoke_assert_equals( true, $update_params[5]->allowsNull(), 'provider response ID can be null when no provider state exists', $failures, $passes );
 agents_api_smoke_assert_equals( 'workspace', $pending_params[0]->getName(), 'get_recent_pending_session first parameter is workspace', $failures, $passes );