pmx-canvas 0.2.0 → 0.2.2

package/skills/pmx-canvas/evals/evals.json

@@ -181,6 +181,205 @@
           "type": "output_check"
         }
       ]
+    },
+    {
+      "id": 8,
+      "name": "workspace-identity-preflight",
+      "prompt": "Attach to the running PMX canvas and add a status node for our deploy. There's already a daemon on port 4313.",
+      "expected_output": "Before mutating, reads GET /health (or serve status) and confirms the returned workspace matches the intended workspace root; refuses to mutate a mismatched/stale listener and starts an isolated server on an explicit --port instead.",
+      "assertions": [
+        {
+          "name": "reads-health",
+          "description": "Reads /health or serve status before any mutation",
+          "type": "output_check"
+        },
+        {
+          "name": "checks-workspace",
+          "description": "Compares the returned workspace to the intended workspace root",
+          "type": "output_check"
+        },
+        {
+          "name": "handles-mismatch",
+          "description": "On workspace mismatch or responsive+pidRunning:false, does NOT mutate; isolates via explicit --port and re-checks /health",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 9,
+      "name": "current-composite-routing",
+      "prompt": "Create a markdown note, a bar chart, and an Excalidraw diagram on the canvas.",
+      "expected_output": "Uses current composites: canvas_node {action:add} for markdown, canvas_render {action:add-graph} for the chart, canvas_app {action:diagram} for Excalidraw. Avoids deprecated single-purpose tools (canvas_add_node/canvas_add_diagram/canvas_build_web_artifact/canvas_open_mcp_app).",
+      "assertions": [
+        {
+          "name": "uses-canvas-node",
+          "description": "Creates the markdown node via canvas_node {action:add}",
+          "type": "output_check"
+        },
+        {
+          "name": "uses-canvas-render",
+          "description": "Creates the chart via canvas_render {action:add-graph}",
+          "type": "output_check"
+        },
+        {
+          "name": "uses-canvas-app",
+          "description": "Creates the Excalidraw diagram via canvas_app {action:diagram}",
+          "type": "output_check"
+        },
+        {
+          "name": "avoids-deprecated",
+          "description": "Does not call deprecated standalones (canvas_add_node/canvas_add_diagram/etc.)",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 10,
+      "name": "existing-board-extension",
+      "prompt": "Add two more findings to the investigation board that's already on the canvas.",
+      "expected_output": "Searches the existing board first, snapshots before extending, adds new nodes without duplicating existing titles, and validates the final layout for collisions.",
+      "assertions": [
+        {
+          "name": "searches-first",
+          "description": "Searches existing nodes (canvas_query {action:search}) before adding",
+          "type": "output_check"
+        },
+        {
+          "name": "snapshots-before",
+          "description": "Snapshots before extending the board",
+          "type": "output_check"
+        },
+        {
+          "name": "no-duplicates",
+          "description": "Adds new nodes without duplicating existing node titles",
+          "type": "output_check"
+        },
+        {
+          "name": "validates-layout",
+          "description": "Runs canvas_query {action:validate} (or arrange+validate) on the result",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 11,
+      "name": "context-pin-workflow",
+      "prompt": "Pin the auth design node so I (the agent) keep it in context, then confirm it's pinned.",
+      "expected_output": "Pins via a verified path (canvas_pin_nodes, the CLI pin, or browser/right-click 'Pin as context'), then reads canvas://pinned-context to confirm; does not claim a broken UI action succeeded.",
+      "assertions": [
+        {
+          "name": "pins-via-verified-path",
+          "description": "Pins via canvas_pin_nodes / CLI pin / 'Pin as context' — not an unverified action",
+          "type": "output_check"
+        },
+        {
+          "name": "reads-pinned-context",
+          "description": "Reads canvas://pinned-context (or canvas_ax_state) to confirm the pin",
+          "type": "output_check"
+        },
+        {
+          "name": "confirms-count",
+          "description": "Confirms the pin is reflected (context count / pinned set) rather than assuming success",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 12,
+      "name": "status-node-cleanup",
+      "prompt": "Remove the obsolete 'Deploy: pending' status node from the board.",
+      "expected_output": "Removes the status node via canvas_node {action:remove} (status nodes are removable like any other type) and verifies removal; undo remains available.",
+      "assertions": [
+        {
+          "name": "removes-status-node",
+          "description": "Removes the status node via canvas_node {action:remove}",
+          "type": "output_check"
+        },
+        {
+          "name": "verifies-removal",
+          "description": "Verifies the node is gone from the layout",
+          "type": "output_check"
+        },
+        {
+          "name": "preserves-undo",
+          "description": "Notes/relies on undo (canvas_history) remaining available",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 13,
+      "name": "ax-html-control-surface",
+      "prompt": "Build an AX control surface as an HTML node with a button that creates a work item and a button that steers me.",
+      "expected_output": "Creates an opted-in html node (axCapabilities.enabled) using the blessed recipe: awaits window.PMX_AX.emit, reflects live state via pmx-ax-update, avoids sandbox-blocked localStorage, and labels the steer button as queued for the next turn (not immediate wake).",
+      "assertions": [
+        {
+          "name": "opts-in-ax",
+          "description": "Creates the html node with axCapabilities.enabled = true",
+          "type": "output_check"
+        },
+        {
+          "name": "awaits-emit",
+          "description": "Uses window.PMX_AX.emit with await (not fire-and-forget)",
+          "type": "output_check"
+        },
+        {
+          "name": "sandbox-safe",
+          "description": "Avoids localStorage/sessionStorage/cookies in the sandboxed iframe",
+          "type": "output_check"
+        },
+        {
+          "name": "labels-steer-queued",
+          "description": "Labels steering as queued for the next turn, not immediate agent wake",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 14,
+      "name": "ax-delivery-lifecycle",
+      "prompt": "There are pending steering messages from the board. Pick them up and act on them.",
+      "expected_output": "Reads compact context (newest-first pendingSteering + totalPending/omittedPending) and/or claims via canvas_ax_delivery {action:claim}; acts, then marks delivered. Understands direct delivery stays FIFO oldest-first.",
+      "assertions": [
+        {
+          "name": "reads-newest-first",
+          "description": "Uses compact context (newest-first + counts) or canvas_ax_delivery claim to find fresh steering",
+          "type": "output_check"
+        },
+        {
+          "name": "acts-then-marks",
+          "description": "Acts on the steering then marks it delivered (canvas_ax_delivery {action:mark})",
+          "type": "output_check"
+        },
+        {
+          "name": "understands-fifo",
+          "description": "Recognizes the direct delivery queue is FIFO oldest-first, distinct from compact context",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 15,
+      "name": "final-cleanup-and-validate",
+      "prompt": "We're done with the test board. Clean up the temporary nodes and leave the canvas as we found it.",
+      "expected_output": "Removes retry/test fixtures, runs canvas_query {action:validate} to confirm no accidental collisions/dangling edges, and restores the baseline snapshot.",
+      "assertions": [
+        {
+          "name": "removes-fixtures",
+          "description": "Removes the temporary/retry fixture nodes",
+          "type": "output_check"
+        },
+        {
+          "name": "validates-final",
+          "description": "Validates the final layout (canvas_query {action:validate})",
+          "type": "output_check"
+        },
+        {
+          "name": "restores-baseline",
+          "description": "Restores the baseline snapshot to leave the canvas as found",
+          "type": "output_check"
+        }
+      ]
     }
   ]
 }

package/skills/pmx-canvas/references/ax-html-control-surface.md

@@ -0,0 +1,93 @@
+# AX HTML Control Surface — a blessed, copy-paste-safe recipe
+
+A canvas `html` node can be a live **AX control surface**: it emits AX interactions
+(create work, request approval, steer the agent, …) and reflects the current AX board
+back, all from inside the sandboxed iframe. The bridge is already injected for you —
+you do **not** need to read `axToken` from the URL or hand-post `pmx-canvas-ax`
+messages. Just opt the node in and use `window.PMX_AX`.
+
+## Opt in
+
+```js
+// MCP / SDK
+canvas_add_html_node({
+  title: "AX Control Room",
+  html: "<!-- see below -->",
+  axCapabilities: { enabled: true, allowed: ["ax.work.create", "ax.steer"] },
+});
+// HTTP: POST /api/canvas/node  { type:"html", title, html, axCapabilities }  (top-level html + axCapabilities both accepted)
+```
+
+Without `axCapabilities.enabled = true`, `window.PMX_AX` is **not** injected — the node
+renders but can't emit. `allowed` narrows what it may emit (never escalates the type's
+ceiling). Flip an existing node on with `canvas_node({ action: "update", id, axCapabilities: { enabled: true, allowed: [...] } })`.
+
+## Three footguns (this is why a hand-rolled node looks "inert")
+
+1. **The iframe is sandboxed opaque-origin** (no `allow-same-origin`). `localStorage`,
+   `sessionStorage`, and `document.cookie` **throw** — and an uncaught throw at script
+   start aborts the whole script, so the node renders blank/inert. Keep state in plain
+   JS variables (or `window.PMX_AX.state`); if you must touch storage, wrap it in
+   `try/catch`.
+2. **`window.PMX_AX.emit(type, payload)` is async.** It returns a Promise that resolves
+   with the result once the canvas acks it. `await` it (or `.then` / `window.PMX_AX.on('ack', cb)`).
+   Reading a result synchronously gets you `undefined`.
+3. **`ax.steer` is recorded, not delivered.** A successful emit (`{ ok: true }`) means
+   the steer was **queued** on the timeline — it does **not** wake or notify the active
+   agent. A cooperating host adapter must drain the delivery queue and call its native
+   send to create a visible turn (host-owned). Otherwise the steer is picked up on the
+   human's next turn. Label steering buttons honestly ("Queued for the agent's next turn").
+
+## Drop-in template (work + steer, with ack + live reflection)
+
+```html
+<style>
+  body { font: 13px system-ui; margin: 0; padding: 12px; }
+  button { cursor: pointer; }
+  #s { margin-left: 8px; color: #6b7280; }
+  ul { padding-left: 18px; }
+</style>
+<button id="add">+ Work item</button>
+<button id="steer">Steer agent</button>
+<span id="s"></span>
+<ul id="q"></ul>
+<script>
+  // In-memory only — NO localStorage/sessionStorage/cookies (sandboxed: they throw).
+  const $ = (id) => document.getElementById(id);
+  const flash = (msg) => { $('s').textContent = msg; setTimeout(() => { $('s').textContent = ''; }, 1500); };
+
+  function render(state) {
+    const items = (state && state.workItems) || [];
+    $('q').innerHTML = items.map((w) => '<li>[' + w.status + '] ' + w.title + '</li>').join('');
+  }
+
+  $('add').onclick = async () => {
+    const r = await window.PMX_AX.emit('ax.work.create', { title: 'New task' });
+    flash(r && r.ok ? 'queued ✓' : ('failed: ' + (r && (r.error || r.code))));
+  };
+  $('steer').onclick = async () => {
+    const r = await window.PMX_AX.emit('ax.steer', { message: 'Prioritize the auth refactor' });
+    // Honest: recorded/queued, NOT delivered to the live agent.
+    flash(r && r.ok ? 'queued for next turn ✓' : 'failed');
+  };
+
+  // Reflect: seeded once at load, then live via the pmx-ax-update event.
+  render(window.PMX_AX && window.PMX_AX.state);
+  window.addEventListener('pmx-ax-update', (e) => render(e.detail));
+</script>
+```
+
+## API surface (injected by PMX when opted in)
+
+- `window.PMX_AX.emit(type, payload) → Promise<{ ok, primitive?, status?, code?, error? }>`
+  — `ok:true` on accept; `ok:false` with `code`/`error` on reject; falls back to an
+  `ax-ack-timeout` result after 10s so `await` never hangs.
+- `window.PMX_AX.on('ack', (result, interaction) => …)` — also fires a `pmx-ax-ack`
+  CustomEvent; use instead of `await` if you prefer a listener.
+- `window.PMX_AX.state` — compact board snapshot `{ focus, workItems, approvalGates,
+  reviewAnnotations, elicitations, modeRequests, policy }` (human review text redacted).
+- `pmx-ax-update` window event — fires with the fresh snapshot on every AX change.
+
+Allowed `type`s are gated per node capability (see the node-capability matrix in
+`SKILL.md`). Emits are clamped to the surface's own node; the server re-validates every
+interaction — the bridge is convenience, not a trust boundary.