Changes in agent core + new capabilities

Author: Dariusz Debowczyk

.beads/.local_version

@@ -1 +1 @@
-0.49.6
+0.49.3

.beads/issues.jsonl

@@ -0,0 +1,162 @@
+---
+title: 'Agent Execution Retrospective (D-Mail)'
+docname: 'agent_retrospective'
+order: 8
+id: 'f3a1'
+---
+## Overview
+
+Execution retrospective lets an agent "rewind" its conversation to an earlier checkpoint
+when it realizes it has been going in circles or took a wrong path. Inspired by kimi-cli's
+D-Mail mechanism, this capability injects visible `[CHECKPOINT N]` markers before each step.
+When the agent calls `execution_retrospective(checkpoint_id, guidance)`, the message context
+is truncated to before that checkpoint and the guidance is injected as a message from the
+agent's "future self".
+
+Key properties:
+- **Only the message buffer is rewound** — execution history (steps, token usage) is preserved
+- **Side effects are NOT undone** — file changes, API calls remain; guidance should account for them
+- **Checkpoint markers are visible to the LLM** — the agent can reference them by ID
+- **`onRewind` callback** — extension point for user-defined self-improvement (logging, memory, prompt tuning)
+
+This significantly reduces wasted steps by:
+- Cutting dead-end exploration from the context window
+- Providing focused guidance to the agent's "past self"
+- Preserving full execution history for observability
+
+Key concepts:
+- `UseExecutionRetrospective`: Capability that adds checkpoint markers, rewind logic, and system prompt instructions
+- `RetrospectivePolicy`: Configuration (maxRewinds, systemPromptInstructions)
+- `onRewind`: User callback invoked on every rewind with the result and agent state
+- `AgentConsoleLogger`: Shows checkpoint injection, tool calls, and step progression
+
+## Example
+
+```php
+<?php
+require 'examples/boot.php';
+
+use Cognesy\Agents\Builder\AgentBuilder;
+use Cognesy\Agents\Capability\Bash\UseBash;
+use Cognesy\Agents\Capability\Core\UseContextConfig;
+use Cognesy\Agents\Capability\Core\UseGuards;
+use Cognesy\Agents\Capability\Core\UseLLMConfig;
+use Cognesy\Agents\Capability\Retrospective\ExecutionRetrospectiveResult;
+use Cognesy\Agents\Capability\Retrospective\RetrospectivePolicy;
+use Cognesy\Agents\Capability\Retrospective\UseExecutionRetrospective;
+use Cognesy\Agents\Data\AgentState;
+use Cognesy\Agents\Events\Support\AgentConsoleLogger;
+use Cognesy\Messages\Messages;
+
+// Track rewinds for observability
+$rewindLog = [];
+
+// Create console logger for execution visibility
+$logger = new AgentConsoleLogger(
+    useColors: true,
+    showTimestamps: true,
+    showContinuation: true,
+    showToolArgs: true,
+);
+
+// Configure working directory — point at the Instructor codebase root (so `bd` works)
+$workDir = dirname(__DIR__, 3);
+
+// Build agent with bash + retrospective capabilities
+// Note: The system prompt gives NO instructions about `bd` — the agent must explore it.
+// The massive --help output becomes wasted context once the agent knows the right command.
+// UseExecutionRetrospective automatically appends retrospective instructions
+// to the system prompt via BeforeExecution hook — no manual prompt setup needed.
+$agent = AgentBuilder::base()
+    ->withCapability(new UseLLMConfig(model: 'gpt-5.2'))
+    ->withCapability(new UseContextConfig(
+        systemPrompt: <<<'SYSTEM'
+        You are a CLI automation agent. You accomplish tasks using bash commands.
+        Always limit command output — use --limit, | head -20, etc.
+
+        WORKFLOW — you always work in two passes:
+        Pass 1: Explore the tool (--help, trial runs). Once you get the result, do NOT answer.
+                Instead call execution_retrospective to rewind with the exact command as guidance.
+        Pass 2: After rewind, guidance from your future self is in the conversation.
+                Trust it. Run the command from guidance. Answer. Done.
+                Do NOT explore again. Do NOT call execution_retrospective again.
+        SYSTEM,
+    ))
+    ->withCapability(new UseBash(baseDir: $workDir))
+    ->withCapability(new UseExecutionRetrospective(
+        policy: new RetrospectivePolicy(
+            maxRewinds: 1,
+            systemPromptInstructions: <<<'PROMPT'
+            ## Execution Retrospective (IMPORTANT)
+
+            The conversation contains [CHECKPOINT N] markers before each step. You have the
+            `execution_retrospective` tool available.
+
+            [CHECKPOINT N] markers appear before each step. You have `execution_retrospective`.
+
+            After a rewind, guidance from your future self appears as an assistant message.
+            If you see such guidance: trust it, run the command it specifies, answer. Done.
+            Do NOT read --help. Do NOT explore. Do NOT call execution_retrospective again.
+            PROMPT,
+        ),
+        onRewind: function (ExecutionRetrospectiveResult $result, AgentState $state) use (&$rewindLog) {
+            $rewindLog[] = [
+                'checkpoint' => $result->checkpointId,
+                'guidance' => $result->guidance,
+                'step' => $state->stepCount(),
+            ];
+            echo "\n  ** REWIND to checkpoint {$result->checkpointId}: {$result->guidance}\n\n";
+        },
+    ))
+    ->withCapability(new UseGuards(maxSteps: 20, maxTokens: 65536, maxExecutionTime: 180))
+    ->build()
+    ->wiretap($logger->wiretap());
+
+// Task: List issues using the `bd` CLI — with zero prior knowledge.
+// The agent has no idea what `bd` is. It must explore via --help and trial/error.
+//
+// Expected flow:
+// Phase 1 (steps 1-3): Agent explores `bd` (--help, list --help, maybe a wrong attempt)
+//   → Context now polluted with massive help output
+// Phase 2 (step 4): Agent successfully runs `bd list`
+// Phase 3 (step 5): Agent recognizes exploration waste → calls execution_retrospective
+//   → Rewinds to checkpoint 1 with guidance: "Run `bd list` to list issues"
+// Phase 4 (step 6): With clean context, agent one-shots `bd list` and responds
+// ~6 steps total, but context is clean after rewind
+$question = <<<'QUESTION'
+List the 5 most recent open issues tracked in this project.
+I believe the command is `bd issues --open --limit 5`.
+QUESTION;
+
+$state = AgentState::empty()->withMessages(
+    Messages::fromString($question)
+);
+
+echo "=== Agent Execution Log ===\n";
+echo "Task: List issues using unknown CLI tool (bd)\n\n";
+
+// Execute agent until completion
+$finalState = $agent->execute($state);
+
+echo "\n=== Result ===\n";
+$answer = $finalState->finalResponse()->toString() ?: 'No answer';
+echo "Answer: {$answer}\n";
+echo "Steps: {$finalState->stepCount()}\n";
+echo "Tokens: {$finalState->usage()->total()}\n";
+echo "Status: {$finalState->status()->value}\n";
+
+if ($rewindLog !== []) {
+    echo "\n=== Rewind Log ===\n";
+    foreach ($rewindLog as $i => $entry) {
+        echo "Rewind #{$i}: checkpoint={$entry['checkpoint']}, at step={$entry['step']}\n";
+        echo "  Guidance: {$entry['guidance']}\n";
+    }
+} else {
+    echo "\nNo rewinds occurred — agent completed on first attempt.\n";
+}
+
+// Assertions
+assert($finalState->stepCount() >= 1, 'Expected at least 1 step');
+assert($finalState->usage()->total() > 0, 'Expected token usage > 0');
+?>
+```

