workboard plugin

workboard is a built-in plugin that turns a single agent's outward-facing state into a structured snapshot for Console aggregation and UI consumers.

This page remains as a command entry point. For the fuller plugin structure, see Plugin Overview, Built-in Plugins Today, and Plugin HTTP Injection.

What it shows

• Whether the agent is currently unfolding, pausing, or idle
• Whether there has been a recent update
• Public-safe fuzzy cues
• A high-level summary that avoids leaking internal context

When to use it

• You want to see what kinds of states your agents are presenting right now
• You want a recent-change surface across the whole agent group in Console
• You want to wire this public-facing state into a custom host or UI SDK surface

Runtime endpoint

When the agent is running, workboard exposes:

• GET /api/workboard/snapshot

The endpoint returns structured JSON, but only as a public-safe high-level projection. It does not expose internal session, service, task, path, or model details.

Console behavior

Console aggregates workboard snapshots from all agents into a dedicated global game world:

• open Workboard from the main Console navigation in the sidebar
• the main stage is a Smallville-style pixel town atlas with a central plaza, four open state buildings, trunk roads, water edges, fences, and terrain boundaries
• entering a state cluster switches into that building's own interior map, with distinct walls, doors, corridors, stations, hub placement, and themed furniture per room
• the map uses a fixed 40 x 24 tile world canvas; normal view keeps the full stage visible, while fullscreen uses cover scaling to fill the whole screen and always preserves square pixel blocks
• the bottom portal rail lets you switch state clusters directly, with a pixel portal transition when entering a room
• agents appear as directional sprites with compact state glyphs while patrolling corridors, gates, and stations
• rooms highlight the focused sprite's quest path, station, and hub relationship
• the atlas supports keyboard-style map control: left/right switch clusters, Enter opens, and Esc returns to the world
• public quest entries become an in-room wall board, while station positions become a blueprint table inside the map instead of extra dashboard cards
• click a cluster to enter it, then click a specific sprite to inspect its public-facing fragments
• the right codex log follows the current focus and shows public-safe state and cues

UI SDK mapping layer

If you use @downcity/ui, you can now do more than render the default Workboard component. The package also exports:

• buildWorkboardGameMapConfig

It maps the public snapshot into a full game-map model, including:

• state-cluster zones
• agent actors
• atlas corridors
• interior patrol routes
• atlas gates and interior stations
• scene props and area labels

That lets you keep the default Downcity pixel game world or feed the same public-safe state into your own custom host renderer.

Notes

• workboard ships as a built-in plugin
• if you disable the plugin, the snapshot endpoint becomes unavailable
• the current version is based on deterministic collection instead of extra model inference
• the current version is intentionally designed for external display, so it only exposes high-level public state

Related

• city plugin
• Plugin Docs Overview