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

41.3 KB
Raw Blame
import { isMemoryAgentEnabled, isMemoryEnabled } from '@librechat/data-schemas';
import {
  Constants,
  Permissions,
  EModelEndpoint,
  PermissionTypes,
  AgentCapabilities,
  HITL_MESSAGE_FILTER_FIELDS,
  STORED_MESSAGE_FILTER_FIELDS,
  hasActivePiiFields,
  hasActivePiiPatterns,
  isActionTool,
  isEphemeralAgentId,
  openapiToFunction,
  validateAndParseOpenAPISpec,
} from 'librechat-data-provider';
import type {
  Agent,
  Action,
  Agents,
  FiltersConfig,
  TConversation,
  TEndpointOption,
  TCheckpointerConfig,
  MessageFilterPiiConfig,
  UserSubmittedMessageFieldPath,
} from 'librechat-data-provider';
import type { ToolApprovalDecisionMap, AskUserQuestionResolution } from '@librechat/agents';
import type { AppConfig, IUser } from '@librechat/data-schemas';
import type {
  AgentContentInput,
  MemoryContentInput,
  AssistantActionContentInput,
} from '~/protection/adapters/submissions';
import type {
  ResumeContentInspection,
  ResumeContentInspectionInput,
  ResumeSnapshotAgent,
} from './inspection';
import type { LocatorTraversalReporter } from '../../protection/diagnostics';
import type { TextContentFragment } from '~/protection/types';
import type { CheckAccessParams } from '~/middleware/access';
import {
  assertModelBoundContent,
  collectModelBoundHistoricalFileIdState,
  hasModelBoundContentProtection,
  type ModelBoundContentInput,
} from '~/middleware/modelBoundContent';
import {
  ContentTraversalLimitError,
  getContentTraversalFragments,
  isContentTraversalProtected,
} from '~/protection/adapters/nested';
import { getResumeAgentSnapshot, getResumeContentInspection } from './inspection';
import { extractStoredMessageContent } from '~/protection/adapters/submissions';
import { agentHasInlineMemoryTools, getMemoryAgentId } from '../memory';
import { isValidInstructionsPromptLink } from '../instructions/linked';
import { LIBRECHAT_CHECKPOINT_NAMESPACE_KEY } from '../checkpointer';
import { AttachmentObjectNotFoundError } from '~/files/encode/utils';
import { ASK_USER_QUESTION_TOOL_NAME } from './askUserQuestionTool';
import { ContentFilterError } from '~/middleware/contentFilter';
import { applyCheckpointDelivery } from '../files/delivery';
import { hasActiveFilePolicy } from '~/protection/files';
import { parseSkillMarkdown } from '../../skills/parse';
import { inspectContent } from '~/protection/runtime';
import { isSkillPrimeMessage } from '../skills';

const GENERIC_RESUME_ERROR = 'Resume failed';

interface ResumeToolCall {
  readonly id?: string;
  readonly name?: unknown;
  readonly args?: unknown;
  readonly arguments?: unknown;
  readonly output?: unknown;
  readonly function?: {
    readonly name?: unknown;
    readonly arguments?: unknown;
    readonly output?: unknown;
  };
  readonly code_interpreter?: {
    readonly input?: unknown;
    readonly outputs?: unknown;
  };
}

interface ResumeContentPart {
  readonly type?: string;
  readonly text?:
    | string
    | {
        readonly value?: string;
        readonly [key: string]: unknown;
      };
  readonly tool_call?: ResumeToolCall;
  readonly [key: string]: unknown;
}

interface ResumeCheckpointMessage {
  readonly role?: string;
  readonly name?: string;
  readonly text?: string;
  readonly content?: string | readonly ResumeContentPart[];
  readonly tool_calls?: readonly ResumeToolCall[];
  readonly files?: readonly object[];
  readonly attachments?: readonly object[];
  readonly file_ids?: readonly string[];
  readonly metadata?: object;
  readonly additional_kwargs?: {
    readonly skillName?: string;
    readonly sourceMessageId?: string;
    readonly sourceMessageIds?: readonly string[];
    readonly provenance?: {
      readonly parts?: readonly {
        readonly attribution?: string;
        readonly sourceMessageId?: string;
      }[];
    };
    readonly tool_calls?: readonly ResumeToolCall[];
  };
  readonly _getType?: () => string;
}

interface ResumeCheckpointer {
  getTuple(config: { configurable: Readonly<Record<string, string>> }): Promise<
    | {
        checkpoint?: {
          channel_values?: {
            messages?: readonly ResumeCheckpointMessage[];
          };
        };
      }
    | null
    | undefined
  >;
}

type ResumeAction = Action & AssistantActionContentInput;

interface ResumeEndpointOption
  extends Pick<Partial<TEndpointOption>, 'agent' | 'model_parameters'> {
  readonly addedConvo?: {
    readonly agent_id?: TConversation['agent_id'];
  };
}

type ResumeValue = ToolApprovalDecisionMap | AskUserQuestionResolution;

interface ResumeProtectionUser extends IUser {
  readonly id: IUser['id'];
  readonly role: IUser['role'];
}

interface ResumeProtectionConfig extends Omit<AppConfig, 'messageFilter'> {
  readonly messageFilter?: {
    readonly pii?: MessageFilterPiiConfig;
  };
}

const RESUME_CHECKPOINT_SKILL_FIELDS = ['name', 'instructions', 'frontmatter'] as const;
const RESUME_STORED_MESSAGE_FILTER_FIELDS = [
  ...STORED_MESSAGE_FILTER_FIELDS,
  ...HITL_MESSAGE_FILTER_FIELDS,
] as const;
const ACTION_DEFINITION_TOOL_FIELDS = ['name', 'arguments'] as const;
const ENCRYPTED_ACTION_METADATA_FIELDS = [
  'api_key',
  'oauth_client_id',
  'oauth_client_secret',
] as const;

