@tianshu-ai/tianshu 0.3.0

package/packages/server/builtinConfig/plugins/files/manifest.json

@@ -0,0 +1,100 @@
+{
+  "id": "files",
+  "version": "0.1.0",
+  "displayName": "Workspace Files",
+  "description": "Browse, read, and upload files in the tenant workspace.",
+  "author": "tianshu-ai",
+  "license": "Apache-2.0",
+  "permissions": ["workspace.read", "workspace.write"],
+  "client": { "entry": "@tianshu-builtin/plugin-files/client" },
+  "server": { "entry": "@tianshu-builtin/plugin-files/server" },
+  "contributes": {
+    "topBarButtons": [
+      {
+        "id": "toggle",
+        "icon": "FolderOpen",
+        "tooltip": "Workspace files",
+        "opensPanel": "files.main",
+        "order": 100
+      }
+    ],
+    "rightPanels": [
+      {
+        "id": "main",
+        "displayName": "Files",
+        "component": "FilesPanel"
+      }
+    ],
+    "composerActions": [
+      {
+        "id": "attach",
+        "icon": "Paperclip",
+        "tooltip": "Attach file",
+        "component": "UploadButton",
+        "order": 100
+      }
+    ],
+    "attachmentRenderers": [
+      {
+        "id": "image",
+        "mimePattern": "image/*",
+        "component": "ImageAttachment",
+        "order": 100
+      },
+      {
+        "id": "any",
+        "mimePattern": "*/*",
+        "component": "FileAttachment",
+        "order": 999
+      }
+    ],
+    "apiRoutes": [
+      { "method": "GET",  "path": "/list",   "handler": "list"   },
+      { "method": "GET",  "path": "/read",   "handler": "read"   },
+      { "method": "GET",  "path": "/raw",    "handler": "raw"    },
+      { "method": "POST", "path": "/upload", "handler": "upload" }
+    ],
+    "tools": [
+      { "id": "list_dir",              "module": "ListDirTool"            },
+      { "id": "read_file",             "module": "ReadFileTool"           },
+      { "id": "write_file",            "module": "WriteFileTool"          },
+      { "id": "edit_file",             "module": "EditFileTool"           },
+      { "id": "glob",                  "module": "GlobTool"               },
+      { "id": "tenant_config_list",    "module": "TenantConfigListTool"   },
+      { "id": "tenant_config_read",    "module": "TenantConfigReadTool"   },
+      { "id": "tenant_config_write",   "module": "TenantConfigWriteTool"  },
+      { "id": "tenant_config_edit",    "module": "TenantConfigEditTool"   },
+      { "id": "tenant_config_delete",  "module": "TenantConfigDeleteTool" },
+      { "id": "tenant_config_glob",    "module": "TenantConfigGlobTool"   }
+    ],
+    "skills": [
+      { "id": "workspace-layout", "path": "skills/files-workspace-layout.md" }
+    ],
+    "systemPromptFragments": [
+      {
+        "id": "workspace-layout",
+        "text": "WORKSPACE LAYOUT\nYour default working directory is the user's private home in this tenant.\n\nPersonal directories (use freely):\n  ./projects/<slug>/   active work; reports, code, deliverables go here.\n  ./uploads/           files the user uploaded for you to look at.\n  ./tmp/               scratch space; clean up after yourself.\n  ./trash/             soft-delete; move things here instead of removing them.\n  ./USER.md            personal preferences (read on demand)."
+      },
+      {
+        "id": "workspace-conventions",
+        "text": "Conventions:\n  - Deliverables go to ./projects/<slug>/, never the home root.\n  - When the user uploads a file, expect it under ./uploads/.\n  - Don't leave scratch artefacts in ./projects/ or the root \u2014 use ./tmp/.\n  - Other users' homes in this tenant are off-limits; you cannot reach them."
+      },
+      {
+        "id": "workspace-references",
+        "text": "Referencing files in your reply:\n  - When you point at a workspace file in your response (e.g. an image you just wrote, a generated report, an attachment), use the workspace:// URI you got back from the fs tool, e.g. `![cover](workspace:///projects/x/cover.png)`.\n  - The chat UI knows how to render those; absolute host paths or bare \"./foo\" links won't preview."
+      },
+      {
+        "id": "edit-vs-write",
+        "text": "- `edit_file` is for changes to an existing file (in-place exact-text replace, atomic). `write_file` is for new files or full rewrites of the entire file. Prefer editing existing files; do not create new files unless asked."
+      },
+      {
+        "id": "edit-old-text-uniqueness",
+        "text": "- Each `edit_file` `old_text` must appear exactly once in the file. Keep `old_text` as small as possible while still being unique \u2014 don't pad with large unchanged regions to \"connect\" two distant changes; emit two separate edits in the same `edits[]` batch instead."
+      },
+      {
+        "id": "read-before-edit",
+        "text": "- Before `edit_file` (or `write_file` overwrite) on a file you haven't seen yet in this session, call `read_file` once. The host tracks reads per session, so a single full-file read covers any number of follow-up `edit_file` / `write_file` calls on that same path \u2014 don't re-read between edits. Files you just created with `write_file` count as already-read; you can `edit_file` them right away without reading first."
+      }
+    ]
+  }
+}

