@abot-ai/runtime 1.0.0

package/dist/src/sessions/context-window.js

@@ -0,0 +1,214 @@
+const TOOL_OBSERVATION_ANNOTATION = "Context note: This message was derived from a previous tool-based observation and may not reflect current external state.";
+const CARRY_SOURCE_PRIORITY = {
+    contextEntry: 1,
+    message: 2,
+};
+function isToolObservationMessage(message) {
+    return (message.role === "assistant" && message.grounding === "tool_observation");
+}
+function isTaskResultBoundary(message) {
+    return (message.role === "assistant" &&
+        message.observationMeta?.kind === "task_result");
+}
+function shouldCarryToolObservation(message) {
+    if (!isToolObservationMessage(message) &&
+        typeof message.observationContent !== "string") {
+        return false;
+    }
+    if (!message.observationMeta) {
+        return false;
+    }
+    return message.observationMeta.carryPolicy === "always";
+}
+function isTaskResultObservation(message) {
+    return message.observationMeta?.kind === "task_result";
+}
+function getTaskResultRole(message) {
+    return message.observationMeta?.taskResultRole;
+}
+function getContextEntryTaskResultRole(entry) {
+    return entry.observationMeta.taskResultRole;
+}
+function buildToolObservationContext(content, meta) {
+    const taskResultRole = meta?.taskResultRole;
+    return {
+        role: "system",
+        content: [TOOL_OBSERVATION_ANNOTATION, content].join("\n"),
+        contextMessageKind: meta?.kind === "task_result"
+            ? "development_task_result_observation"
+            : "prior_tool_observation",
+        ...(taskResultRole ? { taskResultRole } : {}),
+    };
+}
+function toToolObservationContext(message) {
+    return buildToolObservationContext(message.content, message.observationMeta);
+}
+function toConversationContext(message) {
+    return {
+        role: message.role,
+        content: message.content,
+        ...(message.attachments && message.attachments.length > 0
+            ? { attachments: message.attachments }
+            : {}),
+    };
+}
+function isNewerCandidate(candidate, current) {
+    if (!current) {
+        return true;
+    }
+    if (candidate.createdAt === current.createdAt) {
+        if (candidate.sourcePriority !== current.sourcePriority) {
+            return candidate.sourcePriority > current.sourcePriority;
+        }
+        return candidate.sequence > current.sequence;
+    }
+    return candidate.createdAt > current.createdAt;
+}
+function pushCandidateContext(target, candidate) {
+    if (candidate) {
+        target.push(candidate.context);
+    }
+}
+export function buildContextBuckets(session, options = {}) {
+    const maxConversationMessages = Number.isFinite(options.maxConversationMessages)
+        ? Math.max(0, Math.floor(options.maxConversationMessages ?? 3))
+        : 3;
+    const maxToolObservationMessages = Number.isFinite(options.maxToolObservationMessages)
+        ? Math.max(0, Math.floor(options.maxToolObservationMessages ?? 2))
+        : 2;
+    const includeRecentConversation = options.includeRecentConversation !== false;
+    const includeRecentConversationAcrossTaskResults = options.includeRecentConversationAcrossTaskResults === true;
+    const recentConversation = [];
+    const priorToolObservations = [];
+    let latestAuthoritativeTaskResultObservation = null;
+    let latestSupplementalTaskResultObservation = null;
+    let latestFallbackTaskResultObservation = null;
+    const recordTaskResultObservation = (candidate, taskResultRole) => {
+        if (taskResultRole === "authoritative_project_handoff") {
+            if (isNewerCandidate(candidate, latestAuthoritativeTaskResultObservation)) {
+                latestAuthoritativeTaskResultObservation = candidate;
+            }
+            return;
+        }
+        if (taskResultRole === "supplemental_follow_up") {
+            if (isNewerCandidate(candidate, latestSupplementalTaskResultObservation)) {
+                latestSupplementalTaskResultObservation = candidate;
+            }
+            return;
+        }
+        if (isNewerCandidate(candidate, latestFallbackTaskResultObservation)) {
+            latestFallbackTaskResultObservation = candidate;
+        }
+    };
+    for (let i = session.messages.length - 1; i >= 0; i -= 1) {
+        const message = session.messages[i];
+        const taskResultBoundary = isTaskResultBoundary(message);
+        const observationContent = typeof message.observationContent === "string"
+            ? message.observationContent.trim()
+            : "";
+        if (observationContent.length > 0 && message.observationMeta) {
+            if (shouldCarryToolObservation(message) &&
+                isTaskResultObservation(message)) {
+                const observation = buildToolObservationContext(observationContent, message.observationMeta);
+                const taskResultRole = getTaskResultRole(message);
+                recordTaskResultObservation({
+                    context: observation,
+                    createdAt: message.createdAt,
+                    sequence: i,
+                    sourcePriority: CARRY_SOURCE_PRIORITY.message,
+                }, taskResultRole);
+            }
+            else if (shouldCarryToolObservation(message) &&
+                priorToolObservations.length < maxToolObservationMessages) {
+                priorToolObservations.push(buildToolObservationContext(observationContent, message.observationMeta));
+            }
+            if (taskResultBoundary && !includeRecentConversationAcrossTaskResults) {
+                break;
+            }
+            continue;
+        }
+        if (isToolObservationMessage(message)) {
+            if (shouldCarryToolObservation(message) &&
+                isTaskResultObservation(message)) {
+                const observation = toToolObservationContext(message);
+                const taskResultRole = getTaskResultRole(message);
+                recordTaskResultObservation({
+                    context: observation,
+                    createdAt: message.createdAt,
+                    sequence: i,
+                    sourcePriority: CARRY_SOURCE_PRIORITY.message,
+                }, taskResultRole);
+            }
+            else if (shouldCarryToolObservation(message) &&
+                priorToolObservations.length < maxToolObservationMessages) {
+                priorToolObservations.push(toToolObservationContext(message));
+            }
+            if (taskResultBoundary && !includeRecentConversationAcrossTaskResults) {
+                break;
+            }
+            continue;
+        }
+        if (taskResultBoundary) {
+            if (includeRecentConversationAcrossTaskResults &&
+                includeRecentConversation &&
+                recentConversation.length < maxConversationMessages) {
+                recentConversation.push(toConversationContext(message));
+            }
+            if (!includeRecentConversationAcrossTaskResults) {
+                break;
+            }
+            continue;
+        }
+        if (includeRecentConversation &&
+            recentConversation.length < maxConversationMessages) {
+            recentConversation.push(toConversationContext(message));
+        }
+        if (recentConversation.length >= maxConversationMessages &&
+            priorToolObservations.length >= maxToolObservationMessages) {
+            break;
+        }
+    }
+    for (let i = (session.contextEntries ?? []).length - 1; i >= 0; i -= 1) {
+        const entry = session.contextEntries?.[i];
+        if (!entry || entry.observationMeta.carryPolicy !== "always") {
+            continue;
+        }
+        const content = entry.content.trim();
+        if (content.length === 0) {
+            continue;
+        }
+        const observation = buildToolObservationContext(content, entry.observationMeta);
+        if (entry.observationMeta.kind === "task_result") {
+            recordTaskResultObservation({
+                context: observation,
+                createdAt: entry.createdAt,
+                sequence: i,
+                sourcePriority: CARRY_SOURCE_PRIORITY.contextEntry,
+            }, getContextEntryTaskResultRole(entry));
+            continue;
+        }
+        if (priorToolObservations.length < maxToolObservationMessages) {
+            priorToolObservations.push(observation);
+        }
+    }
+    recentConversation.reverse();
+    priorToolObservations.reverse();
+    pushCandidateContext(priorToolObservations, latestSupplementalTaskResultObservation);
+    if (latestAuthoritativeTaskResultObservation) {
+        pushCandidateContext(priorToolObservations, latestAuthoritativeTaskResultObservation);
+    }
+    else {
+        pushCandidateContext(priorToolObservations, latestFallbackTaskResultObservation);
+    }
+    return {
+        recentConversation,
+        priorToolObservations,
+    };
+}
+export function buildContextWindow(session, maxMessages = 10) {
+    const buckets = buildContextBuckets(session, {
+        maxConversationMessages: maxMessages,
+        maxToolObservationMessages: 0,
+    });
+    return buckets.recentConversation;
+}

