From 63bcb882a697248e2d6ac37da4006e726dccd730 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 16 Oct 2026 11:11:54 +0800 Subject: [PATCH] feat(ext/ai): add CoW sandbox for Marqdo-only agent trials Give agents a capability-capped run path that stages workspace edits until commit, so generated .mq.md can be verified without polluting the real tree. Co-authored-by: Cursor --- .gitignore | 3 + CHANGELOG.md | 1 + doc/README.md | 3 + doc/design/ext-ai-sandbox.md | 104 ++++ doc/research/ai-agent-sandbox.md | 392 +++++++++++++++ doc/roadmap/ai-stack.md | 1 + doc/roadmap/ext-ai-sandbox.md | 28 ++ ext/ai/sandbox.mq.md | 109 ++++ ext/ai/沙盒.mq.md | 63 +++ plugins/agent/src/lib.rs | 29 ++ plugins/agent/src/sandbox.rs | 53 ++ src/host/fs.rs | 15 +- src/host/mod.rs | 4 + src/host/net.rs | 9 + src/host/plugin.rs | 13 + src/host/sandbox_fs.rs | 475 ++++++++++++++++++ src/host/sys.rs | 3 + src/lib.rs | 12 +- tests/ext/sandbox-cow.mq.md | 60 +++ tests/ext/sandbox-deny.mq.md | 34 ++ tests/ext/sandbox-fixtures/guest-json.mq.md | 9 + tests/ext/sandbox-fixtures/guest-plugin.mq.md | 8 + tests/ext/sandbox-run-lib.mq.md | 22 + tests/gold.rs | 35 ++ 24 files changed, 1483 insertions(+), 2 deletions(-) create mode 100644 doc/design/ext-ai-sandbox.md create mode 100644 doc/research/ai-agent-sandbox.md create mode 100644 doc/roadmap/ext-ai-sandbox.md create mode 100644 ext/ai/sandbox.mq.md create mode 100644 ext/ai/沙盒.mq.md create mode 100644 plugins/agent/src/sandbox.rs create mode 100644 src/host/sandbox_fs.rs create mode 100644 tests/ext/sandbox-cow.mq.md create mode 100644 tests/ext/sandbox-deny.mq.md create mode 100644 tests/ext/sandbox-fixtures/guest-json.mq.md create mode 100644 tests/ext/sandbox-fixtures/guest-plugin.mq.md create mode 100644 tests/ext/sandbox-run-lib.mq.md diff --git a/.gitignore b/.gitignore index 59b7fa0..72d50de 100644 --- a/.gitignore +++ b/.gitignore @@ -87,3 +87,6 @@ tests/ext/:memory: # local secrets .env + +# sandbox gold leftovers +tests/ext/_sbx_cow/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 2b9955c..221cc88 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## Unreleased ### Added +- **`ext/ai/sandbox`**:AI 试跑 CoW 工作区(`open` / `run` / `diff` / `commit` / `discard` / `inspect`);经 `plugins/agent` `sandbox_*` → `host_query`;默认拒 `plugin`/`exec`/`net`;设计见 [ext-ai-sandbox.md](doc/design/ext-ai-sandbox.md)。 ### Fixed diff --git a/doc/README.md b/doc/README.md index fc41bba..52843d0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -90,6 +90,9 @@ | [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 | | [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** | | [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** | +| [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 | +| [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) | +| [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 | | [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus | | [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) | | [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) | diff --git a/doc/design/ext-ai-sandbox.md b/doc/design/ext-ai-sandbox.md new file mode 100644 index 0000000..4605e2b --- /dev/null +++ b/doc/design/ext-ai-sandbox.md @@ -0,0 +1,104 @@ +# Official AI sandbox (`ext/ai/sandbox`) + +| | | +|---|---| +| Status | **Accepted · implementing** | +| Date | 2026-10-16 | +| Related | [research/ai-agent-sandbox.md](../research/ai-agent-sandbox.md) · [roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [stdlib-writeback.md](stdlib-writeback.md) | + +--- + +## 0. One-liner + +**Agent-only Marqdo trial runtime:** capability-isomorphic to browser Wasm defaults, CoW workspace until explicit `commit`, author surface under `ext/ai` (not stdlib). + +--- + +## 1. Goals / non-goals + +### Goals + +| # | Goal | +|---|------| +| G1 | Open a CoW session over a workspace root; edits stay in upper until `commit` | +| G2 | `run` executes `.mq.md` (or in-memory source) under deny-by-default caps with core `lib/*` usable | +| G3 | `diff` / `discard` / `inspect` for review gates | +| G4 | Stable `unavailable in sandbox` for plugin.load, exec foreign/subtask path|code|lang, net (default), `ext/web` server APIs | +| G5 | Author API in `ext/ai/sandbox` via `plugins/agent` — **no** public `lib/sandbox` | + +### Non-goals (this wave) + +| # | Non-goal | +|---|----------| +| N1 | Embed wasmtime in CLI | +| N2 | True Wasm ABI plugins (linalg/quantum) | +| N3 | bwrap / microVM | +| N4 | Full `ext/web` listen/DB/WS inside sandbox | +| N5 | Symlink-forest workspace isolation | +| N6 | Default host-proxy of all native ABI plugins | +| N7 | Wire `agent.step`/`plan` through sandbox automatically (later) | + +--- + +## 2. Layering + +```text +ext/ai/sandbox.mq.md → plugin.load agent → sandbox_* ABI + ↓ host_query + HostContext + CowSession + (fs / writeback see upper) +``` + +| Layer | May call `host_*` | Role | +|-------|-------------------|------| +| `ext/ai/sandbox` | **No** | Author facade | +| `plugins/agent` | via `host_query` only | Register `sandbox_*`; forward to host | +| `src/host` | — | CoW session store; fs/writeback intercept; nested `run` | + +--- + +## 3. Author API + +EN: `ext/ai/sandbox.mq.md` · ZH: `ext/ai/沙盒.mq.md` (separate files, no mixed names in one module). + +| Method | Params | Result | +|--------|--------|--------| +| `open` | optional `root=` (default entry dir / cwd) | map `{ id, root }` | +| `write` | `id=`, `path=`, `text=` | none | +| `read` | `id=`, `path=` | text | +| `remove` | `id=`, `path=` | none (whiteout) | +| `diff` | `id=` | list of `{ path, kind: write\|remove }` | +| `commit` | `id=` | `{ ok, applied }` | +| `discard` | `id=` | `{ ok }` | +| `run` | `id=`, `path=` **or** `source=` | `{ ok, value, stdout?, error? }` | +| `inspect` | `id=` | caps, root, change count, notes | + +Default `run` caps: `fs_write=true` (CoW only), `exec=false`, `net=false`, `plugin=false`. + +--- + +## 4. CoW semantics + +- **lower** = real workspace root (read-through). +- **upper** = session map path → bytes. +- **whiteout** = logical deletes; reads miss; commit unlinks lower. +- No symlink-as-isolation; resolve paths under root; reject `..` escape. +- Until `commit`, host tree unchanged (verifiable with `git status` / file mtime). + +--- + +## 5. Hard bans + +1. No public `lib/sandbox`. +2. No symlink forest as the isolation story. +3. No silent success when capability missing — diagnose `unavailable in sandbox`. +4. `ext/**` must not call `host_*`. +5. Do not treat empty `# main` as sandbox completeness. + +--- + +## 6. ABI / host_query + +Plugin exports (registered on agent plugin): `sandbox_open`, `sandbox_write`, `sandbox_read`, `sandbox_remove`, `sandbox_diff`, `sandbox_commit`, `sandbox_discard`, `sandbox_run`, `sandbox_inspect`. + +Implementation: each forwards to allowlisted `host_query` names of the same stem (e.g. `sandbox_open`), which mutate the process-local CoW store and (for `run`) invoke nested capture with a sandboxed `HostContext`. diff --git a/doc/research/ai-agent-sandbox.md b/doc/research/ai-agent-sandbox.md new file mode 100644 index 0000000..e6d9a79 --- /dev/null +++ b/doc/research/ai-agent-sandbox.md @@ -0,0 +1,392 @@ +# 调研:AI 扩展库沙盒设计(执行隔离 × 工作区暂存 × 写回) + +| | | +|---|---| +| 状态 | **调研笔记 · 供 `ext/ai/*` 沙盒设计锁定参考**(**2026-10-16 修订**:纳入「AI 只生成 Marqdo」产品约束) | +| 日期 | 2026-10-16 | +| 范围 | 浏览器 WASM / WASI、OS 进程沙盒、容器 / microVM、CoW 叠加工作区、符号链接暂存方案;对照 Marqdo AI 栈 | +| 相关设计 | **[ext-ai-sandbox.md](../design/ext-ai-sandbox.md)** · **[roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md)** · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [adr/0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-modules.md](../design/stdlib-modules.md) | +| 姊妹调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) | + +--- + +## 0. 一句话结论 + +**在「Agent 只生成 / 只执行 Marqdo(`.mq.md`)」这一产品约束下,Marqdo AI 沙盒应以 Wasm 为主沙盒——且必须是「内核 + `lib/*` + `ext/*`」可运行的完整运行时沙盒,而不是只跑光秃解释器。** + +锁定方向: + +1. **执行隔离 = Marqdo Wasm 运行时(与 ADR 0002 同构)** — deny-by-default 能力导入;**默认不授予** shell / 外联 / `dlopen` 原生插件。AI 产出面收窄到 Markdown 程序后,不必为通用 coding Agent 的「任意二进制」付沙盒税。 +2. **库完备性是验收线,不是加分项** — 沙盒内须能 `import lib/…` 与受支持的 `ext/…`;缺能力时 **显式失败**,禁止静默空成功(对齐 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5)。 +3. **工作区突变 = CoW / whiteout / 显式 commit**(应用层 VFS,必要时 overlay)— 「修改短暂不生效 → 确认写回」保留;**禁止以符号链接森林作为隔离边界**。 +4. **OS 沙盒 / microVM** — 降为 **逃逸舱 / 托管 Profile**:仅当显式启用 foreign、`subtask` 真子进程、或未来多租户托管时使用;**不是** Marqdo-only Agent 的默认主路径。 + +初稿曾按「通用 coding Agent 还需 shell」把 Wasm 与 bwrap 并列;在 Marqdo-only 约束下,主结论改为 **Wasm-first + 库完备 + CoW 写回**。 + +--- + +## 1. 调研方法与边界 + +### 1.1 做了什么 + +| 动作 | 说明 | +|------|------| +| 厂商/产品文档 | Anthropic Claude Code sandbox / `@anthropic-ai/sandbox-runtime`;VS Code Copilot agent sandboxing;Docker AI Sandboxes;Turso AgentFS CoW overlay;OpenSandbox isolation sessions;WASI / jco preview2-shim;VS Code for the Web WASM webshell | +| 工程对比文 | Northflank / Cosmonic 2026 agent sandbox 指南;gVisor vs Firecracker vs Docker 对比;ContainAI security comparison | +| 学术与标准 | USENIX SEC'22 *Provably-Safe Multilingual Software Sandboxing using WebAssembly*;KTH 论文 *Intra-process Fault Isolation Using WebAssembly*(SFI 通信开销);ACM TOSEM *Research on WebAssembly Runtimes: A Survey*(2025);WASI Design Principles(capability / 无 ambient authority) | +| 安全案例 | brig 项目挂载 symlink 逃逸(CVSS 8.2);Anthropic sandbox-runtime 对 bwrap bind 跟随 symlink 的修复;Docker Sandbox「direct mount vs clone」威胁说明 | +| 对照本仓 | `ext/ai/{llm,agent}`、`lib/writeback`、`lib/subtask`、ADR 0002 浏览器 WASM、`RunOptions.allow_fs_write` 默认关 | + +### 1.2 不做的 + +- 不把「发版用的容器镜像」与「Agent 工具沙盒」混为一谈。 +- 不宣称某一云厂商托管沙盒(E2B / Modal / Daytona)为 Marqdo 默认依赖。 +- 不修改 `doc/next/*`(手写真相源);本文件只进 `doc/research/`。 + +### 1.3 产品约束(修订要点):AI 只生成 Marqdo + +这是相对通用 coding Agent(Claude Code / Codex)的 **结构性好消息**: + +| 通用 Agent | Marqdo AI Agent(本调研采纳) | +|------------|------------------------------| +| 模型可产出 shell / Python / 任意仓库补丁 | 模型产出面收束为 **`.mq.md`(文档即程序)** | +| 沙盒必须兼容「整台开发机能力」 | 沙盒只需跑 **同构 Marqdo 运行时** | +| Wasm 往往只能罩住工具子集 | Wasm **可以**成为主执行边界 | +| 标准库 = 语言运行时 + OS 工具链 | 标准库 / 扩展 = **`lib/*.mq.md` + `ext/**`(+ 受控宿主能力)** | + +硬规则建议(后续 design 应写死): + +1. Agent 工具表 **不提供** 通用 `bash` / 任意语言 `exec`(除非显式 opt-in 逃逸舱,且另套 OS 沙盒)。 +2. Agent 改仓库的权威动作是 **写 / 修订 `.mq.md`(含写回块)**,经 CoW 会话再 `commit`。 +3. 运行 Agent 生成的程序 = 在沙盒里 `run` 该 `.mq.md`,且其 `import` 的 **lib 与 ext 必须可用或显式报不可用**。 + +### 1.4 威胁模型(在 Marqdo-only 下收窄) + +| 威胁 | 典型路径 | Marqdo-only 下的权重 | +|------|----------|----------------------| +| T1 提示注入 | 诱导读密钥、外泄、破坏 `.mq.md` | 仍高 — 靠能力拒绝 + CoW | +| T2 工具侧信道 | `subtask`/`foreign` 子进程 | **默认关闭**;opt-in 才升权 | +| T3 工作区即时破坏 | 直接写穿源树 | 靠 CoW;commit 闸门 | +| T4 挂载逃逸 | symlink / bind 打穿 | 仍相关 — **勿用 symlink 作 W 层** | +| T5 网络外泄 | `lib/net` / llm 出站 | 能力开关 + 域名策略 | +| T6 Wasm 宿主桥过宽 | `host_fs_*` / 插件桥过宽 | **主威胁** — 桥 = 权限表 | +| T7 库残缺假安全 | 沙盒能跑 `# main` 但 `import lib/fs` 怪崩或静默空 | **产品验收威胁** | + +**成功标准:** 失败域止于会话 upper + 已授予能力;真实工作区默认只读直至 commit;**代表性 `lib/*` 与 `ext/*` 金样在沙盒内可跑或得到明确 `unavailable in sandbox` 诊断**。 + +--- + +## 2. 先拆三个「沙盒放哪里」(Marqdo-only 版) + +业界「Harness / Workspace / Execution」三分法仍成立,但 **Execution 的内容变了**: + +```text +┌──────────────────────────────────────────────────────────┐ +│ Pattern H — Harness(编排环) │ +│ ext/ai/agent · parent Plan-and-Move ·(可选)MCP client │ +├──────────────────────────────────────────────────────────┤ +│ Pattern W — Workspace mutation(.mq.md 真相如何变) │ +│ CoW upper / whiteout / diff / commit → writeback │ +├──────────────────────────────────────────────────────────┤ +│ Pattern X — 执行 Agent 产出的 Marqdo 程序 │ +│ Wasm Marqdo runtime + embedded/packaged lib + sandboxed │ +│ ext 能力面(非「任意 shell」) │ +└──────────────────────────────────────────────────────────┘ +``` + +| Pattern | Marqdo 落点 | 沙盒要解决什么 | +|---------|-------------|----------------| +| H | `ext/ai/agent` | 编排是否持有过宽宿主权限;模型 I/O 与执行隔离 | +| W | `lib/writeback` · 工作簿 | 编辑是否立刻污染仓库;人审/父裁决后落盘 | +| X | **Wasm 内 `run` `.mq.md`** | 计算隔离;**lib/ext 能力是否完备且受控** | + +用户提案在 Marqdo-only 下:**Wasm 作 X 主底层是正确方向**;仍须改掉 symlink,并补上 **库完备性** 这一环。 + +--- + +## 3. 方案谱系(横向对比) + +> **读法(修订后):** 下表仍保留通用 Agent 对照。对 **Marqdo-only** 产品,请以 §0 / §5 / §6 的 Wasm-first 结论为准;本节 A/B 升权,F/G/H 降为逃逸舱或托管。 + +评分:● 强 / ◐ 中 / ○ 弱 / — 不适用。维度按「隔离强度」等客观属性;**产品适配**见 §5。 + +| 方案 | 隔离强度 | 启动成本 | 任意二进制 | 工作区暂存语义 | 与 Marqdo 契合 | 主要风险 | +|------|----------|----------|------------|----------------|----------------|----------| +| **A. 浏览器 WASM + 虚拟 FS** | ●(计算)◐(经桥的 FS) | ● | ○ | ◐(需自建 overlay) | ●(已有 ADR 0002) | 宿主桥过宽;无原生 toolchain | +| **B. WASI / Component Model(非浏览器亦可)** | ● | ● | ○(仅 WASI 目标) | ●(preopens + 自建 VFS) | ● | 工具链不全则需降级 | +| **C. 符号链接映射工作区 + 延迟写回** | ○ | ● | —(本身不是执行沙盒) | ◐(似是而非) | ○ | **symlink 逃逸是已知高危类** | +| **D. 应用层 CoW VFS(upper/lower/whiteout)** | ◐(逻辑) | ● | — | ● | ●● | 必须配合 X 层 OS 隔离 | +| **E. OS overlayfs / FUSE / AgentFS 式 CoW** | ●(配合命名空间) | ◐ | ●(在沙盒内) | ●● | ● | Linux/macOS 实现分叉;运维 | +| **F. bubblewrap / Seatbelt(Anthropic SRT 类)** | ● | ● | ● | ○(默认可写 cwd) | ● | 需另加 CoW 才有「暂不生效」 | +| **G. Docker / 硬化容器 / gVisor** | ◐→● | ◐ | ● | ◐(volume 策略) | ◐ | 共享内核或兼容性;重 | +| **H. microVM(Firecracker / Kata)** | ●● | ◐ | ● | ◐ | ○(本地 CLI 过重) | KVM/运维;适合多租户托管 | +| **I. 纯语言沙盒(RestrictedPython 等)** | ○ | ● | ○ | — | ○ | 对 Agent 工具链几乎无用 | + +### 3.1 A — 浏览器 WASM + 虚拟 FS + +**机制:** Wasm 线性内存 + 校验 + 仅经 import 碰宿主;FS 多为内存树 / OPFS / 经 JS bridge 的映射。Marqdo 已锁定「解释器进 WASM」(ADR 0002),默认 `allow_fs_write=false`。 + +**文献支撑:** Wasm 作为 SFI 窄腰(Bosamiya et al., USENIX SEC'22);进程内沙盒跨边界通信可比 IPC 快数量级(KTH Wasm-SFI 论文);WASI 明确 **capability / 无 ambient authority**。 + +**优点:** 与「代码即文档」浏览器运行同构;deny-by-default;适合跑 `.mq.md`、公式库、受控插件。 +**缺点:** 不能原生跑 `cargo test` / `npm` / 任意 shell;安全上限取决于 **bridge 授予了什么**;浏览器场景下「符号链接用户工作区」通常要落到 File System Access API 或服务端中继,**不是** POSIX symlink 语义。 + +**判定:** 在 **Marqdo-only** 约束下,作为 **Pattern X 主沙盒** 与浏览器内 Marqdo 的正解;完备性取决于 **lib 嵌入 + ext 能力桥**(§4.1),不取决于 shell。通用「任意二进制 Agent」场景下仍不够——但那不是本产品默认。 + +### 3.2 B — WASI / Component Model(CLI 宿主) + +**机制:** preopens 显式挂载;`WASIShim({ sandbox: { preopens, enableNetwork: false } })`(Bytecode Alliance jco);Component imports = 权限表。 + +**优点:** 与 Wasm 同族,可在 Node/Wasmtime 跑,不绑浏览器;能力模型清晰。 +**缺点:** 同 A,任意 Linux 工具链需「宿主机再包一层」或改编译目标。 + +**判定:** Marqdo **官方扩展 / 插件中可 Wasm 化的部分**应走这条;与 ADR 0002 一条能力谱。 + +### 3.3 C — 符号链接映射工作区(用户设想的核心) + +**设想:** 沙盒根下用 symlink 指向用户文件;写改暂存别处;确认后写回;删除 = 删 symlink。 + +**表面吸引力:** 零拷贝读、实现「像」有暂存。 + +**为何行业不把它当隔离原语:** + +1. **Bind/mount 跟随 symlink 是经典逃逸。** Anthropic `sandbox-runtime` 明确修复:`allowWrite` 若为指向界外的 symlink,bwrap `--bind` 会把真实目标变成可写(PR #138 类修复)。 +2. **项目挂载未解析 symlink 可致高危。** Endor Labs 披露 brig「project mount symlink traversal」(CVSS 8.2):Agent 在可写项目内把子目录换成指向 `/etc` 的 symlink,下一轮宿主机按字符串挂载即打穿。 +3. **「删除 = 删 symlink」语义错误。** 删链接只去掉别名,**不等于**对 lower 层文件的 whiteout;若链接指向真实文件且曾被打开写穿,删除链接也救不回。 +4. **写穿风险。** 若某路径被解析成真实 inode 且可写,暂存承诺立刻破产。 +5. **跨平台。** Windows junction/reparse、浏览器虚拟 FS、容器 bind,行为不一致。 + +**判定:** **否决作为 Marqdo 默认工作区隔离方案。** 允许在 **只读、已解析、拒绝可写路径上的 symlink 组件** 的前提下作实现细节,但不得当作安全边界叙事。 + +### 3.4 D — 应用层 CoW VFS(推荐作 W 层默认) + +**机制:** + +```text +lower = 真实工作区(只读打开 / 只读能力) +upper = 会话 delta(内存 map / 目录树 / SQLite blob) +whiteout = 逻辑删除集合 +view(path) = upper ?? (!whiteout && lower) +commit() = 把 upper/whiteout 应用到 lower(可经人审) +discard() = 丢弃会话 +diff() = 可审变更集 +``` + +与 Turso AgentFS、OpenSandbox `workspace.mode: overlay` 的 **语义同构**,但不强制 FUSE。 + +**与 Marqdo 对齐点:** + +| VFS 操作 | Marqdo 真相 | +|----------|-------------| +| `diff()` | 父 Agent / 人审材料;可进 view | +| `commit()` 文本结果 | `writeback.record` / 工作簿补丁 | +| `discard()` | 失败回合不污染仓库 | +| 只读 lower | 防止 T3 即时破坏 | + +**优点:** 纯用户态、可测、可嵌入 `plugins/agent`;不依赖 root/FUSE;金样可锁。 +**缺点:** 对 **沙盒内原生工具**(它们走真实 POSIX)不可见,除非再挂 E 或把工具 I/O 也改走 VFS API。 + +**判定:** **Pattern W 的默认实现。** + +### 3.5 E — OS CoW overlay(AgentFS / overlayfs / OpenSandbox) + +**机制(AgentFS 公开设计):** lower=宿主只读;upper=SQLite delta;删除=whiteout;Linux 用 FUSE+user/mount ns;macOS 用 NFS+`sandbox-exec`。OpenSandbox 默认 `overlay`,会话结束可丢 upper。 + +**优点:** 对 **任意 shell 工具**透明;「改了但宿主机 `git status` 仍干净」体验业界已验证。 +**缺点:** 平台依赖;FUSE 权限;与应用层 D 双实现成本。 + +**判定:** **当 Pattern X 需要真实 shell 且要求暂存对工具透明时**启用(Linux 优先);作为 D 的「native 加速后端」,不是替代 Wasm。 + +### 3.6 F — OS 进程沙盒(bwrap / Seatbelt / VS Code Copilot) + +**机制:** Anthropic:文件系统隔离 + **网络隔离(缺一不可)**;Linux bubblewrap + 代理;macOS Seatbelt。VS Code Copilot:同类依赖;路径分 readwrite / readonly / denied;明确「不是 VM,削弱授权即削弱边界」。 + +**优点:** 本地编码 Agent 的事实标准;覆盖子进程;启动轻。 +**缺点:** 默认可写 cwd → **没有**「暂不生效」;必须与 D/E 组合。Symlink 配置路径需解析与拒绝。 + +**判定:** **Pattern X(shell/外联/MCP)本地默认。** + +### 3.7 G / H — 容器与 microVM + +**共识:** 裸 Docker 共享内核,不适合作唯一边界应对不可信代码;gVisor 加强 syscall 拦截;Firecracker/Kata 适合多租户与高威胁(~125ms 级启动)。Docker AI Sandboxes 区分 **direct mount(即时写穿)** vs **clone(只读源 + 私有副本)**——后者才接近「确认后写回」。 + +**判定:** Marqdo **本地 CLI 默认不强制 microVM**;若未来 `ext` 提供托管执行 / 多租户,再把 H 定为服务端 Profile。G 可作为打包/CI Profile。 + +### 3.8 I — 语言级沙盒 + +对「Agent 会跑 shell」场景基本无效;仅作极窄解释器内嵌参考。 + +--- + +## 4. 专门评估:用户提案(修订) + +> 浏览器 WASM 作沙盒底层 + 符号链接用户工作区 + 修改短暂不生效 + 确认后写回 + 删除变删 symlink。 +> **补充约束:** AI 只生成 Marqdo;沙盒须能用标准库与扩展库。 + +| 子命题 | 评价 | 说明 | +|--------|------|------| +| Wasm 作主执行隔离 | **在 Marqdo-only 下正确** | 与 ADR 0002 同构;不必为 shell 全集付税 | +| 沙盒须含 lib + ext | **正确且关键** | 「能跑 `# main`」≠ 好沙盒;见 §4.1 | +| 「短暂不生效」 | **正确** | CoW / staging(方案 D,必要时 E) | +| 「确认后写回」 | **正确且极契合 Marqdo** | 与 writeback、父裁决、workbook 同一哲学 | +| 「symlink 映射工作区」 | **仍错误** | 与是否只用 Marqdo 无关;换 CoW/whiteout | +| 「删除 = 删 symlink」 | **仍错误** | 应为 whiteout;commit 时再对 lower 删除 | +| 「性能最好且安全性最高」 | **Wasm 主路径下接近成立** | 前提是桥最小权限 + CoW;symlink 仍拉低安全 | + +**修订后的正确表述:** + +> **以 Wasm Marqdo 运行时为主沙盒,打包/嵌入 `lib/*`,经能力桥提供受支持的 `ext/*`;工作区用 lower 只读 + upper/whiteout;人审/父裁决后 commit。符号链接不作隔离原语。shell/外联/原生 dlopen 默认关闭,仅作显式逃逸舱。** + +### 4.1 库完备性:什么叫「标准库和扩展库也能用」 + +沙盒若只能跑内置算术、却不能 `import lib/json` 或跑 `ext/ai/llm` 的离线金样,对 Agent 开发几乎无用——模型生成的 `.mq.md` **本来就会依赖 lib/ext**。 + +三类库进沙盒的路径不同: + +| 类别 | 今日形态 | 沙盒策略 | +|------|----------|----------| +| **纯 `.mq.md` 库**(多数 `lib/*`、部分 `ext` 门面) | 源码 import | **嵌入或会话导入图**(已有 `embedded_lib` / import map)— 必须默认可用 | +| **需宿主能力的 lib**(`fs` / `net` / `writeback` / `subtask` / `datetime.now`…) | `host_*` | **经能力表桥接**到会话 VFS / 受控 clock / 受控 fetch;默认最小集 | +| **原生 ABI 扩展**(`plugins/web`、`plugins/agent`、quantum 等 `.so`) | `plugin.load` + dlopen | 浏览器/Wasm **无 dlopen**(ADR 0002 N2)。沙盒内应:**纯 mq 门面 + Wasm 插件**、或 **宿主代执行且权限计入会话**、或 **显式 `unavailable`** — 禁止假装成功 | + +与 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5 对齐并扩展为 **Agent 沙盒能力矩阵(草案)**: + +| 能力 | 沙盒默认 | 备注 | +|------|----------|------| +| builtins / 表 / 控制流 / 对象 | ✓ | 内核 | +| `lib/math` `json` `table` `text` `collection`… | ✓ | embedded | +| `lib/fs` | ✓(仅会话 VFS) | 写进 upper;禁越出 root | +| `lib/writeback` | ✓(写会话内 `.mq.md`) | commit 后才进真实树 | +| `lib/net` / llm HTTP | 默认关 / 域名白名单 | 与 T5 | +| `lib/subtask` `fn=` | ✓(同 Wasm 会话) | | +| `lib/subtask` `path=`/`code=`/`lang=` | **默认拒** | 逃逸舱 + OS 沙盒 | +| `lib/plugin` + 原生 `.so` | **默认拒** | 改 Wasm 插件或宿主代执行 | +| `ext/ai/llm` · `ext/ai/agent`(mq 门面) | ✓(能力允许时) | 网络/密钥另授 | +| `ext/web` 服务端 listen/DB | **默认拒或只读 stub** | 完整 axum 不进沙盒;可测「装配/渲染」子集 | +| `ext/quantum` / `ext/linalg` | 目标 ✓ | 优先纯逻辑 / Wasm 插件,避免强依赖宿主机 .so | + +**验收金样建议(S 阶段):** +一套「沙盒烟囱」:`import` 常用 lib → 写会话文件 → writeback → `diff` → `commit`;再各挑一个 **纯逻辑 ext** 与一个 **需网络的 ext**(后者验证拒绝/白名单)。缺能力必须诊断含 `unavailable in sandbox`(或同等措辞)。 + +--- + +## 5. 综合评分(面向 Marqdo-only 产品) + +加权(修订):执行隔离契合 Marqdo-only 30%、**lib/ext 完备** 25%、与 writeback 真相 20%、实现成本 15%、跨端(CLI↔浏览器)10%。 +(「任意 shell 工具完备」不再作为主权重。) + +| 候选架构 | 分(相对) | 备注 | +|----------|------------|------| +| **A/B Wasm-first + D CoW + 库完备能力表** | **100(推荐)** | 主路径 | +| 同上 + 逃逸舱 F(opt-in shell) | 95 | 兼容少数 foreign 需求 | +| D + E + F(通用 coding 向) | 75 | 过重;非 Marqdo-only 默认 | +| 仅 F(可写 cwd) | 55 | 缺 CoW;且鼓励非 mq 工具 | +| 仅 A 但无 CoW、无 lib 嵌入 | 40 | 「半沙盒」 | +| 仅 C(symlink) | 20 | 否决 | +| 仅 H(人人 microVM) | 50 | 托管可选;本地默认过重 | + +**绝对「最硬」单点**仍可以是 microVM(托管 Profile)。 +**Marqdo「最合适」:** **Wasm 完整运行时沙盒(内核+lib+受控 ext)+ CoW 工作区 + commit 闸门**。 + +--- + +## 6. Marqdo 应采用的沙盒设计(推荐锁定草案 · 修订) + +### 6.1 产品形态 + +| Profile | 场景 | 执行(X) | 工作区(W) | +|---------|------|-----------|------------| +| **`mq-sandbox`(默认)** | Agent 生成并试跑 `.mq.md` | **Wasm Marqdo** + embedded `lib/*` + 能力桥 `ext` | 应用层 CoW;commit→真实树 / writeback | +| **`browser`** | 页内同构运行 | 同左(ADR 0002) | 内存/OPFS;无 POSIX symlink | +| **`escape`(显式)** | foreign / 真子进程 | OS 沙盒包一层 | 仍建议 CoW 可见 | +| **`hosted`(可选)** | 多租户 | Wasm 或 microVM | 会话隔离;凭证外置 | + +### 6.2 推荐架构图 + +```text + ┌──────────────────────────────────────┐ + │ ext/ai/agent (Harness) │ + │ 只产出 / 编排 .mq.md · 人审闸门 │ + └──────────────────┬───────────────────┘ + │ + ┌─────────────────────┼─────────────────────┐ + ▼ ▼ + ┌────────────────────┐ ┌────────────────────┐ + │ Workspace CoW (W) │ │ Marqdo Wasm (X) │ + │ lower = RO 工作区 │◄── fs/writeback ───│ 同构解释器/VM │ + │ upper / whiteout │ 能力导入 │ + embedded lib/* │ + │ diff·commit·discard│ │ + ext 能力面 │ + └─────────┬──────────┘ │ 默认: 无 shell/so │ + │ └────────────────────┘ + ▼ + 真实工作区 / + (代码即文档真相源) + + (可选)escape: subtask path|code|lang → OS sandbox +``` + +### 6.3 API 面建议(设计级,非立即实现) + +落点倾向:宿主能力进 `plugins/agent` / Wasm HostContext;作者面经 `ext/ai` 或 `lib`(**禁止** `ext/**` 直调 `host_*`)。 + +| 概念 | 语义 | +|------|------| +| `sandbox.open(root, mode=cow)` | 打开会话;lower 只读 | +| `sandbox.read/write/list/remove` | 经 view;remove → whiteout | +| `sandbox.diff` / `stat` | 供父 Agent / view | +| `sandbox.commit` / `discard` | 闸门;可要求 HITL | +| `sandbox.run(source\|path, caps=…)` | **Wasm 跑 Marqdo**;caps 声明 fs/net/llm/… | +| `sandbox.caps` / `inspect` | 列出已授能力与 lib/ext 可用性(对齐 `web.inspect` 哲学) | +| `sandbox.exec(...)` | **仅 escape Profile**;默认不存在于作者工具表 | + +与现有衔接: + +- `lib/*`:优先 embedded;FS/时间/网络走会话 caps。 +- `ext/*`:mq 门面可加载;原生插件默认不可用并诊断;长期可 Wasm 化的(linalg/quantum 逻辑)优先进 Wasm。 +- `lib/writeback`:写入会话内文件;`commit` 时进入真实树。 +- `lib/subtask`:默认仅 `fn=`;`path`/`code`/`lang` 要 escape。 + +### 6.4 硬禁(写入后续 design 时应保留) + +1. **不以 symlink 森林作为隔离或暂存原语。** +2. **不以「能跑空 `# main`」宣称沙盒完成** — 必须过 lib/ext 完备金样或显式 unavailable。 +3. **默认工具表不提供通用 shell / 任意语言 exec。** +4. **不默认可写 bind 真实工作区。** +5. **宿主桥 = 权限表**:未授能力不得 ambient 成功。 +6. **不静默降级**:缺 Wasm/能力时不得假装已隔离。 +7. **`ext/**` 不调 `host_*`**(既有宪法)。 + +### 6.5 分阶段落地(建议,非 `doc/next`) + +| 阶段 | 交付 | 验收线索 | +|------|------|----------| +| S0 | 威胁模型 + 本调研(含 Marqdo-only) | 本文 | +| S1 | Wasm `run` + embedded 核心 `lib/*` + 会话 VFS 读 | 常用 lib 金样在沙盒绿 | +| S2 | CoW upper/whiteout + diff/commit/discard | 未 commit 时宿主机 `git status` 干净 | +| S3 | writeback / 工作簿在会话内可写;commit 对齐 | agent step 金样 | +| S4 | caps:net/llm 白名单;`subtask` 非 fn 默认拒 | 诊断字符串稳定 | +| S5 | 代表性 ext(纯逻辑 + 需网)沙盒金样 | 完备性验收 | +| S6 | (可选)escape OS 沙盒;hosted microVM | 文档标明非默认 | + +--- + +## 7. 外部资料索引(抽样) + +| 类型 | 引用 | +|------|------| +| 产品 | [Anthropic: Claude Code sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) · [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) · [VS Code agent sandboxing](https://code.visualstudio.com/docs/agents/run/agent-sandboxing) · [Docker AI Sandboxes security](https://docs.docker.com/ai/sandboxes/security/) · [Turso AgentFS overlay](https://turso.tech/blog/agentfs-overlay) · [OpenSandbox isolation sessions](https://open-sandbox.ai/guides/isolation-sessions) | +| 标准 | [WASI Design Principles](https://github.com/WebAssembly/WASI/blob/main/docs/DesignPrinciples.md) · [jco preview2-shim sandbox](https://github.com/bytecodealliance/jco/blob/main/packages/preview2-shim/README.md) | +| 论文 | Bosamiya et al., *Provably-Safe Multilingual Software Sandboxing using WebAssembly*, USENIX Security 2022 · *Intra-process Fault Isolation Using WebAssembly* (KTH) · *Research on WebAssembly Runtimes: A Survey*, ACM TOSEM 2025 | +| 综述 | [Cosmonic: Choosing an AI agent sandbox (2026)](https://cosmonic.com/ai-sandbox/choosing-an-agent-sandbox/) · [Northflank: MicroVMs, gVisor & isolation](https://northflank.com/blog/how-to-sandbox-ai-agents) | +| 安全案例 | [brig symlink traversal / Endor Labs](https://www.endorlabs.com/learn/project-mount-symlink-traversal-in-brig-how-a-sandbox-reaches-host-directories-it-was-never-given) · Anthropic sandbox-runtime symlink bind 修复 | + +--- + +## 8. 结语 + +- **产品好消息:** Agent 只生成 Marqdo → **Wasm 主沙盒设计成立**,不必默认扛通用 shell Agent 的复杂度。 +- **好沙盒的定义:** 不只跑内核,还要 **`lib/*` 可用、`ext/*` 在能力表内可用或显式不可用**;再加 **CoW + commit** 保护仓库真相。 +- **仍要改掉的:** 符号链接当暂存/隔离;默认开放 foreign/dlopen;「空 main 能跑」就算完工。 +- **降级为非默认的:** bwrap/microVM — 留给 escape / hosted,而不是 Marqdo-only 主路径。 + +不急着实现。下一步若继续收敛,再开 `doc/design/ext-ai-sandbox.md` 把 **能力矩阵 + 库完备金样清单** 锁死即可;**仍不要改 `doc/next/*`**。 diff --git a/doc/roadmap/ai-stack.md b/doc/roadmap/ai-stack.md index ba1c68a..0e872fe 100644 --- a/doc/roadmap/ai-stack.md +++ b/doc/roadmap/ai-stack.md @@ -18,6 +18,7 @@ |----|------|------| | **Intelligence primitive** | `ask` / `stream` / `collect`;结果对象 | `ext/ai/llm` | | **Agent runtime** | `run` / `step` / `plan` / `route` | `ext/ai/agent` | +| **Sandbox (trial)** | CoW workspace + capped `run` | `ext/ai/sandbox` · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) | | **Memory / compile** | episode → skill → policy | `plugins/agent`(ABI;**不进** `src/host`) | | **Transport** | HTTP / SSE / provider | `ext/ai/llm/openai` · `ollama`;用户不可见 | diff --git a/doc/roadmap/ext-ai-sandbox.md b/doc/roadmap/ext-ai-sandbox.md new file mode 100644 index 0000000..e053bf8 --- /dev/null +++ b/doc/roadmap/ext-ai-sandbox.md @@ -0,0 +1,28 @@ +# Roadmap: `ext/ai/sandbox` (AI CoW trial runtime) + +| | | +|---|---| +| Status | **Active** | +| Date | 2026-10-16 | +| Design | [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) | +| Research | [ai-agent-sandbox.md](../research/ai-agent-sandbox.md) | + +## Milestones + +| ID | Deliverable | Done when | +|----|-------------|-----------| +| S0 | Design + this roadmap + research cross-links | **done** | +| S1 | CoW open/write/read/remove/diff/commit/discard | **done** (`sandbox-cow`) | +| S2 | `run` + default caps + core lib inside run | **done** (`sandbox-run-lib`) | +| S3 | `inspect` + deny plugin.load | **done** (`sandbox-deny`) | +| S4 | Polish: ai-stack + CHANGELOG | **done** | + +## Gold samples (target) + +- `tests/ext/sandbox-cow.mq.md` +- `tests/ext/sandbox-run-lib.mq.md` +- `tests/ext/sandbox-deny.mq.md` + +## Out of scope this wave + +wasmtime CLI embed · Wasm ABI plugins · bwrap/microVM · full web in sandbox · auto-wire agent.step · edit `doc/next/*` diff --git a/ext/ai/sandbox.mq.md b/ext/ai/sandbox.mq.md new file mode 100644 index 0000000..ed5b75f --- /dev/null +++ b/ext/ai/sandbox.mq.md @@ -0,0 +1,109 @@ +--- +title: ext/ai/sandbox +description: >- + CoW trial workspace for AI-generated Marqdo: open / run / diff / commit. + Native work lives in plugins/agent (`sandbox_*` → host_query). +import plugin:lib/plugin.mq.md +import sys:lib/sys.mq.md +--- + +Load the agent plugin once per call (same pattern as other `ext/ai` helpers). + +## ensure_plugin + +**p = plugin.native_path name="agent"** +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/sandbox: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent) + > sys.exit code=1 + +## open + + `root`=None + +Open a CoW session. Optional `root=` (directory). Default: entry file directory. + +> ensure_plugin + +1. `root` + *> sandbox_open root=`root`* +2. * + *> sandbox_open* + +## write + + `id` + + `path` + + `text` + +Write text into the session upper layer (host tree unchanged until `commit`). + +> ensure_plugin +*> sandbox_write id=`id` path=`path` text=`text`* + +## read + + `id` + + `path` + +Read through CoW (upper, else lower; whiteout misses). + +> ensure_plugin +*> sandbox_read id=`id` path=`path`* + +## remove + + `id` + + `path` + +Logical delete (whiteout). + +> ensure_plugin +*> sandbox_remove id=`id` path=`path`* + +## diff + + `id` + +List of `{ path, kind }` pending changes (`write` | `remove`). + +> ensure_plugin +*> sandbox_diff id=`id`* + +## commit + + `id` + +Apply upper / whiteout to the real workspace root. + +> ensure_plugin +*> sandbox_commit id=`id`* + +## discard + + `id` + +Drop the session without writing the host tree. + +> ensure_plugin +*> sandbox_discard id=`id`* + +## run + + `id` + + `source`=None + + `path`=None + +Run Marqdo under sandbox caps (`exec` / `net` / `plugin` off; fs via CoW). +Pass `source=` or `path=` (relative to session root). + +> ensure_plugin + +1. `source` + *> sandbox_run id=`id` source=`source`* +2. `path` + *> sandbox_run id=`id` path=`path`* +3. * + > print text=ext/ai/sandbox.run: need source= or path= + > sys.exit code=1 + +## inspect + + `id` + +Caps defaults, change counts, and availability notes. + +> ensure_plugin +*> sandbox_inspect id=`id`* diff --git a/ext/ai/沙盒.mq.md b/ext/ai/沙盒.mq.md new file mode 100644 index 0000000..8e7afa2 --- /dev/null +++ b/ext/ai/沙盒.mq.md @@ -0,0 +1,63 @@ +--- +title: ext/ai/沙盒 +description: >- + AI 试跑 CoW 工作区:打开 / 运行 / 差异 / 提交(中文面,委托英文 sandbox 模块)。 +import sandbox:ext/ai/sandbox.mq.md +--- + +## 打开 + + `根`=None + +*> sandbox.open root=`根`* + +## 写入 + + `id` + + `路径` + + `文本` + +*> sandbox.write id=`id` path=`路径` text=`文本`* + +## 读取 + + `id` + + `路径` + +*> sandbox.read id=`id` path=`路径`* + +## 删除 + + `id` + + `路径` + +*> sandbox.remove id=`id` path=`路径`* + +## 差异 + + `id` + +*> sandbox.diff id=`id`* + +## 提交 + + `id` + +*> sandbox.commit id=`id`* + +## 丢弃 + + `id` + +*> sandbox.discard id=`id`* + +## 运行 + + `id` + + `源码`=None + + `路径`=None + +1. `源码` + *> sandbox.run id=`id` source=`源码`* +2. `路径` + *> sandbox.run id=`id` path=`路径`* +3. * + > print text=沙盒.运行: 需要 源码= 或 路径= + > sys.exit code=1 + +## 检查 + + `id` + +*> sandbox.inspect id=`id`* diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 470e958..06e5757 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -8,6 +8,7 @@ mod mcp_server; mod memory; mod resume; mod route; +mod sandbox; use std::collections::HashMap; use std::ffi::{CStr, CString}; @@ -1180,6 +1181,34 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int { return 1; } + // Optional JSON keys only — empty params CSV so omitted args are not required. + if register(host, "sandbox_open", "", sandbox::sandbox_open) != 0 { + return 1; + } + if register(host, "sandbox_write", "", sandbox::sandbox_write) != 0 { + return 1; + } + if register(host, "sandbox_read", "", sandbox::sandbox_read) != 0 { + return 1; + } + if register(host, "sandbox_remove", "", sandbox::sandbox_remove) != 0 { + return 1; + } + if register(host, "sandbox_diff", "", sandbox::sandbox_diff) != 0 { + return 1; + } + if register(host, "sandbox_commit", "", sandbox::sandbox_commit) != 0 { + return 1; + } + if register(host, "sandbox_discard", "", sandbox::sandbox_discard) != 0 { + return 1; + } + if register(host, "sandbox_inspect", "", sandbox::sandbox_inspect) != 0 { + return 1; + } + if register(host, "sandbox_run", "", sandbox::sandbox_run) != 0 { + return 1; + } 0 } diff --git a/plugins/agent/src/sandbox.rs b/plugins/agent/src/sandbox.rs new file mode 100644 index 0000000..2193aae --- /dev/null +++ b/plugins/agent/src/sandbox.rs @@ -0,0 +1,53 @@ +//! Forward `sandbox_*` plugin calls to host_query (CoW lives in the host). + +use super::{ + host_query_json_args, parse_args, set_err, set_out, +}; +use std::os::raw::c_char; + +fn forward( + query_name: &str, + args_json: *const c_char, + out_json: *mut *mut c_char, + err_msg: *mut *mut c_char, +) -> i32 { + let v = match parse_args(args_json) { + Ok(v) => v, + Err(e) => { + set_err(err_msg, &format!("{query_name}: {e}")); + return 1; + } + }; + match host_query_json_args(query_name, &v) { + Ok(j) => { + set_out(out_json, &j.to_string()); + 0 + } + Err(e) => { + set_err(err_msg, &e); + 1 + } + } +} + +macro_rules! sandbox_ffi { + ($fn_name:ident, $query:expr) => { + pub unsafe extern "C" fn $fn_name( + args_json: *const c_char, + out_json: *mut *mut c_char, + err_msg: *mut *mut c_char, + ) -> i32 { + forward($query, args_json, out_json, err_msg) + } + }; +} + +sandbox_ffi!(sandbox_open, "sandbox_open"); +sandbox_ffi!(sandbox_write, "sandbox_write"); +sandbox_ffi!(sandbox_read, "sandbox_read"); +sandbox_ffi!(sandbox_remove, "sandbox_remove"); +sandbox_ffi!(sandbox_diff, "sandbox_diff"); +sandbox_ffi!(sandbox_commit, "sandbox_commit"); +sandbox_ffi!(sandbox_discard, "sandbox_discard"); +sandbox_ffi!(sandbox_inspect, "sandbox_inspect"); +sandbox_ffi!(sandbox_run, "sandbox_run"); diff --git a/src/host/fs.rs b/src/host/fs.rs index 6a58405..c7138b3 100644 --- a/src/host/fs.rs +++ b/src/host/fs.rs @@ -34,6 +34,9 @@ fn text_body(v: &Value) -> Result<&str, String> { pub fn read_text(ctx: &HostContext, path: &Value) -> Result { let p = ctx.resolve_path(text_path(path)?)?; + if let Some(hit) = crate::host::sandbox_fs::cow_read_text(ctx, &p)? { + return Ok(Value::Text(hit)); + } let s = fs::read_to_string(&p).map_err(|e| format!("read_text {}: {e}", p.display()))?; Ok(Value::Text(s)) } @@ -43,10 +46,14 @@ pub fn write_text(ctx: &HostContext, path: &Value, text: &Value) -> Result Result Result { let p = ctx.resolve_path(text_path(path)?)?; + if let Some(hit) = crate::host::sandbox_fs::cow_exists(ctx, &p)? { + return Ok(Value::Bool(hit)); + } Ok(Value::Bool(p.exists())) } @@ -109,6 +119,9 @@ pub fn remove(ctx: &HostContext, path: &Value) -> Result { return Err("remove denied by host policy".into()); } let p = ctx.resolve_path(text_path(path)?)?; + if crate::host::sandbox_fs::cow_remove(ctx, &p)? { + return Ok(Value::None); + } if p.is_dir() { fs::remove_dir_all(&p).map_err(|e| format!("remove {}: {e}", p.display()))?; } else { diff --git a/src/host/mod.rs b/src/host/mod.rs index 7223d38..b68dc94 100644 --- a/src/host/mod.rs +++ b/src/host/mod.rs @@ -40,6 +40,7 @@ pub mod subtask; #[cfg(not(feature = "exec-host"))] #[path = "subtask_stub.rs"] pub mod subtask; +pub mod sandbox_fs; mod sys; pub mod writeback; @@ -111,6 +112,8 @@ pub struct HostContext { pub subtask_seq: u64, /// Minimum log level (`lib/log`); default Info (20). See `host::log::Level`. pub log_min_level: u8, + /// Active `ext/ai/sandbox` CoW session id (nested `sandbox_run`). + pub sandbox_session: Option, } impl Default for HostContext { @@ -135,6 +138,7 @@ impl Default for HostContext { subtasks: HashMap::new(), subtask_seq: 0, log_min_level: 20, // Info + sandbox_session: None, } } } diff --git a/src/host/net.rs b/src/host/net.rs index d345560..201ecdf 100644 --- a/src/host/net.rs +++ b/src/host/net.rs @@ -120,6 +120,9 @@ pub fn http_get( headers: Option<&Value>, ) -> Result { if !ctx.allow_net() { + if ctx.sandbox_session.is_some() { + return Err("net unavailable in sandbox".into()); + } return Err("http_get denied by host policy".into()); } let url = as_text(url, "url")?; @@ -137,6 +140,9 @@ pub fn http_post( headers: Option<&Value>, ) -> Result { if !ctx.allow_net() { + if ctx.sandbox_session.is_some() { + return Err("net unavailable in sandbox".into()); + } return Err("http_post denied by host policy".into()); } let url = as_text(url, "url")?; @@ -161,6 +167,9 @@ pub fn http_request( headers: Option<&Value>, ) -> Result { if !ctx.allow_net() { + if ctx.sandbox_session.is_some() { + return Err("net unavailable in sandbox".into()); + } return Err("http_request denied by host policy".into()); } let method = as_text(method, "method")?.to_uppercase(); diff --git a/src/host/plugin.rs b/src/host/plugin.rs index 941523c..69b33de 100644 --- a/src/host/plugin.rs +++ b/src/host/plugin.rs @@ -417,6 +417,16 @@ unsafe extern "C" fn host_query( }); Ok(serde_json::json!({ "ok": true })) })(), + name if name.starts_with("sandbox_") => (|| { + let raw = args_owned.as_deref().unwrap_or("{}"); + let args: serde_json::Value = serde_json::from_str(if raw.trim().is_empty() { + "{}" + } else { + raw + }) + .map_err(|e| format!("{name} args: {e}"))?; + crate::host::sandbox_fs::query(name, &args, ctx) + })(), // ADR 0007: run a Document/Endpoint `.mq.md` for HTTP handlers. "run_artifact" => (|| { let raw = args_owned.as_deref().unwrap_or("{}"); @@ -472,6 +482,9 @@ unsafe extern "C" fn host_query( pub fn load(ctx: &mut HostContext, path: &Value) -> Result { if !ctx.allow_plugin() { + if ctx.sandbox_session.is_some() { + return Err("plugin.load unavailable in sandbox".into()); + } return Err("plugin_load denied by host policy".into()); } let rel = as_text(path, "path")?; diff --git a/src/host/sandbox_fs.rs b/src/host/sandbox_fs.rs new file mode 100644 index 0000000..5bf6739 --- /dev/null +++ b/src/host/sandbox_fs.rs @@ -0,0 +1,475 @@ +//! Application-level CoW workspace for `ext/ai/sandbox` (via host_query). +//! +//! lower = real root (read-through); upper = session bytes; whiteout = logical delete. +//! Not a symlink forest. Symlink targets are not followed as isolation primitives. + +use std::collections::{HashMap, HashSet}; +use std::path::{Component, Path, PathBuf}; +use std::sync::{Mutex, OnceLock}; + +use serde_json::json; + +use crate::host::HostContext; +use crate::value::Value; + +#[derive(Debug, Default)] +pub struct CowSession { + pub root: PathBuf, + /// Relative path (forward slashes) → file bytes. + pub upper: HashMap>, + pub whiteout: HashSet, +} + +static SESSIONS: OnceLock>> = OnceLock::new(); +static SEQ: OnceLock> = OnceLock::new(); + +fn sessions() -> &'static Mutex> { + SESSIONS.get_or_init(|| Mutex::new(HashMap::new())) +} + +fn next_id() -> String { + let mut g = SEQ + .get_or_init(|| Mutex::new(0)) + .lock() + .unwrap_or_else(|e| e.into_inner()); + *g = g.wrapping_add(1); + format!("sbx-{g}") +} + +fn normalize_rel(rel: &str) -> Result { + let rel = rel.trim().trim_start_matches('/'); + if rel.is_empty() { + return Err("sandbox path must not be empty".into()); + } + let p = Path::new(rel); + if p.is_absolute() { + return Err("sandbox path must be relative to session root".into()); + } + let mut out = Vec::new(); + for c in p.components() { + match c { + Component::Normal(s) => out.push(s.to_string_lossy().into_owned()), + Component::CurDir => {} + Component::ParentDir => { + return Err("sandbox path must not contain '..'".into()); + } + _ => return Err(format!("sandbox path invalid component in `{rel}`")), + } + } + if out.is_empty() { + return Err("sandbox path must not be empty".into()); + } + Ok(out.join("/")) +} + +fn abs_under_root(root: &Path, rel: &str) -> Result { + let rel_n = normalize_rel(rel)?; + let abs = root.join(Path::new(&rel_n)); + let root_canon = root.canonicalize().unwrap_or_else(|_| root.to_path_buf()); + // Parent may not exist yet for writes — check by prefix components. + let mut check = abs.clone(); + loop { + if check == *root || check == root_canon { + return Ok(root.join(Path::new(&rel_n))); + } + if !check.pop() { + break; + } + if let Ok(c) = check.canonicalize() { + if crate::host::path_under_root(&c, &root_canon) || c == root_canon { + return Ok(root.join(Path::new(&rel_n))); + } + } + } + if crate::host::path_under_root(&abs, root) { + return Ok(abs); + } + Err(format!("path escapes sandbox root: {rel_n}")) +} + +pub fn open(root: Option<&str>, ctx: &HostContext) -> Result { + let root_pb = if let Some(r) = root.filter(|s| !s.is_empty()) { + let p = PathBuf::from(r); + if p.is_absolute() { + p + } else { + ctx.cwd.join(p) + } + } else if let Some(ep) = &ctx.entry_path { + ep.parent() + .unwrap_or(ep.as_path()) + .to_path_buf() + } else { + ctx.cwd.clone() + }; + let root_pb = if root_pb.is_absolute() { + root_pb + } else { + std::env::current_dir() + .unwrap_or_else(|_| PathBuf::from(".")) + .join(root_pb) + }; + if !root_pb.is_dir() { + return Err(format!( + "sandbox_open: root is not a directory: {}", + root_pb.display() + )); + } + let id = next_id(); + let sess = CowSession { + root: root_pb.clone(), + upper: HashMap::new(), + whiteout: HashSet::new(), + }; + sessions() + .lock() + .unwrap_or_else(|e| e.into_inner()) + .insert(id.clone(), sess); + Ok(json!({ + "id": id, + "root": root_pb.to_string_lossy(), + })) +} + +fn with_session_mut(id: &str, f: F) -> Result +where + F: FnOnce(&mut CowSession) -> Result, +{ + let mut map = sessions().lock().unwrap_or_else(|e| e.into_inner()); + let sess = map + .get_mut(id) + .ok_or_else(|| format!("sandbox: unknown session `{id}`"))?; + f(sess) +} + +fn with_session(id: &str, f: F) -> Result +where + F: FnOnce(&CowSession) -> Result, +{ + let map = sessions().lock().unwrap_or_else(|e| e.into_inner()); + let sess = map + .get(id) + .ok_or_else(|| format!("sandbox: unknown session `{id}`"))?; + f(sess) +} + +pub fn write(id: &str, path: &str, text: &str) -> Result { + with_session_mut(id, |sess| { + let rel = normalize_rel(path)?; + let _ = abs_under_root(&sess.root, &rel)?; + sess.whiteout.remove(&rel); + sess.upper.insert(rel, text.as_bytes().to_vec()); + Ok(json!({ "ok": true })) + }) +} + +pub fn read(id: &str, path: &str) -> Result { + with_session(id, |sess| { + let rel = normalize_rel(path)?; + if sess.whiteout.contains(&rel) { + return Err(format!("sandbox_read: not found (whiteout): {rel}")); + } + if let Some(bytes) = sess.upper.get(&rel) { + let s = String::from_utf8(bytes.clone()) + .map_err(|e| format!("sandbox_read: not utf-8: {e}"))?; + return Ok(json!(s)); + } + let abs = abs_under_root(&sess.root, &rel)?; + let s = std::fs::read_to_string(&abs) + .map_err(|e| format!("sandbox_read {}: {e}", abs.display()))?; + Ok(json!(s)) + }) +} + +pub fn remove(id: &str, path: &str) -> Result { + with_session_mut(id, |sess| { + let rel = normalize_rel(path)?; + let _ = abs_under_root(&sess.root, &rel)?; + sess.upper.remove(&rel); + sess.whiteout.insert(rel); + Ok(json!({ "ok": true })) + }) +} + +pub fn diff(id: &str) -> Result { + with_session(id, |sess| { + let mut items: Vec = Vec::new(); + for p in sess.upper.keys() { + items.push(json!({ "path": p, "kind": "write" })); + } + for p in &sess.whiteout { + items.push(json!({ "path": p, "kind": "remove" })); + } + items.sort_by(|a, b| { + let pa = a.get("path").and_then(|v| v.as_str()).unwrap_or(""); + let pb = b.get("path").and_then(|v| v.as_str()).unwrap_or(""); + pa.cmp(pb) + }); + Ok(json!(items)) + }) +} + +pub fn commit(id: &str) -> Result { + with_session_mut(id, |sess| { + let mut applied = 0i64; + let writes: Vec<(String, Vec)> = sess + .upper + .iter() + .map(|(k, v)| (k.clone(), v.clone())) + .collect(); + let removes: Vec = sess.whiteout.iter().cloned().collect(); + for (rel, bytes) in writes { + let abs = abs_under_root(&sess.root, &rel)?; + if let Some(parent) = abs.parent() { + std::fs::create_dir_all(parent) + .map_err(|e| format!("sandbox_commit mkdir: {e}"))?; + } + std::fs::write(&abs, &bytes) + .map_err(|e| format!("sandbox_commit write {}: {e}", abs.display()))?; + applied += 1; + } + for rel in removes { + let abs = abs_under_root(&sess.root, &rel)?; + if abs.exists() { + if abs.is_dir() { + std::fs::remove_dir_all(&abs) + .map_err(|e| format!("sandbox_commit remove {}: {e}", abs.display()))?; + } else { + std::fs::remove_file(&abs) + .map_err(|e| format!("sandbox_commit remove {}: {e}", abs.display()))?; + } + applied += 1; + } + } + sess.upper.clear(); + sess.whiteout.clear(); + Ok(json!({ "ok": true, "applied": applied })) + }) +} + +pub fn discard(id: &str) -> Result { + let mut map = sessions().lock().unwrap_or_else(|e| e.into_inner()); + if map.remove(id).is_none() { + return Err(format!("sandbox: unknown session `{id}`")); + } + Ok(json!({ "ok": true })) +} + +pub fn inspect(id: &str) -> Result { + with_session(id, |sess| { + Ok(json!({ + "id": id, + "root": sess.root.to_string_lossy(), + "upper_count": sess.upper.len(), + "whiteout_count": sess.whiteout.len(), + "caps_default": { + "fs_write": true, + "exec": false, + "net": false, + "plugin": false + }, + "notes": [ + "ext/web listen/DB/WS unavailable in sandbox", + "plugin.load denied during sandbox.run", + "subtask path/code/lang unavailable in sandbox" + ] + })) + }) +} + +/// Read file bytes through CoW for an active host sandbox session (lib/fs). +pub fn cow_read_text(ctx: &HostContext, abs: &Path) -> Result, String> { + let Some(id) = ctx.sandbox_session.as_deref() else { + return Ok(None); + }; + with_session(id, |sess| { + let rel = rel_from_root(&sess.root, abs)?; + if sess.whiteout.contains(&rel) { + return Err(format!("read_text: not found (sandbox whiteout): {rel}")); + } + if let Some(bytes) = sess.upper.get(&rel) { + let s = String::from_utf8(bytes.clone()) + .map_err(|e| format!("read_text: not utf-8: {e}"))?; + return Ok(Some(s)); + } + Ok(None) + }) +} + +pub fn cow_write_text(ctx: &HostContext, abs: &Path, text: &str) -> Result { + let Some(id) = ctx.sandbox_session.as_deref() else { + return Ok(false); + }; + with_session_mut(id, |sess| { + let rel = rel_from_root(&sess.root, abs)?; + sess.whiteout.remove(&rel); + sess.upper.insert(rel, text.as_bytes().to_vec()); + Ok(true) + }) +} + +pub fn cow_remove(ctx: &HostContext, abs: &Path) -> Result { + let Some(id) = ctx.sandbox_session.as_deref() else { + return Ok(false); + }; + with_session_mut(id, |sess| { + let rel = rel_from_root(&sess.root, abs)?; + sess.upper.remove(&rel); + sess.whiteout.insert(rel); + Ok(true) + }) +} + +pub fn cow_exists(ctx: &HostContext, abs: &Path) -> Result, String> { + let Some(id) = ctx.sandbox_session.as_deref() else { + return Ok(None); + }; + with_session(id, |sess| { + let rel = rel_from_root(&sess.root, abs)?; + if sess.whiteout.contains(&rel) { + return Ok(Some(false)); + } + if sess.upper.contains_key(&rel) { + return Ok(Some(true)); + } + Ok(None) + }) +} + +fn rel_from_root(root: &Path, abs: &Path) -> Result { + let root_canon = root.canonicalize().unwrap_or_else(|_| root.to_path_buf()); + let abs_canon = abs.canonicalize().unwrap_or_else(|_| abs.to_path_buf()); + let rel = abs_canon + .strip_prefix(&root_canon) + .or_else(|_| abs.strip_prefix(root)) + .map_err(|_| format!("path not under sandbox root: {}", abs.display()))?; + normalize_rel(&rel.to_string_lossy().replace('\\', "/")) +} + +pub fn run( + id: &str, + source: Option<&str>, + path: Option<&str>, +) -> Result { + let (root, body) = with_session(id, |sess| { + let body = if let Some(src) = source.filter(|s| !s.trim().is_empty()) { + src.to_string() + } else if let Some(p) = path.filter(|s| !s.is_empty()) { + let rel = normalize_rel(p)?; + if sess.whiteout.contains(&rel) { + return Err(format!("sandbox_run: path whiteout: {rel}")); + } + if let Some(bytes) = sess.upper.get(&rel) { + String::from_utf8(bytes.clone()) + .map_err(|e| format!("sandbox_run: path not utf-8: {e}"))? + } else { + let abs = abs_under_root(&sess.root, &rel)?; + std::fs::read_to_string(&abs) + .map_err(|e| format!("sandbox_run read {}: {e}", abs.display()))? + } + } else { + return Err("sandbox_run requires `source` or `path`".into()); + }; + Ok((sess.root.clone(), body)) + })?; + + let opts = crate::RunOptions { + allow_fs_write: true, + allow_exec: false, + allow_net: false, + allow_plugin: false, + fs_root: Some(root), + sandbox_session: Some(id.to_string()), + sleep_limit_ms: Some(0), + ..crate::RunOptions::default() + }; + + match crate::run_source(&body, &opts) { + Ok(cap) => { + let value = crate::host::json::value_to_json(&cap.value) + .unwrap_or(serde_json::Value::Null); + Ok(json!({ + "ok": true, + "value": value, + "stdout": cap.stdout, + })) + } + Err(e) => { + let msg = e.to_string(); + Ok(json!({ + "ok": false, + "error": msg, + "value": null, + "stdout": "", + })) + } + } +} + +/// Parse host_query JSON args helper used from plugin.rs. +pub fn query(name: &str, args: &serde_json::Value, ctx: &HostContext) -> Result { + let id = || { + args.get("id") + .and_then(|v| v.as_str()) + .ok_or_else(|| format!("{name}: missing `id`")) + }; + match name { + "sandbox_open" => { + let root = args.get("root").and_then(|v| v.as_str()); + open(root, ctx) + } + "sandbox_write" => { + let path = args + .get("path") + .and_then(|v| v.as_str()) + .ok_or_else(|| "sandbox_write: missing `path`".to_string())?; + let text = args + .get("text") + .and_then(|v| v.as_str()) + .ok_or_else(|| "sandbox_write: missing `text`".to_string())?; + write(id()?, path, text) + } + "sandbox_read" => { + let path = args + .get("path") + .and_then(|v| v.as_str()) + .ok_or_else(|| "sandbox_read: missing `path`".to_string())?; + read(id()?, path) + } + "sandbox_remove" => { + let path = args + .get("path") + .and_then(|v| v.as_str()) + .ok_or_else(|| "sandbox_remove: missing `path`".to_string())?; + remove(id()?, path) + } + "sandbox_diff" => diff(id()?), + "sandbox_commit" => commit(id()?), + "sandbox_discard" => discard(id()?), + "sandbox_inspect" => inspect(id()?), + "sandbox_run" => { + let source = args.get("source").and_then(|v| v.as_str()); + let path = args.get("path").and_then(|v| v.as_str()); + run(id()?, source, path) + } + other => Err(format!("sandbox query unknown `{other}`")), + } +} + +#[allow(dead_code)] +pub fn unavailable(feature: &str) -> String { + format!("{feature} unavailable in sandbox") +} + +/// Used by fs layer when session is active — map Value path through resolve then CoW. +pub fn try_read_value(ctx: &HostContext, path: &Value) -> Result, String> { + let rel = match path { + Value::Text(s) => s.as_str(), + _ => return Ok(None), + }; + let abs = ctx.resolve_path(rel)?; + match cow_read_text(ctx, &abs)? { + Some(s) => Ok(Some(Value::Text(s))), + None => Ok(None), + } +} diff --git a/src/host/sys.rs b/src/host/sys.rs index 8bd7558..2b73a17 100644 --- a/src/host/sys.rs +++ b/src/host/sys.rs @@ -150,6 +150,9 @@ pub fn exec( { use std::process::Stdio; if !ctx.allow_exec() { + if ctx.sandbox_session.is_some() { + return Err("exec unavailable in sandbox".into()); + } return Err("exec denied by host policy".into()); } let cmd = as_text(cmd, "cmd")?; diff --git a/src/lib.rs b/src/lib.rs index d63cbf2..04a929f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -92,6 +92,8 @@ pub struct RunOptions { pub allow_fs_write: bool, pub allow_exec: bool, pub allow_net: bool, + /// Native `plugin.load` (default true for CLI; false inside `sandbox.run`). + pub allow_plugin: bool, /// Exposed via `host_args` / `args`. pub argv: Vec, /// Override filesystem sandbox root (default: source file's directory). @@ -102,6 +104,8 @@ pub struct RunOptions { pub emit_result: Option, /// CLI `--bind KEY=VALUE` pairs for Artifact Metadata Binding (`arg` + overlay). pub binds: Vec<(String, String)>, + /// Attach CoW session for `ext/ai/sandbox` nested runs. + pub sandbox_session: Option, } impl Default for RunOptions { @@ -118,11 +122,13 @@ impl Default for RunOptions { allow_fs_write: true, allow_exec: true, allow_net: true, + allow_plugin: true, argv: Vec::new(), fs_root: None, sleep_limit_ms: None, emit_result: None, binds: Vec::new(), + sandbox_session: None, } } } @@ -154,7 +160,7 @@ impl RunOptions { fs_write: self.allow_fs_write, exec: self.allow_exec, net: self.allow_net, - plugin: true, + plugin: self.allow_plugin, } } } @@ -289,6 +295,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result { host.set_entry_source(Some(path), &source); host.argv = opts.argv.clone(); host.entry_metadata = module.metadata.clone(); + host.sandbox_session = opts.sandbox_session.clone(); if let Some(root) = &opts.fs_root { host.fs_root = Some(root.clone()); host.cwd = root.clone(); @@ -315,6 +322,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result { host.set_entry_source(Some(path), &source); host.argv = opts.argv.clone(); host.entry_metadata = module.metadata.clone(); + host.sandbox_session = opts.sandbox_session.clone(); if let Some(root) = &opts.fs_root { host.fs_root = Some(root.clone()); host.cwd = root.clone(); @@ -351,6 +359,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result { host.set_entry_source(None, source); host.argv = opts.argv.clone(); host.entry_metadata = module.metadata.clone(); + host.sandbox_session = opts.sandbox_session.clone(); if let Some(root) = &opts.fs_root { host.fs_root = Some(root.clone()); host.cwd = root.clone(); @@ -377,6 +386,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result { host.set_entry_source(None, source); host.argv = opts.argv.clone(); host.entry_metadata = module.metadata.clone(); + host.sandbox_session = opts.sandbox_session.clone(); if let Some(root) = &opts.fs_root { host.fs_root = Some(root.clone()); host.cwd = root.clone(); diff --git a/tests/ext/sandbox-cow.mq.md b/tests/ext/sandbox-cow.mq.md new file mode 100644 index 0000000..1987093 --- /dev/null +++ b/tests/ext/sandbox-cow.mq.md @@ -0,0 +1,60 @@ +--- +title: sandbox CoW — write stays upper until commit +description: > + Readable trial: seed on disk, mutate in session, host tree unchanged, + then commit / discard. Prefer link index over json.get. +import sandbox:ext/ai/sandbox.mq.md +import fs:lib/fs.mq.md +--- + +# main + +Prepare a tiny workspace under this test directory (reset leftovers from prior runs). + +**had = fs.exists path="_sbx_cow"** +1. `had` + > fs.remove path="_sbx_cow" +2. * + **_ = 0** + +> fs.make_dir path="_sbx_cow" +> fs.write_text path="_sbx_cow/seed.txt" text=seed-lower + +**sb = sandbox.open root="_sbx_cow"** +**id = [id](sb)** + +Session edits (upper / whiteout only). + +> sandbox.write id=`id` path="seed.txt" text=seed-upper +> sandbox.write id=`id` path="new.txt" text=brand-new +> sandbox.remove id=`id` path="seed.txt" + +**pending = sandbox.diff id=`id`** +**n = len value=`pending`** +> print text=`n` + +Host tree must still show the lower seed; `new.txt` must not exist yet. + +**lower = fs.read_text path="_sbx_cow/seed.txt"** +> print text=`lower` +**ex_new = fs.exists path="_sbx_cow/new.txt"** +> print text=`ex_new` + +Commit applies upper + whiteout. + +> sandbox.commit id=`id` + +**after = fs.read_text path="_sbx_cow/new.txt"** +> print text=`after` +**seed_gone = fs.exists path="_sbx_cow/seed.txt"** +> print text=`seed_gone` + +Discard must not touch the host. + +**sb2 = sandbox.open root="_sbx_cow"** +**id2 = [id](sb2)** +> sandbox.write id=`id2` path="new.txt" text=should-discard +> sandbox.discard id=`id2` + +**kept = fs.read_text path="_sbx_cow/new.txt"** +> print text=`kept` diff --git a/tests/ext/sandbox-deny.mq.md b/tests/ext/sandbox-deny.mq.md new file mode 100644 index 0000000..df1e9e3 --- /dev/null +++ b/tests/ext/sandbox-deny.mq.md @@ -0,0 +1,34 @@ +--- +title: sandbox.run — plugin.load denied; inspect lists notes +description: > + Guest that loads a native plugin must fail with unavailable in sandbox. + No json.get chains — link index + a small expect table. +import sandbox:ext/ai/sandbox.mq.md +--- + +# main + +**sb = sandbox.open root="sandbox-fixtures"** +**id = [id](sb)** + +**ret = sandbox.run id=`id` path="guest-plugin.mq.md"** +**ok = [ok](ret)** +**err = [error](ret)** +> print text=`ok` + +**parts = split value=`err` sep="unavailable in sandbox"** +**hits = len value=`parts`** +1. `hits` > 1 + > print text=deny-ok +2. * + > print text=`err` + +**info = sandbox.inspect id=`id`** +**notes = [notes](info)** +**nn = len value=`notes`** +1. `nn` > 0 + > print text=inspect-ok +2. * + > print text=inspect-missing + +> sandbox.discard id=`id` diff --git a/tests/ext/sandbox-fixtures/guest-json.mq.md b/tests/ext/sandbox-fixtures/guest-json.mq.md new file mode 100644 index 0000000..7919bd1 --- /dev/null +++ b/tests/ext/sandbox-fixtures/guest-json.mq.md @@ -0,0 +1,9 @@ +--- +import json:lib/json.mq.md +--- + +# main + +**m = > json.parse text={"a":1}** +**x = > json.get value=`m` key="a"** +> print text=`x` diff --git a/tests/ext/sandbox-fixtures/guest-plugin.mq.md b/tests/ext/sandbox-fixtures/guest-plugin.mq.md new file mode 100644 index 0000000..26db62d --- /dev/null +++ b/tests/ext/sandbox-fixtures/guest-plugin.mq.md @@ -0,0 +1,8 @@ +--- +import plugin:lib/plugin.mq.md +--- + +# main + +**p = > plugin.native_path name="agent"** +> plugin.load path=`p` diff --git a/tests/ext/sandbox-run-lib.mq.md b/tests/ext/sandbox-run-lib.mq.md new file mode 100644 index 0000000..50ab1d8 --- /dev/null +++ b/tests/ext/sandbox-run-lib.mq.md @@ -0,0 +1,22 @@ +--- +title: sandbox.run — core lib/json inside the trial +description: Guest fixture imports lib/json; print ok and guest stdout via link index. +import sandbox:ext/ai/sandbox.mq.md +--- + +# main + +Open a session on the fixture directory (guest programs live here). + +**sb = sandbox.open root="sandbox-fixtures"** +**id = [id](sb)** + +Run the guest that imports `lib/json` and prints `1`. + +**ret = sandbox.run id=`id` path="guest-json.mq.md"** +**ok = [ok](ret)** +**out = [stdout](ret)** +> print text=`ok` +> print text=`out` + +> sandbox.discard id=`id` diff --git a/tests/gold.rs b/tests/gold.rs index 0ce8bc1..0ceca41 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -2951,6 +2951,41 @@ fn ext_agent_zero_llm() { ); } +#[test] +fn ext_ai_sandbox_cow() { + ensure_agent_plugin_built(); + assert_out( + "tests/ext/sandbox-cow.mq.md", + "2 +seed-lower +False +brand-new +False +brand-new", + ); +} + +#[test] +fn ext_ai_sandbox_run_lib() { + ensure_agent_plugin_built(); + assert_out( + "tests/ext/sandbox-run-lib.mq.md", + "True +1", + ); +} + +#[test] +fn ext_ai_sandbox_deny() { + ensure_agent_plugin_built(); + assert_out( + "tests/ext/sandbox-deny.mq.md", + "False +deny-ok +inspect-ok", + ); +} + #[test] fn ext_llm_named_offline() { let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));