Release version 1.21.0

Author: ddebowczyk

.beads/issues.jsonl

@@ -140,7 +140,8 @@
             "pestphp/pest-plugin": true,
             "php-http/discovery": true
         },
-        "sort-packages": true
+        "sort-packages": true,
+        "process-timeout": 600
     },
     "require": {
         "php": "^8.3|^8.4|^8.5",

composer.json

@@ -10,7 +10,7 @@ class User {
 
 $user = (new StructuredOutput)
     //->wiretap(fn($e) => $e->print())
-    ->withDsn('preset=xai,model=grok-2')
+    ->withDsn('preset=xai,model=grok-3')
     ->withMessages("Our user Jason is 25 years old.")
     ->withresponseClass(User::class)
     ->get();

docs-build/cookbook/instructor/advanced/dsn.mdx

@@ -5,7 +5,7 @@ use Cognesy\Polyglot\Inference\Inference;
 use Cognesy\Utils\Str;
 
 $answer = (new Inference)
-    ->withDsn('preset=xai,model=grok-2')
+    ->withDsn('preset=xai,model=grok-3')
     ->with(
         messages: [['role' => 'user', 'content' => 'What is the capital of France']],
         options: ['max_tokens' => 64]

docs-build/cookbook/polyglot/llm_advanced/dsn.mdx

@@ -1,8 +1,9 @@
-<?php
+<?php declare(strict_types=1);
 require 'examples/boot.php';
 
 use Cognesy\Addons\Agent\AgentBuilder;
 use Cognesy\Addons\Agent\Core\Data\AgentState;
+use Cognesy\Addons\Agent\Core\Enums\AgentStatus;
 use Cognesy\Messages\Messages;
 
 // Build a basic agent
@@ -24,4 +25,21 @@ $response = $finalState->currentStep()?->outputMessages()->toString() ?? 'No res
 echo "Answer: {$response}\n";
 echo "Steps: {$finalState->stepCount()}\n";
 echo "Status: {$finalState->status()->value}\n";
+
+if ($finalState->status() === AgentStatus::Failed) {
+    $debug = $finalState->debug();
+    $stepType = $finalState->currentStep()?->stepType()?->value;
+    if ($stepType !== null) {
+        echo "Step type: {$stepType}\n";
+    }
+    if (($debug['stopReason'] ?? '') !== '') {
+        echo "Stop reason: {$debug['stopReason']}\n";
+    }
+    if (($debug['resolvedBy'] ?? '') !== '') {
+        echo "Resolved by: {$debug['resolvedBy']}\n";
+    }
+    if (($debug['errors'] ?? '') !== '') {
+        echo "Errors: {$debug['errors']}\n";
+    }
+}
 ?>

docs-build/cookbook/polyglot/llm_extras/agent_basic.mdx

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 require 'examples/boot.php';
 
 use Cognesy\AgentCtrl\AgentCtrl;
@@ -23,7 +23,12 @@ $agent->onEvent(AgentExecutionStarted::class, function(AgentExecutionStarted $ev
 });
 
 $agent->onEvent(AgentTextReceived::class, function(AgentTextReceived $event): void {
-    $preview = strlen($event->text) > 50 ? substr($event->text, 0, 50) . '...' : $event->text;
+    $preview = $event->text;
+    if (strlen($event->text) > 50) {
+        $preview = substr($event->text, 0, 50) . '...';
+        // replace new lines with spaces to keep output clean
+        $preview = str_replace("\n", ' ', $preview);
+    }
     echo "-> Text: \"{$preview}\"\n";
 });
 
@@ -32,7 +37,11 @@ $agent->onEvent(AgentToolUsed::class, function(AgentToolUsed $event): void {
 });
 
 $agent->onEvent(AgentExecutionCompleted::class, function(AgentExecutionCompleted $event): void {
-    echo "-> Completed: {$event->toolCallCount} tool calls, cost: $" . number_format($event->cost, 4) . "\n";
+    $costLabel = 'n/a';
+    if ($event->cost !== null) {
+        $costLabel = '$' . number_format($event->cost, 4);
+    }
+    echo "-> Completed: {$event->toolCallCount} tool calls, cost: {$costLabel}\n";
 });
 
 // Execute with streaming to see events in real-time

docs-build/cookbook/polyglot/llm_extras/agent_ctrl_events.mdx

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 require 'examples/boot.php';
 
 use Cognesy\Addons\Agent\AgentBuilder;
@@ -183,6 +183,14 @@ while ($agent->hasNextStep($state)) {
     $step = $state->currentStep();
     echo "Step {$state->stepCount()}: [{$step->stepType()->value}]\n";
 
+    if ($step->hasErrors()) {
+        $errors = $step->errorsAsString();
+        if ($errors !== '') {
+            $errors = str_replace("\n", "\n  !! ", $errors);
+            echo "  !! {$errors}\n";
+        }
+    }
+
     if ($step->hasToolCalls()) {
         foreach ($step->toolCalls()->all() as $toolCall) {
             $args = $toolCall->args();
@@ -197,6 +205,15 @@ while ($agent->hasNextStep($state)) {
 
     // Show tool execution results
     foreach ($step->toolExecutions()->all() as $execution) {
+        if ($execution->hasError()) {
+            $errorMessage = $execution->errorMessage();
+            $label = 'Unknown tool execution error';
+            if ($errorMessage !== '') {
+                $label = $errorMessage;
+            }
+            echo "    ← Error: {$label}\n";
+            continue;
+        }
         $result = $execution->value();
         $resultStr = match (true) {
             is_string($result) => $result,

docs-build/cookbook/polyglot/llm_extras/agent_structured_output.mdx

@@ -1,8 +1,9 @@
-<?php
+<?php declare(strict_types=1);
 require 'examples/boot.php';
 
 use Cognesy\Addons\Agent\AgentBuilder;
 use Cognesy\Addons\Agent\Capabilities\File\UseFileTools;
+use Cognesy\Addons\Agent\Capabilities\Subagent\SpawnSubagentTool;
 use Cognesy\Addons\Agent\Capabilities\Subagent\UseSubagents;
 use Cognesy\Addons\Agent\Core\Data\AgentState;
 use Cognesy\Addons\Agent\Registry\AgentRegistry;
@@ -31,6 +32,8 @@ $registry->register(new AgentSpec(
     tools: ['read_file'],
 ));
 
+SpawnSubagentTool::clearSubagentStates();
+
 // Build main orchestration agent
 $agent = AgentBuilder::base()
     ->withCapability(new UseFileTools($workDir))
@@ -40,9 +43,9 @@ $agent = AgentBuilder::base()
 // Task requiring multiple isolated reviews
 $task = <<<TASK
 Review these three files and provide a summary:
-1. src/Agent/AgentBuilder.php
-2. src/Agent/AgentState.php
-3. src/Agent/Agent.php
+1. packages/addons/src/Agent/AgentBuilder.php
+2. packages/addons/src/Agent/Core/Data/AgentState.php
+3. packages/addons/src/Agent/Agent.php
 
 For each file, spawn a reviewer subagent. Then summarize the findings.
 TASK;
@@ -81,6 +84,6 @@ echo $summary . "\n\n";
 
 echo "Stats:\n";
 echo "  Steps: {$state->stepCount()}\n";
-echo "  Subagents spawned: " . ($state->metadata()->get('subagent_count') ?? 0) . "\n";
+echo "  Subagents spawned: " . count(SpawnSubagentTool::getSubagentStates()) . "\n";
 echo "  Status: {$state->status()->value}\n";
 ?>

docs-build/cookbook/polyglot/llm_extras/agent_subagents.mdx

@@ -1,10 +1,12 @@
-<?php
+<?php declare(strict_types=1);
 
 require 'examples/boot.php';
 
 use Cognesy\Addons\Chat\ChatFactory;
 use Cognesy\Addons\Chat\Collections\Participants;
 use Cognesy\Addons\Chat\Data\ChatState;
+use Cognesy\Addons\Chat\Events\MessageBufferSummarized;
+use Cognesy\Addons\Chat\Events\MessagesMovedToBuffer;
 use Cognesy\Addons\Chat\Participants\LLMParticipant;
 use Cognesy\Addons\Chat\Participants\ScriptedParticipant;
 use Cognesy\Addons\Chat\Utils\SummarizeMessages;
@@ -17,10 +19,49 @@ use Cognesy\Addons\StepByStep\StateProcessing\Processors\MoveMessagesToBuffer;
 use Cognesy\Addons\StepByStep\StateProcessing\Processors\SummarizeBuffer;
 use Cognesy\Addons\StepByStep\StateProcessing\StateProcessors;
 use Cognesy\Events\Dispatchers\EventDispatcher;
+use Cognesy\Messages\Message;
 use Cognesy\Messages\Messages;
 use Cognesy\Polyglot\Inference\LLMProvider;
+use Cognesy\Utils\Tokenizer;
 
 $events = new EventDispatcher();
+$bufferTokenLimit = 600;
+$summaryTriggerLimit = 200;
+$summaryMaxTokens = 512;
+$bufferTokens = 0;
+
+$events->addListener(MessagesMovedToBuffer::class, function(MessagesMovedToBuffer $event) use (
+    $bufferTokenLimit,
+    $summaryTriggerLimit,
+    &$bufferTokens
+): void {
+    $overflow = Messages::fromArray($event->data['overflow'] ?? []);
+    $keep = Messages::fromArray($event->data['keep'] ?? []);
+    $overflowTokens = Tokenizer::tokenCount($overflow->toString());
+    if ($overflowTokens === 0) {
+        return;
+    }
+    $keepTokens = Tokenizer::tokenCount($keep->toString());
+    $totalTokens = $overflowTokens + $keepTokens;
+    $bufferTokens += $overflowTokens;
+
+    echo "\n>>> Buffer overflow detected (messages {$totalTokens} tokens > {$bufferTokenLimit}). ";
+    echo "Moved {$overflowTokens} tokens to buffer ({$bufferTokens}/{$summaryTriggerLimit}).\n";
+});
+
+$events->addListener(MessageBufferSummarized::class, function(MessageBufferSummarized $event) use (
+    $summaryTriggerLimit,
+    &$bufferTokens
+): void {
+    $buffer = Messages::fromArray($event->data['buffer'] ?? []);
+    $bufferTokens = Tokenizer::tokenCount($buffer->toString());
+    $summaryText = (string) ($event->data['summary'] ?? '');
+    $summaryTokens = Tokenizer::tokenCount($summaryText);
+
+    echo "\n>>> Summarization triggered ({$bufferTokens} tokens > {$summaryTriggerLimit}).\n";
+    echo ">>> Summary tokens: {$summaryTokens}\n";
+    $bufferTokens = 0;
+});
 
 $student = new ScriptedParticipant(
     name: 'student',
@@ -60,30 +101,55 @@ $chat = ChatFactory::default(
         ),
     ),
     processors: new StateProcessors(
-        new AccumulateTokenUsage(),
-        new AppendStepMessages(),
-        new MoveMessagesToBuffer(
-            maxTokens: 128,
-            bufferSection: 'buffer',
-            events: $events
-        ),
         new SummarizeBuffer(
-            maxBufferTokens: 128,
-            maxSummaryTokens: 512,
+            maxBufferTokens: $summaryTriggerLimit,
+            maxSummaryTokens: $summaryMaxTokens,
             bufferSection: 'buffer',
             summarySection: 'summary',
             summarizer: new SummarizeMessages(llm: LLMProvider::using('openai')),
             events: $events,
         ),
+        new MoveMessagesToBuffer(
+            maxTokens: $bufferTokenLimit,
+            bufferSection: 'buffer',
+            events: $events
+        ),
+        new AppendStepMessages(),
+        new AccumulateTokenUsage(),
     ),
     events: $events,
 );//->wiretap(fn(Event $e) => $e->printDebug());
 
-$context = "# CONTEXT\n\n" . file_get_contents(__DIR__ . '/summary.md');
+$context = "# CONTEXT\n\nThis is a long-running coaching session about improving sales performance using the Challenger Sale approach.";
+$seedHistory = Messages::fromString(content: $context, role: 'system')
+    ->appendMessage(Message::fromString(
+        content: 'I keep stalling after the first discovery call and need a clear Challenger-style way to reframe the conversation and surface urgency.',
+        role: 'user'
+    ))
+    ->appendMessage(Message::fromString(
+        content: 'Lead with a tailored insight that challenges their current assumption, then ask two pointed questions that quantify the gap and cost.',
+        role: 'assistant'
+    ))
+    ->appendMessage(Message::fromString(
+        content: 'Prospects compare us to cheaper tools, so I need a concise way to defend ROI without sounding defensive.',
+        role: 'user'
+    ))
+    ->appendMessage(Message::fromString(
+        content: 'Use a short payback story with a concrete metric, then contrast the cost of delay against a specific business outcome.',
+        role: 'assistant'
+    ))
+    ->appendMessage(Message::fromString(
+        content: 'We sell across industries and I struggle to adapt the story without rebuilding the whole deck.',
+        role: 'user'
+    ))
+    ->appendMessage(Message::fromString(
+        content: 'Keep a core narrative and swap only the pains and metrics so the challenge-then-resolution arc stays consistent.',
+        role: 'assistant'
+    ));
 
-$state = (new ChatState)->withMessages(
-    Messages::fromString(content: $context, role: 'system')
-);
+$state = (new ChatState)->withMessages($seedHistory);
+
+echo "Messages keep at most {$bufferTokenLimit} tokens; buffer summarizes past {$summaryTriggerLimit} tokens.\n";
 
 while ($chat->hasNextStep($state)) {
     $state = $chat->nextStep($state);
@@ -92,7 +158,11 @@ while ($chat->hasNextStep($state)) {
     $name = $step?->participantName() ?? 'unknown';
     $content = trim($step?->outputMessages()->toString() ?? '');
     echo "\n--- Step " . ($state->stepCount()) . " ($name) ---\n";
-    echo ($content ?: '[eot]'). "\n";
+    $display = $content;
+    if ($display === '') {
+        $display = '[eot]';
+    }
+    echo $display . "\n";
 //    echo "---------------------\n";
 //    echo "SUMMARY:\n" . $state->store()->section('summary')->get()?->toString();
 //    echo "---------------------\n";
@@ -101,4 +171,10 @@ while ($chat->hasNextStep($state)) {
 //    echo "MESSAGES:\n" . $state->store()->section('messages')->get()?->toString();
 //    echo "=====================\n";
 }
+
+$summaryText = trim($state->store()->section('summary')->messages()->toString());
+if ($summaryText !== '') {
+    echo "\n--- Final Summary ---\n";
+    echo $summaryText . "\n";
+}
 ?>

docs-build/cookbook/polyglot/llm_extras/chat_with_summary.mdx

@@ -6,7 +6,7 @@ use Cognesy\Addons\StepByStep\Continuation\Criteria\ErrorPolicyCriterion;
 use Cognesy\Addons\StepByStep\Continuation\Criteria\ExecutionTimeLimit;
 use Cognesy\Addons\StepByStep\Continuation\Criteria\StepsLimit;
 use Cognesy\Addons\StepByStep\Continuation\Criteria\TokenUsageLimit;
-use Cognesy\Addons\StepByStep\Continuation\ErrorPolicy;
+use Cognesy\Addons\StepByStep\ErrorHandling\ErrorPolicy;
 use Cognesy\Addons\ToolUse\Collections\Tools;
 use Cognesy\Addons\ToolUse\Data\ToolUseState;
 use Cognesy\Addons\ToolUse\Drivers\ReAct\ContinuationCriteria\StopOnFinalDecision;