package/dist/src/sessions/index.d.ts

@@ -0,0 +1,49 @@
+import type { AgentMode } from "../shared/types.js";
+import { buildContextBuckets, buildContextWindow } from "./context-window.js";
+import type { SessionMemoryCheckpointCommit } from "./memory/contracts.js";
+import type { SessionArtifactPathInput, SessionContextEntryKind, SessionMessageGrounding, SessionMessageObservationMeta, SessionMessageRole, SessionMessageSource, SessionMessageTaskType, SessionThinkingTraceEntry } from "./types.js";
+export type { SessionArtifactPath, SessionArtifactPathInput } from "./types.js";
+export { buildContextBuckets, buildContextWindow };
+export declare function getOrCreateSession(sessionId: string): Promise<import("./types.js").SessionRecord>;
+export declare function getAllSessions(): Promise<import("./types.js").SessionRecord[]>;
+export declare function listSessions(params?: {
+    limit?: number;
+    cursor?: string | null;
+}): Promise<import("./types.js").SessionListResult>;
+export declare function getSessionById(sessionId: string): Promise<import("./types.js").SessionRecord | null>;
+export declare function getSessionSnapshot(sessionId: string, options?: {
+    afterMessageId?: string | number | null;
+    includeRequests?: boolean;
+}): Promise<import("./types.js").SessionSnapshot | null>;
+export declare function updateSessionTitle(sessionId: string, title: string): Promise<import("./types.js").SessionRecord | null>;
+export declare function updateSessionRuntimeMode(sessionId: string, runtimeModeId: string | null): Promise<import("./types.js").SessionRecord | null>;
+export declare function getRequestReplayById(requestId: string, afterSeq?: number): Promise<import("./types.js").SessionRequestReplay | null>;
+export declare function deleteSession(sessionId: string): Promise<boolean>;
+export declare function deleteSessionWithStats(sessionId: string): Promise<import("./types.js").SessionDeleteResult>;
+export declare function resetSession(sessionId: string): Promise<import("./types.js").SessionRecord | null>;
+export declare function clearSessionMessages(sessionId: string): Promise<import("./types.js").SessionMessagesClearResult | null>;
+export declare function appendMessage(sessionId: string, role: SessionMessageRole, content: string, options?: {
+    lastAgentMode?: AgentMode;
+    grounding?: SessionMessageGrounding;
+    observationMeta?: SessionMessageObservationMeta;
+    observationContent?: string;
+    thinkingTrace?: SessionThinkingTraceEntry[];
+    source?: SessionMessageSource;
+    taskType?: SessionMessageTaskType;
+    requestId?: string;
+    cronJobId?: string;
+    cronTitle?: string;
+    triggerType?: string;
+}): Promise<import("./types.js").SessionRecord>;
+export declare function appendContextEntry(sessionId: string, options: {
+    kind: SessionContextEntryKind;
+    content: string;
+    observationMeta: SessionMessageObservationMeta;
+    requestId?: string;
+}): Promise<import("./types.js").SessionRecord>;
+export declare function upsertArtifactPaths(sessionId: string, inputs: readonly SessionArtifactPathInput[]): Promise<import("./types.js").SessionRecord>;
+export declare function startRequestStream(sessionId: string, requestId: string): Promise<import("./types.js").SessionRecord>;
+export declare function appendRequestEvent(sessionId: string, requestId: string, payload: Record<string, unknown>): Promise<import("./types.js").SessionRecord>;
+export declare function compareAndSwapSessionMemoryCheckpoint(sessionId: string, command: SessionMemoryCheckpointCommit): Promise<import("./memory/contracts.js").SessionMemoryCheckpointCommitResult>;
+export declare function deleteMessage(sessionId: string, messageId: string): Promise<import("./types.js").SessionRecord | null>;
+export declare function deleteMessageWithStats(sessionId: string, messageId: string): Promise<import("./types.js").SessionMessageDeleteResult | null>;

