@openprd/cli 0.1.18 → 0.1.19

package/src/canvas-workspace.js

@@ -21,7 +21,6 @@
  * Keep the HTTP API small and file-backed. If realtime collaboration is added,
  * preserve this file-backed session format as the review/archive source.
  */
-import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
 import http from 'node:http';
@@ -32,529 +31,54 @@ import { fileURLToPath } from 'node:url';
 import { renderCanvasAppHtml } from './canvas-app.html.js';
 import { cjoin, exists, readJson, writeJson } from './fs-utils.js';
 import { timestamp } from './time.js';
+import {
+  CANVAS_SURFACE_BACKGROUND,
+  HANDOFF_TEXT_MAX,
+  appendOperation,
+  firstPresent,
+  isPlainObject,
+  normalizeBindingTitle,
+  normalizeStringArray,
+  readOps,
+  sanitizeSessionSegment,
+  trimString,
+} from './canvas-session-store.js';
+import {
+  buildCanvasSessionPaths,
+  ensureCanvasSession,
+  resolveCanvasSessionBinding,
+} from './canvas-binding.js';
+import {
+  CODEX_AGENT_BRIDGE_TRANSPORT,
+  CODEX_DELEGATION_RELAY_TRANSPORT,
+  claimCodexAgentBridgeItem,
+  codexRelayNeedsAgentBridgeFallback,
+  listCodexAgentBridgeOutbox,
+  markCodexAgentBridgeItem,
+  queueCodexAgentBridge,
+  queueCodexThreadRelay,
+} from './canvas-codex-relay.js';
+import {
+  buildCanvasSelectionPayload,
+  dataUrlToBuffer,
+  extensionFromMime,
+  insertAnchoredCanvasImage,
+  materializeImage,
+  mimeFromPath,
+  normalizeCanvasScene,
+  normalizeCanvasSizeContract,
+  appendLibraryItem,
+  readLibrary,
+  writeLibrary,
+} from './canvas-scene.js';
 
-const CANVAS_SCHEMA_VERSION = 1;
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 0;
 const DEFAULT_DAEMON_PORT = 4767;
 const BODY_LIMIT_BYTES = 35 * 1024 * 1024;
-const SESSION_KEY_MAX = 84;
 const DAEMON_READY_TIMEOUT_MS = 7000;
-const HANDOFF_TEXT_MAX = 24000;
 const CLI_BIN_PATH = cjoin(path.dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'openprd.js');
-const CODEX_APP_SERVER_RELAY_WORKER_PATH = cjoin(path.dirname(fileURLToPath(import.meta.url)), 'codex-app-server-relay.js');
-const CODEX_APP_SERVER_RELAY_TIMEOUT_MS = 20 * 60 * 1000;
-const CODEX_APP_SERVER_RELAY_START_WAIT_MS = 0;
-const CODEX_APP_BUNDLE_BIN_PATH = '/Applications/Codex.app/Contents/Resources/codex';
-const CODEX_DELEGATION_RELAY_TRANSPORT = 'codex-app-server-codex-delegation-turn-start';
-const CODEX_AGENT_BRIDGE_TRANSPORT = 'codex-agent-send-message-to-thread';
-const CANVAS_SURFACE_BACKGROUND = '#ffffff';
-const LEGACY_CANVAS_BACKGROUNDS = new Set(['#fbfaf7', '#fffdf9', '#f8f6f1']);
 const CANVAS_OPEN_TARGETS = new Set(['auto', 'system', 'codex-browser']);
