pmx-canvas 0.7.3 → 0.8.2

package/src/mcp/canvas-app.ts

@@ -0,0 +1,318 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { summarizeNodeForAgentContext } from '../shared/agent-context.js';
+import type { CanvasNodeState } from '../server/canvas-state.js';
+import { OperationError } from '../server/operations/index.js';
+import { CANVAS_APP_URI, type CanvasAppSnapshot } from '../shared/canvas-app.js';
+import type { CanvasAccess } from './canvas-access.js';
+
+const readOnly = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+const additive = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+const editing = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
+const boardId = z.string().min(1).describe('Active board id from pmx_read_canvas; refuses a stale board.');
+const boardListSchema = z.array(z.object({ id: z.string(), name: z.string() }));
+const summaryShape = {
+  boardId: z.string().nullable(),
+  boardName: z.string(),
+  boards: boardListSchema,
+  revision: z.string(),
+  nodeCount: z.number(),
+  edgeCount: z.number(),
+  pinnedNodeIds: z.array(z.string()),
+  nodes: z.array(z.object({ id: z.string(), title: z.string(), type: z.string(), contentRevision: z.number() })),
+};
+
+function editableContent(node: CanvasNodeState): string | undefined {
+  return node.type === 'markdown' &&
+    !node.data.path &&
+    typeof node.data.content === 'string' &&
+    node.data.content.length <= 50_000
+    ? node.data.content
+    : undefined;
+}
+
+async function readSnapshot(canvas: CanvasAccess): Promise<CanvasAppSnapshot> {
+  const target = await canvas.prepareContextRead();
+  const { boards } = z.object({ boards: boardListSchema }).parse(await canvas.invoker().invoke('board.list', {}));
+  if (!target.boardId) {
+    return {
+      boardId: null,
+      boardName: 'No board open',
+      boards,
+      revision: createHash('sha256').update(JSON.stringify(boards)).digest('hex'),
+      nodes: [],
+      edges: [],
+      pinnedNodeIds: [],
+    };
+  }
+  // Explicit board reads prevent a concurrent workbench switch mixing two boards.
+  const layout = await canvas.getLayout(target.boardId);
+  const info = z
+    .object({ board: z.object({ name: z.string() }) })
+    .parse(await canvas.invoker().invoke('board.get', { id: target.boardId }));
+  const projection = {
+    boardId: target.boardId,
+    boardName: info.board.name,
+    boards,
+    nodes: layout.nodes.map((node) => {
+      const src = node.data.src;
+      // No network fetches, local paths, SVG or active documents in the app iframe.
+      const image =
+        node.type === 'image' &&
+        typeof src === 'string' &&
+        src.length <= 1_400_000 &&
+        /^data:image\/(png|jpeg|gif|webp);base64,[A-Za-z0-9+/=]+$/.test(src)
+          ? src
+          : undefined;
+      return {
+        id: node.id,
+        type: node.type,
+        title: typeof node.data.title === 'string' ? node.data.title : node.type,
+        text: summarizeNodeForAgentContext(node, { defaultTextLength: 8000, webpageTextLength: 8000 }),
+        contentRevision: node.contentRevision ?? 0,
+        editableContent: editableContent(node),
+        position: node.position,
+        size: node.size,
+        ...(image ? { image } : {}),
+      };
+    }),
+    edges: layout.edges.map(({ id, from, to, label }) => ({ id, from, to, label: label ?? '' })),
+    pinnedNodeIds: target.pinnedNodeIds,
+  };
+  return { ...projection, revision: createHash('sha256').update(JSON.stringify(projection)).digest('hex') };
+}
+
+function snapshotResult(snapshot: CanvasAppSnapshot): CallToolResult {
+  return {
+    content: [
+      { type: 'text', text: `${snapshot.boardName}: ${snapshot.nodes.length} nodes, ${snapshot.edges.length} edges.` },
+    ],
+    structuredContent: {
+      boardId: snapshot.boardId,
+      boardName: snapshot.boardName,
+      boards: snapshot.boards,
+      revision: snapshot.revision,
+      nodeCount: snapshot.nodes.length,
+      edgeCount: snapshot.edges.length,
+      pinnedNodeIds: snapshot.pinnedNodeIds,
+      nodes: snapshot.nodes.map(({ id, title, type, contentRevision }) => ({ id, title, type, contentRevision })),
+    },
+    // Full preview text and image bytes go to the app, not the model's tool transcript.
+    _meta: { canvas: snapshot },
+  };
+}
+
+async function toolResult(run: () => Promise<CallToolResult>): Promise<CallToolResult> {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof OperationError) {
+      return { isError: true, content: [{ type: 'text', text: error.message }] };
+    }
+    console.error('[canvas-app] tool failed', error);
+    return {
+      isError: true,
+      content: [{ type: 'text', text: 'Could not access the canvas. Check the PMX server logs.' }],
+    };
+  }
+}
+
+/** Focused app profile; deliberately does not register the general-purpose composites. */
+export function registerCanvasApp(server: McpServer, ensureCanvas: () => Promise<CanvasAccess>): void {
+  const read = () => toolResult(async () => snapshotResult(await readSnapshot(await ensureCanvas())));
+  const invoke = (operation: string, input: Record<string, unknown>) =>
+    toolResult(async () => {
+      const result = await (await ensureCanvas()).invoker().invoke(operation, input);
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+  registerAppTool(
+    server,
+    'pmx_open_canvas',
+    {
+      title: 'PMX Canvas',
+      description: 'Open a live view of the shared PMX board. Select nodes to share context with the conversation.',
+      inputSchema: {},
+      outputSchema: summaryShape,
+      annotations: readOnly,
+      _meta: {
+        ui: { resourceUri: CANVAS_APP_URI },
+        // ChatGPT-specific extensions are confined to this launcher descriptor.
+        'openai/ui': { entrypoints: [{ type: 'global' }, { type: 'thread' }], preferredModelDisplayMode: 'fullscreen' },
+      },
+    },
+    read,
+  );
+  registerAppTool(
+    server,
+    'pmx_read_canvas',
+    {
+      title: 'Read PMX Canvas',
+      description:
+        'Read the shared active board, node identifiers and context pins. Use pmx_read_node for full note content before editing. Does not change boards.',
+      inputSchema: {},
+      outputSchema: summaryShape,
+      annotations: readOnly,
+      _meta: { ui: { visibility: ['model', 'app'] } },
+    },
+    read,
+  );
+
+  server.registerTool(
+    'pmx_read_node',
+    {
+      title: 'Read a complete PMX note',
+      description:
+        'Read full editable Markdown, content revision, position and incident edges for one note. Always read this before replacing or appending content; selection context is truncated. Other node types, file-linked and oversized notes require the workbench.',
+      inputSchema: { boardId, id: z.string().min(1) },
+      annotations: readOnly,
+    },
+    (input) =>
+      toolResult(async () => {
+        const layout = await (await ensureCanvas()).getLayout(input.boardId);
+        const node = layout.nodes.find((entry) => entry.id === input.id);
+        const content = node && editableContent(node);
+        if (!node || content === undefined)
+          throw new OperationError('This node is not an editable standalone note. Use the PMX workbench.');
+        const result = {
+          boardId: input.boardId,
+          id: node.id,
+          type: node.type,
+          title: typeof node.data.title === 'string' ? node.data.title : node.type,
+          content,
+          contentRevision: node.contentRevision ?? 0,
+          position: node.position,
+          size: node.size,
+          edges: layout.edges
+            .filter((edge) => edge.from === node.id || edge.to === node.id)
+            .map(({ id, from, to, type, label }) => ({ id, from, to, type, label: label ?? '' })),
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+      }),
+  );
+
+  server.registerTool(
+    'pmx_add_note',
+    {
+      title: 'Add a PMX note',
+      description: 'Add a Markdown note to the shared active board at a canvas position. Existing nodes are preserved.',
+      inputSchema: {
+        boardId,
+        title: z.string().min(1).max(200),
+        content: z.string().max(50_000),
+        x: z.number().finite(),
+        y: z.number().finite(),
+      },
+      annotations: additive,
+    },
+    (input) =>
+      toolResult(async () => {
+        const canvas = await ensureCanvas();
+        const result = await canvas.invoker().invoke('node.add', { ...input, type: 'markdown' });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      }),
+  );
+  server.registerTool(
+    'pmx_connect_nodes',
+    {
+      title: 'Connect PMX nodes',
+      description: 'Add a labelled relationship between two nodes on the shared active board.',
+      inputSchema: {
+        boardId,
+        from: z.string().min(1),
+        to: z.string().min(1),
+        type: z.enum(['flow', 'depends-on', 'relation', 'references']),
+        label: z.string().max(500).optional(),
+      },
+      annotations: additive,
+    },
+    (input) =>
+      toolResult(async () => {
+        const canvas = await ensureCanvas();
+        const result = await canvas.invoker().invoke('edge.add', { ...input, expectedBoardId: input.boardId });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      }),
+  );
+
+  server.registerTool(
+    'pmx_create_board',
+    {
+      title: 'Create a PMX board',
+      description:
+        'Create an empty board without switching the shared workspace. Open it explicitly with pmx_open_board.',
+      inputSchema: { name: z.string().trim().min(1).max(120) },
+      annotations: additive,
+    },
+    (input) => invoke('board.create', input),
+  );
+  server.registerTool(
+    'pmx_open_board',
+    {
+      title: 'Switch the shared PMX board',
+      description: 'Switch the active board for ALL conversations and the workbench. Null opens Home.',
+      inputSchema: { id: z.string().min(1).nullable(), expectedBoardId: boardId.nullable() },
+      annotations: editing,
+    },
+    (input) => invoke('board.open', input),
+  );
+  server.registerTool(
+    'pmx_pin_nodes',
+    {
+      title: 'Curate PMX context pins',
+      description: 'Add or remove context pins without replacing unrelated pins.',
+      inputSchema: { boardId, nodeIds: z.array(z.string().min(1)).min(1).max(20), mode: z.enum(['add', 'remove']) },
+      annotations: editing,
+    },
+    (input) => invoke('pin.set', { ...input, expectedBoardId: input.boardId }),
+  );
+  server.registerTool(
+    'pmx_move_node',
+    {
+      title: 'Move a PMX node',
+      description: 'Set the position of an existing node. Moving a group also moves its children.',
+      inputSchema: { boardId, id: z.string().min(1), x: z.number().finite(), y: z.number().finite() },
+      annotations: editing,
+    },
+    (input) => invoke('node.update', { ...input, expectedBoardId: input.boardId }),
+  );
+  server.registerTool(
+    'pmx_update_note',
+    {
+      title: 'Edit a PMX note',
+      description:
+        'Replace standalone Markdown using full content and revision from pmx_read_node, never from a truncated selection excerpt. Refuses stale edits and file-linked notes.',
+      inputSchema: {
+        boardId,
+        id: z.string().min(1),
+        expectedContentRevision: z.number().int().nonnegative(),
+        title: z.string().min(1).max(200),
+        content: z.string().max(50_000),
+      },
+      annotations: editing,
+    },
+    (input) =>
+      toolResult(async () => {
+        const canvas = await ensureCanvas();
+        const node = await canvas.getNode(input.id, input.boardId);
+        if (!node || editableContent(node) === undefined)
+          throw new OperationError('Edit this node in the PMX workbench.');
+        // Compare again inside node.update, atomically with the actual mutation.
+        const result = await canvas.invoker().invoke('node.update', { ...input, expectedBoardId: input.boardId });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      }),
+  );
+
+  registerAppResource(server, 'PMX Canvas', CANVAS_APP_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => ({
+    contents: [
+      {
+        uri: CANVAS_APP_URI,
+        mimeType: RESOURCE_MIME_TYPE,
+        text: await readFile(new URL('../../dist/canvas/mcp-app.html', import.meta.url), 'utf8'),
+        _meta: { ui: { prefersBorder: false, csp: { connectDomains: [], resourceDomains: [], frameDomains: [] } } },
+      },
+    ],
+  }));
+}

package/src/mcp/server.ts

@@ -34,7 +34,7 @@ import { registerOperationTools, registerCompositeTools } from '../server/operat
 import { agentSourceLabel } from '../server/operations/invoker.js';
 import { contextReadFromPayload } from '../server/context-reads.js';
 import { createCanvasAccess, refreshCanvasAccess, type CanvasAccess } from './canvas-access.js';
-import { serializeNodeForAgentContext } from '../server/agent-context.js';
+import { serializeNodeForAgentContext } from '../shared/agent-context.js';
 import { buildSpatialContext, findNeighborhoods } from '../server/spatial-analysis.js';
 import {
   getCanvasNodeTitle,

package/src/mcp/workbench-app.ts

@@ -0,0 +1,211 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { listOperations, OperationError } from '../server/operations/index.js';
+import { matchOperationPath, readOperationInput } from '../server/operations/http.js';
+import type { CanvasAccess } from './canvas-access.js';
+
+// Explicitly bounded to workbench operations. No shell, automation, arbitrary
+// HTTP proxy, external MCP tool calls, or caller-supplied authority headers.
+const writes = new Set([
+  'board.create',
+  'board.open',
+  'board.update',
+  'board.create-from',
+  'board.delete',
+  'node.add',
+  'jsonrender.add',
+  'graph.add',
+  'node.update',
+  'node.remove',
+  'node.refresh',
+  'edge.add',
+  'edge.update',
+  'edge.remove',
+  'group.create',
+  'group.add',
+  'group.remove',
+  'pin.set',
+  'annotation.add',
+  'annotation.remove',
+  'theme.set',
+  'viewport.set',
+  'canvas.apply-updates',
+  'canvas.clear',
+  'arrange',
+  'node.focus',
+  'view.fit',
+  'snapshot.save',
+  'snapshot.restore',
+  'snapshot.delete',
+  'tour.set',
+  'ax.focus.set',
+  'ax.policy.set',
+  'ax.work.create',
+  'ax.work.update',
+  'ax.review.add',
+  'ax.review.update',
+  'ax.elicitation.respond',
+  'ax.mode.resolve',
+  'ax.steer',
+  'ax.event.record',
+  'ax.presence.set',
+  'ax.interaction.submit',
+  'intent.clear',
+  'import.request',
+  'import.cancel',
+  'import.commit',
+  'export.run',
+]);
+
+function readableAsset(path: string): boolean {
+  return (
+    [
+      '/health',
+      '/api/workbench/poll',
+      '/api/workbench/state',
+      '/api/file',
+      '/api/canvas/json-render/view',
+      '/api/canvas/file-bytes',
+    ].includes(path) ||
+    /^\/api\/canvas\/(surface|image|frame-documents|exports)\/[^/]+$/.test(path) ||
+    /^\/api\/canvas\/attachments\/[^/]+\/bytes$/.test(path)
+  );
+}
+
+/** HTTP-shaped replies let the real workbench retain its existing API contracts. */
+export function registerWorkbenchApp(server: McpServer, ensureCanvas: () => Promise<CanvasAccess>): void {
+  server.registerTool(
+    'pmx_workbench_request',
+    {
+      title: 'PMX workbench transport',
+      description: 'App-only transport for the PMX workbench. Not an assistant tool.',
+      inputSchema: {
+        path: z.string().max(8192),
+        method: z.enum(['GET', 'POST', 'PATCH', 'PUT', 'DELETE', 'HEAD']),
+        body: z.string().max(4_000_000).optional(),
+        expectedBoardId: z.string().nullable(),
+      },
+      // Workbench webpage/image actions can fetch user-chosen external URLs.
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+      _meta: { ui: { visibility: ['app'] } },
+    },
+    async (input) => {
+      const reply = (status: number, body: string, contentType = 'application/json', encoding = 'text') => ({
+        content: [
+          { type: 'text' as const, text: status < 400 ? 'Workbench request completed.' : 'Workbench request refused.' },
+        ],
+        _meta: { response: { status, body, contentType, encoding } },
+      });
+      try {
+        const canvas = await ensureCanvas();
+        const base = canvas.remoteBaseUrl ?? `http://127.0.0.1:${canvas.port}`;
+        const url = new URL(input.path, base);
+        if (
+          !input.path.startsWith('/') ||
+          input.path.startsWith('//') ||
+          input.path.includes('\\') ||
+          url.origin !== new URL(base).origin ||
+          url.username ||
+          url.password ||
+          url.hash
+        ) {
+          throw new OperationError('Only local PMX workbench paths are allowed.', 403);
+        }
+        const req = new Request(url, {
+          method: input.method,
+          headers: { 'Content-Type': 'application/json' },
+          ...(input.body === undefined ? {} : { body: input.body }),
+        });
+        for (const op of listOperations()) {
+          const route = op.http;
+          if (!route || route.method !== input.method) continue;
+          const params = matchOperationPath(route.path, url.pathname);
+          if (!params) continue;
+          if (!url.pathname.startsWith('/api/canvas/') || (input.method !== 'GET' && !writes.has(op.name)))
+            throw new OperationError('This action requires the local PMX workbench.', 403);
+          const args = route.readInput
+            ? await route.readInput(req, params, url)
+            : await readOperationInput(req, params, url);
+          if (input.method !== 'GET') args.expectedBoardId = input.expectedBoardId;
+          // This profile is one agent transport, never browser/system authority
+          // or a caller-selected writer whose wider territory could bypass a fence.
+          args.source = 'mcp';
+          delete args.agentId;
+          if (
+            op.name === 'ax.interaction.submit' &&
+            (args.type === 'ax.approval.resolve' || args.type === 'ax.flow.materialize')
+          )
+            throw new OperationError('Resolve approvals and materialize flows in the local PMX workbench.', 403);
+          if (op.name === 'node.add' || op.name === 'node.update') {
+            const data = args.data;
+            const nodeType = op.name === 'node.add' ? args.type : (await canvas.getNode(String(args.id)))?.type;
+            // Trace tool names describe past activity; they never launch a backend.
+            const launchFields = ['transportConfig', 'toolInput', 'serverName', 'appSessionId'];
+            if (nodeType !== 'trace') launchFields.push('toolName');
+            if (
+              (op.name === 'node.add' && args.type === 'mcp-app') ||
+              (data && typeof data === 'object' && launchFields.some((field) => field in data))
+            )
+              throw new OperationError('Configure external MCP apps in the local PMX workbench.', 403);
+          }
+          if (
+            op.name === 'node.update' &&
+            ('content' in args || (args.data && typeof args.data === 'object' && 'content' in args.data))
+          ) {
+            if (typeof args.expectedContentRevision !== 'number')
+              throw new OperationError('Read the note before editing: a content revision is required.', 409);
+            const node = await canvas.getNode(String(args.id));
+            if (node?.data.path) throw new OperationError('Edit file-linked content in the local PMX workbench.', 403);
+          }
+          const result = await canvas.invoker().invoke(op.name, args);
+          return reply(route.status ? route.status(result) : 200, JSON.stringify(result));
+        }
+        if (
+          !((input.method === 'GET' || input.method === 'HEAD') && readableAsset(url.pathname)) &&
+          !(input.method === 'POST' && url.pathname === '/api/render')
+        ) {
+          throw new OperationError('This action requires the local PMX workbench.', 403);
+        }
+        // Resolve only PMX's internal surface redirects. Never follow to arbitrary
+        // hosts or return the workbench HTML (which carries its human boot token).
+        let target = url;
+        let response: Response | undefined;
+        for (let redirects = 0; redirects < 3; redirects++) {
+          response = await fetch(target, {
+            method: input.method,
+            body: input.body,
+            headers: { 'Content-Type': 'application/json' },
+            redirect: 'manual',
+            signal: AbortSignal.timeout(15_000),
+          });
+          if (response.status < 300 || response.status >= 400) break;
+          const next = new URL(response.headers.get('location') ?? '', target);
+          if (next.origin !== url.origin || !readableAsset(next.pathname))
+            throw new OperationError('External surfaces must be opened outside the embedded workbench.', 403);
+          target = next;
+        }
+        if (!response || (response.status >= 300 && response.status < 400))
+          throw new OperationError('Could not resolve the PMX surface.');
+        const bytes = await response.arrayBuffer();
+        if (bytes.byteLength > 24 * 1024 * 1024)
+          throw new OperationError('This asset is too large for the MCP connection.');
+        const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
+        const text = /^(text\/|application\/(json|javascript))/.test(contentType);
+        return reply(
+          response.status,
+          text ? new TextDecoder().decode(bytes) : Buffer.from(bytes).toString('base64'),
+          contentType,
+          text ? 'text' : 'base64',
+        );
+      } catch (error) {
+        if (error instanceof OperationError)
+          return reply(error.status, JSON.stringify({ ok: false, error: error.message }));
+        console.error('[workbench-app] request failed', error);
+        return reply(
+          502,
+          JSON.stringify({ ok: false, error: 'PMX workbench request failed. Check the daemon and retry.' }),
+        );
+      }
+    },
+  );
+}

package/src/server/agent-presence.ts

@@ -32,7 +32,7 @@ import {
   PRESENCE_TOOLING_SETTLE_MS,
   TRANSPORT_SOURCES,
 } from '../shared/agent-presence.js';
-import { serializeNodeForAgentContext } from './agent-context.js';
+import { serializeNodeForAgentContext } from '../shared/agent-context.js';
 import type { PmxAxActivityKind } from './ax-state.js';
 import { type CanvasNodeState, canvasState } from './canvas-state.js';
 import { OperationError } from './operations/types.js';
@@ -205,6 +205,8 @@ interface StoredPresence extends AgentPresence {
   lastActivityNodeId: string | null;
   /** Snapshot of the board taken when this session attached (the receipt diffs against it). */
   startSnapshotId: string | null;
+  /** When this session attached (ISO); the receipt counts reads and pins from here. */
+  startedAt: string | null;
 }
 
 function presenceKey(source: string, agentId: string | null | undefined): string {
@@ -230,7 +232,12 @@ export function estimateContextBudget(): ContextBudget {
 /** Returns the id of the pre-session snapshot the server took, if any. */
 type SessionStartListener = (presence: AgentPresence) => string | null;
 export type SessionEndReason = 'human' | 'agent' | 'idle-timeout';
-type SessionEndListener = (presence: AgentPresence, startSnapshotId: string | null, endedBy: SessionEndReason) => void;
+type SessionEndListener = (
+  presence: AgentPresence,
+  startSnapshotId: string | null,
+  endedBy: SessionEndReason,
+  startedAt: string | null,
+) => void;
 
 export class AgentPresenceRegistry {
   private readonly presences = new Map<string, StoredPresence>();
@@ -392,6 +399,7 @@ export class AgentPresenceRegistry {
       phaseSetMs: now,
       toolingUntilMs: null,
       startSnapshotId: null,
+      startedAt: null,
     };
     const wasAttached = stored.attached;
     stored.lastSeenMs = now;
@@ -448,6 +456,7 @@ export class AgentPresenceRegistry {
       // moment stays the receipt baseline via the inherited snapshot. A
       // placeholder that already adopted work is a real session and stays.
       let inheritedSnapshotId: string | null = null;
+      let inheritedStartedAt: string | null = null;
       if (stored.source !== 'browser') {
         const placeholder = [...this.presences.values()].find(
           (presence) =>
@@ -463,13 +472,20 @@ export class AgentPresenceRegistry {
             if (target === placeholder.sessionId) this.aliases.set(channel, key);
           }
           inheritedSnapshotId = placeholder.startSnapshotId;
+          inheritedStartedAt = placeholder.startedAt;
         }
       }
       stored.startSnapshotId = inheritedSnapshotId ?? this.onSessionStart(this.publicView(stored, now));
+      stored.startedAt = inheritedStartedAt ?? new Date(now).toISOString();
     }
     if (input.attached === false) {
       if (wasAttached)
-        this.onSessionEnd(this.publicView(stored, now), stored.startSnapshotId, input.endedBy ?? 'agent');
+        this.onSessionEnd(
+          this.publicView(stored, now),
+          stored.startSnapshotId,
+          input.endedBy ?? 'agent',
+          stored.startedAt,
+        );
       // An explicit detach always removes the presence. In particular, a
       // worker that reports attached:false must not be refreshed into another
       // full activity TTL as an external writer.
@@ -481,7 +497,24 @@ export class AgentPresenceRegistry {
     }
     if (input.focusNodeId !== undefined) stored.focusNodeId = input.focusNodeId;
     if (input.parentAgentId !== undefined) stored.parentAgentId = input.parentAgentId;
-    if (input.cursor !== undefined) stored.cursor = input.cursor;
+    if (input.cursor !== undefined) {
+      // A MOVING cursor is the agent visibly working: it keeps a live explicit
+      // `tooling` from settling (a host streaming cursor moves after one
+      // `tooling` report read as Idle within seconds). A stationary heartbeat
+      // is not activity, and `thinking` keeps its own longer clock (below).
+      const moved =
+        input.cursor !== null && (stored.cursor?.x !== input.cursor.x || stored.cursor?.y !== input.cursor.y);
+      if (
+        moved &&
+        input.phase === undefined &&
+        stored.phase === 'tooling' &&
+        stored.toolingUntilMs !== null &&
+        stored.toolingUntilMs > now
+      ) {
+        stored.toolingUntilMs = now + PRESENCE_TOOLING_SETTLE_MS;
+      }
+      stored.cursor = input.cursor;
+    }
     if (input.contextUsage !== undefined) stored.contextUsage = input.contextUsage;
     if (input.phase === 'tooling' && input.derivedTooling) {
       // Copilot's finding: an op-derived tooling touch used to CLOBBER the
@@ -585,7 +618,8 @@ export class AgentPresenceRegistry {
     const removed = this.presences.delete(sessionId);
     if (removed) {
       this.dropAliasesTo(sessionId);
-      if (stored?.attached) this.onSessionEnd(this.publicView(stored, Date.now()), stored.startSnapshotId, 'agent');
+      if (stored?.attached)
+        this.onSessionEnd(this.publicView(stored, Date.now()), stored.startSnapshotId, 'agent', stored.startedAt);
       this.scheduleEmit();
     }
     this.maybeStopSweeper();
@@ -700,7 +734,12 @@ export class AgentPresenceRegistry {
         this.presences.delete(key);
         this.dropAliasesTo(key);
         if (presence.attached)
-          this.onSessionEnd(this.publicView(presence, now), presence.startSnapshotId, 'idle-timeout');
+          this.onSessionEnd(
+            this.publicView(presence, now),
+            presence.startSnapshotId,
+            'idle-timeout',
+            presence.startedAt,
+          );
         changed = true;
         continue;
       }

package/src/server/ax-context.ts

@@ -1,4 +1,4 @@
-import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
+import { buildAgentContextPreamble, serializeNodeForAgentContext } from '../shared/agent-context.js';
 import {
   type PmxAxHumanAnnotation,
   buildAxContext,

package/src/server/ax-state.ts

@@ -1,7 +1,7 @@
 import type { CanvasLayout, CanvasNodeState } from './canvas-state.js';
 import { clampGateTtlMs, DEFAULT_GATE_TTL_MS } from '../shared/approval-gates.js';
 import type { AxApprovalStatus, AxEventKind, AxWorkItemStatus } from '../shared/ax-kinds.js';
-import type { AgentContextNode } from './agent-context.js';
+import type { AgentContextNode } from '../shared/agent-context.js';
 import type { ActorAttribution } from './attribution.js';
 
 export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';