package/dist/src/sessions/index.js

@@ -0,0 +1,64 @@
+import { buildContextBuckets, buildContextWindow } from "./context-window.js";
+import { SessionService } from "./session-service.js";
+const sessionService = new SessionService();
+export { buildContextBuckets, buildContextWindow };
+export function getOrCreateSession(sessionId) {
+    return sessionService.getOrCreateSession(sessionId);
+}
+export function getAllSessions() {
+    return sessionService.getAllSessions();
+}
+export function listSessions(params) {
+    return sessionService.listSessions(params);
+}
+export function getSessionById(sessionId) {
+    return sessionService.getSessionById(sessionId);
+}
+export function getSessionSnapshot(sessionId, options) {
+    return sessionService.getSessionSnapshot(sessionId, options);
+}
+export function updateSessionTitle(sessionId, title) {
+    return sessionService.updateSessionTitle(sessionId, title);
+}
+export function updateSessionRuntimeMode(sessionId, runtimeModeId) {
+    return sessionService.updateSessionRuntimeMode(sessionId, runtimeModeId);
+}
+export function getRequestReplayById(requestId, afterSeq = 0) {
+    return sessionService.getRequestReplayById(requestId, afterSeq);
+}
+export function deleteSession(sessionId) {
+    return sessionService.deleteSession(sessionId);
+}
+export function deleteSessionWithStats(sessionId) {
+    return sessionService.deleteSessionWithStats(sessionId);
+}
+export function resetSession(sessionId) {
+    return sessionService.resetSession(sessionId);
+}
+export function clearSessionMessages(sessionId) {
+    return sessionService.clearSessionMessages(sessionId);
+}
+export function appendMessage(sessionId, role, content, options = {}) {
+    return sessionService.appendMessage(sessionId, role, content, options);
+}
+export function appendContextEntry(sessionId, options) {
+    return sessionService.appendContextEntry(sessionId, options);
+}
+export function upsertArtifactPaths(sessionId, inputs) {
+    return sessionService.upsertArtifactPaths(sessionId, inputs);
+}
+export function startRequestStream(sessionId, requestId) {
+    return sessionService.startRequestStream(sessionId, requestId);
+}
+export function appendRequestEvent(sessionId, requestId, payload) {
+    return sessionService.appendRequestEvent(sessionId, requestId, payload);
+}
+export function compareAndSwapSessionMemoryCheckpoint(sessionId, command) {
+    return sessionService.compareAndSwapSessionMemoryCheckpoint(sessionId, command);
+}
+export function deleteMessage(sessionId, messageId) {
+    return sessionService.deleteMessage(sessionId, messageId);
+}
+export function deleteMessageWithStats(sessionId, messageId) {
+    return sessionService.deleteMessageWithStats(sessionId, messageId);
+}

