refactor: move shared CLI command types to sandbox package

Dariusz Debowczyk · Dariusz Debowczyk · commit b2af1aad44b7 · 2026-02-21T21:02:19.000+01:00
diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl
diff --git a/packages/agent-ctrl/src/Bridge/ClaudeCodeBridge.php b/packages/agent-ctrl/src/Bridge/ClaudeCodeBridge.php
@@ -9,7 +9,7 @@
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Dto\StreamEvent\StreamEvent;
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Enum\OutputFormat;
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Enum\PermissionMode;
-use Cognesy\AgentCtrl\Common\Enum\SandboxDriver;
+use Cognesy\Sandbox\Enums\SandboxDriver;
 use Cognesy\AgentCtrl\Common\Execution\SandboxCommandExecutor;
 use Cognesy\AgentCtrl\Common\Value\PathList;
 use Cognesy\AgentCtrl\Contract\AgentBridge;
diff --git a/packages/agent-ctrl/src/Bridge/CodexBridge.php b/packages/agent-ctrl/src/Bridge/CodexBridge.php
@@ -2,7 +2,7 @@
 
 namespace Cognesy\AgentCtrl\Bridge;
 
-use Cognesy\AgentCtrl\Common\Enum\SandboxDriver;
+use Cognesy\Sandbox\Enums\SandboxDriver;
 use Cognesy\AgentCtrl\Common\Execution\SandboxCommandExecutor;
 use Cognesy\AgentCtrl\Common\Value\PathList;
 use Cognesy\AgentCtrl\Contract\AgentBridge;
diff --git a/packages/agent-ctrl/src/Bridge/OpenCodeBridge.php b/packages/agent-ctrl/src/Bridge/OpenCodeBridge.php
@@ -2,7 +2,7 @@
 
 namespace Cognesy\AgentCtrl\Bridge;
 
-use Cognesy\AgentCtrl\Common\Enum\SandboxDriver;
+use Cognesy\Sandbox\Enums\SandboxDriver;
 use Cognesy\AgentCtrl\Common\Execution\SandboxCommandExecutor;
 use Cognesy\AgentCtrl\Contract\AgentBridge;
 use Cognesy\AgentCtrl\Contract\StreamHandler;
diff --git a/packages/agent-ctrl/src/Builder/AbstractBridgeBuilder.php b/packages/agent-ctrl/src/Builder/AbstractBridgeBuilder.php
@@ -2,7 +2,7 @@
 
 namespace Cognesy\AgentCtrl\Builder;
 
-use Cognesy\AgentCtrl\Common\Enum\SandboxDriver;
+use Cognesy\Sandbox\Enums\SandboxDriver;
 use Cognesy\AgentCtrl\Contract\AgentBridge;
 use Cognesy\AgentCtrl\Contract\AgentBridgeBuilder;
 use Cognesy\AgentCtrl\Contract\StreamHandler;
diff --git a/packages/agent-ctrl/src/ClaudeCode/Application/Builder/ClaudeCommandBuilder.php b/packages/agent-ctrl/src/ClaudeCode/Application/Builder/ClaudeCommandBuilder.php
@@ -6,8 +6,8 @@
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Enum\InputFormat;
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Enum\OutputFormat;
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Enum\PermissionMode;
-use Cognesy\AgentCtrl\Common\Value\Argv;
-use Cognesy\AgentCtrl\Common\Value\CommandSpec;
+use Cognesy\Sandbox\Value\Argv;
+use Cognesy\Sandbox\Value\CommandSpec;
 use Cognesy\Sandbox\Utils\ProcUtils;
 
 final class ClaudeCommandBuilder
diff --git a/packages/agent-ctrl/src/Common/Contract/CommandExecutor.php b/packages/agent-ctrl/src/Common/Contract/CommandExecutor.php
@@ -3,7 +3,7 @@
 namespace Cognesy\AgentCtrl\Common\Contract;
 
 use Cognesy\AgentCtrl\Common\Execution\ExecutionPolicy;
