npm - pmx-canvas - Versions diffs - 0.1.25 → 0.1.27 - Mend

pmx-canvas 0.1.25 → 0.1.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (63) hide show

package/.github/extensions/pmx-canvas/extension.mjs +191 -0
package/CHANGELOG.md +116 -0
package/Readme.md +74 -27
package/dist/canvas/index.js +82 -82
package/dist/json-render/index.css +1 -1
package/dist/json-render/index.js +944 -164
package/dist/types/json-render/catalog.d.ts +195 -20
package/dist/types/json-render/charts/components.d.ts +7 -0
package/dist/types/json-render/charts/definitions.d.ts +13 -1
package/dist/types/json-render/charts/tufte-components.d.ts +65 -0
package/dist/types/json-render/charts/tufte-definitions.d.ts +164 -0
package/dist/types/json-render/directives.d.ts +23 -0
package/dist/types/json-render/renderer/index.d.ts +1 -0
package/dist/types/json-render/server.d.ts +32 -1
package/dist/types/mcp/canvas-access.d.ts +62 -0
package/dist/types/server/ax-state.d.ts +170 -0
package/dist/types/server/canvas-db.d.ts +17 -1
package/dist/types/server/canvas-operations.d.ts +45 -0
package/dist/types/server/canvas-schema.d.ts +5 -1
package/dist/types/server/canvas-state.d.ts +95 -4
package/dist/types/server/index.d.ts +118 -2
package/dist/types/server/mutation-history.d.ts +1 -1
package/docs/cli.md +42 -0
package/docs/http-api.md +64 -0
package/docs/mcp.md +23 -5
package/docs/node-types.md +1 -1
package/docs/screenshots/codex-app.png +0 -0
package/docs/screenshots/github-copilot-app.png +0 -0
package/docs/sdk.md +19 -1
package/package.json +10 -7
package/skills/control-session-orchestrator/SKILL.md +359 -0
package/skills/control-session-orchestrator/evals/evals.json +75 -0
package/skills/data-analysis/SKILL.md +6 -0
package/skills/pmx-canvas/SKILL.md +63 -4
package/skills/pmx-canvas/references/github-copilot-app-adapter.md +6 -0
package/skills/tufte-viz/SKILL.md +157 -0
package/skills/tufte-viz/references/analytical-design.md +217 -0
package/skills/tufte-viz/references/tufte-principles.md +147 -0
package/src/cli/agent.ts +280 -2
package/src/cli/index.ts +2 -1
package/src/client/nodes/ExtAppFrame.tsx +23 -1
package/src/client/nodes/McpAppNode.tsx +6 -2
package/src/json-render/catalog.ts +22 -1
package/src/json-render/charts/components.tsx +97 -10
package/src/json-render/charts/definitions.ts +19 -2
package/src/json-render/charts/extra-components.tsx +5 -4
package/src/json-render/charts/tufte-components.tsx +383 -0
package/src/json-render/charts/tufte-definitions.ts +128 -0
package/src/json-render/directives.ts +29 -0
package/src/json-render/renderer/index.css +101 -0
package/src/json-render/renderer/index.tsx +33 -0
package/src/json-render/server.ts +257 -5
package/src/mcp/canvas-access.ts +261 -0
package/src/mcp/server.ts +500 -7
package/src/server/ax-context.ts +8 -3
package/src/server/ax-state.ts +447 -0
package/src/server/canvas-db.ts +184 -1
package/src/server/canvas-operations.ts +107 -0
package/src/server/canvas-schema.ts +26 -3
package/src/server/canvas-state.ts +349 -2
package/src/server/index.ts +250 -2
package/src/server/mutation-history.ts +6 -0
package/src/server/server.ts +428 -2

package/src/mcp/server.ts CHANGED Viewed

@@ -100,7 +100,7 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
 }