package/dist/src/sessions/memory/contracts.d.ts

@@ -0,0 +1,29 @@
+export declare const SESSION_MEMORY_CHECKPOINT_KIND: "runtime_session_memory_checkpoint_v1";
+export declare const SESSION_MEMORY_SUMMARY_MAX_CHARACTERS = 12000;
+export type SessionMemoryMessageReference = Readonly<{
+    messageId: string;
+    fingerprint: string;
+}>;
+export type SessionMemoryCheckpoint = Readonly<{
+    kind: typeof SESSION_MEMORY_CHECKPOINT_KIND;
+    revision: number;
+    sourceRevision: string;
+    coveredMessages: readonly SessionMemoryMessageReference[];
+    summary: string;
+    createdAt: string;
+}>;
+export type SessionMemoryCheckpointCommit = Readonly<{
+    expectedSourceRevision: string;
+    expectedCheckpointRevision: number;
+    checkpoint: SessionMemoryCheckpoint;
+}>;
+export type SessionMemoryCheckpointCommitResult = Readonly<{
+    committed: true;
+    checkpoint: SessionMemoryCheckpoint;
+}> | Readonly<{
+    committed: false;
+    reason: "source_revision_mismatch" | "checkpoint_revision_mismatch";
+}>;
+export type SessionMemoryRepository = Readonly<{
+    compareAndSwapSessionMemoryCheckpoint(sessionId: string, command: SessionMemoryCheckpointCommit): Promise<SessionMemoryCheckpointCommitResult>;
+}>;

