ai-chatbot/services/zcode-agent/README.md

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.