pmx-canvas 0.11.0 → 0.12.1

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/evals/fixtures/code-exploration/src/auth/jwt.ts

@@ -0,0 +1,17 @@
+const SECRET = process.env.JWT_SECRET ?? 'dev-secret';
+
+export interface JwtClaims {
+  sub: string;
+  exp: number;
+}
+
+export function signJwt(claims: JwtClaims): string {
+  const payload = Buffer.from(JSON.stringify(claims)).toString('base64url');
+  return `${payload}.${SECRET}`;
+}
+
+export function verifyJwt(token: string): JwtClaims | null {
+  const [payload, signature] = token.split('.');
+  if (signature !== SECRET || !payload) return null;
+  return JSON.parse(Buffer.from(payload, 'base64url').toString()) as JwtClaims;
+}

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/evals/fixtures/code-exploration/src/auth/login.ts

@@ -0,0 +1,12 @@
+import { signJwt, type JwtClaims } from './jwt';
+
+export async function login(username: string, password: string): Promise<string | null> {
+  const ok = await checkCredentials(username, password);
+  if (!ok) return null;
+  const claims: JwtClaims = { sub: username, exp: Date.now() + 3_600_000 };
+  return signJwt(claims);
+}
+
+async function checkCredentials(username: string, password: string): Promise<boolean> {
+  return Boolean(username) && password.length >= 8;
+}

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/evals/fixtures/code-exploration/src/auth/middleware.ts

@@ -0,0 +1,13 @@
+import { verifyJwt } from './jwt';
+
+export interface AuthedRequest {
+  headers: Record<string, string>;
+  userId?: string;
+}
+
+export function authMiddleware(req: AuthedRequest, next: () => void): void {
+  const token = (req.headers.authorization ?? '').replace(/^Bearer /, '');
+  const claims = verifyJwt(token);
+  if (claims) req.userId = claims.sub;
+  next();
+}

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/evals/fixtures/code-exploration/src/routes/auth.ts

@@ -0,0 +1,13 @@
+import { login } from '../auth/login';
+import { authMiddleware, type AuthedRequest } from '../auth/middleware';
+
+export function registerAuthRoutes(router: {
+  post(path: string, handler: (req: AuthedRequest) => Promise<unknown>): void;
+  use(handler: (req: AuthedRequest, next: () => void) => void): void;
+}): void {
+  router.use(authMiddleware);
+  router.post('/login', async (req) => {
+    const token = await login(req.headers.username ?? '', req.headers.password ?? '');
+    return token ? { token } : { error: 'invalid credentials' };
+  });
+}

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/evals/fixtures/investigation-board/src/handlers/users.ts

@@ -0,0 +1,27 @@
+import { EventEmitter } from 'node:events';
+
+const refreshBus = new EventEmitter();
+
+interface UserRequest {
+  query: Record<string, string>;
+  headers: Record<string, string>;
+}
+
+interface UserResponse {
+  json(body: unknown): void;
+}
+
+/**
+ * GET /api/users
+ *
+ * Memory leak: every request registers a `refresh` listener whose closure
+ * captures the entire `req` object and is never removed. The heap retains one
+ * request per call and the EventEmitter listener count grows without bound.
+ */
+export function getUsers(req: UserRequest, res: UserResponse): void {
+  refreshBus.on('refresh', () => {
+    // Captures `req` for the lifetime of the process — the leak.
+    void req.headers;
+  });
+  res.json({ users: [] });
+}

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/mcp.json

@@ -0,0 +1,36 @@
+{
+  "pmx-canvas": {
+    "command": "bun",
+    "args": [
+      "${AMP_SKILL_DIR}/../../start-mcp.mjs"
+    ],
+    "includeTools": [
+      "canvas_connect_workspace",
+      "canvas_help",
+      "canvas_pin_nodes",
+      "canvas_invoke_command",
+      "canvas_batch",
+      "canvas_import",
+      "canvas_snapshot",
+      "canvas_board",
+      "canvas_node",
+      "canvas_render",
+      "canvas_edge",
+      "canvas_group",
+      "canvas_history",
+      "canvas_view",
+      "canvas_query",
+      "canvas_app",
+      "canvas_webview",
+      "canvas_ax_state",
+      "canvas_ax_work",
+      "canvas_ax_gate",
+      "canvas_ax_timeline",
+      "canvas_ax_delivery",
+      "canvas_intent",
+      "canvas_ax_interaction",
+      "canvas_ingest_activity",
+      "canvas_screenshot"
+    ]
+  }
+}

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