package/dist/src/sessions/memory/contracts.js

@@ -0,0 +1,2 @@
+export const SESSION_MEMORY_CHECKPOINT_KIND = "runtime_session_memory_checkpoint_v1";
+export const SESSION_MEMORY_SUMMARY_MAX_CHARACTERS = 12_000;

package/dist/src/sessions/memory/rules.d.ts

@@ -0,0 +1,5 @@
+import type { SessionRecord } from "../types.js";
+import { type SessionMemoryCheckpoint, type SessionMemoryCheckpointCommit, type SessionMemoryCheckpointCommitResult } from "./contracts.js";
+export declare function assertValidSessionMemoryCheckpoint(checkpoint: SessionMemoryCheckpoint): void;
+export declare function resolveSessionMemoryCheckpointCommit(session: SessionRecord, command: SessionMemoryCheckpointCommit): SessionMemoryCheckpointCommitResult;
+export declare function resolveApplicableSessionMemoryCheckpoint(session: SessionRecord): SessionMemoryCheckpoint | undefined;

package/dist/src/sessions/memory/rules.js

@@ -0,0 +1,77 @@
+import { SESSION_MEMORY_CHECKPOINT_KIND, SESSION_MEMORY_SUMMARY_MAX_CHARACTERS, } from "./contracts.js";
+import { resolveCoveredTurnCount, snapshotSessionMemorySource, } from "./source.js";
+const SHA256_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+export function assertValidSessionMemoryCheckpoint(checkpoint) {
+    const checkpointIsValid = hasValidCheckpointIdentity(checkpoint) &&
+        hasValidCheckpointCoverage(checkpoint) &&
+        hasValidCheckpointSummary(checkpoint) &&
+        hasValidCheckpointTimestamp(checkpoint);
+    if (!checkpointIsValid) {
+        throw new Error("session_memory_checkpoint_invalid");
+    }
+}
+export function resolveSessionMemoryCheckpointCommit(session, command) {
+    const source = snapshotSessionMemorySource(session);
+    if (source.sourceRevision !== command.expectedSourceRevision) {
+        return Object.freeze({
+            committed: false,
+            reason: "source_revision_mismatch",
+        });
+    }
+    const currentCheckpointRevision = session.sessionMemoryCheckpoint?.revision ?? 0;
+    if (currentCheckpointRevision !== command.expectedCheckpointRevision) {
+        return Object.freeze({
+            committed: false,
+            reason: "checkpoint_revision_mismatch",
+        });
+    }
+    assertValidSessionMemoryCheckpoint(command.checkpoint);
+    const expectedRevision = command.expectedCheckpointRevision + 1;
+    const coveredTurnCount = resolveCoveredTurnCount(source, command.checkpoint);
+    const checkpointIsBoundToCommit = command.checkpoint.revision === expectedRevision &&
+        command.checkpoint.sourceRevision === command.expectedSourceRevision &&
+        coveredTurnCount !== undefined;
+    if (!checkpointIsBoundToCommit) {
+        throw new Error("session_memory_checkpoint_binding_invalid");
+    }
+    return Object.freeze({
+        committed: true,
+        checkpoint: command.checkpoint,
+    });
+}
+export function resolveApplicableSessionMemoryCheckpoint(session) {
+    const checkpoint = session.sessionMemoryCheckpoint;
+    if (!checkpoint) {
+        return undefined;
+    }
+    try {
+        assertValidSessionMemoryCheckpoint(checkpoint);
+    }
+    catch {
+        return undefined;
+    }
+    const source = snapshotSessionMemorySource(session);
+    return resolveCoveredTurnCount(source, checkpoint) === undefined
+        ? undefined
+        : checkpoint;
+}
+function hasValidCheckpointIdentity(checkpoint) {
+    return (checkpoint.kind === SESSION_MEMORY_CHECKPOINT_KIND &&
+        Number.isSafeInteger(checkpoint.revision) &&
+        checkpoint.revision >= 1 &&
+        SHA256_PATTERN.test(checkpoint.sourceRevision));
+}
+function hasValidCheckpointCoverage(checkpoint) {
+    const coverage = checkpoint.coveredMessages;
+    if (coverage.length === 0) {
+        return false;
+    }
+    return coverage.every(({ messageId, fingerprint }) => messageId.trim().length > 0 && SHA256_PATTERN.test(fingerprint));
+}
+function hasValidCheckpointSummary(checkpoint) {
+    const summaryLength = checkpoint.summary.trim().length;
+    return (summaryLength > 0 && summaryLength <= SESSION_MEMORY_SUMMARY_MAX_CHARACTERS);
+}
+function hasValidCheckpointTimestamp(checkpoint) {
+    return Number.isFinite(Date.parse(checkpoint.createdAt));
+}

