clawconnect-agent 0.2.5 → 0.2.7

package/dist/openclaw/relay/chat-history.js

@@ -1,8 +1,60 @@
 import { createHash } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { join } from "node:path";
+import { restoreGatewayHistoryMessages } from "./gateway-history-projection.js";
 import { readFile, stat } from "fs/promises";
 import { buildHistorySnapshotPage } from "../../core/relay/timeline-event-builder.js";
-import { resolveOpenClawSessionTranscript, } from "./session-context.js";
-import { normalizeOpenClawAssistantMediaSidecars } from "./assistant-media-sidecar.js";
+import { canonicalizeOpenClawSessionScope, resolveOpenClawSessionTranscript, sessionKeyCandidates, } from "./session-context.js";
+import { resolveOpenClawStateDir } from "../runtime/openclaw-paths.js";
+import { normalizeOpenClawAssistantMediaSidecars, normalizeOpenClawAutomaticMediaReplies, } from "./assistant-media-sidecar.js";
+import { adaptOpenClawMessageToolDelivery } from "./outgoing-media-relay.js";
+import { createProjectionMetadata, openClawAgentIdFromSessionKey, openClawSourceOrderScope, } from "../../core/relay/timeline-projection-v3.js";
+import { createSourceCommit } from "../../core/relay/source-commit.js";
+/**
+ * Read the durable OpenClaw SQLite watermark for one session. This is a
+ * source-commit signal only; callers must not use it to derive message ids or
+ * reorder rows. It intentionally returns null when the authoritative SQLite
+ * source is not available so the caller can use the native gateway stream.
+ */
+export function readOpenClawSourceCommitCursor(rawParams, defaults) {
+    const params = normalizeTranscriptHistoryParams(rawParams, defaults.mainSessionKey);
+    const agentId = params.sessionKey.match(/^agent:([^:]+):/)?.[1] ?? defaults.defaultAgentId ?? "main";
+    const databasePath = join(resolveOpenClawStateDir(), "agents", agentId, "agent", "openclaw-agent.sqlite");
+    let database;
+    try {
+        database = new DatabaseSync(databasePath, { readOnly: true });
+        const session = findSqliteSessionNode(database, params.sessionKey, defaults);
+        const sourceSessionId = cleanHistoryString(session?.current_session_id);
+        if (!sourceSessionId)
+            return null;
+        const row = database.prepare(`
+      SELECT MAX(seq) AS committed_through_seq
+      FROM transcript_events
+      WHERE session_id = ?
+    `).get(sourceSessionId);
+        const committedThroughSeq = Number(row?.committed_through_seq ?? 0);
+        if (!Number.isSafeInteger(committedThroughSeq) || committedThroughSeq < 0)
+            return null;
+        const gatewayId = requireProjectionIdentity(params.projectionGatewayId, "gatewayId");
+        const sourceOrderScope = openClawSourceOrderScope({ agentId, sessionId: sourceSessionId });
+        return createSourceCommit({
+            gatewayType: "openclaw",
+            gatewayId,
+            producerId: agentId,
+            sourceSessionId,
+            sourceOrderScope,
+            sourceGeneration: sourceSessionId,
+            committedThroughSeq,
+            sourceRevision: `seq:${committedThroughSeq}`,
+        });
+    }
+    catch {
+        return null;
+    }
+    finally {
+        database?.close();
+    }
+}
 const DEFAULT_TRANSCRIPT_HISTORY_LIMIT = 100;
 const MAX_TRANSCRIPT_HISTORY_LIMIT = 200;
 const CURSOR_PREFIX = "seq:";
@@ -14,6 +66,14 @@ export function clearTranscriptHistoryCache() {
 }
 export async function readOpenClawTranscriptChatHistory(rawParams, defaults) {
     const params = normalizeTranscriptHistoryParams(rawParams, defaults.mainSessionKey);
+    // OpenClaw 2026.8 writes the live conversation into the agent SQLite event
+    // log. Its seq is the same order used by Control UI; falling through to the
+    // gateway projection loses that order for records appended asynchronously
+    // (notably scheduled jobs with images).
+    const sqliteHistory = readOpenClawSqliteChatHistory(params, defaults);
+    if (sqliteHistory) {
+        return sqliteHistory;
+    }
     const transcript = await resolveOpenClawSessionTranscript(params.sessionKey, defaults);
     if (!transcript) {
         return null;
@@ -22,39 +82,178 @@ export async function readOpenClawTranscriptChatHistory(rawParams, defaults) {
         sessionKey: transcript.sessionKey,
         sessionId: transcript.sessionId,
         transcriptPath: transcript.logPath,
+        projectionGatewayId: params.projectionGatewayId,
         limit: params.limit,
         cursor: params.cursor,
         direction: params.direction,
+        projectionVersion: params.projectionVersion,
+        sessionDefaults: defaults,
     });
 }
