diff --git a/dogfood/mcp/README.md b/dogfood/mcp/README.md index 1de739a277..cbfaaa486b 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 99c84b2b40..32794304f0 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 2ab5a546b3..acff96c03d 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 0000000000..82827e1e78 --- /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 0000000000..181b5de69a --- /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 0000000000..44a8548e18 --- /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 d0a3d0e2fe..8fb433261c 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 05e1c82415..3c6cbb319d 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}" diff --git a/src/ai/src/Exceptions/InvalidApiKeyException.php b/src/ai/src/Exceptions/InvalidApiKeyException.php new file mode 100644 index 0000000000..266e570865 --- /dev/null +++ b/src/ai/src/Exceptions/InvalidApiKeyException.php @@ -0,0 +1,27 @@ +provider}]. " . parent::prepareMessage($response); + } +} diff --git a/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php b/src/ai/src/Gateway/Anthropic/Concerns/HandlesTextStreaming.php index 4b7f7a7711..35c11045d1 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,15 @@ 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); + // 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; } } elseif ($deltaType === 'input_json_delta') { $partial = (string) ($data['delta']['partial_json'] ?? ''); diff --git a/src/ai/src/Gateway/Anthropic/Concerns/MapsAttachments.php b/src/ai/src/Gateway/Anthropic/Concerns/MapsAttachments.php index 661441b5ba..e73e580561 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/src/ai/src/Gateway/Anthropic/Concerns/MapsTools.php b/src/ai/src/Gateway/Anthropic/Concerns/MapsTools.php index 4d54acb56d..f03b2c1bed 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 245244d154..d28dce7d9f 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 1595018b44..a4afafceca 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/Concerns/DecodesStructuredOutput.php b/src/ai/src/Gateway/Concerns/DecodesStructuredOutput.php index b1a6930909..f5a89b8730 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,37 @@ 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); + } + + $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; + } + } + + return null; + } + /** * Escape unescaped double quotes in object keys, where only a quote followed by a colon closes the key. */ diff --git a/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php b/src/ai/src/Gateway/Concerns/HandlesFailoverErrors.php index 1a32f36f9a..d781675479 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, @@ -65,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); @@ -109,6 +119,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. */ @@ -126,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 new file mode 100644 index 0000000000..80e95fc536 --- /dev/null +++ b/src/ai/src/Gateway/Gemini/Concerns/HandlesGeminiErrors.php @@ -0,0 +1,40 @@ +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', flags: 0) ?? $exception->response->json('error', flags: 0); + + $message = is_string($error['message'] ?? null) ? $error['message'] : ''; + + return match ($status) { + 400 => collect($error['details'] ?? [])->contains('reason', 'API_KEY_INVALID'), + 403 => Str::contains($message, ['unregistered callers', 'reported as leaked']), + }; + } +} diff --git a/src/ai/src/Gateway/Gemini/GeminiClassificationGateway.php b/src/ai/src/Gateway/Gemini/GeminiClassificationGateway.php new file mode 100644 index 0000000000..0dfa8cd96d --- /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/Gemini/GeminiFileGateway.php b/src/ai/src/Gateway/Gemini/GeminiFileGateway.php index 57dc19c95b..5aaef9d9ac 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 23dbc16cb3..57bce9b17f 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 e48f3f09fb..b793429419 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/Groq/GroqGateway.php b/src/ai/src/Gateway/Groq/GroqGateway.php index 64e707d3f5..b794efeeb0 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/Ollama/Concerns/HandlesTextStreaming.php b/src/ai/src/Gateway/Ollama/Concerns/HandlesTextStreaming.php index 63541efdcc..bd714822a8 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 3646c3cbc9..49f350f119 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/src/ai/src/Gateway/OpenAi/OpenAiClassificationGateway.php b/src/ai/src/Gateway/OpenAi/OpenAiClassificationGateway.php index 72ab382eb4..b67b47112f 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 a836dd15ae..f90ad9dd77 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/OpenAiCompatible/Concerns/HandlesTextStreaming.php b/src/ai/src/Gateway/OpenAiCompatible/Concerns/HandlesTextStreaming.php index d0a406b538..3754b1e911 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 f7ff5fa568..1b8c040dae 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/src/ai/src/Gateway/OpenRouter/OpenRouterGateway.php b/src/ai/src/Gateway/OpenRouter/OpenRouterGateway.php index 73ee6da82d..37a0a076e2 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/Gateway/Xai/Concerns/HandlesXaiErrors.php b/src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php new file mode 100644 index 0000000000..705f7a05d7 --- /dev/null +++ b/src/ai/src/Gateway/Xai/Concerns/HandlesXaiErrors.php @@ -0,0 +1,25 @@ +response->status()) { + 401 => true, + 400 => is_string($error = $exception->response->json('error', flags: 0)) && 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 881c7b8444..2bdc73afca 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 ed3a13d5bd..e3f66a269a 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/src/ai/src/Providers/GeminiProvider.php b/src/ai/src/Providers/GeminiProvider.php index 773b986bd4..bf8ef8c52e 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 e12179e75d..1ba09f3e55 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/Storage/DatabaseConversationStore.php b/src/ai/src/Storage/DatabaseConversationStore.php index 2a5b279496..9a91313895 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/src/ai/src/Streaming/Events/Error.php b/src/ai/src/Streaming/Events/Error.php index cbbb9d1d79..b3e3d20c79 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 e122b9f1fa..43d34bd5ba 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 8a1577a948..da9f9a0081 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/src/docs/mcp.md b/src/docs/mcp.md index 6f1d1108a7..de621e9b0f 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 6c7562194e..7704e08739 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 3a55af00f3..8fa4b77bd5 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 1de3eed533..93331c4dd2 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 dc16b62dcf..69cf053ab8 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,39 @@ 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->ensureResponseExpected($response, $message, $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), ); } @@ -229,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; @@ -337,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. * @@ -376,25 +416,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.php b/src/mcp/src/Server.php index 17fde4a626..c09cd63f0a 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 428390b619..682454cc7c 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 99cdb016ce..37eab84a82 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 3e63698550..f427747959 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); } /** @@ -68,11 +67,15 @@ 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; } - if (ProtocolVersion::tryFrom($version)?->handshake() === ProtocolHandshake::Discovery) { + if (in_array($version, ProtocolVersion::serverSupported(), true)) { return response()->json([ 'jsonrpc' => '2.0', 'id' => $id, @@ -80,7 +83,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 +94,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 +107,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 +123,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/Server/Middleware/ValidateOrigin.php b/src/mcp/src/Server/Middleware/ValidateOrigin.php index 045067ddd5..192f175e47 100644 --- a/src/mcp/src/Server/Middleware/ValidateOrigin.php +++ b/src/mcp/src/Server/Middleware/ValidateOrigin.php @@ -7,10 +7,12 @@ use Closure; use Hypervel\Contracts\Config\Repository; 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; -use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException; class ValidateOrigin { @@ -23,40 +25,71 @@ 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); + } + + /** + * Determine whether the request origin is allowed. + */ + protected function allowed(string $origin): bool + { + $normalized = $this->normalize($origin); - 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); - } + // Browsers send only a scheme, host and port, so a header with a path, query or fragment is malformed. + if ($normalized === null || ! $this->isBareOrigin($origin)) { + return false; + } - foreach ($this->config->array('mcp.allowed_origins') as $allowedOrigin) { - if ($origin === $this->origin($allowedOrigin)) { - return $next($request); - } - } + // Trust configured origins, never the incoming request's Host header. + if ($normalized === $this->normalize($this->config->string('app.url'))) { + return true; } - throw new AccessDeniedHttpException('Origin is not allowed.'); + // 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. 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->isBareOrigin(Str::chopEnd($allowed, '/')) + && $this->normalize($allowed) === $normalized + ), + ); } /** - * Normalize an HTTP origin without making a network request. + * Determine whether the value has no path, query or fragment after its scheme and authority. */ - protected function origin(string $value, bool $allowPath = false): ?string + 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. + */ + protected function normalize(string $origin): ?string { try { - $uri = Uri::of($value); + $uri = Uri::of($origin); } catch (InvalidArgumentException) { return null; } @@ -66,8 +99,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 2d52ce9fab..41584bb7da 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/src/mcp/src/Transport/JsonRpcRequest.php b/src/mcp/src/Transport/JsonRpcRequest.php index cc10d84665..51c56b20a3 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/Ai/Feature/BroadcastAgentTest.php b/tests/Ai/Feature/BroadcastAgentTest.php index 958e94c04f..efb3c5c52e 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/MessageMappingTest.php b/tests/Ai/Feature/Providers/Anthropic/MessageMappingTest.php index a5caed9716..59ecd077fe 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([ diff --git a/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php b/tests/Ai/Feature/Providers/Anthropic/StreamingTest.php index 1af2ca6ced..7a82293603 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,52 @@ 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'], + ), + ]); + + $events = $this->collectStreamEvents(); + + $citations = array_map( + fn (CitationEvent $e): array => [$e->citation->url, $e->citation->title], + 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']); + } } diff --git a/tests/Ai/Feature/Providers/Anthropic/ToolMappingTest.php b/tests/Ai/Feature/Providers/Anthropic/ToolMappingTest.php index 0e62abfa0b..e6b686e409 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 0000000000..4a70a1f4ee --- /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/Gemini/ErrorHandlingTest.php b/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php index bdd08883bf..c91e41ec83 100644 --- a/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php +++ b/tests/Ai/Feature/Providers/Gemini/ErrorHandlingTest.php @@ -6,12 +6,14 @@ 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; 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; @@ -193,4 +195,82 @@ 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', + ]]]], + ]; + } + + #[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([ + '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 a0fbe2e2fa..cc78c58b77 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 ce02c0e950..00ef6dcbf3 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/Groq/TranscriptionTest.php b/tests/Ai/Feature/Providers/Groq/TranscriptionTest.php index 06f158fac9..a0696800aa 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/Ollama/StreamingTest.php b/tests/Ai/Feature/Providers/Ollama/StreamingTest.php index 94409672ad..8d59070eda 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/Feature/Providers/OpenAi/AudioTest.php b/tests/Ai/Feature/Providers/OpenAi/AudioTest.php index d071911d65..4fa95743c5 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 3fccb2938d..dbffc7b516 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 67c50ebaed..ba9ddd7122 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/OpenAiCompatible/OpenAiCompatibleTest.php b/tests/Ai/Feature/Providers/OpenAiCompatible/OpenAiCompatibleTest.php index f973f848f0..641ed5b711 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/Ai/Feature/Providers/OpenRouter/TranscriptionTest.php b/tests/Ai/Feature/Providers/OpenRouter/TranscriptionTest.php index 1d8ed247c9..ba48b627ea 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 06b97d6d51..c48d4d61e2 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/Ai/Feature/Providers/Xai/ErrorHandlingTest.php b/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php index f2e3d5b0b8..55b7ccb7c4 100644 --- a/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php +++ b/tests/Ai/Feature/Providers/Xai/ErrorHandlingTest.php @@ -5,13 +5,16 @@ 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; 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; +use PHPUnit\Framework\Attributes\DataProvider; class ErrorHandlingTest extends TestCase { @@ -104,4 +107,48 @@ 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.', + ]], + ]; + } + + #[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/Feature/Providers/Xai/ImageGenerationTest.php b/tests/Ai/Feature/Providers/Xai/ImageGenerationTest.php index 19c9bef484..1711d7f629 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/Feature/Storage/DatabaseConversationStoreTest.php b/tests/Ai/Feature/Storage/DatabaseConversationStoreTest.php index 97703a3f62..787b6be3dc 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)]; diff --git a/tests/Ai/Fixtures/OllamaHelpers.php b/tests/Ai/Fixtures/OllamaHelpers.php index 2e9f099efc..f3120e3f63 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), ]; } } diff --git a/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php b/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php index f61ac4d735..8ad5c67a11 100644 --- a/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php +++ b/tests/Ai/Unit/Gateway/Concerns/DecodesStructuredOutputTest.php @@ -100,4 +100,43 @@ 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```"}``')); + } + + 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"}```')); + } } diff --git a/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php b/tests/Ai/Unit/Gateway/Concerns/HandlesFailoverErrorsTest.php index 6e5fa7f503..22210ebc8f 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 { @@ -117,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(); diff --git a/tests/Integration/Ai/AgentTest.php b/tests/Integration/Ai/AgentTest.php index b4b1e25e4f..7711143e54 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 { diff --git a/tests/Integration/Ai/Fixtures/Providers.php b/tests/Integration/Ai/Fixtures/Providers.php index 6701806878..7c84085c07 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'], diff --git a/tests/Mcp/Feature/Client/HandshakeNegotiationTest.php b/tests/Mcp/Feature/Client/HandshakeNegotiationTest.php index 4551bbebef..32c3f6b0b1 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/Client/OAuthCallbackRouteTest.php b/tests/Mcp/Feature/Client/OAuthCallbackRouteTest.php index 668479947f..69c8a01b38 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); diff --git a/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php b/tests/Mcp/Feature/Server/Middleware/ValidateMcpHeadersTest.php index afbe341c2e..10009fb399 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(); @@ -262,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')] @@ -330,6 +426,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 +477,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/Feature/Server/Middleware/ValidateOriginTest.php b/tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php new file mode 100644 index 0000000000..b2e8cdf8ab --- /dev/null +++ b/tests/Mcp/Feature/Server/Middleware/ValidateOriginTest.php @@ -0,0 +1,182 @@ +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); + } + + #[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']); + + $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 bb7211101e..edb3066d8a 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 9af5f4af3f..92d9c09528 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; @@ -20,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; @@ -262,62 +264,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 +357,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( @@ -547,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() diff --git a/tests/Mcp/Unit/Methods/CallToolTest.php b/tests/Mcp/Unit/Methods/CallToolTest.php index 3786f28f0b..10f19f4c65 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 1469e2d06c..5ef8118197 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 dfa62b0186..3d5c139d8f 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 04a6b7797a..06dbc79b4a 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 ab29a23965..8956e2fb13 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 9ca773425e..67d8b72640 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 68c7cd7f18..b80a23f029 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 af7dfc3e57..05eaf293be 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/Server/Middleware/ValidateOriginTest.php b/tests/Mcp/Unit/Server/Middleware/ValidateOriginTest.php deleted file mode 100644 index 57fb7072bd..0000000000 --- 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']], - ])); - } -} diff --git a/tests/Mcp/Unit/ServerTest.php b/tests/Mcp/Unit/ServerTest.php index 787116ec2a..44bac3561a 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 69ce5dd9a9..c1190e8cfd 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 35ef0221f5..591a074266 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(); } }