From eb903a7058fb2e6b0712f7111113514ea91ad9a1 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:04:41 +0000 Subject: [PATCH 01/17] Declare the never return type on a throwing MCP test closure The Http::fake closure in the OAuth advertisement-probe test always throws, so it now declares never, matching upstream. The other closures and fixtures that upstream typed already declare native return types in Hypervel. Port laravel/mcp b82ad51d (direct commit) at 4cf6b4ea. Its follow-up styling commit 18d01aaf only imports stdClass for upstream's fixture return types, which Hypervel's fixtures don't need. Validation: the OAuth callback route tests pass. --- tests/Mcp/Feature/Client/OAuthCallbackRouteTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/Mcp/Feature/Client/OAuthCallbackRouteTest.php b/tests/Mcp/Feature/Client/OAuthCallbackRouteTest.php index 668479947..69c8a01b3 100644 --- a/tests/Mcp/Feature/Client/OAuthCallbackRouteTest.php +++ b/tests/Mcp/Feature/Client/OAuthCallbackRouteTest.php @@ -622,7 +622,7 @@ public function testReportsAnUnreachableResourceDuringTheAdvertisementProbeAsAnO { $this->withoutExceptionHandling(); Http::preventStrayRequests(); - Http::fake(['https://mcp.test/mcp' => fn () => throw new ConnectionException('Connection timed out')]); + Http::fake(['https://mcp.test/mcp' => fn (): never => throw new ConnectionException('Connection timed out')]); $this->registerGithubClient(); Mcp::oAuthRoutesFor('github', fn (): null => null); From f180f97968aabcabba6e24e562d8bd998f4ce136 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:05:05 +0000 Subject: [PATCH 02/17] Return protocol errors for malformed MCP requests and headers Malformed requests, params and header values now get precise JSON-RPC errors instead of internal errors, and stateless requests treat the removed lifecycle methods as unknown. - Headers (#391, #397): mismatch messages and the legacy version error show a header value that isn't printable as its base64 form, instead of substituting invalid UTF-8 in the response. Surrounding whitespace is ignored when comparing header values, and a legacy request's version header is checked against the versions the server supports. - Envelopes (#395): a body that isn't a JSON object is an Invalid Request. Objects and arrays both decode to PHP arrays, so the first non-whitespace character identifies an object; `{}` and objects with numeric member names are validated as requests. - Responses (#395): a result that can't be encoded is reported and answered with an internal error, which shows the encoder message only in debug mode. A streamed notification that can't be encoded is dropped. Errors without an ID take the request's ID. - Params (#395): `JsonRpcRequest::validate()` is added for custom JSON-RPC methods. Completion requests check their parameter shapes directly before resolving the reference: the validator skips type rules for blank strings, so upstream's rules let a blank `ref` or `context.arguments` reach typed parameters and fail with a TypeError. The other built-in handlers keep their direct checks. - Methods (#397): `initialize` and `ping` are not found on stateless requests, even when an application replaces their handlers; upstream checks the handler class instead of the method name. A missing resource's error data includes the requested URI. Port laravel/mcp #391, #395 and #397 at 4cf6b4ea. They change the same classes and tests, so they share this commit; #397's conformance harness changes are in the next commit. Validation: the MCP suite and the AI package's MCP tests pass; formatting and full static analysis pass. --- src/mcp/src/Server.php | 70 +++++-- .../src/Server/Methods/CompletionComplete.php | 43 ++--- src/mcp/src/Server/Methods/ReadResource.php | 2 +- .../Server/Middleware/ValidateMcpHeaders.php | 25 ++- src/mcp/src/Transport/JsonRpcRequest.php | 24 +++ .../Middleware/ValidateMcpHeadersTest.php | 175 +++++++++++++++--- tests/Mcp/Unit/Methods/CallToolTest.php | 4 +- .../Unit/Methods/CompletionCompleteTest.php | 55 ++++-- tests/Mcp/Unit/Methods/GetPromptTest.php | 4 +- tests/Mcp/Unit/Methods/ListPromptsTest.php | 37 ++++ .../Methods/ListResourceTemplatesTest.php | 37 ++++ tests/Mcp/Unit/Methods/ListResourcesTest.php | 37 ++++ tests/Mcp/Unit/Methods/ListToolsTest.php | 37 ++++ tests/Mcp/Unit/Methods/ReadResourceTest.php | 44 +++-- tests/Mcp/Unit/ServerTest.php | 174 ++++++++++++++++- .../Mcp/Unit/Transport/JsonRpcRequestTest.php | 31 +++- .../Unit/Transport/JsonRpcResponseTest.php | 4 +- 17 files changed, 676 insertions(+), 127 deletions(-) diff --git a/src/mcp/src/Server.php b/src/mcp/src/Server.php index 17fde4a62..c09cd63f0 100644 --- a/src/mcp/src/Server.php +++ b/src/mcp/src/Server.php @@ -226,8 +226,9 @@ public function handle(string $rawMessage): void throw new JsonRpcException('Parse error: Invalid JSON was received by the server.', ErrorCode::PARSE_ERROR->value); } - if (! is_array($jsonRequest) || array_is_list($jsonRequest)) { - throw new JsonRpcException('Invalid Request: The message must be an object.', ErrorCode::INVALID_REQUEST->value); + // JSON objects and arrays both decode to PHP arrays, so the first character identifies an object. + if ($rawMessage[strspn($rawMessage, " \t\n\r")] !== '{') { + throw new JsonRpcException('Invalid Request: The request must be a JSON object.', ErrorCode::INVALID_REQUEST->value); } $request = array_key_exists('id', $jsonRequest) @@ -240,15 +241,12 @@ public function handle(string $rawMessage): void $requestId = $request->id; $request->source = $rawMessage; - $legacy = $request->isLegacy(); - if (! $legacy) { + if (! $request->isLegacy()) { $this->validateProtocolMeta($request, $context); } - // Initialize and ping belong to the legacy protocol, even on a server supporting both eras. - if (! isset($this->methods[$request->method]) - || (! $legacy && in_array($request->method, ['initialize', 'ping'], true))) { + if (! $this->implementsMethod($request)) { throw new JsonRpcException( "The method [{$request->method}] was not found.", ErrorCode::METHOD_NOT_FOUND->value, @@ -273,6 +271,11 @@ protected function sendException(Throwable $exception, ServerContext $context, i if ($exception instanceof JsonRpcException) { $response = $exception->toJsonRpcResponse(); + + // The exception may omit the request ID, which the client needs to match the error. + if ($requestId !== null) { + $response->content['id'] ??= $requestId; + } } else { report($exception); @@ -287,18 +290,7 @@ protected function sendException(Throwable $exception, ServerContext $context, i ); } - try { - $this->send($response, $context); - } catch (JsonException $exception) { - report($exception); - - // Error data supplied by application code can also be unencodable. - $this->transport->send(JsonRpcResponse::error( - $requestId, - ErrorCode::INTERNAL_ERROR->value, - 'Something went wrong while processing the request.', - )->toJson()); - } + $this->send($response, $context); } /** @@ -376,6 +368,20 @@ protected function validateProtocolMeta(JsonRpcRequest $request, ServerContext $ } } + /** + * Determine whether the server implements the requested method. + */ + protected function implementsMethod(JsonRpcRequest $request): bool + { + if (! isset($this->methods[$request->method])) { + return false; + } + + // Unlike upstream, this checks the method name rather than its handler class. The stateless + // protocol removed initialize and ping by name, even when the application replaces their handlers. + return $request->isLegacy() || ! in_array($request->method, ['initialize', 'ping'], true); + } + /** * Invoke the method and deliver its eager or streamed response. * @@ -441,7 +447,31 @@ protected function send(JsonRpcResponse $response, ServerContext $context, ?Json ]; } - $this->transport->send($response->toJson()); + // A method may return an error without the request ID, which the client needs to match the error. + if ($request instanceof JsonRpcRequest && array_key_exists('error', $response->content)) { + $response->content['id'] ??= $request->id; + } + + try { + $message = $response->toJson(); + } catch (JsonException $jsonException) { + report($jsonException); + + // Dropping an unencodable notification lets a streamed request still deliver its result. + if (array_key_exists('method', $response->content)) { + return; + } + + $message = JsonRpcResponse::error( + $response->content['id'] ?? null, + ErrorCode::INTERNAL_ERROR->value, + Container::getInstance()->make(Repository::class)->boolean('app.debug') + ? $jsonException->getMessage() + : 'Something went wrong while processing the request.', + )->toJson(); + } + + $this->transport->send($message); } /** diff --git a/src/mcp/src/Server/Methods/CompletionComplete.php b/src/mcp/src/Server/Methods/CompletionComplete.php index 428390b61..682454cc7 100644 --- a/src/mcp/src/Server/Methods/CompletionComplete.php +++ b/src/mcp/src/Server/Methods/CompletionComplete.php @@ -52,8 +52,21 @@ public function handle(JsonRpcRequest $request, ServerContext $context): JsonRpc ); } - if (! is_array($ref) || ! is_array($argument)) { - throw new JsonRpcException('The [ref] and [argument] parameters must be objects.', -32602, $request->id); + // Unlike upstream, these checks do not use the validator. It skips type rules for blank + // strings, so a blank [ref] or [context.arguments] would reach the typed parameters below. + if (! is_array($ref) || ! is_string($ref['name'] ?? '') || ! is_string($ref['uri'] ?? '')) { + throw new JsonRpcException('The [ref] parameter must be an object with string [name] and [uri] members.', -32602, $request->id); + } + + if (! is_array($argument) || ! is_string($argument['name'] ?? '') || ! is_string(Arr::get($argument, 'value', ''))) { + throw new JsonRpcException('The [argument] parameter must be an object with string [name] and [value] members.', -32602, $request->id); + } + + $completionContext = $request->get('context', []); + $contextArguments = is_array($completionContext) ? Arr::get($completionContext, 'arguments', []) : null; + + if (! is_array($contextArguments) || ! array_all($contextArguments, fn (mixed $value): bool => is_string($value))) { + throw new JsonRpcException('The [context] parameter must be an object whose [arguments] member contains strings.', -32602, $request->id); } try { @@ -81,16 +94,6 @@ public function handle(JsonRpcRequest $request, ServerContext $context): JsonRpc ); } - if (! is_string($argumentName) || ! is_string($argumentValue)) { - throw new JsonRpcException('The argument [name] and [value] members must be strings.', -32602, $request->id); - } - - $completionContext = $request->get('context', []); - - if (! is_array($completionContext) || ! is_array($contextArguments = Arr::get($completionContext, 'arguments', []))) { - throw new JsonRpcException('The [context] and its [arguments] member must be objects.', -32602, $request->id); - } - try { $result = $this->invokeCompletion($primitive, $argumentName, $argumentValue, $contextArguments); } catch (Exception $exception) { @@ -113,21 +116,11 @@ public function handle(JsonRpcRequest $request, ServerContext $context): JsonRpc */ protected function resolvePrimitive(array $ref, ServerContext $context): Prompt|Resource|HasUriTemplate { - $type = Arr::get($ref, 'type'); - $key = match ($type) { - 'ref/prompt' => 'name', - 'ref/resource' => 'uri', + return match (Arr::get($ref, 'type')) { + 'ref/prompt' => $this->resolvePrompt(Arr::get($ref, 'name'), $context), + 'ref/resource' => $this->resolveResource(Arr::get($ref, 'uri'), $context), default => throw new InvalidArgumentException('Invalid reference type. Expected ref/prompt or ref/resource.'), }; - $name = Arr::get($ref, $key); - - if ($name !== null && ! is_string($name)) { - throw new InvalidArgumentException("The reference [{$key}] member must be a string."); - } - - return $type === 'ref/prompt' - ? $this->resolvePrompt($name, $context) - : $this->resolveResource($name, $context); } /** diff --git a/src/mcp/src/Server/Methods/ReadResource.php b/src/mcp/src/Server/Methods/ReadResource.php index 99cdb016c..37eab84a8 100644 --- a/src/mcp/src/Server/Methods/ReadResource.php +++ b/src/mcp/src/Server/Methods/ReadResource.php @@ -52,7 +52,7 @@ public function handle(JsonRpcRequest $request, ServerContext $context): Generat $invalidArgumentException->getMessage(), ErrorCode::INVALID_PARAMS->value, $request->id, - $uri === null || $uri === '' ? null : ['uri' => $uri], + is_string($uri) && $uri !== '' ? ['uri' => $uri] : null, ); } diff --git a/src/mcp/src/Server/Middleware/ValidateMcpHeaders.php b/src/mcp/src/Server/Middleware/ValidateMcpHeaders.php index 3e6369855..44b510ec6 100644 --- a/src/mcp/src/Server/Middleware/ValidateMcpHeaders.php +++ b/src/mcp/src/Server/Middleware/ValidateMcpHeaders.php @@ -8,7 +8,6 @@ use Hypervel\Http\Request; use Hypervel\Mcp\Enums\ErrorCode; use Hypervel\Mcp\Enums\MetaKey; -use Hypervel\Mcp\Enums\ProtocolHandshake; use Hypervel\Mcp\Enums\ProtocolVersion; use Hypervel\Mcp\Enums\RequestHeader; use Hypervel\Mcp\Transport\HeaderValue; @@ -55,7 +54,7 @@ public function handle(Request $request, Closure $next): Response 'code' => ErrorCode::HEADER_MISMATCH->value, 'message' => $mismatch, ], - ], 400, options: JSON_INVALID_UTF8_SUBSTITUTE); + ], 400); } /** @@ -72,7 +71,7 @@ protected function unsupportedLegacyVersion(Request $request, mixed $id): ?Respo return null; } - if (ProtocolVersion::tryFrom($version)?->handshake() === ProtocolHandshake::Discovery) { + if (in_array($version, ProtocolVersion::serverSupported(), true)) { return response()->json([ 'jsonrpc' => '2.0', 'id' => $id, @@ -80,7 +79,7 @@ protected function unsupportedLegacyVersion(Request $request, mixed $id): ?Respo 'code' => ErrorCode::INVALID_PARAMS->value, 'message' => 'Invalid params: The request [_meta] is missing the required [' . MetaKey::PROTOCOL_VERSION->value . '] member.', ], - ], 400, options: JSON_INVALID_UTF8_SUBSTITUTE); + ], 400); } return response()->json([ @@ -91,10 +90,10 @@ protected function unsupportedLegacyVersion(Request $request, mixed $id): ?Respo 'message' => 'Unsupported protocol version', 'data' => [ 'supported' => ProtocolVersion::initializeSupported(), - 'requested' => $version, + 'requested' => $this->printable(new HeaderValue($version)), ], ], - ], 400, options: JSON_INVALID_UTF8_SUBSTITUTE); + ], 400); } /** @@ -104,6 +103,10 @@ protected function mismatch(Request $request, RequestHeader $header, mixed $expe { $value = $request->header($header->value); + if (is_string($value)) { + $value = trim($value, " \t"); + } + if (! is_string($value) || $value === '') { return $required ? "Header mismatch: The [{$header->value}] header is required." : null; } @@ -116,6 +119,14 @@ protected function mismatch(Request $request, RequestHeader $header, mixed $expe return null; } - return "Header mismatch: The [{$header->value}] header value [{$headerValue->value}] does not match the request body value [{$expected}]."; + return "Header mismatch: The [{$header->value}] header value [{$this->printable($headerValue)}] does not match the request body value [{$expected}]."; + } + + /** + * Get a header value that is safe to show in an error message. + */ + protected function printable(HeaderValue $value): string + { + return preg_match('/\A\P{Cc}*\z/u', $value->value) === 1 ? $value->value : (string) $value; } } diff --git a/src/mcp/src/Transport/JsonRpcRequest.php b/src/mcp/src/Transport/JsonRpcRequest.php index cc10d8466..51c56b20a 100644 --- a/src/mcp/src/Transport/JsonRpcRequest.php +++ b/src/mcp/src/Transport/JsonRpcRequest.php @@ -4,10 +4,14 @@ namespace Hypervel\Mcp\Transport; +use Hypervel\Mcp\Enums\ErrorCode; use Hypervel\Mcp\Enums\MetaKey; use Hypervel\Mcp\Enums\RequestHeader; use Hypervel\Mcp\Exceptions\JsonRpcException; use Hypervel\Mcp\Request; +use Hypervel\Mcp\Support\ValidationMessages; +use Hypervel\Support\Facades\Validator; +use Hypervel\Validation\ValidationException; use stdClass; class JsonRpcRequest @@ -107,6 +111,26 @@ public function get(string $key, mixed $default = null): mixed return $this->params[$key] ?? $default; } + /** + * Validate the request parameters. + * + * Use this in custom JSON-RPC method handlers registered with Server::addMethod(). Tools, + * prompts and resources validate their arguments through Hypervel\Mcp\Request instead. + * + * @param array $rules + * @return array + * + * @throws JsonRpcException + */ + public function validate(array $rules): array + { + try { + return Validator::make($this->params, $rules)->validate(); + } catch (ValidationException $validationException) { + throw new JsonRpcException(ValidationMessages::from($validationException), ErrorCode::INVALID_PARAMS->value, $this->id); + } + } + /** * Get the request metadata. * diff --git a/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php b/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php index afbe341c2..2481bc75b 100644 --- a/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php +++ b/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php @@ -87,24 +87,63 @@ public function testRejectsAProtocolVersionHeaderThatContradictsTheBodyMeta(): v $this->assertSame(-32020, $response->json('error.code')); } - public function testInvalidHeaderBytesStillProduceAProtocolError(): void + #[DataProvider('requiredHeaders')] + public function testIgnoresWhitespaceSurroundingAHeaderValue(string $header): void { $message = callToolMessage(); + $headers = mcpHeaders($message); - $this->postJson('test-mcp', $message, [ - ...mcpHeaders($message), - 'Mcp-Name' => "invalid-\xFF", - ])->assertStatus(400) - ->assertJsonPath('id', $message['id']) - ->assertJsonPath('error.code', -32020) - ->assertJsonPath('error.message', "Header mismatch: The [Mcp-Name] header value [invalid-\u{FFFD}] does not match the request body value [{$message['params']['name']}]."); - - $this->postJson('test-mcp', ['jsonrpc' => '2.0', 'id' => 3, 'method' => 'tools/list'], [ - 'MCP-Protocol-Version' => "invalid-\xFF", - ])->assertStatus(400) - ->assertJsonPath('id', 3) - ->assertJsonPath('error.code', -32022) - ->assertJsonPath('error.data.requested', "invalid-\u{FFFD}"); + $headers[$header] = " \t{$headers[$header]} "; + + $response = $this->postJson('test-mcp', $message, $headers); + + $response->assertStatus(200); + } + + public function testRejectsARequestWithoutMetadataThatSendsAStatelessProtocolVersionHeader(): void + { + $message = ['jsonrpc' => '2.0', 'id' => 3, 'method' => 'server/discover', 'params' => []]; + + $response = $this->postJson('test-mcp', $message, mcpHeaders($message)); + + $response->assertStatus(400); + + $this->assertEquals([ + 'jsonrpc' => '2.0', + 'id' => 3, + 'error' => [ + 'code' => -32602, + 'message' => 'Invalid params: The request [_meta] is missing the required [io.modelcontextprotocol/protocolVersion] member.', + ], + ], $response->json()); + } + + #[DataProvider('removedLifecycleMethods')] + public function testAnswersTheRemovedLifecycleMethodsWithA404OnAStatelessRequest(string $method): void + { + $message = [ + 'jsonrpc' => '2.0', + 'id' => 9, + 'method' => $method, + 'params' => ['_meta' => protocolMeta()], + ]; + + $response = $this->postJson('test-mcp', $message, mcpHeaders($message)); + + $response->assertStatus(404); + + $this->assertEquals([ + 'code' => -32601, + 'message' => "The method [{$method}] was not found.", + ], $response->json('error')); + } + + /** + * Provide the legacy lifecycle methods removed from the stateless protocol. + */ + public static function removedLifecycleMethods(): array + { + return [['initialize'], ['ping']]; } #[DataProvider('invalidRequestIds')] @@ -146,6 +185,68 @@ public function testDecodesABase64SentinelNameHeaderBeforeComparingIt(): void $response->assertStatus(200); } + public function testRejectsABase64NameHeaderThatDecodesToInvalidUtf8(): void + { + $message = callToolMessage(); + + $response = $this->postJson('test-mcp', $message, [ + ...mcpHeaders($message), + 'Mcp-Name' => '=?base64?/w==?=', + ]); + + $response->assertStatus(400); + + $this->assertEquals([ + 'code' => -32020, + 'message' => "Header mismatch: The [Mcp-Name] header value [=?base64?/w==?=] does not match the request body value [{$message['params']['name']}].", + ], $response->json('error')); + } + + #[DataProvider('requiredHeaders')] + public function testRejectsAHeaderCarryingInvalidUtf8Bytes(string $header): void + { + $message = callToolMessage(); + + $response = $this->postJson('test-mcp', $message, [ + ...mcpHeaders($message), + $header => "\xFF", + ]); + + $response->assertStatus(400); + + $this->assertSame($message['id'], $response->json('id')); + $this->assertSame(-32020, $response->json('error.code')); + $this->assertStringContainsString('header value [=?base64?/w==?=]', $response->json('error.message')); + } + + public function testQuotesANonAsciiNameHeaderDecodedInTheMismatchMessage(): void + { + $message = callToolMessage(); + + $response = $this->postJson('test-mcp', $message, [ + ...mcpHeaders($message), + 'Mcp-Name' => '=?base64?SGVsbG8sIOS4lueVjA==?=', + ]); + + $response->assertStatus(400); + + $this->assertSame("Header mismatch: The [Mcp-Name] header value [Hello, 世界] does not match the request body value [{$message['params']['name']}].", $response->json('error.message')); + } + + public function testEncodesADecodedNameHeaderCarryingControlCharactersInTheMismatchMessage(): void + { + $message = callToolMessage(); + + $response = $this->postJson('test-mcp', $message, [ + ...mcpHeaders($message), + 'Mcp-Name' => '=?base64?' . base64_encode("a\nb") . '?=', + ]); + + $response->assertStatus(400); + + $this->assertSame('Header mismatch: The [Mcp-Name] header value [=?base64?' . base64_encode("a\nb") . "?=] does not match the request body value [{$message['params']['name']}].", $response->json('error.message')); + } + public function testDoesNotRequireANameHeaderForMethodsWithoutANamedTarget(): void { $message = listToolsMessage(); @@ -205,20 +306,19 @@ public function testRejectsMissingMetadataWhenTheRequestIdentifiesAModernProtoco } /** - * Provide modern-only methods and a method identified by its version header. + * Provide a modern-only method and a method identified by its version header. */ public static function missingMetadataMethods(): array { - return [['server/discover'], ['subscriptions/listen'], ['tools/list']]; + return [['subscriptions/listen'], ['tools/list']]; } - #[DataProvider('unsupportedModernMethods')] - public function testAnswersAnUnsupportedModernMethodWithA404(string $method): void + public function testAnswersAnUnknownMethodWithA404(): void { $message = [ 'jsonrpc' => '2.0', 'id' => 9, - 'method' => $method, + 'method' => 'unknown/method', 'params' => ['_meta' => protocolMeta()], ]; @@ -229,14 +329,6 @@ public function testAnswersAnUnsupportedModernMethodWithA404(string $method): vo $this->assertSame(-32601, $response->json('error.code')); } - /** - * Provide unknown methods and methods removed from the modern protocol. - */ - public static function unsupportedModernMethods(): array - { - return [['unknown/method'], ['initialize'], ['ping']]; - } - public function testRequiresTheProtocolVersionHeaderEvenWhenTheBodyOmitsTheMetaMember(): void { $message = listToolsMessage(); @@ -330,6 +422,28 @@ public function testAnswersALegacyRequestCarryingAnUnsupportedProtocolVersionHea ], $response->json()); } + public function testAnswersALegacyRequestCarryingAnInvalidUtf8ProtocolVersionHeaderWithA400(): void + { + $response = $this->postJson('test-mcp', ['jsonrpc' => '2.0', 'id' => 3, 'method' => 'tools/list', 'params' => []], [ + 'MCP-Protocol-Version' => "\xFF", + ]); + + $response->assertStatus(400); + + $this->assertEquals([ + 'jsonrpc' => '2.0', + 'id' => 3, + 'error' => [ + 'code' => -32022, + 'message' => 'Unsupported protocol version', + 'data' => [ + 'supported' => ['2025-11-25', '2025-06-18'], + 'requested' => '=?base64?/w==?=', + ], + ], + ], $response->json()); + } + public function testRequiresTheNameHeaderEvenWhenTheBodyCarriesNoUsableName(): void { $message = callToolMessage(); @@ -359,7 +473,10 @@ public function testDoesNotDecodeTheBase64SentinelOnHeadersOtherThanTheName(): v $response->assertStatus(400); - $this->assertSame(-32020, $response->json('error.code')); + $this->assertEquals([ + 'code' => -32020, + 'message' => 'Header mismatch: The [Mcp-Method] header value [=?base64?' . base64_encode('tools/call') . '?=] does not match the request body value [tools/call].', + ], $response->json('error')); } public function testAnswersAnInternalErrorWithA500(): void diff --git a/tests/Mcp/Unit/Methods/CallToolTest.php b/tests/Mcp/Unit/Methods/CallToolTest.php index 3786f28f0..10f19f4c6 100644 --- a/tests/Mcp/Unit/Methods/CallToolTest.php +++ b/tests/Mcp/Unit/Methods/CallToolTest.php @@ -1029,7 +1029,7 @@ public function testReturnsAResourceLinkContentBlockInTheWirePayload(): void } #[DataProvider('invalidNames')] - public function testRejectsNonStringToolNames(mixed $name): void + public function testRejectsAWronglyTypedNameParameter(mixed $name): void { $request = new JsonRpcRequest(42, 'tools/call', ['name' => $name]); @@ -1045,6 +1045,6 @@ public function testRejectsNonStringToolNames(mixed $name): void */ public static function invalidNames(): array { - return [[1], [[]], [false]]; + return ['array' => [['x']], 'int' => [1], 'empty array' => [[]], 'bool' => [false]]; } } diff --git a/tests/Mcp/Unit/Methods/CompletionCompleteTest.php b/tests/Mcp/Unit/Methods/CompletionCompleteTest.php index 1469e2d06..5ef811819 100644 --- a/tests/Mcp/Unit/Methods/CompletionCompleteTest.php +++ b/tests/Mcp/Unit/Methods/CompletionCompleteTest.php @@ -450,37 +450,58 @@ public function testPassesEmptyContextWhenContextIsNotProvided(): void $this->assertSame([], $this->app->make(CompletionMethodTestPrompt::class)->lastContext); } - #[DataProvider('invalidParameters')] - public function testRejectsMalformedParameters(array $overrides): void + #[DataProvider('wronglyTypedCompletionParams')] + public function testRejectsWronglyTypedCompletionParams(array $params, string $message): void { - $request = new JsonRpcRequest('1', 'completion/complete', array_replace([ - 'ref' => ['type' => 'ref/prompt', 'name' => 'completion-method-test-prompt'], - 'argument' => ['name' => 'test', 'value' => ''], - ], $overrides)); + $server = new CompletionMethodTestServer(new FakeTransporter); $this->expectException(JsonRpcException::class); $this->expectExceptionCode(-32602); + $this->expectExceptionMessage($message); - (new CompletionComplete)->handle($request, (new CompletionMethodTestServer(new FakeTransporter))->createContext()); + (new CompletionComplete)->handle(new JsonRpcRequest('1', 'completion/complete', $params), $server->createContext()); } /** - * Return invalid completion parameter shapes. + * Return wrongly typed completion parameters. */ - public static function invalidParameters(): array + public static function wronglyTypedCompletionParams(): array { return [ - 'reference scalar' => [['ref' => 'prompt']], - 'argument scalar' => [['argument' => 'test']], - 'prompt name' => [['ref' => ['type' => 'ref/prompt', 'name' => []]]], - 'resource URI' => [['ref' => ['type' => 'ref/resource', 'uri' => []]]], - 'argument name' => [['argument' => ['name' => []]]], - 'argument value' => [['argument' => ['name' => 'test', 'value' => []]]], - 'context scalar' => [['context' => 'invalid']], - 'context arguments' => [['context' => ['arguments' => 'invalid']]], + 'ref' => [['ref' => 'x', 'argument' => ['name' => 'a']], 'The [ref] parameter must be an object with string [name] and [uri] members.'], + 'argument' => [['ref' => ['type' => 'ref/prompt', 'name' => 'p'], 'argument' => 'x'], 'The [argument] parameter must be an object with string [name] and [value] members.'], + 'ref name' => [['ref' => ['type' => 'ref/prompt', 'name' => ['x']], 'argument' => ['name' => 'a']], 'The [ref] parameter must be an object with string [name] and [uri] members.'], + 'ref uri' => [['ref' => ['type' => 'ref/resource', 'uri' => 1], 'argument' => ['name' => 'a']], 'The [ref] parameter must be an object with string [name] and [uri] members.'], + 'argument name' => [['ref' => ['type' => 'ref/prompt', 'name' => 'p'], 'argument' => ['name' => 1]], 'The [argument] parameter must be an object with string [name] and [value] members.'], + 'argument value' => [['ref' => ['type' => 'ref/prompt', 'name' => 'p'], 'argument' => ['name' => 'a', 'value' => ['x']]], 'The [argument] parameter must be an object with string [name] and [value] members.'], + 'context' => [['ref' => ['type' => 'ref/prompt', 'name' => 'p'], 'argument' => ['name' => 'a'], 'context' => 'x'], 'The [context] parameter must be an object whose [arguments] member contains strings.'], + 'context arguments' => [['ref' => ['type' => 'ref/prompt', 'name' => 'p'], 'argument' => ['name' => 'a'], 'context' => ['arguments' => 'x']], 'The [context] parameter must be an object whose [arguments] member contains strings.'], + 'context argument value' => [['ref' => ['type' => 'ref/prompt', 'name' => 'p'], 'argument' => ['name' => 'a'], 'context' => ['arguments' => ['b' => ['x']]]], 'The [context] parameter must be an object whose [arguments] member contains strings.'], + 'blank ref' => [['ref' => ' ', 'argument' => ['name' => 'a']], 'The [ref] parameter must be an object with string [name] and [uri] members.'], + 'blank context arguments' => [['ref' => ['type' => 'ref/prompt', 'name' => 'p'], 'argument' => ['name' => 'a'], 'context' => ['arguments' => '']], 'The [context] parameter must be an object whose [arguments] member contains strings.'], ]; } + public function testRejectsWronglyTypedParamsForAPrimitiveWithoutCompletion(): void + { + $server = new class(new FakeTransporter) extends Server { + protected string $name = 'Test'; + + protected array $capabilities = ['completions' => []]; + + protected array $prompts = [NonCompletionPrompt::class]; + }; + + $this->expectException(JsonRpcException::class); + $this->expectExceptionCode(-32602); + $this->expectExceptionMessage('The [argument] parameter must be an object with string [name] and [value] members.'); + + (new CompletionComplete)->handle(new JsonRpcRequest('1', 'completion/complete', [ + 'ref' => ['type' => 'ref/prompt', 'name' => 'non-completion-prompt'], + 'argument' => ['name' => 'test', 'value' => ['x']], + ]), $server->createContext()); + } + #[TestWith([false], 'direct cancellation')] #[TestWith([true], 'wrapped cancellation')] public function testCancellationIsNotConvertedToAnEmptyCompletion(bool $wrapped): void diff --git a/tests/Mcp/Unit/Methods/GetPromptTest.php b/tests/Mcp/Unit/Methods/GetPromptTest.php index dfa62b018..3d5c139d8 100644 --- a/tests/Mcp/Unit/Methods/GetPromptTest.php +++ b/tests/Mcp/Unit/Methods/GetPromptTest.php @@ -404,7 +404,7 @@ public function handle(Request $request): Response } #[DataProvider('invalidNames')] - public function testRejectsNonStringPromptNames(mixed $name): void + public function testRejectsAWronglyTypedNameParameter(mixed $name): void { $request = new JsonRpcRequest(42, 'prompts/get', ['name' => $name]); @@ -420,6 +420,6 @@ public function testRejectsNonStringPromptNames(mixed $name): void */ public static function invalidNames(): array { - return [[1], [[]], [false]]; + return ['array' => [['x']], 'int' => [1], 'empty array' => [[]], 'bool' => [false]]; } } diff --git a/tests/Mcp/Unit/Methods/ListPromptsTest.php b/tests/Mcp/Unit/Methods/ListPromptsTest.php index 04a6b7797..06dbc79b4 100644 --- a/tests/Mcp/Unit/Methods/ListPromptsTest.php +++ b/tests/Mcp/Unit/Methods/ListPromptsTest.php @@ -5,6 +5,7 @@ namespace Hypervel\Tests\Mcp\Unit\Methods; use Hypervel\Context\CoroutineContext; +use Hypervel\Mcp\Exceptions\JsonRpcException; use Hypervel\Mcp\Request; use Hypervel\Mcp\Schema\Implementation; use Hypervel\Mcp\Server\Methods\ListPrompts; @@ -13,6 +14,7 @@ use Hypervel\Mcp\Transport\JsonRpcResponse; use Hypervel\Tests\Mcp\Fixtures\ReviewMyCodePrompt; use Hypervel\Tests\Mcp\TestCase; +use PHPUnit\Framework\Attributes\DataProvider; class ListPromptsTest extends TestCase { @@ -173,4 +175,39 @@ public function shouldRegister(Request $request): bool 'prompts' => [], ], $payload['result']); } + + #[DataProvider('wronglyTypedPaginationParams')] + public function testRejectsWronglyTypedPaginationParams(array $params, string $message): void + { + $context = new ServerContext( + supportedProtocolVersions: ['2025-03-26'], + serverCapabilities: [], + implementation: new Implementation('Test Server', '1.0.0'), + instructions: 'Test instructions', + maxPaginationLength: 50, + defaultPaginationLength: 10, + tools: [], + resources: [], + prompts: [], + ); + + $this->expectException(JsonRpcException::class); + $this->expectExceptionMessage($message); + + (new ListPrompts)->handle(new JsonRpcRequest(1, 'prompts/list', $params), $context); + } + + /** + * Provide wrongly typed pagination params. + */ + public static function wronglyTypedPaginationParams(): array + { + return [ + 'cursor as int' => [['cursor' => 1], 'Invalid params: The [cursor] member must be a string.'], + 'cursor as array' => [['cursor' => ['x']], 'Invalid params: The [cursor] member must be a string.'], + 'per_page as string' => [['per_page' => '10'], 'Invalid params: The [per_page] member must be a positive integer.'], + 'per_page as zero' => [['per_page' => 0], 'Invalid params: The [per_page] member must be a positive integer.'], + 'per_page as negative' => [['per_page' => -1], 'Invalid params: The [per_page] member must be a positive integer.'], + ]; + } } diff --git a/tests/Mcp/Unit/Methods/ListResourceTemplatesTest.php b/tests/Mcp/Unit/Methods/ListResourceTemplatesTest.php index ab29a2396..8956e2fb1 100644 --- a/tests/Mcp/Unit/Methods/ListResourceTemplatesTest.php +++ b/tests/Mcp/Unit/Methods/ListResourceTemplatesTest.php @@ -4,6 +4,7 @@ namespace Hypervel\Tests\Mcp\Unit\Methods; +use Hypervel\Mcp\Exceptions\JsonRpcException; use Hypervel\Mcp\Request; use Hypervel\Mcp\Response; use Hypervel\Mcp\Schema\Implementation; @@ -14,6 +15,7 @@ use Hypervel\Mcp\Support\UriTemplate; use Hypervel\Mcp\Transport\JsonRpcRequest; use Hypervel\Tests\Mcp\TestCase; +use PHPUnit\Framework\Attributes\DataProvider; class ListResourceTemplatesTest extends TestCase { @@ -183,4 +185,39 @@ public function handle(Request $request): Response $this->assertSame('file://users/{id}/data', $template['uriTemplate']); $this->assertSame('application/json', $template['mimeType']); } + + #[DataProvider('wronglyTypedPaginationParams')] + public function testRejectsWronglyTypedPaginationParams(array $params, string $message): void + { + $context = new ServerContext( + supportedProtocolVersions: ['2025-03-26'], + serverCapabilities: [], + implementation: new Implementation('Test Server', '1.0.0'), + instructions: 'Test instructions', + maxPaginationLength: 50, + defaultPaginationLength: 10, + tools: [], + resources: [], + prompts: [], + ); + + $this->expectException(JsonRpcException::class); + $this->expectExceptionMessage($message); + + (new ListResourceTemplates)->handle(new JsonRpcRequest(1, 'resources/templates/list', $params), $context); + } + + /** + * Provide wrongly typed pagination params. + */ + public static function wronglyTypedPaginationParams(): array + { + return [ + 'cursor as int' => [['cursor' => 1], 'Invalid params: The [cursor] member must be a string.'], + 'cursor as array' => [['cursor' => ['x']], 'Invalid params: The [cursor] member must be a string.'], + 'per_page as string' => [['per_page' => '10'], 'Invalid params: The [per_page] member must be a positive integer.'], + 'per_page as zero' => [['per_page' => 0], 'Invalid params: The [per_page] member must be a positive integer.'], + 'per_page as negative' => [['per_page' => -1], 'Invalid params: The [per_page] member must be a positive integer.'], + ]; + } } diff --git a/tests/Mcp/Unit/Methods/ListResourcesTest.php b/tests/Mcp/Unit/Methods/ListResourcesTest.php index 9ca773425..67d8b7264 100644 --- a/tests/Mcp/Unit/Methods/ListResourcesTest.php +++ b/tests/Mcp/Unit/Methods/ListResourcesTest.php @@ -6,6 +6,7 @@ use Hypervel\Context\CoroutineContext; use Hypervel\Mcp\Enums\Role; +use Hypervel\Mcp\Exceptions\JsonRpcException; use Hypervel\Mcp\Request; use Hypervel\Mcp\Response; use Hypervel\Mcp\Schema\Implementation; @@ -20,6 +21,7 @@ use Hypervel\Mcp\Transport\JsonRpcRequest; use Hypervel\Mcp\Transport\JsonRpcResponse; use Hypervel\Tests\Mcp\TestCase; +use PHPUnit\Framework\Attributes\DataProvider; class ListResourcesTest extends TestCase { @@ -363,4 +365,39 @@ public function handle(Request $request): Response $this->assertSame($staticResource->name(), $payload['result']['resources'][0]['name']); $this->assertSame($staticResource->uri(), $payload['result']['resources'][0]['uri']); } + + #[DataProvider('wronglyTypedPaginationParams')] + public function testRejectsWronglyTypedPaginationParams(array $params, string $message): void + { + $context = new ServerContext( + supportedProtocolVersions: ['2025-03-26'], + serverCapabilities: [], + implementation: new Implementation('Test Server', '1.0.0'), + instructions: 'Test instructions', + maxPaginationLength: 50, + defaultPaginationLength: 10, + tools: [], + resources: [], + prompts: [], + ); + + $this->expectException(JsonRpcException::class); + $this->expectExceptionMessage($message); + + (new ListResources)->handle(new JsonRpcRequest(1, 'resources/list', $params), $context); + } + + /** + * Provide wrongly typed pagination params. + */ + public static function wronglyTypedPaginationParams(): array + { + return [ + 'cursor as int' => [['cursor' => 1], 'Invalid params: The [cursor] member must be a string.'], + 'cursor as array' => [['cursor' => ['x']], 'Invalid params: The [cursor] member must be a string.'], + 'per_page as string' => [['per_page' => '10'], 'Invalid params: The [per_page] member must be a positive integer.'], + 'per_page as zero' => [['per_page' => 0], 'Invalid params: The [per_page] member must be a positive integer.'], + 'per_page as negative' => [['per_page' => -1], 'Invalid params: The [per_page] member must be a positive integer.'], + ]; + } } diff --git a/tests/Mcp/Unit/Methods/ListToolsTest.php b/tests/Mcp/Unit/Methods/ListToolsTest.php index 68c7cd7f1..b80a23f02 100644 --- a/tests/Mcp/Unit/Methods/ListToolsTest.php +++ b/tests/Mcp/Unit/Methods/ListToolsTest.php @@ -6,6 +6,7 @@ use Hypervel\Context\CoroutineContext; use Hypervel\Contracts\JsonSchema\JsonSchema; +use Hypervel\Mcp\Exceptions\JsonRpcException; use Hypervel\Mcp\Request; use Hypervel\Mcp\Schema\Implementation; use Hypervel\Mcp\Server\Methods\ListTools; @@ -18,6 +19,7 @@ use Hypervel\Tests\Mcp\Fixtures\ToolWithoutOutputSchema; use Hypervel\Tests\Mcp\Fixtures\ToolWithOutputSchema; use Hypervel\Tests\Mcp\TestCase; +use PHPUnit\Framework\Attributes\DataProvider; class ListToolsTest extends TestCase { @@ -564,6 +566,41 @@ public function testListsToolsInADeterministicOrderMatchingDeclarationOrder(): v $this->assertSame($declarationOrder, [...$pageOne, ...$pageTwo]); } + #[DataProvider('wronglyTypedPaginationParams')] + public function testRejectsWronglyTypedPaginationParams(array $params, string $message): void + { + $context = new ServerContext( + supportedProtocolVersions: ['2025-03-26'], + serverCapabilities: [], + implementation: new Implementation('Test Server', '1.0.0'), + instructions: 'Test instructions', + maxPaginationLength: 50, + defaultPaginationLength: 10, + tools: [], + resources: [], + prompts: [], + ); + + $this->expectException(JsonRpcException::class); + $this->expectExceptionMessage($message); + + (new ListTools)->handle(new JsonRpcRequest(1, 'tools/list', $params), $context); + } + + /** + * Provide wrongly typed pagination params. + */ + public static function wronglyTypedPaginationParams(): array + { + return [ + 'cursor as int' => [['cursor' => 1], 'Invalid params: The [cursor] member must be a string.'], + 'cursor as array' => [['cursor' => ['x']], 'Invalid params: The [cursor] member must be a string.'], + 'per_page as string' => [['per_page' => '10'], 'Invalid params: The [per_page] member must be a positive integer.'], + 'per_page as zero' => [['per_page' => 0], 'Invalid params: The [per_page] member must be a positive integer.'], + 'per_page as negative' => [['per_page' => -1], 'Invalid params: The [per_page] member must be a positive integer.'], + ]; + } + /** * Create distinct tools for pagination. * diff --git a/tests/Mcp/Unit/Methods/ReadResourceTest.php b/tests/Mcp/Unit/Methods/ReadResourceTest.php index af7dfc3e5..05eaf293b 100644 --- a/tests/Mcp/Unit/Methods/ReadResourceTest.php +++ b/tests/Mcp/Unit/Methods/ReadResourceTest.php @@ -82,13 +82,7 @@ public function testThrowsErrorWhenUriIsMissing(): void params: [] // intentionally omitting 'uri' ); - try { - $readResource->handle($jsonRpcRequest, $context); - } catch (JsonRpcException $exception) { - $this->assertNull($exception->data()); - - throw $exception; - } + $readResource->handle($jsonRpcRequest, $context); } public function testThrowsExceptionWhenResourceIsNotFound(): void @@ -105,12 +99,36 @@ public function testThrowsExceptionWhenResourceIsNotFound(): void params: ['uri' => 'file://resources/non-existent'] ); + $readResource->handle($jsonRpcRequest, $context); + } + + public function testIncludesTheRequestedUriInTheNotFoundErrorData(): void + { + $jsonRpcRequest = new JsonRpcRequest( + id: 1, + method: 'resources/read', + params: ['uri' => 'file://resources/non-existent'] + ); + try { - $readResource->handle($jsonRpcRequest, $context); - } catch (JsonRpcException $exception) { - $this->assertSame(['uri' => 'file://resources/non-existent'], $exception->data()); + (new ReadResource)->handle($jsonRpcRequest, $this->getServerContext()); + + $this->fail('Expected a JsonRpcException.'); + } catch (JsonRpcException $jsonRpcException) { + $this->assertSame(['uri' => 'file://resources/non-existent'], $jsonRpcException->data()); + } + } + + public function testOmitsTheErrorDataWhenTheUriIsMissing(): void + { + $jsonRpcRequest = new JsonRpcRequest(id: 1, method: 'resources/read', params: []); - throw $exception; + try { + (new ReadResource)->handle($jsonRpcRequest, $this->getServerContext()); + + $this->fail('Expected a JsonRpcException.'); + } catch (JsonRpcException $jsonRpcException) { + $this->assertNull($jsonRpcException->data()); } } @@ -922,7 +940,7 @@ public static function consecutiveResourceUris(): array } #[DataProvider('invalidUris')] - public function testRejectsNonStringUris(mixed $uri): void + public function testRejectsAWronglyTypedUriParameter(mixed $uri): void { $request = new JsonRpcRequest(42, 'resources/read', ['uri' => $uri]); @@ -938,6 +956,6 @@ public function testRejectsNonStringUris(mixed $uri): void */ public static function invalidUris(): array { - return [[1], [[]], [false]]; + return ['array' => [['x']], 'int' => [1], 'empty array' => [[]], 'bool' => [false]]; } } diff --git a/tests/Mcp/Unit/ServerTest.php b/tests/Mcp/Unit/ServerTest.php index 787116ec2..44bac3561 100644 --- a/tests/Mcp/Unit/ServerTest.php +++ b/tests/Mcp/Unit/ServerTest.php @@ -17,10 +17,12 @@ use Hypervel\Mcp\Server\ServerContext; use Hypervel\Mcp\Transport\JsonRpcRequest; use Hypervel\Mcp\Transport\JsonRpcResponse; +use Hypervel\Support\Facades\Exceptions; use Hypervel\Tests\Mcp\Fixtures\ArrayTransport; use Hypervel\Tests\Mcp\Fixtures\CustomMethodHandler; use Hypervel\Tests\Mcp\Fixtures\ExampleServer; use Hypervel\Tests\Mcp\TestCase; +use JsonException; use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\Attributes\TestWith; use RuntimeException; @@ -580,6 +582,15 @@ public function testLetsAddMethodOverrideTheBuiltInInitializeHandler(): void $response = json_decode((string) $transport->sent[0], true); $this->assertSame('Custom method executed successfully!', $response['result']['message']); + + ($transport->handler)(json_encode([ + 'jsonrpc' => '2.0', + 'id' => 457, + 'method' => 'initialize', + 'params' => ['_meta' => protocolMeta()], + ])); + + $this->assertSame(-32601, json_decode((string) $transport->sent[1], true)['error']['code']); } public function testDiscoversAnEmptyCapabilitySetAsAJsonObject(): void @@ -788,23 +799,165 @@ public function testMergesIconAttributesWithIconsMethodOutput(): void $this->assertSame('https://example.com/from-method.png', $context->implementation->icons[1]->src); } - #[DataProvider('invalidEnvelopes')] - public function testRejectsNonObjectEnvelopesAsInvalidRequests(string $payload): void + public function testRejectsWronglyTypedParamsAsInvalidParamsWithoutReporting(): void { + config(['app.debug' => true]); + Exceptions::fake(); + $transport = new ArrayTransport; $server = new ExampleServer($transport); - $server->handle($payload); - $response = json_decode($transport->sent[0], true); - $this->assertSame(-32600, $response['error']['code']); + $server->start(); + + ($transport->handler)(json_encode([ + 'jsonrpc' => '2.0', + 'id' => 1, + 'method' => 'tools/call', + 'params' => ['name' => ['x'], '_meta' => protocolMeta()], + ])); + + $this->assertSame([ + 'jsonrpc' => '2.0', + 'id' => 1, + 'error' => [ + 'code' => -32602, + 'message' => 'The [name] parameter must be a string.', + ], + ], json_decode((string) $transport->sent[0], true)); + + Exceptions::assertNothingReported(); + } + + #[DataProvider('nonObjectRequestBodies')] + public function testRejectsARequestBodyThatIsNotAJsonObject(string $body): void + { + config(['app.debug' => true]); + Exceptions::fake(); + + $transport = new ArrayTransport; + $server = new ExampleServer($transport); + + $server->start(); + + ($transport->handler)($body); + + $this->assertSame([ + 'jsonrpc' => '2.0', + 'error' => [ + 'code' => -32600, + 'message' => 'Invalid Request: The request must be a JSON object.', + ], + ], json_decode((string) $transport->sent[0], true)); + + Exceptions::assertNothingReported(); } /** * Supply valid JSON values that are not request objects. */ - public static function invalidEnvelopes(): array + public static function nonObjectRequestBodies(): array { - return [['null'], ['true'], ['5'], ['"text"'], ['[]'], ['[{"jsonrpc":"2.0","id":1,"method":"ping"}]']]; + return [['null'], ['1'], ['"string"'], ['true'], ['[1]'], ['[{"jsonrpc":"2.0","id":1,"method":"ping"}]'], [" \n[] "]]; + } + + #[TestWith([' {} '], 'empty object')] + #[TestWith(['{"0":"ping"}'], 'numeric member names')] + public function testValidatesTheMembersOfARequestObjectThatDecodesToAList(string $rawMessage): void + { + $transport = new ArrayTransport; + $server = new ExampleServer($transport); + + $server->handle($rawMessage); + + $this->assertSame([ + 'jsonrpc' => '2.0', + 'error' => [ + 'code' => -32600, + 'message' => 'Invalid Request: Invalid JSON-RPC version. Must be "2.0".', + ], + ], json_decode((string) $transport->sent[0], true)); + } + + #[DataProvider('unencodableResults')] + public function testRespondsWithAnInternalErrorWhenTheResultCannotBeEncoded(bool $debug, string $message): void + { + config(['app.debug' => $debug]); + Exceptions::fake(); + + $transport = new ArrayTransport; + $server = new ExampleServer($transport); + $server->addMethod('test/failure', TerminalFailureMethod::class); + $this->app->instance(TerminalFailureMethod::class, new TerminalFailureMethod(false, 'encoding')); + + $server->start(); + + ($transport->handler)(json_encode([ + 'jsonrpc' => '2.0', + 'id' => 999, + 'method' => 'test/failure', + 'params' => ['_meta' => protocolMeta()], + ])); + + $this->assertSame([ + 'jsonrpc' => '2.0', + 'id' => 999, + 'error' => [ + 'code' => -32603, + 'message' => $message, + ], + ], json_decode((string) $transport->sent[0], true)); + + Exceptions::assertReported(JsonException::class); + } + + /** + * Supply the debug modes for an unencodable result. + */ + public static function unencodableResults(): array + { + // Upstream's invalid UTF-8 rows do not apply: Hypervel responses replace invalid UTF-8 instead of failing. + return [ + 'nan' => [false, 'Something went wrong while processing the request.'], + 'nan in debug' => [true, 'Inf and NaN cannot be JSON encoded'], + ]; + } + + public function testDropsAStreamedNotificationThatCannotBeEncodedAndStillSendsTheResult(): void + { + Exceptions::fake(); + + $transport = new ArrayTransport; + $server = new ExampleServer($transport); + $server->addMethod('test/method', CustomMethodHandler::class); + + $this->app->bind(CustomMethodHandler::class, fn (): Method => new class implements Method { + /** + * Stream an unencodable notification before the result. + */ + public function handle(JsonRpcRequest $request, ServerContext $context): iterable + { + yield JsonRpcResponse::notification('notifications/progress', ['progress' => NAN]); + yield JsonRpcResponse::result($request->id, ['value' => 'ok']); + } + }); + + $server->start(); + + ($transport->handler)(json_encode([ + 'jsonrpc' => '2.0', + 'id' => 999, + 'method' => 'test/method', + 'params' => ['_meta' => protocolMeta()], + ])); + + $this->assertCount(1, $transport->sent); + + $response = json_decode((string) $transport->sent[0], true); + + $this->assertSame(999, $response['id']); + $this->assertSame('ok', $response['result']['value']); + + Exceptions::assertReported(JsonException::class); } #[DataProvider('terminalFailures')] @@ -834,13 +987,15 @@ public function testEncodesTerminalFailuresFromEagerAndLazyMethods(bool $streami public static function terminalFailures(): array { return [ - [false, 'encoding', -32603], [true, 'encoding', -32603], [false, 'protocol', -32602], [true, 'protocol', -32602], [false, 'error-data', -32603], [true, 'error-data', -32603], [true, 'ordinary', -32603], + [false, 'unidentified-protocol', -32602], + [true, 'unidentified-error-data', -32603], + [false, 'returned-error-data', -32603], ]; } @@ -944,6 +1099,9 @@ private function result(JsonRpcRequest $request): JsonRpcResponse 'protocol' => throw new JsonRpcException('Invalid argument', -32602, $request->id), 'error-data' => throw new JsonRpcException('Invalid argument', -32602, $request->id, ['value' => NAN]), 'ordinary' => throw new Exception('Failed after progress'), + 'unidentified-protocol' => throw new JsonRpcException('Invalid argument', -32602), + 'unidentified-error-data' => throw new JsonRpcException('Invalid argument', -32602, data: ['value' => NAN]), + 'returned-error-data' => JsonRpcResponse::error(null, -32602, 'Invalid argument', ['value' => NAN]), }; } } diff --git a/tests/Mcp/Unit/Transport/JsonRpcRequestTest.php b/tests/Mcp/Unit/Transport/JsonRpcRequestTest.php index 69ce5dd9a..c1190e8cf 100644 --- a/tests/Mcp/Unit/Transport/JsonRpcRequestTest.php +++ b/tests/Mcp/Unit/Transport/JsonRpcRequestTest.php @@ -6,7 +6,7 @@ use Hypervel\Mcp\Exceptions\JsonRpcException; use Hypervel\Mcp\Transport\JsonRpcRequest; -use Hypervel\Tests\TestCase; +use Hypervel\Tests\Mcp\TestCase; use JsonException; use PHPUnit\Framework\Attributes\DataProvider; @@ -324,6 +324,35 @@ public function testOmitsTheNameHeaderWhenTheBodyCarriesNoUsableName(): void $this->assertNull($request->name()); } + public function testValidatesParamsAndReturnsTheValidatedData(): void + { + $request = new JsonRpcRequest(1, 'tools/list', ['cursor' => 'abc']); + + $this->assertSame(['cursor' => 'abc'], $request->validate(['cursor' => ['nullable', 'string']])); + } + + public function testThrowsInvalidParamsCarryingTheRequestIdWhenValidationFails(): void + { + $request = new JsonRpcRequest(7, 'tools/list', ['cursor' => 1]); + + try { + $request->validate(['cursor' => ['nullable', 'string']]); + } catch (JsonRpcException $jsonRpcException) { + $this->assertSame([ + 'jsonrpc' => '2.0', + 'id' => 7, + 'error' => [ + 'code' => -32602, + 'message' => 'The cursor field must be a string.', + ], + ], $jsonRpcException->toJsonRpcResponse()->toArray()); + + return; + } + + $this->fail('Expected a JsonRpcException.'); + } + public function testPreservesNumericObjectPropertiesFromTheWire(): void { $source = '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"arguments":{"0":"first","1":"second"}}}'; diff --git a/tests/Mcp/Unit/Transport/JsonRpcResponseTest.php b/tests/Mcp/Unit/Transport/JsonRpcResponseTest.php index 35ef0221f..591a07426 100644 --- a/tests/Mcp/Unit/Transport/JsonRpcResponseTest.php +++ b/tests/Mcp/Unit/Transport/JsonRpcResponseTest.php @@ -129,10 +129,10 @@ public function testSubstitutesInvalidUtf8InApplicationText(): void $this->assertSame("hello\u{FFFD}", json_decode($response->toJson(), true, flags: JSON_THROW_ON_ERROR)['result']['text']); } - public function testThrowsForValuesThatCannotBeEncoded(): void + public function testThrowsInsteadOfReturningAnEmptyStringWhenTheResponseCannotBeEncoded(): void { $this->expectException(JsonException::class); - JsonRpcResponse::result(1, ['value' => INF])->toJson(); + JsonRpcResponse::result(1, ['value' => NAN])->toJson(); } } From 238749b8f96fc3964edeca1dd6d7bbd1c7d6d5e1 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:05:12 +0000 Subject: [PATCH 03/17] Add MCP conformance fixtures and pin the conformance suite The conformance server gains upstream's custom-header, JSON Schema 2020-12, logging and streaming-elicitation tools, and the prompt fixture completes the values the runner expects. The runner is pinned to @modelcontextprotocol/conformance 0.2.0-alpha.12, so results don't shift with new suite releases. The client fixture selects its tool calls as upstream does (#397). The baseline drops json-schema-2020-12, which now passes, and http-header-validation, which passes since Swoole 6.3.0RC2 strips header whitespace. The remaining comments describe what is missing: server-side validation of mirrored Mcp-Param headers, and the diagnostic tool for requests that need an undeclared client capability. Port laravel/mcp #396 and #397's harness changes at 4cf6b4ea. Upstream's Pint exclusion does not apply. Validation: both conformance suites report no unexpected failures or stale baseline entries. --- dogfood/mcp/README.md | 4 +- dogfood/mcp/conformance/ConformanceServer.php | 8 +++ .../Prompts/PromptWithArguments.php | 7 +- .../conformance/Tools/CustomHeaderTool.php | 47 ++++++++++++++ .../Tools/JsonSchema202012Tool.php | 65 +++++++++++++++++++ dogfood/mcp/conformance/Tools/LoggingTool.php | 24 +++++++ .../Tools/StreamingElicitationTool.php | 24 +++++++ dogfood/mcp/conformance/client.php | 31 +++++---- .../mcp/conformance/conformance-baseline.yml | 7 +- dogfood/mcp/conformance/run.sh | 2 +- 10 files changed, 192 insertions(+), 27 deletions(-) create mode 100644 dogfood/mcp/conformance/Tools/CustomHeaderTool.php create mode 100644 dogfood/mcp/conformance/Tools/JsonSchema202012Tool.php create mode 100644 dogfood/mcp/conformance/Tools/LoggingTool.php create mode 100644 dogfood/mcp/conformance/Tools/StreamingElicitationTool.php diff --git a/dogfood/mcp/README.md b/dogfood/mcp/README.md index 1de739a27..cbfaaa486 100644 --- a/dogfood/mcp/README.md +++ b/dogfood/mcp/README.md @@ -12,7 +12,7 @@ bash conformance/run.sh client Use `bash conformance/run.sh all` to run both. The server command starts an isolated Testbench application on `127.0.0.1:8001` and stops it when finished. The client command runs against mock servers started by the conformance runner. -The runner downloads `@modelcontextprotocol/conformance@alpha` through `npx`. Set `CONFORMANCE_PACKAGE` to select a particular package version, `CONFORMANCE_PORT` to change the server port, or `CONFORMANCE_REVISION` to select the requirements revision (default `2026-07-28`). The server readiness probe uses modern discovery. +The runner downloads `@modelcontextprotocol/conformance@0.2.0-alpha.12` through `npx`. Set `CONFORMANCE_PACKAGE` to select a particular package version, `CONFORMANCE_PORT` to change the server port, or `CONFORMANCE_REVISION` to select the requirements revision (default `2026-07-28`). The server readiness probe uses modern discovery. Each run prints its output directory. Logs, raw results and summary badges go into a new OS temporary directory. Set `CONFORMANCE_OUTPUT_DIR` to choose a different, empty output directory; reusing one mixes its results with previous runs. @@ -20,7 +20,7 @@ Each run prints its output directory. Logs, raw results and summary badges go in `conformance/conformance-baseline.yml` lists known failures. A successful command means no unexpected failures or stale baseline entries were reported; it does not mean every protocol check passed. The score includes passing and failing checks, excluding warnings and skipped checks. -The server fixtures exercise the package's supported tools, prompts, resources, completions and progress notifications. Several runner scenarios require optional features the package does not implement, such as Tasks, multi-round input requests and embedded-resource content. Swoole's trailing HTTP header whitespace defect also remains an expected failure until fixed upstream. +The server fixtures exercise the package's supported tools, prompts, resources, completions and progress notifications. Several runner scenarios require optional features the package does not implement, such as Tasks, multi-round input requests and embedded-resource content. The client fixture exercises discovery, tool calls, schema preservation, HTTP header mirroring and OAuth against the runner's local servers. Authorization runs headlessly: the mock authorization endpoint redirects directly to a callback, which the fixture passes to the package's OAuth client. An array session holds the pending exchange. The fixture allows initial authorization and one reauthorization, including scope step-up and authorization-server migration. diff --git a/dogfood/mcp/conformance/ConformanceServer.php b/dogfood/mcp/conformance/ConformanceServer.php index 99c84b2b4..32794304f 100644 --- a/dogfood/mcp/conformance/ConformanceServer.php +++ b/dogfood/mcp/conformance/ConformanceServer.php @@ -13,12 +13,16 @@ use Hypervel\Dogfood\Mcp\Conformance\Resources\TemplateResource; use Hypervel\Dogfood\Mcp\Conformance\Resources\WatchedResource; use Hypervel\Dogfood\Mcp\Conformance\Tools\AudioContentTool; +use Hypervel\Dogfood\Mcp\Conformance\Tools\CustomHeaderTool; use Hypervel\Dogfood\Mcp\Conformance\Tools\EmbeddedResourceTool; use Hypervel\Dogfood\Mcp\Conformance\Tools\ErrorHandlingTool; use Hypervel\Dogfood\Mcp\Conformance\Tools\ImageContentTool; +use Hypervel\Dogfood\Mcp\Conformance\Tools\JsonSchema202012Tool; +use Hypervel\Dogfood\Mcp\Conformance\Tools\LoggingTool; use Hypervel\Dogfood\Mcp\Conformance\Tools\MultipleContentTypesTool; use Hypervel\Dogfood\Mcp\Conformance\Tools\ProgressTool; use Hypervel\Dogfood\Mcp\Conformance\Tools\SimpleTextTool; +use Hypervel\Dogfood\Mcp\Conformance\Tools\StreamingElicitationTool; use Hypervel\Mcp\Server; class ConformanceServer extends Server @@ -41,6 +45,10 @@ class ConformanceServer extends Server MultipleContentTypesTool::class, ErrorHandlingTool::class, ProgressTool::class, + JsonSchema202012Tool::class, + CustomHeaderTool::class, + LoggingTool::class, + StreamingElicitationTool::class, ]; public array $resources = [ diff --git a/dogfood/mcp/conformance/Prompts/PromptWithArguments.php b/dogfood/mcp/conformance/Prompts/PromptWithArguments.php index 2ab5a546b..acff96c03 100644 --- a/dogfood/mcp/conformance/Prompts/PromptWithArguments.php +++ b/dogfood/mcp/conformance/Prompts/PromptWithArguments.php @@ -46,8 +46,9 @@ public function arguments(): array */ public function complete(string $argument, string $value, array $context): CompletionResponse { - return $argument === 'arg1' - ? CompletionResponse::match(['test', 'testing', 'testable']) - : CompletionResponse::empty(); + return match ($argument) { + 'arg1' => CompletionResponse::match(['paris', 'park', 'party']), + default => CompletionResponse::empty(), + }; } } diff --git a/dogfood/mcp/conformance/Tools/CustomHeaderTool.php b/dogfood/mcp/conformance/Tools/CustomHeaderTool.php new file mode 100644 index 000000000..82827e1e7 --- /dev/null +++ b/dogfood/mcp/conformance/Tools/CustomHeaderTool.php @@ -0,0 +1,47 @@ +get('region')}"); + } + + /** + * Get the tool's input schema. + */ + public function schema(JsonSchema $schema): array + { + return [ + 'region' => $schema->string()->description('Deployment region')->required(), + ]; + } + + /** + * Mark the region parameter for header mirroring. + */ + public function toArray(): array + { + $tool = parent::toArray(); + + $tool['inputSchema']['properties']['region']['x-mcp-header'] = 'Region'; + + return $tool; + } +} diff --git a/dogfood/mcp/conformance/Tools/JsonSchema202012Tool.php b/dogfood/mcp/conformance/Tools/JsonSchema202012Tool.php new file mode 100644 index 000000000..181b5de69 --- /dev/null +++ b/dogfood/mcp/conformance/Tools/JsonSchema202012Tool.php @@ -0,0 +1,65 @@ + [ + '$schema' => 'https://json-schema.org/draft/2020-12/schema', + 'type' => 'object', + '$defs' => [ + 'address' => [ + '$anchor' => 'addressDef', + 'type' => 'object', + 'properties' => [ + 'street' => ['type' => 'string'], + 'city' => ['type' => 'string'], + ], + ], + ], + 'properties' => [ + 'name' => ['type' => 'string'], + 'address' => ['$ref' => '#/$defs/address'], + 'contactMethod' => ['type' => 'string', 'enum' => ['phone', 'email']], + 'phone' => ['type' => 'string'], + 'email' => ['type' => 'string'], + ], + 'allOf' => [ + ['anyOf' => [['required' => ['phone']], ['required' => ['email']]]], + ], + 'if' => [ + 'properties' => ['contactMethod' => ['const' => 'phone']], + 'required' => ['contactMethod'], + ], + 'then' => ['required' => ['phone']], + 'else' => ['required' => ['email']], + 'additionalProperties' => false, + ], + ]; + } +} diff --git a/dogfood/mcp/conformance/Tools/LoggingTool.php b/dogfood/mcp/conformance/Tools/LoggingTool.php new file mode 100644 index 000000000..44a8548e1 --- /dev/null +++ b/dogfood/mcp/conformance/Tools/LoggingTool.php @@ -0,0 +1,24 @@ +count())); - if ($scenario === 'http-custom-headers') { - foreach ($context['toolCalls'] as $call) { - $execute(fn () => $client->callTool($tools->get($call['name']), $call['arguments'])); - } - } elseif ($scenario === 'json-schema-2020-12-preservation') { - $execute(fn () => $client->callTool($tools->get('json_schema_echo'), [ - 'schema' => $tools->get('json_schema_2020_12_tool')->inputSchema, - ])); - } elseif ($scenario !== 'initialize') { - $tool = $tools->first(); - - if ($tool !== null) { - $execute(fn () => $client->callTool($tool, $scenario === 'tools_call' ? ['a' => 2, 'b' => 3] : [])); - - $log(sprintf('called tool %s', $tool->name)); - } + $calls = match (true) { + isset($context['toolCalls']) => $context['toolCalls'], + $scenario === 'tools_call' => [['name' => 'add_numbers', 'arguments' => ['a' => 1, 'b' => 2]]], + $scenario === 'json-schema-2020-12-preservation' => [[ + 'name' => 'json_schema_echo', + 'arguments' => ['schema' => $tools->get('json_schema_2020_12_tool')?->inputSchema], + ]], + $scenario === 'initialize' || $tools->isEmpty() => [], + default => [['name' => $tools->first()->name, 'arguments' => []]], + }; + + foreach ($calls as $call) { + $execute(fn () => $client->callTool($tools->get($call['name']) ?? $call['name'], $call['arguments'] ?? [])); + + $log(sprintf('called tool %s', $call['name'])); } $client->disconnect(); diff --git a/dogfood/mcp/conformance/conformance-baseline.yml b/dogfood/mcp/conformance/conformance-baseline.yml index d0a3d0e2f..8fb433261 100644 --- a/dogfood/mcp/conformance/conformance-baseline.yml +++ b/dogfood/mcp/conformance/conformance-baseline.yml @@ -25,13 +25,10 @@ server: - tools-call-embedded-resource - tools-call-mixed-content - prompts-get-embedded-resource - # Diagnostic tools for capability requests, elicitation and logging are not implemented. + # The diagnostic tool for requests needing an undeclared client capability is not implemented. - server-stateless - # TODO: Remove once Swoole strips trailing HTTP/1 header whitespace upstream. - - http-header-validation - # Server schemas do not expose custom header annotations or arbitrary JSON Schema keywords. + # The server does not validate mirrored Mcp-Param headers against the request body. - http-custom-header-server-validation - - json-schema-2020-12 client: # Multi-round input requests are not implemented. diff --git a/dogfood/mcp/conformance/run.sh b/dogfood/mcp/conformance/run.sh index 05e1c8241..3c6cbb319 100755 --- a/dogfood/mcp/conformance/run.sh +++ b/dogfood/mcp/conformance/run.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash set -uo pipefail -CONFORMANCE="${CONFORMANCE_PACKAGE:-@modelcontextprotocol/conformance@alpha}" +CONFORMANCE="${CONFORMANCE_PACKAGE:-@modelcontextprotocol/conformance@0.2.0-alpha.12}" REVISION="${CONFORMANCE_REVISION:-2026-07-28}" PORT="${CONFORMANCE_PORT:-8001}" From b0aaf42adebd3a2cd77635e37e263b5ada11e953 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:10:25 +0000 Subject: [PATCH 04/17] Refuse MCP client redirects and validate request origins The HTTP client transport no longer follows redirects (#392). Hypervel removed custom headers on cross-origin redirects, but the redirected request still carried its body to the new destination, including internal addresses. A redirect now fails with a TransportException naming its status, so clients use the server's final URL. The OAuth discovery probe keeps its own redirect handling. Origin validation follows upstream (#394): a rejected origin gets a JSON-RPC 403 error, `'*'` allows every origin, `mcp.allowed_origins` accepts a string or a list and ignores non-string entries, configured URLs may end with a slash, and the GET and DELETE routes are checked too. Hypervel keeps stricter rules: the header must be a single bare origin, and loopback origins are not trusted implicitly, because a local web app isn't necessarily one the server operator trusts. The header is parsed once, `app.url` is checked first and the configured list stops at the first match. The client reports a 403 that carries a JSON-RPC error and no authentication challenge, such as an Origin rejection, as a protocol error. Upstream treats every 403 as an authorization requirement, so `tools(default: ...)` silently returned its fallback. Port laravel/mcp #392 and #394 at 4cf6b4ea. They share the transport and documentation changes, so they share this commit. Validation: the MCP suite and the AI package's MCP tests pass; formatting and full static analysis pass; both conformance suites report no unexpected failures. --- src/docs/mcp.md | 6 +- src/docs/porting-from-laravel.md | 4 +- src/mcp/README.md | 3 +- src/mcp/config/mcp.php | 3 +- .../src/Client/Transport/HttpTransport.php | 40 +++-- .../src/Server/Middleware/ValidateOrigin.php | 57 +++--- src/mcp/src/Server/Registrar.php | 6 +- .../Client/HandshakeNegotiationTest.php | 17 ++ .../Server/Middleware/ValidateOriginTest.php | 170 ++++++++++++++++++ .../Unit/Client/OAuth/OAuthTransportTest.php | 20 +++ .../Client/Transport/HttpTransportTest.php | 106 ++++++----- .../Server/Middleware/ValidateOriginTest.php | 87 --------- 12 files changed, 329 insertions(+), 190 deletions(-) create mode 100644 tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php delete mode 100644 tests/Mcp/Unit/Server/Middleware/ValidateOriginTest.php diff --git a/src/docs/mcp.md b/src/docs/mcp.md index 6f1d1108a..de621e9b0 100644 --- a/src/docs/mcp.md +++ b/src/docs/mcp.md @@ -188,6 +188,8 @@ php artisan vendor:publish --tag=mcp-config ], ``` +Your application's own origin is allowed even when `app.url` is local, but other origins on your machine are not. Add a frontend that calls the server directly from another local port to this list, such as `http://localhost:5173`. To allow every origin, use `'*'`. + Set `app.url` to your application's trusted public URL. Origin validation does not replace authentication or your application's CORS configuration. These settings belong to the application; end users do not need to change their browsers or CLI clients. @@ -2017,6 +2019,8 @@ use Hypervel\Mcp\Client; $client = Client::web('https://api.githubcopilot.com/mcp/'); ``` +The client does not follow redirects, so use the server's final URL. + To connect to a local MCP server that runs as a command, use the `Client::local` method, providing the command and any arguments needed to start the server: ```php @@ -2106,8 +2110,6 @@ $client = Client::web('https://projects.example.com/mcp')->withHeaders([ ]); ``` -Custom headers are removed when a redirect changes the configured URL's scheme, host, or port. They remain removed for the rest of that redirect chain, even if it returns to the original origin. A new request to the configured URL sends them again. Connect to the destination server's URL directly if it needs those headers. - #### Linking User Accounts With OAuth diff --git a/src/docs/porting-from-laravel.md b/src/docs/porting-from-laravel.md index 6c7562194..7704e0873 100644 --- a/src/docs/porting-from-laravel.md +++ b/src/docs/porting-from-laravel.md @@ -582,7 +582,7 @@ Custom conversation stores must implement `ClaimsPendingApprovals` to resume sto ### MCP -For direct browser clients from another origin, add their origins to `mcp.allowed_origins`; `app.url` is allowed automatically. See [allowed origins](/docs/{{version}}/mcp#allowed-origins). +Laravel allows loopback browser origins such as `http://localhost:5173` automatically, while Hypervel requires them in `mcp.allowed_origins`; see [allowed origins](/docs/{{version}}/mcp#allowed-origins). Local OAuth discovery is served by Passport's `passport.metadata` route, using its explicitly configured HTTPS issuer. Replace references to `mcp.oauth.register` with `passport.clients.register`; MCP no longer defines authorization-server metadata routes. Choose one registration endpoint, using `Mcp::oauthRoutes(registration: false)` with native Passport registration or an external server. Register MCP resource identifiers in Passport and enforce both audience and `mcp:use` on the MCP routes. See [OAuth setup](/docs/{{version}}/mcp#oauth). @@ -596,8 +596,6 @@ If an OAuth client relies on Laravel's implicit `mcp:use` scope and the remote s Use `redirect()->signedRoute()` when forwarding `resource_metadata` or `scope` to an MCP client's connect route. Unsigned hints are rejected to prevent credential disclosure through substituted discovery metadata; see [authorization challenges](/docs/{{version}}/mcp#client-oauth-scopes). -If an MCP client's URL redirects to another origin that needs its custom headers, configure the final URL directly. Hypervel follows the redirect without forwarding those headers; see [custom client headers](/docs/{{version}}/mcp#client-custom-headers). - Modern HTTP streams cancel on client disconnect. Review handlers that perform side effects while streaming and ensure their cleanup runs on cancellation; legacy streams still finish. See [streaming responses](/docs/{{version}}/mcp#streaming-responses). MCP servers do not negotiate protocol revision `2025-03-26`. Clients limited to that revision cannot connect; use clients that support `2025-06-18` or newer. See [protocol versions](/docs/{{version}}/mcp#protocol-versions). diff --git a/src/mcp/README.md b/src/mcp/README.md index 3a55af00f..8fa4b77bd 100644 --- a/src/mcp/README.md +++ b/src/mcp/README.md @@ -7,14 +7,13 @@ Documentation: https://hypervel.org/docs/mcp ## Differences From Laravel -- HTTP servers validate browser origins against `app.url` and `mcp.allowed_origins`. Configure additional origins for direct cross-origin browser clients; see [allowed origins](https://hypervel.org/docs/mcp#allowed-origins). +- HTTP servers do not trust loopback browser origins automatically, because a local web app is not necessarily one the server operator trusts. List a local frontend that calls the server directly, such as `http://localhost:5173`, in `mcp.allowed_origins`; see [allowed origins](https://hypervel.org/docs/mcp#allowed-origins). - Modern HTTP streams cancel their work when the client disconnects; legacy streams finish. Account for cancellation when performing streamed side effects; see [streaming responses](https://hypervel.org/docs/mcp#streaming-responses). - Servers do not negotiate protocol revision `2025-03-26`, which Laravel accepts in the `initialize` handshake without supporting the JSON-RPC batching it requires. Clients requesting it are offered `2025-11-25`, so use clients that support `2025-06-18` or newer; see [protocol versions](https://hypervel.org/docs/mcp#protocol-versions). - Dynamic OAuth registration is rate limited by Passport's `passport` limiter. Customize that limiter when needed; see [OAuth authentication](https://hypervel.org/docs/mcp#oauth). - Local authorization-server discovery belongs to Passport and requires its configured HTTPS issuer. MCP keeps protected-resource discovery and uses `passport.clients.register` for registration. Choose one registration endpoint and define resource audiences in Passport; see [OAuth setup](https://hypervel.org/docs/mcp#oauth). - Anonymous registration persists an explicit scope ceiling from Passport's anonymous allowance plus `mcp:use`; custom client schemas require `scopes` and `third_party`. Wildcard callback domains permit HTTPS and HTTP loopback only; explicit administrator allowances and configured native schemes remain supported. See [registration policy](https://hypervel.org/docs/mcp#oauth). - Connect URLs containing `resource_metadata` or `scope` must be signed with `redirect()->signedRoute()` or `URL::signedRoute()` to prevent discovery-hint tampering; see [authorization challenges](https://hypervel.org/docs/mcp#client-oauth-scopes). -- Custom client headers stay on the configured origin across redirects because they may contain credentials. Connect directly to a server on another origin if it needs those headers; see [custom client headers](https://hypervel.org/docs/mcp#client-custom-headers). - OAuth clients resolve DNS locally and pin each OAuth request through `OAuthDestinationPolicy`, including behind ordinary proxies. Private DNS destinations require an explicit policy allowance, even when the resource itself is private. See [OAuth destinations](https://hypervel.org/docs/mcp#oauth-destinations). - OAuth requests use capped response streams instead of Laravel's protected `oAuthCurlOptions()` helper, which is omitted because the transport owns protocol restrictions and rejects its raw cURL options. Customize `$maxOAuthResponseSize` or the request through `oAuthRequest()`. - OAuth clients use the remote server's advertised scopes instead of assuming `mcp:use`. Set `withOAuth(scope: 'mcp:use')` when that scope is required but not advertised; see [OAuth scopes](https://hypervel.org/docs/mcp#client-oauth-scopes). diff --git a/src/mcp/config/mcp.php b/src/mcp/config/mcp.php index 1de3eed53..93331c4dd 100644 --- a/src/mcp/config/mcp.php +++ b/src/mcp/config/mcp.php @@ -10,7 +10,8 @@ | | Browser requests may use the origin configured in app.url. List any | additional browser application origins here, including their scheme - | and port. Clients that do not send an Origin header are also allowed. + | and port, or use "*" to allow every origin. Clients that do not send + | an Origin header are also allowed. | */ diff --git a/src/mcp/src/Client/Transport/HttpTransport.php b/src/mcp/src/Client/Transport/HttpTransport.php index dc16b62dc..22f9b8e4f 100644 --- a/src/mcp/src/Client/Transport/HttpTransport.php +++ b/src/mcp/src/Client/Transport/HttpTransport.php @@ -15,7 +15,6 @@ use Hypervel\Mcp\Client\Contracts\UsesProtocol; use Hypervel\Mcp\Client\Exceptions\AuthorizationRequiredException; use Hypervel\Mcp\Client\Exceptions\TransportException; -use Hypervel\Mcp\Client\Middleware\RestrictHeadersToOrigin; use Hypervel\Mcp\Client\OAuth\WwwAuthenticateChallenge; use Hypervel\Mcp\Enums\ProtocolHandshake; use Hypervel\Mcp\Enums\ProtocolVersion; @@ -204,18 +203,37 @@ public function send(string $message, array $headers = []): void $exchange->response = $response; + if ($response->redirect()) { + $this->resetFailedExchange($exchange); + + throw new TransportException("The endpoint [{$this->url}] responded with a redirect [{$response->status()}], which is not followed."); + } + if ($exchange->initializing && $exchange->generation === $this->generation) { $this->captureSessionId($response); } if ($response->status() === 401 || $response->status() === 403) { - $challenge = WwwAuthenticateChallenge::parse($response->header('WWW-Authenticate')); + $challenge = $response->header('WWW-Authenticate'); + + // Unlike upstream, a 403 carrying a JSON-RPC error instead of a challenge, such as an + // Origin rejection, reaches the caller as a protocol error rather than an authorization prompt. + if ($response->status() === 403 && $challenge === '') { + $content = trim($response->body()); + $exchange->ensureOpen(); + + if ($this->hasJsonRpcError($content)) { + $this->queue[] = $content; + + return; + } + } $this->resetFailedExchange($exchange); throw new AuthorizationRequiredException( "The server responded with HTTP {$response->status()} for endpoint [{$this->url}]. Authorization is required.", - $challenge, + WwwAuthenticateChallenge::parse($challenge), ); } @@ -376,25 +394,13 @@ protected function headers(array $mirrored = []): array } /** - * Prepare a request with custom headers restricted to the configured origin. + * Prepare a request that does not follow redirects. * * @param array $headers */ protected function request(array $headers = []): PendingRequest { - $request = Http::withHeaders($this->headers($headers)); - - if ($this->customHeaders === []) { - return $request; - } - - // Preserve protocol headers: a redirect target may have issued the session during initialization. - $customHeaders = array_values(array_filter( - array_keys($this->customHeaders), - fn (string $name): bool => ! $this->reserved($name), - )); - - return $request->withMiddleware(new RestrictHeadersToOrigin($this->url, $customHeaders)); + return Http::withHeaders($this->headers($headers))->withoutRedirecting(); } /** diff --git a/src/mcp/src/Server/Middleware/ValidateOrigin.php b/src/mcp/src/Server/Middleware/ValidateOrigin.php index 045067ddd..34ae4f255 100644 --- a/src/mcp/src/Server/Middleware/ValidateOrigin.php +++ b/src/mcp/src/Server/Middleware/ValidateOrigin.php @@ -7,10 +7,11 @@ use Closure; use Hypervel\Contracts\Config\Repository; use Hypervel\Http\Request; +use Hypervel\Mcp\Enums\ErrorCode; +use Hypervel\Support\Arr; use Hypervel\Support\Uri; use InvalidArgumentException; use Symfony\Component\HttpFoundation\Response; -use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException; class ValidateOrigin { @@ -23,40 +24,58 @@ public function __construct(protected Repository $config) /** * Reject browser origins that the application has not allowed. + * + * @param Closure(Request): (Response) $next */ public function handle(Request $request, Closure $next): Response { $origins = $request->headers->all('origin'); - if ($origins === []) { + if ($origins === [] || (count($origins) === 1 && $this->allowed($origins[0]))) { return $next($request); } - $origin = count($origins) === 1 ? $this->origin($origins[0]) : null; + return response()->json([ + 'jsonrpc' => '2.0', + 'error' => [ + 'code' => ErrorCode::INVALID_REQUEST->value, + 'message' => 'Forbidden: The request origin is not allowed.', + ], + ], 403); + } - if ($origin !== null) { - // Trust configured origins, never the incoming request's Host header. - if ($origin === $this->origin($this->config->string('app.url'), allowPath: true)) { - return $next($request); - } + /** + * Determine whether the request origin is allowed. + */ + protected function allowed(string $origin): bool + { + $normalized = $this->normalize($origin); - foreach ($this->config->array('mcp.allowed_origins') as $allowedOrigin) { - if ($origin === $this->origin($allowedOrigin)) { - return $next($request); - } - } + // Browsers send only a scheme, host and port, so a header with a path, query or fragment is malformed. + if ($normalized === null || substr_count($origin, '/') !== 2 || strpbrk($origin, '?#') !== false) { + return false; } - throw new AccessDeniedHttpException('Origin is not allowed.'); + // Trust configured origins, never the incoming request's Host header. + if ($normalized === $this->normalize($this->config->string('app.url'))) { + return true; + } + + // Unlike upstream, loopback origins are not trusted implicitly: a local web app on the + // browser user's machine is not necessarily one the server operator trusts. + return array_any( + Arr::wrap($this->config->get('mcp.allowed_origins', [])), + fn (mixed $allowed): bool => $allowed === '*' || (is_string($allowed) && $this->normalize($allowed) === $normalized), + ); } /** - * Normalize an HTTP origin without making a network request. + * Reduce an HTTP URL to its normalized origin without making a network request. */ - protected function origin(string $value, bool $allowPath = false): ?string + protected function normalize(string $origin): ?string { try { - $uri = Uri::of($value); + $uri = Uri::of($origin); } catch (InvalidArgumentException) { return null; } @@ -66,8 +85,6 @@ protected function origin(string $value, bool $allowPath = false): ?string return null; } - $origin = $uri->scheme() . '://' . $uri->authority(); - - return $allowPath || $uri->value() === $origin ? $origin : null; + return $uri->scheme() . '://' . $uri->authority(); } } diff --git a/src/mcp/src/Server/Registrar.php b/src/mcp/src/Server/Registrar.php index 2d52ce9fa..41584bb7d 100644 --- a/src/mcp/src/Server/Registrar.php +++ b/src/mcp/src/Server/Registrar.php @@ -53,9 +53,11 @@ class Registrar public function web(string $route, string $serverClass): Route { // https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#listening-for-messages-from-the-server - Router::get($route, fn (): Response => response('', 405)->header('Allow', 'POST')); + Router::get($route, fn (): Response => response('', 405)->header('Allow', 'POST')) + ->middleware(ValidateOrigin::class); - Router::delete($route, fn (): Response => response('', 405)->header('Allow', 'POST')); + Router::delete($route, fn (): Response => response('', 405)->header('Allow', 'POST')) + ->middleware(ValidateOrigin::class); $route = Router::post($route, static fn (): mixed => static::startServer( $serverClass, diff --git a/tests/Mcp/Feature/Client/HandshakeNegotiationTest.php b/tests/Mcp/Feature/Client/HandshakeNegotiationTest.php index 4551bbebe..32c3f6b0b 100644 --- a/tests/Mcp/Feature/Client/HandshakeNegotiationTest.php +++ b/tests/Mcp/Feature/Client/HandshakeNegotiationTest.php @@ -70,6 +70,23 @@ public function testReadsAProtocolErrorOutOfA400Response(): void } } + public function testReportsAnOriginRejectionAsAProtocolErrorInsteadOfFallingBackToTheDefault(): void + { + $rejection = json_encode([ + 'jsonrpc' => '2.0', + 'error' => ['code' => -32600, 'message' => 'Forbidden: The request origin is not allowed.'], + ]); + + // The probe's Invalid Request error permits the legacy handshake, which the server rejects too. + Http::fakeSequence() + ->push($rejection, 403, ['Content-Type' => 'application/json']) + ->push($rejection, 403, ['Content-Type' => 'application/json']); + + $this->expectException(JsonRpcException::class); + $this->expectExceptionMessage('Forbidden: The request origin is not allowed.'); + Client::web('https://mcp.test/mcp')->tools(default: []); + } + public function testRetriesWithAMutualVersionFromAProtocolErrorInA400Response(): void { Http::fakeSequence() diff --git a/tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php b/tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php new file mode 100644 index 000000000..d5ea57f5f --- /dev/null +++ b/tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php @@ -0,0 +1,170 @@ +postJson('test-mcp', $message, mcpHeaders($message))->assertStatus(200); + } + + #[DataProvider('allowedOrigins')] + public function testAcceptsARequestFromAnAllowedOrigin(string $origin): void + { + config(['app.url' => 'https://app.test/']); + + $message = listToolsMessage(); + + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => $origin])->assertStatus(200); + } + + /** + * Provide origins matching the application URL. + */ + public static function allowedOrigins(): array + { + // REMOVED: Upstream's localhost, IPv4 and IPv6 loopback rows; Hypervel trusts loopback origins only when configured. + return [ + 'application url' => ['https://app.test'], + 'application url with default port' => ['https://APP.test:443'], + ]; + } + + #[DataProvider('disallowedOrigins')] + public function testRejectsARequestFromAnOriginThatIsNotAllowed(string $origin): void + { + config(['app.url' => 'https://app.test']); + + $message = listToolsMessage(); + + $response = $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => $origin]); + + $response->assertStatus(403); + + $this->assertEquals([ + 'jsonrpc' => '2.0', + 'error' => [ + 'code' => -32600, + 'message' => 'Forbidden: The request origin is not allowed.', + ], + ], $response->json()); + } + + /** + * Provide unapproved and malformed origins. + */ + public static function disallowedOrigins(): array + { + return [ + 'foreign host' => ['https://evil.example'], + 'subdomain of application' => ['https://evil.app.test'], + 'different scheme' => ['http://app.test'], + 'different port' => ['https://app.test:8443'], + 'opaque origin' => ['null'], + 'unsupported scheme' => ['file://app.test'], + 'loopback' => ['http://localhost:6274'], + 'empty' => [''], + 'path' => ['https://app.test/path'], + 'trailing slash' => ['https://app.test/'], + 'credentials' => ['https://user@app.test'], + 'query' => ['https://app.test?query'], + 'fragment' => ['https://app.test#fragment'], + 'invalid port' => ['https://app.test:99999'], + ]; + } + + public function testRejectsARebindingRequestWhoseHostMatchesItsOrigin(): void + { + config(['app.url' => 'https://app.test']); + + $message = listToolsMessage(); + + $this->postJson('http://evil.example/test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'http://evil.example']) + ->assertStatus(403); + } + + public function testAcceptsTheApplicationOriginWhenItsUrlHasAPath(): void + { + config(['app.url' => 'https://app.test/subdirectory']); + + $message = listToolsMessage(); + + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://app.test'])->assertStatus(200); + } + + public function testAcceptsARequestFromAConfiguredOrigin(): void + { + config(['mcp.allowed_origins' => ['https://client.example/']]); + + $message = listToolsMessage(); + + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://client.example'])->assertStatus(200); + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://evil.example'])->assertStatus(403); + } + + public function testAcceptsAConfiguredOriginGivenAsAString(): void + { + config(['mcp.allowed_origins' => 'https://client.example']); + + $message = listToolsMessage(); + + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://client.example'])->assertStatus(200); + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://evil.example'])->assertStatus(403); + } + + public function testIgnoresConfiguredOriginsThatAreNotStrings(): void + { + config(['mcp.allowed_origins' => [null, 42, 'https://client.example']]); + + $message = listToolsMessage(); + + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://client.example'])->assertStatus(200); + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://evil.example'])->assertStatus(403); + } + + public function testAcceptsAnyOriginWhenAllOriginsAreAllowed(): void + { + config(['mcp.allowed_origins' => ['*']]); + + $message = listToolsMessage(); + + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://evil.example'])->assertStatus(200); + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'null'])->assertStatus(403); + } + + #[TestWith(['GET'])] + #[TestWith(['DELETE'])] + public function testValidatesTheOriginOnGetAndDeleteRequests(string $method): void + { + $this->json($method, 'test-mcp', [], ['Origin' => 'https://evil.example'])->assertStatus(403); + $this->json($method, 'test-mcp')->assertStatus(405); + } + + public function testRejectsMultipleOriginHeaders(): void + { + config(['app.url' => 'https://app.test']); + + $request = Request::create('https://app.test/test-mcp', 'POST'); + $request->headers->set('Origin', ['https://app.test', 'https://other.test']); + + $response = $this->app->make(ValidateOrigin::class)->handle($request, function (): never { + $this->fail('The request must be rejected before reaching the handler.'); + }); + + $this->assertSame(403, $response->getStatusCode()); + } +} diff --git a/tests/Mcp/Unit/Client/OAuth/OAuthTransportTest.php b/tests/Mcp/Unit/Client/OAuth/OAuthTransportTest.php index bb7211101..edb3066d8 100644 --- a/tests/Mcp/Unit/Client/OAuth/OAuthTransportTest.php +++ b/tests/Mcp/Unit/Client/OAuth/OAuthTransportTest.php @@ -64,6 +64,26 @@ public function testThrowsAuthorizationRequiredExceptionOnA403(): void $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/list', 'params' => []])); } + public function testThrowsAuthorizationRequiredExceptionOnA403ChallengeCarryingAJsonRpcError(): void + { + Http::fake([ + 'https://mcp.test/mcp' => Http::response( + json_encode(['jsonrpc' => '2.0', 'error' => ['code' => -32600, 'message' => 'Forbidden']]), + 403, + ['WWW-Authenticate' => 'Bearer error="insufficient_scope", scope="files:write"'], + ), + ]); + + $transport = new HttpTransport('https://mcp.test/mcp'); + + try { + $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/list', 'params' => []])); + $this->fail('Expected AuthorizationRequiredException.'); + } catch (AuthorizationRequiredException $authorizationRequiredException) { + $this->assertSame('files:write', $authorizationRequiredException->scope()); + } + } + public function testParsesMixedWwwAuthenticateChallengesWithQuotedCommasAndUnquotedValues(): void { $challenge = WwwAuthenticateChallenge::parse('Basic realm="api", Bearer resource_metadata="https://mcp.test/.well-known/oauth-protected-resource/a,b", scope=files:read, error_description="needs access"'); diff --git a/tests/Mcp/Unit/Client/Transport/HttpTransportTest.php b/tests/Mcp/Unit/Client/Transport/HttpTransportTest.php index 9af5f4af3..6a2c059cf 100644 --- a/tests/Mcp/Unit/Client/Transport/HttpTransportTest.php +++ b/tests/Mcp/Unit/Client/Transport/HttpTransportTest.php @@ -13,6 +13,7 @@ use Hypervel\Http\Client\ConnectionException; use Hypervel\Http\Client\Request; use Hypervel\Mcp\Client; +use Hypervel\Mcp\Client\Exceptions\TransportException; use Hypervel\Mcp\Client\Transport\HttpTransport; use Hypervel\Mcp\Enums\ProtocolVersion; use Hypervel\Mcp\Exceptions\ClientException; @@ -262,62 +263,6 @@ public function testReplacesADefaultHeaderCaseInsensitivelyInsteadOfSendingADupl }); } - #[TestWith([false], 'message')] - #[TestWith([true], 'session termination')] - public function testRedirectsKeepCustomHeadersRemovedAfterLeavingTheirOrigin(bool $disconnect): void - { - $requests = []; - Http::fake(function (Request $request) use (&$requests): PromiseInterface { - if (($request['method'] ?? null) === 'initialize') { - return Http::response(['jsonrpc' => '2.0', 'id' => 1, 'result' => []], headers: [ - 'MCP-Session-Id' => 'resource-session', - ]); - } - - $requests[] = $request; - - return match ($request->url()) { - 'https://mcp.test/mcp' => Http::response('', 307, ['Location' => 'https://other.test/mcp']), - 'https://other.test/mcp' => Http::response('', 307, ['Location' => 'https://mcp.test/return']), - default => Http::response('', 202), - }; - }); - $transport = new HttpTransport('https://mcp.test/mcp'); - $transport->withHeaders(['X-Api-Key' => 'resource-secret', 'MCP-Protocol-Version' => 'ignored']); - $transport->useProtocol(ProtocolVersion::V2025_11_25); - - try { - $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'method' => 'initialize'])); - $transport->receive(); - - if ($disconnect) { - $transport->disconnect(); - } else { - $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 2, 'method' => 'ping'])); - } - - $this->assertCount(3, $requests); - $this->assertTrue($requests[0]->hasHeader('X-Api-Key', 'resource-secret')); - foreach ([1, 2] as $index) { - $this->assertFalse($requests[$index]->hasHeader('X-Api-Key')); - $this->assertTrue($requests[$index]->hasHeader('MCP-Session-Id', 'resource-session')); - $this->assertTrue($requests[$index]->hasHeader('MCP-Protocol-Version', ProtocolVersion::V2025_11_25->value)); - } - $this->assertTrue($requests[0]->hasHeader('MCP-Session-Id', 'resource-session')); - - if (! $disconnect) { - $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 3, 'method' => 'ping'])); - - $this->assertCount(6, $requests); - $this->assertTrue($requests[3]->hasHeader('X-Api-Key', 'resource-secret')); - $this->assertFalse($requests[4]->hasHeader('X-Api-Key')); - $this->assertFalse($requests[5]->hasHeader('X-Api-Key')); - } - } finally { - $transport->disconnect(); - } - } - public function testLetsACustomAuthorizationHeaderOverrideTheBearerToken(): void { Http::fake(['*' => Http::response(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'result' => []]), 200, ['Content-Type' => 'application/json'])]); @@ -411,6 +356,55 @@ public function testThrowsAClientExceptionOnAnUnexpectedHttpStatus(): void $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'method' => 'ping', 'params' => []])); } + #[TestWith([301])] + #[TestWith([302])] + #[TestWith([303])] + #[TestWith([307])] + #[TestWith([308])] + public function testDoesNotFollowARedirectFromTheMcpServer(int $status): void + { + Http::preventStrayRequests(); + + Http::fake([ + 'https://mcp.test/mcp' => Http::response('', $status, [ + 'Location' => 'http://169.254.169.254/latest/meta-data/iam/security-credentials/', + ]), + 'http://169.254.169.254/*' => Http::response('{}', 200), + ]); + + $transport = new HttpTransport('https://mcp.test/mcp'); + $transport->withHeaders(['X-Api-Key' => 'secret-gateway-key']); + + try { + $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/call', 'params' => ['name' => 'run', 'arguments' => []]])); + + $this->fail('Expected a TransportException.'); + } catch (TransportException $exception) { + $this->assertSame("The endpoint [https://mcp.test/mcp] responded with a redirect [{$status}], which is not followed.", $exception->getMessage()); + } + + Http::assertSentCount(1); + Http::assertNotSent(fn (Request $request): bool => str_starts_with($request->url(), 'http://169.254.169.254')); + } + + public function testDoesNotFollowARedirectWhenTerminatingTheSession(): void + { + Http::fakeSequence('https://mcp.test/mcp') + ->push(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'result' => []]), 200, ['Content-Type' => 'application/json', 'MCP-Session-Id' => 'session-del']) + ->push('', 307, ['Location' => 'http://127.0.0.1:6379/']); + + Http::fake(['http://127.0.0.1:6379/*' => Http::response('', 200)]); + + $transport = new HttpTransport('https://mcp.test/mcp'); + $transport->useProtocol(ProtocolVersion::V2025_11_25); + $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'method' => 'initialize', 'params' => []])); + $transport->receive(); + $transport->disconnect(); + + Http::assertSentCount(2); + Http::assertNotSent(fn (Request $request): bool => str_starts_with($request->url(), 'http://127.0.0.1')); + } + public function testSendsADeleteWithTheSessionIdOnDisconnect(): void { Http::fake(['*' => Http::response( diff --git a/tests/Mcp/Unit/Server/Middleware/ValidateOriginTest.php b/tests/Mcp/Unit/Server/Middleware/ValidateOriginTest.php deleted file mode 100644 index 57fb7072b..000000000 --- a/tests/Mcp/Unit/Server/Middleware/ValidateOriginTest.php +++ /dev/null @@ -1,87 +0,0 @@ -headers->set('Origin', $origin); - } - - $response = new Response('ok'); - - $this->assertSame($response, $this->middleware()->handle($request, fn (): Response => $response)); - } - - /** - * Provide allowed origins, including normalized default ports. - */ - public static function allowedOrigins(): array - { - return [ - 'no header' => [null], - 'application' => ['https://app.test'], - 'normalized application' => ['HTTPS://APP.TEST:443'], - 'additional origin' => ['http://client.test:8080'], - ]; - } - - #[DataProvider('rejectedOrigins')] - public function testRejectsOtherOriginsBeforeCallingTheHandler(string|array $origin): void - { - $request = Request::create('https://untrusted-host.test/mcp'); - $request->headers->set('Origin', $origin); - - $this->expectException(AccessDeniedHttpException::class); - - $this->middleware()->handle($request, function (): never { - $this->fail('The request must be rejected before reaching the handler.'); - }); - } - - /** - * Provide unapproved and malformed origins. - */ - public static function rejectedOrigins(): array - { - return [ - 'host header is not trusted' => ['https://untrusted-host.test'], - 'different port' => ['https://app.test:8443'], - 'different scheme' => ['http://app.test'], - 'opaque' => ['null'], - 'empty' => [''], - 'path' => ['https://app.test/path'], - 'credentials' => ['https://user@app.test'], - 'query' => ['https://app.test?query'], - 'fragment' => ['https://app.test#fragment'], - 'invalid port' => ['https://app.test:99999'], - 'multiple headers' => [['https://app.test', 'https://other.test']], - ]; - } - - /** - * Create middleware with the application's trusted origins. - */ - private function middleware(): ValidateOrigin - { - return new ValidateOrigin(new Repository([ - 'app' => ['url' => 'https://app.test/subdirectory'], - 'mcp' => ['allowed_origins' => ['http://client.test:8080']], - ])); - } -} From 2aeae532670aee73e1f5f4d984b2ba12fc0ee0a8 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:56:09 +0000 Subject: [PATCH 05/17] Run OpenAI-compatible tool calls sent without an index Some OpenAI-compatible servers stream tool call deltas without an index, so the stream failed to assemble them. A delta without an index now continues the last call unless it names a new one, and a delta whose id matches an earlier call continues that call. Upstream only compared the id with the last call, so an interleaved fragment of the first of two parallel calls lost its arguments and produced an extra call; Hypervel matches the id against every pending call instead. Hypervel already treated a "stop" finish carrying tool calls as a tool turn in both the streamed and buffered paths, so only the comment and expressions were aligned with upstream. Port laravel/ai#1192 at a2cb93a2. Ported the feature tests and their helpers, and the Gemini-backed integration tests, which read the key from ai.providers.gemini.key. Added a regression test for an interleaved fragment that carries an earlier call's id. Validation: the changed test files pass; formatting and full static analysis pass. --- .../Concerns/HandlesTextStreaming.php | 29 +++- .../Concerns/ParsesTextResponses.php | 7 +- .../OpenAiCompatible/OpenAiCompatibleTest.php | 135 ++++++++++++++++++ tests/Integration/Ai/AgentTest.php | 46 ++++++ 4 files changed, 208 insertions(+), 9 deletions(-) diff --git a/src/ai/src/Gateway/OpenAiCompatible/Concerns/HandlesTextStreaming.php b/src/ai/src/Gateway/OpenAiCompatible/Concerns/HandlesTextStreaming.php index d0a406b53..3754b1e91 100644 --- a/src/ai/src/Gateway/OpenAiCompatible/Concerns/HandlesTextStreaming.php +++ b/src/ai/src/Gateway/OpenAiCompatible/Concerns/HandlesTextStreaming.php @@ -139,7 +139,7 @@ protected function processTextStream( if (isset($delta['tool_calls'])) { foreach ($delta['tool_calls'] as $tcDelta) { - $idx = $tcDelta['index']; + $idx = $tcDelta['index'] ?? $this->inferToolCallIndex($pendingToolCalls, $tcDelta); if (! isset($pendingToolCalls[$idx])) { $pendingToolCalls[$idx] = [ @@ -193,7 +193,7 @@ protected function processTextStream( ))->withInvocationId($invocationId); } - // Compatible servers can report stop when a named tool choice forces the call. + // Some servers finish a tool turn with "stop" rather than "tool_calls". if (filled($pendingToolCalls) && in_array($finishReason, ['tool_calls', 'stop'], true)) { $toolCalls = $this->mapStreamToolCalls($pendingToolCalls); @@ -209,12 +209,35 @@ protected function processTextStream( return new StepResponse( text: $currentText, toolCalls: $toolCalls, - finishReason: filled($toolCalls) ? FinishReason::ToolCalls : $this->extractFinishReason(['finish_reason' => $finishReason]), + finishReason: $toolCalls !== [] + ? FinishReason::ToolCalls + : $this->extractFinishReason(['finish_reason' => $finishReason]), usage: $usage ?? new TextUsage(0, 0), meta: new Meta($provider->name(), $responseModel), ); } + /** + * Infer a tool call delta's index for servers that omit it: a new id, or a second name, starts a new call. + * + * @param array $pendingToolCalls + */ + protected function inferToolCallIndex(array $pendingToolCalls, array $tcDelta): int + { + // Unlike upstream, a known id continues its own call rather than only the last one, so interleaved + // fragments of parallel calls are not merged into the wrong call or split into a new one. + if (isset($tcDelta['id'])) { + return array_find_key($pendingToolCalls, fn (array $toolCall): bool => $toolCall['id'] === $tcDelta['id']) + ?? count($pendingToolCalls); + } + + $last = end($pendingToolCalls); + + $startsNewCall = $last === false || (isset($tcDelta['function']['name']) && $last['name'] !== ''); + + return $startsNewCall ? count($pendingToolCalls) : array_key_last($pendingToolCalls); + } + /** * Map raw streaming tool call data to ToolCall DTOs. * diff --git a/src/ai/src/Gateway/OpenAiCompatible/Concerns/ParsesTextResponses.php b/src/ai/src/Gateway/OpenAiCompatible/Concerns/ParsesTextResponses.php index f7ff5fa56..1b8c040da 100644 --- a/src/ai/src/Gateway/OpenAiCompatible/Concerns/ParsesTextResponses.php +++ b/src/ai/src/Gateway/OpenAiCompatible/Concerns/ParsesTextResponses.php @@ -57,15 +57,10 @@ protected function parseTextResponse( $finishReason = $this->extractFinishReason($choice); - // Compatible servers can report stop when a named tool choice forces the call. - if ($finishReason === FinishReason::Stop && $mappedToolCalls !== []) { - $finishReason = FinishReason::ToolCalls; - } - return new StepResponse( text: $text, toolCalls: $mappedToolCalls, - finishReason: $finishReason, + finishReason: filled($mappedToolCalls) && $finishReason === FinishReason::Stop ? FinishReason::ToolCalls : $finishReason, usage: $this->extractUsage($data), meta: new Meta($provider->name(), $model), structured: $structured ? $this->decodeStructuredOutput($text) : null, diff --git a/tests/Ai/Feature/Providers/OpenAiCompatible/OpenAiCompatibleTest.php b/tests/Ai/Feature/Providers/OpenAiCompatible/OpenAiCompatibleTest.php index f973f848f..641ed5b71 100644 --- a/tests/Ai/Feature/Providers/OpenAiCompatible/OpenAiCompatibleTest.php +++ b/tests/Ai/Feature/Providers/OpenAiCompatible/OpenAiCompatibleTest.php @@ -11,11 +11,14 @@ use Hypervel\Ai\Exceptions\StreamErrorException; use Hypervel\Ai\Promptable; use Hypervel\Ai\Streaming\Events\Error; +use Hypervel\Ai\Streaming\Events\ToolCall as ToolCallEvent; +use Hypervel\Ai\Streaming\Events\ToolResult as ToolResultEvent; use Hypervel\Contracts\Foundation\Application; use Hypervel\Http\Client\Request; use Hypervel\Support\Facades\Http; use Hypervel\Tests\Ai\Fixtures\Agents\AttributeAgent; use Hypervel\Tests\Ai\Fixtures\Agents\AttributeToolChoiceAgent; +use Hypervel\Tests\Ai\Fixtures\Agents\MultiStepToolAgent; use Hypervel\Tests\Ai\Fixtures\Agents\NestedStructuredAgent; use Hypervel\Tests\Ai\Fixtures\Agents\StructuredAgent; use Hypervel\Tests\Ai\Fixtures\Agents\ToolChoiceAgent; @@ -457,6 +460,103 @@ public function providerOptions(Lab|string $provider): array && data_get(json_decode($request->body(), true), 'top_k') === 10); } + public function testPromptingRunsAToolCallThatFinishesWithStop(): void + { + Http::fakeSequence() + ->push([ + 'id' => 'chatcmpl-123', + 'object' => 'chat.completion', + 'model' => 'local-model', + 'choices' => [[ + 'index' => 0, + 'message' => ['role' => 'assistant', 'content' => null, 'tool_calls' => [$this->fakeOpenAiCompatibleToolCall('call_123', '{}')]], + 'finish_reason' => 'stop', + ]], + ]) + ->pushResponse($this->fakeOpenAiCompatibleResponse('Done')); + + $response = (new MultiStepToolAgent)->prompt('Generate', provider: 'openai-compatible'); + + $this->assertCount(1, $response->toolResults); + $this->assertSame('Done', $response->text); + } + + public function testStreamingRunsAToolCallThatArrivesWithoutAnIndex(): void + { + Http::fakeSequence() + ->pushResponse($this->fakeOpenAiCompatibleToolCallStream([ + [$this->fakeOpenAiCompatibleToolCall('call_123', '')], + [['function' => ['arguments' => '{}']]], + ], 'tool_calls')) + ->pushResponse($this->fakeOpenAiCompatibleStream()); + + $events = collect((new MultiStepToolAgent)->stream('Generate', provider: 'openai-compatible')); + + $this->assertCount(1, $events->filter(fn ($event): bool => $event instanceof ToolCallEvent)); + $this->assertCount(1, $events->filter(fn ($event): bool => $event instanceof ToolResultEvent)); + } + + public function testStreamingRunsAToolCallThatFinishesWithStop(): void + { + Http::fakeSequence() + ->pushResponse($this->fakeOpenAiCompatibleToolCallStream([ + [['index' => 0] + $this->fakeOpenAiCompatibleToolCall('call_123', '{}')], + ], 'stop')) + ->pushResponse($this->fakeOpenAiCompatibleStream()); + + $events = collect((new MultiStepToolAgent)->stream('Generate', provider: 'openai-compatible')); + + $this->assertCount(1, $events->filter(fn ($event): bool => $event instanceof ToolCallEvent)); + $this->assertCount(1, $events->filter(fn ($event): bool => $event instanceof ToolResultEvent)); + } + + public function testStreamingRunsTwoWholeToolCallsThatArriveWithoutAnIndex(): void + { + Http::fakeSequence() + ->pushResponse($this->fakeOpenAiCompatibleToolCallStream([ + [$this->fakeOpenAiCompatibleToolCall('call_1', '{}')], + [$this->fakeOpenAiCompatibleToolCall('call_2', '{}')], + ], 'tool_calls')) + ->pushResponse($this->fakeOpenAiCompatibleStream()); + + $events = collect((new MultiStepToolAgent)->stream('Generate', provider: 'openai-compatible')); + + $this->assertCount(2, $events->filter(fn ($event): bool => $event instanceof ToolCallEvent)); + $this->assertCount(2, $events->filter(fn ($event): bool => $event instanceof ToolResultEvent)); + } + + public function testStreamingRoutesAnIdentifiedFragmentWithoutAnIndexToItsOwnCall(): void + { + Http::fakeSequence() + ->pushResponse($this->fakeOpenAiCompatibleToolCallStream([ + [$this->fakeOpenAiCompatibleToolCall('call_1', '{"min":')], + [$this->fakeOpenAiCompatibleToolCall('call_2', '{}')], + [['id' => 'call_1', 'function' => ['arguments' => '1}']]], + ], 'tool_calls')) + ->pushResponse($this->fakeOpenAiCompatibleStream()); + + $events = collect((new MultiStepToolAgent)->stream('Generate', provider: 'openai-compatible')); + + $toolCalls = $events->filter(fn ($event): bool => $event instanceof ToolCallEvent) + ->map(fn (ToolCallEvent $event): array => [$event->toolCall->id, $event->toolCall->arguments]) + ->values() + ->all(); + + $this->assertSame([['call_1', ['min' => 1]], ['call_2', []]], $toolCalls); + } + + public function testStreamingDiscardsToolCallsCutOffByTheLengthLimit(): void + { + Http::fake(['*' => $this->fakeOpenAiCompatibleToolCallStream([ + [['index' => 0] + $this->fakeOpenAiCompatibleToolCall('call_123', '{"min":')], + ], 'length')]); + + $events = collect((new MultiStepToolAgent)->stream('Generate', provider: 'openai-compatible')); + + $this->assertEmpty($events->filter(fn ($event): bool => $event instanceof ToolCallEvent)); + $this->assertEmpty($events->filter(fn ($event): bool => $event instanceof ToolResultEvent)); + } + /** * Create a chat completion response. */ @@ -475,6 +575,41 @@ protected function fakeOpenAiCompatibleResponse(string $content): PromiseInterfa ]); } + /** + * Create a tool call for the fixed number generator. + */ + protected function fakeOpenAiCompatibleToolCall(string $id, string $arguments): array + { + return [ + 'id' => $id, + 'type' => 'function', + 'function' => ['name' => 'FixedNumberGenerator', 'arguments' => $arguments], + ]; + } + + /** + * Create a chat stream of tool call deltas. + * + * @param array> $toolCallDeltas + */ + protected function fakeOpenAiCompatibleToolCallStream(array $toolCallDeltas, string $finish): PromiseInterface + { + $chunk = fn (array $delta, ?string $finish = null): string => 'data: ' . json_encode([ + 'id' => 'chatcmpl-123', + 'object' => 'chat.completion.chunk', + 'model' => 'local-model', + 'choices' => [['index' => 0, 'delta' => $delta, 'finish_reason' => $finish]], + ]); + + $body = implode("\n\n", [ + ...array_map(fn (array $toolCalls): string => $chunk(['tool_calls' => $toolCalls]), $toolCallDeltas), + $chunk([], $finish), + 'data: [DONE]', + ]) . "\n\n"; + + return Http::response($body, 200, ['Content-Type' => 'text/event-stream']); + } + /** * Create a completed chat stream. */ diff --git a/tests/Integration/Ai/AgentTest.php b/tests/Integration/Ai/AgentTest.php index b4b1e25e4..7711143e5 100644 --- a/tests/Integration/Ai/AgentTest.php +++ b/tests/Integration/Ai/AgentTest.php @@ -27,6 +27,8 @@ use Hypervel\Ai\Responses\StreamedAgentResponse; use Hypervel\Ai\Skills\Skill; use Hypervel\Ai\Streaming\Events\TextDelta; +use Hypervel\Ai\Streaming\Events\ToolCall as ToolCallEvent; +use Hypervel\Ai\Streaming\Events\ToolResult as ToolResultEvent; use Hypervel\Ai\ToolChoice; use Hypervel\Ai\Tools\LoadSkill; use Hypervel\Contracts\JsonSchema\JsonSchema; @@ -37,6 +39,7 @@ use Hypervel\Testbench\Attributes\WithConfig; use Hypervel\Tests\Ai\Fixtures\Agents\AssistantAgent; use Hypervel\Tests\Ai\Fixtures\Agents\ConversationalAgent; +use Hypervel\Tests\Ai\Fixtures\Agents\MultiStepToolAgent; use Hypervel\Tests\Ai\Fixtures\Agents\StructuredAgent; use Hypervel\Tests\Ai\Fixtures\Agents\ToolUsingAgent; use Hypervel\Tests\Ai\Fixtures\Tools\FixedNumberGenerator; @@ -512,6 +515,49 @@ public function testOpenAiReplaysEchoedOutputBlocksOnAStoreFalseToolCallContinua $this->assertCount(1, $response->toolCalls); } + public function testOpenAiCompatibleStreamsParallelToolCallsSentWithoutAnIndexAndFinishedWithStop(): void + { + requiresApiKey('GEMINI_API_KEY'); + + config(['ai.providers.openai-compatible' => [ + ...config('ai.providers.openai-compatible'), + 'url' => 'https://generativelanguage.googleapis.com/v1beta/openai', + 'key' => config('ai.providers.gemini.key'), + ]]); + + $response = (new MultiStepToolAgent)->stream( + 'Generate two numbers by calling the tool twice in parallel, then reply with both numbers.', + provider: 'openai-compatible', + model: 'gemini-3-flash-preview', + ); + + $events = collect($response); + + $this->assertCount(2, $events->whereInstanceOf(ToolCallEvent::class)); + $this->assertCount(2, $events->whereInstanceOf(ToolResultEvent::class)); + $this->assertStringContainsString('72019', $response->text); + } + + public function testOpenAiCompatiblePromptsWithAToolCallFinishedWithStop(): void + { + requiresApiKey('GEMINI_API_KEY'); + + config(['ai.providers.openai-compatible' => [ + ...config('ai.providers.openai-compatible'), + 'url' => 'https://generativelanguage.googleapis.com/v1beta/openai', + 'key' => config('ai.providers.gemini.key'), + ]]); + + $response = (new MultiStepToolAgent)->prompt( + 'Generate a number by calling the tool, then reply with the number.', + provider: 'openai-compatible', + model: 'gemini-3-flash-preview', + ); + + $this->assertCount(1, $response->toolResults); + $this->assertStringContainsString('72019', $response->text); + } + #[DataProviderExternal(Providers::class, 'reasoning')] public function testAgentsSurfaceTheReasoningAPromptedTurnProduced(string $provider, string $apiKey, string $model, array $options): void { From 8cf1563fb4f9fa7245c1aacb486e3bf4465ed0db Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:56:16 +0000 Subject: [PATCH 06/17] Hint at a missing or invalid API key when a provider rejects it A 401 from an AI provider now raises InvalidApiKeyException, a RequestException whose message names the provider and says the key is missing or invalid, before the credit and rate-limit checks run. Gemini and xAI report a rejected key with their own statuses and messages, so their file, store, text and image gateways use provider-specific error handling traits. The exception is not failoverable. Port laravel/ai#1215 at a2cb93a2. Hypervel's RequestException always has a response, so upstream's null-safe reads are dropped. Ported the failover error, Gemini and xAI error handling, Gemini file and store gateway, and xAI image generation tests. Validation: the changed test files pass; formatting and full static analysis pass. --- .../src/Exceptions/InvalidApiKeyException.php | 27 +++++++++ .../Concerns/HandlesFailoverErrors.php | 17 ++++++ .../Gemini/Concerns/HandlesGeminiErrors.php | 32 ++++++++++ .../src/Gateway/Gemini/GeminiFileGateway.php | 3 +- src/ai/src/Gateway/Gemini/GeminiGateway.php | 3 +- .../src/Gateway/Gemini/GeminiStoreGateway.php | 3 +- .../Gateway/Xai/Concerns/HandlesXaiErrors.php | 27 +++++++++ src/ai/src/Gateway/Xai/XaiGateway.php | 3 +- src/ai/src/Gateway/Xai/XaiImageGateway.php | 3 +- .../Providers/Gemini/ErrorHandlingTest.php | 60 +++++++++++++++++++ .../Providers/Gemini/FileGatewayTest.php | 18 ++++++ .../Providers/Gemini/StoreGatewayTest.php | 18 ++++++ .../Providers/Xai/ErrorHandlingTest.php | 27 +++++++++ .../Providers/Xai/ImageGenerationTest.php | 16 +++++ .../Concerns/HandlesFailoverErrorsTest.php | 11 ++++ 15 files changed, 258 insertions(+), 10 deletions(-) create mode 100644 src/ai/src/Exceptions/InvalidApiKeyException.php create mode 100644 src/ai/src/Gateway/Gemini/Concerns/HandlesGeminiErrors.php create mode 100644 src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php diff --git a/src/ai/src/Exceptions/InvalidApiKeyException.php b/src/ai/src/Exceptions/InvalidApiKeyException.php new file mode 100644 index 000000000..266e57086 --- /dev/null +++ b/src/ai/src/Exceptions/InvalidApiKeyException.php @@ -0,0 +1,27 @@ +provider}]. " . parent::prepareMessage($response); + } +} diff --git a/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php b/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php index 1a32f36f9..b28f3d4f6 100644 --- a/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php +++ b/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php @@ -6,6 +6,7 @@ use Closure; use Hypervel\Ai\Exceptions\InsufficientCreditsException; +use Hypervel\Ai\Exceptions\InvalidApiKeyException; use Hypervel\Ai\Exceptions\ProviderConnectionException; use Hypervel\Ai\Exceptions\ProviderOverloadedException; use Hypervel\Ai\Exceptions\RateLimitedException; @@ -41,6 +42,14 @@ protected function withErrorHandling(string $providerName, Closure $callback): m } catch (RequestException $requestException) { $status = $requestException->response->status(); + if ($this->isInvalidApiKey($requestException)) { + throw new InvalidApiKeyException( + $providerName, + $requestException->response, + $requestException->truncateExceptionsAt + ); + } + if ($this->isInsufficientCredits($requestException)) { throw InsufficientCreditsException::forProvider( $providerName, @@ -109,6 +118,14 @@ protected function retryAfterSeconds(Throwable $exception): ?int return ctype_digit($retryAfter) && (int) $retryAfter <= 10 ? (int) $retryAfter : null; } + /** + * Determine if the provider rejected the request for a missing or invalid API key. + */ + protected function isInvalidApiKey(RequestException $exception): bool + { + return $exception->response->status() === 401; + } + /** * Determine if the response is a 402, or a 429 insufficient credits or quota error rather than a rate limit. */ diff --git a/src/ai/src/Gateway/Gemini/Concerns/HandlesGeminiErrors.php b/src/ai/src/Gateway/Gemini/Concerns/HandlesGeminiErrors.php new file mode 100644 index 000000000..ed721501d --- /dev/null +++ b/src/ai/src/Gateway/Gemini/Concerns/HandlesGeminiErrors.php @@ -0,0 +1,32 @@ +response->json('0.error') ?? $exception->response->json('error'); + + $message = is_string($error['message'] ?? null) ? $error['message'] : ''; + + return match ($exception->response->status()) { + 401 => true, + 400 => collect($error['details'] ?? [])->contains('reason', 'API_KEY_INVALID'), + 403 => Str::contains($message, ['unregistered callers', 'reported as leaked']), + default => false, + }; + } +} diff --git a/src/ai/src/Gateway/Gemini/GeminiFileGateway.php b/src/ai/src/Gateway/Gemini/GeminiFileGateway.php index 57dc19c95..5aaef9d9a 100644 --- a/src/ai/src/Gateway/Gemini/GeminiFileGateway.php +++ b/src/ai/src/Gateway/Gemini/GeminiFileGateway.php @@ -10,7 +10,6 @@ use Hypervel\Ai\Enums\Lab; use Hypervel\Ai\Gateway\Concerns\CreatesClient; use Hypervel\Ai\Gateway\Concerns\EncodesResourceIds; -use Hypervel\Ai\Gateway\Concerns\HandlesFailoverErrors; use Hypervel\Ai\Gateway\Concerns\PreparesStorableFiles; use Hypervel\Ai\Providers\Provider; use Hypervel\Ai\Responses\FileResponse; @@ -20,9 +19,9 @@ class GeminiFileGateway implements FileGateway { + use Concerns\HandlesGeminiErrors; use CreatesClient; use EncodesResourceIds; - use HandlesFailoverErrors; use PreparesStorableFiles; /** diff --git a/src/ai/src/Gateway/Gemini/GeminiGateway.php b/src/ai/src/Gateway/Gemini/GeminiGateway.php index 23dbc16cb..57bce9b17 100644 --- a/src/ai/src/Gateway/Gemini/GeminiGateway.php +++ b/src/ai/src/Gateway/Gemini/GeminiGateway.php @@ -14,7 +14,6 @@ use Hypervel\Ai\Contracts\Providers\TextProvider; use Hypervel\Ai\Contracts\Providers\TranscriptionProvider; use Hypervel\Ai\Files\Image as ImageFile; -use Hypervel\Ai\Gateway\Concerns\HandlesFailoverErrors; use Hypervel\Ai\Gateway\Concerns\ParsesServerSentEvents; use Hypervel\Ai\Gateway\Concerns\WrapsPcmAudio; use Hypervel\Ai\Gateway\StepContext; @@ -39,13 +38,13 @@ class GeminiGateway implements Gateway, StepTextGateway { use Concerns\BuildsTextRequests; use Concerns\CreatesGeminiClient; + use Concerns\HandlesGeminiErrors; use Concerns\HandlesTextStreaming; use Concerns\MapsAttachments; use Concerns\MapsEmbeddingInputs; use Concerns\MapsMessages; use Concerns\MapsTools; use Concerns\ParsesTextResponses; - use HandlesFailoverErrors; use ParsesServerSentEvents; use WrapsPcmAudio; diff --git a/src/ai/src/Gateway/Gemini/GeminiStoreGateway.php b/src/ai/src/Gateway/Gemini/GeminiStoreGateway.php index e48f3f09f..b79342941 100644 --- a/src/ai/src/Gateway/Gemini/GeminiStoreGateway.php +++ b/src/ai/src/Gateway/Gemini/GeminiStoreGateway.php @@ -11,7 +11,6 @@ use Hypervel\Ai\Exceptions\AiException; use Hypervel\Ai\Gateway\Concerns\CreatesClient; use Hypervel\Ai\Gateway\Concerns\EncodesResourceIds; -use Hypervel\Ai\Gateway\Concerns\HandlesFailoverErrors; use Hypervel\Ai\Providers\Provider; use Hypervel\Ai\Responses\Data\StoreFileCounts; use Hypervel\Ai\Store; @@ -24,9 +23,9 @@ class GeminiStoreGateway implements StoreGateway { + use Concerns\HandlesGeminiErrors; use CreatesClient; use EncodesResourceIds; - use HandlesFailoverErrors; /** * Get a vector store by its ID. diff --git a/src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php b/src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php new file mode 100644 index 000000000..c4367f9ce --- /dev/null +++ b/src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php @@ -0,0 +1,27 @@ +response->json('error'); + + return match ($exception->response->status()) { + 401 => true, + 400 => is_string($error) && str_starts_with($error, 'Incorrect API key'), + default => false, + }; + } +} diff --git a/src/ai/src/Gateway/Xai/XaiGateway.php b/src/ai/src/Gateway/Xai/XaiGateway.php index 881c7b844..2bdc73afc 100644 --- a/src/ai/src/Gateway/Xai/XaiGateway.php +++ b/src/ai/src/Gateway/Xai/XaiGateway.php @@ -13,7 +13,6 @@ use Hypervel\Ai\Contracts\Providers\ImageProvider; use Hypervel\Ai\Contracts\Providers\TextProvider; use Hypervel\Ai\Contracts\Providers\TranscriptionProvider; -use Hypervel\Ai\Gateway\Concerns\HandlesFailoverErrors; use Hypervel\Ai\Gateway\Concerns\ParsesServerSentEvents; use Hypervel\Ai\Gateway\StepContext; use Hypervel\Ai\Gateway\StepResponse; @@ -32,11 +31,11 @@ class XaiGateway implements Gateway, StepTextGateway use Concerns\BuildsTextRequests; use Concerns\CreatesXaiClient; use Concerns\HandlesTextStreaming; + use Concerns\HandlesXaiErrors; use Concerns\MapsAttachments; use Concerns\MapsMessages; use Concerns\MapsTools; use Concerns\ParsesTextResponses; - use HandlesFailoverErrors; use ParsesServerSentEvents; /** diff --git a/src/ai/src/Gateway/Xai/XaiImageGateway.php b/src/ai/src/Gateway/Xai/XaiImageGateway.php index ed3a13d5b..e3f66a269 100644 --- a/src/ai/src/Gateway/Xai/XaiImageGateway.php +++ b/src/ai/src/Gateway/Xai/XaiImageGateway.php @@ -11,7 +11,6 @@ use Hypervel\Ai\Files\Image; use Hypervel\Ai\Files\ProviderImage; use Hypervel\Ai\Files\RemoteImage; -use Hypervel\Ai\Gateway\Concerns\HandlesFailoverErrors; use Hypervel\Ai\Providers\Provider; use Hypervel\Ai\Responses\Data\GeneratedImage; use Hypervel\Ai\Responses\Data\ImageUsage; @@ -23,7 +22,7 @@ class XaiImageGateway implements ImageGateway { use Concerns\CreatesXaiClient; - use HandlesFailoverErrors; + use Concerns\HandlesXaiErrors; /** * Generate an image. diff --git a/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php b/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php index bdd08883b..a046b9cd7 100644 --- a/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php +++ b/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php @@ -6,6 +6,7 @@ use GuzzleHttp\Promise\PromiseInterface; use Hypervel\Ai\Exceptions\AiException; +use Hypervel\Ai\Exceptions\InvalidApiKeyException; use Hypervel\Ai\Exceptions\ProviderConnectionException; use Hypervel\Ai\Exceptions\ProviderOverloadedException; use Hypervel\Ai\Exceptions\RateLimitedException; @@ -193,4 +194,63 @@ public function testConnectionFailureFailsOverToTheNextProvider(): void $this->assertSame('Recovered on the backup provider', $response->text); } + + #[DataProvider('rejectedApiKeys')] + public function testARejectedApiKeyHintsAtTheKey(int $status, array $body): void + { + Http::fake(['generativelanguage.googleapis.com/*' => Http::response($body, $status)]); + + $this->expectException(InvalidApiKeyException::class); + $this->expectExceptionMessage('Missing or invalid API key for AI provider [gemini].'); + + (new AssistantAgent)->prompt('Hi', provider: 'gemini'); + } + + /** + * Provide Gemini's rejected API key responses. + */ + public static function rejectedApiKeys(): array + { + return [ + 'unauthenticated' => [401, ['error' => [ + 'code' => 'authentication', + 'message' => 'Request had invalid authentication credentials.', + ]]], + 'invalid key' => [400, [['error' => [ + 'code' => 400, + 'message' => 'API key not valid. Please pass a valid API key.', + 'status' => 'INVALID_ARGUMENT', + 'details' => [['@type' => 'type.googleapis.com/google.rpc.ErrorInfo', 'reason' => 'API_KEY_INVALID']], + ]]]], + 'missing key' => [403, [['error' => [ + 'code' => 403, + 'message' => "Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.", + 'status' => 'PERMISSION_DENIED', + ]]]], + 'leaked key' => [403, [['error' => [ + 'code' => 403, + 'message' => 'Your API key was reported as leaked. Please use another API key.', + 'status' => 'PERMISSION_DENIED', + ]]]], + ]; + } + + public function testAPermissionErrorUnrelatedToTheApiKeyStaysARequestException(): void + { + Http::fake([ + 'generativelanguage.googleapis.com/*' => Http::response([['error' => [ + 'code' => 403, + 'message' => 'Your project has been denied access. Please contact support.', + 'status' => 'PERMISSION_DENIED', + ]]], 403), + ]); + + try { + (new AssistantAgent)->prompt('Hi', provider: 'gemini'); + + $this->fail('Expected a RequestException.'); + } catch (RequestException $exception) { + $this->assertNotInstanceOf(InvalidApiKeyException::class, $exception); + } + } } diff --git a/tests/Ai/Feature/Providers/Gemini/FileGatewayTest.php b/tests/Ai/Feature/Providers/Gemini/FileGatewayTest.php index a0fbe2e2f..cc78c58b7 100644 --- a/tests/Ai/Feature/Providers/Gemini/FileGatewayTest.php +++ b/tests/Ai/Feature/Providers/Gemini/FileGatewayTest.php @@ -4,6 +4,7 @@ namespace Hypervel\Tests\Ai\Feature\Providers\Gemini; +use Hypervel\Ai\Exceptions\InvalidApiKeyException; use Hypervel\Ai\Files; use Hypervel\Ai\Files\Document; use Hypervel\Contracts\Foundation\Application; @@ -197,4 +198,21 @@ public function testDeleteFileRejectsAPrefixedDotSegmentId(): void Http::assertNothingSent(); } + + public function testARejectedApiKeyHintsAtTheKey(): void + { + Http::fake([ + 'generativelanguage.googleapis.com/*' => Http::response(['error' => [ + 'code' => 400, + 'message' => 'API key not valid. Please pass a valid API key.', + 'status' => 'INVALID_ARGUMENT', + 'details' => [['@type' => 'type.googleapis.com/google.rpc.ErrorInfo', 'reason' => 'API_KEY_INVALID']], + ]], 400), + ]); + + $this->expectException(InvalidApiKeyException::class); + $this->expectExceptionMessage('Missing or invalid API key for AI provider [gemini].'); + + Files::get('abc123', provider: 'gemini'); + } } diff --git a/tests/Ai/Feature/Providers/Gemini/StoreGatewayTest.php b/tests/Ai/Feature/Providers/Gemini/StoreGatewayTest.php index ce02c0e95..00ef6dcbf 100644 --- a/tests/Ai/Feature/Providers/Gemini/StoreGatewayTest.php +++ b/tests/Ai/Feature/Providers/Gemini/StoreGatewayTest.php @@ -6,6 +6,7 @@ use Hypervel\Ai\AiManager; use Hypervel\Ai\Exceptions\AiException; +use Hypervel\Ai\Exceptions\InvalidApiKeyException; use Hypervel\Ai\Providers\GeminiProvider; use Hypervel\Ai\Stores; use Hypervel\Contracts\Foundation\Application; @@ -457,4 +458,21 @@ public function testRemoveFileRebuildsAFullDocumentPathFromEncodedSegments(): vo Http::assertSent(fn (Request $request): bool => $request->method() === 'DELETE' && str_starts_with((string) $request->url(), 'https://generativelanguage.googleapis.com/v1beta/fileSearchStores/store123/documents/doc456%3Fforce%3Dfalse')); } + + public function testARejectedApiKeyHintsAtTheKey(): void + { + Http::fake([ + 'generativelanguage.googleapis.com/*' => Http::response(['error' => [ + 'code' => 400, + 'message' => 'API key not valid. Please pass a valid API key.', + 'status' => 'INVALID_ARGUMENT', + 'details' => [['@type' => 'type.googleapis.com/google.rpc.ErrorInfo', 'reason' => 'API_KEY_INVALID']], + ]], 400), + ]); + + $this->expectException(InvalidApiKeyException::class); + $this->expectExceptionMessage('Missing or invalid API key for AI provider [gemini].'); + + Stores::get('store123', provider: 'gemini'); + } } diff --git a/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php b/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php index f2e3d5b0b..cc3465e0e 100644 --- a/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php +++ b/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php @@ -5,6 +5,7 @@ namespace Hypervel\Tests\Ai\Feature\Providers\Xai; use Hypervel\Ai\Exceptions\AiException; +use Hypervel\Ai\Exceptions\InvalidApiKeyException; use Hypervel\Ai\Exceptions\ProviderOverloadedException; use Hypervel\Ai\Exceptions\RateLimitedException; use Hypervel\Contracts\Foundation\Application; @@ -12,6 +13,7 @@ use Hypervel\Support\Facades\Http; use Hypervel\Tests\Ai\Fixtures\Agents\AssistantAgent; use Hypervel\Tests\Ai\TestCase; +use PHPUnit\Framework\Attributes\DataProvider; class ErrorHandlingTest extends TestCase { @@ -104,4 +106,29 @@ public function testFailedStatusResponseThrowsAiException(): void (new AssistantAgent)->prompt('Hi', provider: 'xai'); } + + #[DataProvider('rejectedApiKeys')] + public function testARejectedApiKeyHintsAtTheKey(int $status, array $body): void + { + Http::fake(['*' => Http::response($body, $status)]); + + $this->expectException(InvalidApiKeyException::class); + $this->expectExceptionMessage('Missing or invalid API key for AI provider [xai].'); + + (new AssistantAgent)->prompt('Hi', provider: 'xai'); + } + + /** + * Provide xAI's rejected API key responses. + */ + public static function rejectedApiKeys(): array + { + return [ + 'unauthenticated' => [401, ['error' => 'Missing or invalid authorization token.']], + 'incorrect key' => [400, [ + 'code' => 'invalid-argument', + 'error' => 'Incorrect API key provided. You can obtain an API key from https://console.x.ai.', + ]], + ]; + } } diff --git a/tests/Ai/Feature/Providers/Xai/ImageGenerationTest.php b/tests/Ai/Feature/Providers/Xai/ImageGenerationTest.php index 19c9bef48..1711d7f62 100644 --- a/tests/Ai/Feature/Providers/Xai/ImageGenerationTest.php +++ b/tests/Ai/Feature/Providers/Xai/ImageGenerationTest.php @@ -6,6 +6,7 @@ use Closure; use GuzzleHttp\Promise\PromiseInterface; +use Hypervel\Ai\Exceptions\InvalidApiKeyException; use Hypervel\Ai\Exceptions\ProviderOverloadedException; use Hypervel\Ai\Exceptions\RateLimitedException; use Hypervel\Ai\Files\Base64Image; @@ -244,4 +245,19 @@ public function testImageHttpErrorResponseThrowsRequestException(): void Image::of('A red apple')->generate(provider: 'xai', model: 'grok-imagine-image'); } + + public function testImageRejectedApiKeyHintsAtTheKey(): void + { + Http::fake([ + 'api.x.ai/*' => Http::response([ + 'code' => 'invalid-argument', + 'error' => 'Incorrect API key provided. You can obtain an API key from https://console.x.ai.', + ], 400), + ]); + + $this->expectException(InvalidApiKeyException::class); + $this->expectExceptionMessage('Missing or invalid API key for AI provider [xai].'); + + Image::of('A red apple')->generate(provider: 'xai', model: 'grok-imagine-image'); + } } diff --git a/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php b/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php index 6e5fa7f50..2dfbe01ee 100644 --- a/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php +++ b/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php @@ -6,6 +6,7 @@ use GuzzleHttp\Psr7\Response as Psr7Response; use Hypervel\Ai\Exceptions\InsufficientCreditsException; +use Hypervel\Ai\Exceptions\InvalidApiKeyException; use Hypervel\Ai\Exceptions\ProviderOverloadedException; use Hypervel\Ai\Exceptions\RateLimitedException; use Hypervel\Ai\Gateway\Concerns\HandlesFailoverErrors; @@ -19,6 +20,16 @@ class HandlesFailoverErrorsTest extends TestCase { use HandlesFailoverErrors; + public function test401HintsAtAMissingOrInvalidApiKey(): void + { + $this->expectException(InvalidApiKeyException::class); + $this->expectExceptionMessage("Missing or invalid API key for AI provider [openai]. HTTP request returned status code 401:\n{\"error\":{\"message\":\"Incorrect API key provided.\"}}\n"); + + $this->withErrorHandling('openai', fn (): never => throw $this->failoverableException(401, [ + 'error' => ['message' => 'Incorrect API key provided.'], + ])); + } + #[DataProvider('overloadStatuses')] public function testOverridingOverloadedStatusCodesReplacesTheDefault503(int $status, string $exception): void { From dc5ae4303848da09df60bb0fca154d65b841ba10 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:56:42 +0000 Subject: [PATCH 07/17] Add Gemini classification and port AI provider and broadcasting fixes These upstream changes share the AI documentation page, the OpenAI gateway, the Anthropic tool-mapping tests and the integration provider datasets, so they land together. Ported from laravel/ai at a2cb93a2 and laravel/docs 13.x at eabbe579. laravel/ai#1208 and laravel/docs#11439: broadcast stream events use their event type as the broadcast name, and a provider stream error is broadcast as "error", so Echo listeners can subscribe by name. A failed broadcastOnQueue operation keeps broadcasting "stream_failed". Ported the broadcast-name test and the documented event names and Echo example. laravel/ai#1212: OpenAI custom voice IDs (voice_...) are sent as a voice object, as the speech API requires. Ported the audio tests. laravel/ai#1214: Anthropic streams emit one citation per URL for cited web search results and fetched pages, and buffered responses no longer report uncited search results as citations. Ported the streaming and tool-mapping citation tests. laravel/ai#1231: Gemini supports classification through its Decisions API, with gemini-decision-1 as the default model and image attachments, including images already stored with Gemini. Shared classification gains payload and usage hooks, and declared score levels take precedence over a returned legend. Hypervel keeps numeric choice labels as JSON object members for Gemini too. Upstream defects fixed here: numeric question names sent the question map as a JSON list to Gemini, TypeSafe and OpenRouter; empty Boolean criteria were sent as a JSON list; and state that cannot be encoded as JSON failed with a type error in the Gemini and OpenAI gateways instead of a JsonException. Ported the Gemini classification tests and integration datasets, with tests for each corrected defect. Upstream has no docs for this, so the classification docs now list Gemini. laravel/ai#1217: OpenAI's default transcription model is gpt-transcribe. gpt-transcribe models reject diarization and send their languages as languages[] fields; the Groq and OpenRouter diarization errors no longer suggest OpenAI. The diarization docs example now names gpt-4o-transcribe-diarize, since the default model would reject it. Ported the transcription tests and removed OpenAI from the integration diarization dataset. laravel/ai#1219: Anthropic tools marked #[Strict] are sent with strict and additionalProperties: false, with unsupported schema constraints moved into descriptions, when native structured output is enabled. Ported the tool-mapping tests. Upstream has no docs for the Strict attribute, so the tools docs now describe strict tool and structured-output schemas and their limits. Validation: the changed test files pass; formatting and full static analysis pass. --- .../Concerns/HandlesTextStreaming.php | 36 +- .../Gateway/Anthropic/Concerns/MapsTools.php | 19 +- .../Concerns/ParsesTextResponses.php | 9 - .../src/Gateway/Concerns/AnswersQuestions.php | 47 ++- .../Gemini/GeminiClassificationGateway.php | 157 +++++++++ src/ai/src/Gateway/Groq/GroqGateway.php | 2 +- .../OpenAi/OpenAiClassificationGateway.php | 2 +- src/ai/src/Gateway/OpenAi/OpenAiGateway.php | 22 +- .../Gateway/OpenRouter/OpenRouterGateway.php | 2 +- src/ai/src/Providers/GeminiProvider.php | 33 +- src/ai/src/Providers/OpenAiProvider.php | 2 +- src/ai/src/Streaming/Events/Error.php | 8 + src/ai/src/Streaming/Events/StreamEvent.php | 10 +- src/docs/ai-sdk.md | 53 ++- tests/Ai/Feature/BroadcastAgentTest.php | 15 + .../Providers/Anthropic/StreamingTest.php | 42 ++- .../Providers/Anthropic/ToolMappingTest.php | 156 +++++++++ .../Providers/Gemini/ClassificationTest.php | 330 ++++++++++++++++++ .../Providers/Groq/TranscriptionTest.php | 2 +- .../Ai/Feature/Providers/OpenAi/AudioTest.php | 10 +- .../Providers/OpenAi/ClassificationTest.php | 12 + .../Providers/OpenAi/TranscriptionTest.php | 78 ++++- .../OpenRouter/TranscriptionTest.php | 2 +- .../Providers/TypeSafe/ClassificationTest.php | 12 +- tests/Integration/Ai/Fixtures/Providers.php | 3 +- 25 files changed, 1001 insertions(+), 63 deletions(-) create mode 100644 src/ai/src/Gateway/Gemini/GeminiClassificationGateway.php create mode 100644 tests/Ai/Feature/Providers/Gemini/ClassificationTest.php diff --git a/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php b/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php index 4b7f7a771..46646a237 100644 --- a/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php +++ b/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php @@ -91,6 +91,7 @@ protected function processTextStream( $messageUsage = []; $usage = null; $stopReason = ''; + $citedUrls = []; $emitTextStart = function () use (&$textStartEmitted, $messageId, $invocationId): ?StreamEvent { if ($textStartEmitted) { @@ -121,6 +122,21 @@ protected function processTextStream( ))->withInvocationId($invocationId); }; + $emitCitation = function (UrlCitation $citation) use (&$citedUrls, $messageId, $invocationId): ?StreamEvent { + if (in_array($citation->url, $citedUrls, true)) { + return null; + } + + $citedUrls[] = $citation->url; + + return (new CitationEvent( + $this->generateEventId(), + $messageId, + $citation, + time(), + ))->withInvocationId($invocationId); + }; + foreach ($this->parseServerSentEvents($streamBody) as $data) { $type = $data['type'] ?? ''; @@ -196,13 +212,9 @@ protected function processTextStream( } elseif ($this->isProviderToolResultBlock($blockType)) { $fetchResult = $data['content_block']['content'] ?? []; - if ($blockType === 'web_fetch_tool_result' && ($fetchResult['type'] ?? '') === 'web_fetch_result' && filled($fetchResult['url'] ?? null)) { - yield (new CitationEvent( - $this->generateEventId(), - $messageId, - new UrlCitation($fetchResult['url'], $fetchResult['content']['title'] ?? null), - time(), - ))->withInvocationId($invocationId); + if ($blockType === 'web_fetch_tool_result' && ($fetchResult['type'] ?? '') === 'web_fetch_result' && filled($fetchResult['url'] ?? null) + && ($event = $emitCitation(new UrlCitation($fetchResult['url'], $fetchResult['content']['title'] ?? null))) instanceof StreamEvent) { + yield $event; } yield (new ProviderToolEvent( @@ -270,13 +282,9 @@ protected function processTextStream( } elseif ($deltaType === 'citations_delta' && $currentBlockType === 'text') { $citationData = $data['delta']['citation'] ?? null; - if ($citationData && ($citationData['type'] ?? '') === 'web_search_result_location') { - yield (new CitationEvent( - $this->generateEventId(), - $messageId, - new UrlCitation($citationData['url'] ?? '', $citationData['title'] ?? null), - time(), - ))->withInvocationId($invocationId); + if ($citationData && ($citationData['type'] ?? '') === 'web_search_result_location' + && ($event = $emitCitation(new UrlCitation($citationData['url'] ?? '', $citationData['title'] ?? null))) instanceof StreamEvent) { + yield $event; } } elseif ($deltaType === 'input_json_delta') { $partial = (string) ($data['delta']['partial_json'] ?? ''); diff --git a/src/ai/src/Gateway/Anthropic/Concerns/MapsTools.php b/src/ai/src/Gateway/Anthropic/Concerns/MapsTools.php index 4d54acb56..f03b2c1be 100644 --- a/src/ai/src/Gateway/Anthropic/Concerns/MapsTools.php +++ b/src/ai/src/Gateway/Anthropic/Concerns/MapsTools.php @@ -4,11 +4,13 @@ namespace Hypervel\Ai\Gateway\Anthropic\Concerns; +use Hypervel\Ai\Attributes\Strict; use Hypervel\Ai\Contracts\Providers\SupportsCodeExecution; use Hypervel\Ai\Contracts\Providers\SupportsWebFetch; use Hypervel\Ai\Contracts\Providers\SupportsWebSearch; use Hypervel\Ai\Contracts\Tool; use Hypervel\Ai\Enums\Lab; +use Hypervel\Ai\Gateway\Anthropic\AnthropicSchemaSanitizer; use Hypervel\Ai\ObjectSchema; use Hypervel\Ai\Providers\Provider; use Hypervel\Ai\Providers\Tools\CodeExecution; @@ -50,12 +52,12 @@ protected function mapTools(array $tools, Provider $provider): array ]; foreach ($tool->tools as $deferred) { - $mapped[] = $this->mapTool($deferred, defer: true); + $mapped[] = $this->mapTool($deferred, $provider, defer: true); } } elseif ($tool instanceof ProviderTool) { $mapped[] = $this->mapProviderTool($tool, $provider); } elseif ($tool instanceof Tool) { - $mapped[] = $this->mapTool($tool); + $mapped[] = $this->mapTool($tool, $provider); } } @@ -65,8 +67,10 @@ protected function mapTools(array $tools, Provider $provider): array /** * Map a regular tool to an Anthropic tool definition. */ - protected function mapTool(Tool $tool, bool $defer = false): array + protected function mapTool(Tool $tool, Provider $provider, bool $defer = false): array { + $strict = Strict::isAppliedTo($tool) && $this->supportsNativeStructuredOutput($provider); + $schema = $tool->schema(new JsonSchemaTypeFactory); $inputSchema = ['type' => 'object', 'properties' => (object) []]; @@ -74,6 +78,10 @@ protected function mapTool(Tool $tool, bool $defer = false): array if (filled($schema)) { $schemaArray = (new ObjectSchema($schema))->toSchema(); + if ($strict) { + $schemaArray = AnthropicSchemaSanitizer::sanitize($schemaArray); + } + $inputSchema['properties'] = (object) ($schemaArray['properties'] ?? []); $inputSchema['required'] = $schemaArray['required'] ?? []; } @@ -84,6 +92,11 @@ protected function mapTool(Tool $tool, bool $defer = false): array 'input_schema' => $inputSchema, ]; + if ($strict) { + $definition['strict'] = true; + $definition['input_schema']['additionalProperties'] = false; + } + if ($defer) { $definition['defer_loading'] = true; } diff --git a/src/ai/src/Gateway/Anthropic/Concerns/ParsesTextResponses.php b/src/ai/src/Gateway/Anthropic/Concerns/ParsesTextResponses.php index 245244d15..d28dce7d9 100644 --- a/src/ai/src/Gateway/Anthropic/Concerns/ParsesTextResponses.php +++ b/src/ai/src/Gateway/Anthropic/Concerns/ParsesTextResponses.php @@ -211,15 +211,6 @@ protected function extractCitations(array $content): Collection foreach ($content as $block) { $blockType = $block['type'] ?? ''; - if ($blockType === 'web_search_tool_result') { - foreach ($block['search_results'] ?? [] as $result) { - $citations->push(new UrlCitation( - $result['url'] ?? '', - $result['title'] ?? null, - )); - } - } - if ($blockType === 'web_fetch_tool_result') { $result = $block['content'] ?? []; diff --git a/src/ai/src/Gateway/Concerns/AnswersQuestions.php b/src/ai/src/Gateway/Concerns/AnswersQuestions.php index 1595018b4..a4afafcec 100644 --- a/src/ai/src/Gateway/Concerns/AnswersQuestions.php +++ b/src/ai/src/Gateway/Concerns/AnswersQuestions.php @@ -46,13 +46,11 @@ public function classify( array $attachments = [], ): ClassificationResponse { /** @var ClassificationProvider&Provider $provider */ + $payload = $this->payload($model, $state, $questions, $attachments); + $response = $this->withErrorHandling( $provider->name(), - fn (): Response => $this->client($provider, $timeout)->post($this->classificationEndpoint(), array_merge($providerOptions, [ - 'model' => $model, - 'state' => $state, - 'questions' => array_map($this->mapQuestion(...), $questions), - ])), + fn (): Response => $this->client($provider, $timeout)->post($this->classificationEndpoint(), array_merge($providerOptions, $payload)), ); $data = $response->json(); @@ -67,14 +65,39 @@ public function classify( return (new ClassificationResponse( $answers, - new TextUsage( - inputTokens: $data['usage']['input_tokens'] ?? 0, - outputTokens: $data['usage']['output_tokens'] ?? 0, - ), + $this->usage($data), new Meta($provider->name(), $this->answeringModel($data, $model)), ))->withRawResponse($response); } + /** + * Build the request payload for the given questions about the state. + * + * @param array|string $state + * @param array $questions + * @param array $attachments + */ + protected function payload(string $model, string|array $state, array $questions, array $attachments): array + { + return [ + 'model' => $model, + 'state' => $state, + // Numeric-string names become integer keys, so the cast keeps the questions a JSON object. + 'questions' => (object) array_map($this->mapQuestion(...), $questions), + ]; + } + + /** + * Map the response usage to text usage. + */ + protected function usage(array $data): TextUsage + { + return new TextUsage( + inputTokens: $data['usage']['input_tokens'] ?? 0, + outputTokens: $data['usage']['output_tokens'] ?? 0, + ); + } + /** * Get the name of the model that answered the questions. */ @@ -92,11 +115,13 @@ protected function mapQuestion(Question $question): array $question instanceof Boolean => array_filter([ 'type' => 'noul', 'instructions' => $question->instructions, - 'criteria' => $question->criteria, + // Empty criteria would encode as a JSON list, so they are omitted like null criteria. + 'criteria' => $question->criteria ?: null, ], fn (mixed $value): bool => $value !== null), $question instanceof Choice => [ 'type' => 'choice', 'instructions' => $question->instructions, + // Numeric-string labels become integer keys, so the cast keeps the criteria a JSON object. 'criteria' => (object) $question->options, ], $question instanceof Score => [ @@ -119,7 +144,7 @@ protected function mapAnswer(array $answer, ?Question $question = null): ?Answer 'score' => new ScoreAnswer( $answer['score'], $this->withIntegerKeys($answer['probabilities'] ?? []), - $this->withIntegerKeys($answer['legend'] ?? ($question instanceof Score ? $question->levels : [])), + $this->withIntegerKeys($question instanceof Score ? $question->levels : ($answer['legend'] ?? [])), $answer['confidence'] ?? null, ), default => null, diff --git a/src/ai/src/Gateway/Gemini/GeminiClassificationGateway.php b/src/ai/src/Gateway/Gemini/GeminiClassificationGateway.php new file mode 100644 index 000000000..0dfa8cd96 --- /dev/null +++ b/src/ai/src/Gateway/Gemini/GeminiClassificationGateway.php @@ -0,0 +1,157 @@ +|string $state + * @param array $questions + * @param array $attachments + */ + protected function payload(string $model, string|array $state, array $questions, array $attachments): array + { + return [ + 'model' => $model, + 'input' => $this->mapInput($state, $attachments), + // Numeric-string names become integer keys, so the cast keeps the questions a JSON object. + 'questions' => (object) array_map($this->mapQuestion(...), $questions), + ]; + } + + /** + * Map the state and attachments to the decisions input. + * + * @param array|string $state + * @param array $attachments + */ + protected function mapInput(string|array $state, array $attachments): string|array + { + $text = $this->toText($state); + + if ($attachments === []) { + return $text; + } + + $content = [['type' => 'text', 'text' => $text]]; + + foreach ($attachments as $name => $attachment) { + if (is_string($name)) { + $content[] = ['type' => 'text', 'text' => "{$name}:"]; + } + + $content[] = $this->mapImage($attachment); + } + + return $content; + } + + /** + * Map an image to an image content block, referencing uploaded files by URI. + * + * @throws InvalidArgumentException if the attachment is not an uploaded file or a JPEG, PNG, GIF, WebP, HEIC, HEIF, BMP, or TIFF image with inline content + */ + protected function mapImage(File|UploadedFile $attachment): array + { + if ($attachment instanceof ProviderImage) { + return array_merge($attachment->providerOptions(Lab::Gemini), [ + 'type' => 'image', + 'uri' => $attachment->id, + ]); + } + + [$image, $content, $mime] = $this->resolveInlineImage($attachment, 'Gemini decisions', [ + 'image/jpeg' => 'JPEG', 'image/png' => 'PNG', 'image/gif' => 'GIF', 'image/webp' => 'WebP', + 'image/heic' => 'HEIC', 'image/heif' => 'HEIF', 'image/bmp' => 'BMP', 'image/tiff' => 'TIFF', + ]); + + return array_merge($image->providerOptions(Lab::Gemini), [ + 'type' => 'image', + 'data' => base64_encode($content), + 'mime_type' => $mime, + ]); + } + + /** + * Map a question to the Gemini decisions wire format. + */ + protected function mapQuestion(Question $question): array + { + return match (true) { + $question instanceof Boolean => array_filter([ + 'type' => 'noul', + 'instructions' => $this->toText($question->instructions), + // Empty criteria would encode as a JSON list, so they are omitted like null criteria. + 'criteria' => $question->criteria ? array_filter([ + 'true_description' => isset($question->criteria['true']) ? $this->toText($question->criteria['true']) : null, + 'false_description' => isset($question->criteria['false']) ? $this->toText($question->criteria['false']) : null, + ], fn (?string $value): bool => $value !== null) : null, + ], fn (mixed $value): bool => $value !== null), + $question instanceof Choice => [ + 'type' => 'choice', + 'instructions' => $this->toText($question->instructions), + // Numeric-string labels become integer keys, so the cast keeps the criteria a JSON object. + 'criteria' => (object) array_map(fn (array|string|null $description): ?string => is_null($description) ? null : $this->toText($description), $question->options), + ], + $question instanceof Score => [ + 'type' => 'score', + 'instructions' => $this->toText($question->instructions), + 'criteria' => array_map($this->toText(...), $question->levels), + ], + default => $question->toArray(), + }; + } + + /** + * Map the response usage to text usage. + */ + protected function usage(array $data): TextUsage + { + return new TextUsage( + inputTokens: $data['usage']['total_input_tokens'] ?? 0, + outputTokens: $data['usage']['total_output_tokens'] ?? 0, + cacheReadInputTokens: $data['usage']['total_cached_tokens'] ?? null, + ); + } + + /** + * Get the path of the endpoint that answers questions. + */ + protected function classificationEndpoint(): string + { + return 'decisions'; + } + + /** + * Convert structured content to the text the endpoint accepts. + * + * @param array|string $value + */ + protected function toText(string|array $value): string + { + return is_string($value) ? $value : json_encode($value, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR); + } +} diff --git a/src/ai/src/Gateway/Groq/GroqGateway.php b/src/ai/src/Gateway/Groq/GroqGateway.php index 64e707d3f..b794efeeb 100644 --- a/src/ai/src/Gateway/Groq/GroqGateway.php +++ b/src/ai/src/Gateway/Groq/GroqGateway.php @@ -119,7 +119,7 @@ public function generateTranscription( ): TranscriptionResponse { if ($diarize) { throw new LogicException( - 'Groq does not support diarized transcription. Use the OpenAI, ElevenLabs, Mistral, or Gemini provider for diarization.' + 'Groq does not support diarized transcription. Use the ElevenLabs, Mistral, or Gemini provider for diarization.' ); } diff --git a/src/ai/src/Gateway/OpenAi/OpenAiClassificationGateway.php b/src/ai/src/Gateway/OpenAi/OpenAiClassificationGateway.php index 72ab382eb..b67b47112 100644 --- a/src/ai/src/Gateway/OpenAi/OpenAiClassificationGateway.php +++ b/src/ai/src/Gateway/OpenAi/OpenAiClassificationGateway.php @@ -223,6 +223,6 @@ protected function mapAnswer(array $answer, ?Question $question): ?Answer */ protected function toText(string|array $value): string { - return is_string($value) ? $value : json_encode($value, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); + return is_string($value) ? $value : json_encode($value, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR); } } diff --git a/src/ai/src/Gateway/OpenAi/OpenAiGateway.php b/src/ai/src/Gateway/OpenAi/OpenAiGateway.php index a836dd15a..f90ad9dd7 100644 --- a/src/ai/src/Gateway/OpenAi/OpenAiGateway.php +++ b/src/ai/src/Gateway/OpenAi/OpenAiGateway.php @@ -188,7 +188,7 @@ public function generateAudio( $voice = match ($voice) { 'default-male' => 'ash', 'default-female' => 'alloy', - default => $voice, + default => str_starts_with($voice, 'voice_') ? ['id' => $voice] : $voice, }; $response = $this->withErrorHandling( @@ -215,7 +215,7 @@ public function generateAudio( * * @param array $providerOptions * - * @throws LogicException if diarization is requested together with the `prompt` provider option + * @throws LogicException if the model does not support the requested diarization options */ public function generateTranscription( TranscriptionProvider $provider, @@ -227,6 +227,12 @@ public function generateTranscription( array $providerOptions = [], ): TranscriptionResponse { /** @var Provider&TranscriptionProvider $provider */ + $usesLanguages = str_starts_with($model, 'gpt-transcribe'); + + if ($usesLanguages && $diarize) { + throw new LogicException('OpenAI model [' . $model . '] does not support diarization.'); + } + if ($diarize && filled($providerOptions['prompt'] ?? null)) { throw new LogicException('OpenAI does not support the `prompt` option for diarized transcriptions.'); } @@ -235,13 +241,23 @@ public function generateTranscription( $model = str_replace('-diarize', '', $model); } + if ($usesLanguages) { + $languages = Arr::wrap($language ?? $providerOptions['languages'] ?? $providerOptions['language'] ?? []); + + unset($providerOptions['language'], $providerOptions['languages']); + + foreach ($languages as $value) { + $providerOptions[] = ['name' => 'languages[]', 'contents' => $value]; + } + } + $response = $this->withErrorHandling( $provider->name(), fn () => $this->client($provider, $timeout) ->attach('file', $audio->content(), $this->audioFilename($audio), array_filter(['Content-Type' => $audio->mimeType()])) ->post('audio/transcriptions', array_merge($providerOptions, array_filter([ 'model' => $model, - 'language' => $language, + 'language' => $usesLanguages ? null : $language, 'response_format' => $diarize ? 'diarized_json' : 'json', ]))), ); diff --git a/src/ai/src/Gateway/OpenRouter/OpenRouterGateway.php b/src/ai/src/Gateway/OpenRouter/OpenRouterGateway.php index 73ee6da82..37a0a076e 100644 --- a/src/ai/src/Gateway/OpenRouter/OpenRouterGateway.php +++ b/src/ai/src/Gateway/OpenRouter/OpenRouterGateway.php @@ -265,7 +265,7 @@ public function generateTranscription( /** @var Provider&TranscriptionProvider $provider */ if ($diarize) { throw new LogicException( - 'OpenRouter does not support diarized transcription. Use the OpenAI, ElevenLabs, Mistral, or Gemini provider for diarization.' + 'OpenRouter does not support diarized transcription. Use the ElevenLabs, Mistral, or Gemini provider for diarization.' ); } diff --git a/src/ai/src/Providers/GeminiProvider.php b/src/ai/src/Providers/GeminiProvider.php index 773b986bd..bf8ef8c52 100644 --- a/src/ai/src/Providers/GeminiProvider.php +++ b/src/ai/src/Providers/GeminiProvider.php @@ -4,9 +4,11 @@ namespace Hypervel\Ai\Providers; +use Hypervel\Ai\Contracts\Gateway\ClassificationGateway; use Hypervel\Ai\Contracts\Gateway\FileGateway; use Hypervel\Ai\Contracts\Gateway\StoreGateway; use Hypervel\Ai\Contracts\Providers\AudioProvider; +use Hypervel\Ai\Contracts\Providers\ClassificationProvider; use Hypervel\Ai\Contracts\Providers\EmbeddingProvider; use Hypervel\Ai\Contracts\Providers\FileProvider; use Hypervel\Ai\Contracts\Providers\ImageProvider; @@ -18,14 +20,17 @@ use Hypervel\Ai\Contracts\Providers\TextProvider; use Hypervel\Ai\Contracts\Providers\TranscriptionProvider; use Hypervel\Ai\Enums\Lab; +use Hypervel\Ai\Gateway\Gemini\GeminiClassificationGateway; use Hypervel\Ai\Gateway\Gemini\GeminiFileGateway; use Hypervel\Ai\Gateway\Gemini\GeminiStoreGateway; +use Hypervel\Ai\Providers\Concerns\Classifies; use Hypervel\Ai\Providers\Concerns\GeneratesAudio; use Hypervel\Ai\Providers\Concerns\GeneratesEmbeddings; use Hypervel\Ai\Providers\Concerns\GeneratesImages; use Hypervel\Ai\Providers\Concerns\GeneratesText; use Hypervel\Ai\Providers\Concerns\GeneratesTranscriptions; use Hypervel\Ai\Providers\Concerns\HasAudioGateway; +use Hypervel\Ai\Providers\Concerns\HasClassificationGateway; use Hypervel\Ai\Providers\Concerns\HasEmbeddingGateway; use Hypervel\Ai\Providers\Concerns\HasFileGateway; use Hypervel\Ai\Providers\Concerns\HasImageGateway; @@ -42,14 +47,16 @@ use Hypervel\Support\Collection; use InvalidArgumentException; -class GeminiProvider extends Provider implements AudioProvider, EmbeddingProvider, FileProvider, ImageProvider, StoreProvider, SupportsCodeExecution, SupportsFileSearch, SupportsWebFetch, SupportsWebSearch, TextProvider, TranscriptionProvider +class GeminiProvider extends Provider implements AudioProvider, ClassificationProvider, EmbeddingProvider, FileProvider, ImageProvider, StoreProvider, SupportsCodeExecution, SupportsFileSearch, SupportsWebFetch, SupportsWebSearch, TextProvider, TranscriptionProvider { + use Classifies; use GeneratesAudio; use GeneratesEmbeddings; use GeneratesImages; use GeneratesText; use GeneratesTranscriptions; use HasAudioGateway; + use HasClassificationGateway; use HasEmbeddingGateway; use HasFileGateway; use HasImageGateway; @@ -202,6 +209,22 @@ public function defaultTranscriptionModel(): string return $this->config['models']['transcription']['default'] ?? 'gemini-3.5-transcribe'; } + /** + * Get the name of the default classification model. + */ + public function defaultClassificationModel(): string + { + return $this->config['models']['classification']['default'] ?? 'gemini-decision-1'; + } + + /** + * Determine if the provider can classify attachments alongside the state. + */ + public function supportsClassificationAttachments(): bool + { + return true; + } + /** * Get the name of the default embeddings model. */ @@ -248,6 +271,14 @@ protected function isGeminiMultimodalEmbeddingModel(string $model): bool return in_array($model, ['gemini-embedding-2', 'gemini-embedding-2-preview'], true); } + /** + * Get the provider's classification gateway. + */ + public function classificationGateway(): ClassificationGateway + { + return $this->classificationGateway ??= new GeminiClassificationGateway; + } + /** * Get the provider's file gateway. */ diff --git a/src/ai/src/Providers/OpenAiProvider.php b/src/ai/src/Providers/OpenAiProvider.php index e12179e75..1ba09f3e5 100644 --- a/src/ai/src/Providers/OpenAiProvider.php +++ b/src/ai/src/Providers/OpenAiProvider.php @@ -181,7 +181,7 @@ public function defaultAudioModel(): string */ public function defaultTranscriptionModel(): string { - return $this->config['models']['transcription']['default'] ?? 'gpt-4o-transcribe-diarize'; + return $this->config['models']['transcription']['default'] ?? 'gpt-transcribe'; } /** diff --git a/src/ai/src/Streaming/Events/Error.php b/src/ai/src/Streaming/Events/Error.php index cbbb9d1d7..b3e3d20c7 100644 --- a/src/ai/src/Streaming/Events/Error.php +++ b/src/ai/src/Streaming/Events/Error.php @@ -19,6 +19,14 @@ public function __construct( ) { } + /** + * Get the name the event is broadcast under. + */ + public function broadcastAs(): string + { + return $this->type === 'stream_failed' ? $this->type : 'error'; + } + /** * Get the event as an array. * diff --git a/src/ai/src/Streaming/Events/StreamEvent.php b/src/ai/src/Streaming/Events/StreamEvent.php index e122b9f1f..43d34bd5b 100644 --- a/src/ai/src/Streaming/Events/StreamEvent.php +++ b/src/ai/src/Streaming/Events/StreamEvent.php @@ -27,7 +27,7 @@ public function broadcast(Channel|array $channels, bool $now = true): void { try { Broadcast::on($channels) - ->as($this->type()) + ->as($this->broadcastAs()) ->with($this->toArray()) ->{$now ? 'sendNow' : 'send'}(); } catch (BroadcastException $broadcastException) { @@ -43,6 +43,14 @@ public function broadcastNow(Channel|array $channels): void $this->broadcast($channels, now: true); } + /** + * Get the name the event is broadcast under. + */ + public function broadcastAs(): string + { + return $this->type(); + } + /** * Get the event's type. */ diff --git a/src/docs/ai-sdk.md b/src/docs/ai-sdk.md index 8a1577a94..da9f9a008 100644 --- a/src/docs/ai-sdk.md +++ b/src/docs/ai-sdk.md @@ -378,7 +378,7 @@ The AI SDK supports a variety of providers across its features. The following ta | STT | OpenAI, OpenAI Compatible, ElevenLabs, Groq, Mistral, Gemini, OpenRouter | | Embeddings | OpenAI, OpenAI Compatible, Gemini, Azure, Bedrock, Cohere, Mistral, Jina, VoyageAI, Ollama, OpenRouter | | Reranking | Cohere, Jina, VoyageAI, Bedrock, OpenRouter | -| Classification | TypeSafe, OpenAI, OpenAI Compatible, OpenRouter | +| Classification | TypeSafe, OpenAI, OpenAI Compatible, Gemini, OpenRouter | | Files | OpenAI, Anthropic, Gemini, Azure, OpenRouter | | Vector Stores | OpenAI, Gemini, Azure | @@ -1311,6 +1311,21 @@ To generate and broadcast the response in the current request, call the agent's Agent and stream-event `broadcast` methods send events immediately by default. Pass `now: false` to queue delivery instead. `broadcastOnQueue` queues the entire agent operation. +Each event is broadcast under its type, such as `stream_start`, `text_delta`, `tool_call`, `tool_result`, and `stream_end`. Errors returned by the provider are always broadcast as `error`, and the provider's own error code is available in the payload's `type` key. When a `broadcastOnQueue` operation fails, a `stream_failed` event is broadcast so your frontend can stop waiting for the response. Since these are [custom broadcast names](/docs/{{version}}/broadcasting#broadcast-name), you should prefix them with a `.` when [listening with Laravel Echo](/docs/{{version}}/broadcasting#listening-for-events): + +```js +Echo.channel('channel-name') + .listen('.text_delta', (event) => { + // event.delta... + }) + .listen('.error', (event) => { + // event.type, event.message... + }) + .listen('.stream_failed', (event) => { + // ... + }); +``` + #### Broadcast Batching @@ -1524,6 +1539,34 @@ When validation fails, the validation messages are returned to the model as the Likewise, when a tool throws an exception, the run continues. The exception is reported to your application's exception handler, and the model receives "The tool call failed." as the tool's result, so it can explain the failure or try another approach. When your application's `debug` configuration option is enabled, the result also includes the exception message. Exception messages may contain sensitive details such as query bindings or server paths, so return a string from your tool when the model should know why an expected failure occurred. + +#### Strict Schemas + +By default, a model may occasionally provide arguments that don't match your tool's schema. You may add the `Strict` attribute to a tool so the provider's strict mode enforces the schema sent to the provider: + +```php +use Hypervel\Ai\Attributes\Strict; +use Hypervel\Ai\Contracts\Tool; + +#[Strict] +class RandomNumberGenerator implements Tool +{ + // ... +} +``` + +OpenAI, Azure OpenAI, xAI, and Anthropic support strict tools, and other providers ignore the attribute. Anthropic applies strict mode through its native structured outputs, which are enabled by default. If you set the `use_native_structured_output` option of your `anthropic` provider configuration to `false`, strict tools are sent as ordinary tools. + +When added to an agent with [structured output](#structured-output), the attribute applies strict mode to the agent's response instead. OpenAI, Azure OpenAI, xAI, Groq, Mistral, OpenRouter, and OpenAI-compatible providers support strict structured output. + +Strict modes limit the schemas they accept. For example, OpenAI requires every property to be required, so mark a property that may have no value as both required and nullable: + +```php +'notes' => $schema->string()->required()->nullable(), +``` + +Anthropic's strict mode doesn't support constraints such as a minimum value, so Hypervel moves them into the property's description before sending the schema. If your tool relies on such a constraint, [validate the arguments](#validating-tool-arguments) as well. + #### Repairing Tool Calls @@ -2842,9 +2885,11 @@ The `diarize` method may be used to indicate you would like the response to incl ```php $transcript = Transcription::fromStorage('audio.mp3') ->diarize() - ->generate(); + ->generate(model: 'gpt-4o-transcribe-diarize'); ``` +OpenAI's default `gpt-transcribe` model does not support diarization, so pass a diarization model such as `gpt-4o-transcribe-diarize`, or use ElevenLabs, Mistral, or Gemini. + Transcription generation may also be queued: ```php @@ -3243,7 +3288,7 @@ $result->meta->provider; ### Classifying Images -When using OpenAI, an OpenAI-compatible provider, TypeSafe, or OpenRouter, images may be classified alongside the given content by passing them as the second argument to the `of` method. Images may be created using the same [file classes used for attachments](#attachments): +When using OpenAI, an OpenAI-compatible provider, Gemini, TypeSafe, or OpenRouter, images may be classified alongside the given content by passing them as the second argument to the `of` method. Images may be created using the same [file classes used for attachments](#attachments): ```php use Hypervel\Ai\Classification; @@ -3268,7 +3313,7 @@ $result = Classification::of('Inspect the products in these photos.', [ ->classify(provider: 'typesafe'); ``` -The image content is sent with the request, so images stored with a provider and referenced using `fromId` can't be classified. OpenAI and OpenAI-compatible providers accept JPEG, PNG, GIF, and WebP images, OpenRouter accepts JPEG, PNG, and WebP images, and TypeSafe accepts JPEG and PNG images. +The image content is sent with the request, so images stored with a provider and referenced using `fromId` can't be classified, except with Gemini, which can classify images stored with Gemini. OpenAI and OpenAI-compatible providers accept JPEG, PNG, GIF, and WebP images, Gemini accepts JPEG, PNG, GIF, WebP, HEIC, HEIF, BMP, and TIFF images, OpenRouter accepts JPEG, PNG, and WebP images, and TypeSafe accepts JPEG and PNG images. ### Yes or No Decisions diff --git a/tests/Ai/Feature/BroadcastAgentTest.php b/tests/Ai/Feature/BroadcastAgentTest.php index 958e94c04..efb3c5c52 100644 --- a/tests/Ai/Feature/BroadcastAgentTest.php +++ b/tests/Ai/Feature/BroadcastAgentTest.php @@ -9,6 +9,7 @@ use Hypervel\Ai\Jobs\BroadcastAgent; use Hypervel\Ai\Prompts\AgentPrompt; use Hypervel\Ai\Responses\StreamedAgentResponse; +use Hypervel\Ai\Streaming\Events\Error; use Hypervel\Broadcasting\AnonymousEvent; use Hypervel\Broadcasting\BroadcastException; use Hypervel\Broadcasting\Channel; @@ -20,6 +21,7 @@ use JMac\Testing\Double; use JMac\Testing\Integrations\PHPUnit\VerifiesDoubles; use PHPUnit\Framework\Attributes\DataProvider; +use PHPUnit\Framework\Attributes\TestWith; use RuntimeException; use Throwable; @@ -142,6 +144,19 @@ public function testFailedBroadcastsOnEveryChannelWhenGivenAnArray(): void && $event->broadcastOn() === $channels); } + #[TestWith(['overloaded_error'])] + #[TestWith(['not_found'])] + #[TestWith(['unknown_error'])] + public function testAProviderErrorBroadcastsAsErrorAndKeepsItsCodeInThePayload(string $code): void + { + Event::fake(); + + (new Error('error-1', $code, 'Overloaded', false, time()))->broadcastNow(new Channel('test-channel')); + + Event::assertDispatched(AnonymousEvent::class, fn (AnonymousEvent $event): bool => $event->broadcastAs() === 'error' + && $event->broadcastWith()['type'] === $code); + } + public function testFailedEventSharesTheInvocationIdWithBroadcastsFromHandle(): void { Event::fake(); diff --git a/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php b/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php index 1af2ca6ce..a75797728 100644 --- a/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php +++ b/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php @@ -296,7 +296,7 @@ public function testStreamingHandlesProviderToolResults(): void 'api.anthropic.com/*' => Http::response( body: $this->ssePayload([ $this->messageStart(), - $this->contentBlockStart(0, ['type' => 'web_search_tool_result', 'tool_use_id' => 'srvtoolu_1', 'search_results' => []]), + $this->contentBlockStart(0, ['type' => 'web_search_tool_result', 'tool_use_id' => 'srvtoolu_1', 'content' => []]), $this->contentBlockStop(0), $this->contentBlockStart(1, ['type' => 'text', 'text' => '']), $this->contentBlockDelta(1, ['type' => 'text_delta', 'text' => 'Found it']), @@ -857,4 +857,44 @@ public function testStreamingSkipsCitationsForAFailedFetch(): void $this->assertEmpty($citations); } + + public function testStreamingEmitsOneCitationPerCitedWebSearchSource(): void + { + $citation = ['type' => 'citations_delta', 'citation' => ['type' => 'web_search_result_location', 'url' => 'https://laravel-news.com/laravel-13', 'title' => 'Laravel 13', 'cited_text' => 'Laravel 13', 'encrypted_index' => 'xyz']]; + + Http::fake([ + 'api.anthropic.com/*' => Http::response( + body: $this->ssePayload([ + $this->messageStart(), + $this->contentBlockStart(0, [ + 'type' => 'web_search_tool_result', + 'tool_use_id' => 'srvtoolu_1', + 'content' => [ + ['type' => 'web_search_result', 'url' => 'https://laravel.com/docs/releases', 'title' => 'Release Notes', 'encrypted_content' => 'abc', 'page_age' => null], + ['type' => 'web_search_result', 'url' => 'https://laravel-news.com/laravel-13', 'title' => 'Laravel 13', 'encrypted_content' => 'def', 'page_age' => null], + ], + ]), + $this->contentBlockStop(0), + $this->contentBlockStart(1, ['type' => 'text', 'text' => '', 'citations' => []]), + $this->contentBlockDelta(1, $citation), + $this->contentBlockDelta(1, ['type' => 'text_delta', 'text' => 'The latest version is Laravel 13.']), + $this->contentBlockStop(1), + $this->contentBlockStart(2, ['type' => 'text', 'text' => '', 'citations' => []]), + $this->contentBlockDelta(2, $citation), + $this->contentBlockDelta(2, ['type' => 'text_delta', 'text' => ' It ships with PHP 8.3 support.']), + $this->contentBlockStop(2), + $this->messageDelta('end_turn', 10), + ]), + status: 200, + headers: ['Content-Type' => 'text/event-stream'], + ), + ]); + + $citations = array_map( + fn (CitationEvent $e): array => [$e->citation->url, $e->citation->title], + array_values(array_filter($this->collectStreamEvents(), fn ($e): bool => $e instanceof CitationEvent)), + ); + + $this->assertSame([['https://laravel-news.com/laravel-13', 'Laravel 13']], $citations); + } } diff --git a/tests/Ai/Feature/Providers/Anthropic/ToolMappingTest.php b/tests/Ai/Feature/Providers/Anthropic/ToolMappingTest.php index 0e62abfa0..e6b686e40 100644 --- a/tests/Ai/Feature/Providers/Anthropic/ToolMappingTest.php +++ b/tests/Ai/Feature/Providers/Anthropic/ToolMappingTest.php @@ -4,13 +4,18 @@ namespace Hypervel\Tests\Ai\Feature\Providers\Anthropic; +use Hypervel\Ai\Attributes\Strict; +use Hypervel\Ai\Contracts\Tool; use Hypervel\Ai\Providers\Tools\CodeExecution; use Hypervel\Ai\Providers\Tools\WebFetch; use Hypervel\Ai\Providers\Tools\WebSearch; +use Hypervel\Ai\Tools\Request; +use Hypervel\Contracts\JsonSchema\JsonSchema; use Hypervel\Support\Facades\Http; use Hypervel\Tests\Ai\Fixtures\Agents\NamedToolAgent; use Hypervel\Tests\Ai\Fixtures\Agents\ToolUsingAgent; use Hypervel\Tests\Ai\Fixtures\AnthropicHelpers; +use Hypervel\Tests\Ai\Fixtures\Tools\NonStrictTool; use Hypervel\Tests\Ai\TestCase; use function Hypervel\Ai\agent; @@ -61,6 +66,78 @@ public function testToolWithANameMethodEmitsTheDeclaredName(): void }); } + public function testToolWithStrictAttributeSendsStrictTrue(): void + { + Http::fake([ + 'api.anthropic.com/*' => $this->fakeTextResponse('ok'), + ]); + + agent(tools: [$this->anthropicStrictOrderTool()])->prompt('Order two', provider: 'anthropic'); + + Http::assertSent(function ($request): bool { + $tool = $request->data()['tools'][0]; + + return $tool['strict'] === true + && $tool['input_schema']['additionalProperties'] === false + && $tool['input_schema']['required'] === ['quantity']; + }); + } + + public function testToolWithoutStrictAttributeOmitsStrict(): void + { + Http::fake([ + 'api.anthropic.com/*' => $this->fakeTextResponse('ok'), + ]); + + agent(tools: [new NonStrictTool])->prompt('Hi', provider: 'anthropic'); + + Http::assertSent(function ($request): bool { + $tool = collect($request->data()['tools'] ?? [])->firstWhere('name', 'NonStrictTool'); + + return ! array_key_exists('strict', $tool) + && ! array_key_exists('additionalProperties', $tool['input_schema']); + }); + } + + public function testStrictToolSchemasDropKeywordsAnthropicStrictModeRejects(): void + { + Http::fake([ + 'api.anthropic.com/*' => $this->fakeTextResponse('ok'), + ]); + + agent(tools: [$this->anthropicStrictOrderTool()])->prompt('Order two', provider: 'anthropic'); + + Http::assertSent(function ($request): bool { + $quantity = ((array) $request->data()['tools'][0]['input_schema']['properties'])['quantity']; + + return ! array_key_exists('minimum', $quantity) + && str_contains($quantity['description'] ?? '', 'Must be at least 1.'); + }); + } + + public function testStrictToolsAreSentAsRegularToolsWhenNativeStructuredOutputIsDisabled(): void + { + config(['ai.providers.anthropic' => [ + ...config('ai.providers.anthropic'), + 'use_native_structured_output' => false, + ]]); + + Http::fake([ + 'api.anthropic.com/*' => $this->fakeTextResponse('ok'), + ]); + + agent(tools: [$this->anthropicStrictOrderTool()])->prompt('Order two', provider: 'anthropic'); + + Http::assertSent(function ($request): bool { + $tool = $request->data()['tools'][0]; + $quantity = ((array) $tool['input_schema']['properties'])['quantity']; + + return ! array_key_exists('strict', $tool) + && ! array_key_exists('additionalProperties', $tool['input_schema']) + && $quantity['minimum'] === 1; + }); + } + public function testWebSearchToolSendsAllowedDomains(): void { Http::fake([ @@ -252,6 +329,50 @@ public function testWebFetchToolResultSkipsCitationsForAFailedFetch(): void $this->assertEmpty($response->meta->citations); } + public function testWebSearchReportsOnlyTheSourcesTheAnswerCites(): void + { + Http::fake([ + 'api.anthropic.com/*' => Http::response([ + 'id' => 'msg_search_1', + 'type' => 'message', + 'role' => 'assistant', + 'model' => 'claude-sonnet-4-6', + 'content' => [ + [ + 'type' => 'server_tool_use', + 'id' => 'srvtoolu_1', + 'name' => 'web_search', + 'input' => (object) ['query' => 'latest laravel version'], + ], + [ + 'type' => 'web_search_tool_result', + 'tool_use_id' => 'srvtoolu_1', + 'content' => [ + ['type' => 'web_search_result', 'url' => 'https://laravel.com/docs/releases', 'title' => 'Release Notes', 'encrypted_content' => 'abc', 'page_age' => null], + ['type' => 'web_search_result', 'url' => 'https://laravel-news.com/laravel-13', 'title' => 'Laravel 13', 'encrypted_content' => 'def', 'page_age' => null], + ], + ], + [ + 'type' => 'text', + 'text' => 'The latest version is Laravel 13.', + 'citations' => [ + ['type' => 'web_search_result_location', 'url' => 'https://laravel-news.com/laravel-13', 'title' => 'Laravel 13', 'cited_text' => 'Laravel 13', 'encrypted_index' => 'xyz'], + ], + ], + ], + 'stop_reason' => 'end_turn', + 'usage' => ['input_tokens' => 10, 'output_tokens' => 5], + ]), + ]); + + $response = agent(tools: [new WebSearch])->prompt('Search it', provider: 'anthropic'); + + $this->assertSame( + [['https://laravel-news.com/laravel-13', 'Laravel 13']], + $response->meta->citations->map(fn ($citation): array => [$citation->url, $citation->title])->all(), + ); + } + public function testWebFetchToolForwardsACustomMaxUses(): void { Http::fake([ @@ -307,4 +428,39 @@ public function testCodeExecutionToolSendsDatedTypeAndName(): void return data_get($tool, 'type') === 'code_execution_20260120'; }); } + + /** + * Create a strict tool whose schema uses a keyword Anthropic's strict mode rejects. + */ + protected function anthropicStrictOrderTool(): Tool + { + return new #[Strict] class implements Tool { + /** + * Get the tool description. + */ + public function description(): string + { + return 'Orders a number of items.'; + } + + /** + * Handle the tool invocation. + */ + public function handle(Request $request): string + { + return 'ok'; + } + + /** + * Get the tool's input schema. + */ + public function schema(JsonSchema $schema): array + { + return [ + 'quantity' => $schema->integer()->min(1)->required(), + 'note' => $schema->string(), + ]; + } + }; + } } diff --git a/tests/Ai/Feature/Providers/Gemini/ClassificationTest.php b/tests/Ai/Feature/Providers/Gemini/ClassificationTest.php new file mode 100644 index 000000000..4a70a1f4e --- /dev/null +++ b/tests/Ai/Feature/Providers/Gemini/ClassificationTest.php @@ -0,0 +1,330 @@ +make('config')->set('ai.providers.gemini.key', 'test-key'); + } + + public function testClassificationPostsToTheGeminiDecisionsEndpoint(): void + { + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + Classification::of('Stripe connect keeps failing, losing sales, help ASAP') + ->questions([ + 'is_urgent' => new Boolean('Does this message convey urgency?', [ + 'true' => 'The customer is blocked.', + 'false' => ['note' => 'Anything else.'], + ]), + 'department' => new Choice('Which team should own this ticket?', [ + 'account' => 'Login, permissions, or profile issues.', + 'frontend' => ['scope' => 'Rendering'], + 'payments' => null, + ]), + 'urgency' => new Score('How urgent is this ticket?', [ + 'Next release', 'This week', ['label' => 'Blocking revenue'], + ]), + ]) + ->classify(provider: 'gemini', model: 'gemini-decision-1'); + + Http::assertSent(function (Request $request): bool { + $body = json_decode($request->body(), true); + + return $request->url() === 'https://generativelanguage.googleapis.com/v1beta/decisions' + && $request->hasHeader('x-goog-api-key', 'test-key') + && $body['model'] === 'gemini-decision-1' + && $body['input'] === 'Stripe connect keeps failing, losing sales, help ASAP' + && ! array_key_exists('state', $body) + && $body['questions'] === [ + 'is_urgent' => [ + 'type' => 'noul', + 'instructions' => 'Does this message convey urgency?', + 'criteria' => ['true_description' => 'The customer is blocked.', 'false_description' => '{"note":"Anything else."}'], + ], + 'department' => [ + 'type' => 'choice', + 'instructions' => 'Which team should own this ticket?', + 'criteria' => ['account' => 'Login, permissions, or profile issues.', 'frontend' => '{"scope":"Rendering"}', 'payments' => null], + ], + 'urgency' => [ + 'type' => 'score', + 'instructions' => 'How urgent is this ticket?', + 'criteria' => ['Next release', 'This week', '{"label":"Blocking revenue"}'], + ], + ]; + }); + } + + public function testBooleanQuestionsWithoutCriteriaOrWithOneCaseSendOnlyWhatWasGiven(): void + { + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + Classification::of('text') + ->questions([ + 'plain' => new Boolean('Urgent?'), + 'one_case' => new Boolean('Urgent?', ['true' => 'Blocked.']), + ]) + ->classify(provider: 'gemini'); + + Http::assertSent(fn (Request $request): bool => json_decode($request->body(), true)['questions'] === [ + 'plain' => ['type' => 'noul', 'instructions' => 'Urgent?'], + 'one_case' => ['type' => 'noul', 'instructions' => 'Urgent?', 'criteria' => ['true_description' => 'Blocked.']], + ]); + } + + public function testNumericNamesRemainJsonObjectMembersAndEmptyCriteriaAreOmitted(): void + { + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + Classification::of('Invoice question') + ->question('0', new Choice('Which department?', ['0' => 'Billing', '1' => 'Technical'])) + ->question('1', new Boolean('Urgent?', [])) + ->classify(provider: 'gemini'); + + Http::assertSent(function (Request $request): bool { + $questions = json_decode($request->body())->questions; + + return is_object($questions) + && is_object($questions->{'0'}->criteria) + && (array) $questions->{'0'}->criteria === ['0' => 'Billing', '1' => 'Technical'] + && (array) $questions->{'1'} === ['type' => 'noul', 'instructions' => 'Urgent?']; + }); + } + + public function testStructuredStateThatCannotBeEncodedThrowsAJsonException(): void + { + Http::fake(); + + $this->expectException(JsonException::class); + + Classification::of(['body' => "\xB1"]) + ->question('is_urgent', new Boolean('Urgent?')) + ->classify(provider: 'gemini'); + } + + public function testStructuredStateIsSentAsJsonText(): void + { + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + Classification::of(['subject' => 'Broken lamp', 'body' => 'It arrived cracked.']) + ->question('is_urgent', new Boolean(['rule' => 'Urgent?'])) + ->classify(provider: 'gemini'); + + Http::assertSent(function (Request $request): bool { + $body = json_decode($request->body(), true); + + return $body['input'] === '{"subject":"Broken lamp","body":"It arrived cracked."}' + && $body['questions']['is_urgent']['instructions'] === '{"rule":"Urgent?"}'; + }); + } + + public function testDecisionsResponseIsParsedIntoTypedAnswers(): void + { + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + $response = Classification::of('text') + ->questions([ + 'is_urgent' => new Boolean('Urgent?'), + 'department' => new Choice('Team?', ['account' => null, 'frontend' => null, 'payments' => null]), + 'urgency' => new Score('How urgent?', ['Next release', 'This week', ['label' => 'Blocking revenue']]), + ]) + ->classify(provider: 'gemini'); + + $this->assertCount(3, $response); + $this->assertInstanceOf(BooleanAnswer::class, $response['is_urgent']); + $this->assertSame(0.96, $response['is_urgent']->probability); + $this->assertInstanceOf(ChoiceAnswer::class, $response['department']); + $this->assertSame('payments', $response['department']->choice); + $this->assertSame(0.16, $response['department']->probabilityOf('frontend')); + $this->assertSame(0.84, $response['department']->confidence); + $this->assertInstanceOf(ScoreAnswer::class, $response['urgency']); + $this->assertSame(1.99, $response['urgency']->score); + $this->assertSame(2, $response['urgency']->level()); + $this->assertSame(['label' => 'Blocking revenue'], $response['urgency']->label()); + $this->assertSame(312, $response->usage->inputTokens); + $this->assertSame(256, $response->usage->cacheReadInputTokens); + $this->assertSame(3, $response->usage->outputTokens); + $this->assertSame('gemini', $response->meta->provider); + $this->assertSame('gemini-decision-1', $response->meta->model); + } + + public function testAnswersOfUnknownTypesAreSkipped(): void + { + Http::fake(['*' => Http::response([ + 'answers' => [ + 'is_urgent' => ['type' => 'noul', 'noul' => 0.2], + 'future' => ['type' => 'ranking', 'ranking' => ['a', 'b']], + ], + 'usage' => ['total_input_tokens' => 10, 'total_output_tokens' => 1], + ])]); + + $response = Classification::of('text')->question('is_urgent', new Boolean('Urgent?'))->classify(provider: 'gemini'); + + $this->assertCount(1, $response); + $this->assertSame(0.2, $response['is_urgent']->probability); + } + + public function testTheRawDecisionsResponseIsExposedOnTheClassificationResponse(): void + { + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + $response = Classification::of('text')->question('is_urgent', new Boolean('Urgent?'))->classify(provider: 'gemini'); + + $this->assertSame(315, $response->raw->json('usage.total_tokens')); + } + + public function testClassificationUsesTheDefaultDecisionsModelWhenNoneIsSpecified(): void + { + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + Classification::of('text')->question('is_urgent', new Boolean('Urgent?'))->classify(provider: 'gemini'); + + Http::assertSent(fn (Request $request): bool => json_decode($request->body(), true)['model'] === 'gemini-decision-1'); + } + + public function testTheDefaultDecisionsModelCanBeConfigured(): void + { + config(['ai.providers.gemini.models.classification.default' => 'gemini-decision-2']); + + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + Classification::of('text')->question('is_urgent', new Boolean('Urgent?'))->classify(provider: 'gemini'); + + Http::assertSent(fn (Request $request): bool => json_decode($request->body(), true)['model'] === 'gemini-decision-2'); + } + + public function testDecisionsRequestsUseTheConfiguredBaseUrl(): void + { + config(['ai.providers.gemini' => [...config('ai.providers.gemini'), 'url' => 'http://localhost:8080/v1beta/']]); + + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + Classification::of('text')->question('is_urgent', new Boolean('Urgent?'))->classify(provider: 'gemini'); + + Http::assertSent(fn (Request $request): bool => $request->url() === 'http://localhost:8080/v1beta/decisions'); + } + + public function testImageAttachmentsAreSentAsInlineImageBlocksLabelledByName(): void + { + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + $jpeg = file_get_contents(__DIR__ . '/../../../Fixtures/Images/blue.jpg'); + + Classification::of('A product photo uploaded by a customer.', [ + 'front' => Image::fromPath(__DIR__ . '/../../../Fixtures/Images/blue.jpg')->withProviderOptions(fn (Lab|string $provider): ?array => $provider === Lab::Gemini ? ['resolution' => 'high'] : null), + 'back' => UploadedFile::fake()->createWithContent('back.heic', 'upload-bytes')->mimeType('image/heic'), + ]) + ->question('damaged', new Boolean('Is the product damaged?')) + ->classify(provider: 'gemini'); + + Http::assertSent(fn (Request $request): bool => json_decode($request->body(), true)['input'] === [ + ['type' => 'text', 'text' => 'A product photo uploaded by a customer.'], + ['type' => 'text', 'text' => 'front:'], + ['resolution' => 'high', 'type' => 'image', 'data' => base64_encode($jpeg), 'mime_type' => 'image/jpeg'], + ['type' => 'text', 'text' => 'back:'], + ['type' => 'image', 'data' => base64_encode('upload-bytes'), 'mime_type' => 'image/heic'], + ]); + } + + public function testUploadedGeminiFilesAreSentAsImageBlocksByUri(): void + { + Http::fake(['*' => Http::response($this->fakeGeminiDecisionsResponse())]); + + Classification::of('A product photo uploaded by a customer.', [Image::fromId('files/abc123')]) + ->question('damaged', new Boolean('Is the product damaged?')) + ->classify(provider: 'gemini'); + + Http::assertSent(fn (Request $request): bool => json_decode($request->body(), true)['input'] === [ + ['type' => 'text', 'text' => 'A product photo uploaded by a customer.'], + ['type' => 'image', 'uri' => 'files/abc123'], + ]); + } + + public function testImagesInUnsupportedFormatsAreRejectedBeforeAnyRequest(): void + { + Http::fake(); + + try { + Classification::of('Inspect this.', [UploadedFile::fake()->createWithContent('photo.svg', '')->mimeType('image/svg+xml')]) + ->question('damaged', new Boolean('Damaged?')) + ->classify(provider: 'gemini'); + + $this->fail('Expected an InvalidArgumentException.'); + } catch (InvalidArgumentException $exception) { + $this->assertSame('Gemini decisions only accept JPEG, PNG, GIF, WebP, HEIC, HEIF, BMP, or TIFF images; [image/svg+xml] given.', $exception->getMessage()); + } + + Http::assertNothingSent(); + } + + public function testARejectedDecisionsRequestThrowsARequestException(): void + { + Http::fake(['*' => Http::response(['error' => ['code' => 400, 'message' => 'Invalid value at questions', 'status' => 'INVALID_ARGUMENT']], 400)]); + + $this->expectException(RequestException::class); + + Classification::of('text')->question('is_urgent', new Boolean('Urgent?'))->classify(provider: 'gemini'); + } + + public function testAnOverloadedDecisionsEndpointRaisesAFailoverException(): void + { + Http::fake(['*' => Http::response(['error' => ['code' => 503, 'message' => 'The model is overloaded.', 'status' => 'UNAVAILABLE']], 503)]); + + $this->expectException(ProviderOverloadedException::class); + + Classification::of('text')->question('is_urgent', new Boolean('Urgent?'))->classify(provider: 'gemini'); + } + + /** + * Create a Gemini decisions response. + */ + protected function fakeGeminiDecisionsResponse(): array + { + return [ + 'answers' => [ + 'is_urgent' => ['type' => 'noul', 'noul' => 0.96, 'confidence' => 0.96], + 'department' => [ + 'type' => 'choice', + 'choice' => 'payments', + 'probabilities' => ['account' => 0.0, 'frontend' => 0.16, 'payments' => 0.84], + 'confidence' => 0.84, + ], + 'urgency' => [ + 'type' => 'score', + 'score' => 1.99, + 'probabilities' => ['0' => 0.0, '1' => 0.01, '2' => 0.99], + 'legend' => ['0' => 'Next release', '1' => 'This week', '2' => '{"label":"Blocking revenue"}'], + 'confidence' => 0.99, + ], + ], + 'usage' => ['total_input_tokens' => 312, 'total_cached_tokens' => 256, 'total_output_tokens' => 3, 'total_tokens' => 315], + ]; + } +} diff --git a/tests/Ai/Feature/Providers/Groq/TranscriptionTest.php b/tests/Ai/Feature/Providers/Groq/TranscriptionTest.php index 06f158fac..a0696800a 100644 --- a/tests/Ai/Feature/Providers/Groq/TranscriptionTest.php +++ b/tests/Ai/Feature/Providers/Groq/TranscriptionTest.php @@ -89,7 +89,7 @@ public function testTranscriptionDiarizeThrowsALogicExceptionWithoutSendingARequ Transcription::fromBase64(base64_encode('fake-audio'), 'audio/mp3')->diarize()->generate(provider: 'groq'); $this->fail('Expected unsupported diarization to be rejected.'); } catch (LogicException $exception) { - $this->assertStringContainsString('does not support diarized transcription', $exception->getMessage()); + $this->assertSame('Groq does not support diarized transcription. Use the ElevenLabs, Mistral, or Gemini provider for diarization.', $exception->getMessage()); } Http::assertNothingSent(); diff --git a/tests/Ai/Feature/Providers/OpenAi/AudioTest.php b/tests/Ai/Feature/Providers/OpenAi/AudioTest.php index d071911d6..4fa95743c 100644 --- a/tests/Ai/Feature/Providers/OpenAi/AudioTest.php +++ b/tests/Ai/Feature/Providers/OpenAi/AudioTest.php @@ -66,7 +66,7 @@ public function testAudioRequestResolvesDefaultMaleVoiceToAsh(): void Http::assertSent(fn (Request $request): bool => json_decode($request->body(), true)['voice'] === 'ash'); } - public function testAudioRequestPassesCustomVoiceIdThroughUnchanged(): void + public function testAudioRequestPassesBuiltInVoicesThroughUnchanged(): void { Http::fake(['*' => $this->fakeOpenAiAudioResponse()]); Audio::of('Hello')->voice('nova')->generate(provider: 'openai', model: 'gpt-4o-mini-tts'); @@ -74,6 +74,14 @@ public function testAudioRequestPassesCustomVoiceIdThroughUnchanged(): void Http::assertSent(fn (Request $request): bool => json_decode($request->body(), true)['voice'] === 'nova'); } + public function testAudioRequestSendsVoiceIdsAsAnObject(): void + { + Http::fake(['*' => $this->fakeOpenAiAudioResponse()]); + Audio::of('Hello')->voice('voice_1234')->generate(provider: 'openai', model: 'gpt-4o-mini-tts'); + + Http::assertSent(fn (Request $request): bool => json_decode($request->body(), true)['voice'] === ['id' => 'voice_1234']); + } + public function testAudioRequestIncludesInstructionsWhenProvided(): void { Http::fake(['*' => $this->fakeOpenAiAudioResponse()]); diff --git a/tests/Ai/Feature/Providers/OpenAi/ClassificationTest.php b/tests/Ai/Feature/Providers/OpenAi/ClassificationTest.php index 3fccb2938..dbffc7b51 100644 --- a/tests/Ai/Feature/Providers/OpenAi/ClassificationTest.php +++ b/tests/Ai/Feature/Providers/OpenAi/ClassificationTest.php @@ -18,6 +18,7 @@ use Hypervel\Support\Facades\Storage; use Hypervel\Tests\Ai\TestCase; use InvalidArgumentException; +use JsonException; use LogicException; use PHPUnit\Framework\Attributes\DataProvider; @@ -102,6 +103,17 @@ public function testStructuredStateIsSentAsJsonText(): void Http::assertSent(fn (Request $request): bool => json_decode($request->body(), true)['input'] === '{"subject":"Refund","body":"Charged twice"}'); } + public function testStructuredStateThatCannotBeEncodedThrowsAJsonException(): void + { + Http::fake(); + + $this->expectException(JsonException::class); + + Classification::of(['body' => "\xB1"]) + ->question('is_urgent', new Boolean('Is this urgent?')) + ->classify(provider: 'openai'); + } + public function testImageAttachmentsAreSentInlineWithTheStateAsAUserMessage(): void { Http::fake(['*' => Http::response($this->fakeOpenAiDecisionsResponse())]); diff --git a/tests/Ai/Feature/Providers/OpenAi/TranscriptionTest.php b/tests/Ai/Feature/Providers/OpenAi/TranscriptionTest.php index 67c50ebae..ba9ddd712 100644 --- a/tests/Ai/Feature/Providers/OpenAi/TranscriptionTest.php +++ b/tests/Ai/Feature/Providers/OpenAi/TranscriptionTest.php @@ -63,14 +63,14 @@ public function testTranscriptionRequestPostsToCorrectEndpoint(): void && str_contains($request->header('Content-Type')[0] ?? '', 'multipart/form-data')); } - public function testTranscriptionIncludesModelInRequest(): void + public function testTranscriptionUsesGptTranscribeByDefault(): void { Http::fake(['*' => fakeOpenAiTranscriptionResponse()]); Transcription::fromBase64(base64_encode('fake-audio'), 'audio/mp3') ->generate(provider: 'openai'); - Http::assertSent(fn (Request $request): bool => str_contains($request->body(), 'gpt-4o-transcribe')); + Http::assertSent(fn (Request $request): bool => str_contains($request->body(), "\r\n\r\ngpt-transcribe\r\n")); } public function testTranscriptionStripsDiarizeSuffixFromModelWhenDiarizeIsOff(): void @@ -124,15 +124,85 @@ public function testTheRawHttpResponseIsExposedOnTheTranscriptionResponse(): voi $this->assertSame('Hello, world!', $response->raw->json('text')); } - public function testTranscriptionSendsLanguageWhenProvided(): void + public function testTranscriptionSendsLanguagesInsteadOfLanguageForTheCurrentModel(): void { Http::fake(['*' => fakeOpenAiTranscriptionResponse()]); Transcription::fromBase64(base64_encode('fake-audio'), 'audio/mp3') ->language('en') + ->withProviderOptions(['language' => 'de', 'languages' => ['fr']]) ->generate(provider: 'openai'); - Http::assertSent(fn (Request $request): bool => collect($request->data())->firstWhere('name', 'language')['contents'] === 'en'); + Http::assertSent(fn (Request $request): bool => str_contains($request->body(), 'name="languages[]"') + && str_contains($request->body(), "\r\n\r\nen\r\n") + && ! str_contains($request->body(), 'name="language"') + && ! str_contains($request->body(), "\r\n\r\nfr\r\n") + && ! str_contains($request->body(), "\r\n\r\nde\r\n")); + } + + public function testTranscriptionSendsLanguagesAsAMultipartArray(): void + { + Http::fake(['*' => fakeOpenAiTranscriptionResponse()]); + + Transcription::fromBase64(base64_encode('fake-audio'), 'audio/mp3') + ->withProviderOptions(['languages' => ['en', 'fr'], 'language' => 'de']) + ->generate(provider: 'openai'); + + Http::assertSent(fn (Request $request): bool => substr_count($request->body(), 'name="languages[]"') === 2 + && str_contains($request->body(), "\r\n\r\nen\r\n") + && str_contains($request->body(), "\r\n\r\nfr\r\n") + && ! str_contains($request->body(), 'name="language"')); + } + + public function testTranscriptionWrapsASingleLanguagesProviderOption(): void + { + Http::fake(['*' => fakeOpenAiTranscriptionResponse()]); + + Transcription::fromBase64(base64_encode('fake-audio'), 'audio/mp3') + ->withProviderOptions(['languages' => 'en']) + ->generate(provider: 'openai'); + + Http::assertSent(fn (Request $request): bool => substr_count($request->body(), 'name="languages[]"') === 1 + && str_contains($request->body(), "\r\n\r\nen\r\n")); + } + + public function testTranscriptionSendsNoLanguageFieldsWhenNoneAreGiven(): void + { + Http::fake(['*' => fakeOpenAiTranscriptionResponse()]); + + Transcription::fromBase64(base64_encode('fake-audio'), 'audio/mp3') + ->generate(provider: 'openai'); + + Http::assertSent(fn (Request $request): bool => ! str_contains($request->body(), 'name="languages[]"') + && ! str_contains($request->body(), 'name="language"')); + } + + public function testTranscriptionRetainsSingularLanguageForExplicitlySelectedLegacyModels(): void + { + Http::fake(['*' => fakeOpenAiTranscriptionResponse()]); + + Transcription::fromBase64(base64_encode('fake-audio'), 'audio/mp3') + ->language('fr') + ->generate(provider: 'openai', model: 'gpt-4o-transcribe'); + + Http::assertSent(fn (Request $request): bool => str_contains($request->body(), 'name="language"') + && ! str_contains($request->body(), 'name="languages[]"')); + } + + public function testDefaultTranscriptionRejectsDiarizationBeforeSendingAudio(): void + { + Http::fake(); + + try { + Transcription::fromBase64(base64_encode('fake-audio'), 'audio/mp3') + ->diarize()->generate(provider: 'openai'); + + $this->fail('Expected a LogicException.'); + } catch (LogicException $exception) { + $this->assertSame('OpenAI model [gpt-transcribe] does not support diarization.', $exception->getMessage()); + } + + Http::assertNothingSent(); } public function testTranscriptionRequestSendsBearerToken(): void diff --git a/tests/Ai/Feature/Providers/OpenRouter/TranscriptionTest.php b/tests/Ai/Feature/Providers/OpenRouter/TranscriptionTest.php index 1d8ed247c..ba48b627e 100644 --- a/tests/Ai/Feature/Providers/OpenRouter/TranscriptionTest.php +++ b/tests/Ai/Feature/Providers/OpenRouter/TranscriptionTest.php @@ -73,7 +73,7 @@ public function testTranscriptionDiarizeThrowsLogicExceptionWithoutSendingReques Http::fake(['*' => fakeOpenRouterTranscriptionResponse()]); $this->expectException(LogicException::class); - $this->expectExceptionMessage('OpenRouter does not support diarized transcription'); + $this->expectExceptionMessage('OpenRouter does not support diarized transcription. Use the ElevenLabs, Mistral, or Gemini provider for diarization.'); try { Transcription::fromBase64(base64_encode('fake-audio'), 'audio/mp3') diff --git a/tests/Ai/Feature/Providers/TypeSafe/ClassificationTest.php b/tests/Ai/Feature/Providers/TypeSafe/ClassificationTest.php index 06b97d6d5..c48d4d61e 100644 --- a/tests/Ai/Feature/Providers/TypeSafe/ClassificationTest.php +++ b/tests/Ai/Feature/Providers/TypeSafe/ClassificationTest.php @@ -129,18 +129,22 @@ public function testBooleanCriteriaAreSentWhenGiven(): void ]); } - public function testNumericChoiceNamesRemainJsonObjectMembers(): void + public function testNumericNamesRemainJsonObjectMembersAndEmptyCriteriaAreOmitted(): void { Http::fake(['*' => Http::response(fakeTypeSafeResponse())]); Classification::of('Invoice question') - ->question('department', new Choice('Which department?', ['0' => 'Billing', '1' => 'Technical'])) + ->question('0', new Choice('Which department?', ['0' => 'Billing', '1' => 'Technical'])) + ->question('1', new Boolean('Urgent?', [])) ->classify(provider: 'typesafe'); Http::assertSent(function (Request $request): bool { - $criteria = json_decode($request->body())->questions->department->criteria; + $questions = json_decode($request->body())->questions; - return is_object($criteria) && (array) $criteria === ['0' => 'Billing', '1' => 'Technical']; + return is_object($questions) + && is_object($questions->{'0'}->criteria) + && (array) $questions->{'0'}->criteria === ['0' => 'Billing', '1' => 'Technical'] + && (array) $questions->{'1'} === ['type' => 'noul', 'instructions' => 'Urgent?']; }); } diff --git a/tests/Integration/Ai/Fixtures/Providers.php b/tests/Integration/Ai/Fixtures/Providers.php index 670180687..7c84085c0 100644 --- a/tests/Integration/Ai/Fixtures/Providers.php +++ b/tests/Integration/Ai/Fixtures/Providers.php @@ -47,7 +47,6 @@ public static function transcription(): array public static function diarization(): array { return [ - 'openai' => ['openai', 'OPENAI_API_KEY'], 'gemini' => ['gemini', 'GEMINI_API_KEY'], ]; } @@ -125,6 +124,7 @@ public static function reranking(): array public static function classification(): array { return [ + 'gemini' => ['gemini', 'GEMINI_API_KEY'], 'openai' => ['openai', 'OPENAI_API_KEY'], 'openrouter' => ['openrouter', 'OPENROUTER_API_KEY'], 'typesafe' => ['typesafe', 'TYPESAFE_API_KEY'], @@ -137,6 +137,7 @@ public static function classification(): array public static function imageClassification(): array { return [ + 'gemini' => ['gemini', 'GEMINI_API_KEY'], 'openai' => ['openai', 'OPENAI_API_KEY'], 'openrouter' => ['openrouter', 'OPENROUTER_API_KEY'], 'typesafe' => ['typesafe', 'TYPESAFE_API_KEY'], From e43537f8380981139191c048e1ebdf0c0bafddeb Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:56:49 +0000 Subject: [PATCH 08/17] Forward attachment provider options to Anthropic requests Provider options set on a document or image attachment, such as cache control, are now merged into the Anthropic content block for that attachment, beneath the mapped fields. OpenAI already forwarded them. Port laravel/ai#1220 at a2cb93a2. Ported the message-mapping tests. Validation: the changed test file passes; formatting and full static analysis pass. --- .../Anthropic/Concerns/MapsAttachments.php | 6 +- .../Anthropic/MessageMappingTest.php | 96 +++++++++++++++++++ 2 files changed, 101 insertions(+), 1 deletion(-) diff --git a/src/ai/src/Gateway/Anthropic/Concerns/MapsAttachments.php b/src/ai/src/Gateway/Anthropic/Concerns/MapsAttachments.php index 661441b5b..e73e58056 100644 --- a/src/ai/src/Gateway/Anthropic/Concerns/MapsAttachments.php +++ b/src/ai/src/Gateway/Anthropic/Concerns/MapsAttachments.php @@ -4,6 +4,8 @@ namespace Hypervel\Ai\Gateway\Anthropic\Concerns; +use Hypervel\Ai\Contracts\HasProviderOptions; +use Hypervel\Ai\Enums\Lab; use Hypervel\Ai\Files\Base64Document; use Hypervel\Ai\Files\Base64Image; use Hypervel\Ai\Files\File; @@ -128,7 +130,9 @@ protected function mapAttachments(Collection $attachments): array $mapped['title'] = $attachment->name(); } - return $mapped; + return $attachment instanceof HasProviderOptions + ? array_merge($attachment->providerOptions(Lab::Anthropic), $mapped) + : $mapped; })->all(); } diff --git a/tests/Ai/Feature/Providers/Anthropic/MessageMappingTest.php b/tests/Ai/Feature/Providers/Anthropic/MessageMappingTest.php index a5caed971..59ecd077f 100644 --- a/tests/Ai/Feature/Providers/Anthropic/MessageMappingTest.php +++ b/tests/Ai/Feature/Providers/Anthropic/MessageMappingTest.php @@ -4,6 +4,7 @@ namespace Hypervel\Tests\Ai\Feature\Providers\Anthropic; +use Hypervel\Ai\Enums\Lab; use Hypervel\Ai\Files\Base64Document; use Hypervel\Ai\Files\Document; use Hypervel\Ai\Files\LocalImage; @@ -469,6 +470,101 @@ public function testStoredDocumentCarriesItsFilenameAsTheDocumentTitle(): void }); } + public function testDocumentAttachmentProviderOptionsAreForwardedToTheContentBlock(): void + { + Http::fake([ + 'api.anthropic.com/*' => $this->fakeTextResponse(), + ]); + + $document = Document::fromString('hello world', 'text/plain') + ->withProviderOptions(['citations' => ['enabled' => true], 'cache_control' => ['type' => 'ephemeral']]); + + agent('You are helpful.')->prompt( + 'Read this.', + attachments: [$document], + provider: 'anthropic', + ); + + Http::assertSent(function ($request): bool { + $block = $request->data()['messages'][0]['content'][0]; + + return $block['type'] === 'document' + && $block['source']['data'] === 'hello world' + && $block['citations'] === ['enabled' => true] + && $block['cache_control'] === ['type' => 'ephemeral']; + }); + } + + public function testImageAttachmentProviderOptionsAreForwardedToTheContentBlock(): void + { + Http::fake([ + 'api.anthropic.com/*' => $this->fakeTextResponse(), + ]); + + $image = (new LocalImage(__DIR__ . '/../../../Fixtures/Images/red.png')) + ->withProviderOptions(['cache_control' => ['type' => 'ephemeral', 'ttl' => '1h']]); + + agent('You are helpful.')->prompt( + 'What is in this image?', + attachments: [$image], + provider: 'anthropic', + ); + + Http::assertSent(function ($request): bool { + $block = $request->data()['messages'][0]['content'][0]; + + return $block['type'] === 'image' + && $block['source']['media_type'] === 'image/png' + && $block['cache_control'] === ['type' => 'ephemeral', 'ttl' => '1h']; + }); + } + + public function testAttachmentProviderOptionsResolveFromAClosureScopedToTheProvider(): void + { + Http::fake([ + 'api.anthropic.com/*' => $this->fakeTextResponse(), + ]); + + $document = Document::fromString('hello world', 'text/plain') + ->withProviderOptions(fn (Lab $provider): array => match ($provider) { + Lab::Anthropic => ['context' => 'Quarterly notes'], + default => [], + }); + + agent('You are helpful.')->prompt( + 'Read this.', + attachments: [$document], + provider: 'anthropic', + ); + + Http::assertSent(function ($request): bool { + return ($request->data()['messages'][0]['content'][0]['context'] ?? null) === 'Quarterly notes'; + }); + } + + public function testAttachmentProviderOptionsDoNotOverwriteTheContentBlockStructure(): void + { + Http::fake([ + 'api.anthropic.com/*' => $this->fakeTextResponse(), + ]); + + $document = Document::fromString('hello world', 'text/plain') + ->withProviderOptions(['type' => 'image', 'source' => ['type' => 'url', 'url' => 'https://example.com']]); + + agent('You are helpful.')->prompt( + 'Read this.', + attachments: [$document], + provider: 'anthropic', + ); + + Http::assertSent(function ($request): bool { + $block = $request->data()['messages'][0]['content'][0]; + + return $block['type'] === 'document' + && $block['source'] === ['type' => 'text', 'media_type' => 'text/plain', 'data' => 'hello world']; + }); + } + public function testUploadedPdfFileMapsToDocumentContentBlock(): void { Http::fake([ From fe8df378c4afedfafe55c5063d3701f6365333ea Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:56:49 +0000 Subject: [PATCH 09/17] Decode structured output from a code fence with unpaired backticks When a model wraps its JSON in a code fence that is not closed, or closed with a different number of backticks, structured output decoding now reads the JSON after the opening fence as a last fallback. Port laravel/ai#1216 at a2cb93a2. Ported the decoding tests. Validation: the changed test file passes; formatting and full static analysis pass. --- .../Concerns/DecodesStructuredOutput.php | 26 +++++++++++++++ .../Concerns/DecodesStructuredOutputTest.php | 32 +++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php b/src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php index b1a693090..a2e9881a3 100644 --- a/src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php +++ b/src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php @@ -4,6 +4,8 @@ namespace Hypervel\Ai\Gateway\Concerns; +use Hypervel\Support\Str; + trait DecodesStructuredOutput { /** @@ -27,9 +29,33 @@ protected function decodeStructuredOutput(?string $text): array $decoded = json_decode($this->escapeQuotesInObjectKeys($this->extractJsonCodeFence($trimmed) ?? $trimmed), true); } + if (! is_array($decoded)) { + $decoded = $this->decodeUnpairedFence($trimmed); + } + return is_array($decoded) ? $decoded : []; } + /** + * Decode a payload whose code fence lost some of its backticks, as a whole or up to its first or last stray run. + */ + private function decodeUnpairedFence(string $text): ?array + { + $unfenced = ltrim($text, '`'); + + if ($unfenced !== $text && strncasecmp($unfenced, 'json', 4) === 0) { + $unfenced = substr($unfenced, 4); + } + + foreach (array_unique([$unfenced, Str::before($unfenced, '``'), Str::beforeLast($unfenced, '``')]) as $candidate) { + if (is_array($decoded = json_decode($candidate, true))) { + return $decoded; + } + } + + return null; + } + /** * Escape unescaped double quotes in object keys, where only a quote followed by a colon closes the key. */ diff --git a/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php b/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php index f61ac4d73..c4a43b16d 100644 --- a/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php +++ b/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php @@ -100,4 +100,36 @@ public function testEscapesUnescapedKeyQuotesInsideArraysAndFencesWithoutTouchin ], ], $this->decodeStructuredOutput($payload)); } + + public function testStripsBackticksThatDoNotPairIntoAFence(): void + { + $this->assertSame(['ok' => true], $this->decodeStructuredOutput('``{"ok":true}')); + $this->assertSame(['ok' => true], $this->decodeStructuredOutput('{"ok":true}``')); + $this->assertSame(['ok' => true], $this->decodeStructuredOutput('``{"ok":true}``')); + } + + public function testIgnoresACommentAfterTheStrayClosingBackticks(): void + { + $payload = "{\"ok\":true}\n``{/* asked for the rest */}"; + + $this->assertSame(['ok' => true], $this->decodeStructuredOutput($payload)); + } + + public function testDecodesAJsonFenceThatIsNeverClosed(): void + { + $this->assertSame(['ok' => true], $this->decodeStructuredOutput("```json\n{\"ok\":true}")); + } + + public function testReturnsEmptyArrayRatherThanPickingAnObjectOutOfSurroundingText(): void + { + $this->assertSame([], $this->decodeStructuredOutput('{"a":1}{"b":2}')); + $this->assertSame([], $this->decodeStructuredOutput('{"ok":true} hope this helps')); + $this->assertSame([], $this->decodeStructuredOutput('Example: {"name":"x"} Answer: ``{"real":1}``')); + } + + public function testKeepsBackticksInsideStringValuesWhenTheFenceLostItsDelimiters(): void + { + $this->assertSame(['reply' => 'type ``x`` here'], $this->decodeStructuredOutput('``{"reply":"type ``x`` here"}``')); + $this->assertSame(['code' => "```php\necho 1;\n```"], $this->decodeStructuredOutput('``{"code":"```php\necho 1;\n```"}``')); + } } From e0fe0b92f72fbee2053029a132942f8ee60f8c2c Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:57:07 +0000 Subject: [PATCH 10/17] Keep the text of every step in a stored prompted response A prompted response's text holds only its final step, so a stored turn lost text a model wrote before calling a tool, or all of it when the final step was empty. The database conversation store now joins the steps' text the way streamed text is joined: continuation steps run together and a tool call starts a new paragraph. Streamed responses keep the text their caller saw, and structured responses keep their structured text. The check that skips a blank approval-only turn uses the same text. Port laravel/ai#1222 at a2cb93a2. Unlike upstream, resuming a paused turn appends the resumed run's text to the paused text instead of rejoining every step, so text a response carries without steps, such as text a resumePausedRow() override supplies, is kept. A structured resume stores only its final structured text. Ported the store tests, and added tests for a structured resume and for an approval run without a paused row. The resume override test now reflects the append behavior. Validation: the store and AI test suites pass; formatting and full static analysis pass. --- .../src/Storage/DatabaseConversationStore.php | 36 ++++- .../Storage/DatabaseConversationStoreTest.php | 139 +++++++++++++++++- 2 files changed, 162 insertions(+), 13 deletions(-) diff --git a/src/ai/src/Storage/DatabaseConversationStore.php b/src/ai/src/Storage/DatabaseConversationStore.php index 2a5b27949..9a9131389 100644 --- a/src/ai/src/Storage/DatabaseConversationStore.php +++ b/src/ai/src/Storage/DatabaseConversationStore.php @@ -30,6 +30,7 @@ use Hypervel\Ai\Responses\Data\ToolCall; use Hypervel\Ai\Responses\Data\ToolResult; use Hypervel\Ai\Responses\StreamedAgentResponse; +use Hypervel\Ai\Responses\StructuredAgentResponse; use Hypervel\Ai\Streaming\Events\TextDelta; use Hypervel\Ai\Support\ConversationPartition; use Hypervel\Context\CoroutineContext; @@ -173,8 +174,9 @@ public function storeAssistantMessage(string $conversationId, ?string $participa $now = now(); $steps = $this->stepsFor($prompt, $response); + $content = $this->contentFor($response, $steps); - if ($prompt->hasApprovalDecisions() && blank($response->text) && $steps->every(fn (array $step) => $step['tool_calls'] === [])) { + if ($prompt->hasApprovalDecisions() && blank($content) && $steps->every(fn (array $step) => $step['tool_calls'] === [])) { return null; } @@ -183,7 +185,7 @@ public function storeAssistantMessage(string $conversationId, ?string $participa $this->table($this->messagesTable())->insert($this->messageAttributes($messageId, $conversationId, $participantType, $participantId, $now, [ 'agent' => $prompt->agent::class, 'role' => 'assistant', - 'content' => $response->text, + 'content' => $content, 'attachments' => '[]', 'steps' => $steps->toJson(), 'usage' => json_encode($response->usage), @@ -323,24 +325,25 @@ protected function pausedRowFor(string $conversationId, AgentPrompt $prompt): ?o protected function resumePausedRow(string $conversationId, object $paused, AgentPrompt $prompt, AgentResponse $response, ?Throwable $exception = null): string { $steps = $this->decodedSteps($paused); + $resumedSteps = $this->stepsFor($prompt, $response); if (($this->decoded($paused->meta)['provider'] ?? null) !== $response->meta->provider) { $steps = $this->withoutReplayBlocks($steps); } if ($response->steps->isNotEmpty()) { - $steps = $steps->concat($this->stepsFor($prompt, $response)); + $steps = $steps->concat($resumedSteps); } if (! $response->hasPendingApprovals()) { $steps = $this->withoutReplayBlocks($steps); } - // Unlike upstream, a streamed resume appends its text to the paused content instead of rejoining every - // step, which would split a continuation the stream displayed as one paragraph, such as a pause_turn. - $content = $response instanceof StreamedAgentResponse - ? TextDelta::join([$paused->content, $response->text]) - : $response->text; + // Unlike upstream, a resume appends its own text to the paused content instead of rejoining every + // step, so text a response carries without steps, such as one an override supplies, is kept. + $content = $response instanceof StructuredAgentResponse + ? $response->text + : TextDelta::join([$paused->content, $this->contentFor($response, $resumedSteps)]); if (blank($content)) { $content = $paused->content; @@ -442,6 +445,23 @@ protected function toolCallsFor(iterable $toolCalls, iterable $toolResults, Coll })->values()->all(); } + /** + * Join the text of the turn's steps the way TextDelta::combine() joins a stream. + * + * @param Collection $steps + */ + protected function contentFor(AgentResponse $response, Collection $steps): string + { + // A streamed response's text is already the joined text its caller saw. + if ($response instanceof StructuredAgentResponse || $response instanceof StreamedAgentResponse) { + return $response->text; + } + + return TextDelta::join($steps + ->chunkWhile(fn (array $step, int $key, Collection $previous): bool => $previous->last()['tool_calls'] === []) + ->map(fn (Collection $steps): string => $steps->pluck('content')->join(''))); + } + /** * Drop the raw provider blocks of the paused rows a now-completed turn resumed from. */ diff --git a/tests/Ai/Feature/Storage/DatabaseConversationStoreTest.php b/tests/Ai/Feature/Storage/DatabaseConversationStoreTest.php index 97703a3f6..787b6be3d 100644 --- a/tests/Ai/Feature/Storage/DatabaseConversationStoreTest.php +++ b/tests/Ai/Feature/Storage/DatabaseConversationStoreTest.php @@ -37,6 +37,7 @@ use Hypervel\Ai\Responses\Data\ToolResult; use Hypervel\Ai\Responses\Data\UrlCitation; use Hypervel\Ai\Responses\StreamedAgentResponse; +use Hypervel\Ai\Responses\StructuredAgentResponse; use Hypervel\Ai\Storage\DatabaseConversationStore; use Hypervel\Ai\Storage\StoredMessage; use Hypervel\Ai\Streaming\Events\Citation as CitationEvent; @@ -65,6 +66,7 @@ use JMac\Testing\Double; use JMac\Testing\Integrations\PHPUnit\VerifiesDoubles; use PHPUnit\Framework\Attributes\DataProvider; +use PHPUnit\Framework\Attributes\TestWith; use RuntimeException; use Throwable; @@ -660,11 +662,138 @@ public function testAResumeFoldsItsStepsTextAndUsageIntoThePausedRow(bool $strea public static function resumeStreamingModes(): array { return [ - 'prompted' => [false, 'Done.'], + 'prompted' => [false, "Let me check.\n\nDone."], 'streamed' => [true, "Let me check.\n\nDone."], ]; } + public function testAPromptedTurnStoresTheTextOfEveryStepWhenItsFinalStepIsEmpty(): void + { + $store = new DatabaseConversationStore; + $conversationId = $store->storeConversation('user', 1, 'Tool conversation'); + + $response = new AgentResponse('invocation-id', '', new TextUsage, new Meta('openai', 'gpt-5')); + $response->steps = collect([ + new Step('Here is the answer.', [new ToolCall('call-1', 'LogAnswer', [])], [new ToolResult('call-1', 'LogAnswer', [], 'Logged')], FinishReason::ToolCalls, new TextUsage, new Meta, '', []), + new Step('', [], [], FinishReason::Stop, new TextUsage, new Meta, '', []), + ]); + + $store->storeAssistantMessage($conversationId, 'user', 1, new AgentPrompt(new ToolUsingAgent, 'Answer', [], Double::for(TextProvider::class)->strict(), 'test-model'), $response); + + $this->assertSame('Here is the answer.', DB::table('agent_conversation_messages')->where('role', 'assistant')->value('content')); + } + + public function testATurnJoinsContinuationStepsWithoutAParagraphBreak(): void + { + $store = new DatabaseConversationStore; + $conversationId = $store->storeConversation('user', 1, 'Tool conversation'); + + $response = new AgentResponse('invocation-id', 'It is 12°C.', new TextUsage, new Meta('anthropic', 'claude')); + $response->steps = collect([ + new Step('Laravel 13 is current, which', [], [], FinishReason::Continue, new TextUsage, new Meta, '', []), + new Step(' shipped in March.', [new ToolCall('call-1', 'GetWeather', [])], [new ToolResult('call-1', 'GetWeather', [], '12°C')], FinishReason::ToolCalls, new TextUsage, new Meta, '', []), + new Step('It is 12°C.', [], [], FinishReason::Stop, new TextUsage, new Meta, '', []), + ]); + + $store->storeAssistantMessage($conversationId, 'user', 1, new AgentPrompt(new ToolUsingAgent, 'Weather?', [], Double::for(TextProvider::class)->strict(), 'test-model'), $response); + + $this->assertSame("Laravel 13 is current, which shipped in March.\n\nIt is 12°C.", DB::table('agent_conversation_messages')->where('role', 'assistant')->value('content')); + } + + #[TestWith([false], 'prompted')] + #[TestWith([true], 'streamed')] + public function testAResumeJoinsItsContinuationStepsWithoutAParagraphBreak(bool $streamed): void + { + $store = new DatabaseConversationStore; + $conversationId = $store->storeConversation('user', 1, 'Approval conversation'); + + insertAssistantTurn($conversationId, 'paused-1', 'Let me check.', [ + assistantStep( + [['id' => 'call-1', 'name' => 'DeleteFile', 'arguments' => []]], + [['id' => 'call-1', 'name' => 'DeleteFile', 'arguments' => [], 'result' => 'Deleted', 'result_id' => null]], + ), + ], []); + + $prompt = new AgentPrompt(new ToolUsingAgent, '', [], Double::for(TextProvider::class)->strict(), 'test-model', approvalDecisions: Decisions::from(['call-1' => true])); + + $steps = collect([ + new Step('Revenue grew', [], [], FinishReason::Continue, new TextUsage, new Meta, '', []), + new Step(' 4%.', [], [], FinishReason::Stop, new TextUsage, new Meta, '', []), + ]); + + if ($streamed) { + $response = new StreamedAgentResponse('invocation-id', collect([ + new TextDelta('event-1', 'message-1', 'Revenue grew', 0), + new TextDelta('event-2', 'message-1', ' 4%.', 0), + new StreamEnd('event-3', 'stop', new TextUsage, 0, $steps), + ]), new Meta('anthropic', 'claude')); + } else { + $response = new AgentResponse('invocation-id', ' 4%.', new TextUsage, new Meta('anthropic', 'claude')); + $response->steps = $steps; + } + + $store->storeAssistantMessage($conversationId, 'user', 1, $prompt, $response); + + $this->assertSame("Let me check.\n\nRevenue grew 4%.", DB::table('agent_conversation_messages')->where('role', 'assistant')->value('content')); + } + + public function testAStructuredTurnStoresItsStructuredTextRatherThanTheTextOfEveryStep(): void + { + $store = new DatabaseConversationStore; + $conversationId = $store->storeConversation('user', 1, 'Structured conversation'); + + $response = new StructuredAgentResponse('invocation-id', ['answer' => 42], '{"answer":42}', new TextUsage, new Meta('openai', 'gpt-5')); + $response->steps = collect([ + new Step('Let me check.', [new ToolCall('call-1', 'Lookup', [])], [new ToolResult('call-1', 'Lookup', [], '42')], FinishReason::ToolCalls, new TextUsage, new Meta, '', []), + new Step('{"answer":42}', [], [], FinishReason::Stop, new TextUsage, new Meta, '', []), + ]); + + $store->storeAssistantMessage($conversationId, 'user', 1, new AgentPrompt(new ToolUsingAgent, 'Answer', [], Double::for(TextProvider::class)->strict(), 'test-model'), $response); + + $this->assertSame('{"answer":42}', DB::table('agent_conversation_messages')->where('role', 'assistant')->value('content')); + } + + public function testAStructuredResumeStoresOnlyItsFinalStructuredText(): void + { + $store = new DatabaseConversationStore; + $conversationId = $store->storeConversation('user', 1, 'Structured conversation'); + + insertAssistantTurn($conversationId, 'paused-1', 'Let me check.', [ + assistantStep( + [['id' => 'call-1', 'name' => 'Lookup', 'arguments' => []]], + [['id' => 'call-1', 'name' => 'Lookup', 'arguments' => [], 'result' => '42', 'result_id' => null]], + ), + ], []); + + $prompt = new AgentPrompt(new ToolUsingAgent, '', [], Double::for(TextProvider::class)->strict(), 'test-model', approvalDecisions: Decisions::from(['call-1' => true])); + + $response = new StructuredAgentResponse('invocation-id', ['answer' => 42], '{"answer":42}', new TextUsage, new Meta('openai', 'gpt-5')); + $response->steps = collect([ + new Step('{"answer":42}', [], [], FinishReason::Stop, new TextUsage, new Meta, '', []), + ]); + + $store->storeAssistantMessage($conversationId, 'user', 1, $prompt, $response); + + $this->assertSame('{"answer":42}', DB::table('agent_conversation_messages')->where('role', 'assistant')->value('content')); + } + + public function testAnApprovalRunWithoutAPausedRowKeepsTheTextOfAnEarlierStep(): void + { + $store = new DatabaseConversationStore; + $conversationId = $store->storeConversation('user', 1, 'Approval conversation'); + + $prompt = new AgentPrompt(new ToolUsingAgent, '', [], Double::for(TextProvider::class)->strict(), 'test-model', approvalDecisions: Decisions::from(['call-1' => true])); + + $response = new AgentResponse('invocation-id', '', new TextUsage, new Meta('anthropic', 'claude')); + $response->steps = collect([ + new Step('Checking.', [], [], FinishReason::Continue, new TextUsage, new Meta, '', []), + new Step('', [], [], FinishReason::Stop, new TextUsage, new Meta, '', []), + ]); + + $this->assertNotNull($store->storeAssistantMessage($conversationId, 'user', 1, $prompt, $response)); + $this->assertSame('Checking.', DB::table('agent_conversation_messages')->where('role', 'assistant')->value('content')); + } + public function testAStreamedTurnThatPausesTwiceKeepsTheTextOfEveryStep(): void { $store = new DatabaseConversationStore; @@ -2140,11 +2269,11 @@ public function testAResumeOverrideReceivesTheFullPausedRow(): void { $store = new class extends DatabaseConversationStore { /** - * Include the prior response text when customizing the resumed message. + * Customize the resumed text from the paused row. */ protected function resumePausedRow(string $conversationId, object $paused, AgentPrompt $prompt, AgentResponse $response, ?Throwable $exception = null): string { - $response->text = $paused->content . ' ' . $response->text; + $response->text = "Resumed after: {$paused->content}"; return parent::resumePausedRow($conversationId, $paused, $prompt, $response, $exception); } @@ -2154,7 +2283,7 @@ protected function resumePausedRow(string $conversationId, object $paused, Agent $store->storeTurn($conversationId, null, null, null, $prompt, $this->response()); - $this->assertDatabaseHas('agent_conversation_messages', ['id' => $messageId, 'content' => 'Hello back Hello back']); + $this->assertDatabaseHas('agent_conversation_messages', ['id' => $messageId, 'content' => "Hello back\n\nResumed after: Hello back"]); } public function testAnotherClaimCannotRecordResults(): void @@ -2341,7 +2470,7 @@ private function pause(DatabaseConversationStore $store): array { $conversationId = $store->storeConversation(null, null, 'Approval'); $response = $this->response()->withSteps(collect([ - new Step('', [new ToolCall('call-1', 'send_email', [], 'result-1')], [], FinishReason::ToolCalls, new TextUsage, new Meta, '', [['type' => 'tool_use', 'id' => 'call-1']]), + new Step('Hello back', [new ToolCall('call-1', 'send_email', [], 'result-1')], [], FinishReason::ToolCalls, new TextUsage, new Meta, '', [['type' => 'tool_use', 'id' => 'call-1']]), ]))->withPendingApprovals(collect([new PendingApproval('call-1', 'send_email', [], 'Sends an email')])); return [$conversationId, $store->storeAssistantMessage($conversationId, null, null, $this->prompt(), $response)]; From 1944d2d43ee94ebcd6623bc3bfac72ac8e1c859a Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:57:07 +0000 Subject: [PATCH 11/17] Keep every tool call of a streamed Ollama reply Hypervel merged streamed Ollama tool calls by their index, or by their position within a chunk. Ollama sends each tool call complete, and calls streamed in separate chunks can share an index, so distinct calls were folded into one. Each streamed tool call is now kept as it arrives, mapped by the same method as buffered responses, and a call without a function is ignored. Calls are still only run after the done chunk. Port laravel/ai#1218 at a2cb93a2. Ported the streaming tests and helper, replacing the fragment-accumulation test, which covered a format Ollama does not send. Validation: the changed test files pass; formatting and full static analysis pass. --- .../Ollama/Concerns/HandlesTextStreaming.php | 72 ++--------- .../Ollama/Concerns/ParsesTextResponses.php | 26 ++-- .../Providers/Ollama/StreamingTest.php | 114 +++++++++--------- tests/Ai/Fixtures/OllamaHelpers.php | 7 +- 4 files changed, 89 insertions(+), 130 deletions(-) diff --git a/src/ai/src/Gateway/Ollama/Concerns/HandlesTextStreaming.php b/src/ai/src/Gateway/Ollama/Concerns/HandlesTextStreaming.php index 63541efdc..bd714822a 100644 --- a/src/ai/src/Gateway/Ollama/Concerns/HandlesTextStreaming.php +++ b/src/ai/src/Gateway/Ollama/Concerns/HandlesTextStreaming.php @@ -10,7 +10,6 @@ use Hypervel\Ai\Responses\Data\FinishReason; use Hypervel\Ai\Responses\Data\Meta; use Hypervel\Ai\Responses\Data\TextUsage; -use Hypervel\Ai\Responses\Data\ToolCall; use Hypervel\Ai\Streaming\Events\Error; use Hypervel\Ai\Streaming\Events\ReasoningDelta; use Hypervel\Ai\Streaming\Events\ReasoningEnd; @@ -44,7 +43,6 @@ protected function processTextStream( $textStartEmitted = false; $currentText = ''; $toolCalls = []; - $pendingToolCalls = []; $usage = null; $lastData = []; @@ -128,43 +126,9 @@ protected function processTextStream( ))->withInvocationId($invocationId); } - // Tool call indexes span chunks, while array positions restart in each chunk. - // Retain positional merging for fragments that omit an explicit index. - if (! empty($data['message']['tool_calls'])) { - foreach ($data['message']['tool_calls'] as $index => $toolCall) { - $index = $toolCall['function']['index'] ?? $index; - - if (! isset($pendingToolCalls[$index])) { - $pendingToolCalls[$index] = [ - 'id' => null, - 'name' => '', - 'arguments' => [], - 'argumentsBuffer' => '', - ]; - } - - if (isset($toolCall['id'])) { - $pendingToolCalls[$index]['id'] = $toolCall['id']; - } - - $name = $toolCall['function']['name'] ?? ''; - - if ($name !== '') { - $pendingToolCalls[$index]['name'] = $name; - } - - if (array_key_exists('arguments', $toolCall['function'] ?? [])) { - $arguments = $toolCall['function']['arguments']; - - if (is_array($arguments)) { - $pendingToolCalls[$index]['arguments'] = array_replace( - $pendingToolCalls[$index]['arguments'], - $arguments - ); - } elseif (is_string($arguments)) { - $pendingToolCalls[$index]['argumentsBuffer'] .= $arguments; - } - } + foreach ($data['message']['tool_calls'] ?? [] as $toolCall) { + if (is_array($toolCall['function'] ?? null)) { + $toolCalls[] = $this->mapToolCall($toolCall); } } @@ -208,30 +172,12 @@ protected function processTextStream( ))->withInvocationId($invocationId); } - if (filled($pendingToolCalls)) { - $toolCalls = array_map(function (array $toolCall): ToolCall { - $arguments = $toolCall['arguments']; - - if ($toolCall['argumentsBuffer'] !== '') { - $decoded = json_decode((string) $toolCall['argumentsBuffer'], true); - - if (is_array($decoded)) { - $arguments = array_replace($arguments, $decoded); - } - } - - $id = $toolCall['id'] ?? (string) Str::uuid7(); - - return new ToolCall($id, $toolCall['name'], $arguments, $id); - }, array_values($pendingToolCalls)); - - foreach ($toolCalls as $toolCall) { - yield (new ToolCallEvent( - $this->generateEventId(), - $toolCall, - time(), - ))->withInvocationId($invocationId); - } + foreach ($toolCalls as $toolCall) { + yield (new ToolCallEvent( + $this->generateEventId(), + $toolCall, + time(), + ))->withInvocationId($invocationId); } $finishReason = $this->extractFinishReason($lastData); diff --git a/src/ai/src/Gateway/Ollama/Concerns/ParsesTextResponses.php b/src/ai/src/Gateway/Ollama/Concerns/ParsesTextResponses.php index 3646c3cbc..49f350f11 100644 --- a/src/ai/src/Gateway/Ollama/Concerns/ParsesTextResponses.php +++ b/src/ai/src/Gateway/Ollama/Concerns/ParsesTextResponses.php @@ -47,16 +47,7 @@ protected function parseTextResponse( $text = $message['content'] ?? ''; $rawToolCalls = $message['tool_calls'] ?? []; - $mappedToolCalls = array_map(function (array $toolCall): ToolCall { - $id = $toolCall['id'] ?? (string) Str::uuid7(); - - return new ToolCall( - id: $id, - name: $toolCall['function']['name'] ?? '', - arguments: $this->parseToolArguments($toolCall['function']['arguments'] ?? []), - resultId: $toolCall['id'] ?? null, - ); - }, $rawToolCalls); + $mappedToolCalls = array_map($this->mapToolCall(...), $rawToolCalls); $finishReason = $this->extractFinishReason($data); @@ -88,6 +79,21 @@ protected function parseToolArguments(mixed $arguments): array return json_decode($arguments ?? '{}', true) ?? []; } + /** + * Map an Ollama tool call to a tool call. + */ + protected function mapToolCall(array $toolCall): ToolCall + { + $id = $toolCall['id'] ?? (string) Str::uuid7(); + + return new ToolCall( + id: $id, + name: $toolCall['function']['name'] ?? '', + arguments: $this->parseToolArguments($toolCall['function']['arguments'] ?? []), + resultId: $toolCall['id'] ?? null, + ); + } + /** * Extract usage data from the Ollama response. */ diff --git a/tests/Ai/Feature/Providers/Ollama/StreamingTest.php b/tests/Ai/Feature/Providers/Ollama/StreamingTest.php index 94409672a..8d59070ed 100644 --- a/tests/Ai/Feature/Providers/Ollama/StreamingTest.php +++ b/tests/Ai/Feature/Providers/Ollama/StreamingTest.php @@ -228,50 +228,38 @@ public function testStreamingRejectsPrematureEof(): void $this->assertEmpty(array_filter($events, fn (StreamEvent $event): bool => $event instanceof TextEnd || $event instanceof StreamEnd)); } - public function testStreamingAccumulatesToolCallArgumentsAcrossChunks(): void + public function testStreamingIgnoresAToolCallWithoutAFunction(): void + { + Http::fake([ + '*' => Http::response( + body: $this->ndjsonPayload([ + $this->chatChunkWithToolCalls([['id' => 'call_1']]), + ]), + status: 200, + ), + ]); + + $events = $this->collectStreamEvents(agent: new ProviderOptionsWithToolsAgent); + + $this->assertEmpty(array_filter($events, fn (StreamEvent $e): bool => $e instanceof ToolCallEvent)); + } + + public function testStreamingGeneratesFallbackIdWhenToolCallHasNoId(): void { Http::fake([ '*' => Http::sequence([ Http::response( body: $this->ndjsonPayload([ - // First chunk: id + name but no arguments yet. [ 'model' => 'llama3.1:8b', 'message' => [ 'role' => 'assistant', 'content' => '', 'tool_calls' => [[ - 'id' => 'call_1', + // No "id" — Ollama sometimes omits it. 'function' => [ 'name' => 'FixedNumberGenerator', - ], - ]], - ], - 'done' => false, - ], - // Second chunk: argument fragment as partial JSON string. - [ - 'model' => 'llama3.1:8b', - 'message' => [ - 'role' => 'assistant', - 'content' => '', - 'tool_calls' => [[ - 'function' => [ - 'arguments' => '{"foo":', - ], - ]], - ], - 'done' => false, - ], - // Third chunk: remainder of the arguments payload. - [ - 'model' => 'llama3.1:8b', - 'message' => [ - 'role' => 'assistant', - 'content' => '', - 'tool_calls' => [[ - 'function' => [ - 'arguments' => '"bar"}', + 'arguments' => (object) [], ], ]], ], @@ -298,35 +286,53 @@ public function testStreamingAccumulatesToolCallArgumentsAcrossChunks(): void $toolCallEvents = array_values(array_filter($events, fn (StreamEvent $e): bool => $e instanceof ToolCallEvent)); $this->assertCount(1, $toolCallEvents); - $this->assertSame('call_1', $toolCallEvents[0]->toolCall->id); $this->assertSame('FixedNumberGenerator', $toolCallEvents[0]->toolCall->name); + $this->assertNotEmpty($toolCallEvents[0]->toolCall->id); + } + + public function testStreamingKeepsEveryToolCallWhenEachArrivesInItsOwnChunk(): void + { + Http::fake([ + '*' => Http::sequence([ + Http::response( + body: $this->ndjsonPayload([ + $this->chatChunkWithToolCalls([$this->toolCallChunk('call_1', 'FixedNumberGenerator', ['foo' => 'bar'], 0)], done: false), + $this->chatChunkWithToolCalls([$this->toolCallChunk('call_2', 'FixedNumberGenerator', ['baz' => 'qux'], 1)], done: false), + $this->chatChunk('', true, 'stop'), + ]), + status: 200, + ), + Http::response( + body: $this->ndjsonPayload([ + $this->chatChunk('done'), + $this->chatChunk('', true, 'stop'), + ]), + status: 200, + ), + ]), + ]); + + $events = $this->collectStreamEvents(agent: new ProviderOptionsWithToolsAgent); + + $toolCallEvents = array_values(array_filter($events, fn (StreamEvent $e): bool => $e instanceof ToolCallEvent)); + + $this->assertCount(2, $toolCallEvents); + $this->assertSame('call_1', $toolCallEvents[0]->toolCall->id); $this->assertSame(['foo' => 'bar'], $toolCallEvents[0]->toolCall->arguments); + $this->assertSame('call_2', $toolCallEvents[1]->toolCall->id); + $this->assertSame(['baz' => 'qux'], $toolCallEvents[1]->toolCall->arguments); } - public function testStreamingGeneratesFallbackIdWhenToolCallHasNoId(): void + public function testStreamingKeepsToolCallsSentTogetherInOneChunk(): void { Http::fake([ '*' => Http::sequence([ Http::response( body: $this->ndjsonPayload([ - [ - 'model' => 'llama3.1:8b', - 'message' => [ - 'role' => 'assistant', - 'content' => '', - 'tool_calls' => [[ - // No "id" — Ollama sometimes omits it. - 'function' => [ - 'name' => 'FixedNumberGenerator', - 'arguments' => (object) [], - ], - ]], - ], - 'done_reason' => 'tool_calls', - 'done' => true, - 'prompt_eval_count' => 1, - 'eval_count' => 1, - ], + $this->chatChunkWithToolCalls([ + $this->toolCallChunk('call_1', 'FixedNumberGenerator', ['foo' => 'bar']), + $this->toolCallChunk('call_2', 'FixedNumberGenerator', ['baz' => 'qux']), + ]), ]), status: 200, ), @@ -344,9 +350,9 @@ public function testStreamingGeneratesFallbackIdWhenToolCallHasNoId(): void $toolCallEvents = array_values(array_filter($events, fn (StreamEvent $e): bool => $e instanceof ToolCallEvent)); - $this->assertCount(1, $toolCallEvents); - $this->assertSame('FixedNumberGenerator', $toolCallEvents[0]->toolCall->name); - $this->assertNotEmpty($toolCallEvents[0]->toolCall->id); + $this->assertCount(2, $toolCallEvents); + $this->assertSame('call_1', $toolCallEvents[0]->toolCall->id); + $this->assertSame('call_2', $toolCallEvents[1]->toolCall->id); } public function testStreamingCapturesUsageFromFinalChunk(): void diff --git a/tests/Ai/Fixtures/OllamaHelpers.php b/tests/Ai/Fixtures/OllamaHelpers.php index 2e9f099ef..f3120e3f6 100644 --- a/tests/Ai/Fixtures/OllamaHelpers.php +++ b/tests/Ai/Fixtures/OllamaHelpers.php @@ -145,14 +145,15 @@ protected function chatChunkWithToolCalls(array $toolCalls, bool $done = true): /** * Create a tool call chunk. */ - protected function toolCallChunk(string $id, string $name, array $arguments = []): array + protected function toolCallChunk(string $id, string $name, array $arguments = [], ?int $index = null): array { return [ 'id' => $id, - 'function' => [ + 'function' => array_filter([ + 'index' => $index, 'name' => $name, 'arguments' => (object) $arguments, - ], + ], fn (mixed $value): bool => $value !== null), ]; } } From ea7dc97bc6bc25ac6db4790074ea3915ddfcd470 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 02:02:28 +0000 Subject: [PATCH 12/17] Classify provider errors when default JSON decoding throws An application can add JSON_THROW_ON_ERROR to Response::$defaultJsonDecodingFlags. Failover handling then read a non-JSON error body, such as an HTML error page, through json(), and the JsonException replaced the rate limited, overloaded or request exception the failure should have raised. Every error-body read in failover handling now decodes with flags: 0, and the xAI and Gemini API key checks read the body only for the statuses they inspect. Validation: the changed test files pass; formatting and full static analysis pass. --- .../Concerns/HandlesFailoverErrors.php | 7 ++++--- .../Gemini/Concerns/HandlesGeminiErrors.php | 16 +++++++++++---- .../Gateway/Xai/Concerns/HandlesXaiErrors.php | 4 +--- .../Providers/Gemini/ErrorHandlingTest.php | 20 +++++++++++++++++++ .../Providers/Xai/ErrorHandlingTest.php | 20 +++++++++++++++++++ .../Concerns/HandlesFailoverErrorsTest.php | 19 ++++++++++++++++++ 6 files changed, 76 insertions(+), 10 deletions(-) diff --git a/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php b/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php index b28f3d4f6..d78167547 100644 --- a/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php +++ b/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php @@ -74,7 +74,8 @@ protected function withErrorHandling(string $providerName, Closure $callback): m ); } - $message = $requestException->response->json('error.message'); + // An error body may not be JSON, and the application's default decoding flags may throw. + $message = $requestException->response->json('error.message', flags: 0); if (is_string($message) && $patterns = $this->insufficientCreditPatterns()) { $message = strtolower($message); @@ -143,8 +144,8 @@ protected function isInsufficientCredits(RequestException $exception): bool $codes = $this->insufficientCreditCodes(); - return in_array($exception->response->json('error.code'), $codes, true) - || in_array($exception->response->json('error.type'), $codes, true); + return in_array($exception->response->json('error.code', flags: 0), $codes, true) + || in_array($exception->response->json('error.type', flags: 0), $codes, true); } /** diff --git a/src/ai/src/Gateway/Gemini/Concerns/HandlesGeminiErrors.php b/src/ai/src/Gateway/Gemini/Concerns/HandlesGeminiErrors.php index ed721501d..80e95fc53 100644 --- a/src/ai/src/Gateway/Gemini/Concerns/HandlesGeminiErrors.php +++ b/src/ai/src/Gateway/Gemini/Concerns/HandlesGeminiErrors.php @@ -17,16 +17,24 @@ trait HandlesGeminiErrors */ protected function isInvalidApiKey(RequestException $exception): bool { + $status = $exception->response->status(); + + if ($status === 401) { + return true; + } + + if ($status !== 400 && $status !== 403) { + return false; + } + // The Interactions API wraps its error body in a list. - $error = $exception->response->json('0.error') ?? $exception->response->json('error'); + $error = $exception->response->json('0.error', flags: 0) ?? $exception->response->json('error', flags: 0); $message = is_string($error['message'] ?? null) ? $error['message'] : ''; - return match ($exception->response->status()) { - 401 => true, + return match ($status) { 400 => collect($error['details'] ?? [])->contains('reason', 'API_KEY_INVALID'), 403 => Str::contains($message, ['unregistered callers', 'reported as leaked']), - default => false, }; } } diff --git a/src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php b/src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php index c4367f9ce..705f7a05d 100644 --- a/src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php +++ b/src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php @@ -16,11 +16,9 @@ trait HandlesXaiErrors */ protected function isInvalidApiKey(RequestException $exception): bool { - $error = $exception->response->json('error'); - return match ($exception->response->status()) { 401 => true, - 400 => is_string($error) && str_starts_with($error, 'Incorrect API key'), + 400 => is_string($error = $exception->response->json('error', flags: 0)) && str_starts_with($error, 'Incorrect API key'), default => false, }; } diff --git a/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php b/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php index a046b9cd7..c91e41ec8 100644 --- a/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php +++ b/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php @@ -13,6 +13,7 @@ use Hypervel\Ai\Responses\Data\FinishReason; use Hypervel\Http\Client\ConnectionException; use Hypervel\Http\Client\RequestException; +use Hypervel\Http\Client\Response; use Hypervel\Support\Facades\Http; use Hypervel\Tests\Ai\Fixtures\Agents\AssistantAgent; use Hypervel\Tests\Ai\Fixtures\GeminiHelpers; @@ -235,6 +236,25 @@ public static function rejectedApiKeys(): array ]; } + #[DataProvider('nonJsonFailures')] + public function testANonJsonErrorBodyKeepsItsExceptionWhenDefaultDecodingThrows(int $status, string $exception): void + { + Response::$defaultJsonDecodingFlags = JSON_THROW_ON_ERROR; + Http::fake(['generativelanguage.googleapis.com/*' => Http::response('Error', $status)]); + + $this->expectException($exception); + + (new AssistantAgent)->prompt('Hi', provider: 'gemini'); + } + + /** + * Provide failures before and after the API key check reads the error body. + */ + public static function nonJsonFailures(): array + { + return [[503, ProviderOverloadedException::class], [403, RequestException::class]]; + } + public function testAPermissionErrorUnrelatedToTheApiKeyStaysARequestException(): void { Http::fake([ diff --git a/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php b/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php index cc3465e0e..55b7ccb7c 100644 --- a/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php +++ b/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php @@ -10,6 +10,7 @@ use Hypervel\Ai\Exceptions\RateLimitedException; use Hypervel\Contracts\Foundation\Application; use Hypervel\Http\Client\RequestException; +use Hypervel\Http\Client\Response; use Hypervel\Support\Facades\Http; use Hypervel\Tests\Ai\Fixtures\Agents\AssistantAgent; use Hypervel\Tests\Ai\TestCase; @@ -131,4 +132,23 @@ public static function rejectedApiKeys(): array ]], ]; } + + #[DataProvider('nonJsonFailures')] + public function testANonJsonErrorBodyKeepsItsExceptionWhenDefaultDecodingThrows(int $status, string $exception): void + { + Response::$defaultJsonDecodingFlags = JSON_THROW_ON_ERROR; + Http::fake(['*' => Http::response('Error', $status)]); + + $this->expectException($exception); + + (new AssistantAgent)->prompt('Hi', provider: 'xai'); + } + + /** + * Provide failures before and after the API key check reads the error body. + */ + public static function nonJsonFailures(): array + { + return [[503, ProviderOverloadedException::class], [400, RequestException::class]]; + } } diff --git a/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php b/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php index 2dfbe01ee..22210ebc8 100644 --- a/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php +++ b/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php @@ -128,6 +128,25 @@ public function test429WithANonJsonBodyStillThrowsRateLimitedException(): void $this->withErrorHandling('openai', fn (): never => throw new RequestException(new Response($response))); } + #[DataProvider('nonJsonFailures')] + public function testANonJsonErrorBodyKeepsItsExceptionWhenDefaultDecodingThrows(int $status, string $exception): void + { + Response::$defaultJsonDecodingFlags = JSON_THROW_ON_ERROR; + $response = new Psr7Response($status, ['Content-Type' => 'text/html'], 'Error'); + + $this->expectException($exception); + + $this->withErrorHandling('openai', fn (): never => throw new RequestException(new Response($response))); + } + + /** + * Provide failures whose classification reads the error body. + */ + public static function nonJsonFailures(): array + { + return [[429, RateLimitedException::class], [400, RequestException::class]]; + } + public function test429WithAnInsufficientQuotaErrorIsNotRetried(): void { Sleep::fake(); From fd3af4a3c1bfb713f39a80c6f1965c6f831006cd Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 02:02:28 +0000 Subject: [PATCH 13/17] Decode a fence closed with a lone or longer backtick run The unpaired-fence fallback still failed when a model closed its JSON with a single backtick, wrapped it in one backtick on each side, or closed a two-backtick fence with three. Each candidate now drops its trailing backticks before decoding. Follow-up to laravel/ai#1216 at a2cb93a2, which has the same gap. Validation: the changed test file passes; formatting and full static analysis pass. --- src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php | 6 +++++- .../Unit/Gateway/Concerns/DecodesStructuredOutputTest.php | 7 +++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php b/src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php index a2e9881a3..f5a89b873 100644 --- a/src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php +++ b/src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php @@ -47,7 +47,11 @@ private function decodeUnpairedFence(string $text): ?array $unfenced = substr($unfenced, 4); } - foreach (array_unique([$unfenced, Str::before($unfenced, '``'), Str::beforeLast($unfenced, '``')]) as $candidate) { + $candidates = [$unfenced, Str::before($unfenced, '``'), Str::beforeLast($unfenced, '``')]; + + // Unlike upstream, each candidate also drops its trailing backticks, so a closing fence with a single + // backtick, or with more backticks than the opening one, does not leave one behind. + foreach (array_unique(array_map(fn (string $candidate): string => rtrim($candidate, '`'), $candidates)) as $candidate) { if (is_array($decoded = json_decode($candidate, true))) { return $decoded; } diff --git a/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php b/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php index c4a43b16d..8ad5c67a1 100644 --- a/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php +++ b/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php @@ -132,4 +132,11 @@ public function testKeepsBackticksInsideStringValuesWhenTheFenceLostItsDelimiter $this->assertSame(['reply' => 'type ``x`` here'], $this->decodeStructuredOutput('``{"reply":"type ``x`` here"}``')); $this->assertSame(['code' => "```php\necho 1;\n```"], $this->decodeStructuredOutput('``{"code":"```php\necho 1;\n```"}``')); } + + public function testStripsAWholeClosingRunThatDoesNotMatchTheOpeningFence(): void + { + $this->assertSame(['ok' => true], $this->decodeStructuredOutput('{"ok":true}`')); + $this->assertSame(['ok' => true], $this->decodeStructuredOutput('`{"ok":true}`')); + $this->assertSame(['reply' => 'type ``x`` here'], $this->decodeStructuredOutput('``{"reply":"type ``x`` here"}```')); + } } From c38b5b839d6f54c8ba3b9f1c2334d9d0bcce9f53 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 02:02:28 +0000 Subject: [PATCH 14/17] Keep streamed Anthropic citations on their text blocks Streaming emitted an event for each web search citation but did not add the citation to its content block, so the step's citations and the replay content sent back on a later turn lacked it, unlike a buffered response. Each citations_delta is now stored on its text block. Extended the streaming citation test to check the step's citations and replay blocks. Validation: the changed test file passes; formatting and full static analysis pass. --- .../Anthropic/Concerns/HandlesTextStreaming.php | 6 ++++++ tests/Ai/Feature/Providers/Anthropic/StreamingTest.php | 10 +++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php b/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php index 46646a237..35c11045d 100644 --- a/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php +++ b/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php @@ -282,6 +282,12 @@ protected function processTextStream( } elseif ($deltaType === 'citations_delta' && $currentBlockType === 'text') { $citationData = $data['delta']['citation'] ?? null; + // Unlike upstream, the citation is kept on its block, as in a buffered response, + // so the step's citations and replay content include it. + if ($citationData && isset($responseContent[$currentBlockIndex])) { + $responseContent[$currentBlockIndex]['citations'][] = $citationData; + } + if ($citationData && ($citationData['type'] ?? '') === 'web_search_result_location' && ($event = $emitCitation(new UrlCitation($citationData['url'] ?? '', $citationData['title'] ?? null))) instanceof StreamEvent) { yield $event; diff --git a/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php b/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php index a75797728..7a8229360 100644 --- a/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php +++ b/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php @@ -890,11 +890,19 @@ public function testStreamingEmitsOneCitationPerCitedWebSearchSource(): void ), ]); + $events = $this->collectStreamEvents(); + $citations = array_map( fn (CitationEvent $e): array => [$e->citation->url, $e->citation->title], - array_values(array_filter($this->collectStreamEvents(), fn ($e): bool => $e instanceof CitationEvent)), + array_values(array_filter($events, fn ($e): bool => $e instanceof CitationEvent)), ); $this->assertSame([['https://laravel-news.com/laravel-13', 'Laravel 13']], $citations); + + $step = collect($events)->first(fn ($e): bool => $e instanceof StreamEnd)->steps->sole(); + + $this->assertSame(['https://laravel-news.com/laravel-13'], $step->meta->citations->pluck('url')->all()); + $this->assertSame([$citation['citation']], $step->replayBlocks[1]['citations']); + $this->assertSame([$citation['citation']], $step->replayBlocks[2]['citations']); } } From a747a7e34b19bcc3b9539229e422e88def8d104c Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 02:02:28 +0000 Subject: [PATCH 15/17] Report rejected MCP notifications and keep the session The HTTP client transport reads no response for a notification. When the server rejected one with a JSON-RPC error, the transport queued the error where nothing reads it, so the rejection went unnoticed. A rejection without one threw, but also cleared the negotiated session while the client stayed connected, so the next request went out without its session ID. A rejected notification now throws a TransportException, with the server's message when the body carries a JSON-RPC error, and keeps the session. Requests, redirects, authorization challenges and a 404 for an expired session are handled as before. Validation: the MCP suite passes; formatting and full static analysis pass. --- .../src/Client/Transport/HttpTransport.php | 22 ++++++++++ .../Client/Transport/HttpTransportTest.php | 43 +++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/src/mcp/src/Client/Transport/HttpTransport.php b/src/mcp/src/Client/Transport/HttpTransport.php index 22f9b8e4f..69cf053ab 100644 --- a/src/mcp/src/Client/Transport/HttpTransport.php +++ b/src/mcp/src/Client/Transport/HttpTransport.php @@ -223,6 +223,8 @@ public function send(string $message, array $headers = []): void $exchange->ensureOpen(); if ($this->hasJsonRpcError($content)) { + $this->ensureResponseExpected($response, $message, $content); + $this->queue[] = $content; return; @@ -247,6 +249,8 @@ public function send(string $message, array $headers = []): void $content = trim($response->body()); $exchange->ensureOpen(); + $this->ensureResponseExpected($response, $message, $content); + if ($this->hasJsonRpcError($content)) { $this->queue[] = $content; @@ -355,6 +359,24 @@ protected function hasJsonRpcError(string $content): bool return is_array($body) && Arr::get($body, 'jsonrpc') === '2.0' && is_array(Arr::get($body, 'error')); } + /** + * Throw when the server rejects a notification, since no response is read for one. + * + * The rejection does not end the session, so the negotiation is kept. + */ + protected function ensureResponseExpected(ClientResponse $response, string $message, string $content): void + { + $outgoing = json_decode($message, true); + + if (! is_array($outgoing) || ! isset($outgoing['method']) || array_key_exists('id', $outgoing)) { + return; + } + + $error = Arr::get(json_decode($content, true), 'error.message'); + + throw new TransportException("The endpoint [{$this->url}] rejected the notification with HTTP status [{$response->status()}]" . (is_string($error) ? ": {$error}" : '.')); + } + /** * Build headers from the current connection and credentials. * diff --git a/tests/Mcp/Unit/Client/Transport/HttpTransportTest.php b/tests/Mcp/Unit/Client/Transport/HttpTransportTest.php index 6a2c059cf..92d9c0952 100644 --- a/tests/Mcp/Unit/Client/Transport/HttpTransportTest.php +++ b/tests/Mcp/Unit/Client/Transport/HttpTransportTest.php @@ -21,6 +21,7 @@ use Hypervel\Mcp\WebClient; use Hypervel\Support\Facades\Http; use Hypervel\Tests\Mcp\TestCase; +use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\Attributes\TestWith; use Psr\Http\Message\StreamInterface; use RuntimeException; @@ -541,6 +542,48 @@ public function testDrivesAFullHandshakeAndToolsListOverHttpViaClientWeb(): void Http::assertSent(fn ($request): bool => ($request['method'] ?? null) === 'tools/list' && $request->hasHeader('MCP-Protocol-Version', ProtocolVersion::V2025_11_25->value)); } + #[DataProvider('rejectedNotifications')] + public function testThrowsWhenTheServerRejectsANotificationAndKeepsTheSession(int $status, string $body, string $reason): void + { + Http::fakeSequence() + ->push(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'result' => []]), 200, ['Content-Type' => 'application/json', 'MCP-Session-Id' => 'session-kept']) + ->push($body, $status) + ->push(json_encode(['jsonrpc' => '2.0', 'id' => 2, 'result' => []]), 200, ['Content-Type' => 'application/json']); + + $transport = new HttpTransport('https://mcp.test/mcp'); + $transport->useProtocol(ProtocolVersion::V2025_11_25); + $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 1, 'method' => 'initialize', 'params' => []])); + $transport->receive(); + + try { + $transport->send(json_encode(['jsonrpc' => '2.0', 'method' => 'notifications/initialized'])); + + $this->fail('Expected a TransportException.'); + } catch (TransportException $exception) { + $this->assertSame("The endpoint [https://mcp.test/mcp] rejected the notification with HTTP status [{$status}]{$reason}", $exception->getMessage()); + } + + $transport->send(json_encode(['jsonrpc' => '2.0', 'id' => 2, 'method' => 'ping', 'params' => []])); + + $this->assertSame(['jsonrpc' => '2.0', 'id' => 2, 'result' => []], json_decode($transport->receive(), true)); + Http::assertSent(fn ($request): bool => ($request['method'] ?? null) === 'ping' && $request->hasHeader('MCP-Session-Id', 'session-kept')); + } + + /** + * Provide notification rejections with and without a JSON-RPC error body. + */ + public static function rejectedNotifications(): array + { + $error = json_encode(['jsonrpc' => '2.0', 'error' => ['code' => -32600, 'message' => 'The notification was not accepted.']]); + + return [ + 'json-rpc error' => [400, $error, ': The notification was not accepted.'], + 'json-rpc error without a challenge' => [403, $error, ': The notification was not accepted.'], + 'plain error' => [400, 'Bad Request', '.'], + 'server error' => [503, 'Service Unavailable', '.'], + ]; + } + public function testThrowsWhenTheServerNegotiatesAProtocolVersionTheClientDoesNotSupport(): void { legacyEndpoint() From 5562433451456825af74add5778d4440852c9b6d Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 02:02:28 +0000 Subject: [PATCH 16/17] Trim the legacy MCP protocol version header The legacy version check compared the MCP-Protocol-Version header untrimmed, so a supported version padded with spaces or tabs was rejected as unsupported. It now trims the value like the other MCP header checks. Validation: the changed test file passes; formatting and full static analysis pass. --- src/mcp/src/Server/Middleware/ValidateMcpHeaders.php | 4 ++++ .../Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/src/mcp/src/Server/Middleware/ValidateMcpHeaders.php b/src/mcp/src/Server/Middleware/ValidateMcpHeaders.php index 44b510ec6..f42774795 100644 --- a/src/mcp/src/Server/Middleware/ValidateMcpHeaders.php +++ b/src/mcp/src/Server/Middleware/ValidateMcpHeaders.php @@ -67,6 +67,10 @@ protected function unsupportedLegacyVersion(Request $request, mixed $id): ?Respo { $version = $request->header(RequestHeader::PROTOCOL_VERSION->value); + if (is_string($version)) { + $version = trim($version, " \t"); + } + if (! is_string($version) || $version === '' || in_array($version, ProtocolVersion::initializeSupported(), true)) { return null; } diff --git a/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php b/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php index 2481bc75b..10009fb39 100644 --- a/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php +++ b/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php @@ -354,6 +354,10 @@ public function testSkipsHeaderValidationForALegacyRequestWithoutProtocolMetadat $response->assertStatus(200); $this->assertNotEmpty($response->json('result.tools')); + + $this->postJson('test-mcp', ['jsonrpc' => '2.0', 'id' => 4, 'method' => 'tools/list', 'params' => []], [ + 'MCP-Protocol-Version' => " \t2025-06-18 ", + ])->assertStatus(200); } #[DataProvider('legacyVersions')] From 869a3e90630c2fcb7031debe578cfcdbf08531c3 Mon Sep 17 00:00:00 2001 From: Raj Siva-Rajah <5361908+binaryfire@users.noreply.github.com> Date: Fri, 20 Nov 2026 02:02:28 +0000 Subject: [PATCH 17/17] Only match configured MCP origins without a path A browser's Origin header never carries a path, so a configured entry such as https://client.example/app matched every app on that host. Configured entries must now be bare origins, optionally ending with a slash; app.url may still include its deployment path. The allowed origins setting is also read without a code-level default, since the shipped config defines it. Follow-up to laravel/mcp#394 at 4cf6b4ea. Validation: the changed test file passes; formatting and full static analysis pass. --- .../src/Server/Middleware/ValidateOrigin.php | 22 +++++++++++++++---- .../Server/Middleware/ValidateOriginTest.php | 12 ++++++++++ 2 files changed, 30 insertions(+), 4 deletions(-) diff --git a/src/mcp/src/Server/Middleware/ValidateOrigin.php b/src/mcp/src/Server/Middleware/ValidateOrigin.php index 34ae4f255..192f175e4 100644 --- a/src/mcp/src/Server/Middleware/ValidateOrigin.php +++ b/src/mcp/src/Server/Middleware/ValidateOrigin.php @@ -9,6 +9,7 @@ use Hypervel\Http\Request; use Hypervel\Mcp\Enums\ErrorCode; use Hypervel\Support\Arr; +use Hypervel\Support\Str; use Hypervel\Support\Uri; use InvalidArgumentException; use Symfony\Component\HttpFoundation\Response; @@ -52,7 +53,7 @@ protected function allowed(string $origin): bool $normalized = $this->normalize($origin); // Browsers send only a scheme, host and port, so a header with a path, query or fragment is malformed. - if ($normalized === null || substr_count($origin, '/') !== 2 || strpbrk($origin, '?#') !== false) { + if ($normalized === null || ! $this->isBareOrigin($origin)) { return false; } @@ -62,13 +63,26 @@ protected function allowed(string $origin): bool } // Unlike upstream, loopback origins are not trusted implicitly: a local web app on the - // browser user's machine is not necessarily one the server operator trusts. + // browser user's machine is not necessarily one the server operator trusts. A configured + // entry with a path never matches either, rather than trusting every app on its host. return array_any( - Arr::wrap($this->config->get('mcp.allowed_origins', [])), - fn (mixed $allowed): bool => $allowed === '*' || (is_string($allowed) && $this->normalize($allowed) === $normalized), + Arr::wrap($this->config->get('mcp.allowed_origins')), + fn (mixed $allowed): bool => $allowed === '*' || ( + is_string($allowed) + && $this->isBareOrigin(Str::chopEnd($allowed, '/')) + && $this->normalize($allowed) === $normalized + ), ); } + /** + * Determine whether the value has no path, query or fragment after its scheme and authority. + */ + protected function isBareOrigin(string $value): bool + { + return substr_count($value, '/') === 2 && strpbrk($value, '?#') === false; + } + /** * Reduce an HTTP URL to its normalized origin without making a network request. */ diff --git a/tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php b/tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php index d5ea57f5f..b2e8cdf8a 100644 --- a/tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php +++ b/tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php @@ -116,6 +116,18 @@ public function testAcceptsARequestFromAConfiguredOrigin(): void $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://evil.example'])->assertStatus(403); } + #[TestWith(['https://client.example/app'])] + #[TestWith(['https://client.example/?app=1'])] + #[TestWith(['https://client.example/#app'])] + public function testIgnoresAConfiguredEntryWithAPathQueryOrFragment(string $allowed): void + { + config(['mcp.allowed_origins' => [$allowed]]); + + $message = listToolsMessage(); + + $this->postJson('test-mcp', $message, [...mcpHeaders($message), 'Origin' => 'https://client.example'])->assertStatus(403); + } + public function testAcceptsAConfiguredOriginGivenAsAString(): void { config(['mcp.allowed_origins' => 'https://client.example']);