pmx-canvas 0.9.2 → 0.10.0

package/docs/mcp.md

@@ -1,10 +1,92 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **24 tools**, **15 static canvas
+PMX Canvas ships an MCP stdio server with **25 tools**, **15 static canvas
 resources**, and two canvas resource templates, plus per-skill resources at
 `canvas://skills/<name>` and the `skill://{name}/{+path}` template. The server emits
-`notifications/resources/updated` when canvas state changes — humans pin
-nodes in the browser, agents are notified immediately.
+`notifications/resources/updated` to subscribed connections when canvas state changes.
+This uses MCP SDK v1, not SDK v2.
+
+## Operation help (0.10)
+
+Call `canvas_help {}` for the sorted registry names exposed through MCP, then
+`canvas_help { op: "node.add" }` for one operation's public `tool`, `description`
+and JSON `inputSchema`. The schema includes required fields, public field names
+and constant routing selectors (`action`, and `kind` for gates). For example,
+`ax.approval.request` maps to `canvas_ax_gate` with `kind: "approval"`,
+`action: "request"` and the optional `approvalAction` field.
+
+Text contains the JSON result; structured content wraps it in `{ result }`.
+Unknown names, internal/human-only operations and non-registry tools such as
+`canvas_screenshot` return text-only `isError`; use `tools/list` for those tools.
+Help reads registry metadata only: it never starts a canvas, writes state, records
+a content read or advances a cursor. It is read-only and idempotent.
+
+Help derives its schema and guidance from the operation registry, not from live
+board state. Handlers still enforce conditional requirements and authorization.
+Existing input schemas stay in `tools/list`; help does not enable lazy discovery
+in hosts. Repeated equivalent output branches are grouped within each tool,
+preserving operation/payload validation and partial-error receipts.
+
+## Tool results and effect hints (0.10)
+
+All 25 tools advertise an object `outputSchema`. Registry-dispatched tools return
+`structuredContent.result = { operation, outcome, data }`. `operation` names the
+dispatched action (for example `node.add`), `outcome` is `success`, `error` or
+`partial`, and `data` is the existing compact tool result. Prose results use
+`data.message`. Exceptions use `operation: null`, `outcome: "error"` and
+`data.message`; this does not guarantee that nothing changed before the exception.
+Batch failures retain completed `results` and `refs`, with `partial` when at least
+one entry completed. Check both `isError` and the outcome before using a result.
+
+The three handwritten tools keep direct structured objects: `canvas_ax_interaction`
+returns its accepted interaction, `canvas_ingest_activity` its event and reaction
+records, and `canvas_screenshot` capture metadata alongside model-visible image
+content. Their errors are text-only `isError` replies. Existing model-facing text
+and compact/full projections remain unchanged; structured results do not introduce
+additional full-card or UI payloads. Inspect the advertised schema for each tool.
+
+All tools declare `readOnlyHint`, `destructiveHint`, `idempotentHint` and
+`openWorldHint`. Composite hints cover every action, not only their read actions.
+`canvas_query` is not read-only because context reads can advance a durable
+consumer cursor. Hints describe effects; they grant no permission or retry guarantee.
+
+## Cancellation and progress (0.10)
+
+MCP cancellation reaches the operation layer in both local and daemon-attached
+connections. Supported AX waits release their listeners and timers immediately;
+batches stop before the next operation and keep completed writes. Webpage fetches
+receive the signal and stop before writing fetched content after cancellation.
+Cancellation does not roll back a created node or other completed mutations.
+If webpage creation already committed, its receipt retains `fetch.cancelled: true`.
+External app builds/runtime calls and local WebView captures are not interruptible
+mid-call; do not treat cancellation as proof that those side effects stopped.
+
+Calls supplying `_meta.progressToken` receive `notifications/progress` at batch
+entry boundaries and supported AX wait start/completion, with `progress`, optional
+`total`, optional `message` and the same token. This works over the daemon bridge
+as well as local stdio. No token means
+no progress notifications. A host that aborts its connection may not receive a
+partial result; inspect canvas state before retrying. See the
+[HTTP streaming contract](http-api.md#operation-cancellation-and-progress-010).
+
+## Resource subscriptions (0.10)
+
+The server advertises `resources.subscribe`. Send `resources/subscribe` with an
+exact live URI, then `resources/unsubscribe` to stop. Subscriptions belong to the
+connection and disappear on close; reconnecting clients must subscribe again.
+
+Live resources are `canvas://layout`, `boards`, `summary`, `context`, `graph`,
+`spatial-context`, `history`, `code-graph`, `pinned-context`, `ax`, `ax-context`,
+`ax-timeline`, `ax-work`, `ax-pending-steering` and `ax-delivery` (each with the
+`canvas://` prefix). Parameterized context and graph URIs are supported, for example
+`canvas://context?consumer=my-agent&budget=3000`; notifications echo the exact
+subscribed URI. Static schema and bundled skill resources do not support subscriptions.
+
+Notifications invalidate cached data, not deliver it. Read the resource when needed.
+They can be broader than the underlying change, and daemon reconnection invalidates
+subscribed resources to cover missed events. Notification delivery does not record
+a context read or advance a consumer cursor. Explicit `resources/read` works without
+subscriptions, including on hosts that do not use this capability.
 
 > **Consolidation complete (plan-006/008).** The MCP surface shrank from 84
 > tools to 22: 16 action-discriminated **composites** (recommended — see
@@ -57,7 +139,7 @@ on its source board. It appears as a `portal` edge in `canvas://graph`, independ
 
 ## Board tours
 
-`canvas_view { action: "get-tour" }` returns `{ tour, derived }`, using group
+`canvas_view { action: "get-tour" }` returns `{ tour, derived, position }`, using group
 reading order when there is no saved tour. `canvas_view { action: "set-tour",
 tour: { stops: [...] } }` persists an ordered tour; `tour: null` resets it.
 `canvas_view { action: "tour-go", stop: 0 }` (or `step: "next" | "previous"`)
@@ -83,12 +165,12 @@ Add to your agent's MCP config:
 }
 ```
 
-The canvas auto-starts on first tool call.
+The canvas auto-starts on first canvas operation, not on `canvas_help`.
 
 ## Private MCP App preview
 
 `pmx-canvas --mcp-app` runs a **separate, experimental stdio profile**; the
-24-tool `--mcp` profile above is unchanged. Build from this checkout first:
+25-tool `--mcp` profile above is separate. Build from this checkout first:
 
 ```bash
 bun run build
@@ -170,6 +252,10 @@ in the user's browser. Standalone Markdown edits carry captured board/content
 revisions; a refused save keeps the current editor draft. Copy that draft before
 closing the editor or switching boards; unsaved drafts do not survive remounts.
 
+Knowledge review, categories, relation presets and board-copy forms handle saves
+in JavaScript, including Enter and input validation. They do not require the
+outer host to grant `allow-forms`; the SDK test host keeps `sandbox="allow-scripts"`.
+
 **Host constraints still apply.** Native PMX controls work without child frames.
 HTML, Mermaid, JSON/graph and nested app renderers need the host to permit local
 `srcdoc` frames. The portable MCP Apps default with empty `frameDomains` is
@@ -354,7 +440,7 @@ Single-card and layout reads record delivered content, not incident relations.
 Use a complete graph or brief relation entry to acknowledge those relations.
 Reads never mark full card content read or
 switch the workbench. Pull needed cards in full separately.
-No new tool is added: the tool count stays 24.
+These reads add no tools beyond the catalog listed above.
 
 Library search is `canvas_query { action: "search", query: "auth", scope:
 "library" }`. It returns board/card IDs and never switches the active board.
@@ -487,13 +573,14 @@ agent intends to publish its own cursor or attention target.
 
 ## Standalone tools
 
-6 tools that intentionally stay outside the composites — folding them would
+7 tools that intentionally stay outside the composites — folding them would
 hurt (distinct callers, binary payloads, trust-boundary or execution-intent
 semantics). See [Migration reference](#migration-reference) below for the
 legacy tools the composites replaced.
 
 | Tool | Description |
 |------|-------------|
+| `canvas_help` | List MCP registry operations or fetch one operation's public arguments and guidance (`op` optional); no canvas access |
 | `canvas_batch` | Run a batch of canvas operations with `$ref` support |
 | `canvas_pin_nodes` | Pin nodes to include in agent context (`nodeIds`, `mode` set/add/remove, optional `reason` shown to the human) |
 | `canvas_invoke_command` | Invoke a registry command (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); records a `command` agent-event, unknown names rejected |
@@ -699,20 +786,9 @@ interaction against the node's effective capabilities.
 
 ## Change notifications
 
-The MCP server emits `notifications/resources/updated` whenever canvas state
-changes:
-
-- Pin changes notify `canvas://pinned-context`, `canvas://ax`, and `canvas://ax-context`
-- AX focus changes notify `canvas://ax` and `canvas://ax-context`
-- Canvas-bound AX mutations (work items, approval gates, review annotations,
-  host capability) notify `canvas://ax`, `canvas://ax-work`, and `canvas://ax-context`
-- AX timeline mutations (agent-events, evidence, steering) notify
-  `canvas://ax-timeline` and `canvas://ax-context`
-- All mutations notify `canvas://layout`, `canvas://summary`,
-  `canvas://spatial-context`, `canvas://history`, `canvas://code-graph`, and `canvas://graph`
-
-This closes the human-to-agent loop: spatial curation in the browser becomes
-an immediate signal in the agent's context.
+Notifications require an explicit subscription to each live resource URI. See
+[Resource subscriptions](#resource-subscriptions-010) for connection lifetime,
+reconnection and broad cache invalidation. Receiving a notification is not a content read.
 
 ## Codex App Adapter
 

package/docs/node-types.md

@@ -77,6 +77,9 @@ Tick a task directly on its card, including quoted and nested tasks. A card clic
 only that task's `[ ]` or `[x]` marker, preserving the rest of the source exactly.
 Task-shaped text in code examples and raw HTML checkboxes are not Markdown task controls.
 
+Expand a Markdown card to read and edit the full document. Source stays outside the
+scrolling text, below ordinary documents and above documents with flow actions.
+
 ## File nodes
 
 File nodes display project files with line numbers and language detection.

package/docs/plans/plan-019-post-0.9-roadmap.md

@@ -1,10 +1,11 @@
 # Plan 019: After 0.9.0
 
-**Status (2026-10-19):** proposed sequence, agreed in direction with the maintainer. Nothing
-here is started. 0.9.0 itself (the CHANGELOG's Unreleased section) still needs the owner's
-acceptance and release approval; this plan begins once it ships. Version numbers below are
-proposals, not assignments; each release still needs explicit approval and the
-[release gates](../RELEASE.md).
+**Status (2026-10-24):** 0.9.3 is released to npm and GitHub, with fresh registry smoke
+passing. Step 2, MCP hardening and SDK tour result parity on SDK v1, is implemented
+and pushed with the Settings tooltip fix, operation help and schema-size reduction.
+The maintainer authorized review, testing and release of 0.10.0; release gates are in progress.
+Later version numbers are proposals, not publication approval; every release must pass
+the [release gates](../RELEASE.md).
 **Sources:** [product vision](../product-vision-2026-09.md) (moves and the 2026-10-19 sequence),
 [design.md build plan](../design.md#build-plan) (Waves 4, 5, Later),
 [plan 009](plan-009-tech-debt-backlog.md) (open debt),
@@ -21,8 +22,8 @@ measured; the maintainer carries that risk rather than reinstating an earlier ga
 
 | Step | Proposed version | Scope | Vision | Size |
 |---|---|---|---|---|
-| 1 | 0.9.1 | Cleanup: tour debt, large-board costs, bounded due evaluator, MCP reconnect, lint | 12, 1 | S–M |
-| 2 | 0.10 | MCP hardening: contracts, annotations, cancellation, resource subscriptions | 6a, 1 | M |
+| 1 | 0.9.3 | Cleanup: tour debt, large-board costs, bounded due evaluator, MCP reconnect, lint | 12, 1 | S–M |
+| 2 | 0.10 | MCP hardening, operation help and bounded discovery-schema reduction | 6a, 1 | M |
 | 3 | 0.11 | One frame host, portal-layer mount, Wave-0 design pass | 5, 9 | M–L |
 | 4 | 0.12 | Wave 5: agent output as nodes, make/inline board, group drill-in, relations sketch parity | 3, 0 | L |
 | 5 | later | Trust (M half), journal, concurrent boards, binary | 7, 4, 8 | L–XL |
@@ -31,10 +32,66 @@ measured; the maintainer carries that risk rather than reinstating an earlier ga
 Each step starts after the previous release ships, except that a concrete defect found in
 use can be fixed narrowly in a patch release without pulling later scope forward.
 
-## Step 1: 0.9.1 cleanup
+## Step 1: 0.9.3 cleanup
 
 Debt deliberately kept out of 0.9.0, plus measured performance leads.
 
+**Local checkpoint, 2026-10-24 (not release approval):**
+- Camera moves now persist only the viewport. A headed browser regression failed on the
+  baseline's two full-card geometry writes, then passed without them; the complete seven-case
+  presentation/recording file passes. Both camera paths use one animation driver while retaining
+  their existing interpolation. Tour resolution reads geometry without hydrating card contents.
+- Tour reads share one result builder. HTTP and MCP return `{ tour, derived, position }`;
+  the SDK preserves its existing direct tour result (`.stops`). Result-shape parity is
+  deferred to 0.10 because changing the SDK to `.tour.stops` breaks callers.
+- `bun run scripts/probe-mcp-reconnect.ts` opened 12 local stdio fixture apps concurrently,
+  then restored them through five server restarts and queried every replacement session's live
+  tool catalog. All 60 restored sessions passed, with no `-32001` timeout. The native-host/remote
+  backend failure remains open; this probe is not evidence that it is fixed.
+- Saved Markdown skips unused reference parsing; saved targets, unresolved links, drafts and
+  inline images retain their behavior. The measurements below leave serialization, offscreen
+  rendering and SSE unchanged because each needs a separate contract or lifecycle decision.
+- Lifecycle-get, node-get and review qualification use the dependency/portal closure, including
+  incoming cross-board sources and unsaved active-board edges. Latest evidence and retirement
+  summaries use indexed queries; requested audit history remains complete. Home counts are
+  unchanged. **Deferred:** aggregate-only Home reads, per-card storage reads within closure boards,
+  and whole-library mutation broadcasts. The current Home client consumes `knowledge.list.cards`.
+- Lint passes with 55 warnings and 12 infos, down from 63 warnings and 12 infos. Eight unused
+  import diagnostics were removed in the touched SDK module. Remaining diagnostics are listed below.
+- Combined checkout verification passed: `bun run build`, `bun run typecheck`, `bun run test`
+  (1,503 tests), `bun run test:client` (332 tests), and
+  `xvfb-run -a bash scripts/run-playwright.sh --headed` (333 tests). The final node-get
+  integration assertion also passed its 32-case relation suite, typecheck and lint. The inspected
+  tour recording shows both stops and the restored editor after exit. These are local source
+  checks, not release smoke, CI, installed-adapter or native-host verification. The patch-only
+  decision is settled; release gates are being run against the final 0.9.3 candidate.
+
+**Reproducible measurements (local Bun 1.4.4, synthetic data):**
+
+| Workload and command | Before | After | Limits |
+|---|---|---|---|
+| 12 Markdown cards, five decodable 400×300 PNGs, 2,459,314 source bytes; `bun run scripts/benchmark-markdown-load.ts --browser --expect-no-reference-lex` | 24 extra reference parses scanning 4,918,628 bytes | Zero extra reference parses; all 12 normalized HTML hashes match | Three warmups and nine HTTP samples; headed Chromium at 1440×900, 2×, one warmup and three reloads. Timing varied on the shared orb, so no board-load speedup claim |
+| Same Markdown board, public state serialization | 4,927,936 bytes | Unchanged | 2,460,294 bytes are duplicated top-level content; removing that alias is only a counterfactual measurement |
+| Same Markdown board, offscreen rendering | Six offscreen POSTs, 508,608 source bytes | Unchanged | All 12 cards render; all five images decode |
+| Same Markdown board, one-character edit | First layout SSE frame: 2,466,713 bytes, 12 nodes | Unchanged | First frame only, not total event traffic |
+| 12 boards × 24 cards × 32 reviews; `bun run scripts/benchmark-lifecycle.ts` | 13 board reads and 9,248 full-history records per request | Two board reads and 32 records per request | One independent inactive-card request; all 32 requested audit records returned. Closure boards still load whole board bodies |
+| Same lifecycle workload, warm medians from three independent runs | 16.016 / 14.938 / 16.648 ms | 0.832 / 1.101 / 0.609 ms | Five warmups and 20 samples per run. First request initializes indexes and was not consistently faster; no cold-start claim |
+
+Remove `--expect-no-reference-lex` when running the Markdown script against the baseline.
+Both benchmarks isolate their databases in disposable workspaces. Dependency-heavy lifecycle
+behavior is covered by cycle, provenance, missing-source and cross-board tests, not this timing workload.
+
+**Remaining lint diagnostics:** `bunx --no-install biome check . --max-diagnostics=200`
+lists the exact locations. These remain outside the narrow behavioral fixes:
+
+| Diagnostics | Count | Reason retained |
+|---|---:|---|
+| Unused imports / variables / parameters / private members | 11 / 8 / 6 / 1 | Spread across unrelated client, server and test modules; remove with their owning cleanup |
+| Optional-chain suggestions | 23 | Existing style suggestions, including untouched regions of changed files |
+| Literal template placeholders | 3 | Tests intentionally exercise literal `${…}` text |
+| Global `isNaN`, confusing `void`, comma operator | 1 each | Existing chart coercion, frame callback and presence expressions need individual semantic review |
+| Infos: template strings / switch cases / index lookup / config deprecation | 6 / 3 / 2 / 1 | Non-gating style/config follow-up, no rule disabled |
+
 - **Tour debt** ([vision move 12](../product-vision-2026-09.md#12-tours-the-board-is-the-presentation-m)):
   a tour camera move saves every node's layout (`commitViewport` → `persistLayout` from the SSE
   camera handler) and re-reads the whole layout (`tour-control.ts`); `animateCameraPath`
@@ -55,8 +112,8 @@ Debt deliberately kept out of 0.9.0, plus measured performance leads.
 **Done when**
 - A tour step changes the viewport and writes no node layout: a test asserts the intended
   viewport change and that no layout-persistence write occurs during `tour go`/`next`
-  (unchanged positions alone would also pass a needless identical rewrite). SDK, HTTP and MCP
-  return the same tour shape, including position. One camera-animation path remains.
+  (unchanged positions alone would also pass a needless identical rewrite). The SDK keeps its
+  existing tour shape; result-shape parity moves to step 2. One camera-animation path remains.
 - Each WI-01 amplifier has a reproducible measurement script and a before/after number on the
   same workload, per the measurement rules in `CLAUDE.md`; unimplicated ones are recorded, not changed.
 - A one-card lifecycle request on a board with populated review histories reads only its
@@ -68,6 +125,121 @@ Debt deliberately kept out of 0.9.0, plus measured performance leads.
 [Vision move 6a](../product-vision-2026-09.md#6a-make-the-tool-surface-cheap-s--staged-follow-up)
 and move 1's context delivery, on the current SDK v1.
 
+**Local implementation checkpoint (2026-10-24):**
+- All 24 tools advertise output schemas and explicit effect hints. Registry results use
+  `{ result: { operation, outcome, data } }`; handwritten interaction, activity and screenshot
+  tools retain their direct objects. Existing model-facing text/projections stay unchanged.
+  Schemas distinguish batch success, empty failure and retained partial outcomes.
+- Cancellation reaches AX waits and webpage I/O through local and HTTP invokers. Batches
+  retain completed receipts and stop before subsequent operations. Progress is opt-in through
+  MCP tokens and HTTP NDJSON. External runtime/build calls and local WebView captures remain
+  noninterruptible mid-call. Disconnects may lose the response, never undo completed writes.
+- Subscriptions belong to each connection, include exact parameterized URIs, and dispose
+  on unsubscribe/close. Local state and workbench events cover library-only changes as well
+  as active nodes; remote SSE reconnects invalidate subscribed resources. Notifications never
+  record reads or advance cursors. A library-only-change regression failed before integration
+  and passes with the shared event source.
+- SDK `getTour()` now returns `{ tour, derived, position }`; `.tour.stops` is documented as
+  the minor-version breaking change. No SDK/dependency upgrade or frame-host work.
+
+**Approved follow-up, 2026-10-24:** `canvas_help { op }` derives one operation's
+public arguments, required fields, routing selectors and guidance from the registry.
+Omitting `op` lists MCP registry names; internal/human-only and non-registry tools are
+excluded. Metadata reads neither boot a canvas nor record content delivery. The catalog
+now has 25 tools. Conditional handler validation still applies; no lazy host discovery
+or smaller input schemas are claimed.
+
+Equivalent success schemas shared by identity are grouped within each tool. Distinct
+payload contracts, error branches and batch partial receipts remain unchanged. Two
+real stdio measurements with `bun run scripts/measure-mcp-catalog.ts` were byte-identical:
+the previous 24-tool candidate's 144,680 UTF-8 JSON bytes become 137,381 for the same
+tools (7,299 fewer, 5.05%). Existing output schemas drop from 77,105 to 69,806 bytes.
+Adding help costs 1,156 catalog bytes including its separator: 138,537 bytes total,
+6,143 fewer than the previous candidate (4.25%). Input-schema byte counts are unchanged.
+This remains larger than published 0.9.3's 65,219 bytes. Bytes are not tokens, latency
+or measured agent effectiveness. `session.start` and composite-input redesign remain deferred.
+
+**Follow-up verification:** build, typecheck and `bun run test` pass (1,546 tests).
+Real SDK stdio checks enumerate help for every exposed registry operation, validate
+required fields, aliases and gate selectors, and create/remove a card using returned
+arguments. Schema controls reject mismatched operations, malformed receipts and extra
+envelope fields while accepting extensible payloads. Lint passes with 55 warnings and
+12 infos. The first combined run caught a second frozen tool list still expecting 24;
+that assertion now includes help. Test-fixture/typecheck failures were corrected, with
+first-failure logs retained.
+
+**Full candidate rerun requested by the maintainer:** `bun run test:coverage` passes
+1,546 tests (67.27% lines, 73.62% functions, above the 60%/64% floors);
+`bun run test:client` passes 332; `xvfb-run -a bash scripts/run-playwright.sh --headed`
+passes all 333 desktop and 600/1024/1920 reference cases. Headed `test:e2e-cli`,
+`release:smoke`, `pack:dry-run`, build, typecheck, lint and generated-catalog mirror
+checks pass. A fresh packed MCP consumer discovers 25 tools, reads help without
+creating state, and validates add/get results. Its allowed dependency versions
+(SDK 1.32.2, Zod 4.6.7 versus checkout 1.28.0/4.3.6) encode nullable primitive schemas
+as type arrays instead of `anyOf`. The initial byte-identity assertion failed;
+comparison passes when only that equivalent encoding is normalized. No dependency changed.
+
+The live portal serves the exact rebuilt bundle. Real stdio help-guided calls and
+headed browser checks pass human pin → notification → explicit read → rendered edit,
+unsubscribe, numeric progress tokens, cancelled approval waits, partial batch receipts
+and refresh persistence. Both minimap toggles leave no tooltip and preserve Settings
+focus. The first recording encoder fell behind; a later recording with the large suite
+finished and a smaller viewport succeeded and was inspected frame by frame.
+Native Amp/Copilot acceptance, Windows/macOS and remote/native reconnect remain unverified.
+
+**Initial hardening verification:** build and typecheck pass; `bun run test` passes 1,544 tests and
+`bun run test:client` passes 332. `xvfb-run -a bash scripts/run-playwright.sh --headed`
+passes 333 cases; three pin/viewport/polling controls also pass after the final local
+subscription event hook. `bun run release:smoke` passes on a disposable packed install,
+not a registry publication. Lint passes with the same 55 warnings and 12 infos; generated
+tool catalogs match. Real stdio tests cover local and daemon-attached progress/cancellation
+and resource isolation. Initial test typing/SDK error-envelope failures and the red
+library-notification regression were corrected; this is not a first-run-green claim.
+Native 0.10 host acceptance, Windows/macOS and remote/native reconnect remain unverified.
+Bounded simplify/harden review found no further blockers and made no additional changes.
+
+**Independent baseline evidence:** the
+[0.9.3 test thread](https://ampcode.com/threads/T-01a048cf-adb3-71bd-a7c6-472053b691d1)
+reports no new confirmed functional defect after reruns, including installed SDK direct-tour
+compatibility and native Amp pin/read/edit/ack acceptance. It does not establish 0.10 MCP
+structured-output, cancellation or subscription conformance. Its low-severity KaTeX advisory,
+unresolved first-run coverage timeout and remote/native reconnect gap remain separate from
+this candidate; no dependency or reconnect fix is claimed here.
+
+**Discovery cost:** `bun run scripts/measure-mcp-catalog.ts` measures UTF-8 bytes of the
+real SDK client's `tools/list` JSON in a disposable stdio workspace, without canvas reads.
+The 0.9.3 baseline is 65,219 bytes; the initial hardening candidate was 144,680 bytes, both 24 tools.
+Output schemas contributed 77,105 bytes before the follow-up above. This is an increase in discovery overhead, not a
+claim of cheaper prompts or a token estimate. Existing result text is unchanged; structured
+results duplicate that projection for machine consumers. Host-specific prompt costs are unmeasured.
+
+| Tool | 0.9.3 bytes | Initial hardening bytes |
+|---|---:|---:|
+| `canvas_pin_nodes` | 782 | 2227 |
+| `canvas_invoke_command` | 804 | 2312 |
+| `canvas_batch` | 1367 | 5184 |
+| `canvas_import` | 1152 | 4251 |
+| `canvas_snapshot` | 2238 | 6365 |
+| `canvas_board` | 5859 | 14803 |
+| `canvas_node` | 8184 | 13485 |
+| `canvas_render` | 6321 | 11165 |
+| `canvas_edge` | 2186 | 4423 |
+| `canvas_group` | 1953 | 4532 |
+| `canvas_history` | 494 | 2430 |
+| `canvas_view` | 4341 | 12821 |
+| `canvas_query` | 2476 | 7000 |
+| `canvas_app` | 4729 | 7496 |
+| `canvas_webview` | 1810 | 4834 |
+| `canvas_ax_state` | 4462 | 7652 |
+| `canvas_ax_work` | 2074 | 4527 |
+| `canvas_ax_gate` | 2417 | 8285 |
+| `canvas_ax_timeline` | 2637 | 6135 |
+| `canvas_ax_delivery` | 1366 | 3284 |
+| `canvas_intent` | 3127 | 5453 |
+| `canvas_ax_interaction` | 1460 | 1969 |
+| `canvas_ingest_activity` | 2341 | 2872 |
+| `canvas_screenshot` | 604 | 1140 |
+
 1. Remeasure `tools/list` size per tool before any schema change.
 2. `outputSchema` + `structuredContent` for stable results (IDs, revisions, mutation
    outcomes); compact model-facing content; UI-only payloads in `_meta` where supported.
@@ -77,8 +249,12 @@ and move 1's context delivery, on the current SDK v1.
    for long operations where the host supports it; partial outcomes reported honestly.
 5. Resource subscriptions: advertise the capability, track subscribed URIs per connection,
    notify only subscribers. Explicit context reads keep working for hosts without them.
+6. Align SDK tour reads with HTTP/MCP `{ tour, derived, position }`; document the breaking
+   change from `.stops` to `.tour.stops` at this minor-version boundary.
+
+7. Approved follow-up: `canvas_help { op }` and bounded output-schema deduplication, as above.
 
-Candidates, not automatic scope: `canvas_help { op }`, `session.start`, per-action schemas.
+Candidates, not automatic scope: `session.start`, composite-input redesign.
 
 **Done when**
 - Representative read and mutation results validate against their advertised schemas.

package/docs/sdk.md

@@ -36,6 +36,16 @@ Missing/stale validating preconditions fail. Reviewed content must persist befor
 record. Read, edit, refresh and explicit retirement restore never renew validation; historical
 records retain their reviewed revision, and legacy unversioned evidence remains unknown.
 
+## Board tours
+
+`canvas.getTour()` returns `{ tour, derived, position }`, matching HTTP and MCP.
+Read stops from `canvas.getTour().tour.stops`. `derived` is true when stops come
+from group reading order rather than a saved tour. `position` is the current
+stop index, or null outside a tour.
+This is a breaking change in 0.10: replace `.getTour().stops` with `.getTour().tour.stops`.
+`canvas.setTour(tourOrNull)` saves the tour or resets it to derived group order.
+See the [tour contract](http-api.md#board-tours) for navigation and camera moves.
+
 ## Quick example
 
 `canvas.addNode` also accepts `destinationBoardId`, `requestId`, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/plugins/pmx-canvas/com.github.copilot/extensions/pmx-canvas/extension.mjs

@@ -312,7 +312,11 @@ async function startPanelServer(instanceId, ctx, pmx) {
                     jsonResponse(res, 400, { ok: false, error: "prompt is required" });
                     return;
                 }
-                await copilotSession?.send({ prompt: body.prompt });
+                if (!copilotSession) {
+                    jsonResponse(res, 503, { ok: false, error: "Copilot session is unavailable." });
+                    return;
+                }
+                await copilotSession.send({ prompt: body.prompt, mode: "immediate" });
                 // Explicit user instruction from the panel → mirror onto the AX
                 // timeline as a steering message (fire-and-forget).
                 const target = await verifiedEntryTarget(entry);
@@ -635,7 +639,8 @@ const pmxCanvas = createCanvas({
             handler: async (ctx) => {
                 const prompt = typeof ctx.input?.prompt === "string" ? ctx.input.prompt.trim() : "";
                 if (!prompt) throw new CanvasError("prompt_required", "prompt is required");
-                await copilotSession?.send({ prompt });
+                if (!copilotSession) throw new CanvasError("copilot_unavailable", "Copilot session is unavailable.");
+                await copilotSession.send({ prompt, mode: "immediate" });
                 // Mirror the explicit user instruction onto the AX timeline as a
                 // steering message (fire-and-forget). This is an explicit action
                 // flow, never a sync from the prompt hook.
@@ -867,7 +872,8 @@ sessionWorkspaceRoot = resolve((await copilotSession.rpc.metadata.snapshot()).wo
 steeringDeliveryPump = createSteeringDeliveryPump({
     consumer: "copilot",
     claim: claimCopilotSteering,
-    send: async (message) => await copilotSession.send({ prompt: message }),
+    // The SDK defaults to enqueue; canvas steering must target the active turn.
+    send: async (message) => await copilotSession.send({ prompt: message, mode: "immediate" }),
     mark: markCopilotSteering,
     getPresence: getCopilotPresence,
     setPresence: async (patch) => await postPresence(sessionWorkspaceRoot, patch),

package/plugins/pmx-canvas/com.github.copilot/extensions/pmx-canvas/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.9.2"
+  "version": "0.10.0"
 }

package/plugins/pmx-canvas/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pmx-canvas",
   "description": "PMX Canvas spatial workbench and MCP tools, with a native canvas panel in the GitHub Copilot app.",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "author": {
     "name": "pskoett",
     "url": "https://github.com/pskoett"

package/plugins/pmx-canvas/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.9.2"
+  "version": "0.10.0"
 }