package/packages/server/builtinConfig/plugins/files/skills/files-workspace-layout.md

@@ -0,0 +1,29 @@
+---
+name: files-workspace-layout
+description: Conventions for the per-user workspace this `files` plugin manages — directory roles (projects, uploads, tmp, trash), where deliverables go, what NOT to touch.
+when:
+  toolPresent: read_file
+---
+
+Your default working directory is the user's private home in this tenant.
+Filesystem tools (`list_dir`, `read_file`, `write_file`, `edit_file`, `glob`)
+operate relative to this home (`/` = home).
+
+## Personal directories
+
+| Path | Role |
+|------|------|
+| `./projects/<slug>/` | Active work. Reports, code, deliverables go here. |
+| `./uploads/`         | Files the user uploaded for you to look at. |
+| `./tmp/`             | Scratch space. Clean up after yourself. |
+| `./trash/`           | Soft-delete. Move things here instead of removing them. |
+| `./USER.md`          | Personal preferences (read on demand). |
+
+## Conventions
+
+- Deliverables go to `./projects/<slug>/`, never the home root.
+- When the user uploads a file, expect it under `./uploads/`.
+- Don't leave scratch artefacts in `./projects/` or the root — use `./tmp/`.
+- Other users' homes in this tenant are off-limits; you cannot reach them via
+  these tools.
+- When you make changes, briefly say what you changed in your reply.

package/packages/server/builtinConfig/plugins/microsandbox/manifest.json

