Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(canvas-control): tell agents a display verb does not move the view, and is never queued
Bas Miliusf7abdee87bca
diff --git a/src/core/canvas-control-core.ts b/src/core/canvas-control-core.tsindex d3420525d..1828a5208 100644--- a/src/core/canvas-control-core.ts+++ b/src/core/canvas-control-core.ts@@ -379,6 +379,11 @@ export function buildCanvasControlInstructions(shimPath: string): string {'- `show-image <path>` / `show-video <path>` — open a media file as a node.','- `show-web (--url U | --file P.html | --html "<...>")` — open a web viewer.','- `open-browser --url U` — open a navigable browser node.',+ ' These four NEVER switch the user\'s view either. If your project is not on screen the node is',+ ' saved into it and waits there — the reply says which project, and adds `offCanvas: true`.',+ ' Nothing is queued: unlike a session, a page or an image is finished the moment it is placed,',+ ' so there is nothing to wait for and nothing to poll. Say where it went rather than assuming',+ ' the user saw it.','- `group --nodes <id,id> [--label L] [--color C]` — wrap sibling nodes or sibling groups in a new labeled frame.',' Every id must share one container. `ungroup --group <id>` dissolves a frame and promotes its direct',' children into the frame\'s parent. `move --nodes <id,id> [--group <id>]` reparents nodes or groups INTO an',@@ -834,6 +839,12 @@ Verbs:- \`show-video <path>\` — open a video file as a player node.- \`show-web (--url U | --file P.html | --html "<...>")\` — open a web viewer (live URL or local HTML you wrote).- \`open-browser --url U\` — open a navigable browser (back/forward/address bar) at a URL.+ **These four never switch the user's view either.** If the project you are running in is not the+ one on screen, the node is saved into it and waits there; the reply names the project and carries+ \`offCanvas: true\`, and if that project is **closed** it says so — the tab is not reopened for+ you. Nothing here is ever \`queued\`: unlike a session, a page, a video or an image is finished+ the moment it is placed, so there is nothing to wait for and nothing to poll. What this costs you+ is the assumption that the user saw it — tell them where it went.In an SSH project, nodes you open run on the HOST (same machine as you). The media viewersrender on the DESKTOP: \`show-image\` and \`show-video\` still work with a host path (thefile is read/fetched back over the connection), but \`show-web --file/--html\` is refused —diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.tsindex 41cd89dfa..1f5088f00 100644--- a/src/main/canvas-control-core.test.ts+++ b/src/main/canvas-control-core.test.ts@@ -741,4 +741,23 @@ describe('the --project clause tells the truth about travel (review #363 I-1 + Mexpect(body, `${name}: tab not reopened`).toMatch(/not reopened/i)}})++ it('both bodies say the DISPLAY verbs do not switch the view either — and are never queued', () => {+ // The second half of the same promise, and the half an agent meets most often: a skill that+ // renders its report as HTML reaches for `show-web` every time it finishes. Two facts it acts+ // on, and the second is why these are not folded into the cold-open sentence: the node is+ // COMPLETE when placed, so a caller told "queued" would wait for something that has already+ // happened. The `offCanvas` field is what it reads instead.+ for (const [name, body] of bodies) {+ const start = body.indexOf('`show-image')+ const end = body.indexOf('`group --nodes', start)+ expect(start, `${name}: the display-verb entries`).toBeGreaterThan(-1)+ expect(end, `${name}: the group entry after them`).toBeGreaterThan(start)+ const clause = body.slice(start, end)+ expect(clause, `${name}: never switches the view`).toMatch(/never switch(es)? the user'?s view/i)+ expect(clause, `${name}: names the field`).toContain('offCanvas')+ // THE STALE CLAIM the split exists to prevent: a display verb reported as queued.+ expect(clause, `${name}: not queued`).toMatch(/nothing (here )?is (ever )?\`?queued/i)+ }+ })})