Deep refactor of schema for 2.0.0

Author: ddebowczyk

.beads/issues.jsonl

@@ -11,15 +11,19 @@ permissions:
 
 jobs:
   build:
-    name: 'PHP ${{ matrix.php }} (Composer Flags: ${{ matrix.composer }})'
+    name: 'PHP ${{ matrix.php }} (Symfony ${{ matrix.symfony }}, Composer Flags: ${{ matrix.composer }})'
 
     runs-on: ubuntu-24.04
 
     strategy:
       fail-fast: true
       matrix:
         php: ['8.3', '8.4', '8.5']
+        symfony: ['^7.0', '^8.0']
         composer: ['--prefer-stable', '--prefer-lowest']
+        exclude:
+          - php: '8.3'
+            symfony: '^8.0'
 
     steps:
     - uses: actions/checkout@v3
@@ -37,14 +41,30 @@ jobs:
 #          ${{ runner.os }}-php-
 
     - name: Install dependencies
-      run: composer update --no-interaction ${{ matrix.composer }}
+      run: >
+        composer update --no-interaction ${{ matrix.composer }} -W
+        --with symfony/console:${{ matrix.symfony }}
+        --with symfony/filesystem:${{ matrix.symfony }}
+        --with symfony/process:${{ matrix.symfony }}
+        --with symfony/property-access:${{ matrix.symfony }}
+        --with symfony/property-info:${{ matrix.symfony }}
+        --with symfony/serializer:${{ matrix.symfony }}
+        --with symfony/validator:${{ matrix.symfony }}
+        --with symfony/var-dumper:${{ matrix.symfony }}
+        --with symfony/yaml:${{ matrix.symfony }}
+        --with symfony/css-selector:${{ matrix.symfony }}
+        --with symfony/dom-crawler:${{ matrix.symfony }}
+        --with symfony/http-client:${{ matrix.symfony }}
 
     - name: Regenerate Autoloader
       run: composer dump-autoload
 
     - name: Run test suite (all code local)
       run: composer test
 
+    - name: Run Instructor docs QA
+      run: composer --working-dir=packages/instructor docs:qa
+
 #    - name: Install dependencies in all packages
 #      run: |
 #        for dir in packages/*; do

.github/workflows/php.yml

@@ -1,7 +1,7 @@
 #!/usr/bin/env php
 <?php
 
-use Cognesy\Doctor\Docs;
+use Cognesy\Doctools\Docs;
 
 ini_set('display_errors', 1);
 ini_set('display_startup_errors', 1);
@@ -28,4 +28,4 @@ require findAutoload();
 
 // run the app
 $app = new Docs();
-$app->run();
+$app->run();

bin/instructor-docs

@@ -47,20 +47,21 @@
         "psr/http-client": "^1.0",
         "psr/http-message": "^2.0",
         "psr/log": "^3.0",