export interface ResumeContentProtectionDependencies {
  readonly onTraversalFailure?: LocatorTraversalReporter;
  getAgentCheckpointer: (
    config: TCheckpointerConfig | undefined,
  ) => Promise<ResumeCheckpointer | undefined>;
  checkAccess: (params: CheckAccessParams) => Promise<boolean>;
  getMessages: ResumeContentInspectionInput['getMessages'];
  getFiles: ResumeContentInspectionInput['getFiles'];
  getAgent: (filter: { id: string }) => Promise<Agent | null | undefined>;
  getActions: (
    query: { agentId: string[] },
    includeSensitive: boolean,
  ) => Promise<ResumeAction[] | null | undefined>;
  getUserMemories: (params: { userId: string; agentId?: string }) => Promise<MemoryContentInput[]>;
  getRoleByName: CheckAccessParams['getRoleByName'];
  decryptMetadata: (metadata: Action['metadata']) => Promise<Action['metadata']>;
  canAccessAgent: (agent: Agent, user: ResumeProtectionUser) => Promise<boolean>;
}

export interface AssertResumeContentAllowedInput {
  readonly appConfig?: ResumeProtectionConfig;
  readonly endpointOption?: ResumeEndpointOption;
  readonly conversationId: string;
  readonly targetMessageId?: string | null;
  readonly user: ResumeProtectionUser;
  readonly storedMessages: ResumeContentInspectionInput['supplementalMessages'];
  readonly seedContent: readonly ResumeContentPart[];
  readonly resumeValue?: ResumeValue | null;
  readonly liveFiles: ResumeContentInspectionInput['liveFiles'];
  readonly isTemporary: boolean;
  readonly checkpointNamespace?: string;
  readonly resolvedAddedAgent?: Agent | null;
}

export interface AssertResumeRuntimeContentAllowedInput
  extends Pick<
    AssertResumeContentAllowedInput,
    | 'appConfig'
    | 'conversationId'
    | 'targetMessageId'
    | 'user'
    | 'storedMessages'
    | 'seedContent'
    | 'resumeValue'
    | 'liveFiles'
    | 'isTemporary'
    | 'checkpointNamespace'
  > {
  readonly agents: NonNullable<ModelBoundContentInput['agents']>;
  readonly files: NonNullable<ModelBoundContentInput['files']>;
}

export type ResumeRuntimeContentProtectionDependencies = Pick<
  ResumeContentProtectionDependencies,
  'getAgentCheckpointer' | 'getMessages' | 'getFiles' | 'onTraversalFailure'
>;

export interface ResumeRuntimeContentProjection {
  readonly resolvedFiles: ResumeContentInspection['hydratedFiles'];
  readonly checkpointFiles: ResumeContentInspection['hydratedFiles'];
}

function hasResumeHistoryProtection(appConfig: ResumeProtectionConfig | undefined): boolean {
  return (
    hasActivePiiPatterns(appConfig?.messageFilter?.pii) ||
    hasActivePiiFields(appConfig?.filters?.messages?.pii, RESUME_STORED_MESSAGE_FILTER_FIELDS) ||
    hasActivePiiPatterns(appConfig?.filters?.toolArguments?.pii) ||
    hasActiveFilePolicy(appConfig?.filters) ||
    hasActivePiiFields(appConfig?.filters?.skills?.pii, RESUME_CHECKPOINT_SKILL_FIELDS)
  );
}

function hasResumeAgentProtection(appConfig: ResumeProtectionConfig | undefined): boolean {
  return (
    hasActivePiiPatterns(appConfig?.filters?.agentInstructions?.pii) ||
    hasActivePiiPatterns(appConfig?.filters?.conversationStarters?.pii) ||
    hasActivePiiPatterns(appConfig?.filters?.modelParameters?.pii) ||
    hasActivePiiPatterns(appConfig?.filters?.actionMetadata?.pii) ||
    hasActivePiiPatterns(appConfig?.filters?.memories?.pii) ||
    hasActivePiiFields(appConfig?.filters?.toolArguments?.pii, ACTION_DEFINITION_TOOL_FIELDS)
  );
}

function hasResumeAgentDefinitionProtection(
  appConfig: ResumeProtectionConfig | undefined,
): boolean {
  return (
    hasActivePiiPatterns(appConfig?.filters?.agentInstructions?.pii) ||
    hasActivePiiPatterns(appConfig?.filters?.conversationStarters?.pii) ||
    hasActivePiiPatterns(appConfig?.filters?.modelParameters?.pii)
  );
}

export function hasResumeContentProtection(appConfig: ResumeProtectionConfig | undefined): boolean {
  return hasModelBoundContentProtection(appConfig?.filters, appConfig?.messageFilter?.pii);
}

function getCheckpointMessageRole(message: ResumeCheckpointMessage): string | undefined {
  const type = message._getType?.() ?? message.role;
  if (type === 'human') {
    return 'user';
  }
  if (type === 'ai') {
    return 'assistant';
  }
  return type;
}

function getCheckpointSkill(message: ResumeCheckpointMessage): {
  name?: string;
  body: string;
  frontmatter?: Record<string, unknown>;
} | null {
  if (!isSkillPrimeMessage(message)) {
    return null;
  }
  const content = message.content;
  let body = '';
  if (typeof content === 'string') {
    body = content;
  } else if (Array.isArray(content)) {
    body = content
      .map((part) => {
        if (typeof part === 'string') {
          return part;
        }
        return typeof part?.text === 'string' ? part.text : '';
      })
      .join('');
  }
  const frontmatter = parseSkillMarkdown(body).frontmatter;
  return {
    name: message.additional_kwargs?.skillName,
    body,
    ...(frontmatter != null && { frontmatter }),
  };
}

