agents-api/src/Runtime/class-wp-agent-runtime-tool-request-store.php at main · Automattic/agents-api · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
<?php
/**
 * External runtime tool request store interface.
 *
 * @package AgentsAPI
 */

namespace AgentsAPI\AI;

defined( 'ABSPATH' ) || exit;

/**
 * Host-provided persistence boundary for pending runtime tool requests.
 */
interface WP_Agent_Runtime_Tool_Request_Store {

	/**
	 * Create or replace a pending runtime tool request.
	 *
	 * @param array<string, mixed> $request Normalized runtime tool request.
	 */
	public function create( array $request ): void;

	/**
	 * Read a runtime tool request by id.
	 *
	 * Stores may retain terminal records after completion or timeout. Completed
	 * records that can expose the prior submitted result should keep that
	 * normalized result under `result` so duplicate submissions can return the
	 * original completion without overwriting it.
	 *
	 * @param string $request_id Runtime tool request id.
	 * @return array<string, mixed>|null Normalized request or null when absent.
	 */
	public function get( string $request_id ): ?array;

	/**
	 * Mark a pending request complete with a client-submitted result.
	 *
	 * Implementations should transition only pending records. Duplicate
	 * completions for terminal records must leave existing store data unchanged.
	 *
	 * @param string               $request_id Runtime tool request id.
	 * @param array<string, mixed> $result Normalized runtime tool result.
	 */
	public function complete( string $request_id, array $result ): void;

	/**
	 * Mark a pending request timed out.
	 *
	 * Implementations should transition only pending records.
	 *
	 * @param string $request_id Runtime tool request id.
	 */
	public function timeout( string $request_id ): void;

	/**
	 * Return recent pending requests for timeout scans or client polling.
	 *
	 * Implementations own concrete filtering semantics, but should support
	 * product-neutral query keys such as `run_id`, `tool_name`, `before`, and
	 * `limit` when they are meaningful for the host store.
	 *
	 * @param array<string, mixed> $query Product-neutral query hints.
	 * @return array<int, array<string, mixed>> Normalized pending requests.
	 */
	public function recent_pending( array $query = array() ): array;
}

/**
 * Atomic terminal-transition capability for exact-once lifecycle operations.
 *
 * Hosts using submit, timeout, or cancel must implement this additive contract.
 * The legacy store interface remains load-compatible for create and read paths.
 */
interface WP_Agent_Runtime_Tool_Request_Atomic_Store extends WP_Agent_Runtime_Tool_Request_Store {

	/**
	 * Conditionally transition a pending request to a terminal status.
	 *
	 * Implementations must use a compare-and-set write and return `true` only for
	 * the caller that changed the pending record. Completed transitions must retain
	 * the normalized result under `result` for duplicate resolution.
	 *
	 * @param string                    $request_id Runtime tool request id.
	 * @param string                    $status Target terminal request status.
	 * @param array<string, mixed>|null $result Normalized completion result, when completing.
	 * @return bool True when this call transitioned the pending record.
	 */
	public function transition_pending( string $request_id, string $status, ?array $result = null ): bool;
}