pmx-canvas 0.6.5 → 0.7.1

package/src/server/ax-context.ts

@@ -119,7 +119,7 @@ function buildHumanAnnotations(layout: CanvasLayout): PmxAxHumanAnnotation[] {
   });
 }
 
-export function buildCanvasAxContext(consumer?: string): PmxAxContext {
+export function buildCanvasAxContext(consumer?: string): PmxAxContext & { boardId: string | null } {
   const layout = canvasState.getLayout();
   const ax = canvasState.getAxState();
   const focusNodes = ax.focus.nodeIds
@@ -130,7 +130,7 @@ export function buildCanvasAxContext(consumer?: string): PmxAxContext {
   // The FIFO claim/ack queue (getPendingSteering) stays oldest-first for processing.
   const pendingSteering = canvasState.getPendingSteeringForContext({ consumer, limit: AX_CONTEXT_STEERING_LIMIT });
   const totalPending = canvasState.getPendingSteeringCount(consumer);
-  return buildAxContext({
+  const context = buildAxContext({
     layout,
     delivery: {
       pendingSteering,
@@ -151,4 +151,6 @@ export function buildCanvasAxContext(consumer?: string): PmxAxContext {
     timeline: canvasState.getAxTimelineSummary(),
     host: canvasState.getHostCapability(),
   });
+  // Capture attribution with the payload, before any transport awaits or board switches.
+  return { ...context, boardId: canvasState.activeBoardId };
 }

package/src/server/ax-interaction.ts

@@ -131,6 +131,7 @@ export const DEFAULT_NODE_AX_CAPABILITIES: Record<CanvasNodeType, NodeAxCapabili
     'ax.event.record',
   ]),
   graph: caps(true, ['ax.evidence.add', 'ax.focus.set', 'ax.event.record']),
+  board: caps(false, []),
   ledger: caps(true, ['ax.evidence.add', 'ax.event.record']),
   trace: caps(true, ['ax.evidence.add', 'ax.event.record']),
   image: caps(true, ['ax.evidence.add', 'ax.review.add']),

package/src/server/ax-state-manager.ts

@@ -84,6 +84,7 @@ import {
   type PmxAxTimelineSummary,
 } from './ax-state.js';
 import type { CanvasChangeType, MutationRecordInfo } from './canvas-state.js';
+import { currentActor, type ActorAttribution } from './attribution.js';
 
 type Database = import('bun:sqlite').Database;
 
@@ -115,6 +116,21 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function resolutionActor(source?: PmxAxSource): ActorAttribution {
+  if (source === 'system') return { actor: 'system', source: 'system' };
+  const actor = currentActor(source ?? 'sdk');
+  return source && actor.actor === 'agent' ? { ...actor, source } : actor;
+}
+
+function selfAnswered(requester: ActorAttribution | undefined, answerer: ActorAttribution): boolean {
+  return (
+    requester?.actor === 'agent' &&
+    answerer.actor === 'agent' &&
+    Boolean(requester.agentId) &&
+    requester.agentId === answerer.agentId
+  );
+}
+
 function logAxStateWarning(action: string, error: unknown, details?: Record<string, unknown>): void {
   console.warn(`[ax-state] ${action}`, { error, ...(details ?? {}) });
 }
@@ -342,7 +358,12 @@ export class AxStateManager {
     options: { source?: PmxAxSource } = {},
   ): PmxAxApprovalGate {
     const oldAxState = this.getAxState();
-    const gate = createAxApprovalGate(input, options.source ?? 'api', this.deps.getNodeIds());
+    const gate = createAxApprovalGate(
+      input,
+      options.source ?? 'api',
+      this.deps.getNodeIds(),
+      resolutionActor(options.source),
+    );
     this.applyAxState({ ...oldAxState, approvalGates: [...oldAxState.approvalGates, gate] });
     const applied = this.getAxState();
     this.deps.scheduleSave();
@@ -372,12 +393,15 @@ export class AxStateManager {
     const oldAxState = this.getAxState();
     const gate = oldAxState.approvalGates.find((g) => g.id === id);
     if (!gate || gate.status !== 'pending') return null;
+    const resolvedBy = resolutionActor(options.source);
     const resolved: PmxAxApprovalGate = {
       ...gate,
       status: decision,
       resolvedAt: new Date().toISOString(),
       resolution: options.resolution ?? null,
       source: options.source ?? gate.source,
+      resolvedBy,
+      selfAnswer: selfAnswered(gate.requestedBy, resolvedBy),
     };
     this.applyAxState({ ...oldAxState, approvalGates: replaceById(oldAxState.approvalGates, resolved) });
     const applied = this.getAxState();
@@ -397,6 +421,15 @@ export class AxStateManager {
         this.deps.notifyChange('ax');
       }),
     });
+    this.recordAxEvent(
+      {
+        kind: 'approval',
+        summary: `${decision === 'approved' ? 'Approved' : decision === 'rejected' ? 'Rejected' : 'Held'} "${gate.title}"`,
+        nodeIds: gate.nodeIds,
+        data: { gateId: id, decision, resolvedBy, selfAnswer: resolved.selfAnswer },
+      },
+      { source: options.source ?? 'api', agentId: resolvedBy.agentId ?? null },
+    );
     return applied.approvalGates.find((g) => g.id === id) ?? null;
   }
 
@@ -415,6 +448,8 @@ export class AxStateManager {
       resolvedAt: null,
       resolution: null,
       source: options.source ?? gate.source,
+      resolvedBy: null,
+      selfAnswer: false,
     };
     this.applyAxState({ ...oldAxState, approvalGates: replaceById(oldAxState.approvalGates, reopened) });
     const applied = this.getAxState();
@@ -545,7 +580,12 @@ export class AxStateManager {
     options: { source?: PmxAxSource } = {},
   ): PmxAxElicitation {
     const oldAxState = this.getAxState();
-    const elicitation = createAxElicitation(input, options.source ?? 'api', this.deps.getNodeIds());
+    const elicitation = createAxElicitation(
+      input,
+      options.source ?? 'api',
+      this.deps.getNodeIds(),
+      resolutionActor(options.source),
+    );
     this.applyAxState({ ...oldAxState, elicitations: [...oldAxState.elicitations, elicitation] });
     const applied = this.getAxState();
     this.deps.scheduleSave();
@@ -575,12 +615,15 @@ export class AxStateManager {
     const oldAxState = this.getAxState();
     const existing = oldAxState.elicitations.find((e) => e.id === id);
     if (!existing || existing.status !== 'pending') return null;
+    const resolvedBy = resolutionActor(options.source);
     const merged: PmxAxElicitation = {
       ...existing,
       status: 'answered',
       response,
       resolvedAt: new Date().toISOString(),
       source: options.source ?? existing.source,
+      resolvedBy,
+      selfAnswer: selfAnswered(existing.requestedBy, resolvedBy),
     };
     this.applyAxState({ ...oldAxState, elicitations: replaceById(oldAxState.elicitations, merged) });
     const applied = this.getAxState();
@@ -600,6 +643,15 @@ export class AxStateManager {
         this.deps.notifyChange('ax');
       }),
     });
+    this.recordAxEvent(
+      {
+        kind: 'approval',
+        summary: `Answered elicitation "${existing.prompt}"`,
+        nodeIds: existing.nodeIds,
+        data: { elicitationId: id, resolvedBy, selfAnswer: merged.selfAnswer },
+      },
+      { source: options.source ?? 'api', agentId: resolvedBy.agentId ?? null },
+    );
     return applied.elicitations.find((e) => e.id === id) ?? null;
   }
 