function normalizeCheckpointToolCalls(message: ResumeCheckpointMessage): ResumeToolCall[] {
  const calls = [
    ...(Array.isArray(message.tool_calls) ? message.tool_calls : []),
    ...(Array.isArray(message.additional_kwargs?.tool_calls)
      ? message.additional_kwargs.tool_calls
      : []),
  ];
  return calls.map((call) => ({
    name: call.name,
    arguments: call.args ?? call.arguments,
    output: call.output,
    function: call.function,
    code_interpreter: call.code_interpreter,
  }));
}

function getResumeCheckpointContent(messages: readonly ResumeCheckpointMessage[]): {
  submittedMessages: ResumeContentInspectionInput['submittedMessages'];
  skills: Array<{ name?: string; body: string; frontmatter?: Record<string, unknown> }>;
} {
  const submittedMessages: ResumeContentInspectionInput['submittedMessages'] = [];
  const skills: Array<{ name?: string; body: string; frontmatter?: Record<string, unknown> }> = [];
  for (const message of messages) {
    const skill = getCheckpointSkill(message);
    if (skill != null) {
      skills.push(skill);
      continue;
    }
    if (getCheckpointMessageRole(message) !== 'user') {
      continue;
    }
    const content = message.content ?? message.text;
    submittedMessages.push({
      ...message,
      role: 'user',
      content:
        typeof content === 'string' || content == null
          ? content
          : content.map((part) => ({
              ...part,
              ...(typeof part.text === 'object' && part.text != null
                ? { text_metadata: part.text }
                : {}),
              text: typeof part.text === 'string' ? part.text : part.text?.value,
            })),
      tool_calls: normalizeCheckpointToolCalls(message).map((call) => ({
        ...call,
        function: {
          name: typeof call.function?.name === 'string' ? call.function.name : undefined,
          arguments:
            typeof call.function?.arguments === 'string' ? call.function.arguments : undefined,
        },
      })),
    });
  }
  return { submittedMessages, skills };
}

async function getResumeCheckpointMessages(
  appConfig: ResumeProtectionConfig | undefined,
  conversationId: string,
  checkpointNamespace: string,
  dependencies: Pick<ResumeContentProtectionDependencies, 'getAgentCheckpointer'>,
): Promise<readonly ResumeCheckpointMessage[]> {
  const checkpointer = await dependencies.getAgentCheckpointer(
    appConfig?.endpoints?.[EModelEndpoint.agents]?.checkpointer,
  );
  if (!checkpointer) {
    return [];
  }
  const tuple = await checkpointer.getTuple({
    configurable: {
      thread_id: conversationId,
      checkpoint_ns: '',
      ...(checkpointNamespace !== '' && {
        [LIBRECHAT_CHECKPOINT_NAMESPACE_KEY]: checkpointNamespace,
      }),
    },
  });
  const messages = tuple?.checkpoint?.channel_values?.messages;
  return Array.isArray(messages) ? messages : [];
}

function assertResumeToolContentAllowed(
  filters: FiltersConfig | undefined,
  messages: readonly ResumeCheckpointMessage[],
  seedContent: readonly ResumeContentPart[],
  resumeValue: ResumeValue | null | undefined,
): void {
  if (
    !hasActivePiiPatterns(filters?.toolArguments?.pii) &&
    !hasActivePiiFields(filters?.messages?.pii, RESUME_STORED_MESSAGE_FILTER_FIELDS)
  ) {
    return;
  }
  const fragments: TextContentFragment[] = [];
  const traversalErrors: Array<{
    error: ContentTraversalLimitError;
    role?: string;
    includeMessageFragments: boolean;
  }> = [];
  const collectStoredMessage = (
    message: Parameters<typeof extractStoredMessageContent>[0],
    includeMessageFragments: boolean,
  ): void => {
    try {
      fragments.push(
        ...extractStoredMessageContent(message).filter(
          (fragment) =>
            fragment.source === 'tool_argument' ||
            (includeMessageFragments &&
              (fragment.source === 'message' || fragment.source === 'assembled_context')),
        ),
      );
    } catch (error) {
      if (!(error instanceof ContentTraversalLimitError)) {
        throw error;
      }
      fragments.push(
        ...getContentTraversalFragments(error).filter(
          (fragment) =>
            fragment.source === 'tool_argument' ||
            (includeMessageFragments &&
              (fragment.source === 'message' || fragment.source === 'assembled_context')),
        ),
      );
      traversalErrors.push({ error, role: message?.role, includeMessageFragments });
    }
  };
  for (const message of messages) {
    const content = message.content;
    const role = getCheckpointMessageRole(message);
    collectStoredMessage(
      {
        role,
        text: typeof content === 'string' ? content : undefined,
        content: Array.isArray(content) ? content : undefined,
        tool_calls: normalizeCheckpointToolCalls(message),
      },
      role === 'user',
    );
  }
  collectStoredMessage(
    {
      role: 'assistant',
      content: seedContent,
    },
    false,
  );
  if ('answer' in (resumeValue ?? {}) && typeof resumeValue?.answer === 'string') {
    fragments.push({
      id: 'resume.answer',
      path: '/answer',
      text: resumeValue.answer,
      source: 'message',
      field: 'answer',
      format: 'plain',
      treatment: 'inspect_only',
      provenance: 'user',
    });
    collectStoredMessage(
      {
        role: 'tool',
        content: [{ text: resumeValue.answer }],
      },
      false,
    );
  }
  for (const decision of Object.values(resumeValue ?? {})) {
    if (decision == null || typeof decision !== 'object') {
      continue;
    }
    if (decision.type === 'edit') {
      collectStoredMessage(
        {
          role: 'assistant',
          tool_calls: [{ arguments: decision.updatedInput }],
        },
        false,
      );
    } else if (decision.type === 'respond' && typeof decision.responseText === 'string') {
      fragments.push({
        id: 'resume.decision.response',
        path: '/decision/responseText',
        text: decision.responseText,
        source: 'message',
        field: 'decision_response',
        format: 'plain',
        treatment: 'inspect_only',
        provenance: 'user',
      });
      collectStoredMessage(
        {
          role: 'tool',
          content: [{ text: decision.responseText }],
        },
        false,
      );
    } else if (decision.type === 'reject' && typeof decision.reason === 'string') {
      fragments.push({
        id: 'resume.decision.reason',
        path: '/decision/reason',
        text: decision.reason,
        source: 'message',
        field: 'decision_reason',
        format: 'plain',
        treatment: 'inspect_only',
        provenance: 'user',
      });
      collectStoredMessage(
        {
          role: 'tool',
          content: [{ text: decision.reason }],
        },
        false,
      );
    }
  }
  const finding = inspectContent(fragments, {
    filters: {
      messages: filters?.messages,
      toolArguments: filters?.toolArguments,
    },
  });
  if (finding != null) {
    throw new ContentFilterError(finding);
  }
  const protectedTraversal = traversalErrors.find(({ error, role, includeMessageFragments }) =>
    isContentTraversalProtected({
      error,
      filters:
        includeMessageFragments || filters == null ? filters : { ...filters, messages: undefined },
      roles: [role],
    }),
  );
  if (protectedTraversal != null) {
    throw protectedTraversal.error;
  }
}

