Add conversation session abilities

agents-api.php

@@ -58,6 +58,7 @@
 require_once AGENTS_API_PATH . 'src/Identity/class-wp-agent-materialized-identity.php';
 require_once AGENTS_API_PATH . 'src/Identity/class-wp-agent-identity-store.php';
 require_once AGENTS_API_PATH . 'src/Transcripts/class-wp-agent-conversation-store.php';
+require_once AGENTS_API_PATH . 'src/Transcripts/class-wp-agent-conversation-sessions.php';
 require_once AGENTS_API_PATH . 'src/Transcripts/class-wp-agent-conversation-lock.php';
 require_once AGENTS_API_PATH . 'src/Transcripts/class-wp-agent-null-conversation-lock.php';
 require_once AGENTS_API_PATH . 'src/Approvals/class-wp-agent-pending-action-store.php';
@@ -72,6 +73,7 @@
 require_once AGENTS_API_PATH . 'src/Consent/class-wp-agent-default-consent-policy.php';
 require_once AGENTS_API_PATH . 'src/Runtime/class-wp-agent-message.php';
 require_once AGENTS_API_PATH . 'src/Runtime/class-wp-agent-execution-principal.php';
+require_once AGENTS_API_PATH . 'src/Transcripts/register-agents-conversation-session-abilities.php';
 require_once AGENTS_API_PATH . 'src/Runtime/class-wp-agent-effective-agent-resolver.php';
 require_once AGENTS_API_PATH . 'src/Runtime/class-wp-agent-compaction-item.php';
 require_once AGENTS_API_PATH . 'src/Runtime/class-wp-agent-compaction-conservation.php';

composer.json

@@ -24,6 +24,7 @@
       "php tests/caller-context-smoke.php",
       "php tests/authorization-smoke.php",
       "php tests/agents-access-ability-smoke.php",
+      "php tests/agents-conversation-session-abilities-smoke.php",
       "php tests/action-policy-values-smoke.php",
       "php tests/consent-policy-smoke.php",
       "php tests/tool-policy-contracts-smoke.php",

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

@@ -0,0 +1,34 @@
+<?php
+/**
+ * Host-store discovery for generic conversation sessions.
+ *
+ * @package AgentsAPI
+ */
+
+namespace AgentsAPI\Core\Database\Chat;
+
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Resolves the host-provided conversation transcript/session store.
+ */
+final class WP_Agent_Conversation_Sessions {
+
+	/**
+	 * Resolve the host-provided conversation store.
+	 *
+	 * Host plugins can pass a store directly in `$context['conversation_store']`
+	 * or provide one through the `wp_agent_conversation_store` filter.
+	 *
+	 * @param array<string,mixed> $context Host-owned request context.
+	 * @return WP_Agent_Conversation_Store|null
+	 */
+	public static function get_store( array $context = array() ): ?WP_Agent_Conversation_Store {
+		if ( isset( $context['conversation_store'] ) && $context['conversation_store'] instanceof WP_Agent_Conversation_Store ) {
+			return $context['conversation_store'];
+		}
+
+		$store = function_exists( 'apply_filters' ) ? apply_filters( 'wp_agent_conversation_store', null, $context ) : null;
+		return $store instanceof WP_Agent_Conversation_Store ? $store : null;
+	}
+}

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

@@ -36,6 +36,22 @@ interface WP_Agent_Conversation_Store {
 	 */
 	public function create_session( WP_Agent_Workspace_Scope $workspace, int $user_id, string $agent_slug = '', array $metadata = array(), string $context = 'chat' ): string;
 
+	/**
+	 * List transcript sessions for one workspace/user pair.
+	 *
+	 * Implementations should return newest sessions first by default and honor the
+	 * `include_messages` arg. List callers pass `include_messages => false` by
+	 * default so concrete stores can avoid loading full transcript payloads.
+	 * Common filter/pagination keys are `limit`, `offset`, `agent_slug`, and
+	 * `context`.
+	 *
+	 * @param WP_Agent_Workspace_Scope $workspace Workspace owning the sessions.
+	 * @param int                      $user_id   WordPress user ID owning the sessions.
+	 * @param array                    $args      Optional host-supported filters/pagination.
+	 * @return array<int,array<string,mixed>> Session rows.
+	 */
+	public function list_sessions( WP_Agent_Workspace_Scope $workspace, int $user_id, array $args = array() ): array;
+
 	/**
 	 * Retrieve a transcript session by ID.
 	 *