feat(approvals): add pending action resolver contracts

Add generic accepted/rejected approval decision vocabulary and contract-only pending-action handler/resolver interfaces, with smoke coverage wired into the Composer test suite.

Author: chubes4

agents-api.php

@@ -41,6 +41,9 @@
 require_once AGENTS_API_PATH . 'src/Identity/MaterializedAgentIdentityStoreInterface.php';
 require_once AGENTS_API_PATH . 'src/Transcripts/ConversationTranscriptStoreInterface.php';
 require_once AGENTS_API_PATH . 'src/Approvals/PendingActionStoreInterface.php';
+require_once AGENTS_API_PATH . 'src/Approvals/ApprovalDecision.php';
+require_once AGENTS_API_PATH . 'src/Approvals/PendingActionHandlerInterface.php';
+require_once AGENTS_API_PATH . 'src/Approvals/PendingActionResolverInterface.php';
 require_once AGENTS_API_PATH . 'src/Runtime/AgentMessageEnvelope.php';
 require_once AGENTS_API_PATH . 'src/Runtime/AgentExecutionPrincipal.php';
 require_once AGENTS_API_PATH . 'src/Runtime/AgentCompactionItem.php';

composer.json

@@ -19,6 +19,7 @@
       "php tests/action-policy-values-smoke.php",
       "php tests/tool-runtime-smoke.php",
       "php tests/pending-action-store-contract-smoke.php",
+      "php tests/approval-resolver-contract-smoke.php",
       "php tests/identity-smoke.php",
       "php tests/compaction-item-smoke.php",
       "php tests/conversation-runner-contracts-smoke.php",

src/Approvals/ApprovalDecision.php

@@ -0,0 +1,73 @@
+<?php
+/**
+ * Generic pending-action approval decision.
+ *
+ * @package AgentsAPI
+ */
+
+namespace AgentsAPI\AI\Approvals;
+
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Immutable accept/reject decision for a pending action.
+ */
+final class ApprovalDecision {
+
+	public const ACCEPTED = 'accepted';
+	public const REJECTED = 'rejected';
+
+	/** @var string Normalized decision value. */
+	private string $value;
+
+	/**
+	 * @param string $value Decision value.
+	 */
+	private function __construct( string $value ) {
+		if ( ! in_array( $value, array( self::ACCEPTED, self::REJECTED ), true ) ) {
+			throw new \InvalidArgumentException( 'Approval decision must be accepted or rejected.' );
+		}
+
+		$this->value = $value;
+	}
+
+	/** @return self Accepted decision. */
+	public static function accepted(): self {
+		return new self( self::ACCEPTED );
+	}
+
+	/** @return self Rejected decision. */
+	public static function rejected(): self {
+		return new self( self::REJECTED );
+	}
+
+	/**
+	 * Build a decision from a stored or request value.
+	 *
+	 * @param string $value Decision value.
+	 * @return self
+	 */
+	public static function from_string( string $value ): self {
+		return new self( $value );
+	}
+
+	/** @return bool Whether the pending action was accepted. */
+	public function is_accepted(): bool {
+		return self::ACCEPTED === $this->value;
+	}
+
+	/** @return bool Whether the pending action was rejected. */
+	public function is_rejected(): bool {
+		return self::REJECTED === $this->value;
+	}
+
+	/** @return string Normalized decision value. */
+	public function value(): string {
+		return $this->value;
+	}
+
+	/** @return string Normalized decision value. */
+	public function __toString(): string {
+		return $this->value;
+	}
+}

src/Approvals/PendingActionHandlerInterface.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * Generic pending-action handler contract.
+ *
+ * @package AgentsAPI
+ */
+
+namespace AgentsAPI\AI\Approvals;
+
+defined( 'ABSPATH' ) || exit;
+
+interface PendingActionHandlerInterface {
+
+	/**
+	 * Resolve a stored pending action with a caller-provided decision.
+	 *
+	 * The apply input is the implementation-owned data captured when the action
+	 * was queued. The payload is fresh resolver input supplied with the decision.
+	 * Permission checks, persistence, and transport concerns stay with callers.
+	 *
+	 * @param ApprovalDecision $decision    Accepted/rejected decision.
+	 * @param array            $apply_input Stored apply input for the pending action.
+	 * @param array            $payload     Fresh resolver payload supplied with the decision.
+	 * @param array            $context     Optional caller context.
+	 * @return mixed Generic implementation result.
+	 */
+	public function handle_pending_action( ApprovalDecision $decision, array $apply_input, array $payload = array(), array $context = array() ): mixed;
+}

src/Approvals/PendingActionResolverInterface.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * Generic pending-action resolver contract.
+ *
+ * @package AgentsAPI
+ */
+
+namespace AgentsAPI\AI\Approvals;
+
+defined( 'ABSPATH' ) || exit;
+
+interface PendingActionResolverInterface {
+
+	/**
+	 * Resolve a pending action by identifier.
+	 *
+	 * Implementations own lookup and persistence. Callers own authentication and
+	 * authorization before invoking the resolver.
+	 *
+	 * @param string           $pending_action_id Stable pending-action identifier.
+	 * @param ApprovalDecision $decision          Accepted/rejected decision.
+	 * @param array            $payload           Fresh resolver payload supplied with the decision.
+	 * @param array            $context           Optional caller context.
+	 * @return mixed Generic resolver result.
+	 */
+	public function resolve_pending_action( string $pending_action_id, ApprovalDecision $decision, array $payload = array(), array $context = array() ): mixed;
+}

