Skip to content

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.

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.ts
index 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 viewers
render on the DESKTOP: \`show-image\` and \`show-video\` still work with a host path (the
file 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.ts
index 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 + M
expect(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)
+ }
+ })
})