minor #186 [Agent] Add missing @throws tags (and description) to interfaces (OskarStark)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Agent] Add missing ``@throws`` tags (and description) to interfaces

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| Docs?         | yes
| Issues        | --
| License       | MIT

Following the pattern from #184, this commit adds missing `@throws` documentation to interface methods that can throw exceptions. This improves developer experience and helps static analysis tools understand the expected behavior.

cc `@VincentLanglet`

Commits
-------

7036dad [Agent] Add missing ``@throws`` tags (and description) to interfaces

Author: OskarStark

src/agent/src/Agent.php

@@ -56,6 +56,10 @@ public function __construct(
 
     /**
      * @param array<string, mixed> $options
+     *
+     * @throws MissingModelSupportException When the model doesn't support audio or image inputs present in the messages
+     * @throws InvalidArgumentException     When the platform returns a client error (4xx) indicating invalid request parameters
+     * @throws RuntimeException             When the platform returns a server error (5xx) or network failure occurs
      */
     public function call(MessageBagInterface $messages, array $options = []): ResultInterface
     {

src/agent/src/AgentInterface.php

@@ -23,7 +23,7 @@ interface AgentInterface
     /**
      * @param array<string, mixed> $options
      *
-     * @throws ExceptionInterface
+     * @throws ExceptionInterface When the agent encounters an error (e.g., unsupported model capabilities, invalid arguments, network failures, or processor errors)
      */
     public function call(MessageBagInterface $messages, array $options = []): ResultInterface;
 }

src/agent/src/ChatInterface.php

@@ -21,7 +21,7 @@ interface ChatInterface
     public function initiate(MessageBagInterface $messages): void;
 
     /**
-     * @throws ExceptionInterface
+     * @throws ExceptionInterface When the chat submission fails due to agent errors
      */
     public function submit(UserMessage $message): AssistantMessage;
 }

src/agent/src/StructuredOutput/AgentProcessor.php

@@ -45,6 +45,10 @@ public function __construct(
         }
     }
 
+    /**
+     * @throws MissingModelSupportException When structured output is requested but the model doesn't support it
+     * @throws InvalidArgumentException     When streaming is enabled with structured output (incompatible options)
+     */
     public function processInput(Input $input): void
     {
         $options = $input->getOptions();

src/agent/src/Toolbox/ToolCallArgumentResolver.php

@@ -38,6 +38,8 @@ public function __construct(
 
     /**
      * @return array<string, mixed>
+     *
+     * @throws ToolException When a mandatory tool parameter is missing from the tool call arguments
      */
     public function resolveArguments(Tool $metadata, ToolCall $toolCall): array
     {

src/mcp-sdk/src/Message/Factory.php

@@ -18,7 +18,7 @@ final class Factory
     /**
      * @return iterable<Notification|Request|InvalidInputMessageException>
      *
-     * @throws \JsonException
+     * @throws \JsonException When the input string is not valid JSON
      */
     public function create(string $input): iterable
     {

src/mcp-sdk/src/Server/JsonRpcHandler.php

@@ -54,8 +54,8 @@ public function __construct(
     /**
      * @return iterable<string|null>
      *
-     * @throws ExceptionInterface
-     * @throws \JsonException
+     * @throws ExceptionInterface When a handler throws an exception during message processing
+     * @throws \JsonException     When JSON encoding of the response fails
      */
     public function process(string $input): iterable
     {
@@ -103,7 +103,7 @@ public function process(string $input): iterable
     }
 
     /**
-     * @throws \JsonException
+     * @throws \JsonException When JSON encoding fails
      */
     private function encodeResponse(Response|Error|null $response): ?string
     {
@@ -123,7 +123,7 @@ private function encodeResponse(Response|Error|null $response): ?string
     }
 
     /**
-     * @throws ExceptionInterface
+     * @throws ExceptionInterface When a notification handler throws an exception
      */
     private function handleNotification(Notification $notification): null
     {
@@ -143,8 +143,8 @@ private function handleNotification(Notification $notification): null
     }
 
     /**
-     * @throws NotFoundExceptionInterface
-     * @throws ExceptionInterface
+     * @throws NotFoundExceptionInterface When no handler is found for the request method
+     * @throws ExceptionInterface         When a request handler throws an exception
      */
     private function handleRequest(Request $request): Response|Error
     {

src/mcp-sdk/src/Server/NotificationHandlerInterface.php

@@ -19,7 +19,7 @@ interface NotificationHandlerInterface
     public function supports(Notification $message): bool;
 
     /**
-     * @throws ExceptionInterface
+     * @throws ExceptionInterface When the handler encounters an error processing the notification
      */
     public function handle(Notification $notification): void;
 }

src/mcp-sdk/src/Server/RequestHandlerInterface.php

@@ -21,7 +21,7 @@ interface RequestHandlerInterface
     public function supports(Request $message): bool;
 
     /**
-     * @throws ExceptionInterface
+     * @throws ExceptionInterface When the handler encounters an error processing the request
      */
     public function createResponse(Request $message): Response|Error;
 }

src/platform/src/Bridge/Gemini/Gemini/ModelClient.php

@@ -39,7 +39,7 @@ public function supports(Model $model): bool
     }
 
     /**
-     * @throws TransportExceptionInterface
+     * @throws TransportExceptionInterface When the HTTP request fails due to network issues
      */
     public function request(Model $model, array|string $payload, array $options = []): RawHttpResult
     {