@tea-agent/loop-agent 0.44.0-next.1 → 0.44.0-next.10

package/dist/worker/console/chat/routes.js

@@ -15,18 +15,18 @@
 import { randomUUID } from "node:crypto";
 import { access } from "node:fs/promises";
 import { parseAssistantContent } from "./assistant-content.js";
-import { OPERATOR_CHAT_ALLOWED_TOOLS, OPERATOR_CHAT_DENIED_TOOLS, OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS, } from "./tools.js";
+import { OPERATOR_CHAT_ALLOWED_TOOLS, OPERATOR_CHAT_DENIED_TOOLS, OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS, OPERATOR_CHAT_SQL_TOOL_CAPABILITIES, } from "./tools.js";
 import { InvalidChatSessionModeError, SESSION_MODE_ACTION_DENIED_CODE, SESSION_MODE_ACTION_DENIED_MESSAGE, SESSION_MODE_IMMUTABLE_CODE, UnknownChatSessionModeError, isWorkflowSessionMode, parseCreateSessionMode, readStoredSessionMode, shouldAcceptOperatorSnapshot, } from "./session-mode.js";
 import { buildModelCallableToolSchemas } from "./tool-adapter.js";
 import { cleanChatTitle, acceptedOperationIdFromResult, isBlankChatSession } from "./session-store.js";
-import { hashChatTurnPayload, projectChatToolEventPayload, projectCompactSnapshot, } from "./chat-event-store.js";
+import { projectUserTurnOutline } from "./user-turn-outline.js";
+import { hashChatTurnPayload, projectChatToolEventPayload, projectUnknownChatEventPayload, projectCompactSnapshot, } from "./chat-event-store.js";
 import { projectDeferredTurnSummary, projectDeferredTurnSummaries, } from "./deferred-turn.js";
 import { THINKING_LEVELS, RuntimeSnapshotUnavailableError, } from "./pi-runtime.js";
 import { ResourcePreferencesError, setSkillAutoInvocationPreference, } from "./resource-preferences-store.js";
 import { ComposerDraftStore } from "./composer-draft-store.js";
-import { walkRepoFiles } from "./repo-walk.js";
-import { isSensitivePath, scrubSecrets } from "./explore-tools.js";
-import { listRepoDirectory, matchRepoHtmlPreviewRoute, readRepoHtmlAsset, readRepoPreview, RepoBrowserError, } from "./repo-browser.js";
+import { scrubSecrets } from "./explore-tools.js";
+import { listChatFilePalette, listRepoDirectory, matchRepoHtmlPreviewRoute, readRepoHtmlAsset, readRepoPreview, RepoBrowserError, } from "./repo-browser.js";
 import { projectRuntimeContext } from "./runtime-context.js";
 import { patchModelsConfig, readModelsConfig, readPackageInventory, } from "./pi-console-config.js";
 import { ChatInterviewAdapter, projectChatInterviewState, } from "./interview-adapter.js";
@@ -36,6 +36,7 @@ import { dispatchOperatorAction } from "../operator-actions.js";
 import { makeHumanGateCard, } from "./human-gate-card.js";
 import { ContractApplyReceiptStore } from "./contract-apply-receipt-store.js";
 import { projectTaskContext } from "./context-panel.js";
+import { deriveContextInsights, estimateTokensFromText, } from "./context-insights.js";
 import { deriveChatSessionTelemetry, deriveChatTurnTelemetry } from "./session-stats.js";
 import { contractApplyPayloadHash, issueHumanGateToken, verifyHumanGateToken, } from "../human-gate-token.js";
 import { sendJson } from "../routes.js";
@@ -49,6 +50,7 @@ import { TerminalSessionRegistry } from "./terminal-sessions.js";
 import { handleTerminalRequest } from "./terminal-routes.js";
 import { handleScmRequest } from "./scm-routes.js";
 import { handleBrowserRequest } from "./browser-routes.js";
+import { DbConnectionError } from "./db-connections.js";
 function projectBrowserChatSession(record) {
     const { telemetrySessionId, ...projected } = record;
     void telemetrySessionId;
@@ -64,6 +66,14 @@ function reopenInitFromRecord(record) {
         sessionMode: record.sessionMode,
     };
 }
+function workspaceProjectionFromRecord(record) {
+    return {
+        sessionMode: record.sessionMode,
+        ...(record.modelProvider ? { modelProvider: record.modelProvider } : {}),
+        ...(record.modelId ? { modelId: record.modelId } : {}),
+        ...(record.thinkingLevel ? { thinkingLevel: record.thinkingLevel } : {}),
+    };
+}
 async function readChatSessionMode(deps, sessionId) {
     let record;
     try {
@@ -196,6 +206,16 @@ export function projectStoredMessagesWithEventOrder(messages, events) {
             ...(finish
                 ? { finishedSeq: finish.seq, finishedAt: finish.at }
                 : {}),
+            ...(start && typeof start.data.step === "number"
+                ? { step: start.data.step }
+                : {}),
+            ...(start &&
+                typeof start.data.parentToolCallId ===
+                    "string"
+                ? {
+                    parentToolCallId: start.data.parentToolCallId,
+                }
+                : {}),
         };
     });
 }
@@ -212,6 +232,43 @@ function turnSummary(turn) {
         abortRequestedAt: turn.abortRequestedAt ?? null,
     };
 }