-function sendCanvasResourceNotifications(type: 'nodes' | 'pins' | 'ax' = 'nodes'): void {
+function sendCanvasResourceNotifications(type: 'nodes' | 'pins' | 'ax' | 'ax-timeline' = 'nodes'): void {
   const server = resourceNotificationServer;
   if (!server) return;
   try {
@@ -110,6 +110,12 @@ function sendCanvasResourceNotifications(type: 'nodes' | 'pins' | 'ax' = 'nodes'
     if (type === 'pins' || type === 'ax') {
       server.server.sendResourceUpdated({ uri: 'canvas://ax' });
       server.server.sendResourceUpdated({ uri: 'canvas://ax-context' });
+      server.server.sendResourceUpdated({ uri: 'canvas://ax-timeline' });
+      server.server.sendResourceUpdated({ uri: 'canvas://ax-work' });
+    }
+    if (type === 'ax-timeline') {
+      server.server.sendResourceUpdated({ uri: 'canvas://ax-timeline' });
+      server.server.sendResourceUpdated({ uri: 'canvas://ax-context' });
     }
     server.server.sendResourceUpdated({ uri: 'canvas://layout' });
     server.server.sendResourceUpdated({ uri: 'canvas://summary' });
@@ -126,7 +132,13 @@ function handleRemoteSseFrame(frame: string): void {
   const event = eventLine?.slice('event: '.length).trim() ?? '';
   if (!event || event === 'connected' || event === 'ping') return;
   sendCanvasResourceNotifications(
-    event === 'context-pins-changed' ? 'pins' : event === 'ax-state-changed' ? 'ax' : 'nodes',
+    event === 'context-pins-changed'
+      ? 'pins'
+      : event === 'ax-state-changed'
+        ? 'ax'
+        : event === 'ax-event-created'
+          ? 'ax-timeline'
+          : 'nodes',
   );
 }
@@ -363,6 +375,10 @@ export async function startMcpServer(): Promise<void> {
       width: z.number().optional().describe('Width in pixels (default: 720)'),
       height: z.number().optional().describe('Height in pixels (default: 600)'),
       strictSize: z.boolean().optional().describe('Keep explicit width/height fixed and scroll overflowing content instead of browser auto-fitting'),
+      children: z.array(z.string()).optional().describe('Group-only alias for childIds. Node IDs to include in a generic group node.'),
+      childIds: z.array(z.string()).optional().describe('Group-only field. Node IDs to include in a generic group node. Prefer canvas_create_group for groups.'),
+      childLayout: z.enum(['grid', 'column', 'flow']).optional().describe('Group-only optional layout for grouped children.'),
+      color: z.string().optional().describe('Group-only frame accent color.'),
       toolName: z.string().optional().describe('Trace node tool or operation label'),
       category: z.string().optional().describe('Trace node category: mcp, file, subagent, or other'),
       status: z.string().optional().describe('Trace node status: running, success, or failed'),
@@ -411,7 +427,7 @@ export async function startMcpServer(): Promise<void> {
     'canvas_add_html_node',
     'Add a normal html node: a self-contained HTML document (with optional inline <script> and CDN <script src="...">) rendered inside a sandboxed iframe (sandbox="allow-scripts"). This is the default HTML surface for reports, widgets, and bespoke visualizations. Presentation mode is opt-in: only pass presentation:true when the user explicitly asks for a deck/fullscreen presentation, or use canvas_add_html_primitive with kind="presentation". The iframe inherits live canvas theme tokens via injected CSS custom properties (both --c-* and common --color-* aliases) so authored HTML using var(--color-text-secondary), var(--color-bg), etc. renders cohesively. No same-origin access; no top-navigation; no forms. For declarative-only views with zero JS, prefer canvas_add_json_render_node. For React + shadcn + routing or multi-component apps, use canvas_build_web_artifact.',
     {
-      html: z.string().describe('HTML document or fragment. Full <html>...</html> documents are passed through with theme styles injected into <head>; bare fragments are wrapped in a minimal document. Inline <script> and remote CDN <script src="..."> are allowed.'),
+      html: z.string().describe('HTML document or fragment. Full <html>...</html> documents are passed through with theme styles injected into <head>; bare fragments are wrapped in a minimal document. Inline <script> and remote CDN <script src="..."> are allowed. If this is a bare path to an existing local .html/.htm file, the file contents are read and used as the HTML.'),
       title: z.string().optional().describe('Node title shown in the canvas titlebar.'),
       summary: z.string().optional().describe('Agent-readable semantic summary for this HTML node. If omitted, PMX derives one from visible HTML text.'),
       agentSummary: z.string().optional().describe('Explicit agent-readable summary. Alias for summary with higher priority when both are provided.'),
@@ -621,7 +637,7 @@ export async function startMcpServer(): Promise<void> {
       yKey: z.string().optional().describe('Y-axis key for line/bar graphs'),
       zKey: z.string().optional().describe('Optional bubble-size key for scatter charts'),
       nameKey: z.string().optional().describe('Slice name key for pie graphs'),
-      valueKey: z.string().optional().describe('Slice value key for pie graphs'),
+      valueKey: z.string().optional().describe('Value key for pie slices, sparkline, dot-plot, and the bullet measure'),
       axisKey: z.string().optional().describe('Category key for radar charts'),
       metrics: z.array(z.string()).optional().describe('Series keys to plot as radar polygons'),
       series: z.array(z.string()).optional().describe('Series keys for stacked-bar segments'),
@@ -629,8 +645,23 @@ export async function startMcpServer(): Promise<void> {
       lineKey: z.string().optional().describe('Line series key for composed charts'),
       aggregate: z.enum(['sum', 'count', 'avg']).optional().describe('Optional aggregation for repeated keys'),
       color: z.string().optional().describe('Optional graph color'),
+      colorBy: z.enum(['series', 'category', 'value', 'none']).optional().describe("Bar charts only: how bars are colored (default 'series')"),
+      highlight: z.union([z.number(), z.enum(['max', 'min'])]).nullable().optional().describe("Bar charts only, colorBy='series': which bar gets the accent"),
       barColor: z.string().optional().describe('Optional bar color for composed charts'),
       lineColor: z.string().optional().describe('Optional line color for composed charts'),
+      labelKey: z.string().optional().describe('Category label key for dot-plot / bullet / slopegraph rows'),
+      targetKey: z.string().optional().describe('Per-row target value key for bullet charts'),
+      rangesKey: z.string().optional().describe('Per-row qualitative band thresholds key (number[]) for bullet charts'),
+      beforeKey: z.string().optional().describe('Left-column value key for slopegraph'),
+      afterKey: z.string().optional().describe('Right-column value key for slopegraph'),
+      beforeLabel: z.string().optional().describe('Header label for the slopegraph left column'),
+      afterLabel: z.string().optional().describe('Header label for the slopegraph right column'),
+      sort: z.enum(['asc', 'desc', 'none']).optional().describe('Row sort order for dot-plot (defaults to desc)'),
+      fill: z.boolean().optional().describe('Sparkline: draw a light area fill under the line'),
+      showEndDot: z.boolean().optional().describe('Sparkline: draw a dot at the last point (default true)'),
+      showMinMax: z.boolean().optional().describe('Sparkline: mark the min and max points'),
+      showValue: z.boolean().optional().describe('Sparkline: print the last value inline'),
+      colorByDirection: z.boolean().optional().describe('Slopegraph: accent rising lines and mute falling ones (default off)'),
       height: z.number().optional().describe('Optional graph content height'),
     },
     async (input) => {
@@ -667,8 +698,23 @@ export async function startMcpServer(): Promise<void> {
                   ...(typeof input.lineKey === 'string' ? { lineKey: input.lineKey } : {}),
                   ...(typeof input.aggregate === 'string' ? { aggregate: input.aggregate } : {}),
                   ...(typeof input.color === 'string' ? { color: input.color } : {}),
+                  ...(typeof input.colorBy === 'string' ? { colorBy: input.colorBy } : {}),
+                  ...(input.highlight !== undefined ? { highlight: input.highlight } : {}),
                   ...(typeof input.barColor === 'string' ? { barColor: input.barColor } : {}),
                   ...(typeof input.lineColor === 'string' ? { lineColor: input.lineColor } : {}),
+                  ...(typeof input.labelKey === 'string' ? { labelKey: input.labelKey } : {}),
+                  ...(typeof input.targetKey === 'string' ? { targetKey: input.targetKey } : {}),
+                  ...(typeof input.rangesKey === 'string' ? { rangesKey: input.rangesKey } : {}),
+                  ...(typeof input.beforeKey === 'string' ? { beforeKey: input.beforeKey } : {}),
+                  ...(typeof input.afterKey === 'string' ? { afterKey: input.afterKey } : {}),
+                  ...(typeof input.beforeLabel === 'string' ? { beforeLabel: input.beforeLabel } : {}),
+                  ...(typeof input.afterLabel === 'string' ? { afterLabel: input.afterLabel } : {}),
+                  ...(typeof input.sort === 'string' ? { sort: input.sort } : {}),
+                  ...(typeof input.fill === 'boolean' ? { fill: input.fill } : {}),
+                  ...(typeof input.showEndDot === 'boolean' ? { showEndDot: input.showEndDot } : {}),
+                  ...(typeof input.showMinMax === 'boolean' ? { showMinMax: input.showMinMax } : {}),
+                  ...(typeof input.showValue === 'boolean' ? { showValue: input.showValue } : {}),
+                  ...(typeof input.colorByDirection === 'boolean' ? { colorByDirection: input.colorByDirection } : {}),
                   ...(typeof input.height === 'number' ? { height: input.height } : {}),
                 },
               });
@@ -827,19 +873,74 @@ export async function startMcpServer(): Promise<void> {
     },
   );
+  // ── canvas_stream_json_render_node ────────────────────────
+  server.tool(
+    'canvas_stream_json_render_node',
+    'Progressively build a json-render node by streaming SpecStream patches, so a panel fills in live as you generate it. Omit nodeId on the first call to create a new streaming node (returns its id); pass that same nodeId on later calls to append more patches; set done=true on the final call. Each call updates the live node. Patches are JSON-Patch operations, e.g. {"op":"add","path":"/elements/card","value":{"type":"Card","props":{"title":"Live"},"children":[]}}, {"op":"replace","path":"/root","value":"card"}, {"op":"add","path":"/elements/card/children/-","value":"row1"}. Build the spec incrementally: set /root, add container elements, then append children. The server accumulates the spec (it is the source of truth); partial specs render what they can.',
+    {
+      nodeId: z.string().optional().describe('Existing streaming node id to append to; omit to create a new streaming node'),
+      title: z.string().optional().describe('Title when creating a new streaming node'),
+      patches: z
+        .array(z.union([z.string(), z.record(z.string(), z.unknown())]))
+        .optional()
+        .describe('SpecStream patches to apply this call: JSON-Patch objects ({op,path,value}) or raw JSONL patch lines'),
+      done: z.boolean().optional().describe('Set true on the final call to mark the stream complete'),
+      x: z.number().optional().describe('Optional X position (new node)'),
+      y: z.number().optional().describe('Optional Y position (new node)'),
+      width: z.number().optional().describe('Optional node width (new node)'),
+      nodeHeight: z.number().optional().describe('Optional node height (new node)'),
+      strictSize: z.boolean().optional().describe('Keep explicit node size fixed and scroll overflowing content (new node)'),
+    },
+    async (input) => {
+      const c = await ensureCanvas();
+      try {
+        const result = await c.streamJsonRenderNode({
+          ...(typeof input.nodeId === 'string' ? { nodeId: input.nodeId } : {}),
+          ...(typeof input.title === 'string' ? { title: input.title } : {}),
+          ...(Array.isArray(input.patches) ? { patches: input.patches } : {}),
+          ...(input.done === true ? { done: true } : {}),
+          ...(typeof input.x === 'number' ? { x: input.x } : {}),
+          ...(typeof input.y === 'number' ? { y: input.y } : {}),
+          ...(typeof input.width === 'number' ? { width: input.width } : {}),
+          ...(typeof input.nodeHeight === 'number' ? { height: input.nodeHeight } : {}),
+          ...(input.strictSize === true ? { strictSize: true } : {}),
+        });
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              ...(await createdNodePayload(c, result.id)),
+              url: result.url,
+              applied: result.applied,
+              skipped: result.skipped,
+              specVersion: result.specVersion,
+              elementCount: result.elementCount,
+              streamStatus: result.streamStatus,
+            }, null, 2),
+          }],
+        };
+      } catch (error) {
+        return {
+          content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+          isError: true,
+        };
+      }
+    },
+  );
   // ── canvas_add_graph_node ─────────────────────────────────
   server.tool(
     'canvas_add_graph_node',
-    'Create a native graph node backed by the json-render chart catalog. Supports line, bar, pie, area, scatter, radar, stacked-bar, and composed (bar+line) graphs rendered directly inside PMX Canvas.',
+    'Create a native graph node backed by the json-render chart catalog. Supports line, bar, pie, area, scatter, radar, stacked-bar, composed (bar+line), sparkline, dot-plot (Cleveland), bullet (Few KPI vs target), and slopegraph (paired before/after) graphs rendered directly inside PMX Canvas.',
     {
       title: z.string().optional().describe('Optional node title'),
-      graphType: z.string().describe('Graph type: line, bar, pie, area, scatter, radar, stacked-bar (or "stack"), composed (or "combo")'),
+      graphType: z.string().describe('Graph type: line, bar, pie, area, scatter, radar, stacked-bar (or "stack"), composed (or "combo"), sparkline, dot-plot (or "dot"), bullet, slopegraph (or "slope")'),
       data: z.array(z.record(z.string(), z.unknown())).describe('Array of chart data objects'),
       xKey: z.string().optional().describe('X-axis key (line/bar/area/scatter/stacked/composed)'),
       yKey: z.string().optional().describe('Y-axis key (line/bar/area/scatter); falls back to barKey for composed'),
       zKey: z.string().optional().describe('Optional bubble-size key for scatter charts'),
       nameKey: z.string().optional().describe('Name key for pie graphs'),
-      valueKey: z.string().optional().describe('Value key for pie graphs'),
+      valueKey: z.string().optional().describe('Value key for pie slices, sparkline, dot-plot, and the bullet measure'),
       axisKey: z.string().optional().describe('Category key for radar charts'),
       metrics: z.array(z.string()).optional().describe('Series keys to plot as radar polygons (defaults to non-axis numeric columns)'),
       series: z.array(z.string()).optional().describe('Series keys for stacked-bar segments (defaults to non-x numeric columns)'),
@@ -847,8 +948,30 @@ export async function startMcpServer(): Promise<void> {
       lineKey: z.string().optional().describe('Line series key for composed charts'),
       aggregate: z.enum(['sum', 'count', 'avg']).optional().describe('Optional aggregation for repeated x-axis values (line/bar/area/stacked)'),
       color: z.string().optional().describe('Optional series color (line/bar/area/scatter)'),
+      colorBy: z
+        .enum(['series', 'category', 'value', 'none'])
+        .optional()
+        .describe("Bar charts only: how bars are colored. 'series' (default) = single accent with one highlighted bar; 'category' = rotate palette per bar; 'value' = shade by magnitude; 'none' = flat. Prefer 'series' — color should encode data, not decorate."),
+      highlight: z
+        .union([z.number(), z.enum(['max', 'min'])])
+        .nullable()
+        .optional()
+        .describe("Bar charts only, for colorBy='series': which bar gets the accent — 'max' (default), 'min', a 0-based index, or null for no emphasis."),
       barColor: z.string().optional().describe('Optional bar color for composed charts'),
       lineColor: z.string().optional().describe('Optional line color for composed charts'),
+      labelKey: z.string().optional().describe('Category label key for dot-plot / bullet / slopegraph rows'),
+      targetKey: z.string().optional().describe('Per-row target value key for bullet charts'),
+      rangesKey: z.string().optional().describe('Per-row qualitative band thresholds key (number[]) for bullet charts'),
+      beforeKey: z.string().optional().describe('Left-column value key for slopegraph'),
+      afterKey: z.string().optional().describe('Right-column value key for slopegraph'),
+      beforeLabel: z.string().optional().describe('Header label for the slopegraph left column'),
+      afterLabel: z.string().optional().describe('Header label for the slopegraph right column'),
+      sort: z.enum(['asc', 'desc', 'none']).optional().describe('Row sort order for dot-plot (defaults to desc)'),
+      fill: z.boolean().optional().describe('Sparkline: draw a light area fill under the line'),
+      showEndDot: z.boolean().optional().describe('Sparkline: draw a dot at the last point (default true)'),
+      showMinMax: z.boolean().optional().describe('Sparkline: mark the min and max points'),
+      showValue: z.boolean().optional().describe('Sparkline: print the last value inline'),
+      colorByDirection: z.boolean().optional().describe('Slopegraph: accent rising lines and mute falling ones (default off — lines use one neutral ink)'),
       height: z.number().optional().describe('Optional chart content height'),
       showLegend: z.boolean().optional().describe('Show chart legend when supported; pass false for compact node layouts'),
       showLabels: z.boolean().optional().describe('Show direct labels when supported, such as pie slice labels (defaults to true)'),
@@ -877,8 +1000,23 @@ export async function startMcpServer(): Promise<void> {
           ...(typeof input.lineKey === 'string' ? { lineKey: input.lineKey } : {}),
           ...(typeof input.aggregate === 'string' ? { aggregate: input.aggregate } : {}),
           ...(typeof input.color === 'string' ? { color: input.color } : {}),
+          ...(typeof input.colorBy === 'string' ? { colorBy: input.colorBy } : {}),
+          ...(input.highlight !== undefined ? { highlight: input.highlight } : {}),
           ...(typeof input.barColor === 'string' ? { barColor: input.barColor } : {}),
           ...(typeof input.lineColor === 'string' ? { lineColor: input.lineColor } : {}),
+          ...(typeof input.labelKey === 'string' ? { labelKey: input.labelKey } : {}),
+          ...(typeof input.targetKey === 'string' ? { targetKey: input.targetKey } : {}),
+          ...(typeof input.rangesKey === 'string' ? { rangesKey: input.rangesKey } : {}),
+          ...(typeof input.beforeKey === 'string' ? { beforeKey: input.beforeKey } : {}),
+          ...(typeof input.afterKey === 'string' ? { afterKey: input.afterKey } : {}),
+          ...(typeof input.beforeLabel === 'string' ? { beforeLabel: input.beforeLabel } : {}),
+          ...(typeof input.afterLabel === 'string' ? { afterLabel: input.afterLabel } : {}),
+          ...(typeof input.sort === 'string' ? { sort: input.sort } : {}),
+          ...(typeof input.fill === 'boolean' ? { fill: input.fill } : {}),
+          ...(typeof input.showEndDot === 'boolean' ? { showEndDot: input.showEndDot } : {}),
+          ...(typeof input.showMinMax === 'boolean' ? { showMinMax: input.showMinMax } : {}),
+          ...(typeof input.showValue === 'boolean' ? { showValue: input.showValue } : {}),
+          ...(typeof input.colorByDirection === 'boolean' ? { colorByDirection: input.colorByDirection } : {}),
           ...(typeof input.height === 'number' ? { height: input.height } : {}),
           ...(typeof input.showLegend === 'boolean' ? { showLegend: input.showLegend } : {}),
           ...(typeof input.showLabels === 'boolean' ? { showLabels: input.showLabels } : {}),
@@ -1144,6 +1282,7 @@ export async function startMcpServer(): Promise<void> {
     async ({ includeContext }) => {
       const c = await ensureCanvas();
       const state = await c.getAxState();
+      const host = await c.getHostCapability();
       const context = includeContext === false ? undefined : await c.getAxContext();
       return {
         content: [
@@ -1152,6 +1291,7 @@ export async function startMcpServer(): Promise<void> {
             text: JSON.stringify({
               ok: true,
               state,
+              host,
               ...(context ? { context } : {}),
             }),
           },
@@ -1183,6 +1323,312 @@ export async function startMcpServer(): Promise<void> {
     },
   );
+  server.tool(
+    'canvas_record_ax_event',
+    'Record a normalized AX timeline event (prompt/assistant-message/tool-start/tool-result/failure/approval/steering). Timeline events persist for diagnostics and continuity but are not restored by snapshots.',
+    {
+      kind: z.enum(['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering'])
+        .describe('Normalized event kind.'),
+      summary: z.string().describe('Short human-readable summary of the event.'),
+      detail: z.string().optional().describe('Optional longer detail or payload text.'),
+      nodeIds: z.array(z.string()).optional().describe('Optional node IDs this event relates to.'),
+      data: z.record(z.string(), z.unknown()).optional().describe('Optional structured data payload.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label. Defaults to mcp.'),
+    },
+    async ({ kind, summary, detail, nodeIds, data, source }) => {
+      const c = await ensureCanvas();
+      const event = await c.recordAxEvent(
+        {
+          kind,
+          summary,
+          ...(typeof detail === 'string' ? { detail } : {}),
+          ...(Array.isArray(nodeIds) ? { nodeIds } : {}),
+          ...(data ? { data } : {}),
+        },
+        { source: source ?? 'mcp' },
+      );
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ ok: true, event }),
+          },
+        ],
+      };
+    },
+  );
+  server.tool(
+    'canvas_send_steering',
+    'Record a steering message: a user instruction from the surface to the active agent session. Persisted on the AX timeline and exposed via canvas://ax-timeline.',
+    {
+      message: z.string().describe('The steering instruction to deliver to the active agent session.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label. Defaults to mcp.'),
+    },
+    async ({ message, source }) => {
+      const c = await ensureCanvas();
+      const steering = await c.sendSteering(message, { source: source ?? 'mcp' });
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ ok: true, steering }),
+          },
+        ],
+      };
+    },
+  );
+  server.tool(
+    'canvas_get_ax_timeline',
+    'Read the bounded AX timeline: recent agent-events, evidence, and steering messages plus counts. Use this for diagnostics and session continuity.',
+    {
+      limit: z.number().optional().describe('Max rows per timeline table (default 50, max 200).'),
+    },
+    async ({ limit }) => {
+      const c = await ensureCanvas();
+      const timeline = await c.getAxTimeline(
+        typeof limit === 'number' && limit > 0 ? { limit } : undefined,
+      );
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ ok: true, ...timeline }),
+          },
+        ],
+      };
+    },
+  );
+  server.tool(
+    'canvas_add_work_item',
+    'Add a canvas-bound AX work item: a visible task/plan/status tied to nodes and agent work. Work items participate in snapshots and are exposed via canvas://ax-work.',
+    {
+      title: z.string().describe('Short title of the work item.'),
+      status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'cancelled'])
+        .optional()
+        .describe('Work item status. Defaults to todo.'),
+      detail: z.string().optional().describe('Optional longer description.'),
+      nodeIds: z.array(z.string()).optional().describe('Optional node IDs this work item is tied to.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label. Defaults to mcp.'),
+    },
+    async ({ title, status, detail, nodeIds, source }) => {
+      const c = await ensureCanvas();
+      const workItem = await c.addWorkItem(
+        {
+          title,
+          ...(status ? { status } : {}),
+          ...(typeof detail === 'string' ? { detail } : {}),
+          ...(Array.isArray(nodeIds) ? { nodeIds } : {}),
+        },
+        { source: source ?? 'mcp' },
+      );
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, workItem }) }],
+      };
+    },
+  );
+  server.tool(
+    'canvas_update_work_item',
+    'Update a canvas-bound AX work item by ID (title/status/detail/nodeIds). Returns null if the work item does not exist.',
+    {
+      id: z.string().describe('Work item ID to update.'),
+      title: z.string().optional().describe('New title.'),
+      status: z.enum(['todo', 'in-progress', 'blocked', 'done', 'cancelled'])
+        .optional()
+        .describe('New status.'),
+      detail: z.string().optional().describe('New detail text.'),
+      nodeIds: z.array(z.string()).optional().describe('Replacement node IDs.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label. Defaults to mcp.'),
+    },
+    async ({ id, title, status, detail, nodeIds, source }) => {
+      const c = await ensureCanvas();
+      const workItem = await c.updateWorkItem(
+        id,
+        {
+          ...(typeof title === 'string' ? { title } : {}),
+          ...(status ? { status } : {}),
+          ...(typeof detail === 'string' ? { detail } : {}),
+          ...(Array.isArray(nodeIds) ? { nodeIds } : {}),
+        },
+        { source: source ?? 'mcp' },
+      );
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: workItem !== null, workItem }) }],
+      };
+    },
+  );
+  server.tool(
+    'canvas_request_approval',
+    'Request human approval before a high-impact AX action: creates a pending approval gate tied to nodes. Canvas-bound and snapshotted; exposed via canvas://ax-work.',
+    {
+      title: z.string().describe('Short title of what needs approval.'),
+      detail: z.string().optional().describe('Optional explanation of the action and its impact.'),
+      action: z.string().optional().describe('Optional machine-readable action identifier the approval gates.'),
+      nodeIds: z.array(z.string()).optional().describe('Optional node IDs this approval relates to.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label. Defaults to mcp.'),
+    },
+    async ({ title, detail, action, nodeIds, source }) => {
+      const c = await ensureCanvas();
+      const approvalGate = await c.requestApproval(
+        {
+          title,
+          ...(typeof detail === 'string' ? { detail } : {}),
+          ...(typeof action === 'string' ? { action } : {}),
+          ...(Array.isArray(nodeIds) ? { nodeIds } : {}),
+        },
+        { source: source ?? 'mcp' },
+      );
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, approvalGate }) }],
+      };
+    },
+  );
+  server.tool(
+    'canvas_resolve_approval',
+    'Resolve a pending approval gate by ID with approved or rejected. Returns null if the gate does not exist or is already resolved.',
+    {
+      id: z.string().describe('Approval gate ID to resolve.'),
+      decision: z.enum(['approved', 'rejected']).describe('Approval decision.'),
+      resolution: z.string().optional().describe('Optional human-readable resolution note.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label. Defaults to mcp.'),
+    },
+    async ({ id, decision, resolution, source }) => {
+      const c = await ensureCanvas();
+      const approvalGate = await c.resolveApproval(id, decision, {
+        ...(typeof resolution === 'string' ? { resolution } : {}),
+        source: source ?? 'mcp',
+      });
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: approvalGate !== null, approvalGate }) }],
+      };
+    },
+  );
+  server.tool(
+    'canvas_add_evidence',
+    'Record an AX evidence item (logs/tool-result/screenshot/file/diff/test-output) on the timeline. Evidence persists for diagnostics and continuity but is not restored by snapshots; exposed via canvas://ax-timeline.',
+    {
+      kind: z.enum(['logs', 'tool-result', 'screenshot', 'file', 'diff', 'test-output'])
+        .describe('Evidence kind.'),
+      title: z.string().describe('Short human-readable title for the evidence.'),
+      body: z.string().optional().describe('Optional inline body/content.'),
+      ref: z.string().optional().describe('Optional reference (path, URL, or external locator).'),
+      nodeIds: z.array(z.string()).optional().describe('Optional node IDs this evidence relates to.'),
+      data: z.record(z.string(), z.unknown()).optional().describe('Optional structured data payload.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label. Defaults to mcp.'),
+    },
+    async ({ kind, title, body, ref, nodeIds, data, source }) => {
+      const c = await ensureCanvas();
+      const evidence = await c.addEvidence(
+        {
+          kind,
+          title,
+          ...(typeof body === 'string' ? { body } : {}),
+          ...(typeof ref === 'string' ? { ref } : {}),
+          ...(Array.isArray(nodeIds) ? { nodeIds } : {}),
+          ...(data ? { data } : {}),
+        },
+        { source: source ?? 'mcp' },
+      );
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, evidence }) }],
+      };
+    },
+  );
+  server.tool(
+    'canvas_add_review_annotation',
+    'Add a canvas-bound review annotation: a comment or finding anchored to a node, file, or region. Review annotations participate in snapshots and are exposed via canvas://ax-work.',
+    {
+      body: z.string().describe('Annotation body text.'),
+      kind: z.enum(['comment', 'finding']).optional().describe('Annotation kind. Default comment.'),
+      severity: z.enum(['info', 'warning', 'error']).optional().describe('Severity. Default info.'),
+      anchorType: z.enum(['node', 'file', 'region']).optional().describe('Anchor type. Default node.'),
+      nodeId: z.string().optional().describe('Node ID when anchorType is node.'),
+      file: z.string().optional().describe('File path when anchorType is file.'),
+      region: z.object({
+        line: z.number().optional(),
+        endLine: z.number().optional(),
+        label: z.string().optional(),
+      }).optional().describe('Region descriptor when anchorType is region.'),
+      author: z.string().optional().describe('Optional author label.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label. Defaults to mcp.'),
+    },
+    async ({ body, kind, severity, anchorType, nodeId, file, region, author, source }) => {
+      const c = await ensureCanvas();
+      const reviewAnnotation = await c.addReviewAnnotation(
+        {
+          body,
+          ...(kind ? { kind } : {}),
+          ...(severity ? { severity } : {}),
+          ...(anchorType ? { anchorType } : {}),
+          ...(typeof nodeId === 'string' ? { nodeId } : {}),
+          ...(typeof file === 'string' ? { file } : {}),
+          ...(region ? { region } : {}),
+          ...(typeof author === 'string' ? { author } : {}),
+        },
+        { source: source ?? 'mcp' },
+      );
+      if (!reviewAnnotation) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ ok: false, error: 'node-anchored review annotation requires a nodeId that exists on the canvas.' }) }],
+          isError: true,
+        };
+      }
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, reviewAnnotation }) }],
+      };
+    },
+  );
+  server.tool(
+    'canvas_report_host_capability',
+    'Report host/session capability from an adapter: what the host can do (canvas/hooks/tools/sessionMessaging/permissions/files/uiPrompts). Stored for diagnostics; core does not depend on a host.',
+    {
+      host: z.string().optional().describe('Host identifier (e.g. copilot, codex).'),
+      canvas: z.boolean().optional(),
+      hooks: z.boolean().optional(),
+      tools: z.boolean().optional(),
+      sessionMessaging: z.boolean().optional(),
+      permissions: z.boolean().optional(),
+      files: z.boolean().optional(),
+      uiPrompts: z.boolean().optional(),
+      raw: z.record(z.string(), z.unknown()).optional().describe('Optional raw capability payload for diagnostics.'),
+      source: z.enum(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system'])
+        .optional()
+        .describe('Optional host/source label. Defaults to mcp.'),
+    },
+    async (input) => {
+      const c = await ensureCanvas();
+      const { source, ...capability } = input;
+      const host = await c.reportHostCapability(capability, { source: source ?? 'mcp' });
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ ok: true, host }) }],
+      };
+    },
+  );
   server.tool(
     'canvas_fit_view',
     'Fit the canvas viewport to all nodes or a selected subset. Useful before screenshots and whole-board review.',
@@ -1606,6 +2052,53 @@ export async function startMcpServer(): Promise<void> {
     },
   );