/**
 * Projects a resume snapshot agent's definition fields for the content-policy
 * scan. Excludes the stored inline `instructions` when the agent has a valid
 * `instructionsPrompt` link — matching `initializeAgent`'s init-time content
 * check, which excludes the same field for the same reason: a linked agent's
 * stored inline text is dead, unused text, superseded by the resolved prompt
 * at runtime, so it must not block a resume this scan gates.
 */
function projectResumeAgentDefinition(agent: ResumeSnapshotAgent): AgentContentInput {
  const hasValidLink = isValidInstructionsPromptLink(agent.instructionsPrompt);
  return {
    name: agent.name,
    category: agent.category,
    description: agent.description,
    instructions: hasValidLink ? undefined : agent.instructions,
    additional_instructions: agent.additional_instructions,
    conversation_starters: agent.conversation_starters,
    edges: agent.edges?.map((edge) => ({
      description: edge.description,
      prompt: typeof edge.prompt === 'string' ? edge.prompt : undefined,
      promptKey: edge.promptKey,
    })),
    artifacts: agent.artifacts,
    support_contact: agent.support_contact,
    toolDefinitions: agent.tools
      ?.filter((tool) => typeof tool === 'string' && isActionTool(tool))
      .map((name) => ({ name })),
    model_parameters: {
      ...(agent.model ? { model: agent.model } : {}),
      ...(agent.model_parameters ?? {}),
    },
  };
}

async function getResumeAdditionalAgentRoots(
  resolvedAddedAgent: Agent | null | undefined,
  endpointOption: ResumeEndpointOption | undefined,
  dependencies: ResumeContentProtectionDependencies,
): Promise<Agent[]> {
  if (resolvedAddedAgent) {
    return [resolvedAddedAgent];
  }
  const addedAgentId = endpointOption?.addedConvo?.agent_id;
  if (typeof addedAgentId !== 'string' || isEphemeralAgentId(addedAgentId)) {
    return [];
  }
  const addedAgent = await dependencies.getAgent({ id: addedAgentId });
  return addedAgent ? [addedAgent] : [];
}

async function getResumeMemoryAgentDefinition(
  appConfig: ResumeProtectionConfig | undefined,
  primaryAgent: ResumeSnapshotAgent,
  dependencies: ResumeContentProtectionDependencies,
): Promise<{ id: string; definition: AgentContentInput } | null> {
  if (!isMemoryAgentEnabled(appConfig?.memory)) {
    return null;
  }
  const configuredAgent = appConfig?.memory?.agent;
  if (configuredAgent != null && 'id' in configuredAgent && configuredAgent.id) {
    if (configuredAgent.id === primaryAgent.id) {
      return {
        id: primaryAgent.id,
        definition: projectResumeAgentDefinition(primaryAgent),
      };
    }
    const agent = await dependencies.getAgent({ id: configuredAgent.id });
    return agent
      ? {
          id: agent.id,
          definition: projectResumeAgentDefinition(agent),
        }
      : null;
  }
  if (
    configuredAgent != null &&
    'provider' in configuredAgent &&
    configuredAgent.provider &&
    configuredAgent.model
  ) {
    return {
      id: `${Constants.EPHEMERAL_AGENT_ID}`,
      definition: {
        instructions: configuredAgent.instructions,
        model_parameters: {
          model: configuredAgent.model,
          ...(configuredAgent.model_parameters ?? {}),
        },
      },
    };
  }
  return null;
}

