Merge pull request #17 from atlas-php/main

Added new middleware feature at runtime.

Author: timothymarois

.github/workflows/deploy-docs.yml

@@ -2,7 +2,7 @@ name: Deploy Documentation
 
 on:
   push:
-    branches: [main]
+    branches: [2.x]
     paths:
       - 'docs/**'
       - '.github/workflows/deploy-docs.yml'

.gitignore

@@ -66,6 +66,4 @@ sandbox/storage/logs/*
 # VitePress
 docs/.vitepress/cache
 docs/.vitepress/dist
-
-# Package-specific ignores
 composer.lock

NOTES.md

@@ -0,0 +1,40 @@
+# Development Notes
+
+## TODO: PHPUnit Security Advisory (CVE-2026-24765)
+
+**Date:** 2026-01-27
+
+**Issue:** PHPUnit has a security vulnerability (CVE-2026-24765 - Unsafe Deserialization in PHPT Code Coverage Handling).
+
+- **Fixed in:** PHPUnit 11.5.50
+- **Pest 3.x conflicts with:** PHPUnit >11.5.33
+- **Result:** Pest 3.x blocks the security fix
+
+**Current Workaround:** Ignoring the advisory in `composer.json`:
+```json
+"audit": {
+    "ignore": ["PKSA-z3gr-8qht-p93v"]
+}
+```
+
+**Why not upgrade to Pest 4?** Pest 4.x requires PHPUnit 12.x - a major version change.
+
+**Action Required:**
+- Monitor Pest 3.x releases for PHPUnit 11.5.50 support
+- Once Pest 3.x supports the fixed PHPUnit, remove the audit ignore
+- Alternatively, evaluate upgrading to Pest 4.x + PHPUnit 12.x
+
+---
+
+## Open Question: Should we commit `composer.lock`?
+
+**Pros:**
+- Reproducible CI builds
+- Avoids surprise failures when upstream dependencies release breaking changes
+- Zero impact on consumers (lock file is ignored when package is installed as dependency)
+
+**Cons:**
+- Traditional library convention is to not commit lock files
+- May mask dependency resolution issues until intentional updates
+
+**Decision:** TBD

README.md

@@ -154,9 +154,9 @@ echo $response->text();
 
 ## Why Atlas?
 
-**The problem:** Prompts scattered across controllers, duplicated configurations, businesses logic tightly coupled with tools, and no consistent way to add logging, validation or even proper error handling.
+**The problem:** Prompts scattered across controllers, duplicated configurations, business logic tightly coupled with tools, and no consistent way to add logging, validation or even proper error handling.
 
-**Atlas decouples your businesses logic:**
+**Atlas decouples your business logic:**
 
 - **Agents** - AI configurations live in dedicated classes, not inline across your codebase.
 - **Tools** - Business logic stays in tool classes with typed parameters. Agents call tools; tools call your services.

composer.json

@@ -15,6 +15,15 @@
         "orchestra/testbench": "^9.0|^10.0",
         "pestphp/pest": "^3.0"
     },
+    "config": {
+        "sort-packages": true,
+        "allow-plugins": {
+            "pestphp/pest-plugin": true
+        },
+        "audit": {
+            "ignore": ["PKSA-z3gr-8qht-p93v"]
+        }
+    },
     "suggest": {
         "prism-php/relay": "Required for MCP (Model Context Protocol) tool support"
     },
@@ -42,12 +51,6 @@
             "@test"
         ]
     },
-    "config": {
-        "sort-packages": true,
-        "allow-plugins": {
-            "pestphp/pest-plugin": true
-        }
-    },
     "extra": {
         "laravel": {
             "providers": [

docs/capabilities/chat.md

@@ -220,6 +220,7 @@ $response = Atlas::agent('support-agent')
 | `withMedia(array $media)` | Attach Prism media objects via builder pattern |
 | `withTools(array $tools)` | Add Atlas tools at runtime (accumulates) |
 | `withMcpTools(array $tools)` | Add MCP tools at runtime ([details](/capabilities/mcp)) |
+| `middleware(array $handlers)` | Attach per-request pipeline handlers ([details](/core-concepts/pipelines#runtime-middleware)) |
 
 </div>
 
@@ -305,6 +306,10 @@ Atlas::agent(string|AgentContract $agent)
     ->withTools(array $tools)                             // Add Atlas tools at runtime
     ->withMcpTools(array $tools)                          // Add MCP tools at runtime
 
+    // Middleware
+    ->middleware(array $handlers)                         // Attach per-request pipeline handlers
+    ->withoutMiddleware()                                 // Remove all runtime middleware
+
     // Structured output
     ->withSchema(SchemaBuilder|ObjectSchema $schema)      // Schema for structured response
     ->usingAutoMode()                                     // Auto schema mode (default)
@@ -374,3 +379,4 @@ Image::fromFileId(string $fileId): Image;
 - [Streaming](/capabilities/streaming) — Real-time streaming responses
 - [Structured](/capabilities/structured-output) — Schema-based responses
 - [MCP](/capabilities/mcp) — External tools from MCP servers
+- [Pipelines](/core-concepts/pipelines#runtime-middleware) — Per-request middleware for validation, logging, and error recovery

docs/core-concepts/agents.md

@@ -965,6 +965,148 @@ $registry->decoratorCount();  // number of registered decorators
 $registry->clearDecorators(); // remove all decorators
 ```
 
+## Runtime Middleware
+
+Attach per-request middleware to agent executions without global registration. This is useful for request-specific validation, logging, or error recovery.
+
+```php
+use Atlasphp\Atlas\Atlas;
+
+$response = Atlas::agent('my-agent')
+    ->middleware([
+        'agent.before_execute' => ValidateInputMiddleware::class,
+        'agent.after_execute' => LogResponseMiddleware::class,
+    ])
+    ->chat($input);
+```
+
+### Multiple Handlers
+
+```php
+->middleware([
+    'agent.before_execute' => [
+        AuthMiddleware::class,
+        RateLimitMiddleware::class,
+    ],
+])
+```
+
+### Handler Instances
+
+Pass configured instances for runtime configuration:
+
+```php
+->middleware([
+    'agent.after_execute' => new MetricsMiddleware($statsd),
+])
+```
+
+### Accumulating Middleware
+
+Multiple calls merge handlers:
+
+```php
+->middleware(['agent.before_execute' => AuthMiddleware::class])
+->middleware(['agent.after_execute' => LogMiddleware::class])
+// Both middleware are applied
+```
+
+### Clearing Middleware
+
+```php
+->withoutMiddleware()
+```
+
+Runtime middleware merges with global handlers by priority. Global handlers run first (sorted by their registered priority), followed by runtime handlers (in registration order).
+
+See [Runtime Middleware](/core-concepts/pipelines#runtime-middleware) for complete documentation including available events, execution order, and examples.
+
+## Queue Processing
+
+AgentContext supports serialization for queue-based async processing. This enables dispatching agent jobs to Laravel queues while Atlas handles only the context serialization—consumers manage all persistence.
+
+### Dispatching to Queue
+
+```php
+// Build context and serialize for queue transport
+$context = new AgentContext(
+    variables: [
+        'user_name' => $user->name
+    ],
+    metadata: [
+        'task_id' => $task->id,
+        'user_id' => $user->id
+    ],
+);
+
+// You create a job that accepts AgentContext as a constructor argument
+ProcessAgentJob::dispatch(
+    agentKey: 'my-agent',
+    input: 'Generate a report',
+    context: $context->toArray(),
+);
+```
+
+### Processing in Job
+
+Create a processing job
+
+```php
+use Atlasphp\Atlas\Agents\Support\AgentContext;
+
+class ProcessAgentJob implements ShouldQueue
+{
+    public function __construct(
+        public string $agentKey,
+        public string $input,
+        public array $context,
+    ) {}
+
+    public function handle(): void
+    {
+        $context = AgentContext::fromArray($this->context);
+
+        $response = Atlas::agent($this->agentKey)
+            ->withContext($context)
+            ->chat($this->input);
+
+        // Handle response...
+    }
+}
+```
+
+### Serialization Notes
+
+The following properties are fully serialized:
+- `messages` — Conversation history in array format
+- `variables` — System prompt variable bindings
+- `metadata` — Pipeline metadata
+- `providerOverride` / `modelOverride` — Provider and model overrides
+- `prismCalls` — Captured Prism method calls
+- `tools` — Atlas tool class names
+- `middleware` — Runtime middleware (class-strings only; handler instances are excluded)
+
+Runtime-only properties (not serialized):
+- `prismMedia` — Media attachments (must be re-attached via `withMedia()`)
+- `prismMessages` — Prism message objects (rebuilt at runtime)
+- `mcpTools` — MCP tools (must be resolved at runtime)
+- Middleware handler instances — Only class-string handlers are serialized
+
+For media attachments, store the file path in metadata and re-attach in your job:
+
+```php
+public function handle(): void
+{
+    $context = AgentContext::fromArray($this->context);
+    $imagePath = $context->getMeta('image_path');
+
+    $response = Atlas::agent($this->agentKey)
+        ->withContext($context)
+        ->withMedia(Image::fromPath($imagePath))
+        ->chat($this->input);
+}
+```
+
 ## API Reference
 
 ```php
@@ -1000,6 +1142,8 @@ Atlas::agent(string|AgentContract $agent)
     ->withMedia(Image|Document|Audio|Video|array $media)     // Attach media
     ->withTools(array $tools)                    // Add Atlas tools at runtime
     ->withMcpTools(array $tools)                 // Add MCP tools at runtime
+    ->middleware(array $handlers)                // Attach per-request pipeline handlers
+    ->withoutMiddleware()                        // Remove all runtime middleware
     ->withSchema(SchemaBuilder|ObjectSchema $schema)         // Structured output
     ->usingAutoMode()                            // Auto schema mode (default)
     ->usingNativeMode()                          // Native JSON schema mode
@@ -1063,4 +1207,4 @@ $registry->clearDecorators(): void;
 - [System Prompts](/core-concepts/system-prompts) — Variable interpolation in prompts
 - [Tools](/core-concepts/tools) — Add callable tools to agents
 - [MCP](/capabilities/mcp) — External tools from MCP servers
-- [Pipelines](/core-concepts/pipelines) — Add middleware for agent execution
+- [Pipelines](/core-concepts/pipelines) — Global and per-request middleware for agent execution