@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/README.md

@@ -56,9 +56,9 @@ Once initialized, open the project in your AI TUI and install the latest skills:
 ```bash
 /import-issue 42           # AI reads the issue, creates a task, extracts requirements
 /analyze-task <task-id>    # AI scans the codebase, finds the root cause, writes analysis.md
-/review-analysis <task-id> # AI self-reviews: "Approved. 0 blockers — proceed to design."
+/review-analysis <task-id> # An isolated reviewer checks the analysis
 /plan-task <task-id>       # AI proposes a fix plan
-/review-plan <task-id>     # AI self-reviews the plan: "Approved. Ready for implementation."
+/review-plan <task-id>     # A fresh isolated reviewer checks the plan
 ```
 
 > **You review the plan and reply in natural language:**
@@ -72,7 +72,7 @@ Just fix it at the application layer in LoginService.
 
 ```bash
 /code-task <task-id>       # AI writes the fix, adds a test for user+tag@example.com — green
-/review-code <task-id>     # AI reviews its own code: "0 blockers, 1 minor (missing JSDoc)."
+/review-code <task-id>     # A fresh isolated reviewer reports one minor finding
 /code-task <task-id>       # AI fixes the minor issue and re-validates
 /commit
 /create-pr <task-id>       # PR opened, auto-linked to issue #42
@@ -141,7 +141,7 @@ ai init
 # or: agent-infra init
 ```
 
-The CLI collects project metadata, installs the `update-agent-infra` seed command for all supported AI TUIs, and generates `.agents/.airc.json`.
+The CLI collects project metadata, lets you select the enabled Agent Clients, installs their `update-agent-infra` seed commands, and generates `.agents/.airc.json`.
 
 > `ai` is a shorthand for `agent-infra`. Both commands are equivalent.
 
@@ -160,11 +160,22 @@ This detects the packaged template version and renders all managed files. The sa
 
 ## Core Commands
 
+Manage the four built-in Agent Clients independently from the project lifecycle:
+
+```bash
+ai agent-client list
+ai agent-client status
+ai agent-client enable codex
+ai agent-client disable gemini-cli
+ai agent-client configure
+```
+
 The most-used lifecycle commands, in delivery order. The command prefix varies by TUI (`/skill` in Claude Code/OpenCode, `$skill` in Codex, `/{{project}}:skill` in Gemini CLI); the workflow semantics stay the same.
 
 | Command | Purpose |
 |---------|---------|
 | `create-task` / `import-issue` | Start a task from a description or a GitHub Issue |
+| `run-task` | Resume and orchestrate the lifecycle in Claude Code with fresh isolated executors/reviewers until a safe commit or stable pause; Codex currently fails closed because its multi-agent runtime does not expose the required lifecycle events |
 | `analyze-task` → `review-analysis` | Capture scope and risks, then review the analysis |
 | `plan-task` → `review-plan` | Design the approach, then review the plan |
 | `code-task` → `review-code` | Implement and test, then run a structured code review |
@@ -197,6 +208,7 @@ In-depth guides live under [`docs/en/`](./docs/en/README.md):
 - [Architecture Overview](./docs/en/architecture.md) — bootstrap CLI, end-to-end flow, layered architecture
 - [Platform Support](./docs/en/platform-support.md) — macOS, Linux, Windows; sandbox engines and resources
 - [Sandbox](./docs/en/sandbox.md) — sandbox aliases, host-sandbox file exchange, user-level dotfiles channel
+- [Benchmark Contract and Threat Model](./docs/en/benchmark.md) — versioned benchmark schemas, trust boundaries, and security guarantees
 - [Feishu Bridge](./docs/en/feishu-bridge.md) — configure the Feishu long-connection adapter, command routing, permissions, and TUI selection
 - [Built-in AI Skills](./docs/en/skills.md) — the full skill catalog by use case
 - [Custom Skills](./docs/en/custom-skills.md) — create and sync project-specific skills

package/README.zh-CN.md

