Merge feat_agent-exit-loop: TerminationException, DoneTool factory, Anthropic safety

Author: carmelosantana

src/Agent/AbstractAgent.php

@@ -10,9 +10,9 @@
 use CarmeloSantana\PHPAgents\Contract\ToolExecutionPolicyInterface;
 use CarmeloSantana\PHPAgents\Contract\ToolInterface;
 use CarmeloSantana\PHPAgents\Contract\ToolkitInterface;
-use CarmeloSantana\PHPAgents\Enum\FinishReason;
 use CarmeloSantana\PHPAgents\Enum\ModelCapability;
 use CarmeloSantana\PHPAgents\Exception\ProviderException;
+use CarmeloSantana\PHPAgents\Exception\TerminationException;
 use CarmeloSantana\PHPAgents\Exception\ToolNotFoundException;
 use CarmeloSantana\PHPAgents\Message\AssistantMessage;
 use CarmeloSantana\PHPAgents\Message\Conversation;
@@ -95,7 +95,6 @@ public function run(MessageInterface $input, ?Conversation $history = null): Out
 
         $allToolResults = [];
         $totalUsage = new Usage();
-        $lastContent = '';
 
         for ($i = 0; $i < $this->maxIterations(); $i++) {
             $this->notify('agent.iteration', $i + 1);
@@ -190,6 +189,20 @@ public function run(MessageInterface $input, ?Conversation $history = null): Out
                         $tool = $this->findTool($toolCall->name, $allTools);
                         $result = $tool->execute($toolCall->arguments);
                         $result = $result->withCallId($toolCall->id);
+                    } catch (TerminationException $e) {
+                        // Tool requested immediate loop termination (e.g. restart)
+                        $result = ToolResult::success($e->getMessage())->withCallId($toolCall->id);
+                        $allToolResults[] = $result;
+                        $conversation->add(new ToolResultMessage($result));
+                        $this->notify('agent.tool_result', $result);
+
+                        return new Output(
+                            content: $e->getMessage(),
+                            toolResults: $allToolResults,
+                            usage: $totalUsage,
+                            iterations: $i + 1,
+                            conversation: $conversation,
+                        );
                     } catch (\Throwable $e) {
                         $this->notify('agent.tool_error', $e->getMessage());
                         $result = ToolResult::error($e->getMessage())->withCallId($toolCall->id);
@@ -203,18 +216,24 @@ public function run(MessageInterface $input, ?Conversation $history = null): Out
                 continue;
             }
 
-            if ($response->content === $lastContent && $response->content !== '') {
-                $conversation->add(new AssistantMessage(
-                    'Warning: You are repeating yourself. Please make progress or call the done tool.',
-                ));
+            // Text-only response (no tool calls) — this IS the response.
+            // The done tool is only needed after tool use to present results.
+            if ($response->content !== '') {
+                $conversation->add(new AssistantMessage($response->content));
+                $this->notify('agent.done', ['response' => $response->content]);
+
+                return new Output(
+                    content: $response->content,
+                    toolResults: $allToolResults,
+                    usage: $totalUsage,
+                    model: $response->model,
+                    iterations: $i + 1,
+                    conversation: $conversation,
+                );
             }
 
-            $lastContent = $response->content;
+            // Empty response with no tool calls — let it retry
             $conversation->add(new AssistantMessage($response->content));
-
-            if ($response->finishReason === FinishReason::Stop && $response->content !== '') {
-                continue;
-            }
         }
 
         $this->notify('agent.error', 'Max iterations reached');
@@ -239,7 +258,7 @@ private function allTools(): array
             $tools = [...$tools, ...$toolkit->tools()];
         }
 
-        $tools[] = new DoneTool();
+        $tools[] = DoneTool::create();
 
         return $tools;
     }

