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 <cursoragent@cursor.com>
This commit is contained in:
1 parent
1bb16dd6db
commit
63bcb882a6
24 files changed
+1483
-2
No files matched your search
@@ -87,3 +87,6 @@ tests/ext/:memory:
|
||||
|
||||
# local secrets
|
||||
.env
|
||||
|
||||
# sandbox gold leftovers
|
||||
tests/ext/_sbx_cow/
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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**(规划) |
|
||||
|
||||
@@ -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`.
|
||||
@@ -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 │
|
||||
│ └────────────────────┘
|
||||
▼
|
||||
真实工作区 / <!-- marqdo-out -->
|
||||
(代码即文档真相源)
|
||||
|
||||
(可选)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/*`**。
|
||||
@@ -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`;用户不可见 |
|
||||
|
||||
|
||||
@@ -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/*`
|
||||
@@ -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`*
|
||||
@@ -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`*
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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");
|
||||
+14
-1
@@ -34,6 +34,9 @@ fn text_body(v: &Value) -> Result<&str, String> {
|
||||
|
||||
pub fn read_text(ctx: &HostContext, path: &Value) -> Result<Value, String> {
|
||||
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<Value
|
||||
return Err("write_text denied by host policy".into());
|
||||
}
|
||||
let p = ctx.resolve_path(text_path(path)?)?;
|
||||
let body = text_body(text)?;
|
||||
if crate::host::sandbox_fs::cow_write_text(ctx, &p, body)? {
|
||||
return Ok(Value::None);
|
||||
}
|
||||
if let Some(parent) = p.parent() {
|
||||
fs::create_dir_all(parent).map_err(|e| format!("write_text mkdir: {e}"))?;
|
||||
}
|
||||
fs::write(&p, text_body(text)?).map_err(|e| format!("write_text {}: {e}", p.display()))?;
|
||||
fs::write(&p, body).map_err(|e| format!("write_text {}: {e}", p.display()))?;
|
||||
Ok(Value::None)
|
||||
}
|
||||
|
||||
@@ -68,6 +75,9 @@ pub fn append_text(ctx: &HostContext, path: &Value, text: &Value) -> Result<Valu
|
||||
|
||||
pub fn exists(ctx: &HostContext, path: &Value) -> Result<Value, String> {
|
||||
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<Value, String> {
|
||||
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 {
|
||||
|
||||
@@ -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<String>,
|
||||
}
|
||||
|
||||
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,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -120,6 +120,9 @@ pub fn http_get(
|
||||
headers: Option<&Value>,
|
||||
) -> Result<Value, String> {
|
||||
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<Value, String> {
|
||||
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<Value, String> {
|
||||
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();
|
||||
|
||||
@@ -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<Value, String> {
|
||||
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")?;
|
||||
|
||||
@@ -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<String, Vec<u8>>,
|
||||
pub whiteout: HashSet<String>,
|
||||
}
|
||||
|
||||
static SESSIONS: OnceLock<Mutex<HashMap<String, CowSession>>> = OnceLock::new();
|
||||
static SEQ: OnceLock<Mutex<u64>> = OnceLock::new();
|
||||
|
||||
fn sessions() -> &'static Mutex<HashMap<String, CowSession>> {
|
||||
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<String, String> {
|
||||
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<PathBuf, String> {
|
||||
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<serde_json::Value, String> {
|
||||
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<F, T>(id: &str, f: F) -> Result<T, String>
|
||||
where
|
||||
F: FnOnce(&mut CowSession) -> Result<T, String>,
|
||||
{
|
||||
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<F, T>(id: &str, f: F) -> Result<T, String>
|
||||
where
|
||||
F: FnOnce(&CowSession) -> Result<T, String>,
|
||||
{
|
||||
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<serde_json::Value, String> {
|
||||
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<serde_json::Value, String> {
|
||||
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<serde_json::Value, String> {
|
||||
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<serde_json::Value, String> {
|
||||
with_session(id, |sess| {
|
||||
let mut items: Vec<serde_json::Value> = 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<serde_json::Value, String> {
|
||||
with_session_mut(id, |sess| {
|
||||
let mut applied = 0i64;
|
||||
let writes: Vec<(String, Vec<u8>)> = sess
|
||||
.upper
|
||||
.iter()
|
||||
.map(|(k, v)| (k.clone(), v.clone()))
|
||||
.collect();
|
||||
let removes: Vec<String> = 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<serde_json::Value, String> {
|
||||
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<serde_json::Value, String> {
|
||||
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<Option<String>, 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<bool, String> {
|
||||
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<bool, String> {
|
||||
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<Option<bool>, 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<String, String> {
|
||||
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<serde_json::Value, String> {
|
||||
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<serde_json::Value, String> {
|
||||
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<Option<Value>, 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),
|
||||
}
|
||||
}
|
||||
@@ -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")?;
|
||||
|
||||
+11
-1
@@ -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<String>,
|
||||
/// Override filesystem sandbox root (default: source file's directory).
|
||||
@@ -102,6 +104,8 @@ pub struct RunOptions {
|
||||
pub emit_result: Option<std::path::PathBuf>,
|
||||
/// 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<String>,
|
||||
}
|
||||
|
||||
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<RunCapture> {
|
||||
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<RunCapture> {
|
||||
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<RunCapture> {
|
||||
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<RunCapture> {
|
||||
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();
|
||||
|
||||
@@ -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`
|
||||
@@ -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`
|
||||
@@ -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`
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
import plugin:lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**p = > plugin.native_path name="agent"**
|
||||
> plugin.load path=`p`
|
||||
@@ -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`
|
||||
@@ -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"));
|
||||
|
||||
Reference in new issue
Block a user