@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/README.md

@@ -93,6 +93,16 @@ Every command above works the same way in Claude Code, Codex, Antigravity CLI, a
 - **AI-assisted updates**: template changes can be merged while preserving project-specific customization
 - **Auditable process-data archive**: preserve local tasks and GitHub evidence in append-only, verifiable snapshots
 
+### Sandbox control boundary
+
+Task-bound sandboxes use a host-only control service for lifecycle and workflow writes. On Linux its fixed endpoint is `/run/user/<uid>/agent-infra/host-control.sock`; on macOS it is `/Users/<login>/Library/Application Support/agent-infra/run/host-control.sock`, resolved from the account identity rather than `HOME` or `TMPDIR`. The service directory is private (`0700`) and the socket is private (`0600`). If the endpoint or sandbox identity is unavailable, task-control commands fail closed.
+
+The shell installer creates and starts the user-scoped service through systemd user units on Linux or launchd user agents on macOS. After a manual npm install, run `agent-infra-internal host-control install`, then enable the generated user service; `agent-infra-internal host-control status` reports endpoint health. No root or setuid service is required.
+
+On macOS, the installer retries service registration during reload. If registration or startup still fails, it exits with an error and a recovery command.
+
+The task directory exposed inside a task-bound sandbox is a writable projection. Artifact commands accept only typed workflow operations and canonical artifact basenames. The host opens candidates with `O_NOFOLLOW`, reads and hashes them through one file descriptor, checks observable metadata changes, and atomically lands validated bytes into the authoritative task directory. Changes to the projection's protected topology fail closed and never turn the projection into task state.
+
 ## Quick Start
 
 ### 1. Install agent-infra

package/README.zh-CN.md

@@ -92,6 +92,16 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 - **AI 辅助升级**：模板升级时可合并变更，同时尽量保留项目侧定制
 - **可审计的过程数据归档**：把本地任务与 GitHub 证据保存为只追加、可校验的快照
 
+### 沙箱控制边界
+
+任务沙箱的生命周期和工作流写操作由宿主专用控制服务执行。Linux 固定端点为 `/run/user/<uid>/agent-infra/host-control.sock`；macOS 固定端点为 `/Users/<login>/Library/Application Support/agent-infra/run/host-control.sock`，路径根据账户身份解析，不读取 `HOME` 或 `TMPDIR`。服务目录权限为 `0700`，socket 权限为 `0600`。端点或沙箱身份不可用时，task-control 命令会失败关闭。
+
+Shell 安装脚本会在 Linux 通过 systemd 用户单元、在 macOS 通过 launchd 用户代理创建并启动该服务。手动 npm 安装后，可运行 `agent-infra-internal host-control install` 创建服务配置，再启用对应的用户服务；`agent-infra-internal host-control status` 可检查端点健康状态。整个服务不需要 root 或 setuid。
+
+macOS 重载期间，安装脚本会重试服务注册；若最终仍无法注册或启动，则以错误退出并提供恢复命令。
+
+任务沙箱内的 task 目录是可写投影。产物命令只接受类型化 workflow 操作和规范的产物 basename。宿主使用 `O_NOFOLLOW` 打开候选文件，通过同一个文件描述符读取并计算摘要，检查可观察的元数据变化，再把已校验字节原子落入权威 task 目录。投影的受保护拓扑发生变化时会失败关闭，投影修改不会变成任务状态。
+
 ## 快速开始
 
 ### 1. 安装 agent-infra

package/bin/cli.ts

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
 import { VERSION } from '../lib/version.ts';
+import {
+  formatTaskViewDiagnostic,
+  guardTaskOperation,
+  TaskViewOperationError
+} from '../lib/internal/task-operation-registry.ts';
+import { PUBLIC_CLI_COMMAND_ALIASES } from '../lib/internal/cli-route-inventory.ts';
 
 // Node.js version check
 const [major = 0, minor = 0] = process.versions.node.split('.').map((part) => parseInt(part, 10));
@@ -15,7 +21,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
+  agent-client    List, status, enable, disable, or configure Agent Clients
   cp <ssh-alias>  Copy local clipboard image to a remote macOS clipboard or Linux sandbox over SSH
   data            Capture, verify, audit, repair, and export process data
   decide          Record a ruling; code-stage decisions require explicit implementation intent