package/dist/src/sessions/memory/source.d.ts

@@ -0,0 +1,14 @@
+import type { SessionMessage, SessionRecord } from "../types.js";
+import type { SessionMemoryCheckpoint, SessionMemoryMessageReference } from "./contracts.js";
+export type SessionMemorySettledTurn = Readonly<{
+    userMessages: readonly SessionMessage[];
+    assistant: SessionMessage;
+}>;
+export type SessionMemorySourceSnapshot = Readonly<{
+    sourceRevision: string;
+    turns: readonly SessionMemorySettledTurn[];
+    messageReferences: readonly SessionMemoryMessageReference[];
+}>;
+export declare function snapshotSessionMemorySource(session: Pick<SessionRecord, "messages">): SessionMemorySourceSnapshot;
+export declare function resolveCoveredTurnCount(snapshot: SessionMemorySourceSnapshot, checkpoint: SessionMemoryCheckpoint | undefined): number | undefined;
+export declare function createSessionMemoryMessageReferences(turns: readonly SessionMemorySettledTurn[]): readonly SessionMemoryMessageReference[];

package/dist/src/sessions/memory/source.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+export function snapshotSessionMemorySource(session) {
+    const turns = collectSettledConversationTurns(session.messages);
+    const messageReferences = Object.freeze(turns.flatMap(turnMessages).map(createMessageReference));
+    return Object.freeze({
+        sourceRevision: fingerprint(messageReferences.map(({ fingerprint: value }) => value).join("\n")),
+        turns,
+        messageReferences,
+    });
+}
+export function resolveCoveredTurnCount(snapshot, checkpoint) {
+    if (!checkpoint) {
+        return 0;
+    }
+    const covered = checkpoint.coveredMessages;
+    if (covered.length > snapshot.messageReferences.length) {
+        return undefined;
+    }
+    const isExactPrefix = covered.every((reference, index) => {
+        const source = snapshot.messageReferences[index];
+        return (source?.messageId === reference.messageId &&
+            source.fingerprint === reference.fingerprint);
+    });
+    if (!isExactPrefix) {
+        return undefined;
+    }
+    return resolveTurnBoundary(snapshot.turns, covered.length);
+}
+export function createSessionMemoryMessageReferences(turns) {
+    return Object.freeze(turns.flatMap(turnMessages).map(createMessageReference));
+}
+function collectSettledConversationTurns(messages) {
+    const pendingUsers = [];
+    const turns = [];
+    for (const message of messages) {
+        if (!isConversationMessage(message)) {
+            continue;
+        }
+        if (message.role === "user") {
+            pendingUsers.push(message);
+            continue;
+        }
+        const userMessages = takePendingUsers(pendingUsers, message);
+        if (userMessages.length === 0) {
+            continue;
+        }
+        turns.push(Object.freeze({ userMessages, assistant: message }));
+    }
+    return Object.freeze(turns);
+}
+function isConversationMessage(message) {
+    return (message.grounding !== "tool_observation" &&
+        message.content.trim().length > 0);
+}
+function takePendingUsers(pendingUsers, assistant) {
+    const indexes = findPendingUserIndexes(pendingUsers, assistant);
+    const selected = indexes.map((index) => pendingUsers[index]);
+    for (const index of [...indexes].reverse()) {
+        pendingUsers.splice(index, 1);
+    }
+    return Object.freeze(selected);
+}
+function findPendingUserIndexes(pendingUsers, assistant) {
+    if (assistant.requestId) {
+        const exact = pendingUsers.flatMap((user, index) => user.requestId === assistant.requestId ? [index] : []);
+        if (exact.length > 0) {
+            return exact;
+        }
+        const fallback = findLastIndex(pendingUsers, (user) => !user.requestId);
+        return fallback >= 0 ? Object.freeze([fallback]) : Object.freeze([]);
+    }
+    const latest = pendingUsers.length - 1;
+    return latest >= 0 ? Object.freeze([latest]) : Object.freeze([]);
+}
+function findLastIndex(entries, predicate) {
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+        if (predicate(entries[index])) {
+            return index;
+        }
+    }
+    return -1;
+}
+function createMessageReference(message) {
+    return Object.freeze({
+        messageId: message.id,
+        fingerprint: fingerprint(JSON.stringify({
+            id: message.id,
+            role: message.role,
+            content: message.content,
+            createdAt: message.createdAt,
+            requestId: message.requestId ?? null,
+        })),
+    });
+}
+function turnMessages(turn) {
+    return [...turn.userMessages, turn.assistant];
+}
+function resolveTurnBoundary(turns, coveredMessageCount) {
+    if (coveredMessageCount === 0) {
+        return 0;
+    }
+    let messageCount = 0;
+    for (let index = 0; index < turns.length; index += 1) {
+        messageCount += turnMessages(turns[index]).length;
+        if (messageCount === coveredMessageCount) {
+            return index + 1;
+        }
+        if (messageCount > coveredMessageCount) {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function fingerprint(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}

package/dist/src/sessions/record/projection.d.ts

@@ -0,0 +1,25 @@
+import type { SessionRecord, SessionRequestRecord, SessionRequestReplay, SessionRuntimeEvent, SessionSnapshotMessage, SessionSnapshotRequest } from "../types.js";
+export declare function compactRequestEvents(events: SessionRuntimeEvent[]): SessionRuntimeEvent[];
+export declare function getSessionRequest(session: SessionRecord, requestId: string): SessionRequestRecord | null;
+export declare function normalizeLimit(limit: number | undefined): number;
+export declare function normalizeCursor(cursor: string | null | undefined): number;
+export declare function normalizeAfterSeq(afterSeq: number): number;
+export declare function toEpochMs(timestamp: string): number;
+export declare function toClientReplayEvent(event: SessionRuntimeEvent): Record<string, unknown>;
+export declare function getRequestFinalState(request: SessionRequestRecord): SessionRequestReplay["finalState"];
+export declare function isSameMessageId(messageId: string, requestedId: string): boolean;
+export declare function filterMessagesAfter(messages: SessionRecord["messages"], afterMessageId: string | number | null | undefined): SessionRecord["messages"];
+export declare function clientVisibleMessages(messages: SessionRecord["messages"]): SessionRecord["messages"];
+export declare function toSnapshotMessage(sessionId: string, message: SessionRecord["messages"][number], requests: SessionRequestRecord[]): SessionSnapshotMessage;
+export declare function toSnapshotRequest(request: SessionRequestRecord): SessionSnapshotRequest;
+export declare function normalizeSessionTitle(title: string): string;
+export declare function toSessionListItem(session: SessionRecord): {
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+    lastMessagePreview: string;
+    lastMessageAt: number | null;
+    latestMessageId: string | number | null;
+    latestAssistantMessageId: string | number | null;
+};