pmx-canvas 0.8.0 → 0.9.0

package/src/server/agent-presence.ts

@@ -19,9 +19,6 @@ import {
   type AgentPhase,
   type AgentPresence,
   type AgentPresenceSnapshot,
-  CONTEXT_BUDGET_DEFAULT_TOKENS,
-  type ContextBudget,
-  estimateTokens,
   HUMAN_STARTED_SESSION_LABEL,
   isSessionActive,
   MAX_ACTIVITY_ENTRIES,
@@ -30,11 +27,11 @@ import {
   PRESENCE_ATTACHED_IDLE_TTL_MS,
   PRESENCE_THINKING_SETTLE_MS,
   PRESENCE_TOOLING_SETTLE_MS,
+  type SessionTouches,
   TRANSPORT_SOURCES,
 } from '../shared/agent-presence.js';
-import { serializeNodeForAgentContext } from '../shared/agent-context.js';
 import type { PmxAxActivityKind } from './ax-state.js';
-import { type CanvasNodeState, canvasState } from './canvas-state.js';
+import { canvasState } from './canvas-state.js';
 import { OperationError } from './operations/types.js';
 
 type PresenceEmitter = (event: string, payload: Record<string, unknown>) => void;
@@ -65,8 +62,12 @@ export interface PresenceTouch {
 }
 
 /** Title a write's summary can name, or a type-based fallback. */
-function nodeTitle(nodeId: string | null | undefined): string | null {
-  const node = nodeId ? canvasState.getNode(nodeId) : undefined;
+function nodeTitle(nodeId: string | null | undefined, boardId?: string): string | null {
+  const node = nodeId
+    ? boardId && boardId !== canvasState.activeBoardId
+      ? canvasState.readBoard(boardId, false)?.state.nodes.find((entry) => entry.id === nodeId)
+      : canvasState.getNode(nodeId)
+    : undefined;
   if (!node) return null;
   const title = typeof node.data.title === 'string' ? node.data.title.trim() : '';
   return title || `${node.type} node`;
@@ -109,11 +110,16 @@ export function describeWrite(
       return { summary: `Updated ${quote(title, 'a node')}`, nodeId };
     case 'node.remove':
       return { summary: 'Removed a node', nodeId };
-    case 'edge.add':
+    case 'edge.add': {
+      const from = str(res.from) || str(input.from);
+      const to = str(res.to) || str(input.to);
+      const toBoardId = str(res.toBoardId) || str(input.toBoardId);
+      const foreignTarget = toBoardId && toBoardId !== canvasState.activeBoardId;
       return {
-        summary: `Connected ${quote(nodeTitle(str(input.from)), 'a node')} → ${quote(nodeTitle(str(input.to)), 'a node')}`,
-        nodeId: str(input.to) || null,
+        summary: `Connected ${quote(nodeTitle(from), 'a node')} → ${quote(nodeTitle(to, toBoardId), foreignTarget ? `a node on board ${toBoardId}` : 'a node')}`,
+        nodeId: foreignTarget ? (canvasState.getNode(from) ? from : null) : to || null,
       };
+    }
     case 'edge.remove':
       return { summary: 'Removed an edge', nodeId: null };
     case 'group.create':
@@ -207,26 +213,74 @@ interface StoredPresence extends AgentPresence {
   startSnapshotId: string | null;
   /** When this session attached (ISO); the receipt counts reads and pins from here. */
   startedAt: string | null;
+  /**
+   * Each board as the session found it — its cards and content revision —
+   * captured at attach and when a board opens mid-session (a session started
+   * on Home gets one when its first write opens a board). The live lens
+   * counts from here.
+   */
+  startBoards: Map<string, { nodeIds: Set<string>; revision: number }>;
+  /** The last computed touches and what they were computed from. */
+  touchesCache: { key: string; value: SessionTouches | undefined } | null;
 }
 
-function presenceKey(source: string, agentId: string | null | undefined): string {
-  return agentId && agentId.trim() ? agentId.trim() : source;
+type Baselines = StoredPresence['startBoards'];
+
+/**
+ * Record the open board as this session finds it, unless it already has. A
+ * board created after the session started began empty: a write on Home opens
+ * a new board while saving, after its first cards exist, so those count as
+ * the session's.
+ */
+function captureBaseline(baselines: Baselines, since: string | null): void {
+  const boardId = canvasState.activeBoardId;
+  if (!boardId || baselines.has(boardId)) return;
+  const createdAt = canvasState.listBoards().find((board) => board.id === boardId)?.createdAt;
+  const bornInSession = since !== null && createdAt !== undefined && createdAt >= since;
+  baselines.set(
+    boardId,
+    bornInSession
+      ? { nodeIds: new Set(), revision: 0 }
+      : {
+          nodeIds: new Set(canvasState.nodeStamps().map((node) => node.id)),
+          revision: canvasState.getContentRevision().revision,
+        },
+  );
 }
 
-function contextBudgetTotal(): number {
-  const raw = Number(process.env.PMX_CANVAS_CONTEXT_BUDGET_TOKENS ?? '');
-  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : CONTEXT_BUDGET_DEFAULT_TOKENS;
+/** The cards an attached session read, created, edited and pinned on the open board since it found it. */
+function sessionTouches(stored: StoredPresence, readVersion: number): SessionTouches | undefined {
+  const boardId = canvasState.activeBoardId;
+  if (!stored.attached || !stored.startedAt || !boardId) return undefined;
+  // A board can open without a change event (a write on Home): record it now.
+  captureBaseline(stored.startBoards, stored.startedAt);
+  const start = stored.startBoards.get(boardId);
+  if (!start) return undefined;
+  const since = stored.startedAt;
+  const pins = Object.entries(canvasState.getContextPinMeta());
+  const key = `${boardId}|${canvasState.getContentRevision().revision}|${readVersion}|${pins.map(([id, meta]) => `${id}@${meta.pinnedAt}`).join(',')}`;
+  if (stored.touchesCache?.key === key) return stored.touchesCache.value;
+  const stamps = canvasState.nodeStamps();
+  const value: SessionTouches = {
+    startedAt: since,
+    read: canvasState.getReadNodeIdsSince(boardId, since),
+    created: stamps.filter((node) => !start.nodeIds.has(node.id) && node.createdBy?.actor === 'agent').map((n) => n.id),
+    edited: stamps
+      .filter(
+        (node) =>
+          start.nodeIds.has(node.id) &&
+          node.lastEditedBy?.actor === 'agent' &&
+          (node.contentRevision ?? 0) > start.revision,
+      )
+      .map((node) => node.id),
+    pinned: pins.filter(([, meta]) => meta.pinnedBy.actor === 'agent' && meta.pinnedAt >= since).map(([id]) => id),
+  };
+  stored.touchesCache = { key, value };
+  return value;
 }
 
-/** Token estimate of the pinned-context payload — the same serialization the MCP resource ships. */
-export function estimateContextBudget(): ContextBudget {
-  const nodes = Array.from(canvasState.contextPinnedNodeIds)
-    .map((id) => canvasState.getNode(id))
-    .filter((node): node is CanvasNodeState => node !== undefined);
-  const payload = nodes.map((node) =>
-    serializeNodeForAgentContext(node, { defaultTextLength: 700, webpageTextLength: 1600, includePosition: true }),
-  );
-  return { used: nodes.length === 0 ? 0 : estimateTokens(JSON.stringify(payload)), total: contextBudgetTotal() };
+function presenceKey(source: string, agentId: string | null | undefined): string {
+  return agentId && agentId.trim() ? agentId.trim() : source;
 }
 
 /** Returns the id of the pre-session snapshot the server took, if any. */
@@ -400,6 +454,8 @@ export class AgentPresenceRegistry {
       toolingUntilMs: null,
       startSnapshotId: null,
       startedAt: null,
+      startBoards: new Map(),
+      touchesCache: null,
     };
     const wasAttached = stored.attached;
     stored.lastSeenMs = now;
@@ -457,6 +513,7 @@ export class AgentPresenceRegistry {
       // placeholder that already adopted work is a real session and stays.
       let inheritedSnapshotId: string | null = null;
       let inheritedStartedAt: string | null = null;
+      let inheritedStartBoards: Baselines | null = null;
       if (stored.source !== 'browser') {
         const placeholder = [...this.presences.values()].find(
           (presence) =>
@@ -473,10 +530,13 @@ export class AgentPresenceRegistry {
           }
           inheritedSnapshotId = placeholder.startSnapshotId;
           inheritedStartedAt = placeholder.startedAt;
+          inheritedStartBoards = placeholder.startBoards;
         }
       }
       stored.startSnapshotId = inheritedSnapshotId ?? this.onSessionStart(this.publicView(stored, now));
       stored.startedAt = inheritedStartedAt ?? new Date(now).toISOString();
+      stored.startBoards = inheritedStartBoards ?? new Map();
+      captureBaseline(stored.startBoards, stored.startedAt);
     }
     if (input.attached === false) {
       if (wasAttached)
@@ -612,6 +672,23 @@ export class AgentPresenceRegistry {
     if (this.presences.size > 0) this.scheduleEmit();
   }
 
+  /** Bumped when an agent read is recorded: the live lens's read list changed. */
+  private readVersion = 0;
+
+  /** A read landed (server.ts's read listener): re-count and re-emit. */
+  noteRead(): void {
+    this.readVersion += 1;
+    this.refresh();
+  }
+
+  /** A board opened: attached sessions record it as they find it, before any write lands. */
+  boardOpened(): void {
+    for (const stored of this.presences.values()) {
+      if (stored.attached) captureBaseline(stored.startBoards, stored.startedAt);
+    }
+    this.refresh();
+  }
+
   /** Remove a writer (session-end). */
   detach(sessionId: string): boolean {
     const stored = this.presences.get(sessionId);
@@ -628,15 +705,22 @@ export class AgentPresenceRegistry {
 
   snapshot(now = Date.now()): AgentPresenceSnapshot {
     this.sweep(now, { emit: false });
-    const presences = [...this.presences.values()].map((stored) => this.publicView(stored, now));
+    const presences = [...this.presences.values()].map((stored) => this.publicView(stored, now, true));
     return {
       presences,
-      budget: estimateContextBudget(),
       sessionActive: isSessionActive(presences),
       activity: this.activity.map((entry) => ({ ...entry })),
     };
   }
 
+  /** Latest attached session: a newly attached reviewer must check fast context again. */
+  reviewSessionStartedAt(): number | null {
+    const starts = [...this.presences.values()]
+      .filter((presence) => presence.attached && presence.startedAt)
+      .map((presence) => Date.parse(presence.startedAt!));
+    return starts.length ? Math.max(...starts) : null;
+  }
+
   /** Test / shutdown hook. */
   reset(): void {
     this.steeringConsumers.clear();
@@ -650,15 +734,22 @@ export class AgentPresenceRegistry {
     this.maybeStopSweeper();
   }
 
-  private publicView(stored: StoredPresence, now: number): AgentPresence {
+  /** `withTouches`: only emitted snapshots carry the session's touches (they read the DB). */
+  private publicView(stored: StoredPresence, now: number, withTouches = false): AgentPresence {
     const {
       lastSeenMs: _lastSeenMs,
       phaseSetMs: _phaseSetMs,
       toolingUntilMs,
       startSnapshotId: _startSnapshotId,
+      startBoards: _startBoards,
+      touchesCache: _touchesCache,
       lastActivityNodeId,
       ...presence
     } = stored;
+    if (withTouches) {
+      const session = sessionTouches(stored, this.readVersion);
+      if (session) presence.session = session;
+    }
     let phase = presence.phase;
     let detail = presence.detail;
     if (toolingUntilMs !== null && toolingUntilMs > now) {
@@ -801,6 +892,15 @@ export const agentPresence = new AgentPresenceRegistry();
 // and context pins. Re-emit on every AX / pin change — whatever transport made
 // it — so no caller has to remember to refresh, and the SDK paths that bypass
 // the operation registry are covered too.
+// The live lens also follows card content (a person's edit takes a card out of
+// the agent's session) and the open board — but not moves, so a drag stays quiet.
+let lastBoardId = canvasState.activeBoardId;
+let lastRevision = canvasState.getContentRevision().revision;
 canvasState.onChange((type) => {
-  if (type === 'ax' || type === 'pins') agentPresence.refresh();
+  const boardId = canvasState.activeBoardId;
+  const revision = canvasState.getContentRevision().revision;
+  if (boardId !== lastBoardId) agentPresence.boardOpened();
+  else if (type === 'ax' || type === 'pins' || revision !== lastRevision) agentPresence.refresh();
+  lastBoardId = boardId;
+  lastRevision = revision;
 });

package/src/server/ax-context.ts

@@ -15,6 +15,8 @@ import {
 } from './ax-state.js';
 import type { CanvasLayout } from './canvas-state.js';
 import { canvasState, type CanvasNodeState } from './canvas-state.js';
+import { lifecycleQualifications } from './lifecycle-status.js';
+import { memoryKey } from '../shared/memory-graph.js';
 
 /**
  * Compact, surface-safe view of the canvas-bound AX state, injected into (and
@@ -54,18 +56,29 @@ export function buildCanvasAxSurfaceSnapshot(): PmxAxSurfaceSnapshot {
   };
 }
 
-function serializeNodes(nodes: CanvasNodeState[]) {
-  return nodes.map((node) =>
-    serializeNodeForAgentContext(node, {
-      defaultTextLength: 700,
-      webpageTextLength: 1600,
-      includePosition: true,
-    }),
-  );
+function serializeNodes(nodes: CanvasNodeState[], qualifications: ReturnType<typeof lifecycleQualifications>) {
+  const qualification = (node: CanvasNodeState) =>
+    canvasState.activeBoardId
+      ? qualifications[memoryKey({ boardId: canvasState.activeBoardId, cardId: node.id })]
+      : undefined;
+  return nodes
+    .filter((node) => !qualification(node)?.retired)
+    .map((node) => ({
+      ...serializeNodeForAgentContext(node, {
+        defaultTextLength: 700,
+        webpageTextLength: 1600,
+        includePosition: true,
+      }),
+      qualification: qualification(node),
+    }));
 }
 
-export function buildCanvasAxPinnedContext(): PmxAxPinnedContext {
-  const nodeIds = Array.from(canvasState.contextPinnedNodeIds);
+export function buildCanvasAxPinnedContext(qualifications = lifecycleQualifications()): PmxAxPinnedContext {
+  const nodeIds = Array.from(canvasState.contextPinnedNodeIds).filter(
+    (id) =>
+      !canvasState.activeBoardId ||
+      !qualifications[memoryKey({ boardId: canvasState.activeBoardId, cardId: id })]?.retired,
+  );
   const nodes = nodeIds
     .map((id) => canvasState.getNode(id))
     .filter((node): node is CanvasNodeState => node !== undefined);
@@ -73,7 +86,7 @@ export function buildCanvasAxPinnedContext(): PmxAxPinnedContext {
     preamble: nodes.length > 0 ? buildAgentContextPreamble(nodes) : '',
     nodeIds,
     count: nodeIds.length,
-    nodes: serializeNodes(nodes),
+    nodes: serializeNodes(nodes, qualifications),
   };
 }
 
@@ -122,6 +135,7 @@ function buildHumanAnnotations(layout: CanvasLayout): PmxAxHumanAnnotation[] {
 export function buildCanvasAxContext(consumer?: string): PmxAxContext & { boardId: string | null } {
   const layout = canvasState.getLayout();
   const ax = canvasState.getAxState();
+  const qualifications = lifecycleQualifications();
   const focusNodes = ax.focus.nodeIds
     .map((id) => canvasState.getNode(id))
     .filter((node): node is CanvasNodeState => node !== undefined);
@@ -138,9 +152,9 @@ export function buildCanvasAxContext(consumer?: string): PmxAxContext & { boardI
       omittedPending: Math.max(0, totalPending - pendingSteering.length),
       pendingActivity: buildPendingAxActivity(ax, consumer),
     },
-    pinned: buildCanvasAxPinnedContext(),
+    pinned: buildCanvasAxPinnedContext(qualifications),
     focus: ax.focus,
-    focusNodes: serializeNodes(focusNodes),
+    focusNodes: serializeNodes(focusNodes, qualifications),
     workItems: ax.workItems,
     approvalGates: ax.approvalGates,
     reviewAnnotations: ax.reviewAnnotations,

package/src/server/board-export.ts

@@ -489,6 +489,7 @@ export async function buildBoardExport(
   const edges = snapshotEdges.map((edge: CanvasEdge) => ({
     from: edge.from,
     to: edge.to,
+    ...(edge.toBoardId !== undefined ? { toBoardId: edge.toBoardId } : {}),
     label: edge.label ?? '',
     style: edge.style ?? 'solid',
   }));
@@ -537,7 +538,10 @@ function exportPage(input: {
   title: string;
   scheme: 'dark' | 'light';
   exportedAt: string;
-  board: { cards: ExportCard[]; edges: Array<{ from: string; to: string; label: string; style: string }> };
+  board: {
+    cards: ExportCard[];
+    edges: Array<{ from: string; to: string; toBoardId?: string; label: string; style: string }>;
+  };
   assets: Record<string, string>;
 }): string {
   const date = new Date(input.exportedAt).toLocaleString('en-GB', { dateStyle: 'medium', timeStyle: 'short' });
@@ -670,10 +674,17 @@ for (const card of ordered) {
     el.appendChild(body(card));
     title.addEventListener('click', () => expand(card));
   }
+  for (const edge of board.edges.filter((edge) => edge.from === card.id && edge.toBoardId !== undefined)) {
+    const connection = document.createElement('div');
+    connection.className = 'card-title';
+    connection.textContent = 'External connection → ' + edge.toBoardId + '/' + edge.to + (edge.label ? ' · ' + edge.label : '');
+    el.appendChild(connection);
+  }
   world.appendChild(el);
 }
 const NS = 'http://www.w3.org/2000/svg';
 for (const edge of board.edges) {
+  if (edge.toBoardId !== undefined) continue;
   const a = byId.get(edge.from), b = byId.get(edge.to);
   if (!a || !b) continue;
   const x1 = a.x + a.w / 2, y1 = a.y + a.h / 2, x2 = b.x + b.w / 2, y2 = b.y + b.h / 2;