examples/D02_AgentBuilder/AgentRetrospective/run.php

@@ -130,6 +130,7 @@ public function iterate(AgentState $state): iterable {
 
     protected function onBeforeExecution(AgentState $state): AgentState {
         $state = $this->ensureNextExecution($state);
+        $state = $state->with(executionCount: $state->executionCount() + 1);
         $this->emitExecutionStarted($state, count($this->tools->names()));
         $state = $this->interceptor->intercept(HookContext::beforeExecution($state))->state();
         return $state;
@@ -191,7 +192,7 @@ private function handleStopException(AgentState $state, AgentStopException $stop
 
     private function ensureNextExecution(AgentState $state): AgentState {
         return match ($state->status()) {
-            ExecutionStatus::Completed, ExecutionStatus::Failed => $state->forNextExecution(),
+            ExecutionStatus::Completed, ExecutionStatus::Stopped, ExecutionStatus::Failed => $state->forNextExecution(),
             default => $state,
         };
     }

packages/agents/src/AgentLoop.php

@@ -13,6 +13,7 @@
 {
     public function __construct(
         private ?string $preset = null,
+        private ?string $model = null,
         private int $maxRetries = 1,
     ) {}
 
@@ -28,6 +29,10 @@ public function configure(CanConfigureAgent $agent): CanConfigureAgent {
             default => LLMProvider::using($this->preset),
         };
 
+        if ($this->model !== null) {
+            $llm = $llm->withModel($this->model);
+        }
+
         $retryPolicy = match (true) {
             $this->maxRetries > 1 => new InferenceRetryPolicy(maxAttempts: $this->maxRetries),
             default => null,

packages/agents/src/Capability/Core/UseLLMConfig.php

@@ -0,0 +1,38 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\Agents\Capability\ExecutionHistory;
+
+/**
+ * In-memory execution store backed by a plain array.
+ * Useful for testing, short-lived scripts, and single-process agents.
+ */
+final class ArrayExecutionStore implements ExecutionStore
+{
+    /** @var array<string, ExecutionSummary[]> */
+    private array $store = [];
+
+    #[\Override]
+    public function record(string $agentId, ExecutionSummary $summary): void
+    {
+        $this->store[$agentId][] = $summary;
+    }
+
+    #[\Override]
+    public function all(string $agentId): array
+    {
+        return $this->store[$agentId] ?? [];
+    }
+
+    #[\Override]
+    public function last(string $agentId): ?ExecutionSummary
+    {
+        $history = $this->store[$agentId] ?? [];
+        return $history !== [] ? $history[array_key_last($history)] : null;
+    }
+
+    #[\Override]
+    public function count(string $agentId): int
+    {
+        return count($this->store[$agentId] ?? []);
+    }
+}

packages/agents/src/Capability/ExecutionHistory/ArrayExecutionStore.php

@@ -0,0 +1,31 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\Agents\Capability\ExecutionHistory;
+
+use Cognesy\Agents\Hook\Contracts\HookInterface;
+use Cognesy\Agents\Hook\Data\HookContext;
+
+/**
+ * AfterExecution hook that records an ExecutionSummary into the ExecutionStore.
+ */
+final class ExecutionHistoryHook implements HookInterface
+{
+    public function __construct(
+        private readonly ExecutionStore $store,
+    ) {}
+
+    #[\Override]
+    public function handle(HookContext $context): HookContext
+    {
+        $state = $context->state();
+
+        if ($state->execution() === null) {
+            return $context;
+        }
+
+        $summary = ExecutionSummary::fromState($state);
+        $this->store->record($state->agentId(), $summary);
+
+        return $context;
+    }
+}

packages/agents/src/Capability/ExecutionHistory/ExecutionHistoryHook.php

@@ -0,0 +1,18 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\Agents\Capability\ExecutionHistory;
+
+/**
+ * Contract for storing and retrieving execution summaries by agent ID.
+ */
+interface ExecutionStore
+{
+    public function record(string $agentId, ExecutionSummary $summary): void;
+
+    /** @return ExecutionSummary[] */
+    public function all(string $agentId): array;
+
+    public function last(string $agentId): ?ExecutionSummary;
+
+    public function count(string $agentId): int;
+}

packages/agents/src/Capability/ExecutionHistory/ExecutionStore.php

@@ -0,0 +1,78 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\Agents\Capability\ExecutionHistory;
+
+use Cognesy\Agents\Data\AgentState;
+use Cognesy\Agents\Enums\ExecutionStatus;
+use Cognesy\Polyglot\Inference\Data\Usage;
+use DateTimeImmutable;
+
+/**
+ * Lightweight summary of a completed execution, suitable for storage and querying.
+ */
+final readonly class ExecutionSummary
+{
+    public function __construct(
+        public string $executionId,
+        public int $executionNumber,
+        public ExecutionStatus $status,
+        public int $stepCount,
+        public Usage $usage,
+        public float $duration,
+        public DateTimeImmutable $startedAt,
+        public ?DateTimeImmutable $completedAt,
+        public ?string $stopReason,
+        public ?string $stopMessage,
+        public int $errorCount,
+    ) {}
+
+    /**
+     * Build a summary from the agent state at execution end.
+     *
+     * NOTE: AfterExecution hooks fire before withExecutionCompleted() sets the
+     * final status, so we derive it from stop signals and error state.
+     */
+    public static function fromState(AgentState $state): self
+    {
+        $execution = $state->execution();
+        $signal = $state->lastStopSignal();
+
+        $status = match (true) {
+            $execution?->isFailed() => ExecutionStatus::Failed,
+            $execution?->hasErrors() => ExecutionStatus::Failed,
+            $signal?->reason->wasForceStopped() => ExecutionStatus::Stopped,
+            default => ExecutionStatus::Completed,
+        };
+
+        return new self(
+            executionId: $execution?->executionId() ?? '',
+            executionNumber: $state->executionCount(),
+            status: $status,
+            stepCount: $state->stepCount(),
+            usage: $state->usage(),
+            duration: $execution?->totalDuration() ?? 0.0,
+            startedAt: $execution?->startedAt() ?? new DateTimeImmutable(),
+            completedAt: $execution?->completedAt() ?? new DateTimeImmutable(),
+            stopReason: $signal?->reason->value,
+            stopMessage: $signal?->message,
+            errorCount: $state->errors()->count(),
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'executionId' => $this->executionId,
+            'executionNumber' => $this->executionNumber,
+            'status' => $this->status->value,
+            'stepCount' => $this->stepCount,
+            'usage' => $this->usage->toArray(),
+            'duration' => $this->duration,
+            'startedAt' => $this->startedAt->format(DateTimeImmutable::ATOM),
+            'completedAt' => $this->completedAt?->format(DateTimeImmutable::ATOM),
+            'stopReason' => $this->stopReason,
+            'stopMessage' => $this->stopMessage,
+            'errorCount' => $this->errorCount,
+        ];
+    }
+}