Skip to content

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

165 KB
Raw Blame
import {
  backgroundResultMetadata,
  HITL_MESSAGE_FILTER_FIELDS,
  isForcedTemporaryRetention,
  RetentionMode,
} from 'librechat-data-provider';
import type { DeleteResult, FilterQuery, Model, Types, UpdateQuery } from 'mongoose';
import type { UserSubmittedMessageFieldPath } from 'librechat-data-provider';
import type { SearchParams } from 'meilisearch';
import type { SchemaWithMeiliMethods } from '~/models/plugins/mongoMeili';
import type { ISubagentContentChunk } from '~/models/subagentContent';
import type { AppConfig, IConversation, IMessage } from '~/types';
import { createChatExpirationDate, createTempChatExpirationDate } from '~/utils/tempChatRetention';
import { activeExpirationFilter, createFallbackRetentionDate } from '~/utils/retention';
import { fitBoundAppSnapshots, hasBoundAppSnapshots } from './appSnapshots';
import { prepareSubagentContentDeletion } from './subagentContent';
import { tenantSafeBulkWrite } from '~/utils/tenantBulkWrite';
import { tenantStorage } from '~/config/tenantContext';
import logger from '~/config/winston';

/** Simple UUID v4 regex to replace zod validation */
const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const MAX_STORED_USER_SUBMITTED_PATHS = 256;
const MAX_NORMALIZED_USER_SUBMITTED_PATHS = MAX_STORED_USER_SUBMITTED_PATHS + 1;
const MAX_STORED_USER_SUBMITTED_FIELD_PATHS = MAX_NORMALIZED_USER_SUBMITTED_PATHS;
const MAX_USER_SUBMITTED_PATH_LENGTH = 2048;
const MAX_PROVENANCE_CAS_ATTEMPTS = 8;
const MAX_SUBAGENT_CONTROL_RECEIPTS = 64;
const MAX_SUBAGENT_CONTROL_MESSAGE_LENGTH = 4 * 1024;
/** One owner admits at most 64 terminal control invocations. The optimistic
 * writer therefore has enough rounds for every admitted receipt to converge. */
const MAX_SUBAGENT_CONTROL_RECEIPT_CAS_ATTEMPTS = 64;
const HITL_MESSAGE_FILTER_FIELD_SET = new Set<string>(HITL_MESSAGE_FILTER_FIELDS);

function normalizeUserSubmittedPaths(paths: unknown): string[] {
  if (!Array.isArray(paths)) {
    return [];
  }
  const normalized: string[] = [];
  const seen = new Set<string>();
  for (const path of paths) {
    if (
      typeof path !== 'string' ||
      !path.startsWith('/') ||
      path.length > MAX_USER_SUBMITTED_PATH_LENGTH ||
      seen.has(path)
    ) {
      continue;
    }
    seen.add(path);
    normalized.push(path);
    if (normalized.length >= MAX_NORMALIZED_USER_SUBMITTED_PATHS) {
      break;
    }
  }
  return normalized;
}

function normalizeUserSubmittedMessageFieldPaths(values: unknown): UserSubmittedMessageFieldPath[] {
  if (!Array.isArray(values)) {
    return [];
  }
  const normalized: UserSubmittedMessageFieldPath[] = [];
  const seen = new Set<string>();
  for (const value of values) {
    if (value == null || typeof value !== 'object') {
      continue;
    }
    const { path, field } = value as { path?: unknown; field?: unknown };
    if (
      typeof path !== 'string' ||
      !path.startsWith('/') ||
      path.length > MAX_USER_SUBMITTED_PATH_LENGTH ||
      typeof field !== 'string' ||
      !HITL_MESSAGE_FILTER_FIELD_SET.has(field)
    ) {
      continue;
    }
    const key = `${field}:${path}`;
    if (seen.has(key)) {
      continue;
    }
    seen.add(key);
    normalized.push({ path, field: field as UserSubmittedMessageFieldPath['field'] });
    if (normalized.length >= MAX_NORMALIZED_USER_SUBMITTED_PATHS) {
      break;
    }
  }
  return normalized;
}

function capNormalizedProvenance(
  userSubmittedPaths: readonly string[],
  userSubmittedMessageFieldPaths: readonly UserSubmittedMessageFieldPath[],
): {
  userSubmittedPaths: string[];
  userSubmittedMessageFieldPaths: UserSubmittedMessageFieldPath[];
  promoteWholeMessage: boolean;
} {
  return {
    userSubmittedPaths: userSubmittedPaths.slice(0, MAX_STORED_USER_SUBMITTED_PATHS),
    userSubmittedMessageFieldPaths: userSubmittedMessageFieldPaths.slice(
      0,
      MAX_STORED_USER_SUBMITTED_FIELD_PATHS,
    ),
    promoteWholeMessage: userSubmittedPaths.length > MAX_STORED_USER_SUBMITTED_PATHS,
  };
}

type StoredSubagentControlReceipt = NonNullable<
  NonNullable<IMessage['subagentTask']>['controlReceipts']
>[number];

const terminalControlReceipt = (receipt: StoredSubagentControlReceipt): boolean =>
  receipt.status === 'applied' || receipt.status === 'rejected' || receipt.status === 'failed';

function retainSubagentControlReceipts(
  current: StoredSubagentControlReceipt[],
  receipt: StoredSubagentControlReceipt,
): {
  status: 'updated' | 'unchanged' | 'conflict' | 'capacity';
  receipts: StoredSubagentControlReceipt[];
} {
  const existingIndex = current.findIndex(
    (candidate) => candidate.invocationId === receipt.invocationId,
  );
  let merged: StoredSubagentControlReceipt[];
  if (existingIndex < 0) {
    merged = [...current, receipt];
  } else {
    const existing = current[existingIndex];
    if (existing.fingerprint !== receipt.fingerprint) {
      return { status: 'conflict', receipts: current };
    }
    if (
      terminalControlReceipt(existing) ||
      existing.status === receipt.status ||
      (existing.status === 'accepted' && receipt.status === 'reserved')
    ) {
      return { status: 'unchanged', receipts: current };
    }
    merged = current.map((candidate, index) => (index === existingIndex ? receipt : candidate));
  }
  const accepted = merged.filter(
    (candidate) => candidate.status === 'reserved' || candidate.status === 'accepted',
  );
  /** Reserved and accepted receipts are idempotency fences for commands that can
   * still take effect. Never evict one to admit another receipt: report capacity
   * so the caller refuses the command before mutating the live task. */
  if (accepted.length > MAX_SUBAGENT_CONTROL_RECEIPTS) {
    return { status: 'capacity', receipts: current };
  }
  const terminalAllowance = Math.max(0, MAX_SUBAGENT_CONTROL_RECEIPTS - accepted.length);
  let terminal =
    terminalAllowance === 0
      ? []
      : merged
          .filter((candidate) => candidate.status !== 'reserved' && candidate.status !== 'accepted')
          .sort(
            (left, right) =>
              left.createdAt.getTime() - right.createdAt.getTime() ||
              left.invocationId.localeCompare(right.invocationId),
          )
          .slice(-terminalAllowance);
  const advancesActiveFence =
    existingIndex >= 0 &&
    !terminalControlReceipt(current[existingIndex]) &&
    terminalControlReceipt(receipt);
  if (
    advancesActiveFence &&
    !terminal.some((candidate) => candidate.invocationId === receipt.invocationId)
  ) {
    /** A terminal transition for an active fence must outrank unrelated terminal
     * history even though it retains the command's older occurrence timestamp. */
    const otherAllowance = Math.max(0, terminalAllowance - 1);
    terminal = [
      ...(otherAllowance === 0
        ? []
        : terminal
            .filter((candidate) => candidate.invocationId !== receipt.invocationId)
            .slice(-otherAllowance)),
      receipt,
    ].sort(
      (left, right) =>
        left.createdAt.getTime() - right.createdAt.getTime() ||
        left.invocationId.localeCompare(right.invocationId),
    );
  }
  const receipts = [...accepted, ...terminal];
  if (!receipts.some((candidate) => candidate.invocationId === receipt.invocationId)) {
    return { status: 'capacity', receipts: current };
  }
  return { status: 'updated', receipts };
}

type MessageProvenance = Pick<
  IMessage,
  'isUserSubmitted' | 'userSubmittedPaths' | 'userSubmittedMessageFieldPaths'
>;

function mergeMessageProvenance(
  current: MessageProvenance | null,
  userSubmittedPaths: readonly string[],
  userSubmittedMessageFieldPaths: readonly UserSubmittedMessageFieldPath[],
  stampModelOutputOnInsert = false,
  explicitIsUserSubmitted?: boolean,
  preserveStoredIsUserSubmitted = true,
): MessageProvenance {
  const provenance = capNormalizedProvenance(
    normalizeUserSubmittedPaths([...(current?.userSubmittedPaths ?? []), ...userSubmittedPaths]),
    normalizeUserSubmittedMessageFieldPaths([
      ...(current?.userSubmittedMessageFieldPaths ?? []),
      ...userSubmittedMessageFieldPaths,
    ]),
  );

  let isUserSubmitted = preserveStoredIsUserSubmitted ? current?.isUserSubmitted : undefined;
  if (typeof explicitIsUserSubmitted === 'boolean') {
    isUserSubmitted = explicitIsUserSubmitted;
  } else if (stampModelOutputOnInsert && isUserSubmitted == null) {
    isUserSubmitted = false;
  }
  if (provenance.promoteWholeMessage) {
    isUserSubmitted = true;
  }

  return {
    userSubmittedPaths: provenance.userSubmittedPaths,
    userSubmittedMessageFieldPaths: provenance.userSubmittedMessageFieldPaths,
    ...(typeof isUserSubmitted === 'boolean' && { isUserSubmitted }),
  };
}

function getProvenanceSnapshotFilter(current: MessageProvenance): Record<string, unknown> {
  return {
    userSubmittedPaths: !Object.prototype.hasOwnProperty.call(current, 'userSubmittedPaths')
      ? { $exists: false }
      : current.userSubmittedPaths,
    userSubmittedMessageFieldPaths: !Object.prototype.hasOwnProperty.call(
      current,
      'userSubmittedMessageFieldPaths',
    )
      ? { $exists: false }
      : current.userSubmittedMessageFieldPaths,
    isUserSubmitted: !Object.prototype.hasOwnProperty.call(current, 'isUserSubmitted')
      ? { $exists: false }
      : current.isUserSubmitted,
  };
}

function getMissingProvenanceFilter(): Record<string, unknown> {
  return {
    userSubmittedPaths: { $exists: false },
    userSubmittedMessageFieldPaths: { $exists: false },
    isUserSubmitted: { $exists: false },
  };
}

function isDuplicateKeyError(err: unknown): boolean {
  return (err as { code?: number }).code === 11000;
}

function getSteerUserSubmittedPaths(content: unknown): string[] {
  if (!Array.isArray(content)) {
    return [];
  }
  const paths: string[] = [];
  for (let index = 0; index < content.length; index++) {
    const part = content[index] as { type?: unknown } | null | undefined;
    if (part?.type === 'steer') {
      paths.push(`/content/${index}`);
    }
  }
  return paths;
}

/** Mongoose omits undefined $set values. Strip identity/version inputs before any sizing callback. */
function sanitizeMessageUpdate(update: Record<string, unknown>): Record<string, unknown> {
  return Object.fromEntries(
    Object.entries(update).filter(
      ([key, value]) => value !== undefined && !['_id', 'tenantId', '__v'].includes(key),
    ),
  );
}

/** Conservatively admit any server-bound resource to the slow path, including legacy MIME forms. */
const NO_BOUND_APPS = { 'attachments.ui_resources.serverBinding': { $exists: false } };

/**
 * A terminal save that must drop a stored `contextMeta` unsets it in the same
 * update that persists the response, so no failure between two writes can
 * leave a completed row carrying a disconnect snapshot's state.
 */
function buildMessageSaveUpdate(
  update: Record<string, unknown>,
  options: {
    stampModelOutputOnInsert: boolean;
    unsetContextMeta: boolean;
    unsetPrivateText?: boolean;
    retentionOnInsert?: { expiredAt: Date; isTemporary: false };
  },
): UpdateQuery<IMessage> {
  return {
    $set: update,
    $inc: { __v: 1 },
    ...((options.stampModelOutputOnInsert || options.retentionOnInsert != null) && {
      $setOnInsert: {
        ...(options.stampModelOutputOnInsert && { isUserSubmitted: false }),
        ...options.retentionOnInsert,
      },
    }),
    ...((options.unsetContextMeta || options.unsetPrivateText) && {
      $unset: {
        ...(options.unsetContextMeta && { contextMeta: 1 }),
        ...(options.unsetPrivateText && {
          privateText: 1,
          privacyRevision: 1,
          ...(update.privateTextTokens === undefined && { privateTextTokens: 1 }),
        }),
      },
    }),
  };
}

/**
 * A legacy temporary message stores only its deadline; hydration then fills
 * `isTemporary` with the schema default `false`, which must not read as permanent.
 */
function isTemporaryMessage(message: IMessage): boolean {
  if (message.isTemporary === true) {
    return true;
  }
  const implicit = message.isTemporary == null || message.$isDefault?.('isTemporary') === true;
  return implicit && message.expiredAt != null;
}

async function findOneAndMergeMessageProvenance(
  Message: Model<IMessage>,
  identity: FilterQuery<IMessage>,
  update: Record<string, unknown>,
  userSubmittedPaths: readonly string[],
  userSubmittedMessageFieldPaths: readonly UserSubmittedMessageFieldPath[],
  options: {
    upsert: boolean;
    stampModelOutputOnInsert?: boolean;
    unsetContextMeta?: boolean;
    unsetPrivateText?: boolean;
    retentionOnInsert?: { expiredAt: Date; isTemporary: false };
    prepareAppUpdate?: (
      current: Record<string, unknown> | null,
      update: Record<string, unknown>,
    ) => Promise<Record<string, unknown>>;
    timestamps?: boolean;
    privateMessagePaths?: string;
    onWrite?: (inserted: boolean, id: unknown) => void;
  },
) {
  const safeUpdate = sanitizeMessageUpdate(update);
  const preservesStoredIsUserSubmitted = !Object.prototype.hasOwnProperty.call(
    safeUpdate,
    'isUserSubmitted',
  );

  /** A small optimistic loop keeps the merge atomic while using only classic update operators. */
  for (let attempt = 0; attempt < MAX_PROVENANCE_CAS_ATTEMPTS; attempt += 1) {
    const current = await Message.findOne(identity)
      .select(
        options.prepareAppUpdate
          ? (options.privateMessagePaths ?? '')
          : {
              isUserSubmitted: 1,
              userSubmittedPaths: 1,
              userSubmittedMessageFieldPaths: 1,
              _id: 0,
            },
      )
      .lean<
        | (MessageProvenance & {
            _id?: Types.ObjectId;
            attachments?: unknown[];
            content?: unknown[];
            __v?: number;
          })
        | null
      >();
    if (current == null && !options.upsert) {
      return null;
    }

    const provenance = mergeMessageProvenance(
      current,
      userSubmittedPaths,
      userSubmittedMessageFieldPaths,
      options.stampModelOutputOnInsert,
      typeof safeUpdate.isUserSubmitted === 'boolean' ? safeUpdate.isUserSubmitted : undefined,
      preservesStoredIsUserSubmitted,
    );
    const filter = {
      ...identity,
      ...(current == null ? getMissingProvenanceFilter() : getProvenanceSnapshotFilter(current)),
      ...(options.prepareAppUpdate &&
        (current != null
          ? {
              _id: current._id,
              __v: current.__v ?? null,
            }
          : { _id: new Message.base.Types.ObjectId() })),
    };
    const admittedUpdate = options.prepareAppUpdate
      ? await options.prepareAppUpdate(current, { ...safeUpdate, ...provenance })
      : { ...safeUpdate, ...provenance };

    try {
      const message = await Message.findOneAndUpdate(
        filter,
        {
          $set: admittedUpdate,
          $inc: { __v: 1 },
          ...(current == null &&
            options.retentionOnInsert != null && { $setOnInsert: options.retentionOnInsert }),
          ...((options.unsetContextMeta || options.unsetPrivateText) && {
            $unset: {
              ...(options.unsetContextMeta && { contextMeta: 1 }),
              ...(options.unsetPrivateText && {
                privateText: 1,
                privacyRevision: 1,
                ...(update.privateTextTokens === undefined && { privateTextTokens: 1 }),
              }),
            },
          }),
        },
        { upsert: options.upsert && current == null, new: true, timestamps: options.timestamps },
      );
      if (message != null) {
        options.onWrite?.(current == null, message._id);
        return message;
      }
    } catch (err) {
      if (!isDuplicateKeyError(err) || !options.upsert) {
        throw err;
      }
    }
  }

  throw new Error('Message provenance write contention exceeded its retry bound.');
}

/**
 * Maximum private transcript JSON that may cross the MongoDB projection seam
 * for the bounded public subagent-activity view. This gives the sanitizer
 * enough source headroom while preventing multi-megabyte transcripts from
 * being materialized merely to produce a 64 KiB public activity response.
 */
export const SUBAGENT_TRANSCRIPT_SOURCE_BYTE_LIMIT: number = 256 * 1024;
const SUBAGENT_ACTIVITY_PROJECTION_SOURCE_BYTE_LIMIT = 64 * 1024;

/**
 * Maximum activity sources materialized for one child-view poll. New writers
 * supply at most four 64 KiB public projections; legacy rows fall back to at
 * most four 256 KiB private transcripts during a rolling deployment.
 */
export const SUBAGENT_TRANSCRIPT_PAGE_LIMIT: number = 4;
const SUBAGENT_ACTIVITY_SOURCE_CANDIDATE_LIMIT = SUBAGENT_TRANSCRIPT_PAGE_LIMIT * 2;

/**
 * Ordinary persisted message content is the authoritative refresh source when
 * an execution did not write a private subagent transcript. Project only the
 * visible activity vocabulary and bound it before MongoDB returns the row.
 */
/**
 * Per-item bounds mirror `SUBAGENT_ACTIVITY_LIMITS` in `packages/api`
 * (`src/agents/activity.ts`) at worst-case 4-byte UTF-8, so activity projected
 * from ordinary message content is clipped no harder than activity projected
 * from a private transcript. The whole view stays bounded downstream by the
 * 64KB serialized-activity budget and the 256KB response trim.
 */
export const SUBAGENT_MESSAGE_ACTIVITY_ITEM_LIMIT: number = 100;
const SUBAGENT_MESSAGE_ACTIVITY_TEXT_CODE_POINT_LIMIT = 8192;
const SUBAGENT_MESSAGE_ACTIVITY_TOOL_INPUT_CODE_POINT_LIMIT = 2048;
const SUBAGENT_MESSAGE_ACTIVITY_TOOL_OUTPUT_CODE_POINT_LIMIT = 4096;
const SUBAGENT_MESSAGE_ACTIVITY_ID_CODE_POINT_LIMIT = 128;
const SUBAGENT_MESSAGE_ACTIVITY_LABEL_CODE_POINT_LIMIT = 512;
const SUBAGENT_MESSAGE_ACTIVITY_LABEL_IDS_LIMIT = 8;
const SUBAGENT_MESSAGE_ACTIVITY_TOTAL_BYTE_LIMIT = 64 * 1024;
const SUBAGENT_VIEW_CONTROL_RECEIPT_LIMIT = 32;
const SUBAGENT_VIEW_CONTROL_STRING_CODE_POINT_LIMIT = 128;