+function turnStateSummary(turn) {
+    return {
+        turnId: turn.turnId,
+        state: turn.state === "queued" ? "running" : turn.state,
+    };
+}
+function turnStatesForIds(events, sessionId, turnIds) {
+    const projected = new Map();
+    for (const turnId of turnIds) {
+        if (!turnId || projected.has(turnId))
+            continue;
+        const turn = events.getTurn(sessionId, turnId);
+        if (turn)
+            projected.set(turnId, turnStateSummary(turn));
+    }
+    return [...projected.values()];
+}
+const MAX_STATE_QUERY_TURN_IDS = 8;
+const MAX_STATE_QUERY_TURN_ID_CHARS = 240;
+function requestedStateTurnIds(req) {
+    const result = [];
+    const seen = new Set();
+    const url = new URL(req.url ?? "/", "http://localhost");
+    for (const raw of url.searchParams.getAll("turnId")) {
+        const turnId = raw.trim();
+        if (!turnId ||
+            turnId.length > MAX_STATE_QUERY_TURN_ID_CHARS ||
+            seen.has(turnId)) {
+            continue;
+        }
+        seen.add(turnId);
+        result.push(turnId);
+        if (result.length >= MAX_STATE_QUERY_TURN_IDS)
+            break;
+    }
+    return result;
+}
 function isTerminalTurnState(state) {
     return state === "settled" || state === "aborted" || state === "failed";
 }
@@ -242,10 +299,99 @@ function writeChatSse(res, event) {
 /** Map a runtime ChatTurnEvent to the persisted event-store partial.
  *
  * Returns undefined for heartbeat (not persisted — keep-alive only). */
-function turnEventToStorePartial(event) {
+export function turnEventToStorePartial(event) {
     switch (event.type) {
         case "agent_start":
             return { kind: "agent_start", data: {} };
+        case "step_start":
+        case "step_end":
+            return {
+                kind: event.type,
+                data: {
+                    step: Number(event.step ?? 1),
+                    ...(event.type === "step_end"
+                        ? { outcome: String(event.outcome ?? "completed") }
+                        : {}),
+                },
+            };
+        case "model_retry":
+            {
+                const retryState = event.state === "completed" || event.state === "failed"
+                    ? event.state
+                    : "scheduled";
+                return {
+                    kind: "model_retry",
+                    data: {
+                        step: Number(event.step ?? 1),
+                        attempt: Number(event.attempt ?? 1),
+                        ...(typeof event.maxAttempts === "number"
+                            ? { maxAttempts: event.maxAttempts }
+                            : {}),
+                        ...(typeof event.delayMs === "number" ? { delayMs: event.delayMs } : {}),
+                        ...(typeof event.errorMessage === "string"
+                            ? { errorMessage: event.errorMessage }
+                            : {}),
+                        state: retryState,
+                        ...(typeof event.success === "boolean" ? { success: event.success } : {}),
+                    },
+                };
+            }
+        case "turn_max_tokens":
+            return {
+                kind: "turn_max_tokens",
+                data: { step: Number(event.step ?? 1) },
+            };
+        case "turn_error":
+            return {
+                kind: "turn_error",
+                data: {
+                    ...(typeof event.step === "number" ? { step: event.step } : {}),
+                    ...(typeof event.code === "string" ? { code: event.code } : {}),
+                    message: String(event.message ?? "模型请求失败"),
+                },
+            };
+        case "request_context":
+            return {
+                kind: "request_context",
+                data: {
+                    requestId: String(event.requestId ?? ""),
+                    step: Number(event.step ?? 1),
+                    ...(event.model && typeof event.model === "object"
+                        ? { model: event.model }
+                        : {}),
+                    ...(typeof event.thinkingLevel === "string"
+                        ? { thinkingLevel: event.thinkingLevel }
+                        : {}),
+                    systemPromptHash: String(event.systemPromptHash ?? ""),
+                    systemPromptChars: Number(event.systemPromptChars ?? 0),
+                    activeTools: Array.isArray(event.activeTools) ? event.activeTools : [],
+                    inputChars: Number(event.inputChars ?? 0),
+                    imageCount: Number(event.imageCount ?? 0),
+                    sources: Array.isArray(event.sources) ? event.sources : [],
+                },
+            };
+        case "command":
+            return {
+                kind: "command",
+                data: {
+                    commandId: String(event.commandId ?? ""),
+                    name: String(event.name ?? "unknown"),
+                    ...(typeof event.argsPreview === "string"
+                        ? { argsPreview: event.argsPreview }
+                        : {}),
+                    ...(typeof event.action === "string" ? { action: event.action } : {}),
+                    outcome: event.outcome === "failed" ? "failed" : "completed",
+                    ...(typeof event.message === "string" ? { message: event.message } : {}),
+                },
+            };
+        case "unknown":
+            return {
+                kind: "unknown",
+                data: projectUnknownChatEventPayload({
+                    eventType: String(event.eventType ?? "unknown"),
+                    value: event.value,
+                }),
+            };
         case "message_update":
         case "message_end": {
             const content = parseAssistantContent(event.content);
@@ -290,6 +436,10 @@ function turnEventToStorePartial(event) {
                         event.messageId
                         ? { messageId: event.messageId }
                         : {}),
+                    ...(typeof event.step === "number" ? { step: event.step } : {}),
+                    ...(typeof event.stopReason === "string"
+                        ? { stopReason: event.stopReason }
+                        : {}),
                 },
             };
         }
@@ -303,6 +453,24 @@ function turnEventToStorePartial(event) {
                     toolCallId: String(event.toolCallId ?? ""),
                     toolName: String(event.toolName ?? ""),
                     value: event.args,
+                    ...(typeof event.step === "number" ? { step: event.step } : {}),
+                    ...(typeof event.parentToolCallId === "string"
+                        ? { parentToolCallId: event.parentToolCallId }
+                        : {}),
+                }),
+            };
+        case "tool_update":
+            return {
+                kind: "tool_update",
+                data: projectChatToolEventPayload({
+                    kind: "tool_update",
+                    toolCallId: String(event.toolCallId ?? ""),
+                    toolName: String(event.toolName ?? ""),
+                    value: event.partialResult,
+                    ...(typeof event.step === "number" ? { step: event.step } : {}),
+                    ...(typeof event.parentToolCallId === "string"
+                        ? { parentToolCallId: event.parentToolCallId }
+                        : {}),
                 }),
             };
         case "tool_result": {
@@ -317,6 +485,10 @@ function turnEventToStorePartial(event) {
                     toolName: String(event.toolName ?? ""),
                     value: event.result,
                     isError: Boolean(event.isError),
+                    ...(typeof event.step === "number" ? { step: event.step } : {}),
+                    ...(typeof event.parentToolCallId === "string"
+                        ? { parentToolCallId: event.parentToolCallId }
+                        : {}),
                     ...(resultOperationId ? { operationId: resultOperationId } : {}),
                 }),
             };