-        "symfony/console": "^7.1",
-        "symfony/filesystem": "^7.1",
-        "symfony/process": "^7.0",
-        "symfony/property-access": "^7.0",
-        "symfony/property-info": "^7.0",
-        "symfony/serializer": "^7.0",
-        "symfony/validator": "^7.0",
-        "symfony/var-dumper": "^7.0",
-        "symfony/yaml": "^7.0",
+        "symfony/console": "^7.1 || ^8.0",
+        "symfony/filesystem": "^7.1 || ^8.0",
+        "symfony/process": "^7.0 || ^8.0",
+        "symfony/property-access": "^7.0 || ^8.0",
+        "symfony/property-info": "^7.0 || ^8.0",
+        "symfony/serializer": "^7.0 || ^8.0",
+        "symfony/validator": "^7.0 || ^8.0",
+        "symfony/var-dumper": "^7.0 || ^8.0",
+        "symfony/yaml": "^7.0 || ^8.0",
         "vlucas/phpdotenv": "^5.6"
     },
     "scripts": {
         "bench": "@php ./vendor/bin/phpbench run",
         "docs": "@php ./bin/instructor-docs",
+        "docs:qa": "bash ./scripts/docs-qa-all.sh",
         "hub": "php ./bin/instructor-hub",
         "phpstan": "@php ./vendor/bin/phpstan analyse -c phpstan.neon",
         "psalm": "@php ./vendor/bin/psalm -c packages/instructor/psalm.xml",
@@ -120,7 +121,7 @@
             "Cognesy\\Pipeline\\": "packages/pipeline/src/",
             "Cognesy\\Polyglot\\": "packages/polyglot/src/",
             "Cognesy\\Sandbox\\": "packages/sandbox/src/",
-            "Cognesy\\Schema\\": "packages/schema/src/",
+            "Cognesy\\Schema\\": "packages/schema2/src/",
             "Cognesy\\Setup\\": "packages/setup/src/",
             "Cognesy\\Stream\\": "packages/stream/src/",
             "Cognesy\\Template\\": "packages/templates/src/",
@@ -150,7 +151,7 @@
             "Cognesy\\Pipeline\\Tests\\": "packages/pipeline/tests/",
             "Cognesy\\Polyglot\\Tests\\": "packages/polyglot/tests/",
             "Cognesy\\Sandbox\\Tests\\": "packages/sandbox/tests/",
-            "Cognesy\\Schema\\Tests\\": "packages/schema/tests/",
+            "Cognesy\\Schema\\Tests\\": "packages/schema2/tests/",
             "Cognesy\\Setup\\Tests\\": "packages/setup/tests/",
             "Cognesy\\Stream\\Tests\\": "packages/stream/tests/",
             "Cognesy\\Templates\\Tests\\": "packages/templates/tests/",
@@ -203,9 +204,9 @@
         "psr/http-factory-implementation": "*",
         "shipmonk/dead-code-detector": "^0.5.1",
         "spatie/browsershot": "^5.1",
-        "symfony/css-selector": "^7.0",
-        "symfony/dom-crawler": "^7.0",
-        "symfony/http-client": "^7.0",
+        "symfony/css-selector": "^7.0 || ^8.0",
+        "symfony/dom-crawler": "^7.0 || ^8.0",
+        "symfony/http-client": "^7.0 || ^8.0",
         "toolkit/cli-utils": "^2.0",
         "twig/twig": "^3.0",
         "vimeo/psalm": "^6.0"

composer.json

@@ -12,7 +12,7 @@
             'streamChunkSize' => 256,
             'maxConcurrent' => 5,
             'poolTimeout' => 60,
-            'failOnError' => true,
+            'failOnError' => false,
         ],
         'guzzle' => [
             'driver' => 'guzzle',
@@ -22,7 +22,7 @@
             'streamChunkSize' => 256,
             'maxConcurrent' => 5,
             'poolTimeout' => 60,
-            'failOnError' => true,
+            'failOnError' => false,
         ],
         'symfony' => [
             'driver' => 'symfony',
@@ -32,7 +32,7 @@
             'streamChunkSize' => 0,
             'maxConcurrent' => 5,
             'poolTimeout' => 60,
-            'failOnError' => true,
+            'failOnError' => false,
         ],
         'laravel' => [
             'driver' => 'laravel',
@@ -42,7 +42,7 @@
             'streamChunkSize' => 256,
             'maxConcurrent' => 5,
             'poolTimeout' => 60,
-            'failOnError' => true,
+            'failOnError' => false,
         ],
         'exthttp' => [
             'driver' => 'exthttp',
@@ -52,7 +52,7 @@
             'streamChunkSize' => 256,
             'maxConcurrent' => 10,
             'poolTimeout' => 60,
-            'failOnError' => true,
+            'failOnError' => false,
         ],
         'http-ollama' => [
             'driver' => 'guzzle',
@@ -62,7 +62,7 @@
             'idleTimeout' => -1,
             'maxConcurrent' => 5,
             'poolTimeout' => 60,
-            'failOnError' => true,
+            'failOnError' => false,
         ],
     ],
 ];

config/http.php

@@ -0,0 +1,26 @@
+---
+title: Overview
+description: 'Unified API for Claude Code, Codex, and OpenCode CLIs.'
+---
+
+`agent-ctrl` gives you one fluent API (`AgentCtrl`) to run different code-agent CLIs.
+
+Supported bridges:
+
+- Claude Code
+- OpenAI Codex
+- OpenCode
+
+All of them return the same response type: `AgentResponse`.
+
+## Docs
+
+- [Getting Started](2-getting-started.md)
+- [Streaming](3-streaming.md)
+- [Session Management](4-session-management.md)
+- [Agent Options](5-agent-options.md)
+- [Response Object](6-response-object.md)
+- [Troubleshooting](7-troubleshooting.md)
+- [Claude Code Bridge (Internals)](8-claude-code-bridge.md)
+- [Codex Bridge (Internals)](9-codex-bridge.md)
+- [OpenCode Bridge (Internals)](10-opencode-bridge.md)

docs-build/packages/agent-ctrl/1-overview.mdx

