pmx-canvas 0.1.36 → 0.2.1

package/src/server/ax-state.ts

@@ -13,7 +13,7 @@ export interface PmxAxFocusState {
 // ── New enums ──────────────────────────────────────────────────────
 export type PmxAxEventKind =
   | 'prompt' | 'assistant-message' | 'tool-start' | 'tool-result'
-  | 'failure' | 'approval' | 'steering' | 'command';
+  | 'failure' | 'approval' | 'steering' | 'command' | 'note';
 export type PmxAxEvidenceKind =
   | 'logs' | 'tool-result' | 'screenshot' | 'file' | 'diff' | 'test-output';
 export type PmxAxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
@@ -168,8 +168,16 @@ export interface PendingAxActivityItem {
 }
 
 // ── Delivery lead block (compact, un-truncated; for per-turn injection) ──
+// `pendingSteering` here is NEWEST-first (most recent at index 0), capped at
+// AX_CONTEXT_STEERING_LIMIT, so a fresh steer is always visible even behind a long
+// backlog (report #57). This is "what's new?" awareness — distinct from the FIFO
+// claim/ack delivery queue (`/api/canvas/ax/delivery/pending`, getPendingSteering),
+// which stays OLDEST-first for ordered processing. The counts let an agent detect a
+// backlog the compact block omits.
 export interface PmxAxDeliveryContext {
   pendingSteering: PmxAxSteeringMessage[];
+  totalPending: number;
+  omittedPending: number;
   pendingActivity: PendingAxActivityItem[];
 }
 
@@ -263,7 +271,7 @@ function normalizeNodeIds(value: unknown, validNodeIds?: Set<string>): string[]
   return ids;
 }
 
-const AX_EVENT_KINDS = new Set<PmxAxEventKind>(['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering', 'command']);
+const AX_EVENT_KINDS = new Set<PmxAxEventKind>(['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering', 'command', 'note']);
 
 // ── Activity ingestion (harness-forwarded tool/session events) ─────
 // A normalized activity the agent's harness forwards; the board auto-reacts.

package/src/server/canvas-db.ts

@@ -921,6 +921,41 @@ export function loadPendingAxSteeringFromDB(
     .filter((s): s is PmxAxSteeringMessage => s !== null);
 }
 
+/**
+ * NEWEST undelivered steering first (report #57) for the compact AX context lead
+ * block — so a fresh steer is visible even behind a long backlog. Loop-safe: excludes
+ * the consumer's own steering in SQL so the LIMIT applies after loop-prevention.
+ * Distinct from loadPendingAxSteeringFromDB (FIFO oldest-first) which the claim/ack
+ * delivery queue uses for ordered processing.
+ */
+export function loadNewestPendingAxSteeringFromDB(
+  db: Database,
+  options: { consumer?: string; limit?: number } = {},
+): PmxAxSteeringMessage[] {
+  interface Row { seq: number; id: string; message: string; delivered: number; created_at: string; source: string | null }
+  const limit = clampTimelineLimit(options.limit);
+  const rows = options.consumer
+    ? db.query<Row, [string, number]>(
+        'SELECT * FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?) ORDER BY seq DESC LIMIT ?',
+      ).all(options.consumer, limit)
+    : db.query<Row, [number]>(
+        'SELECT * FROM ax_steering WHERE delivered = 0 ORDER BY seq DESC LIMIT ?',
+      ).all(limit);
+  return rows
+    .map((r) => normalizeAxSteeringMessage({ ...r, createdAt: r.created_at, delivered: r.delivered === 1 }))
+    .filter((s): s is PmxAxSteeringMessage => s !== null);
+}
+
+/** Total undelivered steering for a consumer (loop-safe — excludes the consumer's own). */
+export function countPendingAxSteeringFromDB(db: Database, consumer?: string): number {
+  const n = consumer
+    ? db.query<{ n: number }, [string]>(
+        'SELECT COUNT(*) AS n FROM ax_steering WHERE delivered = 0 AND (source IS NULL OR source != ?)',
+      ).get(consumer)?.n
+    : db.query<{ n: number }, []>('SELECT COUNT(*) AS n FROM ax_steering WHERE delivered = 0').get()?.n;
+  return Number(n ?? 0);
+}
+
 function countRows(db: Database, table: 'ax_events' | 'ax_evidence' | 'ax_steering'): number {
   return Number(db.query<{ n: number }, []>(`SELECT COUNT(*) AS n FROM ${table}`).get()?.n ?? 0);
 }

package/src/server/canvas-operations.ts