@@ -0,0 +1,177 @@
+{
+  "id": "microsandbox",
+  "version": "0.1.0",
+  "displayName": "MicroSandbox",
+  "description": "Per-tenant shell sandbox running on microsandbox (Apple Virtualization.framework / KVM). Provides sandbox.shell + an opt-in browser.cdp sidecar (Stealth Chromium via CloakBrowser + Playwright MCP + noVNC; lit up by a follow-up PR).",
+  "author": "tianshu-ai",
+  "license": "Apache-2.0",
+  "permissions": ["workspace.read", "workspace.write", "process.spawn"],
+  "provides": ["sandbox.shell", "sandbox.taskPool", "browser.cdp"],
+  "client": { "entry": "@tianshu-builtin/plugin-microsandbox/client" },
+  "server": { "entry": "@tianshu-builtin/plugin-microsandbox/server" },
+  "contributes": {
+    "topBarButtons": [
+      {
+        "id": "browser",
+        "icon": "Globe",
+        "tooltip": "Browser viewport (noVNC)",
+        "opensPanel": "microsandbox.browser",
+        "order": 210
+      }
+    ],
+    "rightPanels": [
+      {
+        "id": "browser",
+        "displayName": "Browser",
+        "component": "BrowserViewportPanel"
+      }
+    ],
+    "adminPages": [
+      {
+        "id": "main",
+        "displayName": "Sandbox",
+        "icon": "Box",
+        "component": "MicroSandboxAdminPage",
+        "group": "Plugins",
+        "order": 100
+      }
+    ],
+    "sandboxes": [
+      {
+        "id": "main",
+        "kind": "shell",
+        "displayName": "MicroSandbox",
+        "module": "MicroSandboxRunner"
+      }
+    ],
+    "tools": [
+      { "id": "exec",                  "module": "ExecTool" },
+      { "id": "reset_sandbox",         "module": "ResetSandboxTool" },
+      { "id": "get_sandbox_status",    "module": "GetSandboxStatusTool" },
+      { "id": "update_sandbox_config", "module": "UpdateSandboxConfigTool" },
+      { "id": "build_sandbox",         "module": "BuildSandboxTool" },
+      { "id": "list_sandbox_builds",   "module": "ListSandboxBuildsTool" },
+      { "id": "use_sandbox_build",     "module": "UseSandboxBuildTool" },
+      { "id": "browser_health_check", "module": "BrowserHealthCheckTool" }
+    ],
+    "toolsets": [
+      { "id": "browser", "module": "BrowserToolset", "displayName": "Playwright (Browser)" }
+    ],
+    "skills": [
+      { "id": "exec-howto",     "path": "skills/microsandbox-exec-howto.md" },
+      { "id": "config",         "path": "skills/microsandbox-config.md" },
+      { "id": "build-use",      "path": "skills/microsandbox-build-use.md" },
+      { "id": "browser-howto",  "path": "skills/microsandbox-browser-howto.md" },
+      { "id": "libreoffice",   "path": "skills/microsandbox-libreoffice.md" }
+    ],
+    "systemPromptFragments": [
+      {
+        "id": "no-foreground-servers",
+        "text": "- Long-running servers (`python -m http.server`, `npm start`, `npm run dev`, anything that listens on a port and never returns) WILL hang the `exec` call until the host's per-call timeout fires (5 min default). Even with `nohup` alone the call hangs because microsandbox's exec channel waits for the started process tree's stdio to close, and nohup doesn't close stdin or detach from the controlling terminal.\n\n  If you need to start a server, the ONLY safe pattern is:\n\n    nohup setsid <cmd> > /tmp/srv.log 2>&1 < /dev/null &\n\n  All four pieces are required: `setsid` puts the process in a new session (no controlling terminal); `< /dev/null` closes stdin; `>/tmp/srv.log 2>&1` redirects stdout AND stderr; trailing `&` puts it in the shell background. Skip any one and exec hangs.\n\n  Then verify with `curl http://localhost:<port>/...` in a separate exec call. Don't background-then-curl in the same shell line \u2014 the shell process itself becomes the parent and won't exit."
+      },
+      {
+        "id": "already-installed-runtimes",
+        "text": "- The sandbox already ships chromium (CDP 9222), Playwright MCP (3200), LibreOffice, Node 22, and Python 3.12. Don't `apt install` / `pip install` / `playwright install` what's already there."
+      },
+      {
+        "id": "task-sandbox-is-ephemeral",
+        "text": "- If you are running as a workboard task worker (you have a workboard task id and your run will end with `task_complete`), the sandbox you `exec` in is per-task and gets stopped the moment the task terminates. Anything you nohup / setsid / disown into the background dies with the sandbox \u2014 don't try to leave servers / queues / cron jobs / file watchers running for someone else to consume. Run the work inline, capture its output to a file under your home, then `task_complete` with the file path.\n\n  Concrete VERIFY-task pattern: if the deliverable is an HTML / PDF / image file and you want to confirm it renders, DON'T spin up `python -m http.server` to serve it. Either (a) use a Playwright MCP `browser_navigate` to `file:///workspace/users/<self>/projects/<slug>/report.html` directly (Playwright MCP is configured with `--allow-unrestricted-file-access`, so file:// URLs work), or (b) `cat` / `head` the file and inspect the structure inline, or (c) for charts, check the rendered file's size + that it contains expected canvas/svg/img markup (`grep -c '<canvas\\|<svg\\|<img' report.html`). Spinning up a transient http server adds a process that has to be cleanly torn down before task_complete, and the typical agent forgets the `setsid + </dev/null` pattern and hangs the run.\n\n  Long-lived background services belong in a chat session (the long-lived sandbox there survives between turns), not in a task. Installed packages, files you wrote, and other on-disk state DO survive across attempts of the same task \u2014 only running processes don't."
+      }
+    ],
+    "apiRoutes": [
+      { "method": "GET",  "path": "/status",          "handler": "status" },
+      { "method": "GET",  "path": "/sandboxfile",     "handler": "getSandboxfile" },
+      { "method": "PUT",  "path": "/sandboxfile",     "handler": "putSandboxfile" },
+      { "method": "GET",  "path": "/sandboxfile/templates", "handler": "getSandboxfileTemplates" },
+      { "method": "GET",  "path": "/builds",          "handler": "getBuilds" },
+      { "method": "POST", "path": "/builds",          "handler": "postBuilds" },
+      { "method": "POST", "path": "/builds/use",      "handler": "postUseBuild" },
+      { "method": "POST", "path": "/reset",           "handler": "postReset" },
+      { "method": "POST", "path": "/exec",            "handler": "postExec" },
+      { "method": "GET",  "path": "/task-pool",       "handler": "getTaskPool" },
+      { "method": "POST", "path": "/task-pool/destroy", "handler": "postTaskPoolDestroy" },
+      { "method": "GET",  "path": "/browser/status",   "handler": "getBrowserStatus" },
+      { "method": "POST", "path": "/browser/restart",  "handler": "postBrowserRestart" },
+      { "method": "POST", "path": "/browser/resize",   "handler": "postBrowserResize" }
+    ]
+  },
+  "configSchema": {
+    "fields": [
+      {
+        "key": "memoryMib",
+        "label": "Browser sandbox memory",
+        "kind": "number",
+        "unit": "MiB",
+        "min": 512,
+        "max": 65536,
+        "step": 512,
+        "default": 2048,
+        "description": "RAM allotted to the long-lived Browser sandbox VM. Increase to 8192+ MiB for browser-heavy workloads (chromium + Playwright MCP), 12288+ for build-time pip / npm of large stacks. Restart the sandbox (Reset) for the new value to take effect."
+      },
+      {
+        "key": "cpus",
+        "label": "Browser sandbox vCPU count",
+        "kind": "number",
+        "min": 1,
+        "max": 16,
+        "step": 1,
+        "default": 2,
+        "description": "Logical CPU count handed to the long-lived Browser sandbox VM. Reset the sandbox after changing."
+      },
+      {
+        "key": "execTimeoutMs",
+        "label": "Per-exec timeout (Browser)",
+        "kind": "number",
+        "unit": "ms",
+        "min": 5000,
+        "max": 1800000,
+        "step": 5000,
+        "default": 300000,
+        "description": "Max wall-clock time for one Browser `exec` call before it's force-killed. Bump this for long-running installers; consider running them with `nohup setsid … &` instead."
+      },
+      {
+        "key": "taskMemoryMib",
+        "label": "Task sandbox memory",
+        "kind": "number",
+        "unit": "MiB",
+        "min": 512,
+        "max": 65536,
+        "step": 512,
+        "default": 2048,
+        "description": "RAM allotted to per-task sandbox VMs (forked from the Task snapshot). Set lower than the Browser value to fit more parallel tasks; raise it for tasks that need a heavy data-science stack. Effective on the next task acquire."
+      },
+      {
+        "key": "taskCpus",
+        "label": "Task sandbox vCPU count",
+        "kind": "number",
+        "min": 1,
+        "max": 16,
+        "step": 1,
+        "default": 2,
+        "description": "Logical CPU count handed to each per-task sandbox VM. Effective on the next task acquire."
+      },
+      {
+        "key": "taskExecTimeoutMs",
+        "label": "Per-exec timeout (Task)",
+        "kind": "number",
+        "unit": "ms",
+        "min": 5000,
+        "max": 1800000,
+        "step": 5000,
+        "default": 300000,
+        "description": "Max wall-clock time for one Task `exec` call before it's force-killed. Per-task sandboxes typically run shorter, more focused commands than the Browser sandbox."
+      },
+      {
+        "key": "taskIdleShutdownMs",
+        "label": "Task sandbox idle shutdown",
+        "kind": "number",
+        "unit": "ms",
+        "min": 0,
+        "max": 86400000,
+        "step": 60000,
+        "default": 600000,
+        "description": "How long a task sandbox stays alive after its task ends before it's stopped. 0 = stop immediately on release. Higher values trade RAM for faster reuse when the same kind of task runs again soon."
+      }
+    ]
+  }
+}

