pmx-canvas 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.2.2",
+  "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" }`.
@@ -191,7 +195,10 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
 - Hosted MCP-app/ext-app nodes such as Excalidraw require the in-canvas host bridge and are not
   standalone **Open as site** targets. URL-backed viewers and bundled web artifacts remain
   openable.
-- Graph and json-render standalone surfaces use `display=site` and fill the browser viewport.
+- Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
+  reflow on a live window resize in a normal browser. Some single-tab host browsers (e.g. the
+  Codex in-app browser) don't deliver live-resize events, so a resized standalone chart can look
+  stale until reload — use a system browser for separate full-page viewing.
 - Some hosts cannot automate inside sandboxed workbench iframes. Verify those interactions in a
   system browser or through server-side AX state.
 - `pmx-canvas screenshot` requires an active WebView. Start it with

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

@@ -6,6 +6,9 @@
       "name": "investigation-board",
       "prompt": "I'm debugging a memory leak in our Node.js API. The /api/users endpoint is leaking memory on every request. I found a suspicious closure in src/handlers/users.ts that captures the entire request object, and the heap snapshot shows growing EventEmitter listeners. Can you set up an investigation board on the canvas so I can see the full picture?",
       "expected_output": "Creates multiple nodes (bug description, code file, heap findings, hypothesis) connected with edges, arranged in a tree layout. Uses appropriate node types (markdown for findings, file for source, status for investigation progress).",
+      "files": [
+        "evals/fixtures/investigation-board/src/handlers/users.ts"
+      ],
       "assertions": [
         {
           "name": "creates-multiple-nodes",
@@ -93,7 +96,7 @@
       "assertions": [
         {
           "name": "reads-pinned-context",
-          "description": "Reads the canvas://pinned-context MCP resource (not just canvas_query action:layout)",
+          "description": "Reads the curated pin set via canvas://pinned-context — or the host-equivalent (canvas_ax_state / the HTTP pinned-context endpoint) where a direct resource tool is unavailable — not just canvas_query action:layout",
           "type": "output_check"
         },
         {
@@ -113,6 +116,12 @@
       "name": "code-exploration-files",
       "prompt": "I'm trying to understand how the authentication flow works in this project. Can you put the relevant auth files on the canvas so I can see how they connect? The main files are src/auth/login.ts, src/auth/middleware.ts, src/auth/jwt.ts, and src/routes/auth.ts.",
       "expected_output": "Creates file nodes for each mentioned file (content auto-loads), relies on code graph to auto-detect import dependencies, groups auth files together, and reads canvas://code-graph for dependency analysis.",
+      "files": [
+        "evals/fixtures/code-exploration/src/auth/jwt.ts",
+        "evals/fixtures/code-exploration/src/auth/login.ts",
+        "evals/fixtures/code-exploration/src/auth/middleware.ts",
+        "evals/fixtures/code-exploration/src/routes/auth.ts"
+      ],
       "assertions": [
         {
           "name": "uses-file-nodes",
@@ -380,6 +389,52 @@
           "type": "output_check"
         }
       ]
+    },
+    {
+      "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. Treats signalling intent as the default before visible mutations rather than an optional step, and does not silently mutate.",
+      "assertions": [
+        {
+          "name": "signals-intent-first",
+          "description": "Calls canvas_intent {action:signal} with label/reason and a confidence in [0,1] before the visible mutation",
+          "type": "output_check"
+        },
+        {
+          "name": "links-mutation-to-intent",
+          "description": "Passes the returned intentId on canvas_node {action:add, type:\"status\", x, y, intentId} so the ghost settles into the real node",
+          "type": "output_check"
+        },
+        {
+          "name": "respects-veto",
+          "description": "Understands a vetoed intent rejects its linked mutation (\"Intent <id> was vetoed\") rather than treating signal as cosmetic, and clears/updates intent appropriately",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 17,
+      "name": "standalone-surface-open-as-site",
+      "prompt": "Open the bar-chart graph node as a standalone full-page site for a screenshot, and also try to open the Excalidraw diagram node the same way. Tell me the correct surface URL for each.",
+      "expected_output": "For the graph/json-render node, uses the stable surface URL /api/canvas/surface/<id> which redirects to the full-viewport display=site viewer (reads surfaceUrl from the node, does not fabricate a path). Recognizes the hosted Excalidraw/ext-app node is NOT an open-as-site target (its surface route returns a clean 404 — it renders only with the in-canvas host bridge) and does not claim a standalone tab will work. Notes that some host browsers (e.g. the Codex in-app single-tab browser) don't deliver live-resize events, so a system browser is recommended for separate full-page viewing.",
+      "assertions": [
+        {
+          "name": "graph-site-surface-url",
+          "description": "Gives the graph node's /api/canvas/surface/<id> URL (which redirects to display=site, full viewport) from the node payload rather than fabricating one",
+          "type": "output_check"
+        },
+        {
+          "name": "extapp-not-open-as-site",
+          "description": "States the hosted Excalidraw/ext-app node is not an open-as-site target (clean 404; renders in-canvas only) instead of claiming a standalone tab works",
+          "type": "output_check"
+        },
+        {
+          "name": "host-browser-caveat",
+          "description": "Recommends a system browser for separate full-page viewing and/or notes single-tab host browsers may not reflow on live resize",
+          "type": "output_check"
+        }
+      ]
     }
   ]
 }

package/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/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/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/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/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/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)
 
@@ -901,6 +918,10 @@ the host's embedded browser (e.g. Codex) opens `_blank` tabs in-place.
   site"); view/edit them in the canvas, or open them externally through their own app
   (report #61). Only bundled `web-artifact` apps (redirect to `/artifact`) and URL-backed
   `mcp-app` / `webpage` viewers redirect to their external site.
+- `graph` / `json-render` nodes redirect to the full-viewport `display=site` viewer; the chart
+  fills the window and reflows on a live resize in a normal browser. Single-tab host browsers
+  that don't deliver live-resize events (e.g. the Codex in-app browser) can leave a resized chart
+  stale until reload — recommend a system browser for separate full-page viewing (report #67).
 - This is additive — opening a site never evicts or replaces canvas nodes.
 
 ### Choosing the Right Visual Tier

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/client/nodes/ExtAppFrame.tsx

@@ -799,7 +799,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
             minHeight: 0,
             border: 'none',
             background: 'var(--c-panel)',
-            pointerEvents: isExpanded ? 'auto' : 'none',
+            pointerEvents: isExpanded && status !== 'loading' ? 'auto' : 'none',
           }}
           title={`Ext App: ${toolName}`}
         />

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);

package/src/server/operations/ops/webview.ts

@@ -147,6 +147,7 @@ const startOperation = defineOperation<z.infer<typeof startSchema>, WebviewStart
   http: {
     method: 'POST',
     path: '/api/workbench/webview/start',
+    errorBodyAsResult: true,
     // Mirror the legacy handler status codes from the SERIALIZED wire body
     // (`status` receives the serialized result): 200 ok; 503 server-not-running
     // ({ ok:false, error } — no webview); else 501 when the runtime is
@@ -173,14 +174,24 @@ const startOperation = defineOperation<z.infer<typeof startSchema>, WebviewStart
     },
     // dataStoreDir is sandboxed to the workspace in buildStartOptions (both the
     // MCP and HTTP surfaces), so no MCP-only buildInput is needed.
-    // formatResult receives the SERIALIZED wire body. Legacy
-    // canvas_webview_start: on success JSON-stringifies the webview status; on
-    // failure surfaces a bare-message isError result.
+    // formatResult receives the SERIALIZED wire body. On success JSON-stringifies the
+    // webview status. On failure return parseable JSON ({ ok:false, error, webview })
+    // — NOT a bare message string — so MCP clients can reliably tell a failure/timeout
+    // apart from valid tool content instead of choking on non-JSON text (report #66).
+    // isError still flags the tool-call failure. (The legacy tool returned a bare
+    // message here; the composite + standalone now share this structured shape.)
     formatResult: (result) => {
       const body = result as { ok?: boolean; webview?: WebviewStatus; error?: string };
       if (body.ok && body.webview) return statusText(body.webview);
       return {
-        content: [{ type: 'text' as const, text: body.error ?? 'WebView start failed.' }],
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            ok: false,
+            error: body.error ?? 'WebView start failed.',
+            ...(body.webview ? { webview: body.webview } : {}),
+          }, null, 2),
+        }],
         isError: true,
       };
     },