@@ -0,0 +1,43 @@
+---
+title: 'OpenCode Bridge (Internals)'
+description: 'Low-level OpenCode CLI bridge flow for advanced use cases.'
+---
+
+> Most users should use `AgentCtrl::openCode()` from the high-level API.
+> Use this page when you need direct request/command/parser control.
+
+## Core Flow
+
+```php
+use Cognesy\AgentCtrl\Common\Execution\SandboxCommandExecutor;
+use Cognesy\AgentCtrl\OpenCode\Application\Builder\OpenCodeCommandBuilder;
+use Cognesy\AgentCtrl\OpenCode\Application\Dto\OpenCodeRequest;
+use Cognesy\AgentCtrl\OpenCode\Application\Parser\ResponseParser;
+use Cognesy\AgentCtrl\OpenCode\Domain\Enum\OutputFormat;
+
+$request = new OpenCodeRequest(
+    prompt: 'Summarize the architecture in short bullets.',
+    outputFormat: OutputFormat::Json,
+);
+
+$spec = (new OpenCodeCommandBuilder())->buildRun($request);
+$result = SandboxCommandExecutor::forOpenCode()->execute($spec);
+$response = (new ResponseParser())->parse($result, OutputFormat::Json);
+
+echo $response->messageText();
+// @doctest id="d364"
+```
+
+## Session Handling
+
+`OpenCodeRequest` supports:
+
+- `continueSession: true` (resume most recent)
+- `sessionId: '...'` (resume a specific session)
+
+## Key Types
+
+- Request DTO: `OpenCodeRequest`
+- Command builder: `OpenCodeCommandBuilder`
+- Parser: `ResponseParser`
+- Stream events: `TextEvent`, `ToolUseEvent`, `StepFinishEvent`, `ErrorEvent`

docs-build/packages/agent-ctrl/10-opencode-bridge.mdx

@@ -0,0 +1,35 @@
+---
+title: 'Getting Started'
+description: 'Run your first prompt with AgentCtrl.'
+---
+
+## Install
+
+```bash
+composer require cognesy/agent-ctrl
+# @doctest id="09bd"
+```
+
+You need at least one CLI binary installed and authenticated (`claude`, `codex`, or `opencode`).
+
+## Minimal Execution
+
+```php
+use Cognesy\AgentCtrl\AgentCtrl;
+
+$response = AgentCtrl::codex()->execute('Summarize this repository.');
+
+echo $response->text();
+// @doctest id="f6ab"
+```
+
+## Runtime Agent Selection
+
+```php
+use Cognesy\AgentCtrl\AgentCtrl;
+use Cognesy\AgentCtrl\Enum\AgentType;
+
+$agent = AgentType::from('codex');
+$response = AgentCtrl::make($agent)->execute('List top risks in this code.');
+// @doctest id="849a"
+```

docs-build/packages/agent-ctrl/2-getting-started.mdx

@@ -0,0 +1,21 @@
+---
+title: Streaming
+description: 'Handle text, tool, completion, and error events in real time.'
+---
+
+Use `executeStreaming()` when you want incremental output.
+
+```php
+use Cognesy\AgentCtrl\AgentCtrl;
+use Cognesy\AgentCtrl\Dto\AgentResponse;
+
+$response = AgentCtrl::openCode()
+    ->onText(fn(string $text) => print($text))
+    ->onToolUse(fn(string $tool, array $input, ?string $output) => print("\n[tool:$tool]\n"))
+    ->onComplete(fn(AgentResponse $response) => print("\n[done]\n"))
+    ->onError(fn(string $message, ?string $code) => print("\n[error:$message]\n"))
+    ->executeStreaming('Explain this package architecture.');
+// @doctest id="ae97"
+```
+
+`execute()` is a non-streaming convenience method.

docs-build/packages/agent-ctrl/3-streaming.mdx

@@ -0,0 +1,35 @@
+---
+title: 'Session Management'
+description: 'Continue the latest session or resume a specific session ID.'
+---
+
+All bridges support continuing and resuming sessions.
+
+## Continue Latest Session
+
+```php
+use Cognesy\AgentCtrl\AgentCtrl;
+
+$response = AgentCtrl::codex()
+    ->continueSession()
+    ->execute('Continue from the previous plan and apply step 2.');
+// @doctest id="9993"
+```
+
+## Resume Specific Session
+
+```php
+use Cognesy\AgentCtrl\AgentCtrl;
+
+$first = AgentCtrl::codex()->execute('Create a migration plan.');
+$sessionId = $first->sessionId();
+
+if ($sessionId !== null) {
+    $next = AgentCtrl::codex()
+        ->resumeSession((string) $sessionId)
+        ->execute('Now implement the first migration.');
+}
+// @doctest id="da0c"
+```
+
+`sessionId()` returns `AgentSessionId|null`.