skimpyclaw 0.3.6 → 0.3.9

package/README.md

@@ -21,7 +21,7 @@ Use SkimpyClaw if you live in Telegram or Discord, want to read and own every li
 - **Chat interface** — Telegram and Discord bots with persistent conversation history
 - **Tool-enabled agent** — file read/write, bash, browser (Playwright), MCP tools via mcporter
 - **Multi-modal support** — voice messages (STT/TTS), image analysis
-- **Subagents** — model autonomously spawns coding/research subagents with retry + concurrency control
+- **Coding agents** — delegate to Claude Code / Codex CLI; `code_with_team` for parallel multi-agent work
 - **Code agents** — delegate coding tasks to Claude Code, Codex, or Kimi CLI with `code_with_agent` and `code_with_team`
 - **Cron scheduler** — run agent prompts or shell scripts on a schedule
 - **Web dashboard** — Preact/Vite SPA with status, cron, audit log, memory, templates, config editor, skills, approvals
@@ -49,7 +49,7 @@ flowchart LR
 
   subgraph Core
     agent["Agent Runtime"]
-    subagents["Subagent Pool"]
+    codeAgents["Coding Agents"]
     cron["Cron"]
     hb["Heartbeat"]
     audit["Audit Log"]
@@ -61,7 +61,7 @@ flowchart LR
   browser --> dash --> api --> agent
   cron --> agent
   hb --> agent
-  agent --> subagents
+  agent --> codeAgents
   agent --> audit
   agent --> skills
   agent --> approvals
@@ -85,6 +85,16 @@ Onboarding validates your Telegram token, provider auth, and creates:
 - `~/.skimpyclaw/config.json`
 - `~/.skimpyclaw/agents/main/*.md` (from templates)
 