/**
 * Exclusion projection for message reads that feed the chat client (the
 * conversation GET and shared-link reads). Every excluded field is either
 * server-internal (ids, replay signatures, legacy summarization state) or a
 * web_search SERP vertical no citation marker or UI can address: markers
 * resolve `search|image|news|video|ref|file` through organic/images/
 * topStories/videos/references (all kept — `news` markers read topStories,
 * never the `news` collection). The JSON export mirrors this cache, so
 * fields removed here also leave user exports.
 */
/**
 * A response the server generated and sampled into a trace. Its trace fields are
 * an ownership claim, so rows a client authored (the message-create route and
 * imports stamp `isUserSubmitted: true`) never count, even if one was persisted
 * with forged fields before those writes stripped them.
 */
/** A response's position in trace order: its creation time, then its `_id`. */
function traceOrderKey(createdAt: Date, id: Types.ObjectId): string {
  return `${createdAt.getTime().toString(36)}.${id.toString()}`;
}

function parseTraceOrderKey(key: string): { createdAt: Date; id: string } | undefined {
  const [time, hex] = key.split('.');
  const createdAt = new Date(Number.parseInt(time ?? '', 36));
  if (Number.isNaN(createdAt.getTime()) || hex == null || !/^[0-9a-f]{24}$/.test(hex)) {
    return undefined;
  }
  return { createdAt, id: hex };
}

/** An explicit tenant scope, so a read without request tenant context still cannot span tenants. */
const traceTenantScope = (tenantId?: string) =>
  tenantId == null ? { tenantId: { $exists: false } } : { tenantId };

const SERVER_AUTHORED_SAMPLED_RESPONSE = {
  langfuseSampled: true,
  isCreatedByUser: false,
  isUserSubmitted: { $ne: true },
} as const;

export const CLIENT_MESSAGE_SELECT: string = [
  '-_id',
  '-__v',
  '-user',
  '-clientId',
  '-invocationId',
  '-conversationSignature',
  '-summary',
  '-summaryTokenCount',
  '-privateText',
  '-privateTextTokens',
  '-contextMeta',
  '-langfuseSampled',
  '-langfuseDestinationIds',
  '-langfuseRunId',
  '-metadata.thoughtSignatures',
  '-content.tool_call.backgroundTask.resultClaim',
  '-content.tool_call.backgroundTask.completionWakeup',
  '-attachments.web_search.knowledgeGraph',
  '-attachments.web_search.peopleAlsoAsk',
  '-attachments.web_search.relatedSearches',
  '-attachments.web_search.shopping',
  '-attachments.web_search.places',
  '-attachments.web_search.news',
  '-attachments.web_search.organic.sitelinks',
  '-attachments.web_search.organic.highlights',
  '-attachments.web_search.topStories.highlights',
].join(' ');

interface MessageQueryOptions {
  limit?: number;
  sort?: Record<string, 1 | -1> | false;
}

export type SubagentTaskResultClaim =
  | { status: 'not_found' }
  | { status: 'claimed'; message: IMessage }
  | { status: 'acquired'; message: IMessage };

export interface BackgroundToolResultRecord {
  taskId: string;
  toolCallId: string;
  toolName: string;
  status: 'completed' | 'error' | 'cancelled';
  output: string;
  agentId?: string;
  /** When the task reached this terminal status. Absent on rows written before
   * the stamp existed, so a consumer must treat it as optional. */
  settledAt?: Date;
}

export type BackgroundToolResultClaim =
  | { status: 'not_found' | 'not_ready' }
  | { status: 'outcome_unknown'; toolName: string }
  | {
      status: 'claimed';
      claim?: {
        kind: 'manual' | 'wakeup';
        claimId: string;
        generationId?: string;
        batchId?: string;
        receiptReconciled?: true;
      };
      messageId?: string;
    }
  | { status: 'acquired'; results: BackgroundToolResultRecord[]; messageId?: string };

export type SubagentThreadViewMessageRecord = Pick<
  IMessage,
  | 'messageId'
  | 'parentMessageId'
  | 'isCreatedByUser'
  | 'text'
  | 'createdAt'
  | 'error'
  | 'unfinished'
  | 'subagentTranscript'
  | 'subagentTriggerProjection'
> & {
  textProjectionTruncated?: boolean;
  contentRecoveryAvailable?: boolean;
  subagentTranscriptProjectionTruncated?: boolean;
  /** Storage-bounded visible content; validated into the public activity type by the API. */
  subagentActivity?: unknown[];
  subagentActivityProjectionJson?: string;
  subagentActivityProjectionTruncated?: boolean;
  /** Storage-bounded task state; private replay and execution fields never cross this seam. */
  subagentTask?: {
    status?: NonNullable<IMessage['subagentTask']>['status'];
    controlReceipts?: Array<
      Omit<StoredSubagentControlReceipt, 'fingerprint'> & { fingerprint?: never }
    >;
    controlReceiptsProjectionTruncated?: boolean;
  };
};

/** Amazon DocumentDB does not support `$$REMOVE`, so the bounded thread-view
 * projections emit `null` where they mean "omit this key". This is the shape as
 * it leaves the aggregation, before those sentinels are pruned back to absent. */
/** Widens the given keys to admit the projection's `null` sentinel. */
type WithNullSentinels<T, K extends keyof T> = Omit<T, K> & {
  [P in K]?: NonNullable<T[P]> | null;
};

type ThreadViewRecord = SubagentThreadViewMessageRecord;
export type ProjectedSubagentThreadViewMessage = WithNullSentinels<
  Omit<ThreadViewRecord, 'subagentTask' | 'subagentTriggerProjection'>,
  'subagentTranscriptProjectionTruncated'
> & {
  subagentTriggerProjection?: WithNullSentinels<
    NonNullable<ThreadViewRecord['subagentTriggerProjection']>,
    'expectedActionToolName'
  > | null;
  subagentTask?:
    | (Omit<NonNullable<ThreadViewRecord['subagentTask']>, 'controlReceipts'> & {
        controlReceipts?: Array<
          WithNullSentinels<
            NonNullable<NonNullable<ThreadViewRecord['subagentTask']>['controlReceipts']>[number],
            'controlId' | 'reason' | 'message'
          >
        >;
      })
    | null;
};

/** Restores the absent-vs-present contract by dropping the `null` sentinels the
 * projection emitted. Bounded by the projection's own row, receipt, and byte
 * limits, and folded into the pass that already materializes each record. */
function pruneProjectedThreadViewMessage(
  message: ProjectedSubagentThreadViewMessage,
): SubagentThreadViewMessageRecord {
  if (message.subagentTranscriptProjectionTruncated === null) {
    delete message.subagentTranscriptProjectionTruncated;
  }
  if (message.subagentTriggerProjection === null) {
    delete message.subagentTriggerProjection;
  } else if (message.subagentTriggerProjection?.expectedActionToolName === null) {
    delete message.subagentTriggerProjection.expectedActionToolName;
  }
  if (message.subagentTask === null) {
    delete message.subagentTask;
  } else {
    for (const receipt of message.subagentTask?.controlReceipts ?? []) {
      if (receipt.controlId === null) delete receipt.controlId;
      if (receipt.reason === null) delete receipt.reason;
      if (receipt.message === null) delete receipt.message;
    }
  }
  return message as SubagentThreadViewMessageRecord;
}

export type ParentSubagentTaskRecord = {
  conversationId: string;
  /** The shared bounded source window filled, so this child's history may be incomplete. */
  sourceTruncated?: boolean;
  tasks: Array<
    Pick<IMessage, 'messageId' | 'createdAt'> & {
      status: NonNullable<IMessage['subagentTask']>['status'];
      /** True when status was inferred from an ordinary event-turn row. */
      statusDerived?: boolean;
      /** Private ordering token used only while merging bounded storage reads. */
      occurrenceId?: Types.ObjectId;
    }
  >;
};

/** A response message whose run was sampled into a trace. */
export interface SampledTraceMessage {
  messageId: string;
  createdAt?: Date;
  /** Opaque ids of the tracing destinations eligible to hold the trace, when recorded. */
  langfuseDestinationIds?: string[];
  /** The run whose trace this response reports, when it is not the message's own id. */
  langfuseRunId?: string;
  /** Opaque position in the conversation's response order, which a later read can resume from. */
  orderKey?: string;
}

export interface ConversationTraceRefs {
  /** Creation time of the user's earliest message in the conversation. */
  firstMessageAt?: Date;
  /** Sampled response messages, oldest first. */
  sampledMessages: SampledTraceMessage[];
}

/**
 * Reads a stored terminal stamp defensively: rows written before the stamp existed
 * omit it, and a document can reach here from a raw read where the date is still a
 * string, so an unusable value is reported as absent rather than as `Invalid Date`.
 */
function toSettledAt(value: unknown): Date | undefined {
  if (value instanceof Date) {
    return Number.isNaN(value.getTime()) ? undefined : value;
  }
  if (typeof value === 'string' || typeof value === 'number') {
    const parsed = new Date(value);
    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
  }
  return undefined;
}

export interface PrivateTextWrite {
  readonly envelope: string;
  readonly revision: string;
}

export interface PrivateTextRead {
  readonly _id?: unknown;
  readonly messageId: string;
  readonly text: string;
  readonly privacyRevision: string;
  readonly privateText: string;
}

export interface MessageMethods {
  getPersistedPrivateTextId(
    input: Parameters<MessageMethods['hasPersistedPrivateText']>[0],
  ): Promise<string | null>;
  hasPersistedPrivateText(input: {
    userId: string;
    tenantId?: string;
    conversationId: string;
    messageId: string;
    privacyRevision: string;
    text: string;
  }): Promise<boolean>;
  getPrivateMessageTexts(input: {
    userId: string;
    tenantId?: string;
    conversationId: string;
    messageIds: readonly string[];
  }): Promise<PrivateTextRead[]>;
  saveMessage(
    ctx: {
      userId: string;
      isTemporary?: boolean;
      expiredAt?: Date;
      interfaceConfig?: AppConfig['interfaceConfig'];
    },
    params: Omit<Partial<IMessage>, 'contextMeta'> & {
      newMessageId?: string;
      contextMeta?: IMessage['contextMeta'] | null;
    },
    metadata?: { context?: string; privateText?: PrivateTextWrite; insertOnly?: boolean },
  ): Promise<IMessage | null | undefined>;
  /**
   * Reads the references a trace viewer needs for one of the user's
   * conversations: when it began and which responses were sampled into traces.
   */
  getConversationTraceRefs(input: {
    user: string;
    conversationId: string;
    tenantId?: string;
    /** Only this response, when it is a sampled one. */
    messageId?: string;
    /** The newest response to include, by the `orderKey` a previous read returned for it. */
    through?: { messageId: string; orderKey: string };
    /** The most responses to return, newest first from `through`; all of them when absent. */
    limit?: number;
  }): Promise<ConversationTraceRefs>;
  /**
   * Whether any of the user's responses in the conversation was sampled into a
   * trace that one of `destinationIds` can hold. A response with no recorded
   * destinations predates the record and counts for every destination.
   */
  hasSampledTraceMessage(input: {
    user: string;
    conversationId: string;
    tenantId?: string;
    destinationIds: string[];
  }): Promise<boolean>;
  recordSubagentTaskControlReceipt(input: {
    userId: string;
    conversationId: string;
    taskId: string;
    tenantId?: string;
    receipt: NonNullable<NonNullable<IMessage['subagentTask']>['controlReceipts']>[number];
  }): Promise<boolean | 'unchanged' | 'conflict'>;
  getSubagentTaskControlReceipt(input: {
    userId: string;
    conversationId: string;
    taskId: string;
    invocationId: string;
    tenantId?: string;
    activeOnly?: boolean;
  }): Promise<NonNullable<NonNullable<IMessage['subagentTask']>['controlReceipts']>[number] | null>;
  getSubagentTaskControlReplay(input: {
    userId: string;
    parentConversationId: string;
    taskId: string;
    invocationId: string;
    tenantId?: string;
  }): Promise<{
    receipt: NonNullable<NonNullable<IMessage['subagentTask']>['controlReceipts']>[number];
    task: {
      taskId: string;
      threadId: string;
      subagentType: string;
      status: NonNullable<IMessage['subagentTask']>['status'];
      resultAvailable: boolean;
      resultClaimed: boolean;
      pendingControls: number;
      createdAt: Date;
      updatedAt: Date;
    };
  } | null>;
  bulkSaveMessages(
    messages: Array<Partial<IMessage>>,
    overrideTimestamp?: boolean,
    provenance?: { privateTextTokens: ReadonlyMap<string, readonly string[]> },
  ): Promise<unknown>;
  updateToolCallResult(params: {
    userId: string;
    messageId: string;
    conversationId: string;
    toolCallId: string;
    stepId?: string;
    agentId?: string;
    output?: string;
    attachments?: unknown[];
    markBackgrounded?: boolean;
    backgroundTask?: {
      taskId: string;
      toolName: string;
      status: 'completed' | 'error';
      cancelled?: true;
      settledAt: Date;
      completionWakeup?: true;
      completionReceipt?: true;
      resultClaim?: {
        kind: 'manual' | 'wakeup';
        claimId: string;
        claimedAt: Date;
        generationId?: string;
        receiptReconciled?: true;
      };
    };
  }): Promise<{ matched: boolean; unfinished: boolean }>;
  claimBackgroundToolResults(params: {
    userId: string;
    conversationId: string;
    /** Optional on recovery polls after the process-local task registry was lost. */
    messageId?: string;
    taskId: string;
    agentId?: string;
    kind: 'manual' | 'wakeup';
    claimId: string;
    /** Physical receipt-batch identity, independent of its logical request. */
    batchId?: string;
    /** Response generation that owns this manual result delivery. */
    generationId?: string;
    /** Manual owner-process takeover after automatic delivery was retired. */
    allowUnfinished?: boolean;
    limit?: number;
    /** Includes JSON escaping, delimiters, and empty result fields. */
    maxMetadataChars?: number;
  }): Promise<BackgroundToolResultClaim>;
  confirmBackgroundToolResultClaim(params: {
    userId: string;
    conversationId: string;
    messageId: string;
    taskId: string;
    claimId: string;
  }): Promise<boolean>;
  releaseBackgroundToolResultClaims(params: {
    userId: string;
    conversationId: string;
    messageId: string;
    /** Omit to release every sibling owned by this exact batch claim. */
    taskIds?: string[];
    /** Receipt-backed results can precede the message projection. */
    allowMissingMessage?: true;
    /** Manual rollback must not erase a committed receipt handoff. */
    onlyIfUnreconciled?: true;
    batchId?: string;
    kind: 'manual' | 'wakeup';
    claimId: string;
  }): Promise<boolean>;
  updateMessage(
    userId: string,
    message: Partial<IMessage> & { newMessageId?: string },
    metadata?: { context?: string },
  ): Promise<Partial<IMessage>>;
  claimSubagentTaskResult(params: {
    userId: string;
    conversationId: string;
    taskId: string;
    kind: 'manual' | 'wakeup';
    claimId: string;
  }): Promise<SubagentTaskResultClaim>;
  releaseSubagentTaskResultClaim(params: {
    userId: string;
    conversationId: string;
    taskId: string;
    kind: 'manual' | 'wakeup';
    claimId: string;
  }): Promise<boolean>;
  getMessages(
    filter: FilterQuery<IMessage>,
    select?: string,
    options?: MessageQueryOptions,
  ): Promise<IMessage[]>;
  getMessagesForSubagentThreadView(input: {
    user: string;
    conversationId: string;
    tenantId?: string;
    selectedTaskId?: string;
    beforeMessageId?: string;
    limit: number;
    textCodePointLimit: number;
  }): Promise<SubagentThreadViewMessageRecord[]>;
  listSubagentTasksForThreads(input: {
    user: string;
    conversationIds: string[];
    tenantId?: string;
    limitPerThread: number;
  }): Promise<ParentSubagentTaskRecord[]>;
  getMessage(params: { user: string; messageId: string }): Promise<IMessage | null>;
  getBranchReasoningOverride(params: {
    user: string;
    conversationId: string;
    parentMessageId: string;
  }): Promise<IMessage['reasoningOverride'] | null>;
  getMessagesByCursor(
    filter: FilterQuery<IMessage>,
    options?: {
      sortField?: string;
      sortOrder?: 1 | -1;
      limit?: number;
      cursor?: string | null;
      select?: string;
    },
  ): Promise<{ messages: IMessage[]; nextCursor: string | null }>;
  searchMessages(
    query: string,
    searchOptions: SearchParams,
    hydrate?: boolean,
  ): Promise<Awaited<ReturnType<SchemaWithMeiliMethods['meiliSearch']>>>;
  deleteMessages(filter: FilterQuery<IMessage>): Promise<DeleteResult>;
}

const DATE_SORT_FIELDS = new Set(['createdAt', 'updatedAt']);
/** Cursor marker for a null or missing sort value, which MongoDB orders before every string, '' included. */
const NULL_SORT_VALUE = '\u0000';
const OBJECT_ID_PATTERN = /^[0-9a-f]{24}$/i;

/** Encodes the last row of a page as `<sortValue>|<_id>`; dates use ISO strings so milliseconds survive. */
function formatMessageCursor(value: unknown, id: unknown): string {
  if (value == null) {
    return id == null ? NULL_SORT_VALUE : `${NULL_SORT_VALUE}|${String(id)}`;
  }
  const sortValue = value instanceof Date ? value.toISOString() : String(value);
  return id == null ? sortValue : `${sortValue}|${String(id)}`;
}

/** Accepts both the compound cursor and the legacy bare sort value from older clients. */
function parseMessageCursor(cursor: string): { value: string; id?: string } {
  const split = cursor.lastIndexOf('|');
  if (split >= 0 && OBJECT_ID_PATTERN.test(cursor.slice(split + 1))) {
    return { value: cursor.slice(0, split), id: cursor.slice(split + 1) };
  }
  return { value: cursor };
}

/** The rows after a cursor, following MongoDB's order: null/missing, then '' (strings only), then values. */
function buildCursorFilter(
  sortField: string,
  op: '$gt' | '$lt',
  value: string | Date,
  position: { value: string; id?: Types.ObjectId },
): FilterQuery<IMessage> {
  if (position.id == null) {
    return { [sortField]: { [op]: value } };
  }
  const tieId = { _id: { [op]: position.id } };
  const ascending = op === '$gt';
  if (position.value === NULL_SORT_VALUE) {
    return {
      $or: [
        { [sortField]: null, ...tieId },
        ...(ascending ? [{ [sortField]: { $ne: null } }] : []),
      ],
    };
  }
  return {
    $or: [
      { [sortField]: { [op]: value } },
      { [sortField]: value, ...tieId },
      ...(ascending ? [] : [{ [sortField]: null }]),
    ],
  };
}

/** The agent-ownership rule shared by background-tool settling and claiming:
 * `agentId` on the part wins, then `tool_call.agentId`, and a part without
 * agent identity belongs to any caller (single-agent runs). `field: null`
 * matches both a missing field and a stored null. The settle and claim paths
 * MUST apply the identical rule, or a settled part becomes unclaimable. */
function agentOwnershipFilter(prefix: string, agentId: string): Record<string, unknown> {
  return {
    $or: [
      { [`${prefix}agentId`]: agentId },
      { [`${prefix}agentId`]: null, [`${prefix}tool_call.agentId`]: agentId },
      { [`${prefix}agentId`]: null, [`${prefix}tool_call.agentId`]: null },
    ],
  };
}