async function getResumeActionSnapshots(
  filters: FiltersConfig | undefined,
  agents: readonly ResumeSnapshotAgent[],
  dependencies: ResumeContentProtectionDependencies,
): Promise<ResumeAction[]> {
  const inspectActionMetadata = hasActivePiiPatterns(filters?.actionMetadata?.pii);
  const inspectActionDefinitions = hasActivePiiFields(
    filters?.toolArguments?.pii,
    ACTION_DEFINITION_TOOL_FIELDS,
  );
  if (!inspectActionMetadata && !inspectActionDefinitions) {
    return [];
  }
  const agentIds = agents
    .filter((agent) => agent.tools?.some((tool) => typeof tool === 'string' && isActionTool(tool)))
    .map((agent) => agent.id)
    .filter((id): id is string => typeof id === 'string' && id.length > 0);
  if (agentIds.length === 0) {
    return [];
  }
  const needsEncryptedMetadata = hasActivePiiFields(
    filters?.actionMetadata?.pii,
    ENCRYPTED_ACTION_METADATA_FIELDS,
  );
  const actions =
    (await dependencies.getActions({ agentId: agentIds }, needsEncryptedMetadata)) ?? [];
  const withFunctions = actions.map((action) => {
    const rawSpec = action.metadata?.raw_spec;
    if (typeof rawSpec !== 'string') {
      return action;
    }
    const parsed = validateAndParseOpenAPISpec(rawSpec);
    if (!parsed.spec) {
      return action;
    }
    try {
      const { functionSignatures } = openapiToFunction(parsed.spec, true);
      return { ...action, functions: functionSignatures };
    } catch {
      return action;
    }
  });
  if (!needsEncryptedMetadata) {
    return withFunctions;
  }
  return Promise.all(
    withFunctions.map(async (action) => ({
      ...action,
      metadata: await dependencies.decryptMetadata(action.metadata),
    })),
  );
}

async function getResumeMemorySnapshots({
  appConfig,
  user,
  agents,
  primaryAgent,
  dependencies,
}: {
  appConfig: ResumeProtectionConfig | undefined;
  user: ResumeProtectionUser;
  agents: readonly ResumeSnapshotAgent[];
  primaryAgent: ResumeSnapshotAgent;
  dependencies: ResumeContentProtectionDependencies;
}): Promise<MemoryContentInput[]> {
  const memoryConfig = appConfig?.memory;
  if (
    !hasActivePiiPatterns(appConfig?.filters?.memories?.pii) ||
    !isMemoryEnabled(memoryConfig) ||
    user.personalization?.memories === false
  ) {
    return [];
  }
  const canReadMemory = await dependencies.checkAccess({
    user,
    permissionType: PermissionTypes.MEMORIES,
    permissions: [Permissions.USE],
    getRoleByName: dependencies.getRoleByName,
  });
  if (!canReadMemory) {
    return [];
  }

  const inlineMemoryAvailable =
    new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities).has(
      AgentCapabilities.memory,
    ) &&
    (await dependencies.checkAccess({
      user,
      permissionType: PermissionTypes.MEMORIES,
      permissions: [Permissions.USE, Permissions.CREATE, Permissions.UPDATE],
      getRoleByName: dependencies.getRoleByName,
    }));
  const automaticMemoryEnabled = isMemoryAgentEnabled(memoryConfig);
  const partitionIds = new Set([getMemoryAgentId(primaryAgent)]);
  for (const agent of agents) {
    if (
      agent.id !== primaryAgent.id &&
      (automaticMemoryEnabled || (inlineMemoryAvailable && agentHasInlineMemoryTools(agent)))
    ) {
      partitionIds.add(getMemoryAgentId(agent));
    }
  }

  const memories = await Promise.all(
    [...partitionIds].map((agentId) =>
      dependencies.getUserMemories({
        userId: `${user.id}`,
        agentId,
      }),
    ),
  );
  return memories.flat();
}

async function assertResumeAgentContentAllowed({
  appConfig,
  endpointOption,
  user,
  resolvedAddedAgent,
  dependencies,
}: Pick<
  AssertResumeContentAllowedInput,
  'appConfig' | 'endpointOption' | 'user' | 'resolvedAddedAgent'
> & {
  dependencies: ResumeContentProtectionDependencies;
}): Promise<void> {
  if (!hasResumeAgentProtection(appConfig)) {
    return;
  }
  const primaryAgent = await endpointOption?.agent;
  if (!primaryAgent) {
    throw new ContentTraversalLimitError();
  }
  const additionalRoots = await getResumeAdditionalAgentRoots(
    resolvedAddedAgent,
    endpointOption,
    dependencies,
  );
  const subagentsEnabled = new Set(appConfig?.endpoints?.[EModelEndpoint.agents]?.capabilities).has(
    AgentCapabilities.subagents,
  );
  const agents = await getResumeAgentSnapshot({
    primaryAgent,
    additionalRoots,
    primaryModelParameters: endpointOption?.model_parameters,
    subagentsEnabled,
    getAgent: async (filter) => (await dependencies.getAgent(filter)) ?? null,
    canAccessAgent: (agent) => dependencies.canAccessAgent(agent, user),
    appConfig,
  });
  const memoryAgentDefinition = hasResumeAgentDefinitionProtection(appConfig)
    ? await getResumeMemoryAgentDefinition(appConfig, primaryAgent, dependencies)
    : null;
  const [actions, memories] = await Promise.all([
    getResumeActionSnapshots(appConfig?.filters, agents, dependencies),
    getResumeMemorySnapshots({
      appConfig,
      user,
      agents,
      primaryAgent: agents[0],
      dependencies,
    }),
  ]);
  const definitionAgents = agents.map(projectResumeAgentDefinition);
  if (
    memoryAgentDefinition != null &&
    !agents.some((agent) => agent.id === memoryAgentDefinition.id)
  ) {
    definitionAgents.push(memoryAgentDefinition.definition);
  }
  assertModelBoundContent({
    onTraversalFailure: dependencies.onTraversalFailure,
    filters: appConfig?.filters,
    legacyPii: appConfig?.messageFilter?.pii,
    agents: definitionAgents,
    actions,
    memories,
  });
}

