pmx-canvas 0.9.2 → 0.10.0

package/src/server/index.ts

@@ -1,13 +1,21 @@
 import { EventEmitter } from 'node:events';
-import { derivedTour, type Camera, type Tour, type TourStop } from '../shared/tour.js';
-import { exitTour, goToTourStop, moveCamera, type TourStep, type TourStepResult } from './tour-control.js';
+import type { Camera, Tour, TourStop } from '../shared/tour.js';
+import {
+  currentTour,
+  exitTour,
+  goToTourStop,
+  moveCamera,
+  type TourState,
+  type TourStep,
+  type TourStepResult,
+} from './tour-control.js';
 export type { Tour, TourStop } from '../shared/tour.js';
-export type { TourStep, TourStepResult } from './tour-control.js';
+export type { TourState, TourStep, TourStepResult } from './tour-control.js';
 import { agentPresence } from './agent-presence.js';
 import { checkFenceTarget, type FenceTarget } from './scope-fence.js';
 import type { AgentPhase, AgentPresence, AgentPresenceSnapshot } from '../shared/agent-presence.js';
-import { canvasState, IMAGE_MIME_MAP } from './canvas-state.js';
-import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout, ViewportState } from './canvas-state.js';
+import { canvasState } from './canvas-state.js';
+import type { CanvasAnnotation, CanvasNodeState, CanvasEdge, CanvasLayout } from './canvas-state.js';
 import { buildCanvasAxContext } from './ax-context.js';
 import { applyAxInteraction, type AxInteractionInput, type AxInteractionPublicResult } from './ax-interaction.js';
 import { intentRegistry } from './intent-registry.js';
@@ -46,12 +54,12 @@ import { workbenchToken } from './workbench-auth.js';
 import type { BackupFile, BackupStatus } from './backup.js';
 import type { ExportManifest } from './board-export.js';
 import { onFileNodeChanged } from './file-watcher.js';
-import { findOpenCanvasPosition, computeGroupBounds } from './placement.js';
+import { findOpenCanvasPosition } from './placement.js';
 import { overlapsAny } from '../shared/placement.js';
 import { buildSpatialContext } from './spatial-analysis.js';
 import { searchCanvasNodes } from './operations/ops/query.js';
 import { mutationHistory, diffLayouts, formatDiff } from './mutation-history.js';