-const CODEX_RELAY_DELIVERED_STATUSES = new Set(['completed']);
-const CODEX_RELAY_ACCEPTED_STATUSES = new Set([...CODEX_RELAY_DELIVERED_STATUSES, 'started']);
-const CODEX_RELAY_PENDING_STATUSES = new Set(['queued', 'starting', 'resuming', 'connecting', 'started']);
-const CODEX_RELAY_WAIT_READY_STATUSES = new Set([
-  ...CODEX_RELAY_ACCEPTED_STATUSES,
-  'failed',
-  'timeout-before-start',
-  'timeout-after-start',
-  'closed-before-start',
-  'closed-after-start',
-]);
-const CODEX_RELAY_AGENT_FALLBACK_STATUSES = new Set([
-  'failed',
-  'timeout-before-start',
-  'closed-before-start',
-]);
-
-const MIME_TYPES = {
-  '.html': 'text/html; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.js': 'text/javascript; charset=utf-8',
-  '.css': 'text/css; charset=utf-8',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.webp': 'image/webp',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.excalidraw': 'application/json; charset=utf-8',
-};
-
-function isPlainObject(value) {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-
-function normalizeCanvasSceneAppState(appState) {
-  const nextAppState = isPlainObject(appState) ? { ...appState } : {};
-  const current = String(nextAppState.viewBackgroundColor ?? '').trim().toLowerCase();
-  if (!current || LEGACY_CANVAS_BACKGROUNDS.has(current)) {
-    nextAppState.viewBackgroundColor = CANVAS_SURFACE_BACKGROUND;
-  }
-  return nextAppState;
-}
-
-function normalizeCanvasScene(scene = {}) {
-  const input = isPlainObject(scene) ? scene : {};
-  return {
-    type: input.type ?? 'openprd.canvas.scene.v1',
-    elements: Array.isArray(input.elements) ? input.elements : [],
-    appState: normalizeCanvasSceneAppState(input.appState),
-    files: isPlainObject(input.files) ? input.files : {},
-    savedAt: input.savedAt ?? timestamp(),
-  };
-}
-
-function normalizeCanvasLibrary(input = {}) {
-  const body = isPlainObject(input) ? input : {};
-  const rawItems = Array.isArray(body.libraryItems)
-    ? body.libraryItems
-    : (Array.isArray(body.items) ? body.items : []);
-  return {
-    type: 'excalidrawlib',
-    version: Number.isFinite(Number(body.version)) ? Number(body.version) : 2,
-    source: body.source ?? 'https://openprd.local/canvas',
-    libraryItems: rawItems.map(normalizeLibraryItem).filter(Boolean),
-  };
-}
-
-function normalizeLibraryItem(item) {
-  if (!isPlainObject(item) || !Array.isArray(item.elements) || item.elements.length === 0) {
-    return null;
-  }
-  const id = String(item.id || `lib-${Date.now()}-${shortHash(JSON.stringify(item.elements))}`);
-  const status = item.status === 'published' ? 'published' : 'unpublished';
-  const created = Number.isFinite(Number(item.created)) ? Number(item.created) : Date.now();
-  const nextItem = {
-    id,
-    status,
-    elements: item.elements,
-    created,
-  };
-  if (typeof item.name === 'string' && item.name.trim()) {
-    nextItem.name = trimString(item.name, 120);
-  }
-  if (typeof item.error === 'string' && item.error.trim()) {
-    nextItem.error = trimString(item.error, 500);
-  }
-  return nextItem;
-}
-
-function shortHash(value) {
-  return crypto.createHash('sha256').update(String(value ?? '')).digest('hex').slice(0, 10);
-}
-
-function sanitizeSessionSegment(value, fallback = 'workspace') {
-  const normalized = String(value ?? '')
-    .trim()
-    .replace(/[/\\:]+/g, '-')
-    .replace(/[^a-zA-Z0-9._-]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, SESSION_KEY_MAX);
-  return normalized || fallback;
-}
-
-function buildSessionKey(kind, id) {
-  const safeKind = sanitizeSessionSegment(kind, 'session');
-  const safeId = sanitizeSessionSegment(id, 'workspace');
-  return `${safeKind}-${safeId}-${shortHash(`${kind}:${id}`)}`;
-}
-
-function firstPresent(...values) {
-  for (const value of values) {
-    if (typeof value === 'string' && value.trim()) {
-      return value.trim();
-    }
-  }
-  return null;
-}
-
-function normalizeBindingTitle(...values) {
-  const title = firstPresent(...values);
-  if (!title) {
-    return null;
-  }
-  return title.length > 160 ? `${title.slice(0, 157)}...` : title;
-}
-
-async function readRuntimeEnvironment(projectRoot) {
-  const runtimePath = cjoin(projectRoot, '.openprd', 'harness', 'runtime-environment.json');
-  if (!(await exists(runtimePath))) {
-    return { path: runtimePath, data: null };
-  }
-  try {
-    return { path: runtimePath, data: await readJson(runtimePath) };
-  } catch {
-    return { path: runtimePath, data: null };
-  }
-}
-
-function flattenRuntimeEvidence(runtimeEnvironment) {
-  const runtime = runtimeEnvironment ?? {};
-  const active = runtime.active ?? runtime.activeClient ?? runtime.current ?? {};
-  const detection = runtime.runtimeDetection ?? {};
-  const detectionActive = detection.active ?? detection.current ?? {};
-  const session = runtime.session ?? runtime.conversation ?? detection.session ?? detectionActive.session ?? {};
-  const turn = runtime.turn ?? detection.turn ?? detectionActive.turn ?? {};
-  const evidence = runtime.evidence ?? detection.evidence ?? detectionActive.evidence ?? {};
-  const observed = runtime.observedCapabilities ?? detection.observedCapabilities ?? detectionActive.observedCapabilities ?? [];
-  return {
-    active,
-    detection,
-    detectionActive,
-    session,
-    turn,
-    evidence,
-    observed,
-  };
-}
-
-function selectRuntimeBinding(runtimeEnvironment) {
-  if (!isPlainObject(runtimeEnvironment)) {
-    return null;
-  }
-  const parts = flattenRuntimeEvidence(runtimeEnvironment);
-  const threadId = firstPresent(
-    parts.active.threadId,
-    parts.active.thread_id,
-    parts.active.conversationId,
-    parts.active.conversation_id,
-    parts.detectionActive.threadId,
-    parts.detectionActive.thread_id,
-    parts.detectionActive.conversationId,
-    parts.detectionActive.conversation_id,
-    parts.session.threadId,
-    parts.session.thread_id,
-    parts.session.conversationId,
-    parts.session.conversation_id,
-    parts.turn.threadId,
-    parts.turn.thread_id,
-    parts.evidence.threadId,
-    parts.evidence.thread_id,
-  );
-  if (threadId) {
-    const title = normalizeBindingTitle(
-      parts.active.threadTitle,
-      parts.active.thread_title,
-      parts.active.conversationTitle,
-      parts.active.conversation_title,
-      parts.active.title,
-      parts.active.name,
-      parts.detectionActive.threadTitle,
-      parts.detectionActive.thread_title,
-      parts.detectionActive.conversationTitle,
-      parts.detectionActive.conversation_title,
-      parts.detectionActive.title,
-      parts.detectionActive.name,
-      parts.session.threadTitle,
-      parts.session.thread_title,
-      parts.session.conversationTitle,
-      parts.session.conversation_title,
-      parts.session.title,
-      parts.session.name,
-      parts.turn.threadTitle,
-      parts.turn.thread_title,
-      parts.turn.conversationTitle,
-      parts.turn.conversation_title,
-      parts.evidence.threadTitle,
-      parts.evidence.thread_title,
-      parts.evidence.conversationTitle,
-      parts.evidence.conversation_title,
-    );
-    return {
-      kind: 'thread',
-      id: threadId,
-      title,
-      threadTitle: title,
-      source: 'runtime-environment:thread',
-      activeClient: firstPresent(parts.active.client, parts.active.activeClient, parts.detectionActive.activeClient, parts.detection.activeClient),
-      surface: firstPresent(parts.active.surface, parts.detectionActive.surface, parts.detection.surface),
-      confidence: firstPresent(parts.active.confidence, parts.detectionActive.confidence, parts.detection.confidence),
-      observedCapabilities: parts.observed,
-    };
-  }
-
-  const sessionId = firstPresent(
-    parts.active.sessionId,
-    parts.active.session_id,
-    parts.detectionActive.sessionId,
-    parts.detectionActive.session_id,
-    parts.session.id,
-    parts.session.sessionId,
-    parts.session.session_id,
-    parts.turn.sessionId,
-    parts.turn.session_id,
-    parts.evidence.sessionId,
-    parts.evidence.session_id,
-  );
-  if (sessionId) {
-    const title = normalizeBindingTitle(
-      parts.active.sessionTitle,
-      parts.active.session_title,
-      parts.active.conversationTitle,
-      parts.active.conversation_title,
-      parts.active.title,
-      parts.active.name,
-      parts.detectionActive.sessionTitle,
-      parts.detectionActive.session_title,
-      parts.detectionActive.conversationTitle,
-      parts.detectionActive.conversation_title,
-      parts.detectionActive.title,
-      parts.detectionActive.name,
-      parts.session.sessionTitle,
-      parts.session.session_title,
-      parts.session.conversationTitle,
-      parts.session.conversation_title,
-      parts.session.title,
-      parts.session.name,
-      parts.turn.sessionTitle,
-      parts.turn.session_title,
-      parts.turn.conversationTitle,
-      parts.turn.conversation_title,
-      parts.evidence.sessionTitle,
-      parts.evidence.session_title,
-      parts.evidence.conversationTitle,
-      parts.evidence.conversation_title,
-    );
-    return {
-      kind: 'session',
-      id: sessionId,
-      title,
-      sessionTitle: title,
-      source: 'runtime-environment:session',
-      activeClient: firstPresent(parts.active.client, parts.active.activeClient, parts.detectionActive.activeClient, parts.detection.activeClient),
-      surface: firstPresent(parts.active.surface, parts.detectionActive.surface, parts.detection.surface),
-      confidence: firstPresent(parts.active.confidence, parts.detectionActive.confidence, parts.detection.confidence),
-      observedCapabilities: parts.observed,
-    };
-  }
-
-  return null;
-}
-
-async function resolveCanvasSessionBinding(projectRoot, options = {}, env = process.env) {
-  const explicitThread = firstPresent(options.thread, options.conversation, options.conversationId);
-  if (explicitThread) {
-    const title = normalizeBindingTitle(options.threadTitle, options.conversationTitle, options.title);
-    return {
-      kind: 'thread',
-      id: explicitThread,
-      displayId: explicitThread,
-      title,
-      threadTitle: title,
-      source: 'flag:thread',
-      confidence: 'explicit',
-      sessionKey: buildSessionKey('thread', explicitThread),
-    };
-  }
-
-  const explicitSession = firstPresent(options.session, options.sessionId);
-  if (explicitSession) {
-    const title = normalizeBindingTitle(options.sessionTitle, options.conversationTitle, options.title);
-    return {
-      kind: 'session',
-      id: explicitSession,
-      displayId: explicitSession,
-      title,
-      sessionTitle: title,
-      source: 'flag:session',
-      confidence: 'explicit',
-      sessionKey: buildSessionKey('session', explicitSession),
-    };
-  }
-
-  const envThread = firstPresent(
-    env.OPENPRD_THREAD_ID,
-    env.OPENPRD_CONVERSATION_ID,
-    env.CODEX_THREAD_ID,
-    env.CODEX_CONVERSATION_ID,
-    env.CLAUDE_THREAD_ID,
-    env.CURSOR_THREAD_ID,
-  );
-  if (envThread) {
-    const title = normalizeBindingTitle(
-      env.OPENPRD_THREAD_TITLE,
-      env.OPENPRD_CONVERSATION_TITLE,
-      env.CODEX_THREAD_TITLE,
-      env.CODEX_CONVERSATION_TITLE,
-      env.CLAUDE_THREAD_TITLE,
-      env.CLAUDE_CONVERSATION_TITLE,
-      env.CURSOR_THREAD_TITLE,
-      env.CURSOR_CONVERSATION_TITLE,
-    );
-    return {
-      kind: 'thread',
-      id: envThread,
-      displayId: envThread,
-      title,
-      threadTitle: title,
-      source: 'env:thread',
-      confidence: 'high',
-      sessionKey: buildSessionKey('thread', envThread),
-    };
-  }
-
-  const envSession = firstPresent(
-    env.OPENPRD_SESSION_ID,
-    env.CODEX_SESSION_ID,
-    env.CLAUDE_SESSION_ID,
-    env.CLAUDE_CODE_SESSION_ID,
-    env.CLAUDE_CODE_CHILD_SESSION,
-    env.CURSOR_SESSION_ID,
-  );
-  if (envSession) {
-    const title = normalizeBindingTitle(
-      env.OPENPRD_SESSION_TITLE,
-      env.OPENPRD_CONVERSATION_TITLE,
-      env.CODEX_SESSION_TITLE,
-      env.CODEX_CONVERSATION_TITLE,
-      env.CLAUDE_SESSION_TITLE,
-      env.CLAUDE_CONVERSATION_TITLE,
-      env.CURSOR_SESSION_TITLE,
-      env.CURSOR_CONVERSATION_TITLE,
-    );
-    return {
-      kind: 'session',
-      id: envSession,
-      displayId: envSession,
-      title,
-      sessionTitle: title,
-      source: 'env:session',
-      confidence: 'medium-high',
-      sessionKey: buildSessionKey('session', envSession),
-    };
-  }
-
-  const runtime = await readRuntimeEnvironment(projectRoot);
-  const runtimeBinding = selectRuntimeBinding(runtime.data);
-  if (runtimeBinding) {
-    const binding = {
-      ...runtimeBinding,
-      displayId: runtimeBinding.id,
-      runtimePath: runtime.path,
-      sessionKey: buildSessionKey(runtimeBinding.kind, runtimeBinding.id),
-    };
-    const title = normalizeBindingTitle(runtimeBinding.title, runtimeBinding.threadTitle, runtimeBinding.sessionTitle, runtimeBinding.name);
-    if (title) {
-      binding.title = title;
-      if (binding.kind === 'thread') {
-        binding.threadTitle = title;
-      }
-      if (binding.kind === 'session') {
-        binding.sessionTitle = title;
-      }
-    }
-    return binding;
-  }
-
-  const workspaceId = shortHash(projectRoot);
-  return {
-    kind: 'workspace',
-    id: workspaceId,
-    displayId: `workspace-${workspaceId}`,
-    source: 'workspace-fallback',
-    confidence: 'low',
-    sessionKey: buildSessionKey('workspace', workspaceId),
-    note: 'No current conversation evidence was found; pass --thread or --session to avoid sharing a fallback canvas.',
-  };
-}
-
-function buildCanvasSessionPaths(projectRoot, binding) {
-  const sessionDir = cjoin(projectRoot, '.openprd', 'harness', 'canvas-sessions', binding.sessionKey);
-  return {
-    sessionDir,
-    sessionFile: cjoin(sessionDir, 'session.json'),
-    sceneFile: cjoin(sessionDir, 'scene.json'),
-    libraryFile: cjoin(sessionDir, 'library.json'),
-    opsFile: cjoin(sessionDir, 'ops.json'),
-    serverFile: cjoin(sessionDir, 'server.json'),
-    logFile: cjoin(sessionDir, 'server.log'),
-    assetsDir: cjoin(sessionDir, 'assets'),
-    exportsDir: cjoin(sessionDir, 'exports'),
-    relaysDir: cjoin(sessionDir, 'relays'),
-  };
-}
-
-function preserveCanvasBindingDisplayTitle(binding, existingBinding) {
-  if (!isPlainObject(binding) || !isPlainObject(existingBinding)) {
-    return binding;
-  }
-  if (binding.kind !== existingBinding.kind || binding.id !== existingBinding.id) {
-    return binding;
-  }
-  const title = normalizeBindingTitle(
-    binding.title,
-    binding.threadTitle,
-    binding.sessionTitle,
-    binding.name,
-    existingBinding.title,
-    existingBinding.threadTitle,
-    existingBinding.sessionTitle,
-    existingBinding.name,
-  );
-  if (!title) {
-    return binding;
-  }
-  const nextBinding = { ...binding, title };
-  if (nextBinding.kind === 'thread') {
-    nextBinding.threadTitle = title;
-  }
-  if (nextBinding.kind === 'session') {
-    nextBinding.sessionTitle = title;
-  }
-  return nextBinding;
-}
-
-async function ensureCanvasSession(projectRoot, options = {}, env = process.env) {
-  const binding = await resolveCanvasSessionBinding(projectRoot, options, env);
-  const paths = buildCanvasSessionPaths(projectRoot, binding);
-  await fs.mkdir(paths.assetsDir, { recursive: true });
-  await fs.mkdir(paths.exportsDir, { recursive: true });
-  await fs.mkdir(paths.relaysDir, { recursive: true });
-  const existing = await readJson(paths.sessionFile).catch(() => null);
-  const resolvedBinding = preserveCanvasBindingDisplayTitle(binding, existing?.binding);
-  const now = timestamp();
-  const session = {
-    schema: `openprd.canvas.session.v${CANVAS_SCHEMA_VERSION}`,
-    version: CANVAS_SCHEMA_VERSION,
-    sessionKey: resolvedBinding.sessionKey,
-    projectRoot,
-    binding: resolvedBinding,
-    paths,
-    createdAt: existing?.createdAt ?? now,
-    updatedAt: now,
-  };
-  await writeJson(paths.sessionFile, session);
-  if (!(await exists(paths.sceneFile))) {
-    await writeJson(paths.sceneFile, {
-      type: 'openprd.canvas.scene.v1',
-      elements: [],
-      appState: {
-        viewBackgroundColor: CANVAS_SURFACE_BACKGROUND,
-      },
-      files: {},
-      savedAt: now,
-    });
-  }
-  if (!(await exists(paths.opsFile))) {
-    await writeJson(paths.opsFile, {
-      type: 'openprd.canvas.ops.v1',
-      nextSeq: 0,
-      ops: [],
-    });
-  }
-  if (!(await exists(paths.libraryFile))) {
-    await writeJson(paths.libraryFile, {
-      type: 'excalidrawlib',
-      version: 2,
-      source: 'https://openprd.local/canvas',
-      libraryItems: [],
-    });
-  }
-  return session;
-}
-
 function jsonResponse(res, statusCode, payload) {
   res.writeHead(statusCode, {
     'content-type': 'application/json; charset=utf-8',
@@ -592,159 +116,6 @@ async function readRequestJson(req, limitBytes = BODY_LIMIT_BYTES) {
   return JSON.parse(text);
 }
 
-async function readOps(paths) {
-  const ops = await readJson(paths.opsFile).catch(() => null);
-  if (!ops || !Array.isArray(ops.ops)) {
-    return { type: 'openprd.canvas.ops.v1', nextSeq: 0, ops: [] };
-  }
-  return ops;
-}
-
-async function appendOperation(paths, operation) {
-  const ops = await readOps(paths);
-  const seq = Number(ops.nextSeq ?? ops.ops.length) + 1;
-  const nextOperation = {
-    id: operation.id ?? `op-${seq}-${shortHash(JSON.stringify(operation))}`,
-    seq,
-    createdAt: timestamp(),
-    ...operation,
-  };
-  const nextOps = {
-    ...ops,
-    nextSeq: seq,
-    ops: [...ops.ops, nextOperation],
-  };
-  await writeJson(paths.opsFile, nextOps);
-  return nextOperation;
-}
-
-async function updateOperation(paths, operationId, patch) {
-  const ops = await readOps(paths);
-  let updatedOperation = null;
-  const nextOperations = ops.ops.map((op) => {
-    if (op.id !== operationId) {
-      return op;
-    }
-    updatedOperation = {
-      ...op,
-      ...patch,
-      updatedAt: timestamp(),
-    };
-    return updatedOperation;
-  });
-  if (!updatedOperation) {
-    const error = new Error(`Canvas operation not found: ${operationId}`);
-    error.statusCode = 404;
-    throw error;
-  }
-  await writeJson(paths.opsFile, {
-    ...ops,
-    ops: nextOperations,
-  });
-  return updatedOperation;
-}
-
-async function readLibrary(paths) {
-  return normalizeCanvasLibrary(await readJson(paths.libraryFile).catch(() => ({
-    type: 'openprd.canvas.library.v1',
-    items: [],
-  })));
-}
-
-async function writeLibrary(paths, library) {
-  const nextLibrary = normalizeCanvasLibrary(library);
-  await writeJson(paths.libraryFile, nextLibrary);
-  return nextLibrary;
-}
-
-async function appendLibraryItem(session, input) {
-  const elements = Array.isArray(input.elements) ? input.elements : [];
-  if (elements.length === 0) {
-    const error = new Error('Expected at least one element for a library item.');
-    error.statusCode = 400;
-    throw error;
-  }
-  const library = await readLibrary(session.paths);
-  const id = `lib-${Date.now()}-${shortHash(JSON.stringify(elements))}`;
-  const item = {
-    id,
-    status: input.status === 'published' ? 'published' : 'unpublished',
-    created: Date.now(),
-    elements,
-  };
-  if (input.name) {
-    item.name = trimString(input.name, 120);
-  }
-  const nextItems = [item, ...library.libraryItems].slice(0, 80);
-  const nextLibrary = await writeLibrary(session.paths, {
-    ...library,
-    libraryItems: nextItems,
-  });
-  return { item, library: nextLibrary };
-}
-
-function dataUrlToBuffer(dataUrl) {
-  const match = /^data:([^;,]+)?(;base64)?,([\s\S]*)$/i.exec(String(dataUrl ?? ''));
-  if (!match) {
-    throw new Error('Expected a data URL.');
-  }
-  const mimeType = match[1] || 'application/octet-stream';
-  const isBase64 = Boolean(match[2]);
-  const raw = match[3] ?? '';
-  const buffer = isBase64 ? Buffer.from(raw, 'base64') : Buffer.from(decodeURIComponent(raw), 'utf8');
-  return { buffer, mimeType };
-}
-
-function extensionFromMime(mimeType, fallback = '.bin') {
-  const normalized = String(mimeType ?? '').split(';')[0].trim().toLowerCase();
-  if (normalized === 'image/png') return '.png';
-  if (normalized === 'image/jpeg' || normalized === 'image/jpg') return '.jpg';
-  if (normalized === 'image/webp') return '.webp';
-  if (normalized === 'image/gif') return '.gif';
-  if (normalized === 'image/svg+xml') return '.svg';
-  if (normalized === 'application/json') return '.json';
-  return fallback;
-}
-
-function mimeFromPath(filePath) {
-  return MIME_TYPES[path.extname(filePath).toLowerCase()] ?? 'application/octet-stream';
-}
-
-function trimString(value, maxLength = HANDOFF_TEXT_MAX) {
-  const text = String(value ?? '');
-  return text.length > maxLength ? `${text.slice(0, maxLength)}\n...[truncated]` : text;
-}
-
-function escapeCodexDelegationXml(value) {
-  return String(value ?? '')
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
-}
-
-function buildCodexDelegationText(sourceThreadId, inputText) {
-  const sourceId = trimString(sourceThreadId || 'openprd-canvas', 200);
-  const text = trimString(inputText || 'Please continue from this OpenPrd Canvas handoff.');
-  return [
-    '<codex_delegation>',
-    `  <source_thread_id>${escapeCodexDelegationXml(sourceId)}</source_thread_id>`,
-    `  <input>${escapeCodexDelegationXml(text)}</input>`,
-    '</codex_delegation>',
-  ].join('\n');
-}
-
-function parsePositiveInteger(value, fallback = 0) {
-  const parsed = Number(value);
-  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
-}
-
-function normalizeStringArray(value) {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-  return value.map((item) => String(item)).filter(Boolean);
-}
-
 function downloadsDir(env = process.env) {
   return env.OPENPRD_DOWNLOADS_DIR || path.join(os.homedir(), 'Downloads');
 }
@@ -804,403 +175,6 @@ async function writeTextToSystemClipboard(text, options = {}) {
   throw error;
 }
 
-function relayTimeoutMs(env = process.env) {
-  return parsePositiveInteger(env.OPENPRD_CANVAS_CODEX_RELAY_TIMEOUT_MS, CODEX_APP_SERVER_RELAY_TIMEOUT_MS);
-}
-
-function relayStartWaitMs(options = {}, env = process.env) {
-  if (options.relayWaitMs != null) {
-    return parsePositiveInteger(options.relayWaitMs, 0);
-  }
-  return parsePositiveInteger(env.OPENPRD_CANVAS_CODEX_RELAY_START_WAIT_MS, CODEX_APP_SERVER_RELAY_START_WAIT_MS);
-}
-
-async function sleep(ms) {
-  await new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-async function waitForCodexRelayStart(statusPath, waitMs) {
-  const timeoutMs = parsePositiveInteger(waitMs, 0);
-  if (!timeoutMs) {
-    return null;
-  }
-  const deadline = Date.now() + timeoutMs;
-  let latest = null;
-  while (Date.now() <= deadline) {
-    latest = await readJson(statusPath).catch(() => latest);
-    if (latest?.status && CODEX_RELAY_WAIT_READY_STATUSES.has(latest.status)) {
-      return latest;
-    }
-    await sleep(350);
-  }
-  latest = await readJson(statusPath).catch(() => latest);
-  return latest ? { ...latest, waitTimedOut: true } : {
-    status: 'queued',
-    waitTimedOut: true,
-  };
-}
-
-function relayStatusSummary(statusDoc) {
-  if (!statusDoc) {
-    return {};
-  }
-  const status = statusDoc.status ?? 'queued';
-  return {
-    status,
-    phase: statusDoc.phase ?? null,
-    turn: statusDoc.turn ?? null,
-    resolvedThread: statusDoc.resolvedThread ?? null,
-    error: statusDoc.error ?? null,
-    waitTimedOut: Boolean(statusDoc.waitTimedOut),
-    delivered: CODEX_RELAY_DELIVERED_STATUSES.has(status),
-    pending: Boolean(statusDoc.waitTimedOut) || CODEX_RELAY_PENDING_STATUSES.has(status),
-    accepted: CODEX_RELAY_ACCEPTED_STATUSES.has(status),
-  };
-}
-
-async function resolveCodexAppServerBin(env = process.env) {
-  if (env.OPENPRD_CODEX_APP_SERVER_BIN) {
-    return env.OPENPRD_CODEX_APP_SERVER_BIN;
-  }
-  if (process.platform === 'darwin' && await exists(CODEX_APP_BUNDLE_BIN_PATH)) {
-    return CODEX_APP_BUNDLE_BIN_PATH;
-  }
-  return 'codex';
-}
-
-function codexRelaySkipReason(session, op, options = {}, env = process.env) {
-  if (options.relay === false || options.disableRelay === true) {
-    return 'disabled-by-request';
-  }
-  if (env.OPENPRD_CANVAS_CODEX_RELAY === '0') {
-    return 'disabled-by-env';
-  }
-  if (String(op.target ?? '').toLowerCase() !== 'codex') {
-    return 'unsupported-target';
-  }
-  if (session.binding?.kind !== 'thread' || !session.binding?.id) {
-    return 'not-thread-bound';
-  }
-  return null;
-}
-
-function buildCodexRelayInput(session, op) {
-  const input = [];
-  const text = trimString(op.promptText || op.instruction || 'Please continue from this OpenPrd Canvas handoff.');
-  if (text.trim()) {
-    const sourceThreadId = session.binding?.id || op.binding?.id || op.threadId || 'openprd-canvas';
-    input.push({ type: 'text', text: buildCodexDelegationText(sourceThreadId, text) });
-  }
-  const exportPath = String(op.exportPath ?? '').trim();
-  if (exportPath) {
-    input.push({ type: 'localImage', path: exportPath });
-  }
-  return input;
-}
-
-function buildCodexAgentBridgePrompt(session, op) {
-  const text = trimString(op.promptText || op.instruction || 'Please continue from this OpenPrd Canvas handoff.');
-  const sourceThreadId = session.binding?.id || op.binding?.id || op.threadId || 'openprd-canvas';
-  return buildCodexDelegationText(sourceThreadId, text);
-}
-
-function summarizeAgentBridgeOperation(op) {
-  if (!op) {
-    return null;
-  }
-  return {
-    id: op.id,
-    seq: op.seq ?? null,
-    status: op.status ?? 'pending',
-    target: op.target ?? 'codex',
-    transport: op.transport ?? CODEX_AGENT_BRIDGE_TRANSPORT,
-    handoffOperationId: op.handoffOperationId ?? null,
-    threadId: op.threadId ?? null,
-    threadTitle: op.threadTitle ?? null,
-    prompt: op.prompt ?? null,
-    promptText: op.promptText ?? null,
-    exportPath: op.exportPath ?? null,
-    exportUrl: op.exportUrl ?? null,
-    selection: op.selection ?? null,
-    placeholderId: op.placeholderId ?? null,
-    elementCount: op.elementCount ?? null,
-    selectedElementIds: Array.isArray(op.selectedElementIds) ? op.selectedElementIds : [],
-    createdAt: op.createdAt ?? null,
-    updatedAt: op.updatedAt ?? null,
-    claimedAt: op.claimedAt ?? null,
-    sentAt: op.sentAt ?? null,
-    failedAt: op.failedAt ?? null,
-    reason: op.reason ?? null,
-    requiresAgentTool: op.requiresAgentTool ?? 'codex_app.send_message_to_thread',
-  };
-}
-
-function codexRelayNeedsAgentBridgeFallback(relay) {
-  if (!relay || relay.status === 'skipped') {
-    return true;
-  }
-  const status = String(relay.status ?? '');
-  if (CODEX_RELAY_AGENT_FALLBACK_STATUSES.has(status)) {
-    return true;
-  }
-  return Boolean(relay.waitTimedOut && ['queued', 'starting', 'resuming'].includes(status));
-}
-
-async function queueCodexAgentBridge(session, op, options = {}) {
-  const requested = Boolean(options.agentBridge || options.foregroundBridge);
-  const base = {
-    target: op.target ?? 'codex',
-    transport: CODEX_AGENT_BRIDGE_TRANSPORT,
-    supportsForegroundMessage: false,
-    requiresAgentTool: 'codex_app.send_message_to_thread',
-  };
-  if (options.agentBridgeSkipReason) {
-    return {
-      ...base,
-      status: 'skipped',
-      reason: options.agentBridgeSkipReason,
-      directRelayStatus: options.directRelay?.status ?? null,
-      directRelayTransport: options.directRelay?.transport ?? CODEX_DELEGATION_RELAY_TRANSPORT,
-    };
-  }
-  if (!requested) {
-    return {
-      ...base,
-      status: 'skipped',
-      reason: 'not-requested',
-    };
-  }
-  if (String(op.target ?? '').toLowerCase() !== 'codex') {
-    return {
-      ...base,
-      status: 'skipped',
-      reason: 'unsupported-target',
-    };
-  }
-  if (session.binding?.kind !== 'thread' || !session.binding?.id) {
-    return {
-      ...base,
-      status: 'skipped',
-      reason: 'not-thread-bound',
-    };
-  }
-  const bridgeOp = await appendOperation(session.paths, {
-    type: 'agent-foreground-relay',
-    target: 'codex',
-    transport: CODEX_AGENT_BRIDGE_TRANSPORT,
-    status: 'pending',
-    handoffOperationId: op.id,
-    threadId: session.binding.id,
-    threadTitle: session.binding.title || session.binding.threadTitle || null,
-    prompt: buildCodexAgentBridgePrompt(session, op),
-    promptText: op.promptText ?? null,
-    exportPath: op.exportPath ?? null,
-    exportUrl: op.exportUrl ?? null,
-    selection: op.selection ?? null,
-    placeholderId: op.placeholderId ?? null,
-    elementCount: op.elementCount ?? null,
-    selectedElementIds: Array.isArray(op.selectedElementIds) ? op.selectedElementIds : [],
-    locale: op.locale ?? null,
-    note: op.note ?? null,
-    requiresAgentTool: 'codex_app.send_message_to_thread',
-    supportsForegroundMessage: true,
-  });
-  return {
-    ...base,
-    ...summarizeAgentBridgeOperation(bridgeOp),
-    status: 'pending',
-    supportsForegroundMessage: true,
-  };
-}
-
-async function listCodexAgentBridgeOutbox(session, options = {}) {
-  const includeAll = Boolean(options.all);
-  const ops = await readOps(session.paths);
-  const items = ops.ops
-    .filter((op) => op.type === 'agent-foreground-relay')
-    .filter((op) => includeAll || ['pending', 'claimed'].includes(op.status ?? 'pending'))
-    .map(summarizeAgentBridgeOperation)
-    .filter(Boolean);
-  return items;
-}
-
-async function claimCodexAgentBridgeItem(session, claim = 'next') {
-  const items = await listCodexAgentBridgeOutbox(session);
-  const value = String(claim || 'next');
-  const item = value === 'next'
-    ? items.find((candidate) => candidate.status === 'pending')
-    : items.find((candidate) => candidate.id === value);
-  if (!item) {
-    return null;
-  }
-  const updated = await updateOperation(session.paths, item.id, {
-    status: 'claimed',
-    claimedAt: timestamp(),
-  });
-  await appendOperation(session.paths, {
-    type: 'agent-foreground-relay-status',
-    bridgeOperationId: item.id,
-    status: 'claimed',
-  });
-  return summarizeAgentBridgeOperation(updated);
-}
-
-async function markCodexAgentBridgeItem(session, id, status, options = {}) {
-  if (!id) {
-    const error = new Error('Expected --id for canvas bridge status update.');
-    error.statusCode = 400;
-    throw error;
-  }
-  const normalizedStatus = status === 'failed' ? 'failed' : 'sent';
-  const timestampField = normalizedStatus === 'failed' ? 'failedAt' : 'sentAt';
-  const updated = await updateOperation(session.paths, id, {
-    status: normalizedStatus,
-    [timestampField]: timestamp(),
-    reason: options.reason ?? null,
-    sentThreadId: options.threadId ?? session.binding?.id ?? null,
-  });
-  await appendOperation(session.paths, {
-    type: 'agent-foreground-relay-status',
-    bridgeOperationId: id,
-    status: normalizedStatus,
-    reason: options.reason ?? null,
-    threadId: options.threadId ?? session.binding?.id ?? null,
-  });
-  return summarizeAgentBridgeOperation(updated);
-}
-
-async function queueCodexThreadRelay(session, op, options = {}, env = process.env) {
-  const skipReason = codexRelaySkipReason(session, op, options, env);
-  const input = buildCodexRelayInput(session, op);
-  const supportsDirectAttachment = input.some((item) => item.type === 'localImage');
-  const base = {
-    target: op.target ?? 'codex',
-    transport: CODEX_DELEGATION_RELAY_TRANSPORT,
-    supportsDirectMessage: !skipReason,
-    supportsDirectAttachment: !skipReason && supportsDirectAttachment,
-    inputTypes: input.map((item) => item.type),
-    promptText: op.promptText,
-    delivered: false,
-    pending: false,
-    accepted: false,
-  };
-  if (skipReason) {
-    return {
-      ...base,
-      status: 'skipped',
-      reason: skipReason,
-      supportsDirectMessage: false,
-      supportsDirectAttachment: false,
-    };
-  }
-
-  await fs.mkdir(session.paths.relaysDir, { recursive: true });
-  const relayName = sanitizeSessionSegment(op.id || `handoff-${Date.now()}`, 'handoff');
-  const payloadPath = cjoin(session.paths.relaysDir, `${relayName}.payload.json`);
-  const statusPath = cjoin(session.paths.relaysDir, `${relayName}.status.json`);
-  const logPath = cjoin(session.paths.relaysDir, `${relayName}.log`);
-  const payload = {
-    schema: 'openprd.codex.app-server-relay.v1',
-    createdAt: timestamp(),
-    handoffOperationId: op.id,
-    threadId: session.binding.id,
-    threadTitle: session.binding.title || session.binding.threadTitle || null,
-    cwd: session.projectRoot,
-    input,
-    payloadPath,
-    statusPath,
-    logPath,
-    codexBin: await resolveCodexAppServerBin(env),
-    timeoutMs: relayTimeoutMs(env),
-  };
-  await writeJson(payloadPath, payload);
-  await writeJson(statusPath, {
-    schema: 'openprd.codex.app-server-relay.status.v1',
-    status: 'queued',
-    createdAt: payload.createdAt,
-    updatedAt: timestamp(),
-    handoffOperationId: op.id,
-    threadId: session.binding.id,
-  });
-
-  if (options.relayDryRun || env.OPENPRD_CANVAS_CODEX_RELAY_DRY_RUN === '1') {
-    return {
-      ...base,
-      ...relayStatusSummary({ status: 'queued' }),
-      status: 'queued',
-      dryRun: true,
-      payloadPath,
-      statusPath,
-      logPath,
-    };
-  }
-
-  const child = spawn(process.execPath, [CODEX_APP_SERVER_RELAY_WORKER_PATH, payloadPath], {
-    cwd: session.projectRoot,
-    detached: true,
-    stdio: 'ignore',
-  });
-  child.unref();
-  const waitedStatus = await waitForCodexRelayStart(statusPath, relayStartWaitMs(options, env));
-  const statusSummary = relayStatusSummary(waitedStatus || { status: 'queued' });
-  return {
-    ...base,
-    status: statusSummary.status ?? 'queued',
-    payloadPath,
-    statusPath,
-    logPath,
-    pid: child.pid ?? null,
-    ...statusSummary,
-  };
-}
-
-async function materializeImage(session, input) {
-  const paths = session.paths;
-  let buffer = null;
-  let mimeType = null;
-  let sourcePath = null;
-  let sourceUrl = null;
-  let extension = '.png';
-
-  if (input.dataUrl) {
-    const parsed = dataUrlToBuffer(input.dataUrl);
-    buffer = parsed.buffer;
-    mimeType = parsed.mimeType;
-    extension = extensionFromMime(mimeType, '.png');
-  } else if (input.path) {
-    sourcePath = path.isAbsolute(input.path) ? input.path : path.resolve(session.projectRoot, input.path);
-    buffer = await fs.readFile(sourcePath);
-    extension = path.extname(sourcePath) || '.png';
-    mimeType = mimeFromPath(sourcePath);
-  } else if (input.url) {
-    sourceUrl = input.url;
-    const response = await fetch(input.url);
-    if (!response.ok) {
-      throw new Error(`Unable to fetch image URL: ${response.status} ${response.statusText}`);
-    }
-    buffer = Buffer.from(await response.arrayBuffer());
-    mimeType = response.headers.get('content-type') ?? 'application/octet-stream';
-    extension = extensionFromMime(mimeType, path.extname(decodeURIComponent(new URL(input.url).pathname)) || '.png');
-  } else {
-    throw new Error('Expected one of: dataUrl, path, url.');
-  }
-
-  const safeExt = extension.startsWith('.') ? extension : `.${extension}`;
-  const digest = shortHash(buffer);
-  const fileName = `image-${Date.now()}-${digest}${safeExt.toLowerCase()}`;
-  const assetPath = cjoin(paths.assetsDir, fileName);
-  await fs.writeFile(assetPath, buffer);
-  return {
-    fileName,
-    assetPath,
-    assetUrl: `/assets/${encodeURIComponent(fileName)}`,
-    mimeType,
-    sourcePath,
-    sourceUrl,
-    digest,
-  };
-}
-
 async function materializeExport(session, input) {
   if (!input.dataUrl) {
     throw new Error('Expected dataUrl for export.');
@@ -1494,6 +468,22 @@ async function handleCanvasRequest(session, req, res) {
     return;
   }
 
+  if (req.method === 'GET' && pathname === '/api/selection') {
+    const scene = normalizeCanvasScene(await readJson(session.paths.sceneFile).catch(() => null));
+    jsonResponse(res, 200, buildCanvasSelectionPayload(scene));
+    return;
+  }
+
+  if (req.method === 'POST' && pathname === '/api/insert-image') {
+    const body = await readRequestJson(req);
+    const inserted = await insertAnchoredCanvasImage(session, body);
+    jsonResponse(res, 200, {
+      ok: true,
+      ...inserted,
+    });
+    return;
+  }
+
   if (req.method === 'GET' && pathname === '/api/ops') {
     const after = Number(url.searchParams.get('after') ?? -1);
     const ops = await readOps(session.paths);
@@ -1697,6 +687,9 @@ async function handleCanvasRequest(session, req, res) {
       mode: body.mode ?? null,
       elementCount: Number.isFinite(Number(body.elementCount)) ? Number(body.elementCount) : null,
       selectedElementIds: normalizeStringArray(body.selectedElementIds),
+      sourceImageElementIds: normalizeStringArray(body.sourceImageElementIds),
+      annotationElementIds: normalizeStringArray(body.annotationElementIds),
+      sizeContract: normalizeCanvasSizeContract(body.sizeContract),
       locale: body.locale ?? null,
       binding: {
         kind: session.binding?.kind ?? null,