type AssertResumeModelBoundContentAllowedInput = Pick<
  AssertResumeContentAllowedInput,
  | 'appConfig'
  | 'conversationId'
  | 'targetMessageId'
  | 'user'
  | 'storedMessages'
  | 'seedContent'
  | 'resumeValue'
  | 'liveFiles'
  | 'isTemporary'
  | 'checkpointNamespace'
> & {
  readonly trustLiveFileContent?: boolean;
  readonly checkpointMessages?: readonly ResumeCheckpointMessage[];
  readonly agents?: ModelBoundContentInput['agents'];
  readonly files?: ModelBoundContentInput['files'];
};

interface ResumeModelBoundContentProjection {
  readonly resolvedFiles: ResumeContentInspection['hydratedFiles'];
  readonly sourceMessages: ResumeContentInspection['originalStoredMessages'];
  readonly checkpointMessages: readonly ResumeCheckpointMessage[];
  readonly historyLoaded: boolean;
}

async function assertResumeModelBoundContentAllowed(
  {
    appConfig,
    conversationId,
    targetMessageId,
    user,
    storedMessages,
    seedContent,
    resumeValue,
    liveFiles,
    isTemporary,
    checkpointNamespace = '',
    trustLiveFileContent,
    checkpointMessages: providedCheckpointMessages,
    agents,
    files,
  }: AssertResumeModelBoundContentAllowedInput,
  dependencies: ResumeRuntimeContentProtectionDependencies,
): Promise<ResumeModelBoundContentProjection> {
  if (!hasResumeHistoryProtection(appConfig)) {
    assertModelBoundContent({
      onTraversalFailure: dependencies.onTraversalFailure,
      filters: appConfig?.filters,
      legacyPii: appConfig?.messageFilter?.pii,
      agents,
      files,
    });
    return {
      resolvedFiles: [],
      sourceMessages: storedMessages,
      checkpointMessages: providedCheckpointMessages ?? [],
      historyLoaded: false,
    };
  }

  let checkpointMessages: readonly ResumeCheckpointMessage[];
  try {
    checkpointMessages =
      providedCheckpointMessages ??
      (await getResumeCheckpointMessages(
        appConfig,
        conversationId,
        checkpointNamespace,
        dependencies,
      ));
  } catch {
    throw new ContentTraversalLimitError();
  }
  const checkpointContent = getResumeCheckpointContent(checkpointMessages);
  const contentInspection = await getResumeContentInspection({
    onTraversalFailure: dependencies.onTraversalFailure,
    appConfig,
    conversationId,
    targetMessageId,
    user,
    supplementalMessages: storedMessages,
    submittedMessages: checkpointContent.submittedMessages,
    fileReferenceInputs: checkpointMessages,
    liveFiles,
    ...(trustLiveFileContent === true && { trustLiveFileContent: true }),
    isTemporary,
    getMessages: dependencies.getMessages,
    getFiles: dependencies.getFiles,
  });
  assertModelBoundContent({
    onTraversalFailure: dependencies.onTraversalFailure,
    filters: appConfig?.filters,
    legacyPii: appConfig?.messageFilter?.pii,
    submittedMessages: contentInspection.submittedMessages,
    storedMessages: contentInspection.storedMessages,
    agents,
    skills: checkpointContent.skills,
    files,
    resolvedFiles: contentInspection.hydratedFiles,
  });
  assertResumeToolContentAllowed(appConfig?.filters, checkpointMessages, seedContent, resumeValue);
  return {
    resolvedFiles: contentInspection.hydratedFiles,
    sourceMessages: contentInspection.originalStoredMessages,
    checkpointMessages,
    historyLoaded: true,
  };
}

export async function assertResumeContentAllowed(
  {
    appConfig,
    endpointOption,
    conversationId,
    targetMessageId,
    user,
    storedMessages,
    seedContent,
    resumeValue,
    liveFiles,
    isTemporary,
    checkpointNamespace = '',
    resolvedAddedAgent,
  }: AssertResumeContentAllowedInput,
  dependencies: ResumeContentProtectionDependencies,
): Promise<void> {
  if (!hasResumeContentProtection(appConfig)) {
    return;
  }
  await assertResumeModelBoundContentAllowed(
    {
      appConfig,
      conversationId,
      targetMessageId,
      user,
      storedMessages,
      seedContent,
      resumeValue,
      liveFiles,
      isTemporary,
      checkpointNamespace,
    },
    dependencies,
  );
  await assertResumeAgentContentAllowed({
    appConfig,
    endpointOption,
    user,
    resolvedAddedAgent,
    dependencies,
  });
}

/**
 * Rechecks the fully initialized runtime projection immediately before a resumed run.
 * The controller-level preflight remains authoritative for approval claiming; this
 * second boundary covers hydrated attachments and dynamic tool context assembled later.
 */