+  server.resource(
+    'ax-timeline',
+    'canvas://ax-timeline',
+    {
+      description:
+        'Bounded PMX AX timeline: recent agent-events, evidence, and steering messages with counts. Persisted for diagnostics and continuity; not restored by snapshots.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const c = await ensureCanvas();
+      const timeline = await c.getAxTimeline();
+      return {
+        contents: [
+          {
+            uri: 'canvas://ax-timeline',
+            mimeType: 'application/json',
+            text: JSON.stringify(timeline, null, 2),
+          },
+        ],
+      };
+    },
+  );
+  server.resource(
+    'ax-work',
+    'canvas://ax-work',
+    {
+      description:
+        'Canvas-bound PMX AX work state: work items, approval gates, and review annotations. Participates in snapshots and restore.',
+      mimeType: 'application/json',
+    },
+    async () => {
+      const c = await ensureCanvas();
+      const [workItems, approvalGates] = await Promise.all([c.listWorkItems(), c.listApprovalGates()]);
+      const state = await c.getAxState();
+      return {
+        contents: [
+          {
+            uri: 'canvas://ax-work',
+            mimeType: 'application/json',
+            text: JSON.stringify({ workItems, approvalGates, reviewAnnotations: state.reviewAnnotations }, null, 2),
+          },
+        ],
+      };
+    },
+  );
   server.resource(
     'canvas-layout',
     'canvas://layout',

package/src/server/ax-context.ts CHANGED Viewed

@@ -25,14 +25,19 @@ export function buildCanvasAxPinnedContext(): PmxAxPinnedContext {
 export function buildCanvasAxContext(): PmxAxContext {
   const layout = canvasState.getLayout();
-  const focus = canvasState.getAxFocus();
-  const focusNodes = focus.nodeIds
+  const ax = canvasState.getAxState();
+  const focusNodes = ax.focus.nodeIds
     .map((id) => canvasState.getNode(id))
     .filter((node): node is CanvasNodeState => node !== undefined);
   return buildAxContext({
     layout,
     pinned: buildCanvasAxPinnedContext(),
-    focus,
+    focus: ax.focus,
     focusNodes: serializeNodes(focusNodes),
+    workItems: ax.workItems,
+    approvalGates: ax.approvalGates,
+    reviewAnnotations: ax.reviewAnnotations,
+    timeline: canvasState.getAxTimelineSummary(),
+    host: canvasState.getHostCapability(),
   });
 }