@@ -19,7 +19,7 @@ import {
 import { mutationHistory } from './mutation-history.js';
 import { computeGroupBounds, findOpenCanvasPosition } from './placement.js';
 import { searchNodes } from './spatial-analysis.js';
-import { getCanvasNodeTitle, serializeCanvasNodeCompact, type SerializedCanvasNode } from './canvas-serialization.js';
+import { getCanvasNodeTitle } from './canvas-serialization.js';
 import { computeAutoArrange } from '../shared/auto-arrange.js';
 import {
   applyJsonRenderStreamPatches,
@@ -52,7 +52,7 @@ export function setCanvasLayoutUpdateEmitter(emitter: (() => void) | null): void
   canvasLayoutUpdateEmitter = emitter;
 }
 
-function emitCanvasLayoutUpdate(): void {
+export function emitCanvasLayoutUpdate(): void {
   canvasLayoutUpdateEmitter?.();
 }
 
@@ -125,12 +125,6 @@ interface CanvasCreateGroupInput {
   childLayout?: CanvasArrangeMode;
 }
 
-export interface CanvasBatchOperation {
-  op: string;
-  assign?: string;
-  args?: Record<string, unknown>;
-}
-
 interface CanvasNodeLookupInput {
   id?: string;
   search?: string;
@@ -1659,323 +1653,3 @@ export function fitCanvasView(options: CanvasFitViewOptions = {}): CanvasFitView
   canvasState.setViewport(viewport);
   return { ok: true, viewport: canvasState.viewport, nodeCount: targetNodes.length, bounds };
 }
-
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-function resolveBatchRefs(value: unknown, refs: Record<string, unknown>): unknown {
-  if (typeof value === 'string' && value.startsWith('$')) {
-    const path = value.slice(1).split('.');
-    let current: unknown = refs[path[0] ?? ''];
-    if (path.length === 1 && isPlainRecord(current) && typeof current.id === 'string') return current.id;
-    for (const segment of path.slice(1)) {
-      if (!isPlainRecord(current) && !Array.isArray(current)) return undefined;
-      current = (current as Record<string, unknown>)[segment];
-    }
-    return current;
-  }
-  if (Array.isArray(value)) return value.map((item) => resolveBatchRefs(item, refs));
-  if (isPlainRecord(value)) {
-    const resolved: Record<string, unknown> = {};
-    for (const [key, child] of Object.entries(value)) {
-      resolved[key] = resolveBatchRefs(child, refs);
-    }
-    return resolved;
-  }
-  return value;
-}
-
-function serializeCreatedNode(node: CanvasNodeState): SerializedCanvasNode {
-  return serializeCanvasNodeCompact(node);
-}
-
-export async function executeCanvasBatch(
-  operations: CanvasBatchOperation[],
-): Promise<{
-  ok: boolean;
-  results: Array<Record<string, unknown>>;
-  refs: Record<string, unknown>;
-  failedIndex?: number;
-  error?: string;
-}> {
-  const refs: Record<string, unknown> = {};
-  const results: Array<Record<string, unknown>> = [];
-
-  for (let index = 0; index < operations.length; index++) {
-    const operation = operations[index];
-    const args = isPlainRecord(operation.args) ? resolveBatchRefs(operation.args, refs) : {};
-    if (!isPlainRecord(args)) {
-      return {
-        ok: false,
-        failedIndex: index,
-        error: `Operation ${index} has invalid args.`,
-        results,
-        refs,
-      };
-    }
-
-    try {
-      let result: Record<string, unknown>;
-      switch (operation.op) {
-        case 'node.add': {
-          const type = typeof args.type === 'string' ? args.type : 'markdown';
-          if (type === 'html-primitive') {
-            throw new Error('Batch html-primitive creation is not supported yet. Use node.add with type "html" and generated html, or create the primitive through MCP/HTTP/CLI first.');
-          }
-          if (type === 'webpage') {
-            const content = typeof args.url === 'string' && args.url.trim().length > 0
-              ? args.url
-              : typeof args.content === 'string'
-                ? args.content
-                : undefined;
-            const created = addCanvasNode({
-              type: 'webpage',
-              ...(typeof args.title === 'string' ? { title: args.title } : {}),
-              ...(content ? { content } : {}),
-              ...(isPlainRecord(args.data) ? { data: args.data } : {}),
-              ...(typeof args.x === 'number' ? { x: args.x } : {}),
-              ...(typeof args.y === 'number' ? { y: args.y } : {}),
-              ...(typeof args.width === 'number' ? { width: args.width } : {}),
-              ...(typeof args.height === 'number' ? { height: args.height } : {}),
-              ...(args.strictSize === true ? { strictSize: true } : {}),
-              defaultWidth: 520,
-              defaultHeight: 420,
-            });
-            const fetch = await refreshCanvasWebpageNode(created.id);
-            const refreshed = canvasState.getNode(created.id) ?? created.node;
-            result = {
-              ok: true,
-              ...serializeCreatedNode(refreshed),
-              fetch: fetch.ok
-                ? { ok: true }
-                : { ok: false, error: fetch.error ?? 'Failed to fetch webpage content.' },
-              ...(fetch.ok ? {} : { error: fetch.error }),
-            };
-          } else {
-            const data = isPlainRecord(args.data) ? args.data : {};
-            const htmlData = type === 'html'
-              ? {
-                  ...data,
-                  ...(typeof args.html === 'string' ? { html: args.html } : {}),
-                  ...(typeof args.summary === 'string' ? { summary: args.summary } : {}),
-                  ...(typeof args.agentSummary === 'string' ? { agentSummary: args.agentSummary } : {}),
-                  ...(typeof args.description === 'string' ? { description: args.description } : {}),
-                  ...(Array.isArray(args.embeddedNodeIds) ? { embeddedNodeIds: args.embeddedNodeIds } : {}),
-                  ...(Array.isArray(args.embeddedUrls) ? { embeddedUrls: args.embeddedUrls } : {}),
-                }
-              : data;
-            const created = addCanvasNode({
-              type: type as CanvasNodeState['type'],
-              ...(typeof args.title === 'string' ? { title: args.title } : {}),
-              ...(typeof args.content === 'string' ? { content: args.content } : {}),
-              ...(Object.keys(htmlData).length > 0 ? { data: htmlData } : {}),
-              ...(typeof args.x === 'number' ? { x: args.x } : {}),
-              ...(typeof args.y === 'number' ? { y: args.y } : {}),
-              ...(typeof args.width === 'number' ? { width: args.width } : {}),
-              ...(typeof args.height === 'number' ? { height: args.height } : {}),
-              ...(args.strictSize === true ? { strictSize: true } : {}),
-              defaultWidth: type === 'html'
-                ? 720
-                : type === 'markdown'
-                  ? MARKDOWN_NODE_DEFAULT_SIZE.width
-                  : type === 'mcp-app'
-                    ? MCP_APP_NODE_DEFAULT_SIZE.width
-                    : type === 'image'
-                      ? IMAGE_NODE_DEFAULT_SIZE.width
-                      : type === 'ledger'
-                        ? LEDGER_NODE_DEFAULT_SIZE.width
-                        : 360,
-              defaultHeight: type === 'html'
-                ? 640
-                : type === 'markdown'
-                  ? MARKDOWN_NODE_DEFAULT_SIZE.height
-                  : type === 'mcp-app'
-                    ? MCP_APP_NODE_DEFAULT_SIZE.height
-                    : type === 'image'
-                      ? IMAGE_NODE_DEFAULT_SIZE.height
-                      : type === 'ledger'
-                        ? LEDGER_NODE_DEFAULT_SIZE.height
-                        : 200,
-              fileMode: 'auto',
-            });
-            result = { ok: true, ...serializeCreatedNode(created.node) };
-          }
-          break;
-        }
-        case 'node.update': {
-          const id = typeof args.id === 'string' ? args.id : '';
-          const node = canvasState.getNode(id);
-          if (!node) throw new Error(`Node "${id}" not found.`);
-          const patch: Partial<CanvasNodeState> = {};
-          if (typeof args.x === 'number' || typeof args.y === 'number') {
-            patch.position = {
-              x: typeof args.x === 'number' ? args.x : node.position.x,
-              y: typeof args.y === 'number' ? args.y : node.position.y,
-            };
-          }
-          if (typeof args.width === 'number' || typeof args.height === 'number') {
-            patch.size = {
-              width: typeof args.width === 'number' ? args.width : node.size.width,
-              height: typeof args.height === 'number' ? args.height : node.size.height,
-            };
-          }
-          if (typeof args.collapsed === 'boolean') patch.collapsed = args.collapsed;
-          if (typeof args.pinned === 'boolean') patch.pinned = args.pinned;
-          if (args.dockPosition === null || args.dockPosition === 'left' || args.dockPosition === 'right') {
-            patch.dockPosition = args.dockPosition;
-          }
-          if (typeof args.title === 'string' || typeof args.content === 'string' || typeof args.arrangeLocked === 'boolean' || typeof args.strictSize === 'boolean' || isPlainRecord(args.data)) {
-            patch.data = {
-              ...node.data,
-              ...(typeof args.title === 'string' ? { title: args.title } : {}),
-              ...(typeof args.content === 'string' ? { content: args.content } : {}),
-              ...(typeof args.arrangeLocked === 'boolean' ? { arrangeLocked: args.arrangeLocked } : {}),
-              ...(typeof args.strictSize === 'boolean' ? { strictSize: args.strictSize } : {}),
-              ...(isPlainRecord(args.data) ? args.data : {}),
-            };
-          }
-          canvasState.updateNode(id, patch);
-          const updated = canvasState.getNode(id);
-          result = { ok: true, ...(updated ? serializeCreatedNode(updated) : { id }) };
-          break;
-        }
-        case 'node.remove': {
-          const id = typeof args.id === 'string' ? args.id : '';
-          const { removed } = removeCanvasNode(id);
-          if (!removed) throw new Error(`Node "${id}" not found.`);
-          result = { ok: true, id, removed: true };
-          break;
-        }
-        case 'graph.add': {
-          const created = createCanvasGraphNode({
-            graphType: String(args.graphType ?? 'line'),
-            data: Array.isArray(args.data) ? args.data.filter((item): item is Record<string, unknown> => isPlainRecord(item)) : [],
-            ...(typeof args.title === 'string' ? { title: args.title } : {}),
-            ...(typeof args.xKey === 'string' ? { xKey: args.xKey } : {}),
-            ...(typeof args.yKey === 'string' ? { yKey: args.yKey } : {}),
-            ...(typeof args.zKey === 'string' ? { zKey: args.zKey } : {}),
-            ...(typeof args.nameKey === 'string' ? { nameKey: args.nameKey } : {}),
-            ...(typeof args.valueKey === 'string' ? { valueKey: args.valueKey } : {}),
-            ...(typeof args.axisKey === 'string' ? { axisKey: args.axisKey } : {}),
-            ...(Array.isArray(args.metrics) ? { metrics: args.metrics.filter((m): m is string => typeof m === 'string') } : {}),
-            ...(Array.isArray(args.series) ? { series: args.series.filter((s): s is string => typeof s === 'string') } : {}),
-            ...(typeof args.barKey === 'string' ? { barKey: args.barKey } : {}),
-            ...(typeof args.lineKey === 'string' ? { lineKey: args.lineKey } : {}),
-            ...(args.aggregate === 'sum' || args.aggregate === 'count' || args.aggregate === 'avg'
-              ? { aggregate: args.aggregate }
-              : {}),
-            ...(typeof args.color === 'string' ? { color: args.color } : {}),
-            ...(typeof args.barColor === 'string' ? { barColor: args.barColor } : {}),
-            ...(typeof args.lineColor === 'string' ? { lineColor: args.lineColor } : {}),
-            ...(typeof args.height === 'number' ? { height: args.height } : {}),
-            ...(typeof args.x === 'number' ? { x: args.x } : {}),
-            ...(typeof args.y === 'number' ? { y: args.y } : {}),
-            ...(typeof args.width === 'number' ? { width: args.width } : {}),
-            ...(typeof args.nodeHeight === 'number' ? { heightPx: args.nodeHeight } : {}),
-            ...(args.strictSize === true ? { strictSize: true } : {}),
-          });
-          result = {
-            ok: true,
-            ...serializeCreatedNode(created.node),
-            url: created.url,
-            spec: created.spec,
-          };
-          break;
-        }
-        case 'edge.add': {
-          const added = addCanvasEdge({
-            ...(typeof args.from === 'string' ? { from: args.from } : {}),
-            ...(typeof args.to === 'string' ? { to: args.to } : {}),
-            ...(typeof args.fromSearch === 'string' ? { fromSearch: args.fromSearch } : {}),
-            ...(typeof args.toSearch === 'string' ? { toSearch: args.toSearch } : {}),
-            type: String(args.type) as CanvasEdge['type'],
-            ...(typeof args.label === 'string' ? { label: args.label } : {}),
-            ...(typeof args.style === 'string' ? { style: args.style as CanvasEdge['style'] } : {}),
-            ...(typeof args.animated === 'boolean' ? { animated: args.animated } : {}),
-          });
-          result = { ok: true, ...added };
-          break;
-        }
-        case 'group.create': {
-          const created = createCanvasGroup({
-            ...(typeof args.title === 'string' ? { title: args.title } : {}),
-            ...(Array.isArray(args.childIds) ? { childIds: args.childIds.filter((id): id is string => typeof id === 'string') } : {}),
-            ...(typeof args.x === 'number' ? { x: args.x } : {}),
-            ...(typeof args.y === 'number' ? { y: args.y } : {}),
-            ...(typeof args.width === 'number' ? { width: args.width } : {}),
-            ...(typeof args.height === 'number' ? { height: args.height } : {}),
-            ...(typeof args.color === 'string' ? { color: args.color } : {}),
-            ...(args.childLayout === 'grid' || args.childLayout === 'column' || args.childLayout === 'flow'
-              ? { childLayout: args.childLayout }
-              : {}),
-          });
-          result = { ok: true, ...serializeCreatedNode(created.node) };
-          break;
-        }
-        case 'group.add': {
-          const groupId = typeof args.groupId === 'string' ? args.groupId : '';
-          const childIds = Array.isArray(args.childIds) ? args.childIds.filter((id): id is string => typeof id === 'string') : [];
-          const ok = canvasState.groupNodes(groupId, childIds, {
-            preservePositions: args.childLayout === undefined,
-            ...(args.childLayout === 'grid' || args.childLayout === 'column' || args.childLayout === 'flow'
-              ? { layout: args.childLayout }
-              : {}),
-          });
-          if (!ok) throw new Error('Group not found or no valid children.');
-          const group = canvasState.getNode(groupId);
-          result = { ok: true, ...(group ? serializeCreatedNode(group) : { id: groupId }) };
-          break;
-        }
-        case 'group.remove': {
-          const groupId = typeof args.groupId === 'string' ? args.groupId : '';
-          const ok = canvasState.ungroupNodes(groupId);
-          if (!ok) throw new Error('Group not found or empty.');
-          result = { ok: true, groupId };
-          break;
-        }
-        case 'pin.set':
-        case 'pin.add':
-        case 'pin.remove': {
-          const ids = Array.isArray(args.nodeIds) ? args.nodeIds.filter((id): id is string => typeof id === 'string') : [];
-          result = {
-            ok: true,
-            ...setCanvasContextPins(ids, operation.op === 'pin.set' ? 'set' : operation.op === 'pin.add' ? 'add' : 'remove'),
-          };
-          break;
-        }
-        case 'snapshot.save': {
-          const snapshot = saveCanvasSnapshot(typeof args.name === 'string' ? args.name : '');
-          if (!snapshot) throw new Error('Failed to save snapshot.');
-          result = { ok: true, snapshot };
-          break;
-        }
-        case 'arrange': {
-          const layout =
-            args.layout === 'column' || args.layout === 'flow' || args.layout === 'grid'
-              ? args.layout
-              : 'grid';
-          result = { ok: true, ...arrangeCanvasNodes(layout) };
-          break;
-        }
-        default:
-          throw new Error(`Unsupported batch operation "${operation.op}".`);
-      }
-
-      results.push(result);
-      if (typeof operation.assign === 'string' && operation.assign.trim().length > 0) {
-        refs[operation.assign] = result;
-      }
-    } catch (error) {
-      return {
-        ok: false,
-        failedIndex: index,
-        error: error instanceof Error ? error.message : String(error),
-        results,
-        refs,
-      };
-    }
-  }
-
-  return { ok: true, results, refs };
-}

package/src/server/canvas-schema.ts

@@ -244,7 +244,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'node',
     description: 'Sandboxed iframe node rendered from inline HTML.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_html_node',
+    mcpTool: 'canvas_node (action:"add", type:"html")',
     fields: [
       { name: 'html', type: 'string', required: false, description: 'HTML document or fragment rendered in the sandboxed iframe.', aliases: ['content', 'stdin'] },
       { name: 'summary', type: 'string', required: false, description: 'Explicit agent-readable summary. If omitted, PMX derives one from visible HTML text.' },
@@ -281,7 +281,7 @@ const CANVAS_CREATE_TYPES: CanvasCreateTypeSchema[] = [
     kind: 'virtual-node',
     description: 'Reusable sandboxed HTML communication primitive rendered as an html node.',
     endpoint: '/api/canvas/node',
-    mcpTool: 'canvas_add_html_primitive',
+    mcpTool: 'canvas_node (action:"add", type:"html", primitive:"<kind>")',
     fields: [
       { name: 'kind', type: 'HtmlPrimitiveKind', required: true, description: 'Primitive kind. See top-level htmlPrimitives for the supported catalog.' },
       { name: 'data', type: 'record<string, unknown>', required: false, description: 'Primitive-specific JSON object payload.' },