+**Sandbox setup (optional — isolates Bash commands in a container):**
+
+```bash
+skimpyclaw sandbox init              # detect runtime, build image, update config
+skimpyclaw sandbox doctor            # verify everything works
+skimpyclaw restart                   # pick up sandbox config
+```
+
+Requires Apple Containers (macOS 26+) or Docker. See [docs/guide/sandbox.md](docs/guide/sandbox.md) for options.
+
 **Stop/Restart daemon (macOS):**
 
 ```bash
@@ -136,8 +146,7 @@ src/
   providers/            # Provider routing + provider implementations (anthropic/openai/codex)
   code-agents/          # Background coding-agent runtime (executor/parser/orchestrator/registry)
   channels/             # Channel adapters/utilities (telegram/discord)
-  subagent.ts           # Background task dispatch: retry, concurrency, disk registry
-  file-lock.ts          # In-memory file lock for concurrent subagent writes
+  file-lock.ts          # In-memory file lock for concurrent writes
   audit.ts              # Append-only audit log (trace/event model, JSONL storage)
   cron.ts               # Job scheduling + execution + cron logging
   heartbeat.ts          # Periodic health/attention checks
@@ -196,7 +205,6 @@ dist/                   # Compiled output + built dashboard assets
 | [docs/architecture.md](docs/architecture.md)   | Component diagram, runtime flow, startup sequence, source layout |
 | [docs/configuration.md](docs/configuration.md) | Full config reference, all sections with examples                |
 | [docs/tools.md](docs/tools.md)                 | Built-in tools, browser tool, MCP integration, code agents       |
-| [docs/subagents.md](docs/subagents.md)         | Subagent types, concurrency, file locking, flow diagram          |
 | [docs/dashboard.md](docs/dashboard.md)         | Web dashboard, all HTTP endpoints + API routes                   |
 | [docs/coding-agents.md](docs/coding-agents.md) | Coding-agent execution model and CLI backends                    |
 | [docs/cli.md](docs/cli.md)                     | CLI commands, service management                                 |

package/dist/__tests__/api.test.js

@@ -116,6 +116,7 @@ vi.mock('../config.js', () => ({
     getSessionsDir: () => SESSIONS_DIR,
     getLogsDir: () => LOGS_DIR,
     getAgentDir: (agentId) => join(TEST_ROOT, 'agents', agentId),
+    isValidAgentId: (agentId) => /^[a-zA-Z0-9_-]+$/.test(agentId),
     listMemoryFiles: (agentId) => {
         const { existsSync, readdirSync, statSync } = require('fs');
         const memDir = join(TEST_ROOT, 'agents', agentId, 'memory', 'logs');

package/dist/__tests__/channels.test.js

@@ -17,7 +17,7 @@ const discordMock = vi.hoisted(() => ({
     sendDiscordProactiveVoice: vi.fn(async () => { }),
     getDiscordDefaultTarget: vi.fn(() => '999'),
 }));
-vi.mock('../telegram.js', () => telegramMock);
+vi.mock('../channels/telegram/index.js', () => telegramMock);
 vi.mock('../discord.js', () => discordMock);
 import { getActiveChannelId, initActiveChannel, sendActiveChannelProactiveMessage, } from '../channels.js';
 function makeConfig(overrides = {}) {

package/dist/__tests__/code-agents-orchestrator.test.js

@@ -33,7 +33,7 @@ vi.mock('../audit.js', () => ({
     addEvent: vi.fn(),
     endTrace: vi.fn(async () => { }),
 }));
-import { computeWaves, decomposeTask, synthesizeResults } from '../code-agents/orchestrator.js';
+import { computeWaves, decomposeTask, synthesizeResults, gatherCodebaseContext } from '../code-agents/orchestrator.js';
 import { runAgentTurn } from '../agent.js';
 import { getCodeAgent, writeCodeAgentTask } from '../code-agents/registry.js';
 const mockRunAgentTurn = vi.mocked(runAgentTurn);
@@ -98,19 +98,20 @@ describe('decomposeTask', () => {
     });
 });
 describe('synthesizeResults', () => {
-    it('truncates child output to 300 chars', async () => {
+    it('uses structured context (summary capped at 500 chars, not raw 1000)', async () => {
         const longOutput = 'x'.repeat(1000);
         mockRunAgentTurn.mockResolvedValueOnce('Synthesis complete');
         const config = { providers: {} };
         await synthesizeResults('original task', [
             { subtask: 'sub1', status: 'completed', output: longOutput },
         ], config);
-        // The prompt sent to runAgentTurn should contain truncated output
         const call = mockRunAgentTurn.mock.calls[mockRunAgentTurn.mock.calls.length - 1];
         const prompt = call[1];
-        // Output should be sliced to 300, not 1000
-        expect(prompt).toContain('Output: ' + 'x'.repeat(300));
-        expect(prompt).not.toContain('x'.repeat(301));
+        // Summary should be capped at 500 chars, not the full 1000
+        expect(prompt).toContain('x'.repeat(500));
+        expect(prompt).not.toContain('x'.repeat(501));
+        // Should use the structured format (Summary: prefix)
+        expect(prompt).toContain('Summary:');
     });
 });
 describe('orchestrator - cancellation after wave spawn', () => {
@@ -134,7 +135,7 @@ describe('orchestrator - spawn failure marks child as failed', () => {
         expect(src).toContain("const child = getCodeAgent(childId);");
         expect(src).toContain("if (child && child.status === 'running')");
         expect(src).toContain("status: 'failed'");
-        expect(src).toContain("error: err instanceof Error ? err.message : String(err)");
+        expect(src).toContain("error: toErrorMessage(err)");
     });
 });
 describe('orchestrator - skip redundant parent writes', () => {
@@ -147,3 +148,69 @@ describe('orchestrator - skip redundant parent writes', () => {
         expect(src).toContain('lastLiveOutput = newLiveOutput');
     });
 });
+describe('gatherCodebaseContext', () => {
+    it('returns a non-empty string for the project root', () => {
+        // Use this project's own root as the workdir
+        const { resolve } = require('path');
+        const projectRoot = resolve(__dirname, '..', '..');
+        const context = gatherCodebaseContext(projectRoot);
+        // Should contain at least scripts or source files
+        expect(context.length).toBeGreaterThan(0);
+        expect(context.length).toBeLessThanOrEqual(2000);
+    });
+    it('returns empty string for nonexistent directory', () => {
+        const context = gatherCodebaseContext('/tmp/nonexistent-dir-12345');
+        // Should not throw, just return empty or minimal context
+        expect(typeof context).toBe('string');
+    });
+});
+describe('decomposeTask with workdir', () => {
+    it('passes workdir context to the decomposition prompt', async () => {
+        mockRunAgentTurn.mockResolvedValueOnce('{"subtasks": [{"description": "sub1", "dependsOn": []}, {"description": "sub2", "dependsOn": []}]}');
+        const config = { providers: {} };
+        const result = await decomposeTask('test task', 2, config, '/tmp');
+        expect(result).toHaveLength(2);
+        // Check the prompt sent to the model includes the richer decomposition instructions
+        const call = mockRunAgentTurn.mock.calls[mockRunAgentTurn.mock.calls.length - 1];
+        const prompt = call[1];
+        expect(prompt).toContain('task decomposition expert');
+        expect(prompt).toContain('git worktree');
+    });
+});
+describe('synthesizeResults with workdir', () => {
+    it('includes git diff info when workdir is a git repo', async () => {
+        mockRunAgentTurn.mockResolvedValueOnce('Synthesis complete');
+        const { resolve } = require('path');
+        const projectRoot = resolve(__dirname, '..', '..');
+        const config = { providers: {} };
+        await synthesizeResults('original task', [
+            { subtask: 'sub1', status: 'completed', output: 'done' },
+        ], config, projectRoot);
+        const call = mockRunAgentTurn.mock.calls[mockRunAgentTurn.mock.calls.length - 1];
+        const prompt = call[1];
+        // Should include the success/failure counts
+        expect(prompt).toContain('1 succeeded, 0 failed');
+    });
+});
+describe('orchestrator - per-wave validation and retry', () => {
+    it('source includes per-wave validation logic', async () => {
+        const { readFileSync } = await vi.importActual('fs');
+        const src = readFileSync(new URL('../../src/code-agents/orchestrator.ts', import.meta.url).pathname.replace('/.worktrees/hardening-code-agents/src/__tests__/../../', '/.worktrees/hardening-code-agents/'), 'utf-8');
+        // Verify per-wave validation exists
+        expect(src).toContain('Per-wave validation: run build after each wave');
+        expect(src).toContain('wave_validation');
+        // Verify retry logic
+        expect(src).toContain('wave_retry_complete');
+        expect(src).toContain('retryPrompt');
+    });
+});
+describe('orchestrator - timeout budgeting', () => {
+    it('computes perChildTimeout based on wave count not team size', async () => {
+        const { readFileSync } = await vi.importActual('fs');
+        const src = readFileSync(new URL('../../src/code-agents/orchestrator.ts', import.meta.url).pathname.replace('/.worktrees/hardening-code-agents/src/__tests__/../../', '/.worktrees/hardening-code-agents/'), 'utf-8');
+        // Verify budget-aware timeout
+        expect(src).toContain('overheadMinutes');
+        expect(src).toContain('availableForChildren');
+        expect(src).toContain('Math.floor(availableForChildren / waves.length)');
+    });
+});

package/dist/__tests__/code-agents-preflight.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/code-agents-preflight.test.js

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+const PRECHECK_ERROR = 'Error: No supported coding CLI found on PATH. Install Codex CLI (`codex`), Claude Code CLI (`claude` or `claude-code`), or Kimi CLI (`kimi`).';
+const toolConfig = {
+    enabled: true,
+    allowedPaths: [process.cwd()],
+    maxIterations: 5,
+    bashTimeout: 5000,
+};
+async function loadSubject(preflightError) {
+    vi.resetModules();
+    const runCodeAgentBackground = vi.fn().mockResolvedValue(undefined);
+    const runTeamOrchestrator = vi.fn().mockResolvedValue(undefined);
+    vi.doMock('../code-agents/utils.js', async () => {
+        const actual = await vi.importActual('../code-agents/utils.js');
+        return {
+            ...actual,
+            getCodingCliPreflightError: () => preflightError,
+        };
+    });
+    vi.doMock('../code-agents/executor.js', () => ({
+        runCodeAgentBackground,
+        runValidation: vi.fn(),
+        buildValidationCommand: vi.fn(() => 'pnpm build && pnpm test'),
+    }));
+    vi.doMock('../code-agents/orchestrator.js', () => ({
+        runTeamOrchestrator,
+        computeWaves: vi.fn(),
+        decomposeTask: vi.fn(),
+        synthesizeResults: vi.fn(),
+        gatherCodebaseContext: vi.fn(),
+    }));
+    vi.doMock('../code-agents/registry.js', () => ({
+        getNextCodeAgentId: vi.fn(() => 'ca_test_1'),
+        storeCodeAgentTask: vi.fn(),
+        writeCodeAgentTask: vi.fn(),
+        getActiveCodeAgents: vi.fn(() => []),
+        getRecentCodeAgents: vi.fn(() => []),
+        getAllCodeAgents: vi.fn(() => []),
+        getCodeAgent: vi.fn(() => null),
+        cancelCodeAgent: vi.fn(),
+        restoreCodeAgentTasks: vi.fn(),
+        getCodeAgentsDir: vi.fn(() => process.cwd()),
+    }));
+    const subject = await import('../code-agents/index.js');
+    return { ...subject, runCodeAgentBackground, runTeamOrchestrator };
+}
+afterEach(() => {
+    vi.doUnmock('../code-agents/utils.js');
+    vi.doUnmock('../code-agents/executor.js');
+    vi.doUnmock('../code-agents/orchestrator.js');
+    vi.doUnmock('../code-agents/registry.js');
+    vi.clearAllMocks();
+    vi.resetModules();
+});
+describe('coding CLI preflight guard', () => {
+    it('fails code_with_agent before spawning when no supported CLI is available', async () => {
+        const { executeCodeWithAgent, runCodeAgentBackground } = await loadSubject(PRECHECK_ERROR);
+        const result = await executeCodeWithAgent({ task: 'Fix bug', workdir: process.cwd() }, toolConfig, {
+            fullConfig: { codeAgents: { maxConcurrent: 99 } },
+        });
+        expect(result).toBe(PRECHECK_ERROR);
+        expect(runCodeAgentBackground).not.toHaveBeenCalled();
+    });
+    it('fails code_with_team before spawning when no supported CLI is available', async () => {
+        const { executeCodeWithTeam, runTeamOrchestrator } = await loadSubject(PRECHECK_ERROR);
+        const result = await executeCodeWithTeam({ task: 'Refactor auth', workdir: process.cwd() }, toolConfig, {
+            fullConfig: { codeAgents: { maxConcurrent: 99 } },
+        });
+        expect(result).toBe(PRECHECK_ERROR);
+        expect(runTeamOrchestrator).not.toHaveBeenCalled();
+    });
+    it('allows code_with_agent when at least one supported CLI exists', async () => {
+        const { executeCodeWithAgent, runCodeAgentBackground } = await loadSubject(null);
+        const result = await executeCodeWithAgent({ task: 'Fix bug', workdir: process.cwd() }, toolConfig, {
+            fullConfig: { codeAgents: { maxConcurrent: 99 } },
+        });
+        expect(result).toContain('Started coding agent');
+        expect(runCodeAgentBackground).toHaveBeenCalledTimes(1);
+    });
+    it('allows code_with_team when at least one supported CLI exists', async () => {
+        const { executeCodeWithTeam, runTeamOrchestrator } = await loadSubject(null);
+        const result = await executeCodeWithTeam({ task: 'Refactor auth', workdir: process.cwd() }, toolConfig, {
+            fullConfig: { codeAgents: { maxConcurrent: 99 } },
+        });
+        expect(result).toContain('Started coding team');
+        expect(runTeamOrchestrator).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/__tests__/code-agents-sandbox.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/code-agents-sandbox.test.js

@@ -0,0 +1,163 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+// Mock heavy dependencies before importing
+vi.mock('../code-agents/registry.js', () => {
+    const tasks = new Map();
+    return {
+        getCodeAgentsDir: () => '/tmp/test-code-agents',
+        ensureCodeAgentsDir: vi.fn(),
+        writeCodeAgentTask: vi.fn((task) => tasks.set(task.id, { ...task })),
+        storeCodeAgentTask: vi.fn((task) => tasks.set(task.id, { ...task })),
+        getCodeAgent: vi.fn((id) => tasks.get(id) || null),
+        setCodeAgentCanceller: vi.fn(),
+        deleteCodeAgentCanceller: vi.fn(),
+        getNextCodeAgentId: vi.fn(() => 'ca-test-1'),
+        getActiveCodeAgents: vi.fn(() => []),
+        getRecentCodeAgents: vi.fn(() => []),
+        _tasks: tasks,
+    };
+});
+vi.mock('../code-agents/parser.js', () => ({
+    parseStreamJsonForLive: vi.fn((s) => s.slice(0, 200)),
+    parseClaudeOutput: vi.fn((s) => ({ text: s, totalCost: 0, inputTokens: 0, outputTokens: 0 })),
+    parseCodexOutput: vi.fn((s) => s),
+}));
+vi.mock('../code-agents/utils.js', () => ({
+    buildCodeAgentArgs: vi.fn(() => ({ cmd: 'echo', args: ['hello'] })),
+    notifyCodeAgentResult: vi.fn(async () => { }),
+    resolveModelAlias: vi.fn((m) => m || 'claude'),
+    resolveSelectedCodeAgent: vi.fn((_req, def) => def || 'claude'),
+    resolveWorkdir: vi.fn((_raw, _proj, root) => root),
+}));
+vi.mock('../audit.js', () => ({
+    startTrace: vi.fn(() => 'trace-1'),
+    addEvent: vi.fn(),
+    endTrace: vi.fn(async () => { }),
+}));
+vi.mock('../usage.js', () => ({
+    buildUsageRecord: vi.fn(() => ({})),
+    recordUsage: vi.fn(),
+}));
+vi.mock('fs', async () => {
+    const actual = await vi.importActual('fs');
+    return {
+        ...actual,
+        createWriteStream: vi.fn(() => ({
+            write: vi.fn(),
+            end: vi.fn(),
+        })),
+        existsSync: vi.fn(() => false),
+    };
+});
+vi.mock('../sandbox/index.js', () => ({
+    ensureContainer: vi.fn(async () => 'sandbox-code-test'),
+    SANDBOX_DEFAULTS: { image: 'skimpyclaw-sandbox:latest', runtime: 'docker' },
+    getRuntime: vi.fn(() => 'docker'),
+    execInContainer: vi.fn(async () => ({ exitCode: 0, stdout: 'PASS', stderr: '' })),
+}));
+describe('buildContainerEnvArgs', () => {
+    it('returns -e flags for allowlisted env vars that exist', async () => {
+        const { buildContainerEnvArgs } = await import('../code-agents/executor.js');
+        const env = {
+            ANTHROPIC_API_KEY: 'sk-test-123',
+            GH_TOKEN: 'ghp_abc',
+            HOME: '/home/sandbox',
+            SOME_OTHER_VAR: 'should-not-appear',
+            PATH: '/usr/bin:/usr/local/bin',
+        };
+        const result = buildContainerEnvArgs(env);
+        expect(result).toContain('-e');
+        expect(result).toContain('ANTHROPIC_API_KEY=sk-test-123');
+        expect(result).toContain('GH_TOKEN=ghp_abc');
+        expect(result).toContain('HOME=/home/sandbox');
+        expect(result).toContain('PATH=/usr/bin:/usr/local/bin');
+        // Non-allowlisted vars should not appear
+        expect(result.join(' ')).not.toContain('SOME_OTHER_VAR');
+    });
+    it('excludes empty and undefined values', async () => {
+        const { buildContainerEnvArgs } = await import('../code-agents/executor.js');
+        const env = {
+            ANTHROPIC_API_KEY: '',
+            GH_TOKEN: undefined,
+            GITHUB_TOKEN: 'ghp_123',
+        };
+        const result = buildContainerEnvArgs(env);
+        expect(result).toContain('GITHUB_TOKEN=ghp_123');
+        // No git signing key passed, so no GIT_CONFIG overrides
+        expect(result.join(' ')).not.toContain('GIT_CONFIG');
+    });
+    it('includes git signing config overrides when gitSigningKey is provided', async () => {
+        const { buildContainerEnvArgs } = await import('../code-agents/executor.js');
+        const result = buildContainerEnvArgs({ ANTHROPIC_API_KEY: 'sk-test' }, { gitSigningKey: '/home/sandbox/.ssh/git_signing_ed25519' });
+        expect(result).toContain('GIT_CONFIG_COUNT=1');
+        expect(result).toContain('GIT_CONFIG_KEY_0=user.signingkey');
+        expect(result).toContain('GIT_CONFIG_VALUE_0=/home/sandbox/.ssh/git_signing_ed25519');
+    });
+    it('omits git signing config when gitSigningKey is not provided', async () => {
+        const { buildContainerEnvArgs } = await import('../code-agents/executor.js');
+        const result = buildContainerEnvArgs({ FOO: 'bar', BAZ: 'qux' });
+        expect(result).not.toContain('FOO=bar');
+        expect(result.join(' ')).not.toContain('GIT_CONFIG');
+        expect(result).toEqual([]);
+    });
+});
+describe('runValidation with sandbox', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('uses execInContainer when sandboxContainer is provided', async () => {
+        const { execInContainer } = await import('../sandbox/index.js');
+        const { runValidation } = await import('../code-agents/executor.js');
+        const result = await runValidation('/workspace', 'sandbox-test');
+        expect(execInContainer).toHaveBeenCalledWith('sandbox-test', expect.any(Array), expect.objectContaining({ timeout: expect.any(Number) }));
+        expect(result.passed).toBe(true);
+        expect(result.output).toBe('PASS');
+    });
+    it('returns failure when execInContainer returns non-zero exit', async () => {
+        const { execInContainer } = await import('../sandbox/index.js');
+        vi.mocked(execInContainer).mockResolvedValueOnce({
+            exitCode: 1,
+            stdout: 'Error: test failed',
+            stderr: 'FAIL',
+        });
+        const { runValidation } = await import('../code-agents/executor.js');
+        const result = await runValidation('/workspace', 'sandbox-fail');
+        expect(result.passed).toBe(false);
+        expect(result.output).toContain('VALIDATION FAILED');
+    });
+    it('returns failure when execInContainer throws', async () => {
+        const { execInContainer } = await import('../sandbox/index.js');
+        vi.mocked(execInContainer).mockRejectedValueOnce(new Error('container not found'));
+        const { runValidation } = await import('../code-agents/executor.js');
+        const result = await runValidation('/workspace', 'sandbox-crash');
+        expect(result.passed).toBe(false);
+        expect(result.output).toContain('sandbox exec error');
+        expect(result.output).toContain('container not found');
+    });
+});
+describe('sandbox config resolution in executeCodeWithAgent', () => {
+    it('resolves sandboxConfig from context.sandboxConfig', async () => {
+        // Test the resolution logic directly — the config should be picked up
+        // from context.sandboxConfig or context.fullConfig.sandbox
+        const contextWithSandbox = {
+            sandboxConfig: { enabled: true, image: 'test-image' },
+            fullConfig: { sandbox: { enabled: false } },
+        };
+        // sandboxConfig takes precedence over fullConfig.sandbox
+        const resolved = contextWithSandbox.sandboxConfig ?? contextWithSandbox.fullConfig?.sandbox;
+        expect(resolved).toEqual({ enabled: true, image: 'test-image' });
+    });
+    it('falls back to fullConfig.sandbox when context.sandboxConfig is absent', () => {
+        const contextFallback = {
+            fullConfig: { sandbox: { enabled: true, image: 'fallback-image' } },
+        };
+        const resolved = contextFallback.sandboxConfig ?? contextFallback.fullConfig?.sandbox;
+        expect(resolved).toEqual({ enabled: true, image: 'fallback-image' });
+    });
+    it('resolves to undefined when no sandbox config present', () => {
+        const contextNone = {
+            fullConfig: {},
+        };
+        const resolved = contextNone.sandboxConfig ?? contextNone.fullConfig?.sandbox;
+        expect(resolved).toBeUndefined();
+    });
+});

package/dist/__tests__/code-agents-utils.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { normalizeCodeAgent, resolveSelectedCodeAgent } from '../code-agents/utils.js';
+import { normalizeCodeAgent, resolveSelectedCodeAgent, getAvailableCodingCliTools, getCodingCliPreflightError, } from '../code-agents/utils.js';
 describe('normalizeCodeAgent', () => {
     it('accepts strict ids', () => {
         expect(normalizeCodeAgent('claude')).toBe('claude');
@@ -39,3 +39,14 @@ describe('resolveSelectedCodeAgent', () => {
         expect(resolveSelectedCodeAgent('claude', 'claude', 'gpt-4.1')).toBe('claude');
     });
 });
+describe('coding CLI preflight', () => {
+    it('returns a clear error when no supported CLI is found on PATH', () => {
+        expect(getAvailableCodingCliTools(() => false)).toEqual([]);
+        expect(getCodingCliPreflightError(() => false)).toBe('Error: No supported coding CLI found on PATH. Install Codex CLI (`codex`), Claude Code CLI (`claude` or `claude-code`), or Kimi CLI (`kimi`).');
+    });
+    it('accepts claude-code binary as claude support', () => {
+        const hasCommand = (name) => name === 'claude-code';
+        expect(getAvailableCodingCliTools(hasCommand)).toEqual(['claude']);
+        expect(getCodingCliPreflightError(hasCommand)).toBeNull();
+    });
+});

package/dist/__tests__/context-manager.test.d.ts

@@ -0,0 +1 @@
+export {};