+function readOpenClawSqliteChatHistory(params, defaults) {
+    const agentId = params.sessionKey.match(/^agent:([^:]+):/)?.[1] ?? defaults.defaultAgentId ?? "main";
+    const databasePath = join(resolveOpenClawStateDir(), "agents", agentId, "agent", "openclaw-agent.sqlite");
+    let database;
+    try {
+        database = new DatabaseSync(databasePath, { readOnly: true });
+        const session = findSqliteSessionNode(database, params.sessionKey, defaults);
+        const sessionId = cleanHistoryString(session?.current_session_id);
+        if (!sessionId)
+            return null;
+        const rows = database.prepare(`
+      SELECT seq, event_json
+      FROM transcript_events
+      WHERE session_id = ?
+      ORDER BY seq ASC
+    `).all(sessionId);
+        const visibleParentIds = resolveSqliteVisibleParentIds(rows);
+        const messages = rows
+            .map((row) => sqliteTranscriptHistoryMessage(row, sessionId, params.projectionVersion === 3, visibleParentIds))
+            .filter((message) => Boolean(message));
+        if (messages.length === 0 && rows.length === 0)
+            return null;
+        const cursorSeq = parseHistoryCursorSeq(params.cursor);
+        const sourceRange = params.direction === "newer"
+            ? (() => {
+                const startIndex = rows.findIndex((row) => {
+                    const seq = typeof row.seq === "number" && Number.isSafeInteger(row.seq) ? row.seq : undefined;
+                    return seq !== undefined && (cursorSeq === undefined || seq > cursorSeq);
+                });
+                const resolvedStart = startIndex < 0 ? rows.length : startIndex;
+                const rawPage = rows.slice(resolvedStart, resolvedStart + params.limit);
+                const rawLast = rawPage.at(-1)?.seq;
+                const rawFirst = rawPage[0]?.seq;
+                const rawSeqs = rawPage.map((row) => row.seq);
+                const sourceRangeHasGap = rawSeqs.some((seq, index) => {
+                    if (index === 0)
+                        return false;
+                    const previous = rawSeqs[index - 1];
+                    return typeof previous !== "number"
+                        || !Number.isSafeInteger(previous)
+                        || typeof seq !== "number"
+                        || !Number.isSafeInteger(seq)
+                        || seq !== previous + 1;
+                });
+                const sourceReadThroughSeq = typeof rawLast === "number" && Number.isSafeInteger(rawLast)
+                    ? rawLast
+                    : undefined;
+                const sourceRangeStartSeq = typeof rawFirst === "number" && Number.isSafeInteger(rawFirst)
+                    ? rawFirst
+                    : undefined;
+                return sourceReadThroughSeq === undefined || sourceRangeStartSeq === undefined
+                    ? undefined
+                    : {
+                        sourceReadThroughSeq,
+                        sourceRangeStartSeq,
+                        sourceRangeHasGap,
+                        sourceHasMore: resolvedStart + rawPage.length < rows.length,
+                    };
+            })()
+            : undefined;
+        return buildTranscriptHistoryResponse({
+            sessionKey: params.sessionKey,
+            sessionId,
+            projectionGatewayId: params.projectionGatewayId,
+            messages: prepareTranscriptHistoryMessages(messages, params.sessionKey, params.projectionVersion, defaults),
+            limit: params.limit,
+            cursor: params.cursor,
+            direction: params.direction,
+            projectionVersion: params.projectionVersion,
+            ...(sourceRange ?? {}),
+        });
+    }
+    catch (error) {
+        if (params.projectionVersion === 3 && error instanceof Error && error.message.startsWith("OpenClaw projection v3")) {
+            throw error;
+        }
+        return null;
+    }
+    finally {
+        database?.close();
+    }
+}
+function findSqliteSessionNode(database, sessionKey, defaults) {
+    const statement = database.prepare(`
+    SELECT current_session_id
+    FROM session_nodes
+    WHERE session_key = ?
+    LIMIT 1
+  `);
+    for (const candidate of sessionKeyCandidates(sessionKey, defaults)) {
+        const session = statement.get(candidate);
+        if (session)
+            return session;
+    }
+    return undefined;
+}
 export async function readChatHistoryFromTranscriptFile(request) {
-    const messages = await readIndexedTranscriptMessages(request.transcriptPath, request.sessionKey);
-    const limit = normalizeHistoryLimit(request.limit);
-    const direction = normalizeHistoryDirection(request.direction);
+    const messages = await readIndexedTranscriptMessages(request.transcriptPath, request.sessionKey, request.projectionVersion, request.sessionDefaults);
+    return buildTranscriptHistoryResponse({
+        sessionKey: request.sessionKey,
+        ...(request.sessionId ? { sessionId: request.sessionId } : {}),
+        projectionGatewayId: request.projectionGatewayId,
+        messages,
+        limit: normalizeHistoryLimit(request.limit),
+        cursor: normalizeCursor(request.cursor),
+        direction: normalizeHistoryDirection(request.direction),
+        projectionVersion: request.projectionVersion,
+    });
+}
+function buildTranscriptHistoryResponse(request) {
+    const projectionGatewayId = request.projectionVersion === 3
+        ? requireProjectionIdentity(request.projectionGatewayId, "gatewayId")
+        : request.projectionGatewayId ?? "clawconnect";
+    const projectionSessionId = request.projectionVersion === 3
+        ? requireProjectionIdentity(request.sessionId, "sourceSessionId")
+        : request.sessionId;
     const cursorSeq = parseHistoryCursorSeq(request.cursor);
-    const page = paginateHistoryMessages(messages, {
-        limit,
-        direction,
+    const boundedMessages = request.direction === "newer" && request.sourceReadThroughSeq !== undefined
+        ? request.messages.filter((message) => {
+            const seq = messageSeq(message);
+            return seq !== undefined
+                && (cursorSeq === undefined || seq > cursorSeq)
+                && seq <= request.sourceReadThroughSeq;
+        })
+        : request.messages;
+    const page = paginateHistoryMessages(boundedMessages, {
+        limit: request.limit,
+        direction: request.direction,
         cursorSeq,
     });
     return {
         sessionKey: request.sessionKey,
+        ...(request.projectionVersion === 3 ? { projectionVersion: 3 } : {}),
         ...(request.sessionId ? { sessionId: request.sessionId } : {}),
         messages: page.messages,
         hasMore: page.hasMore,
         ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
         ...(page.newestCursor ? { newestCursor: page.newestCursor } : {}),
+        ...(request.sourceReadThroughSeq !== undefined ? { sourceReadThroughSeq: request.sourceReadThroughSeq } : {}),
+        ...(request.sourceRangeStartSeq !== undefined ? { sourceRangeStartSeq: request.sourceRangeStartSeq } : {}),
+        ...(request.sourceRangeHasGap !== undefined ? { sourceRangeHasGap: request.sourceRangeHasGap } : {}),
+        ...(request.sourceHasMore !== undefined ? { sourceHasMore: request.sourceHasMore } : {}),
         timelineSnapshot: buildHistorySnapshotPage({
-            gatewayId: "clawconnect",
+            gatewayId: projectionGatewayId,
             sessionKey: request.sessionKey,
             cursor: normalizeCursor(request.cursor) ?? null,
             hasMore: page.hasMore,
             nextCursor: page.nextCursor ?? null,
             newestCursor: page.newestCursor ?? null,
             orderPolicy: "transcript",
-            ...(request.sessionId ? { sourceOrderScope: request.sessionId } : {}),
+            ...(projectionSessionId
+                ? {
+                    sourceOrderScope: request.projectionVersion === 3
+                        ? openClawSourceOrderScope({
+                            agentId: openClawAgentIdFromSessionKey(request.sessionKey),
+                            sessionId: projectionSessionId,
+                        })
+                        : projectionSessionId,
+                }
+                : {}),
             messages: page.messages.map((message, index) => {
-                const seq = messageSeq(message) ?? index + 1;
+                const seq = request.projectionVersion === 3
+                    ? requireProjectionSequence(messageSeq(message), index)
+                    : messageSeq(message) ?? index + 1;
                 const role = normalizeTimelineRole(message.role);
                 const clientMessageId = historyString(message, "clientMessageId", "client_message_id");
                 const idempotencyKey = historyString(message, "idempotencyKey", "idempotency_key");
@@ -73,10 +272,34 @@ export async function readChatHistoryFromTranscriptFile(request) {
                         ? block
                         : { ...block, toolCallId })
                     : content;
+                const sourceSessionId = request.projectionVersion === 3 ? projectionSessionId : undefined;
+                const sourceMessageId = request.projectionVersion === 3
+                    ? requireProjectionIdentity(messageId, "sourceMessageId")
+                    : messageId;
+                const projection = sourceSessionId && sourceMessageId
+                    ? createProjectionMetadata({
+                        gatewayType: "openclaw",
+                        gatewayId: projectionGatewayId,
+                        producerId: openClawAgentIdFromSessionKey(request.sessionKey),
+                        sourceSessionId,
+                        sourceMessageId,
+                        sourceOrderScope: openClawSourceOrderScope({
+                            agentId: openClawAgentIdFromSessionKey(request.sessionKey),
+                            sessionId: sourceSessionId,
+                        }),
+                        sourceOrderSeq: seq,
+                        sourceRole: role,
+                        ...(historyString(message, "parentId", "parent_id")
+                            ? { parentSourceMessageId: historyString(message, "parentId", "parent_id") }
+                            : {}),
+                        timelineDelivery: "independent",
+                    })
+                    : undefined;
+                const timelineMessageId = projection?.canonicalMessageId ?? messageId ?? `${role}-${turnId}`;
                 return {
                     turnId,
                     runId: historyString(message, "runId", "run_id") ?? turnId,
-                    messageId: messageId ?? `${role}-${turnId}`,
+                    messageId: timelineMessageId,
                     role,
                     messageState: normalizeTimelineMessageState(message),
                     createdAt: normalizeTimelineCreatedAt(message) ?? fallbackTimelineCreatedAt(page.messages, index),
@@ -89,6 +312,7 @@ export async function readChatHistoryFromTranscriptFile(request) {
                     ...(extractAttachmentIds(canonicalContent).length > 0
                         ? { attachmentIds: extractAttachmentIds(canonicalContent) }
                         : {}),
+                    ...(projection ?? {}),
                 };
             }),
             attachments: [],
@@ -103,19 +327,46 @@ export async function readChatHistoryFromTranscriptFile(request) {
  * of asking downstream clients to infer missing user turns from assistant text.
  */
 export function canonicalizeOpenClawGatewayHistoryResponse(history, request) {
-    const filtered = filterOpenClawHeartbeatHistoryResponse(history);
-    if (filtered.timelineSnapshot) {
+    const projectionGatewayId = request.projectionVersion === 3
+        ? requireProjectionIdentity(request.projectionGatewayId, "gatewayId")
+        : request.projectionGatewayId ?? "clawconnect";
+    const requestedSessionKey = cleanHistoryString(history.sessionKey) ?? request.sessionKey;
+    const restored = restoreGatewayHistoryMessages(history.messages ?? []);
+    const projectionVersion = request.projectionVersion;
+    const materializedDeliveries = materializeOpenClawMessageToolDeliveries(restored);
+    const explicitSidecars = normalizeOpenClawAssistantMediaSidecars(materializedDeliveries.messages, requestedSessionKey, {
+        ...(projectionVersion === 3 ? { projectionVersion: 3 } : {}),
+        ...(request.sessionDefaults ? { sessionDefaults: request.sessionDefaults } : {}),
+    });
+    const automaticMediaReplies = normalizeOpenClawAutomaticMediaReplies(explicitSidecars.messages, requestedSessionKey, {
+        ...(projectionVersion === 3 ? { projectionVersion: 3 } : {}),
+        ...(request.sessionDefaults ? { sessionDefaults: request.sessionDefaults } : {}),
+    });
+    const normalizedHistory = materializedDeliveries.changed || restored !== history.messages || explicitSidecars.changed || automaticMediaReplies.changed
+        ? { ...history, messages: automaticMediaReplies.messages }
+        : history;
+    const filtered = filterOpenClawHeartbeatHistoryResponse(normalizedHistory);
+    if (filtered.timelineSnapshot && projectionVersion !== 3) {
         return filtered;
     }
-    const sessionKey = cleanHistoryString(filtered.sessionKey) ?? request.sessionKey;
+    const sessionKey = canonicalizeOpenClawSessionScope(cleanHistoryString(filtered.sessionKey) ?? request.sessionKey, request.sessionDefaults) ?? (cleanHistoryString(filtered.sessionKey) ?? request.sessionKey);
     const messages = filtered.messages ?? [];
-    const sourceOrderScope = cleanHistoryString(filtered.sessionId)
-        ?? messages.map(openClawTranscriptSource).find((value) => Boolean(value));
+    const rawSourceSessionId = cleanHistoryString(filtered.sessionId);
+    const sourceSessionId = projectionVersion === 3
+        ? requireProjectionIdentity(rawSourceSessionId, "sourceSessionId")
+        : undefined;
+    const agentId = openClawAgentIdFromSessionKey(sessionKey);
+    const sourceOrderScope = rawSourceSessionId
+        ? projectionVersion === 3
+            ? openClawSourceOrderScope({ agentId, sessionId: rawSourceSessionId })
+            : rawSourceSessionId
+        : messages.map(openClawTranscriptSource).find((value) => Boolean(value));
     return {
         ...filtered,
         sessionKey,
+        ...(projectionVersion === 3 ? { projectionVersion: 3 } : {}),
         timelineSnapshot: buildHistorySnapshotPage({
-            gatewayId: "clawconnect",
+            gatewayId: projectionGatewayId,
             sessionKey,
             cursor: request.cursor ?? null,
             hasMore: Boolean(filtered.hasMore),
@@ -123,12 +374,18 @@ export function canonicalizeOpenClawGatewayHistoryResponse(history, request) {
             newestCursor: filtered.newestCursor ?? null,
             orderPolicy: "transcript",
             ...(sourceOrderScope ? { sourceOrderScope } : {}),
-            messages: canonicalizeOpenClawGatewayHistoryMessages(messages, sessionKey),
+            messages: canonicalizeOpenClawGatewayHistoryMessages(messages, sessionKey, {
+                agentId,
+                projectionGatewayId,
+                ...(projectionVersion === 3 ? { projectionVersion: 3 } : {}),
+                ...(sourceSessionId ? { sourceSessionId } : {}),
+                ...(sourceOrderScope ? { sourceOrderScope } : {}),
+            }),
             attachments: [],
         }),
     };
 }
-function canonicalizeOpenClawGatewayHistoryMessages(messages, sessionKey) {
+function canonicalizeOpenClawGatewayHistoryMessages(messages, sessionKey, projection) {
     const finalAssistantIndexByRunId = new Map();
     messages.forEach((message, index) => {
         if (normalizeTimelineRole(message.role) !== "assistant")
@@ -138,7 +395,9 @@ function canonicalizeOpenClawGatewayHistoryMessages(messages, sessionKey) {
             finalAssistantIndexByRunId.set(runId, index);
     });
     return messages.map((message, index) => {
-        const seq = messageSeq(message) ?? index + 1;
+        const seq = projection?.projectionVersion === 3
+            ? requireProjectionSequence(messageSeq(message), index)
+            : messageSeq(message) ?? index + 1;
         const role = normalizeTimelineRole(message.role);
         const rawIdempotencyKey = historyString(message, "idempotencyKey", "idempotency_key")
             ?? openClawHistoryString(message, "idempotencyKey", "idempotency_key");
@@ -147,6 +406,9 @@ function canonicalizeOpenClawGatewayHistoryMessages(messages, sessionKey) {
             ?? normalizeTranscriptTurnId(clientMessageId);
         const providerMessageId = historyString(message, "messageId", "message_id", "id")
             ?? openClawHistoryString(message, "id");
+        const sourceMessageId = projection?.projectionVersion === 3
+            ? requireProjectionIdentity(providerMessageId, "sourceMessageId")
+            : providerMessageId;
         const runId = historyString(message, "runId", "run_id")
             ?? openClawRunId(message)
             ?? normalizedInputId;
@@ -172,11 +434,32 @@ function canonicalizeOpenClawGatewayHistoryMessages(messages, sessionKey) {
             toolCallId,
             index,
             finalAssistantIndexByRunId,
+            projectionVersion: projection?.projectionVersion,
         });
+        const sourceSessionId = projection?.sourceSessionId;
+        const sourceOrderScope = projection?.sourceOrderScope;
+        const projectionMetadata = projection?.projectionVersion === 3
+            && sourceSessionId && sourceOrderScope && sourceMessageId
+            ? createProjectionMetadata({
+                gatewayType: "openclaw",
+                gatewayId: requireProjectionIdentity(projection.projectionGatewayId, "gatewayId"),
+                producerId: projection.agentId,
+                sourceSessionId,
+                sourceMessageId,
+                sourceOrderScope,
+                sourceOrderSeq: seq,
+                sourceRole: role,
+                ...(historyString(message, "parentId", "parent_id")
+                    ? { parentSourceMessageId: historyString(message, "parentId", "parent_id") }
+                    : {}),
+                timelineDelivery: "independent",
+            })
+            : undefined;
+        const timelineMessageId = projectionMetadata?.canonicalMessageId ?? messageId;
         return {
             turnId,
             runId: runId ?? turnId,
-            messageId,
+            messageId: timelineMessageId,
             role,
             messageState: normalizeTimelineMessageState(message),
             createdAt: normalizeTimelineCreatedAt(message) ?? fallbackTimelineCreatedAt(messages, index),
@@ -189,6 +472,7 @@ function canonicalizeOpenClawGatewayHistoryMessages(messages, sessionKey) {
             ...(extractAttachmentIds(canonicalContent).length > 0
                 ? { attachmentIds: extractAttachmentIds(canonicalContent) }
                 : {}),
+            ...(projectionMetadata ?? {}),
         };
     });
 }
@@ -231,11 +515,16 @@ function normalizeTranscriptHistoryParams(rawParams, fallbackSessionKey) {
         limit: normalizeHistoryLimit(record.limit),
         ...(cursor ? { cursor } : {}),
         direction: normalizeHistoryDirection(record.direction),
+        ...(record.projectionVersion === 3 ? { projectionVersion: 3 } : {}),
+        ...(typeof record.projectionGatewayId === "string" && record.projectionGatewayId.trim().length > 0
+            ? { projectionGatewayId: record.projectionGatewayId.trim() }
+            : {}),
     };
 }
-async function readIndexedTranscriptMessages(transcriptPath, sessionKey) {
+async function readIndexedTranscriptMessages(transcriptPath, sessionKey, projectionVersion, sessionDefaults) {
     const stats = await stat(transcriptPath);
-    const cached = transcriptHistoryCache.get(transcriptPath);
+    const cacheKey = `${transcriptPath}\u0000${projectionVersion === 3 ? "v3" : "v2"}`;
+    const cached = transcriptHistoryCache.get(cacheKey);
     if (cached && cached.size === stats.size && cached.mtimeMs === stats.mtimeMs) {
         return cached.messages;
     }
@@ -246,25 +535,157 @@ async function readIndexedTranscriptMessages(transcriptPath, sessionKey) {
         if (!trimmed) {
             continue;
         }
-        const message = parseTranscriptHistoryLine(trimmed, messages.length + 1);
+        const message = parseTranscriptHistoryLine(trimmed, messages.length + 1, projectionVersion === 3);
         if (message) {
             messages.push(message);
         }
     }
-    // Fold the automatic assistant-media sidecar before lineage reconstruction.
-    // Lineage deliberately rewrites idempotency keys to mobile turn IDs, while
-    // the raw <run>:assistant-media key and parentId are the authoritative
-    // relationship needed to keep the desktop and mobile projections aligned.
-    const foldedMessages = normalizeOpenClawAssistantMediaSidecars(messages, sessionKey).messages;
-    restoreTranscriptTurnLineage(foldedMessages);
-    const visibleMessages = filterOpenClawHeartbeatArtifacts(foldedMessages);
-    transcriptHistoryCache.set(transcriptPath, {
+    const visibleMessages = prepareTranscriptHistoryMessages(messages, sessionKey, projectionVersion, sessionDefaults);
+    transcriptHistoryCache.set(cacheKey, {
         size: stats.size,
         mtimeMs: stats.mtimeMs,
         messages: visibleMessages,
     });
     return visibleMessages;
 }
+function sqliteTranscriptHistoryMessage(row, sessionId, strictProjectionV3 = false, visibleParentIds) {
+    const seq = typeof row.seq === "number" && Number.isFinite(row.seq) && row.seq > 0
+        ? Math.round(row.seq)
+        : undefined;
+    if (!seq || typeof row.event_json !== "string")
+        return null;
+    let event;
+    try {
+        event = JSON.parse(row.event_json);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(event) || event.type !== "message" || !isRecord(event.message))
+        return null;
+    // `event.id`/`event.parentId` form the transcript's real lineage graph.
+    // Do not replace that graph with a synthetic seq id: assistant events often
+    // lack their own run id and are linked back to the originating user turn
+    // only through those event ids.
+    const sourceMessageId = cleanHistoryString(event.id);
+    const message = { ...event.message, seq };
+    if (strictProjectionV3 && !cleanHistoryString(message.id) && !sourceMessageId) {
+        throw new Error(`OpenClaw projection v3 sourceMessageId is missing at source seq ${seq}`);
+    }
+    if (!cleanHistoryString(message.id)) {
+        message.id = sourceMessageId ?? `sqlite-${sessionId}-${seq}`;
+    }
+    const timestamp = normalizeHistoryTimestamp(message.timestamp ?? event.timestamp);
+    if (timestamp !== undefined) {
+        message.timestamp = timestamp;
+        message.createdAt = cleanHistoryString(message.createdAt) ?? new Date(timestamp).toISOString();
+    }
+    const parentId = (sourceMessageId ? visibleParentIds?.get(sourceMessageId) : undefined)
+        ?? cleanHistoryString(event.parentId)
+        ?? cleanHistoryString(message.parentId);
+    if (parentId)
+        message.parentId = parentId;
+    return message;
+}
+/**
+ * SQLite stores every transcript event in one parent graph, including hidden
+ * custom/thinking rows. Collapse only those hidden hops so visible messages
+ * retain deterministic source lineage and can inherit the originating mobile
+ * run id. Distinct message identities remain untouched.
+ */
+function resolveSqliteVisibleParentIds(rows) {
+    const nodes = new Map();
+    for (const row of rows) {
+        if (typeof row.event_json !== "string")
+            continue;
+        let event;
+        try {
+            event = JSON.parse(row.event_json);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(event))
+            continue;
+        const eventId = cleanHistoryString(event.id);
+        if (!eventId)
+            continue;
+        const visibleMessageId = event.type === "message" && isRecord(event.message)
+            ? cleanHistoryString(event.message.id) ?? eventId
+            : undefined;
+        nodes.set(eventId, {
+            eventId,
+            ...(cleanHistoryString(event.parentId) ? { parentId: cleanHistoryString(event.parentId) } : {}),
+            ...(visibleMessageId ? { visibleMessageId } : {}),
+        });
+    }
+    const resolved = new Map();
+    for (const node of nodes.values()) {
+        if (!node.visibleMessageId || !node.parentId)
+            continue;
+        let parentId = node.parentId;
+        const visited = new Set();
+        while (parentId && !visited.has(parentId)) {
+            visited.add(parentId);
+            const parent = nodes.get(parentId);
+            if (!parent)
+                break;
+            if (parent.visibleMessageId) {
+                resolved.set(node.eventId, parent.visibleMessageId);
+                break;
+            }
+            parentId = parent.parentId;
+        }
+    }
+    return resolved;
+}
+function prepareTranscriptHistoryMessages(messages, sessionKey, projectionVersion, sessionDefaults) {
+    messages = materializeOpenClawMessageToolDeliveries(messages).messages;
+    // Fold the automatic assistant-media sidecar before lineage reconstruction.
+    // Lineage deliberately rewrites idempotency keys to mobile turn IDs, while
+    // the raw <run>:assistant-media key and parentId are the authoritative
+    // relationship needed to keep the desktop and mobile projections aligned.
+    const projectionOptions = projectionVersion === 3 ? { projectionVersion: 3 } : undefined;
+    const relationOptions = {
+        ...(projectionOptions ?? {}),
+        ...(sessionDefaults ? { sessionDefaults } : {}),
+    };
+    const explicitSidecars = normalizeOpenClawAssistantMediaSidecars(messages, sessionKey, relationOptions).messages;
+    restoreTranscriptTurnLineage(explicitSidecars, projectionVersion);
+    const foldedMessages = normalizeOpenClawAutomaticMediaReplies(explicitSidecars, sessionKey, relationOptions).messages;
+    return filterOpenClawHeartbeatArtifacts(foldedMessages);
+}
+/**
+ * The installed OpenClaw producer records a settled message-tool delivery as
+ * a `toolResult` row. That row is an execution detail, not a user-visible
+ * timeline item. Promote only the producer's strict, structured receipt to an
+ * independent assistant row; never use its prose content or generic
+ * `openclawDelivery.mediaUrls` display field as evidence.
+ */
+function materializeOpenClawMessageToolDeliveries(messages) {
+    let changed = false;
+    const materialized = messages.map((message) => {
+        if (message.role !== "toolResult" && message.role !== "tool_result") {
+            return message;
+        }
+        const receipt = adaptOpenClawMessageToolDelivery(message);
+        if (!receipt)
+            return message;
+        changed = true;
+        return {
+            ...message,
+            role: "assistant",
+            runId: receipt.sourceRunId,
+            turnId: receipt.sourceRunId,
+            idempotencyKey: receipt.idempotencyKey,
+            // Keep the strict typed receipt on the canonical row until the relay
+            // replaces its local paths with uploaded attachment blocks.
+            openclawDelivery: receipt,
+            content: [],
+        };
+    });
+    return { messages: materialized, changed };
+}
 /**
  * OpenClaw 会把内部心跳探测写入 transcript。只有精确的保留提示最终得到纯确认回执时，
  * 才隐藏整段内部记录；若心跳产生真实告警，则保留完整内容供用户查看。
@@ -395,7 +816,7 @@ function resolveTextOnlyHistoryContent(content) {
     }
     return { text, hasNonTextContent };
 }
-function parseTranscriptHistoryLine(line, seq) {
+function parseTranscriptHistoryLine(line, seq, strictProjectionV3 = false) {
     let parsed;
     try {
         parsed = JSON.parse(line);
@@ -412,6 +833,9 @@ function parseTranscriptHistoryLine(line, seq) {
     }
     const message = { ...rawMessage, seq };
     if (typeof message.id !== "string" || message.id.trim().length === 0) {
+        if (strictProjectionV3 && (typeof parsed.id !== "string" || parsed.id.trim().length === 0)) {
+            throw new Error(`OpenClaw projection v3 sourceMessageId is missing at source seq ${seq}`);
+        }
         const id = typeof parsed.id === "string" && parsed.id.trim().length > 0 ? parsed.id.trim() : `transcript-${seq}`;
         message.id = id;
     }
@@ -434,7 +858,7 @@ function parseTranscriptHistoryLine(line, seq) {
  * idempotency key through that chain so history and realtime resolve to the
  * same canonical message without comparing text or timestamps.
  */
-function restoreTranscriptTurnLineage(messages) {
+function restoreTranscriptTurnLineage(messages, projectionVersion) {
     const byId = new Map();
     const lastAssistantByMobileTurn = new Map();
     for (const message of messages) {
@@ -475,8 +899,10 @@ function restoreTranscriptTurnLineage(messages) {
     }
     // 一个 OpenClaw turn 可能包含若干工具中间消息；只有最后一个 assistant 输出
     // 与实时 final 共用 canonical messageId，其他中间消息继续保留 transcript 身份。
-    for (const [turnId, message] of lastAssistantByMobileTurn.entries()) {
-        message.messageId = `assistant-${turnId}`;
+    if (projectionVersion !== 3) {
+        for (const [turnId, message] of lastAssistantByMobileTurn.entries()) {
+            message.messageId = `assistant-${turnId}`;
+        }
     }
 }
 function normalizeTranscriptTurnId(value) {
@@ -548,6 +974,18 @@ function normalizeHistoryLimit(value) {
 function normalizeHistoryDirection(value) {
     return value === "newer" ? "newer" : "older";
 }
+function requireProjectionIdentity(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`OpenClaw projection v3 identity is missing ${field}`);
+    }
+    return value.trim();
+}
+function requireProjectionSequence(value, index) {
+    if (!Number.isSafeInteger(value) || (value ?? 0) <= 0) {
+        throw new Error(`OpenClaw projection v3 sourceOrderSeq is missing or invalid at row ${index}`);
+    }
+    return value;
+}
 function normalizeCursor(value) {
     return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }
@@ -729,20 +1167,30 @@ function historyNumber(record, ...fields) {
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-export function extractHistoryOutcome(history, context) {
+export function extractHistoryOutcome(history, context, preferredText) {
     const messages = history?.messages ?? [];
     if (messages.length === 0) {
         return null;
     }
-    const userIndex = findHistoryUserIndex(messages, context);
-    if (userIndex === -1) {
+    const scope = findHistoryScope(messages, context);
+    if (!scope) {
         return null;
     }
-    if (hasUnresolvedUserBefore(messages, userIndex)) {
+    if (scope.hasUser && hasUnresolvedUserBefore(messages, scope.startIndex)) {
         return null;
     }
     let latestError = null;
-    for (let index = userIndex + 1; index < messages.length; index += 1) {
+    let latestFinal = null;
+    // `preferredText` is retained for call-site compatibility only.  Assistant
+    // prose is not a message identity and must never select an attachment row;
+    // the stable turn/message/tool ids above and source order are authoritative.
+    void preferredText;
+    // When the history page starts after the user row, the first assistant row
+    // carrying the same stable run id is the deterministic scope boundary. Do
+    // not require a text/timestamp guess just because pagination omitted the
+    // user record.
+    const firstMessageIndex = scope.hasUser ? scope.startIndex + 1 : scope.startIndex;
+    for (let index = firstMessageIndex; index < messages.length; index += 1) {
         const message = messages[index];
         if (message.role === "user") {
             return null;
@@ -751,8 +1199,15 @@ export function extractHistoryOutcome(history, context) {
             continue;
         }
         const text = extractHistoryMessageText(message);
-        if (text.length > 0 || hasHistoryMessageContent(message)) {
-            return { kind: "final", text, message };
+        const mediaOnlyProjectionRow = history?.projectionVersion === 3
+            && text.length === 0
+            && nonTextHistoryContent(message).length > 0;
+        if (!mediaOnlyProjectionRow && (text.length > 0 || hasHistoryMessageContent(message))) {
+            // One OpenClaw run may contain several independent message-tool replies.
+            // The last authoritative assistant row is the terminal history outcome;
+            // returning the first row loses later media on fallback/replay.
+            latestFinal = { kind: "final", text, message };
+            continue;
         }
         if (typeof message.errorMessage === "string" &&
             message.errorMessage.trim().length > 0 &&
@@ -760,7 +1215,56 @@ export function extractHistoryOutcome(history, context) {
             latestError = message.errorMessage.trim();
         }
     }
-    return latestError ? { kind: "error", errorMessage: latestError } : null;
+    return latestFinal ?? (latestError ? { kind: "error", errorMessage: latestError } : null);
+}
+/**
+ * Return all media delivery rows belonging to the matched OpenClaw turn.
+ * A provider may emit only the first image on the live terminal while the
+ * remaining message-tool deliveries are committed to history. This helper
+ * keeps the user-turn boundary as the only scope and never matches by text.
+ */
+export function extractHistoryMediaContent(history, context) {
+    const messages = history?.messages ?? [];
+    const scope = findHistoryScope(messages, context);
+    if (!scope || (scope.hasUser && hasUnresolvedUserBefore(messages, scope.startIndex)))
+        return [];
+    const media = [];
+    const firstMessageIndex = scope.hasUser ? scope.startIndex + 1 : scope.startIndex;
+    for (let index = firstMessageIndex; index < messages.length; index += 1) {
+        const message = messages[index];
+        if (message.role === "user")
+            break;
+        if (message.role === "assistant")
+            media.push(...nonTextHistoryContent(message));
+    }
+    return media.filter((block) => typeof block.type === "string");
+}
+/**
+ * Collect media rows only when the provider gives an explicit parent edge.
+ * v3 message-tool rows remain independent canonical messages; this helper is
+ * solely for an outgoing terminal payload that deliberately owns its child
+ * sidecars, and never falls back to run/client/text/time matching.
+ */
+export function extractExplicitParentMediaContent(history, parentMessage) {
+    if (!history || !parentMessage)
+        return [];
+    const parentMessageId = historyString(parentMessage, "messageId", "message_id", "id");
+    if (!parentMessageId)
+        return [];
+    return (history.messages ?? []).flatMap((message) => {
+        const explicitParentId = historyString(message, "parentId", "parent_id");
+        if (explicitParentId !== parentMessageId)
+            return [];
+        return nonTextHistoryContent(message);
+    }).filter((block) => typeof block.type === "string");
+}
+function nonTextHistoryContent(message) {
+    return Array.isArray(message.content)
+        ? message.content.filter((block) => {
+            const type = typeof block?.type === "string" ? block.type.trim().toLowerCase() : "";
+            return ["image", "file", "audio", "voice", "video", "attachment"].includes(type);
+        })
+        : [];
 }
 function hasUnresolvedUserBefore(messages, userIndex) {
     for (let index = userIndex - 1; index >= 0; index -= 1) {
@@ -842,10 +1346,10 @@ function isToolOnlyHistoryBlockType(type) {
         || normalizedType === "computercall"
         || normalizedType === "computercalloutput";
 }
-function findHistoryUserIndex(messages, context) {
+function findHistoryScope(messages, context) {
     const canonicalRunId = normalizeTranscriptTurnId(context.canonicalRunId);
     if (!canonicalRunId) {
-        return -1;
+        return undefined;
     }
     for (let index = messages.length - 1; index >= 0; index -= 1) {
         const message = messages[index];
@@ -859,9 +1363,26 @@ function findHistoryUserIndex(messages, context) {
             message.runId,
         ].map(normalizeTranscriptTurnId);
         if (stableIds.includes(canonicalRunId)) {
-            return index;
+            return { startIndex: index, hasUser: true };
         }
     }
-    return -1;
+    // `chat.history` is paginated, and a busy OpenClaw turn can append more
+    // than the live enrichment page size after its user row (tool calls,
+    // delivery mirrors, and the final commentary). The assistant delivery rows
+    // still carry the authoritative run/turn id, so use the first matching row
+    // as the scope boundary when the user row is outside this page. This is a
+    // stable identity-based reconciliation, not a text or timestamp heuristic.
+    const firstRunMessageIndex = messages.findIndex((message) => {
+        const stableIds = [
+            message.runId,
+            message.turnId,
+            message.idempotencyKey,
+            message.clientMessageId,
+        ].map(normalizeTranscriptTurnId);
+        return stableIds.includes(canonicalRunId);
+    });
+    return firstRunMessageIndex >= 0
+        ? { startIndex: firstRunMessageIndex, hasUser: false }
+        : undefined;
 }
 //# sourceMappingURL=chat-history.js.map