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 { Buffer } from 'node:buffer';
import {
RetentionMode,
isForcedTemporaryRetention,
UNSEEN_REPLY_WATERMARK,
} from 'librechat-data-provider';
import type {
AnyBulkWriteOperation,
DeleteResult,
FilterQuery,
Model,
SortOrder,
Types,
UpdateQuery,
} from 'mongoose';
import type { SearchParams } from 'meilisearch';
import type {
IAgentEventActorCheckpoint,
IAgentEventActorReconciliation,
IAgentEventActorSnapshot,
IAgentEventActorState,
IAgentEventActorSuspensionEvidence,
IAgentEventBindingRecord,
IAgentTriggerDeliveryDocument,
AppConfig,
IChatProjectDocument,
IActiveSubagentThreadLease,
IConversation,
IMessage,
ISharedLink,
ISubagentThreadReservation,
} from '~/types';
import type { SchemaWithMeiliMethods } from '~/models/plugins/mongoMeili';
import type { MessageMethods } from './message';
import {
MAX_AGENT_EVENT_ACTOR_DISCOVERED_TOOLS,
MAX_AGENT_EVENT_ACTOR_ENCODING_LENGTH,
MAX_AGENT_EVENT_ACTOR_SKILLS,
MAX_AGENT_EVENT_ACTOR_SUMMARY_LENGTH,
MAX_AGENT_EVENT_ACTOR_TOOL_NAME_LENGTH,
} from '~/types/convo';
import {
activeExpirationFilter,
buildRetentionVisibilityFilter,
createFallbackRetentionDate,
} from '~/utils/retention';
import {
refreshChatProjectStatsForUser,
updateChatProjectLastConversationForUser,
} from './chatProject';
import { createChatExpirationDate, createTempChatExpirationDate } from '~/utils/tempChatRetention';
import { isAgentFadingTier, isAgentFadingTierEntries } from '~/utils/fading';
import { isCompactionSemanticIndexProjection } from '~/types/compaction';
import { withoutMeiliIndexing } from '~/models/plugins/mongoMeili';
import { prepareSubagentContentDeletion } from './subagentContent';
import { tenantSafeBulkWrite } from '~/utils/tenantBulkWrite';
import { isValidObjectIdString } from '~/utils/objectId';
import { decrementTagCounts } from './conversationTag';
import logger from '~/config/winston';
const ACTOR_CHECKPOINT_FIELDS = [
'agentEventActor',
'agentEventActorCleanup',
'agentEventActorReconciliations',
'agentEventActorSuspension',
] as const;
/** Removes each field and every dotted path beneath it, which Mongo reads as a write to the field. */
function stripFields(record: Record<string, unknown>, fields: readonly string[]): void {
for (const key of Object.keys(record)) {
if (fields.some((field) => key === field || key.startsWith(`${field}.`))) {
delete record[key];
}
}
}
function stripActorCheckpointFields(record: Record<string, unknown>): void {
stripFields(record, ACTOR_CHECKPOINT_FIELDS);
}
/** Written only by the lane methods, so no save, unset or import may reach them. */
const LANE_PRIVATE_FIELDS = ['laneGit', 'laneGitSeq', 'codeAttachmentEpoch'] as const;
/** The lane state a reader may see; the sequence number that fences writes stays private. */
export type ConvoLaneGitView = Omit<NonNullable<IConversation['laneGit']>, 'seq'>;
/** What a lane recorder needs to place and fence its writes, read once when its tool is created. */
export type ConvoLaneContext = {
subagentThread?: IConversation['subagentThread'] | null;
/** Counts the owner's moves and detaches of the workspace the report is written to (the visible
* root for a subagent thread); 0 until the first. */
codeAttachmentEpoch: number;
};
const AGENT_EVENT_ACTOR_RECEIPT_RETENTION_MS = 90 * 24 * 60 * 60_000;
const MAX_AGENT_EVENT_ACTOR_SUSPENSION_BYTES = 64 * 1_024;
/** MeiliSearch's default `pagination.maxTotalHits` ceiling. */
const MEILI_SEARCH_LIMIT = 1000;
/** Ceiling for a single conversation page; the sidebar's largest request is 100. */
const MAX_CONVO_PAGE_SIZE = 100;
const DEFAULT_CONVO_PAGE_SIZE = 25;
const nextMonotonicStamp = (previous?: Date): Date => {
const previousMs = previous?.getTime() ?? 0;
return new Date(Math.max(Date.now(), Number.isFinite(previousMs) ? previousMs + 1 : 0));
};
const escapeMeiliFilterValue = (value: string): string =>
value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
function validateAgentEventActorSuspension(
conversationId: string,
suspension: IAgentEventActorSuspensionEvidence,
actionId: string,
jobCreatedAt: number,
previous?: AgentEventActorSettlementAuthority,
): void {
const invocation = suspension?.invocation;
const fork = invocation?.fork;
const checkpoint = suspension?.checkpoint;
if (
suspension?.version !== 1 ||
typeof suspension.suspensionId !== 'string' ||
suspension.suspensionId.length === 0 ||
!Number.isSafeInteger(suspension.attempt) ||
suspension.attempt < 0 ||
!Number.isSafeInteger(suspension.issuedAt) ||
!Number.isSafeInteger(suspension.expiresAt) ||
suspension.expiresAt <= suspension.issuedAt ||
invocation?.actorThreadId !== conversationId ||
fork?.threadId !== conversationId ||
checkpoint?.threadId !== conversationId ||
fork?.invocationId !== invocation?.invocationId ||
checkpoint?.invocationId !== invocation?.invocationId ||
checkpoint?.checkpointNs !== fork?.checkpointNs ||
typeof suspension.interrupt?.id !== 'string' ||
suspension.interrupt.id.length === 0 ||
typeof suspension.suspensionDigest !== 'string' ||
suspension.suspensionDigest.length === 0 ||
typeof actionId !== 'string' ||
actionId.length === 0 ||
!Number.isSafeInteger(jobCreatedAt) ||
jobCreatedAt < 0 ||
(previous == null ? suspension.attempt !== 0 : suspension.attempt !== previous.attempt + 1)
) {
throw new Error('Event actor suspension evidence is invalid');
}
let serialized: string;
try {
serialized = JSON.stringify(suspension);
} catch {
throw new Error('Event actor suspension evidence is not JSON-safe');
}
if (Buffer.byteLength(serialized, 'utf8') > MAX_AGENT_EVENT_ACTOR_SUSPENSION_BYTES) {
throw new RangeError('Event actor suspension exceeds maximum payload size');
}
}
type ConversationUpdateResult = {
value:
| (IConversation & {
_id: unknown;
$isDefault: (path: string) => boolean;
toObject: () => IConversation;
})
| null;
lastErrorObject?: {
updatedExisting?: boolean;
};
};
export type SubagentThreadReadRecord = Pick<
IConversation,
| 'conversationId'
| 'tenantId'
| 'title'
| 'agent_id'
| 'updatedAt'
| 'subagentThread'
| 'subagentThreadLease'
> & {
actorId?: string;
};
export type ParentSubagentThreadRecord = SubagentThreadReadRecord;
export type AgentEventActorCommitResult =
| {
status: 'committed';
state: IAgentEventActorState;
prunableCheckpoint?: IAgentEventActorCheckpoint;
}
| { status: 'stale'; state?: IAgentEventActorState };
export interface AgentEventActorSettlementAuthority {
suspensionId: string;
attempt: number;
resumeAttemptId: string;
}
export interface AgentEventActorReconciliationStorageMetrics {
pending: number;
oldestPendingAgeSeconds: number;
}
const ARCHIVE_CONVERSATION_BATCH_SIZE = 500;
const PROJECT_STATS_REFRESH_CONCURRENCY = 10;
const PROJECT_STATS_REFRESH_MAX_PASSES = 2;
const PROJECT_DISCOVERY_MAX_ATTEMPTS = 3;
const subagentThreadReadRecord = (conversation: IConversation): SubagentThreadReadRecord => ({
conversationId: conversation.conversationId,
...(conversation.tenantId == null ? {} : { tenantId: conversation.tenantId }),
...(conversation.title == null ? {} : { title: conversation.title }),
...(conversation.agent_id == null ? {} : { agent_id: conversation.agent_id }),
...(conversation.updatedAt == null ? {} : { updatedAt: conversation.updatedAt }),
...(conversation.subagentThread == null ? {} : { subagentThread: conversation.subagentThread }),
...(conversation.subagentThreadLease == null
? {}
: { subagentThreadLease: conversation.subagentThreadLease }),
...(conversation.agentEventBinding?.actorId == null
? {}
: { actorId: conversation.agentEventBinding.actorId }),
});
async function discoverProjectIds(
Conversation: Model<IConversation>,
filter: FilterQuery<IConversation>,
): Promise<string[]> {
let lastError: unknown;
for (let attempt = 0; attempt < PROJECT_DISCOVERY_MAX_ATTEMPTS; attempt++) {
try {
const currentProjectIds = await Conversation.distinct('chatProjectId', filter);
return currentProjectIds.filter((projectId): projectId is string => Boolean(projectId));
} catch (error) {
lastError = error;
logger.error('[archiveAllConvos] Conversations archived but project discovery failed', error);
}
}
throw lastError;
}
/**
* A project dropped here stays wrong forever: its chats are archived, so no retry of
* archive-all can find them again to recompute against. The likeliest rejection is also
* the most recoverable one, `refreshChatProjectStatsForUser` giving up after the project
* changed under every compare-and-set attempt, so failures are collected and replayed
* once the rest of the run has stopped competing with them.
*/
async function refreshChatProjectStatsInBatches(
mongoose: typeof import('mongoose'),
user: string,
projectIds: Iterable<string>,
): Promise<void> {
let pending = [...projectIds];
for (let pass = 0; pass < PROJECT_STATS_REFRESH_MAX_PASSES && pending.length > 0; pass++) {
const failed: string[] = [];
for (let index = 0; index < pending.length; index += PROJECT_STATS_REFRESH_CONCURRENCY) {
const batch = pending.slice(index, index + PROJECT_STATS_REFRESH_CONCURRENCY);
const results = await Promise.allSettled(
batch.map((projectId) => refreshChatProjectStatsForUser(mongoose, user, projectId)),
);
for (let resultIndex = 0; resultIndex < results.length; resultIndex++) {
const result = results[resultIndex];
if (result.status === 'rejected') {
failed.push(batch[resultIndex]);
logger.error(
`[refreshChatProjectStatsInBatches] Failed to refresh project ${batch[resultIndex]}`,
result.reason,
);
}
}
}
pending = failed;
}
if (pending.length > 0) {
logger.error(
`[refreshChatProjectStatsInBatches] Left ${pending.length} project(s) unreconciled: ${pending.join(', ')}`,
);
}
}
export type ConversationTitleState = Pick<
IConversation,
'title' | 'titleSetByUser' | 'titleRevision'
>;
export interface ConversationMethods {
getConvoFiles(conversationId: string): Promise<string[]>;
searchConversation(
conversationId: string,
fieldsToSelect?: string | null,
): Promise<IConversation | null>;
saveConvo(
ctx: {
userId: string;
isTemporary?: boolean;
expiredAt?: Date;
interfaceConfig?: AppConfig['interfaceConfig'];
},
data: { conversationId: string; newConversationId?: string; [key: string]: unknown },
metadata?: {
context?: string;
unsetFields?: Record<string, number>;
noUpsert?: boolean;
createdAtOnInsert?: Date;
preserveUpdatedAt?: boolean;
titleSource?: 'manual' | 'generated';
/** Same-tenant persisted agent already resolved by the request layer. */
initialAgentId?: string | null;
/** `_id`s of messages this save just wrote. When present, they are appended with
* `$addToSet` and the O(n) read-and-rewrite of the `messages` array is skipped;
* every save without this option still rebuilds the array from the database. */
/** Casts plain string ids, so callers outside this package need not name the id type. */
appendMessageIds?: Array<Types.ObjectId | string>;
/** Advance the reply version and clear the catch-up after persisting an assistant reply. */
stampReply?: boolean;
/** Durable messageId paired atomically with a reply stamp. */
replyMessageId?: string;
},
): Promise<IConversation | { message: string } | null>;
/**
* Stamps forced-temporary retention onto an existing conversation and, optionally, some of its
* messages, for writes that bypass the retention-aware save path. Reuses the stored deadline
* rather than opening a new window, never upserts, never rewrites `messages`, and releases the
* conversation's bookmark counts exactly once when it stops being visible.
*/
stampForcedRetention(
ctx: { userId: string; interfaceConfig?: AppConfig['interfaceConfig'] },
target: { conversationId: string; messageIds?: string[] },
): Promise<void>;
setConvoPinned(
user: string,
conversationId: string,
pinned: boolean,
): Promise<IConversation | null>;
appendConvoMessageReference(
user: string,
conversationId: string,
messageId: string,
): Promise<IConversation | null>;
getConvoCodeEnvironmentDecision(
user: string,
conversationId: string,
): Promise<Pick<
IConversation,
'conversationId' | 'codeEnvironmentMode' | 'codeWorkspaces' | 'codeEnvironmentRevision'
> | null>;
reserveConvoLaneGitSeq(user: string, conversationId: string): Promise<number | null>;
getConvoLaneContext(user: string, conversationId: string): Promise<ConvoLaneContext | null>;
setConvoLaneGit(input: {
user: string;
conversationId: string;
laneGit: Pick<NonNullable<IConversation['laneGit']>, 'branch' | 'head'>;
repo?: string;
/** A pull request the command's output linked to; replaces the one recorded for the lane. */
pullRequest?: number;
/** Reserved with `reserveConvoLaneGitSeq` when the command settled. */
seq: number;
/** The workspace the command ran in; the write applies only while the chat is still on it. */
workspace?: {
environmentId: string;
workspaceId: string;
required?: boolean;
/** The attachment epoch read when the tool was created; see `getConvoLaneContext`. */
epoch?: number;
};
}): Promise<boolean>;
getConvoLaneGit(
user: string,
conversationId: string,
): Promise<Omit<NonNullable<IConversation['laneGit']>, 'seq'> | null>;
getConvosLaneGit(
user: string,
conversationIds: string[],
): Promise<Array<{ conversationId: string; laneGit: ConvoLaneGitView }>>;
addConvoToolApprovalAllows(input: {
user: string;
conversationId: string;
toolNames: string[];
max: number;
}): Promise<boolean>;
readAdmittedConvoCodeEnvironmentDecision(
user: string,
conversationId: string,
): Promise<Pick<
IConversation,
'conversationId' | 'codeEnvironmentMode' | 'codeWorkspaces' | 'codeAttachmentEpoch'
> | null>;
replaceConvoCodeEnvironmentDecision(
params: {
user: string;
conversationId: string;
expected: Pick<
IConversation,
'codeEnvironmentMode' | 'codeWorkspaces' | 'codeEnvironmentRevision'
>;
} & (
| {
codeEnvironmentMode: 'attached';
codeWorkspaces: NonNullable<IConversation['codeWorkspaces']>;
}
| { codeEnvironmentMode: 'without_attached'; codeWorkspaces?: undefined }
),
): Promise<IConversation | null>;
bulkSaveConvos(conversations: Array<Record<string, unknown>>): Promise<unknown>;
getConvosByCursor(
user: string,
options?: {
cursor?: string | null;
limit?: number;
isArchived?: boolean;
pinned?: boolean;
tags?: string[];
search?: string;
sortBy?: string;
sortDirection?: string;
projectId?: string;
updatedAfter?: Date;
createdAfter?: Date;
endpoints?: string[];
hasFiles?: boolean;
sharedOnly?: boolean;
},
): Promise<{ conversations: IConversation[]; nextCursor: string | null }>;
getConvosQueried(
user: string,
convoIds: Array<{ conversationId: string }> | null,
cursor?: string | null,
limit?: number,
): Promise<{
conversations: IConversation[];
nextCursor: string | null;
convoMap: Record<string, unknown>;
}>;
getConvo(user: string, conversationId: string): Promise<IConversation | null>;
getConvoTitleState(user: string, conversationId: string): Promise<ConversationTitleState | null>;
getSubagentThreadForParent(input: {
user: string;
parentConversationId: string;
conversationId: string;
tenantId?: string;
}): Promise<SubagentThreadReadRecord | null>;
listSubagentThreadsForParent(input: {
user: string;
parentConversationId: string;
tenantId?: string;
limit: number;
}): Promise<ParentSubagentThreadRecord[]>;
getAgentEventBinding(input: {
user: string;
bindingId: string;
sourceKeyId: string;
tenantId?: string;
}): Promise<IAgentEventBindingRecord | null>;
getAgentEventActorSnapshot(input: {
user: string;
conversationId: string;
tenantId?: string;
}): Promise<IAgentEventActorSnapshot | undefined>;
commitAgentEventActorState(input: {
user: string;
conversationId: string;
tenantId?: string;
invocationId: string;
action: IAgentEventActorReconciliation['action'];
expected?: IAgentEventActorState;
expectedEpoch: number;
checkpoint: IAgentEventActorCheckpoint;
contextFingerprint?: IAgentEventActorState['contextFingerprint'];
skillManifest?: IAgentEventActorState['skillManifest'];
discoveredToolNames?: IAgentEventActorState['discoveredToolNames'];
summary?: IAgentEventActorState['summary'];
contextMeta?: IAgentEventActorState['contextMeta'];
compactionSemanticIndex?: IAgentEventActorState['compactionSemanticIndex'];
settlementAuthority?: AgentEventActorSettlementAuthority;
}): Promise<AgentEventActorCommitResult>;
storeAgentEventActorSuspension(input: {
user: string;
conversationId: string;
tenantId?: string;
suspension: IAgentEventActorSuspensionEvidence;
kind?: 'human_decision' | 'internal_completion';
appliedAction?: { toolName: string; toolCallId?: string };
handlingGenerationCreatedAt?: number;
actionId: string;
jobCreatedAt: number;
/** The segment applied its expected action before publishing this successor pause. */
invalidateHead?: boolean;
previous?: AgentEventActorSettlementAuthority;
}): Promise<{ status: 'stored' | 'stale' }>;
claimAgentEventActorSuspension(input: {
user: string;
conversationId: string;
tenantId?: string;
suspensionId: string;
attempt: number;
actionId: string;
jobCreatedAt: number;
resumeAttemptId: string;
}): Promise<{ status: 'claimed' | 'stale' }>;
settleAgentEventActorSuspension(input: {
user: string;
conversationId: string;
tenantId?: string;
suspensionId: string;
attempt: number;
resumeAttemptId: string;
invocationId: string;
checkpoint: IAgentEventActorReconciliation['checkpoint'];
}): Promise<{ status: 'settled' | 'stale' }>;
cancelAgentEventActorSuspension(input: {
user: string;
conversationId: string;
tenantId?: string;
suspensionId: string;
attempt: number;
invocationId: string;
checkpoint: IAgentEventActorReconciliation['checkpoint'];
/** Exact orphaned resume claim proven not to have entered provider execution. */
claimedResumeAttemptId?: string;
}): Promise<{ status: 'cancelled' | 'stale' }>;
beginAgentEventActorLegacyTurn(input: {
user: string;
conversationId: string;
tenantId?: string;
token: string;
}): Promise<boolean>;
completeAgentEventActorLegacyTurn(input: {
user: string;
conversationId: string;
tenantId?: string;
token: string;
}): Promise<boolean>;
recordAgentEventActorReconciliation(input: {
user: string;
conversationId: string;
tenantId?: string;
reconciliation: IAgentEventActorReconciliation;
}): Promise<boolean>;
resolveAgentEventActorReconciliation(input: {
user: string;
conversationId: string;
tenantId?: string;
invocationId: string;
checkpoint: IAgentEventActorReconciliation['checkpoint'];
expectedActionAdmitted?: boolean;
resolution:
| 'checkpoint_verified'
| 'action_compensated'
| 'history_repaired'
| 'invocation_abandoned';
}): Promise<boolean>;
clearAgentEventActorReconciliation(input: {
user: string;
conversationId: string;
tenantId?: string;
invocationId: string;
checkpoint: IAgentEventActorReconciliation['checkpoint'];
resolution: 'checkpoint_verified' | 'action_compensated' | 'history_repaired';
}): Promise<boolean>;
getAgentEventActorReconciliationStorageMetrics(
now: Date,
): Promise<AgentEventActorReconciliationStorageMetrics>;
expireLegacyAgentEventActorReceipts(
now: Date,
limit?: number,
activity?: { found: boolean },
): Promise<number>;
reserveSubagentThread(input: {
user: string;
conversationId: string;
conversation: Partial<IConversation>;
tenantId?: string;
}): Promise<ISubagentThreadReservation>;
acquireSubagentThreadLease(input: {
user: string;
conversationId: string;
token: string;
taskId: string;
now: Date;
expiresAt: Date;
tenantId?: string;
}): Promise<boolean>;
renewSubagentThreadLease(input: {
user: string;
conversationId: string;
token: string;
now: Date;
expiresAt: Date;
tenantId?: string;
}): Promise<boolean>;
releaseSubagentThreadLease(input: {
user: string;
conversationId: string;
token: string;
tenantId?: string;
}): Promise<boolean>;
countActiveSubagentThreadLeases(input: {
user: string;
now: Date;
tenantId?: string;
}): Promise<number>;
listActiveSubagentThreadLeases(input: {
user: string;
now: Date;
tenantId?: string;
}): Promise<IActiveSubagentThreadLease[]>;
getConvoOwnership(
user: string,
conversationId: string,
tenantId?: string | null,
): Promise<Pick<IConversation, 'user' | 'tenantId' | 'subagentThread'> | null>;
getConvoRetention(
user: string,
conversationId: string,
): Promise<Pick<IConversation, 'expiredAt' | 'isTemporary'> | null>;
getConvoTitle(user: string, conversationId: string): Promise<string | null>;
markConvoSeen(
user: string,
conversationId: string,
observedResponseAt?: Date,
): Promise<{ modified: boolean }>;
markConvoUnread(
user: string,
conversationId: string,
): Promise<{
modified: boolean;
lastResponseAt?: Date;
lastResponseMessageId?: string;
lastResponseIsManual?: boolean;
isMarkedUnread?: boolean;
}>;
stampConvoLastResponse(
user: string,
conversationId: string,
responseMessageId: string,
): Promise<{ lastResponseAt: Date; lastResponseMessageId: string; updatedAt?: Date } | null>;
deleteConvos(
user: string,
filter: FilterQuery<IConversation>,
options?: {
beforeDelete?: (conversationIds: string[]) => Promise<void>;
allowEmpty?: boolean;
},
): Promise<DeleteResult & { messages: DeleteResult; conversationIds: string[] }>;
archiveAllConvos(user: string): Promise<{ archivedCount: number }>;
}
export interface ConversationMethodDeps
extends Pick<MessageMethods, 'getMessages' | 'deleteMessages'> {
searchMessages?: MessageMethods['searchMessages'];
deleteAgentQueuedTurns?: (
user: string,
conversations: Array<{ conversationId: string; tenantId?: string; allTenants?: true }>,
) => Promise<void>;
eraseAgentTriggerDeliveryConversationResults?: (
user: string,
conversationIds: string[],
) => Promise<void>;
prepareAgentTriggerConversationResultErasure?: (
user: string,
conversationIds: string[],
) => Promise<void>;
}
export function createConversationMethods(
mongoose: typeof import('mongoose'),
deps?: ConversationMethodDeps,
): ConversationMethods {
let legacyReceiptExpiryCursor: Types.ObjectId | undefined;
/**
* Stamps a real assistant reply with a strictly increasing server value.
*
* The read and write are a classic compare-and-set pair so this remains compatible with
* DocumentDB: concurrent writers that read the same value retry against the winner and use
* `max(now, previous + 1ms, updatedAt + 1ms)`. Advancing both versions makes the reply itself
* distinguishable from a metadata-only promotion. Only a successful write supplies a stamp.
*/
async function stampReplyWithCas(
Conversation: Model<IConversation>,
filter: FilterQuery<IConversation>,
responseMessageId: string,
projection?: Record<string, 0 | 1>,
): Promise<{ stamp: Date; conversation: Partial<IConversation> } | null> {
const replyFilter = { ...filter, isTemporary: { $ne: true } };
for (;;) {
const current = await Conversation.findOne(replyFilter)
.select({ lastResponseAt: 1, updatedAt: 1 })
.lean<Pick<IConversation, 'lastResponseAt' | 'updatedAt'> | null>();
if (!current) {
return null;
}
const previous = current.lastResponseAt;
const latestActivity =
current.updatedAt && (!previous || current.updatedAt > previous)
? current.updatedAt
: previous;
const stamp = nextMonotonicStamp(latestActivity);
const casFilter: FilterQuery<IConversation> =
previous == null
? {
...replyFilter,
updatedAt: current.updatedAt ?? null,
$or: [{ lastResponseAt: null }, { lastResponseAt: { $exists: false } }],
}
: { ...replyFilter, lastResponseAt: previous, updatedAt: current.updatedAt ?? null };
const stamped = await Conversation.findOneAndUpdate(
casFilter,
{
$set: {
lastResponseAt: stamp,
lastResponseMessageId: responseMessageId,
isMarkedUnread: false,
lastSeenAt: new Date(UNSEEN_REPLY_WATERMARK),
},
$unset: { lastResponseIsManual: '' },
$max: { updatedAt: stamp },
},
{ new: true, projection, timestamps: false },
).lean<Partial<IConversation> | null>();
if (stamped) {
return { stamp, conversation: stamped };
}
}
}
function getMessageMethods() {
if (!deps) {
throw new Error('Message methods not injected into conversation methods');
}
return deps;
}
function getVisibleConversationRetentionFilter(): FilterQuery<IConversation> {
return buildRetentionVisibilityFilter<IConversation>();
}
/** Child threads are durable execution records, not user-navigable conversations. */
function getHumanConversationFilter(): FilterQuery<IConversation> {
return { subagentThread: { $exists: false } } as FilterQuery<IConversation>;
}
/**
* Searches for a conversation by conversationId and returns a lean document with only conversationId and user.
*/
/** `fieldsToSelect: null` returns the full document so one read can serve the whole request. */
async function searchConversation(
conversationId: string,
fieldsToSelect: string | null = 'conversationId user',
) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return await Conversation.findOne({ conversationId }, fieldsToSelect).lean<IConversation>();
} catch (error) {
logger.error('[searchConversation] Error searching conversation', error);
throw new Error('Error searching conversation');
}
}
/**
* Retrieves a single conversation for a given user and conversation ID.
*/
async function getConvo(user: string, conversationId: string) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return await Conversation.findOne({ user, conversationId }).lean<IConversation>();
} catch (error) {
logger.error('[getConvo] Error getting single conversation', error);
throw new Error('Error getting single conversation');
}
}
async function getConvoTitleState(
user: string,
conversationId: string,
): Promise<ConversationTitleState | null> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return Conversation.findOne({ user, conversationId })
.select('title titleSetByUser titleRevision -_id')
.lean<ConversationTitleState>();
}
/** Resolves a child only through its owning parent and includes its private live lease. */
async function getSubagentThreadForParent(input: {
user: string;
parentConversationId: string;
conversationId: string;
tenantId?: string;
}): Promise<SubagentThreadReadRecord | null> {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const conversation = await Conversation.findOne({
user: input.user,
conversationId: input.conversationId,
'subagentThread.parentConversationId': input.parentConversationId,
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
})
.select(
'conversationId tenantId title agent_id updatedAt subagentThread +subagentThreadLease +agentEventBinding',
)
.lean<IConversation>();
if (conversation == null) return null;
return subagentThreadReadRecord(conversation);
} catch (error) {
logger.error('[getSubagentThreadForParent] Error getting child conversation', error);
throw new Error('Error getting child conversation');
}
}
/**
* Lists bounded child metadata through immutable parent lineage. Private
* event-delivery records are collapsed to actor identity inside this Module.
*/
async function listSubagentThreadsForParent(input: {
user: string;
parentConversationId: string;
tenantId?: string;
limit: number;
}): Promise<ParentSubagentThreadRecord[]> {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const conversations = await Conversation.find({
user: input.user,
'subagentThread.parentConversationId': input.parentConversationId,
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
})
.select(
'conversationId tenantId title agent_id updatedAt subagentThread +subagentThreadLease +agentEventBinding',
)
.sort({ updatedAt: -1, conversationId: 1, _id: 1 })
.limit(input.limit)
.lean<IConversation[]>();
return conversations.map(subagentThreadReadRecord);
} catch (error) {
logger.error('[listSubagentThreadsForParent] Error listing child conversations', error);
throw new Error('Error listing child conversations');
}
}
/** Resolves an event target only when the API key, owner, and tenant all match. */
async function getAgentEventBinding(input: {
user: string;
bindingId: string;
sourceKeyId: string;
tenantId?: string;
}): Promise<IAgentEventBindingRecord | null> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const conversation = await Conversation.findOne({
user: input.user,
'agentEventBinding.bindingId': input.bindingId,
'agentEventBinding.sourceKeyId': input.sourceKeyId,
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
})
.select(
'conversationId agent_id tenantId isTemporary expiredAt subagentThread +agentEventBinding',
)
.lean<IConversation>();
if (
conversation?.agentEventBinding == null ||
conversation.subagentThread == null ||
typeof conversation.agent_id !== 'string'
) {
return null;
}
return {
conversationId: conversation.conversationId,
agentId: conversation.agent_id,
...(conversation.tenantId == null ? {} : { tenantId: conversation.tenantId }),
...(conversation.isTemporary == null ? {} : { isTemporary: conversation.isTemporary }),
...(conversation.expiredAt == null ? {} : { expiredAt: conversation.expiredAt }),
binding: conversation.agentEventBinding,
lineage: conversation.subagentThread,
};
}
function readableActorSuspension(
suspension: IConversation['agentEventActorSuspension'],
): IAgentEventActorSnapshot['suspension'] {
if (suspension == null) return null;
if (suspension.status === 'pending_owned') return { ...suspension, status: 'pending' };
if (suspension.status === 'claimed_owned') return { ...suspension, status: 'claimed' };
return suspension;
}
/** Reads the private actor head and every fail-closed reconciliation marker. */
async function getAgentEventActorSnapshot(input: {
user: string;
conversationId: string;
tenantId?: string;
}): Promise<IAgentEventActorSnapshot | undefined> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const conversation = await Conversation.findOne({
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
})
.select(
'+agentEventActor +agentEventActorReconciliations +agentEventActorEpoch +agentEventActorLegacyTurn +agentEventActorSuspension',
)
.lean<IConversation>();
return conversation == null
? undefined
: {
state: conversation.agentEventActor ?? null,
reconciliations: conversation.agentEventActorReconciliations ?? [],
legacyTurn: conversation.agentEventActorLegacyTurn ?? null,
suspension: readableActorSuspension(conversation.agentEventActorSuspension),
epoch: conversation.agentEventActorEpoch ?? 0,
};
}
/** Publishes one SDK-issued suspension, or atomically replaces its exact claimed predecessor. */
async function storeAgentEventActorSuspension(input: {
user: string;
conversationId: string;
tenantId?: string;
suspension: IAgentEventActorSuspensionEvidence;
kind?: 'human_decision' | 'internal_completion';
appliedAction?: { toolName: string; toolCallId?: string };
handlingGenerationCreatedAt?: number;
actionId: string;
jobCreatedAt: number;
invalidateHead?: boolean;
previous?: AgentEventActorSettlementAuthority;
}): Promise<{ status: 'stored' | 'stale' }> {
validateAgentEventActorSuspension(
input.conversationId,
input.suspension,
input.actionId,
input.jobCreatedAt,
input.previous,
);
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const predecessor: FilterQuery<IConversation> =
input.previous == null
? {
$or: [
{ agentEventActorSuspension: { $exists: false } },
{ 'agentEventActorSuspension.status': 'closed' },
],
}
: {
'agentEventActorSuspension.status': { $in: ['claimed', 'claimed_owned'] },
'agentEventActorSuspension.suspension.suspensionId': input.previous.suspensionId,
'agentEventActorSuspension.suspension.attempt': input.previous.attempt,
'agentEventActorSuspension.resumeAttemptId': input.previous.resumeAttemptId,
};
const ownership = {
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
agentEventActorReconciliations: {
$elemMatch: {
invocationId: input.suspension.invocation.invocationId,
status: 'invocation_pending',
},
},
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
...predecessor,
};
const suspension = {
suspension: input.suspension,
kind: input.kind ?? 'human_decision',
...(input.appliedAction == null ? {} : { appliedAction: input.appliedAction }),
handlingGenerationCreatedAt: input.handlingGenerationCreatedAt ?? input.jobCreatedAt,
actionId: input.actionId,
jobCreatedAt: input.jobCreatedAt,
status: 'pending_owned' as const,
observedAt: new Date(),
};
const storeUpdate = {
$set: {
agentEventActorSuspension: suspension,
...(input.invalidateHead === true ? { 'agentEventActor.requiresColdStart': true } : {}),
},
};
let stored = await Conversation.findOneAndUpdate(
{
...ownership,
...(input.invalidateHead === true ? { agentEventActor: { $exists: true } } : {}),
},
storeUpdate,
{ new: false, timestamps: false },
)
.select('_id')
.lean<IConversation>();
/** A headless actor is already guaranteed to cold-start; publish the
* successor without manufacturing a partial canonical state. */
if (stored == null && input.invalidateHead === true) {
stored = await Conversation.findOneAndUpdate(
{ ...ownership, agentEventActor: { $exists: false } },
{
$set: {
agentEventActorSuspension: suspension,
},
},
{ new: false, timestamps: false },
)
.select('_id')
.lean<IConversation>();
}
return { status: stored == null ? 'stale' : 'stored' };
}
/** One resume attempt wins the canonical Conversation-side suspension fence. */
async function claimAgentEventActorSuspension(input: {
user: string;
conversationId: string;
tenantId?: string;
suspensionId: string;
attempt: number;
actionId: string;
jobCreatedAt: number;
resumeAttemptId: string;
}): Promise<{ status: 'claimed' | 'stale' }> {
if (
input.suspensionId.length === 0 ||
!Number.isSafeInteger(input.attempt) ||
input.attempt < 0 ||
input.actionId.length === 0 ||
!Number.isSafeInteger(input.jobCreatedAt) ||
input.jobCreatedAt < 0 ||
input.resumeAttemptId.length === 0
) {
throw new Error('Event actor suspension claim is invalid');
}
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const claimed = await Conversation.findOneAndUpdate(
{
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
'agentEventActorSuspension.status': { $in: ['pending', 'pending_owned'] },
'agentEventActorSuspension.suspension.suspensionId': input.suspensionId,
'agentEventActorSuspension.suspension.attempt': input.attempt,
'agentEventActorSuspension.actionId': input.actionId,
'agentEventActorSuspension.jobCreatedAt': input.jobCreatedAt,
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
},
{
$set: {
'agentEventActorSuspension.status': 'claimed_owned',
'agentEventActorSuspension.resumeAttemptId': input.resumeAttemptId,
'agentEventActorSuspension.observedAt': new Date(),
},
$unset: {
'agentEventActorSuspension.outcome': 1,
'agentEventActorSuspension.closedAt': 1,
},
},
{ new: false, timestamps: false },
)
.select('_id')
.lean<IConversation>();
return { status: claimed == null ? 'stale' : 'claimed' };
}
/** Closes a claimed no-action suspension while retaining one bounded retry receipt. */
async function settleAgentEventActorSuspension(input: {
user: string;
conversationId: string;
tenantId?: string;
suspensionId: string;
attempt: number;
resumeAttemptId: string;
invocationId: string;
checkpoint: IAgentEventActorReconciliation['checkpoint'];
}): Promise<{ status: 'settled' | 'stale' }> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const settled = await Conversation.findOneAndUpdate(
{
user: input.user,
conversationId: input.conversationId,
'agentEventActorSuspension.status': { $in: ['claimed', 'claimed_owned'] },
'agentEventActorSuspension.suspension.suspensionId': input.suspensionId,
'agentEventActorSuspension.suspension.attempt': input.attempt,
'agentEventActorSuspension.resumeAttemptId': input.resumeAttemptId,
agentEventActorReconciliations: {
$elemMatch: {
invocationId: input.invocationId,
status: 'invocation_pending',
'checkpoint.threadId': input.checkpoint.threadId,
'checkpoint.checkpointNs': input.checkpoint.checkpointNs,
...(input.checkpoint.checkpointId == null
? { 'checkpoint.checkpointId': { $exists: false } }
: { 'checkpoint.checkpointId': input.checkpoint.checkpointId }),
},
},
...subagentLeaseTenantFilter(input.tenantId),
},
{
$set: {
'agentEventActorSuspension.status': 'closed',
'agentEventActorSuspension.outcome': 'settled',
'agentEventActorSuspension.closedAt': new Date(),
'agentEventActorSuspension.observedAt': new Date(),
},
$pull: {
agentEventActorReconciliations: {
invocationId: input.invocationId,
status: 'invocation_pending',
'checkpoint.threadId': input.checkpoint.threadId,
'checkpoint.checkpointNs': input.checkpoint.checkpointNs,
...(input.checkpoint.checkpointId == null
? { 'checkpoint.checkpointId': { $exists: false } }
: { 'checkpoint.checkpointId': input.checkpoint.checkpointId }),
},
},
},
{ new: false, timestamps: false },
)
.select('_id')
.lean<IConversation>();
if (settled != null) {
return { status: 'settled' };
}
const snapshot = await getAgentEventActorSnapshot(input);
return snapshot?.suspension?.status === 'closed' &&
snapshot.suspension.outcome === 'settled' &&
snapshot.suspension.suspension.suspensionId === input.suspensionId &&
snapshot.suspension.suspension.attempt === input.attempt &&
snapshot.suspension.resumeAttemptId === input.resumeAttemptId
? { status: 'settled' }
: { status: 'stale' };
}
/** Cancellation races resume through the same current-suspension predicate. */
async function cancelAgentEventActorSuspension(input: {
user: string;
conversationId: string;
tenantId?: string;
suspensionId: string;
attempt: number;
invocationId: string;
checkpoint: IAgentEventActorReconciliation['checkpoint'];
claimedResumeAttemptId?: string;
}): Promise<{ status: 'cancelled' | 'stale' }> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const suspensionOwner =
input.claimedResumeAttemptId == null
? { 'agentEventActorSuspension.status': { $in: ['pending', 'pending_owned'] } }
: {
'agentEventActorSuspension.status': { $in: ['claimed', 'claimed_owned'] },
'agentEventActorSuspension.resumeAttemptId': input.claimedResumeAttemptId,
};
const cancelled = await Conversation.findOneAndUpdate(
{
user: input.user,
conversationId: input.conversationId,
...suspensionOwner,
'agentEventActorSuspension.suspension.suspensionId': input.suspensionId,
'agentEventActorSuspension.suspension.attempt': input.attempt,
agentEventActorReconciliations: {
$elemMatch: {
invocationId: input.invocationId,
status: 'invocation_pending',
'checkpoint.threadId': input.checkpoint.threadId,
'checkpoint.checkpointNs': input.checkpoint.checkpointNs,
...(input.checkpoint.checkpointId == null
? { 'checkpoint.checkpointId': { $exists: false } }
: { 'checkpoint.checkpointId': input.checkpoint.checkpointId }),
},
},
...subagentLeaseTenantFilter(input.tenantId),
},
{
$set: {
'agentEventActorSuspension.status': 'closed',
'agentEventActorSuspension.outcome': 'cancelled',
'agentEventActorSuspension.closedAt': new Date(),
'agentEventActorSuspension.observedAt': new Date(),
},
$pull: {
agentEventActorReconciliations: {
invocationId: input.invocationId,
status: 'invocation_pending',
'checkpoint.threadId': input.checkpoint.threadId,
'checkpoint.checkpointNs': input.checkpoint.checkpointNs,
...(input.checkpoint.checkpointId == null
? { 'checkpoint.checkpointId': { $exists: false } }
: { 'checkpoint.checkpointId': input.checkpoint.checkpointId }),
},
},
},
{ new: false, timestamps: false },
)
.select('_id')
.lean<IConversation>();
if (cancelled != null) {
return { status: 'cancelled' };
}
const snapshot = await getAgentEventActorSnapshot(input);
return snapshot?.suspension?.status === 'closed' &&
snapshot.suspension.outcome === 'cancelled' &&
snapshot.suspension.suspension.suspensionId === input.suspensionId &&
snapshot.suspension.suspension.attempt === input.attempt
? { status: 'cancelled' }
: { status: 'stale' };
}
/** Advances one actor head only when its complete prior identity still matches. */
async function commitAgentEventActorState(input: {
user: string;
conversationId: string;
tenantId?: string;
invocationId: string;
action: IAgentEventActorReconciliation['action'];
expected?: IAgentEventActorState;
expectedEpoch: number;
checkpoint: IAgentEventActorCheckpoint;
contextFingerprint?: IAgentEventActorState['contextFingerprint'];
skillManifest?: IAgentEventActorState['skillManifest'];
discoveredToolNames?: IAgentEventActorState['discoveredToolNames'];
summary?: IAgentEventActorState['summary'];
contextMeta?: IAgentEventActorState['contextMeta'];
compactionSemanticIndex?: IAgentEventActorState['compactionSemanticIndex'];
settlementAuthority?: AgentEventActorSettlementAuthority;
}): Promise<AgentEventActorCommitResult> {
if (input.checkpoint.threadId !== input.conversationId) {
throw new Error('Event actor checkpoint changed its logical thread');
}
if ((input.skillManifest?.length ?? 0) > MAX_AGENT_EVENT_ACTOR_SKILLS) {
throw new RangeError(`Event actor Skill manifest exceeds ${MAX_AGENT_EVENT_ACTOR_SKILLS}`);
}
if (
(input.discoveredToolNames?.length ?? 0) > MAX_AGENT_EVENT_ACTOR_DISCOVERED_TOOLS ||
input.discoveredToolNames?.some(
(name) => name.length === 0 || name.length > MAX_AGENT_EVENT_ACTOR_TOOL_NAME_LENGTH,
)
) {
throw new RangeError('Event actor discovered-tool state is invalid');
}
if (
input.summary != null &&
(input.summary.text.length === 0 ||
input.summary.text.length > MAX_AGENT_EVENT_ACTOR_SUMMARY_LENGTH ||
!Number.isFinite(input.summary.tokenCount) ||
input.summary.tokenCount < 0)
) {
throw new RangeError('Event actor summary state is invalid');
}
if (
input.contextMeta != null &&
(!Number.isFinite(input.contextMeta.calibrationRatio) ||
input.contextMeta.calibrationRatio < 0.5 ||
input.contextMeta.calibrationRatio > 5 ||
(input.contextMeta.encoding != null &&
(input.contextMeta.encoding.length === 0 ||
input.contextMeta.encoding.length > MAX_AGENT_EVENT_ACTOR_ENCODING_LENGTH)))
) {
throw new RangeError('Event actor context calibration is invalid');
}
if (
input.contextMeta?.fadingTiers != null &&
!isAgentFadingTierEntries(input.contextMeta.fadingTiers)
) {
throw new RangeError('Event actor context fading tiers are invalid');
}
if (input.contextMeta?.fading != null && !isAgentFadingTier(input.contextMeta.fading)) {
throw new RangeError('Event actor context fading tier is invalid');
}
if (
input.compactionSemanticIndex != null &&
!isCompactionSemanticIndexProjection(input.compactionSemanticIndex)
) {
throw new RangeError('Event actor compaction semantic index is invalid');
}
const Conversation = mongoose.models.Conversation as Model<IConversation>;
/** A legacy turn against a headless or already cold-marked actor leaves
* the head fields unchanged, so the CAS must also require the invalidation
* epoch observed at preparation. `null` matches a document that has never
* been invalidated. */
const expectedFilter: FilterQuery<IConversation> = {
agentEventActorEpoch: input.expectedEpoch === 0 ? null : input.expectedEpoch,
/** A legacy turn in flight has not yet persisted its messages, so no
* fork rebuild can be complete — refuse the commit outright rather than
* relying on the epoch, which only moves once that turn seals. */
agentEventActorLegacyTurn: { $exists: false },
...(input.expected == null
? { agentEventActor: { $exists: false } }
: {
'agentEventActor.generation': input.expected.generation,
'agentEventActor.checkpoint.threadId': input.expected.checkpoint.threadId,
'agentEventActor.checkpoint.checkpointId': input.expected.checkpoint.checkpointId,
'agentEventActor.checkpoint.checkpointNs': input.expected.checkpoint.checkpointNs,
'agentEventActor.previousCheckpoint': input.expected.previousCheckpoint ?? {
$exists: false,
},
...(input.expected.contextFingerprint == null
? { 'agentEventActor.contextFingerprint': { $exists: false } }
: {
'agentEventActor.contextFingerprint.algorithm':
input.expected.contextFingerprint.algorithm,
'agentEventActor.contextFingerprint.version':
input.expected.contextFingerprint.version,
'agentEventActor.contextFingerprint.digest':
input.expected.contextFingerprint.digest,
}),
...(input.expected.skillManifest == null
? { 'agentEventActor.skillManifest': { $exists: false } }
: { 'agentEventActor.skillManifest': input.expected.skillManifest }),
...(input.expected.discoveredToolNames == null
? { 'agentEventActor.discoveredToolNames': { $exists: false } }
: { 'agentEventActor.discoveredToolNames': input.expected.discoveredToolNames }),
...(input.expected.summary == null
? { 'agentEventActor.summary': { $exists: false } }
: { 'agentEventActor.summary': input.expected.summary }),
...(input.expected.contextMeta == null
? { 'agentEventActor.contextMeta': { $exists: false } }
: { 'agentEventActor.contextMeta': input.expected.contextMeta }),
...(input.expected.compactionSemanticIndex == null
? { 'agentEventActor.compactionSemanticIndex': { $exists: false } }
: {
'agentEventActor.compactionSemanticIndex': input.expected.compactionSemanticIndex,
}),
'agentEventActor.requiresColdStart':
input.expected.requiresColdStart === true ? true : { $ne: true },
}),
};
const settlementFilter: FilterQuery<IConversation> =
input.settlementAuthority == null
? {}
: {
'agentEventActorSuspension.status': { $in: ['claimed', 'claimed_owned'] },
'agentEventActorSuspension.suspension.suspensionId':
input.settlementAuthority.suspensionId,
'agentEventActorSuspension.suspension.attempt': input.settlementAuthority.attempt,
'agentEventActorSuspension.resumeAttemptId': input.settlementAuthority.resumeAttemptId,
};
const nextState: IAgentEventActorState = {
generation: (input.expected?.generation ?? 0) + 1,
checkpoint: input.checkpoint,
...(input.contextFingerprint == null ? {} : { contextFingerprint: input.contextFingerprint }),
...(input.skillManifest == null ? {} : { skillManifest: input.skillManifest }),
...(input.discoveredToolNames == null
? {}
: { discoveredToolNames: input.discoveredToolNames }),
...(input.summary == null ? {} : { summary: input.summary }),
...(input.contextMeta == null ? {} : { contextMeta: input.contextMeta }),
...(input.compactionSemanticIndex == null
? {}
: { compactionSemanticIndex: input.compactionSemanticIndex }),
...(input.expected == null ? {} : { previousCheckpoint: input.expected.checkpoint }),
};
const previous = await Conversation.findOneAndUpdate(
{
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
agentEventActorReconciliations: {
$elemMatch: {
invocationId: input.invocationId,
status: 'invocation_pending',
},
},
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
...expectedFilter,
...settlementFilter,
},
{
$set: {
agentEventActor: nextState,
'agentEventActorReconciliations.$.status': 'persistence_pending',
'agentEventActorReconciliations.$.checkpoint': input.checkpoint,
'agentEventActorReconciliations.$.action': input.action,
'agentEventActorReconciliations.$.observedAt': new Date(),
...(input.settlementAuthority == null
? {}
: {
'agentEventActorSuspension.status': 'closed',
'agentEventActorSuspension.outcome': 'committed',
'agentEventActorSuspension.closedAt': new Date(),
'agentEventActorSuspension.observedAt': new Date(),
}),
},
...(input.expected?.previousCheckpoint == null
? {}
: {
$addToSet: { agentEventActorCleanup: input.expected.previousCheckpoint },
}),
$unset: { 'agentEventActorReconciliations.$.error': 1 },
},
{ new: false, timestamps: false },
)
.select('+agentEventActor +agentEventActorSuspension')
.lean<IConversation>();
if (previous != null) {
return {
status: 'committed',
state: nextState,
...(previous.agentEventActor?.previousCheckpoint == null
? {}
: { prunableCheckpoint: previous.agentEventActor.previousCheckpoint }),
};
}
if (input.settlementAuthority != null) {
/** A resumed action must close its claim even when another head won.
* The negative full-head predicate makes this mutually exclusive with
* the commit CAS above; the retained closure is the ambiguous-reply receipt. */
const closedStale = await Conversation.findOneAndUpdate(
{
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
agentEventActorReconciliations: {
$elemMatch: {
invocationId: input.invocationId,
status: 'invocation_pending',
},
},
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
...settlementFilter,
$nor: [expectedFilter],
},
{
$set: {
'agentEventActorSuspension.status': 'closed',
'agentEventActorSuspension.outcome': 'stale',
'agentEventActorSuspension.closedAt': new Date(),
'agentEventActorSuspension.observedAt': new Date(),
},
},
{ new: false, timestamps: false },
)
.select('+agentEventActor +agentEventActorSuspension')
.lean<IConversation>();
if (closedStale != null) {
return {
status: 'stale',
...(closedStale.agentEventActor == null ? {} : { state: closedStale.agentEventActor }),
};
}
const current = await getAgentEventActorSnapshot(input);
const receipt = current?.suspension;
const matchesAuthority =
receipt?.suspension.suspensionId === input.settlementAuthority.suspensionId &&
receipt?.suspension.attempt === input.settlementAuthority.attempt &&
receipt?.resumeAttemptId === input.settlementAuthority.resumeAttemptId;
if (matchesAuthority && receipt?.status === 'closed') {
if (receipt.outcome === 'committed' && current?.state != null) {
return { status: 'committed', state: current.state };
}
if (receipt.outcome === 'stale') {
return {
status: 'stale',
...(current?.state == null ? {} : { state: current.state }),
};
}
}
if (matchesAuthority) {
throw new Error('Resumed event actor commit could not close its suspension fence');
}
return {
status: 'stale',
...(current?.state == null ? {} : { state: current.state }),
};
}
const current = await getAgentEventActorSnapshot(input);
return {
status: 'stale',
...(current?.state == null ? {} : { state: current.state }),
};
}
/**
* Opens the durable fence for one legacy-path turn BEFORE it executes. One
* mutually exclusive classic update sets the token and, only when a valid
* head exists, marks it cold — no partial fence state is externally visible.
* Refuses while another legacy turn or fork lifecycle is active. Abandoned
* legacy tokens are reclaimed through the bounded recovery operation before
* admission is retried.
*/
async function beginAgentEventActorLegacyTurn(input: {
user: string;
conversationId: string;
tenantId?: string;
token: string;
}): Promise<boolean> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const ownership: FilterQuery<IConversation> = {
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
agentEventActorLegacyTurn: { $exists: false },
agentEventActorReconciliations: {
$not: { $elemMatch: { status: { $ne: 'settled' } } },
},
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
};
const legacyTurn = { token: input.token, startedAt: new Date() };
/** DocumentDB does not support aggregation-pipeline updates. Split the
* headful/headless shapes into mutually exclusive classic updates. A head
* cannot appear between them without first creating an unresolved fork
* lifecycle, which the shared ownership filter rejects. */
const openedWithHead = await Conversation.findOneAndUpdate(
{ ...ownership, 'agentEventActor.generation': { $exists: true } },
{
$set: {
agentEventActorLegacyTurn: legacyTurn,
'agentEventActor.requiresColdStart': true,
},
},
{ new: true, timestamps: false },
).lean<IConversation>();
if (openedWithHead != null) {
return true;
}
const openedHeadless = await Conversation.findOneAndUpdate(
{ ...ownership, 'agentEventActor.generation': { $exists: false } },
{ $set: { agentEventActorLegacyTurn: legacyTurn } },
{ new: true, timestamps: false },
).lean<IConversation>();
return openedHeadless != null;
}
/**
* Closes the fence in ONE atomic write once the legacy turn's history is
* durable: clears this exact token and advances the epoch together, so a
* fork can never observe a cleared fence at an unchanged epoch. Matching the
* token keeps a later turn's seal from closing an earlier turn's fence.
*/
async function completeAgentEventActorLegacyTurn(input: {
user: string;
conversationId: string;
tenantId?: string;
token: string;
}): Promise<boolean> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const sealed = await Conversation.findOneAndUpdate(
{
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
'agentEventActorLegacyTurn.token': input.token,
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
},
{
$unset: { agentEventActorLegacyTurn: 1 },
$inc: { agentEventActorEpoch: 1 },
},
{ new: true, timestamps: false },
).lean<IConversation>();
return sealed != null;
}
/** Acquires or advances one invocation lifecycle fence and blocks competing turns. */
async function recordAgentEventActorReconciliation(input: {
user: string;
conversationId: string;
tenantId?: string;
reconciliation: IAgentEventActorReconciliation;
}): Promise<boolean> {
if (input.reconciliation.checkpoint.threadId !== input.conversationId) {
throw new Error('Event actor reconciliation changed its logical thread');
}
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const ownership = {
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
};
const existing = await Conversation.findOne(ownership)
.select('+agentEventActorReconciliations')
.lean<IConversation>();
const journal = existing?.agentEventActorReconciliations ?? [];
const current = journal.find((item) => item.invocationId === input.reconciliation.invocationId);
if (current != null) {
const confirmsActionAdmission =
current.status === 'invocation_pending' &&
current.actionAdmitted !== true &&
input.reconciliation.status === 'invocation_pending' &&
input.reconciliation.actionAdmitted === true &&
current.checkpoint.threadId === input.reconciliation.checkpoint.threadId &&
current.checkpoint.checkpointId === input.reconciliation.checkpoint.checkpointId &&
current.checkpoint.checkpointNs === input.reconciliation.checkpoint.checkpointNs &&
current.action.toolName === input.reconciliation.action.toolName &&
current.action.toolCallId === input.reconciliation.action.toolCallId;
const canTransition =
confirmsActionAdmission ||
(current?.status === 'invocation_pending' &&
input.reconciliation.status !== 'invocation_pending') ||
(current?.status === 'persistence_pending' &&
(input.reconciliation.status === 'persistence_failed' ||
input.reconciliation.status === 'history_persisted')) ||
(current?.status === 'persistence_failed' &&
input.reconciliation.status === 'history_persisted');
const sameIdentity =
current?.status === input.reconciliation.status &&
current.actionAdmitted === input.reconciliation.actionAdmitted &&
current.checkpoint.threadId === input.reconciliation.checkpoint.threadId &&
current.checkpoint.checkpointId === input.reconciliation.checkpoint.checkpointId &&
current.checkpoint.checkpointNs === input.reconciliation.checkpoint.checkpointNs &&
current.action.toolName === input.reconciliation.action.toolName &&
current.action.toolCallId === input.reconciliation.action.toolCallId;
/** A pending record is an exclusive ownership fence, not an idempotent
* receipt. A second executor must not inherit the first owner's claim. */
if (input.reconciliation.status === 'invocation_pending' && !confirmsActionAdmission) {
return false;
}
if (!canTransition) {
return sameIdentity;
}
const transitioned = await Conversation.findOneAndUpdate(
{
...ownership,
agentEventActorReconciliations: {
$elemMatch: {
invocationId: input.reconciliation.invocationId,
status: current!.status,
...(confirmsActionAdmission && {
actionAdmitted: { $ne: true },
'checkpoint.threadId': current.checkpoint.threadId,
'checkpoint.checkpointNs': current.checkpoint.checkpointNs,
...(current.checkpoint.checkpointId == null
? { 'checkpoint.checkpointId': { $exists: false } }
: { 'checkpoint.checkpointId': current.checkpoint.checkpointId }),
'action.toolName': current.action.toolName,
...(current.action.toolCallId == null
? { 'action.toolCallId': { $exists: false } }
: { 'action.toolCallId': current.action.toolCallId }),
}),
},
},
},
{ $set: { 'agentEventActorReconciliations.$': input.reconciliation } },
{ new: true, timestamps: false },
)
.select('+agentEventActorReconciliations')
.lean<IConversation>();
return transitioned != null;
}
/** Every post-acquisition state must transition the exact pending lifecycle.
* Never recreate a marker after terminal recovery has already removed it. */
if (input.reconciliation.status !== 'invocation_pending') {
return false;
}
const recorded = await Conversation.findOneAndUpdate(
{
...ownership,
agentEventActorLegacyTurn: { $exists: false },
agentEventActorReconciliations: {
$not: { $elemMatch: { status: { $ne: 'settled' } } },
},
'agentEventActorReconciliations.invocationId': { $ne: input.reconciliation.invocationId },
},
{ $push: { agentEventActorReconciliations: input.reconciliation } },
{ new: true, timestamps: false },
)
.select('+agentEventActorReconciliations')
.lean<IConversation>();
if (
recorded?.agentEventActorReconciliations?.some(
(item) => item.invocationId === input.reconciliation.invocationId,
) === true
) {
return true;
}
/** Another writer won the same invocation fence while this write raced. */
return false;
}
/** Resolves exactly one lifecycle after settlement, abandonment, or repair. */
async function resolveAgentEventActorReconciliation(input: {
user: string;
conversationId: string;
tenantId?: string;
invocationId: string;
checkpoint: IAgentEventActorReconciliation['checkpoint'];
expectedActionAdmitted?: boolean;
resolution:
| 'checkpoint_verified'
| 'action_compensated'
| 'history_repaired'
| 'invocation_abandoned';
}): Promise<boolean> {
if (input.checkpoint.threadId !== input.conversationId) {
throw new Error('Event actor reconciliation changed its logical thread');
}
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const exactCheckpoint: Record<string, unknown> = {
invocationId: input.invocationId,
'checkpoint.threadId': input.checkpoint.threadId,
'checkpoint.checkpointNs': input.checkpoint.checkpointNs,
...(input.checkpoint.checkpointId == null
? { 'checkpoint.checkpointId': { $exists: false } }
: { 'checkpoint.checkpointId': input.checkpoint.checkpointId }),
};
if (
input.resolution === 'checkpoint_verified' &&
(typeof input.checkpoint.checkpointId !== 'string' ||
input.checkpoint.checkpointId.length === 0)
) {
return false;
}
const owner = {
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
};
if (input.resolution === 'checkpoint_verified') {
const settled = await Conversation.findOneAndUpdate(
{
...owner,
'agentEventActor.checkpoint.threadId': input.checkpoint.threadId,
'agentEventActor.checkpoint.checkpointId': input.checkpoint.checkpointId!,
'agentEventActor.checkpoint.checkpointNs': input.checkpoint.checkpointNs,
agentEventActorReconciliations: {
$elemMatch: { ...exactCheckpoint, status: 'history_persisted' },
},
},
{
$set: {
'agentEventActorReconciliations.$.status': 'settled',
'agentEventActorReconciliations.$.resolution': 'checkpoint_verified',
'agentEventActorReconciliations.$.observedAt': new Date(),
},
$unset: { 'agentEventActorReconciliations.$.error': 1 },
},
{ new: true, timestamps: false },
)
.select('+agentEventActorReconciliations')
.lean<IConversation>();
if (settled != null) {
return true;
}
/** A verification retry may replay only a receipt that verification
* itself settled. A compensated receipt must fail this resolve so the
* caller re-reads and honors the compensation instead. */
const replay = await Conversation.exists({
...owner,
'agentEventActor.checkpoint.threadId': input.checkpoint.threadId,
'agentEventActor.checkpoint.checkpointId': input.checkpoint.checkpointId!,
'agentEventActor.checkpoint.checkpointNs': input.checkpoint.checkpointNs,
agentEventActorReconciliations: {
$elemMatch: { ...exactCheckpoint, status: 'settled', resolution: 'checkpoint_verified' },
},
});
return replay != null;
}
let expectedAdmissionFilter: Record<string, unknown> = {};
if (input.expectedActionAdmitted != null) {
expectedAdmissionFilter = input.expectedActionAdmitted
? { actionAdmitted: true }
: { actionAdmitted: { $ne: true } };
}
const checkpointFilter: Record<string, unknown> = {
...exactCheckpoint,
...(input.resolution === 'invocation_abandoned'
? {
status: 'invocation_pending',
...expectedAdmissionFilter,
}
: {
status: {
$in: [
'persistence_pending',
'history_persisted',
'commit_conflict',
'commit_indeterminate',
'persistence_failed',
],
},
}),
};
const ownership = {
...owner,
agentEventActorReconciliations: { $elemMatch: checkpointFilter },
};
const mustRebuild =
input.resolution === 'action_compensated' || input.resolution === 'history_repaired';
if (!mustRebuild) {
const abandoned = await Conversation.findOneAndUpdate(
ownership,
{ $pull: { agentEventActorReconciliations: checkpointFilter } },
{ new: true, timestamps: false },
)
.select('+agentEventActorReconciliations')
.lean<IConversation>();
return abandoned != null;
}
/** Repair and compensation both act on an invocation whose action already
* reached the outside world, so the receipt must survive as the durable
* same-invocation tombstone. Deleting it would let a delayed duplicate
* owner reacquire the same id and repeat that action. Compensation undoes
* the effect; it does not re-authorize the delivery, so a legitimate retry
* must arrive under a new invocation id. */
const retainedReceipt = {
'agentEventActorReconciliations.$.status': 'settled',
'agentEventActorReconciliations.$.resolution': input.resolution,
'agentEventActorReconciliations.$.observedAt': new Date(),
};
const resolved = await Conversation.findOneAndUpdate(
{ ...ownership, agentEventActor: { $exists: true } },
{ $set: { ...retainedReceipt, 'agentEventActor.requiresColdStart': true } },
{ new: true, timestamps: false },
)
.select('+agentEventActorReconciliations')
.lean<IConversation>();
if (resolved != null) {
return true;
}
/** Compensation before a first committed head must retire the exact fence
* without creating a partial actor state that cannot be resumed. */
const resolvedWithoutHead = await Conversation.findOneAndUpdate(
{ ...ownership, agentEventActor: { $exists: false } },
{ $set: retainedReceipt },
{ new: true, timestamps: false },
)
.select('+agentEventActorReconciliations')
.lean<IConversation>();
if (resolvedWithoutHead != null) {
return true;
}
/** A retried repair finds its own retained receipt already settled. */
const replayed = await Conversation.exists({
...owner,
agentEventActorReconciliations: {
$elemMatch: { ...exactCheckpoint, status: 'settled', resolution: input.resolution },
},
});
return replayed != null;
}
/** Removes an active lifecycle only after its terminal proof is durable elsewhere. */
async function clearAgentEventActorReconciliation(input: {
user: string;
conversationId: string;
tenantId?: string;
invocationId: string;
checkpoint: IAgentEventActorReconciliation['checkpoint'];
resolution: 'checkpoint_verified' | 'action_compensated' | 'history_repaired';
}): Promise<boolean> {
if (input.checkpoint.threadId !== input.conversationId) {
throw new Error('Event actor reconciliation changed its logical thread');
}
if (
input.resolution === 'checkpoint_verified' &&
(typeof input.checkpoint.checkpointId !== 'string' ||
input.checkpoint.checkpointId.length === 0)
) {
return false;
}
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const exactCheckpoint = {
invocationId: input.invocationId,
'checkpoint.threadId': input.checkpoint.threadId,
'checkpoint.checkpointNs': input.checkpoint.checkpointNs,
...(input.checkpoint.checkpointId == null
? { 'checkpoint.checkpointId': { $exists: false } }
: { 'checkpoint.checkpointId': input.checkpoint.checkpointId }),
};
const owner = {
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
agentEventBinding: { $exists: true },
...subagentLeaseTenantFilter(input.tenantId),
...activeExpirationFilter<IConversation>(),
};
const activeStatuses =
input.resolution === 'checkpoint_verified'
? ['history_persisted']
: [
'persistence_pending',
'history_persisted',
'commit_conflict',
'commit_indeterminate',
'persistence_failed',
];
const lifecycle = {
...exactCheckpoint,
$or: [
{ status: { $in: activeStatuses } },
{ status: 'settled', resolution: input.resolution },
],
};
const clearedWithHead = await Conversation.findOneAndUpdate(
{
...owner,
agentEventActor: { $exists: true },
...(input.resolution === 'checkpoint_verified' && {
'agentEventActor.checkpoint.threadId': input.checkpoint.threadId,
'agentEventActor.checkpoint.checkpointId': input.checkpoint.checkpointId,
'agentEventActor.checkpoint.checkpointNs': input.checkpoint.checkpointNs,
}),
agentEventActorReconciliations: { $elemMatch: lifecycle },
},
{
...(input.resolution === 'checkpoint_verified'
? {}
: { $set: { 'agentEventActor.requiresColdStart': true } }),
$pull: { agentEventActorReconciliations: lifecycle },
},
{ new: true, timestamps: false },
)
.select('+agentEventActorReconciliations')
.lean<IConversation>();
if (clearedWithHead != null) {
return true;
}
if (input.resolution !== 'checkpoint_verified') {
const clearedWithoutHead = await Conversation.findOneAndUpdate(
{
...owner,
agentEventActor: { $exists: false },
agentEventActorReconciliations: { $elemMatch: lifecycle },
},
{ $pull: { agentEventActorReconciliations: lifecycle } },
{ new: true, timestamps: false },
)
.select('+agentEventActorReconciliations')
.lean<IConversation>();
if (clearedWithoutHead != null) {
return true;
}
}
const conflict = await Conversation.exists({
...owner,
agentEventActorReconciliations: { $elemMatch: { invocationId: input.invocationId } },
});
if (conflict != null) {
return false;
}
return (await Conversation.exists(owner)) != null;
}
async function getAgentEventActorReconciliationStorageMetrics(
now: Date,
): Promise<AgentEventActorReconciliationStorageMetrics> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const [row] = await Conversation.aggregate<{ pending: number; oldestObservedAt?: Date }>([
{
$match: {
agentEventActorReconciliations: {
$elemMatch: { status: { $ne: 'settled' } },
},
},
},
{ $unwind: '$agentEventActorReconciliations' },
{ $match: { 'agentEventActorReconciliations.status': { $ne: 'settled' } } },
{
$group: {
_id: null,
pending: { $sum: 1 },
oldestObservedAt: { $min: '$agentEventActorReconciliations.observedAt' },
},
},
]);
const oldestObservedAt = row?.oldestObservedAt;
return {
pending: row?.pending ?? 0,
oldestPendingAgeSeconds:
oldestObservedAt == null
? 0
: Math.max(0, (now.getTime() - oldestObservedAt.getTime()) / 1000),
};
}
/** Bounded mixed-version cleanup for terminal receipts embedded by older
* builds. New receipts expire through the delivery collection TTL index,
* but dormant legacy conversations need an independent retirement path. */
async function expireLegacyAgentEventActorReceipts(
now: Date,
limit = 100,
activity?: { found: boolean },
): Promise<number> {
if (Number.isNaN(now.getTime())) {
throw new TypeError('now must be a valid date');
}
const boundedLimit = Math.max(1, Math.min(Math.trunc(limit), 1_000));
const cutoff = new Date(now.getTime() - AGENT_EVENT_ACTOR_RECEIPT_RETENTION_MS);
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const Delivery = mongoose.models.AgentTriggerDelivery as
| Model<IAgentTriggerDeliveryDocument>
| undefined;
if (Delivery == null) {
return 0;
}
/** Advance a bounded candidate page before querying delivery protection.
* Reaching the end resets the cursor so newly expiry-eligible older rows
* enter the next sweep without making any one pass collection-wide. */
const candidates = await Conversation.find({
...(legacyReceiptExpiryCursor == null ? {} : { _id: { $gt: legacyReceiptExpiryCursor } }),
})
/** Pure inclusion, as an object. The string form
* `'_id +agentEventActorReconciliations'` compiles to `{ _id: 1 }` plus a
* `: 0` exclusion for every OTHER `select: false` sibling — the `+` token
* only un-hides its field and `_id` alone does not make the projection
* inclusive. MongoDB tolerates that mixed shape via the `_id` exception;
* Amazon DocumentDB rejects it, which failed this sweep on every pass and
* took the sequenced lane reclamation down with it. An explicit `1` for a
* `select: false` path overrides the schema default, so nothing hidden
* leaks and nothing extra is fetched. */
.select({ _id: 1, agentEventActorReconciliations: 1 })
.sort({ _id: 1 })
.limit(boundedLimit)
.lean<
Array<Pick<IConversation, 'agentEventActorReconciliations'> & { _id: Types.ObjectId }>
>();
if (candidates.length === 0) {
legacyReceiptExpiryCursor = undefined;
return 0;
}
legacyReceiptExpiryCursor = candidates[candidates.length - 1]._id;
// A full page is not an empty sweep: later conversations may contain
// expired receipts. Keep scanning at base cadence until the page walk ends.
if (activity != null && candidates.length === boundedLimit) activity.found = true;
const expiredInvocationIds = [
...new Set(
candidates.flatMap((candidate) =>
(candidate.agentEventActorReconciliations ?? [])
.filter((receipt) => receipt.status === 'settled' && receipt.observedAt <= cutoff)
.map((receipt) => receipt.invocationId),
),
),
];
if (expiredInvocationIds.length === 0) return 0;
if (activity != null) activity.found = true;
const protectedInvocationIds = new Set(
await Delivery.find({
deliveryKey: { $in: expiredInvocationIds },
$or: [{ handling: { $exists: false } }, { 'handling.status': 'started' }],
}).distinct<string>('deliveryKey'),
);
const operations = candidates.flatMap((candidate) => {
const removable = (candidate.agentEventActorReconciliations ?? [])
.filter(
(receipt) =>
receipt.status === 'settled' &&
receipt.observedAt <= cutoff &&
!protectedInvocationIds.has(receipt.invocationId),
)
.map((receipt) => receipt.invocationId);
return removable.length === 0
? []
: [
{
updateOne: {
filter: { _id: candidate._id },
update: {
$pull: {
agentEventActorReconciliations: {
invocationId: { $in: removable },
status: 'settled',
observedAt: { $lte: cutoff },
},
},
},
},
},
];
}) as unknown as AnyBulkWriteOperation[];
if (operations.length === 0) {
return 0;
}
const result = await tenantSafeBulkWrite(Conversation, operations, {
ordered: false,
timestamps: false,
});
return result.modifiedCount;
}
/** Creates immutable child lineage exactly once without overwriting a concurrent winner. */
async function reserveSubagentThread(input: {
user: string;
conversationId: string;
conversation: Partial<IConversation>;
tenantId?: string;
}): Promise<ISubagentThreadReservation> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const filter = {
user: input.user,
conversationId: input.conversationId,
...(input.tenantId == null ? { tenantId: { $exists: false } } : { tenantId: input.tenantId }),
};
try {
const result = (await Conversation.findOneAndUpdate(
filter,
{
$setOnInsert: {
...input.conversation,
user: input.user,
conversationId: input.conversationId,
messages: [],
},
},
{ new: true, upsert: true, includeResultMetadata: true, setDefaultsOnInsert: true },
).select('+agentEventBinding')) as unknown as ConversationUpdateResult;
if (result.value == null) {
throw new Error('Unable to reserve the subagent thread.');
}
return {
conversation: result.value.toObject(),
created: result.lastErrorObject?.updatedExisting !== true,
};
} catch (error) {
/** Concurrent upserts can race at the unique index. The document that won is
* the reservation; callers still validate its immutable lineage before use. */
if ((error as { code?: number }).code === 11000) {
const existing = await Conversation.findOne(filter)
.select('+agentEventBinding')
.lean<IConversation>();
if (existing != null) {
return { conversation: existing, created: false };
}
}
throw error;
}
}
function subagentLeaseTenantFilter(tenantId?: string): FilterQuery<IConversation> {
return tenantId == null ? { tenantId: { $exists: false } } : { tenantId };
}
/** Atomically claims one durable child thread across all API replicas. */
async function acquireSubagentThreadLease(input: {
user: string;
conversationId: string;
token: string;
taskId: string;
now: Date;
expiresAt: Date;
tenantId?: string;
}): Promise<boolean> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const result = await Conversation.updateOne(
{
user: input.user,
conversationId: input.conversationId,
subagentThread: { $exists: true },
...subagentLeaseTenantFilter(input.tenantId),
$or: [
{ subagentThreadLease: { $exists: false } },
{ 'subagentThreadLease.expiresAt': { $lte: input.now } },
{ 'subagentThreadLease.token': input.token },
],
},
{
$set: {
subagentThreadLease: {
token: input.token,
taskId: input.taskId,
expiresAt: input.expiresAt,
},
/** Child threads are hidden from normal recents. Stamp the task start
* explicitly so bounded parent discovery promotes real new activity;
* automatic timestamps stay disabled for lease heartbeats/releases. */
updatedAt: input.now,
},
},
{ timestamps: false },
);
return result.matchedCount === 1;
}
/** Renews only the unexpired lease owned by this exact task token. */
async function renewSubagentThreadLease(input: {
user: string;
conversationId: string;
token: string;
now: Date;
expiresAt: Date;
tenantId?: string;
}): Promise<boolean> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const result = await Conversation.updateOne(
{
user: input.user,
conversationId: input.conversationId,
...subagentLeaseTenantFilter(input.tenantId),
'subagentThreadLease.token': input.token,
'subagentThreadLease.expiresAt': { $gt: input.now },
},
{ $set: { 'subagentThreadLease.expiresAt': input.expiresAt } },
{ timestamps: false },
);
return result.matchedCount === 1;
}
/** Releases only the lease owned by this exact task token. */
async function releaseSubagentThreadLease(input: {
user: string;
conversationId: string;
token: string;
tenantId?: string;
}): Promise<boolean> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const result = await Conversation.updateOne(
{
user: input.user,
conversationId: input.conversationId,
...subagentLeaseTenantFilter(input.tenantId),
'subagentThreadLease.token': input.token,
},
{ $unset: { subagentThreadLease: 1 } },
{ timestamps: false },
);
return result.modifiedCount === 1;
}
/** Counts live child execution fences while account deletion drains. */
async function countActiveSubagentThreadLeases(input: {
user: string;
now: Date;
tenantId?: string;
}): Promise<number> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return Conversation.countDocuments({
user: input.user,
...subagentLeaseTenantFilter(input.tenantId),
'subagentThreadLease.expiresAt': { $gt: input.now },
});
}
/** Resolves only live task addresses so account-wide cancellation stays O(active tasks). */
async function listActiveSubagentThreadLeases(input: {
user: string;
now: Date;
tenantId?: string;
}): Promise<IActiveSubagentThreadLease[]> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const conversations = await Conversation.find({
user: input.user,
...subagentLeaseTenantFilter(input.tenantId),
'subagentThreadLease.expiresAt': { $gt: input.now },
})
.select('conversationId subagentThread.parentConversationId +subagentThreadLease')
.lean<
Array<Pick<IConversation, 'conversationId' | 'subagentThread' | 'subagentThreadLease'>>
>();
return conversations.flatMap((conversation) => {
const { conversationId } = conversation;
const parentConversationId = conversation.subagentThread?.parentConversationId;
const taskId = conversation.subagentThreadLease?.taskId;
return typeof conversationId === 'string' &&
conversationId !== '' &&
typeof parentConversationId === 'string' &&
parentConversationId !== '' &&
typeof taskId === 'string' &&
taskId !== ''
? [{ conversationId, parentConversationId, taskId }]
: [];
});
}
/**
* Public-read probe: resolves ownership plus the child-thread discriminator
* without materializing the full conversation document (preset spread +
* message ObjectId array).
*/
async function getConvoOwnership(user: string, conversationId: string, tenantId?: string | null) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const tenantFilter =
tenantId === undefined ? {} : subagentLeaseTenantFilter(tenantId ?? undefined);
return await Conversation.findOne(
{
user,
conversationId,
...tenantFilter,
...activeExpirationFilter<IConversation>(),
},
'user tenantId subagentThread',
).lean<Pick<IConversation, 'user' | 'tenantId' | 'subagentThread'>>();
} catch (error) {
logger.error('[getConvoOwnership] Error checking conversation ownership', error);
throw new Error('Error checking conversation ownership');
}
}
/**
* Retrieves only the retention deadline for a conversation.
*/
async function getConvoRetention(
user: string,
conversationId: string,
): Promise<Pick<IConversation, 'expiredAt' | 'isTemporary'> | null> {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return await Conversation.findOne({ user, conversationId }, 'expiredAt isTemporary').lean<
Pick<IConversation, 'expiredAt' | 'isTemporary'>
>();
} catch (error) {
logger.error('[getConvoRetention] Error getting conversation retention fields', error);
throw new Error('Error getting conversation retention fields');
}
}
/**
* Searches for a conversation by conversationId and returns associated file ids.
*/
async function getConvoFiles(conversationId: string): Promise<string[]> {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return (
(await Conversation.findOne({ conversationId }, 'files').lean<IConversation>())?.files ?? []
);
} catch (error) {
logger.error('[getConvoFiles] Error getting conversation files', error);
throw new Error('Error getting conversation files');
}
}
async function stampForcedRetention(
{ userId, interfaceConfig }: { userId: string; interfaceConfig?: AppConfig['interfaceConfig'] },
{ conversationId, messageIds = [] }: { conversationId: string; messageIds?: string[] },
): Promise<void> {
if (!userId || !isForcedTemporaryRetention(interfaceConfig?.retentionMode)) {
return;
}
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const stored = await Conversation.findOne({ conversationId, user: userId })
.select({ _id: 1, isTemporary: 1, expiredAt: 1, tags: 1 })
.lean<{
_id: Types.ObjectId;
isTemporary?: boolean;
expiredAt?: Date | null;
tags?: string[];
} | null>();
if (!stored) {
return;
}
let expiredAt = stored.expiredAt ?? null;
if (expiredAt == null) {
try {
expiredAt = createTempChatExpirationDate(interfaceConfig);
} catch (err) {
logger.error('[stampForcedRetention] Error creating temporary chat expiration date:', err);
expiredAt = createFallbackRetentionDate();
}
}
let stampedDeadline = stored.expiredAt != null;
if (stored.isTemporary !== true) {
/**
* Conditional on the transition, so concurrent stamps release the bookmark counts once;
* the released tags are cleared with it so a later delete cannot release them again.
*/
const converted = await Conversation.updateOne(
{ _id: stored._id, isTemporary: { $ne: true } },
{ $set: { isTemporary: true, expiredAt, tags: [] } },
{ timestamps: false },
);
stampedDeadline ||= converted.modifiedCount > 0;
if (converted.modifiedCount > 0 && stored.tags?.length) {
await decrementTagCounts(mongoose, userId, stored.tags);
}
} else if (stored.expiredAt == null) {
const stamped = await Conversation.updateOne(
{ _id: stored._id, expiredAt: null },
{ $set: { expiredAt } },
{ timestamps: false },
);
stampedDeadline = stamped.modifiedCount > 0;
}
if (messageIds.length === 0) {
return;
}
if (!stampedDeadline) {
/** A concurrent stamp set the conversation's deadline first; its messages share that one. */
const current = await Conversation.findOne({ _id: stored._id })
.select({ expiredAt: 1 })
.lean<{ expiredAt?: Date | null } | null>();
expiredAt = current?.expiredAt ?? expiredAt;
}
const Message = mongoose.models.Message as Model<IMessage>;
await Message.updateMany(
{ user: userId, conversationId, messageId: { $in: messageIds } },
{ $set: { isTemporary: true, expiredAt } },
{ timestamps: false },
);
}
/**
* Saves a conversation to the database.
*/
async function saveConvo(
{
userId,
isTemporary,
expiredAt,
interfaceConfig,
}: {
userId: string;
isTemporary?: boolean;
expiredAt?: Date;
interfaceConfig?: AppConfig['interfaceConfig'];
},
{
conversationId,
newConversationId,
...convo
}: {
conversationId: string;
newConversationId?: string;
[key: string]: unknown;
},
metadata?: {
context?: string;
unsetFields?: Record<string, number>;
noUpsert?: boolean;
createdAtOnInsert?: Date;
preserveUpdatedAt?: boolean;
titleSource?: 'manual' | 'generated';
initialAgentId?: string | null;
/** Casts plain string ids, so callers outside this package need not name the id type. */
appendMessageIds?: Array<Types.ObjectId | string>;
/** Stamp `lastResponseAt` at write time: this save carries a persisted assistant reply. */
stampReply?: boolean;
/** Durable messageId paired atomically with a reply stamp. */
replyMessageId?: string;
},
) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const { getMessages } = getMessageMethods();
if (metadata?.context) {
logger.debug(`[saveConvo] ${metadata.context}`);
}
const appendMessageIds = metadata?.appendMessageIds;
const update: Record<string, unknown> = { ...convo, user: userId };
delete update.isTemporary;
delete update.expiredAt;
/* Read-state fields are server-owned. A stale marker must never be reintroduced by a
* metadata save after a real reply cleared it. */
delete update.lastResponseIsManual;
delete update.isMarkedUnread;
delete update.lastResponseAt;
delete update.lastResponseMessageId;
delete update.initial_agent_id;
delete update.titleSetByUser;
delete update.titleRevision;
if (metadata?.titleSource === 'manual') {
update.titleSetByUser = true;
}
/* Remembered tool approvals are granted only by a validated resume. */
delete update.toolApprovalAllows;
stripFields(update, LANE_PRIVATE_FIELDS);
/** Ordinary saves may seed a decision, but only an explicit move may replace it. */
const decisionOnInsert = {
...(convo.codeEnvironmentMode != null && {
codeEnvironmentMode: convo.codeEnvironmentMode,
}),
...(convo.codeWorkspaces != null && { codeWorkspaces: convo.codeWorkspaces }),
};
delete update.codeEnvironmentRevision;
delete update.codeEnvironmentMode;
delete update.codeWorkspaces;
stripActorCheckpointFields(update);
if (appendMessageIds == null) {
update.messages = await getMessages({ conversationId, user: userId }, '_id');
} else {
delete update.messages;
}
const unsetFields: Record<string, number> = { ...(metadata?.unsetFields ?? {}) };
delete unsetFields.lastResponseIsManual;
delete unsetFields.isMarkedUnread;
delete unsetFields.lastResponseMessageId;
delete unsetFields.lastResponseAt;
delete unsetFields.initial_agent_id;
delete unsetFields.titleSetByUser;
delete unsetFields.titleRevision;
delete unsetFields.toolApprovalAllows;
stripFields(unsetFields, LANE_PRIVATE_FIELDS);
delete unsetFields.codeEnvironmentRevision;
delete unsetFields.codeEnvironmentMode;
delete unsetFields.codeWorkspaces;
stripActorCheckpointFields(unsetFields);
let chatProjectIdOnInsert: string | undefined;
// Turn saves may seed a new conversation, never move or detach an existing one.
const candidate = update.chatProjectId;
delete update.chatProjectId;
delete unsetFields.chatProjectId;
if (metadata?.noUpsert !== true && typeof candidate === 'string') {
if (isValidObjectIdString(candidate)) {
const ChatProject = mongoose.models.ChatProject as Model<IChatProjectDocument>;
const project = await ChatProject.exists({
_id: new mongoose.Types.ObjectId(candidate),
user: userId,
});
if (project != null) {
chatProjectIdOnInsert = candidate;
}
}
}
if (newConversationId) {
update.conversationId = newConversationId;
}
let retentionOnInsert: { expiredAt: Date; isTemporary: false } | undefined;
const forcedTemporary = isForcedTemporaryRetention(interfaceConfig?.retentionMode);
if (expiredAt instanceof Date && !Number.isNaN(expiredAt.getTime())) {
if (forcedTemporary) {
update.isTemporary = true;
} else if (typeof isTemporary === 'boolean') {
update.isTemporary = isTemporary;
}
update.expiredAt = expiredAt;
} else if (forcedTemporary) {
update.isTemporary = true;
try {
update.expiredAt = createTempChatExpirationDate(interfaceConfig);
} catch (err) {
logger.error('Error creating temporary chat expiration date:', err);
logger.info(`---\`saveConvo\` context: ${metadata?.context}`);
update.expiredAt = createFallbackRetentionDate();
}
} else if (interfaceConfig?.retentionMode === RetentionMode.ALL) {
if (typeof isTemporary === 'boolean') {
update.isTemporary = isTemporary;
}
if (
typeof isTemporary === 'boolean' ||
interfaceConfig.generalChatRetention === undefined
) {
try {
update.expiredAt = createChatExpirationDate(interfaceConfig, isTemporary);
} catch (err) {
logger.error('Error creating chat expiration date:', err);
logger.info(`---\`saveConvo\` context: ${metadata?.context}`);
update.expiredAt = createFallbackRetentionDate();
}
} else {
try {
retentionOnInsert = {
expiredAt: createChatExpirationDate(interfaceConfig, false),
isTemporary: false,
};
} catch (err) {
logger.error('Error creating chat expiration date:', err);
logger.info(`---\`saveConvo\` context: ${metadata?.context}`);
retentionOnInsert = {
expiredAt: createFallbackRetentionDate(),
isTemporary: false,
};
}
}
} else if (isTemporary === true) {
update.isTemporary = true;
try {
update.expiredAt = createTempChatExpirationDate(interfaceConfig);
} catch (err) {
logger.error('Error creating temporary chat expiration date:', err);
logger.info(`---\`saveConvo\` context: ${metadata?.context}`);
update.expiredAt = createFallbackRetentionDate();
}
} else if (isTemporary === false) {
update.isTemporary = false;
update.expiredAt = null;
}
const createdAtOnInsert =
metadata?.createdAtOnInsert instanceof Date &&
!Number.isNaN(metadata.createdAtOnInsert.getTime())
? metadata.createdAtOnInsert
: undefined;
/**
* Metadata-only edits (pinning) must not read as activity: the sidebar orders
* chats by `updatedAt`, so bumping it would hoist an untouched chat to Today.
*/
const preserveUpdatedAt = metadata?.preserveUpdatedAt === true;
const updatesArchiveState = typeof update.isArchived === 'boolean';
if (!preserveUpdatedAt && (createdAtOnInsert || updatesArchiveState)) {
update.updatedAt = new Date();
}
const timestampOptions: { timestamps?: false } = {};
if (updatesArchiveState || createdAtOnInsert || preserveUpdatedAt) {
timestampOptions.timestamps = false;
}
const canUpsert = metadata?.noUpsert !== true && metadata?.titleSource !== 'generated';
const initialAgentId =
canUpsert &&
typeof metadata?.initialAgentId === 'string' &&
metadata.initialAgentId.trim() !== ''
? metadata.initialAgentId
: null;
const buildOperation = (setFields: Record<string, unknown>) => {
const operation: Record<string, unknown> = { $set: setFields };
if (metadata?.titleSource === 'manual') {
operation.$inc = { titleRevision: 1 };
}
if (appendMessageIds != null && appendMessageIds.length > 0) {
operation.$addToSet = { messages: { $each: appendMessageIds } };
}
/* Two responses can persist concurrently, and the older one can reach the write last.
* `$max` keeps whichever stamp is later without a pipeline update, which the
* DocumentDB targets rule out. */
if (setFields.lastResponseAt instanceof Date) {
const { lastResponseAt, ...withoutReplyStamp } = setFields;
operation.$set = {
...withoutReplyStamp,
isMarkedUnread: false,
lastSeenAt: new Date(UNSEEN_REPLY_WATERMARK),
};
operation.$max = { lastResponseAt };
operation.$unset = { lastResponseIsManual: '' };
}
if (Object.keys(unsetFields).length > 0) {
operation.$unset = {
...(operation.$unset as Record<string, unknown> | undefined),
...unsetFields,
};
}
const createdAtForInsert = updatesArchiveState
? (createdAtOnInsert ??
(!preserveUpdatedAt && update.updatedAt instanceof Date ? update.updatedAt : undefined))
: createdAtOnInsert;
operation.$setOnInsert = {
initial_agent_id: initialAgentId,
...decisionOnInsert,
...retentionOnInsert,
...(chatProjectIdOnInsert ? { chatProjectId: chatProjectIdOnInsert } : {}),
...(createdAtForInsert ? { createdAt: createdAtForInsert } : {}),
};
return operation;
};
const baseFilter = {
conversationId,
user: userId,
...(metadata?.titleSource === 'generated' && {
titleSetByUser: { $ne: true },
title: { $in: [null, '', 'New Chat'] },
}),
};
const runUpdate = (
filter: Record<string, unknown>,
operation: Record<string, unknown>,
upsert: boolean,
) =>
Conversation.findOneAndUpdate(filter, operation, {
new: true,
upsert,
includeResultMetadata: true,
...timestampOptions,
}) as unknown as Promise<ConversationUpdateResult>;
let conversationResult: ConversationUpdateResult;
if (update.isArchived === true) {
/** DocumentDB documents no support for pipeline-form updates on any engine
* version (`misc/documentdb/documentdb-compat.md`), so the stamp is applied
* by compare-and-set instead of `$cond`. Matching on the flag is what keeps
* it atomic: only the write that finds the chat unarchived stamps it, so a
* duplicate or retried archive cannot move `archivedAt`, and an unarchive
* that lands first is re-stamped rather than left bare. */
const withoutStamp = { ...update };
delete withoutStamp.archivedAt;
const stamped = { ...withoutStamp, archivedAt: update.archivedAt ?? new Date() };
const runArchiveWrites = async () => {
const transitioned = await runUpdate(
{ ...baseFilter, isArchived: { $ne: true } },
buildOperation(stamped),
false,
);
if (transitioned.value) {
return transitioned;
}
return runUpdate(
{ ...baseFilter, isArchived: true },
buildOperation(withoutStamp),
false,
);
};
conversationResult = await runArchiveWrites();
/** Both conditional writes miss when the flag flips between them: the chat was
* already archived when the first ran and unarchived again before the second.
* That is a live conversation, so confirm it is really gone before letting the
* route answer 404, and retry the pair when it is not. */
for (let attempt = 0; !conversationResult.value && attempt < 2; attempt++) {
if (!(await Conversation.exists(baseFilter))) {
break;
}
conversationResult = await runArchiveWrites();
}
if (!conversationResult.value && canUpsert) {
conversationResult = await runUpdate(baseFilter, buildOperation(stamped), true);
}
if (!conversationResult.value) {
/** Alternating archive and unarchive requests can split every attempt, so
* exhausting the retries still proves nothing about whether the chat exists.
* Answer with its actual current state rather than reporting it missing. */
const current = await Conversation.findOne(baseFilter);
if (current) {
conversationResult = {
value: current as unknown as ConversationUpdateResult['value'],
lastErrorObject: { updatedExisting: true },
};
}
}
} else {
conversationResult = await runUpdate(
baseFilter,
buildOperation(updatesArchiveState ? { ...update, archivedAt: null } : update),
canUpsert,
);
}
const conversation = conversationResult.value;
if (!conversation) {
logger.debug('[saveConvo] Conversation not found, skipping update');
return null;
}
/** `$setOnInsert` only reaches a chat this save creates, yet a chat whose earlier turns never
* involved a code-capable agent holds no decision either: without this fill its first
* workspace choice is dropped and the next turn starts undecided again. The filter repeats
* that absence, so a concurrent writer that decided first keeps its decision and a chat that
* already holds one is never touched. Only a whole decision seeds a row, never bare
* selections. */
if (
decisionOnInsert.codeEnvironmentMode != null &&
conversation.codeEnvironmentMode == null &&
(conversation.codeWorkspaces?.length ?? 0) === 0
) {
const seeded = await Conversation.updateOne(
{
_id: conversation._id,
codeEnvironmentMode: { $in: [null] },
$or: [{ codeWorkspaces: { $in: [null] } }, { codeWorkspaces: { $size: 0 } }],
},
{ $set: decisionOnInsert },
{ timestamps: false },
);
if (seeded.modifiedCount > 0) {
Object.assign(conversation, decisionOnInsert);
}
}
/** Reuse the saved row's chat type when callers omit it, preserving existing deadlines. */
if (
interfaceConfig?.retentionMode === RetentionMode.ALL &&
interfaceConfig.generalChatRetention !== undefined &&
typeof isTemporary !== 'boolean' &&
conversation.expiredAt == null
) {
const deadline = createChatExpirationDate(
interfaceConfig,
conversation.isTemporary === true,
);
const result = await Conversation.updateOne(
{
_id: conversation._id,
expiredAt: null,
isTemporary: conversation.isTemporary === true ? true : { $ne: true },
},
{ $set: { expiredAt: deadline } },
{ timestamps: false },
);
if (result.modifiedCount > 0) {
conversation.expiredAt = deadline;
}
}
/* Advance the version and reset catch-up atomically. The database CAS orders
* concurrent replies even when their application hosts disagree about wall-clock time. */
let replyStampApplied = false;
if (metadata?.stampReply === true) {
const responseMessageId = metadata.replyMessageId;
if (typeof responseMessageId === 'string' && responseMessageId.length > 0) {
try {
const stamped = await stampReplyWithCas(
Conversation,
{ _id: conversation._id },
responseMessageId,
{
lastResponseAt: 1,
lastResponseMessageId: 1,
lastResponseIsManual: 1,
isMarkedUnread: 1,
lastSeenAt: 1,
updatedAt: 1,
},
);
if (stamped) {
/* The caller hands this document to the client as the turn's conversation, and the
* seen acknowledgement is bound to the stamp it carries. */
replyStampApplied = true;
conversation.lastResponseAt = stamped.stamp;
conversation.lastResponseMessageId = stamped.conversation.lastResponseMessageId;
conversation.lastResponseIsManual = stamped.conversation.lastResponseIsManual;
conversation.isMarkedUnread = stamped.conversation.isMarkedUnread;
conversation.lastSeenAt = stamped.conversation.lastSeenAt;
if (stamped.conversation.updatedAt) {
conversation.updatedAt = stamped.conversation.updatedAt;
}
}
} catch (error) {
logger.error('[saveConvo] Failed to stamp persisted reply', error);
}
}
}
if (
interfaceConfig?.retentionMode === RetentionMode.ALL &&
typeof isTemporary !== 'boolean' &&
(conversation.isTemporary == null ||
(conversation.isTemporary === false && conversation.$isDefault('isTemporary')))
) {
/* This backfill runs after the main write, so it needs the same timestamp
suppression: otherwise the first pin or archive of a legacy chat under
`RetentionMode.ALL` bumps `updatedAt` here and lands in Today anyway.
A reply stamp is the same case for a different reason: the CAS above set `updatedAt`
to the stamp deliberately, and an away tab that has never cached this conversation
reads the two disagreeing as a metadata-only promotion, withholding the reply's
chime and desktop notification. */
await Conversation.updateOne(
{ _id: conversation._id, isTemporary: { $ne: false } },
{ $set: { isTemporary: false } },
preserveUpdatedAt || replyStampApplied ? { timestamps: false } : {},
);
conversation.isTemporary = false;
}
/* The conversation and its reply stamp are durable by now, and the caller hands this
document to the client as the turn's conversation. Project statistics are maintenance
on a different collection: letting one of their failures reach the catch below would
answer a successful save with an error, dropping the stamp from the terminal event and
presenting a reply the user already watched arrive as unread on the next refresh. */
try {
if (conversation.chatProjectId) {
const isRetentionVisibilityUpdate =
typeof update.isTemporary === 'boolean' ||
Object.prototype.hasOwnProperty.call(convo, 'expiredAt') ||
Object.prototype.hasOwnProperty.call(unsetFields, 'isTemporary') ||
Object.prototype.hasOwnProperty.call(unsetFields, 'expiredAt');
/**
* Saving a conversation that is itself archived or retention-hidden (e.g.
* renaming or title generation on an archived project chat) must recompute
* stats rather than take the incremental fast path, otherwise the project's
* lastConversationAt/Id would point at a chat the project workspace hides.
*/
const isConversationHidden =
conversation.isArchived === true ||
conversation.isTemporary === true ||
(conversation.expiredAt != null &&
new Date(conversation.expiredAt).getTime() <= Date.now());
const isNewConversation = conversationResult.lastErrorObject?.updatedExisting === false;
const shouldRefreshProjectStats =
isNewConversation ||
typeof update.isArchived === 'boolean' ||
Object.prototype.hasOwnProperty.call(unsetFields, 'isArchived') ||
isRetentionVisibilityUpdate ||
isConversationHidden;
if (shouldRefreshProjectStats) {
await refreshChatProjectStatsForUser(mongoose, userId, conversation.chatProjectId);
} else if (!preserveUpdatedAt) {
await updateChatProjectLastConversationForUser(
mongoose,
userId,
conversation.chatProjectId,
conversation,
);
}
}
} catch (error) {
logger.error('[saveConvo] Failed to maintain project statistics', error);
}
return conversation.toObject();
} catch (error) {
logger.error('[saveConvo] Error saving conversation', error);
if (metadata?.context) {
logger.info(`[saveConvo] ${metadata.context}`);
}
return { message: 'Error saving conversation' };
}
}
/**
* Flips the pinned flag on its own rather than routing through `saveConvo`.
*
* Pinning is pure metadata: it moves no chat between projects, changes nothing the
* project workspace hides, and opens no retention window, so none of `saveConvo`'s
* tail work applies. Going direct drops the `getMessages` round trip and the rewrite
* of the whole message-id array that a one-field toggle would otherwise pay for, and
* `timestamps: false` keeps the sidebar ordering by real activity.
*
* Returns null when no conversation matched, so a pin can never insert one.
*/
async function setConvoPinned(user: string, conversationId: string, pinned: boolean) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return await Conversation.findOneAndUpdate(
{ conversationId, user },
{ $set: { pinned } },
{ new: true, timestamps: false },
).lean<IConversation>();
} catch (error) {
logger.error('[setConvoPinned] Error updating pinned state', error);
throw new Error('Error updating pinned state');
}
}
/**
* Adds one message's id to a conversation's message list, and nothing else.
*
* A message write that failed, or that resolved falsy on a duplicate key it could not
* re-read, leaves its row out of `messages`, and the bare `saveMessage` retries that
* restore the row never add it. Going direct keeps the repair to what it is: no
* `getMessages` round trip, no rewrite of the whole array, and no `$set` of fields the
* caller never meant to touch. `timestamps: false` because repairing a reference is not
* activity and must not reorder the sidebar.
*
* Takes the id as a string so callers stay free of the storage engine's own id type; the
* cast to it happens here. Returns null when no conversation matched, so a repair can
* never insert one.
*/
async function appendConvoMessageReference(
user: string,
conversationId: string,
messageId: string,
) {
if (!isValidObjectIdString(messageId)) {
logger.warn('[appendConvoMessageReference] Ignoring an unusable message id');
return null;
}
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return await Conversation.findOneAndUpdate(
{ conversationId, user },
{ $addToSet: { messages: new mongoose.Types.ObjectId(messageId) } },
{ new: true, timestamps: false },
).lean<IConversation>();
} catch (error) {
logger.error('[appendConvoMessageReference] Error appending the message reference', error);
throw new Error('Error appending the message reference');
}
}
/** Internal snapshot for a transition. The revision is never exposed in ordinary chat reads. */
async function getConvoCodeEnvironmentDecision(user: string, conversationId: string) {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return Conversation.findOne({ user, conversationId })
.select('conversationId codeEnvironmentMode codeWorkspaces +codeEnvironmentRevision')
.lean<IConversation>();
}
/**
* Call only AFTER publishing the generation's active job. Atomically advance the fence and
* return the post-update decision in one round trip. A run that wins invalidates an in-flight
* transition's revision; a transition that wins is observed by this read.
*/
/**
* Remember tools the owner approved for the rest of one conversation. Owner-scoped,
* idempotent (`$addToSet`), and bounded: the write matches only while the stored list
* plus the names it does not hold yet fits `max`, so concurrent resumes cannot grow it
* past the cap and a name already stored costs no room. Returns whether it applied.
*/
async function addConvoToolApprovalAllows({
user,
conversationId,
toolNames,
max,
}: {
user: string;
conversationId: string;
toolNames: string[];
max: number;
}): Promise<boolean> {
const names = [...new Set(toolNames.filter((name) => typeof name === 'string' && name))];
if (names.length === 0 || names.length > max) {
return false;
}
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const result = await withoutMeiliIndexing(
Conversation.updateOne(
{
user,
conversationId,
$expr: {
$lte: [
{ $size: { $setUnion: [{ $ifNull: ['$toolApprovalAllows', []] }, names] } },
max,
],
},
},
{ $addToSet: { toolApprovalAllows: { $each: names } } },
{ timestamps: false },
),
);
return result.matchedCount === 1;
}
/**
* Reserve the next lane report sequence number for an owner's conversation. The counter lives in
* the database, so every replica draws from one order that no process clock can skew, and the
* number is taken when a command settles, before its write is attempted. Resolves to null when
* the conversation does not exist yet for this owner.
*/
async function reserveConvoLaneGitSeq(
user: string,
conversationId: string,
): Promise<number | null> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const reserved = await withoutMeiliIndexing(
Conversation.findOneAndUpdate(
{ user, conversationId, ...activeExpirationFilter<IConversation>() },
{ $inc: { laneGitSeq: 1 } },
{ new: true, timestamps: false },
),
)
.select('laneGitSeq')
.lean<Pick<IConversation, 'laneGitSeq'> | null>();
return reserved?.laneGitSeq ?? null;
}
/**
* The route and attachment epoch a lane recorder needs, in one owner-scoped read. A subagent
* thread's route names the visible conversation its lane belongs to. The epoch advances only
* when the owner moves or detaches the workspace (never when a generation is admitted), so a
* report captured before a move away and back to the same workspace still reads as stale.
* Resolves to null for a conversation that does not exist yet, or is not this owner's.
*/
async function getConvoLaneContext(
user: string,
conversationId: string,
): Promise<ConvoLaneContext | null> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const now = new Date();
/**
* The thread and its visible root in one operation, so the epoch cannot move between two
* reads. The tenant plugin scopes only the base collection of an aggregate, never the joined
* one, so the join is narrowed here to the same owner, tenant and visibility as the base row:
* a root outside them reads as absent, exactly as it did when it was read on its own.
*/
const [row] = await Conversation.aggregate<{
subagentThread?: IConversation['subagentThread'] | null;
codeAttachmentEpoch?: number;
_root?: Array<{ codeAttachmentEpoch?: number }>;
}>([
{ $match: { user, conversationId, ...activeExpirationFilter<IConversation>() } },
{
$lookup: {
from: 'conversations',
localField: 'subagentThread.rootConversationId',
foreignField: 'conversationId',
as: '_root',
},
},
{
$project: {
subagentThread: 1,
codeAttachmentEpoch: 1,
_root: {
$filter: {
input: '$_root',
as: 'r',
cond: {
$and: [
{ $eq: ['$$r.user', user] },
{ $eq: [{ $ifNull: ['$$r.tenantId', null] }, { $ifNull: ['$tenantId', null] }] },
{
$or: [
{ $eq: [{ $ifNull: ['$$r.expiredAt', null] }, null] },
{ $gt: ['$$r.expiredAt', now] },
],
},
],
},
},
},
},
},
{ $limit: 1 },
]);
if (row == null) return null;
const rootId = row.subagentThread?.rootConversationId;
/** A thread's report is written to its visible root, so it is fenced by the root's epoch. */
const fenced = rootId && rootId !== conversationId ? row._root?.[0] : row;
return {
subagentThread: row.subagentThread ?? null,
codeAttachmentEpoch: fenced?.codeAttachmentEpoch ?? 0,
};
}
/**
* Record the branch and head a conversation's code lane last reported. Owner-scoped and fenced
* by the sequence number reserved when the command settled: the write matches only while the
* stored report carries a lower one, so a delayed older report, from this process or another
* replica, can never replace a newer state. When the caller names the workspace the command ran
* in, the write also matches only while the conversation is still attached to it, so a report
* queued before a move or detach cannot bring the old workspace's lane back. A conversation
* with no stored workspace (an agent default) accepts the report unless the caller requires a
* recorded one. Server-written only: generic saves and imports cannot set it. An expired
* temporary chat is treated as gone, here and in the reservation and the read, the way every
* other owner-scoped conversation access treats it. Resolves to whether the write applied; false
* means a newer report is already stored, the workspace no longer matches, or there is no such
* conversation for this owner.
*/
async function setConvoLaneGit({
user,
conversationId,
laneGit,
repo,
pullRequest,
seq,
workspace,
}: {
user: string;
conversationId: string;
laneGit: Pick<NonNullable<IConversation['laneGit']>, 'branch' | 'head'>;
repo?: string;
pullRequest?: number;
seq: number;
workspace?: { environmentId: string; workspaceId: string; required?: boolean; epoch?: number };
}): Promise<boolean> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const epochFence =
workspace?.epoch == null
? []
: [
{
codeAttachmentEpoch: workspace.epoch === 0 ? { $in: [null, 0] } : workspace.epoch,
},
];
const workspaceFence =
workspace == null
? []
: [
...epochFence,
{
$or: [
{
codeWorkspaces: {
$elemMatch: {
environmentId: workspace.environmentId,
workspaceId: workspace.workspaceId,
},
},
},
...(workspace.required === true
? []
: [
{
codeEnvironmentMode: { $ne: 'without_attached' },
$or: [
{ codeWorkspaces: { $exists: false } },
{ codeWorkspaces: null },
{ codeWorkspaces: { $size: 0 } },
],
},
]),
],
},
];
const fences: FilterQuery<IConversation>[] = [
{
$or: [
{ 'laneGit.seq': { $exists: false } },
{ 'laneGit.seq': null },
{ 'laneGit.seq': { $lt: seq } },
],
},
...workspaceFence,
];
const write = async (
lane: FilterQuery<IConversation> | null,
update: UpdateQuery<IConversation>,
): Promise<boolean> => {
const result = await withoutMeiliIndexing(
Conversation.updateOne(
{
user,
conversationId,
...activeExpirationFilter<IConversation>(),
$and: lane == null ? fences : [...fences, lane],
},
update,
{ timestamps: false },
),
);
return result.modifiedCount === 1;
};
const replaced = {
branch: laneGit.branch,
head: laneGit.head,
...(repo ? { repo } : {}),
...(pullRequest != null ? { pullRequest } : {}),
seq,
};
if (pullRequest != null) return write(null, { $set: { laneGit: replaced } });
/**
* A report without a link keeps the one already recorded while the lane is still on that
* branch and repository, and drops it otherwise. Plain updates rather than an aggregation
* pipeline, which Amazon DocumentDB rejects: the first matches only the same lane and sets its
* fields one by one, the second only another lane and replaces the whole state. A concurrent
* write can move the stored lane between the two, so they are retried once.
*/
const sameLane = { 'laneGit.branch': laneGit.branch, 'laneGit.repo': repo || null };
for (let attempt = 0; attempt < 2; attempt++) {
const kept = await write(sameLane, {
$set: {
'laneGit.branch': laneGit.branch,
'laneGit.head': laneGit.head,
'laneGit.seq': seq,
},
});
if (kept) return true;
if (await write({ $nor: [sameLane] }, { $set: { laneGit: replaced } })) return true;
}
return false;
}
/** The last reported lane state, or null when the conversation has none or is not the owner's. */
async function getConvoLaneGit(
user: string,
conversationId: string,
): Promise<Omit<NonNullable<IConversation['laneGit']>, 'seq'> | null> {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const stored = await Conversation.findOne({
user,
conversationId,
...activeExpirationFilter<IConversation>(),
})
.select('laneGit')
.lean<Pick<IConversation, 'laneGit'> | null>();
if (stored?.laneGit == null) return null;
const { branch, head, repo, pullRequest } = stored.laneGit;
return {
branch,
head,
...(repo ? { repo } : {}),
...(pullRequest != null ? { pullRequest } : {}),
};
}
/**
* The last reported lane state of each of the owner's conversations that has one, in one query.
* A conversation that is missing, expired, another owner's or has no lane is simply absent, so a
* caller cannot tell them apart.
*/
async function getConvosLaneGit(
user: string,
conversationIds: string[],
): Promise<Array<{ conversationId: string; laneGit: ConvoLaneGitView }>> {
if (conversationIds.length === 0) return [];
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const stored = await Conversation.find({
user,
conversationId: { $in: conversationIds },
laneGit: { $exists: true, $ne: null },
...activeExpirationFilter<IConversation>(),
})
.select('conversationId laneGit')
.lean<Array<Pick<IConversation, 'conversationId' | 'laneGit'>>>();
return stored.flatMap(({ conversationId, laneGit }) => {
if (laneGit == null || conversationId == null) return [];
const { branch, head, repo, pullRequest } = laneGit;
return [
{
conversationId,
laneGit: {
branch,
head,
...(repo ? { repo } : {}),
...(pullRequest != null ? { pullRequest } : {}),
},
},
];
});
}
/**
* The decision a run is admitted on, with the attachment epoch of that same document. The epoch
* is `0` for a conversation never moved, so a lane report can be fenced by exactly the snapshot
* the workspace came from instead of a second read that a move could slip between.
*/
async function readAdmittedConvoCodeEnvironmentDecision(user: string, conversationId: string) {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const admitted = await withoutMeiliIndexing(
Conversation.findOneAndUpdate(
{ user, conversationId },
{ $inc: { codeEnvironmentRevision: 1 } },
{ new: true, timestamps: false },
),
)
.select('conversationId codeEnvironmentMode codeWorkspaces +codeAttachmentEpoch')
.lean<IConversation>();
return admitted == null
? admitted
: { ...admitted, codeAttachmentEpoch: admitted.codeAttachmentEpoch ?? 0 };
}
/**
* Compare-and-swap for an owner's explicit replacement of a code-environment decision, whether
* that attaches an environment, moves to another, or leaves attached execution behind.
* The filter repeats the stored decision being replaced, so a writer that changed it first
* leaves this update unmatched rather than overwritten. A missing and a null mode both
* describe a legacy decision inferred from its selections. Leaving attached execution clears
* the selections outright: a decision that kept them would read as attached again.
*/
async function replaceConvoCodeEnvironmentDecision({
user,
conversationId,
expected,
codeEnvironmentMode,
codeWorkspaces,
}: {
user: string;
conversationId: string;
expected: Pick<
IConversation,
'codeEnvironmentMode' | 'codeWorkspaces' | 'codeEnvironmentRevision'
>;
} & (
| {
codeEnvironmentMode: 'attached';
codeWorkspaces: NonNullable<IConversation['codeWorkspaces']>;
}
| { codeEnvironmentMode: 'without_attached'; codeWorkspaces?: undefined }
)) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return await Conversation.findOneAndUpdate(
{
conversationId,
user,
codeEnvironmentMode: expected.codeEnvironmentMode ?? { $in: [null] },
codeWorkspaces: expected.codeWorkspaces ?? { $in: [null] },
codeEnvironmentRevision: expected.codeEnvironmentRevision ?? { $in: [null] },
},
/** The reported lane belongs to the workspace being replaced, so it goes with it. */
codeEnvironmentMode === 'attached'
? {
$set: { codeEnvironmentMode, codeWorkspaces },
$unset: { laneGit: 1 },
$inc: { codeEnvironmentRevision: 1, codeAttachmentEpoch: 1 },
}
: {
$set: { codeEnvironmentMode },
$unset: { codeWorkspaces: 1, laneGit: 1 },
$inc: { codeEnvironmentRevision: 1, codeAttachmentEpoch: 1 },
},
{ new: true, timestamps: false },
).lean<IConversation>();
} catch (error) {
logger.error('[replaceConvoCodeEnvironmentDecision] Error moving code environment', error);
throw new Error('Error moving code environment');
}
}
/**
* Saves multiple conversations in bulk.
*/
async function bulkSaveConvos(conversations: Array<Record<string, unknown>>) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const ChatProject = mongoose.models.ChatProject as Model<IChatProjectDocument>;
/**
* Validate project ownership before persisting (mirrors saveConvo). Bulk
* paths like import/duplicate/fork can carry a chatProjectId that does not
* belong to the user; persisting it would create an orphan assignment that
* is hidden from both the project and the unassigned filter.
*/
const candidatePairs = new Map<string, { user: string; projectId: string }>();
for (const convo of conversations) {
if (
typeof convo.user === 'string' &&
typeof convo.chatProjectId === 'string' &&
isValidObjectIdString(convo.chatProjectId)
) {
candidatePairs.set(`${convo.user}:${convo.chatProjectId}`, {
user: convo.user,
projectId: convo.chatProjectId,
});
}
}
const ownedProjects = new Set<string>();
if (candidatePairs.size > 0) {
const owned = await ChatProject.find({
$or: [...candidatePairs.values()].map(({ user, projectId }) => ({
_id: new mongoose.Types.ObjectId(projectId),
user,
})),
})
.select('_id user')
.lean<Array<{ _id: { toString: () => string }; user: string }>>();
for (const project of owned) {
ownedProjects.add(`${project.user}:${project._id.toString()}`);
}
}
/**
* Capture each conversation's existing project so a bulk move (import that
* overwrites an existing (user, conversationId), duplicate/fork) also refreshes
* the project it leaves, not just the one it joins. One batched read keeps this
* O(1) in round-trips regardless of batch size.
*/
const previousProjectByConversation = new Map<string, string>();
const conversationPairs = conversations
.filter((c) => typeof c.user === 'string' && typeof c.conversationId === 'string')
.map((c) => ({ user: c.user as string, conversationId: c.conversationId as string }));
if (conversationPairs.length > 0) {
const existing = await Conversation.find(
{ $or: conversationPairs },
'user conversationId chatProjectId',
).lean<Array<{ user: string; conversationId: string; chatProjectId?: string | null }>>();
for (const doc of existing) {
if (doc.chatProjectId) {
previousProjectByConversation.set(
`${doc.user}:${doc.conversationId}`,
doc.chatProjectId,
);
}
}
}
const affectedProjectStats = new Map<string, { user: string; projectId: string }>();
const bulkOps = conversations.map((convo) => {
const { codeEnvironmentMode, codeWorkspaces, ...sanitized } = convo;
/* Read state belongs to the reader who lived through the replies, so an import never
carries one in: the rows arrive unseen-free and unread-free. */
delete sanitized.lastResponseAt;
delete sanitized.lastResponseMessageId;
delete sanitized.lastResponseIsManual;
delete sanitized.isMarkedUnread;
delete sanitized.lastSeenAt;
delete sanitized.codeApprovalMode;
delete sanitized.initial_agent_id;
delete sanitized.toolApprovalAllows;
stripFields(sanitized, LANE_PRIVATE_FIELDS);
delete sanitized.codeEnvironmentRevision;
stripActorCheckpointFields(sanitized);
if (typeof sanitized.user === 'string' && typeof sanitized.chatProjectId === 'string') {
if (ownedProjects.has(`${sanitized.user}:${sanitized.chatProjectId}`)) {
affectedProjectStats.set(`${sanitized.user}:${sanitized.chatProjectId}`, {
user: sanitized.user,
projectId: sanitized.chatProjectId,
});
} else {
sanitized.chatProjectId = null;
}
}
if (typeof sanitized.user === 'string' && typeof sanitized.conversationId === 'string') {
const previousProjectId = previousProjectByConversation.get(
`${sanitized.user}:${sanitized.conversationId}`,
);
const newProjectId =
typeof sanitized.chatProjectId === 'string' ? sanitized.chatProjectId : null;
if (previousProjectId && previousProjectId !== newProjectId) {
affectedProjectStats.set(`${sanitized.user}:${previousProjectId}`, {
user: sanitized.user,
projectId: previousProjectId,
});
}
}
return {
updateOne: {
filter: {
conversationId: sanitized.conversationId,
user: sanitized.user,
},
update: {
$set: sanitized,
$setOnInsert: {
initial_agent_id: null,
...(codeEnvironmentMode != null && { codeEnvironmentMode }),
...(codeWorkspaces != null && { codeWorkspaces }),
},
},
upsert: true,
timestamps: false,
},
};
});
const result = await tenantSafeBulkWrite(Conversation, bulkOps);
await Promise.all(
[...affectedProjectStats.values()].map(({ user, projectId }) =>
refreshChatProjectStatsForUser(mongoose, user, projectId),
),
);
return result;
} catch (error) {
logger.error('[bulkSaveConvos] Error saving conversations in bulk', error);
throw new Error('Failed to save conversations in bulk.');
}
}
/**
* Flags which conversations on a page currently have an active shared link, in one
* batched lookup instead of a query per row. The flag lives in another collection, so
* it is derived per request rather than projected; a failure here degrades the badge
* but must never fail the conversation list itself.
*/
async function attachSharedFlags(user: string, conversations: IConversation[]): Promise<void> {
const SharedLink = mongoose.models.SharedLink as Model<ISharedLink> | undefined;
if (!SharedLink || conversations.length === 0) {
return;
}
/* A deployment with shared links off serves no links and renders no badge, so the
extra round trip on the sidebar's first page would buy nothing. */
const allowSharedLinks = process.env.ALLOW_SHARED_LINKS;
if (allowSharedLinks !== undefined && allowSharedLinks.toLowerCase().trim() !== 'true') {
return;
}
try {
const shares = await SharedLink.find({
user,
conversationId: { $in: conversations.map((convo) => convo.conversationId) },
...activeExpirationFilter<ISharedLink>(),
})
.select('conversationId')
.lean();
const shared = new Set(shares.map((share) => share.conversationId));
for (const convo of conversations) {
convo.isShared = shared.has(convo.conversationId);
}
} catch (error) {
logger.error('[attachSharedFlags] Error resolving shared conversations', error);
}
}
/**
* Conversations with a file on any of this user's messages. A message holds files in
* three places: uploads on `files`, tool and assistant output on `attachments` (a stored
* file, or a download-only one the client renders by its `filepath`), and content parts
* in every shape replay reads (a steer's `files`, a provider-native `file` or
* `image_file`, or a bare `file_id`).
*/
async function getMessageFileConversationIds(user: string): Promise<string[] | null> {
const Message = mongoose.models.Message as Model<IMessage> | undefined;
if (!Message) {
return null;
}
return Message.find({
user,
$or: [
{ 'files.0': { $exists: true } },
{ 'attachments.file_id': { $type: 'string' } },
{ 'attachments.filepath': { $type: 'string', $gt: '' } },
{ 'content.files.0': { $exists: true } },
{ 'content.file.file_id': { $type: 'string' } },
{ 'content.image_file.file_id': { $type: 'string' } },
{ 'content.file_id': { $type: 'string' } },
],
}).distinct('conversationId');
}
/**
* The conversations this user is actively sharing.
*
* Shared state is not a field on the conversation: it is a live link that can expire,
* so a denormalized flag would keep saying "shared" after a link lapsed. This asks the
* links themselves, indexed by `{ user, conversationId }`, and returns `null` when the
* deployment has sharing switched off so the caller can tell "no links" from "not
* applicable".
*/
async function getSharedConversationIds(user: string): Promise<string[] | null> {
const SharedLink = mongoose.models.SharedLink as Model<ISharedLink> | undefined;
if (!SharedLink) {
return null;
}
const allowSharedLinks = process.env.ALLOW_SHARED_LINKS;
if (allowSharedLinks !== undefined && allowSharedLinks.toLowerCase().trim() !== 'true') {
return null;
}
/* Distinct, not find: the only thing this caller can use is the set of IDs, so the
server dedupes and returns nothing else. Covered by `{ user, conversationId }`. */
const sharedIds = await SharedLink.find({
user,
...activeExpirationFilter<ISharedLink>(),
}).distinct('conversationId');
return sharedIds.filter(
(conversationId): conversationId is string => typeof conversationId === 'string',
);
}
/**
* Retrieves conversations using cursor-based pagination.
*/
async function getConvosByCursor(
user: string,
{
cursor,
limit = DEFAULT_CONVO_PAGE_SIZE,
isArchived = false,
pinned = false,
tags,
search,
sortBy = 'updatedAt',
sortDirection = 'desc',
projectId,
updatedAfter,
createdAfter,
endpoints,
hasFiles,
sharedOnly,
}: {
cursor?: string | null;
limit?: number;
isArchived?: boolean;
pinned?: boolean;
tags?: string[];
search?: string;
sortBy?: string;
sortDirection?: string;
projectId?: string;
updatedAfter?: Date;
createdAfter?: Date;
endpoints?: string[];
hasFiles?: boolean;
sharedOnly?: boolean;
} = {},
) {
const Conversation = mongoose.models.Conversation as Model<IConversation> &
Pick<SchemaWithMeiliMethods, 'meiliSearch'>;
/* `.limit(0)` is "no limit" to MongoDB and a negative one caps to a single batch, so an
unclamped page size hands the caller the whole collection rather than a page of it. */
const pageSize = Number.isFinite(limit)
? Math.min(Math.max(Math.trunc(limit), 1), MAX_CONVO_PAGE_SIZE)
: DEFAULT_CONVO_PAGE_SIZE;
const filters: FilterQuery<IConversation>[] = [{ user } as FilterQuery<IConversation>];
if (isArchived) {
filters.push({ isArchived: true } as FilterQuery<IConversation>);
} else {
filters.push({
$or: [{ isArchived: false }, { isArchived: { $exists: false } }],
} as FilterQuery<IConversation>);
}
if (pinned) {
filters.push({ pinned: true } as FilterQuery<IConversation>);
}
if (Array.isArray(tags) && tags.length > 0) {
filters.push({ tags: { $in: tags } } as FilterQuery<IConversation>);
}
if (projectId === 'unassigned') {
filters.push({
$or: [{ chatProjectId: null }, { chatProjectId: { $exists: false } }],
} as FilterQuery<IConversation>);
} else if (projectId) {
filters.push({ chatProjectId: projectId } as FilterQuery<IConversation>);
}
/* Ranges are half-open on purpose: the caller sends the start of the window it
means, and "since midnight" must not depend on how the clock rounds. */
if (updatedAfter instanceof Date && !Number.isNaN(updatedAfter.getTime())) {
filters.push({ updatedAt: { $gte: updatedAfter } } as FilterQuery<IConversation>);
}
if (createdAfter instanceof Date && !Number.isNaN(createdAfter.getTime())) {
filters.push({ createdAt: { $gte: createdAfter } } as FilterQuery<IConversation>);
}
if (Array.isArray(endpoints) && endpoints.length > 0) {
filters.push({ endpoint: { $in: endpoints } } as FilterQuery<IConversation>);
}
/* The two facet lookups are independent user-scoped reads, so they start together
instead of adding their latencies on every page that combines them. */
const [messageFileIds, activeShares] = await Promise.all([
hasFiles === true ? getMessageFileConversationIds(user) : null,
sharedOnly === true ? getSharedConversationIds(user) : null,
]);
/* Attachments are not one field: the standard flow rides them on messages, imports
can land them on the conversation, and `files` is absent or `[]` when empty. The
conversation-side predicate alone would miss every ordinary chat with an upload,
so the message-side conversation IDs are OR-matched in. */
if (hasFiles === true) {
const orClauses: FilterQuery<IConversation>[] = [
{ files: { $exists: true, $not: { $size: 0 } } } as FilterQuery<IConversation>,
];
if (messageFileIds != null && messageFileIds.length > 0) {
orClauses.push({ conversationId: { $in: messageFileIds } } as FilterQuery<IConversation>);
}
filters.push({ $or: orClauses } as FilterQuery<IConversation>);
}
/* When this filter runs, the page's rows are already known to be shared, so the set
is kept and used to mark `isShared` directly instead of issuing a second
SharedLink query after the conversation query for the same answers. */
let sharedIds: Set<string> | null = null;
if (sharedOnly === true) {
/* Nothing shared, or sharing switched off, means nothing can match. Returning early
also keeps an empty `$in` out of the query, which would match every document. */
if (activeShares == null || activeShares.length === 0) {
return { conversations: [], nextCursor: null };
}
sharedIds = new Set(activeShares);
filters.push({ conversationId: { $in: activeShares } } as FilterQuery<IConversation>);
}
filters.push(getVisibleConversationRetentionFilter());
filters.push(getHumanConversationFilter());
if (search) {
try {
const searchParams: SearchParams = {
filter: `user = "${escapeMeiliFilterValue(user)}"`,
limit: MEILI_SEARCH_LIMIT,
attributesToRetrieve: ['conversationId', 'originalConversationId'],
};
const [convoResults, messageHits] = await Promise.all([
Conversation.meiliSearch(search, searchParams),
deps?.searchMessages
? deps.searchMessages(search, searchParams).then(
(results) => (Array.isArray(results.hits) ? results.hits : []),
(error) => {
logger.error(
'[getConvosByCursor] Message search failed, using title matches only',
error,
);
return [];
},
)
: [],
]);
const matchingIds = new Set<string>();
for (const hit of convoResults.hits ?? []) {
if (typeof hit.conversationId === 'string') {
matchingIds.add(hit.conversationId);
}
}
for (const hit of messageHits) {
if (typeof hit.conversationId === 'string') {
matchingIds.add(hit.conversationId);
}
}
if (!matchingIds.size) {
return { conversations: [], nextCursor: null };
}
filters.push({
conversationId: { $in: [...matchingIds] },
} as FilterQuery<IConversation>);
} catch (error) {
logger.error('[getConvosByCursor] Error during meiliSearch', error);
throw new Error('Error during meiliSearch');
}
}
const validSortFields = ['title', 'createdAt', 'updatedAt', 'archivedAt'];
if (!validSortFields.includes(sortBy)) {
throw new Error(
`Invalid sortBy field: ${sortBy}. Must be one of ${validSortFields.join(', ')}`,
);
}
const finalSortBy = sortBy;
const finalSortDirection = sortDirection === 'asc' ? 'asc' : 'desc';
/* `title` and `archivedAt` are both absent on plenty of rows, and BSON orders a
missing field before every string and every date alike. The paging clauses below
therefore treat them the same way; `createdAt`/`updatedAt` are always present. */
const sortFieldIsNullable = finalSortBy === 'title' || finalSortBy === 'archivedAt';
/* The archive view renders `archivedAt ?? createdAt`, so the legacy group, which
shares a missing `archivedAt`, has to be ordered by the same `createdAt` the cell
shows rather than by last activity, or its dates read out of order. */
const secondaryField = finalSortBy === 'archivedAt' ? 'createdAt' : 'updatedAt';
let cursorFilter: FilterQuery<IConversation> | null = null;
if (cursor) {
try {
const decoded = JSON.parse(Buffer.from(cursor, 'base64').toString());
const { primary, secondary, id } = decoded;
const secondaryValue = new Date(secondary);
const descending = finalSortDirection !== 'asc';
const op = descending ? '$lt' : '$gt';
const sortsBySecondary = finalSortBy === secondaryField;
const boundaryId =
typeof id === 'string' && isValidObjectIdString(id)
? { [op]: new mongoose.Types.ObjectId(id) }
: null;
/* One clause per sort level, so the page boundary is exact. Titles and
timestamps both repeat; `_id` is the only field guaranteed to break the
tie, and without that last clause every row sharing the boundary's
(sort field, updatedAt) pair is skipped instead of returned. */
const clauses: FilterQuery<IConversation>[] = [];
/* A title or an archive stamp can be absent, and BSON orders a missing field
before every string and date while `$lt`/`$gt` never cross that type
boundary. Those rows therefore need clauses of their own: their own tail
when the boundary is one of them, and the whole group when a descending
page runs past the last non-null value. */
if (primary == null) {
clauses.push({ [finalSortBy]: null, [secondaryField]: { [op]: secondaryValue } });
if (boundaryId) {
clauses.push({
[finalSortBy]: null,
[secondaryField]: secondaryValue,
_id: boundaryId,
});
}
if (!descending) {
clauses.push({ [finalSortBy]: { $ne: null } });
}
} else {
const primaryValue = finalSortBy === 'title' ? primary : new Date(primary);
clauses.push({ [finalSortBy]: { [op]: primaryValue } });
if (!sortsBySecondary) {
clauses.push({
[finalSortBy]: primaryValue,
[secondaryField]: { [op]: secondaryValue },
});
}
if (boundaryId) {
clauses.push({
[finalSortBy]: primaryValue,
...(sortsBySecondary ? {} : { [secondaryField]: secondaryValue }),
_id: boundaryId,
});
}
if (descending && sortFieldIsNullable) {
clauses.push({ [finalSortBy]: null });
}
}
cursorFilter = { $or: clauses } as FilterQuery<IConversation>;
} catch {
logger.warn('[getConvosByCursor] Invalid cursor format, starting from beginning');
}
if (cursorFilter) {
filters.push(cursorFilter);
}
}
const query: FilterQuery<IConversation> =
filters.length === 1 ? filters[0] : ({ $and: filters } as FilterQuery<IConversation>);
try {
const sortOrder: SortOrder = finalSortDirection === 'asc' ? 1 : -1;
const sortObj: Record<string, SortOrder> = { [finalSortBy]: sortOrder };
if (finalSortBy !== secondaryField) {
sortObj[secondaryField] = sortOrder;
}
sortObj._id = sortOrder;
const convos = await Conversation.find(query)
/* `isArchived` rides along so a row can offer archive or restore from its own state:
the sidebar lists archived and unarchived chats in the same session, and the
active list also carries the unarchived pins beside them. */
.select(
'conversationId endpoint title titleSetByUser titleRevision createdAt updatedAt archivedAt isArchived user model agent_id assistant_id spec iconURL chatProjectId pinned lastResponseAt lastResponseMessageId lastResponseIsManual isMarkedUnread lastSeenAt codeEnvironmentMode codeWorkspaces',
)
.sort(sortObj)
.limit(pageSize + 1)
.lean<IConversation[]>();
let nextCursor: string | null = null;
if (convos.length > pageSize) {
convos.pop();
const lastReturned = convos[convos.length - 1];
const sortValues: Record<string, string | Date | null | undefined> = {
title: lastReturned.title,
createdAt: lastReturned.createdAt,
updatedAt: lastReturned.updatedAt,
archivedAt: lastReturned.archivedAt,
};
const primaryValue = sortValues[finalSortBy];
/* A null primary is what tells the next page it is inside the missing-value
group, so an absent stamp has to survive as null rather than collapse to
the epoch, which would page from 1970 and replay the whole archive. */
let primaryStr: string | null = null;
if (finalSortBy === 'title') {
primaryStr = typeof primaryValue === 'string' ? primaryValue : null;
} else if (primaryValue != null) {
primaryStr = new Date(primaryValue).toISOString();
}
const secondaryValueOut =
secondaryField === 'createdAt' ? lastReturned.createdAt : lastReturned.updatedAt;
const secondaryStr = new Date(secondaryValueOut ?? 0).toISOString();
const composite = {
primary: primaryStr,
secondary: secondaryStr,
id: String(lastReturned._id),
};
nextCursor = Buffer.from(JSON.stringify(composite)).toString('base64');
}
/* Stamped by the replica that selected the decision, so a row from one that predates it
is told apart from an ordinary chat, which carries no decision either. */
for (const convo of convos) {
convo.codeDecisionListed = true;
}
if (sharedIds != null) {
for (const convo of convos) {
convo.isShared = sharedIds.has(convo.conversationId);
}
} else {
await attachSharedFlags(user, convos);
}
return { conversations: convos, nextCursor };
} catch (error) {
logger.error('[getConvosByCursor] Error getting conversations', error);
throw new Error('Error getting conversations');
}
}
/**
* Fetches specific conversations by ID array with pagination.
*/
async function getConvosQueried(
user: string,
convoIds: Array<{ conversationId: string }> | null,
cursor: string | null = null,
limit = 25,
) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
if (!convoIds?.length) {
return { conversations: [], nextCursor: null, convoMap: {} };
}
const conversationIds = convoIds.map((convo) => convo.conversationId);
const results = await Conversation.find({
$and: [
{ user, conversationId: { $in: conversationIds } },
getVisibleConversationRetentionFilter(),
getHumanConversationFilter(),
],
} as FilterQuery<IConversation>).lean<IConversation[]>();
results.sort(
(a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime(),
);
let filtered = results;
if (cursor && cursor !== 'start') {
const cursorDate = new Date(cursor);
filtered = results.filter((convo) => new Date(convo.updatedAt ?? 0) < cursorDate);
}
const limited = filtered.slice(0, limit + 1);
let nextCursor: string | null = null;
if (limited.length > limit) {
limited.pop();
nextCursor = (limited[limited.length - 1].updatedAt as Date).toISOString();
}
await attachSharedFlags(user, limited);
const convoMap: Record<string, unknown> = {};
limited.forEach((convo) => {
convoMap[convo.conversationId] = convo;
});
return { conversations: limited, nextCursor, convoMap };
} catch (error) {
logger.error('[getConvosQueried] Error getting conversations', error);
throw new Error('Error fetching conversations');
}
}
/**
* Gets conversation title, returning 'New Chat' as default.
*/
async function getConvoTitle(user: string, conversationId: string) {
try {
const convo = await getConvo(user, conversationId);
if (convo && !convo.title) {
return null;
} else {
return convo?.title || 'New Chat';
}
} catch (error) {
logger.error('[getConvoTitle] Error getting conversation title', error);
throw new Error('Error getting conversation title');
}
}
/**
* Deletes conversations and their associated messages for a given user and filter.
*/
async function deleteConvos(
user: string,
filter: FilterQuery<IConversation>,
options?: {
beforeDelete?: (conversationIds: string[]) => Promise<void>;
/** Idempotent destructive-recovery mode. An empty selection is success, while
* query, cascade, reconciliation, and deletion failures still propagate. */
allowEmpty?: boolean;
},
) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const { deleteMessages, getMessages } = getMessageMethods();
const userFilter = { ...filter, user };
type DeletionConversation = Pick<
IConversation,
'conversationId' | 'tenantId' | 'chatProjectId' | 'tags'
>;
const retryCascadeOperation = async <T>(operation: () => PromiseLike<T> | T): Promise<T> => {
let lastError: unknown;
for (let attempt = 1; attempt <= 3; attempt += 1) {
try {
return await operation();
} catch (error) {
lastError = error;
if (attempt < 3) {
await new Promise((resolve) => setTimeout(resolve, 25 * attempt));
}
}
}
throw lastError;
};
let conversations = await Conversation.find(userFilter)
.select('conversationId tenantId chatProjectId tags')
.lean<DeletionConversation[]>();
const recoveryConversationIds: string[] = [];
if (!conversations.length && typeof filter.conversationId === 'string') {
/** A prior attempt may have deleted the root before a descendant read failed.
* Resume from immutable root lineage and retain the root id for message,
* checkpoint, and tool cleanup. The message probe distinguishes that partial
* commit from a conversation id that never existed. */
const [descendants, rootMessages] = await Promise.all([
retryCascadeOperation(() =>
Conversation.find({
user,
'subagentThread.rootConversationId': filter.conversationId,
})
.select('conversationId tenantId chatProjectId tags')
.lean<DeletionConversation[]>(),
),
getMessages({ user, conversationId: filter.conversationId }, '_id', { limit: 1 }),
]);
if (descendants.length === 0 && rootMessages.length === 0 && options?.allowEmpty !== true) {
throw new Error('Conversation not found or already deleted.');
}
conversations = descendants;
recoveryConversationIds.push(filter.conversationId);
} else if (!conversations.length) {
if (options?.allowEmpty === true) {
return {
acknowledged: true,
deletedCount: 0,
messages: { acknowledged: true, deletedCount: 0 },
conversationIds: [],
};
}
throw new Error('Conversation not found or already deleted.');
}
/**
* Delete roots first, then walk their owner-scoped lineage. Apart from
* making child threads share the parent's lifecycle, deleting each wave
* before discovering the next closes the child-creation race: a creator
* that started concurrently sees its parent disappear and rolls back,
* while a child already committed is found by the next query.
*/
const deletedConversations: DeletionConversation[] = [];
const seen = new Set<string>();
let pending = conversations;
let acknowledged = true;
let deletedCount = 0;
const reconcileDeletedWave = async (
wave: DeletionConversation[],
waveDeletedCount: number,
): Promise<void> => {
if (waveDeletedCount === 0) {
return;
}
/**
* Commit derived metadata while the deleted documents are still available in
* memory. Descendant discovery can fail after this point; deferring the
* reconciliation until the whole walk completes would make the root's tags and
* project impossible to recover on a later retry.
*/
const tagDecrements: string[] = [];
for (const conversation of wave) {
for (const tag of new Set(conversation.tags ?? [])) {
tagDecrements.push(tag);
}
}
await decrementTagCounts(mongoose, user, tagDecrements);
const waveProjectIds = new Set(
wave
.map((conversation) => conversation.chatProjectId)
.filter((projectId): projectId is string => Boolean(projectId)),
);
if (waveProjectIds.size > 0) {
try {
await refreshChatProjectStatsInBatches(mongoose, user, waveProjectIds);
} catch (error) {
logger.error('[deleteConvos] Conversations deleted but stats refresh failed', error);
}
}
};
while (pending.length > 0) {
const wave = pending.filter((conversation) => !seen.has(conversation.conversationId));
if (wave.length === 0) {
break;
}
const waveIds = wave.map((conversation) => conversation.conversationId);
await deps?.deleteAgentQueuedTurns?.(
user,
wave.map((conversation) => ({
conversationId: conversation.conversationId,
...(conversation.tenantId != null && { tenantId: conversation.tenantId }),
})),
);
await options?.beforeDelete?.(waveIds);
await deps?.prepareAgentTriggerConversationResultErasure?.(user, waveIds);
await retryCascadeOperation(() =>
prepareSubagentContentDeletion(mongoose, {
user,
conversationId: { $in: waveIds },
}),
);
const result = await Conversation.deleteMany({ user, conversationId: { $in: waveIds } });
if (result.deletedCount > 0) {
/** Result erasure is irreversible. Keep receipts intact when a
* pre-delete hook or the conversation delete itself fails, so a
* retained conversation cannot lose a receipt-only completion. */
try {
await deps?.eraseAgentTriggerDeliveryConversationResults?.(user, waveIds);
} catch (error) {
logger.error('[deleteConvos] Receipt erasure deferred to durable cleanup', error);
}
}
acknowledged &&= result.acknowledged;
deletedCount += result.deletedCount;
await reconcileDeletedWave(wave, result.deletedCount);
for (const conversation of wave) {
seen.add(conversation.conversationId);
deletedConversations.push(conversation);
}
pending = await retryCascadeOperation(() =>
Conversation.find({
user,
'subagentThread.parentConversationId': { $in: waveIds },
})
.select('conversationId tenantId chatProjectId tags')
.lean<DeletionConversation[]>(),
);
}
const conversationIds = [
...recoveryConversationIds,
...deletedConversations.map((conversation) => conversation.conversationId),
];
if (recoveryConversationIds.length > 0) {
await deps?.deleteAgentQueuedTurns?.(
user,
recoveryConversationIds.map((conversationId) => ({
conversationId,
allTenants: true,
})),
);
try {
await deps?.eraseAgentTriggerDeliveryConversationResults?.(user, recoveryConversationIds);
} catch (error) {
logger.error('[deleteConvos] Receipt erasure deferred to durable cleanup', error);
}
}
const deleteConvoResult: DeleteResult = { acknowledged, deletedCount };
/**
* Post-delete cleanup is best-effort: the conversations are already gone, so a
* thrown error here would hide the deletion from the caller — dropping the
* `conversationIds` that downstream cleanup (e.g. agent-checkpoint pruning)
* needs, with no way to recover them on retry (the query finds nothing).
*/
let deleteMessagesResult: DeleteResult = { acknowledged: false, deletedCount: 0 };
try {
deleteMessagesResult = await deleteMessages({
conversationId: { $in: conversationIds },
user,
});
} catch (error) {
logger.error('[deleteConvos] Conversations deleted but message cleanup failed', error);
}
try {
await mongoose.models.ToolApprovalGrant?.deleteMany({
user,
conversationId: { $in: conversationIds },
});
} catch {
logger.warn('[deleteConvos] Remembered approval cleanup failed.');
}
// conversationIds lets callers run sibling cleanup that lives in higher layers
// (e.g. pruning the conversations' durable agent checkpoints) without re-querying
// documents that no longer exist.
return { ...deleteConvoResult, messages: deleteMessagesResult, conversationIds };
} catch (error) {
logger.error('[deleteConvos] Error deleting conversations and messages', error);
throw error;
}
}
/**
* Archives every conversation the user can currently see in one pass. Temporary and
* retention-expired conversations are left alone: they are already hidden from the
* chat list, so archiving them would only resurrect them in the archived view.
*/
async function archiveAllConvos(user: string) {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const projectIds = new Set<string>();
/** One stamp for the whole sweep so the archived view groups the run together
* instead of fanning it out across however long the batching took, and so the
* recovery below can find everything this call committed without holding an id
* per conversation in memory. */
const archivedAt = new Date();
let archivedCount = 0;
/** A write whose result never came back may still have committed, so reconciliation
* keys off the attempt rather than off `archivedCount`: a stepdown between commit and
* acknowledgement would otherwise strand those chats with stale project counts, and no
* retry can find them again because they no longer match the sweep filter. */
let attemptedArchiveWrite = false;
try {
const filter = {
user,
$and: [
{ $or: [{ isArchived: false }, { isArchived: { $exists: false } }] },
getVisibleConversationRetentionFilter(),
getHumanConversationFilter(),
],
} as FilterQuery<IConversation>;
const snapshotBoundary = await Conversation.findOne(filter)
.select('_id')
.sort({ _id: -1 })
.lean<Pick<IConversation, '_id'>>();
if (!snapshotBoundary) {
return { archivedCount: 0 };
}
let lastConversationId: Types.ObjectId | null = null;
while (true) {
const idRange = lastConversationId
? { $gt: lastConversationId, $lte: snapshotBoundary._id }
: { $lte: snapshotBoundary._id };
const conversations = await Conversation.find({ ...filter, _id: idRange })
.select('_id chatProjectId')
.sort({ _id: 1 })
.limit(ARCHIVE_CONVERSATION_BATCH_SIZE)
.lean<Array<Pick<IConversation, '_id' | 'chatProjectId'>>>();
if (conversations.length === 0) {
break;
}
const conversationIds: Types.ObjectId[] = [];
for (const conversation of conversations) {
conversationIds.push(conversation._id);
if (conversation.chatProjectId) {
projectIds.add(conversation.chatProjectId);
}
}
lastConversationId = conversationIds[conversationIds.length - 1];
/**
* `timestamps: false` keeps each conversation's own `updatedAt`, so the archived
* view stays sorted by real activity instead of collapsing onto the archive time.
* `archivedAt` is still stamped: the filter only matches unarchived chats, so this
* cannot move an existing stamp, and leaving it unset would drop the whole sweep
* into the legacy group the archived table sorts and dates by `createdAt`.
*/
attemptedArchiveWrite = true;
const result = await Conversation.updateMany(
{ ...filter, _id: { $in: conversationIds } },
{ $set: { isArchived: true, archivedAt } },
{ timestamps: false },
);
const batchArchivedCount = result.modifiedCount ?? 0;
archivedCount += batchArchivedCount;
if (batchArchivedCount > 0) {
const currentProjectIds = await discoverProjectIds(Conversation, {
_id: { $in: conversationIds },
user,
});
for (const projectId of currentProjectIds) {
projectIds.add(projectId);
}
}
}
return { archivedCount };
} catch (error) {
logger.error('[archiveAllConvos] Error archiving conversations', error);
throw error;
} finally {
/**
* Best-effort, mirroring `deleteConvos`: committed batches are already archived, so
* a stats failure must not hide that from the caller. Recover destination projects
* first, because in-loop discovery can throw after a move and a retry cannot see
* those already-archived chats. The sweep marker is what identifies them, so this
* costs one indexed query rather than a per-conversation id list: history size
* changes how much this reads, never how much it holds.
*/
if (attemptedArchiveWrite) {
try {
const recoveredProjectIds = await discoverProjectIds(Conversation, {
user,
isArchived: true,
archivedAt,
});
for (const projectId of recoveredProjectIds) {
projectIds.add(projectId);
}
} catch (error) {
logger.error(
'[archiveAllConvos] Conversations archived but project recovery failed',
error,
);
}
}
if (attemptedArchiveWrite && projectIds.size > 0) {
try {
await refreshChatProjectStatsInBatches(mongoose, user, projectIds);
} catch (error) {
logger.error('[archiveAllConvos] Conversations archived but stats refresh failed', error);
}
}
}
}
/**
* Records that the user has caught up with a conversation's newest message.
*
* `observedResponseAt` is the reply the client actually had on screen. Filtering on it keeps
* the acknowledgement bound to that reply: if another device persisted a newer one in the
* meantime, nothing matches and the indicator survives instead of being cleared for a message
* nobody read. The stamp itself stays server-side, so no client clock is trusted.
*
* Deliberately bypasses `saveConvo`: this needs neither the message lookup nor the upsert,
* and `timestamps: false` keeps `updatedAt` untouched so reading a conversation does not
* reorder the sidebar.
*/
async function markConvoSeen(user: string, conversationId: string, observedResponseAt?: Date) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const filter: FilterQuery<IConversation> = { conversationId, user };
if (observedResponseAt) {
filter.lastResponseAt = { $lte: observedResponseAt };
}
/* Never earlier than the reply being acknowledged. The filter guarantees the stored
* response is no newer than what the client observed, but across replicas the node
* writing this can be behind the one that stamped the reply, and a catch-up older than
* the response it acknowledges would read as unseen again on the next refetch. */
const now = new Date();
const lastSeenAt = observedResponseAt && observedResponseAt > now ? observedResponseAt : now;
const result = await Conversation.updateOne(
filter,
{ $set: { lastSeenAt }, $unset: { isMarkedUnread: '' } },
{ timestamps: false },
);
/* Matched, not modified: a retry of an acknowledgement that already landed writes the
* same value back, which MongoDB reports as zero documents modified. The client reads
* `modified: false` as a rejected stale acknowledgement and rolls its cache back to
* unseen, so success has to mean "the observed reply is still the newest", which is
* exactly what the filter matching does. */
return { modified: result.matchedCount > 0 };
} catch (error) {
logger.error('[markConvoSeen] Error marking conversation seen', error);
throw new Error('Error marking conversation seen');
}
}
/**
* Flags a conversation as unread again: the user explicitly wants the indicator back.
*
* A conversation that has never been replied to has no stamp for the dot to compare against,
* so the flag stamps a strictly monotonic server value and records its source explicitly.
* A real reply racing this write either wins first (and the clear-only path preserves it) or
* sees the synthetic stamp and advances past it while clearing the marker.
*
* Classic operators only. Pipeline-form updates (and `$$REMOVE`) are unsupported on every
* DocumentDB engine this project targets.
*/
async function markConvoUnread(user: string, conversationId: string) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const projection = {
lastResponseAt: 1,
lastResponseMessageId: 1,
lastResponseIsManual: 1,
isMarkedUnread: 1,
};
const stamped = await Conversation.findOneAndUpdate(
{
conversationId,
user,
$or: [{ lastResponseAt: null }, { lastResponseAt: { $exists: false } }],
},
{
$set: { lastResponseAt: new Date(), lastResponseIsManual: true, isMarkedUnread: true },
$unset: { lastSeenAt: '', lastResponseMessageId: '' },
},
{ timestamps: false, new: true, projection },
).lean<
Pick<
IConversation,
'lastResponseAt' | 'lastResponseMessageId' | 'lastResponseIsManual' | 'isMarkedUnread'
>
>();
if (stamped) {
return {
modified: true,
lastResponseAt: stamped.lastResponseAt,
lastResponseMessageId: stamped.lastResponseMessageId,
lastResponseIsManual: stamped.lastResponseIsManual === true,
isMarkedUnread: stamped.isMarkedUnread,
};
}
const cleared = await Conversation.findOneAndUpdate(
{ conversationId, user },
{ $set: { isMarkedUnread: true }, $unset: { lastSeenAt: '' } },
{ timestamps: false, new: true, projection },
).lean<
Pick<
IConversation,
'lastResponseAt' | 'lastResponseMessageId' | 'lastResponseIsManual' | 'isMarkedUnread'
>
>();
return cleared
? {
modified: true,
lastResponseAt: cleared.lastResponseAt,
lastResponseMessageId: cleared.lastResponseMessageId,
lastResponseIsManual: cleared.lastResponseIsManual === true,
isMarkedUnread: cleared.isMarkedUnread,
}
: { modified: false };
} catch (error) {
logger.error('[markConvoUnread] Error marking conversation unread', error);
throw new Error('Error marking conversation unread');
}
}
/**
* Stamps a persisted assistant reply for paths that save the message directly
* (assistants threads, resumed runs, terminal abort re-saves) rather than through
* BaseClient's saveConvo payload.
*
* The same compare-and-set write `saveConvo` uses advances the reply version and clears the
* previous catch-up atomically. Every persisted reply advances beyond the stored version,
* including concurrent replies and replies from hosts whose clocks are behind.
*
* `updatedAt` moves with it, exactly as BaseClient's reply path already does: a new reply is
* real activity and belongs at the top of the sidebar. It is also what the away poll pages
* by, so a stamp that left the order alone would hide replies to any conversation that had
* fallen past the first page. Contrast `markConvoSeen`, where reading must not reorder.
*/
async function stampConvoLastResponse(
user: string,
conversationId: string,
responseMessageId: string,
) {
try {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
const stamped = await stampReplyWithCas(
Conversation,
{ conversationId, user },
responseMessageId,
{
conversationId: 1,
chatProjectId: 1,
createdAt: 1,
updatedAt: 1,
lastResponseMessageId: 1,
},
);
/* Moving `updatedAt` is only half of what `saveConvo` does for a project chat: the
* workspace sorts on `ChatProject.lastConversationAt`, so lifting the conversation
* while leaving its project behind would make the two views disagree. */
if (stamped?.conversation.chatProjectId) {
try {
await updateChatProjectLastConversationForUser(
mongoose,
user,
stamped.conversation.chatProjectId,
stamped.conversation as IConversation,
);
} catch (error) {
logger.error('[stampConvoLastResponse] Failed to update project activity', error);
}
}
/* Return the exact server-side stamp that won the CAS. Callers that deliver a terminal
* event can merge this into their read-state cache without inventing a browser timestamp. */
return stamped
? {
lastResponseAt: stamped.stamp,
lastResponseMessageId: responseMessageId,
...(stamped.conversation.updatedAt
? { updatedAt: stamped.conversation.updatedAt }
: {}),
}
: null;
} catch (error) {
logger.error('[stampConvoLastResponse] Error stamping conversation reply', error);
throw new Error('Error stamping conversation reply');
}
}
return {
getConvoFiles,
searchConversation,
stampForcedRetention,
saveConvo,
setConvoPinned,
appendConvoMessageReference,
getConvoCodeEnvironmentDecision,
addConvoToolApprovalAllows,
reserveConvoLaneGitSeq,
setConvoLaneGit,
getConvoLaneGit,
getConvosLaneGit,
getConvoLaneContext,
readAdmittedConvoCodeEnvironmentDecision,
replaceConvoCodeEnvironmentDecision,
bulkSaveConvos,
getConvosByCursor,
getConvosQueried,
getConvo,
getConvoTitleState,
getSubagentThreadForParent,
listSubagentThreadsForParent,
getAgentEventBinding,
getAgentEventActorSnapshot,
commitAgentEventActorState,
storeAgentEventActorSuspension,
claimAgentEventActorSuspension,
settleAgentEventActorSuspension,
cancelAgentEventActorSuspension,
beginAgentEventActorLegacyTurn,
completeAgentEventActorLegacyTurn,
recordAgentEventActorReconciliation,
resolveAgentEventActorReconciliation,
clearAgentEventActorReconciliation,
getAgentEventActorReconciliationStorageMetrics,
expireLegacyAgentEventActorReceipts,
reserveSubagentThread,
acquireSubagentThreadLease,
renewSubagentThreadLease,
releaseSubagentThreadLease,
countActiveSubagentThreadLeases,
listActiveSubagentThreadLeases,
getConvoOwnership,
getConvoRetention,
getConvoTitle,
markConvoSeen,
markConvoUnread,
stampConvoLastResponse,
deleteConvos,
archiveAllConvos,
};
}