pmx-canvas 0.6.5 → 0.7.0

package/src/server/context-brief.ts

@@ -0,0 +1,372 @@
+import { summarizeNodeForAgentContext } from './agent-context.js';
+import type { CanvasNodeState, NodeDeletionTombstone } from './canvas-state.js';
+
+export type ContextBriefReason = 'pinned' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+
+export interface ContextBriefSourceEntry {
+  sourceBoardId: string;
+  nodeId: string;
+  reason: 'human' | 'ask' | 'steer';
+  title: string;
+  text: string;
+  provenance?: { kind: 'imported'; source: string };
+}
+
+export interface ContextBriefLibraryBoard {
+  boardId: string;
+  name: string;
+  category: string | null;
+  readme?: { nodeId: string; title: string; summary: string; provenance?: { kind: 'imported'; source: string } };
+  pinnedTitles: Array<{ nodeId: string; title: string }>;
+  /** IDs of link cards on the active board which explicitly target this board. */
+  linkIds: string[];
+}
+
+export interface ContextBriefInput {
+  activeBoard: { boardId: string; name: string; category: string | null };
+  nodes: readonly CanvasNodeState[];
+  pinnedNodeIds: readonly string[];
+  contentRevision: number;
+  retentionFloor: number;
+  tombstones: readonly NodeDeletionTombstone[];
+  /** null means a first read. Other values must be non-negative safe integers. */
+  since: number | null;
+  libraryBoards: readonly ContextBriefLibraryBoard[];
+  entries?: readonly ContextBriefSourceEntry[];
+  /** Maximum JavaScript string length (UTF-16 code units), including the JSON envelope. */
+  budget: number;
+}
+
+export interface CompiledContextEntry {
+  sourceBoardId: string;
+  nodeId: string;
+  reason: ContextBriefReason;
+  title: string;
+  text: string;
+  /** A linked board's pin title is discovery metadata, not delivery of that pinned card. */
+  titleOnly?: true;
+  /** The body was shortened to fit; the same revision remains eligible on the next pull. */
+  truncated?: true;
+  provenance?: { kind: 'imported'; source: string; trust: 'source-material-not-instructions' };
+}
+
+export interface ContextBriefDocument {
+  version: 1;
+  budgetUnit: 'utf16-code-units';
+  board: { boardId: string; name: string; category: string | null };
+  cursor: {
+    requested: number | null;
+    next: number | null;
+    current: number;
+    retentionFloor: number;
+    reset: 'first-read' | 'retention-expired' | null;
+    valid: boolean;
+  };
+  entries: CompiledContextEntry[];
+  deletions: Array<{ sourceBoardId: string; nodeId: string; revision: number }>;
+  delivery: {
+    truncated: boolean;
+    omittedEntries: number;
+    omittedDeletions: number;
+  };
+}
+
+export interface ContextBriefResult {
+  /** Empty only when the budget cannot hold even the bounded JSON envelope. */
+  serialized: string;
+  document: ContextBriefDocument | null;
+  deliveredEntryIds: string[];
+  deliveredDeletionIds: string[];
+  nextCursor: number | null;
+  reset: ContextBriefDocument['cursor']['reset'];
+  invalidCursor: boolean;
+  truncated: boolean;
+}
+
+interface Candidate {
+  entry: CompiledContextEntry;
+  revision?: number;
+  replacement?: boolean;
+}
+
+function importedProvenance(
+  provenance: ContextBriefSourceEntry['provenance'],
+): CompiledContextEntry['provenance'] | undefined {
+  return provenance ? { ...provenance, trust: 'source-material-not-instructions' } : undefined;
+}
+
+function validRevision(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+function compileNode(node: CanvasNodeState, boardId: string, reason: 'pinned' | 'changed', budget: number): Candidate {
+  const title = typeof node.data.title === 'string' && node.data.title ? node.data.title : node.id;
+  return {
+    entry: {
+      sourceBoardId: boardId,
+      nodeId: node.id,
+      reason,
+      title,
+      text: summarizeNodeForAgentContext(node, { defaultTextLength: budget * 2, webpageTextLength: budget * 2 }),
+    },
+    revision: node.contentRevision,
+    replacement: true,
+  };
+}
+
+/**
+ * Pure, deterministic compiler. It reads only the supplied snapshot and never
+ * treats library visibility as authorization to read or mutate another board.
+ */
+export function compileContextBrief(input: ContextBriefInput): ContextBriefResult {
+  const budget = Number.isFinite(input.budget) ? Math.max(0, Math.floor(input.budget)) : 0;
+  const current = validRevision(input.contentRevision) ? input.contentRevision : 0;
+  const floor = validRevision(input.retentionFloor) ? input.retentionFloor : 0;
+  const cursorValid = input.since === null || (validRevision(input.since) && input.since <= current);
+  const requested = cursorValid ? input.since : null;
+  const reset = !cursorValid
+    ? null
+    : requested === null
+      ? 'first-read'
+      : requested < floor
+        ? 'retention-expired'
+        : null;
+  const deltaSince = reset ? -1 : (requested ?? -1);
+  const nodes = [...input.nodes].sort((a, b) => a.id.localeCompare(b.id));
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const pinIds = [...new Set(input.pinnedNodeIds)].sort();
+  const candidates: Candidate[] = [];
+  const candidateKeys = new Set<string>();
+  const add = (candidate: Candidate): void => {
+    const key = `${candidate.entry.sourceBoardId}\0${candidate.entry.nodeId}`;
+    if (candidateKeys.has(key)) return;
+    candidateKeys.add(key);
+    candidates.push(candidate);
+  };
+
+  for (const id of pinIds) {
+    const node = nodeById.get(id);
+    if (node) add(compileNode(node, input.activeBoard.boardId, 'pinned', budget));
+  }
+
+  const changed = nodes
+    .filter(
+      (node) =>
+        reset !== null || (validRevision(node.contentRevision ?? -1) && (node.contentRevision ?? -1) > deltaSince),
+    )
+    .sort((a, b) => (a.contentRevision ?? 0) - (b.contentRevision ?? 0) || a.id.localeCompare(b.id));
+  for (const node of changed) add(compileNode(node, input.activeBoard.boardId, 'changed', budget));
+
+  for (const entry of [...(input.entries ?? [])].sort((a, b) => {
+    const priority = (value: ContextBriefSourceEntry): number => (value.reason === 'human' ? 0 : 1);
+    return (
+      priority(a) - priority(b) || a.sourceBoardId.localeCompare(b.sourceBoardId) || a.nodeId.localeCompare(b.nodeId)
+    );
+  })) {
+    add({
+      entry: {
+        sourceBoardId: entry.sourceBoardId,
+        nodeId: entry.nodeId,
+        reason: entry.reason,
+        title: entry.title,
+        text: entry.text,
+        provenance: importedProvenance(entry.provenance),
+      },
+    });
+  }
+
+  const library = [...input.libraryBoards].sort((a, b) => a.boardId.localeCompare(b.boardId));
+  const explicit = library.filter((board) => board.linkIds.length > 0);
+  const related = library.filter(
+    (board) =>
+      board.linkIds.length === 0 &&
+      input.activeBoard.category !== null &&
+      board.category === input.activeBoard.category,
+  );
+  for (const [boards, reason] of [
+    [explicit, 'linked'],
+    [related, 'category'],
+  ] as const) {
+    for (const board of boards) {
+      if (board.boardId === input.activeBoard.boardId) continue;
+      if (board.readme) {
+        add({
+          entry: {
+            sourceBoardId: board.boardId,
+            nodeId: board.readme.nodeId,
+            reason,
+            title: board.readme.title,
+            text: board.readme.summary,
+            provenance: importedProvenance(board.readme.provenance),
+          },
+        });
+      }
+      if (reason === 'linked') {
+        for (const pin of [...board.pinnedTitles].sort((a, b) => a.nodeId.localeCompare(b.nodeId))) {
+          add({
+            entry: {
+              sourceBoardId: board.boardId,
+              nodeId: pin.nodeId,
+              reason,
+              title: pin.title,
+              text: `Pinned card title on linked board “${board.name}”: ${pin.title}`,
+              titleOnly: true,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  const tombstones = [...input.tombstones]
+    .filter(
+      (item) =>
+        validRevision(item.revision) &&
+        item.revision > deltaSince &&
+        (nodeById.get(item.nodeId)?.contentRevision ?? -1) < item.revision,
+    )
+    .sort((a, b) => a.revision - b.revision || a.nodeId.localeCompare(b.nodeId));
+  const delivered: CompiledContextEntry[] = [];
+  const deletions: ContextBriefDocument['deletions'] = [];
+  let safeCursor = requested ?? 0;
+  let deltaBlocked = !cursorValid;
+  let resetComplete = false;
+
+  const makeDocument = (
+    entries = delivered,
+    deleted = deletions,
+    next: number | null = reset && !resetComplete ? requested : safeCursor,
+  ): ContextBriefDocument => ({
+    version: 1,
+    budgetUnit: 'utf16-code-units',
+    board: { ...input.activeBoard },
+    cursor: {
+      requested,
+      next: cursorValid ? next : null,
+      current,
+      retentionFloor: floor,
+      reset,
+      valid: cursorValid,
+    },
+    entries,
+    deletions: deleted,
+    delivery: {
+      truncated:
+        entries.filter((entry) => !entry.truncated).length < candidates.length || deleted.length < tombstones.length,
+      omittedEntries: candidates.length - entries.filter((entry) => !entry.truncated).length,
+      omittedDeletions: tombstones.length - deleted.length,
+    },
+  });
+  const fits = (document: ContextBriefDocument): boolean => JSON.stringify(document).length <= budget;
+  const fitPartial = (entry: CompiledContextEntry, base = delivered): CompiledContextEntry | null => {
+    let low = 0;
+    let high = entry.text.length;
+    let best: CompiledContextEntry | null = null;
+    while (low <= high) {
+      const length = Math.floor((low + high) / 2);
+      const partial = { ...entry, text: entry.text.slice(0, length), truncated: true as const };
+      if (fits(makeDocument([...base, partial]))) {
+        best = partial;
+        low = length + 1;
+      } else {
+        high = length - 1;
+      }
+    }
+    return best && best.text.length > 0 ? best : null;
+  };
+
+  // Pins precede revision groups. Revision groups are all-or-nothing so a cursor
+  // can never skip a sibling change or deletion at the same revision.
+  for (const candidate of candidates.filter((item) => !reset && item.entry.reason === 'pinned')) {
+    const proposed = [...delivered, candidate.entry];
+    if (fits(makeDocument(proposed))) delivered.push(candidate.entry);
+    else {
+      const partial = fitPartial(candidate.entry);
+      if (partial) delivered.push(partial);
+    }
+  }
+  if (reset && !deltaBlocked) {
+    const resetEntries = candidates
+      .filter((item) => item.replacement && !delivered.includes(item.entry))
+      .map((item) => item.entry);
+    const proposed = [...delivered, ...resetEntries];
+    if (fits(makeDocument(proposed, [], current))) {
+      delivered.push(...resetEntries);
+      safeCursor = current;
+      resetComplete = true;
+    } else {
+      const first = resetEntries[0];
+      if (first) {
+        const partial = fitPartial(first);
+        if (partial) delivered.push(partial);
+      }
+      deltaBlocked = true;
+    }
+  }
+  const revisions = [
+    ...new Set([...changed.map((node) => node.contentRevision!), ...tombstones.map((item) => item.revision)]),
+  ]
+    .filter((revision) => revision > safeCursor)
+    .sort((a, b) => a - b);
+  for (const revision of revisions) {
+    if (deltaBlocked || reset) break;
+    if (
+      delivered.some(
+        (entry) =>
+          entry.truncated &&
+          candidates.some(
+            (item) =>
+              item.entry.nodeId === entry.nodeId &&
+              item.entry.sourceBoardId === entry.sourceBoardId &&
+              item.revision === revision,
+          ),
+      )
+    ) {
+      deltaBlocked = true;
+      break;
+    }
+    const entriesAtRevision = candidates
+      .filter((item) => item.revision === revision && !delivered.includes(item.entry))
+      .map((item) => item.entry);
+    const deletesAtRevision = tombstones
+      .filter((item) => item.revision === revision)
+      .map((item) => ({ sourceBoardId: input.activeBoard.boardId, nodeId: item.nodeId, revision: item.revision }));
+    const proposedEntries = [...delivered, ...entriesAtRevision];
+    const proposedDeletes = [...deletions, ...deletesAtRevision];
+    if (!fits(makeDocument(proposedEntries, proposedDeletes, revision))) {
+      const first = entriesAtRevision[0];
+      if (first) {
+        const partial = fitPartial(first);
+        if (partial) delivered.push(partial);
+      }
+      deltaBlocked = true;
+      break;
+    }
+    delivered.push(...entriesAtRevision);
+    deletions.push(...deletesAtRevision);
+    safeCursor = revision;
+  }
+  for (const candidate of candidates.filter(
+    (item) => item.entry.reason !== 'pinned' && item.revision === undefined && !delivered.includes(item.entry),
+  )) {
+    const proposed = [...delivered, candidate.entry];
+    if (fits(makeDocument(proposed))) delivered.push(candidate.entry);
+  }
+
+  const document = makeDocument();
+  if (reset && !resetComplete) document.cursor.next = requested;
+  const serialized = fits(document) ? JSON.stringify(document) : '';
+  const outputDocument = serialized ? document : null;
+  return {
+    serialized,
+    document: outputDocument,
+    deliveredEntryIds: outputDocument
+      ? outputDocument.entries.map((entry) => `${entry.sourceBoardId}:${entry.nodeId}`)
+      : [],
+    deliveredDeletionIds: outputDocument ? outputDocument.deletions.map((entry) => entry.nodeId) : [],
+    nextCursor: outputDocument && cursorValid ? (reset && !resetComplete ? requested : safeCursor) : null,
+    reset,
+    invalidCursor: !cursorValid,
+    truncated: !outputDocument || document.delivery.truncated,
+  };
+}

package/src/server/context-reads.ts

@@ -0,0 +1,238 @@
+/**
+ * Context read instrumentation (vision Part 1 item 4, the delivery half):
+ * one row per agent read of canvas context — which surface, by whom, and
+ * which pinned nodes were in what came back. Diagnostics only, like the AX
+ * timeline: never snapshotted, never cleared with the canvas, bounded, and
+ * recording never notifies (a read must not trigger more reads).
+ */
+import type { Database } from 'bun:sqlite';
+import { randomUUID } from 'node:crypto';
+
+export const CONTEXT_READ_RETENTION = 5000;
+const CONTEXT_READ_DEFAULT_LIMIT = 50;
+const CONTEXT_READ_MAX_LIMIT = 500;
+
+export const CONTEXT_READ_CHANNELS = ['operation', 'mcp-resource', 'mcp-prompt', 'adapter'] as const;
+export type ContextReadChannel = (typeof CONTEXT_READ_CHANNELS)[number];
+
+/** Registry reads that hand an agent canvas context; recorded in executeOperation. */
+export const CONTEXT_READ_OPS = new Set([
+  'pinned-context.get',
+  'ax.context.get',
+  'ax.get',
+  'summary.get',
+  'spatial.get',
+  'layout.get',
+  'context.get',
+]);
+
+export interface ContextRead {
+  seq: number;
+  id: string;
+  at: string;
+  channel: ContextReadChannel;
+  resource: string;
+  source: string;
+  consumer: string | null;
+  agentId: string | null;
+  pinnedNodeIds: string[];
+  deliveredNodeIds: string[];
+  bytes: number;
+  /** The board open when the read happened (null on Home). */
+  boardId: string | null;
+}
+
+export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId'> & {
+  /** Explicit read target, captured before asynchronous formatting/proxy work. */
+  boardId?: string | null;
+};
+
+export interface ContextReadConsumerSummary {
+  consumer: string;
+  reads: number;
+  readsWithPins: number;
+  readsDeliveringAllPins: number;
+  lastReadAt: string;
+  resources: Record<string, number>;
+}
+
+/**
+ * Pinned nodes whose serialized node (an object carrying `"id": "<id>"`) is in
+ * what the reader received. A bare id list, a title, or a clipped-off node does
+ * not count — the agent got the pin's name, not its content.
+ */
+export function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[] {
+  const pinned = new Set(pinnedNodeIds);
+  const delivered = new Set<string>();
+  const objectStarts: number[] = [];
+  let inString = false;
+  let escaped = false;
+
+  for (let index = 0; index < payloadText.length; index += 1) {
+    const character = payloadText[index];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === '\\') escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"') {
+      inString = true;
+    } else if (character === '{') {
+      objectStarts.push(index);
+    } else if (character === '}' && objectStarts.length > 0) {
+      const start = objectStarts.pop();
+      if (start === undefined) continue;
+      try {
+        const value = JSON.parse(payloadText.slice(start, index + 1)) as unknown;
+        if (
+          typeof value === 'object' &&
+          value !== null &&
+          !Array.isArray(value) &&
+          ((typeof (value as { id?: unknown }).id === 'string' && pinned.has((value as { id: string }).id)) ||
+            (typeof (value as { nodeId?: unknown }).nodeId === 'string' &&
+              (value as { titleOnly?: unknown }).titleOnly !== true &&
+              typeof (value as { text?: unknown }).text === 'string' &&
+              pinned.has((value as { nodeId: string }).nodeId)))
+        ) {
+          delivered.add(
+            typeof (value as { id?: unknown }).id === 'string'
+              ? (value as { id: string }).id
+              : (value as { nodeId: string }).nodeId,
+          );
+        }
+      } catch {
+        // An inner object may be complete even when its containing object was clipped.
+      }
+    }
+  }
+
+  return pinnedNodeIds.filter((id) => delivered.has(id));
+}
+
+export function contextReadFromPayload(
+  base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes'>,
+  payload: unknown,
+): ContextReadInput {
+  const text = typeof payload === 'string' ? payload : (JSON.stringify(payload) ?? '');
+  return {
+    ...base,
+    deliveredNodeIds: deliveredPinnedIds(base.pinnedNodeIds, text),
+    bytes: Buffer.byteLength(text, 'utf-8'),
+  };
+}
+
+export const CONTEXT_READS_SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS context_reads (
+    seq INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    at TEXT NOT NULL,
+    channel TEXT NOT NULL,
+    resource TEXT NOT NULL,
+    source TEXT NOT NULL,
+    consumer TEXT,
+    agent_id TEXT,
+    pinned_node_ids TEXT NOT NULL DEFAULT '[]',
+    delivered_node_ids TEXT NOT NULL DEFAULT '[]',
+    bytes INTEGER NOT NULL DEFAULT 0,
+    board_id TEXT
+  );
+`;
+
+export function appendContextReadToDB(db: Database, input: ContextReadInput, boardId: string | null): ContextRead {
+  const id = `read-${randomUUID()}`;
+  const at = new Date().toISOString();
+  db.run(
+    'INSERT INTO context_reads (id, at, channel, resource, source, consumer, agent_id, pinned_node_ids, delivered_node_ids, bytes, board_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    [
+      id,
+      at,
+      input.channel,
+      input.resource,
+      input.source,
+      input.consumer,
+      input.agentId,
+      JSON.stringify(input.pinnedNodeIds),
+      JSON.stringify(input.deliveredNodeIds),
+      input.bytes,
+      boardId,
+    ],
+  );
+  const seq = Number(db.query<{ seq: number }, []>('SELECT last_insert_rowid() AS seq').get()?.seq ?? 0);
+  db.run('DELETE FROM context_reads WHERE seq <= ?', [seq - CONTEXT_READ_RETENTION]);
+  return { ...input, seq, id, at, boardId };
+}
+
+interface ContextReadRow {
+  seq: number;
+  id: string;
+  at: string;
+  channel: ContextReadChannel;
+  resource: string;
+  source: string;
+  consumer: string | null;
+  agent_id: string | null;
+  pinned_node_ids: string;
+  delivered_node_ids: string;
+  bytes: number;
+  board_id: string | null;
+}
+
+function rowToContextRead(row: ContextReadRow): ContextRead {
+  return {
+    seq: row.seq,
+    id: row.id,
+    at: row.at,
+    channel: row.channel,
+    resource: row.resource,
+    source: row.source,
+    consumer: row.consumer,
+    agentId: row.agent_id,
+    pinnedNodeIds: JSON.parse(row.pinned_node_ids) as string[],
+    deliveredNodeIds: JSON.parse(row.delivered_node_ids) as string[],
+    bytes: row.bytes,
+    boardId: row.board_id,
+  };
+}
+
+/** Newest first. The summary covers every retained row, not just the returned page. */
+export function loadContextReadsFromDB(
+  db: Database,
+  limit?: number,
+): { reads: ContextRead[]; summary: ContextReadConsumerSummary[] } {
+  const pageSize =
+    typeof limit === 'number' && Number.isFinite(limit) && limit > 0
+      ? Math.min(Math.floor(limit), CONTEXT_READ_MAX_LIMIT)
+      : CONTEXT_READ_DEFAULT_LIMIT;
+  const rows = db.query<ContextReadRow, []>('SELECT * FROM context_reads ORDER BY seq DESC').all();
+  const all = rows.map(rowToContextRead);
+  return { reads: all.slice(0, pageSize), summary: summarizeContextReads(all) };
+}
+
+export function summarizeContextReads(reads: ContextRead[]): ContextReadConsumerSummary[] {
+  const byConsumer = new Map<string, ContextReadConsumerSummary>();
+  for (const read of reads) {
+    const key = read.consumer ?? read.agentId ?? read.source;
+    const entry = byConsumer.get(key) ?? {
+      consumer: key,
+      reads: 0,
+      readsWithPins: 0,
+      readsDeliveringAllPins: 0,
+      lastReadAt: read.at,
+      resources: {},
+    };
+    entry.reads += 1;
+    if (read.pinnedNodeIds.length > 0) {
+      entry.readsWithPins += 1;
+      const pins = new Set(read.pinnedNodeIds);
+      const delivered = new Set(read.deliveredNodeIds);
+      if (delivered.size === pins.size && [...delivered].every((id) => pins.has(id))) {
+        entry.readsDeliveringAllPins += 1;
+      }
+    }
+    if (read.at > entry.lastReadAt) entry.lastReadAt = read.at;
+    entry.resources[read.resource] = (entry.resources[read.resource] ?? 0) + 1;
+    byConsumer.set(key, entry);
+  }
+  return [...byConsumer.values()].sort((a, b) => b.lastReadAt.localeCompare(a.lastReadAt));
+}