src/Exception/TerminationException.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CarmeloSantana\PHPAgents\Exception;
+
+/**
+ * Thrown by a tool to signal that the agent loop should terminate immediately.
+ *
+ * When a tool throws this exception, AbstractAgent catches it, records the
+ * message as a successful tool result, and returns an Output without
+ * continuing to the next iteration. This allows tools like "restart" or
+ * "shutdown" to cleanly exit the agent loop while still persisting the
+ * conversation state.
+ *
+ * The exception message is used as the tool result content and the final
+ * Output content.
+ */
+final class TerminationException extends \RuntimeException {}

src/Message/Conversation.php

@@ -230,6 +230,78 @@ public function repairToolPairing(): self
         return $result;
     }
 
+    /**
+     * Merge consecutive messages with the same role into single messages.
+     *
+     * After pruning operations (dropOldestTurns, repairToolPairing), the
+     * conversation may contain consecutive same-role messages. Some providers
+     * (notably Anthropic) reject these. This method merges them by concatenating
+     * text content with newlines.
+     *
+     * Tool messages are never merged — each tool result must correspond to
+     * exactly one tool_use_id. Assistant messages with tool calls are also
+     * kept separate to preserve their tool_call structure.
+     *
+     * Returns a new Conversation.
+     */
+    public function mergeConsecutiveRoles(): self
+    {
+        $result = new self();
+        $lastMsg = null;
+
+        foreach ($this->messages as $msg) {
+            // Never merge tool result messages — they have unique tool_call_ids
+            if ($msg->role() === Role::Tool) {
+                $result->add($msg);
+                $lastMsg = $msg;
+                continue;
+            }
+
+            // Never merge assistant messages with tool calls — structure matters
+            if ($msg->role() === Role::Assistant && !empty($msg->toolCalls())) {
+                $result->add($msg);
+                $lastMsg = $msg;
+                continue;
+            }
+
+            // Merge consecutive same-role text-only messages
+            if (
+                $lastMsg !== null
+                && $lastMsg->role() === $msg->role()
+                && empty($lastMsg->toolCalls())
+            ) {
+                // Remove the last message and replace with merged content
+                $messages = $result->messages();
+                $lastContent = is_string($lastMsg->content()) ? $lastMsg->content() : (json_encode($lastMsg->content()) ?: '');
+                $newContent = is_string($msg->content()) ? $msg->content() : (json_encode($msg->content()) ?: '');
+                $mergedContent = $lastContent . "\n\n" . $newContent;
+
+                // Rebuild the conversation without the last message
+                $result = new self();
+                for ($i = 0; $i < count($messages) - 1; $i++) {
+                    $result->add($messages[$i]);
+                }
+
+                // Add merged message based on role.
+                // At this point $msg is User, Assistant (text-only), or System
+                // since Tool and Assistant-with-tool-calls are handled above.
+                $merged = match ($msg->role()) {
+                    Role::User => new UserMessage($mergedContent),
+                    Role::Assistant => new AssistantMessage($mergedContent),
+                    default => new SystemMessage($mergedContent),
+                };
+                $result->add($merged);
+                $lastMsg = $merged;
+                continue;
+            }
+
+            $result->add($msg);
+            $lastMsg = $msg;
+        }
+
+        return $result;
+    }
+
     /**
      * Progressively prune the conversation to fit within a token budget.
      *
@@ -269,6 +341,9 @@ public function fitWithinBudget(int $maxTokens, int $safetyMarginPercent = 20):
         // Step 4: Repair any orphaned tool results from dropped turns
         $result = $result->repairToolPairing();
 
+        // Step 5: Merge consecutive same-role messages that may result from pruning
+        $result = $result->mergeConsecutiveRoles();
+
         return $result;
     }
 

src/Provider/AnthropicProvider.php

@@ -163,12 +163,15 @@ private function extractSystemAndMessages(array $messages): array
 
         // Merge consecutive same-role messages (required by Anthropic).
         // Consecutive tool_result user messages must be combined into a single
-        // user message with multiple content blocks.
+        // user message with multiple content blocks. Handle mixed content types
+        // (string + array) by normalizing strings to text content blocks.
         $merged = [];
         foreach ($formatted as $msg) {
             $last = end($merged);
-            if ($last !== false && $last['role'] === $msg['role'] && is_array($last['content']) && is_array($msg['content'])) {
-                $merged[array_key_last($merged)]['content'] = array_merge($last['content'], $msg['content']);
+            if ($last !== false && $last['role'] === $msg['role']) {
+                $lastContent = $this->normalizeContent($last['content']);
+                $msgContent = $this->normalizeContent($msg['content']);
+                $merged[array_key_last($merged)]['content'] = array_merge($lastContent, $msgContent);
             } else {
                 $merged[] = $msg;
             }
@@ -302,4 +305,22 @@ private function parseStreamEvent(array $event): Response
             model: $this->model,
         );
     }
+
+    /**
+     * Normalize message content to an array of content blocks.
+     *
+     * Anthropic requires content blocks when merging consecutive same-role
+     * messages. Plain string content is converted to a text block.
+     *
+     * @param string|array<array<string, mixed>> $content
+     * @return array<array<string, mixed>>
+     */
+    private function normalizeContent(string|array $content): array
+    {
+        if (is_string($content)) {
+            return $content !== '' ? [['type' => 'text', 'text' => $content]] : [];
+        }
+
+        return $content;
+    }
 }

