dsh-wayfinder-ui
A tracker-agnostic Wayfinder runner plugin for DeepSeek Harness (DSH): every new session learns a three-verb registration contract, maps live in a per-workspace registry file at .wayfinder-runner/state.json (committed), and the UI polls /dsh-wayfinder/state.json.
When to reach for it
You chart Wayfinder maps for DSH work and want every ready task picked up by its own top-level session while the dependency map tracks progress live — regardless of where the tasks are tracked (dex, Jira, GitHub issues, markdown files).
Prerequisites
- Node.js ≥22 (see
engines in package.json)
- DSH with the web profile (
~/.dsh/profiles/web/)
pnpm or npm for local development
Install
# 1. Clone anywhere
git clone https://github.com/andrepontesmelo/dsh-wayfinder-ui.git
# 2. Symlink into the web profile
ln -s /path/to/dsh-wayfinder-ui ~/.dsh/profiles/web/node_modules/dsh-wayfinder-ui
Append the plugin row to ~/.dsh/profiles/web/cordis.patch.yml:
- insert:
- id: wayfinder
name: 'dsh-wayfinder-ui'
Spawned sessions inherit the spawning session's route (provider/model); optional provider/model arguments on wayfinder_spawn_session override that inheritance per call.
They join the spawning session's workspace as well; when the caller is Ungrouped — or the wayfinder root lies outside the caller's own workspace directory, which upstream attach validation rejects — the spawned session stays Ungrouped instead of being forcibly regrouped.
Restart the GUI. The model tools and the map panel both load on startup.
npm: npm install dsh-wayfinder-ui is planned after manual validation — GitHub is the install source until then.
It's working if
- A fresh session receives the three-verb contract on startup, and Settings → Wayfinder lists the toggles.
wayfinder_map_create writes .wayfinder-runner/state.json and the right rail renders your map's task rows.- An approved spawn opens one top-level session per ready task, and a worker's
wayfinder_task_resolve flips its row to done.
Tools
All seven are model-callable once the plugin is installed.
- wayfinder_snippet — prints the protocol: propose ready wayfinder tasks to the human, ask for explicit approval, then call
wayfinder_spawn_session exactly once. Never spawn without approval. It also documents the seed-message format and the route-inheritance rule.
- wayfinder_spawn_session — spawns one top-level DSH session per ready task, in parallel. Tasks come from the registry frontier: omit
tasks to spawn every ready task (derived status todo; done and blocked-by-undone rows are skipped). Each seed carries a Task locator line pointing at where the task's work lives, so workers find their real tickets wherever they are tracked — dex, Jira, GitHub issues, markdown files. Each spawned session joins the spawning session's workspace and inherits its route; pass optional provider/model to override per call.
- wayfinder_map_create — charts a new map into the registry: validates
tasks: [{id, title, type?, locator, blockedBy?}], persists it at <root>/.wayfinder-runner/state.json, and makes it the selected open map.
- wayfinder_task_resolve — marks one task done because a worker finished it (the worker-report path), stamping the reporting session onto the row.
- wayfinder_task_set_status — manual override of one task's status (
todo|done|running|waiting|blocked). Prefer wayfinder_task_resolve for worker completion reports.
- wayfinder_map_sync — create-or-replace a map by name with a complete task list; also registered as the
/wayfinder-map-sync recovery hatch.
- wayfinder_grilling_start — report that a grilling task's session has begun grilling a batch and awaits the user. Stamps
grillingSince on the row, which lights a flame in the panels (right rail + in-session card); wayfinder_task_resolve clears it. Grilling-typed spawns carry the instruction in their seed.
How it works
- Chart —
wayfinder_map_create validates the task list and persists the map as the selected open map of the workspace registry.
- Spawn — each approved task gets a top-level DSH session seeded with
/wayfinder work on task (TASK_ID) of map (MAP_NAME) (the leading /wayfinder gesture makes the harness inject the skill content, exactly as if the human typed the slash command) plus its Task locator line.
- Report — workers finish by calling
wayfinder_task_resolve, which marks their task done and links the reporting session.
- Derive —
done comes from reports/manual overrides, blocked from blockedBy edges, and running/waiting are computed live from the spawned sessions (running agent; idle agent whose newest model-visible event is an assistant message).
- Restart — the plugin reloads the state file:
selectedMapId wins (falling back to the newest open map), and sessions re-associate with their rows by matching the seeded message.
Surfaces
- In-session card — the collapsible To-dos-style card above the composer renders only in the session that charted the map: the payload carries
createdBySessionId, and the dock compares it against its own session. A map without a stamped owner (hand-written registry) shows no card anywhere; call wayfinder_map_sync once from your session to claim it.
- Right rail and ambient sidebar badges stay workspace-wide on purpose: mission control should be visible from every session. Both remain individually togglable in Settings → Wayfinder.
- Session links — task rows on the rail (and on an expanded card) carry an ↗ link when a session is spawned for that row; clicking opens that session, exactly like clicking its sidebar row.
- Grilling flames — one 🔥 per live grilling batch: a grilling-typed session calls
wayfinder_grilling_start when it starts grilling and waits for you; the rail and card show a flame pill (N grilling) plus a per-row flame until the task resolves.
Development
pnpm install
npm test # node --test
Known limitations
- Web profile only: the card, right rail, and sidebar badges live in the DSH GUI.
- Spawns target the registry's selected open map (
selectedMapId, falling back to the newest open map).
License
MIT © 2026 Andre Melo
