pmx-canvas 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to `pmx-canvas` are documented here. This project follows
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-06-24
+
+### Fixed
+
+- **`canvas_ax_delivery` claim can surface the newest steering first (report #68).** The
+  delivery claim (`canvas_claim_ax_delivery` / `GET /api/canvas/ax/delivery/pending` / CLI
+  `ax delivery list`) defaults to oldest-first FIFO for ordered processing, but on a
+  long-lived board with stale undelivered steering an agent claiming with a small `limit`
+  could process old leftovers and miss the human's latest in-canvas action. A new `order`
+  parameter (`"oldest"` default, `"newest"`) lets an adapter claim newest-first so a fresh
+  browser-originated steer is never buried behind the backlog. Additive — the default FIFO
+  order, wire shape, and the compact `canvas://ax-context` newest-first lead block are all
+  unchanged.
+- **CLI `ax` commands honor `--source` (report #69).** `pmx-canvas ax focus … --source codex`
+  (and the other `ax` subcommands that record a source — `steer`, `event add`, `interaction`,
+  `work`, `approval`, `review`, `evidence`, `elicitation`, `mode`, `command`, `policy`) now
+  persist the given source instead of always recording `cli`, so an adapterless agent using
+  the CLI as a fallback transport attributes its actions correctly (keeping AX loop-safety
+  accurate). The flag defaults to `cli` when omitted — unchanged for existing usage.
+
+### Docs
+
+- **Ghost Cursor skill guidance: default-on, with concrete use/skip + settle scope.** The
+  bundled `pmx-canvas` skill now frames proactive `canvas_intent` signalling as the default
+  before meaningful spatial mutations, with explicit use-vs-skip lists and a one-ghost-per-
+  human-meaningful-move rule for batches. It also documents that linked settle is scoped to
+  node / edge / group mutations — `canvas_app` (diagram / mcp-app) and `canvas_webview`
+  reject an `intentId` (HTTP 400), so signal a ghost, then clear it and open without one.
+
 ## [0.2.3] - 2026-06-23
 
 ### Fixed
@@ -2388,6 +2417,7 @@ otherwise have to discover by trial and error.
 - Regression coverage for snapshot flat-`id` aliases on both MCP and
   HTTP surfaces, plus async / top-level-`await` WebView script bodies.
 
+[0.2.4]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.4
 [0.2.3]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.3
 [0.2.2]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.2
 [0.2.1]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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/skills/pmx-canvas/SKILL.md

@@ -27,8 +27,12 @@ Humans curate agent context by pinning nodes; agents read that curation through
    nodes. Read the full layout only when necessary.
 4. **Snapshot before destructive changes.** Use `canvas_snapshot` before clear, restore, or a major
    reorganization.
-5. **Signal substantial spatial changes.** Use `canvas_intent { action: "signal", ... }` before a
-   visible create, move, connect, remove, or edit when human steering would be useful.
+5. **Show intent with the Ghost Cursor — by default.** Signal with
+   `canvas_intent { action: "signal", ... }` before every meaningful create, move, connect, remove,
+   or edit, then pass the returned `intent.id` as `intentId` on the mutation so the ghost settles
+   into the result. Use it as much as possible to make your next move and your work visible: the
+   human watches intent form and can veto mid-thought. Skip it only for trivial in-place tweaks or
+   high-frequency batch churn.
 6. **Mutate through current composites.** Prefer the 15 composite MCP tools below.
 7. **Arrange and validate.** After batch changes, use `canvas_view { action: "arrange" }` when
    appropriate and always finish with `canvas_query { action: "validate" }`.

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

@@ -394,7 +394,7 @@
       "id": 16,
       "name": "ghost-cursor-intent",
       "prompt": "Add an 'Auth design' status node to the review area. Before adding it, signal what you're about to do so I can veto it if I disagree, then make the change.",
-      "expected_output": "Signals a create intent first with canvas_intent {action:signal, kind:\"create\", position, nodeType:\"status\", label, reason, confidence}, then creates the 'Auth design' node at that position with canvas_node {action:\"add\", type:\"status\", x, y, intentId}. Understands that a vetoed intent rejects its linked mutation. Does not silently mutate without signalling when steering would help.",
+      "expected_output": "Signals a create intent first with canvas_intent {action:signal, kind:\"create\", position, nodeType:\"status\", label, reason, confidence}, then creates the 'Auth design' node at that position with canvas_node {action:\"add\", type:\"status\", x, y, intentId}. Understands that a vetoed intent rejects its linked mutation. Treats signalling intent as the default before visible mutations rather than an optional step, and does not silently mutate.",
       "assertions": [
         {
           "name": "signals-intent-first",

package/skills/pmx-canvas/references/full-reference.md

@@ -75,8 +75,8 @@ section below.
    you need the full board.
 4. **Snapshot before destructive work** — `canvas_snapshot { name }` before clear/major
    reorg; restore if needed.
-5. **Signal then mutate** — optionally `canvas_intent { action: "signal", … }` to telegraph the
-   move, then create with the right composite: `canvas_node` (markdown/status/file/webpage/html
+5. **Signal then mutate (default behavior)** — signal with `canvas_intent { action: "signal", … }`
+   to telegraph the move before nearly every mutation, then create with the right composite: `canvas_node` (markdown/status/file/webpage/html
    incl. primitives), `canvas_render` (json-render/graph), `canvas_app` (mcp-app/diagram/
    web-artifact). Prefer composites — the legacy single-purpose tools are deprecated (removed in
    v0.3).
@@ -441,6 +441,10 @@ identifier is passed as `approvalAction`, since `action` is the lifecycle discri
 
 #### Narrate your next move with `canvas_intent` (Ghost Cursor of Intent)
 
+**Use the Ghost Cursor as much as possible** — it is the primary way to make your intent and your
+work visible on a shared board. Default to signaling before you act; skip it only for trivial
+in-place tweaks or high-frequency batch churn.
+
 Before you create/move/connect/edit/remove on the canvas, **signal the move** so a
 faint placeholder forms where you're about to act — the human sees the next move
 coming and can veto it mid-thought. Intents are ephemeral presence: never
@@ -455,12 +459,25 @@ Narrate → linked mutation → automatic settle:
 Use `canvas_intent { action: "clear", id }` only when abandoning a plan without
 performing the linked mutation.
 
+**Linked settle is scoped to node, edge, and group mutations** (`canvas_node`,
+`canvas_edge`, `canvas_group` and their ops). `canvas_app` opens (diagram /
+mcp-app) and `canvas_webview` do **not** accept an `intentId` and reject it with a
+400 — to telegraph one of those, signal a ghost, then `clear` it (or let it
+expire) and run the open *without* an `intentId`.
+
 Per kind, pass the anchor it renders against: `position` for `create`/`move`,
 `nodeId` for `move`/`edit`/`remove`, `edge: { from, to, type }` for `connect`. The
-payoff is **legibility** — `reason` is shown beneath the ghost. For a planned
-batch, signal all intents up front (with `seq` for ordering), then commit them one
-by one with the corresponding `intentId` so the human watches the layout wireframe
-in before it fills.
+payoff is **legibility** — `reason` is shown beneath the ghost.
+
+**When to use vs skip.** Signal for adds, removes, and moves of visible nodes;
+connecting nodes; creating groups; layout reorganizations; meaningful title/content
+edits; destructive actions (clear/restore/remove); and creating
+artifact/report/dashboard nodes. Skip for tiny metadata fixes, API-only pin/unpin
+verification, deterministic report-node refreshes the human just asked for,
+post-restore cleanup, and bulk fixture churn. **For batch work, signal one ghost
+per human-meaningful move, not one per low-level op** — e.g. one "lay out the
+investigation board" intent, then run the batch with that linked `intentId` (use
+`seq` to order staged previews) so the human watches the wireframe before it fills.
 
 ### Standalones (first-class — not deprecated)
 

package/src/cli/agent.ts

@@ -249,6 +249,16 @@ function optionalNumberFlag(flags: Record<string, string | true>, name: string,
   return Math.floor(parsed);
 }
 
+/**
+ * AX `source` for a CLI-originated action. Defaults to `cli`, but honors an
+ * explicit `--source <label>` so an adapterless agent using the CLI as a fallback
+ * transport (e.g. `--source codex`) attributes its actions correctly — keeping
+ * loop-safety (a consumer never gets back its own steering) accurate (report #69).
+ */
+function resolveAxSource(flags: Record<string, string | true>): string {
+  return getStringFlag(flags, 'source') ?? 'cli';
+}
+
 function optionalFiniteFlag(flags: Record<string, string | true>, name: string, hint: string): number | undefined {
   const val = flags[name];
   if (!val || val === true) return undefined;
@@ -1884,7 +1894,7 @@ cmd('ax focus', 'Set or clear PMX AX focus without moving the viewport', [
     die('Missing node ID', 'pmx-canvas ax focus <node-id> [more-node-ids]');
   }
 
-  output(await api('POST', '/api/canvas/ax/focus', { nodeIds, source: 'cli' }));
+  output(await api('POST', '/api/canvas/ax/focus', { nodeIds, source: resolveAxSource(flags) }));
 });
 
 cmd('ax event add', 'Record a normalized AX timeline event', [
@@ -1903,7 +1913,7 @@ cmd('ax event add', 'Record a normalized AX timeline event', [
     summary,
     ...(detail ? { detail } : {}),
     ...(positional.length > 0 ? { nodeIds: positional } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
@@ -1919,7 +1929,7 @@ cmd('ax steer', 'Send a steering message to the active agent session', [
     die('Missing steering message', 'pmx-canvas ax steer <message>');
   }
 
-  output(await api('POST', '/api/canvas/ax/steer', { message, source: 'cli' }));
+  output(await api('POST', '/api/canvas/ax/steer', { message, source: resolveAxSource(flags) }));
 });
 
 cmd('ax interaction', 'Submit a node-originated AX interaction (capability-gated)', [
@@ -1948,21 +1958,27 @@ cmd('ax interaction', 'Submit a node-originated AX interaction (capability-gated
     type,
     sourceNodeId,
     ...(payload !== undefined ? { payload } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
 cmd('ax delivery list', 'List pending AX steering for a consumer (loop-safe)', [
   'pmx-canvas ax delivery list',
   'pmx-canvas ax delivery list --consumer copilot --limit 20',
+  'pmx-canvas ax delivery list --order newest   # latest browser steering first (#68)',
 ], async (args) => {
   const { flags } = parseFlags(args);
   if (flags.help || flags.h) return showCommandHelp('ax delivery list');
   const consumer = getStringFlag(flags, 'consumer');
   const limit = optionalNumberFlag(flags, 'limit', 'pmx-canvas ax delivery list --limit <n>');
+  const order = getStringFlag(flags, 'order');
+  if (order !== undefined && order !== 'newest' && order !== 'oldest') {
+    die('Invalid --order', 'pmx-canvas ax delivery list --order newest|oldest');
+  }
   const params = new URLSearchParams();
   if (consumer) params.set('consumer', consumer);
   if (limit) params.set('limit', String(limit));
+  if (order) params.set('order', order);
   const qs = params.toString();
   output(await api('GET', `/api/canvas/ax/delivery/pending${qs ? `?${qs}` : ''}`));
 });
@@ -1988,7 +2004,7 @@ cmd('ax elicitation request', 'Request structured human input', [
   output(await api('POST', '/api/canvas/ax/elicitation', {
     prompt,
     ...(fields ? { fields: fields.split(',').map((f) => f.trim()).filter(Boolean) } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
@@ -2004,7 +2020,7 @@ cmd('ax elicitation respond', 'Answer a pending elicitation', [
   if (raw) {
     try { response = JSON.parse(raw); } catch { die('Invalid --response JSON', '--response \'{"k":"v"}\''); }
   }
-  output(await api('POST', `/api/canvas/ax/elicitation/${encodeURIComponent(id)}/respond`, { response, source: 'cli' }));
+  output(await api('POST', `/api/canvas/ax/elicitation/${encodeURIComponent(id)}/respond`, { response, source: resolveAxSource(flags) }));
 });
 
 cmd('ax elicitation list', 'List elicitations', ['pmx-canvas ax elicitation list'], async (args) => {
@@ -2020,7 +2036,7 @@ cmd('ax mode request', 'Request a workflow mode transition (plan/execute/autonom
   if (flags.help || flags.h) return showCommandHelp('ax mode request');
   const mode = requireFlag(flags, 'mode', 'pmx-canvas ax mode request --mode plan|execute|autonomous');
   const reason = getStringFlag(flags, 'reason');
-  output(await api('POST', '/api/canvas/ax/mode', { mode, ...(reason ? { reason } : {}), source: 'cli' }));
+  output(await api('POST', '/api/canvas/ax/mode', { mode, ...(reason ? { reason } : {}), source: resolveAxSource(flags) }));
 });
 
 cmd('ax mode resolve', 'Resolve a pending mode request', [
@@ -2036,7 +2052,7 @@ cmd('ax mode resolve', 'Resolve a pending mode request', [
   output(await api('POST', `/api/canvas/ax/mode/${encodeURIComponent(id)}/resolve`, {
     decision,
     ...(resolution ? { resolution } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
@@ -2065,7 +2081,7 @@ cmd('ax command invoke', 'Invoke a registry-gated PMX command intent', [
   if (raw) {
     try { cmdArgs = JSON.parse(raw); } catch { die('Invalid --args JSON', '--args \'{"k":"v"}\''); }
   }
-  output(await api('POST', '/api/canvas/ax/command', { name, ...(cmdArgs !== undefined ? { args: cmdArgs } : {}), source: 'cli' }));
+  output(await api('POST', '/api/canvas/ax/command', { name, ...(cmdArgs !== undefined ? { args: cmdArgs } : {}), source: resolveAxSource(flags) }));
 });
 
 cmd('ax policy get', 'Show the current declarative AX policy', ['pmx-canvas ax policy get'], async (args) => {
@@ -2091,7 +2107,7 @@ cmd('ax policy set', 'Set the declarative AX policy (stored by PMX, enforced by
   const prompt = (mode || systemAppend)
     ? { ...(mode ? { mode } : {}), ...(systemAppend ? { systemAppend } : {}) }
     : undefined;
-  output(await api('POST', '/api/canvas/ax/policy', { ...(tools ? { tools } : {}), ...(prompt ? { prompt } : {}), source: 'cli' }));
+  output(await api('POST', '/api/canvas/ax/policy', { ...(tools ? { tools } : {}), ...(prompt ? { prompt } : {}), source: resolveAxSource(flags) }));
 });
 
 cmd('ax timeline', 'Read the bounded AX timeline (events, evidence, steering)', [
@@ -2121,7 +2137,7 @@ cmd('ax work add', 'Add a canvas-bound AX work item', [
     ...(status ? { status } : {}),
     ...(detail ? { detail } : {}),
     ...(positional.length > 0 ? { nodeIds: positional } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
@@ -2143,7 +2159,7 @@ cmd('ax work update', 'Update a canvas-bound AX work item by ID', [
     ...(status ? { status } : {}),
     ...(detail ? { detail } : {}),
     ...(positional.length > 1 ? { nodeIds: positional.slice(1) } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
@@ -2172,7 +2188,7 @@ cmd('ax approval request', 'Request a canvas-bound AX approval gate', [
     ...(detail ? { detail } : {}),
     ...(action ? { action } : {}),
     ...(positional.length > 0 ? { nodeIds: positional } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
@@ -2194,7 +2210,7 @@ cmd('ax approval resolve', 'Resolve a pending AX approval gate by ID', [
   output(await api('POST', `/api/canvas/ax/approval/${encodeURIComponent(id)}/resolve`, {
     decision,
     ...(resolution ? { resolution } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
@@ -2225,7 +2241,7 @@ cmd('ax evidence add', 'Record an AX evidence item on the timeline', [
     ...(body ? { body } : {}),
     ...(ref ? { ref } : {}),
     ...(positional.length > 0 ? { nodeIds: positional } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
@@ -2252,7 +2268,7 @@ cmd('ax review add', 'Add a canvas-bound AX review annotation', [
     ...(nodeId ? { nodeId } : {}),
     ...(file ? { file } : {}),
     ...(author ? { author } : {}),
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 
@@ -2283,7 +2299,7 @@ cmd('ax host report', 'Report host/session capability to the canvas', [
     permissions: flags.permissions === true,
     files: flags.files === true,
     uiPrompts: flags['ui-prompts'] === true,
-    source: 'cli',
+    source: resolveAxSource(flags),
   }));
 });
 

package/src/server/operations/ops/ax-timeline.ts

@@ -250,6 +250,7 @@ const axTimelineGetOperation = defineOperation<z.infer<typeof axTimelineGetSchem
 const axDeliveryPendingShape = {
   consumer: z.unknown().optional().describe('Consumer/source label to exclude from results (e.g. copilot, mcp).'),
   limit: z.unknown().optional().describe('Max steering messages to return.'),
+  order: z.unknown().optional().describe('"oldest" (FIFO, default) or "newest" first.'),
 };
 
 const axDeliveryPendingSchema = z.looseObject(axDeliveryPendingShape);
@@ -265,10 +266,11 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
   },
   mcp: {
     toolName: 'canvas_claim_ax_delivery',
-    description: 'Claim pending PMX AX deliveries for a consumer (adapterless delivery). Returns `pending` undelivered steering (mark each with canvas_mark_ax_delivery after acting) AND `pendingActivity`: open canvas-bound AX items awaiting the agent (open work items, pending approval gates / elicitations / mode requests) — typically created by the human in the browser. Both exclude items the consumer itself originated (loop prevention). pendingActivity is read-only here: resolve each via its own tool (canvas_resolve_approval / canvas_respond_elicitation / canvas_resolve_mode / canvas_update_work_item), not canvas_mark_ax_delivery.',
+    description: 'Claim pending PMX AX deliveries for a consumer (adapterless delivery). Returns `pending` undelivered steering (mark each with canvas_mark_ax_delivery after acting) AND `pendingActivity`: open canvas-bound AX items awaiting the agent (open work items, pending approval gates / elicitations / mode requests) — typically created by the human in the browser. Both exclude items the consumer itself originated (loop prevention). `pending` defaults to oldest-first (FIFO, for ordered processing); pass `order:"newest"` to surface the human\'s LATEST in-canvas steering first when a small `limit` would otherwise bury it behind a stale backlog (report #68). pendingActivity is read-only here: resolve each via its own tool (canvas_resolve_approval / canvas_respond_elicitation / canvas_resolve_mode / canvas_update_work_item), not canvas_mark_ax_delivery.',
     extraShape: {
       consumer: z.string().optional().describe('Consumer/source label to exclude from results (e.g. copilot, mcp).'),
       limit: z.number().optional().describe('Max steering messages to return.'),
+      order: z.enum(['newest', 'oldest']).optional().describe('Order of returned steering: "oldest" (FIFO, default) for ordered processing, or "newest" first to see the latest browser action when limited.'),
     },
     // `consumer` is a loop-safety scope, not a source label — never defaulted.
     formatResult: axJsonResult,
@@ -277,10 +279,15 @@ const axDeliveryPendingOperation = defineOperation<z.infer<typeof axDeliveryPend
     const consumer = typeof input.consumer === 'string' ? input.consumer : undefined;
     const limitRaw = Number(input.limit ?? '');
     const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? limitRaw : undefined;
-    const pending = canvasState.getPendingSteering({
-      ...(consumer ? { consumer } : {}),
-      ...(limit ? { limit } : {}),
-    });
+    // #68: default FIFO (oldest-first) for ordered processing; `order:"newest"`
+    // surfaces the latest browser-originated steering first so a small `limit`
+    // can't bury the human's current action behind stale undelivered rows. Both
+    // queries apply the same loop-safe consumer filter before the limit.
+    const newest = input.order === 'newest';
+    const scope = { ...(consumer ? { consumer } : {}), ...(limit ? { limit } : {}) };
+    const pending = newest
+      ? canvasState.getPendingSteeringForContext(scope)
+      : canvasState.getPendingSteering(scope);
     // The MCP tool aggregated pendingActivity; one wire body now serves it over
     // HTTP too (documented broadening). Loop-safe: consumer scopes both queries.
     const pendingActivity = buildPendingAxActivity(canvasState.getAxState(), consumer);