export async function assertResumeRuntimeContentAllowed(
  input: AssertResumeRuntimeContentAllowedInput,
  dependencies: ResumeRuntimeContentProtectionDependencies,
): Promise<ResumeRuntimeContentProjection> {
  let checkpointMessages = hasResumeHistoryProtection(input.appConfig)
    ? await getResumeCheckpointMessages(
        input.appConfig,
        input.conversationId,
        input.checkpointNamespace ?? '',
        dependencies,
      )
    : undefined;
  const modelBoundProjection = hasResumeContentProtection(input.appConfig)
    ? await assertResumeModelBoundContentAllowed(
        {
          ...input,
          trustLiveFileContent: true,
          checkpointMessages,
        },
        dependencies,
      )
    : undefined;
  const resolvedFiles = modelBoundProjection?.resolvedFiles ?? [];
  if (modelBoundProjection?.historyLoaded === true) {
    checkpointMessages = modelBoundProjection.checkpointMessages;
  }
  checkpointMessages ??= await getResumeCheckpointMessages(
    input.appConfig,
    input.conversationId,
    input.checkpointNamespace ?? '',
    dependencies,
  );
  const checkpointSourceMessageIds = new Set(
    checkpointMessages
      .flatMap((message) => {
        const additionalKwargs = message.additional_kwargs;
        return [
          additionalKwargs?.sourceMessageId,
          ...(Array.isArray(additionalKwargs?.sourceMessageIds)
            ? additionalKwargs.sourceMessageIds
            : []),
          ...(Array.isArray(additionalKwargs?.provenance?.parts)
            ? additionalKwargs.provenance.parts
                .filter((part) => part?.attribution === 'user' || part?.attribution === 'tool')
                .map((part) => part.sourceMessageId)
            : []),
        ];
      })
      .filter(
        (messageId): messageId is string => typeof messageId === 'string' && messageId.length > 0,
      ),
  );
  let sourceMessages = (modelBoundProjection?.sourceMessages ?? input.storedMessages).filter(
    (message) => {
      const messageId = message.messageId ?? message.id;
      return messageId != null && checkpointSourceMessageIds.has(messageId);
    },
  );
  const resolvedSourceMessageIds = new Set(
    sourceMessages
      .map((message) => message.messageId ?? message.id)
      .filter((messageId): messageId is string => messageId != null),
  );
  const missingSourceMessageIds = [...checkpointSourceMessageIds].filter(
    (messageId) => !resolvedSourceMessageIds.has(messageId),
  );
  if (
    modelBoundProjection?.historyLoaded !== true &&
    !input.isTemporary &&
    missingSourceMessageIds.length > 0 &&
    input.user?.id
  ) {
    const persistedMessages =
      (await dependencies.getMessages({
        conversationId: input.conversationId,
        user: input.user.id,
      })) ?? [];
    const sourceMessagesById = new Map(
      sourceMessages.map((message) => [message.messageId ?? message.id, message]),
    );
    for (const message of persistedMessages) {
      const messageId = message.messageId ?? message.id;
      if (messageId != null && checkpointSourceMessageIds.has(messageId)) {
        sourceMessagesById.set(messageId, message);
      }
    }
    sourceMessages = [...sourceMessagesById.values()];
  }
  const availableSourceMessageIds = new Set(
    sourceMessages
      .map((message) => message.messageId ?? message.id)
      .filter((messageId): messageId is string => messageId != null),
  );
  const unresolvedSourceMessageId = [...checkpointSourceMessageIds].find(
    (messageId) => !availableSourceMessageIds.has(messageId),
  );
  if (unresolvedSourceMessageId != null) {
    throw new Error('A checkpoint source message is no longer available');
  }
  const checkpointFileInputs = [
    ...checkpointMessages.map((message) => ({
      files: message.files,
      content: message.content,
    })),
    ...sourceMessages.map((message) => ({ files: message.files, content: message.content })),
  ] as ResumeContentInspectionInput['supplementalMessages'];
  const nonSteerCheckpointFileIds = collectModelBoundHistoricalFileIdState(
    checkpointFileInputs.map((message) => ({
      files: message?.files,
      content: Array.isArray(message?.content)
        ? message.content.filter((part) => part?.type !== 'steer')
        : message?.content,
    })),
  ).fileIds;
  const checkpointSteerFileIds: string[] = [];
  for (const message of checkpointFileInputs) {
    if (!Array.isArray(message?.content)) {
      continue;
    }
    for (const part of message.content) {
      if (part?.type !== 'steer' || !Array.isArray(part.files)) {
        continue;
      }
      for (const file of part.files) {
        if (typeof file?.file_id === 'string' && file.file_id.length > 0) {
          checkpointSteerFileIds.push(file.file_id);
        }
      }
    }
  }
  const checkpointFileIdOccurrences = [...nonSteerCheckpointFileIds, ...checkpointSteerFileIds];
  const checkpointFileIds = new Set(checkpointFileIdOccurrences);
  const resolvedFilesById = new Map(
    resolvedFiles
      .filter((file) => checkpointFileIds.has(file.file_id ?? ''))
      .map((file) => [file.file_id, file]),
  );
  const missingCheckpointFileIds = [...checkpointFileIds].filter(
    (fileId) => !resolvedFilesById.has(fileId),
  );
  const missingCheckpointFileIdSet = new Set(missingCheckpointFileIds);
  if (missingCheckpointFileIds.length > 0 && input.user?.id) {
    const ownerFiles =
      (await dependencies.getFiles(
        {
          file_id: { $in: missingCheckpointFileIds },
          user: input.user.id,
          ...(input.user.tenantId != null && { tenantId: input.user.tenantId }),
        },
        {},
        {},
      )) ?? [];
    for (const file of ownerFiles) {
      if (missingCheckpointFileIdSet.has(file.file_id ?? '')) {
        resolvedFilesById.set(file.file_id, file);
      }
    }
  }
  const checkpointFiles = checkpointFileIdOccurrences
    .map((fileId) => resolvedFilesById.get(fileId))
    .filter((file): file is NonNullable<typeof file> => file != null);
  if ([...checkpointFileIds].some((fileId) => !resolvedFilesById.has(fileId))) {
    const unresolvedFileId = [...checkpointFileIds].find(
      (fileId) => !resolvedFilesById.has(fileId),
    );
    throw new AttachmentObjectNotFoundError(unresolvedFileId ?? 'unknown');
  }
  return { resolvedFiles, checkpointFiles: applyCheckpointDelivery(checkpointFiles) };
}