-import { recomputeCodeGraph, buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
+import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import {
   addCanvasNode,
   addCanvasEdge,
@@ -90,12 +98,7 @@ import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
 import { serializeCanvasNode, type SerializedCanvasNode } from './canvas-serialization.js';
 import { contextReadFromPayload } from './context-reads.js';
-import {
-  buildHtmlPrimitive,
-  getHtmlPrimitiveSemanticMetadata,
-  isHtmlPrimitiveKind,
-  listHtmlPrimitiveDescriptors,
-} from './html-primitives.js';
+import { buildHtmlPrimitive, getHtmlPrimitiveSemanticMetadata } from './html-primitives.js';
 import type { HtmlPrimitiveKind } from './html-primitives.js';
 import {
   buildWebArtifactOnCanvas,
@@ -104,15 +107,7 @@ import {
 } from './web-artifacts.js';
 import { closeMcpAppSession, type ExternalMcpTransportConfig } from './mcp-app-runtime.js';
 import type { DiagramPresetOpenInput } from './diagram-presets.js';
-import {
-  buildGraphSpec,
-  GRAPH_NODE_SIZE,
-  JSON_RENDER_NODE_SIZE,
-  normalizeAndValidateJsonRenderSpec,
-  type GraphNodeInput,
-  type JsonRenderNodeInput,
-  type JsonRenderSpec,
-} from '../json-render/server.js';
+import type { GraphNodeInput, JsonRenderNodeInput, JsonRenderSpec } from '../json-render/server.js';
 import {
   startCanvasServer,
   stopCanvasServer,
@@ -126,15 +121,8 @@ import {
   screenshotCanvasAutomationWebView,
   emitPrimaryWorkbenchEvent,
   setPrimaryWorkbenchCanvasPromptHandler,
-  setPrimaryWorkbenchAutoOpenEnabled,
-  consumePrimaryWorkbenchIntents,
-} from './server.js';
-import type {
-  CanvasAutomationWebViewOptions,
-  CanvasAutomationWebViewStatus,
-  PrimaryWorkbenchCanvasPromptRequest,
-  PrimaryWorkbenchIntent,
 } from './server.js';
+import type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus } from './server.js';
 
 /**
  * Node object returned by the SDK's create/get methods. It is the fully
@@ -632,8 +620,8 @@ export class PmxCanvas extends EventEmitter {
     );
   }
 
-  getTour(): Tour {
-    return canvasState.getTour() ?? derivedTour(canvasState.getLayout().nodes);
+  getTour(): TourState {
+    return currentTour();
   }
 
   setTour(tour: Tour | null): void {

package/src/server/knowledge-lifecycle.ts

@@ -1,6 +1,7 @@
 import type { Database } from 'bun:sqlite';
 import { z } from 'zod';
 import { normalizeBoardFolder } from '../shared/boards.js';
+import { memoryKey, type MemoryTarget } from '../shared/memory-graph.js';
 import { currentActor, type ActorAttribution } from './attribution.js';
 import { OperationError } from './operations/types.js';
 import type { LifecycleQualification } from '../shared/lifecycle-status.js';
@@ -47,6 +48,16 @@ export interface ReviewRecord {
   sourceRevisions?: Record<string, number | null>;
 }
 
+// SQLite trim defaults to ASCII space; match JavaScript evidence.trim(), including Unicode whitespace.
+const evidenceWhitespace =
+  '\u0009\u000a\u000b\u000c\u000d\u0020\u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff';
+const validationPredicate = `json_extract(value, '$.applied') = 1
+  AND json_extract(value, '$.outcome') IN ('retain', 'revise', 'externalize')
+  AND trim(json_extract(value, '$.evidence'), '${evidenceWhitespace}') <> ''`;
+const retirementPredicate = `(json_extract(value, '$.outcome') = 'restore'
+  OR (json_extract(value, '$.applied') = 1 AND json_extract(value, '$.outcome') = 'retire'))`;
+const indexedDatabases = new WeakSet<Database>();
+
 export type KnowledgeInput =
   | { action: 'list' }
   | { action: 'category-set'; category: KnowledgeCategory }
@@ -240,6 +251,61 @@ export class KnowledgeLifecycle {
     return resolved;
   }
 
+  private indexedDb(): Database {
+    const db = this.db();
+    if (!indexedDatabases.has(db)) {
+      db.exec(`CREATE INDEX IF NOT EXISTS review_latest_validation ON review_records
+        (board_id, node_id, sequence DESC) WHERE ${validationPredicate};
+        CREATE INDEX IF NOT EXISTS review_latest_retirement ON review_records
+        (board_id, node_id, sequence DESC) WHERE ${retirementPredicate};
+        CREATE INDEX IF NOT EXISTS lifecycle_incoming_sources ON edges (to_board_id, to_node)
+        WHERE COALESCE(kind, type) IN ('derived-from', 'contradicts', 'supersedes');`);
+      indexedDatabases.add(db);
+    }
+    return db;
+  }
+
+  /** Stored owners of semantic sources; the caller overlays the active board's unsaved edges. */
+  incomingSourceBoards(target: MemoryTarget, activeBoardId: string | null): string[] {
+    return this.indexedDb()
+      .query<{ board_id: string }, [string, string | null, string | null]>(
+        `SELECT DISTINCT board_id FROM edges WHERE to_board_id = ? AND to_node = ?
+       AND board_id IS NOT ? AND COALESCE(kind, type) IN ('derived-from', 'contradicts', 'supersedes')`,
+      )
+      .all(target.boardId, target.cardId ?? null, activeBoardId)
+      .map((row) => row.board_id);
+  }
+
+  /** One indexed latest validation and retirement per card, never its full audit history. */
+  reviewSummaries(targets: MemoryTarget[]): Map<string, { lastValidation: ReviewRecord | null; retired: boolean }> {
+    if (!targets.length) return new Map();
+    const rows = this.indexedDb()
+      .query<{ boardId: string; nodeId: string; validation: string | null; retirement: string | null }, [string]>(
+        `WITH targets AS (
+         SELECT json_extract(value, '$.boardId') AS boardId, json_extract(value, '$.cardId') AS nodeId
+         FROM json_each(?)
+       ) SELECT boardId, nodeId,
+         (SELECT value FROM review_records WHERE board_id = boardId AND node_id = nodeId
+          AND ${validationPredicate} ORDER BY sequence DESC LIMIT 1) AS validation,
+         (SELECT json_extract(value, '$.outcome') FROM review_records WHERE board_id = boardId AND node_id = nodeId
+          AND ${retirementPredicate} ORDER BY sequence DESC LIMIT 1) AS retirement
+       FROM targets`,
+      )
+      .all(JSON.stringify(targets));
+    return new Map(
+      rows.map((row) => {
+        const record: ReviewRecord | null = row.validation ? JSON.parse(row.validation) : null;
+        return [
+          memoryKey({ boardId: row.boardId, cardId: row.nodeId }),
+          {
+            lastValidation: record ? { ...record, contentRevision: record.contentRevision ?? null } : null,
+            retired: row.retirement === 'retire',
+          },
+        ];
+      }),
+    );
+  }
+
   reviews(boardId: string, nodeId: string) {
     const records = (
       this.db()

package/src/server/lifecycle-status.ts

@@ -25,8 +25,70 @@ export function lifecycleQualifications(
   return lifecycleSnapshot(now, atUse).cards;
 }
 
+/** A card being inspected is in use, including its transitive sources and portal contents. */
+export function lifecycleQualification(target: MemoryTarget, now = Date.now()): LifecycleQualification | undefined {
+  return lifecycleSnapshot(now, [target], target).cards[memoryKey(target)];
+}
+
+/** Read closure boards once; never activate them or flush the active board to discover edges. */
+function dependencyClosure(target: MemoryTarget) {
+  const reads = new Map<string, ReturnType<typeof canvasState.readBoard>>();
+  const nodes = new Map<string, CanvasNodeState>();
+  const dependencies = new Map<string, MemoryTarget[]>();
+  const selected = new Set<string>();
+  const queue: MemoryTarget[] = [target];
+  const read = (boardId: string) => {
+    if (!reads.has(boardId)) {
+      const board = canvasState.readBoard(boardId, false);
+      reads.set(boardId, board);
+      for (const node of board?.layout.nodes ?? []) nodes.set(memoryKey({ boardId, cardId: node.id }), node);
+      for (const edge of board?.layout.edges ?? []) {
+        const end = relationSourceEnd(edge);
+        if (!end) continue;
+        const from = { boardId, cardId: edge.from };
+        const to = { boardId: edge.toBoardId ?? boardId, cardId: edge.to };
+        const key = memoryKey(end === 'from' ? to : from);
+        const sources = dependencies.get(key) ?? [];
+        sources.push(end === 'from' ? from : to);
+        dependencies.set(key, sources);
+      }
+    }
+    return reads.get(boardId);
+  };
+  const activeBoardId = canvasState.activeBoardId;
+  const incomingActive = new Set(
+    canvasState
+      .getEdges()
+      .flatMap((edge) =>
+        edge.toBoardId && relationSourceEnd(edge) === 'from'
+          ? [memoryKey({ boardId: edge.toBoardId, cardId: edge.to })]
+          : [],
+      ),
+  );
+  for (const current of queue) {
+    const key = memoryKey(current);
+    if (selected.has(key)) continue;
+    selected.add(key);
+    const board = read(current.boardId);
+    if (!current.cardId) {
+      for (const node of board?.layout.nodes ?? []) queue.push({ boardId: current.boardId, cardId: node.id });
+      continue;
+    }
+    const node = nodes.get(key);
+    if (!node) continue;
+    const provenance = normalizeCanvasNodeData(node.type, node.data).provenance as CanvasNodeProvenance | undefined;
+    queue.push(...(provenance?.sources ?? []).map(({ boardId, cardId }) => ({ boardId, cardId })));
+    if (node.type === 'board' && typeof node.data.boardId === 'string') queue.push({ boardId: node.data.boardId });
+    const owners = new Set([current.boardId, ...canvasState.knowledge.incomingSourceBoards(current, activeBoardId)]);
+    if (activeBoardId && incomingActive.has(key)) owners.add(activeBoardId);
+    for (const owner of owners) read(owner);
+    queue.push(...(dependencies.get(key) ?? []));
+  }
+  return { reads, selected };
+}
+
 /** Compact queue metadata and qualifications come from the same authoritative read. */
-export function lifecycleSnapshot(now = Date.now(), atUse: MemoryTarget[] = []) {
+export function lifecycleSnapshot(now = Date.now(), atUse: MemoryTarget[] = [], only?: MemoryTarget) {
   const result: Record<string, LifecycleQualification> = {};
   const cards = new Map<string, CanvasNodeState>();
   const validations = new Map<string, ReviewRecord | null>();
@@ -34,26 +96,36 @@ export function lifecycleSnapshot(now = Date.now(), atUse: MemoryTarget[] = [])
   const portals = new Map<string, string>();
   const policies = new Map<string, Lifecycle | null>();
   const used = new Set<string>();
-  const reads = canvasState.listBoards().map((board) => ({ board, read: canvasState.readBoard(board.id, false) }));
+  const boards = canvasState.listBoards();
+  const closure = only ? dependencyClosure(only) : null;
+  const reads = boards
+    .filter((board) => !closure || closure.reads.has(board.id))
+    .map((board) => ({
+      board,
+      read: closure ? closure.reads.get(board.id) : canvasState.readBoard(board.id, false),
+    }));
+  const targets = reads
+    .flatMap(({ board, read }) => (read?.layout.nodes ?? []).map((node) => ({ boardId: board.id, cardId: node.id })))
+    .filter((target) => !closure || closure.selected.has(memoryKey(target)));
+  const summaries = canvasState.databasePath ? canvasState.knowledge.reviewSummaries(targets) : null;
   const catalog = canvasState.databasePath
     ? canvasState.knowledge.list()
     : { categories: [], folders: [], relationPresets: [] };
   const session =
     agentPresence.reviewSessionStartedAt() ??
     Date.parse(
-      reads.find(({ board }) => board.id === canvasState.activeBoardId)?.board.lastOpenedAt ??
+      boards.find((board) => board.id === canvasState.activeBoardId)?.lastOpenedAt ??
         new Date(processStartedAt).toISOString(),
     );
   for (const { board, read } of reads) {
     const seen = new Map(canvasState.getNodeReadStatus(board.id).map((status) => [status.nodeId, status]));
     for (const node of read?.layout.nodes ?? []) {
       const key = memoryKey({ boardId: board.id, cardId: node.id });
+      if (closure && !closure.selected.has(key)) continue;
       cards.set(key, node);
       const { lifecycle } = canvasState.knowledge.resolveCard(board.folder, node, catalog);
       policies.set(key, lifecycle);
-      const { lastValidation, retired } = canvasState.databasePath
-        ? canvasState.knowledge.reviews(board.id, node.id)
-        : { lastValidation: null, retired: false };
+      const { lastValidation, retired } = summaries?.get(key) ?? { lastValidation: null, retired: false };
       validations.set(key, lastValidation);
       const lastRead = seen.get(node.id);
       const pinned = read!.state.contextPins.includes(node.id);
@@ -218,7 +290,7 @@ export function lifecycleSnapshot(now = Date.now(), atUse: MemoryTarget[] = [])
   for (const { board, read } of reads) {
     for (const node of read?.layout.nodes ?? []) {
       const status = result[memoryKey({ boardId: board.id, cardId: node.id })];
-      if (status.retired || !(status.due || status.sources.length)) continue;
+      if (!status || status.retired || !(status.due || status.sources.length)) continue;
       reviewCards.push({
         boardId: board.id,
         cardId: node.id,

package/src/server/operations/http.ts

@@ -8,7 +8,7 @@
  */
 import { executeOperation, listOperations } from './registry.js';
 import { SOURCE_LABEL_RE } from '../agent-presence.js';
-import { OperationError } from './types.js';
+import { OperationError, type OperationExecutionOptions, type OperationProgress } from './types.js';
 import { isWorkbenchToken, refuseStaleWorkbenchWrite } from '../workbench-auth.js';
 
 function responseJson(data: unknown, status = 200): Response {
@@ -20,6 +20,57 @@ function responseJson(data: unknown, status = 200): Response {
   });
 }
 
+/** Opt-in NDJSON; the terminal frame retains the ordinary HTTP status/body. */
+export type OperationStreamFrame =
+  | { type: 'progress'; progress: OperationProgress }
+  | { type: 'result'; status: number; body: unknown };
+
+function operationFailure(name: string, error: unknown, signal: AbortSignal): Response {
+  if (signal.aborted) return responseJson({ ok: false, cancelled: true, error: 'Operation cancelled.' }, 499);
+  if (error instanceof OperationError) {
+    return responseJson({ ok: false, error: error.message, ...(error.details ?? {}) }, error.status);
+  }
+  // Keep unexpected errors server-side, never leak a Bun development overlay.
+  console.error(`[operation] unhandled error dispatching ${name}:`, error);
+  return responseJson({ ok: false, error: 'Internal error processing the request.' }, 500);
+}
+
+function progressResponse(
+  req: Request,
+  name: string,
+  run: (options: OperationExecutionOptions) => Promise<Response>,
+): Response {
+  const cancelled = new AbortController();
+  const signal = AbortSignal.any([req.signal, cancelled.signal]);
+  const encoder = new TextEncoder();
+  let closed = false;
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const send = (frame: OperationStreamFrame): void => {
+        if (!closed) controller.enqueue(encoder.encode(`${JSON.stringify(frame)}\n`));
+      };
+      let response: Response;
+      try {
+        response = await run({ signal, onProgress: (progress) => send({ type: 'progress', progress }) });
+      } catch (error) {
+        response = operationFailure(name, error, signal);
+      }
+      if (!closed) {
+        send({ type: 'result', status: response.status, body: await response.json() });
+        closed = true;
+        controller.close();
+      }
+    },
+    cancel() {
+      closed = true;
+      cancelled.abort();
+    },
+  });
+  return new Response(stream, {
+    headers: { 'Content-Type': 'application/x-ndjson', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no' },
+  });
+}
+
 export function matchOperationPath(template: string, pathname: string): Record<string, string> | null {
   const templateSegments = template.split('/');
   const pathSegments = pathname.split('/');
@@ -83,6 +134,7 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
     const params = matchOperationPath(route.path, url.pathname);
     if (!params) continue;
     try {
+      req.signal.throwIfAborted();
       const input = route.readInput
         ? await route.readInput(req, params, url)
         : await readOperationInput(req, params, url);
@@ -100,27 +152,23 @@ export async function dispatchOperationRoute(req: Request, url: URL): Promise<Re
       // HTTP callers read as 'api'.
       const sourceHeader = req.headers.get('x-pmx-source');
       const source = sourceHeader && SOURCE_LABEL_RE.test(sourceHeader) ? sourceHeader : 'api';
-      const result = await executeOperation(op.name, input, {
-        // The legacy marker remains a UI-policy signal (ghost suppression).
-        // Only the unguessable boot token classifies authorship as human.
-        suppressAutoGhost: workbenchMarked,
-        fromWorkbench: workbenchMarked,
-        humanAuthor,
-        source,
-        proxiedRead: req.headers.get('x-pmx-proxied-read') === '1',
-      });
-      return responseJson(result, route.status ? route.status(result) : 200);
+      const run = async (options: OperationExecutionOptions): Promise<Response> => {
+        const result = await executeOperation(op.name, input, {
+          ...options,
+          // The legacy marker remains a UI-policy signal (ghost suppression).
+          // Only the unguessable boot token classifies authorship as human.
+          suppressAutoGhost: workbenchMarked,
+          fromWorkbench: workbenchMarked,
+          humanAuthor,
+          source,
+          proxiedRead: req.headers.get('x-pmx-proxied-read') === '1',
+        });
+        return responseJson(result, route.status ? route.status(result) : 200);
+      };
+      if (req.headers.get('accept') === 'application/x-ndjson') return progressResponse(req, op.name, run);
+      return await run({ signal: req.signal });
     } catch (error) {
-      if (error instanceof OperationError) {
-        return responseJson({ ok: false, error: error.message, ...(error.details ?? {}) }, error.status);
-      }
-      // An unexpected (non-OperationError) throw from a handler MUST NOT escape the
-      // dispatcher: Bun.serve has no per-request boundary, so an escaped throw renders
-      // its dev error overlay (HTTP 500 text/html leaking the absolute server source
-      // path + stack). Return a clean JSON 500 with a generic message instead (the
-      // real error is logged server-side, never echoed to the client).
-      console.error(`[operation] unhandled error dispatching ${op.name}:`, error);
-      return responseJson({ ok: false, error: 'Internal error processing the request.' }, 500);
+      return operationFailure(op.name, error, req.signal);
     }
   }
   return null;

package/src/server/operations/index.ts

@@ -77,7 +77,12 @@ export { runCanvasBatchOperation, type BatchEnvelope } from './ops/batch.js';
 // OpenMcpAppCoreResult is the SDK's cast target for executeOperation('mcpapp.open').
 export type { OpenMcpAppCoreResult } from './ops/app.js';
 export { LocalOperationInvoker, HttpOperationInvoker, type OperationInvoker } from './invoker.js';
-export { registerOperationTools, registerCompositeTools, type OperationToolHost } from './mcp.js';
+export {
+  registerOperationTools,
+  registerCompositeTools,
+  registerOperationHelpTool,
+  type OperationToolHost,
+} from './mcp.js';
 export { compositeToolDefinitions, type CompositeToolDefinition } from './composites.js';
 export {
   OperationError,
@@ -85,5 +90,7 @@ export {
   type Operation,
   type OperationContext,
   type OperationDefinition,
+  type OperationExecutionOptions,
   type OperationErrorStatus,
+  type OperationProgress,
 } from './types.js';

package/src/server/operations/invoker.ts

@@ -5,10 +5,11 @@
  */
 import { SOURCE_LABEL_RE } from '../agent-presence.js';
 import { executeOperation, getOperation } from './registry.js';
-import { OperationError, type OperationErrorStatus } from './types.js';
+import { OperationError, type OperationErrorStatus, type OperationExecutionOptions } from './types.js';
+import type { OperationStreamFrame } from './http.js';
 
 export interface OperationInvoker {
-  invoke(name: string, input: Record<string, unknown>): Promise<unknown>;
+  invoke(name: string, input: Record<string, unknown>, options?: OperationExecutionOptions): Promise<unknown>;
 }
 
 /**
@@ -40,9 +41,14 @@ export class LocalOperationInvoker implements OperationInvoker {
     this.proxiedRead = source === 'mcp';
   }
 
-  async invoke(name: string, input: Record<string, unknown>): Promise<unknown> {
+  async invoke(
+    name: string,
+    input: Record<string, unknown>,
+    options: OperationExecutionOptions = {},
+  ): Promise<unknown> {
     const args = this.allowExternalMcp ? input : { ...input, allowExternalMcp: false };
     return await executeOperation(name, defaultPresenceSource(name, args, this.source), {
+      ...options,
       source: this.source,
       proxiedRead: this.proxiedRead,
     });
@@ -53,6 +59,37 @@ function toOperationErrorStatus(status: number): OperationErrorStatus {
   return status === 404 ? 404 : status === 409 ? 409 : status === 403 ? 403 : 400;
 }
 
+async function readProgressResponse(response: Response, options: OperationExecutionOptions): Promise<Response> {
+  if (!response.body) throw new OperationError('Missing operation progress stream.');
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      buffer += decoder.decode(value, { stream: !done });
+      let end = buffer.indexOf('\n');
+      while (end !== -1) {
+        const frame = JSON.parse(buffer.slice(0, end)) as OperationStreamFrame;
+        buffer = buffer.slice(end + 1);
+        if (frame.type === 'result') return Response.json(frame.body, { status: frame.status });
+        if (frame.type !== 'progress') throw new OperationError('Invalid operation progress frame.');
+        try {
+          await options.onProgress?.(frame.progress);
+        } catch (error) {
+          if (!options.signal?.aborted) console.error('[operation] progress callback failed:', error);
+        }
+        end = buffer.indexOf('\n');
+      }
+      if (done) throw new OperationError('Operation progress stream ended without a result.');
+    }
+  } finally {
+    // A fetch abort already errors the reader; preserve that original failure.
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
 /** Builds the HTTP request from the op's route template (`:id` from input, GET flags to query). */
 export class HttpOperationInvoker implements OperationInvoker {
   private readonly baseUrl: string;
@@ -70,7 +107,12 @@ export class HttpOperationInvoker implements OperationInvoker {
     this.proxiedRead = source === 'mcp';
   }
 
-  async invoke(name: string, rawInput: Record<string, unknown>): Promise<unknown> {
+  async invoke(
+    name: string,
+    rawInput: Record<string, unknown>,
+    options: OperationExecutionOptions = {},
+  ): Promise<unknown> {
+    options.signal?.throwIfAborted();
     const args = this.allowExternalMcp ? rawInput : { ...rawInput, allowExternalMcp: false };
     const input = defaultPresenceSource(name, args, this.source);
     const op = getOperation(name);
@@ -96,8 +138,10 @@ export class HttpOperationInvoker implements OperationInvoker {
 
     let url = `${this.baseUrl}${path}`;
     const proxyHeaders: Record<string, string> = this.proxiedRead ? { 'x-pmx-proxied-read': '1' } : {};
+    if (options.onProgress) proxyHeaders.accept = 'application/x-ndjson';
     const init: RequestInit = {
       method: route.method,
+      signal: options.signal,
       headers: { 'x-pmx-source': this.source, ...proxyHeaders },
     };
     if (route.method === 'GET' || route.method === 'DELETE') {
@@ -112,7 +156,10 @@ export class HttpOperationInvoker implements OperationInvoker {
       init.body = JSON.stringify(rest);
     }
 
-    const response = await fetch(url, init);
+    let response = await fetch(url, init);
+    if (response.headers.get('content-type')?.startsWith('application/x-ndjson')) {
+      response = await readProgressResponse(response, options);
+    }
     const text = await response.text();
     let parsed: unknown = null;
     let parsedAsJson = false;
@@ -125,6 +172,7 @@ export class HttpOperationInvoker implements OperationInvoker {
       }
     }
     if (!response.ok) {
+      if (response.status === 499) throw new DOMException('Operation cancelled.', 'AbortError');
       // errorBodyAsResult carries the route's STRUCTURED partial-failure
       // envelope (e.g. canvas_batch { ok:false, failedIndex, ... }) through as
       // a result. A non-JSON error body (an HTML 502 from a proxy, a foreign