@@ -613,7 +665,12 @@ export class AxStateManager {
     options: { source?: PmxAxSource } = {},
   ): PmxAxModeRequest {
     const oldAxState = this.getAxState();
-    const request = createAxModeRequest(input, options.source ?? 'api', this.deps.getNodeIds());
+    const request = createAxModeRequest(
+      input,
+      options.source ?? 'api',
+      this.deps.getNodeIds(),
+      resolutionActor(options.source),
+    );
     this.applyAxState({ ...oldAxState, modeRequests: [...oldAxState.modeRequests, request] });
     const applied = this.getAxState();
     this.deps.scheduleSave();
@@ -643,12 +700,15 @@ export class AxStateManager {
     const oldAxState = this.getAxState();
     const existing = oldAxState.modeRequests.find((m) => m.id === id);
     if (!existing || existing.status !== 'pending') return null;
+    const resolvedBy = resolutionActor(options.source);
     const merged: PmxAxModeRequest = {
       ...existing,
       status: decision,
       resolvedAt: new Date().toISOString(),
       resolution: options.resolution ?? null,
       source: options.source ?? existing.source,
+      resolvedBy,
+      selfAnswer: selfAnswered(existing.requestedBy, resolvedBy),
     };
     this.applyAxState({ ...oldAxState, modeRequests: replaceById(oldAxState.modeRequests, merged) });
     const applied = this.getAxState();
@@ -668,6 +728,15 @@ export class AxStateManager {
         this.deps.notifyChange('ax');
       }),
     });