type UpdateToolCallResultInput = {
  userId: string;
  messageId: string;
  conversationId: string;
  toolCallId: string;
  stepId?: string;
  /** Scopes the part match when provider tool-call ids repeat across
   *  agents in one response message (e.g. `call_0` per response); a part
   *  without agent identity matches any caller (single-agent runs). */
  agentId?: string;
  output?: string;
  attachments?: unknown[];
  /**
   * Stamps `backgrounded: true` onto the patched tool call. Replacing the
   * dispatch-handle output with the settled task's stdout destroys the only
   * signal renderers had that this call ran detached (the handle JSON and
   * the live status-marker attachment are both transient), so the patch
   * that erases it must persist a durable one alongside.
   */
  markBackgrounded?: boolean;
  backgroundTask?: {
    taskId: string;
    toolName: string;
    status: 'completed' | 'error';
    cancelled?: true;
    settledAt: Date;
    completionWakeup?: true;
    completionReceipt?: true;
    resultClaim?: {
      kind: 'manual' | 'wakeup';
      claimId: string;
      claimedAt: Date;
      generationId?: string;
    };
  };
};

type SteplessToolCallFallback = {
  content: NonNullable<IMessage['content']>;
  hasResultClaim: boolean;
};

export interface MessageDependencies {
  /** Read from deployment config, never from a message/request or a principal override. */
  getMCPAppMessageBudget?: () => Promise<number | undefined>;
}

