agent-runner-mcp

一个把三平台沙箱 runner 协议暴露给任何 MCP 客户端（Claude Code、Codex 等）的 MCP server：在证据保护的沙箱里跑任务、读 EXIT 协议、拿尸检报告。零依赖——MCP 协议层手写。每个能力声明带实验编号。

English: README.md。

为什么存在 / Why this exists

Agent 框架各自为政，但"在沙箱里可靠地执行任务并留下证据"是共性刚需。本 server 把 dsh-witness 的 runner 协议（lock=pid:startSec、EXIT:、尸检分类学）包装成 MCP 工具——Claude Code 实测 ✓ Connected，Codex 等 MCP 客户端同协议可接。

工具 / Tools

| 工具 | 语义 | |---|---| | task_run | 沙箱执行命令（Windows ACL / Linux bwrap / macOS sandbox-exec 按平台自动选），返回任务目录 | | task_wait | 等终态（EXIT: 写入）| | task_output | 按字节偏移增量读 out.log | | task_autopsy | 生成尸检报告（autopsy-spec 格式：manner/evidence/verdict/D-01~D-09）| | task_kill | 按 lock pid 击杀（崩溃实验）| | task_adopt | 三证据收养判定（lock 解析 + 进程存活 + exit 协议）|

快速开始 / Quick start

# 安装（git 源）
dsh plugin --profile <name> add "github:Wang-Lin-Chang/agent-runner-mcp#v0.1.1"

# 注册到 Claude Code
claude mcp add agent-runner -- node dist/server.js

# 或直接跑测试（15 断言协议实测）
npm test

验收证据 / Acceptance evidence

• EXP-1：MCP 协议层实测 15/15（握手 / 六工具 / EXIT:0→D-01 / 崩溃→D-08 / EXIT:1→D-02）
• EXP-2：Claude Code 2.1.92 真实客户端 ✓ Connected（initialize + tools/list 握手）
• EXP-3：Windows ACL 持久性判决（观测产物与证据区分离）
• EXP-4：死亡语义矩阵对齐 autopsy-spec 分类学

诚实边界 / Honest boundaries

• Claude Code 会话内工具调用需登录态——本机未登录，协议握手实测、会话调用未实测不声称。
• 本 server 是 runner 协议层：完整 registry 级收养/事件溯源/缓存见 dsh-witness。
• Windows CI 管理员环境下 ACL 沙箱失效 → runner fail-closed（EXIT:-998）为协议正确回应；沙箱能力验收在非管理员环境实测。
• 离线适用面：架构无网络依赖（本地进程 + 文件协议）；数天级断网长跑未实测。

License

Apache-2.0