# Canvas Agent native runtime

Agent/Auto Agent (including presets and both canvas types) invokes the unmodified
Apache-2.0 ZCode CLI. Its own model loop, scheduler, context management, sessions,
MCP, skills, memory and subagent tools execute in the task sandbox. Claw retains
its existing route. `lib/ai/canvas-agent-runtime/loop.ts` is a legacy regression
fixture and is not the Agent production execution owner.

## Build and provision

Build the official `zai-org/ZCode` repository at commit
`0a1fc56d279fd1001f78387bd81aec1c26767411` with Node 24 and its frozen lockfile:
`pnpm install --frozen-lockfile --ignore-scripts --filter '@zcode/cli...'`, then
`pnpm --filter '@zcode/cli...' build`. From this project run
`node scripts/zcode-agent/stage-runtime.mjs UPSTREAM_PATH RUNTIME_PATH`.
The stage checks the source commit and unmodified source, includes upstream
license/notices and pins the CLI bundle checksum in `manifest.json`.

Production needs Linux, systemd cgroups, bubblewrap, setpriv and a verified
Linux Node 24 binary in `RUNTIME_PATH/bin/node`. Keep the immutable runtime owned
by root and outside task directories. No Docker image or global Node upgrade is
required. Configure the project service:

- `CANVAS_ZCODE_RUNTIME_DIR=/opt/yedir-canvas-zcode/current`
- `CANVAS_ZCODE_STATE_DIR=/var/lib/yedir-canvas-agent`
- `CANVAS_ZCODE_NODE_PATH=/opt/yedir-canvas-zcode/current/bin/node`

Apply the additive `0104_add_canvas_agent_runs.sql` migration before the new
route is used. The host service launches a scope, drops to a unique numeric task
UID and starts unshared mount/user/PID/network/IPC namespaces. Each task mounts
only its workspace/home, read-only runtime/system binaries and its exact broker
socket. Provider/database/storage secrets remain in the authenticated host
adapter. Cgroups impose 1 GiB memory, 128 tasks and two CPU cores; the runner also
enforces wall time, output and workspace budgets. Missing sandbox components
fail closed. macOS development uses Seatbelt with the same private file scopes
and only the exact task broker TCP port; it does not provide Linux cgroup quotas.

All registered canvas business capabilities are exposed through task-scoped MCP.
Ownership, enabled backend services, quotas and explicit destructive intent are
still checked by the host. Local file selection and UI-only panels need the user
browser; unimplemented backend functions report their limitation rather than
claiming completion. Tools cannot request an arbitrary host command or model URL.

## Recovery and verification

`CanvasAgentRun` stores ownership, leases, tool call identifiers and outputs,
cancellation/supplements, verification, native session ID and runtime provenance.
The CLI's private session files allow explicit resume. A tool is checkpointed
before execution; an unknown paid outcome prevents automatic resubmission.
Client disconnection does not abort accepted business work. Keep task directories
for resumable runs; monitor their disk usage and remove only stopped, expired
runs after their recovery window. Preserve active and immediately previous runtime
releases while rolling out or rolling back.

With `ZCODE_FIXTURE_RUNTIME` pointing to the built runtime, run
`pnpm test:zcode-agent` and `pnpm test:canvas-agent`. Native tests exercise the
actual CLI with a deterministic model, actual MCP, resume and OS isolation;
the adapter fixture checks idempotency, schema validation, repair scope and
uncertain results. These fixtures do not prove a configured real provider is
healthy. A release also needs a real-provider test on a private image and video
canvas, authentication/ownership probes and static-resource checks before
switching the active Next build.

Current authorization: video canvas and storyboard Agent access is paused by the user. Image canvas and non-video project tools remain authorized; the real project workspace is checked server-side, so forged client mode cannot enable video. Full per-entry audit: authorization-audit.json / authorization-audit.html.