@@ -0,0 +1,101 @@
+# 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_node({
+  action: "add",
+  type: "html",
+  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: [...] } })`.
+
+Changing effective capabilities reloads the mounted HTML document in both `src` and
+`srcdoc` modes, including disable/re-enable and allowed-action changes. Unsaved iframe-local
+drafts reset: save important state through durable AX primitives before changing capabilities.
+Wait for the new document, invoke the action, and verify both its acknowledgement and persisted
+result. On 0.8.0, late enabling required a deliberate remount; upgrading fixes that missing bridge.
+
+## 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.

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/codex-app-adapter.md

@@ -0,0 +1,151 @@
+# Codex App Adapter
+
+Use this reference when PMX Canvas is running natively in the Codex app. The adapter is intentionally
+thin: PMX Canvas remains the state owner, Codex uses MCP for agent operations/context, and the Codex
+in-app Browser renders the live PMX workbench.
+
+## Adapter Identity
+
+- Host: Codex app
+- Visual surface: Codex in-app Browser opened to the PMX `/workbench` URL
+- Agent surface: PMX Canvas MCP server (`pmx-canvas --mcp`)
+- Fallback surface: PMX Canvas CLI for manual scripts when MCP is unavailable
+- AX source label: `codex`
+
+This is not a separate PMX renderer and does not require a Codex extension API. Codex already has
+the two native surfaces PMX needs: MCP resources/tools for the agent, and the in-app Browser for the
+human-visible canvas. Prefer MCP over the CLI for Codex-native use because MCP exposes structured
+tools, resources, and `canvas://ax-context`; use the CLI only as a fallback or for shell scripts.
+
+## What The Adapter Does
+
+- Opens the live PMX workbench in the Codex in-app Browser.
+- Uses MCP tools/resources for all agent-side operations.
+- Reads `canvas://ax-context` or `canvas_ax_state { action: "get" }` for pinned and focused context.
+- Sets AX focus through `canvas_ax_state { action: "set-focus" }` with `source: "codex"` when the
+  focus change comes from Codex-hosted steering.
+- Keeps all persistent PMX state in `.pmx-canvas/canvas.db`; Codex does not own canvas state.
+
+## Setup
+
+Use MCP as the primary Codex adapter path.
+
+Add the PMX MCP server to the Codex workspace config:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bunx",
+      "args": ["pmx-canvas", "--mcp"]
+    }
+  }
+}
+```
+
+For local repo development, use the source entrypoint instead:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bun",
+      "args": ["run", "src/mcp/server.ts"]
+    }
+  }
+}
+```
+
+The MCP server auto-starts the HTTP workbench on first tool call. Open the returned workbench URL
+in the Codex in-app Browser, usually `http://127.0.0.1:4313/workbench` or
+`http://localhost:4313/workbench`.
+
+### Agent presence (cursor + phase chip)
+
+Name the agent on the MCP server so its writes, its session, and its cursor share one identity:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "bunx",
+      "args": ["pmx-canvas", "--mcp"],
+      "env": { "PMX_CANVAS_AGENT_SOURCE": "codex" }
+    }
+  }
+}
+```
+
+Then attach at the start of a task and detach at the end:
+
+```json
+{ "tool": "canvas_ax_state", "action": "set-presence", "attached": true, "label": "Codex", "phase": "idle" }
+{ "tool": "canvas_ax_state", "action": "set-presence", "attached": false }
+```
+
+While attached the workbench shows the Codex cursor on the node it last touched and a phase chip
+(`thinking` · `tooling` · `waiting-approval` · `idle`). `tooling` and the cursor position are
+derived from Codex's own MCP writes — nothing per call. Even without `PMX_CANVAS_AGENT_SOURCE`,
+writes arriving as plain `mcp` are attributed to the single attached session.
+
+## Codex-Native Workflow
+
+1. Open `/workbench` in the Codex in-app Browser as the first visible action. If PMX is not running
+   yet, start/connect the MCP server first only long enough to get the workbench URL, then open the
+   browser before mutating the board.
+2. Start or keep using the PMX MCP server for agent operations.
+3. Use the browser canvas for human spatial curation: pin nodes, move nodes, group nodes, and
+   inspect rendered artifacts.
+4. Use MCP tools for agent operations: create/update nodes, pin nodes, read layout, and read AX
+   context.
+5. When Codex wants to mark the current attention target, call
+   `canvas_ax_state { action: "set-focus", … }` with:
+
+```json
+{
+  "nodeIds": ["node-123"],
+  "source": "codex"
+}
+```
+
+## Context Contract
+
+Codex agents should treat PMX AX context as host-native working context:
+
+- `canvas://pinned-context` is the explicit human-curated node set.
+- `canvas://ax-context` combines pins, focus, and surface metadata, plus a compact
+  loop-safe `delivery: { pendingSteering, pendingActivity }` lead block
+  (`GET /api/canvas/ax/context?consumer=codex` filters out Codex-originated items).
+- `canvas_ax_state { action: "get" }` returns both persisted AX state and agent-ready context.
+- Focus is a current attention target, not a command to ignore the rest of the repository.
+
+The adapterless MCP+Browser path is poll-based: there is no automatic prompt injection,
+so a board click does not wake the current turn. Codex agents poll
+`canvas_ax_delivery { action: "claim" }` (steering + `pendingActivity`) and act/ack explicitly. The
+loop-closing surfaces work over MCP today even without a dedicated extension:
+
+- **Self-report work** with `canvas_ingest_activity` (the board auto-reacts: a failed
+  tool → a blocked work item + review + evidence). Automatic forwarding of Codex's own
+  tool hooks would need a Codex adapter; manual ingestion works now.
+- **Block on a decision** with `canvas_ax_gate { kind, action: "await", id }` (it long-polls PMX
+  until the human resolves the gate in the Browser or the timeout elapses) instead of looping on
+  `canvas_ax_state { action: "get" }`.
+
+## Live-Test Checklist
+
+1. Open `http://127.0.0.1:4313/workbench` in the Codex in-app Browser first so the user can see
+   all later canvas mutations.
+2. Confirm the PMX MCP server is configured for the workspace.
+3. Call `canvas_ax_state { action: "get" }` and confirm it returns `ok: true`.
+4. Add or reuse a node, then pin it from the browser or with `canvas_pin_nodes`.
+5. Read `canvas://ax-context` and confirm the pinned node appears.
+6. Call `canvas_ax_state { action: "set-focus", source: "codex" }` with a real node ID.
+7. Read `canvas_ax_state { action: "get" }` again and confirm `state.focus.source` is `codex`.
+8. Refresh the browser and confirm the workbench still shows the same state.
+
+## Adapter Boundary
+
+Do not add Codex-specific APIs to PMX Canvas core. Core owns neutral AX primitives; Codex maps them
+through MCP and the in-app Browser. If Codex later exposes a dedicated extension or prompt-injection
+hook, implement that as a separate adapter layer that reads the same `/api/canvas/ax/context` or
+`canvas://ax-context` contract.