+    this.recordAxEvent(
+      {
+        kind: 'approval',
+        summary: `${decision === 'approved' ? 'Approved' : 'Rejected'} ${existing.mode} mode request`,
+        nodeIds: existing.nodeIds,
+        data: { modeRequestId: id, decision, resolvedBy, selfAnswer: merged.selfAnswer },
+      },
+      { source: options.source ?? 'api', agentId: resolvedBy.agentId ?? null },
+    );
     return applied.modeRequests.find((m) => m.id === id) ?? null;
   }
 

package/src/server/ax-state.ts

@@ -2,6 +2,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 { ActorAttribution } from './attribution.js';
 
 export type PmxAxSource = 'agent' | 'amp' | 'api' | 'browser' | 'cli' | 'codex' | 'copilot' | 'mcp' | 'sdk' | 'system';
 
@@ -48,6 +49,9 @@ export interface PmxAxApprovalGate {
   resolvedAt: string | null;
   resolution: string | null;
   source: PmxAxSource | null;
+  requestedBy?: ActorAttribution;
+  resolvedBy?: ActorAttribution | null;
+  selfAnswer?: boolean;
 }
 
 export interface PmxAxReviewRegion {
@@ -301,6 +305,16 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function normalizeAttribution(value: unknown): ActorAttribution {
+  if (!isRecord(value)) return { actor: 'unknown', source: 'unknown' };
+  const actor = value.actor;
+  return {
+    actor: actor === 'human' || actor === 'agent' || actor === 'system' ? actor : 'unknown',
+    source: typeof value.source === 'string' ? value.source : 'unknown',
+    ...(typeof value.agentId === 'string' ? { agentId: value.agentId } : {}),
+  };
+}
+
 function normalizeSource(value: unknown): PmxAxSource | null {
   return typeof value === 'string' && AX_SOURCES.has(value as PmxAxSource) ? (value as PmxAxSource) : null;
 }
@@ -548,6 +562,9 @@ export interface PmxAxElicitation {
   createdAt: string;
   resolvedAt: string | null;
   source: PmxAxSource | null;
+  requestedBy?: ActorAttribution;
+  resolvedBy?: ActorAttribution | null;
+  selfAnswer?: boolean;
 }
 
 export function normalizeAxElicitation(input: unknown, validNodeIds?: Set<string>): PmxAxElicitation | null {
@@ -564,6 +581,9 @@ export function normalizeAxElicitation(input: unknown, validNodeIds?: Set<string
     createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
     resolvedAt: normalizeTimestamp(input.resolvedAt),
     source: normalizeSource(input.source),
+    requestedBy: normalizeAttribution(input.requestedBy),
+    resolvedBy: input.resolvedBy ? normalizeAttribution(input.resolvedBy) : null,
+    selfAnswer: input.selfAnswer === true,
   };
 }
 
@@ -571,6 +591,7 @@ export function createAxElicitation(
   input: { prompt: string; fields?: string[]; nodeIds?: string[] },
   source: PmxAxSource | null,
   validNodeIds?: Set<string>,
+  requestedBy: ActorAttribution = { actor: 'unknown', source: 'unknown' },
 ): PmxAxElicitation {
   return {
     id: axId('elic'),
@@ -582,6 +603,9 @@ export function createAxElicitation(
     createdAt: nowIso(),
     resolvedAt: null,
     source,
+    requestedBy,
+    resolvedBy: null,
+    selfAnswer: false,
   };
 }
 
@@ -602,6 +626,9 @@ export interface PmxAxModeRequest {
   resolvedAt: string | null;
   resolution: string | null;
   source: PmxAxSource | null;
+  requestedBy?: ActorAttribution;
+  resolvedBy?: ActorAttribution | null;
+  selfAnswer?: boolean;
 }
 
 export function normalizeAxModeRequest(input: unknown, validNodeIds?: Set<string>): PmxAxModeRequest | null {
@@ -618,6 +645,9 @@ export function normalizeAxModeRequest(input: unknown, validNodeIds?: Set<string
     resolvedAt: normalizeTimestamp(input.resolvedAt),
     resolution: optionalString(input.resolution),
     source: normalizeSource(input.source),
+    requestedBy: normalizeAttribution(input.requestedBy),
+    resolvedBy: input.resolvedBy ? normalizeAttribution(input.resolvedBy) : null,
+    selfAnswer: input.selfAnswer === true,
   };
 }
 
@@ -625,6 +655,7 @@ export function createAxModeRequest(
   input: { mode: PmxAxMode; reason?: string | null; nodeIds?: string[] },
   source: PmxAxSource | null,
   validNodeIds?: Set<string>,
+  requestedBy: ActorAttribution = { actor: 'unknown', source: 'unknown' },
 ): PmxAxModeRequest {
   return {
     id: axId('mode'),
@@ -636,6 +667,9 @@ export function createAxModeRequest(
     resolvedAt: null,
     resolution: null,
     source,
+    requestedBy,
+    resolvedBy: null,
+    selfAnswer: false,
   };
 }
 
@@ -715,6 +749,9 @@ export function normalizeAxApprovalGate(input: unknown, validNodeIds?: Set<strin
     resolvedAt: normalizeTimestamp(input.resolvedAt),
     resolution: optionalString(input.resolution),
     source: normalizeSource(input.source),
+    requestedBy: normalizeAttribution(input.requestedBy),
+    resolvedBy: input.resolvedBy ? normalizeAttribution(input.resolvedBy) : null,
+    selfAnswer: input.selfAnswer === true,
   };
 }
 
@@ -856,6 +893,7 @@ export function createAxApprovalGate(
   input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[]; ttlMs?: number },
   source: PmxAxSource | null,
   validNodeIds?: Set<string>,
+  requestedBy: ActorAttribution = { actor: 'unknown', source: 'unknown' },
 ): PmxAxApprovalGate {
   const created = Date.now();
   return {
@@ -870,6 +908,9 @@ export function createAxApprovalGate(
     resolvedAt: null,
     resolution: null,
     source,
+    requestedBy,
+    resolvedBy: null,
+    selfAnswer: false,
   };
 }
 

package/src/server/backup.ts

@@ -0,0 +1,178 @@
+/**
+ * Library backup (plan 012): the whole workspace database — every board, its
+ * snapshots and blobs — copied with `VACUUM INTO`, which is safe while the
+ * server runs. Backups are plain files in a folder the human chooses; the
+ * schedule lives in the database and runs inside the server.
+ */
+import { Database } from 'bun:sqlite';
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { canvasState, PMX_CANVAS_DIR } from './canvas-state.js';
+
+const FILE_PATTERN = /^canvas-(\d{8}T\d{9}Z)(?:-(\d+))?\.db$/;
+const DEFAULT_KEEP = 14;
+const MIN_INTERVAL_MS = 60_000;
+const CHECK_INTERVAL_MS = 60_000;
+
+const META = {
+  folder: 'backup_folder',
+  everyMs: 'backup_every_ms',
+  keep: 'backup_keep',
+  lastAt: 'backup_last_at',
+  lastPath: 'backup_last_path',
+} as const;
+
+export interface BackupFile {
+  path: string;
+  bytes: number;
+  at: string;
+}
+
+export interface BackupStatus {
+  folder: string;
+  keep: number;
+  everyMs: number | null;
+  lastAt: string | null;
+  lastPath: string | null;
+  backups: BackupFile[];
+}
+
+/** "90s", "30m", "24h", "7d" → milliseconds. */
+export function parseBackupInterval(value: string): number | null {
+  const match = value.trim().match(/^(\d+)\s*([smhd])$/i);
+  if (!match) return null;
+  const unit = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[match[2].toLowerCase() as 's' | 'm' | 'h' | 'd'];
+  return Number(match[1]) * unit;
+}
+
+function resolveFolder(folder: string): string {
+  return isAbsolute(folder) ? folder : resolve(canvasState.workspaceRoot, folder);
+}
+
+/** Beside the database: `.pmx-canvas/backups` unless PMX_CANVAS_DB_PATH moved it. */
+function defaultFolder(): string {
+  const dbPath = canvasState.databasePath;
+  return resolve(
+    dbPath ? join(dirname(dbPath), 'backups') : join(canvasState.workspaceRoot, PMX_CANVAS_DIR, 'backups'),
+  );
+}
+
+function listBackupFiles(folder: string): BackupFile[] {
+  if (!existsSync(folder)) return [];
+  // Newest first by the name's timestamp, then its same-millisecond counter.
+  const order = (name: string): string => {
+    const match = name.match(FILE_PATTERN);
+    return `${match?.[1] ?? ''}-${(match?.[2] ?? '1').padStart(6, '0')}`;
+  };
+  return readdirSync(folder)
+    .filter((name) => FILE_PATTERN.test(name))
+    .sort((a, b) => order(b).localeCompare(order(a)))
+    .map((name) => {
+      const path = join(folder, name);
+      const stat = statSync(path);
+      return { path, bytes: stat.size, at: stat.mtime.toISOString() };
+    });
+}
+
+export function getBackupStatus(): BackupStatus {
+  const everyMs = Number(canvasState.readWorkspaceMeta(META.everyMs));
+  const folder = canvasState.readWorkspaceMeta(META.folder) ?? defaultFolder();
+  return {
+    folder,
+    keep: Number(canvasState.readWorkspaceMeta(META.keep)) || DEFAULT_KEEP,
+    everyMs: everyMs > 0 ? everyMs : null,
+    lastAt: canvasState.readWorkspaceMeta(META.lastAt),
+    lastPath: canvasState.readWorkspaceMeta(META.lastPath),
+    backups: listBackupFiles(folder),
+  };
+}
+
+/** Back up now; keeps the newest `keep` backups in the folder and removes older ones. */
+export function runBackup(options: { folder?: string; keep?: number } = {}): {
+  backup: BackupFile;
+  removed: string[];
+} {
+  const status = getBackupStatus();
+  const folder = options.folder ? resolveFolder(options.folder) : status.folder;
+  const keep = options.keep ?? status.keep;
+  mkdirSync(folder, { recursive: true });
+
+  const stamp = new Date().toISOString().replace(/[-:.]/g, '');
+  let path = join(folder, `canvas-${stamp}.db`);
+  for (let n = 2; existsSync(path); n++) path = join(folder, `canvas-${stamp}-${n}.db`);
+  canvasState.backupDatabaseTo(path);
+
+  const removed = listBackupFiles(folder)
+    .slice(keep)
+    .map((file) => file.path);
+  for (const file of removed) rmSync(file, { force: true });
+
+  const at = new Date().toISOString();
+  canvasState.writeWorkspaceMeta(META.lastAt, at);
+  canvasState.writeWorkspaceMeta(META.lastPath, path);
+  return { backup: { path, bytes: statSync(path).size, at }, removed };
+}
+
+/** Set the schedule (`everyMs` null turns it off). Folder and keep also apply to manual backups. */
+export function setBackupSchedule(options: { everyMs: number | null; folder?: string; keep?: number }): BackupStatus {
+  if (options.everyMs !== null && options.everyMs < MIN_INTERVAL_MS) {
+    throw new Error('Back up at most once a minute.');
+  }
+  canvasState.writeWorkspaceMeta(META.everyMs, options.everyMs === null ? null : String(options.everyMs));
+  if (options.folder) canvasState.writeWorkspaceMeta(META.folder, resolveFolder(options.folder));
+  if (options.keep) canvasState.writeWorkspaceMeta(META.keep, String(options.keep));
+  return getBackupStatus();
+}
+
+/** Runs a scheduled backup when one is due. Returns whether it ran. */
+export function runDueBackup(now = Date.now()): boolean {
+  if (!canvasState.databasePath) return false;
+  const { everyMs, lastAt } = getBackupStatus();
+  if (!everyMs) return false;
+  if (lastAt && now - Date.parse(lastAt) < everyMs) return false;
+  runBackup();
+  return true;
+}
+
+/** Rejects anything that is not a canvas database before the live file is touched. */
+export function assertRestorableBackup(file: string): void {
+  if (!existsSync(file) || !statSync(file).isFile()) throw new Error(`No backup file at ${file}.`);
+  if (resolve(file) === resolve(canvasState.databasePath ?? '')) {
+    throw new Error('That is the live database, not a backup.');
+  }
+  let tables: string[] = [];
+  try {
+    const db = new Database(file, { readonly: true });
+    tables = db
+      .query<{ name: string }, []>("SELECT name FROM sqlite_master WHERE type = 'table'")
+      .all()
+      .map((row) => row.name);
+    db.close();
+  } catch {
+    throw new Error(`${file} is not a SQLite database.`);
+  }
+  if (!tables.includes('meta') || !tables.includes('nodes')) {
+    throw new Error(`${file} is not a PMX Canvas database.`);
+  }
+}
+
+let timer: ReturnType<typeof setInterval> | null = null;
+
+export function startBackupScheduler(): void {
+  stopBackupScheduler();
+  const check = () => {
+    try {
+      runDueBackup();
+    } catch (error) {
+      console.warn('[backup] scheduled backup failed', error);
+    }
+  };
+  check();
+  timer = setInterval(check, CHECK_INTERVAL_MS);
+  timer.unref?.();
+}
+
+export function stopBackupScheduler(): void {
+  if (timer) clearInterval(timer);
+  timer = null;
+}