@bbigbang/core 0.1.0

package/dist/web/panelRoutes.js

@@ -0,0 +1,2147 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getComponentContract, getEffectiveDatasetSchema, normalizePanelApiJsonlAllowedOrigins, normalizePanelApiJsonlAllowedUrlPrefixes, normalizePanelApiJsonlAuthProfileNames, walkPanelTemplateNodes, } from '@bbigbang/protocol';
+import { validateSession, getUserAgentAccess, getUserChannelAccess } from '../services/auth.js';
+import { buildCanonicalAssetStoragePath, sanitizeAssetFilename, } from './assets.js';
+import { resolveDirectUserIdFromReplyTarget } from './directReplyTargets.js';
+import { getPanelById, getPanelRowByIndex, getPanelState, getSharedPanelState, aggregatePanelRows, listPanelRows, loadAttachmentRow, updatePanelRowCachedAssetIdIfCurrent, upsertPanelState, validateStateBlob, applySharedSelectionPatch, normalizePanelSelectionForRowCount, normalizePanelStateSelectionForRowCount, } from './panels.js';
+import { deletePanelAttachmentArtifacts, hardDeletePanelWithArtifacts, } from './panelLifecycle.js';
+import { deleteExpiredPanelPreviews, getPanelPreviewById, getPanelPreviewRowByIndex, isPanelPreviewExpired, listPanelPreviewRows, } from './panelPreviews.js';
+import { WorkspaceToolServiceError, getWorkspaceToolMediaRelativePathCandidates, } from '../services/workspaceToolService.js';
+import { insertPanelAuditEvent, listPanelAuditEvents, } from './panelAudit.js';
+import { ActionCardError, cancelActionCard, confirmActionCard, getActionCardById, } from './actionCards.js';
+import { aggregatePanelQueryHandleRows, isPanelQueryHandleSource, listPanelQueryHandleRows, listPanelQueryHandleRowsByIndices, PanelQueryHandleError, } from './panelQueryHandles.js';
+import { ensureSurfaceOwner, getSurfaceCollaboratorRole, listSurfaceCollaborators, removeSurfaceCollaborator, upsertSurfaceCollaborator, } from './surfaceCollaborators.js';
+import { buildPanelActionActivationPrompt, buildPanelActionActivationContextSections, } from './panelActivationPrompt.js';
+import { insertPanelActionMessage, insertPanelPlatformExecMessage } from './panelActionMessages.js';
+import { resolvePanelMediaPath } from './panelPathPolicy.js';
+import { panelMediaDefaultFilename, panelMediaDisplayTypeLimitBytes, panelMediaMimeMatchesDisplayType, panelMediaSizeCapExceededError, } from './panelMediaPolicy.js';
+import { isPlatformAgent } from '../services/suggestedPlannerService.js';
+function getRequestUser(req, db) {
+    const authHeader = typeof req.headers.authorization === 'string' ? req.headers.authorization : '';
+    const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7).trim() : '';
+    return token ? validateSession(db, token) : null;
+}
+function requireUser(req, reply, db) {
+    const user = getRequestUser(req, db);
+    if (!user) {
+        reply.code(401);
+        return null;
+    }
+    return user;
+}
+function requireAdmin(req, reply, db) {
+    const user = requireUser(req, reply, db);
+    if (!user)
+        return null;
+    if (!user.isAdmin) {
+        reply.code(403);
+        return null;
+    }
+    return user;
+}
+function getDeclaredPanelMediaDisplayType(panel, slotName) {
+    const mediaSlots = panel.props?.mediaSlots;
+    if (!Array.isArray(mediaSlots))
+        return undefined;
+    const slot = mediaSlots.find((candidate) => (candidate
+        && typeof candidate === 'object'
+        && 'name' in candidate
+        && candidate.name === slotName));
+    if (slot?.displayType === 'text' || slot?.displayType === 'latex')
+        return slot.displayType;
+    if (slot?.displayType === 'img')
+        return 'img';
+    return undefined;
+}
+function getWorkspaceToolManifestMediaDisplayType(tool, slotName) {
+    return tool.manifest.view.mediaSlots?.find((slot) => slot.name === slotName)?.displayType;
+}
+function loadNodeRuntimeCapabilities(db, nodeId) {
+    const normalizedNodeId = nodeId?.trim();
+    if (!normalizedNodeId)
+        return null;
+    const row = db.prepare(`SELECT capabilities_json as capabilitiesJson
+       FROM node_runtime_snapshots
+      WHERE node_id = ?
+      LIMIT 1`).get(normalizedNodeId);
+    if (!row?.capabilitiesJson)
+        return null;
+    try {
+        const parsed = JSON.parse(row.capabilitiesJson);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function loadPanelApiJsonlAllowedOrigins(db, conversationManager, panelAgentId) {
+    const agent = conversationManager.getAgent(panelAgentId);
+    const capabilities = loadNodeRuntimeCapabilities(db, agent?.nodeId);
+    return normalizePanelApiJsonlAllowedOrigins(capabilities?.panelApiJsonlAllowedOrigins);
+}
+function loadPanelApiJsonlAllowedUrlPrefixes(db, conversationManager, panelAgentId) {
+    const agent = conversationManager.getAgent(panelAgentId);
+    const capabilities = loadNodeRuntimeCapabilities(db, agent?.nodeId);
+    return normalizePanelApiJsonlAllowedUrlPrefixes(capabilities?.panelApiJsonlAllowedUrlPrefixes);
+}
+function loadPanelApiJsonlAuthProfiles(db, conversationManager, panelAgentId) {
+    const agent = conversationManager.getAgent(panelAgentId);
+    const capabilities = loadNodeRuntimeCapabilities(db, agent?.nodeId);
+    return normalizePanelApiJsonlAuthProfileNames(capabilities?.panelApiJsonlAuthProfiles);
+}
+function isWorkspaceToolVisibilityError(error) {
+    return error instanceof WorkspaceToolServiceError
+        && (error.statusCode === 403 || error.statusCode === 404);
+}
+function asToolPanelLookupError(error) {
+    if (error instanceof WorkspaceToolServiceError) {
+        const serverError = new Error(error.message);
+        serverError.cause = error;
+        return serverError;
+    }
+    return error;
+}
+function panelMediaCacheControl(scopeType) {
+    if (scopeType === 'tool') {
+        return 'private, no-cache, max-age=0, must-revalidate';
+    }
+    return 'private, max-age=31536000, immutable';
+}
+function uncachedPanelMediaCacheControl() {
+    return 'private, no-cache, max-age=0, must-revalidate';
+}
+function canAccessConversation(user, conversationId, conversationManager, db) {
+    if (user.isAdmin)
+        return true;
+    const conv = conversationManager.getConversation(conversationId);
+    if (!conv)
+        return false;
+    if (conv.threadKind === 'direct')
+        return conv.userId === user.id;
+    return getUserChannelAccess(db, user.id).includes(conv.channelId);
+}
+function canUserActOnActionCardPanel(db, user, actionCardId) {
+    const card = getActionCardById(db, actionCardId);
+    if (!card)
+        return false;
+    if (user.isAdmin)
+        return true;
+    if (card.actionType !== 'channel:add_member' || !card.originChannelId)
+        return false;
+    const targetChannelId = typeof card.payload.channelId === 'string' ? card.payload.channelId.trim() : '';
+    if (!targetChannelId)
+        return false;
+    const allowedChannels = new Set(getUserChannelAccess(db, user.id));
+    return allowedChannels.has(card.originChannelId) && allowedChannels.has(targetChannelId);
+}
+function requireConversationAccess(req, reply, conversationId, db, conversationManager) {
+    const user = requireUser(req, reply, db);
+    if (!user)
+        return null;
+    if (!canAccessConversation(user, conversationId, conversationManager, db)) {
+        reply.code(403);
+        return null;
+    }
+    return user;
+}
+function parseFilter(raw) {
+    if (!raw)
+        return null;
+    const eqIdx = raw.indexOf('=');
+    if (eqIdx <= 0)
+        return null;
+    const field = raw.slice(0, eqIdx).trim();
+    const value = raw.slice(eqIdx + 1);
+    if (!field)
+        return null;
+    return { field, value };
+}
+function parseSort(raw) {
+    if (!raw)
+        return null;
+    const colonIdx = raw.lastIndexOf(':');
+    if (colonIdx <= 0)
+        return null;
+    const field = raw.slice(0, colonIdx).trim();
+    const direction = raw.slice(colonIdx + 1).trim().toLowerCase();
+    if (!field)
+        return null;
+    if (direction !== 'asc' && direction !== 'desc')
+        return null;
+    return { field, direction };
+}
+function parsePanelAggregateOp(raw) {
+    if (raw === 'count' || raw === 'sum' || raw === 'avg' || raw === 'min' || raw === 'max')
+        return raw;
+    return null;
+}
+function resolvePanelOwnerUserId(db, panel, conversationManager) {
+    const explicitOwner = panel.ownerUserId?.trim();
+    if (explicitOwner)
+        return explicitOwner;
+    const conversation = conversationManager.getConversation(panel.conversationId);
+    const directConversationUserId = conversation?.userId?.trim();
+    if (directConversationUserId)
+        return directConversationUserId;
+    if (panel.scopeType === 'direct') {
+        const replyTarget = conversation?.replyTarget ?? null;
+        return resolveDirectUserIdFromReplyTarget(db, replyTarget);
+    }
+    return null;
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function resolvePanelActionCommand(action) {
+    const command = action.command?.trim() || action.rpcCommand?.trim() || '';
+    return command || null;
+}
+function resolvePanelActionDeclaredCwd(action) {
+    return action.cwd?.trim() || action.rpcCwd?.trim() || undefined;
+}
+const PANEL_RPC_TIMEOUT_MS = 30_000;
+const PANEL_RPC_POLL_INTERVAL_MS = 150;
+const FORM_FIELD_KEY_PATTERN = /^([0-9]+):([A-Za-z_][A-Za-z0-9_:-]{0,63})$/;
+const PARAMETER_FIELD_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_:-]{0,63}$/;
+function validatePanelSubmitForm(form, changedRowIndices) {
+    if (form === undefined) {
+        if (changedRowIndices !== undefined && (!Array.isArray(changedRowIndices) || changedRowIndices.length > 0)) {
+            return { ok: false, error: 'changedRowIndices requires row-scoped form field keys' };
+        }
+        return { ok: true, form: {}, changedRowIndices: [] };
+    }
+    if (!isPlainRecord(form)) {
+        return { ok: false, error: 'form must be an object' };
+    }
+    const rowIndices = new Set();
+    for (const key of Object.keys(form)) {
+        const match = FORM_FIELD_KEY_PATTERN.exec(key);
+        if (match) {
+            rowIndices.add(Number(match[1]));
+            continue;
+        }
+        if (!PARAMETER_FIELD_KEY_PATTERN.test(key)) {
+            return { ok: false, error: `Invalid form field key: ${key}` };
+        }
+    }
+    const derived = Array.from(rowIndices).sort((a, b) => a - b);
+    if (changedRowIndices !== undefined) {
+        if (!Array.isArray(changedRowIndices)) {
+            return { ok: false, error: 'changedRowIndices must be an array' };
+        }
+        const normalized = Array.from(new Set(changedRowIndices.filter((value) => Number.isInteger(value) && value >= 0))).sort((a, b) => a - b);
+        if (normalized.length !== changedRowIndices.length) {
+            return { ok: false, error: 'changedRowIndices must contain non-negative integers' };
+        }
+        if (normalized.length !== derived.length || normalized.some((value, index) => value !== derived[index])) {
+            return { ok: false, error: 'changedRowIndices must match rows referenced by row-scoped form keys' };
+        }
+    }
+    return { ok: true, form, changedRowIndices: derived };
+}
+function panelRowIdsForIndices(db, panelId, rowIndices) {
+    if (rowIndices.length === 0)
+        return [];
+    const rowIds = [];
+    for (const rowIndex of rowIndices) {
+        const rowId = getPanelRowByIndex(db, panelId, rowIndex)?.rowId?.trim();
+        if (!rowId)
+            return null;
+        rowIds.push(rowId);
+    }
+    return rowIds;
+}
+function isPanelAnnotationBox(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const box = value;
+    return ['x', 'y', 'w', 'h'].every((key) => typeof box[key] === 'number' && Number.isFinite(box[key]));
+}
+function isPanelAnnotation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.label === 'string' && record.label.trim().length > 0 && isPanelAnnotationBox(record.box);
+}
+function containsPanelAnnotations(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.length > 0 && value.every(isPanelAnnotation);
+}
+function collectAnnotationFields(panel) {
+    if (panel.component !== 'RowTemplateGrid')
+        return new Set();
+    const template = panel.props?.template;
+    const fields = new Set();
+    walkPanelTemplateNodes(template, (node) => {
+        if (node.type === 'ImageSlot' && node.editable === true && typeof node.annotationsField === 'string') {
+            fields.add(node.annotationsField);
+        }
+    });
+    return fields;
+}
+function isAnnotationFormKey(key, annotationFields) {
+    const separatorIndex = key.indexOf(':');
+    if (separatorIndex <= 0)
+        return false;
+    return annotationFields.has(key.slice(separatorIndex + 1));
+}
+function normalizeStoredSelectionForPanel(panel, selection) {
+    return normalizePanelSelectionForRowCount(panel.rowCount, selection);
+}
+function normalizeStateSelectionForPanel(panel, state) {
+    return normalizePanelStateSelectionForRowCount(panel.rowCount, state);
+}
+function validateSelectionIndices(panel, selection) {
+    const seen = new Set();
+    for (const value of selection) {
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || seen.has(value)) {
+            return { ok: false, error: 'selection must contain unique non-negative row indices' };
+        }
+        seen.add(value);
+    }
+    const normalized = Array.from(seen).sort((a, b) => a - b);
+    if (normalized.length !== selection.length) {
+        return { ok: false, error: 'selection must contain unique non-negative row indices' };
+    }
+    const bounded = normalizeStoredSelectionForPanel(panel, normalized);
+    if (bounded.length !== normalized.length) {
+        return { ok: false, error: 'selection references row indices outside the panel row range' };
+    }
+    return { ok: true, selection: bounded };
+}
+export function registerPanelRoutes(app, db, conversationManager, workspaceBroker, workspaceToolService, terminalBroker, assetStoreRoot, broadcastToChannel, broadcast) {
+    const resolvePanelActionMode = (action) => action.mode ?? (resolvePanelActionCommand(action) ? 'platform_exec' : 'notify_agent');
+    const sanitizePanelActionsForClient = (actions) => (actions ?? []).map((action) => ({
+        id: action.id,
+        label: action.label,
+        mode: resolvePanelActionMode(action),
+        ...(action.variant ? { variant: action.variant } : {}),
+        ...(action.description ? { description: action.description } : {}),
+    }));
+    const emitPanelDeleted = (panel) => {
+        const event = {
+            type: 'panel.deleted',
+            panelId: panel.id,
+            deletedAt: Date.now(),
+        };
+        const conv = conversationManager.getConversation(panel.conversationId);
+        if (panel.scopeType === 'direct' && broadcast) {
+            broadcast(panel.conversationId, event);
+            return;
+        }
+        if (panel.scopeType === 'tool') {
+            return;
+        }
+        if (conv?.channelId && broadcastToChannel) {
+            if (panel.scopeType === 'thread' && conv.threadRootId) {
+                event.threadRootId = conv.threadRootId;
+            }
+            broadcastToChannel(conv.channelId, event);
+        }
+    };
+    const canDeletePanelForUser = (user, panel) => {
+        if (panel.scopeType === 'tool')
+            return false;
+        if (user.isAdmin)
+            return true;
+        return resolvePanelOwnerUserId(db, panel, conversationManager) === user.id;
+    };
+    const ensurePanelSurfaceOwner = (panel) => {
+        const createdAt = typeof panel.createdAt === 'number'
+            ? panel.createdAt
+            : typeof panel.createdAt === 'string'
+                ? Date.parse(panel.createdAt)
+                : undefined;
+        ensureSurfaceOwner(db, {
+            surfaceType: 'panel',
+            surfaceId: panel.id,
+            agentId: panel.agentId,
+            createdAt: Number.isFinite(createdAt) ? createdAt : undefined,
+        });
+    };
+    const canManagePanelCollaboratorsForUser = (user, panel) => {
+        if (panel.scopeType === 'tool')
+            return false;
+        if (panel.archivedAt)
+            return false;
+        return canDeletePanelForUser(user, panel);
+    };
+    const formatPanelCollaboratorsForUser = (user, panel) => {
+        ensurePanelSurfaceOwner(panel);
+        return {
+            panelId: panel.id,
+            canManage: canManagePanelCollaboratorsForUser(user, panel),
+            collaborators: listSurfaceCollaborators(db, 'panel', panel.id).map((row) => {
+                const agent = conversationManager.getAgent(row.agentId);
+                return {
+                    agentId: row.agentId,
+                    name: agent?.name ?? null,
+                    role: row.role,
+                    addedBy: row.addedBy ?? null,
+                    createdAt: new Date(row.createdAt).toISOString(),
+                };
+            }),
+        };
+    };
+    const canAccessPanel = async (user, panel) => {
+        if (panel.scopeType === 'tool') {
+            try {
+                await resolveToolProjectionForViewer(user, panel.id);
+                return true;
+            }
+            catch (error) {
+                if (!isWorkspaceToolVisibilityError(error)) {
+                    throw error;
+                }
+                return false;
+            }
+        }
+        return canAccessConversation(user, panel.conversationId, conversationManager, db);
+    };
+    const resolveToolProjectionForViewer = async (user, panelId) => {
+        try {
+            return await workspaceToolService.getToolForViewerByPanelId(user.id, panelId);
+        }
+        catch (error) {
+            if (!isWorkspaceToolVisibilityError(error)) {
+                throw asToolPanelLookupError(error);
+            }
+            throw error;
+        }
+    };
+    const getPanelSurfaceContractForViewer = async (user, panel) => {
+        if (panel.scopeType !== 'tool') {
+            return {
+                scopeId: null,
+                surfaceProfile: 'panel',
+                surfaceFeatures: { browseControls: true },
+            };
+        }
+        const surface = workspaceToolService.getToolSurfaceMetadataForViewer(user.id, panel.id);
+        return {
+            scopeId: panel.id,
+            surfaceProfile: surface.surfaceProfile,
+            surfaceFeatures: surface.surfaceFeatures,
+        };
+    };
+    const canViewerSeeToolMaintenanceConversationId = (user, panel) => {
+        const panelOwnerUserId = resolvePanelOwnerUserId(db, panel, conversationManager);
+        return user.isAdmin || panelOwnerUserId === user.id;
+    };
+    const canRunPanelPlatformExec = (user, panel) => {
+        const conversation = conversationManager.getConversation(panel.conversationId);
+        if (!conversation) {
+            return { ok: false, statusCode: 409, error: 'Panel conversation is unavailable' };
+        }
+        if (panel.scopeType === 'direct') {
+            if (conversation.threadKind !== 'direct') {
+                return { ok: false, statusCode: 409, error: 'Direct panel platform_exec actions require a direct conversation' };
+            }
+            const directUserId = conversation.userId?.trim()
+                || resolveDirectUserIdFromReplyTarget(db, conversation.replyTarget ?? null);
+            if (!directUserId) {
+                return { ok: false, statusCode: 409, error: 'Direct panel platform_exec actions require a user-bound direct panel' };
+            }
+            return user.isAdmin || directUserId === user.id
+                ? { ok: true }
+                : { ok: false, statusCode: 403, error: 'Access denied' };
+        }
+        if (panel.scopeType === 'channel' || panel.scopeType === 'thread') {
+            if (!conversation.channelId) {
+                return { ok: false, statusCode: 409, error: 'Panel channel is unavailable' };
+            }
+            return user.isAdmin || getUserChannelAccess(db, user.id).includes(conversation.channelId)
+                ? { ok: true }
+                : { ok: false, statusCode: 403, error: 'Access denied' };
+        }
+        return { ok: false, statusCode: 409, error: 'Tool-scoped panel actions must be delegated to the workspace tool' };
+    };
+    const emitPanelActionTriggered = (panelId, conversationId, scopeType, userId, submitKind, actionId) => {
+        const conv = conversationManager.getConversation(conversationId);
+        if (!conv)
+            return;
+        const actionEvent = {
+            type: 'panel.action_triggered',
+            panelId,
+            submitKind,
+            ...(actionId ? { actionId } : undefined),
+            triggeredByUserId: userId,
+            triggeredAt: Date.now(),
+        };
+        if (scopeType === 'direct' && broadcast) {
+            broadcast(conversationId, actionEvent);
+            return;
+        }
+        if (scopeType === 'tool') {
+            return;
+        }
+        if (conv.channelId && broadcastToChannel) {
+            if (scopeType === 'thread' && conv.threadRootId) {
+                actionEvent.threadRootId = conv.threadRootId;
+            }
+            broadcastToChannel(conv.channelId, actionEvent);
+        }
+    };
+    const resolvePanelActionExecutionCwd = (workspaceRoot, actionCwd) => {
+        if (!actionCwd)
+            return { ok: true, cwd: workspaceRoot };
+        if (path.isAbsolute(actionCwd)) {
+            return { ok: false, error: 'action cwd must be relative to the agent workspace root' };
+        }
+        const resolved = path.resolve(workspaceRoot, actionCwd);
+        const relative = path.relative(workspaceRoot, resolved);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            return { ok: false, error: 'action cwd must stay inside the agent workspace root' };
+        }
+        return { ok: true, cwd: resolved };
+    };
+    const waitForPanelActionTerminalExit = async (nodeId, terminalId) => {
+        const deadline = Date.now() + PANEL_RPC_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            const snapshot = await terminalBroker.snapshotTerminal(nodeId, terminalId);
+            if (snapshot.terminal.exited)
+                return snapshot;
+            await new Promise((resolve) => setTimeout(resolve, PANEL_RPC_POLL_INTERVAL_MS));
+        }
+        throw new Error('Timed out waiting for panel RPC action to finish.');
+    };
+    const submitPanel = async (params) => {
+        const panel = getPanelById(db, params.panelId);
+        if (!panel) {
+            params.reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (panel.archivedAt) {
+            params.reply.code(409);
+            return { error: 'Panel is archived' };
+        }
+        if (!(await canAccessPanel(params.user, panel))) {
+            params.reply.code(403);
+            return { error: 'Access denied' };
+        }
+        if (panel.scopeType === 'tool') {
+            params.reply.code(409);
+            return { error: 'Tool snapshot panels do not accept panel submits' };
+        }
+        const action = params.submitKind === 'action'
+            ? (panel.actions ?? []).find((a) => a.id === params.actionId)
+            : undefined;
+        if (params.submitKind === 'action' && !action) {
+            params.reply.code(400);
+            return { error: 'Action not declared for this panel' };
+        }
+        if (params.submitKind !== 'action' && params.actionId !== undefined) {
+            params.reply.code(400);
+            return { error: 'actionId is only valid for action submits' };
+        }
+        const conv = conversationManager.getConversation(panel.conversationId);
+        if (!conv) {
+            params.reply.code(404);
+            return { error: 'Conversation not found' };
+        }
+        if (panel.scopeType !== 'direct' && !conv.channelId) {
+            params.reply.code(400);
+            return { error: 'Panel conversation is missing channel scope' };
+        }
+        if (panel.scopeType === 'thread' && !conv.threadRootId) {
+            params.reply.code(400);
+            return { error: 'Panel conversation is missing thread scope' };
+        }
+        const scope = panel.scopeType === 'direct'
+            ? { type: 'direct', conversationId: panel.conversationId }
+            : panel.scopeType === 'thread'
+                ? {
+                    type: 'thread',
+                    conversationId: panel.conversationId,
+                    channelId: conv.channelId,
+                    threadRootId: conv.threadRootId,
+                }
+                : {
+                    type: 'channel',
+                    conversationId: panel.conversationId,
+                    channelId: conv.channelId,
+                };
+        const perUserState = getPanelState(db, panel.id, params.user.id);
+        const filters = perUserState?.state?.filters ?? {};
+        const sort = perUserState?.state?.sort ?? {};
+        let selection;
+        let latestVersion;
+        if (panel.scopeType !== 'direct') {
+            const sharedState = getSharedPanelState(db, panel.id);
+            selection = normalizeStoredSelectionForPanel(panel, sharedState?.state?.selection);
+            latestVersion = sharedState?.version ?? 0;
+        }
+        else {
+            selection = normalizeStoredSelectionForPanel(panel, perUserState?.state?.selection);
+            latestVersion = panel.version;
+        }
+        const validatedForm = validatePanelSubmitForm(params.form, params.changedRowIndices);
+        if (!validatedForm.ok) {
+            params.reply.code(400);
+            return { error: validatedForm.error };
+        }
+        const changedRowIndices = validatedForm.changedRowIndices;
+        const form = validatedForm.form;
+        if (changedRowIndices.some((rowIndex) => !getPanelRowByIndex(db, panel.id, rowIndex))) {
+            params.reply.code(400);
+            return { error: 'form references unknown row index' };
+        }
+        const submittedBaseVersion = Number.isFinite(params.baseVersion)
+            ? Number(params.baseVersion)
+            : latestVersion;
+        const previewLimit = 5;
+        const previewSource = changedRowIndices.length > 0 ? changedRowIndices : selection;
+        const selectedRowIds = panelRowIdsForIndices(db, panel.id, selection);
+        const changedRowIds = panelRowIdsForIndices(db, panel.id, changedRowIndices);
+        const previewRows = previewSource
+            .slice(0, previewLimit)
+            .map((rowIndex) => getPanelRowByIndex(db, panel.id, rowIndex))
+            .filter((row) => Boolean(row))
+            .map((row) => ({
+            rowIndex: row.rowIndex,
+            fields: row.fields,
+        }));
+        const formDelta = Object.fromEntries(Object.entries(form).map(([key, value]) => [key, { to: value }]));
+        const basePayload = {
+            panelId: panel.id,
+            actor: {
+                userId: params.user.id,
+                username: params.user.username ?? 'User',
+            },
+            scope,
+            baseVersion: submittedBaseVersion,
+            submittedVersion: latestVersion,
+            ...(submittedBaseVersion < latestVersion
+                ? { concurrency: { staleBase: true, latestVersion } }
+                : undefined),
+            viewState: {
+                filters,
+                sort,
+            },
+            refs: {
+                selectedRowIndices: selection,
+                ...(selectedRowIds && selectedRowIds.length > 0 ? { selectedRowIds } : undefined),
+                ...(changedRowIndices.length > 0 ? { changedRowIndices } : undefined),
+                ...(changedRowIds && changedRowIds.length > 0 ? { changedRowIds } : undefined),
+            },
+            delta: {
+                ...(panel.scopeType !== 'direct' ? { shared: { selection } } : undefined),
+                perUser: { filters, sort },
+                ...(Object.keys(formDelta).length > 0 ? { form: formDelta } : undefined),
+            },
+            summary: {
+                selectedCount: selection.length,
+                ...(Object.keys(formDelta).length > 0 ? { changedFieldCount: Object.keys(formDelta).length } : undefined),
+                truncated: previewSource.length > previewRows.length,
+            },
+            preview: {
+                rows: previewRows,
+            },
+            metadata: {
+                ...(params.metadata ?? {}),
+                ...(action
+                    ? {
+                        action: {
+                            id: action.id,
+                            label: action.label,
+                            ...(action.variant ? { variant: action.variant } : {}),
+                            ...(action.description ? { description: action.description } : {}),
+                        },
+                    }
+                    : undefined),
+                component: panel.component,
+            },
+        };
+        const payload = params.submitKind === 'action'
+            ? {
+                ...basePayload,
+                submitKind: 'action',
+                actionId: action.id,
+            }
+            : {
+                ...basePayload,
+                submitKind: params.submitKind,
+            };
+        const prompt = buildPanelActionActivationPrompt({ payload });
+        const activationContextSections = buildPanelActionActivationContextSections({ payload });
+        const auditChannelId = conv.threadKind === 'direct' ? `dm:${panel.agentId}` : conv.channelId;
+        const submitLabel = action?.label ?? params.metadata?.label ?? params.submitKind;
+        insertPanelActionMessage(db, {
+            channelId: auditChannelId,
+            target: conv.replyTarget ?? `dm:${panel.agentId}`,
+            actionLabel: submitLabel,
+            payload,
+            threadRootId: conv.threadRootId ?? null,
+        });
+        const result = await conversationManager.submitPrompt(panel.conversationId, prompt, {
+            recordAsUserMessage: false,
+            activationContextSections,
+        });
+        emitPanelActionTriggered(panel.id, panel.conversationId, panel.scopeType, params.user.id, params.submitKind, action?.id);
+        insertPanelAuditEvent(db, {
+            panelId: panel.id,
+            eventType: params.submitKind === 'action' ? 'actioned' : 'submitted',
+            version: panel.version,
+            submitKind: params.submitKind,
+            actionId: params.actionId ?? undefined,
+            actorType: 'user',
+            actorId: params.user.id,
+            runId: result.runId ?? null,
+            conversationId: panel.conversationId,
+            scopeType: panel.scopeType,
+            scopeId: panel.scopeId ?? null,
+            metadata: params.submitKind === 'action'
+                ? { actionId: params.actionId, actionMode: 'notify_agent' }
+                : {
+                    baseVersion: submittedBaseVersion,
+                    submittedVersion: latestVersion,
+                    selectedCount: selection.length,
+                    ...(selection.length > 0 ? { selectedRowIndices: selection } : undefined),
+                    ...(selectedRowIds && selectedRowIds.length > 0 ? { selectedRowIds } : undefined),
+                    ...(changedRowIndices.length > 0 ? { changedRowIndices } : undefined),
+                    ...(changedRowIds && changedRowIds.length > 0 ? { changedRowIds } : undefined),
+                    ...(Object.keys(formDelta).length > 0 ? { changedFieldCount: Object.keys(formDelta).length } : {}),
+                },
+        });
+        return { ok: true, queued: result.queued, runId: result.runId };
+    };
+    app.get('/api/panel-previews/:id', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const preview = getPanelPreviewById(db, req.params.id);
+        if (!preview) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (isPanelPreviewExpired(preview)) {
+            deleteExpiredPanelPreviews(db);
+            reply.code(410);
+            return { error: 'Panel preview expired' };
+        }
+        if (!canAccessConversation(user, preview.conversationId, conversationManager, db)) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        return {
+            id: preview.id,
+            component: preview.component,
+            props: preview.props ?? {},
+            actions: [],
+            rowCount: preview.rowCount ?? 0,
+            rowCountKnown: preview.rowCountKnown ?? true,
+            datasetSource: preview.datasetSource,
+            status: preview.status,
+            progress: null,
+            result: null,
+            scopeType: 'preview',
+            scopeId: preview.conversationId,
+            surfaceProfile: 'preview',
+            surfaceFeatures: { browseControls: true },
+            conversationId: preview.conversationId,
+            agentId: preview.agentId,
+            createdAt: preview.createdAt,
+            updatedAt: preview.updatedAt,
+            archivedAt: null,
+            expiresAt: preview.expiresAt,
+            version: 1,
+            canDelete: false,
+            toolPromotion: null,
+        };
+    });
+    app.get('/api/panel-previews/:id/rows', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const preview = getPanelPreviewById(db, req.params.id);
+        if (!preview) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (isPanelPreviewExpired(preview)) {
+            deleteExpiredPanelPreviews(db);
+            reply.code(410);
+            return { error: 'Panel preview expired' };
+        }
+        if (!canAccessConversation(user, preview.conversationId, conversationManager, db)) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        const contract = getComponentContract(preview.component);
+        if (!contract) {
+            reply.code(400);
+            return { error: 'Unknown component contract' };
+        }
+        const effectiveDatasetSchema = getEffectiveDatasetSchema(contract, preview.props ?? {});
+        const fieldByName = new Map(effectiveDatasetSchema?.fields.map((f) => [f.name, f]) ?? []);
+        const declaredFields = new Set(effectiveDatasetSchema?.fields.map((f) => f.name) ?? []);
+        const filterableFields = new Set(effectiveDatasetSchema?.fields.filter((f) => f.filterable).map((f) => f.name) ?? []);
+        const sortableFields = new Set(effectiveDatasetSchema?.fields.filter((f) => f.sortable).map((f) => f.name) ?? []);
+        const filter = parseFilter(req.query.filter);
+        if (filter) {
+            if (!declaredFields.has(filter.field)) {
+                reply.code(400);
+                return { error: `Filter field "${filter.field}" is not declared` };
+            }
+            if (!filterableFields.has(filter.field)) {
+                reply.code(400);
+                return { error: `Filter field "${filter.field}" is not filterable` };
+            }
+        }
+        const sort = parseSort(req.query.sort);
+        if (sort) {
+            if (!declaredFields.has(sort.field)) {
+                reply.code(400);
+                return { error: `Sort field "${sort.field}" is not declared` };
+            }
+            if (!sortableFields.has(sort.field)) {
+                reply.code(400);
+                return { error: `Sort field "${sort.field}" is not sortable` };
+            }
+        }
+        const limit = Number(req.query.limit ?? '50');
+        const options = {
+            filterField: filter?.field,
+            filterValue: filter?.value,
+            sortField: sort?.field,
+            sortDirection: sort?.direction,
+            sortFieldType: sort ? fieldByName.get(sort.field)?.type : undefined,
+            cursor: req.query.cursor ?? null,
+            limit: Number.isFinite(limit) && limit > 0 ? limit : 50,
+        };
+        const result = listPanelPreviewRows(db, preview.id, options);
+        return { rows: result.rows, nextCursor: result.nextCursor };
+    });
+    app.get('/api/panel-previews/:id/rows/:rowIndex/media/:slot', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const preview = getPanelPreviewById(db, req.params.id);
+        if (!preview) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (isPanelPreviewExpired(preview)) {
+            deleteExpiredPanelPreviews(db);
+            reply.code(410);
+            return { error: 'Panel preview expired' };
+        }
+        if (!canAccessConversation(user, preview.conversationId, conversationManager, db)) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        const rowIndex = Number(req.params.rowIndex);
+        if (!Number.isFinite(rowIndex) || rowIndex < 0 || !Number.isInteger(rowIndex)) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        const row = getPanelPreviewRowByIndex(db, preview.id, rowIndex);
+        if (!row) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        const mediaSlot = row.media[req.params.slot];
+        if (!mediaSlot || mediaSlot.kind !== 'workspace_path') {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (!row.nodeId) {
+            reply.code(503);
+            return { error: 'Agent node unavailable' };
+        }
+        const declaredDisplayType = getDeclaredPanelMediaDisplayType(preview, req.params.slot) ?? 'img';
+        const agent = conversationManager.getAgent(preview.agentId);
+        const resolvedMediaPath = resolvePanelMediaPath(agent?.workspacePath, mediaSlot.value, conversationManager.getConfig());
+        if (!resolvedMediaPath.ok) {
+            reply.code(resolvedMediaPath.statusCode);
+            return { error: resolvedMediaPath.error };
+        }
+        const result = await workspaceBroker.streamExactPath(row.nodeId, resolvedMediaPath.absolutePath, { allowedRoot: resolvedMediaPath.allowedRoot });
+        if (!panelMediaMimeMatchesDisplayType(result.mimeType, declaredDisplayType)) {
+            reply.code(400);
+            return { error: declaredDisplayType === 'img' ? 'Non-image media not supported' : `Media mime type does not match declared displayType ${declaredDisplayType}` };
+        }
+        if (result.size > panelMediaDisplayTypeLimitBytes(declaredDisplayType)) {
+            const error = panelMediaSizeCapExceededError(declaredDisplayType);
+            reply.code(error.statusCode);
+            return { error: error.error };
+        }
+        const chunks = [];
+        for await (const chunk of result.stream) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        const buffer = Buffer.concat(chunks);
+        reply.header('Content-Type', result.mimeType);
+        reply.header('Content-Length', String(buffer.length));
+        reply.header('Cache-Control', uncachedPanelMediaCacheControl());
+        reply.header('X-Content-Type-Options', 'nosniff');
+        return reply.send(buffer);
+    });
+    app.get('/api/panels/:id', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        const canViewToolMaintenanceConversationId = canViewerSeeToolMaintenanceConversationId(user, panel);
+        const surfaceContract = await getPanelSurfaceContractForViewer(user, panel);
+        return {
+            id: panel.id,
+            component: panel.component,
+            props: panel.props ?? {},
+            actions: sanitizePanelActionsForClient(panel.actions),
+            rowCount: panel.rowCount ?? 0,
+            rowCountKnown: panel.rowCountKnown ?? true,
+            datasetSource: panel.datasetSource,
+            status: panel.status,
+            progress: panel.progress ?? null,
+            result: panel.result ?? null,
+            scopeType: panel.scopeType,
+            scopeId: panel.scopeId ?? surfaceContract.scopeId ?? null,
+            toolId: panel.toolId ?? null,
+            surfaceProfile: surfaceContract.surfaceProfile,
+            surfaceFeatures: surfaceContract.surfaceFeatures,
+            conversationId: panel.scopeType === 'tool' && !canViewToolMaintenanceConversationId ? '' : panel.conversationId,
+            agentId: panel.agentId,
+            createdAt: panel.createdAt,
+            updatedAt: panel.updatedAt,
+            archivedAt: panel.archivedAt ?? null,
+            version: panel.version,
+            canDelete: canDeletePanelForUser(user, panel),
+            toolPromotion: panel.scopeType === 'tool' ? null : workspaceToolService.getPanelPromotionInfoForUser(user.id, panel.id),
+        };
+    });
+    app.get('/api/panels/:id/collaborators', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        if (panel.scopeType === 'tool') {
+            reply.code(409);
+            return { error: 'Tool panel collaborators are managed through the workspace tool surface' };
+        }
+        return formatPanelCollaboratorsForUser(user, panel);
+    });
+    app.post('/api/panels/:id/collaborators', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        if (panel.scopeType === 'tool') {
+            reply.code(409);
+            return { error: 'Tool panel collaborators are managed through the workspace tool surface' };
+        }
+        if (!canManagePanelCollaboratorsForUser(user, panel)) {
+            reply.code(panel.archivedAt ? 409 : 403);
+            return { error: panel.archivedAt ? 'Panel is archived' : 'Access denied' };
+        }
+        const body = req.body ?? {};
+        const collaboratorAgentId = typeof body.collaboratorAgentId === 'string' && body.collaboratorAgentId.trim()
+            ? body.collaboratorAgentId.trim()
+            : typeof body.agentId === 'string' && body.agentId.trim()
+                ? body.agentId.trim()
+                : '';
+        if (!collaboratorAgentId) {
+            reply.code(400);
+            return { error: 'collaboratorAgentId is required' };
+        }
+        const collaboratorAgent = conversationManager.getAgent(collaboratorAgentId);
+        if (!collaboratorAgent || isPlatformAgent(collaboratorAgent)) {
+            reply.code(404);
+            return { error: 'Collaborator agent not found' };
+        }
+        if (!user.isAdmin && !getUserAgentAccess(db, user.id).includes(collaboratorAgent.agentId)) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        ensurePanelSurfaceOwner(panel);
+        upsertSurfaceCollaborator(db, {
+            surfaceType: 'panel',
+            surfaceId: panel.id,
+            agentId: collaboratorAgent.agentId,
+            role: collaboratorAgent.agentId === panel.agentId ? 'owner' : 'collaborator',
+            addedBy: `user:${user.id}`,
+        });
+        return formatPanelCollaboratorsForUser(user, panel);
+    });
+    app.delete('/api/panels/:id/collaborators/:collaboratorAgentId', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        if (panel.scopeType === 'tool') {
+            reply.code(409);
+            return { error: 'Tool panel collaborators are managed through the workspace tool surface' };
+        }
+        if (!canManagePanelCollaboratorsForUser(user, panel)) {
+            reply.code(panel.archivedAt ? 409 : 403);
+            return { error: panel.archivedAt ? 'Panel is archived' : 'Access denied' };
+        }
+        ensurePanelSurfaceOwner(panel);
+        const collaboratorAgentId = req.params.collaboratorAgentId.trim();
+        const role = getSurfaceCollaboratorRole(db, 'panel', panel.id, collaboratorAgentId);
+        if (!role) {
+            reply.code(404);
+            return { error: 'Collaborator not found' };
+        }
+        if (role === 'owner') {
+            reply.code(400);
+            return { error: 'Panel owner cannot be removed' };
+        }
+        removeSurfaceCollaborator(db, 'panel', panel.id, collaboratorAgentId);
+        return formatPanelCollaboratorsForUser(user, panel);
+    });
+    app.delete('/api/panels/:id', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (!canDeletePanelForUser(user, panel)) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        const deleted = hardDeletePanelWithArtifacts(db, panel.id);
+        if (!deleted) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        emitPanelDeleted(deleted);
+        reply.code(204);
+        return;
+    });
+    app.post('/api/panels/:id/promote-to-tool', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        const promotionInfo = workspaceToolService.getPanelPromotionInfoForUser(user.id, panel.id);
+        const canOpenArchivedLinkedTool = promotionInfo?.state === 'source_archived_linked_live_tool';
+        if (!canOpenArchivedLinkedTool && !(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        try {
+            return await workspaceToolService.promotePanelToTool({
+                userId: user.id,
+                panelId: panel.id,
+            });
+        }
+        catch (error) {
+            const statusCode = typeof error.statusCode === 'number'
+                ? error.statusCode
+                : 500;
+            reply.code(statusCode);
+            return { error: String(error?.message ?? error) };
+        }
+    });
+    app.get('/api/panels/:id/rows', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        if (panel.archivedAt) {
+            reply.code(409);
+            return { error: 'Panel is archived' };
+        }
+        const contract = getComponentContract(panel.component);
+        if (!contract) {
+            reply.code(400);
+            return { error: 'Unknown component contract' };
+        }
+        const effectiveDatasetSchema = getEffectiveDatasetSchema(contract, panel.props ?? {});
+        const fieldByName = new Map(effectiveDatasetSchema?.fields.map((f) => [f.name, f]) ?? []);
+        const declaredFields = new Set(effectiveDatasetSchema?.fields.map((f) => f.name) ?? []);
+        const filterableFields = new Set(effectiveDatasetSchema?.fields.filter((f) => f.filterable).map((f) => f.name) ?? []);
+        const sortableFields = new Set(effectiveDatasetSchema?.fields.filter((f) => f.sortable).map((f) => f.name) ?? []);
+        const filter = parseFilter(req.query.filter);
+        if (filter) {
+            if (!declaredFields.has(filter.field)) {
+                reply.code(400);
+                return { error: `Filter field "${filter.field}" is not declared` };
+            }
+            if (!filterableFields.has(filter.field)) {
+                reply.code(400);
+                return { error: `Filter field "${filter.field}" is not filterable` };
+            }
+        }
+        const sort = parseSort(req.query.sort);
+        if (sort) {
+            if (!declaredFields.has(sort.field)) {
+                reply.code(400);
+                return { error: `Sort field "${sort.field}" is not declared` };
+            }
+            if (!sortableFields.has(sort.field)) {
+                reply.code(400);
+                return { error: `Sort field "${sort.field}" is not sortable` };
+            }
+        }
+        const limit = Number(req.query.limit ?? '50');
+        let result;
+        try {
+            const options = {
+                filterField: filter?.field,
+                filterValue: filter?.value,
+                sortField: sort?.field,
+                sortDirection: sort?.direction,
+                sortFieldType: sort ? fieldByName.get(sort.field)?.type : undefined,
+                cursor: req.query.cursor ?? null,
+                limit: Number.isFinite(limit) && limit > 0 ? limit : 50,
+            };
+            result = isPanelQueryHandleSource(panel)
+                ? await listPanelQueryHandleRows({
+                    db,
+                    panel,
+                    conversationManager,
+                    workspaceBroker,
+                    config: conversationManager.getConfig(),
+                    apiJsonlAllowedOrigins: loadPanelApiJsonlAllowedOrigins(db, conversationManager, panel.agentId),
+                    apiJsonlAllowedUrlPrefixes: loadPanelApiJsonlAllowedUrlPrefixes(db, conversationManager, panel.agentId),
+                    apiJsonlAuthProfiles: loadPanelApiJsonlAuthProfiles(db, conversationManager, panel.agentId),
+                    datasetSchema: effectiveDatasetSchema,
+                    options,
+                })
+                : listPanelRows(db, panel.id, options);
+        }
+        catch (error) {
+            if (error instanceof PanelQueryHandleError) {
+                reply.code(error.statusCode);
+                return { error: error.message };
+            }
+            throw error;
+        }
+        return {
+            rows: result.rows,
+            nextCursor: result.nextCursor,
+        };
+    });
+    app.get('/api/panels/:id/aggregate', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        if (panel.archivedAt) {
+            reply.code(409);
+            return { error: 'Panel is archived' };
+        }
+        const contract = getComponentContract(panel.component);
+        if (!contract) {
+            reply.code(400);
+            return { error: 'Unknown component contract' };
+        }
+        const op = parsePanelAggregateOp(req.query.op);
+        if (!op) {
+            reply.code(400);
+            return { error: 'Aggregate op must be count, sum, avg, min, or max' };
+        }
+        const effectiveDatasetSchema = getEffectiveDatasetSchema(contract, panel.props ?? {});
+        const declaredFields = new Set(effectiveDatasetSchema?.fields.map((f) => f.name) ?? []);
+        const filterableFields = new Set(effectiveDatasetSchema?.fields.filter((f) => f.filterable).map((f) => f.name) ?? []);
+        const field = typeof req.query.field === 'string' && req.query.field.trim()
+            ? req.query.field.trim()
+            : undefined;
+        if (field && !declaredFields.has(field)) {
+            reply.code(400);
+            return { error: `Aggregate field "${field}" is not declared` };
+        }
+        if (op !== 'count' && !field) {
+            reply.code(400);
+            return { error: `Aggregate field is required for ${op}` };
+        }
+        const filter = parseFilter(req.query.filter);
+        if (filter) {
+            if (!declaredFields.has(filter.field)) {
+                reply.code(400);
+                return { error: `Filter field "${filter.field}" is not declared` };
+            }
+            if (!filterableFields.has(filter.field)) {
+                reply.code(400);
+                return { error: `Filter field "${filter.field}" is not filterable` };
+            }
+        }
+        try {
+            const result = isPanelQueryHandleSource(panel)
+                ? await aggregatePanelQueryHandleRows({
+                    db,
+                    panel,
+                    conversationManager,
+                    workspaceBroker,
+                    config: conversationManager.getConfig(),
+                    apiJsonlAllowedOrigins: loadPanelApiJsonlAllowedOrigins(db, conversationManager, panel.agentId),
+                    apiJsonlAllowedUrlPrefixes: loadPanelApiJsonlAllowedUrlPrefixes(db, conversationManager, panel.agentId),
+                    apiJsonlAuthProfiles: loadPanelApiJsonlAuthProfiles(db, conversationManager, panel.agentId),
+                    datasetSchema: effectiveDatasetSchema,
+                    options: {
+                        op,
+                        field,
+                        filterField: filter?.field,
+                        filterValue: filter?.value,
+                    },
+                })
+                : aggregatePanelRows(db, panel.id, {
+                    op,
+                    field,
+                    filterField: filter?.field,
+                    filterValue: filter?.value,
+                });
+            return result;
+        }
+        catch (error) {
+            if (error instanceof PanelQueryHandleError) {
+                reply.code(error.statusCode);
+                return { error: error.message };
+            }
+            throw error;
+        }
+    });
+    app.get('/api/panels/:id/rows/:rowIndex/media/:slot', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (panel.archivedAt) {
+            reply.code(409);
+            return { error: 'Panel is archived' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        const rowIndex = Number(req.params.rowIndex);
+        if (!Number.isFinite(rowIndex) || rowIndex < 0 || !Number.isInteger(rowIndex)) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        const agent = conversationManager.getAgent(panel.agentId);
+        let row = getPanelRowByIndex(db, panel.id, rowIndex);
+        if (!row && isPanelQueryHandleSource(panel)) {
+            const contract = getComponentContract(panel.component);
+            if (!contract) {
+                reply.code(400);
+                return { error: 'Unknown component contract' };
+            }
+            try {
+                const dynamicRows = await listPanelQueryHandleRowsByIndices({
+                    db,
+                    panel,
+                    conversationManager,
+                    workspaceBroker,
+                    config: conversationManager.getConfig(),
+                    apiJsonlAllowedOrigins: loadPanelApiJsonlAllowedOrigins(db, conversationManager, panel.agentId),
+                    apiJsonlAllowedUrlPrefixes: loadPanelApiJsonlAllowedUrlPrefixes(db, conversationManager, panel.agentId),
+                    apiJsonlAuthProfiles: loadPanelApiJsonlAuthProfiles(db, conversationManager, panel.agentId),
+                    datasetSchema: getEffectiveDatasetSchema(contract, panel.props ?? {}),
+                    rowIndices: [rowIndex],
+                });
+                const dynamicRow = dynamicRows.rows[0];
+                row = dynamicRow
+                    ? {
+                        rowIndex: dynamicRow.rowIndex,
+                        rowId: dynamicRow.rowId,
+                        fields: dynamicRow.fields,
+                        media: dynamicRow.media,
+                        nodeId: agent?.nodeId ?? null,
+                        cachedAssetIds: {},
+                    }
+                    : null;
+            }
+            catch (error) {
+                if (error instanceof PanelQueryHandleError) {
+                    reply.code(error.statusCode);
+                    return { error: error.message };
+                }
+                throw error;
+            }
+        }
+        if (!row) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        const mediaSlot = row.media[req.params.slot];
+        if (!mediaSlot) {
+            reply.code(404);
+            return { error: 'Slot not found' };
+        }
+        const panelDeclaredDisplayType = getDeclaredPanelMediaDisplayType(panel, req.params.slot);
+        let declaredDisplayType = panelDeclaredDisplayType ?? 'img';
+        // Tool snapshots may serve owner/admin workspace fallbacks, so their media cache cannot be shared safely.
+        const canUseMediaCache = panel.scopeType !== 'tool' && !isPanelQueryHandleSource(panel);
+        const cachedAssetId = canUseMediaCache ? row.cachedAssetIds[req.params.slot] : undefined;
+        if (canUseMediaCache && cachedAssetId) {
+            const assetRow = loadAttachmentRow(db, cachedAssetId);
+            if (assetRow && assetRow.storagePath && fs.existsSync(assetRow.storagePath)) {
+                const buffer = fs.readFileSync(assetRow.storagePath);
+                reply.header('Content-Type', assetRow.mimeType ?? 'application/octet-stream');
+                reply.header('Content-Length', String(buffer.length));
+                reply.header('Cache-Control', panelMediaCacheControl(panel.scopeType));
+                reply.header('X-Content-Type-Options', 'nosniff');
+                return reply.send(buffer);
+            }
+            // Stale cache entry; fall through to fetch
+        }
+        if (mediaSlot.kind === 'asset') {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (mediaSlot.kind !== 'workspace_path') {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (!row.nodeId) {
+            reply.code(503);
+            return { error: 'Agent node unavailable' };
+        }
+        let mediaPathCandidates = [{
+                relativePath: mediaSlot.value,
+                source: 'workspace_fallback',
+            }];
+        if (panel.scopeType === 'tool') {
+            try {
+                const resolvedTool = await workspaceToolService.getToolForViewerByPanelId(user.id, panel.id);
+                declaredDisplayType = panelDeclaredDisplayType
+                    ?? getWorkspaceToolManifestMediaDisplayType(resolvedTool, req.params.slot)
+                    ?? 'img';
+                if (path.isAbsolute(mediaSlot.value)) {
+                    mediaPathCandidates = [{
+                            relativePath: mediaSlot.value,
+                            source: 'workspace_fallback',
+                        }];
+                }
+                else {
+                    const toolLookup = await workspaceToolService.getToolMediaLookupForViewer(user.id, resolvedTool.toolId, {
+                        allowAdminBypass: true,
+                    });
+                    mediaPathCandidates = getWorkspaceToolMediaRelativePathCandidates({
+                        toolId: resolvedTool.toolId,
+                        revision: resolvedTool.revision,
+                        sourceBundleRoot: toolLookup.sourceBundleRoot,
+                    }, mediaSlot.value, {
+                        includeWorkspaceFallback: resolvedTool.isOwner || user.isAdmin,
+                    });
+                }
+            }
+            catch (error) {
+                if (!isWorkspaceToolVisibilityError(error)) {
+                    throw asToolPanelLookupError(error);
+                }
+                reply.code(403);
+                return { error: 'Access denied' };
+            }
+        }
+        try {
+            let lastCandidateError = null;
+            for (const candidatePath of mediaPathCandidates) {
+                const resolvedMediaPath = resolvePanelMediaPath(agent?.workspacePath, candidatePath.relativePath, conversationManager.getConfig(), { allowedRelativeRoot: candidatePath.allowedRelativeRoot });
+                if (!resolvedMediaPath.ok) {
+                    lastCandidateError = {
+                        statusCode: resolvedMediaPath.statusCode,
+                        error: resolvedMediaPath.error,
+                    };
+                    continue;
+                }
+                const { absolutePath, allowedRoot } = resolvedMediaPath;
+                try {
+                    const result = await workspaceBroker.streamExactPath(row.nodeId, absolutePath, { allowedRoot });
+                    if (!panelMediaMimeMatchesDisplayType(result.mimeType, declaredDisplayType)) {
+                        lastCandidateError = {
+                            statusCode: 400,
+                            error: declaredDisplayType === 'img'
+                                ? 'Non-image media not supported'
+                                : `Media mime type does not match declared displayType ${declaredDisplayType}`,
+                        };
+                        continue;
+                    }
+                    const mediaLimitBytes = panelMediaDisplayTypeLimitBytes(declaredDisplayType);
+                    if (result.size > mediaLimitBytes) {
+                        lastCandidateError = panelMediaSizeCapExceededError(declaredDisplayType);
+                        continue;
+                    }
+                    const chunks = [];
+                    for await (const chunk of result.stream) {
+                        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                    }
+                    const buffer = Buffer.concat(chunks);
+                    if (!canUseMediaCache) {
+                        reply.header('Content-Type', result.mimeType);
+                        reply.header('Content-Length', String(buffer.length));
+                        reply.header('Cache-Control', uncachedPanelMediaCacheControl());
+                        reply.header('X-Content-Type-Options', 'nosniff');
+                        return reply.send(buffer);
+                    }
+                    const assetId = randomUUID();
+                    const filename = path.basename(absolutePath) || panelMediaDefaultFilename(declaredDisplayType);
+                    const sanitizedFilename = sanitizeAssetFilename(filename);
+                    const storagePath = buildCanonicalAssetStoragePath({
+                        assetsRoot: assetStoreRoot,
+                        assetId,
+                        filename: sanitizedFilename,
+                        scopeType: 'agent_upload',
+                        scopeId: panel.id,
+                    });
+                    fs.mkdirSync(path.dirname(storagePath), { recursive: true });
+                    fs.writeFileSync(storagePath, buffer);
+                    db.prepare(`INSERT INTO attachments(
+                 id, filename, original_filename, mime_type, size_bytes, storage_path,
+                 channel_id, agent_id, user_id, scope_type, scope_id, kind, materialization_policy, created_at
+               )
+               VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'workspace_cache', ?)`).run(assetId, sanitizedFilename, filename, result.mimeType, buffer.length, storagePath, null, panel.agentId, null, 'agent_upload', panel.id, declaredDisplayType === 'img' ? 'image' : 'binary', Date.now());
+                    const cached = updatePanelRowCachedAssetIdIfCurrent(db, {
+                        panelId: panel.id,
+                        panelVersion: panel.version,
+                        rowIndex,
+                        rowId: row.rowId,
+                        nodeId: row.nodeId,
+                        slot: req.params.slot,
+                        expectedCachedAssetId: cachedAssetId ?? null,
+                        mediaSlot,
+                        assetId,
+                    });
+                    if (!cached) {
+                        deletePanelAttachmentArtifacts(db, {
+                            panelId: panel.id,
+                            attachmentIds: [assetId],
+                        });
+                        reply.code(409);
+                        return { error: 'Panel row changed; retry media request' };
+                    }
+                    reply.header('Content-Type', result.mimeType);
+                    reply.header('Content-Length', String(buffer.length));
+                    reply.header('Cache-Control', panelMediaCacheControl(panel.scopeType));
+                    reply.header('X-Content-Type-Options', 'nosniff');
+                    return reply.send(buffer);
+                }
+                catch (error) {
+                    const message = String(error?.message ?? error);
+                    if (message === 'Agent node is offline.'
+                        || message.startsWith('Agent node disconnected:')
+                        || message.includes('request timed out.')) {
+                        throw error;
+                    }
+                    lastCandidateError = { statusCode: 400, error: message };
+                }
+            }
+            reply.code(lastCandidateError?.statusCode ?? 404);
+            return { error: lastCandidateError?.error ?? 'Not found' };
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            if (message === 'Agent node is offline.' || message.startsWith('Agent node disconnected:')) {
+                reply.code(503);
+                return { error: 'Agent node is offline' };
+            }
+            if (message.includes('request timed out.')) {
+                reply.code(504);
+                return { error: 'Workspace stream request timed out' };
+            }
+            if (message.startsWith('binary_file:')
+                || message.startsWith('file_too_large:')
+                || message.startsWith('not_file:')
+                || message.startsWith('not_found:')) {
+                reply.code(400);
+                return { error: message };
+            }
+            reply.code(502);
+            return { error: message };
+        }
+    });
+    app.get('/api/panels/:id/state', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (panel.archivedAt) {
+            reply.code(409);
+            return { error: 'Panel is archived' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        const defaultState = { filters: {}, sort: {}, selection: [] };
+        // For non-direct scopes, return shared + per-user envelope
+        if (panel.scopeType === 'channel' || panel.scopeType === 'thread') {
+            const perUser = normalizeStateSelectionForPanel(panel, getPanelState(db, panel.id, user.id)?.state ?? defaultState);
+            const shared = getSharedPanelState(db, panel.id);
+            return {
+                perUser,
+                shared: normalizeStateSelectionForPanel(panel, shared?.state ?? { selection: [] }),
+                version: shared?.version ?? 0,
+            };
+        }
+        const state = getPanelState(db, panel.id, user.id);
+        return {
+            state: normalizeStateSelectionForPanel(panel, state?.state ?? defaultState),
+        };
+    });
+    app.put('/api/panels/:id/state', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (panel.archivedAt) {
+            reply.code(409);
+            return { error: 'Panel is archived' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        let latestVersion;
+        if (panel.scopeType === 'direct') {
+            latestVersion = panel.version;
+        }
+        else {
+            latestVersion = getSharedPanelState(db, panel.id)?.version ?? panel.version;
+        }
+        const submittedBaseVersion = Number.isFinite(req.body?.baseVersion)
+            ? Number(req.body.baseVersion)
+            : latestVersion;
+        if (submittedBaseVersion < latestVersion) {
+            reply.code(409);
+            return {
+                error: 'Stale base version',
+                staleBase: true,
+                latestVersion,
+            };
+        }
+        const contract = getComponentContract(panel.component);
+        const stateBlob = req.body?.state;
+        const errors = validateStateBlob(contract?.stateSchema, stateBlob);
+        if (errors.length > 0) {
+            reply.code(400);
+            return { error: 'Invalid state', details: errors };
+        }
+        const stateRecord = { ...stateBlob };
+        if (Array.isArray(stateRecord.selection)) {
+            const validatedSelection = validateSelectionIndices(panel, stateRecord.selection);
+            if (!validatedSelection.ok) {
+                reply.code(400);
+                return { error: validatedSelection.error };
+            }
+            stateRecord.selection = validatedSelection.selection;
+        }
+        upsertPanelState(db, panel.id, user.id, stateRecord);
+        const formValues = stateRecord.formValues;
+        const formValueKeys = formValues && typeof formValues === 'object' && !Array.isArray(formValues)
+            ? Object.keys(formValues)
+            : [];
+        const annotationFields = collectAnnotationFields(panel);
+        const hasAnnotationValues = formValues && typeof formValues === 'object' && !Array.isArray(formValues)
+            ? Object.entries(formValues).some(([key, value]) => (containsPanelAnnotations(value) || (Array.isArray(value) && value.length === 0 && isAnnotationFormKey(key, annotationFields))))
+            : false;
+        insertPanelAuditEvent(db, {
+            panelId: panel.id,
+            eventType: hasAnnotationValues ? 'annotation_saved' : 'state_saved',
+            version: panel.version,
+            actorType: 'user',
+            actorId: user.id,
+            conversationId: panel.conversationId,
+            scopeType: panel.scopeType,
+            scopeId: panel.scopeId ?? null,
+            metadata: {
+                stateKeys: Object.keys(stateRecord),
+                ...(formValueKeys.length > 0 ? { formValueKeyCount: formValueKeys.length } : {}),
+            },
+        });
+        return { ok: true, version: latestVersion };
+    });
+    app.patch('/api/panels/:id/shared-state', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (panel.archivedAt) {
+            reply.code(409);
+            return { error: 'Panel is archived' };
+        }
+        if (!(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        // Shared state only applies to non-direct panels
+        if (panel.scopeType === 'direct' || panel.scopeType === 'tool') {
+            reply.code(400);
+            return { error: 'Shared state is not available for direct panels' };
+        }
+        const rawSelection = Array.isArray(req.body?.selection) ? req.body.selection : [];
+        const validatedSelection = validateSelectionIndices(panel, rawSelection);
+        if (!validatedSelection.ok) {
+            reply.code(400);
+            return { error: validatedSelection.error };
+        }
+        const currentShared = getSharedPanelState(db, panel.id);
+        const baseSelection = normalizeStoredSelectionForPanel(panel, currentShared?.state?.selection);
+        const result = applySharedSelectionPatch(db, panel.id, { selection: validatedSelection.selection, baseSelection }, user.id);
+        const committedSelection = Array.isArray(result.state.selection) ? result.state.selection : [];
+        const committedRowIds = panelRowIdsForIndices(db, panel.id, committedSelection);
+        insertPanelAuditEvent(db, {
+            panelId: panel.id,
+            eventType: 'selection_committed',
+            version: panel.version,
+            actorType: 'user',
+            actorId: user.id,
+            conversationId: panel.conversationId,
+            scopeType: panel.scopeType,
+            scopeId: panel.scopeId ?? null,
+            metadata: {
+                selectedCount: committedSelection.length,
+                ...(committedSelection.length > 0 ? { selectedRowIndices: committedSelection } : undefined),
+                ...(committedRowIds && committedRowIds.length > 0 ? { selectedRowIds: committedRowIds } : undefined),
+                sharedVersion: result.version,
+            },
+        });
+        // Broadcast shared state update
+        const conv = conversationManager.getConversation(panel.conversationId);
+        if (conv?.channelId && broadcastToChannel) {
+            const sharedStateEvent = {
+                type: 'panel.shared_state_updated',
+                panelId: panel.id,
+                shared: result.state,
+                version: result.version,
+                updatedByUserId: user.id,
+                updatedAt: Date.now(),
+            };
+            if (panel.scopeType === 'thread' && conv.threadRootId) {
+                sharedStateEvent.threadRootId = conv.threadRootId;
+            }
+            broadcastToChannel(conv.channelId, sharedStateEvent);
+        }
+        return { ok: true, shared: result.state, version: result.version };
+    });
+    app.post('/api/panels/:id/actions/:actionId', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const panel = getPanelById(db, req.params.id);
+        if (!panel) {
+            reply.code(404);
+            return { error: 'Not found' };
+        }
+        if (panel.archivedAt) {
+            reply.code(409);
+            return { error: 'Panel is archived' };
+        }
+        const action = (panel.actions ?? []).find((item) => item.id === req.params.actionId);
+        if (!action) {
+            reply.code(400);
+            return { error: 'Action not declared for this panel' };
+        }
+        if (panel.scopeType === 'tool') {
+            let resolvedTool;
+            try {
+                resolvedTool = await resolveToolProjectionForViewer(user, panel.id);
+            }
+            catch (error) {
+                if (!isWorkspaceToolVisibilityError(error)) {
+                    throw error;
+                }
+                reply.code(403);
+                return { error: 'Access denied' };
+            }
+            const panelContext = { panel };
+            try {
+                const result = await workspaceToolService.invokeAction({
+                    userId: user.id,
+                    toolId: resolvedTool.toolId,
+                    actionId: req.params.actionId,
+                    inputParams: req.body?.params,
+                    allowAdminBypass: panelContext != null,
+                });
+                const auditedPanel = getPanelById(db, panel.id) ?? panel;
+                emitPanelActionTriggered(auditedPanel.id, auditedPanel.conversationId, auditedPanel.scopeType, user.id, 'action', req.params.actionId);
+                insertPanelAuditEvent(db, {
+                    panelId: auditedPanel.id,
+                    eventType: 'actioned',
+                    version: auditedPanel.version,
+                    submitKind: 'action',
+                    actionId: req.params.actionId,
+                    actorType: 'user',
+                    actorId: user.id,
+                    runId: result.mode === 'platform_exec' ? result.run.runId : (result.runId ?? null),
+                    conversationId: auditedPanel.conversationId,
+                    scopeType: auditedPanel.scopeType,
+                    scopeId: resolvedTool.toolId,
+                    metadata: {
+                        delegatedToToolAction: true,
+                        toolActionMode: result.mode,
+                        actionId: req.params.actionId,
+                        toolId: resolvedTool.toolId,
+                        ...(result.mode === 'platform_exec'
+                            ? {
+                                toolRunId: result.run.runId,
+                                toolRunStatus: result.run.status,
+                            }
+                            : {
+                                notifiedConversationId: result.conversationId,
+                                notifiedRunId: result.runId ?? null,
+                                queued: result.queued,
+                            }),
+                    },
+                });
+                return {
+                    ok: true,
+                    mode: result.mode,
+                    queued: result.mode === 'notify_agent' ? result.queued : false,
+                    outputText: result.outputText ?? null,
+                    latestState: result.latestState ?? null,
+                    runId: result.mode === 'platform_exec' ? result.run.runId : result.runId,
+                    tool: result.tool,
+                };
+            }
+            catch (error) {
+                const statusCode = typeof error.statusCode === 'number'
+                    ? error.statusCode
+                    : 500;
+                const failedRunId = typeof error.runId === 'string'
+                    ? error.runId
+                    : null;
+                const auditedPanel = getPanelById(db, panel.id) ?? panel;
+                insertPanelAuditEvent(db, {
+                    panelId: auditedPanel.id,
+                    eventType: 'failed',
+                    version: auditedPanel.version,
+                    submitKind: 'action',
+                    actionId: req.params.actionId,
+                    failureClass: 'tool_panel_action_failed',
+                    actorType: 'user',
+                    actorId: user.id,
+                    runId: failedRunId,
+                    conversationId: auditedPanel.conversationId,
+                    scopeType: auditedPanel.scopeType,
+                    scopeId: resolvedTool.toolId,
+                    metadata: {
+                        delegatedToToolAction: true,
+                        actionId: req.params.actionId,
+                        toolId: resolvedTool.toolId,
+                        toolRunId: failedRunId,
+                        statusCode,
+                        error: String(error?.message ?? error),
+                    },
+                });
+                reply.code(statusCode);
+                return { error: String(error?.message ?? error) };
+            }
+        }
+        const actionCardId = typeof panel.props?.actionCardId === 'string'
+            ? panel.props.actionCardId.trim()
+            : '';
+        if (actionCardId && (req.params.actionId === 'confirm' || req.params.actionId === 'cancel')) {
+            if (!canUserActOnActionCardPanel(db, user, actionCardId)) {
+                reply.code(403);
+                return { error: 'Action card access required' };
+            }
+            try {
+                const result = req.params.actionId === 'confirm'
+                    ? confirmActionCard(db, {
+                        id: actionCardId,
+                        confirmedBy: user.id,
+                        confirmedByName: user.username,
+                        conversationManager,
+                        broadcastToChannel,
+                    })
+                    : cancelActionCard(db, {
+                        id: actionCardId,
+                        cancelledBy: user.id,
+                        cancelledByName: user.username,
+                        broadcastToChannel,
+                    });
+                emitPanelActionTriggered(panel.id, panel.conversationId, panel.scopeType, user.id, 'action', req.params.actionId);
+                insertPanelAuditEvent(db, {
+                    panelId: panel.id,
+                    eventType: 'actioned',
+                    version: panel.version,
+                    submitKind: 'action',
+                    actionId: req.params.actionId,
+                    actorType: 'user',
+                    actorId: user.id,
+                    conversationId: panel.conversationId,
+                    scopeType: panel.scopeType,
+                    scopeId: panel.scopeId ?? null,
+                    metadata: {
+                        actionCardId,
+                        actionCardAction: req.params.actionId,
+                    },
+                });
+                return {
+                    ok: true,
+                    mode: 'action_card',
+                    ...result,
+                };
+            }
+            catch (error) {
+                const statusCode = error instanceof ActionCardError ? error.statusCode : 500;
+                reply.code(statusCode);
+                return {
+                    error: String(error?.message ?? error),
+                    ...(error instanceof ActionCardError && error.errorCode
+                        ? { error_code: error.errorCode, errorCode: error.errorCode }
+                        : {}),
+                };
+            }
+        }
+        const actionMode = resolvePanelActionMode(action);
+        if (actionMode === 'notify_agent' && !(await canAccessPanel(user, panel))) {
+            reply.code(403);
+            return { error: 'Access denied' };
+        }
+        if (actionMode === 'notify_agent') {
+            const result = await submitPanel({
+                panelId: req.params.id,
+                user,
+                reply,
+                submitKind: 'action',
+                actionId: req.params.actionId,
+                baseVersion: req.body?.baseVersion,
+            });
+            return 'error' in result ? result : { ...result, mode: 'notify_agent' };
+        }
+        const actionCommand = resolvePanelActionCommand(action);
+        if (!actionCommand) {
+            reply.code(400);
+            return { error: 'platform_exec panel actions require command' };
+        }
+        const platformExecAccess = canRunPanelPlatformExec(user, panel);
+        if (!platformExecAccess.ok) {
+            reply.code(platformExecAccess.statusCode);
+            return { error: platformExecAccess.error };
+        }
+        const conv = conversationManager.getConversation(panel.conversationId);
+        if (!conv) {
+            reply.code(409);
+            return { error: 'Panel conversation is unavailable' };
+        }
+        const auditChannelId = conv.threadKind === 'direct' ? `dm:${panel.agentId}` : conv.channelId;
+        if (!auditChannelId) {
+            reply.code(409);
+            return { error: 'Panel channel is unavailable' };
+        }
+        const agent = conversationManager.getAgent(panel.agentId);
+        if (!agent?.nodeId || !agent.workspacePath) {
+            reply.code(503);
+            return { error: 'Agent node unavailable' };
+        }
+        const resolvedCwd = resolvePanelActionExecutionCwd(agent.workspacePath, resolvePanelActionDeclaredCwd(action));
+        if (!resolvedCwd.ok) {
+            reply.code(400);
+            return { error: resolvedCwd.error };
+        }
+        emitPanelActionTriggered(panel.id, panel.conversationId, panel.scopeType, user.id, 'action', action.id);
+        let terminalId = null;
+        try {
+            const terminal = await terminalBroker.createTerminal(agent.nodeId, {
+                workspaceRoot: agent.workspacePath,
+                cwd: resolvedCwd.cwd,
+                name: `panel-action:${action.id}`,
+                startupCommand: actionCommand,
+                closeOnStartupCommand: true,
+            });
+            terminalId = terminal.terminalId;
+            const snapshot = await waitForPanelActionTerminalExit(agent.nodeId, terminal.terminalId);
+            const signal = snapshot.terminal.signal && snapshot.terminal.signal !== '0'
+                ? snapshot.terminal.signal
+                : null;
+            const exitCode = snapshot.terminal.exitCode ?? (snapshot.terminal.exited && !signal ? 0 : null);
+            const status = signal || exitCode !== 0 ? 'failed' : 'completed';
+            insertPanelPlatformExecMessage(db, {
+                channelId: auditChannelId,
+                target: conv.replyTarget ?? `dm:${panel.agentId}`,
+                panelId: panel.id,
+                component: panel.component,
+                actionId: action.id,
+                actionLabel: action.label,
+                actorUserId: user.id,
+                actorUsername: user.username,
+                status,
+                exitCode,
+                signal,
+                outputText: snapshot.buffer,
+                threadRootId: conv.threadRootId ?? null,
+            });
+            if (signal || exitCode !== 0) {
+                insertPanelAuditEvent(db, {
+                    panelId: panel.id,
+                    eventType: 'failed',
+                    version: panel.version,
+                    submitKind: 'action',
+                    actionId: action.id,
+                    failureClass: 'panel_action_rpc_failed',
+                    actorType: 'user',
+                    actorId: user.id,
+                    runId: null,
+                    conversationId: panel.conversationId,
+                    scopeType: panel.scopeType,
+                    scopeId: panel.scopeId ?? null,
+                    metadata: {
+                        rpc: true,
+                        exitCode,
+                        signal,
+                        outputBytes: snapshot.buffer.length,
+                    },
+                });
+                reply.code(500);
+                return {
+                    error: signal
+                        ? `Panel RPC action "${action.label}" exited with signal ${signal}`
+                        : `Panel RPC action "${action.label}" failed with exit code ${exitCode ?? 'unknown'}`,
+                };
+            }
+            insertPanelAuditEvent(db, {
+                panelId: panel.id,
+                eventType: 'actioned',
+                version: panel.version,
+                submitKind: 'action',
+                actionId: action.id,
+                actorType: 'user',
+                actorId: user.id,
+                runId: null,
+                conversationId: panel.conversationId,
+                scopeType: panel.scopeType,
+                scopeId: panel.scopeId ?? null,
+                metadata: {
+                    rpc: true,
+                    exitCode,
+                    signal,
+                    outputBytes: snapshot.buffer.length,
+                },
+            });
+            return {
+                ok: true,
+                mode: 'platform_exec',
+                queued: false,
+                outputText: snapshot.buffer,
+                exitCode,
+                signal,
+            };
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            reply.code(message.includes('offline') ? 503 : 500);
+            return { error: message };
+        }
+        finally {
+            if (terminalId) {
+                await Promise.resolve(terminalBroker.closeTerminal(agent.nodeId, terminalId)).catch(() => undefined);
+            }
+        }
+    });
+    app.post('/api/panels/:id/submits', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const submitKind = req.body?.submitKind;
+        if (submitKind !== 'form' && submitKind !== 'apply' && submitKind !== 'done') {
+            reply.code(400);
+            return { error: 'submitKind must be form, apply, or done' };
+        }
+        return submitPanel({
+            panelId: req.params.id,
+            user,
+            reply,
+            submitKind,
+            actionId: req.body?.actionId,
+            baseVersion: req.body?.baseVersion,
+            form: req.body?.form,
+            changedRowIndices: req.body?.changedRowIndices,
+            metadata: req.body?.metadata,
+        });
+    });
+    app.get('/internal/panels/:panelId/audit', async (req, reply) => {
+        const user = requireAdmin(req, reply, db);
+        if (!user)
+            return { error: 'Forbidden' };
+        const events = listPanelAuditEvents(db, req.params.panelId);
+        return events.map((event) => ({
+            panelId: event.panelId,
+            event: event.event,
+            timestamp: event.timestamp,
+            version: event.version,
+            changed: event.changed ? JSON.parse(event.changed) : undefined,
+            submitKind: event.submitKind ?? undefined,
+            actionId: event.actionId ?? undefined,
+            failureClass: event.failureClass ?? undefined,
+            actor: {
+                type: event.actorType,
+                id: event.actorId,
+                runId: event.runId,
+            },
+            conversationId: event.conversationId,
+            scopeType: event.scopeType,
+            scopeId: event.scopeId ?? undefined,
+            metadata: JSON.parse(event.metadataJson),
+        }));
+    });
+    // Service proxy: browser → core → agent-node WS → localhost:{port}/{path}
+    // Requires the tool manifest to declare a service.port.
+    // Only the tool owner or collaborators may call this.
+    const SERVICE_PROXY_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+    const SERVICE_PROXY_MAX_BYTES = 4 * 1024 * 1024; // 4 MB response cap
+    app.all('/api/workspace-tools/:toolId/service-proxy/*', async (req, reply) => {
+        const user = requireUser(req, reply, db);
+        if (!user)
+            return { error: 'Unauthorized' };
+        const method = req.method.toUpperCase();
+        if (!SERVICE_PROXY_METHODS.has(method)) {
+            reply.code(405);
+            return { error: 'Method not allowed' };
+        }
+        let tool;
+        try {
+            tool = await workspaceToolService.getToolForViewer(user.id, req.params.toolId);
+        }
+        catch (error) {
+            if (error instanceof Error && 'statusCode' in error && error.statusCode === 404) {
+                reply.code(404);
+                return { error: 'Tool not found' };
+            }
+            throw error;
+        }
+        const serviceManifest = tool.manifest.service;
+        if (!serviceManifest) {
+            reply.code(409);
+            return { error: 'Tool does not declare a service port in its manifest' };
+        }
+        const nodeId = tool.agentNodeId;
+        if (!nodeId) {
+            reply.code(503);
+            return { error: 'Tool agent node is not connected' };
+        }
+        const subpath = req.params['*'] ?? '';
+        const targetUrl = `http://localhost:${serviceManifest.port}/${subpath}`;
+        const body = typeof req.body === 'string'
+            ? req.body
+            : req.body != null
+                ? JSON.stringify(req.body)
+                : undefined;
+        const forwardHeaders = {};
+        const contentType = req.headers['content-type'];
+        if (contentType)
+            forwardHeaders['content-type'] = contentType;
+        const accept = req.headers['accept'];
+        if (accept)
+            forwardHeaders['accept'] = accept;
+        let result;
+        try {
+            result = await workspaceBroker.proxyWorkspaceService(nodeId, targetUrl, {
+                method: method,
+                headers: forwardHeaders,
+                ...(body !== undefined ? { body } : {}),
+                maxBytes: SERVICE_PROXY_MAX_BYTES,
+            });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Service proxy failed';
+            if (msg.includes('offline') || msg.includes('not connected')) {
+                reply.code(503);
+                return { error: msg };
+            }
+            if (msg.includes('timed out')) {
+                reply.code(504);
+                return { error: msg };
+            }
+            reply.code(502);
+            return { error: msg };
+        }
+        reply.code(result.status);
+        if (result.contentType)
+            reply.header('content-type', result.contentType);
+        return reply.send(result.body);
+    });
+    app.get('/api/internal/admin/panels/:id/trace', async (req, reply) => {
+        const user = requireAdmin(req, reply, db);
+        if (!user)
+            return { error: 'Forbidden' };
+        const events = listPanelAuditEvents(db, req.params.id);
+        return events.map((event) => ({
+            panelId: event.panelId,
+            eventType: event.event,
+            timestamp: event.timestamp,
+            version: event.version,
+            changed: event.changed ? JSON.parse(event.changed) : undefined,
+            submitKind: event.submitKind ?? undefined,
+            actionId: event.actionId ?? undefined,
+            failureClass: event.failureClass ?? undefined,
+            actor: {
+                type: event.actorType,
+                id: event.actorId,
+                runId: event.runId,
+            },
+            conversationId: event.conversationId,
+            scopeType: event.scopeType,
+            scopeId: event.scopeId ?? undefined,
+            metadata: JSON.parse(event.metadataJson),
+        }));
+    });
+}