-use Cognesy\AgentCtrl\Common\Value\CommandSpec;
+use Cognesy\Sandbox\Value\CommandSpec;
 use Cognesy\Sandbox\Data\ExecResult;
 
 interface CommandExecutor
diff --git a/packages/agent-ctrl/src/Common/Execution/SandboxCommandExecutor.php b/packages/agent-ctrl/src/Common/Execution/SandboxCommandExecutor.php
@@ -3,8 +3,8 @@
 namespace Cognesy\AgentCtrl\Common\Execution;
 
 use Cognesy\AgentCtrl\Common\Contract\CommandExecutor;
-use Cognesy\AgentCtrl\Common\Enum\SandboxDriver;
-use Cognesy\AgentCtrl\Common\Value\CommandSpec;
+use Cognesy\Sandbox\Enums\SandboxDriver;
+use Cognesy\Sandbox\Value\CommandSpec;
 use Cognesy\AgentCtrl\Enum\AgentType;
 use Cognesy\AgentCtrl\Event\ExecutionAttempted;
 use Cognesy\AgentCtrl\Event\ProcessExecutionCompleted;
diff --git a/packages/agent-ctrl/src/Contract/AgentBridgeBuilder.php b/packages/agent-ctrl/src/Contract/AgentBridgeBuilder.php
@@ -2,7 +2,7 @@
 
 namespace Cognesy\AgentCtrl\Contract;
 