tests/approval-resolver-contract-smoke.php

@@ -0,0 +1,86 @@
+<?php
+/**
+ * Pure-PHP smoke test for pending-action approval resolver contracts.
+ *
+ * Run with: php tests/approval-resolver-contract-smoke.php
+ *
+ * @package AgentsAPI\Tests
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	define( 'ABSPATH', __DIR__ . '/' );
+}
+
+$failures = array();
+$passes   = 0;
+
+echo "agents-api-approval-resolver-contract-smoke\n";
+
+require_once __DIR__ . '/agents-api-smoke-helpers.php';
+agents_api_smoke_require_module();
+
+$accepted = AgentsAPI\AI\Approvals\ApprovalDecision::accepted();
+$rejected = AgentsAPI\AI\Approvals\ApprovalDecision::from_string( AgentsAPI\AI\Approvals\ApprovalDecision::REJECTED );
+
+agents_api_smoke_assert_equals( 'accepted', AgentsAPI\AI\Approvals\ApprovalDecision::ACCEPTED, 'accepted vocabulary is stable', $failures, $passes );
+agents_api_smoke_assert_equals( 'rejected', AgentsAPI\AI\Approvals\ApprovalDecision::REJECTED, 'rejected vocabulary is stable', $failures, $passes );
+agents_api_smoke_assert_equals( 'accepted', $accepted->value(), 'accepted decision exposes normalized value', $failures, $passes );
+agents_api_smoke_assert_equals( true, $accepted->is_accepted(), 'accepted decision reports accepted', $failures, $passes );
+agents_api_smoke_assert_equals( false, $accepted->is_rejected(), 'accepted decision does not report rejected', $failures, $passes );
+agents_api_smoke_assert_equals( 'rejected', (string) $rejected, 'rejected decision stringifies to normalized value', $failures, $passes );
+agents_api_smoke_assert_equals( true, $rejected->is_rejected(), 'rejected decision reports rejected', $failures, $passes );
+
+$handler = new class() implements AgentsAPI\AI\Approvals\PendingActionHandlerInterface {
+	public function handle_pending_action( AgentsAPI\AI\Approvals\ApprovalDecision $decision, array $apply_input, array $payload = array(), array $context = array() ): mixed {
+		return array(
+			'decision' => $decision->value(),
+			'target'   => $apply_input['target'] ?? null,
+			'reason'   => $payload['reason'] ?? null,
+			'actor'    => $context['actor'] ?? null,
+		);
+	}
+};
+
+$handled = $handler->handle_pending_action(
+	$accepted,
+	array( 'target' => 'diff-123' ),
+	array( 'reason' => 'looks-good' ),
+	array( 'actor' => 'reviewer' )
+);
+
+agents_api_smoke_assert_equals( 'accepted', $handled['decision'], 'handler receives decision object', $failures, $passes );
+agents_api_smoke_assert_equals( 'diff-123', $handled['target'], 'handler receives stored apply input', $failures, $passes );
+agents_api_smoke_assert_equals( 'looks-good', $handled['reason'], 'handler receives resolver payload', $failures, $passes );
+agents_api_smoke_assert_equals( 'reviewer', $handled['actor'], 'handler receives optional context', $failures, $passes );
+
+$resolver = new class( $handler ) implements AgentsAPI\AI\Approvals\PendingActionResolverInterface {
+	public function __construct( private AgentsAPI\AI\Approvals\PendingActionHandlerInterface $handler ) {}
+
+	public function resolve_pending_action( string $pending_action_id, AgentsAPI\AI\Approvals\ApprovalDecision $decision, array $payload = array(), array $context = array() ): mixed {
+		return $this->handler->handle_pending_action(
+			$decision,
+			array( 'target' => $pending_action_id ),
+			$payload,
+			$context
+		);
+	}
+};
+
+$resolved = $resolver->resolve_pending_action(
+	'diff-456',
+	AgentsAPI\AI\Approvals\ApprovalDecision::rejected(),
+	array( 'reason' => 'needs-work' )
+);
+
+agents_api_smoke_assert_equals( 'rejected', $resolved['decision'], 'resolver receives rejected decision', $failures, $passes );
+agents_api_smoke_assert_equals( 'diff-456', $resolved['target'], 'resolver maps pending action id to stored input', $failures, $passes );
+agents_api_smoke_assert_equals( 'needs-work', $resolved['reason'], 'resolver forwards payload to handler', $failures, $passes );
+
+try {
+	AgentsAPI\AI\Approvals\ApprovalDecision::from_string( 'approved' );
+	agents_api_smoke_assert_equals( true, false, 'unknown decision is rejected', $failures, $passes );
+} catch ( InvalidArgumentException $e ) {
+	agents_api_smoke_assert_equals( true, str_contains( $e->getMessage(), 'accepted or rejected' ), 'unknown decision is rejected', $failures, $passes );
+}
+
+agents_api_smoke_finish( 'Agents API approval resolver contract', $failures, $passes );