@@ -43,16 +49,27 @@ Examples:
   npx @fitlab-ai/agent-infra init
 `;
 
-const COMMAND_ALIASES: Record<string, string> = {
-  s: 'sandbox',
-  t: 'task'
-};
-
 const rawCommand = process.argv[2] || '';
-const command = Object.hasOwn(COMMAND_ALIASES, rawCommand)
-  ? COMMAND_ALIASES[rawCommand]
+const command = Object.hasOwn(PUBLIC_CLI_COMMAND_ALIASES, rawCommand)
+  ? PUBLIC_CLI_COMMAND_ALIASES[rawCommand as keyof typeof PUBLIC_CLI_COMMAND_ALIASES]
   : rawCommand;
 
+let taskViewGuardFailed = false;
+try {
+  const guard = guardTaskOperation('public', command ?? '', process.argv.slice(3));
+  if (guard.taskView && guard.descriptor.effect === 'diagnostic') {
+    process.stderr.write(formatTaskViewDiagnostic(guard.taskView));
+  }
+} catch (error) {
+  taskViewGuardFailed = true;
+  if (error instanceof TaskViewOperationError) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = error.exitCode;
+  } else {
+    throw error;
+  }
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -73,7 +90,7 @@ async function importCommand(importPath: string) {
   }
 }
 
-switch (command) {
+if (!taskViewGuardFailed) switch (command) {
   case 'agent-client': {
     const imported = await importCommand('../lib/agent-client.ts');
     if (!imported) break;

package/bin/internal-cli.sh

@@ -0,0 +1,45 @@
+#!/bin/sh
+set -eu
+
+script_path=$0
+case "$script_path" in
+  [A-Za-z]:*)
+    drive=${script_path%"${script_path#?}"}
+    drive=$(printf '%s' "$drive" | tr '[:upper:]' '[:lower:]')
+    script_path="/${drive}${script_path#?:}"
+    script_path=$(printf '%s' "$script_path" | tr '\\' '/')
+    ;;
+  /*) ;;
+  *) script_path=$PWD/$script_path ;;
+esac
+while [ -L "$script_path" ]; do
+  link_target=$(readlink "$script_path")
+  case "$link_target" in
+    /*) script_path=$link_target ;;
+    *) script_path=$(dirname -- "$script_path")/$link_target ;;
+  esac
+done
+script_dir=$(CDPATH= cd -- "$(dirname -- "$script_path")" && pwd -P)
+if [ -f "$script_dir/internal-cli.js" ]; then
+  internal_cli="$script_dir/internal-cli.js"
+else
+  internal_cli="$script_dir/../dist/bin/internal-cli.js"
+fi
+
+command=${1-}
+task_control_command=false
+case "$command" in
+  task-lifecycle|task-orchestration|task-finalization) task_control_command=true ;;
+esac
+
+status_mount_present=false
+if [ -d /run/agent-infra/control-status ]; then status_mount_present=true; fi
+launch_config=${AGENT_INFRA_TASK_ID-}${AGENT_INFRA_CONTROL_TOKEN-}${AGENT_INFRA_CONTROL_GENERATION-}${AGENT_INFRA_CONTROL_DIR-}${AGENT_INFRA_CONTROL_STATUS_DIR-}${AGENT_INFRA_RUNTIME_DIR-}${AGENT_INFRA_EXECUTOR_MANIFEST-}
+if [ "$task_control_command" = true ] && [ "$status_mount_present" = true ] && [ -z "$launch_config" ] && [ -z "${AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT-}" ]; then
+  printf '%s\n' '{"status":"failed","changed":false,"error":{"code":"SANDBOX_CONTROL_IDENTITY_MISSING","message":"sandbox control identity is present but its launch configuration is missing"}}'
+  exit 1
+fi
+# The outer launcher owns the Node startup boundary. A task-bound process must
+# not pass preload, import, or loader injection into the control router.
+unset NODE_OPTIONS NODE_PATH
+exec node "$internal_cli" "$@"

package/dist/bin/cli.js

@@ -8,6 +8,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { VERSION } from '../lib/version.js';
+import { formatTaskViewDiagnostic, guardTaskOperation, TaskViewOperationError } from '../lib/internal/task-operation-registry.js';
+import { PUBLIC_CLI_COMMAND_ALIASES } from '../lib/internal/cli-route-inventory.js';
 // Node.js version check
 const [major = 0, minor = 0] = process.versions.node.split('.').map((part) => parseInt(part, 10));
 if (major < 22 || (major === 22 && minor < 9)) {
@@ -19,7 +21,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
+  agent-client    List, status, enable, disable, or configure Agent Clients
   cp <ssh-alias>  Copy local clipboard image to a remote macOS clipboard or Linux sandbox over SSH
   data            Capture, verify, audit, repair, and export process data
   decide          Record a ruling; code-stage decisions require explicit implementation intent
@@ -46,14 +48,27 @@ Examples:
   cd my-project && ai init
   npx @fitlab-ai/agent-infra init
 `;
-const COMMAND_ALIASES = {
-    s: 'sandbox',
-    t: 'task'
-};
 const rawCommand = process.argv[2] || '';
