63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
# 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.
|