package/dist/amp-plugin/pmx-canvas/skills/pmx-canvas/references/excalidraw-diagram-authoring.md

@@ -0,0 +1,150 @@
+# Excalidraw Diagram Authoring
+
+Use this guide when creating diagrams through PMX Canvas with `canvas_app { action: "diagram" }` or
+`pmx-canvas external-app add --kind excalidraw`.
+
+Request `width: 720, height: 500` when opening the standard landscape diagram tile. Treat those as
+requested preset dimensions, not authoritative geometry: after the app mounts, query
+`canvas_query { action: "layout" }` and use the node's persisted width and height for placement,
+overlap checks, and any later layout. A hosted app can resize during mount.
+
+## Why Text Can Still Drift
+
+PMX normalizes canonical Excalidraw bound text (`containerId` / `boundElements`) into the hosted
+app's supported shape-level `label` format before calling Excalidraw. That fixes the payload
+format mismatch, but it does not fix poor diagram geometry.
+
+Text can still appear clipped or misplaced when:
+
+- A label is too long for its shape.
+- A diamond or ellipse is too small for the label's usable center area.
+- The `cameraUpdate` viewport is too tight or not 4:3.
+- Title, footer, or notes are placed near the camera edge.
+- The caller bypasses PMX and sends raw elements directly to Excalidraw MCP.
+
+## Text Format Rules
+
+For text inside a rectangle, ellipse, or diamond, use shape-level `label`:
+
+```json
+{
+  "type": "rectangle",
+  "id": "step-a",
+  "x": 100,
+  "y": 100,
+  "width": 260,
+  "height": 90,
+  "label": { "text": "Step A", "fontSize": 18 }
+}
+```
+
+Do not create separate centered text elements for shape labels:
+
+```json
+{
+  "type": "text",
+  "containerId": "step-a",
+  "text": "Step A"
+}
+```
+
+Standalone text is fine for titles, notes, captions, and free-floating annotations. For standalone
+text, `x` is the left edge; `textAlign` does not center it on a point.
+
+## Label Length Rules
+
+- Use 1-4 words inside shapes.
+- Put detailed explanations in nearby standalone text annotations.
+- Prefer `Bound Text` over `Pattern B: containerId+boundElements only`.
+- If a label needs more than 4 words, either widen the shape or split the idea into a label plus an annotation.
+
+## Shape Sizing Rules
+
+- Minimum labeled rectangle or ellipse: `180x80`.
+- For 3-5 word labels: `240x90` or larger.
+- For long labels: `320+` width or use an external annotation.
+- Diamonds need more room than rectangles because the usable center area is smaller.
+- Leave at least `30px` gap between shapes and labels/arrows.
+
+## Camera Rules
+
+Always start with a `cameraUpdate` as the first element.
+
+Use 4:3 camera sizes only:
+
+- `400x300`
+- `600x450`
+- `800x600`
+- `1200x900`
+- `1600x1200`
+
+Camera bounds must include the full diagram plus padding. Leave at least `80px` padding around all
+visible content.
+
+Example:
+
+```json
+{ "type": "cameraUpdate", "x": 20, "y": 0, "width": 1200, "height": 900 }
+```
+
+If a title, footer, or rightmost label is clipped, the camera is wrong even if the elements are valid.
+
+## Good Pattern
+
+```json
+[
+  { "type": "cameraUpdate", "x": 20, "y": 0, "width": 1200, "height": 900 },
+  {
+    "type": "rectangle",
+    "id": "a",
+    "x": 120,
+    "y": 160,
+    "width": 260,
+    "height": 90,
+    "backgroundColor": "#a5d8ff",
+    "fillStyle": "solid",
+    "label": { "text": "Short Label", "fontSize": 18 }
+  },
+  {
+    "type": "rectangle",
+    "id": "b",
+    "x": 520,
+    "y": 160,
+    "width": 280,
+    "height": 90,
+    "backgroundColor": "#b2f2bb",
+    "fillStyle": "solid",
+    "label": { "text": "Next Step", "fontSize": 18 }
+  },
+  {
+    "type": "arrow",
+    "id": "a-to-b",
+    "x": 390,
+    "y": 205,
+    "width": 110,
+    "height": 0,
+    "points": [[0, 0], [110, 0]],
+    "endArrowhead": "arrow",
+    "label": { "text": "then", "fontSize": 14 }
+  },
+  {
+    "type": "text",
+    "id": "note",
+    "x": 120,
+    "y": 290,
+    "text": "Longer explanation goes here, outside the shape.",
+    "fontSize": 16
+  }
+]
+```
+
+## Preflight Checklist
+
+- Shape text uses `label`, not separate `text` elements.
+- Shape labels are short enough to fit.
+- Long explanations are outside shapes.
+- The first element is a 4:3 `cameraUpdate`.
+- Camera has at least `80px` padding around all visible content.
+- Titles and footers are not near the camera edge.
+- Arrows have explicit `points` and enough space for labels.
+- Calls go through PMX (`canvas_app { action: "diagram" }` or `external-app add --kind excalidraw`) unless you manually apply these rules to raw Excalidraw MCP input.