-const command = Object.hasOwn(COMMAND_ALIASES, rawCommand)
-    ? COMMAND_ALIASES[rawCommand]
+const command = Object.hasOwn(PUBLIC_CLI_COMMAND_ALIASES, rawCommand)
+    ? PUBLIC_CLI_COMMAND_ALIASES[rawCommand]
     : rawCommand;
+let taskViewGuardFailed = false;
+try {
+    const guard = guardTaskOperation('public', command ?? '', process.argv.slice(3));
+    if (guard.taskView && guard.descriptor.effect === 'diagnostic') {
+        process.stderr.write(formatTaskViewDiagnostic(guard.taskView));
+    }
+}
+catch (error) {
+    taskViewGuardFailed = true;
+    if (error instanceof TaskViewOperationError) {
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = error.exitCode;
+    }
+    else {
+        throw error;
+    }
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -71,164 +86,165 @@ async function importCommand(importPath) {
         throw error;
     }
 }
-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)
-            break;
-        const { cmdCp } = imported;
-        const code = await cmdCp(process.argv.slice(3)).catch((e) => {
-            process.stderr.write(`Error: ${errorMessage(e)}\n`);
-            return 1;
-        });
-        if (code)
-            process.exitCode = code;
-        break;
-    }
-    case 'data': {
-        const imported = await importCommand('../lib/process-data/index.ts');
-        if (!imported)
-            break;
-        const { cmdData } = imported;
-        const code = await cmdData(process.argv.slice(3)).catch((e) => {
-            process.stderr.write(`Error: ${errorMessage(e)}\n`);
-            return 1;
-        });
-        if (code)
-            process.exitCode = code;
-        break;
-    }
-    case 'decide': {
-        const imported = await importCommand('../lib/decide.ts');
-        if (!imported)
+if (!taskViewGuardFailed)
+    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;
-        const { cmdDecide } = imported;
-        await cmdDecide(process.argv.slice(3));
-        break;
-    }
-    case 'init': {
-        const imported = await importCommand('../lib/init.ts');
-        if (!imported)
+        }
+        case 'cp': {
+            const imported = await importCommand('../lib/cp.ts');
+            if (!imported)
+                break;
+            const { cmdCp } = imported;
+            const code = await cmdCp(process.argv.slice(3)).catch((e) => {
+                process.stderr.write(`Error: ${errorMessage(e)}\n`);
+                return 1;
+            });
+            if (code)
+                process.exitCode = code;
             break;
-        const { cmdInit } = imported;
-        await cmdInit().catch((e) => {
-            process.stderr.write(`Error: ${errorMessage(e)}\n`);
-            process.exitCode = 1;
-        });
-        break;
-    }
-    case 'merge': {
-        const imported = await importCommand('../lib/merge.ts');
-        if (!imported)
+        }
+        case 'data': {
+            const imported = await importCommand('../lib/process-data/index.ts');
+            if (!imported)
+                break;
+            const { cmdData } = imported;
+            const code = await cmdData(process.argv.slice(3)).catch((e) => {
+                process.stderr.write(`Error: ${errorMessage(e)}\n`);
+                return 1;
+            });
+            if (code)
+                process.exitCode = code;
             break;
-        const { cmdMerge } = imported;
-        await cmdMerge(process.argv.slice(3)).catch((e) => {
-            process.stderr.write(`Error: ${errorMessage(e)}\n`);
-            process.exitCode = 1;
-        });
-        break;
-    }
-    case 'run': {
-        const imported = await importCommand('../lib/run/index.ts');
-        if (!imported)
+        }
+        case 'decide': {
+            const imported = await importCommand('../lib/decide.ts');
+            if (!imported)
+                break;
+            const { cmdDecide } = imported;
+            await cmdDecide(process.argv.slice(3));
             break;
-        const { cmdRun } = imported;
-        await cmdRun(process.argv.slice(3));
-        break;
-    }
-    case 'sandbox': {
-        const imported = await importCommand('../lib/sandbox/index.ts');
-        if (!imported)
-            break;
-        const { runSandbox } = imported;
-        await runSandbox(process.argv.slice(3)).catch((e) => {
-            process.stderr.write(`Error: ${errorMessage(e)}\n`);
-            process.exit(1);
-        });
-        break;
-    }
-    case 'server': {
-        const imported = await importCommand('../lib/server/index.ts');
-        if (!imported)
-            break;
-        const { runServer } = imported;
-        await runServer(process.argv.slice(3)).catch((e) => {
-            process.stderr.write(`Error: ${errorMessage(e)}\n`);
-            process.exit(1);
-        });
-        break;
-    }
-    case 'task': {
-        const imported = await importCommand('../lib/task/index.ts');
-        if (!imported)
-            break;
-        const { runTask } = imported;
-        await runTask(process.argv.slice(3)).catch((e) => {
-            process.stderr.write(`Error: ${errorMessage(e)}\n`);
-            process.exit(1);
-        });
-        break;
-    }
-    case 'update': {
-        const imported = await importCommand('../lib/self-update.ts');
-        if (!imported)
+        }
+        case 'init': {
+            const imported = await importCommand('../lib/init.ts');
+            if (!imported)
+                break;
+            const { cmdInit } = imported;
+            await cmdInit().catch((e) => {
+                process.stderr.write(`Error: ${errorMessage(e)}\n`);
+                process.exitCode = 1;
+            });
             break;
-        const { cmdUpdate } = imported;
-        const code = await cmdUpdate().catch((e) => {
-            process.stderr.write(`Error: ${errorMessage(e)}\n`);
-            process.exitCode = 1;
-            return 1;
-        });
-        if (code !== 0)
-            process.exitCode = code;
-        break;
-    }
-    case 'sync': {
-        const imported = await importCommand('../lib/update.ts');
-        if (!imported)
+        }
+        case 'merge': {
+            const imported = await importCommand('../lib/merge.ts');
+            if (!imported)
+                break;
+            const { cmdMerge } = imported;
+            await cmdMerge(process.argv.slice(3)).catch((e) => {
+                process.stderr.write(`Error: ${errorMessage(e)}\n`);
+                process.exitCode = 1;
+            });
+            break;
+        }
+        case 'run': {
+            const imported = await importCommand('../lib/run/index.ts');
+            if (!imported)
+                break;
+            const { cmdRun } = imported;
+            await cmdRun(process.argv.slice(3));
+            break;
+        }
+        case 'sandbox': {
+            const imported = await importCommand('../lib/sandbox/index.ts');
+            if (!imported)
+                break;
+            const { runSandbox } = imported;
+            await runSandbox(process.argv.slice(3)).catch((e) => {
+                process.stderr.write(`Error: ${errorMessage(e)}\n`);
+                process.exit(1);
+            });
+            break;
+        }
+        case 'server': {
+            const imported = await importCommand('../lib/server/index.ts');
+            if (!imported)
+                break;
+            const { runServer } = imported;
+            await runServer(process.argv.slice(3)).catch((e) => {
+                process.stderr.write(`Error: ${errorMessage(e)}\n`);
+                process.exit(1);
+            });
             break;
-        const { cmdSync } = imported;
-        await cmdSync().catch((e) => {
-            process.stderr.write(`Error: ${errorMessage(e)}\n`);
-            process.exitCode = 1;
-        });
-        break;
-    }
-    case 'version': {
-        if (process.argv[3] === '--raw') {
-            console.log(VERSION);
         }
-        else {
+        case 'task': {
+            const imported = await importCommand('../lib/task/index.ts');
+            if (!imported)
+                break;
+            const { runTask } = imported;
+            await runTask(process.argv.slice(3)).catch((e) => {
+                process.stderr.write(`Error: ${errorMessage(e)}\n`);
+                process.exit(1);
+            });
+            break;
+        }
+        case 'update': {
+            const imported = await importCommand('../lib/self-update.ts');
+            if (!imported)
+                break;
+            const { cmdUpdate } = imported;
+            const code = await cmdUpdate().catch((e) => {
+                process.stderr.write(`Error: ${errorMessage(e)}\n`);
+                process.exitCode = 1;
+                return 1;
+            });
+            if (code !== 0)
+                process.exitCode = code;
+            break;
+        }
+        case 'sync': {
+            const imported = await importCommand('../lib/update.ts');
+            if (!imported)
+                break;
+            const { cmdSync } = imported;
+            await cmdSync().catch((e) => {
+                process.stderr.write(`Error: ${errorMessage(e)}\n`);
+                process.exitCode = 1;
+            });
+            break;
+        }
+        case 'version': {
+            if (process.argv[3] === '--raw') {
+                console.log(VERSION);
+            }
+            else {
+                console.log(`agent-infra ${VERSION}`);
+            }
+            break;
+        }
+        case '--version':
+        case '-v': {
             console.log(`agent-infra ${VERSION}`);
+            break;
         }
-        break;
-    }
-    case '--version':
-    case '-v': {
-        console.log(`agent-infra ${VERSION}`);
-        break;
+        case 'help':
+        case '':
+            process.stdout.write(USAGE);
+            break;
+        default:
+            process.stderr.write(`Unknown command: ${command}\n\n`);
+            process.stdout.write(USAGE);
+            process.exitCode = 1;
+            break;
     }
-    case 'help':
-    case '':
-        process.stdout.write(USAGE);
-        break;
-    default:
-        process.stderr.write(`Unknown command: ${command}\n\n`);
-        process.stdout.write(USAGE);
-        process.exitCode = 1;
-        break;
-}
 //# sourceMappingURL=cli.js.map