export function getUserFacingResumeError(
  error: { readonly message?: string } | null | undefined,
  appConfig: ResumeProtectionConfig | undefined,
): string {
  if (hasResumeContentProtection(appConfig)) {
    return GENERIC_RESUME_ERROR;
  }
  return typeof error?.message === 'string' ? error.message : GENERIC_RESUME_ERROR;
}

export const mergeUserSubmittedPaths = (
  ...pathLists: readonly (readonly (string | null | undefined)[] | null | undefined)[]
): string[] => [
  ...new Set(
    pathLists
      .flatMap((paths) => paths ?? [])
      .filter(
        (path): path is string =>
          typeof path === 'string' && path.startsWith('/') && path.length <= 2048,
      ),
  ),
];

export const mergeUserSubmittedMessageFieldPaths = (
  ...entryLists: readonly (
    | readonly (UserSubmittedMessageFieldPath | null | undefined)[]
    | null
    | undefined
  )[]
): UserSubmittedMessageFieldPath[] => {
  const entries: UserSubmittedMessageFieldPath[] = [];
  const seen = new Set<string>();
  const allowedFields = new Set<string>(HITL_MESSAGE_FILTER_FIELDS);
  for (const entry of entryLists.flatMap((values) => values ?? [])) {
    if (
      entry == null ||
      typeof entry.path !== 'string' ||
      !entry.path.startsWith('/') ||
      entry.path.length > 2048 ||
      !allowedFields.has(entry.field)
    ) {
      continue;
    }
    const key = `${entry.field}:${entry.path}`;
    if (seen.has(key)) {
      continue;
    }
    seen.add(key);
    entries.push(entry);
  }
  return entries;
};

/** Map user decisions to the exact assistant fields they mutate during resume. */
export function getResumeUserSubmittedPaths(
  content: readonly ResumeContentPart[] | null | undefined,
  pendingAction: Pick<Agents.PendingAction, 'payload'> | null | undefined,
  body: { readonly decisions?: readonly Agents.ToolApprovalResolution[] } | null | undefined,
): string[] {
  const paths: string[] = [];
  const parts = Array.isArray(content) ? content : [];
  for (let index = 0; index < parts.length; index++) {
    if (parts[index]?.type === 'steer') {
      paths.push(`/content/${index}`);
    }
  }

  const payload = pendingAction?.payload;
  if (payload?.type === 'ask_user_question') {
    return paths;
  }
  if (payload?.type !== 'tool_approval') {
    return paths;
  }

  const resolutions = new Map(
    (body?.decisions ?? []).map((decision) => [decision.tool_call_id, decision]),
  );
  for (let index = 0; index < parts.length; index++) {
    const resolution = resolutions.get(parts[index]?.tool_call?.id ?? '');
    if (resolution?.decision === 'edit') {
      paths.push(`/content/${index}/tool_call/args`);
    }
  }
  return paths;
}

/** Preserve exact request-only message fields after they are embedded in tool outputs. */
export function getResumeUserSubmittedMessageFieldPaths(
  content: readonly ResumeContentPart[] | null | undefined,
  pendingAction: Pick<Agents.PendingAction, 'payload'> | null | undefined,
  body:
    | {
        readonly answer?: string;
        readonly decisions?: readonly Agents.ToolApprovalResolution[];
      }
    | null
    | undefined,
): UserSubmittedMessageFieldPath[] {
  const parts = Array.isArray(content) ? content : [];
  const payload = pendingAction?.payload;
  if (payload?.type === 'ask_user_question' && typeof body?.answer === 'string') {
    const toolCallId = payload.tool_call_id;
    for (let index = parts.length - 1; index >= 0; index--) {
      const toolCall = parts[index]?.tool_call;
      if (toolCall?.name !== ASK_USER_QUESTION_TOOL_NAME) {
        continue;
      }
      if (typeof toolCallId === 'string' && toolCallId.length > 0) {
        if (toolCall.id === toolCallId) {
          return [{ path: `/content/${index}/tool_call/output`, field: 'answer' }];
        }
        continue;
      }
      // Provenance can be recomputed after the current answer is stamped. The
      // newest ask is still the current legacy interrupt; skipping its output
      // would incorrectly attribute the answer to an older unanswered ask.
      return [{ path: `/content/${index}/tool_call/output`, field: 'answer' }];
    }
    return [];
  }
  if (payload?.type !== 'tool_approval') {
    return [];
  }

  const resolutions = new Map(
    (body?.decisions ?? []).map((decision) => [decision.tool_call_id, decision]),
  );
  const entries: UserSubmittedMessageFieldPath[] = [];
  for (let index = 0; index < parts.length; index++) {
    const resolution = resolutions.get(parts[index]?.tool_call?.id ?? '');
    if (resolution?.decision === 'respond' && typeof resolution.responseText === 'string') {
      entries.push({
        path: `/content/${index}/tool_call/output`,
        field: 'decision_response',
      });
    } else if (resolution?.decision === 'reject' && typeof resolution.reason === 'string') {
      entries.push({
        path: `/content/${index}/tool_call/output`,
        field: 'decision_reason',
      });
    }
  }
  return entries;
}