@@ -55,9 +55,9 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 ```bash
 /import-issue 42           # AI 读取 Issue，创建任务，提取需求
 /analyze-task <task-id>    # AI 扫描代码库，定位根因，输出 analysis.md
-/review-analysis <task-id> # AI 自审：“通过。0 阻塞项 —— 可进入方案设计。”
+/review-analysis <task-id> # 隔离 reviewer 审查分析产物
 /plan-task <task-id>       # AI 提出修复方案
-/review-plan <task-id>     # AI 自审方案：“通过，可进入编码。”
+/review-plan <task-id>     # fresh 隔离 reviewer 审查方案
 ```
 
 > **你审查方案后用自然语言回复：**
@@ -71,7 +71,7 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 
 ```bash
 /code-task <task-id>       # AI 编写修复代码，添加 user+tag@example.com 测试 —— 通过
-/review-code <task-id>     # AI 审查自己的实现：“0 阻塞项，1 次要（缺少 JSDoc）。”
+/review-code <task-id>     # fresh 隔离 reviewer 报告一个次要问题
 /code-task <task-id>       # AI 修复次要问题并重新验证
 /commit
 /create-pr <task-id>       # PR 已创建，自动关联 Issue #42
@@ -140,7 +140,7 @@ ai init
 # 或：agent-infra init
 ```
 
-CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-infra` 种子命令，并生成 `.agents/.airc.json`。
+CLI 会收集项目元数据，让你选择启用的 Agent Client，为其安装 `update-agent-infra` 种子命令，并生成 `.agents/.airc.json`。
 
 > `ai` 是 `agent-infra` 的简写命令，两者等价。
 
@@ -159,11 +159,22 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 
 ## 核心命令
 
+以下命令用于独立管理四个内建 Agent Client：
+
+```bash
+ai agent-client list
+ai agent-client status
+ai agent-client enable codex
+ai agent-client disable gemini-cli
+ai agent-client configure
+```
+
 最常用的生命周期命令，按交付顺序排列。命令前缀因 TUI 而异（Claude Code/OpenCode 用 `/skill`，Codex 用 `$skill`，Gemini CLI 用 `/{{project}}:skill`），工作流语义保持一致。
 
 | 命令 | 用途 |
 |------|------|
 | `create-task` / `import-issue` | 从描述或 GitHub Issue 创建任务 |
+| `run-task` | 在 Claude Code 中从当前状态续跑生命周期，用 fresh 隔离 executor/reviewer 推进到安全提交或稳定暂停；Codex 当前因多代理运行时未暴露所需生命周期事件而失败关闭 |
 | `analyze-task` → `review-analysis` | 明确范围与风险，再审查分析 |
 | `plan-task` → `review-plan` | 设计实现路径，再审查方案 |
 | `code-task` → `review-code` | 实现并测试，再执行结构化代码审查 |
@@ -196,6 +207,7 @@ my-project/
 - [架构概览](./docs/zh-CN/architecture.md) — 引导 CLI、端到端流程、分层架构
 - [平台支持](./docs/zh-CN/platform-support.md) — macOS、Linux、Windows；沙箱引擎与资源配置
 - [沙箱](./docs/zh-CN/sandbox.md) — 沙箱 aliases、宿主-沙箱文件交换、用户级 dotfiles 通道
+- [Benchmark 契约与威胁模型](./docs/zh-CN/benchmark.md) — 版本化 benchmark schema、信任边界与安全保证
 - [飞书桥接](./docs/zh-CN/feishu-bridge.md) — 配置飞书长连接 adapter、命令路由、权限和 TUI 选择
 - [内置 AI Skills](./docs/zh-CN/skills.md) — 按使用场景分组的完整 skill 清单
 - [自定义 Skills](./docs/zh-CN/custom-skills.md) — 创建并同步项目专属 skill

package/bin/cli.ts

@@ -15,6 +15,7 @@ const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructur
 Usage: ai <command> [options]
 
 Commands:
+  agent-client    List, inspect, enable, disable, or configure Agent Clients
   cp <ssh-alias>  Copy local clipboard image to a remote macOS clipboard or Linux sandbox over SSH
   decide          Record a ruling; code-stage decisions require explicit implementation intent
   help            Show this help message
@@ -71,6 +72,17 @@ async function importCommand(importPath: string) {
 }
 
 switch (command) {
+  case 'agent-client': {
+    const imported = await importCommand('../lib/agent-client.ts');
+    if (!imported) break;
+    const { cmdAgentClient } = imported;
+    const code = await cmdAgentClient(process.argv.slice(3)).catch((e: unknown) => {
+      process.stderr.write(`Error: ${errorMessage(e)}\n`);
+      return 1;
+    });
+    if (code) process.exitCode = code;
+    break;
+  }
   case 'cp': {
     const imported = await importCommand('../lib/cp.ts');
     if (!imported) break;

package/dist/bin/cli.js

@@ -19,6 +19,7 @@ const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructur
 Usage: ai <command> [options]
 
 Commands:
+  agent-client    List, inspect, enable, disable, or configure Agent Clients
   cp <ssh-alias>  Copy local clipboard image to a remote macOS clipboard or Linux sandbox over SSH
   decide          Record a ruling; code-stage decisions require explicit implementation intent
   help            Show this help message
@@ -69,6 +70,19 @@ async function importCommand(importPath) {
     }
 }
 switch (command) {
+    case 'agent-client': {
+        const imported = await importCommand('../lib/agent-client.ts');
+        if (!imported)
+            break;
+        const { cmdAgentClient } = imported;
+        const code = await cmdAgentClient(process.argv.slice(3)).catch((e) => {
+            process.stderr.write(`Error: ${errorMessage(e)}\n`);
+            return 1;
+        });
+        if (code)
+            process.exitCode = code;
+        break;
+    }
     case 'cp': {
         const imported = await importCommand('../lib/cp.ts');
         if (!imported)

package/dist/bin/internal-cli.js

@@ -6,6 +6,11 @@ if (major < 22 || (major === 22 && minor < 9)) {
 }
 const command = process.argv[2] || '';
 switch (command) {
+    case 'agent-client': {
+        const { agentClient } = await import('../lib/internal/agent-client.js');
+        agentClient(process.argv.slice(3));
+        break;
+    }
     case 'git-workflow': {
         const { gitWorkflow } = await import('../lib/internal/git-workflow.js');
         gitWorkflow(process.argv.slice(3));
@@ -66,6 +71,16 @@ switch (command) {
         taskArtifact(process.argv.slice(3));
         break;
     }
+    case 'task-orchestration': {
+        const { taskOrchestration } = await import('../lib/internal/task-orchestration.js');
+        taskOrchestration(process.argv.slice(3));
+        break;
+    }
+    case 'task-review': {
+        const { taskReview } = await import('../lib/internal/task-review.js');
+        taskReview(process.argv.slice(3));
+        break;
+    }
     case 'task-event': {
         const { taskEvent } = await import('../lib/internal/task-event.js');
         taskEvent(process.argv.slice(3));

package/dist/lib/agent-client.js

@@ -0,0 +1,163 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { AgentClientConfigError, normalizeAgentClients } from './agent-clients/config.js';
+import { applyAgentClientReconciliation, planAgentClientReconciliation } from './agent-clients/reconcile.js';
+import { listAgentClientAdapters } from './agent-clients/registry.js';
+import { AGENT_CLIENT_IDS, isAgentClientId } from './agent-clients/types.js';
+import { closePrompt, multiSelect } from './prompt.js';
+import { resolveTemplateDir } from './paths.js';
+const USAGE = `Usage: ai agent-client <operation>
+
+Operations:
+  list                 List built-in Agent Clients
+  status               Show project integration and sandbox state
+  enable <client-id>   Enable project integration only
+  disable <client-id>  Disable project integration only
+  configure            Configure integration and sandbox state interactively
+`;
+class AgentClientCommandError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = 'AgentClientCommandError';
+        this.code = code;
+    }
+}
+function readConfig(projectRoot) {
+    const configPath = path.join(projectRoot, '.agents', '.airc.json');
+    if (!fs.existsSync(configPath)) {
+        throw new AgentClientCommandError('AGENT_CLIENT_CONFIG_NOT_FOUND', 'No .agents/.airc.json found. Run "ai init" first.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch (error) {
+        throw new AgentClientCommandError('AGENT_CLIENT_CONFIG_INVALID', error instanceof Error ? error.message : String(error));
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new AgentClientCommandError('AGENT_CLIENT_CONFIG_INVALID', 'configuration root must be an object');
+    }
+    return parsed;
+}
+function choices() {
+    return listAgentClientAdapters().map((adapter) => ({
+        id: adapter.id,
+        label: adapter.displayName
+    }));
+}
+function selected(state, field) {
+    return AGENT_CLIENT_IDS.filter((id) => state[id][field]);
+}
+function workflowPlan(projectRoot, config, mutation) {
+    const templateRoot = resolveTemplateDir();
+    if (!templateRoot) {
+        throw new AgentClientCommandError('AGENT_CLIENT_TEMPLATE_NOT_FOUND', 'Template directory not found');
+    }
+    const platform = config.platform;
+    const platformType = typeof platform === 'object' && platform !== null && 'type' in platform
+        ? String(platform.type ?? 'github')
+        : 'github';
+    return planAgentClientReconciliation({
+        config,
+        mutation,
+        projectRoot,
+        templateRoot,
+        platformType,
+        language: String(config.language ?? 'en')
+    });
+}
+function printState(state) {
+    for (const adapter of listAgentClientAdapters()) {
+        const value = state[adapter.id];
+        process.stdout.write(`  ${adapter.id}: enabled=${String(value.enabled)} installInSandbox=${String(value.installInSandbox)}\n`);
+    }
+}
+async function cmdAgentClient(args) {
+    const operation = args[0];
+    if (!operation || operation === '--help' || operation === '-h' || operation === 'help') {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (operation === 'list') {
+        if (args.length !== 1) {
+            throw new AgentClientCommandError('AGENT_CLIENT_ARGUMENT_INVALID', 'list accepts no arguments');
+        }
+        for (const adapter of listAgentClientAdapters()) {
+            process.stdout.write(`${adapter.id}\t${adapter.displayName}\t${adapter.invocation}\tcommands=${adapter.capabilities.commands.level}\tsandbox=${adapter.capabilities.sandbox.level}\n`);
+        }
+        return 0;
+    }
+    const projectRoot = process.cwd();
+    const config = readConfig(projectRoot);
+    try {
+        if (operation === 'status') {
+            if (args.length !== 1) {
+                throw new AgentClientCommandError('AGENT_CLIENT_ARGUMENT_INVALID', 'status accepts no arguments');
+            }
+            const plan = workflowPlan(projectRoot, config, { type: 'none' });
+            process.stdout.write(`source: ${plan.source}\n`);
+            printState(plan.desired);
+            for (const seed of plan.seedOperations) {
+                process.stdout.write(`  seed ${seed.target}: ${seed.kind}\n`);
+            }
+            for (const diagnostic of plan.diagnostics) {
+                process.stdout.write(`  diagnostic ${diagnostic.code} at ${diagnostic.path}\n`);
+            }
+            return 0;
+        }
+        if (operation === 'enable' || operation === 'disable') {
+            if (args.length !== 2) {
+                throw new AgentClientCommandError('AGENT_CLIENT_ARGUMENT_INVALID', `${operation} requires exactly one client id`);
+            }
+            const id = args[1];
+            if (!isAgentClientId(id)) {
+                throw new AgentClientCommandError('UNKNOWN_AGENT_CLIENT', `Unknown Agent Client '${String(id)}'`);
+            }
+            const plan = workflowPlan(projectRoot, config, {
+                type: 'set-enabled',
+                id,
+                value: operation === 'enable'
+            });
+            process.stdout.write('Before:\n');
+            printState(plan.before);
+            const result = applyAgentClientReconciliation(plan);
+            process.stdout.write('After:\n');
+            printState(plan.desired);
+            process.stdout.write(`Result: ${result.status}; applied=${result.applied.length}; protected=${result.protected.length}\n`);
+            return 0;
+        }
+        if (operation === 'configure') {
+            if (args.length !== 1) {
+                throw new AgentClientCommandError('AGENT_CLIENT_ARGUMENT_INVALID', 'configure accepts no arguments');
+            }
+            const normalized = normalizeAgentClients(config);
+            let enabled;
+            let installed;
+            try {
+                enabled = await multiSelect('Agent Client project integrations', choices(), selected(normalized.state, 'enabled'));
+                installed = await multiSelect('Agent Clients installed in sandbox', choices(), selected(normalized.state, 'installInSandbox'));
+            }
+            finally {
+                closePrompt();
+            }
+            const state = Object.fromEntries(AGENT_CLIENT_IDS.map((id) => [id, {
+                    enabled: enabled.includes(id),
+                    installInSandbox: installed.includes(id)
+                }]));
+            const plan = workflowPlan(projectRoot, config, { type: 'replace-state', state });
+            const result = applyAgentClientReconciliation(plan);
+            process.stdout.write(`Result: ${result.status}; applied=${result.applied.length}; protected=${result.protected.length}\n`);
+            return 0;
+        }
+        throw new AgentClientCommandError('AGENT_CLIENT_OPERATION_INVALID', `Unknown operation '${operation}'`);
+    }
+    catch (error) {
+        if (error instanceof AgentClientConfigError) {
+            throw new AgentClientCommandError(error.code, error.message);
+        }
+        throw error;
+    }
+}
+export { AgentClientCommandError, cmdAgentClient };
+//# sourceMappingURL=agent-client.js.map

package/dist/lib/agent-clients/adapter.js

@@ -0,0 +1,294 @@
+import { AGENT_CLIENT_CAPABILITY_IDS, AGENT_CLIENT_SUPPORT_LEVELS, isAgentClientId } from './types.js';
+import { SANDBOX_HOOK_PHASES } from '../sandbox/tool-types.js';
+const PROJECT_ASSET_CATEGORIES = ['managed', 'merged', 'ejected'];
+const MAX_SANDBOX_HOOK_TIMEOUT_MS = 300_000;
+const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+function freezeRecoveryProbe(id, checkId, value) {
+    if (!value
+        || typeof value.script !== 'string'
+        || value.script.trim() === ''
+        || !Array.isArray(value.args)
+        || value.args.some((arg) => typeof arg !== 'string')
+        || (value.user !== undefined && (typeof value.user !== 'string' || value.user === ''))) {
+        throw new Error(`Agent Client '${id}' recovery check '${checkId}' has an invalid probe`);
+    }
+    return Object.freeze({
+        script: value.script,
+        args: Object.freeze([...value.args]),
+        ...(value.user === undefined ? {} : { user: value.user })
+    });
+}
+function freezeTool(tool) {
+    if (typeof tool.id !== 'string' || !TOOL_ID_PATTERN.test(tool.id)) {
+        throw new Error(`Invalid sandbox tool id: ${String(tool.id)}`);
+    }
+    if (!tool.install?.cmd || !['npm', 'shell'].includes(tool.install.type)) {
+        throw new Error(`Sandbox tool '${tool.id}' has invalid install`);
+    }
+    if (!tool.containerMount.startsWith('/')) {
+        throw new Error(`Sandbox tool '${tool.id}' containerMount must be absolute`);
+    }
+    if (!tool.versionCmd) {
+        throw new Error(`Sandbox tool '${tool.id}' requires versionCmd`);
+    }
+    return Object.freeze({
+        ...tool,
+        install: Object.freeze({ ...tool.install }),
+        ...(tool.envVars ? { envVars: Object.freeze({ ...tool.envVars }) } : {}),
+        ...(tool.hostPreSeedFiles ? {
+            hostPreSeedFiles: Object.freeze(tool.hostPreSeedFiles.map((entry) => Object.freeze({ ...entry })))
+        } : {}),
+        ...(tool.hostPreSeedDirs ? {
+            hostPreSeedDirs: Object.freeze(tool.hostPreSeedDirs.map((entry) => Object.freeze({ ...entry })))
+        } : {}),
+        ...(tool.pathRewriteFiles ? { pathRewriteFiles: Object.freeze([...tool.pathRewriteFiles]) } : {}),
+        ...(tool.hostLiveMounts ? {
+            hostLiveMounts: Object.freeze(tool.hostLiveMounts.map((entry) => Object.freeze({ ...entry })))
+        } : {}),
+        ...(tool.postSetupCmds ? { postSetupCmds: Object.freeze([...tool.postSetupCmds]) } : {}),
+        ...(tool.tmpfs ? {
+            tmpfs: Object.freeze({
+                ...tool.tmpfs,
+                ...(tool.tmpfs.seed ? { seed: Object.freeze([...tool.tmpfs.seed]) } : {})
+            })
+        } : {})
+    });
+}
+function freezeAliases(id, aliases) {
+    const names = new Set();
+    return Object.freeze(aliases.map((alias) => {
+        if (!alias.name || !alias.command || names.has(alias.name)) {
+            throw new Error(`Agent Client '${id}' has invalid or duplicate sandbox alias '${alias.name}'`);
+        }
+        names.add(alias.name);
+        return Object.freeze({ ...alias });
+    }));
+}
+function isProjectRelativeLiteral(value) {
+    if (value.length === 0
+        || value.startsWith('/')
+        || /^[a-zA-Z]:/.test(value)
+        || value.includes('\\')
+        || /[*?[\]{}]/.test(value)) {
+        return false;
+    }
+    return !value.split('/').some((segment) => segment === '..');
+}
+function defineAgentClientAdapter(candidate) {
+    if (!isAgentClientId(candidate.id)) {
+        throw new Error(`Unknown Agent Client ID '${String(candidate.id)}'`);
+    }
+    if (typeof candidate.displayName !== 'string' || candidate.displayName.trim() === '') {
+        throw new Error(`Agent Client '${candidate.id}' requires a display name`);
+    }
+    if (typeof candidate.invocation !== 'string'
+        || candidate.invocation.trim() === ''
+        || /[\r\n]/.test(candidate.invocation)) {
+        throw new Error(`Agent Client '${candidate.id}' requires a single-line invocation`);
+    }
+    const invocationPlaceholders = [
+        ...candidate.invocation.matchAll(/\$\{([^}]+)\}/g)
+    ].map((match) => match[1]);
+    if (!invocationPlaceholders.includes('skillName')
+        || invocationPlaceholders.some((placeholder) => placeholder !== 'skillName' && placeholder !== 'projectName')
+        || candidate.invocation
+            .replaceAll('${skillName}', '')
+            .replaceAll('${projectName}', '')
+            .includes('${')) {
+        throw new Error(`Agent Client '${candidate.id}' has an invalid invocation`);
+    }
+    if (typeof candidate.capabilities !== 'object'
+        || candidate.capabilities === null
+        || Array.isArray(candidate.capabilities)) {
+        throw new Error(`Agent Client '${candidate.id}' has an invalid capability map`);
+    }
+    const capabilityKeys = Object.keys(candidate.capabilities);
+    if (capabilityKeys.length !== AGENT_CLIENT_CAPABILITY_IDS.length
+        || AGENT_CLIENT_CAPABILITY_IDS.some((capability) => !Object.prototype.hasOwnProperty.call(candidate.capabilities, capability))) {
+        throw new Error(`Agent Client '${candidate.id}' has an invalid capability map`);
+    }
+    const capabilities = Object.fromEntries(AGENT_CLIENT_CAPABILITY_IDS.map((capability) => {
+        const support = candidate.capabilities[capability];
+        if (typeof support !== 'object'
+            || support === null
+            || !AGENT_CLIENT_SUPPORT_LEVELS.includes(support.level)) {
+            throw new Error(`Agent Client '${candidate.id}' has invalid support for '${capability}'`);
+        }
+        return [capability, Object.freeze({ level: support.level })];
+    }));
+    if (typeof candidate.project !== 'object'
+        || candidate.project === null
+        || Array.isArray(candidate.project)) {
+        throw new Error(`Agent Client '${candidate.id}' has an invalid project descriptor`);
+    }
+    const ownedPathPrefixes = candidate.project.ownedPathPrefixes;
+    if (!Array.isArray(ownedPathPrefixes) || ownedPathPrefixes.length === 0) {
+        throw new Error(`Agent Client '${candidate.id}' requires owned path prefixes`);
+    }
+    const paths = ownedPathPrefixes.map((prefix) => {
+        if (typeof prefix !== 'string'
+            || !isProjectRelativeLiteral(prefix)
+            || !prefix.endsWith('/')) {
+            throw new Error(`Agent Client '${candidate.id}' has invalid owned path prefix '${String(prefix)}'`);
+        }
+        return prefix;
+    });
+    if (new Set(paths).size !== paths.length) {
+        throw new Error(`Agent Client '${candidate.id}' has duplicate owned path prefixes`);
+    }
+    const projectAssets = Object.fromEntries(PROJECT_ASSET_CATEGORIES.map((category) => {
+        const values = candidate.project[category];
+        if (!Array.isArray(values)) {
+            throw new Error(`Agent Client '${candidate.id}' has invalid '${category}' project assets`);
+        }
+        const assets = values.map((asset) => {
+            if (typeof asset !== 'string'
+                || !isProjectRelativeLiteral(asset)
+                || !paths.some((prefix) => asset === prefix.slice(0, -1) || asset.startsWith(prefix))) {
+                throw new Error(`Agent Client '${candidate.id}' has invalid '${category}' project asset '${String(asset)}'`);
+            }
+            return asset;
+        });
+        if (new Set(assets).size !== assets.length) {
+            throw new Error(`Agent Client '${candidate.id}' has duplicate '${category}' project assets`);
+        }
+        return [category, Object.freeze(assets)];
+    }));
+    const categorizedAssets = PROJECT_ASSET_CATEGORIES.flatMap((category) => projectAssets[category].map((asset) => ({ asset, category })));
+    const seenAssets = new Map();
+    for (const { asset, category } of categorizedAssets) {
+        const previous = seenAssets.get(asset);
+        if (previous) {
+            throw new Error(`Agent Client '${candidate.id}' project asset '${asset}' overlaps '${previous}' and '${category}'`);
+        }
+        seenAssets.set(asset, category);
+    }
+    if (!Array.isArray(candidate.project.seedCommands)) {
+        throw new Error(`Agent Client '${candidate.id}' has invalid seed commands`);
+    }
+    const seedTargets = new Set();
+    const seedCommands = candidate.project.seedCommands.map((seed) => {
+        if (!seed || typeof seed !== 'object') {
+            throw new Error(`Agent Client '${candidate.id}' has an invalid seed command`);
+        }
+        const placeholders = [
+            ...seed.target.matchAll(/\$\{([^}]+)\}/g)
+        ].map((match) => match[1]);
+        const targetProbe = seed.target.replaceAll('${projectName}', 'project');
+        if (placeholders.some((placeholder) => placeholder !== 'projectName')
+            || targetProbe.includes('${')
+            || !isProjectRelativeLiteral(targetProbe)
+            || !paths.some((prefix) => targetProbe === prefix.slice(0, -1) || targetProbe.startsWith(prefix))
+            || seedTargets.has(seed.target)) {
+            throw new Error(`Agent Client '${candidate.id}' has invalid seed target '${String(seed.target)}'`);
+        }
+        if (!seed.templates
+            || typeof seed.templates.en !== 'string'
+            || typeof seed.templates['zh-CN'] !== 'string'
+            || !isProjectRelativeLiteral(seed.templates.en)
+            || !isProjectRelativeLiteral(seed.templates['zh-CN'])) {
+            throw new Error(`Agent Client '${candidate.id}' has invalid seed templates`);
+        }
+        seedTargets.add(seed.target);
+        return Object.freeze({
+            templates: Object.freeze({ ...seed.templates }),
+            target: seed.target
+        });
+    });
+    if (!candidate.sandbox || typeof candidate.sandbox.createTool !== 'function') {
+        throw new Error(`Agent Client '${candidate.id}' requires a sandbox descriptor`);
+    }
+    const hookIds = new Set();
+    const hooks = Object.freeze(candidate.sandbox.hooks.map((hook) => {
+        if (!hook.id
+            || hookIds.has(hook.id)
+            || !SANDBOX_HOOK_PHASES.includes(hook.phase)
+            || typeof hook.run !== 'function') {
+            throw new Error(`Agent Client '${candidate.id}' has an invalid sandbox hook`);
+        }
+        if (hook.timeoutMs !== undefined
+            && (!Number.isInteger(hook.timeoutMs)
+                || hook.timeoutMs <= 0
+                || hook.timeoutMs > MAX_SANDBOX_HOOK_TIMEOUT_MS)) {
+            throw new Error(`Agent Client '${candidate.id}' hook '${hook.id}' has invalid timeoutMs`);
+        }
+        hookIds.add(hook.id);
+        return Object.freeze({ ...hook });
+    }));
+    const recoveryCheckIds = new Set();
+    if (candidate.sandbox.recoveryChecks !== undefined
+        && !Array.isArray(candidate.sandbox.recoveryChecks)) {
+        throw new Error(`Agent Client '${candidate.id}' has invalid recovery checks`);
+    }
+    const recoveryChecks = Object.freeze((candidate.sandbox.recoveryChecks ?? []).map((check) => {
+        if (!check
+            || typeof check.id !== 'string'
+            || !TOOL_ID_PATTERN.test(check.id)
+            || recoveryCheckIds.has(check.id)) {
+            throw new Error(`Agent Client '${candidate.id}' has an invalid recovery check`);
+        }
+        const probe = freezeRecoveryProbe(candidate.id, check.id, check.probe);
+        const when = check.when === undefined
+            ? undefined
+            : freezeRecoveryProbe(candidate.id, check.id, check.when);
+        if (!check.finding
+            || !['permissions', 'builtin-link', 'hard-failure'].includes(check.finding.repairKind)
+            || typeof check.finding.message !== 'string'
+            || check.finding.message.trim() === ''
+            || (check.finding.path !== undefined
+                && (typeof check.finding.path !== 'string' || !check.finding.path.startsWith('/')))
+            || (check.finding.repairKind === 'permissions'
+                && check.finding.path === undefined)) {
+            throw new Error(`Agent Client '${candidate.id}' recovery check '${check.id}' has an invalid finding`);
+        }
+        let repair;
+        if (check.repair !== undefined) {
+            if (typeof check.repair.user !== 'string'
+                || check.repair.user === ''
+                || typeof check.repair.command !== 'string'
+                || check.repair.command === ''
+                || !Array.isArray(check.repair.args)
+                || check.repair.args.some((arg) => typeof arg !== 'string')) {
+                throw new Error(`Agent Client '${candidate.id}' recovery check '${check.id}' has an invalid repair`);
+            }
+            repair = Object.freeze({
+                user: check.repair.user,
+                command: check.repair.command,
+                args: Object.freeze([...check.repair.args])
+            });
+        }
+        if (check.finding.repairKind === 'builtin-link' && repair === undefined) {
+            throw new Error(`Agent Client '${candidate.id}' recovery check '${check.id}' requires a repair`);
+        }
+        recoveryCheckIds.add(check.id);
+        return Object.freeze({
+            id: check.id,
+            ...(when === undefined ? {} : { when }),
+            probe,
+            finding: Object.freeze({ ...check.finding }),
+            ...(repair === undefined ? {} : { repair })
+        });
+    }));
+    const aliases = freezeAliases(candidate.id, candidate.sandbox.aliases);
+    const createTool = (context) => {
+        const tool = freezeTool(candidate.sandbox.createTool(context));
+        if (tool.id !== candidate.id) {
+            throw new Error(`Agent Client '${candidate.id}' sandbox tool id must match the adapter id`);
+        }
+        return tool;
+    };
+    return Object.freeze({
+        id: candidate.id,
+        displayName: candidate.displayName,
+        invocation: candidate.invocation,
+        capabilities: Object.freeze(capabilities),
+        project: Object.freeze({
+            ownedPathPrefixes: Object.freeze(paths),
+            ...projectAssets,
+            seedCommands: Object.freeze(seedCommands)
+        }),
+        sandbox: Object.freeze({ createTool, aliases, hooks, recoveryChecks })
+    });
+}
+export { defineAgentClientAdapter };
+//# sourceMappingURL=adapter.js.map