pmx-canvas 0.3.0 → 0.3.1

package/src/mcp/server.ts

@@ -197,12 +197,19 @@ function compactNodePayload(node: Awaited<ReturnType<CanvasAccess['getNode']>>):
   };
 }
 
-function compactLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>, pinnedIds: string[]): Record<string, unknown> {
+function compactLayoutPayload(
+  layout: Awaited<ReturnType<CanvasAccess['getLayout']>>,
+  pinnedIds: string[],
+): Record<string, unknown> {
   return {
     summary: buildSummaryFromLayout(layout, pinnedIds),
     viewport: layout.viewport,
-    annotations: (layout.annotations ?? []).map((annotation) => summarizeCanvasAnnotationForContext(annotation, layout.nodes)),
-    nodes: layout.nodes.map((node) => compactNodePayload(node)).filter((node): node is Record<string, unknown> => node !== null),
+    annotations: (layout.annotations ?? []).map((annotation) =>
+      summarizeCanvasAnnotationForContext(annotation, layout.nodes),
+    ),
+    nodes: layout.nodes
+      .map((node) => compactNodePayload(node))
+      .filter((node): node is Record<string, unknown> => node !== null),
     edges: layout.edges.map((edge) => ({
       id: edge.id,
       from: edge.from,
@@ -218,11 +225,16 @@ function compactLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout
 function agentSafeFullLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>): Record<string, unknown> {
   return {
     ...serializeCanvasLayoutForAgent(layout),
-    annotations: (layout.annotations ?? []).map((annotation) => summarizeCanvasAnnotationForContext(annotation, layout.nodes)),
+    annotations: (layout.annotations ?? []).map((annotation) =>
+      summarizeCanvasAnnotationForContext(annotation, layout.nodes),
+    ),
   };
 }
 
-function buildSummaryFromLayout(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>, pinnedIds: string[]): Record<string, unknown> {
+function buildSummaryFromLayout(
+  layout: Awaited<ReturnType<CanvasAccess['getLayout']>>,
+  pinnedIds: string[],
+): Record<string, unknown> {
   const pinned = new Set(pinnedIds);
   const nodesByType: Record<string, number> = {};
   const pinnedTitles: string[] = [];
@@ -235,7 +247,9 @@ function buildSummaryFromLayout(layout: Awaited<ReturnType<CanvasAccess['getLayo
     totalNodes: layout.nodes.length,
     totalEdges: layout.edges.length,
     totalAnnotations: (layout.annotations ?? []).length,
-    annotations: (layout.annotations ?? []).map((annotation) => summarizeCanvasAnnotationForContext(annotation, layout.nodes)),
+    annotations: (layout.annotations ?? []).map((annotation) =>
+      summarizeCanvasAnnotationForContext(annotation, layout.nodes),
+    ),
     nodesByType,
     pinnedCount: pinned.size,
     pinnedTitles,
@@ -276,12 +290,18 @@ export async function startMcpServer(): Promise<void> {
     'canvas_ax_interaction',
     'Submit a node-originated AX interaction: a capability-gated, validated event from an eligible node that maps onto an AX operation (work item, evidence, approval, review, focus, steering, event). Returns { ok: false, code } if the node type/metadata does not allow the interaction type or the payload is invalid.',
     {
-      type: z.enum(AX_INTERACTION_TYPES).describe('Interaction type, e.g. ax.work.create, ax.evidence.add, ax.focus.set.'),
+      type: z
+        .enum(AX_INTERACTION_TYPES)
+        .describe('Interaction type, e.g. ax.work.create, ax.evidence.add, ax.focus.set.'),
       sourceNodeId: z.string().describe('The node emitting the interaction.'),
-      payload: z.record(z.string(), z.unknown()).optional().describe('Type-specific payload, e.g. {"title":"..."} for ax.work.create.'),
+      payload: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('Type-specific payload, e.g. {"title":"..."} for ax.work.create.'),
       sourceSurface: z.enum(['native-node', 'json-render', 'html-node', 'mcp-app', 'adapter']).optional(),
       correlationId: z.string().optional(),
-      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+      source: z
+        .enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
         .optional()
         .describe('Optional host/source label. Defaults to mcp.'),
     },
@@ -319,29 +339,59 @@ export async function startMcpServer(): Promise<void> {
     'canvas_ingest_activity',
     'Ingest a normalized agent activity (a tool/session event your harness forwards) so the board reacts automatically — primitive A, makes AX bidirectional. Always records a timeline event; kind-driven default reactions (overridable per call via `reactions`): failure/error → work item (blocked) + review finding + evidence (logs); tool-result + outcome:"success" → evidence (tool-result); everything else (tool-start, session-*, command, note) → event only. Set any reaction to false to suppress it, or to an object to override its fields. Returns { event, workItem, evidence, review }.',
     {
-      kind: z.enum(['tool-start', 'tool-result', 'failure', 'error', 'session-start', 'session-end', 'command', 'note']),
+      kind: z.enum([
+        'tool-start',
+        'tool-result',
+        'failure',
+        'error',
+        'session-start',
+        'session-end',
+        'command',
+        'note',
+      ]),
       title: z.string(),
       summary: z.string().optional(),
       outcome: z.enum(['success', 'failure']).optional(),
-      ref: z.string().optional().describe('A file path, URL, or commit the activity refers to (used as the review file anchor for failures).'),
+      ref: z
+        .string()
+        .optional()
+        .describe('A file path, URL, or commit the activity refers to (used as the review file anchor for failures).'),
       nodeIds: z.array(z.string()).optional(),
       data: z.record(z.string(), z.unknown()).optional(),
-      reactions: z.object({
-        workItem: z.union([z.literal(false), z.object({
-          status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'cancelled']).optional(),
-          detail: z.string().nullable().optional(),
-        })]).optional(),
-        evidence: z.union([z.literal(false), z.object({
-          kind: z.enum(['logs', 'tool-result', 'screenshot', 'file', 'diff', 'test-output']).optional(),
-          body: z.string().nullable().optional(),
-        })]).optional(),
-        review: z.union([z.literal(false), z.object({
-          severity: z.enum(['info', 'warning', 'error']).optional(),
-          kind: z.enum(['comment', 'finding']).optional(),
-          anchorType: z.enum(['node', 'file', 'region']).optional(),
-          nodeId: z.string().nullable().optional(),
-        })]).optional(),
-      }).optional().describe('Override or suppress the kind-driven default reactions.'),
+      reactions: z
+        .object({
+          workItem: z
+            .union([
+              z.literal(false),
+              z.object({
+                status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'cancelled']).optional(),
+                detail: z.string().nullable().optional(),
+              }),
+            ])
+            .optional(),
+          evidence: z
+            .union([
+              z.literal(false),
+              z.object({
+                kind: z.enum(['logs', 'tool-result', 'screenshot', 'file', 'diff', 'test-output']).optional(),
+                body: z.string().nullable().optional(),
+              }),
+            ])
+            .optional(),
+          review: z
+            .union([
+              z.literal(false),
+              z.object({
+                severity: z.enum(['info', 'warning', 'error']).optional(),
+                kind: z.enum(['comment', 'finding']).optional(),
+                anchorType: z.enum(['node', 'file', 'region']).optional(),
+                nodeId: z.string().nullable().optional(),
+              }),
+            ])
+            .optional(),
+        })
+        .optional()
+        .describe('Override or suppress the kind-driven default reactions.'),
       source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']).optional(),
     },
     async ({ kind, title, summary, outcome, ref, nodeIds, data, reactions, source }) => {
@@ -391,7 +441,10 @@ export async function startMcpServer(): Promise<void> {
     'canvas_screenshot',
     'Capture a screenshot from the active Bun.WebView automation session. Returns both an MCP image payload and JSON metadata. Requires an active automation session started via canvas_webview with action "start".',
     {
-      format: z.enum(['png', 'jpeg', 'webp']).optional().describe('Screenshot format (default depends on Bun; png recommended)'),
+      format: z
+        .enum(['png', 'jpeg', 'webp'])
+        .optional()
+        .describe('Screenshot format (default depends on Bun; png recommended)'),
       quality: z.number().optional().describe('Optional quality for lossy formats'),
     },
     async ({ format, quality }) => {
@@ -407,27 +460,21 @@ export async function startMcpServer(): Promise<void> {
             {
               type: 'image',
               data: encodeBase64(bytes),
-              mimeType:
-                format === 'jpeg'
-                  ? 'image/jpeg'
-                  : format === 'webp'
-                    ? 'image/webp'
-                    : 'image/png',
+              mimeType: format === 'jpeg' ? 'image/jpeg' : format === 'webp' ? 'image/webp' : 'image/png',
             },
             {
               type: 'text',
-              text: JSON.stringify({
-                bytes: bytes.byteLength,
-                backend: status.backend,
-                width: status.width,
-                height: status.height,
-                mimeType:
-                  format === 'jpeg'
-                    ? 'image/jpeg'
-                    : format === 'webp'
-                      ? 'image/webp'
-                      : 'image/png',
-              }, null, 2),
+              text: JSON.stringify(
+                {
+                  bytes: bytes.byteLength,
+                  backend: status.backend,
+                  width: status.width,
+                  height: status.height,
+                  mimeType: format === 'jpeg' ? 'image/jpeg' : format === 'webp' ? 'image/webp' : 'image/png',
+                },
+                null,
+                2,
+              ),
             },
           ],
         };
@@ -449,8 +496,7 @@ export async function startMcpServer(): Promise<void> {
     'schema',
     'canvas://schema',
     {
-      description:
-        `Machine-readable create schemas, canonical examples, json-render catalog details, and MCP node-type routing from the running PMX Canvas server version. Routing: ${structuredSchemaDescription()}.`,
+      description: `Machine-readable create schemas, canonical examples, json-render catalog details, and MCP node-type routing from the running PMX Canvas server version. Routing: ${structuredSchemaDescription()}.`,
       mimeType: 'application/json',
     },
     async () => ({
@@ -480,20 +526,20 @@ export async function startMcpServer(): Promise<void> {
       const layout = await c.getLayout();
 
       const pinnedNodes = layout.nodes.filter((n) => pinnedIds.has(n.id));
-      const pinnedEdges = layout.edges.filter(
-        (e) => pinnedIds.has(e.from) && pinnedIds.has(e.to),
-      );
+      const pinnedEdges = layout.edges.filter((e) => pinnedIds.has(e.from) && pinnedIds.has(e.to));
 
       // Compute neighborhoods: for each pinned node, find nearby unpinned nodes
       const neighborhoods = findNeighborhoods(layout.nodes, pinnedIds);
 
       const context = {
         pinnedCount: pinnedNodes.length,
-        nodes: pinnedNodes.map((n) => serializeNodeForAgentContext(n, {
-          defaultTextLength: 700,
-          webpageTextLength: 1600,
-          includePosition: true,
-        })),
+        nodes: pinnedNodes.map((n) =>
+          serializeNodeForAgentContext(n, {
+            defaultTextLength: 700,
+            webpageTextLength: 1600,
+            includePosition: true,
+          }),
+        ),
         edges: pinnedEdges.map((e) => ({
           id: e.id,
           from: e.from,
@@ -547,8 +593,7 @@ export async function startMcpServer(): Promise<void> {
     'ax-context',
     'canvas://ax-context',
     {
-      description:
-        'Agent-ready PMX AX context combining pinned context, focus, and surface metadata.',
+      description: 'Agent-ready PMX AX context combining pinned context, focus, and surface metadata.',
       mimeType: 'application/json',
     },
     async () => {
@@ -606,14 +651,18 @@ export async function startMcpServer(): Promise<void> {
           {
             uri: 'canvas://ax-work',
             mimeType: 'application/json',
-            text: JSON.stringify({
-              workItems,
-              approvalGates,
-              reviewAnnotations: state.reviewAnnotations,
-              elicitations: state.elicitations,
-              modeRequests: state.modeRequests,
-              policy: state.policy,
-            }, null, 2),
+            text: JSON.stringify(
+              {
+                workItems,
+                approvalGates,
+                reviewAnnotations: state.reviewAnnotations,
+                elicitations: state.elicitations,
+                modeRequests: state.modeRequests,
+                policy: state.policy,
+              },
+              null,
+              2,
+            ),
           },
         ],
       };
@@ -634,7 +683,11 @@ export async function startMcpServer(): Promise<void> {
       const pendingActivity = buildPendingAxActivity(state);
       return {
         contents: [
-          { uri: 'canvas://ax-pending-steering', mimeType: 'application/json', text: JSON.stringify({ pending, pendingActivity }, null, 2) },
+          {
+            uri: 'canvas://ax-pending-steering',
+            mimeType: 'application/json',
+            text: JSON.stringify({ pending, pendingActivity }, null, 2),
+          },
         ],
       };
     },
@@ -653,7 +706,11 @@ export async function startMcpServer(): Promise<void> {
       const timeline = await c.getAxTimeline();
       return {
         contents: [
-          { uri: 'canvas://ax-delivery', mimeType: 'application/json', text: JSON.stringify({ steering: timeline.steering }, null, 2) },
+          {
+            uri: 'canvas://ax-delivery',
+            mimeType: 'application/json',
+            text: JSON.stringify({ steering: timeline.steering }, null, 2),
+          },
         ],
       };
     },
@@ -732,13 +789,18 @@ export async function startMcpServer(): Promise<void> {
         'grouped together), provides reading order (top-left to bottom-right), and shows ' +
         'neighborhoods around pinned nodes (nearby unpinned nodes the human implicitly associated). ' +
         'This makes "spatial arrangement is communication" real — read this to understand the ' +
-        'human\'s spatial intent, not just which nodes are pinned.',
+        "human's spatial intent, not just which nodes are pinned.",
       mimeType: 'application/json',
     },
     async () => {
       const c = await ensureCanvas();
       const layout = await c.getLayout();
-      const spatial = buildSpatialContext(layout.nodes, layout.edges, new Set(await c.getPinnedNodeIds()), layout.annotations ?? []);
+      const spatial = buildSpatialContext(
+        layout.nodes,
+        layout.edges,
+        new Set(await c.getPinnedNodeIds()),
+        layout.annotations ?? [],
+      );
       return {
         contents: [
           {

package/src/server/agent-context.ts

@@ -56,11 +56,8 @@ function summarizeWebpageData(data: Record<string, unknown>, maxLength: number):
   const status = typeof data.status === 'string' ? data.status : '';
   const statusCode = typeof data.statusCode === 'number' ? data.statusCode : null;
   const error = typeof data.error === 'string' ? data.error : '';
-  const content = typeof data.content === 'string'
-    ? data.content
-    : typeof data.excerpt === 'string'
-      ? data.excerpt
-      : '';
+  const content =
+    typeof data.content === 'string' ? data.content : typeof data.excerpt === 'string' ? data.excerpt : '';
 
   if (url) parts.push(`URL: ${url}`);
   if (pageTitle) parts.push(`Title: ${pageTitle}`);
@@ -132,9 +129,7 @@ function summarizeWebArtifactData(data: Record<string, unknown>, maxLength: numb
   const sourceFiles = Array.isArray(data.sourceFiles)
     ? data.sourceFiles.filter((file): file is string => typeof file === 'string')
     : [];
-  const deps = Array.isArray(data.deps)
-    ? data.deps.filter((dep): dep is string => typeof dep === 'string')
-    : [];
+  const deps = Array.isArray(data.deps) ? data.deps.filter((dep): dep is string => typeof dep === 'string') : [];
 
   if (content) parts.push(content);
   if (!content && title) parts.push(`Web artifact: ${title}`);
@@ -170,7 +165,16 @@ function metadataForNode(node: CanvasNodeState): Record<string, unknown> | undef
   switch (node.type) {
     case 'webpage': {
       const metadata: Record<string, unknown> = {};
-      for (const key of ['url', 'pageTitle', 'description', 'imageUrl', 'fetchedAt', 'status', 'statusCode', 'contentType']) {
+      for (const key of [
+        'url',
+        'pageTitle',
+        'description',
+        'imageUrl',
+        'fetchedAt',
+        'status',
+        'statusCode',
+        'contentType',
+      ]) {
         const value = node.data[key];
         if (value !== undefined && value !== null && value !== '') metadata[key] = value;
       }
@@ -194,7 +198,19 @@ function metadataForNode(node: CanvasNodeState): Record<string, unknown> | undef
     }
     case 'html': {
       const metadata: Record<string, unknown> = {};
-      for (const key of ['summary', 'description', 'agentSummary', 'contentSummary', 'htmlPrimitive', 'presentation', 'slideCount', 'slideTitles', 'speakerNotes', 'embeddedNodeIds', 'embeddedUrls']) {
+      for (const key of [
+        'summary',
+        'description',
+        'agentSummary',
+        'contentSummary',
+        'htmlPrimitive',
+        'presentation',
+        'slideCount',
+        'slideTitles',
+        'speakerNotes',
+        'embeddedNodeIds',
+        'embeddedUrls',
+      ]) {
         const value = node.data[key];
         if (Array.isArray(value)) {
           if (value.length > 0) metadata[key] = value;
@@ -206,7 +222,22 @@ function metadataForNode(node: CanvasNodeState): Record<string, unknown> | undef
     }
     case 'mcp-app': {
       const metadata: Record<string, unknown> = {};
-      for (const key of ['url', 'path', 'mode', 'hostMode', 'viewerType', 'serverName', 'toolName', 'resourceUri', 'sessionStatus', 'projectPath', 'artifactBytes', 'sourceFiles', 'sourceFileCount', 'deps']) {
+      for (const key of [
+        'url',
+        'path',
+        'mode',
+        'hostMode',
+        'viewerType',
+        'serverName',
+        'toolName',
+        'resourceUri',
+        'sessionStatus',
+        'projectPath',
+        'artifactBytes',
+        'sourceFiles',
+        'sourceFileCount',
+        'deps',
+      ]) {
         const value = node.data[key];
         if (Array.isArray(value)) {
           if (value.length > 0) metadata[key] = value;
@@ -221,10 +252,7 @@ function metadataForNode(node: CanvasNodeState): Record<string, unknown> | undef
   }
 }
 
-export function summarizeNodeForAgentContext(
-  node: CanvasNodeState,
-  options: AgentContextOptions = {},
-): string {
+export function summarizeNodeForAgentContext(node: CanvasNodeState, options: AgentContextOptions = {}): string {
   const defaultTextLength = options.defaultTextLength ?? DEFAULT_CONTEXT_TEXT_LENGTH;
   const webpageTextLength = options.webpageTextLength ?? DEFAULT_WEBPAGE_CONTEXT_TEXT_LENGTH;
 
@@ -241,9 +269,7 @@ export function summarizeNodeForAgentContext(
       if (chartCfg) {
         const chartTitle = (chartCfg.title as string) || 'Untitled chart';
         const chartType = (chartCfg.type as string) || 'unknown';
-        const labels = Array.isArray(chartCfg.labels)
-          ? (chartCfg.labels as string[]).join(', ')
-          : '';
+        const labels = Array.isArray(chartCfg.labels) ? (chartCfg.labels as string[]).join(', ') : '';
         return truncateContextText(`Chart: ${chartTitle} (${chartType}). Labels: ${labels}`, defaultTextLength);
       }
       return summarizeMcpAppData(node.data, defaultTextLength);
@@ -263,14 +289,17 @@ export function summarizeNodeForAgentContext(
       if (typeof node.data.htmlPrimitive === 'string') {
         return summarizeHtmlPrimitiveData(node.data, defaultTextLength);
       }
-      return stringifyContextValue({
-        title: node.data.title,
-        description: node.data.description,
-        summary: node.data.summary,
-        contentSummary: node.data.contentSummary,
-        embeddedNodeIds: node.data.embeddedNodeIds,
-        embeddedUrls: node.data.embeddedUrls,
-      }, defaultTextLength);
+      return stringifyContextValue(
+        {
+          title: node.data.title,
+          description: node.data.description,
+          summary: node.data.summary,
+          contentSummary: node.data.contentSummary,
+          embeddedNodeIds: node.data.embeddedNodeIds,
+          embeddedUrls: node.data.embeddedUrls,
+        },
+        defaultTextLength,
+      );
     }
     case 'prompt':
     case 'response': {
@@ -279,11 +308,12 @@ export function summarizeNodeForAgentContext(
     }
     case 'file': {
       const path = typeof node.data.path === 'string' ? node.data.path : '';
-      const fileContent = typeof node.data.fileContent === 'string'
-        ? node.data.fileContent
-        : typeof node.data.content === 'string'
-          ? node.data.content
-          : '';
+      const fileContent =
+        typeof node.data.fileContent === 'string'
+          ? node.data.fileContent
+          : typeof node.data.content === 'string'
+            ? node.data.content
+            : '';
       const prefix = path ? `Path: ${path}\n\n` : '';
       const remaining = Math.max(0, defaultTextLength - prefix.length);
       return `${prefix}${truncateContextText(fileContent, remaining)}`.trim();
@@ -309,13 +339,10 @@ export function serializeNodeForAgentContext(
   };
 }
 
-export function buildAgentContextPreamble(
-  nodes: CanvasNodeState[],
-  options: AgentContextOptions = {},
-): string {
+export function buildAgentContextPreamble(nodes: CanvasNodeState[], options: AgentContextOptions = {}): string {
   const sections = nodes
     .map((node) => {
-      const title = (typeof node.data.title === 'string' && node.data.title) ? node.data.title : node.id;
+      const title = typeof node.data.title === 'string' && node.data.title ? node.data.title : node.id;
       const content = summarizeNodeForAgentContext(node, options);
       if (!content) return '';
       const kind = getCanvasNodeKind(node);

package/src/server/ax-context.ts

@@ -53,11 +53,13 @@ export function buildCanvasAxSurfaceSnapshot(): PmxAxSurfaceSnapshot {
 }
 
 function serializeNodes(nodes: CanvasNodeState[]) {
-  return nodes.map((node) => serializeNodeForAgentContext(node, {
-    defaultTextLength: 700,
-    webpageTextLength: 1600,
-    includePosition: true,
-  }));
+  return nodes.map((node) =>
+    serializeNodeForAgentContext(node, {
+      defaultTextLength: 700,
+      webpageTextLength: 1600,
+      includePosition: true,
+    }),
+  );
 }
 
 export function buildCanvasAxPinnedContext(): PmxAxPinnedContext {