Runbook: Canvas UI (Phase 4)

Running the visual canvas and its live agent streaming.

Prerequisites

docker compose up -d        # incl. redis (event bus) + langfuse
ollama serve
aop serve                   # backend REST + WebSocket on :8000

Start the canvas

cd frontend
pnpm install                # first time only
pnpm dev                    # http://localhost:3000   (or: pnpm build && pnpm start)

Point at a non-default backend with NEXT_PUBLIC_API_BASE.

Use it

1. Palette (left): click to add agent / tool / collection nodes (loaded from the backend /agents, /tools, /collections).
2. Drag nodes; drag between handles to connect data flows.
3. On an agent node: type a task, click ▶ Run. The frontend POSTs /runs, opens /ws/runs/{id}, and the node status + Inspector update live (trace, tool calls, token usage, final answer).
4. Toolbar: backend health badge, Export / Import the canvas JSON, Clear.

How live streaming works

POST /runs → background run publishes events to a Redis Stream run:<id> → WS /ws/runs/{id} tails it. Because it's a Stream (not raw pub/sub), a client that connects after the run starts still replays every event from the beginning.

Troubleshooting

Symptom	Cause	Fix
Palette empty / "Backend offline"	aop serve not running	start it; check NEXT_PUBLIC_API_BASE.
CORS error in browser console	origin not allowed	set AOP_API_CORS_ORIGINS to include the frontend origin.
Run never streams steps	Redis down	docker compose up -d redis; aop diagnose.
node "error" status	agent/tool failed (e.g. Ollama down)	see the Inspector trace; check ollama serve.
next build type errors	stale types	re-run pnpm install; pnpm typecheck.

Verify (CI-style)

cd frontend
pnpm lint
pnpm typecheck
pnpm build