@@ -606,6 +778,7 @@ export async function handleChatCapabilities(_req, res, deps) {
         deniedTools: OPERATOR_CHAT_DENIED_TOOLS,
         deniedOperatorActions: OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS,
         tools: toolSchemas,
+        builtinCustomTools: OPERATOR_CHAT_SQL_TOOL_CAPABILITIES,
         builtinSubagents: [
             {
                 toolId: "Agent",
@@ -803,25 +976,47 @@ export async function handleForkChatSession(req, res, deps, sourceSessionId) {
         });
         return;
     }
+    let forkedHandle;
+    let forkPersisted = false;
     try {
+        const body = await readJsonBody(req);
+        const throughMessageId = typeof body.throughMessageId === "string" && body.throughMessageId.trim()
+            ? body.throughMessageId.trim()
+            : undefined;
+        const throughUserMessageIndex = throughMessageId
+            ? source.messages
+                .filter((message) => message.role === "user")
+                .findIndex((message) => message.id === throughMessageId)
+            : undefined;
+        if (throughMessageId && throughUserMessageIndex === -1) {
+            throw new Error("FORK_MESSAGE_NOT_FOUND");
+        }
         const handle = await deps.runtime.forkSession({
             sourceSessionFile: source.sessionFile ?? "",
             sessionMode: source.sessionMode,
             ...(source.modelProvider && source.modelId
                 ? { model: { provider: source.modelProvider, modelId: source.modelId } }
                 : {}),
+            ...(throughUserMessageIndex !== undefined
+                ? { throughUserMessageIndex }
+                : {}),
         });
+        forkedHandle = handle;
         await deps.store.forkFrom({
             sourceSessionId,
             targetSessionId: handle.sessionId,
             targetSessionFile: handle.sessionFile,
+            ...(throughMessageId ? { throughMessageId } : {}),
         });
+        forkPersisted = true;
         await deps.attachSession?.(handle.sessionId).catch(() => undefined);
-        const copied = deps.events.forkContextRefs({
-            sourceSessionId,
-            targetSessionId: handle.sessionId,
-            targetTurnId: `${handle.sessionId}:fork`,
-        });
+        const copied = throughMessageId
+            ? { copiedCount: 0 }
+            : deps.events.forkContextRefs({
+                sourceSessionId,
+                targetSessionId: handle.sessionId,
+                targetTurnId: `${handle.sessionId}:fork`,
+            });
         await deps.operationLinker.recoverSession(handle.sessionId);
         sendJson(res, 201, {
             ok: true,
@@ -835,6 +1030,12 @@ export async function handleForkChatSession(req, res, deps, sourceSessionId) {
         });
     }
     catch (error) {
+        if (forkedHandle && !forkPersisted) {
+            deps.runtime.dispose(forkedHandle.sessionId);
+            await deps.store
+                .discardUnownedSession(forkedHandle.sessionId, forkedHandle.sessionFile)
+                .catch(() => undefined);
+        }
         sendJson(res, 409, {
             ok: false,
             error: {
@@ -981,12 +1182,21 @@ export async function handleGetChatSession(_req, res, deps, sessionId) {
     const lastEvent = snapshot.at(-1);
     const activeTurn = deps.events.getActiveTurn(sessionId);
     const pendingQuestion = await deps.questionRegistry?.get(sessionId);
+    const sddSessionIdentity = deps.sddDataAlignment && (await deps.sddDataAlignment.isEligible())
+        ? { telemetrySessionId: record.telemetrySessionId ?? null }
+        : undefined;
+    const projectedMessages = projectStoredMessagesWithEventOrder(messagePage.messages, snapshot);
+    const turnStates = turnStatesForIds(deps.events, sessionId, [
+        ...projectedMessages.map((message) => message.turnId),
+        ...snapshot.map((event) => event.turnId),
+    ]);
     sendJson(res, 200, {
         ok: true,
         eventEpoch: deps.events.epoch(sessionId),
         session: {
             ...projectBrowserChatSession(record),
-            messages: projectStoredMessagesWithEventOrder(messagePage.messages, snapshot),
+            messages: projectedMessages,
+            turnStates,
             composerDraft,
             activeTurnId: activeTurn?.turnId,
             turnPhase: activeTurn
@@ -1006,6 +1216,10 @@ export async function handleGetChatSession(_req, res, deps, sessionId) {
         sessionStats: telemetry.stats,
         usage: telemetry.usage,
         turnTelemetry: deriveChatTurnTelemetry(snapshot),
+        userTurnOutline: projectUserTurnOutline(record.messages ?? []),
+        ...(sddSessionIdentity
+            ? { sddDataAlignment: sddSessionIdentity }
+            : {}),
         contextPressure: typeof deps.runtime.getContextPressureTelemetry === "function"
             ? deps.runtime.getContextPressureTelemetry(sessionId)
             : undefined,
@@ -1021,6 +1235,16 @@ export async function handleGetChatSession(_req, res, deps, sessionId) {
             turnId: event.turnId,
             data: event.data,
         })),
+        conversationEvents: snapshot.filter((event) => [
+            "step_start",
+            "step_end",
+            "model_retry",
+            "turn_error",
+            "turn_max_tokens",
+            "request_context",
+            "command",
+            "unknown",
+        ].includes(event.kind)),
         lastEventId: lastEvent?.eventId ?? null,
         lastEventSeq: lastEvent?.seq ?? 0,
     });
@@ -1271,7 +1495,14 @@ function emitUserMessageEvent(deps, sessionId, turnId, userMessage, clientReques
         data: {
             ...(clientRequestId ? { clientRequestId } : {}),
             ...(steering ? { steering: true } : {}),
-            message: { id: userMessage.id, text: userMessage.text, at: userMessage.at },
+            message: {
+                id: userMessage.id,
+                text: userMessage.text,
+                at: userMessage.at,
+                ...(userMessage.attachments?.length
+                    ? { attachments: userMessage.attachments }
+                    : {}),
+            },
         },
     });
 }
@@ -1279,7 +1510,7 @@ function emitUserMessageEvent(deps, sessionId, turnId, userMessage, clientReques
  *  get_state equivalent): exposes the active turn + the latest turn's durable
  *  outcome WITHOUT the full message payload, so the UI can poll it on an
  *  interval / visibility / online without paying for session detail. */
-export async function handleGetChatSessionState(_req, res, deps, sessionId) {
+export async function handleGetChatSessionState(req, res, deps, sessionId) {
     const record = await deps.store.get(sessionId);
     if (!record) {
         sendJson(res, 404, {
@@ -1310,9 +1541,15 @@ export async function handleGetChatSessionState(_req, res, deps, sessionId) {
         : runtimeBusy
             ? "running"
             : "idle";
+    const turnStates = turnStatesForIds(deps.events, sessionId, [
+        active?.turnId,
+        latest?.turnId,
+        ...requestedStateTurnIds(req),
+    ]);
     sendJson(res, 200, {
         ok: true,
         state: {
+            turnStates,
             // Legacy flat fields retained for older clients.
             activeTurnId: active?.turnId ?? null,
             activeTurnState: active?.state ?? null,
@@ -2669,6 +2906,7 @@ export async function handleChatEventsStream(req, res, deps, sessionId) {
         kind: "stream_ready",
         sessionId,
         epoch: deps.events.epoch(sessionId),
+        lastSeq: deps.events.latestSeq(sessionId),
         latestEventId: retainedTail?.eventId ?? null,
     });
     let closed = false;
@@ -2890,28 +3128,8 @@ async function handlePiConfig(req, res, deps, resource) {
 async function handleChatFiles(res, deps, sessionId, query) {
     if (!(await requireChatSession(res, deps, sessionId)))
         return;
-    const q = query.trim().toLowerCase();
-    const walked = await walkRepoFiles(deps.appData.repoRoot, {
-        skipSensitive: true,
-        maxFiles: 5000,
-        includeDirs: true,
-    });
-    const entries = walked
-        .filter((entry) => !isSensitivePath(entry.repoRelative) &&
-        (!q || entry.repoRelative.toLowerCase().includes(q)))
-        .sort((a, b) => {
-        const aDir = a.repoRelative.endsWith("/");
-        const bDir = b.repoRelative.endsWith("/");
-        if (aDir !== bDir)
-            return aDir ? -1 : 1;
-        return a.repoRelative.localeCompare(b.repoRelative);
-    })
-        .slice(0, 50)
-        .map((entry) => ({
-        path: entry.repoRelative,
-        isDir: entry.repoRelative.endsWith("/"),
-    }));
-    sendJson(res, 200, { ok: true, files: entries });
+    const files = await listChatFilePalette(deps.appData.repoRoot, query);
+    sendJson(res, 200, { ok: true, files });
 }
 export async function handleChatCommands(res, deps, sessionId) {
     try {
@@ -2973,7 +3191,32 @@ async function handleSddBingo(req, res, deps, sessionId) {
             throw new SddDataAlignmentError("SDD_INVALID_SKILL_NAME", "请求体只允许 skillName 字段", 400);
         }
         const result = await deps.sddDataAlignment.report(sessionId, body.skillName);
-        sendJson(res, 200, { ok: true, skillName: result.skillName });
+        const turnId = deps.events.latestTurnId(sessionId) ?? `${sessionId}:operator-action`;
+        deps.events.append(sessionId, turnId, {
+            kind: "operator-action",
+            data: {
+                schemaVersion: 1,
+                action: "sdd-bingo",
+                skillName: result.skillName,
+                telemetrySessionId: result.telemetrySessionId,
+            },
+        });
+        deps.events.append(sessionId, `${sessionId}:command:${result.telemetrySessionId}`, {
+            kind: "command",
+            data: {
+                commandId: `sdd-bingo:${result.telemetrySessionId}`,
+                name: "sdd-bingo",
+                ...(result.skillName ? { argsPreview: result.skillName } : {}),
+                action: "sdd-bingo",
+                outcome: "completed",
+                message: `Session: ${result.telemetrySessionId}`,
+            },
+        });
+        sendJson(res, 200, {
+            ok: true,
+            skillName: result.skillName,
+            telemetrySessionId: result.telemetrySessionId,
+        });
     }
     catch (error) {
         if (error instanceof SddDataAlignmentError) {
@@ -2990,20 +3233,25 @@ async function handleSddBingo(req, res, deps, sessionId) {
     }
 }
 export async function handleRuntimeContext(res, deps, sessionId) {
-    const ensured = await ensureActiveSession(deps, sessionId);
-    if (!ensured.ok) {
-        sendJson(res, ensured.status, { ok: false, error: { code: ensured.code, message: ensured.message } });
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        sendJson(res, 404, {
+            ok: false,
+            error: {
+                code: "PI_SESSION_NOT_FOUND",
+                message: `chat session not found: ${sessionId}`,
+            },
+        });
         return;
     }
-    // AC-03: system prompt comes from the REAL Pi session (agent.state.systemPrompt
-    // fallback chain); resources come from that session's ResourceLoader. The raw
-    // prompt stays server-side; the browser only ever receives the scrubbed +
-    // length-limited projection. RF-02: a critical projection failure is 503
-    // PI_RUNTIME_UNAVAILABLE — never a 500 leak or a fake-empty context.
+    // Live Agent is preferred. Cold inspect uses workspace ResourceLoader /
+    // ModelRuntime without SessionManager.open(jsonl); prompt still reopens.
+    // RF-02: a critical projection failure is 503 PI_RUNTIME_UNAVAILABLE.
     let snapshot;
     try {
         snapshot = await deps.runtime.getRuntimeSnapshot(sessionId, {
             includeRaw: true,
+            workspaceProjection: workspaceProjectionFromRecord(record),
         });
     }
     catch (error) {
@@ -3053,19 +3301,94 @@ export async function handleRuntimeContext(res, deps, sessionId) {
         }),
     });
 }
+/**
+ * GET /sessions/:id/context-insights: dsh-context parity dashboard projection.
+ * Folds the persisted event ring (works for idle/restored sessions) and, when
+ * the Pi session is live, anchors the estimate with the runtime snapshot's
+ * system-prompt size + active tool count. Read-only; never fabricates payload
+ * text beyond the bounded previews already stored on the ring.
+ */
+export async function handleContextInsights(res, deps, sessionId) {
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        sendJson(res, 404, {
+            ok: false,
+            error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` },
+        });
+        return;
+    }
+    await deps.operationLinker.recoverSession(sessionId);
+    const snapshot = deps.events.snapshot(sessionId);
+    let systemPromptChars;
+    let systemPromptPreview;
+    let activeTools;
+    let skillInjections;
+    try {
+        const runtimeSnapshot = await deps.runtime.getRuntimeSnapshot(sessionId, {
+            includeRaw: true,
+            workspaceProjection: workspaceProjectionFromRecord(record),
+        });
+        if (runtimeSnapshot) {
+            systemPromptChars = runtimeSnapshot.systemPrompt.characters;
+            const raw = runtimeSnapshot.systemPrompt.raw ??
+                runtimeSnapshot.systemPrompt.text;
+            if (typeof raw === "string" && raw) {
+                systemPromptPreview = raw.slice(0, 120_000);
+            }
+            activeTools = runtimeSnapshot.activeTools;
+            skillInjections = runtimeSnapshot.skills
+                .slice(0, 50)
+                .map((skill) => ({
+                name: skill.name,
+                tokens: estimateTokensFromText(skill.description ?? skill.name),
+            }));
+        }
+    }
+    catch {
+        // Insights are derived from the durable ring; a live-snapshot miss only
+        // drops the anchor figures / browser static categories, never the dashboard.
+    }
+    // Tool schemas: capabilities registry projection for whitelisted operator
+    // actions, plus Pi builtins active on this session.
+    const schemaTools = buildModelCallableToolSchemas().map((tool) => ({
+        id: tool.toolId,
+        description: tool.description,
+    }));
+    const activeSet = new Set((activeTools ?? []).map((t) => t.toLowerCase()));
+    const builtinTools = (activeTools ?? [])
+        .filter((name) => !schemaTools.some((t) => t.id === name))
+        .map((name) => ({ id: name, description: "" }));
+    const insights = deriveContextInsights(snapshot, {
+        sessionId,
+        ...(systemPromptChars !== undefined ? { systemPromptChars } : {}),
+        ...(systemPromptPreview !== undefined
+            ? { systemPromptPreview }
+            : {}),
+        tools: [...schemaTools, ...builtinTools],
+        ...(skillInjections ? { skillInjections } : {}),
+    });
+    sendJson(res, 200, { ok: true, insights });
+}
 // Exported for the direct handler-boundary tests (trace binding for
 // vt-route-model-errors); router dispatch behavior is unchanged.
 export async function handleModels(req, res, deps, sessionId) {
-    // AC-01/AC-06: models (and model/thinking mutation) requests reuse the same
-    // activation path. A missing/reopen-failed runtime is a STRUCTURED error —
-    // never a fabricated empty model list.
-    const ensured = await ensureActiveSession(deps, sessionId);
-    if (!ensured.ok) {
-        sendJson(res, ensured.status, { ok: false, error: { code: ensured.code, message: ensured.message } });
-        return;
-    }
     try {
         if ((req.method ?? "GET").toUpperCase() === "GET") {
+            // Catalog is workspace-scoped (models.json / ModelRuntime). Do not wait
+            // for Pi conversation reopen and do not start it here — prompt / reload
+            // / model mutation still reopen, and concurrent reopen would stall this
+            // cheap list on the single Node thread.
+            const record = await deps.store.get(sessionId);
+            if (!record) {
+                sendJson(res, 404, {
+                    ok: false,
+                    error: {
+                        code: "PI_SESSION_NOT_FOUND",
+                        message: `chat session not found: ${sessionId}`,
+                    },
+                });
+                return;
+            }
             let models;
             try {
                 models = await deps.runtime.listModels(sessionId);
@@ -3094,6 +3417,11 @@ export async function handleModels(req, res, deps, sessionId) {
             });
             return;
         }
+        const ensured = await ensureActiveSession(deps, sessionId);
+        if (!ensured.ok) {
+            sendJson(res, ensured.status, { ok: false, error: { code: ensured.code, message: ensured.message } });
+            return;
+        }
         const gate = gateMutation(req, deps);
         if (!gate.ok) {
             sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
@@ -3149,18 +3477,24 @@ async function requireChatSession(res, deps, sessionId) {
     });
     return false;
 }
-/**
- * Unified session activation (design §2.1 / AC-01): models, runtime snapshot,
- * reload and model/thinking mutation requests all flow through this path.
- *
- * - runtime already holds the session → ok;
- * - only a persisted record exists → reopen from record.sessionFile;
- * - no record / missing session file → 404 PI_SESSION_NOT_FOUND;
- * - SDK reopen failure → 503 PI_RUNTIME_UNAVAILABLE.
- *
- * Never fabricates a fresh session or an empty model list.
- */
+const ensureActiveSessionInFlight = new WeakMap();
 export async function ensureActiveSession(deps, sessionId) {
+    let bySession = ensureActiveSessionInFlight.get(deps);
+    if (!bySession) {
+        bySession = new Map();
+        ensureActiveSessionInFlight.set(deps, bySession);
+    }
+    const existing = bySession.get(sessionId);
+    if (existing)
+        return existing;
+    const pending = runEnsureActiveSession(deps, sessionId).finally(() => {
+        if (bySession.get(sessionId) === pending)
+            bySession.delete(sessionId);
+    });
+    bySession.set(sessionId, pending);
+    return pending;
+}
+async function runEnsureActiveSession(deps, sessionId) {
     // Wait for create-path materialization before treating the session as missing.
     if (typeof deps.runtime.ensureSessionReady === "function") {
         try {
@@ -3406,19 +3740,28 @@ export async function handleReloadSession(req, res, deps, sessionId) {
     });
 }
 /**
- * GET /sessions/:id/runtime-snapshot (AC-01): the unified live snapshot.
+ * GET /sessions/:id/runtime-snapshot (AC-01): live Agent when present,
+ * otherwise workspace ResourceLoader projection (no JSONL reopen).
  */
 export async function handleRuntimeSnapshot(_res, res, deps, sessionId) {
-    const ensured = await ensureActiveSession(deps, sessionId);
-    if (!ensured.ok) {
-        sendJson(res, ensured.status, { ok: false, error: { code: ensured.code, message: ensured.message } });
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        sendJson(res, 404, {
+            ok: false,
+            error: {
+                code: "PI_SESSION_NOT_FOUND",
+                message: `chat session not found: ${sessionId}`,
+            },
+        });
         return;
     }
     // RF-02: a critical snapshot projection failure is 503 PI_RUNTIME_UNAVAILABLE
     // — never a 200 fake-empty snapshot.
     let snapshot;
     try {
-        snapshot = await deps.runtime.getRuntimeSnapshot(sessionId);
+        snapshot = await deps.runtime.getRuntimeSnapshot(sessionId, {
+            workspaceProjection: workspaceProjectionFromRecord(record),
+        });
     }
     catch (error) {
         if (sendRuntimeUnavailable(res, error))
@@ -3901,7 +4244,7 @@ async function handleDagHumanGate(req, res, deps, sessionId, step) {
             : step === "confirm"
                 ? "confirmDagConfirmation"
                 : "runDag";
-        const result = await dispatchOperatorAction(ctx, {
+        const result = await dispatchOperatorAction({ ...ctx, chatSessionRef: sessionId }, {
             action,
             actionParams: body,
             clientRequestId: typeof body.clientRequestId === "string"
@@ -4241,7 +4584,14 @@ export async function handleChatMessages(res, deps, sessionId, url) {
             limit: Number.isFinite(limit) ? limit : 30,
             beforeId: url.searchParams.get("beforeId") ?? undefined,
         });
-        sendJson(res, 200, { ok: true, ...page });
+        const snapshot = deps.events.snapshot(sessionId);
+        const messages = projectStoredMessagesWithEventOrder(page.messages, snapshot);
+        sendJson(res, 200, {
+            ok: true,
+            ...page,
+            messages,
+            turnStates: turnStatesForIds(deps.events, sessionId, messages.map((message) => message.turnId)),
+        });
     }
     catch (error) {
         sendJson(res, 404, {
@@ -4253,6 +4603,23 @@ export async function handleChatMessages(res, deps, sessionId, url) {
         });
     }
 }
+export async function handleChatAttachment(res, deps, sessionId, attachmentId) {
+    const attachment = await deps.store.readAttachment(sessionId, attachmentId);
+    if (!attachment) {
+        sendJson(res, 404, {
+            ok: false,
+            error: { code: "NOT_FOUND", message: "chat attachment not found" },
+        });
+        return;
+    }
+    res.writeHead(200, {
+        "content-type": attachment.metadata.mimeType,
+        "content-length": String(attachment.bytes.length),
+        "cache-control": "private, max-age=31536000, immutable",
+        "x-content-type-options": "nosniff",
+    });
+    res.end(attachment.bytes);
+}
 /**
  * Dispatch a chat HTTP request. Returns true if handled.
  * Mounted under /api/operator/v1/chat/*.
@@ -4279,6 +4646,24 @@ export async function handleChatRequest(req, res, deps, pathname, workspaceScope
         throw error;
     }
 }
+function databaseConnectionInput(body, engine) {
+    return {
+        name: typeof body.name === "string" ? body.name : "",
+        engine,
+        ...(typeof body.path === "string" ? { path: body.path } : {}),
+        ...(body.mode === "parameters" || body.mode === "url-env" ? { mode: body.mode } : {}),
+        ...(typeof body.urlEnv === "string" ? { urlEnv: body.urlEnv } : {}),
+        ...(typeof body.host === "string" ? { host: body.host } : {}),
+        ...(typeof body.port === "number" ? { port: body.port } : {}),
+        ...(typeof body.database === "string" ? { database: body.database } : {}),
+        ...(typeof body.username === "string" ? { username: body.username } : {}),
+        ...(body.passwordMode === "runtime" || body.passwordMode === "environment" || body.passwordMode === "encrypted" ? { passwordMode: body.passwordMode } : {}),
+        ...(typeof body.passwordRef === "string" ? { passwordRef: body.passwordRef } : {}),
+        ...(typeof body.passwordEnv === "string" ? { passwordEnv: body.passwordEnv } : {}),
+        ...(typeof body.password === "string" ? { password: body.password } : {}),
+        ...(typeof body.ssl === "boolean" ? { ssl: body.ssl } : {}),
+    };
+}
 async function dispatchChatRequest(req, res, deps, pathname, workspaceScope) {
     // Terminal management API (model + Console UI shared PTY registry).
     if (await handleTerminalRequest(req, res, {
@@ -4358,6 +4743,117 @@ async function dispatchChatRequest(req, res, deps, pathname, workspaceScope) {
         await handleChatCapabilities(req, res, deps);
         return true;
     }
+    if (method === "GET" && pathname === "/api/operator/v1/chat/database-connections/export") {
+        sendJson(res, 200, { ok: true, document: deps.runtime.exportDatabaseConnections() });
+        return true;
+    }
+    if (method === "POST" && pathname === "/api/operator/v1/chat/database-connections/import") {
+        const gate = gateMutation(req, deps);
+        if (!gate.ok) {
+            sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+            return true;
+        }
+        try {
+            const body = await readJsonBody(req);
+            const conflict = body.conflict === "overwrite" ? "overwrite" : "skip";
+            const result = await deps.runtime.importDatabaseConnections(body.document, conflict);
+            sendJson(res, 200, { ok: true, result });
+        }
+        catch (error) {
+            const code = error instanceof DbConnectionError ? error.code : "DB_PERSISTENCE_ERROR";
+            const status = code === "DB_PERSISTENCE_ERROR" ? 500 : 400;
+            sendJson(res, status, { ok: false, error: { code, message: error instanceof Error ? error.message : String(error) } });
+        }
+        return true;
+    }
+    if (pathname === "/api/operator/v1/chat/database-connections" &&
+        (method === "GET" || method === "POST")) {
+        if (method === "GET") {
+            sendJson(res, 200, { ok: true, connections: deps.runtime.listDatabaseConnections() });
+            return true;
+        }
+        const gate = gateMutation(req, deps);
+        if (!gate.ok) {
+            sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+            return true;
+        }
+        try {
+            const body = await readJsonBody(req);
+            const engine = body.engine;
+            if (engine !== "sqlite" && engine !== "postgres" && engine !== "mysql") {
+                throw new DbConnectionError("DB_INVALID_CONFIG", "engine must be sqlite, postgres, or mysql");
+            }
+            const connection = await deps.runtime.addDatabaseConnection(databaseConnectionInput(body, engine));
+            sendJson(res, 201, { ok: true, connection });
+        }
+        catch (error) {
+            const code = error instanceof DbConnectionError ? error.code : "DB_PERSISTENCE_ERROR";
+            const status = code === "DB_PERSISTENCE_ERROR" ? 500 : 400;
+            sendJson(res, status, { ok: false, error: { code, message: error instanceof Error ? error.message : String(error) } });
+        }
+        return true;
+    }
+    const databaseBrowseRoute = pathname.match(/^\/api\/operator\/v1\/chat\/database-connections\/([^/]+)\/browse$/);
+    if (databaseBrowseRoute && method === "GET") {
+        const name = decodeURIComponent(databaseBrowseRoute[1]);
+        try {
+            const table = url.searchParams.get("table")?.trim();
+            const database = url.searchParams.get("database")?.trim() || undefined;
+            if (!table) {
+                const databases = await deps.runtime.listDatabaseDatabases(name);
+                const connection = deps.runtime.listDatabaseConnections().find((item) => item.name === name);
+                const shouldLoadTables = connection?.engine === "sqlite" || Boolean(database || connection?.database);
+                sendJson(res, 200, { ok: true, connection: name, database, databases, tables: shouldLoadTables ? await deps.runtime.listDatabaseTables(name, database) : [] });
+            }
+            else {
+                const page = Number(url.searchParams.get("page") ?? "1");
+                const pageSize = Number(url.searchParams.get("pageSize") ?? "50");
+                sendJson(res, 200, { ok: true, result: await deps.runtime.browseDatabaseTable(name, table, page, pageSize, database) });
+            }
+        }
+        catch (error) {
+            const code = error instanceof DbConnectionError ? error.code : "DB_ENGINE_ERROR";
+            const status = code === "DB_CONNECTION_NOT_FOUND" ? 404 : 400;
+            sendJson(res, status, { ok: false, error: { code, message: error instanceof Error ? error.message : String(error) } });
+        }
+        return true;
+    }
+    const databaseConnectionRoute = pathname.match(/^\/api\/operator\/v1\/chat\/database-connections\/([^/]+)(?:\/(test))?$/);
+    if (databaseConnectionRoute && (method === "DELETE" || method === "POST" || method === "PATCH")) {
+        const gate = gateMutation(req, deps);
+        if (!gate.ok) {
+            sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+            return true;
+        }
+        const name = decodeURIComponent(databaseConnectionRoute[1]);
+        try {
+            if (method === "POST" && databaseConnectionRoute[2] === "test") {
+                sendJson(res, 200, { ok: true, result: await deps.runtime.testDatabaseConnection(name) });
+            }
+            else if (method === "PATCH" && !databaseConnectionRoute[2]) {
+                const body = await readJsonBody(req);
+                const engine = body.engine;
+                if (engine !== "sqlite" && engine !== "postgres" && engine !== "mysql") {
+                    throw new DbConnectionError("DB_INVALID_CONFIG", "engine must be sqlite, postgres, or mysql");
+                }
+                const connection = await deps.runtime.updateDatabaseConnection(name, databaseConnectionInput(body, engine));
+                sendJson(res, 200, { ok: true, connection });
+            }
+            else if (method === "DELETE" && !databaseConnectionRoute[2]) {
+                await deps.runtime.removeDatabaseConnection(name);
+                sendJson(res, 200, { ok: true });
+            }
+            else {
+                sendJson(res, 405, { ok: false, error: { code: "METHOD_NOT_ALLOWED", message: "method not allowed" } });
+            }
+        }
+        catch (error) {
+            const code = error instanceof DbConnectionError ? error.code : "DB_ENGINE_ERROR";
+            const status = code === "DB_CONNECTION_NOT_FOUND" ? 404 : code === "DB_PERSISTENCE_ERROR" ? 500 : 400;
+            sendJson(res, status, { ok: false, error: { code, message: error instanceof Error ? error.message : String(error) } });
+        }
+        return true;
+    }
     const htmlPreviewRoute = matchRepoHtmlPreviewRoute(pathname);
     if (method === "GET" && htmlPreviewRoute) {
         if (!htmlPreviewRoute.rawPath)
@@ -4443,7 +4939,7 @@ async function dispatchChatRequest(req, res, deps, pathname, workspaceScope) {
         await handleSddBingo(req, res, deps, decodeURIComponent(sddBingo[1]));
         return true;
     }
-    const m4Route = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/(draft|files|runtime-context|runtime-snapshot|models|model|reload|commands)$/);
+    const m4Route = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/(draft|files|runtime-context|runtime-snapshot|context-insights|models|model|reload|commands)$/);
     if (m4Route) {
         const id = decodeURIComponent(m4Route[1]);
         const route = m4Route[2];
@@ -4463,6 +4959,10 @@ async function dispatchChatRequest(req, res, deps, pathname, workspaceScope) {
             await handleRuntimeSnapshot(req, res, deps, id);
             return true;
         }
+        if (route === "context-insights" && method === "GET") {
+            await handleContextInsights(res, deps, id);
+            return true;
+        }
         if (route === "models" && method === "GET") {
             await handleModels(req, res, deps, id);
             return true;
@@ -4557,6 +5057,11 @@ async function dispatchChatRequest(req, res, deps, pathname, workspaceScope) {
         await handleChatMessages(res, deps, decodeURIComponent(sessionMessages[1]), url);
         return true;
     }
+    const sessionAttachment = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/attachments\/([^/]+)$/);
+    if (method === "GET" && sessionAttachment) {
+        await handleChatAttachment(res, deps, decodeURIComponent(sessionAttachment[1]), decodeURIComponent(sessionAttachment[2]));
+        return true;
+    }
     const sessionPrompt = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/prompt$/);
     if (method === "POST" && sessionPrompt) {
         await handleChatPrompt(req, res, deps, decodeURIComponent(sessionPrompt[1]));