export function createMessageMethods(
  mongoose: typeof import('mongoose'),
  deps: MessageDependencies = {},
): MessageMethods {
  /** The API constructs method adapters before it necessarily registers every model. */
  function privateMessagePaths(): string {
    const Message = mongoose.models.Message as Model<IMessage>;
    return Object.entries(Message.schema.paths)
      .filter(([, path]) => path.options.select === false)
      .map(([name]) => `+${name}`)
      .join(' ');
  }

  async function prepareAppUpdate(
    update: Record<string, unknown>,
    current: Record<string, unknown> | null,
    unsetContextMeta = false,
    retentionOnInsert?: { expiredAt: Date; isTemporary: false },
  ): Promise<Record<string, unknown>> {
    const Message = mongoose.models.Message as Model<IMessage>;
    const safeUpdate = sanitizeMessageUpdate(update);
    // Omission retains the attachments of THIS fenced row; null/[] explicitly clears them.
    const attachments = Object.prototype.hasOwnProperty.call(safeUpdate, 'attachments')
      ? safeUpdate.attachments
      : current?.attachments;
    if (!hasBoundAppSnapshots(attachments)) return safeUpdate;
    const maxBytes = await deps.getMCPAppMessageBudget?.();
    const admitted = fitBoundAppSnapshots(
      attachments as unknown[],
      (candidateAttachments) => {
        const fields = {
          ...current,
          ...(current == null ? retentionOnInsert : {}),
          ...safeUpdate,
          attachments: candidateAttachments,
          ...(unsetContextMeta ? { contextMeta: undefined } : {}),
          createdAt: current?.createdAt ?? safeUpdate.createdAt ?? new Date(),
          updatedAt: new Date(),
          __v: (Number(current?.__v) || 0) + 1,
        };
        const next = new Message(fields).toObject({ depopulate: true, minimize: false });
        // Keep unknown fields already stored by a newer producer, even if this schema drops them.
        const candidate = { ...current, ...next };
        if (unsetContextMeta) delete candidate.contextMeta;
        return mongoose.mongo.BSON.calculateObjectSize(candidate);
      },
      maxBytes,
    );
    if (admitted !== attachments) {
      logger.warn('[saveMessage] Optional MCP App documents exceeded the message BSON budget');
    }
    return admitted === attachments ? safeUpdate : { ...safeUpdate, attachments: admitted };
  }

  /** One admission owner for save, edit, record and import. No size heuristics or stale closures. */
  async function writeMessage(
    identity: FilterQuery<IMessage>,
    input: Record<string, unknown>,
    options: {
      upsert: boolean;
      stampModelOutputOnInsert?: boolean;
      unsetContextMeta?: boolean;
      retentionOnInsert?: { expiredAt: Date; isTemporary: false };
      unsetPrivateText?: boolean;
      timestamps?: boolean;
      onWrite?: (inserted: boolean, id: unknown) => void;
    },
  ): Promise<IMessage | null> {
    const Message = mongoose.models.Message as Model<IMessage>;
    const update = sanitizeMessageUpdate(input);
    const paths = normalizeUserSubmittedPaths(update.userSubmittedPaths);
    const fields = normalizeUserSubmittedMessageFieldPaths(update.userSubmittedMessageFieldPaths);
    delete update.userSubmittedPaths;
    delete update.userSubmittedMessageFieldPaths;
    if (!hasBoundAppSnapshots(update.attachments) && paths.length === 0 && fields.length === 0) {
      try {
        // Preserve the single-write common path. If an App row is excluded, its existing
        // unique (messageId, user, tenantId) index rejects the upsert; budget that row below.
        const fast = await Message.findOneAndUpdate(
          { ...identity, ...NO_BOUND_APPS },
          buildMessageSaveUpdate(update, {
            stampModelOutputOnInsert: options.stampModelOutputOnInsert ?? false,
            unsetContextMeta: options.unsetContextMeta ?? false,
            retentionOnInsert: options.retentionOnInsert,
            unsetPrivateText: options.unsetPrivateText,
          }),
          {
            upsert: options.upsert,
            new: true,
            timestamps: options.timestamps,
            includeResultMetadata: true,
          },
        );
        if (fast.value) {
          options.onWrite?.(fast.lastErrorObject?.updatedExisting === false, fast.value._id);
          return fast.value;
        }
      } catch (error) {
        if (!isDuplicateKeyError(error)) throw error;
      }
    }
    return findOneAndMergeMessageProvenance(Message, identity, update, paths, fields, {
      ...options,
      privateMessagePaths: privateMessagePaths(),
      prepareAppUpdate: (current, sanitized) =>
        prepareAppUpdate(sanitized, current, options.unsetContextMeta, options.retentionOnInsert),
    });
  }

  /**
   * Saves a message in the database.
   */
  async function saveMessage(
    {
      userId,
      isTemporary,
      expiredAt,
      interfaceConfig,
    }: {
      userId: string;
      isTemporary?: boolean;
      expiredAt?: Date;
      interfaceConfig?: AppConfig['interfaceConfig'];
    },
    params: Omit<Partial<IMessage>, 'contextMeta'> & {
      newMessageId?: string;
      /** `null` unsets a previously stored value; omission leaves it in place. */
      contextMeta?: IMessage['contextMeta'] | null;
    },
    metadata?: { context?: string; privateText?: PrivateTextWrite; insertOnly?: boolean },
  ) {
    if (!userId) {
      throw new Error('User not authenticated');
    }

    const conversationId = params.conversationId as string | undefined;
    if (!conversationId || !UUID_REGEX.test(conversationId)) {
      logger.warn(
        `Invalid conversation ID: ${conversationId} (context: ${metadata?.context ?? 'n/a'})`,
      );
      return;
    }

    try {
      const Message = mongoose.models.Message as Model<IMessage>;
      const update: Record<string, unknown> = {
        ...params,
        user: userId,
        messageId: params.newMessageId || params.messageId,
      };
      delete update.privateText;
      delete update.privacyRevision;
      delete update.privateTextTokens;
      if (metadata?.privateText != null) {
        if (params.isCreatedByUser !== true || typeof params.text !== 'string') {
          throw new Error('Private text requires a user message.');
        }
        update.privateText = metadata.privateText.envelope;
        update.privacyRevision = metadata.privateText.revision;
      }
      delete update.isTemporary;
      delete update.expiredAt;
      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(`---\`saveMessage\` 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(`---\`saveMessage\` 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(`---\`saveMessage\` 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(`---\`saveMessage\` context: ${metadata?.context}`);
          update.expiredAt = createFallbackRetentionDate();
        }
      } else if (isTemporary === false) {
        update.isTemporary = false;
        update.expiredAt = null;
      }

      /** A response that ends with nothing to carry must drop what an earlier
       * partial save (a disconnect snapshot) stored, or the next turn would seed
       * from stale state; omission never unsets, and the unset rides the same
       * update as the response. */
      const unsetContextMeta = update.contextMeta === null;
      if (unsetContextMeta) {
        delete update.contextMeta;
      }
      if (update.tokenCount != null && isNaN(update.tokenCount as number)) {
        logger.warn(
          `Resetting invalid \`tokenCount\` for message \`${params.messageId}\`: ${update.tokenCount}`,
        );
        logger.info(`---\`saveMessage\` context: ${metadata?.context}`);
        update.tokenCount = 0;
      }
      const userSubmittedPaths = normalizeUserSubmittedPaths([
        ...(Array.isArray(params.userSubmittedPaths) ? params.userSubmittedPaths : []),
        ...getSteerUserSubmittedPaths(params.content),
      ]);
      const userSubmittedMessageFieldPaths = normalizeUserSubmittedMessageFieldPaths(
        params.userSubmittedMessageFieldPaths,
      );
      delete update.userSubmittedPaths;
      delete update.userSubmittedMessageFieldPaths;
      delete update.__v;
      const stampModelOutputOnInsert =
        params.isCreatedByUser === false && params.isUserSubmitted === undefined;
      if (metadata?.insertOnly === true) {
        if (metadata.privateText != null) {
          throw new Error('A private message cannot use the ordinary insert-only writer.');
        }
        const now = new Date();
        const existingOrInserted = await Message.findOneAndUpdate(
          { messageId: params.messageId, user: userId },
          {
            $setOnInsert: {
              ...update,
              ...(userSubmittedPaths.length > 0 && { userSubmittedPaths }),
              ...(userSubmittedMessageFieldPaths.length > 0 && { userSubmittedMessageFieldPaths }),
              ...retentionOnInsert,
              createdAt: now,
              updatedAt: now,
            },
          },
          { upsert: true, new: true, timestamps: false },
        );
        return existingOrInserted?.toObject();
      }
      const message = await writeMessage(
        { messageId: params.messageId, user: userId },
        { ...update, userSubmittedPaths, userSubmittedMessageFieldPaths },
        {
          upsert: true,
          stampModelOutputOnInsert,
          unsetContextMeta,
          retentionOnInsert,
          unsetPrivateText:
            metadata?.privateText == null && Object.prototype.hasOwnProperty.call(update, 'text'),
        },
      );

      if (message == null) {
        return message;
      }

      /** 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' &&
        message.expiredAt == null
      ) {
        const deadline = createChatExpirationDate(interfaceConfig, message.isTemporary === true);
        const result = await Message.updateOne(
          {
            _id: message._id,
            expiredAt: null,
            isTemporary: message.isTemporary === true ? true : { $ne: true },
          },
          { $set: { expiredAt: deadline } },
          { timestamps: false },
        );
        if (result.modifiedCount > 0) {
          message.expiredAt = deadline;
        }
      }

      if (
        interfaceConfig?.retentionMode === RetentionMode.ALL &&
        typeof isTemporary !== 'boolean' &&
        (message.isTemporary == null ||
          (message.isTemporary === false && message.$isDefault('isTemporary')))
      ) {
        await Message.updateOne(
          { _id: message._id, isTemporary: { $ne: false } },
          { $set: { isTemporary: false } },
        );
        message.isTemporary = false;
      }

      return message.toObject();
    } catch (err: unknown) {
      logger.error('Error saving message:', err);
      logger.info(`---\`saveMessage\` context: ${metadata?.context}`);

      const mongoErr = err as { code?: number; message?: string };
      if (mongoErr.code === 11000 && mongoErr.message?.includes('duplicate key error')) {
        logger.warn(`Duplicate messageId detected: ${params.messageId}. Continuing execution.`);

        try {
          const Message = mongoose.models.Message as Model<IMessage>;
          const existingMessage = await Message.findOne({
            messageId: params.messageId,
            user: userId,
          });

          if (existingMessage) {
            return existingMessage.toObject();
          }

          return undefined;
        } catch (findError) {
          logger.warn(
            `Could not retrieve existing message with ID ${params.messageId}: ${(findError as Error).message}`,
          );
          return undefined;
        }
      }

      throw err;
    }
  }

  /**
   * Saves multiple messages in bulk.
   */
  async function bulkSaveMessages(
    messages: Array<Record<string, unknown>>,
    overrideTimestamp = false,
    provenance?: { privateTextTokens: ReadonlyMap<string, readonly string[]> },
  ) {
    try {
      const Message = mongoose.models.Message as Model<IMessage>;
      const bulkOps = messages.map((message) => {
        const normalizedMessage = sanitizeMessageUpdate(message);
        delete normalizedMessage.privateText;
        delete normalizedMessage.privacyRevision;
        delete normalizedMessage.privateTextTokens;
        const tokens = provenance?.privateTextTokens.get(String(message.messageId));
        const text = message.text;
        if (
          tokens?.length &&
          tokens.length <= 4096 &&
          message.isCreatedByUser === true &&
          typeof text === 'string'
        ) {
          normalizedMessage.privateTextTokens = tokens.filter(
            (token) =>
              /^\[(?:EMAIL|PHONE|NAME|CREDENTIAL|CUSTOM)_\d+_[a-f0-9]{32}\]$/.test(token) &&
              text.includes(token),
          );
        }
        const submittedProvenance = capNormalizedProvenance(
          normalizeUserSubmittedPaths(message.userSubmittedPaths),
          normalizeUserSubmittedMessageFieldPaths(message.userSubmittedMessageFieldPaths),
        );
        if (submittedProvenance.userSubmittedPaths.length > 0) {
          normalizedMessage.userSubmittedPaths = submittedProvenance.userSubmittedPaths;
        } else {
          delete normalizedMessage.userSubmittedPaths;
        }
        if (submittedProvenance.userSubmittedMessageFieldPaths.length > 0) {
          normalizedMessage.userSubmittedMessageFieldPaths =
            submittedProvenance.userSubmittedMessageFieldPaths;
        } else {
          delete normalizedMessage.userSubmittedMessageFieldPaths;
        }
        if (submittedProvenance.promoteWholeMessage) {
          normalizedMessage.isUserSubmitted = true;
        }
        return {
          updateOne: {
            filter: {
              messageId: message.messageId,
              ...(message.user != null ? { user: message.user } : {}),
            },
            update: {
              $set: normalizedMessage,
              $inc: { __v: 1 },
              $unset: {
                privateText: 1,
                privacyRevision: 1,
                ...(normalizedMessage.privateTextTokens == null && { privateTextTokens: 1 }),
              },
            },
            timestamps: !overrideTimestamp,
            upsert: true,
          },
        };
      });
      // Keep no-App imports batched. The atomic predicate makes a race with App attachment
      // creation collide on the unique key, at which point only that row uses guarded admission.
      const guarded: typeof bulkOps = [];
      const ordinary = bulkOps.filter((op) => {
        if (hasBoundAppSnapshots(op.updateOne.update.$set.attachments)) {
          guarded.push(op);
          return false;
        }
        return true;
      });
      let result:
        | {
            matchedCount: number;
            modifiedCount: number;
            upsertedCount: number;
            upsertedIds: Record<number, unknown>;
          }
        | undefined;
      const repaired = {
        matchedCount: 0,
        modifiedCount: 0,
        upsertedCount: 0,
        upsertedIds: {} as Record<number, unknown>,
      };
      if (ordinary.length) {
        try {
          result = await tenantSafeBulkWrite(
            Message,
            ordinary.map((op) => ({
              updateOne: {
                ...op.updateOne,
                filter: { ...op.updateOne.filter, ...NO_BOUND_APPS },
              },
            })),
            { ordered: false },
          );
        } catch (error) {
          const failure = error as {
            writeErrors?: Array<{ code: number; index: number }>;
            result?: typeof result;
          };
          if (
            !failure.writeErrors?.length ||
            failure.writeErrors.some((item) => item.code !== 11000)
          )
            throw error;
          result = failure.result;
          for (const { index } of failure.writeErrors) guarded.push(ordinary[index]);
        }
      }
      // Ordinary imports stay batched; exceptional App rows are admitted one at a time.
      for (const op of guarded) {
        await writeMessage(op.updateOne.filter, op.updateOne.update.$set, {
          upsert: true,
          unsetPrivateText: true,
          timestamps: !overrideTimestamp,
          onWrite: (inserted, id) => {
            if (inserted) {
              repaired.upsertedCount++;
              repaired.upsertedIds[bulkOps.indexOf(op)] = id;
            } else {
              repaired.matchedCount++;
              repaired.modifiedCount++;
            }
          },
        });
      }
      if (!guarded.length) return result;
      const upsertedIds: Record<number, unknown> = { ...repaired.upsertedIds };
      for (const [index, id] of Object.entries(result?.upsertedIds ?? {})) {
        upsertedIds[bulkOps.indexOf(ordinary[Number(index)])] = id;
      }
      return {
        insertedCount: 0,
        deletedCount: 0,
        insertedIds: {},
        upsertedIds,
        matchedCount: (result?.matchedCount ?? 0) + repaired.matchedCount,
        modifiedCount: (result?.modifiedCount ?? 0) + repaired.modifiedCount,
        upsertedCount: (result?.upsertedCount ?? 0) + repaired.upsertedCount,
      };
    } catch (err) {
      logger.error('Error saving messages in bulk:', err);
      throw err;
    }
  }

  /**
   * Patches a persisted tool_call content part in place and appends attachments,
   * for results that settle after the turn's message was finalized (background
   * tool calls). Atomic single update so two tasks completing concurrently on
   * the same message cannot lose each other's attachments, and IDEMPOTENT
   * (attachments dedupe by `file_id ?? filepath`, scoped to this tool call so
   * sibling calls sharing a filename keep their own entries) so it can be
   * re-applied to heal a later full-row save that reverted the patch.
   *
   * Returns `matched: false` when the message row does not exist yet (the
   * dispatch turn has not finalized) and surfaces `unfinished` when the
   * matched row is a mid-turn partial save (client disconnect) — the eventual
   * finalize will overwrite the patch with in-memory content, so callers
   * should keep re-applying until a finalized row is patched.
   */
  async function updateToolCallResult(
    input: UpdateToolCallResultInput,
  ): Promise<{ matched: boolean; unfinished: boolean }> {
    const exact = await settleToolCallResult(input, input.stepId);
    if (exact.matched || input.stepId == null) {
      return exact;
    }
    /** A turn resumed after an approval pause persists the tool calls it made
     * before the pause without their step ids, so an exact step match can never
     * land and the settled result would be given up. On a finished row, fall back
     * to the one part with this call id (and agent scope) that has no stored step.
     * An unfinished row may not hold the real part yet, and more than one
     * candidate means a repeated provider id: both stay unmatched rather than
     * patching the wrong part. */
    const fallback = await getSteplessToolCallFallback(input);
    if (fallback == null) {
      return exact;
    }
    return settleToolCallResult(input, null, fallback);
  }

  async function getSteplessToolCallFallback({
    userId,
    messageId,
    conversationId,
    toolCallId,
    stepId,
    agentId,
  }: UpdateToolCallResultInput): Promise<SteplessToolCallFallback | undefined> {
    const Message = mongoose.models.Message as Model<IMessage>;
    const row = await Message.findOne({ messageId, user: userId, conversationId })
      .select({ content: 1, unfinished: 1 })
      .lean<Pick<IMessage, 'content' | 'unfinished'> | null>();
    if (row == null || row.unfinished === true) {
      return;
    }
    let candidates = 0;
    let hasResultClaim = false;
    const content = row.content ?? [];
    for (const part of content) {
      const entry = part as {
        type?: unknown;
        agentId?: unknown;
        tool_call?: {
          id?: unknown;
          stepId?: unknown;
          agentId?: unknown;
          backgroundTask?: { resultClaim?: unknown };
        };
      } | null;
      if (entry?.type !== 'tool_call' || entry.tool_call?.id !== toolCallId) {
        continue;
      }
      const owner = entry.agentId ?? entry.tool_call.agentId;
      if (agentId != null && owner != null && owner !== agentId) {
        continue;
      }
      /** An unmatched write can mean attachment contention, not a missing
       * identity. Never substitute a sibling for an existing exact part. */
      if (entry.tool_call.stepId === stepId) {
        return;
      }
      if (entry.tool_call.stepId != null) {
        continue;
      }
      candidates += 1;
      if (candidates > 1) {
        return;
      }
      hasResultClaim = entry.tool_call.backgroundTask?.resultClaim != null;
    }
    return candidates === 1 ? { content, hasResultClaim } : undefined;
  }

  async function settleToolCallResult(
    {
      userId,
      messageId,
      conversationId,
      toolCallId,
      stepId,
      agentId,
      output,
      attachments,
      markBackgrounded,
      backgroundTask,
    }: UpdateToolCallResultInput,
    /** A step id to match exactly, `null` to match a part with no stored step,
     * or `undefined` to ignore steps. */
    stepMatch: string | null | undefined,
    fallback?: SteplessToolCallFallback,
  ): Promise<{ matched: boolean; unfinished: boolean }> {
    /** One source of truth for which content part this settle may touch:
     * `prefix: ''` yields the `$elemMatch` document filter, `prefix: 'part.'`
     * the arrayFilters element filter — the same predicate in one dialect,
     * where the old code kept an aggregation `$expr` twin of it. `field: null`
     * matches both a missing field and a stored null, mirroring the previous
     * `$ifNull` chains. */
    const partScope = (prefix: string): Record<string, unknown> => ({
      [`${prefix}type`]: 'tool_call',
      [`${prefix}tool_call.id`]: toolCallId,
      ...(stepMatch !== undefined ? { [`${prefix}tool_call.stepId`]: stepMatch } : {}),
      ...(agentId != null ? agentOwnershipFilter(prefix, agentId) : {}),
    });
    const messageFilter = {
      messageId,
      user: userId,
      conversationId,
      ...(fallback == null
        ? { content: { $elemMatch: partScope('') } }
        : { content: fallback.content, unfinished: { $ne: true } }),
    };
    const partIdentityFilter = partScope('part.');
    /** Amazon DocumentDB rejects aggregation-pipeline updates, so the part
     * patch addresses the matching tool-call parts with the filtered positional
     * operator and plain `$set`/`$unset`. Setting `backgroundTask` subfields
     * individually preserves an existing `resultClaim` without the per-part
     * branching the old pipeline needed, and clearing `completionWakeup` keeps
     * the old whole-object replacement's disarm semantics. */
    const partPatch: Record<string, string | number | boolean | Date> = {};
    let disarmWakeup = false;
    if (output !== undefined || backgroundTask != null) {
      if (output !== undefined) {
        partPatch['content.$[part].tool_call.output'] = output;
      }
      if (markBackgrounded === true) {
        partPatch['content.$[part].tool_call.backgrounded'] = true;
      }
      if (backgroundTask != null) {
        partPatch['content.$[part].tool_call.backgroundTask.version'] = 1;
        partPatch['content.$[part].tool_call.backgroundTask.taskId'] = backgroundTask.taskId;
        partPatch['content.$[part].tool_call.backgroundTask.toolName'] = backgroundTask.toolName;
        partPatch['content.$[part].tool_call.backgroundTask.status'] = backgroundTask.status;
        partPatch['content.$[part].tool_call.backgroundTask.cancelled'] =
          backgroundTask.cancelled === true;
        partPatch['content.$[part].tool_call.backgroundTask.settledAt'] = backgroundTask.settledAt;
        if (backgroundTask.completionReceipt === true) {
          partPatch['content.$[part].tool_call.backgroundTask.completionReceipt'] = true;
        }
        if (backgroundTask.completionWakeup === true) {
          partPatch['content.$[part].tool_call.backgroundTask.completionWakeup'] = true;
        } else {
          disarmWakeup = true;
        }
      }
    }
    const incomingAttachments = attachments ?? [];
    const mergingAttachments = incomingAttachments.length > 0;
    if (Object.keys(partPatch).length === 0 && !mergingAttachments) {
      return { matched: false, unfinished: false };
    }
    /** Fence the fallback on the content used to establish its unique identity.
     * A concurrent save or claim must invalidate the whole write, including any
     * supplied claim. The snapshot lets us preserve an existing claim and stamp
     * a missing one atomically with settlement, rather than before this fence. */
    const settlePatch = {
      ...partPatch,
      ...(fallback != null && !fallback.hasResultClaim && backgroundTask?.resultClaim != null
        ? { 'content.$[part].tool_call.backgroundTask.resultClaim': backgroundTask.resultClaim }
        : {}),
    };
    const settleUpdate = {
      $inc: { __v: 1 },
      ...(Object.keys(settlePatch).length > 0 ? { $set: settlePatch } : {}),
      ...(disarmWakeup
        ? { $unset: { 'content.$[part].tool_call.backgroundTask.completionWakeup': 1 } }
        : {}),
    };
    const settleOptions = {
      new: true,
      projection: { unfinished: 1 },
      ...(Object.keys(partPatch).length > 0 || disarmWakeup
        ? { arrayFilters: [partIdentityFilter] }
        : {}),
    };
    try {
      const Message = mongoose.models.Message as Model<IMessage>;
      /** A supplied claim is stamped BEFORE the settle write, on parts that
       * carry none (`resultClaim: null` also admits a stored null, as the old
       * `$ifNull` did). Ordering is what keeps the split safe: until the settle
       * write lands, the part is not terminal, so a concurrent wakeup or manual
       * poll sees `not_ready` and stands down; the old single pipeline wrote
       * claim and receipt atomically, and a claim-after-settle order would
       * instead expose a claimable terminal part that lets a second consumer
       * deliver the same result. A crash between the writes is healed by the
       * settle retry, whose claim write no-ops against its own stamp. */
      if (fallback == null && backgroundTask?.resultClaim != null) {
        await Message.updateOne(
          messageFilter,
          {
            $set: {
              'content.$[part].tool_call.backgroundTask.resultClaim': backgroundTask.resultClaim,
            },
          },
          {
            arrayFilters: [
              { ...partIdentityFilter, 'part.tool_call.backgroundTask.resultClaim': null },
            ],
          },
        );
      }
      if (!mergingAttachments) {
        const fast = await Message.findOneAndUpdate(
          { ...messageFilter, ...NO_BOUND_APPS },
          settleUpdate,
          settleOptions,
        ).lean<{ unfinished?: boolean } | null>();
        if (fast) return { matched: true, unfinished: fast.unfinished === true };
        // Either absent, or a bound-App row needs an exact candidate even for tiny results.
      }
      /** Dedupe key mirrors the resume merge: `file_id ?? filepath`, so
       * download-fallback attachments (no `file_id`, only a filepath) stay
       * idempotent across re-applications instead of duplicating per poll.
       * Replace only THIS tool call's prior entries: sibling calls can
       * legitimately share a `file_id` (the filename claim is per-conversation),
       * and the client anchors attachments to cards by `toolCallId`. Provider
       * tool-call ids repeat across agents in handoff messages, so a sibling
       * agent's attachment under the same id/key must survive (missing agent
       * identity = legacy wildcard). */
      const attachmentKeys = new Set(
        incomingAttachments
          .map((attachment) => {
            const { file_id, filepath } = attachment as { file_id?: unknown; filepath?: unknown };
            return typeof file_id === 'string' ? file_id : filepath;
          })
          .filter((key): key is string => typeof key === 'string'),
      );
      const replacesEntry = (existing: unknown): boolean => {
        if (existing == null || typeof existing !== 'object') return false;
        const entry = existing as {
          file_id?: unknown;
          filepath?: unknown;
          toolCallId?: unknown;
          agentId?: unknown;
          stepId?: unknown;
        };
        const key = entry.file_id ?? entry.filepath;
        if (typeof key !== 'string' || !attachmentKeys.has(key)) return false;
        if (entry.toolCallId !== toolCallId) return false;
        const entryAgent = entry.agentId ?? null;
        if (agentId != null && entryAgent !== null && entryAgent !== agentId) return false;
        const entryStep = entry.stepId ?? null;
        if (stepId != null && entryStep !== null && entryStep !== stepId) return false;
        return true;
      };
      /** Classic `$pull` and `$push` conflict on the same field. Keep merge and
       * part patch in one update; ordinary attachments retain the preexisting
       * array compare-and-swap. For bound Apps, a large array in BOTH the filter
       * and update exceeds MongoDB's 16 MiB command limit even when the resulting
       * document fits. Use the small `__v` fence instead: every save with
       * attachments and every background settle increments it. A lost fence is
       * re-read and re-budgeted before retrying the combined write. */
      const incomingApp = hasBoundAppSnapshots(incomingAttachments);
      for (let attempt = 0; attempt < ATTACHMENT_MERGE_CAS_ATTEMPTS; attempt += 1) {
        const row = await Message.findOne(messageFilter)
          .select(incomingApp ? privateMessagePaths() : { _id: 1, attachments: 1, __v: 1 })
          .lean<
            | (Record<string, unknown> & {
                _id: Types.ObjectId;
                attachments?: unknown[];
                __v?: number;
              })
            | null
          >();
        if (row == null) {
          return { matched: false, unfinished: false };
        }
        const hasApps = incomingApp || hasBoundAppSnapshots(row.attachments);
        /** Avoid materializing the whole message for ordinary file attachments. */
        const current =
          hasApps && !incomingApp
            ? await Message.findOne({
                ...messageFilter,
                _id: row._id,
                __v: row.__v ?? null,
              })
                .select(privateMessagePaths())
                .lean<
                  | (Record<string, unknown> & { _id: Types.ObjectId; attachments?: unknown[] })
                  | null
                >()
            : row;
        if (current == null) continue;
        const prior = Array.isArray(current.attachments) ? current.attachments : [];
        const merged = [...prior.filter((entry) => !replacesEntry(entry)), ...incomingAttachments];
        let admitted = merged;
        if (hasApps) {
          const content = Array.isArray(current.content) ? current.content : [];
          const nextContent = content.map((entry) => {
            if (entry == null || typeof entry !== 'object') return entry;
            const part = entry as {
              type?: unknown;
              agentId?: unknown;
              tool_call?: {
                id?: unknown;
                stepId?: unknown;
                agentId?: unknown;
                backgroundTask?: Record<string, unknown>;
              };
            };
            // Exactly the agentOwnershipFilter precedence: part agent, then call agent, then wildcard.
            const owner = part.agentId ?? part.tool_call?.agentId;
            if (
              part.type !== 'tool_call' ||
              part.tool_call?.id !== toolCallId ||
              (stepId != null && part.tool_call.stepId !== stepId) ||
              (agentId != null && owner != null && owner !== agentId)
            )
              return entry;
            const task = { ...part.tool_call.backgroundTask };
            if (backgroundTask) {
              Object.assign(task, {
                version: 1,
                taskId: backgroundTask.taskId,
                toolName: backgroundTask.toolName,
                status: backgroundTask.status,
                cancelled: backgroundTask.cancelled === true,
                settledAt: backgroundTask.settledAt,
              });
              if (backgroundTask.completionReceipt) task.completionReceipt = true;
              if (backgroundTask.completionWakeup) task.completionWakeup = true;
              else delete task.completionWakeup;
            }
            return {
              ...part,
              tool_call: {
                ...part.tool_call,
                ...(output !== undefined && { output }),
                ...((output !== undefined || backgroundTask != null) &&
                  markBackgrounded && { backgrounded: true }),
                ...(backgroundTask && { backgroundTask: task }),
              },
            };
          });
          admitted = (
            await prepareAppUpdate({ attachments: merged, content: nextContent }, current)
          ).attachments as unknown[];
        }
        const result = await Message.findOneAndUpdate(
          {
            ...messageFilter,
            _id: current._id,
            ...(hasApps
              ? { __v: current.__v ?? null }
              : { attachments: current.attachments == null ? null : current.attachments }),
          },
          {
            ...settleUpdate,
            $set: { ...settlePatch, attachments: admitted },
          },
          settleOptions,
        ).lean<{ unfinished?: boolean } | null>();
        if (result != null) {
          return { matched: true, unfinished: result.unfinished === true };
        }
      }
      /** Losing every fence round means concurrent writers kept advancing the
       * array — the document exists and is healthy, so persistence must stay
       * retryable ABOVE this bounded loop. The settle retry treats an
       * unmatched result as retry-then-heal-later; a throw would land on
       * ambiguous-failure handling that can retire the completion outright,
       * losing a completed tool result to mere attachment contention. */
      logger.warn(
        `[updateToolCallResult] Attachment merge for tool call ${toolCallId} lost ` +
          `${ATTACHMENT_MERGE_CAS_ATTEMPTS} fence rounds; leaving the retry to the caller`,
      );
      return { matched: false, unfinished: false };
    } catch (err) {
      logger.error('Error updating tool call result:', err);
      throw err;
    }
  }

  const MAX_BACKGROUND_TOOL_RESULT_BATCH = 16;
  /** Bounds the attachments-merge fence retries. Each lost round means a
   * concurrent writer changed the array, so re-reading converges. */
  const ATTACHMENT_MERGE_CAS_ATTEMPTS = 8;

  function readBackgroundToolResultClaim(
    row: Pick<IMessage, 'content'>,
    taskId: string,
  ):
    | {
        kind: 'manual' | 'wakeup';
        claimId: string;
        generationId?: string;
        batchId?: string;
        receiptReconciled?: true;
      }
    | undefined {
    for (const part of row.content ?? []) {
      if (part == null || typeof part !== 'object' || Array.isArray(part)) {
        continue;
      }
      const backgroundTask = (
        part as {
          tool_call?: {
            backgroundTask?: {
              taskId?: unknown;
              resultClaim?: {
                kind?: unknown;
                claimId?: unknown;
                generationId?: unknown;
                batchId?: unknown;
                receiptReconciled?: unknown;
              };
            };
          };
        }
      ).tool_call?.backgroundTask;
      if (backgroundTask?.taskId !== taskId) {
        continue;
      }
      const claim = backgroundTask.resultClaim;
      if (
        (claim?.kind === 'manual' || claim?.kind === 'wakeup') &&
        typeof claim.claimId === 'string' &&
        claim.claimId.length > 0
      ) {
        return {
          kind: claim.kind,
          claimId: claim.claimId,
          ...(typeof claim.batchId === 'string' && { batchId: claim.batchId }),
          ...(claim.receiptReconciled === true && { receiptReconciled: true }),
          ...(typeof claim.generationId === 'string' && claim.generationId.length > 0
            ? { generationId: claim.generationId }
            : {}),
        };
      }
      return;
    }
  }

  function parseBackgroundToolResults(
    message: IMessage,
    claim: { kind: 'manual' | 'wakeup'; claimId: string; batchId?: string },
  ): BackgroundToolResultRecord[] {
    const results: BackgroundToolResultRecord[] = [];
    for (const part of message.content ?? []) {
      if (part == null || typeof part !== 'object' || Array.isArray(part)) {
        continue;
      }
      const record = part as {
        agentId?: unknown;
        tool_call?: {
          id?: unknown;
          agentId?: unknown;
          output?: unknown;
          backgroundTask?: {
            taskId?: unknown;
            toolName?: unknown;
            status?: unknown;
            cancelled?: unknown;
            settledAt?: unknown;
            resultClaim?: { kind?: unknown; claimId?: unknown; batchId?: unknown };
          };
        };
      };
      const toolCall = record.tool_call;
      const task = toolCall?.backgroundTask;
      if (
        typeof toolCall?.id !== 'string' ||
        typeof task?.taskId !== 'string' ||
        typeof task.toolName !== 'string' ||
        (task.status !== 'completed' && task.status !== 'error') ||
        task.resultClaim?.kind !== claim.kind ||
        task.resultClaim.claimId !== claim.claimId ||
        task.resultClaim.batchId !== claim.batchId
      ) {
        continue;
      }
      let resultAgentId: string | undefined;
      if (typeof record.agentId === 'string') {
        resultAgentId = record.agentId;
      } else if (typeof toolCall.agentId === 'string') {
        resultAgentId = toolCall.agentId;
      }
      const settledAt = toSettledAt(task.settledAt);
      results.push({
        taskId: task.taskId,
        toolCallId: toolCall.id,
        toolName: task.toolName,
        status: task.cancelled === true ? 'cancelled' : task.status,
        output: typeof toolCall.output === 'string' ? toolCall.output : '',
        ...(resultAgentId == null ? {} : { agentId: resultAgentId }),
        ...(settledAt == null ? {} : { settledAt }),
      });
    }
    return results;
  }

  function readBackgroundToolHandle(
    message: IMessage,
    taskId: string,
    agentId?: string,
  ): string | undefined {
    for (const part of message.content ?? []) {
      if (part == null || typeof part !== 'object' || Array.isArray(part)) {
        continue;
      }
      const record = part as {
        agentId?: unknown;
        tool_call?: { agentId?: unknown; output?: unknown };
      };
      const partAgentId = record.agentId ?? record.tool_call?.agentId;
      const sameAgent =
        agentId == null ||
        partAgentId == null ||
        (typeof partAgentId === 'string' && partAgentId === agentId);
      const output = record.tool_call?.output;
      if (!sameAgent || typeof output !== 'string' || !output.includes(taskId)) {
        continue;
      }
      try {
        const handle = JSON.parse(output) as {
          background_task_id?: unknown;
          subagent_type?: unknown;
          tool?: unknown;
          status?: unknown;
        };
        if (
          handle.background_task_id === taskId &&
          handle.status === 'running' &&
          typeof handle.subagent_type !== 'string' &&
          typeof handle.tool === 'string' &&
          handle.tool.length > 0
        ) {
          return handle.tool;
        }
      } catch {
        continue;
      }
    }
    return;
  }

  /** Atomically elects manual polling or one automatic continuation. Wakeups
   * also claim a bounded set of already-settled siblings from the same parent
   * response, avoiding one paid continuation per concurrently completed tool. */
  async function claimBackgroundToolResults({
    userId,
    conversationId,
    messageId,
    taskId,
    agentId,
    kind,
    claimId,
    generationId,
    batchId,
    allowUnfinished = false,
    limit = kind === 'wakeup' ? 8 : 1,
    maxMetadataChars,
  }: Parameters<
    MessageMethods['claimBackgroundToolResults']
  >[0]): Promise<BackgroundToolResultClaim> {
    const requestedMessageId = messageId?.trim();
    const requestedGenerationId = generationId?.trim();
    if (
      (requestedMessageId != null &&
        (requestedMessageId.length === 0 || requestedMessageId.length > 256)) ||
      (batchId != null && (batchId.length === 0 || batchId.length > 128 || kind !== 'wakeup')) ||
      taskId.length === 0 ||
      taskId.length > 256 ||
      claimId.length === 0 ||
      claimId.length > 128 ||
      (requestedGenerationId != null &&
        (requestedGenerationId.length === 0 || requestedGenerationId.length > 256)) ||
      (requestedGenerationId != null && kind !== 'manual') ||
      (allowUnfinished && kind !== 'manual') ||
      (kind !== 'manual' && kind !== 'wakeup') ||
      !Number.isSafeInteger(limit) ||
      limit < 1 ||
      (maxMetadataChars != null &&
        (!Number.isSafeInteger(maxMetadataChars) || maxMetadataChars < 1))
    ) {
      throw new TypeError('Invalid background tool result claim');
    }
    const boundedLimit = Math.max(1, Math.min(MAX_BACKGROUND_TOOL_RESULT_BATCH, limit));
    const Message = mongoose.models.Message as Model<IMessage>;
    const row = await Message.findOne({
      user: userId,
      conversationId,
      ...(requestedMessageId != null
        ? { messageId: requestedMessageId }
        : {
            content: {
              $elemMatch: { 'tool_call.backgroundTask.taskId': taskId },
            },
          }),
    })
      .select({ content: 1, unfinished: 1, messageId: 1 })
      .sort({ createdAt: -1, _id: -1 })
      .lean<IMessage | null>();
    if (row == null) {
      if (requestedMessageId == null) {
        const escapedTaskId = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
        const handleRow = await Message.findOne({
          user: userId,
          conversationId,
          content: {
            $elemMatch: {
              type: 'tool_call',
              'tool_call.output': new RegExp(`"background_task_id"\\s*:\\s*"${escapedTaskId}"`),
              ...(agentId == null ? {} : agentOwnershipFilter('', agentId)),
            },
          },
        })
          .select({ content: 1 })
          .sort({ createdAt: -1, _id: -1 })
          .lean<IMessage | null>();
        const toolName =
          handleRow == null ? undefined : readBackgroundToolHandle(handleRow, taskId, agentId);
        if (toolName != null) {
          return { status: 'outcome_unknown', toolName };
        }
      }
      return { status: 'not_found' };
    }
    /** Only an owner-process manual poll that already retired automatic
     * delivery may consume a terminal receipt on an unfinished response.
     * Every other claimant waits for finalization, preventing a poll from
     * racing the automatic continuation while the parent generation runs. */
    if (row.unfinished === true && !(kind === 'manual' && allowUnfinished)) {
      return { status: 'not_ready' };
    }
    const resolvedMessageId = row.messageId;
    if (typeof resolvedMessageId !== 'string' || resolvedMessageId.length === 0) {
      return { status: 'not_found' };
    }
    const recoveredSource = requestedMessageId == null ? { messageId: resolvedMessageId } : {};
    const requestedClaim = readBackgroundToolResultClaim(row, taskId);
    const replaying =
      requestedClaim?.kind === kind &&
      requestedClaim.claimId === claimId &&
      requestedClaim.batchId === batchId;
    const candidates: string[] = [];
    const costs = new Map<string, number>();
    let receiptBacked = false;
    let requestedState: 'ready' | 'claimed' | 'missing' = 'missing';
    for (const part of row.content ?? []) {
      if (part == null || typeof part !== 'object' || Array.isArray(part)) {
        continue;
      }
      const task = (part as { tool_call?: { backgroundTask?: Record<string, unknown> } }).tool_call
        ?.backgroundTask;
      const partRecord = part as { agentId?: unknown; tool_call?: { agentId?: unknown } };
      const partAgentId = partRecord.agentId ?? partRecord.tool_call?.agentId;
      const candidateId = task?.taskId;
      if (typeof candidateId !== 'string') {
        continue;
      }
      const terminal = task?.status === 'completed' || task?.status === 'error';
      const wakeupEligible = kind !== 'wakeup' || task?.completionWakeup === true;
      const resultClaim = task?.resultClaim as
        | { kind?: unknown; claimId?: unknown; batchId?: unknown }
        | undefined;
      const replay =
        resultClaim?.kind === kind &&
        resultClaim.claimId === claimId &&
        resultClaim.batchId === batchId;
      const sameAgent =
        agentId == null ||
        partAgentId == null ||
        (typeof partAgentId === 'string' && partAgentId === agentId);
      /** A lost-receipt retry replays exactly its original assignment. It must
       * not absorb siblings that completed after the already-admitted input
       * was constructed, or those results would be claimed but never shown. */
      const claimable =
        terminal && wakeupEligible && sameAgent && (replaying ? replay : resultClaim == null);
      if (candidateId === taskId) {
        receiptBacked = task?.completionReceipt === true;
        if (claimable) {
          requestedState = 'ready';
        } else if (resultClaim != null) {
          requestedState = 'claimed';
        }
      }
      if (
        claimable &&
        (candidateId === taskId || task?.completionReceipt !== true) &&
        (candidateId === taskId || kind === 'wakeup') &&
        candidates.length < boundedLimit
      ) {
        candidates.push(candidateId);
      }
      if (claimable && (candidateId === taskId || candidates.includes(candidateId))) {
        const call = (part as { tool_call?: { id?: string } }).tool_call;
        if (typeof call?.id === 'string' && typeof task?.toolName === 'string') {
          const terminalStatus = task.status === 'error' ? 'error' : 'completed';
          costs.set(
            candidateId,
            JSON.stringify(
              backgroundResultMetadata({
                taskId: candidateId,
                toolCallId: call.id,
                toolName: task.toolName,
                status: task.cancelled === true ? 'cancelled' : terminalStatus,
              }),
            ).length + 1,
          );
        }
      }
    }
    if (requestedState === 'missing') {
      return { status: 'not_ready' };
    }
    if (requestedState === 'claimed') {
      return {
        status: 'claimed',
        ...(requestedClaim == null ? {} : { claim: requestedClaim }),
        ...recoveredSource,
      };
    }
    if (!candidates.includes(taskId)) {
      candidates.unshift(taskId);
      candidates.splice(boundedLimit);
    }
    if (!replaying) {
      /** A receipt lives on another document, so it cannot join this atomic
       * message-row batch. Keep its delivery task-local in both directions. */
      if (receiptBacked) candidates.splice(0, candidates.length, taskId);
      if (maxMetadataChars != null) {
        let remaining = maxMetadataChars - 1 - (costs.get(taskId) ?? maxMetadataChars);
        if (remaining < 0)
          throw new TypeError('Background result metadata exceeds its input budget');
        const admitted = candidates.filter((id) => {
          if (id === taskId) return true;
          const cost = costs.get(id) ?? maxMetadataChars;
          if (cost > remaining) return false;
          remaining -= cost;
          return true;
        });
        candidates.splice(0, candidates.length, ...admitted);
      }
    }
    const claimedAt = new Date();
    const claimStamp = {
      kind,
      claimId,
      claimedAt,
      ...(batchId != null && { batchId }),
      ...(kind === 'manual' && requestedGenerationId != null
        ? { generationId: requestedGenerationId }
        : {}),
    };
    const claimFilter: FilterQuery<IMessage> = {
      user: userId,
      conversationId,
      messageId: resolvedMessageId,
      ...(kind === 'manual' && allowUnfinished ? {} : { unfinished: { $ne: true } }),
      content: {
        $elemMatch: {
          type: 'tool_call',
          'tool_call.backgroundTask.taskId': taskId,
          'tool_call.backgroundTask.status': { $in: ['completed', 'error'] },
          ...(kind === 'wakeup' ? { 'tool_call.backgroundTask.completionWakeup': true } : {}),
          ...(replaying
            ? {
                'tool_call.backgroundTask.resultClaim.kind': kind,
                'tool_call.backgroundTask.resultClaim.claimId': claimId,
                'tool_call.backgroundTask.resultClaim.batchId': batchId ?? null,
              }
            : /** Missing OR stored null: the in-memory claimable scan, the
               * claim arrayFilters, and the settle stamp all treat a null
               * claim as unclaimed, and the subfield-preserving settle write
               * keeps a persisted null a whole-object rewrite used to drop.
               * `$exists: false` here would strand such a part as terminal
               * but permanently unclaimable. */
              { 'tool_call.backgroundTask.resultClaim': null }),
        },
      },
      ...(agentId != null
        ? {
            $expr: {
              $anyElementTrue: {
                $map: {
                  input: { $ifNull: ['$content', []] },
                  as: 'candidate',
                  in: {
                    $and: [
                      { $eq: ['$$candidate.tool_call.backgroundTask.taskId', taskId] },
                      {
                        $in: [
                          {
                            $ifNull: [
                              {
                                $ifNull: ['$$candidate.agentId', '$$candidate.tool_call.agentId'],
                              },
                              null,
                            ],
                          },
                          [null, agentId],
                        ],
                      },
                    ],
                  },
                },
              },
            },
          }
        : {}),
    };
    const updated = replaying
      ? await Message.findOne(claimFilter).select({ content: 1 }).lean<IMessage | null>()
      : await Message.findOneAndUpdate(
          claimFilter,
          /** Stamps the claim onto every part this pass admitted. The filtered
           * positional operator selects those parts by predicate, so the write
           * touches only them instead of re-emitting the whole content array, and
           * needs no read-modify-write. Amazon DocumentDB rejects the
           * aggregation-pipeline form this replaces. */
          { $set: { 'content.$[part].tool_call.backgroundTask.resultClaim': claimStamp } },
          {
            new: true,
            projection: { content: 1 },
            arrayFilters: [
              {
                'part.type': 'tool_call',
                'part.tool_call.backgroundTask.taskId': { $in: candidates },
                'part.tool_call.backgroundTask.status': { $in: ['completed', 'error'] },
                ...(kind === 'wakeup'
                  ? { 'part.tool_call.backgroundTask.completionWakeup': true }
                  : {}),
                $and: [
                  {
                    'part.tool_call.backgroundTask.resultClaim': null,
                  },
                  ...(agentId == null ? [] : [agentOwnershipFilter('part.', agentId)]),
                ],
              },
            ],
          },
        ).lean<IMessage | null>();
    if (updated == null) {
      return { status: 'not_ready' };
    }
    const results = parseBackgroundToolResults(updated, { kind, claimId, batchId });
    const competingClaim = readBackgroundToolResultClaim(updated, taskId);
    return results.some((result) => result.taskId === taskId)
      ? { status: 'acquired', results, ...recoveredSource }
      : {
          status: 'claimed',
          ...(competingClaim == null ? {} : { claim: competingClaim }),
          ...recoveredSource,
        };
  }

  /** Manual ownership is committed only after receipt arbitration completes. */
  async function confirmBackgroundToolResultClaim(
    input: Parameters<MessageMethods['confirmBackgroundToolResultClaim']>[0],
  ): Promise<boolean> {
    const Message = mongoose.models.Message as Model<IMessage>;
    const identity = {
      'tool_call.backgroundTask.taskId': input.taskId,
      'tool_call.backgroundTask.resultClaim.kind': 'manual',
      'tool_call.backgroundTask.resultClaim.claimId': input.claimId,
    };
    try {
      const confirmed = await Message.updateOne(
        {
          user: input.userId,
          conversationId: input.conversationId,
          messageId: input.messageId,
          content: { $elemMatch: identity },
        },
        {
          $set: { 'content.$[part].tool_call.backgroundTask.resultClaim.receiptReconciled': true },
        },
        {
          arrayFilters: [
            {
              'part.tool_call.backgroundTask.taskId': input.taskId,
              'part.tool_call.backgroundTask.resultClaim.kind': 'manual',
              'part.tool_call.backgroundTask.resultClaim.claimId': input.claimId,
            },
          ],
        },
      );
      return confirmed.matchedCount === 1;
    } catch (error) {
      // A lost write reply is not an uncommitted handoff. Read only the exact
      // manual claim, never manufacture success from another claimant.
      const committed = await Message.exists({
        user: input.userId,
        conversationId: input.conversationId,
        messageId: input.messageId,
        content: {
          $elemMatch: {
            ...identity,
            'tool_call.backgroundTask.resultClaim.receiptReconciled': true,
          },
        },
      });
      if (committed != null) return true;
      throw error;
    }
  }

  async function releaseBackgroundToolResultClaims({
    userId,
    conversationId,
    messageId,
    taskIds,
    allowMissingMessage,
    onlyIfUnreconciled,
    kind,
    claimId,
    batchId,
  }: {
    userId: string;
    conversationId: string;
    messageId: string;
    taskIds?: string[];
    /** Receipt-backed results can precede the message projection. */
    allowMissingMessage?: true;
    /** Manual rollback must not erase a committed receipt handoff. */
    onlyIfUnreconciled?: true;
    batchId?: string;
    kind: 'manual' | 'wakeup';
    claimId: string;
  }): Promise<boolean> {
    if (onlyIfUnreconciled === true && kind !== 'manual')
      throw new TypeError('Unreconciled rollback requires a manual claim');
    if (taskIds?.length === 0) {
      return true;
    }
    const Message = mongoose.models.Message as Model<IMessage>;
    /** Drops the claim stamp from every content part this claimant owns. The
     * filtered positional operator addresses those parts by predicate in one
     * atomic write, so no read-modify-write and no rewrite of untouched parts;
     * Amazon DocumentDB rejects the aggregation-pipeline form this replaces.
     * The filter requires a `content` array because the filtered positional
     * operator errors on a row without one, where the old pipeline's
     * `$ifNull` no-op'd — a legacy row with no array simply has no claims. */
    const updated = await Message.findOneAndUpdate(
      { user: userId, conversationId, messageId, content: { $type: 'array' } },
      { $unset: { 'content.$[part].tool_call.backgroundTask.resultClaim': 1 } },
      {
        new: true,
        projection: { content: 1 },
        arrayFilters: [
          {
            'part.tool_call.backgroundTask.resultClaim.kind': kind,
            'part.tool_call.backgroundTask.resultClaim.claimId': claimId,
            'part.tool_call.backgroundTask.resultClaim.batchId': batchId ?? null,
            ...(onlyIfUnreconciled === true && {
              'part.tool_call.backgroundTask.resultClaim.receiptReconciled': { $ne: true },
            }),
            ...(taskIds == null
              ? {}
              : { 'part.tool_call.backgroundTask.taskId': { $in: taskIds } }),
          },
        ],
      },
    ).lean<IMessage | null>();
    if (updated == null) {
      const arraylessRow = await Message.exists({
        user: userId,
        conversationId,
        messageId,
        content: { $not: { $type: 'array' } },
      });
      if (arraylessRow != null) return true;
      return (
        allowMissingMessage === true &&
        (await Message.exists({ user: userId, conversationId, messageId })) == null
      );
    }
    const remaining = parseBackgroundToolResults(updated, { kind, claimId, batchId });
    return taskIds == null
      ? remaining.length === 0
      : !remaining.some((result) => taskIds.includes(result.taskId));
  }

  /**
   * Updates a message and returns sanitized fields.
   */
  async function updateMessage(
    userId: string,
    message: { messageId: string; [key: string]: unknown },
    metadata?: { context?: string },
  ) {
    try {
      const { messageId, ...update } = message;
      delete update.privateText;
      delete update.privacyRevision;
      delete update.privateTextTokens;
      const updatedMessage = await writeMessage({ messageId, user: userId }, update, {
        upsert: false,
        unsetPrivateText: Object.prototype.hasOwnProperty.call(update, 'text'),
      });

      if (!updatedMessage) {
        throw new Error('Message not found or user not authorized.');
      }

      return {
        messageId: updatedMessage.messageId,
        conversationId: updatedMessage.conversationId,
        parentMessageId: updatedMessage.parentMessageId,
        sender: updatedMessage.sender,
        text: updatedMessage.text,
        isCreatedByUser: updatedMessage.isCreatedByUser,
        isUserSubmitted: updatedMessage.isUserSubmitted,
        userSubmittedPaths: updatedMessage.userSubmittedPaths,
        userSubmittedMessageFieldPaths: updatedMessage.userSubmittedMessageFieldPaths,
        tokenCount: updatedMessage.tokenCount,
        feedback: updatedMessage.feedback,
        endpoint: updatedMessage.endpoint,
        isTemporary: isTemporaryMessage(updatedMessage),
        langfuseSampled: updatedMessage.langfuseSampled,
        langfuseDestinationIds: updatedMessage.langfuseDestinationIds,
        langfuseRunId: updatedMessage.langfuseRunId,
      };
    } catch (err) {
      logger.error('Error updating message:', err);
      if (metadata?.context) {
        logger.info(`---\`updateMessage\` context: ${metadata.context}`);
      }
      throw err;
    }
  }

  /**
   * Atomically records one bounded parent-to-child control receipt on the
   * durable task input. Terminal receipt states are monotonic, and accepted
   * receipts are retained ahead of older terminal history when the bound fills.
   */
  async function recordSubagentTaskControlReceipt({
    userId,
    conversationId,
    taskId,
    tenantId,
    receipt,
  }: {
    userId: string;
    conversationId: string;
    taskId: string;
    tenantId?: string;
    receipt: NonNullable<NonNullable<IMessage['subagentTask']>['controlReceipts']>[number];
  }): Promise<boolean | 'unchanged' | 'conflict'> {
    const validActions = new Set(['steer', 'queue', 'interrupt', 'cancel', 'cancel_message']);
    const validStatuses = new Set(['reserved', 'accepted', 'applied', 'rejected', 'failed']);
    if (
      userId.length === 0 ||
      conversationId.length === 0 ||
      conversationId.length > 256 ||
      taskId.length === 0 ||
      taskId.length > 256 ||
      receipt.invocationId.length === 0 ||
      receipt.invocationId.length > 128 ||
      receipt.fingerprint.length === 0 ||
      receipt.fingerprint.length > 128 ||
      !validActions.has(receipt.action) ||
      !validStatuses.has(receipt.status) ||
      (receipt.controlId != null && receipt.controlId.length > 256) ||
      (receipt.message != null && receipt.message.length > MAX_SUBAGENT_CONTROL_MESSAGE_LENGTH) ||
      !Number.isFinite(receipt.createdAt.getTime()) ||
      !Number.isFinite(receipt.updatedAt.getTime())
    ) {
      throw new TypeError('Invalid subagent task control receipt');
    }
    const Message = mongoose.models.Message as Model<IMessage>;
    const recordsTerminalRejection =
      receipt.status === 'rejected' && receipt.reason === 'task_not_running';
    const identity = {
      user: userId,
      conversationId,
      ...(tenantId == null ? { tenantId: { $exists: false } } : { tenantId }),
      messageId: `${taskId}:user`,
      /** A genuinely new command can arrive after its task settles or its final
       * lease expires. Persist that authoritative rejection for retries; every
       * command that could still be applied remains fenced to a running task. */
      ...(recordsTerminalRejection
        ? { 'subagentTask.status': { $in: ['running', 'completed', 'error', 'cancelled'] } }
        : { 'subagentTask.status': 'running' }),
    };
    /** Amazon DocumentDB does not support aggregation-pipeline updates. Use a
     * bounded optimistic compare-and-swap: the read is small, the write uses
     * only plain operators, and concurrent writers retry rather than overwrite. */
    for (let attempt = 0; attempt < MAX_SUBAGENT_CONTROL_RECEIPT_CAS_ATTEMPTS; attempt += 1) {
      const currentMessage = await Message.findOne(identity)
        .select({ 'subagentTask.controlReceipts': 1, _id: 0 })
        .lean<Pick<IMessage, 'subagentTask'> | null>();
      if (currentMessage == null) return false;
      const current = currentMessage.subagentTask?.controlReceipts ?? [];
      const retained = retainSubagentControlReceipts(current, receipt);
      if (retained.status === 'conflict') return 'conflict';
      if (retained.status === 'unchanged') return 'unchanged';
      if (retained.status === 'capacity') return false;
      const next = retained.receipts;
      const currentFilter =
        currentMessage.subagentTask?.controlReceipts == null
          ? { 'subagentTask.controlReceipts': { $exists: false } }
          : { 'subagentTask.controlReceipts': current };
      const updated = await Message.findOneAndUpdate(
        { ...identity, ...currentFilter },
        { $set: { 'subagentTask.controlReceipts': next } },
        { new: false, projection: { messageId: 1 } },
      ).lean<{ messageId: string } | null>();
      if (updated != null) return true;
    }
    throw new Error('Subagent control receipt write contention exceeded its retry bound.');
  }

  /** Reads one bounded authoritative receipt by its exact durable task identity.
   * The stored projection is already capped, and no task/runtime metadata leaves
   * this method. Authorization remains part of the Mongo identity. */
  async function getSubagentTaskControlReceipt({
    userId,
    conversationId,
    taskId,
    invocationId,
    tenantId,
    activeOnly = false,
  }: {
    userId: string;
    conversationId: string;
    taskId: string;
    invocationId: string;
    tenantId?: string;
    activeOnly?: boolean;
  }): Promise<StoredSubagentControlReceipt | null> {
    if (
      userId.length === 0 ||
      conversationId.length === 0 ||
      conversationId.length > 256 ||
      taskId.length === 0 ||
      taskId.length > 256 ||
      invocationId.length === 0 ||
      invocationId.length > 128
    ) {
      throw new TypeError('Invalid subagent task control receipt identity');
    }
    const Message = mongoose.models.Message as Model<IMessage>;
    const input = await Message.findOne({
      ...(activeOnly ? activeExpirationFilter<IMessage>() : {}),
      user: userId,
      conversationId,
      ...(tenantId == null ? { tenantId: { $exists: false } } : { tenantId }),
      messageId: `${taskId}:user`,
      'subagentTask.controlReceipts.invocationId': invocationId,
    })
      .select({ 'subagentTask.controlReceipts': 1, _id: 0 })
      .lean<Pick<IMessage, 'subagentTask'> | null>();
    const receipt = input?.subagentTask?.controlReceipts?.find(
      (candidate) => candidate.invocationId === invocationId,
    );
    /** Reservations are a server-private at-most-once fence, not proof that a
     * control was applied. Public HTTP callers retry through the owning store. */
    return receipt?.status === 'reserved' ? null : (receipt ?? null);
  }

  /** Resolves one authoritative receipt after its live owner disappears. The
   * child conversation must still belong to the caller's parent thread, so a
   * task id learned in another chat cannot cross orchestration scopes. */
  async function getSubagentTaskControlReplay({
    userId,
    parentConversationId,
    taskId,
    invocationId,
    tenantId,
  }: {
    userId: string;
    parentConversationId: string;
    taskId: string;
    invocationId: string;
    tenantId?: string;
  }): Promise<{
    receipt: StoredSubagentControlReceipt;
    task: {
      taskId: string;
      threadId: string;
      subagentType: string;
      status: 'running' | 'completed' | 'error' | 'cancelled';
      resultAvailable: boolean;
      resultClaimed: boolean;
      pendingControls: number;
      createdAt: Date;
      updatedAt: Date;
    };
  } | null> {
    if (
      userId.length === 0 ||
      parentConversationId.length === 0 ||
      parentConversationId.length > 256 ||
      taskId.length === 0 ||
      taskId.length > 256 ||
      invocationId.length === 0 ||
      invocationId.length > 128
    ) {
      throw new TypeError('Invalid subagent task control replay identity');
    }
    const Message = mongoose.models.Message as Model<IMessage>;
    const input = await Message.findOne({
      user: userId,
      ...(tenantId == null ? { tenantId: { $exists: false } } : { tenantId }),
      messageId: `${taskId}:user`,
      'subagentTask.controlReceipts.invocationId': invocationId,
    })
      .select({
        conversationId: 1,
        createdAt: 1,
        updatedAt: 1,
        'subagentTask.status': 1,
        'subagentTask.controlReceipts': 1,
        _id: 0,
      })
      .lean<Pick<IMessage, 'conversationId' | 'createdAt' | 'updatedAt' | 'subagentTask'> | null>();
    const receipt = input?.subagentTask?.controlReceipts?.find(
      (candidate) => candidate.invocationId === invocationId,
    );
    const status = input?.subagentTask?.status;
    if (
      input == null ||
      receipt == null ||
      status == null ||
      input.createdAt == null ||
      input.updatedAt == null
    ) {
      return null;
    }
    const Conversation = mongoose.models.Conversation as Model<IConversation>;
    const conversationQuery = Conversation.findOne({
      user: userId,
      conversationId: input.conversationId,
      ...(tenantId == null ? { tenantId: { $exists: false } } : { tenantId }),
      'subagentThread.parentConversationId': parentConversationId,
      ...activeExpirationFilter<IConversation>(),
    })
      .select({ 'subagentThread.subagentType': 1, _id: 0 })
      .lean<Pick<IConversation, 'subagentThread'> | null>();
    const terminalQuery = Message.findOne({
      user: userId,
      conversationId: input.conversationId,
      ...(tenantId == null ? { tenantId: { $exists: false } } : { tenantId }),
      messageId: `${taskId}:assistant`,
      'subagentTask.status': { $in: ['completed', 'error', 'cancelled'] },
    })
      .select({ updatedAt: 1, 'subagentTask.status': 1, 'subagentTask.resultClaim': 1, _id: 0 })
      .lean<Pick<IMessage, 'updatedAt' | 'subagentTask'> | null>();
    const [conversation, terminal] = await Promise.all([conversationQuery, terminalQuery]);
    const subagentType = conversation?.subagentThread?.subagentType;
    if (subagentType == null || subagentType === '') return null;
    /** A committed cancel receipt is itself the authoritative cancellation
     * boundary. The terminal row is written asynchronously and may not exist if
     * the owner exits between those two durable commits. */
    const replayStatus =
      terminal?.subagentTask?.status ??
      (receipt.action === 'cancel' && receipt.status === 'applied' ? 'cancelled' : status);
    return {
      receipt,
      task: {
        taskId,
        threadId: input.conversationId,
        subagentType,
        status: replayStatus,
        resultAvailable: terminal != null,
        resultClaimed: terminal?.subagentTask?.resultClaim != null,
        pendingControls:
          input.subagentTask?.controlReceipts?.filter(
            (candidate) => candidate.status === 'accepted',
          ).length ?? 0,
        createdAt: input.createdAt,
        updatedAt:
          terminal?.updatedAt ??
          (receipt.action === 'cancel' && receipt.status === 'applied'
            ? receipt.updatedAt
            : input.updatedAt),
      },
    };
  }

  /** Atomically assigns one durable terminal child result to either its
   * explicit poller or one idempotent automatic wakeup delivery. */
  async function claimSubagentTaskResult({
    userId,
    conversationId,
    taskId,
    kind,
    claimId,
  }: {
    userId: string;
    conversationId: string;
    taskId: string;
    kind: 'manual' | 'wakeup';
    claimId: string;
  }): Promise<SubagentTaskResultClaim> {
    if (
      taskId.length === 0 ||
      taskId.length > 256 ||
      conversationId.length === 0 ||
      conversationId.length > 256 ||
      (kind !== 'manual' && kind !== 'wakeup') ||
      claimId.length === 0 ||
      claimId.length > 128
    ) {
      throw new TypeError('Invalid subagent task result claim');
    }
    const Message = mongoose.models.Message as Model<IMessage>;
    const messageId = `${taskId}:assistant`;
    const terminal = ['completed', 'error', 'cancelled'];
    const claim = {
      kind,
      claimId,
      claimedAt: new Date(),
    };
    const claimable = {
      $or: [
        { 'subagentTask.resultClaim': { $exists: false } },
        {
          'subagentTask.resultClaim.kind': kind,
          'subagentTask.resultClaim.claimId': claimId,
        },
        ...(kind === 'manual'
          ? [
              {
                'subagentTask.resultClaim.kind': { $exists: false },
                'subagentTask.resultClaim.claimId': claimId,
              },
            ]
          : []),
      ],
    };
    const projection = {
      messageId: 1,
      conversationId: 1,
      parentMessageId: 1,
      sender: 1,
      text: 1,
      error: 1,
      createdAt: 1,
      updatedAt: 1,
      subagentTask: 1,
    };
    const acquired = await Message.findOneAndUpdate(
      {
        user: userId,
        conversationId,
        messageId,
        'subagentTask.status': { $in: terminal },
        ...claimable,
      },
      { $set: { 'subagentTask.resultClaim': claim } },
      { new: true, projection },
    ).lean<IMessage | null>();
    if (acquired != null) {
      return { status: 'acquired', message: acquired };
    }
    const existing = await Message.findOne({
      user: userId,
      conversationId,
      messageId,
      'subagentTask.status': { $in: terminal },
    })
      .select(projection)
      .lean<IMessage | null>();
    return existing == null ? { status: 'not_found' } : { status: 'claimed', message: existing };
  }

  /** Releases only the exact consumer assignment. This is used when a
   * pre-admission automatic continuation is definitively rejected, allowing a
   * later manual poll (or the same delivery retry) to claim the durable result. */
  async function releaseSubagentTaskResultClaim({
    userId,
    conversationId,
    taskId,
    kind,
    claimId,
  }: {
    userId: string;
    conversationId: string;
    taskId: string;
    kind: 'manual' | 'wakeup';
    claimId: string;
  }): Promise<boolean> {
    if (
      taskId.length === 0 ||
      taskId.length > 256 ||
      conversationId.length === 0 ||
      conversationId.length > 256 ||
      (kind !== 'manual' && kind !== 'wakeup') ||
      claimId.length === 0 ||
      claimId.length > 128
    ) {
      throw new TypeError('Invalid subagent task result claim release');
    }
    const Message = mongoose.models.Message as Model<IMessage>;
    const result = await Message.updateOne(
      {
        user: userId,
        conversationId,
        messageId: `${taskId}:assistant`,
        'subagentTask.resultClaim.kind': kind,
        'subagentTask.resultClaim.claimId': claimId,
      },
      { $unset: { 'subagentTask.resultClaim': 1 } },
    );
    return result.modifiedCount === 1;
  }

  /**
   * Retrieves messages from the database.
   */
  async function getMessages(
    filter: FilterQuery<IMessage>,
    select?: string,
    options: MessageQueryOptions = {},
  ) {
    try {
      const Message = mongoose.models.Message as Model<IMessage>;
      const query = Message.find(filter);
      if (select) {
        query.select(select);
      }
      if (options.sort !== false) {
        query.sort(options.sort ?? { createdAt: 1 });
      }
      if (options.limit != null && options.limit > 0) {
        query.limit(options.limit);
      }

      return await query.lean<IMessage[]>();
    } catch (err) {
      logger.error('Error getting messages:', err);
      throw err;
    }
  }

  /**
   * Reads the fixed public child-thread projection and truncates text inside
   * MongoDB so oversized persisted messages are never materialized by the API.
   */
  async function getMessagesForSubagentThreadView(input: {
    user: string;
    conversationId: string;
    tenantId?: string;
    selectedTaskId?: string;
    beforeMessageId?: string;
    limit: number;
    textCodePointLimit: number;
  }): Promise<SubagentThreadViewMessageRecord[]> {
    try {
      const Message = mongoose.models.Message as Model<IMessage>;
      const transcriptJsonBytes = {
        $strLenBytes: {
          $convert: {
            input: '$subagentTranscript.messagesJson',
            to: 'string',
            onError: '',
            onNull: '',
          },
        },
      };
      const transcriptIsString = {
        $eq: [{ $type: '$subagentTranscript.messagesJson' }, 'string'],
      };
      const activityProjectionJsonBytes = {
        $strLenBytes: {
          $convert: {
            input: '$subagentActivityProjection.activityJson',
            to: 'string',
            onError: '',
            onNull: '',
          },
        },
      };
      const activityProjectionIsString = {
        $eq: [{ $type: '$subagentActivityProjection.activityJson' }, 'string'],
      };
      const activityProjectionAvailable = {
        $and: [
          { $in: ['$subagentActivityProjection.version', [1, 2]] },
          {
            $eq: ['$messageId', { $concat: ['$subagentActivityProjection.taskId', ':assistant'] }],
          },
          '$_subagentActivityProjectionSourceIsString',
          {
            $lte: [
              '$_subagentActivityProjectionSourceBytes',
              SUBAGENT_ACTIVITY_PROJECTION_SOURCE_BYTE_LIMIT,
            ],
          },
        ],
      };
      const transcriptAvailable = {
        $and: [
          '$_subagentTranscriptSourceIsString',
          { $eq: ['$messageId', { $concat: ['$subagentTranscript.taskId', ':assistant'] }] },
          {
            $lte: ['$_subagentTranscriptSourceBytes', SUBAGENT_TRANSCRIPT_SOURCE_BYTE_LIMIT],
          },
        ],
      };
      // Legacy reprojection is optional: retain the usable projection until the
      // API validates the current input boundary against the bounded transcript.
      const legacySteeringTranscriptAvailable = {
        $and: [
          { $eq: ['$subagentActivityProjection.version', 1] },
          {
            $cond: [
              transcriptAvailable,
              {
                $gte: [
                  { $indexOfBytes: ['$subagentTranscript.messagesJson', '"source":"steer"'] },
                  0,
                ],
              },
              false,
            ],
          },
        ],
      };
      const boundedString = (path: string, codePointLimit: number) => ({
        $substrCP: [
          {
            $cond: [{ $eq: [{ $type: path }, 'string'] }, path, ''],
          },
          0,
          codePointLimit,
        ],
      });
      const stringProjectionTruncated = (path: string, codePointLimit: number) => ({
        $gt: [
          {
            $strLenCP: {
              $cond: [{ $eq: [{ $type: path }, 'string'] }, path, ''],
            },
          },
          codePointLimit,
        ],
      });
      const boundedStringArray = (path: string) => ({
        $map: {
          input: {
            $slice: [
              { $cond: [{ $isArray: path }, path, []] },
              SUBAGENT_MESSAGE_ACTIVITY_LABEL_IDS_LIMIT,
            ],
          },
          as: 'value',
          in: boundedString('$$value', SUBAGENT_MESSAGE_ACTIVITY_ID_CODE_POINT_LIMIT),
        },
      });
      const boundedControlReceipt = {
        invocationId: boundedString(
          '$$receipt.invocationId',
          SUBAGENT_VIEW_CONTROL_STRING_CODE_POINT_LIMIT,
        ),
        controlId: {
          $cond: [
            { $eq: [{ $type: '$$receipt.controlId' }, 'string'] },
            boundedString('$$receipt.controlId', SUBAGENT_VIEW_CONTROL_STRING_CODE_POINT_LIMIT),
            null,
          ],
        },
        action: '$$receipt.action',
        status: '$$receipt.status',
        createdAt: '$$receipt.createdAt',
        updatedAt: '$$receipt.updatedAt',
        boundary: '$$receipt.boundary',
        reason: {
          $cond: [
            { $eq: [{ $type: '$$receipt.reason' }, 'string'] },
            boundedString('$$receipt.reason', SUBAGENT_VIEW_CONTROL_STRING_CODE_POINT_LIMIT),
            null,
          ],
        },
        message: {
          $cond: [
            { $eq: [{ $type: '$$receipt.message' }, 'string'] },
            boundedString('$$receipt.message', MAX_SUBAGENT_CONTROL_MESSAGE_LENGTH),
            null,
          ],
        },
        messageTruncated: {
          $or: [
            { $eq: ['$$receipt.messageTruncated', true] },
            stringProjectionTruncated('$$receipt.message', MAX_SUBAGENT_CONTROL_MESSAGE_LENGTH),
          ],
        },
      };
      const boundedSubagentTask = {
        $cond: [
          { $eq: [{ $type: '$subagentTask' }, 'object'] },
          {
            status: '$subagentTask.status',
            controlReceipts: {
              $let: {
                vars: {
                  visible: {
                    $filter: {
                      input: {
                        $cond: [
                          { $isArray: '$subagentTask.controlReceipts' },
                          '$subagentTask.controlReceipts',
                          [],
                        ],
                      },
                      as: 'receipt',
                      cond: { $ne: ['$$receipt.status', 'reserved'] },
                    },
                  },
                },
                in: {
                  $let: {
                    vars: {
                      accepted: {
                        $slice: [
                          {
                            $filter: {
                              input: '$$visible',
                              as: 'receipt',
                              cond: { $eq: ['$$receipt.status', 'accepted'] },
                            },
                          },
                          SUBAGENT_VIEW_CONTROL_RECEIPT_LIMIT,
                        ],
                      },
                      terminal: {
                        $filter: {
                          input: '$$visible',
                          as: 'receipt',
                          cond: { $ne: ['$$receipt.status', 'accepted'] },
                        },
                      },
                    },
                    in: {
                      $map: {
                        input: {
                          $concatArrays: [
                            '$$accepted',
                            {
                              $let: {
                                vars: {
                                  allowance: {
                                    $subtract: [
                                      SUBAGENT_VIEW_CONTROL_RECEIPT_LIMIT,
                                      { $size: '$$accepted' },
                                    ],
                                  },
                                },
                                in: {
                                  $cond: [
                                    { $gt: ['$$allowance', 0] },
                                    { $slice: ['$$terminal', { $multiply: [-1, '$$allowance'] }] },
                                    [],
                                  ],
                                },
                              },
                            },
                          ],
                        },
                        as: 'receipt',
                        in: boundedControlReceipt,
                      },
                    },
                  },
                },
              },
            },
            controlReceiptsProjectionTruncated: {
              $gt: [
                {
                  $size: {
                    $filter: {
                      input: {
                        $cond: [
                          { $isArray: '$subagentTask.controlReceipts' },
                          '$subagentTask.controlReceipts',
                          [],
                        ],
                      },
                      as: 'receipt',
                      cond: { $ne: ['$$receipt.status', 'reserved'] },
                    },
                  },
                },
                SUBAGENT_VIEW_CONTROL_RECEIPT_LIMIT,
              ],
            },
          },
          null,
        ],
      };
      /** Mixed-typed content metadata must be type-gated before projection, or a
       *  malformed part could tunnel arbitrarily large values past the byte cap
       *  through a passthrough field. `$type`-based checks stay DocumentDB-safe. */
      const boundedNumber = (path: string) => ({
        $cond: [{ $in: [{ $type: path }, ['int', 'long', 'double', 'decimal']] }, path, null],
      });
      const boundedBoolean = (path: string) => ({
        $cond: [{ $eq: [{ $type: path }, 'bool'] }, path, null],
      });
      const boundedEnum = (path: string, allowed: string[]) => ({
        $cond: [{ $in: [path, allowed] }, path, null],
      });
      /** Estimated serialized bytes for one already-clipped activity item; the
       *  constants cover the non-string JSON envelope per item type. This is a
       *  BSON-transfer budget: `$strLenBytes` measures exactly what MongoDB
       *  ships to the API. JSON escaping can expand strings after transfer,
       *  which the API bounds precisely — `boundActivity` in
       *  `packages/api/src/agents/activity.ts` re-fits the same array to 64KB
       *  of `JSON.stringify` output before anything reaches a response. */
      const activityItemBytes = (item: string) => ({
        $switch: {
          branches: [
            {
              case: { $eq: [`${item}.type`, 'writing'] },
              then: { $add: [{ $strLenBytes: `${item}.text` }, 64] },
            },
            {
              case: { $eq: [`${item}.type`, 'activity_label'] },
              then: {
                $add: [
                  { $strLenBytes: `${item}.label` },
                  {
                    $reduce: {
                      input: {
                        $concatArrays: [
                          {
                            $cond: [{ $isArray: `${item}.toolCallIds` }, `${item}.toolCallIds`, []],
                          },
                          { $cond: [{ $isArray: `${item}.agentIds` }, `${item}.agentIds`, []] },
                        ],
                      },
                      initialValue: 0,
                      in: { $add: ['$$value', { $strLenBytes: '$$this' }, 8] },
                    },
                  },
                  512,
                ],
              },
            },
            {
              case: { $eq: [`${item}.type`, 'tool'] },
              then: {
                $add: [
                  { $strLenBytes: `${item}.input` },
                  { $strLenBytes: `${item}.output` },
                  { $strLenBytes: `${item}.name` },
                  { $strLenBytes: `${item}.toolCallId` },
                  192,
                ],
              },
            },
          ],
          default: 32,
        },
      });
      /** Newest-first fit into the aggregate budget, so raising per-item limits
       *  cannot multiply into megabytes per row before the API's own trims run. */
      const budgetedActivity = (clipped: Record<string, unknown>) => ({
        $reverseArray: {
          $let: {
            vars: {
              fitted: {
                $reduce: {
                  input: { $reverseArray: clipped },
                  initialValue: { items: [] as never[], bytes: 0, done: false },
                  in: {
                    $let: {
                      vars: { size: activityItemBytes('$$this') },
                      in: {
                        $cond: [
                          {
                            $or: [
                              '$$value.done',
                              {
                                $gt: [
                                  { $add: ['$$value.bytes', '$$size'] },
                                  SUBAGENT_MESSAGE_ACTIVITY_TOTAL_BYTE_LIMIT,
                                ],
                              },
                            ],
                          },
                          /* The retained timeline must be a contiguous newest
                             suffix: once one entry does not fit, older entries
                             are not allowed to fill the gap around it. */
                          { items: '$$value.items', bytes: '$$value.bytes', done: true },
                          {
                            items: { $concatArrays: ['$$value.items', ['$$this']] },
                            bytes: { $add: ['$$value.bytes', '$$size'] },
                            done: false,
                          },
                        ],
                      },
                    },
                  },
                },
              },
            },
            in: '$$fitted.items',
          },
        },
      });
      const activityBytesOverBudget = (clipped: Record<string, unknown>) => ({
        $gt: [
          {
            $reduce: {
              input: clipped,
              initialValue: 0,
              in: { $add: ['$$value', activityItemBytes('$$this')] },
            },
          },
          SUBAGENT_MESSAGE_ACTIVITY_TOTAL_BYTE_LIMIT,
        ],
      });
      const clippedActivityContent = {
        $filter: {
          input: {
            $map: {
              input: {
                $slice: [
                  { $cond: [{ $isArray: '$content' }, '$content', []] },
                  -SUBAGENT_MESSAGE_ACTIVITY_ITEM_LIMIT,
                ],
              },
              as: 'part',
              in: {
                $switch: {
                  branches: [
                    {
                      case: { $eq: ['$$part.type', 'text'] },
                      then: {
                        type: 'writing',
                        text: boundedString(
                          '$$part.text',
                          SUBAGENT_MESSAGE_ACTIVITY_TEXT_CODE_POINT_LIMIT,
                        ),
                        textTruncated: stringProjectionTruncated(
                          '$$part.text',
                          SUBAGENT_MESSAGE_ACTIVITY_TEXT_CODE_POINT_LIMIT,
                        ),
                      },
                    },
                    {
                      case: { $in: ['$$part.type', ['think', 'reasoning']] },
                      then: { type: 'reasoning' },
                    },
                    {
                      case: { $eq: ['$$part.type', 'activity_label'] },
                      then: {
                        type: 'activity_label',
                        label: boundedString(
                          '$$part.activity_label',
                          SUBAGENT_MESSAGE_ACTIVITY_LABEL_CODE_POINT_LIMIT,
                        ),
                        labelType: boundedEnum('$$part.activity_label_type', ['phase']),
                        toolCallIds: boundedStringArray('$$part.tool_call_ids'),
                        activityStartIndex: boundedNumber('$$part.activity_start_index'),
                        activityEndIndex: boundedNumber('$$part.activity_end_index'),
                        activityCount: boundedNumber('$$part.activity_count'),
                        agentIds: boundedStringArray('$$part.agent_ids'),
                        status: boundedEnum('$$part.status', ['ok', 'partial', 'failed']),
                        pending: boundedBoolean('$$part.pending'),
                        labelTruncated: {
                          $or: [
                            stringProjectionTruncated(
                              '$$part.activity_label',
                              SUBAGENT_MESSAGE_ACTIVITY_LABEL_CODE_POINT_LIMIT,
                            ),
                            {
                              $gt: [
                                {
                                  $size: {
                                    $cond: [
                                      { $isArray: '$$part.tool_call_ids' },
                                      '$$part.tool_call_ids',
                                      [],
                                    ],
                                  },
                                },
                                SUBAGENT_MESSAGE_ACTIVITY_LABEL_IDS_LIMIT,
                              ],
                            },
                            {
                              $gt: [
                                {
                                  $size: {
                                    $cond: [
                                      { $isArray: '$$part.agent_ids' },
                                      '$$part.agent_ids',
                                      [],
                                    ],
                                  },
                                },
                                SUBAGENT_MESSAGE_ACTIVITY_LABEL_IDS_LIMIT,
                              ],
                            },
                          ],
                        },
                      },
                    },
                    {
                      case: { $eq: ['$$part.type', 'tool_call'] },
                      then: {
                        type: 'tool',
                        toolCallId: boundedString(
                          '$$part.tool_call.id',
                          SUBAGENT_MESSAGE_ACTIVITY_ID_CODE_POINT_LIMIT,
                        ),
                        name: boundedString(
                          '$$part.tool_call.name',
                          SUBAGENT_MESSAGE_ACTIVITY_ID_CODE_POINT_LIMIT,
                        ),
                        input: boundedString(
                          '$$part.tool_call.args',
                          SUBAGENT_MESSAGE_ACTIVITY_TOOL_INPUT_CODE_POINT_LIMIT,
                        ),
                        output: boundedString(
                          '$$part.tool_call.output',
                          SUBAGENT_MESSAGE_ACTIVITY_TOOL_OUTPUT_CODE_POINT_LIMIT,
                        ),
                        progress: boundedNumber('$$part.tool_call.progress'),
                        runStepStatus: boundedEnum('$$part.tool_call.runStepStatus', [
                          'running',
                          'completed',
                          'failed',
                          'cancelled',
                        ]),
                        inputValidationError: boundedBoolean(
                          '$$part.tool_call.inputValidationError',
                        ),
                        inputTruncated: stringProjectionTruncated(
                          '$$part.tool_call.args',
                          SUBAGENT_MESSAGE_ACTIVITY_TOOL_INPUT_CODE_POINT_LIMIT,
                        ),
                        outputTruncated: stringProjectionTruncated(
                          '$$part.tool_call.output',
                          SUBAGENT_MESSAGE_ACTIVITY_TOOL_OUTPUT_CODE_POINT_LIMIT,
                        ),
                      },
                    },
                  ],
                  default: null,
                },
              },
            },
          },
          as: 'activity',
          cond: { $ne: ['$$activity', null] },
        },
      };
      const boundedActivityContent = budgetedActivity(clippedActivityContent);
      type ActivitySourceProjection = WithNullSentinels<
        Pick<
          SubagentThreadViewMessageRecord,
          | 'messageId'
          | 'subagentTranscript'
          | 'subagentActivityProjectionJson'
          | 'subagentActivityProjectionTruncated'
        >,
        | 'subagentTranscript'
        | 'subagentActivityProjectionJson'
        | 'subagentActivityProjectionTruncated'
      >;
      const boundedMessageProjection = {
        _id: 0,
        messageId: 1,
        parentMessageId: 1,
        isCreatedByUser: 1,
        text: {
          $substrCP: [{ $ifNull: ['$text', ''] }, 0, input.textCodePointLimit],
        },
        textProjectionTruncated: {
          $gt: [{ $strLenCP: { $ifNull: ['$text', ''] } }, input.textCodePointLimit],
        },
        createdAt: 1,
        error: 1,
        unfinished: 1,
        contentRecoveryAvailable: {
          $and: [
            { $eq: [{ $ifNull: ['$subagentContent.version', 0] }, 1] },
            { $ne: [{ $ifNull: ['$subagentContent.deleted', false] }, true] },
          ],
        },
        subagentTranscriptProjectionTruncated: {
          $cond: [{ $ne: [{ $type: '$subagentTranscript.messagesJson' }, 'missing'] }, true, null],
        },
        subagentActivity: boundedActivityContent,
        subagentActivityProjectionTruncated: {
          $or: [
            {
              $gt: [
                {
                  $size: { $cond: [{ $isArray: '$content' }, '$content', []] },
                },
                SUBAGENT_MESSAGE_ACTIVITY_ITEM_LIMIT,
              ],
            },
            activityBytesOverBudget(clippedActivityContent),
          ],
        },
        subagentTask: boundedSubagentTask,
        subagentTriggerProjection: {
          $cond: [
            { $eq: ['$subagentTriggerProjection.version', 1] },
            {
              version: 1,
              eventType: boundedString(
                '$subagentTriggerProjection.eventType',
                SUBAGENT_MESSAGE_ACTIVITY_ID_CODE_POINT_LIMIT,
              ),
              sourceType: boundedString(
                '$subagentTriggerProjection.sourceType',
                SUBAGENT_MESSAGE_ACTIVITY_ID_CODE_POINT_LIMIT,
              ),
              occurredAt: '$subagentTriggerProjection.occurredAt',
              expectedActionToolName: {
                $cond: [
                  {
                    $eq: [{ $type: '$subagentTriggerProjection.expectedActionToolName' }, 'string'],
                  },
                  boundedString(
                    '$subagentTriggerProjection.expectedActionToolName',
                    SUBAGENT_MESSAGE_ACTIVITY_ID_CODE_POINT_LIMIT,
                  ),
                  null,
                ],
              },
            },
            null,
          ],
        },
      };
      const sourceMetadataProjection = {
        _subagentTranscriptSourceBytes: transcriptJsonBytes,
        _subagentTranscriptSourceIsString: transcriptIsString,
        _subagentActivityProjectionSourceBytes: activityProjectionJsonBytes,
        _subagentActivityProjectionSourceIsString: activityProjectionIsString,
      };
      const activitySourcePayload = {
        subagentActivityProjectionJson: {
          $cond: [activityProjectionAvailable, '$subagentActivityProjection.activityJson', null],
        },
        subagentActivityProjectionTruncated: {
          $cond: [activityProjectionAvailable, '$subagentActivityProjection.truncated', null],
        },
        subagentTranscript: {
          $cond: [
            {
              $and: [
                transcriptAvailable,
                {
                  $or: [
                    { $eq: [activityProjectionAvailable, false] },
                    legacySteeringTranscriptAvailable,
                  ],
                },
              ],
            },
            {
              taskId: '$subagentTranscript.taskId',
              mode: '$subagentTranscript.mode',
              messagesJson: '$subagentTranscript.messagesJson',
            },
            null,
          ],
        },
      };
      const activitySourceProjection = {
        _id: 0,
        messageId: 1,
        ...activitySourcePayload,
      };
      const baseMatch = {
        user: input.user,
        conversationId: input.conversationId,
        ...(input.tenantId == null
          ? { tenantId: { $exists: false } }
          : { tenantId: input.tenantId }),
      };
      const anchor =
        input.beforeMessageId == null
          ? null
          : await Message.findOne({ ...baseMatch, messageId: input.beforeMessageId })
              .select('_id createdAt')
              .lean<Pick<IMessage, '_id' | 'createdAt'>>();
      if (input.beforeMessageId != null && anchor == null) return [];
      const pageMatch =
        anchor == null
          ? baseMatch
          : {
              ...baseMatch,
              $or: [
                { createdAt: { $lt: anchor.createdAt } },
                { createdAt: anchor.createdAt, _id: { $lte: anchor._id } },
              ],
            };
      /** Keep rows as independent MongoDB results. A `$facet` would combine the
       * complete page into one BSON document and could exceed MongoDB's 16 MiB
       * document limit before the API applies its smaller public byte budget. */
      const messagesPromise = Message.aggregate<ProjectedSubagentThreadViewMessage>([
        { $match: pageMatch },
        { $sort: { createdAt: -1, _id: -1 } },
        { $limit: input.limit },
        { $project: boundedMessageProjection },
      ]);
      const recentSourcesPromise = Message.aggregate<ActivitySourceProjection>([
        { $match: pageMatch },
        { $sort: { createdAt: -1, _id: -1 } },
        { $limit: SUBAGENT_ACTIVITY_SOURCE_CANDIDATE_LIMIT },
        {
          $match: {
            ...(input.selectedTaskId == null
              ? {}
              : { messageId: { $ne: `${input.selectedTaskId}:assistant` } }),
            $or: [
              { 'subagentActivityProjection.activityJson': { $exists: true } },
              { 'subagentTranscript.messagesJson': { $exists: true } },
            ],
          },
        },
        { $addFields: sourceMetadataProjection },
        {
          $match: {
            $expr: {
              $or: [
                {
                  $and: [
                    activityProjectionAvailable,
                    {
                      $eq: [
                        '$messageId',
                        { $concat: ['$subagentActivityProjection.taskId', ':assistant'] },
                      ],
                    },
                  ],
                },
                {
                  $and: [
                    transcriptAvailable,
                    {
                      $eq: [
                        '$messageId',
                        { $concat: ['$subagentTranscript.taskId', ':assistant'] },
                      ],
                    },
                  ],
                },
              ],
            },
          },
        },
        { $limit: SUBAGENT_TRANSCRIPT_PAGE_LIMIT - (input.selectedTaskId == null ? 0 : 1) },
        { $project: activitySourceProjection },
      ]);
      /** One read replaces the unsupported `$facet` while keeping its guarantee:
       * the bounded message fields and the source payload for each selected row
       * come from the same document version, so a transcript persisted between
       * two separate reads can never yield a message without its source. Rows
       * stay independent results, so no combined document approaches the 16 MiB
       * limit the surrounding reads already avoid. Only operators Amazon
       * DocumentDB accepts are used. */
      const selectedProjectionPromise =
        input.selectedTaskId == null
          ? Promise.resolve({
              selectedMessages: [] as ProjectedSubagentThreadViewMessage[],
              selectedSources: [] as ActivitySourceProjection[],
            })
          : Message.aggregate<
              ProjectedSubagentThreadViewMessage & {
                _selectedSource: ActivitySourceProjection | null;
              }
            >([
              {
                $match: {
                  ...baseMatch,
                  messageId: {
                    $in: [`${input.selectedTaskId}:user`, `${input.selectedTaskId}:assistant`],
                  },
                },
              },
              { $limit: 2 },
              { $addFields: sourceMetadataProjection },
              {
                $project: {
                  ...boundedMessageProjection,
                  _selectedSource: {
                    $cond: [
                      {
                        $and: [
                          { $eq: ['$messageId', `${input.selectedTaskId}:assistant`] },
                          {
                            $or: [
                              {
                                $and: [
                                  {
                                    $eq: [
                                      '$subagentActivityProjection.taskId',
                                      input.selectedTaskId,
                                    ],
                                  },
                                  activityProjectionAvailable,
                                ],
                              },
                              {
                                $and: [
                                  { $eq: ['$subagentTranscript.taskId', input.selectedTaskId] },
                                  transcriptAvailable,
                                ],
                              },
                            ],
                          },
                        ],
                      },
                      { messageId: '$messageId', ...activitySourcePayload },
                      null,
                    ],
                  },
                },
              },
            ]).then((rows) => {
              const selectedSources: ActivitySourceProjection[] = [];
              const selectedMessages = rows.map(({ _selectedSource, ...message }) => {
                if (_selectedSource != null) {
                  selectedSources.push(_selectedSource);
                }
                return message;
              });
              return { selectedMessages, selectedSources };
            });
      const [messages, recentSources, selectedProjection] = await Promise.all([
        messagesPromise,
        recentSourcesPromise,
        selectedProjectionPromise,
      ]);
      const sourcesByMessageId = new Map(
        [...selectedProjection.selectedSources, ...recentSources].map((record) => [
          record.messageId,
          record,
        ]),
      );
      /** The page rows come from an independent concurrent read; for the
       * selected task, the single-snapshot pair is authoritative — a page
       * duplicate can predate the source read and claim a transcript that
       * `selectedSources` does not carry. Replace duplicates in place (keeping
       * page order) instead of discarding the snapshot version. */
      const selectedByMessageId = new Map(
        selectedProjection.selectedMessages.map((message) => [message.messageId, message]),
      );
      for (let index = 0; index < messages.length; index += 1) {
        const snapshot = selectedByMessageId.get(messages[index].messageId);
        if (snapshot != null) {
          messages[index] = snapshot;
          selectedByMessageId.delete(snapshot.messageId);
        }
      }
      for (const message of selectedByMessageId.values()) {
        messages.push(message);
      }
      return messages.map((row) => {
        const message = pruneProjectedThreadViewMessage(row);
        const source = sourcesByMessageId.get(message.messageId);
        if (source == null) return message;
        const projected = { ...message };
        if (source.subagentActivityProjectionJson != null) {
          delete projected.subagentTranscriptProjectionTruncated;
          return {
            ...projected,
            subagentActivityProjectionJson: source.subagentActivityProjectionJson,
            ...(source.subagentTranscript == null
              ? {}
              : { subagentTranscript: source.subagentTranscript }),
            ...(source.subagentActivityProjectionTruncated === true
              ? { subagentActivityProjectionTruncated: true }
              : {}),
          };
        }
        if (source.subagentTranscript == null) return message;
        delete projected.subagentTranscriptProjectionTruncated;
        return { ...projected, subagentTranscript: source.subagentTranscript };
      });
    } catch (err) {
      logger.error('Error getting bounded subagent thread messages:', err);
      throw err;
    }
  }

  /** Returns newest bounded task outcomes for every selected child in two
   * constant-size batch reads. The first read guarantees one latest task per
   * child; the second caps recent source rows before any grouping accumulator.
   * This avoids both N+1 reads and newer top-N accumulators that DocumentDB 5
   * does not support. */
  async function listSubagentTasksForThreads(input: {
    user: string;
    conversationIds: string[];
    tenantId?: string;
    limitPerThread: number;
  }): Promise<ParentSubagentTaskRecord[]> {
    if (input.conversationIds.length === 0) {
      return [];
    }
    const Message = mongoose.models.Message as Model<IMessage>;
    const match = {
      user: input.user,
      conversationId: { $in: input.conversationIds },
      ...(input.tenantId == null ? { tenantId: { $exists: false } } : { tenantId: input.tenantId }),
      messageId: { $regex: /:(user|assistant)$/ },
    };
    const taskProjection = {
      messageId: '$messageId',
      createdAt: '$createdAt',
      occurrenceId: '$_id',
      statusDerived: {
        $eq: [{ $ifNull: ['$subagentTask.status', null] }, null],
      },
      status: {
        $ifNull: [
          '$subagentTask.status',
          {
            $cond: [
              { $regexMatch: { input: '$messageId', regex: /:assistant$/ } },
              {
                $cond: [
                  { $eq: ['$error', true] },
                  'error',
                  { $cond: [{ $eq: ['$unfinished', true] }, 'cancelled', 'completed'] },
                ],
              },
              'running',
            ],
          },
        ],
      },
    };
    const sourceLimit = Math.min(
      4096,
      Math.max(
        input.conversationIds.length,
        input.conversationIds.length * input.limitPerThread * 2,
      ),
    );
    type AggregateRecord = ParentSubagentTaskRecord & { sourceRows?: number };
    const compareOccurrenceIds = (left?: Types.ObjectId, right?: Types.ObjectId): number => {
      const leftValue = left?.toHexString() ?? '';
      const rightValue = right?.toHexString() ?? '';
      if (leftValue === rightValue) return 0;
      return leftValue > rightValue ? 1 : -1;
    };
    const taskTimestamp = (value: Date | undefined): number =>
      value == null ? Number.NEGATIVE_INFINITY : value.getTime();
    const [latestRecords, recentRecords] = await Promise.all([
      Message.aggregate<ParentSubagentTaskRecord>([
        { $match: match },
        { $sort: { conversationId: 1, createdAt: -1, _id: -1 } },
        { $group: { _id: '$conversationId', task: { $first: taskProjection } } },
        { $project: { _id: 0, conversationId: '$_id', tasks: ['$task'] } },
        { $sort: { conversationId: 1 } },
      ]),
      Message.aggregate<AggregateRecord>([
        { $match: match },
        { $sort: { createdAt: -1, _id: -1 } },
        { $limit: sourceLimit + 1 },
        {
          $addFields: {
            _subagentIsAssistant: { $regexMatch: { input: '$messageId', regex: /:assistant$/ } },
            _subagentTaskId: {
              $substrBytes: [
                '$messageId',
                0,
                {
                  $subtract: [
                    { $strLenBytes: '$messageId' },
                    {
                      $cond: [
                        { $regexMatch: { input: '$messageId', regex: /:assistant$/ } },
                        10,
                        5,
                      ],
                    },
                  ],
                },
              ],
            },
          },
        },
        {
          $sort: {
            conversationId: 1,
            _subagentTaskId: 1,
            _subagentIsAssistant: -1,
            createdAt: -1,
            _id: -1,
          },
        },
        {
          $group: {
            _id: { conversationId: '$conversationId', taskId: '$_subagentTaskId' },
            task: { $first: taskProjection },
            sourceRows: { $sum: 1 },
          },
        },
        {
          $sort: {
            '_id.conversationId': 1,
            'task.createdAt': -1,
            'task.occurrenceId': -1,
            '_id.taskId': 1,
          },
        },
        {
          $group: {
            _id: '$_id.conversationId',
            tasks: { $push: '$task' },
            sourceRows: { $sum: '$sourceRows' },
          },
        },
        {
          $project: {
            _id: 0,
            conversationId: '$_id',
            tasks: { $slice: ['$tasks', input.limitPerThread] },
            sourceRows: 1,
          },
        },
        { $sort: { conversationId: 1 } },
      ]),
    ]);
    const sourceTruncated =
      recentRecords.reduce((total, record) => total + (record.sourceRows ?? 0), 0) > sourceLimit;
    const records = new Map<string, ParentSubagentTaskRecord>(
      recentRecords.map((record) => [
        record.conversationId,
        {
          conversationId: record.conversationId,
          tasks: record.tasks,
          ...(sourceTruncated ? { sourceTruncated: true } : {}),
        },
      ]),
    );
    for (const latest of latestRecords) {
      const current = records.get(latest.conversationId);
      if (current == null) {
        records.set(latest.conversationId, {
          ...latest,
          ...(sourceTruncated ? { sourceTruncated: true } : {}),
        });
        continue;
      }
      const candidates = [...current.tasks, ...latest.tasks];
      const tasksById = new Map<string, (typeof candidates)[number]>();
      for (const candidate of candidates) {
        const taskId = candidate.messageId.replace(/:(user|assistant)$/, '');
        const existing = tasksById.get(taskId);
        const candidateTime = taskTimestamp(candidate.createdAt);
        const existingTime = taskTimestamp(existing?.createdAt);
        const candidateIsAssistant = candidate.messageId.endsWith(':assistant');
        const existingIsAssistant = existing?.messageId.endsWith(':assistant') === true;
        const occurrenceDifference = compareOccurrenceIds(
          candidate.occurrenceId,
          existing?.occurrenceId,
        );
        if (
          existing == null ||
          candidateTime > existingTime ||
          (candidateTime === existingTime && occurrenceDifference > 0) ||
          (candidateTime === existingTime &&
            occurrenceDifference === 0 &&
            candidateIsAssistant &&
            !existingIsAssistant)
        ) {
          tasksById.set(taskId, candidate);
        }
      }
      current.tasks = [...tasksById.values()]
        .sort((left, right) => {
          const timeDifference = taskTimestamp(right.createdAt) - taskTimestamp(left.createdAt);
          if (timeDifference !== 0) return timeDifference;
          const occurrenceDifference = compareOccurrenceIds(right.occurrenceId, left.occurrenceId);
          if (occurrenceDifference !== 0) return occurrenceDifference;
          const assistantDifference =
            Number(right.messageId.endsWith(':assistant')) -
            Number(left.messageId.endsWith(':assistant'));
          if (assistantDifference !== 0) return assistantDifference;
          return left.messageId.localeCompare(right.messageId);
        })
        .slice(0, input.limitPerThread);
    }
    return [...records.values()].sort((left, right) =>
      left.conversationId.localeCompare(right.conversationId),
    );
  }

  async function getConversationTraceRefs({
    user,
    conversationId,
    tenantId,
    messageId,
    through,
    limit,
  }: {
    user: string;
    conversationId: string;
    tenantId?: string;
    messageId?: string;
    through?: { messageId: string; orderKey: string };
    limit?: number;
  }): Promise<ConversationTraceRefs> {
    try {
      const Message = mongoose.models.Message as Model<IMessage>;
      const scope = { user, conversationId, ...traceTenantScope(tenantId) };
      const anchor = through != null ? parseTraceOrderKey(through.orderKey) : undefined;
      const range =
        anchor != null
          ? {
              $or: [
                { createdAt: { $lt: anchor.createdAt } },
                {
                  createdAt: anchor.createdAt,
                  _id: { $lte: new mongoose.Types.ObjectId(anchor.id) },
                },
              ],
            }
          : {};
      const query = Message.find({
        ...scope,
        ...SERVER_AUTHORED_SAMPLED_RESPONSE,
        ...(messageId != null ? { messageId } : {}),
        ...range,
      }).select('_id messageId createdAt langfuseDestinationIds langfuseRunId');
      const bounded = limit != null;
      /** `_id` breaks ties between responses saved in the same millisecond, so every page
       *  request rebuilds the same turn order its cursor was positioned in. */
      const sorted = bounded
        ? query.sort({ createdAt: -1, _id: -1 }).limit(limit)
        : query.sort({ createdAt: 1, _id: 1 });
      const [first, rows] = await Promise.all([
        Message.findOne(scope)
          .select('createdAt -_id')
          .sort({ createdAt: 1 })
          .lean<Pick<IMessage, 'createdAt'>>(),
        through != null && anchor == null
          ? []
          : sorted.lean<
              Array<
                Pick<
                  IMessage,
                  'messageId' | 'createdAt' | 'langfuseDestinationIds' | 'langfuseRunId'
                > & { _id: Types.ObjectId }
              >
            >(),
      ]);
      const sampled = bounded ? rows.reverse() : rows;
      /** A position that no longer names its response (deleted, or never issued) resumes nothing. */
      if (through != null && sampled[sampled.length - 1]?.messageId !== through.messageId) {
        return { firstMessageAt: first?.createdAt, sampledMessages: [] };
      }
      return {
        firstMessageAt: first?.createdAt,
        sampledMessages: sampled
          .filter((message) => typeof message.messageId === 'string')
          .map(({ _id, messageId: id, createdAt, langfuseDestinationIds, langfuseRunId }) => ({
            messageId: id,
            ...(createdAt != null ? { createdAt, orderKey: traceOrderKey(createdAt, _id) } : {}),
            ...(Array.isArray(langfuseDestinationIds) ? { langfuseDestinationIds } : {}),
            ...(typeof langfuseRunId === 'string' && langfuseRunId.length > 0
              ? { langfuseRunId }
              : {}),
          })),
      };
    } catch (err) {
      logger.error('Error getting conversation trace references:', err);
      throw err;
    }
  }

  async function hasSampledTraceMessage({
    user,
    conversationId,
    tenantId,
    destinationIds,
  }: {
    user: string;
    conversationId: string;
    tenantId?: string;
    destinationIds: string[];
  }): Promise<boolean> {
    try {
      const Message = mongoose.models.Message as Model<IMessage>;
      const match = await Message.findOne({
        user,
        conversationId,
        ...traceTenantScope(tenantId),
        ...SERVER_AUTHORED_SAMPLED_RESPONSE,
        $or: [
          { langfuseDestinationIds: null },
          { langfuseDestinationIds: { $in: destinationIds } },
        ],
      })
        .select('_id')
        .lean();
      return match != null;
    } catch (err) {
      logger.error('Error checking for a sampled trace message:', err);
      throw err;
    }
  }

  /**
   * The reasoning level a branch runs at: the override on the nearest user message at or above
   * `parentMessageId` that carries one, or `null` when none does. One read of the conversation's
   * links and levels, projected to those fields; the walk itself is in memory.
   */
  async function getBranchReasoningOverride({
    user,
    conversationId,
    parentMessageId,
  }: {
    user: string;
    conversationId: string;
    parentMessageId: string;
  }): Promise<IMessage['reasoningOverride'] | null> {
    const Message = mongoose.models.Message as Model<IMessage>;
    const rows = await Message.find(
      { user, conversationId },
      { _id: 0, messageId: 1, parentMessageId: 1, isCreatedByUser: 1, reasoningOverride: 1 },
    ).lean<
      Pick<IMessage, 'messageId' | 'parentMessageId' | 'isCreatedByUser' | 'reasoningOverride'>[]
    >();
    const byId = new Map(rows.map((row) => [row.messageId, row]));
    const visited = new Set<string>();
    let current = byId.get(parentMessageId);
    while (current != null && !visited.has(current.messageId)) {
      visited.add(current.messageId);
      if (current.isCreatedByUser === true && current.reasoningOverride != null) {
        return current.reasoningOverride;
      }
      current = current.parentMessageId != null ? byId.get(current.parentMessageId) : undefined;
    }
    return null;
  }

  /**
   * Retrieves a single message from the database.
   */
  async function getMessage({ user, messageId }: { user: string; messageId: string }) {
    try {
      const Message = mongoose.models.Message as Model<IMessage>;
      return await Message.findOne({ user, messageId }).lean<IMessage>();
    } catch (err) {
      logger.error('Error getting message:', err);
      throw err;
    }
  }

  /**
   * Deletes messages from the database.
   */
  async function deleteMessages(filter: FilterQuery<IMessage>) {
    try {
      const Message = mongoose.models.Message as Model<IMessage>;
      if (typeof filter.messageId === 'string' && !/:(user|assistant)$/.test(filter.messageId)) {
        return await Message.deleteMany(filter);
      }
      const wholeScope =
        typeof filter.user === 'string' &&
        Object.keys(filter).every((key) => ['user', 'conversationId', 'tenantId'].includes(key));
      const contentSources = wholeScope
        ? []
        : await Message.find({
            $and: [filter, { subagentContent: { $exists: true } }],
          })
            .select('user tenantId conversationId messageId')
            .lean<IMessage[]>();
      const SubagentContent = mongoose.models.SubagentContent as
        | Model<ISubagentContentChunk>
        | undefined;
      if (SubagentContent != null) {
        if (wholeScope) {
          await prepareSubagentContentDeletion(mongoose, filter);
          return await Message.deleteMany(filter);
        }
        const scopes = new Map<
          string,
          {
            user: string;
            conversationId: string;
            taskId: string;
            tenantId: string | { $exists: false };
          }
        >();
        for (const source of contentSources) {
          const taskId = source.messageId.replace(/:(user|assistant)$/, '');
          if (taskId === source.messageId) continue;
          scopes.set(`${source.tenantId ?? ''}:${source.user}:${source.conversationId}:${taskId}`, {
            user: source.user,
            conversationId: source.conversationId,
            taskId,
            tenantId: source.tenantId ?? { $exists: false },
          });
        }
        if (scopes.size > 0) {
          const contentScopes = [...scopes.values()];
          /** Revoke the task before cleanup, including appends already admitted.
           * Retain both markers until payload deletion succeeds so retries rediscover them. */
          await Message.updateMany(
            {
              $or: contentScopes.map(({ taskId, ...scope }) => ({
                ...scope,
                messageId: { $in: [`${taskId}:user`, `${taskId}:assistant`] },
              })),
            },
            { $set: { 'subagentContent.deleted': true } },
          );
          await SubagentContent.deleteMany({ $or: contentScopes });
        }
      }
      return await Message.deleteMany(filter);
    } catch (err) {
      logger.error('Error deleting messages:', err);
      throw err;
    }
  }

  /**
   * Retrieves paginated messages with custom sorting and cursor support.
   */
  async function getMessagesByCursor(
    filter: FilterQuery<IMessage>,
    options: {
      sortField?: string;
      sortOrder?: 1 | -1;
      limit?: number;
      cursor?: string | null;
      /** Projection for the page, e.g. `CLIENT_MESSAGE_SELECT` for client-facing reads. */
      select?: string;
    } = {},
  ) {
    const Message = mongoose.models.Message as Model<IMessage>;
    const { sortField = 'createdAt', sortOrder = -1, limit = 25, cursor, select } = options;
    const queryFilter: FilterQuery<IMessage> = { ...filter };
    const position = cursor ? parseMessageCursor(cursor) : null;
    if (position != null) {
      const op = sortOrder === 1 ? '$gt' : '$lt';
      const value =
        DATE_SORT_FIELDS.has(sortField) && position.value !== NULL_SORT_VALUE
          ? new Date(position.value)
          : position.value;
      const id = position.id == null ? undefined : new mongoose.Types.ObjectId(position.id);
      const after = buildCursorFilter(sortField, op, value, { value: position.value, id });
      queryFilter.$and = [...(queryFilter.$and ?? []), after];
    }
    const query = Message.find(queryFilter);
    /** The cursor needs `_id`, so an `-_id` projection is applied after it is read. */
    const tokens = select ? select.split(/\s+/).filter(Boolean) : [];
    const omitId = tokens.includes('-_id');
    if (tokens.length > 0) {
      query.select(tokens.filter((token) => token !== '-_id').join(' '));
    }
    /** `_id` makes the order total, so a page boundary inside a run of equal sort values is stable. */
    const messages = await query
      .sort({ [sortField]: sortOrder, _id: sortOrder })
      .limit(limit + 1)
      .lean<IMessage[]>();

    let nextCursor: string | null = null;
    if (messages.length > limit) {
      messages.pop();
      const last = messages[messages.length - 1];
      nextCursor = formatMessageCursor(last[sortField as keyof IMessage], last._id);
    }
    if (omitId) {
      for (const message of messages) {
        delete (message as { _id?: unknown })._id;
      }
    }
    return { messages, nextCursor };
  }

  /**
   * Performs a MeiliSearch query on the Message collection.
   * Requires the meilisearch plugin to be registered on the Message model.
   */
  async function searchMessages(
    query: string,
    searchOptions: SearchParams,
    hydrate?: boolean,
  ): Promise<Awaited<ReturnType<SchemaWithMeiliMethods['meiliSearch']>>> {
    const Message = mongoose.models.Message as SchemaWithMeiliMethods;
    if (typeof Message.meiliSearch !== 'function') {
      throw new Error('MeiliSearch plugin not registered on Message model');
    }
    return Message.meiliSearch(query, searchOptions, hydrate);
  }

  async function getPersistedPrivateTextId(input: {
    userId: string;
    tenantId?: string;
    conversationId: string;
    messageId: string;
    privacyRevision: string;
    text: string;
  }): Promise<string | null> {
    if (
      !input.userId ||
      !input.messageId ||
      !input.privacyRevision ||
      !UUID_REGEX.test(input.conversationId)
    ) {
      return null;
    }
    const activeTenant = tenantStorage.getStore()?.tenantId;
    if (activeTenant != null && activeTenant !== input.tenantId) {
      return null;
    }
    const Message = mongoose.models.Message as Model<IMessage>;
    const stored = await Message.exists({
      user: input.userId,
      ...traceTenantScope(input.tenantId),
      conversationId: input.conversationId,
      messageId: input.messageId,
      text: input.text,
      privacyRevision: input.privacyRevision,
      privateText: { $exists: true },
      $or: [{ expiredAt: null }, { expiredAt: { $gt: new Date() } }],
    });
    return stored == null ? null : String(stored._id);
  }

  async function hasPersistedPrivateText(
    input: Parameters<MessageMethods['hasPersistedPrivateText']>[0],
  ): Promise<boolean> {
    return (await getPersistedPrivateTextId(input)) != null;
  }

  async function getPrivateMessageTexts(input: {
    userId: string;
    tenantId?: string;
    conversationId: string;
    messageIds: readonly string[];
  }): Promise<PrivateTextRead[]> {
    if (!input.userId || !UUID_REGEX.test(input.conversationId) || input.messageIds.length > 50) {
      throw new Error('Invalid private message read.');
    }
    const activeTenant = tenantStorage.getStore()?.tenantId;
    if (activeTenant != null && activeTenant !== input.tenantId) {
      return [];
    }
    const Message = mongoose.models.Message as Model<IMessage>;
    return Message.find({
      user: input.userId,
      ...traceTenantScope(input.tenantId),
      conversationId: input.conversationId,
      messageId: { $in: input.messageIds },
      isCreatedByUser: true,
      privateText: { $exists: true },
      $or: [{ expiredAt: null }, { expiredAt: { $gt: new Date() } }],
    })
      .select('messageId text privacyRevision +privateText')
      .limit(50)
      .lean<PrivateTextRead[]>();
  }

  return {
    hasPersistedPrivateText,
    getPersistedPrivateTextId,
    getPrivateMessageTexts,
    saveMessage,
    bulkSaveMessages,
    updateToolCallResult,
    claimBackgroundToolResults,
    confirmBackgroundToolResultClaim,
    releaseBackgroundToolResultClaims,
    updateMessage,
    recordSubagentTaskControlReceipt,
    getSubagentTaskControlReceipt,
    getSubagentTaskControlReplay,
    claimSubagentTaskResult,
    releaseSubagentTaskResultClaim,
    getMessages,
    getConversationTraceRefs,
    hasSampledTraceMessage,
    getMessagesForSubagentThreadView,
    listSubagentTasksForThreads,
    getMessage,
    getBranchReasoningOverride,
    getMessagesByCursor,
    searchMessages,
    deleteMessages,
  };
}