@useorgx/openclaw-plugin 0.4.9 → 0.7.2

package/dist/http/routes/live-snapshot.js

@@ -1,3 +1,38 @@
+import { normalizeReportingBlockedSessions } from "../helpers/session-classification.js";
+import { buildSliceRunProjections } from "../helpers/slice-run-projections.js";
+import { buildSliceExperienceSnapshotV2, findSessionDetailProjection, findSliceNarrative, } from "../helpers/slice-experience-v2.js";
+import { shouldHideActivityItem } from "../../event-sanitization.js";
+import { KNOWN_DECISION_ACTION_TYPES, normalizeDecisionActionType, } from "../../contracts/shared-types.js";
+import { resolveWorkspaceScope, workspaceScopeFromHeaders, } from "../helpers/workspace-scope.js";
+const LIVE_SNAPSHOT_UPSTREAM_TIMEOUT_MS = (() => {
+    const raw = Number(process.env.ORGX_LIVE_SNAPSHOT_UPSTREAM_TIMEOUT_MS ?? "");
+    if (!Number.isFinite(raw))
+        return 3_500;
+    return Math.max(500, Math.min(60_000, Math.floor(raw)));
+})();
+const LIVE_SNAPSHOT_NEXT_UP_TIMEOUT_MS = (() => {
+    const raw = Number(process.env.ORGX_LIVE_SNAPSHOT_NEXT_UP_TIMEOUT_MS ?? "");
+    if (!Number.isFinite(raw))
+        return 1_200;
+    return Math.max(250, Math.min(15_000, Math.floor(raw)));
+})();
+async function withSoftTimeout(work, timeoutMs, label) {
+    let timer = null;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 function outboxStatusFromSummary(summary) {
     return {
         pendingTotal: summary.pendingTotal,
@@ -49,28 +84,205 @@ function maybeFilterActivity(items, input) {
     }
     return filtered;
 }
+function filterSessionsByInitiativeSet(sessions, initiativeIds) {
+    if (initiativeIds.size === 0) {
+        return {
+            nodes: [],
+            edges: [],
+            groups: [],
+        };
+    }
+    const filteredNodes = sessions.nodes.filter((node) => {
+        const initiativeId = node.initiativeId?.trim() ?? "";
+        return initiativeId.length > 0 && initiativeIds.has(initiativeId);
+    });
+    const filteredNodeIds = new Set(filteredNodes.map((node) => node.id));
+    const filteredGroupIds = new Set(filteredNodes.map((node) => node.groupId));
+    return {
+        nodes: filteredNodes,
+        edges: sessions.edges.filter((edge) => filteredNodeIds.has(edge.parentId) && filteredNodeIds.has(edge.childId)),
+        groups: sessions.groups.filter((group) => filteredGroupIds.has(group.id)),
+    };
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function pickString(input, keys) {
+    if (!input)
+        return null;
+    for (const key of keys) {
+        const value = input[key];
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    return null;
+}
+function resolveActivitySliceRunId(item) {
+    if (item.runId && item.runId.trim().length > 0)
+        return item.runId.trim();
+    const metadata = asRecord(item.metadata);
+    return pickString(metadata, [
+        "slice_run_id",
+        "sliceRunId",
+        "active_run_id",
+        "activeRunId",
+        "run_id",
+        "runId",
+        "correlation_id",
+        "correlationId",
+    ]);
+}
+function resolveDecisionIdsForSlice(decisions, sliceRunId) {
+    const target = sliceRunId.trim();
+    if (!target)
+        return [];
+    const matched = [];
+    for (const decision of decisions) {
+        const decisionId = pickString(decision, ["id"]);
+        if (!decisionId)
+            continue;
+        const metadata = asRecord(decision.metadata);
+        const linkedSliceRunId = pickString(metadata, [
+            "slice_run_id",
+            "sliceRunId",
+            "run_id",
+            "runId",
+            "correlation_id",
+            "correlationId",
+        ]);
+        if (!linkedSliceRunId || linkedSliceRunId !== target)
+            continue;
+        const status = (pickString(decision, ["status"]) ?? "pending").toLowerCase();
+        if (status === "approved" || status === "declined" || status === "resolved" || status === "cancelled") {
+            continue;
+        }
+        if (matched.includes(decisionId))
+            continue;
+        matched.push(decisionId);
+    }
+    return matched;
+}
+function resolveInitiativeIdFromActivity(item) {
+    if (item.initiativeId && item.initiativeId.trim().length > 0) {
+        return item.initiativeId.trim();
+    }
+    const metadata = asRecord(item.metadata);
+    return pickString(metadata, ["initiative_id", "initiativeId"]);
+}
+function filterActivityByInitiativeSet(items, initiativeIds) {
+    if (initiativeIds.size === 0)
+        return [];
+    return items.filter((item) => {
+        const initiativeId = resolveInitiativeIdFromActivity(item);
+        return initiativeId ? initiativeIds.has(initiativeId) : false;
+    });
+}
+function resolveInitiativeIdFromRecord(entry) {
+    const direct = pickString(entry, ["initiative_id", "initiativeId", "initiative"]);
+    if (direct)
+        return direct;
+    const metadata = asRecord(entry.metadata);
+    return pickString(metadata, ["initiative_id", "initiativeId"]);
+}
+function filterRecordsByInitiativeSet(rows, initiativeIds) {
+    if (initiativeIds.size === 0)
+        return [];
+    return rows.filter((row) => {
+        const initiativeId = resolveInitiativeIdFromRecord(row);
+        return initiativeId ? initiativeIds.has(initiativeId) : false;
+    });
+}
+function filterRuntimeInstancesByInitiativeSet(rows, initiativeIds) {
+    if (initiativeIds.size === 0)
+        return [];
+    return rows.filter((row) => {
+        const initiativeId = row.initiativeId?.trim() ?? "";
+        return initiativeId.length > 0 && initiativeIds.has(initiativeId);
+    });
+}
+function filterHandoffsByInitiativeSet(rows, initiativeIds) {
+    if (initiativeIds.size === 0)
+        return [];
+    return rows.filter((entry) => {
+        const record = asRecord(entry);
+        const initiativeId = pickString(record, [
+            "initiative_id",
+            "initiativeId",
+            "initiative",
+        ]);
+        if (initiativeId && initiativeIds.has(initiativeId))
+            return true;
+        const metadata = asRecord(record?.metadata);
+        const metadataInitiativeId = pickString(metadata, ["initiative_id", "initiativeId"]);
+        return metadataInitiativeId ? initiativeIds.has(metadataInitiativeId) : false;
+    });
+}
 export function registerLiveSnapshotRoutes(router, deps) {
-    async function renderSnapshot(path, query, res) {
+    const snapshotAliasKey = (base, workspaceId) => {
+        const normalized = (workspaceId ?? "").trim();
+        if (!normalized)
+            return base;
+        return `${base}:${normalized}`;
+    };
+    const headerScopeFromRequest = (req) => workspaceScopeFromHeaders(req?.headers);
+    function parseSnapshotQuery(query, headerScope) {
         const sessionsLimit = deps.parsePositiveInt(query.get("sessionsLimit") ?? query.get("sessions_limit"), 320);
         const activityLimit = deps.parsePositiveInt(query.get("activityLimit") ?? query.get("activity_limit"), 600);
         const decisionsLimit = deps.parsePositiveInt(query.get("decisionsLimit") ?? query.get("decisions_limit"), 120);
         const initiative = query.get("initiative");
+        const scope = resolveWorkspaceScope(query, headerScope, {
+            allowProjectScope: false,
+        });
+        const projectId = scope.workspaceId;
         const run = query.get("run");
         const since = query.get("since");
         const decisionStatus = query.get("status") ?? "pending";
         const includeIdleRaw = query.get("include_idle");
         const includeIdle = includeIdleRaw === null ? undefined : includeIdleRaw !== "false";
-        const snapshotCacheKey = `${path}?${query.toString()}`;
-        const cachedSnapshot = deps.readSnapshotResponseCache(snapshotCacheKey);
-        if (cachedSnapshot) {
-            deps.sendJson(res, 200, cachedSnapshot);
-            return;
+        return {
+            sessionsLimit,
+            activityLimit,
+            decisionsLimit,
+            initiative,
+            projectId,
+            run,
+            since,
+            decisionStatus,
+            includeIdle,
+            scopeError: scope.error ?? null,
+        };
+    }
+    const validateWorkspaceScope = (query, res, location, headerScope) => {
+        const scope = resolveWorkspaceScope(query, headerScope, {
+            allowProjectScope: false,
+        });
+        if (!scope.error)
+            return true;
+        deps.sendJson(res, 400, {
+            error: scope.error,
+            error_location: location,
+        });
+        return false;
+    };
+    async function buildSnapshotBundle(query, headerScope) {
+        const parsed = parseSnapshotQuery(query, headerScope);
+        const { sessionsLimit, activityLimit, decisionsLimit, initiative, projectId, run, since, decisionStatus, includeIdle, scopeError, } = parsed;
+        if (scopeError) {
+            throw new Error(scopeError);
         }
         const degraded = [];
         const contextStore = deps.readAgentContexts();
         const agentContexts = contextStore.agents;
         const runContexts = contextStore.runs ?? {};
         const scopedAgentIds = deps.getScopedAgentIds(agentContexts);
+        const scopedProjectInitiativeIds = projectId && projectId.trim().length > 0
+            ? new Set(await deps.listInitiativeIdsForProject({ projectId: projectId.trim() }))
+            : null;
         let outboxStatus;
         try {
             const diagnosticsOutbox = await deps.readDiagnosticsOutboxStatus();
@@ -93,24 +305,28 @@ export function registerLiveSnapshotRoutes(router, deps) {
             return localSnapshot;
         };
         const settled = await Promise.allSettled([
-            deps.getLiveSessions({
+            withSoftTimeout(deps.getLiveSessions({
                 initiative,
+                projectId,
                 limit: sessionsLimit,
-            }),
-            deps.getLiveActivity({
+            }), LIVE_SNAPSHOT_UPSTREAM_TIMEOUT_MS, "live sessions"),
+            withSoftTimeout(deps.getLiveActivity({
                 run,
                 since,
+                projectId,
                 limit: activityLimit,
-            }),
-            deps.getHandoffs(),
-            deps.getLiveDecisions({
+            }), LIVE_SNAPSHOT_UPSTREAM_TIMEOUT_MS, "live activity"),
+            withSoftTimeout(deps.getHandoffs(), LIVE_SNAPSHOT_UPSTREAM_TIMEOUT_MS, "handoffs"),
+            withSoftTimeout(deps.getLiveDecisions({
                 status: decisionStatus,
+                projectId,
                 limit: decisionsLimit,
-            }),
-            deps.getLiveAgents({
+            }), LIVE_SNAPSHOT_UPSTREAM_TIMEOUT_MS, "live decisions"),
+            withSoftTimeout(deps.getLiveAgents({
                 initiative,
+                projectId,
                 includeIdle,
-            }),
+            }), LIVE_SNAPSHOT_UPSTREAM_TIMEOUT_MS, "live agents"),
         ]);
         let sessions = {
             nodes: [],
@@ -229,14 +445,25 @@ export function registerLiveSnapshotRoutes(router, deps) {
             const buffered = await deps.readOutboxItems();
             if (buffered.length > 0) {
                 const merged = [...activity, ...buffered]
-                    .sort((a, b) => Date.parse(b.timestamp) - Date.parse(a.timestamp))
+                    .sort((a, b) => {
+                    const d = Date.parse(b.timestamp) - Date.parse(a.timestamp);
+                    if (d !== 0)
+                        return d;
+                    return b.id.localeCompare(a.id);
+                })
                     .slice(0, activityLimit);
                 const deduped = [];
-                const seen = new Set();
+                const seenIds = new Set();
+                const seenSemantic = new Set();
                 for (const item of merged) {
-                    if (seen.has(item.id))
+                    if (seenIds.has(item.id))
                         continue;
-                    seen.add(item.id);
+                    seenIds.add(item.id);
+                    const sk = deps.semanticActivityKey(item);
+                    if (sk && seenSemantic.has(sk))
+                        continue;
+                    if (sk)
+                        seenSemantic.add(sk);
                     deduped.push(item);
                 }
                 activity = deduped;
@@ -252,6 +479,14 @@ export function registerLiveSnapshotRoutes(router, deps) {
         if (run && run.trim().length > 0) {
             runtimeInstances = runtimeInstances.filter((instance) => instance.runId === run || instance.correlationId === run);
         }
+        if (scopedProjectInitiativeIds) {
+            sessions = filterSessionsByInitiativeSet(sessions, scopedProjectInitiativeIds);
+            activity = filterActivityByInitiativeSet(activity, scopedProjectInitiativeIds);
+            decisions = filterRecordsByInitiativeSet(decisions, scopedProjectInitiativeIds);
+            agents = filterRecordsByInitiativeSet(agents, scopedProjectInitiativeIds);
+            handoffs = filterHandoffsByInitiativeSet(handoffs, scopedProjectInitiativeIds);
+            runtimeInstances = filterRuntimeInstancesByInitiativeSet(runtimeInstances, scopedProjectInitiativeIds);
+        }
         sessions = deps.injectRuntimeInstancesAsSessions(sessions, runtimeInstances);
         sessions = deps.enrichSessionsWithRuntime(sessions, runtimeInstances);
         activity = deps.enrichActivityWithRuntime(activity, runtimeInstances);
@@ -259,6 +494,18 @@ export function registerLiveSnapshotRoutes(router, deps) {
             agents: agentContexts,
             runs: runContexts,
         });
+        activity = activity.filter((item) => !shouldHideActivityItem(item));
+        sessions = normalizeReportingBlockedSessions({
+            sessions,
+            activity,
+            runtimeInstances,
+        });
+        const sliceRuns = buildSliceRunProjections({
+            activity,
+            sessions: sessions.nodes,
+            decisions,
+            runtimeInstances,
+        });
         try {
             const fingerprint = deps.snapshotActivityFingerprint(activity);
             const now = Date.now();
@@ -281,17 +528,400 @@ export function registerLiveSnapshotRoutes(router, deps) {
             activity,
             handoffs,
             decisions,
+            sliceRuns,
             agents,
             runtimeInstances,
             outbox: outboxStatus,
             generatedAt: new Date().toISOString(),
+            projectId,
             degraded: degraded.length > 0 ? degraded : undefined,
         };
+        if (typeof deps.listChatThreads === "function") {
+            try {
+                const listed = deps.listChatThreads({
+                    commandCenterId: projectId,
+                    initiativeId: initiative,
+                    limit: 120,
+                    offset: 0,
+                });
+                payload.chat = {
+                    threads: listed.threads,
+                    total: listed.total,
+                    updatedAt: listed.updatedAt,
+                };
+            }
+            catch (err) {
+                degraded.push(`chat unavailable (${deps.safeErrorMessage(err)})`);
+            }
+        }
+        let nextUpItems = [];
+        if (typeof deps.buildNextUpQueue === "function") {
+            try {
+                const nextUp = await withSoftTimeout(deps.buildNextUpQueue({ initiativeId: initiative, projectId }), LIVE_SNAPSHOT_NEXT_UP_TIMEOUT_MS, "next-up queue");
+                nextUpItems = Array.isArray(nextUp.items)
+                    ? nextUp.items.filter((item) => Boolean(item))
+                    : [];
+                for (const warning of nextUp.degraded ?? []) {
+                    if (typeof warning !== "string" || warning.trim().length === 0)
+                        continue;
+                    degraded.push(`next-up ${warning}`);
+                }
+            }
+            catch (err) {
+                degraded.push(`next-up unavailable (${deps.safeErrorMessage(err)})`);
+            }
+        }
+        const v2 = buildSliceExperienceSnapshotV2({
+            generatedAt: payload.generatedAt,
+            sliceRuns: payload.sliceRuns,
+            sessions: payload.sessions.nodes,
+            activity: payload.activity,
+            runtimeInstances: payload.runtimeInstances,
+            nextUpItems,
+        });
+        return {
+            payload: {
+                ...payload,
+                degraded: degraded.length > 0 ? degraded : undefined,
+            },
+            v2,
+            decisionsRaw: decisions,
+        };
+    }
+    async function renderSnapshot(path, query, res, headerScope) {
+        if (!validateWorkspaceScope(query, res, "live.snapshot.validation", headerScope))
+            return;
+        const snapshotCacheKey = `${path}?${query.toString()}`;
+        const cachedSnapshot = deps.readSnapshotResponseCache(snapshotCacheKey);
+        if (cachedSnapshot) {
+            deps.sendJson(res, 200, cachedSnapshot);
+            return;
+        }
+        const bundle = await buildSnapshotBundle(query, headerScope);
+        const parsed = parseSnapshotQuery(query, headerScope);
+        deps.writeSnapshotResponseCache(snapshotCacheKey, bundle.payload);
+        deps.writeSnapshotResponseCache("live-snapshot", bundle.payload);
+        deps.writeSnapshotResponseCache(snapshotAliasKey("live-snapshot", parsed.projectId), bundle.payload);
+        deps.sendJson(res, 200, bundle.payload);
+    }
+    async function renderSnapshotV2(path, query, res, headerScope) {
+        if (!validateWorkspaceScope(query, res, "live.snapshot-v2.validation", headerScope))
+            return;
+        const snapshotCacheKey = `${path}?${query.toString()}`;
+        const cachedSnapshot = deps.readSnapshotResponseCache(snapshotCacheKey);
+        if (cachedSnapshot) {
+            deps.sendJson(res, 200, cachedSnapshot);
+            return;
+        }
+        const bundle = await buildSnapshotBundle(query, headerScope);
+        const parsed = parseSnapshotQuery(query, headerScope);
+        const payload = {
+            ...bundle.v2,
+            sessions: bundle.payload.sessions,
+            activity: bundle.payload.activity,
+            handoffs: bundle.payload.handoffs,
+            decisions: bundle.payload.decisions,
+            sliceRuns: bundle.payload.sliceRuns,
+            agents: bundle.payload.agents,
+            runtimeInstances: bundle.payload.runtimeInstances,
+            outbox: bundle.payload.outbox,
+            chat: bundle.payload.chat,
+            degraded: bundle.payload.degraded,
+        };
         deps.writeSnapshotResponseCache(snapshotCacheKey, payload);
+        deps.writeSnapshotResponseCache("live-snapshot-v2", payload);
+        deps.writeSnapshotResponseCache(snapshotAliasKey("live-snapshot-v2", parsed.projectId), payload);
         deps.sendJson(res, 200, payload);
     }
-    router.add("GET", "dashboard-bundle", async ({ path, query, res }) => renderSnapshot(path, query, res), "Live dashboard bundle");
-    router.add("HEAD", "dashboard-bundle", async ({ path, query, res }) => renderSnapshot(path, query, res), "Live dashboard bundle (HEAD)");
-    router.add("GET", "live/snapshot", async ({ path, query, res }) => renderSnapshot(path, query, res), "Live snapshot");
-    router.add("HEAD", "live/snapshot", async ({ path, query, res }) => renderSnapshot(path, query, res), "Live snapshot (HEAD)");
+    async function renderSliceNarrative(path, query, res, headerScope) {
+        if (!validateWorkspaceScope(query, res, "live.snapshot.slice-narrative.validation", headerScope))
+            return;
+        const narrativeMatch = path.match(/^slices\/([^/]+)\/narrative$/);
+        const timelineMatch = path.match(/^slices\/([^/]+)\/timeline$/);
+        const match = narrativeMatch ?? timelineMatch;
+        if (!match) {
+            deps.sendJson(res, 404, { error: "Unknown API endpoint" });
+            return;
+        }
+        const sliceRunId = decodeURIComponent(match[1]).trim();
+        if (!sliceRunId) {
+            deps.sendJson(res, 400, { error: "sliceRunId is required." });
+            return;
+        }
+        const bundle = await buildSnapshotBundle(query, headerScope);
+        const narrative = findSliceNarrative(bundle.v2.timelineNarrative, sliceRunId);
+        const projection = bundle.v2.projections.find((entry) => entry.sliceRunId === sliceRunId) ?? null;
+        if (!narrative || !projection) {
+            deps.sendJson(res, 404, { error: "Slice narrative not found." });
+            return;
+        }
+        const chronology = bundle.payload.activity
+            .filter((item) => {
+            const activitySliceRunId = resolveActivitySliceRunId(item);
+            if (activitySliceRunId === sliceRunId)
+                return true;
+            if (projection.runId && item.runId === projection.runId)
+                return true;
+            return false;
+        })
+            .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))
+            .map((item) => ({
+            id: item.id,
+            timestamp: item.timestamp,
+            type: item.type,
+            title: item.title,
+            summary: item.summary ?? item.description ?? null,
+            metadata: item.metadata ?? null,
+        }));
+        deps.sendJson(res, 200, {
+            ok: true,
+            sliceRunId,
+            narrative,
+            projection,
+            chronology,
+        });
+    }
+    async function renderSessionDetailV2(path, query, res, headerScope) {
+        if (!validateWorkspaceScope(query, res, "live.snapshot.session-detail.validation", headerScope))
+            return;
+        const detailMatch = path.match(/^sessions\/([^/]+)\/detail-v2$/);
+        if (!detailMatch) {
+            deps.sendJson(res, 404, { error: "Unknown API endpoint" });
+            return;
+        }
+        const sessionId = decodeURIComponent(detailMatch[1]).trim();
+        if (!sessionId) {
+            deps.sendJson(res, 400, { error: "sessionId is required." });
+            return;
+        }
+        const bundle = await buildSnapshotBundle(query, headerScope);
+        const projection = findSessionDetailProjection(bundle.v2.projections, sessionId);
+        if (!projection) {
+            deps.sendJson(res, 404, { error: "Session detail not found." });
+            return;
+        }
+        const narrative = findSliceNarrative(bundle.v2.timelineNarrative, projection.sliceRunId);
+        const chronology = bundle.payload.activity
+            .filter((item) => {
+            const activitySliceRunId = resolveActivitySliceRunId(item);
+            if (activitySliceRunId === projection.sliceRunId)
+                return true;
+            if (projection.runId && item.runId === projection.runId)
+                return true;
+            if (item.runId && item.runId === sessionId)
+                return true;
+            return false;
+        })
+            .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))
+            .map((item) => ({
+            id: item.id,
+            timestamp: item.timestamp,
+            type: item.type,
+            title: item.title,
+            summary: item.summary ?? item.description ?? null,
+            metadata: item.metadata ?? null,
+        }));
+        deps.sendJson(res, 200, {
+            ok: true,
+            sessionId,
+            activeSliceSummary: projection,
+            initiativeBreakdown: {
+                initiativeIds: projection.lineage.initiativeIds,
+                initiativeTitles: projection.lineage.initiativeTitles,
+                workstreamIds: projection.lineage.workstreamIds,
+                workstreamTitles: projection.lineage.workstreamTitles,
+                taskIds: projection.lineage.taskIds,
+                milestoneIds: projection.lineage.milestoneIds,
+                iwmtIds: projection.lineage.iwmtIds,
+            },
+            progressModel: {
+                lifecycleState: projection.lifecycleState,
+                outcomeState: projection.outcomeState,
+                confidence: projection.confidence,
+                statusExplainer: projection.statusExplainer,
+            },
+            artifactBundle: projection.artifacts,
+            decisionAction: projection.actionContract,
+            chronology,
+            narrative,
+        });
+    }
+    async function executeSliceAction(path, query, req, res, headerScope) {
+        if (!validateWorkspaceScope(query, res, "live.snapshot.slice-action.validation", headerScope))
+            return;
+        const actionMatch = path.match(/^slices\/([^/]+)\/actions\/([^/]+)$/);
+        if (!actionMatch) {
+            deps.sendJson(res, 404, { error: "Unknown API endpoint" });
+            return;
+        }
+        const sliceRunId = decodeURIComponent(actionMatch[1]).trim();
+        const requestedAction = decodeURIComponent(actionMatch[2]).trim();
+        const actionType = normalizeDecisionActionType(requestedAction);
+        if (!sliceRunId) {
+            deps.sendJson(res, 400, { error: "sliceRunId is required." });
+            return;
+        }
+        if (!actionType) {
+            deps.sendJson(res, 400, {
+                error: "Action type is required.",
+            });
+            return;
+        }
+        const payload = typeof deps.parseJsonRequest === "function"
+            ? await deps.parseJsonRequest(req)
+            : {};
+        const note = pickString(payload, ["note", "context", "reason"]);
+        const optionId = pickString(payload, ["option_id", "optionId"]);
+        const bundle = await buildSnapshotBundle(query, headerScope);
+        const projection = bundle.v2.projections.find((entry) => entry.sliceRunId === sliceRunId) ?? null;
+        if (!projection) {
+            deps.sendJson(res, 404, { error: "Slice projection not found." });
+            return;
+        }
+        const declaredAction = normalizeDecisionActionType(projection.actionContract?.actionType ?? null);
+        if (declaredAction && declaredAction !== actionType && !(declaredAction === "open_artifact" && actionType === "open_artifact")) {
+            deps.sendJson(res, 409, {
+                error: "Action does not match current slice state.",
+                expectedAction: declaredAction,
+                requestedAction: actionType,
+            });
+            return;
+        }
+        if (actionType === "open_artifact") {
+            const artifact = projection.artifacts[0] ?? null;
+            if (!artifact) {
+                deps.sendJson(res, 409, { error: "No artifact is available for this slice." });
+                return;
+            }
+            deps.sendJson(res, 200, {
+                ok: true,
+                action: "open_artifact",
+                sliceRunId,
+                artifact,
+            });
+            return;
+        }
+        if (actionType === "retry" ||
+            actionType === "resume" ||
+            actionType === "start") {
+            if (typeof deps.runAction !== "function") {
+                deps.sendJson(res, 501, { error: "Run actions are not configured." });
+                return;
+            }
+            const runId = projection.runId ?? projection.sliceRunId;
+            const result = await deps.runAction(runId, "resume", {
+                reason: note ?? `slice_action:${actionType}`,
+            });
+            deps.sendJson(res, 200, {
+                ok: true,
+                action: actionType,
+                mappedAction: "resume",
+                sliceRunId,
+                runId,
+                result,
+            });
+            return;
+        }
+        if (actionType === "approve" || actionType === "reject") {
+            if (typeof deps.bulkDecideDecisions !== "function") {
+                deps.sendJson(res, 501, { error: "Decision actions are not configured." });
+                return;
+            }
+            const decisionAction = actionType === "approve" ? "approve" : "reject";
+            const decisionIdsFromBody = Array.isArray(payload.decisionIds)
+                ? payload.decisionIds
+                    .map((value) => (typeof value === "string" ? value.trim() : ""))
+                    .filter(Boolean)
+                : [];
+            const singleDecisionId = pickString(payload, ["decisionId", "decision_id"]);
+            const decisionIds = Array.from(new Set([
+                ...decisionIdsFromBody,
+                ...(singleDecisionId ? [singleDecisionId] : []),
+                ...resolveDecisionIdsForSlice(bundle.decisionsRaw, sliceRunId),
+            ]));
+            if (decisionIds.length === 0) {
+                deps.sendJson(res, 400, {
+                    error: "No matching pending decision was found for this slice.",
+                });
+                return;
+            }
+            const results = await deps.bulkDecideDecisions(decisionIds, decisionAction, {
+                note: note ?? undefined,
+                optionId: optionId ?? undefined,
+            });
+            const updated = results.filter((entry) => entry.ok === true).length;
+            const resolvedIds = results
+                .map((entry, index) => {
+                if (entry.ok !== true)
+                    return null;
+                if (typeof entry.id === "string" && entry.id.trim().length > 0) {
+                    return entry.id.trim();
+                }
+                return decisionIds[index] ?? null;
+            })
+                .filter((id) => typeof id === "string" && id.length > 0);
+            if (updated > 0 && typeof deps.emitDecisionResolvedActivity === "function") {
+                try {
+                    await deps.emitDecisionResolvedActivity({
+                        ids: resolvedIds.length > 0 ? resolvedIds : decisionIds,
+                        action: decisionAction,
+                        note: note ?? null,
+                        optionId: optionId ?? null,
+                        sliceRunId,
+                        initiativeId: projection.lineage.initiativeIds[0] ?? null,
+                    });
+                }
+                catch {
+                    // best effort; mutation already completed
+                }
+            }
+            deps.sendJson(res, updated > 0 ? 200 : 207, {
+                ok: updated > 0,
+                action: decisionAction,
+                sliceRunId,
+                requested: decisionIds.length,
+                updated,
+                failed: decisionIds.length - updated,
+                results,
+            });
+            return;
+        }
+        if (actionType === "provide_context") {
+            deps.sendJson(res, 200, {
+                ok: true,
+                action: "provide_context",
+                sliceRunId,
+                note: note ?? null,
+                message: note
+                    ? "Context captured for this slice."
+                    : "No note submitted. Provide a note to attach additional context.",
+            });
+            return;
+        }
+        deps.sendJson(res, 400, {
+            error: "Unsupported action type.",
+            actionType,
+            supported: [
+                "approve",
+                "reject",
+                "retry",
+                "resume",
+                "start",
+                "open_artifact",
+                "provide_context",
+            ],
+            knownActionTypes: KNOWN_DECISION_ACTION_TYPES,
+        });
+    }
+    router.add("GET", "dashboard-bundle", async ({ path, query, res, req }) => renderSnapshot(path, query, res, headerScopeFromRequest(req)), "Live dashboard bundle");
+    router.add("HEAD", "dashboard-bundle", async ({ path, query, res, req }) => renderSnapshot(path, query, res, headerScopeFromRequest(req)), "Live dashboard bundle (HEAD)");
+    router.add("GET", "live/snapshot", async ({ path, query, res, req }) => renderSnapshot(path, query, res, headerScopeFromRequest(req)), "Live snapshot");
+    router.add("HEAD", "live/snapshot", async ({ path, query, res, req }) => renderSnapshot(path, query, res, headerScopeFromRequest(req)), "Live snapshot (HEAD)");
+    router.add("GET", "live/snapshot-v2", async ({ path, query, res, req }) => renderSnapshotV2(path, query, res, headerScopeFromRequest(req)), "Live snapshot (v2 projections)");
+    router.add("HEAD", "live/snapshot-v2", async ({ path, query, res, req }) => renderSnapshotV2(path, query, res, headerScopeFromRequest(req)), "Live snapshot (v2 projections, HEAD)");
+    router.add("GET", "slices/*", async ({ path, query, res, req }) => renderSliceNarrative(path, query, res, headerScopeFromRequest(req)), "Slice narrative/timeline projections");
+    router.add("HEAD", "slices/*", async ({ path, query, res, req }) => renderSliceNarrative(path, query, res, headerScopeFromRequest(req)), "Slice narrative/timeline projections (HEAD)");
+    router.add("POST", "slices/*", async ({ path, query, req, res }) => executeSliceAction(path, query, req, res, headerScopeFromRequest(req)), "Slice action contracts");
+    router.add("GET", "sessions/*", async ({ path, query, res, req }) => renderSessionDetailV2(path, query, res, headerScopeFromRequest(req)), "Session detail (v2 projections)");
+    router.add("HEAD", "sessions/*", async ({ path, query, res, req }) => renderSessionDetailV2(path, query, res, headerScopeFromRequest(req)), "Session detail (v2 projections, HEAD)");
 }