Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { ContentTypes, ErrorTypes } from 'librechat-data-provider';
import {
COMPACTION_SEMANTIC_INDEX_PROJECTION_VERSION,
MAX_COMPACTION_SEMANTIC_INDEX_ENTRIES,
MAX_COMPACTION_SEMANTIC_INDEX_IDENTITY_LENGTH,
MAX_COMPACTION_SEMANTIC_INDEX_SOURCE_CONTENT_INDEX,
MAX_COMPACTION_SEMANTIC_INDEX_TEXT_LENGTH,
isCompactionSemanticIndexProjection,
} from '@librechat/data-schemas';
import type {
CompactionSemanticIndex,
CompactionSemanticIndexEntry,
CompactionSemanticIndexSnapshot,
} from '@librechat/agents';
import type {
ICompactionSemanticIndexProjection,
TCompactionSemanticIndexEntry,
} from '@librechat/data-schemas';
import type { SummaryContentPart, TMessageContentParts } from 'librechat-data-provider';
import type { IAgentEventActorSummary } from '@librechat/data-schemas';
import type { ErrorTurnAnnouncement, ErrorTurnStampStore } from '~/conversations/announce';
import { getPreliminaryResponseMessageId } from '~/utils/message';
import { createAgentEventActorSummary } from './compatibility';
import { announceErrorTurn } from '~/conversations/announce';
/** Text of a summary content part, in any persisted shape — `content` blocks
* today, a string `content` or a bare `text` on rows written before them.
* Empty for anything else. */
export function getSummaryPartText(part: TMessageContentParts | null | undefined): string {
if (part?.type !== ContentTypes.SUMMARY) {
return '';
}
/** Widened on purpose: rows written before summary `content` blocks hold a
* string `content` or a bare `text`, neither of which the part type models. */
const content: unknown = part.content;
if (typeof content === 'string') {
return content.trim();
}
if (Array.isArray(content)) {
let text = '';
for (const block of content) {
if (block != null && typeof block === 'object' && 'text' in block) {
text += typeof block.text === 'string' ? block.text : '';
}
}
return text.trim();
}
return 'text' in part && typeof part.text === 'string' ? part.text.trim() : '';
}
/**
* A summary that can stand for the history it covers: it carries text, and its
* round both finished and did not error. A round that failed or was cut off
* keeps whatever deltas it streamed, so its text is a truncated prefix of the
* history it was summarizing rather than a checkpoint for it — the same test
* `isCompactedLeaf` applies when deciding whether a compaction can be retried.
*
* `failed` has only been stamped since the server began recording errored
* rounds, so the flags alone cannot vouch for older rows. The aggregator gives
* the structural answer: deltas stream `content` blocks into the part, and only
* a completed round replaces it with the final block, which is the only writer
* of `boundary`. A `content`-block summary without one therefore never
* finished, however it was stored. Rows in the bare-`text` shape predate that
* aggregator and are left to the flags.
*/
export function isUsableSummaryPart(part: unknown): part is SummaryContentPart {
if (part == null || typeof part !== 'object' || !('type' in part)) {
return false;
}
if (part.type !== ContentTypes.SUMMARY) {
return false;
}
/** Narrowed by the discriminant above: this is the summary union member. */
const summary = part as SummaryContentPart;
if (summary.failed === true || summary.summarizing === true) {
return false;
}
if (Array.isArray(summary.content) && summary.boundary == null) {
return false;
}
return getSummaryPartText(summary).length > 0;
}
/**
* The summary a message offers as the conversation's checkpoint: the last
* usable one in its content (last-summary-wins). Null when the message carries
* none — an empty or failed summary leaves the history it hangs off in place.
*/
export function findCheckpointSummaryPart(content: unknown): SummaryContentPart | null {
if (!Array.isArray(content)) {
return null;
}
let checkpoint: SummaryContentPart | null = null;
for (const part of content) {
if (isUsableSummaryPart(part)) {
checkpoint = part;
}
}
return checkpoint;
}
/** The fields a history row offers when it may be a summary checkpoint. */
export interface CheckpointCandidate {
content?: unknown;
summary?: string | null;
summaryTokenCount?: number | null;
tokenCount?: number | null;
}
/**
* The row a history read stops at, as it enters the prompt, or null when the
* row is no checkpoint and the read continues past it. A content-block summary
* keeps the row from that summary on: a response that summarized mid-run keeps
* producing after it, and the SDK formatter (`applySummaryBoundary`) promotes
* the summary and keeps the parts that follow, exactly as it does when the full
* history is sent. A sliced row drops its stored token count, which still covers
* the parts before the summary, so the prompt is charged for what it sends. A
* legacy `summary` field replaces the whole row.
*/
export function resolveCheckpointMessage<T extends CheckpointCandidate>(
message: T,
): (T & { role?: 'system' }) | null {
const summaryPart = findCheckpointSummaryPart(message.content);
if (summaryPart != null && Array.isArray(message.content)) {
const summaryIndex = message.content.lastIndexOf(summaryPart);
return summaryIndex === 0
? message
: { ...message, content: message.content.slice(summaryIndex), tokenCount: undefined };
}
if (!message.summary) {
return null;
}
return {
...message,
role: 'system',
content: [{ type: ContentTypes.TEXT, text: message.summary }],
tokenCount: message.summaryTokenCount ?? message.tokenCount,
};
}
/**
* The summary a warm event-actor continuation carries forward: the last usable
* one in the run's content parts, stamped as actor state. A failed or
* unfinished round's partial deltas would otherwise be persisted as actor state
* and handed to the next run as its `initialSummary`, which skips durable
* history entirely. A missing or invalid token count is recorded as zero.
*/
export function getLatestEventActorSummary(
contentParts: unknown,
): IAgentEventActorSummary | undefined {
if (!Array.isArray(contentParts)) {
return undefined;
}
for (let index = contentParts.length - 1; index >= 0; index -= 1) {
const part: unknown = contentParts[index];
if (!isUsableSummaryPart(part)) {
continue;
}
const tokenCount = part.tokenCount;
return createAgentEventActorSummary({
text: getSummaryPartText(part),
tokenCount:
typeof tokenCount === 'number' && Number.isFinite(tokenCount) && tokenCount >= 0
? tokenCount
: 0,
});
}
return undefined;
}
/** The typed failure a manual compaction reports when it produced no summary. */
const COMPACTION_FAILED_ERROR = JSON.stringify({ type: ErrorTypes.COMPACTION_FAILED });
/**
* The content a failed manual compaction persists: the typed failure, marked as
* the compaction's own outcome. A turn saved from a thrown failure has no
* content of its own, so without this the row is indistinguishable from an
* answer to the message it hangs off and keeps that message's rerun controls.
*/
function compactionFailureContent(
errorText: string = COMPACTION_FAILED_ERROR,
): TMessageContentParts[] {
return [{ type: ContentTypes.ERROR, error: errorText, initiatedBy: 'user' }];
}
/**
* The content fields a failed turn is persisted with. A manual compaction owns
* its identity through content, so its row carries the marked failure; every
* other failed turn contributes nothing and keeps its text-only shape. Callers
* spread the result rather than deciding which turns are compactions.
*/
export function resolveFailedTurnContent(
requestBody: { compact?: boolean } | null | undefined,
errorText: string,
): { content?: TMessageContentParts[] } {
if (requestBody?.compact !== true) {
return {};
}
return { content: compactionFailureContent(errorText) };
}
/**
* The content an aborted compaction persists: the run's stream-aggregated
* parts, carrying the marker that keeps the turn identifiable as a compaction.
* The abort path owns a cancelled run's row (a stopped turn is unfinished, not
* failed) and nothing else on that path knows the request was a compaction, so
* without this the row reads as an answer to the message it hangs off and keeps
* that message's rerun controls: on a branch ending in a user message,
* Regenerate would answer the user turn behind the compaction instead of
* redoing it.
*
* A terminal abort (Stop) settles the turn, so it applies the completed run's
* outcome rules: a usable summary is marked as the outcome; a partial one
* keeps its text but is marked `failed`, or its label would present the
* truncated prefix as a finished checkpoint; a placeholder that never streamed
* text goes, leaving the typed failure as the row's outcome. A non-terminal
* snapshot (`synthesizeFailure: false`, the disconnect save the run may still
* complete and overwrite) marks what is there and rewrites nothing else.
* Content from a turn that was not a compaction is returned unchanged, and
* the parts are never edited in place: the aggregated parts belong to the
* still-live run on the disconnect path, so every stamped part is a copy.
*/
export function markAbortedCompactionContent(
contentParts: TMessageContentParts[],
isCompaction: boolean,
{ synthesizeFailure = true }: { synthesizeFailure?: boolean } = {},
): TMessageContentParts[] {
if (!isCompaction) {
return contentParts;
}
const marked: TMessageContentParts[] = [];
let hasOutcome = false;
let removedUnfinishedRound = false;
for (const part of contentParts) {
if (part == null) {
marked.push(part);
continue;
}
if (part.type === ContentTypes.ERROR) {
marked.push({ ...part, initiatedBy: 'user' as const });
hasOutcome = true;
removedUnfinishedRound = false;
continue;
}
if (part.type !== ContentTypes.SUMMARY) {
marked.push(part);
continue;
}
/** The usability predicate's false side narrows the part's type away, so
* the reference is taken before it runs. */
const summary = part;
if (isUsableSummaryPart(part)) {
marked.push({ ...summary, initiatedBy: 'user' as const });
hasOutcome = true;
removedUnfinishedRound = false;
continue;
}
if (!synthesizeFailure) {
marked.push({ ...summary, initiatedBy: 'user' as const });
continue;
}
if (isSummaryPartWithText(summary)) {
marked.push({ ...summary, initiatedBy: 'user' as const, failed: true });
hasOutcome = true;
removedUnfinishedRound = false;
continue;
}
/** A later outcome supersedes this placeholder's round; the flag is
* cleared whenever an outcome follows, so only a round opened after the
* latest outcome synthesizes the failure. */
removedUnfinishedRound = true;
}
/** An earlier round's checkpoint is not this round's outcome: a round the
* run opened but never finished still records the typed failure beside it,
* or the stopped turn reads as the successful compaction the checkpoint
* describes. */
if ((!hasOutcome || removedUnfinishedRound) && synthesizeFailure) {
marked.push(...compactionFailureContent());
}
return marked;
}
/** Whether a job record's durable final event is a reconciliation frame: the
* conservative substitute published when the terminal row write failed, so
* no message row backs the terminal claim. */
function hasDurableReconcileFrame(finalEvent: unknown): boolean {
if (typeof finalEvent !== 'string' || finalEvent.length === 0) {
return false;
}
try {
const parsed = JSON.parse(finalEvent) as { reconcile?: unknown } | null;
return parsed?.reconcile === true;
} catch {
return false;
}
}
/** Whether a job record has reached a status whose path owns the turn's final
* row (completion, error, or abort): the disconnect snapshot must not be
* written over it, or the settled row reopens as an unfinished response.
* Only a same-epoch record is trusted, and only one whose terminal write
* actually landed. */
export function isSettledJobRecord(
jobRecord:
| {
createdAt?: number;
status?: string;
terminalPersistencePending?: boolean;
finalEvent?: string;
}
| null
| undefined,
jobCreatedAt?: number,
): boolean {
if (jobRecord == null || (jobCreatedAt != null && jobRecord.createdAt !== jobCreatedAt)) {
return false;
}
if (jobRecord.terminalPersistencePending === true) {
/** The terminal claim precedes its row write: the status alone does not
* prove the row is durable, and the snapshot is still the fallback if
* that write fails. */
return false;
}
if (hasDurableReconcileFrame(jobRecord.finalEvent)) {
/** The terminal write failed and a reconciliation frame was published in
* its place: nothing was persisted for the turn, so the streamed
* snapshot remains its only row. */
return false;
}
return (
jobRecord.status === 'complete' ||
jobRecord.status === 'error' ||
jobRecord.status === 'aborted'
);
}
/** How a disconnect may persist this turn's snapshot. */
export type DisconnectSnapshotMode =
/** The run is still live: the snapshot keeps the live shape. */
| 'live'
/** The terminal write failed and settled for a reconciliation frame: the
* snapshot is the turn's only row, so it persists with the terminal
* outcome and envelope. */
| 'terminal'
/** A durable terminal row exists: the snapshot is withheld so it cannot
* reopen the settled turn. */
| 'skip';
/** The row flags a promoted compaction snapshot settles with, keyed by the
* reconciled claim's status: a stopped compaction is settled like the abort
* route writes it (nothing continues it), a completed run is a finished row,
* and everything else takes the error envelope. */
export function resolveReconciledSnapshotEnvelope(status: unknown): {
unfinished: boolean;
error: boolean;
} {
if (status === 'aborted' || status === 'complete') {
return { unfinished: false, error: false };
}
return { unfinished: false, error: true };
}
/**
* How the last-subscriber disconnect may persist this turn's snapshot. An
* ordinary turn always keeps its live snapshot as the fallback row: its job
* record cannot prove a response row landed. A compaction whose settling path
* (completion, error, abort) durably owns the final row withholds the
* snapshot, so it cannot reopen the settled turn. A same-epoch compaction
* whose terminal claim settled for a reconciliation frame is promoted to the
* terminal row, but a reconciliation frame does not prove the row is missing
* (an error turn can land before it), so the response row is read first and a
* settled one withholds the promotion; the anchor must be persisted too, or
* the promotion would recreate the orphan an absent-anchor abort withheld.
*/
export async function resolveDisconnectSnapshotMode(
isCompaction: boolean,
jobRecord:
| {
createdAt?: number;
status?: string;
terminalPersistencePending?: boolean;
finalEvent?: string;
}
| null
| undefined,
jobCreatedAt: number | undefined,
{
anchorExists = async () => true,
responseRowSettled = async () => false,
}: {
anchorExists?: () => Promise<boolean>;
/** Whether a finished (not `unfinished`) response row already exists. */
responseRowSettled?: () => Promise<boolean>;
} = {},
): Promise<DisconnectSnapshotMode> {
if (!isCompaction) {
return 'live';
}
if (isSettledJobRecord(jobRecord, jobCreatedAt)) {
return 'skip';
}
/** Another epoch's reconciliation frame belongs to a different
* generation and never promotes this one's snapshot. */
const sameEpoch = jobCreatedAt == null || jobRecord?.createdAt === jobCreatedAt;
if (!sameEpoch || !hasDurableReconcileFrame(jobRecord?.finalEvent)) {
return 'live';
}
/** Both reads are scoped to the turn's user and independent, so they run
* together; a settled row still wins over a persisted anchor. */
const [settled, anchored] = await Promise.all([responseRowSettled(), anchorExists()]);
return !settled && anchored ? 'terminal' : 'skip';
}
/**
* Every id a compaction's finished row can carry: the response id the stream
* preallocated, and the id the failed-turn path writes its error row under,
* derived from the anchor exactly as that path derives it. A settled row under
* either already ends the turn.
*/
function terminalRowIds(anchorMessageId: string, responseMessageId: string): string[] {
const errorRowId = getPreliminaryResponseMessageId({
compact: true,
messageId: anchorMessageId,
liveResponseMessageId: responseMessageId,
});
/** An anchor ending in one underscore derives itself; the failed-turn path
* then redirects its error row to the response id, so the anchor is never a
* terminal identity. */
return errorRowId == null || errorRowId === responseMessageId || errorRowId === anchorMessageId
? [responseMessageId]
: [responseMessageId, errorRowId];
}
/** What the last-subscriber disconnect writes for this turn, if anything. */
export type DisconnectSnapshotPlan =
| { write: false }
| {
write: true;
content: TMessageContentParts[];
unfinished: boolean;
error: boolean;
};
/**
* Plans the last-subscriber disconnect snapshot through the caller's message
* reader: the mode, the marked content, and the row envelope. The caller only
* builds and writes the row, inside its own tenant context (the reads here
* run in it too). A live snapshot with nothing persistable is skipped; a
* promoted terminal snapshot synthesizes its outcome even from empty content.
*/
export async function planDisconnectSnapshot(
isCompaction: boolean,
{
content,
jobRecord,
jobCreatedAt,
userId,
conversationId,
anchorMessageId,
responseMessageId,
liveSaved = false,
getMessages,
onReadError,
}: {
/** The streamed content, already filtered to persistable parts. */
content: TMessageContentParts[];
jobRecord: Parameters<typeof resolveDisconnectSnapshotMode>[1];
jobCreatedAt: number | undefined;
userId: string;
conversationId: string;
anchorMessageId: string;
responseMessageId: string;
/** This process already wrote a live snapshot of the turn: only a terminal
* promotion writes again. */
liveSaved?: boolean;
getMessages: (
filter: { user: string; messageId: string; conversationId: string },
projection?: string,
) => Promise<ReadableMessageRow[]>;
/** Receives a row read that failed while planning. */
onReadError?: (error: unknown) => void;
},
): Promise<DisconnectSnapshotPlan> {
/** A failed row read proves nothing either way: it is reported, nothing is
* written, and the next disconnect plans again. */
let mode: DisconnectSnapshotMode;
try {
mode = await resolveDisconnectSnapshotMode(isCompaction, jobRecord, jobCreatedAt, {
anchorExists: async () =>
(await getMessages({ user: userId, messageId: anchorMessageId, conversationId }, '_id'))
.length > 0,
responseRowSettled: async () => {
const rows = await Promise.all(
terminalRowIds(anchorMessageId, responseMessageId).map((messageId) =>
getMessages({ user: userId, messageId, conversationId }, '_id unfinished'),
),
);
return rows.some(([row]) => row != null && row.unfinished !== true);
},
});
} catch (error) {
onReadError?.(error);
return { write: false };
}
if (mode === 'skip' || (mode === 'live' && (liveSaved || content.length === 0))) {
return { write: false };
}
const marked = markAbortedCompactionContent(content, isCompaction, {
synthesizeFailure: mode === 'terminal',
});
if (marked.length === 0) {
return { write: false };
}
return {
write: true,
content: marked,
...(mode === 'terminal'
? resolveReconciledSnapshotEnvelope(jobRecord?.status)
: { unfinished: true, error: false }),
};
}
/**
* Stamps a promoted disconnect snapshot on its conversation once it is
* written: it is the turn's terminal row, so another device must learn the
* turn ended exactly as it would from any persisted terminal turn. A live
* snapshot is a fallback, not a reply, and stays unannounced. Never throws.
*/
export async function announceDisconnectSnapshot(
deps: ErrorTurnStampStore,
plan: DisconnectSnapshotPlan,
announcement: ErrorTurnAnnouncement,
): Promise<void> {
if (!plan.write || plan.unfinished) {
return;
}
await announceErrorTurn(deps, announcement);
}
/**
* Runs a turn's disconnect snapshots one at a time and plans the snapshot once
* more when the turn settles, before its terminal cleanup releases the content
* and resume state the plan reads. Once every subscriber has left, no further
* disconnect arrives, so a terminal write that failed afterwards would leave a
* compaction's live snapshot (or nothing, when it left before any content)
* without its terminal outcome. Serializing keeps an earlier live write from
* landing over the promoted row.
*/
export function createDisconnectSnapshotQueue({
isCompaction,
persist,
readContent,
onSettleError,
}: {
isCompaction: boolean;
/** Plans and writes one snapshot of the turn's content. */
persist: (content: TMessageContentParts[]) => Promise<void>;
/** The turn's stored content once it settled. */
readContent: () => Promise<TMessageContentParts[]>;
onSettleError?: (error: unknown) => void;
}): {
onDisconnect: (content: TMessageContentParts[]) => Promise<void>;
settle: () => Promise<void>;
} {
let pending: Promise<void> = Promise.resolve();
let disconnected = false;
const enqueue = (write: () => Promise<void>): Promise<void> => {
const next = pending.then(write);
pending = next.catch(() => undefined);
return next;
};
return {
onDisconnect: (content) => {
disconnected = true;
return enqueue(() => persist(content));
},
settle: async () => {
if (!isCompaction || !disconnected) {
return;
}
try {
await enqueue(async () => persist(await readContent()));
} catch (error) {
onSettleError?.(error);
}
},
};
}
/** How the abort route persists a stopped turn's prerequisite rows. */
export type AbortAnchorDecision = 'persist' | 'skip-anchor' | 'skip-turn';
/**
* Decides how a stopped turn's persistence treats its user row, reading the
* anchor through the caller's database reader. A compaction's `userMessage`
* is the branch leaf projected for identity only: when the leaf is persisted,
* the projection must never be upserted over it (an ordinary prerequisite
* write would erase a user leaf's text or turn an assistant leaf into an
* empty user row), so only the aborted response is written. When the leaf is
* NOT persisted, Stop won the race before the branch loaded and there is
* nothing to anchor the response onto, so nothing is written at all; a read
* that fails says the same thing, without throwing past the caller's
* remaining cleanup. Ordinary turns keep the prerequisite write.
*/
export async function resolveAbortedTurnAnchorDecision(
jobData:
| {
compact?: boolean;
conversationId?: string;
userMessage?: { messageId?: string } | null;
}
| null
| undefined,
{
messageExists,
}: { messageExists: (messageId: string, conversationId?: string) => Promise<boolean> },
): Promise<AbortAnchorDecision> {
if (jobData?.compact !== true) {
return 'persist';
}
/** A compaction with no anchor id has nothing to hang its response on. */
const anchorId = jobData.userMessage?.messageId;
if (anchorId == null || anchorId.length === 0) {
return 'skip-turn';
}
try {
const anchorExists = await messageExists(anchorId, jobData.conversationId);
return anchorExists ? 'skip-anchor' : 'skip-turn';
} catch {
return 'skip-turn';
}
}
/** The abort route's persistence plan for a stopped turn: which rows to write
* and whether the normal FINAL must be withheld (the manager publishes a
* reconciliation frame instead, so the client is never pointed at a response
* that was deliberately never persisted). */
export interface AbortedTurnPersistencePlan {
writeUserRow: boolean;
writeResponseRow: boolean;
/** An ordinary stopped reply stays `unfinished` so it can be continued; a
* stopped compaction is settled, since nothing continues it and a live
* envelope would keep restored sessions reading it as still running. */
responseUnfinished: boolean;
withholdFinal: boolean;
withholdReason?: string;
}
export function planAbortedTurnPersistence(
anchorDecision: AbortAnchorDecision,
shouldPersistAbortedTurn: boolean,
): AbortedTurnPersistencePlan {
const active = shouldPersistAbortedTurn && anchorDecision !== 'skip-turn';
/** Withholding the FINAL only matters when a row would otherwise have been
* written: an abort with no persistable content and no created event
* publishes an early-abort FINAL of its own, and nothing was withheld. */
const withhold = shouldPersistAbortedTurn && anchorDecision === 'skip-turn';
return {
writeUserRow: active && anchorDecision === 'persist',
writeResponseRow: active,
responseUnfinished: anchorDecision === 'persist',
withholdFinal: withhold,
...(withhold && {
withholdReason: 'Compaction anchor unavailable; abort turn withheld',
}),
};
}
/**
* The abort route's whole persistence decision for a stopped turn: reads the
* compaction anchor through the caller's message reader (id-only), plans the
* rows, and returns the failures the route must report so the manager
* publishes a reconciliation frame instead of a normal FINAL.
*/
export async function resolveAbortedTurnPersistence(
jobData: Parameters<typeof resolveAbortedTurnAnchorDecision>[0],
shouldPersistAbortedTurn: boolean,
{
userId,
getMessages,
}: {
userId?: string;
getMessages: (
filter: { user?: string; messageId: string; conversationId?: string },
projection?: string,
) => Promise<unknown[]>;
},
): Promise<AbortedTurnPersistencePlan & { persistenceErrors: Error[] }> {
/** No row to write means no anchor to verify: the read is skipped, so an
* outage cannot turn an early abort's own FINAL into a reconciliation. */
if (!shouldPersistAbortedTurn) {
return { ...planAbortedTurnPersistence('persist', false), persistenceErrors: [] };
}
/** A failed read still resolves to skip-turn, so cleanup runs; the failure
* itself is reported beside the withheld turn, keeping an outage
* distinguishable from an absent anchor at the caller's error boundary. */
let readError: Error | undefined;
const anchorDecision = await resolveAbortedTurnAnchorDecision(jobData, {
messageExists: async (messageId, conversationId) => {
try {
return (await getMessages({ user: userId, messageId, conversationId }, '_id')).length > 0;
} catch (error) {
readError = error instanceof Error ? error : new Error(String(error));
throw error;
}
},
});
const plan = planAbortedTurnPersistence(anchorDecision, shouldPersistAbortedTurn);
const persistenceErrors: Error[] = [];
if (readError != null) {
persistenceErrors.push(readError);
}
if (plan.withholdFinal && plan.withholdReason) {
persistenceErrors.push(new Error(plan.withholdReason));
}
return { ...plan, persistenceErrors };
}
/** A message row as the failed-turn settlement reads it: identity for the
* anchor-shaped check, content and envelope for the live row it finalizes. */
export type ReadableMessageRow = {
messageId: string;
content?: unknown;
unfinished?: boolean;
};
/** How a failed generation's fresh error row proceeds after its existing rows
* are settled. */
export type ErrorTurnSettlement =
/** An existing row covers the turn; the caller skips the error row. */
| { covered: true }
/** The error row is written under `errorRowMessageId`: the error id
* itself, or the live response id when the anchor-shaped collision makes
* the error id unusable for it. */
| { covered: false; errorRowMessageId: string };
/**
* Settles the rows a failed generation already persisted before its error row
* is written, through the caller's injected reads and write.
*
* The error id can normalize back to the compaction anchor itself when the
* anchor ends in `_`: a match there never receives the error row, and the
* failed run settles its own distinct live response row instead. When no live
* row exists either, the error row is still written, redirected to the live
* response id so it can never overwrite the anchor. Ordinary turns keep their
* existing behavior: a found partial row is preserved as it stands and blocks
* the error row.
*/
export async function settleExistingRowsBeforeErrorTurn(
requestBody: { compact?: boolean } | null | undefined,
{
userId,
conversationId,
errorMessageId,
liveResponseMessageId,
getMessages,
saveFinalizedTurn,
announceSettledTurn,
}: {
userId: string;
conversationId: string;
errorMessageId: string;
liveResponseMessageId?: string | null;
getMessages: (
filter: { user: string; messageId: string; conversationId: string },
projection?: string,
) => Promise<ReadableMessageRow[]>;
saveFinalizedTurn: (message: Record<string, unknown>) => Promise<unknown>;
/** Announces a row this settlement finalized, as the error row's own
* path does, so other devices learn the persisted turn ended. */
announceSettledTurn?: (messageId: string) => Promise<unknown>;
},
): Promise<ErrorTurnSettlement> {
const isCompaction = requestBody?.compact === true;
const settleLiveRow = async (): Promise<boolean> => {
if (liveResponseMessageId == null) {
return false;
}
/** Full documents only where the compaction finalization needs the
* content; ordinary failures keep the id-only projection. */
const partial = await getMessages(
{ user: userId, messageId: liveResponseMessageId, conversationId },
isCompaction ? undefined : '_id',
);
if (partial.length === 0) {
return false;
}
const finalized = await persistFinalizedCompactionTurn(partial[0], requestBody, {
messageId: liveResponseMessageId,
conversationId,
saveMessage: saveFinalizedTurn,
});
if (finalized) {
await announceSettledTurn?.(liveResponseMessageId);
}
return true;
};
/** The bounded fallback already names this run's response, not the anchor. */
if (isCompaction && errorMessageId === liveResponseMessageId) {
return (await settleLiveRow())
? { covered: true }
: { covered: false, errorRowMessageId: errorMessageId };
}
const existing = await getMessages(
{ user: userId, messageId: errorMessageId, conversationId },
'_id',
);
if (existing.length > 0) {
if (!isCompaction) {
return { covered: true };
}
if (await settleLiveRow()) {
return { covered: true };
}
/** The match is the anchor itself: the error row goes to the failed
* run's own response id when one exists, and is withheld entirely when
* none does (a failure before the id was allocated), because writing it
* under the error id would overwrite the anchor. */
if (liveResponseMessageId != null && liveResponseMessageId !== errorMessageId) {
return { covered: false, errorRowMessageId: liveResponseMessageId };
}
return { covered: true };
}
if (liveResponseMessageId !== errorMessageId && (await settleLiveRow())) {
return { covered: true };
}
return { covered: false, errorRowMessageId: errorMessageId };
}
/**
* Finalizes a failed compaction's already-persisted partial row, with the
* write injected so the operation runs against whatever persistence the
* caller owns. The row settles with the terminal envelope the error path
* writes (an errored, finished turn): with the snapshot's `unfinished` flag
* left in place, restored sessions and downstream readers would keep
* classifying the failed turn as an incomplete response. Returns whether a
* write happened.
*/
export async function persistFinalizedCompactionTurn(
partialRow: { content?: unknown } | null | undefined,
requestBody: { compact?: boolean } | null | undefined,
{
messageId,
conversationId,
saveMessage,
}: {
messageId: string;
conversationId: string;
saveMessage: (message: Record<string, unknown>) => Promise<unknown>;
},
): Promise<boolean> {
const finalized = resolveFinalizedCompactionTurn(partialRow, requestBody);
if (!finalized.write) {
return false;
}
const saved = await saveMessage({
messageId,
conversationId,
unfinished: false,
error: true,
...(finalized.content != null && { content: finalized.content }),
});
if (saved == null) {
/** The same contract the surrounding failed-turn persistence holds: a
* falsy save is a failure to settle, not a settled row. */
throw new Error('Failed compaction turn could not be finalized');
}
return true;
}
/** What a failed compaction does with its already-persisted partial row. */
export type FinalizedCompactionTurn =
/** Not the failed run's row, or one holding nothing but a completed
* checkpoint on a row that was already settled. */
| { write: false }
/** The terminal marking is applied to the parts (a legacy or snapshot row
* may carry failure parts that never got the identity marker) and the row
* settles with the terminal envelope. */
| { write: true; content: TMessageContentParts[] };
/**
* The disconnect save is marker-only because the run is still live when it
* fires, so when the run then fails that snapshot is the row that stays: a
* partial summary is marked failed beside its text, a snapshot with no
* summary or error part gets the typed failure, and a snapshot whose parts
* already carry the failure has the terminal marking reapplied (idempotent
* for marked parts, stamping legacy parts that predate the marker) beside
* its settled envelope. A completed checkpoint is preserved as content, but a
* snapshot still flagged `unfinished` settles its envelope even then, or the
* restored conversation keeps treating the terminal job as live; a row that
* was already settled is left alone. Rows of turns that were not compactions
* are never written.
*/
export function resolveFinalizedCompactionTurn(
partialRow: { content?: unknown; unfinished?: boolean } | null | undefined,
requestBody: { compact?: boolean } | null | undefined,
): FinalizedCompactionTurn {
if (requestBody?.compact !== true) {
return { write: false };
}
/** A settled row belongs to the path that settled it, whatever its
* parts hold: a late failure must not rewrite or re-announce it. */
if (partialRow?.unfinished === false) {
return { write: false };
}
const content = Array.isArray(partialRow?.content)
? (partialRow.content as TMessageContentParts[])
: [];
/** Every part is inspected: a row can hold an earlier round's terminal
* outcome beside a later unfinished summary, and that summary still needs
* its failure marked. */
let sawFailure = false;
let sawCheckpoint = false;
let unfinishedSummary = false;
for (const part of content) {
if (part?.type === ContentTypes.SUMMARY) {
if (part.failed === true) {
sawFailure = true;
} else if (isUsableSummaryPart(part)) {
sawCheckpoint = true;
} else {
unfinishedSummary = true;
}
} else if (part?.type === ContentTypes.ERROR) {
sawFailure = true;
}
}
if (unfinishedSummary || sawFailure) {
return { write: true, content: markAbortedCompactionContent(content, true) };
}
if (sawCheckpoint) {
return partialRow?.unfinished === true
? { write: true, content: markAbortedCompactionContent(content, true) }
: { write: false };
}
return { write: true, content: markAbortedCompactionContent(content, true) };
}
/**
* Stamps `initiatedBy: 'user'` on the part that carries a manual compaction's
* outcome, which is the turn's only record of having been one: the run emits no
* text of its own, and a compaction hangs off whatever leaf the branch ends
* with, so a reader cannot infer it from the turn's shape or its parent.
*
* Every outcome is marked. A run that produced a summary marks it; a run that
* recorded why it could not (an error part, e.g. a skipped compaction) marks
* that instead; a run that produced neither records the typed failure here, so
* it persists and streams like any other failed compaction rather than as an
* empty assistant message. A cancelled run keeps failing as a typed error: the
* turn stopped early rather than failing, and the abort path owns it.
*/
export function markCompactionOutcome(
contentParts: TMessageContentParts[],
{ aborted = false }: { aborted?: boolean } = {},
): void {
const summary = contentParts.find(isUsableSummaryPart);
if (summary != null) {
summary.initiatedBy = 'user';
return;
}
let markedFailure = false;
for (const part of contentParts) {
if (part?.type === ContentTypes.ERROR) {
part.initiatedBy = 'user';
markedFailure = true;
}
}
if (markedFailure) {
return;
}
if (aborted) {
throw Object.assign(new Error(COMPACTION_FAILED_ERROR), { code: 'COMPACTION_FAILED' });
}
/** A failed round keeps whatever deltas it streamed, and a summary part with
* text is the history boundary for everything downstream. Persisting a
* truncated one would stand in for the history it failed to summarize, so
* the unusable summary goes and the typed failure is the turn's whole
* outcome. */
for (let index = contentParts.length - 1; index >= 0; index -= 1) {
if (contentParts[index]?.type === ContentTypes.SUMMARY) {
contentParts.splice(index, 1);
}
}
contentParts.push(...compactionFailureContent());
}
function isSummaryPartWithText(part: unknown): boolean {
if (part == null || typeof part !== 'object' || !('type' in part)) {
return false;
}
if (part.type !== ContentTypes.SUMMARY) {
return false;
}
/** Narrowed by the discriminant above: this is the summary union member. */
const summary = part as SummaryContentPart;
return getSummaryPartText(summary).length > 0;
}
/** The content of one message with every unusable summary part removed, or the
* same array when there was nothing to remove. */
function withoutUnusableSummaryParts(content: unknown[]): unknown[] {
const filtered = content.filter(
(part) => isUsableSummaryPart(part) || !isSummaryPartWithText(part),
);
return filtered.length === content.length ? content : filtered;
}
/**
* Points one model-facing message at content free of the summary parts that
* cannot bound history, and reports whether anything went. The SDK's summary
* scan takes the last summary part carrying text as the conversation's history
* boundary and drops every message before it, reading neither `failed` nor
* `summarizing`: a round that errored or was cut off keeps the deltas it
* streamed, so leaving that part in would replace the history it never
* finished summarizing with the prefix it produced. An empty summary is left
* alone — it bounds nothing, and the renderer owns how it appears.
*
* The message gets a NEW content array rather than a spliced one, because a
* formatted prompt copy shares its content array with the stored message it
* came from: splicing would reindex the persisted row's parts under every
* reader that holds it. This belongs on a prompt copy before its token count
* is taken, so the count, the prompt total an admission check reads, and any
* later per-index adjustment all describe what the model actually receives.
*/
export function dropUnusableSummaryParts(message: { content?: unknown }): boolean {
const content = message?.content;
if (!Array.isArray(content)) {
return false;
}
const filtered = withoutUnusableSummaryParts(content);
if (filtered === content) {
return false;
}
message.content = filtered;
return true;
}
/**
* The same rule for a payload whose messages the caller may not touch:
* returns a payload of messages carrying no unusable summary part, leaving the
* input and its messages untouched and returning the same reference when
* nothing needed dropping. Message positions are preserved, so an index-keyed
* token map stays aligned.
*/
export function stripUnusableSummaryParts<T extends { content?: unknown }>(payload: T[]): T[] {
if (!Array.isArray(payload)) {
return payload;
}
let changed = false;
const result = payload.map((message) => {
const content = message?.content;
if (!Array.isArray(content)) {
return message;
}
const filtered = withoutUnusableSummaryParts(content);
if (filtered === content) {
return message;
}
changed = true;
return { ...message, content: filtered };
});
return changed ? result : payload;
}
function snapshotEntry(
entry: CompactionSemanticIndexEntry,
): TCompactionSemanticIndexEntry | undefined {
const { type, sourceMessageId, sourceContentIndex, revision, status, text, redacted } = entry;
if (
typeof sourceMessageId !== 'string' ||
sourceMessageId.length === 0 ||
sourceMessageId.length > MAX_COMPACTION_SEMANTIC_INDEX_IDENTITY_LENGTH ||
!Number.isSafeInteger(sourceContentIndex) ||
sourceContentIndex < 0 ||
sourceContentIndex > MAX_COMPACTION_SEMANTIC_INDEX_SOURCE_CONTENT_INDEX ||
!Number.isSafeInteger(revision) ||
revision < 0 ||
(status !== 'committed' && status !== 'pending') ||
typeof text !== 'string' ||
(redacted !== undefined && typeof redacted !== 'boolean')
) {
return undefined;
}
const oversized = text.length > MAX_COMPACTION_SEMANTIC_INDEX_TEXT_LENGTH;
const snapshotRedacted = redacted === true || oversized;
const snapshotText = status === 'pending' || snapshotRedacted ? '' : text;
const common = {
sourceMessageId,
sourceContentIndex,
revision,
status,
text: snapshotText,
...(redacted !== undefined || oversized ? { redacted: snapshotRedacted } : {}),
};
if (type === 'activity_phase') {
return { type, ...common };
}
if (type === 'reasoning_label') {
const reasoningStepId = entry.reasoningStepId;
if (
typeof reasoningStepId !== 'string' ||
reasoningStepId.length === 0 ||
reasoningStepId.length > MAX_COMPACTION_SEMANTIC_INDEX_IDENTITY_LENGTH
) {
return undefined;
}
return { type, reasoningStepId, ...common };
}
const toolCallId = entry.toolCallId;
if (
typeof toolCallId !== 'string' ||
toolCallId.length === 0 ||
toolCallId.length > MAX_COMPACTION_SEMANTIC_INDEX_IDENTITY_LENGTH
) {
return undefined;
}
return { type, toolCallId, ...common };
}
function isCompactionSemanticIndexSnapshot(
input: CompactionSemanticIndex | CompactionSemanticIndexSnapshot,
): input is CompactionSemanticIndexSnapshot {
return !Array.isArray(input);
}
export function createCompactionSemanticIndexProjection(
input: CompactionSemanticIndex | CompactionSemanticIndexSnapshot | undefined,
): ICompactionSemanticIndexProjection | undefined {
if (input == null) {
return undefined;
}
const isSnapshot = isCompactionSemanticIndexSnapshot(input);
const index = isSnapshot ? input.entries : input;
const providedEntryCount = isSnapshot ? input.providedEntryCount : input.length;
if (
!Array.isArray(index) ||
index.length === 0 ||
index.length > MAX_COMPACTION_SEMANTIC_INDEX_ENTRIES ||
providedEntryCount == null ||
!Number.isSafeInteger(providedEntryCount) ||
providedEntryCount < index.length
) {
return undefined;
}
const entries: TCompactionSemanticIndexEntry[] = [];
for (const entry of index) {
const snapshot = snapshotEntry(entry);
if (snapshot == null) {
return undefined;
}
entries.push(snapshot);
}
return {
version: COMPACTION_SEMANTIC_INDEX_PROJECTION_VERSION,
entries,
providedEntryCount,
};
}
export function restoreCompactionSemanticIndexSnapshot(
projection: ICompactionSemanticIndexProjection | null | undefined,
): CompactionSemanticIndexSnapshot | undefined {
if (!isCompactionSemanticIndexProjection(projection)) {
return undefined;
}
const entries: CompactionSemanticIndexEntry[] = [];
for (const entry of projection.entries) {
const snapshot = snapshotEntry(entry);
if (snapshot == null) {
return undefined;
}
entries.push(Object.freeze(snapshot));
}
return Object.freeze({
entries: Object.freeze(entries),
providedEntryCount: projection.providedEntryCount ?? entries.length,
});
}