-use Cognesy\AgentCtrl\Common\Enum\SandboxDriver;
+use Cognesy\Sandbox\Enums\SandboxDriver;
 use Cognesy\AgentCtrl\Dto\AgentResponse;
 
 /**
diff --git a/packages/agent-ctrl/src/OpenAICodex/Application/Builder/CodexCommandBuilder.php b/packages/agent-ctrl/src/OpenAICodex/Application/Builder/CodexCommandBuilder.php
@@ -2,8 +2,8 @@
 
 namespace Cognesy\AgentCtrl\OpenAICodex\Application\Builder;
 
-use Cognesy\AgentCtrl\Common\Value\Argv;
-use Cognesy\AgentCtrl\Common\Value\CommandSpec;
+use Cognesy\Sandbox\Value\Argv;
+use Cognesy\Sandbox\Value\CommandSpec;
 use Cognesy\AgentCtrl\OpenAICodex\Application\Dto\CodexRequest;
 use Cognesy\AgentCtrl\OpenAICodex\Domain\Enum\OutputFormat;
 use Cognesy\AgentCtrl\OpenAICodex\Domain\Enum\SandboxMode;
diff --git a/packages/agent-ctrl/src/OpenCode/Application/Builder/OpenCodeCommandBuilder.php b/packages/agent-ctrl/src/OpenCode/Application/Builder/OpenCodeCommandBuilder.php
@@ -2,8 +2,8 @@
 
 namespace Cognesy\AgentCtrl\OpenCode\Application\Builder;
 
-use Cognesy\AgentCtrl\Common\Value\Argv;
-use Cognesy\AgentCtrl\Common\Value\CommandSpec;
+use Cognesy\Sandbox\Value\Argv;
+use Cognesy\Sandbox\Value\CommandSpec;
 use Cognesy\AgentCtrl\OpenCode\Application\Dto\OpenCodeRequest;
 use Cognesy\AgentCtrl\OpenCode\Domain\Enum\OutputFormat;
 use Cognesy\Sandbox\Utils\ProcUtils;
diff --git a/packages/agent-ctrl/tests/Unit/Common/SandboxCommandExecutorMissingCommandTest.php b/packages/agent-ctrl/tests/Unit/Common/SandboxCommandExecutorMissingCommandTest.php
@@ -1,8 +1,8 @@
 <?php declare(strict_types=1);
 
 use Cognesy\AgentCtrl\Common\Execution\SandboxCommandExecutor;
-use Cognesy\AgentCtrl\Common\Value\Argv;
-use Cognesy\AgentCtrl\Common\Value\CommandSpec;
+use Cognesy\Sandbox\Value\Argv;
+use Cognesy\Sandbox\Value\CommandSpec;
 
 it('reports non-zero exit code for missing commands', function () {
     $executor = SandboxCommandExecutor::default();
diff --git a/packages/auxiliary/tests/Integration/ClaudeCodeCli/ClaudeCodeCliIntegrationTest.php b/packages/auxiliary/tests/Integration/ClaudeCodeCli/ClaudeCodeCliIntegrationTest.php
@@ -25,7 +25,7 @@
     $executor = new class implements CommandExecutor {
         public array $capturedArgv = [];
 
-        public function execute(\Cognesy\AgentCtrl\Common\Value\CommandSpec $command): ExecResult {
+        public function execute(\Cognesy\Sandbox\Value\CommandSpec $command): ExecResult {
             $this->capturedArgv = $command->argv()->toArray();
             $payload = '{"type":"result","result":"ok","session_id":"abc","total_cost_usd":0.001}';
             return new ExecResult($payload, '', 0, 0.01);
diff --git a/packages/hub/examples/D02_AgentCtrl/ClaudeCodeSearch/run.php b/packages/hub/examples/D02_AgentCtrl/ClaudeCodeSearch/run.php
@@ -31,7 +31,7 @@
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Enum\OutputFormat;
 use Cognesy\AgentCtrl\ClaudeCode\Domain\Enum\PermissionMode;
 use Cognesy\AgentCtrl\Common\Execution\SandboxCommandExecutor;
-use Cognesy\AgentCtrl\Common\Enum\SandboxDriver;
+use Cognesy\Sandbox\Enums\SandboxDriver;
 use Cognesy\AgentCtrl\Common\Execution\ExecutionPolicy;
 
 // Ensure we're running from monorepo root
diff --git a/packages/laravel/src/Facades/AgentCtrl.php b/packages/laravel/src/Facades/AgentCtrl.php
@@ -125,7 +125,7 @@ protected static function applyLaravelDefaults(
 
         // Apply sandbox driver if configured
         if ($sandbox = $config['sandbox'] ?? config('instructor.agents.sandbox')) {
-            $sandboxDriver = \Cognesy\AgentCtrl\Common\Enum\SandboxDriver::from($sandbox);
+            $sandboxDriver = \Cognesy\Sandbox\Enums\SandboxDriver::from($sandbox);
             $builder->withSandboxDriver($sandboxDriver);
         }
 
diff --git a/packages/sandbox/src/Enums/SandboxDriver.php b/packages/sandbox/src/Enums/SandboxDriver.php
@@ -0,0 +1,12 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\Sandbox\Enums;
+
+enum SandboxDriver: string
+{
+    case Host = 'host';
+    case Docker = 'docker';
+    case Podman = 'podman';
+    case Firejail = 'firejail';
+    case Bubblewrap = 'bubblewrap';
+}
diff --git a/packages/sandbox/src/Value/Argv.php b/packages/sandbox/src/Value/Argv.php
@@ -0,0 +1,36 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\Sandbox\Value;
+
+final readonly class Argv
+{
+    /** @var list<string> */
+    private array $items;
+
+    /**
+     * @param list<string> $items
+     */
+    private function __construct(array $items) {
+        $this->items = array_values($items);
+    }
+
+    /**
+     * @param list<string> $items
+     */
+    public static function of(array $items) : self {
+        return new self($items);
+    }
+
+    public function with(string $value) : self {
+        $items = $this->items;
+        $items[] = $value;
+        return new self($items);
+    }
+
+    /**
+     * @return list<string>
+     */
+    public function toArray() : array {
+        return $this->items;
+    }
+}
diff --git a/packages/sandbox/src/Value/CommandSpec.php b/packages/sandbox/src/Value/CommandSpec.php
@@ -0,0 +1,22 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\Sandbox\Value;
+
+final readonly class CommandSpec
+{
+    private Argv $argv;
+    private ?string $stdin;
+
+    public function __construct(Argv $argv, ?string $stdin = null) {
+        $this->argv = $argv;
+        $this->stdin = $stdin;
+    }
+
+    public function argv() : Argv {
+        return $this->argv;
+    }
+
+    public function stdin() : ?string {
+        return $this->stdin;
+    }
+}