package/packages/server/builtinConfig/plugins/microsandbox/skills/microsandbox-browser-howto.md

@@ -0,0 +1,155 @@
+---
+name: microsandbox-browser-howto
+description: How the embedded browser surface works — three agent tools (browser_navigate / browser_snapshot / browser_screenshot), when each is the right pick, and what to do when the tools are not yet available.
+when:
+  toolPresent: browser_navigate
+---
+
+The microsandbox plugin ships an embedded **Stealth Chromium**
+(CloakBrowser) reachable through Playwright MCP, plus a noVNC
+viewport in the admin Browser page. Three agent tools surface that
+stack:
+
+| Tool | Use when |
+|------|----------|
+| `browser_navigate(url)` | You need a real page render — JS, redirects, cookies. Equivalent to `page.goto()`. |
+| `browser_snapshot()` | You want to *act on* the page next. Returns an accessibility tree (roles, names, refs). Cheap, structured, easy to reason about. |
+| `browser_screenshot()` | You need pixels — visual diffing, vision-model prompting, sharing a screenshot back to the user. |
+
+## Don't install another browser
+
+The sandbox **already has** a chromium running on port 9222 (CDP),
+a Playwright MCP server on 3200, and noVNC on 6080. You will
+sometimes feel like reaching for `pip install playwright &&
+playwright install chromium` or `npx playwright install` to do
+your own scripted scrape — don't.
+
+- `playwright install chromium` downloads ~200 MB to the sandbox
+  every time. The sandbox is ephemeral; the next reset throws
+  the download away. Network egress is restricted; the install
+  often hangs or 403s.
+- A second chromium would race the first for `--user-data-dir`,
+  CDP port 9222, and X11 display :99.
+- The MCP tools (`browser_navigate`, etc.) already cover the 90%
+  case more cheaply than a hand-rolled Playwright script.
+
+Use the MCP tools first. If you genuinely need scripted control
+(login flows with conditional logic, multi-step forms),
+connect to the existing chromium via CDP from inside the sandbox
+shell:
+
+```python
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    # Reuse the already-running browser — no install step.
+    browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")
+    page = browser.contexts[0].new_page()
+    page.goto("https://example.com")
+    print(page.title())
+```
+
+`pip install playwright` (the Python package) is fine — it's
+small. **Skip the `playwright install` step**. You're connecting
+to an existing browser, not launching a new one.
+
+## Default workflow
+
+```
+1. browser_navigate("https://…")
+2. browser_snapshot()                 # find the element to act on
+3. browser_screenshot()               # only if you need the picture
+```
+
+Snapshots beat screenshots whenever the model needs to *interact*
+or *extract*. Screenshots are best treated as a presentation
+format, not a comprehension format.
+
+## Tool availability
+
+These tools are gated on the BrowserSidecar reporting a live
+Playwright MCP port. If the chromium stack isn't built into the
+tenant's Sandboxfile yet, the tools won't show up in your tool
+list — there's no point trying to fall back to them.
+
+If the user wants to use the browser:
+
+1. They open `/admin/microsandbox/browser` and check **Status**.
+2. If "not running", they edit the Sandboxfile (Sandbox admin
+   page) to include the browser layer (CloakBrowser + Xvfb +
+   x11vnc + noVNC + Playwright MCP), build, then `use & reset`.
+3. Once the admin page reports `ready: true` with three live
+   ports, your tool list reloads and `browser_*` tools show up.
+
+Don't tell the user "I'll navigate" before the tools are available
+— the call will return a structured error and waste a turn.
+
+## Coordinates and viewports
+
+When the user has the admin Browser page open, the noVNC iframe
+reports its size back to the host via a ResizeObserver, and that
+viewport is reachable through `browser.cdp`'s `getLastViewport()`.
+The browser tools auto-set Playwright's viewport from this before
+each navigation, so screenshots match what the user sees.
+
+If the user is **not** watching the page (no admin tab open), the
+viewport falls back to `1280x800`. Don't write skills that
+hard-code coordinates — they'll only work for one viewport.
+
+## When the browser tools hang
+
+If a `browser_*` call returns a confusing timeout / error, or
+`exec` itself sticks (the symptom is "the conversation just
+stops emitting tokens for 30+s"), call:
+
+```
+browser_health_check()
+```
+
+It probes CDP `/json/version` with a 2.5s timeout and returns
+`{ok, latencyMs, error?, suggestion?}`. The `suggestion` field
+tells you the next concrete recovery step:
+
+- **CDP host port not mapped**: the snapshot you booted doesn't
+  ship the browser stack. Build one that does (template
+  `browser.yaml`).
+- **CDP not reachable / connect refused**: chromium or
+  supervisord crashed inside the guest. Try `browser_restart`
+  first (cheap, ~5s). If the next `browser_health_check` still
+  fails, escalate to `reset_sandbox`.
+- **CDP probe timed out**: the sandbox VM itself is wedged.
+  Skip `browser_restart` (it'll hang too) and go straight to
+  `reset_sandbox`. Files under `/workspace` survive.
+
+Don't loop the probe — call once, act on the suggestion, call
+again only after attempting recovery.
+
+## What NOT to do
+
+- Don't `browser_navigate` to user input as a URL without
+  validating the scheme. Stick to `https://` for arbitrary user
+  input; if the user explicitly asks for a local resource (a
+  service running in the same sandbox), confirm `http://localhost`
+  is intended.
+- Don't `browser_screenshot` without `browser_navigate` first —
+  the tool will return whatever the page state was, which may be
+  blank or the previous user's content.
+- Don't paste large snapshot blobs back into the chat verbatim.
+  Summarise: "the page has a search box (ref=e3) and a list of 12
+  results (refs=e7..e18)" is much more useful than 4 KB of AX
+  JSON.
+- Don't expect the embedded chromium to share cookies with the
+  user's host browser. Each sandbox has an isolated profile;
+  authenticated sessions need to be performed inside the sandbox
+  (e.g. via `browser_navigate` to a login URL the user trusts).
+
+## Why CloakBrowser instead of stock Chromium
+
+Stock headless chromium leaks several automation tells (navigator.
+webdriver, headless UA, missing GPU/WebGL profile, abnormal
+plugin/font lists). CloakBrowser patches those at the C++ source
+level, so common bot-detection sites don't refuse the page. Same
+Playwright API, drop-in `launch()` replacement.
+
+This does **not** mean you can ignore site terms of service.
+Realistic fingerprints help compatibility, not authorisation. If a
+site's TOS forbids automated access, that's still a no.

package/packages/server/builtinConfig/plugins/microsandbox/skills/microsandbox-build-use.md

@@ -0,0 +1,201 @@
+---
+name: microsandbox-build-use
+description: How to author a Sandboxfile, build a snapshot, sanity-check it, then switch the tenant to use it. Covers the build → preview → use → reset loop and the common failure modes.
+when:
+  toolPresent: build_sandbox
+---
+
+The sandbox image you customize via a Sandboxfile. Three tools cooperate:
+
+| Tool | What it does |
+|------|--------------|
+| `build_sandbox` | reads the Sandboxfile, boots a builder VM, runs the steps, captures a snapshot, writes build metadata. **Does not** affect the live sandbox. |
+| `list_sandbox_builds` | lists past builds (newest first), with which one is currently in use. |
+| `use_sandbox_build(build_id)` | switches the tenant pointer to that build. The next `reset_sandbox` (or process restart) boots the new VM `fromSnapshot(...)`. Tenant-scoped — does not publish anything outside the tenant. |
+
+## Sandboxfile location
+
+`<your-userHomeDir>/sandbox/Sandboxfile`. Use `write_file("/sandbox/Sandboxfile", "...")` to author it; `build_sandbox` reads from there by default.
+
+## Sandboxfile grammar (v0)
+
+```yaml
+image: python:3.12-slim          # required: any OCI image microsandbox can pull
+cpus: 4                          # optional, default 4
+memory_mib: 4096                 # optional, default 4096
+
+# Pre-installed layers, applied in this order. All optional.
+apt:
+  - libreoffice-writer
+  - fonts-noto-cjk
+pip:
+  - pandas
+  - numpy
+npm:
+  - tsx
+  - typescript
+
+# Free-form shell commands, run last, in array order.
+exec:
+  - sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources
+  # Multi-source fallback for the Node tarball. nodejs.org first,
+  # npmmirror as backup. --connect-timeout / --max-time keep curl
+  # from hanging when a mirror RSTs mid-download.
+  - |
+    bash -c '
+      set -eu; VER=v22.20.0; F=node-${VER}-linux-arm64.tar.xz
+      for u in https://nodejs.org/dist/${VER}/${F} \
+               https://npmmirror.com/mirrors/node/${VER}/${F} \
+               https://registry.npmmirror.com/-/binary/node/${VER}/${F}; do
+        echo "[node] trying $u"
+        if curl -fsSL --retry 3 --retry-delay 5 --retry-all-errors \
+             --connect-timeout 30 --max-time 600 "$u" \
+           | tar -xJ -C /usr/local --strip-components=1; then
+          echo "[node] installed from $u"; exit 0
+        fi
+      done
+      echo "[node] all sources exhausted" >&2; exit 1
+    '
+```
+
+The four list slots are convenience wrappers: `apt`/`pip`/`npm` produce one
+combined `apt-get install -y --no-install-recommends ...` (or pip / npm)
+call. Anything more complex goes in `exec`.
+
+## The full lifecycle
+
+```
+1. write_file("/sandbox/Sandboxfile", "...")
+2. build_sandbox()                      # 30s–10min; returns build_id
+3. (sanity-check via the admin /shell preview, or via tools below)
+4. use_sandbox_build(build_id)          # writes tenant pointer
+5. reset_sandbox()                      # live VM picks up the new snapshot
+```
+
+You can also sanity-check from the agent: tools work the same against
+the build snapshot as against any image (the agent doesn't have a
+preview-exec equivalent yet — that's an admin UI feature). For agent
+flow, the cheap heuristic is: trust the build log tail
+(`build_sandbox` returns it) for "did the install command succeed?",
+then `use_sandbox_build` + `reset_sandbox`, then run real verification
+commands via `exec`.
+
+## Common failure modes
+
+### apt step "succeeds" but the package isn't there
+Usual cause: a step like `echo node=$(node --version)` swallows the
+inner failure because `echo` exits 0 even with `$()` empty. **Verify
+with `bash -c`**:
+
+```yaml
+exec:
+  - bash -c "node --version && npm --version && libreoffice --version | head -1"
+```
+
+`bash -c` propagates the inner `&&` failure; the build fails properly.
+
+### Slow apt
+Default Debian mirrors are slow from CN. First exec step should swap to
+a regional mirror:
+
+```yaml
+exec:
+  - sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources
+  - apt-get update -qq
+  # …rest of your apt installs as a *single* exec line, or via the apt: list
+```
+
+If you're using the `apt:` list slot, the runner already issues
+`apt-get update`; the `sed` line in `exec` happens before that, so the
+update sees the fast mirror.
+
+### apt's nodejs is too old
+Debian bookworm ships Node 18; modern packages need 20+. Skip the apt
+nodejs and grab a binary from a CN mirror:
+
+```yaml
+exec:
+  - DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends curl ca-certificates xz-utils
+  # Multi-source fallback — don't rely on a single CN mirror; it
+  # WILL flake. nodejs.org first, npmmirror as backup.
+  - |
+    bash -c '
+      set -eu; VER=v22.20.0; F=node-${VER}-linux-arm64.tar.xz
+      for u in https://nodejs.org/dist/${VER}/${F} \
+               https://npmmirror.com/mirrors/node/${VER}/${F} \
+               https://registry.npmmirror.com/-/binary/node/${VER}/${F}; do
+        echo "[node] trying $u"
+        if curl -fsSL --retry 3 --retry-delay 5 --retry-all-errors \
+             --connect-timeout 30 --max-time 600 "$u" \
+           | tar -xJ -C /usr/local --strip-components=1; then
+          echo "[node] installed from $u"; exit 0
+        fi
+      done
+      echo "[node] all sources exhausted" >&2; exit 1
+    '
+  - npm config set registry https://registry.npmmirror.com
+```
+
+(`linux-arm64` because microsandbox on Apple Silicon is arm64; for
+x86_64 hosts use `linux-x64`.)
+
+### LibreOffice + CJK font rendering hangs
+You also need `fontconfig` and a fontconfig refresh:
+
+```yaml
+exec:
+  - DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends fontconfig fonts-noto-cjk libreoffice-writer
+  - fc-cache -fv
+```
+
+Without `fc-cache`, the first LibreOffice invocation can spend 30+s
+rebuilding the font index (and sometimes hangs in our setup).
+
+### Snapshot lost between sessions
+`use_sandbox_build` writes a tenant pointer; the live VM only picks
+it up on `reset_sandbox`. If you switch but skip the reset, the next
+agent turn still runs the old image. The user's admin UI has a
+one-click "Use & Reset" button that does both; from the agent always
+pair them.
+
+## Snapshot retention
+
+Snapshots live in microsandbox's local store under
+`~/.microsandbox/snapshots/<name>/`. They are *not* garbage-collected
+automatically in v0; build a lot and you'll fill the disk. Old builds
+can be removed manually with `rm -rf` on that path (no agent tool yet).
+
+The disk-format pointer file (`<tenant>/_tenant/sandbox/current.json`)
+still uses the field names `publishedAt`/`publishedBy` for backwards
+compatibility with existing tenants. The user-facing terminology is
+"in use" / "switch"; the on-disk fields are an implementation detail.
+
+## Pre-flight checklist
+
+Before calling `build_sandbox`, double-check:
+
+- [ ] You wrote the Sandboxfile (`write_file("/sandbox/Sandboxfile", ...)`),
+      not just discussed it.
+- [ ] Final verification step uses `bash -c "<chained checks>"`, not bare
+      `echo $(...)` (silent-failure trap).
+- [ ] If installing user-space binaries (Node, Go, …) you used a regional
+      mirror — default mirrors are too slow inside the sandbox network.
+- [ ] You explicitly want this image — check with the user if you're
+      switching the tenant's in-use build; that affects every future
+      agent turn.
+
+## What NOT to do
+
+- Don't call `use_sandbox_build(build_id)` without first reading
+  `list_sandbox_builds` to confirm the snapshot still exists.
+- Don't run multi-stage workflows (download → compile → install) inline
+  in the verification step — separate them. A failed download in line
+  N+1 is much easier to debug than one of three commands chained
+  through `&&`.
+- Don't rely on `apt-get install` exit code alone to confirm the
+  package works; the install can succeed but the binary may not be on
+  `PATH`. Always test with `which <bin>` or `<bin> --version`.
+- Don't `npm install -g <pkg>` immediately after `npm install -g
+  npm@latest` in the same `exec` line — npm may relink during upgrade
+  and the second call sees a half-installed registry. Split into two
+  `exec` lines.