src/Tool/DoneTool.php

@@ -5,62 +5,39 @@
 namespace CarmeloSantana\PHPAgents\Tool;
 
 use CarmeloSantana\PHPAgents\Contract\ToolInterface;
-use CarmeloSantana\PHPAgents\Enum\ToolResultStatus;
 use CarmeloSantana\PHPAgents\Tool\Parameter\StringParameter;
 
-final class DoneTool implements ToolInterface
+/**
+ * Factory for the built-in "done" tool that signals agent completion.
+ *
+ * Returns a standard Tool instance using the same Parameter-driven schema
+ * generation as all other tools — no hand-written toFunctionSchema().
+ */
+final class DoneTool
 {
     public const NAME = 'done';
 
-    public function name(): string
+    /**
+     * Create the done tool instance.
+     *
+     * Uses the generic Tool class with a StringParameter, ensuring
+     * consistent schema generation across all tools.
+     */
+    public static function create(): ToolInterface
     {
-        return self::NAME;
-    }
-
-    public function description(): string
-    {
-        return 'Call this tool when you have completed the task. '
-            . 'Pass your final response in the "response" parameter. '
-            . 'You MUST call this tool to finish — do not end without it.';
-    }
-
-    public function parameters(): array
-    {
-        return [
-            new StringParameter(
-                name: 'response',
-                description: 'Your final response to the user\'s request.',
-                required: true,
-            ),
-        ];
-    }
-
-    public function execute(array $input): ToolResult
-    {
-        return new ToolResult(
-            ToolResultStatus::Success,
-            $input['response'] ?? '',
-        );
-    }
-
-    public function toFunctionSchema(): array
-    {
-        return [
-            'type' => 'function',
-            'function' => [
-                'name' => $this->name(),
-                'description' => $this->description(),
-                'parameters' => [
-                    'type' => 'object',
-                    'properties' => [
-                        'response' => [
-                            'type' => 'string',
-                            'description' => 'Your final response to the user\'s request.',
-                        ],
-                    ],
-                    'required' => ['response'],
-                ],
+        return new Tool(
+            name: self::NAME,
+            description: 'Present your final response to the user after using tools. '
+                . 'Pass your completed answer in the "response" parameter. '
+                . 'Only needed after tool use — for simple conversation, respond with text directly.',
+            parameters: [
+                new StringParameter(
+                    name: 'response',
+                    description: 'Your final response to the user\'s request.',
+                    required: true,
+                ),
             ],
-        ];
+            callback: fn(array $input): ToolResult => ToolResult::success($input['response'] ?? ''),
+        );
     }
 }