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

237 KB
Raw Blame
/**
 * Stub `buildBashExecutionToolDescription` since the installed SDK version
 * may pre-date the export. Kept as a partial mock so `Providers` and the
 * rest of the namespace come through `jest.requireActual`.
 */
jest.mock('@librechat/agents', () => ({
  ...jest.requireActual('@librechat/agents'),
  ReadFileToolDefinition: {
    name: 'read_file',
    description: 'read skill files using {skillName}/{filePath} and SKILL.md',
    parameters: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: 'For skill files: "{skillName}/{path}".',
        },
      },
    },
    responseFormat: 'content',
  },
  BashExecutionToolDefinition: {
    name: 'bash_tool',
    description: 'bash',
    schema: { type: 'object', properties: {} },
  },
  buildBashExecutionToolDescription: ({
    enableToolOutputReferences,
  }: {
    enableToolOutputReferences?: boolean;
  } = {}): string =>
    enableToolOutputReferences === true ? 'bash {{tool<idx>turn<turn>}}' : 'bash',
}));

import { Providers } from '@librechat/agents';
import { createHash } from 'node:crypto';
import { logger } from '@librechat/data-schemas';
import { createRepositoryInstructionLoader } from '../../code/instructions';
import {
  Tools,
  Constants,
  ErrorTypes,
  Permissions,
  EModelEndpoint,
  EToolResources,
  FileContext,
  FileSources,
  PermissionTypes,
  AgentCapabilities,
  configSchema,
} from 'librechat-data-provider';
import type { IMongoFile } from '@librechat/data-schemas';
import type { Agent, TFile, FiltersConfig, AgentInstructionsPrompt } from 'librechat-data-provider';
import type { ServerRequest, InitializeResultBase, EndpointTokenConfig } from '~/types';
import type { ResolveLinkedInstructions } from '../instructions/linked';
import type { InitializeAgentDbMethods } from '../initialize';
import type { CodeExecutionContext } from '../execution';
import type { GraphSubagentHostConfig } from '../discovery';
import type { ProjectFileRecord } from '../../projects/resources';
import { toCanonicalProjectResource } from '../../projects/resources';
import { DEFAULT_MAX_CONTEXT_TOKENS } from '../initialize';
import { discoverConnectedAgents, resolveSubagentGraphs } from '../discovery';

// Mock logger — `format` must be a callable factory so @librechat/data-schemas
// dist module-load completes cleanly; see api/test/__mocks__/logger.js.
jest.mock('winston', () => ({
  createLogger: jest.fn(() => ({
    debug: jest.fn(),
    warn: jest.fn(),
    error: jest.fn(),
    info: jest.fn(),
  })),
  format: Object.assign(
    jest.fn((fn) => () => ({ transform: fn })),
    {
      combine: jest.fn(),
      colorize: jest.fn(),
      simple: jest.fn(),
      label: jest.fn(),
      timestamp: jest.fn(),
      printf: jest.fn(),
      errors: jest.fn(),
      splat: jest.fn(),
      json: jest.fn(),
    },
  ),
  addColors: jest.fn(),
  transports: {
    Console: jest.fn(),
    DailyRotateFile: jest.fn(),
    File: jest.fn(),
  },
}));

const mockExtractLibreChatParams = jest.fn();
const mockGetModelMaxTokens = jest.fn();
const mockOptionalChainWithEmptyCheck = jest.fn();
const mockGetThreadData = jest.fn();

jest.mock('~/utils', () => ({
  extractLibreChatParams: (...args: unknown[]) => mockExtractLibreChatParams(...args),
  getModelMaxTokens: (...args: unknown[]) => mockGetModelMaxTokens(...args),
  optionalChainWithEmptyCheck: (...args: unknown[]) => mockOptionalChainWithEmptyCheck(...args),
  getThreadData: (...args: unknown[]) => mockGetThreadData(...args),
}));

const mockGetProviderConfig = jest.fn();
jest.mock('~/endpoints', () => ({
  getProviderConfig: (...args: unknown[]) => mockGetProviderConfig(...args),
}));

jest.mock('~/files', () => ({
  filterFilesByEndpointRuntimeConfig: jest.fn(() => []),
}));

jest.mock('~/prompts', () => ({
  generateArtifactsPrompt: jest.fn(() => null),
}));

jest.mock('../resources', () => ({
  primeResources: jest.fn().mockResolvedValue({
    attachments: [],
    tool_resources: undefined,
  }),
}));

jest.mock('../../middleware/modelBoundContent', () => {
  const actual = jest.requireActual('../../middleware/modelBoundContent');
  /* Real by default; a single test overrides it to stand in for a policy that started
   * refusing a file after it was attached. */
  return {
    ...actual,
    assertModelBoundContent: jest.fn((...args: unknown[]) =>
      (actual as { assertModelBoundContent: (...a: unknown[]) => void }).assertModelBoundContent(
        ...args,
      ),
    ),
  };
});

import { initializeAgent } from '../initialize';
import { primeResources } from '../resources';
import { isFatalAgentInitializationError } from '../errors';
import { canAgentGraphPause } from '../hitl/admission';

const realUtils = jest.requireActual<typeof import('~/utils')>('~/utils');

/**
 * Creates minimal mock objects for initializeAgent tests.
 *
 * @param overrides.overrideProvider - Simulates the value returned by `getProviderConfig`.
 *   Defaults to `provider` (native endpoint where no remapping occurs). Set to a different
 *   value (e.g. `Providers.OPENAI`) alongside a custom `provider` to simulate a custom
 *   endpoint whose provider is resolved to a built-in.
 * @param overrides.useRealTokenLookup - When true, `getModelMaxTokens` delegates to the real
 *   implementation so tests exercise actual token-map resolution. Otherwise a controlled
 *   `modelDefault` is returned.
 */
function createMocks(overrides?: {
  provider?: string;
  overrideProvider?: string;
  model?: string;
  maxContextTokens?: number;
  modelDefault?: number;
  maxOutputTokens?: number;
  endpointTokenConfig?: EndpointTokenConfig;
  useRealTokenLookup?: boolean;
  providerTools?: unknown[];
  loadedToolDefinitions?: Array<{
    name: string;
    description?: string;
    parameters?: object;
  }>;
  structuredTools?: unknown[];
}) {
  const {
    provider = Providers.OPENAI,
    overrideProvider,
    model = 'test-model',
    maxContextTokens,
    modelDefault = 200000,
    maxOutputTokens = 4096,
    endpointTokenConfig,
    useRealTokenLookup = false,
    providerTools,
    loadedToolDefinitions = [],
    structuredTools = [],
  } = overrides ?? {};

  const resolvedOverrideProvider = overrideProvider ?? provider;

  const agent = {
    id: 'agent-1',
    model,
    provider,
    tools: [],
    model_parameters: { model },
  } as unknown as Agent;

  const req = {
    user: { id: 'user-1' },
    config: {},
  } as unknown as ServerRequest;

  const res = {} as unknown as import('express').Response;

  const mockGetOptions = jest.fn().mockResolvedValue({
    llmConfig: { model, maxTokens: maxOutputTokens },
    endpointTokenConfig,
    ...(providerTools !== undefined ? { tools: providerTools } : {}),
  } satisfies InitializeResultBase);

  mockGetProviderConfig.mockReturnValue({
    getOptions: mockGetOptions,
    overrideProvider: resolvedOverrideProvider,
  });

  mockExtractLibreChatParams.mockReturnValue({
    resendFiles: false,
    maxContextTokens,
    modelOptions: { model },
  });

  if (useRealTokenLookup) {
    mockGetModelMaxTokens.mockImplementation(realUtils.getModelMaxTokens);
  } else {
    mockGetModelMaxTokens.mockReturnValue(modelDefault);
  }

  // Real implementation: treats 0 as a valid (non-empty) value — load-bearing for the maxContextTokens=0 test
  mockOptionalChainWithEmptyCheck.mockImplementation(realUtils.optionalChainWithEmptyCheck);

  const loadTools = jest.fn().mockResolvedValue({
    tools: structuredTools,
    toolContextMap: {},
    dynamicToolContextMap: {},
    userMCPAuthMap: undefined,
    toolRegistry: undefined,
    toolDefinitions: loadedToolDefinitions,
    hasDeferredTools: false,
  });

  const db: InitializeAgentDbMethods = {
    getProjectFiles: jest.fn().mockResolvedValue([]),
    getFiles: jest.fn().mockResolvedValue([]),
    getConvoFiles: jest.fn().mockResolvedValue([]),
    updateFilesUsage: jest.fn().mockResolvedValue([]),
    getUserKey: jest.fn().mockResolvedValue('user-1'),
    getUserKeyValues: jest.fn().mockResolvedValue([]),
    getToolFilesByIds: jest.fn().mockResolvedValue([]),
  };

  return { agent, req, res, loadTools, db };
}

function countNamedWebSearchTools(tools: unknown[] | undefined): number {
  return (
    tools?.filter((tool) => {
      if (tool == null || typeof tool !== 'object') {
        return false;
      }
      const { name } = tool as { name?: unknown };
      return name === Tools.web_search;
    }).length ?? 0
  );
}

function countGoogleSearchTools(tools: unknown[] | undefined): number {
  return (
    tools?.filter((tool) => {
      if (tool == null || typeof tool !== 'object') {
        return false;
      }
      return 'googleSearch' in tool || 'googleSearchRetrieval' in tool;
    }).length ?? 0
  );
}

function countWebSearchDefinitions(toolDefinitions: Array<{ name: string }> | undefined): number {
  return (
    toolDefinitions?.filter((toolDefinition) => toolDefinition.name === Tools.web_search).length ??
    0
  );
}

function countUrlContextTools(tools: unknown[] | undefined): number {
  return (
    tools?.filter((tool) => tool != null && typeof tool === 'object' && 'urlContext' in tool)
      .length ?? 0
  );
}

describe('initializeAgent — execution context', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it.each(['prefer', 'defer', 'off'] as const)(
    'uses saved repository instruction mode %s in definitions-only initialization',
    async (mode) => {
      const { agent, req, res, loadTools, db } = createMocks();
      agent.instructions = 'Agent conventions';
      agent.repositoryInstructions = mode;
      const content = 'Repository conventions';
      const authHeaders = jest.fn(async () => ({}));
      const fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue(
        new Response(
          JSON.stringify({
            protocolVersion: 1,
            operation: 'read_file',
            workspaceId: 'primary',
            path: 'AGENTS.md',
            content,
            startLine: 1,
            endLine: 1,
            truncated: false,
          }),
        ),
      );
      loadTools.mockResolvedValue({
        toolDefinitions: [],
        repositoryInstructionSource: {
          load: createRepositoryInstructionLoader(),
          enabled: true,
          principalId: `test-${mode}`,
          context: {
            environmentType: 'attached',
            baseUrl: 'https://code.example/v1',
            codeWorkspace: {
              workspaceId: 'primary',
              operations: ['read_file'],
              instructions: [
                {
                  path: 'AGENTS.md',
                  bytes: Buffer.byteLength(content),
                  sha256: createHash('sha256').update(content).digest('hex'),
                  truncated: false,
                },
              ],
            },
          },
          authHeaders,
        },
      });
      const result = await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([agent.provider]),
          isInitialAgent: true,
        },
        db,
      );
      if (mode === 'off') {
        expect(result.instructions).toBe('Agent conventions');
        expect(authHeaders).not.toHaveBeenCalled();
        expect(fetchSpy).not.toHaveBeenCalled();
      } else {
        expect(result.instructions).toContain('Repository conventions');
        expect(result.instructions).toMatch(/^Agent conventions\n\nRepository-provided/);
        expect(result.instructions).toContain(
          mode === 'defer' ? 'unless they conflict' : 'prefer these instructions',
        );
      }
      expect(result.additional_instructions ?? '').not.toContain('Repository conventions');
      fetchSpy.mockRestore();
    },
  );

  it('carries request-resolved Azure identity to the run without changing persisted agent fields', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: EModelEndpoint.azureOpenAI,
      model: 'gpt-6-astra',
    });
    const azureOptions = {
      azureOpenAIApiKey: 'request-key',
      azureOpenAIApiInstanceName: 'request-instance',
      azureOpenAIApiDeploymentName: 'deployment',
      azureOpenAIApiVersion: '2024-10-21',
    };
    mockGetProviderConfig.mockReturnValue({
      overrideProvider: Providers.AZURE,
      getOptions: jest.fn().mockResolvedValue({
        azureOptions,
        llmConfig: {
          model: 'gpt-6-astra',
          useResponsesApi: true,
          apiKey: 'request-key',
          modelKwargs: { model: 'deployment' },
        },
      }),
    });
    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([EModelEndpoint.azureOpenAI]),
        isInitialAgent: true,
      },
      db,
    );
    expect(result.azureOptions).toEqual(azureOptions);
    expect(result.model_parameters).not.toHaveProperty('azureOpenAIApiInstanceName');
    expect(agent).not.toHaveProperty('azureOptions');
  });

  it('initializes without Express request or response objects', async () => {
    const { agent, loadTools, db } = createMocks();
    const previousReqDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'req');
    Object.defineProperty(globalThis, 'req', {
      configurable: true,
      writable: true,
      value: undefined,
    });
    const appConfig = {
      endpoints: {
        [EModelEndpoint.agents]: {
          statefulCodeSessions: {
            environments: [
              {
                id: 'request-free-stateful',
                name: 'Request-free stateful',
                type: 'attached',
                baseURL: 'https://stateful.example.com/v1',
              },
            ],
          },
        },
      },
    };

    try {
      await expect(
        initializeAgent(
          {
            runtime: {
              user: { id: 'user-1' } as never,
              appConfig: appConfig as never,
              requestBody: { timezone: 'America/New_York' },
              turnStartedAt: 1000,
            },
            agent,
            loadTools,
            endpointOption: { endpoint: EModelEndpoint.agents },
            allowedProviders: new Set([Providers.OPENAI]),
            isInitialAgent: true,
          },
          db,
        ),
      ).resolves.toBeDefined();
    } finally {
      if (previousReqDescriptor == null) {
        delete (globalThis as typeof globalThis & { req?: unknown }).req;
      } else {
        Object.defineProperty(globalThis, 'req', previousReqDescriptor);
      }
    }

    expect(loadTools).toHaveBeenCalledWith(expect.not.objectContaining({ req: expect.anything() }));
    expect(loadTools).toHaveBeenCalledWith(expect.not.objectContaining({ res: expect.anything() }));
  });
});

describe('initializeAgent: allowed providers', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  /** The effective config serves `endpoints.agents.allowedProviders` in served names, so a
   *  YAML `Ollama` arrives as `ollama`. The chat path's model check before this is covered in
   *  `api/server/services/Endpoints/agents/initialize.spec.js`. */
  it.each(['ollama', 'Ollama', 'OLLAMA'])(
    'sets up an agent saved with provider %s on the served ollama endpoint',
    async (provider) => {
      const { agent, req, res, loadTools, db } = createMocks({
        provider,
        overrideProvider: Providers.OPENAI,
      });

      const result = await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set(['ollama']),
          isInitialAgent: true,
        },
        db,
      );

      expect(mockGetProviderConfig).toHaveBeenCalledWith(
        expect.objectContaining({ provider: 'ollama' }),
      );
      const { getOptions } = mockGetProviderConfig.mock.results[0].value;
      expect(getOptions).toHaveBeenCalledWith(expect.objectContaining({ endpoint: 'ollama' }));
      expect(result.endpoint).toBe('ollama');
    },
  );

  it('rejects a provider the allowed list does not name', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: 'OpenRouter',
      overrideProvider: Providers.OPENAI,
    });

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set(['ollama']),
          isInitialAgent: true,
        },
        db,
      ),
    ).rejects.toThrow(ErrorTypes.INVALID_AGENT_PROVIDER);
  });
});

describe('initializeAgent: ChatProject context', () => {
  const filterMock = jest.requireMock('~/files') as {
    filterFilesByEndpointRuntimeConfig: jest.Mock;
  };
  const realFilters = jest.requireActual<typeof import('~/files/filter')>('~/files/filter');

  beforeEach(() => {
    jest.clearAllMocks();
    filterMock.filterFilesByEndpointRuntimeConfig
      .mockReset()
      .mockImplementation(realFilters.filterFilesByEndpointRuntimeConfig);
  });

  afterEach(() => {
    filterMock.filterFilesByEndpointRuntimeConfig.mockReset().mockReturnValue([]);
  });

  const projectFile: TFile = {
    file_id: 'project-file',
    filename: 'project.txt',
    filepath: '/uploads/project.txt',
    type: 'text/plain',
    object: 'file',
    bytes: 12,
    usage: 0,
    user: 'user-1',
    embedded: true,
    context: FileContext.message_attachment,
  };
  const canonicalFile: ProjectFileRecord = {
    ...projectFile,
    _id: '507f1f77bcf86cd799439012',
    user: projectFile.user,
    expiredAt: undefined,
    createdAt: new Date('2020-01-01'),
    updatedAt: new Date('2020-01-01'),
    text: 'Safe canonical Project content.',
  };
  const projectContext = {
    projectId: 'project-1',
    contextRevision: 3,
    instructions: 'Prefer concise project answers.',
    file_ids: ['project-file'],
    resources: [toCanonicalProjectResource(canonicalFile)],
  };
  const projectFilePolicy: FiltersConfig = {
    files: {
      pii: {
        fields: ['extracted_text'],
        starterPatterns: [],
        customPatterns: [{ id: 'project-policy', label: 'Project policy', regex: 'BLOCKED' }],
      },
    },
  };

  function projectRuntime() {
    return {
      user: createMocks().req.user,
      appConfig: {
        endpoints: {
          [EModelEndpoint.agents]: {
            capabilities: [AgentCapabilities.file_search],
          },
        },
      } as NonNullable<ServerRequest['config']>,
      requestBody: {},
      turnStartedAt: 1,
      chatProjectContext: projectContext,
    };
  }

  it('keeps Agent and Project guidance exactly once in initialized output without mutating the definition', async () => {
    const { agent, loadTools, db } = createMocks();
    agent.instructions = 'Follow the Agent instructions.';
    agent.additional_instructions = 'Agent dynamic guidance.';
    const originalAdditionalInstructions = agent.additional_instructions;

    const result = await initializeAgent(
      {
        runtime: projectRuntime(),
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: true,
      },
      db,
    );

    expect(result.instructions).toBe('Follow the Agent instructions.');
    expect(result.additional_instructions).toContain('Agent dynamic guidance.');
    expect(result.additional_instructions).toContain(projectContext.instructions);
    const additionalInstructions = result.additional_instructions ?? '';
    expect(additionalInstructions.split('Agent dynamic guidance.').length - 1).toBe(1);
    expect(additionalInstructions.split(projectContext.instructions).length - 1).toBe(1);
    expect(additionalInstructions.split('Project guidance (user-provided context').length - 1).toBe(
      1,
    );
    expect(agent.additional_instructions).toBe(originalAdditionalInstructions);
  });
  it('propagates Project guidance and files to a discovered child through real initialization', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.id = 'child-agent';
    agent._id = 'mongo-child-agent';
    agent.instructions = 'Child Agent instructions.';
    agent.tools = [Tools.file_search];
    req.config = projectRuntime().appConfig;
    req.chatProjectContext = projectContext;
    const getProjectFiles = jest.fn().mockResolvedValue([canonicalFile]);
    const projectDb = { ...db, getProjectFiles };
    const primaryConfig = await initializeAgent(
      {
        runtime: projectRuntime(),
        agent: {
          ...agent,
          id: 'primary-agent',
          edges: [{ from: 'primary-agent', to: 'child-agent', edgeType: 'handoff' }],
          tools: [],
        },
        loadTools,
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: true,
      },
      projectDb,
    );

    const result = await discoverConnectedAgents(
      {
        req,
        res,
        primaryConfig,
        allowedProviders: new Set([Providers.OPENAI]),
        modelsConfig: { openai: ['test-model'] },
        loadTools,
        useChatProjectContext: true,
      },
      {
        getAgent: jest.fn().mockResolvedValue(agent),
        checkPermission: jest.fn().mockResolvedValue(true),
        logViolation: jest.fn(),
        db: projectDb,
        validateAgentModel: jest.fn().mockResolvedValue({ isValid: true }),
      },
    );

    const childConfig = result.agentConfigs.get('child-agent');
    expect(childConfig?.additional_instructions).toContain(projectContext.instructions);
    expect(childConfig?.tool_resources?.[EToolResources.file_search]?.files).toEqual([projectFile]);
  });
  it('propagates Project guidance and files to a saved graph member through real initialization', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.id = 'graph-agent';
    agent._id = 'mongo-graph-agent';
    agent.instructions = 'Graph Agent instructions.';
    agent.tools = [Tools.file_search];
    req.config = projectRuntime().appConfig;
    req.chatProjectContext = projectContext;
    const getProjectFiles = jest.fn().mockResolvedValue([canonicalFile]);
    const projectDb = { ...db, getProjectFiles };
    const primaryConfig: GraphSubagentHostConfig = await initializeAgent(
      {
        runtime: projectRuntime(),
        agent: {
          ...agent,
          id: 'primary-agent',
          tools: [],
          subagents: {
            enabled: true,
            graphs: [
              {
                type: 'team',
                name: 'Project team',
                description: 'Project-aware graph',
                agent_ids: ['graph-agent'],
                edges: [],
                entry_agent_id: 'graph-agent',
                result_agent_id: 'graph-agent',
              },
            ],
          },
        },
        loadTools,
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: true,
      },
      projectDb,
    );

    await resolveSubagentGraphs(
      {
        req,
        res,
        primaryConfig,
        rootConfigs: [primaryConfig],
        allowedProviders: new Set([Providers.OPENAI]),
        modelsConfig: { openai: ['test-model'] },
        loadTools,
        useChatProjectContext: true,
      },
      {
        getAgent: jest.fn().mockResolvedValue(agent),
        checkPermission: jest.fn().mockResolvedValue(true),
        logViolation: jest.fn(),
        db: projectDb,
        validateAgentModel: jest.fn().mockResolvedValue({ isValid: true }),
      },
    );

    const graphMember = primaryConfig.subagentGraphConfigs?.[0]?.memberConfigs[0];
    expect(graphMember?.additional_instructions).toContain(projectContext.instructions);
    expect(graphMember?.tool_resources?.[EToolResources.file_search]?.files).toEqual([projectFile]);
  });

  it('adds ready Project files only to enabled File Search resources', async () => {
    const { agent, loadTools, db } = createMocks();
    agent.tools = [Tools.file_search];
    const originalTools = [...agent.tools];

    const result = await initializeAgent(
      {
        runtime: projectRuntime(),
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: true,
      },
      db,
    );

    expect(result.tool_resources).toEqual({
      [EToolResources.file_search]: { files: [projectFile] },
    });
    expect(result.tool_resources?.[EToolResources.file_search]).not.toHaveProperty('file_ids');
    expect(agent.tools).toEqual(originalTools);
    expect(agent).not.toHaveProperty('tool_resources');
    expect(db.getFiles).not.toHaveBeenCalled();
  });
  it('queues cleared Project files for the first search in a new conversation', async () => {
    const { agent, loadTools, db } = createMocks();
    agent.tools = [Tools.file_search];
    const repairing = {
      ...canonicalFile,
      embedded: false,
      source: FileSources.s3,
      metadata: { searchDestination: true },
    };
    const runtime = projectRuntime();
    runtime.chatProjectContext = {
      ...projectContext,
      resources: [toCanonicalProjectResource(repairing)],
    };
    const result = await initializeAgent(
      {
        runtime,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: true,
      },
      db,
    );
    expect(result.provisionState?.vectorDBFiles).toEqual([
      expect.objectContaining({
        file_id: 'project-file',
        embedded: false,
        source: FileSources.s3,
        metadata: { searchDestination: true },
      }),
    ]);
    expect(result.provisionState?.codeEnvFiles).toEqual([]);
    expect(result.provisionState?.agentScopedFileIds.size).toBe(0);
    expect(agent.tools).toEqual([Tools.file_search]);
    expect(db.getFiles).not.toHaveBeenCalled();
    expect(db.getProjectFiles).not.toHaveBeenCalled();
  });

  describe('retained Project repair endpoint policy', () => {
    const MB = 1024 * 1024;
    const realResources = jest.requireActual<typeof import('../resources')>('../resources');

    beforeEach(() => {
      jest.mocked(primeResources).mockImplementationOnce(realResources.primeResources);
    });

    function repairFile(
      overrides: Partial<ProjectFileRecord & TFile> = {},
    ): ProjectFileRecord & TFile {
      return {
        ...canonicalFile,
        embedded: false,
        source: FileSources.s3,
        storageKey: 'uploads/project.txt',
        storageRegion: 'us-east-1',
        tenantId: 'tenant-1',
        context: FileContext.message_attachment,
        bytes: MB / 2,
        metadata: { searchDestination: true },
        ...overrides,
      };
    }

    async function initializeRepairs({
      projectFiles = [repairFile()],
      current = [],
      deferred = [],
      persistent = [],
      fileConfig,
      filters,
    }: {
      projectFiles?: ProjectFileRecord[];
      current?: TFile[];
      deferred?: TFile[];
      persistent?: TFile[];
      fileConfig?: NonNullable<ServerRequest['config']>['fileConfig'];
      filters?: FiltersConfig;
    } = {}) {
      const { agent, loadTools, db } = createMocks();
      agent.tools = [Tools.file_search];
      agent.endpoint = EModelEndpoint.openAI;
      agent.tool_resources = {
        [EToolResources.file_search]: { file_ids: persistent.map((file) => file.file_id) },
      };
      const runtime = projectRuntime();
      runtime.user!.tenantId = 'tenant-1';
      runtime.appConfig.fileConfig = fileConfig;
      runtime.appConfig.filters = filters;
      runtime.chatProjectContext = {
        ...projectContext,
        file_ids: projectFiles.map((file) => file.file_id),
        resources: projectFiles.map(toCanonicalProjectResource),
      };
      const getFiles = jest.fn().mockResolvedValue(persistent);
      if (current.length > 0 || deferred.length > 0) {
        getFiles.mockResolvedValueOnce([...current, ...deferred]);
      }
      const getProjectFiles = jest.fn().mockResolvedValue(projectFiles);
      const getDeferredProvisionFiles = jest.fn().mockResolvedValue(deferred);
      const result = await initializeAgent(
        {
          runtime,
          agent,
          loadTools,
          requestFiles: current.map(({ file_id }) => ({ file_id }) as IMongoFile),
          conversationId: deferred.length > 0 ? 'repair-conversation' : undefined,
          allowedProviders: new Set([Providers.OPENAI]),
          useChatProjectContext: true,
          fileSearchAvailable: true,
        },
        {
          ...db,
          getFiles,
          getProjectFiles,
          getDeferredProvisionFiles,
          getConvoFiles: jest.fn().mockResolvedValue(deferred.map((file) => file.file_id)),
        },
      );
      return { result, runtime, getFiles, getProjectFiles, getDeferredProvisionFiles };
    }

    it.each([
      { policy: 'disabled files', config: { disabled: true } },
      { policy: 'MIME allowlist', config: { supportedMimeTypes: ['application/pdf'] } },
      { policy: 'per-file size', config: { fileSizeLimit: 0.25 } },
      { policy: 'total size', config: { totalSizeLimit: 0.25 } },
    ])('does not append or queue a repair rejected by $policy', async ({ config }) => {
      const { result, getFiles, getProjectFiles } = await initializeRepairs({
        fileConfig: { endpoints: { [EModelEndpoint.openAI]: config } },
      });
      expect(result.tool_resources?.[EToolResources.file_search]?.files ?? []).toEqual([]);
      expect(result.provisionState?.vectorDBFiles ?? []).toEqual([]);
      expect(getFiles).not.toHaveBeenCalled();
      expect(getProjectFiles).not.toHaveBeenCalled();
    });

    it.each([
      { routingMimeType: 'text/csv', allowed: 'text/csv', admitted: true },
      { routingMimeType: 'text/csv', allowed: 'text/plain', admitted: false },
      { routingMimeType: undefined, allowed: 'text/plain', admitted: true },
      { routingMimeType: undefined, allowed: 'text/csv', admitted: false },
    ])(
      'screens retained repairs routed as $routingMimeType against $allowed',
      async ({ routingMimeType, allowed, admitted }) => {
        const { result, getFiles, getProjectFiles } = await initializeRepairs({
          projectFiles: [
            repairFile({
              type: 'text/plain',
              metadata: {
                searchDestination: true,
                ...(routingMimeType !== undefined ? { routingMimeType } : {}),
              },
            }),
          ],
          fileConfig: {
            endpoints: { [EModelEndpoint.openAI]: { supportedMimeTypes: [allowed] } },
          },
        });
        const queued = result.provisionState?.vectorDBFiles ?? [];
        const attached = result.tool_resources?.[EToolResources.file_search]?.files ?? [];
        expect(queued).toHaveLength(admitted ? 1 : 0);
        expect(attached).toHaveLength(admitted ? 1 : 0);
        if (admitted) {
          expect(queued[0]).toMatchObject({
            type: 'text/plain',
            metadata: {
              searchDestination: true,
              ...(routingMimeType !== undefined ? { routingMimeType } : {}),
            },
          });
        }
        expect(getFiles).not.toHaveBeenCalled();
        expect(getProjectFiles).not.toHaveBeenCalled();
      },
    );

    it.each([undefined, false, true])(
      'queues an admitted repair without rereading it when retainedFileCleanup is %p',
      async (retainedFileCleanup) => {
        const { result, runtime, getFiles, getProjectFiles } = await initializeRepairs({
          fileConfig: {
            ...(retainedFileCleanup === undefined ? {} : { retainedFileCleanup }),
            endpoints: {
              [EModelEndpoint.openAI]: {
                supportedMimeTypes: ['text/plain'],
                fileSizeLimit: 0.5,
                totalSizeLimit: 0.5,
              },
            },
          },
        });
        const admitted = runtime.chatProjectContext.resources[0];
        if (admitted.availability !== 'ready') {
          throw new Error('Expected a ready Project fixture');
        }
        expect(result.provisionState?.vectorDBFiles).toEqual([admitted.file]);
        expect(result.provisionState?.vectorDBFiles[0]).toBe(admitted.file);
        expect(result.tool_resources?.[EToolResources.file_search]?.files).toEqual([admitted.file]);
        expect(admitted.file).toMatchObject({
          embedded: false,
          user: 'user-1',
          tenantId: 'tenant-1',
          source: FileSources.s3,
          storageKey: 'uploads/project.txt',
          storageRegion: 'us-east-1',
          metadata: { searchDestination: true },
        });
        expect(result.provisionState?.agentScopedFileIds.size).toBe(0);
        expect(getFiles).not.toHaveBeenCalled();
        expect(getProjectFiles).not.toHaveBeenCalled();
      },
    );

    it.each([false, true])(
      'rejects an over-budget Project repair that overlaps current files (deferred: %s)',
      async (deferred) => {
        const oversized = repairFile({ bytes: 2 * MB });
        const { result } = await initializeRepairs({
          projectFiles: [oversized],
          current: [oversized],
          deferred: deferred ? [oversized] : [],
          fileConfig: { endpoints: { [EModelEndpoint.openAI]: { totalSizeLimit: 1 } } },
        });
        expect(result.provisionState?.vectorDBFiles ?? []).toEqual([]);
        expect(result.tool_resources?.[EToolResources.file_search]?.files ?? []).toEqual([]);
      },
    );

    it.each([false, true])(
      'reserves current admission before deferred candidates (overlap first: %s)',
      async (overlapFirst) => {
        const current = repairFile({ file_id: 'current', bytes: (MB * 3) / 4 });
        const other = repairFile({ file_id: 'deferred', bytes: (MB * 3) / 4 });
        const { result } = await initializeRepairs({
          projectFiles: [current, other],
          current: [current],
          deferred: overlapFirst ? [current, other] : [other, current],
          fileConfig: { endpoints: { [EModelEndpoint.openAI]: { totalSizeLimit: 1 } } },
        });
        expect(result.provisionState?.vectorDBFiles.map((file) => file.file_id)).toEqual([
          'current',
        ]);
      },
    );

    it('does not charge duplicate current files twice before admitting other project repairs', async () => {
      const shared = repairFile({ file_id: 'shared-current', bytes: MB / 2 });
      const other = repairFile({ file_id: 'other-project', bytes: MB / 2 });
      const { result } = await initializeRepairs({
        projectFiles: [shared, other],
        current: [shared, shared],
        deferred: [shared, shared],
        fileConfig: { endpoints: { [EModelEndpoint.openAI]: { totalSizeLimit: 1 } } },
      });
      const ids = result.provisionState?.vectorDBFiles.map((file) => file.file_id) ?? [];
      expect(ids).toEqual(['shared-current', 'other-project']);
    });

    it('shares one allowance with current, deferred and persistent files, counting overlaps once', async () => {
      const shared = repairFile({ file_id: 'shared', bytes: MB / 4 });
      const currentOnly = repairFile({ file_id: 'current', bytes: MB / 8 });
      const deferredOnly = repairFile({ file_id: 'deferred', bytes: MB / 8 });
      const persistentOnly = repairFile({ file_id: 'persistent', bytes: MB / 4 });
      const fits = repairFile({ file_id: 'fits', bytes: MB / 4 });
      const overflow = repairFile({ file_id: 'overflow', bytes: MB / 8 });
      const { result, getFiles, getProjectFiles, getDeferredProvisionFiles } =
        await initializeRepairs({
          projectFiles: [shared, persistentOnly, fits, overflow],
          current: [shared, currentOnly],
          deferred: [shared, deferredOnly],
          persistent: [shared, persistentOnly],
          fileConfig: { endpoints: { [EModelEndpoint.openAI]: { totalSizeLimit: 1 } } },
        });
      const queuedIds = result.provisionState?.vectorDBFiles.map((file) => file.file_id) ?? [];
      expect(queuedIds).toEqual(
        expect.arrayContaining(['shared', 'current', 'deferred', 'persistent', 'fits']),
      );
      expect(queuedIds).not.toContain('overflow');
      expect(new Set(queuedIds).size).toBe(queuedIds.length);
      expect(result.tool_resources?.[EToolResources.file_search]?.files).toEqual(
        expect.arrayContaining([expect.objectContaining({ file_id: 'fits' })]),
      );
      expect(result.tool_resources?.[EToolResources.file_search]?.files).not.toEqual(
        expect.arrayContaining([expect.objectContaining({ file_id: 'overflow' })]),
      );
      expect(filterMock.filterFilesByEndpointRuntimeConfig).toHaveBeenLastCalledWith(
        expect.anything(),
        expect.objectContaining({
          consumedBytes: (MB * 3) / 4,
          files: [
            expect.objectContaining({ file_id: 'fits' }),
            expect.objectContaining({ file_id: 'overflow' }),
          ],
        }),
      );
      expect(getFiles).toHaveBeenCalledTimes(2);
      expect(getProjectFiles).not.toHaveBeenCalled();
      expect(getDeferredProvisionFiles).toHaveBeenCalledTimes(1);
    });

    it.each(['endpoint', 'content'])(
      'does not charge persistent files rejected by %s policy',
      async (policy) => {
        const persistent = repairFile({
          file_id: 'rejected-persistent',
          bytes: (MB * 3) / 4,
          ...(policy === 'endpoint' ? { type: 'application/pdf' } : { text: 'BLOCKED' }),
        });
        const { result } = await initializeRepairs({
          persistent: [persistent],
          filters: policy === 'content' ? projectFilePolicy : undefined,
          fileConfig: {
            endpoints: {
              [EModelEndpoint.openAI]: { supportedMimeTypes: ['text/plain'], totalSizeLimit: 1 },
            },
          },
        });
        expect(result.provisionState?.vectorDBFiles.map((file) => file.file_id)).toEqual([
          projectFile.file_id,
        ]);
        expect(filterMock.filterFilesByEndpointRuntimeConfig).toHaveBeenLastCalledWith(
          expect.anything(),
          expect.objectContaining({ consumedBytes: 0 }),
        );
      },
    );
  });

  it('adds Project files for file_search supplied by a manual Skill', async () => {
    const { agent, req, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    agent.tools = [];
    loadTools.mockImplementation(async ({ tools }: { tools: string[] }) => ({
      tools: [],
      toolContextMap: {},
      toolDefinitions: tools.map((name) => ({ name, description: '', parameters: {} })),
      hasDeferredTools: false,
    }));
    const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn().mockResolvedValue({
      _id: skillId,
      name: 'project-file-search',
      body: 'Search project files.',
      author: { toString: () => req.user!.id } as unknown as import('mongoose').Types.ObjectId,
      allowedTools: [Tools.file_search],
    });

    const result = await initializeAgent(
      {
        runtime: projectRuntime(),
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['project-file-search'],
      },
      {
        ...db,
        listSkillsByAccess: async () => ({ skills: [], has_more: false, after: null }),
        getSkillByName,
      },
    );

    expect(loadTools).toHaveBeenCalledWith(expect.objectContaining({ tools: [Tools.file_search] }));
    expect(result.tool_resources?.[EToolResources.file_search]?.files).toEqual([projectFile]);
  });

  it('does not hydrate or inject Project files when file_search is role-disabled', async () => {
    const { agent, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn().mockResolvedValue({
      _id: skillId,
      name: 'denied-project-file-search',
      body: 'Search project files.',
      author: { toString: () => 'user-1' } as unknown as import('mongoose').Types.ObjectId,
      allowedTools: [Tools.file_search],
    });
    const projectDb = {
      ...db,
      getProjectFiles: jest
        .fn()
        .mockRejectedValue(new Error('Project resource lookup unavailable')),
      listSkillsByAccess: async () => ({ skills: [], has_more: false, after: null }),
      getSkillByName,
    };

    const result = await initializeAgent(
      {
        runtime: {
          ...projectRuntime(),
          chatProjectContext: { ...projectContext, resources: [] },
          chatProjectFiles: undefined,
        },
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['denied-project-file-search'],
        fileSearchAvailable: false,
      },
      projectDb,
    );

    expect(projectDb.getProjectFiles).not.toHaveBeenCalled();
    expect(db.getFiles).not.toHaveBeenCalled();
    expect(result.tool_resources).toBeUndefined();
  });

  it('shares policy hydration across concurrent graph agents without injecting file text', async () => {
    const { agent, loadTools, db } = createMocks();
    agent.tools = [Tools.file_search];
    const getProjectFiles = jest.fn().mockResolvedValue([canonicalFile]);
    const projectDb = { ...db, getProjectFiles };
    const runtime = { ...projectRuntime(), chatProjectFiles: undefined };
    runtime.appConfig.filters = projectFilePolicy;
    const params = {
      runtime,
      agent,
      loadTools,
      endpointOption: { endpoint: EModelEndpoint.agents },
      allowedProviders: new Set([Providers.OPENAI]),
      useChatProjectContext: true,
    };
    const results = await Promise.all([
      initializeAgent(params, projectDb),
      initializeAgent(params, projectDb),
    ]);
    for (const result of results) {
      expect(result.tool_resources?.[EToolResources.file_search]?.files).toEqual([
        expect.objectContaining({ file_id: 'project-file', filepath: '/uploads/project.txt' }),
      ]);
      expect(result.tool_resources?.[EToolResources.file_search]?.files?.[0]).not.toHaveProperty(
        'text',
      );
      expect(result.attachments).not.toEqual(
        expect.arrayContaining([expect.objectContaining({ file_id: projectFile.file_id })]),
      );
    }
    expect(getProjectFiles).toHaveBeenCalledTimes(1);
  });

  it('rejects prohibited Project content before tool setup or usage mutation', async () => {
    const { agent, loadTools, db } = createMocks();
    agent.tools = [Tools.file_search];
    const runtime = projectRuntime();
    runtime.appConfig.filters = projectFilePolicy;
    const getProjectFiles = jest.fn().mockResolvedValue([{ ...canonicalFile, text: 'BLOCKED' }]);
    await expect(
      initializeAgent(
        {
          runtime,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          useChatProjectContext: true,
        },
        { ...db, getProjectFiles },
      ),
    ).rejects.toMatchObject({ code: 'content_filter_block' });
    expect(loadTools).not.toHaveBeenCalled();
    expect(db.updateFilesUsage).not.toHaveBeenCalled();
  });

  it.each(['expired', 'changed-version'])(
    'rejects a %s resource during policy hydration instead of replacing the admitted snapshot',
    async (change) => {
      const { agent, loadTools, db } = createMocks();
      agent.tools = [Tools.file_search];
      const runtime = projectRuntime();
      runtime.appConfig.filters = projectFilePolicy;
      const changedFile =
        change === 'expired'
          ? { ...canonicalFile, expiredAt: new Date(0) }
          : { ...canonicalFile, updatedAt: new Date('2030-01-01') };
      await expect(
        initializeAgent(
          {
            runtime,
            agent,
            loadTools,
            endpointOption: { endpoint: EModelEndpoint.agents },
            allowedProviders: new Set([Providers.OPENAI]),
            useChatProjectContext: true,
          },
          { ...db, getProjectFiles: jest.fn().mockResolvedValue([changedFile]) },
        ),
      ).rejects.toMatchObject({
        code: 'PROJECT_RESOURCES_CHANGED',
        status: 409,
        retryable: true,
      });
      expect(loadTools).not.toHaveBeenCalled();
      expect(db.updateFilesUsage).not.toHaveBeenCalled();
    },
  );

  it('does not inject Project guidance or resources into an auxiliary opt-out', async () => {
    const { agent, loadTools, db } = createMocks();
    agent.tools = [Tools.file_search];
    agent.additional_instructions = 'Auxiliary Agent guidance.';

    const result = await initializeAgent(
      {
        runtime: projectRuntime(),
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: false,
      },
      db,
    );

    expect(result.additional_instructions).toBe('Auxiliary Agent guidance.');
    expect(result.additional_instructions).not.toContain('Project guidance');
    expect(result.tool_resources).toBeUndefined();
  });

  it('never enables disabled File Search for Project files', async () => {
    const { agent, loadTools, db } = createMocks();

    const result = await initializeAgent(
      {
        runtime: { ...projectRuntime(), chatProjectFiles: undefined },
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: true,
      },
      db,
    );

    expect(result.tools).toEqual([]);
    expect(result.toolDefinitions).toEqual([]);
    expect(result.tool_resources).toBeUndefined();
    expect(db.getFiles).not.toHaveBeenCalled();
  });
});

describe('initializeAgent — current content policy preflight', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('rejects a blocked stored definition before file, resource, tool, or provider side effects', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { primeResources } = jest.requireMock('../resources') as {
      primeResources: jest.Mock;
    };
    agent.instructions = 'Use PRIVATE-INSTRUCTIONS for every response';
    req.config = {
      filters: {
        agentInstructions: {
          pii: {
            starterPatterns: [],
            customPatterns: [
              {
                id: 'private',
                label: 'private value',
                regex: 'PRIVATE-[A-Z]+',
              },
            ],
          },
        },
      },
    } as unknown as ServerRequest['config'];

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          requestFiles: [{ file_id: 'file-1' } as IMongoFile],
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
        },
        db,
      ),
    ).rejects.toMatchObject({
      code: 'content_filter_block',
      body: {
        error: 'content_filter_block',
        source: 'agent_instruction',
        field: 'instructions',
      },
    });

    expect(db.updateFilesUsage).not.toHaveBeenCalled();
    expect(primeResources).not.toHaveBeenCalled();
    expect(loadTools).not.toHaveBeenCalled();
    expect(mockGetProviderConfig).not.toHaveBeenCalled();
  });

  it('does not treat unresolved canonical file IDs as agent-definition text', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tool_resources = {
      [EToolResources.context]: {
        file_ids: ['canonical-file-1'],
      },
    };
    req.config = {
      filters: {
        files: {
          pii: {
            starterPatterns: ['sk_prefix'],
            uninspectable: 'block',
          },
        },
      },
    } as unknown as ServerRequest['config'];

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
        },
        db,
      ),
    ).resolves.toBeDefined();
  });

  it('rejects a blocked resolved skill before resource or provider side effects', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { primeResources } = jest.requireMock('../resources') as {
      primeResources: jest.Mock;
    };
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn().mockResolvedValue({
      _id: skillId,
      name: 'private-skill',
      body: 'Follow PRIVATE-SKILL before answering',
      author: {
        toString: () => req.user?.id,
      } as unknown as import('mongoose').Types.ObjectId,
    });
    req.config = {
      filters: {
        skills: {
          pii: {
            starterPatterns: [],
            customPatterns: [
              {
                id: 'private',
                label: 'private value',
                regex: 'PRIVATE-[A-Z]+',
              },
            ],
          },
        },
      },
    } as unknown as ServerRequest['config'];

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          requestFiles: [{ file_id: 'file-1' } as IMongoFile],
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          accessibleSkillIds: [skillId],
          manualSkills: ['private-skill'],
        },
        { ...db, getSkillByName },
      ),
    ).rejects.toMatchObject({
      code: 'content_filter_block',
      body: {
        error: 'content_filter_block',
        source: 'skill',
        field: 'instructions',
      },
    });

    expect(getSkillByName).toHaveBeenCalled();
    expect(db.updateFilesUsage).not.toHaveBeenCalled();
    expect(primeResources).not.toHaveBeenCalled();
    expect(loadTools).not.toHaveBeenCalled();
    expect(mockGetProviderConfig).not.toHaveBeenCalled();
  });

  it('inspects only the deduped model-bound skill definition when manual invocation wins', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const author = {
      toString: () => req.user?.id,
    } as unknown as import('mongoose').Types.ObjectId;
    const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn().mockResolvedValue({
      _id: skillId,
      name: 'shared-skill',
      body: 'Safe manually selected instructions',
      author,
    });
    const listAlwaysApplySkills: InitializeAgentDbMethods['listAlwaysApplySkills'] = jest
      .fn()
      .mockResolvedValue({
        skills: [
          {
            _id: skillId,
            name: 'shared-skill',
            body: 'Discarded PRIVATE-SKILL definition',
            author,
          },
        ],
        has_more: false,
        after: null,
      });
    req.config = {
      filters: {
        skills: {
          pii: {
            starterPatterns: [],
            customPatterns: [{ id: 'private', label: 'private value', regex: 'PRIVATE-[A-Z]+' }],
          },
        },
      },
    } as unknown as ServerRequest['config'];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['shared-skill'],
      },
      {
        ...db,
        getSkillByName,
        listAlwaysApplySkills,
        listSkillsByAccess: async () => ({ skills: [], has_more: false, after: null }),
      },
    );

    expect(result.manualSkillPrimes).toEqual([
      expect.objectContaining({
        name: 'shared-skill',
        body: 'Safe manually selected instructions',
      }),
    ]);
    expect(result.alwaysApplySkillPrimes).toEqual([]);
  });

  it('does not traverse resolved skill metadata when skill policy is inactive', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const broadFrontmatter = Object.fromEntries(
      Array.from({ length: 4_200 }, (_, index) => [`field-${index}`, `value-${index}`]),
    );
    const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn().mockResolvedValue({
      _id: skillId,
      name: 'broad-skill',
      body: 'Safe instructions',
      frontmatter: broadFrontmatter,
      author: { toString: () => req.user?.id } as unknown as import('mongoose').Types.ObjectId,
    });
    req.config = {
      filters: {
        messages: { pii: { starterPatterns: ['sk_prefix'] } },
      },
    } as unknown as ServerRequest['config'];

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          accessibleSkillIds: [skillId],
          manualSkills: ['broad-skill'],
        },
        { ...db, getSkillByName },
      ),
    ).resolves.toBeDefined();
  });

  it('fails closed on traversal only when the affected skill field is selected', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn().mockResolvedValue({
      _id: skillId,
      name: 'broad-skill',
      body: 'Safe instructions',
      frontmatter: Object.fromEntries(
        Array.from({ length: 4_200 }, (_, index) => [`field-${index}`, `value-${index}`]),
      ),
      author: { toString: () => req.user?.id } as unknown as import('mongoose').Types.ObjectId,
    });
    req.config = {
      filters: {
        skills: {
          pii: {
            fields: ['frontmatter'],
            starterPatterns: ['sk_prefix'],
          },
        },
      },
    } as unknown as ServerRequest['config'];

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          accessibleSkillIds: [skillId],
          manualSkills: ['broad-skill'],
        },
        { ...db, getSkillByName },
      ),
    ).rejects.toMatchObject({ code: 'content_filter_uninspectable' });
  });

  it('rejects blocked active skill-catalog metadata before resource or provider side effects', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { primeResources } = jest.requireMock('../resources') as {
      primeResources: jest.Mock;
    };
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const listSkillsByAccess: InitializeAgentDbMethods['listSkillsByAccess'] = jest
      .fn()
      .mockResolvedValue({
        skills: [
          {
            _id: skillId,
            name: 'catalog-skill',
            description: 'Use PRIVATE-CATALOG data',
            author: {
              toString: () => req.user?.id,
            } as unknown as import('mongoose').Types.ObjectId,
          },
        ],
        has_more: false,
        after: null,
      });
    req.config = {
      filters: {
        skills: {
          pii: {
            starterPatterns: [],
            customPatterns: [
              {
                id: 'private',
                label: 'private value',
                regex: 'PRIVATE-[A-Z]+',
              },
            ],
          },
        },
      },
    } as unknown as ServerRequest['config'];

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          requestFiles: [{ file_id: 'file-1' } as IMongoFile],
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          accessibleSkillIds: [skillId],
        },
        { ...db, listSkillsByAccess },
      ),
    ).rejects.toMatchObject({
      code: 'content_filter_block',
      body: {
        error: 'content_filter_block',
        source: 'skill',
        field: 'description',
      },
    });

    expect(listSkillsByAccess).toHaveBeenCalledTimes(1);
    expect(db.updateFilesUsage).not.toHaveBeenCalled();
    expect(primeResources).not.toHaveBeenCalled();
    expect(loadTools).not.toHaveBeenCalled();
    expect(mockGetProviderConfig).not.toHaveBeenCalled();
  });

  it('reuses a safe inspected skill-catalog snapshot during initialization', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const listSkillsByAccess: InitializeAgentDbMethods['listSkillsByAccess'] = jest
      .fn()
      .mockResolvedValue({
        skills: [
          {
            _id: skillId,
            name: 'safe-skill',
            description: 'Safe catalog description',
            author: {
              toString: () => req.user?.id,
            } as unknown as import('mongoose').Types.ObjectId,
          },
        ],
        has_more: false,
        after: null,
      });
    req.config = {
      filters: {
        skills: {
          pii: {
            starterPatterns: ['sk_prefix'],
          },
        },
      },
    } as unknown as ServerRequest['config'];

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
      },
      { ...db, listSkillsByAccess },
    );

    expect(listSkillsByAccess).toHaveBeenCalledTimes(1);
  });
});

describe('initializeAgent — custom provider token lookup', () => {
  const CUSTOM_PROVIDER = 'EduGPT';

  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('passes the resolved provider endpoint to getModelMaxTokens, not the custom name', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: CUSTOM_PROVIDER,
      overrideProvider: Providers.OPENAI,
      model: 'qwen3-235b-a22b',
      useRealTokenLookup: true,
    });

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([CUSTOM_PROVIDER]),
        isInitialAgent: true,
      },
      db,
    );

    // providerEndpointMap["openAI"] = "openAI" (valid), not providerEndpointMap["EduGPT"] = undefined
    expect(mockGetModelMaxTokens).toHaveBeenCalledWith(
      'qwen3-235b-a22b',
      EModelEndpoint.openAI,
      undefined,
    );
  });

  it('uses endpointTokenConfig from the custom endpoint for unrecognized models', async () => {
    const customTokenConfig: EndpointTokenConfig = {
      'my-custom-model-v1': { context: 65536, prompt: 1, completion: 1 },
    };
    const { agent, req, res, loadTools, db } = createMocks({
      provider: CUSTOM_PROVIDER,
      overrideProvider: Providers.OPENAI,
      model: 'my-custom-model-v1',
      endpointTokenConfig: customTokenConfig,
      useRealTokenLookup: true,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([CUSTOM_PROVIDER]),
        isInitialAgent: true,
      },
      db,
    );

    expect(mockGetModelMaxTokens).toHaveBeenCalledWith(
      'my-custom-model-v1',
      EModelEndpoint.openAI,
      customTokenConfig,
    );

    // Pipeline check: verifies endpointTokenConfig.context flows through the full
    // optionalChainWithEmptyCheck → Math.max formula. The toHaveBeenCalledWith
    // assertion above catches the actual provider-resolution regression.
    expect(result.maxContextTokens).toBe(Math.round((65536 - 4096) * 0.95));
  });
});

describe('initializeAgent — provider web_search precedence', () => {
  const nativeWebSearchTool = {
    type: 'web_search_20250305',
    name: Tools.web_search,
  };
  const nativeGoogleSearchTool = { googleSearch: {} };
  const libreChatWebSearchDefinition = {
    name: Tools.web_search,
    description: 'Search the web',
    parameters: { type: 'object', properties: {} },
  };
  const mcpToolDefinition = {
    name: 'mcp_lookup',
    description: 'Lookup context',
    parameters: { type: 'object', properties: {} },
  };

  beforeEach(() => {
    jest.clearAllMocks();
  });

  async function initializeGoogleMixedToolAgent(model: string, provider = Providers.GOOGLE) {
    const { agent, req, res, loadTools, db } = createMocks({
      provider,
      model,
      providerTools: [nativeGoogleSearchTool],
      loadedToolDefinitions: [mcpToolDefinition],
    });
    agent.tools = ['mcp_lookup'];

    return initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([provider]),
        isInitialAgent: true,
      },
      db,
    );
  }

  it('keeps Anthropic native web_search when LibreChat search is not selected', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.ANTHROPIC,
      providerTools: [nativeWebSearchTool],
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.ANTHROPIC]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.tools).toEqual([nativeWebSearchTool]);
    expect(countNamedWebSearchTools(result.tools)).toBe(1);
    expect(countWebSearchDefinitions(result.toolDefinitions)).toBe(0);
  });

  it('keeps LibreChat web_search definitions when native Anthropic search is not enabled', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.ANTHROPIC,
      loadedToolDefinitions: [libreChatWebSearchDefinition],
    });
    agent.tools = [Tools.web_search];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.ANTHROPIC]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.tools).toEqual([]);
    expect(countNamedWebSearchTools(result.tools)).toBe(0);
    expect(countWebSearchDefinitions(result.toolDefinitions)).toBe(1);
  });

  it('prefers LibreChat web_search when Anthropic native search is also enabled', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.ANTHROPIC,
      providerTools: [nativeWebSearchTool],
      loadedToolDefinitions: [libreChatWebSearchDefinition],
    });
    agent.tools = [Tools.web_search];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.ANTHROPIC]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.tools).toEqual([]);
    expect(countNamedWebSearchTools(result.tools)).toBe(0);
    expect(countWebSearchDefinitions(result.toolDefinitions)).toBe(1);
  });

  it('keeps Google native search when LibreChat web_search is not selected', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.GOOGLE,
      model: 'gemini-3.5-flash',
      providerTools: [nativeGoogleSearchTool],
      loadedToolDefinitions: [mcpToolDefinition],
    });
    agent.tools = ['mcp_lookup'];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.GOOGLE]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.tools).toEqual([nativeGoogleSearchTool]);
    expect(countGoogleSearchTools(result.tools)).toBe(1);
    expect(result.toolDefinitions).toContain(mcpToolDefinition);
    expect(result.model_parameters).toEqual(
      expect.objectContaining({
        includeServerSideToolInvocations: true,
      }),
    );
  });

  it('includes the mixed-tool flag for Vertex AI native search with external tools', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.VERTEXAI,
      model: 'gemini-3.5-flash',
      providerTools: [nativeGoogleSearchTool],
      loadedToolDefinitions: [mcpToolDefinition],
    });
    agent.tools = ['mcp_lookup'];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.VERTEXAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.tools).toEqual([nativeGoogleSearchTool]);
    expect(result.toolDefinitions).toContain(mcpToolDefinition);
    expect(result.model_parameters).toEqual(
      expect.objectContaining({
        includeServerSideToolInvocations: true,
      }),
    );
  });

  it.each([
    'gemini-3-flash-preview',
    'gemini-3-pro-preview',
    'gemini-3.1-pro-preview',
    'gemini-3.1-pro-preview-customtools',
    'gemini-3.1-flash-lite',
    'gemini-3.1-flash-lite-preview',
    'gemini-3.5-flash',
    'google/gemini-3.5-flash-latest',
    'models/gemini-3.10-pro-preview',
    'gemini-4-pro-preview',
  ])('allows Google mixed tools for supported Gemini text model %s', async (model) => {
    const result = await initializeGoogleMixedToolAgent(model);

    expect(result.tools).toEqual([nativeGoogleSearchTool]);
    expect(result.toolDefinitions).toContain(mcpToolDefinition);
    expect(result.model_parameters).toEqual(
      expect.objectContaining({
        includeServerSideToolInvocations: true,
      }),
    );
  });

  it('sets the mixed-tool flag when the skill catalog adds the external tool', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.GOOGLE,
      model: 'gemini-3.5-flash',
      providerTools: [nativeGoogleSearchTool],
    });
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const author = {
      toString: () => req.user?.id,
    } as unknown as import('mongoose').Types.ObjectId;

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.GOOGLE]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
      },
      {
        ...db,
        listSkillsByAccess: jest.fn().mockResolvedValue({
          skills: [
            {
              _id: skillId,
              name: 'research-helper',
              description: 'Research current information.',
              author,
            },
          ],
          has_more: false,
          after: null,
        }),
      },
    );

    expect(result.tools).toEqual([nativeGoogleSearchTool]);
    expect(result.toolDefinitions?.map((toolDefinition) => toolDefinition.name)).toContain('skill');
    expect(result.model_parameters).toEqual(
      expect.objectContaining({
        includeServerSideToolInvocations: true,
      }),
    );
  });

  it.each([
    'gemini-2.5-flash',
    'gemini-3',
    'gemini-3.1',
    'gemini-3-pro-image-preview',
    'gemini-3.1-flash-image',
    'gemini-3.5-flash-live',
    'gemini-4-pro-tts',
  ])('rejects Google mixed tools for unsupported Gemini model %s', async (model) => {
    await expect(initializeGoogleMixedToolAgent(model)).rejects.toThrow(/google_tool_conflict/);
  });

  it('prefers LibreChat web_search when Google native search is also enabled', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.GOOGLE,
      providerTools: [nativeGoogleSearchTool],
      loadedToolDefinitions: [libreChatWebSearchDefinition],
    });
    agent.tools = [Tools.web_search];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.GOOGLE]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.tools).toEqual([]);
    expect(countGoogleSearchTools(result.tools)).toBe(0);
    expect(countWebSearchDefinitions(result.toolDefinitions)).toBe(1);
  });

  it('leaves providers without a native web search conflict unchanged', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.OPENAI,
      providerTools: [nativeWebSearchTool],
      loadedToolDefinitions: [libreChatWebSearchDefinition],
    });
    agent.tools = [Tools.web_search];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.tools).toEqual([nativeWebSearchTool]);
    expect(countNamedWebSearchTools(result.tools)).toBe(1);
    expect(countWebSearchDefinitions(result.toolDefinitions)).toBe(1);
  });

  it('treats the Google urlContext tool as a native provider tool', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.GOOGLE,
      model: 'gemini-1.5-flash',
      providerTools: [{ urlContext: {} }],
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.GOOGLE]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.tools).toEqual([{ urlContext: {} }]);
    expect(countUrlContextTools(result.tools)).toBe(1);
  });

  it('preserves the Google urlContext tool when LibreChat web_search is also enabled', async () => {
    /**
     * url_context is unrelated to web search, so the LibreChat web_search conflict
     * resolver must not strip the native urlContext tool. The combination of a
     * provider tool with an agent tool requires a combination-capable Gemini model.
     */
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.GOOGLE,
      model: 'gemini-3.5-flash',
      providerTools: [{ urlContext: {} }],
      loadedToolDefinitions: [libreChatWebSearchDefinition],
    });
    agent.tools = [Tools.web_search];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.GOOGLE]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.tools).toEqual([{ urlContext: {} }]);
    expect(countUrlContextTools(result.tools)).toBe(1);
    expect(countWebSearchDefinitions(result.toolDefinitions)).toBe(1);
  });
});

describe('initializeAgent — stable and dynamic instruction fields', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('moves instructions with temporal special vars into the dynamic tail using the turn start', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.instructions =
      'Today is {{current_date}}. The turn began at {{current_datetime}} ({{iso_datetime}}).';
    req.conversationCreatedAt = '2026-08-25T10:00:00.000Z';
    req.turnStartedAt = new Date('2026-08-31T06:20:00.000Z').getTime();
    req.body = { timezone: 'UTC' };

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.instructions).toBeUndefined();
    expect(result.additional_instructions).toBe(
      'Today is 2026-08-31 (Monday). The turn began at 2026-08-31 06:20:00 +00:00 (Monday) (2026-08-31T06:20:00.000Z).',
    );
  });

  it('resolves temporal special vars in the request timezone', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.instructions = 'It is currently {{current_datetime}}.';
    req.turnStartedAt = new Date('2024-01-15T18:30:00.000Z').getTime();
    req.body = { timezone: 'America/New_York' };

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.instructions).toBeUndefined();
    expect(result.additional_instructions).toBe(
      'It is currently 2024-01-15 13:30:00 -05:00 (Monday).',
    );
  });

  it('keeps non-temporal special vars in stable instructions', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.instructions = 'You are helping {{current_user}}.';
    req.user = { id: 'user-1', name: 'Test User' } as never;

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.instructions).toBe('You are helping Test User.');
    expect(result.additional_instructions).toBeUndefined();
  });

  it('appends generated artifact guidance without replacing existing dynamic instructions', async () => {
    const { generateArtifactsPrompt } = jest.requireMock('~/prompts') as {
      generateArtifactsPrompt: jest.Mock;
    };
    generateArtifactsPrompt.mockReturnValue('Artifact guidance');

    const { agent, req, res, loadTools, db } = createMocks();
    agent.additional_instructions = 'Existing dynamic';
    agent.artifacts = 'enabled' as never;

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.additional_instructions).toBe('Existing dynamic\n\nArtifact guidance');
  });
});

describe('initializeAgent — attachment scoping', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('keeps request attachments separate from agent context attachments', async () => {
    const { primeResources } = jest.requireMock('../resources') as {
      primeResources: jest.Mock;
    };
    const requestFile = { file_id: 'request-file', filename: 'request.txt' };
    const agentContextFile = { file_id: 'agent-context-file', filename: 'agent-context.txt' };
    primeResources.mockResolvedValueOnce({
      attachments: [agentContextFile, requestFile],
      requestAttachments: [requestFile],
      agentContextAttachments: [agentContextFile],
      tool_resources: undefined,
    });

    const { agent, req, res, loadTools, db } = createMocks();

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.attachments).toEqual([agentContextFile, requestFile]);
    expect(result.requestAttachments).toEqual([requestFile]);
    expect(result.agentContextAttachments).toEqual([agentContextFile]);
  });

  it('applies aggregate limits only to endpoint-compatible file survivors', async () => {
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const incompatibleFiles = Array.from({ length: 11 }, (_, index) => ({
      file_id: `incompatible-${index}`,
      filename: `incompatible-${index}.bin`,
      type: 'application/x-incompatible',
      bytes: 1024,
    })) as IMongoFile[];
    const { agent, req, res, loadTools, db } = createMocks();
    mockExtractLibreChatParams.mockReturnValueOnce({
      resendFiles: true,
      maxContextTokens: undefined,
      modelOptions: { model: agent.model },
    });
    (db.getFiles as jest.Mock).mockResolvedValueOnce(incompatibleFiles);
    filterFilesByEndpointRuntimeConfig.mockReturnValueOnce([]);

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          requestFiles: incompatibleFiles,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
        },
        db,
      ),
    ).resolves.toBeDefined();
    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
      req.config,
      expect.objectContaining({ files: incompatibleFiles }),
    );
  });

  it('does not apply model attachment limits to tool-only workspace files', async () => {
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const toolFiles = Array.from({ length: 11 }, (_, index) => ({
      file_id: `tool-${index}`,
      filename: `tool-${index}.txt`,
      type: 'text/plain',
      bytes: 1024,
    })) as IMongoFile[];
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [EToolResources.file_search];
    mockExtractLibreChatParams.mockReturnValueOnce({
      resendFiles: true,
      maxContextTokens: undefined,
      modelOptions: { model: agent.model },
    });
    (db.getConvoFiles as jest.Mock).mockResolvedValueOnce(toolFiles.map((file) => file.file_id));
    (db.getToolFilesByIds as jest.Mock).mockResolvedValueOnce(toolFiles);
    (db.getFiles as jest.Mock).mockResolvedValueOnce(toolFiles);
    filterFilesByEndpointRuntimeConfig.mockImplementationOnce(
      (_config: ServerRequest['config'], { files }: { files: IMongoFile[] }) => files,
    );

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          conversationId: 'conversation-1',
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
        },
        db,
      ),
    ).resolves.toBeDefined();
  });

  it('does not apply model attachment limits to a tool-only current request file', async () => {
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const toolOnlyRequestFile = {
      file_id: 'request-tool-only',
      filename: 'workspace.bin',
      type: 'application/octet-stream',
      bytes: 200 * 1024 * 1024,
      embedded: true,
    } as IMongoFile;
    const { agent, req, res, loadTools, db } = createMocks();
    mockExtractLibreChatParams.mockReturnValueOnce({
      resendFiles: true,
      maxContextTokens: undefined,
      modelOptions: { model: agent.model },
    });
    (db.getFiles as jest.Mock).mockResolvedValueOnce([toolOnlyRequestFile]);
    filterFilesByEndpointRuntimeConfig.mockImplementationOnce(
      (_config: ServerRequest['config'], { files }: { files: IMongoFile[] }) => files,
    );

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          requestFiles: [toolOnlyRequestFile],
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
        },
        db,
      ),
    ).resolves.toBeDefined();
  });

  it.each([
    ['no conversation file IDs', [], true, true],
    ['only a sibling-branch file ID', ['sibling-file'], true, true],
    ['no file references on the active branch', ['sibling-file'], false, true],
    ['an unanchored continuation', ['embedded-message-file'], true, false],
  ])(
    'restores search files with %s',
    async (_case, conversationFiles, hasBranchFile, hasAnchor) => {
      const { primeResources } = jest.requireMock('../resources') as { primeResources: jest.Mock };
      const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
        filterFilesByEndpointRuntimeConfig: jest.Mock;
      };
      const file = {
        file_id: 'embedded-message-file',
        user: 'user-1',
        filename: 'report.pdf',
        filepath: '/uploads/report.pdf',
        object: 'file',
        source: FileSources.local,
        type: 'application/pdf',
        bytes: 1024,
        usage: 0,
        context: FileContext.message_attachment,
        embedded: true,
        llmDeliveryPath: 'none',
        metadata: { destinationChosen: false, embeddedEntities: ['user-1'] },
      };
      const { agent, req, res, loadTools, db } = createMocks({
        loadedToolDefinitions: [{ name: Tools.file_search }],
      });
      agent.tools = [Tools.file_search];
      req.resolvedConversation = { conversationId: 'conv-1', files: conversationFiles };
      mockExtractLibreChatParams.mockReturnValueOnce({
        resendFiles: true,
        maxContextTokens: undefined,
        modelOptions: { model: agent.model },
      });
      if (hasAnchor) {
        mockGetThreadData.mockImplementationOnce(realUtils.getThreadData);
      }
      filterFilesByEndpointRuntimeConfig.mockImplementation(
        (_config: ServerRequest['config'], { files }: { files: IMongoFile[] }) => files,
      );
      primeResources.mockImplementationOnce(
        jest.requireActual<typeof import('../resources')>('../resources').primeResources,
      );
      const getMessages = jest.fn().mockResolvedValue([
        {
          messageId: 'uploaded-message',
          parentMessageId: Constants.NO_PARENT,
          files: hasBranchFile ? [{ file_id: file.file_id }] : [],
        },
        { messageId: 'first-reply', parentMessageId: 'uploaded-message' },
        {
          messageId: 'sibling-message',
          parentMessageId: Constants.NO_PARENT,
          files: [{ file_id: 'sibling-file' }],
        },
      ]);
      const allFiles = new Map([
        [file.file_id, file],
        ['sibling-file', { ...file, file_id: 'sibling-file', filename: 'sibling.pdf' }],
      ]);
      const getToolFilesByIds = jest
        .fn()
        .mockImplementation(async (ids: string[]) =>
          ids.map((id) => allFiles.get(id)).filter((entry) => entry != null),
        );
      const getFiles = jest
        .fn()
        .mockImplementation(async (filter: { file_id: { $in: string[] } }) =>
          filter.file_id.$in.map((id) => allFiles.get(id)).filter((entry) => entry != null),
        );

      const result = await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          conversationId: 'conv-1',
          parentMessageId: hasAnchor ? 'first-reply' : undefined,
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          fileSearchAvailable: true,
        },
        {
          ...db,
          getMessages,
          getToolFilesByIds,
          getFiles,
          getDeferredProvisionFiles: jest.fn().mockResolvedValue([]),
        },
      );

      const expectedFileIds = hasBranchFile ? [file.file_id] : [];
      expect(getToolFilesByIds).toHaveBeenCalledWith(
        expectedFileIds,
        new Set([EToolResources.file_search]),
        {
          userId: 'user-1',
          tenantId: undefined,
        },
      );
      expect(
        result.tool_resources?.[EToolResources.file_search]?.files?.map((entry) => entry.file_id) ??
          [],
      ).toEqual(expectedFileIds);
      expect(result.provisionState?.vectorDBFiles ?? []).toEqual([]);
      expect(db.getConvoFiles).not.toHaveBeenCalled();
      if (!hasAnchor) {
        expect(getMessages).not.toHaveBeenCalled();
      }
    },
  );

  it('owner-scopes request file usage updates while preserving trusted tool files', async () => {
    const { primeResources } = jest.requireMock('../resources') as {
      primeResources: jest.Mock;
    };
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const requestFile = { file_id: 'request-file', filename: 'request.txt' } as IMongoFile;
    const toolFile = { file_id: 'tool-file', filename: 'tool.txt' } as IMongoFile;
    const { agent, req, res, loadTools, db } = createMocks();

    agent.tools = [EToolResources.file_search];
    mockExtractLibreChatParams.mockReturnValueOnce({
      resendFiles: true,
      maxContextTokens: undefined,
      modelOptions: { model: agent.model },
    });
    (db.getFiles as jest.Mock).mockResolvedValueOnce([requestFile, toolFile]);
    (db.getConvoFiles as jest.Mock).mockResolvedValueOnce([toolFile.file_id]);
    (db.getToolFilesByIds as jest.Mock).mockResolvedValueOnce([toolFile]);
    (db.updateFilesUsage as jest.Mock)
      .mockResolvedValueOnce([{ ...requestFile, filename: 'post-mutation-request.txt' }])
      .mockResolvedValueOnce([{ ...toolFile, filename: 'post-mutation-tool.txt' }]);
    filterFilesByEndpointRuntimeConfig.mockImplementationOnce(
      (_req: ServerRequest, { files }: { files: IMongoFile[] }) => files,
    );

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        requestFiles: [requestFile],
        conversationId: 'conversation-1',
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(db.getToolFilesByIds).toHaveBeenCalledWith(
      [toolFile.file_id],
      new Set([EToolResources.file_search]),
      { userId: 'user-1', tenantId: undefined },
    );
    expect(db.getFiles).toHaveBeenCalledWith(
      {
        file_id: { $in: [requestFile.file_id, toolFile.file_id] },
        user: 'user-1',
      },
      {},
      {},
    );
    expect(db.updateFilesUsage).toHaveBeenNthCalledWith(1, [requestFile], undefined, {
      user: 'user-1',
      tenantId: undefined,
    });
    expect(db.updateFilesUsage).toHaveBeenNthCalledWith(2, [toolFile], undefined, {
      user: 'user-1',
      tenantId: undefined,
    });
    await expect(primeResources.mock.calls[0][0].attachments).resolves.toEqual([
      requestFile,
      toolFile,
    ]);
  });

  it('rejects blocked resent file content before usage mutation or resource priming', async () => {
    const { primeResources } = jest.requireMock('../resources') as {
      primeResources: jest.Mock;
    };
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const blockedFile = {
      file_id: 'blocked-file',
      filename: 'stored.txt',
      text: 'PRIVATE-FILE',
    } as IMongoFile;
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [EToolResources.file_search];
    req.config = {
      filters: {
        files: {
          pii: {
            fields: ['extracted_text'],
            starterPatterns: [],
            customPatterns: [
              {
                id: 'private',
                label: 'private value',
                regex: 'PRIVATE-[A-Z]+',
              },
            ],
          },
        },
      },
    } as unknown as ServerRequest['config'];
    mockExtractLibreChatParams.mockReturnValueOnce({
      resendFiles: true,
      maxContextTokens: undefined,
      modelOptions: { model: agent.model },
    });
    (db.getConvoFiles as jest.Mock).mockResolvedValueOnce([blockedFile.file_id]);
    (db.getToolFilesByIds as jest.Mock).mockResolvedValueOnce([blockedFile]);
    (db.getFiles as jest.Mock).mockResolvedValueOnce([blockedFile]);
    filterFilesByEndpointRuntimeConfig.mockImplementationOnce(
      (_req: ServerRequest, { files }: { files: IMongoFile[] }) => files,
    );

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          conversationId: 'conversation-1',
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
        },
        db,
      ),
    ).rejects.toMatchObject({
      code: 'content_filter_block',
      body: {
        error: 'content_filter_block',
        source: 'file',
        field: 'extracted_text',
      },
    });

    expect(db.updateFilesUsage).not.toHaveBeenCalled();
    expect(primeResources).not.toHaveBeenCalled();
    expect(loadTools).not.toHaveBeenCalled();
    expect(mockGetProviderConfig).toHaveBeenCalledTimes(1);
  });
});

describe('initializeAgent — maxContextTokens', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it.each(['us.openai.gpt-6-sol', 'global.openai.gpt-6-astra', 'us.openai.gpt-5.6-terra'])(
    'budgets %s using the Bedrock context window',
    async (model) => {
      const { agent, req, res, loadTools, db } = createMocks({
        provider: Providers.BEDROCK,
        model,
        maxOutputTokens: 4096,
        useRealTokenLookup: true,
      });

      const result = await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.BEDROCK]),
          isInitialAgent: true,
        },
        db,
      );

      expect(mockGetModelMaxTokens).toHaveBeenCalledWith(model, EModelEndpoint.bedrock, undefined);
      expect(result.maxContextTokens).toBe(Math.round((950000 - 4096) * 0.95));
      expect(result.maxContextTokens).toBeGreaterThan(38079);
    },
  );

  it('uses user-configured maxContextTokens when provided via model_parameters', async () => {
    const userValue = 50000;
    const { agent, req, res, loadTools, db } = createMocks({
      maxContextTokens: userValue,
      modelDefault: 200000,
      maxOutputTokens: 4096,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: {
          endpoint: EModelEndpoint.agents,
          model_parameters: { maxContextTokens: userValue },
        },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.maxContextTokens).toBe(userValue);
  });

  it('falls back to formula when maxContextTokens is NOT provided', async () => {
    const modelDefault = 200000;
    const maxOutputTokens = 4096;
    const { agent, req, res, loadTools, db } = createMocks({
      maxContextTokens: undefined,
      modelDefault,
      maxOutputTokens,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    const expected = Math.round((modelDefault - maxOutputTokens) * 0.95);
    expect(result.maxContextTokens).toBe(expected);
  });

  it('falls back to formula when maxContextTokens is 0', async () => {
    const maxOutputTokens = 4096;
    const { agent, req, res, loadTools, db } = createMocks({
      maxContextTokens: 0,
      modelDefault: 200000,
      maxOutputTokens,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: {
          endpoint: EModelEndpoint.agents,
          model_parameters: { maxContextTokens: 0 },
        },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.maxContextTokens).not.toBe(0);
    const expected = Math.round((DEFAULT_MAX_CONTEXT_TOKENS - maxOutputTokens) * 0.95);
    expect(result.maxContextTokens).toBe(expected);
  });

  it('falls back to formula when maxContextTokens is negative', async () => {
    const maxOutputTokens = 4096;
    const { agent, req, res, loadTools, db } = createMocks({
      maxContextTokens: -1,
      modelDefault: 200000,
      maxOutputTokens,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: {
          endpoint: EModelEndpoint.agents,
          model_parameters: { maxContextTokens: -1 },
        },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    // -1 is not used as-is; the formula kicks in
    expect(result.maxContextTokens).not.toBe(-1);
  });

  it('preserves small user-configured value (e.g. 1000 from modelSpec)', async () => {
    const userValue = 1000;
    const { agent, req, res, loadTools, db } = createMocks({
      maxContextTokens: userValue,
      modelDefault: 128000,
      maxOutputTokens: 4096,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: {
          endpoint: EModelEndpoint.agents,
          model_parameters: { maxContextTokens: userValue },
        },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    // Should NOT be overridden to Math.round((128000 - 4096) * 0.95) = 117,709
    expect(result.maxContextTokens).toBe(userValue);
  });

  it('sets baseContextTokens to agentMaxContextNum minus maxOutputTokensNum', async () => {
    const modelDefault = 200000;
    const maxOutputTokens = 4096;
    const { agent, req, res, loadTools, db } = createMocks({
      maxContextTokens: undefined,
      modelDefault,
      maxOutputTokens,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.baseContextTokens).toBe(modelDefault - maxOutputTokens);
  });

  it('clamps maxContextTokens to at least 1024 for tiny models', async () => {
    const modelDefault = 1100;
    const maxOutputTokens = 1050;
    const { agent, req, res, loadTools, db } = createMocks({
      maxContextTokens: undefined,
      modelDefault,
      maxOutputTokens,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    // baseContextTokens = 1100 - 1050 = 50, formula would give ~47.5 rounded
    // but Math.max(1024, ...) clamps it
    expect(result.maxContextTokens).toBe(1024);
  });
});

describe('initializeAgent — manual skill priming (Phase 3)', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  /**
   * Minimal listSkillsByAccess that satisfies `injectSkillCatalog` so the
   * manualSkills resolver branch runs. Returns an empty page — we don't care
   * about the catalog here, only that `accessibleSkillIds` is non-empty so
   * the manual-invocation block gets reached.
   */
  const emptyListSkillsByAccess: InitializeAgentDbMethods['listSkillsByAccess'] = async () => ({
    skills: [],
    has_more: false,
    after: null,
  });

  it('attaches resolved manual skill primes to the initialized agent', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    /**
     * Ownership-based active-state default only kicks in when
     * `skill.author.toString() === userId`. The default mock user id is a
     * literal string, not an ObjectId, so align the skill author with it so
     * `resolveSkillActive` treats the skill as owned and active.
     */
    const ownerAuthor = {
      toString: () => req.user?.id,
    } as unknown as import('mongoose').Types.ObjectId;

    const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn().mockResolvedValue({
      _id: skillId,
      name: 'brand-guidelines',
      body: '# Brand guidelines\nUse blue.',
      author: ownerAuthor,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['brand-guidelines'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    expect(result.manualSkillPrimes).toEqual([
      { _id: skillId, name: 'brand-guidelines', body: '# Brand guidelines\nUse blue.' },
    ]);
    /* `preferUserInvocable` keeps name-collision lookups consistent with
       the popover for manual paths — model-only (`userInvocable: false`)
       duplicates can't shadow the user-invocable doc the user picked. */
    expect(getSkillByName).toHaveBeenCalledWith('brand-guidelines', [skillId], {
      preferUserInvocable: true,
    });
  });

  it('leaves manualSkillPrimes undefined when no manualSkills are provided', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess },
    );

    expect(result.manualSkillPrimes).toBeUndefined();
  });

  it('returns empty array when every manual skill is unresolvable (no primes, no throw)', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest
      .fn()
      .mockResolvedValue(null);

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['does-not-exist'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    expect(result.manualSkillPrimes).toEqual([]);
  });

  it('skips resolution entirely when accessibleSkillIds is empty (user has no skill access)', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const getSkillByName: InitializeAgentDbMethods['getSkillByName'] = jest.fn();

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [],
        manualSkills: ['anything'],
      },
      { ...db, getSkillByName },
    );

    expect(result.manualSkillPrimes).toBeUndefined();
    expect(getSkillByName).not.toHaveBeenCalled();
  });

  it('silently no-ops when getSkillByName is not provided in db methods', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['foo'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess },
    );

    expect(result.manualSkillPrimes).toBeUndefined();
  });
});

describe('initializeAgent — skill `allowed-tools` union (Phase 6)', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  /**
   * Same minimal pager used in the Phase 3 suite — the catalog isn't what
   * we're exercising; we just need accessibleSkillIds to be non-empty so the
   * resolver path runs.
   */
  const emptyListSkillsByAccess: InitializeAgentDbMethods['listSkillsByAccess'] = async () => ({
    skills: [],
    has_more: false,
    after: null,
  });

  /** Helper: build a getSkillByName that returns a single skill with allowedTools. */
  const buildGetSkillByName = (
    name: string,
    allowedTools: string[] | undefined,
    skillId: import('mongoose').Types.ObjectId,
    userId: string,
  ): InitializeAgentDbMethods['getSkillByName'] =>
    jest.fn().mockResolvedValue({
      _id: skillId,
      name,
      body: `body of ${name}`,
      author: { toString: () => userId } as unknown as import('mongoose').Types.ObjectId,
      ...(allowedTools !== undefined ? { allowedTools } : {}),
    });

  it('passes the union of agent.tools + allowed-tools to loadTools and merges resulting toolDefinitions', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    /* Mock loadTools to echo back what was requested as toolDefinitions —
       lets the test assert both the input list and the output merge. */
    loadTools.mockImplementation(async ({ tools }: { tools: string[] }) => ({
      tools: [],
      toolContextMap: {},
      userMCPAuthMap: undefined,
      toolRegistry: undefined,
      toolDefinitions: tools.map((name: string) => ({ name, description: '', parameters: {} })),
      hasDeferredTools: false,
      actionsEnabled: undefined,
    }));

    const getSkillByName = buildGetSkillByName(
      'tool-skill',
      ['execute_code', 'read_file'],
      skillId,
      req.user!.id,
    );

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['tool-skill'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    /* Single loadTools call with the union — agent.tools + extras, dedup
       not needed because unionPrimeAllowedTools already excluded
       agent-baseline names. Order: agent first, then extras. */
    expect(loadTools).toHaveBeenCalledTimes(1);
    expect(loadTools.mock.calls[0][0].tools).toEqual(['web_search', 'execute_code', 'read_file']);

    /* All three tools should appear in the merged toolDefinitions. */
    const definedNames = result.toolDefinitions?.map((d) => d.name) ?? [];
    expect(definedNames).toEqual(
      expect.arrayContaining(['web_search', 'execute_code', 'read_file']),
    );
  });

  it('does not call loadTools twice when the skill declares no allowed-tools', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    const getSkillByName = buildGetSkillByName('plain', undefined, skillId, req.user!.id);

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['plain'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    expect(loadTools).toHaveBeenCalledTimes(1);
    expect(loadTools.mock.calls[0][0].tools).toEqual(['web_search']);
  });

  it('skips extras already on the agent (agent baseline wins; no double-loading)', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search', 'execute_code'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    const getSkillByName = buildGetSkillByName(
      'overlap',
      ['web_search', 'read_file'], // web_search overlaps; read_file is new
      skillId,
      req.user!.id,
    );

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['overlap'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    /* web_search is on the agent — not duplicated; only read_file is "extra". */
    expect(loadTools.mock.calls[0][0].tools).toEqual(['web_search', 'execute_code', 'read_file']);
  });

  it('retries loadTools without extras when the union call returns undefined (production loaders swallow errors)', async () => {
    /* Production loaders (`createToolLoader` in `initialize.js`,
       `openai.js`, `responses.js`) wrap `loadAgentTools` in try/catch
       and return `undefined` on failure. Without explicit handling we'd
       fall through to the empty fallback and silently drop the agent's
       baseline tools. This test pins the retry-on-undefined behavior. */
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    let call = 0;
    loadTools.mockImplementation(async ({ tools }: { tools: string[] }) => {
      call += 1;
      if (call === 1) {
        return undefined; // simulate swallowed error in createToolLoader
      }
      return {
        tools: [],
        toolContextMap: {},
        userMCPAuthMap: undefined,
        toolRegistry: undefined,
        toolDefinitions: tools.map((name) => ({ name, description: '', parameters: {} })),
        hasDeferredTools: false,
        actionsEnabled: undefined,
      };
    });

    const getSkillByName = buildGetSkillByName(
      'silent-fail-skill',
      ['mcp__broken__tool'],
      skillId,
      req.user!.id,
    );

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['silent-fail-skill'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    /* Two calls: union first (returned undefined → silent fail), then
       base-only retry (succeeded). Agent's web_search survives. */
    expect(loadTools).toHaveBeenCalledTimes(2);
    expect(loadTools.mock.calls[0][0].tools).toEqual(['web_search', 'mcp__broken__tool']);
    expect(loadTools.mock.calls[1][0].tools).toEqual(['web_search']);

    const definedNames = result.toolDefinitions?.map((d) => d.name) ?? [];
    expect(definedNames).toContain('web_search');
    expect(definedNames).not.toContain('mcp__broken__tool');
  });
  it('removes skill-added Project resources before retrying without denied tools', async () => {
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    filterFilesByEndpointRuntimeConfig.mockImplementationOnce(
      (_config: unknown, { files }: { files: TFile[] }) => files,
    );
    const { agent, req, loadTools, db } = createMocks();
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const projectFile = {
      file_id: 'project-file',
      filename: 'project.txt',
      type: 'text/plain',
      embedded: true,
    } as TFile;
    agent.tools = [];

    let call = 0;
    loadTools.mockImplementation(async ({ tools }: { tools: string[] }) => {
      call += 1;
      if (call === 1) {
        return undefined;
      }
      return {
        tools: [],
        toolContextMap: {},
        toolDefinitions: tools.map((name) => ({ name, description: '', parameters: {} })),
        hasDeferredTools: false,
      };
    });

    const getSkillByName = buildGetSkillByName(
      'project-file-search-fallback',
      [Tools.file_search],
      skillId,
      req.user!.id,
    );

    const result = await initializeAgent(
      {
        runtime: {
          user: req.user,
          appConfig: {
            endpoints: {
              [EModelEndpoint.agents]: {
                capabilities: [AgentCapabilities.file_search],
              },
            },
          } as NonNullable<ServerRequest['config']>,
          requestBody: {},
          turnStartedAt: 1,
          chatProjectContext: {
            projectId: 'project-1',
            contextRevision: 1,
            instructions: '',
            file_ids: [projectFile.file_id],
            resources: [
              {
                file_id: projectFile.file_id,
                identity: 'canonical-project-file',
                availability: 'ready',
                version: 'fixture-version',
                file: projectFile,
              },
            ],
          },
        },
        req,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        useChatProjectContext: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['project-file-search-fallback'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    expect(loadTools).toHaveBeenCalledTimes(2);
    expect(loadTools.mock.calls[0][0].tool_resources).toEqual({
      [EToolResources.file_search]: { files: [projectFile] },
    });
    expect(loadTools.mock.calls[1][0].tools).toEqual([]);
    expect(loadTools.mock.calls[1][0].tool_resources).toBeUndefined();
    expect(result.tool_resources).toBeUndefined();
  });

  it('retries loadTools without extras when the union call throws (agent tools must still load)', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    /* First call (with extras) fails; second call (without extras) succeeds. */
    let call = 0;
    loadTools.mockImplementation(async ({ tools }: { tools: string[] }) => {
      call += 1;
      if (call === 1) {
        throw new Error('MCP connection failed for skill-added tool');
      }
      return {
        tools: [],
        toolContextMap: {},
        userMCPAuthMap: undefined,
        toolRegistry: undefined,
        toolDefinitions: tools.map((name) => ({ name, description: '', parameters: {} })),
        hasDeferredTools: false,
        actionsEnabled: undefined,
      };
    });

    const getSkillByName = buildGetSkillByName(
      'bad-tool-skill',
      ['mcp__broken__tool'],
      skillId,
      req.user!.id,
    );

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['bad-tool-skill'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    /* Two calls: union first (threw), then base-only retry (succeeded). */
    expect(loadTools).toHaveBeenCalledTimes(2);
    expect(loadTools.mock.calls[0][0].tools).toEqual(['web_search', 'mcp__broken__tool']);
    expect(loadTools.mock.calls[1][0].tools).toEqual(['web_search']);

    /* Agent's own tool survives; the broken extra is silently dropped. */
    const definedNames = result.toolDefinitions?.map((d) => d.name) ?? [];
    expect(definedNames).toContain('web_search');
    expect(definedNames).not.toContain('mcp__broken__tool');
  });

  it.each([
    ['Error', new Error('run cancelled')],
    ['string', 'run cancelled'],
  ])(
    'does not retry skill-added tools when the owning signal aborts with an %s reason',
    async (_, reason) => {
      const { agent, req, res, loadTools, db } = createMocks();
      agent.tools = ['web_search'];
      const { Types } = await import('mongoose');
      const skillId = new Types.ObjectId();
      const controller = new AbortController();
      controller.abort(reason);
      loadTools.mockRejectedValue(reason);

      const getSkillByName = buildGetSkillByName(
        'cancelled-tool-skill',
        ['mcp__warehouse__query'],
        skillId,
        req.user!.id,
      );

      await expect(
        initializeAgent(
          {
            req,
            res,
            agent,
            loadTools,
            signal: controller.signal,
            endpointOption: { endpoint: EModelEndpoint.agents },
            allowedProviders: new Set([Providers.OPENAI]),
            isInitialAgent: true,
            accessibleSkillIds: [skillId],
            manualSkills: ['cancelled-tool-skill'],
          },
          { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
        ),
      ).rejects.toBe(reason);

      expect(loadTools).toHaveBeenCalledTimes(1);
    },
  );

  it('does not retry a resource recovery failure when execute_code is skill-added', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const resourceRecoveryError = Object.assign(new Error('resource recovery required'), {
      code: ErrorTypes.RESOURCE_RECOVERY_REQUIRED,
      status: 409,
      statusCode: 409,
    });
    loadTools.mockRejectedValue(resourceRecoveryError);

    const getSkillByName = buildGetSkillByName(
      'code-skill',
      [Tools.execute_code],
      skillId,
      req.user!.id,
    );

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          accessibleSkillIds: [skillId],
          manualSkills: ['code-skill'],
        },
        { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
      ),
    ).rejects.toBe(resourceRecoveryError);

    expect(loadTools).toHaveBeenCalledTimes(1);
    expect(loadTools.mock.calls[0][0].tools).toEqual(['web_search', Tools.execute_code]);
  });

  it('still retries when only skill-added tools expect unavailable MCP tools', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const expectedMCPError = Object.assign(new Error('expected MCP tools are unavailable'), {
      code: 'AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE',
      statusCode: 503,
    });
    loadTools.mockRejectedValueOnce(expectedMCPError).mockResolvedValueOnce({
      tools: [],
      toolContextMap: {},
      userMCPAuthMap: undefined,
      toolRegistry: undefined,
      toolDefinitions: [{ name: 'web_search', description: '', parameters: {} }],
      hasDeferredTools: false,
      actionsEnabled: undefined,
    });

    const getSkillByName = buildGetSkillByName(
      'mcp-skill',
      ['mcp__warehouse__query'],
      skillId,
      req.user!.id,
    );

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['mcp-skill'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    expect(loadTools).toHaveBeenCalledTimes(2);
    expect(loadTools.mock.calls[0][0].tools).toEqual(['web_search', 'mcp__warehouse__query']);
    expect(loadTools.mock.calls[1][0].tools).toEqual(['web_search']);
    expect(result.toolDefinitions?.map((definition) => definition.name)).toContain('web_search');
  });

  it('falls back to host-provided skill authoring tools when BOTH loadTools calls return undefined', async () => {
    /* Worst-case silent-failure path: production loaders catch errors
       and return undefined. If the agent's own tools fail to load AND
       the retry without extras also fails, loaded registry tools drop out,
       but host-provided file authoring remains available for skill access. */
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    /* Both calls (with extras + without extras) silently return undefined. */
    loadTools.mockResolvedValue(undefined);

    const getSkillByName = buildGetSkillByName(
      'broken-skill',
      ['some-tool'],
      skillId,
      req.user!.id,
    );

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        skillAuthoringAvailable: true,
        manualSkills: ['broken-skill'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    /* Two attempts (initial + retry), both undefined. Registry-backed tools
       fall away, but read/create/edit_file are registered by the initializer
       so skill authoring still works — and `skill` comes with them, so a
       skill authored in this run can still be invoked despite the empty
       catalog. */
    expect(loadTools).toHaveBeenCalledTimes(2);
    const definedNames = result.toolDefinitions?.map((d) => d.name) ?? [];
    expect(definedNames).toEqual(['read_file', 'create_file', 'edit_file', 'skill']);
  });

  it('propagates the error when loadTools fails AND there are no skill-added extras to drop', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search'];
    /* No skills, no extras — a thrown loadTools is the agent's own problem,
       not ours to absorb. */
    loadTools.mockRejectedValueOnce(new Error('agent tool registry corrupted'));

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          accessibleSkillIds: undefined,
        },
        db,
      ),
    ).rejects.toThrow('agent tool registry corrupted');
    expect(loadTools).toHaveBeenCalledTimes(1);
  });

  it('does not invoke loadTools twice when the agent has no tools and the skill adds none', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();

    const getSkillByName = buildGetSkillByName('plain', [], skillId, req.user!.id);

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['plain'],
      },
      { ...db, listSkillsByAccess: emptyListSkillsByAccess, getSkillByName },
    );

    expect(loadTools).toHaveBeenCalledTimes(1);
    expect(loadTools.mock.calls[0][0].tools).toEqual([]);
  });
});

describe('initializeAgent — execute_code capability expansion', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('expands execute_code into bash_tool + read_file when codeEnvAvailable=true', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['execute_code'];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      db,
    );

    const names = (result.toolDefinitions ?? []).map((d) => d.name);
    expect(names).toContain('bash_tool');
    expect(names).toContain('read_file');
    expect(names).toContain('create_file');
    expect(names).toContain('edit_file');
    /* The legacy `execute_code` tool def is no longer registered by this
       path — the string stays in `agent.tools` as the capability trigger
       but never appears in the tool definitions the LLM sees. */
    expect(names).not.toContain('execute_code');
    const readFile = result.toolDefinitions?.find((d) => d.name === 'read_file');
    expect(readFile?.description).toContain('code-sandbox');
    expect(readFile?.description).not.toContain('{skillName}');
    expect(readFile?.description).not.toContain('SKILL.md');
    const createFile = result.toolDefinitions?.find((d) => d.name === 'create_file');
    expect(createFile?.description).toContain('code-execution sandbox');
    expect(createFile?.description).toContain('/mnt/data/');
    expect(createFile?.description).not.toContain('skills/');
    expect(result.skillAuthoringAvailable).toBe(false);
    expect(result.fileAuthoringToolNames).toEqual(new Set(['create_file', 'edit_file']));
  });

  it('withholds attached code tools when the conversation works without an environment', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [Tools.execute_code];
    agent.tool_resources = {
      [EToolResources.execute_code]: { file_ids: ['attached-code-file'] },
    };
    agent.stateful_code_sessions = true;
    agent.code_environment_id = 'personal-vm';
    req.config = {
      endpoints: {
        [EModelEndpoint.agents]: {
          statefulCodeSessions: {
            environments: [
              {
                id: 'personal-vm',
                name: 'Personal VM',
                type: 'attached',
                baseURL: 'https://code.example.com/v1',
              },
            ],
          },
        },
      },
    } as unknown as NonNullable<typeof req.config>;

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        requestBody: {
          conversationId: 'conversation-1',
          codeEnvironmentMode: 'without_attached',
        },
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
        statefulSessionsAvailable: true,
      },
      db,
    );

    expect(result.codeEnvAvailable).toBe(false);
    expect(result.codeExecutionContext).toEqual(
      expect.objectContaining({ executionProfile: 'default', statefulSessions: false }),
    );
    expect(result.toolDefinitions?.map(({ name }) => name)).not.toEqual(
      expect.arrayContaining(['bash_tool', 'read_file', 'create_file', 'edit_file']),
    );
    const { primeResources } = jest.requireMock('../resources') as { primeResources: jest.Mock };
    const primeCall = primeResources.mock.calls[primeResources.mock.calls.length - 1][0];
    expect(primeCall.enabledToolResources.has(EToolResources.execute_code)).toBe(false);
    expect(primeCall.tool_resources).not.toHaveProperty(EToolResources.execute_code);
    expect(loadTools).toHaveBeenLastCalledWith(
      expect.objectContaining({ attachedEnvironmentOptOut: true }),
    );
  });

  it('does not disable managed code tools for the without-attached decision', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [Tools.execute_code];
    agent.stateful_code_sessions = true;
    agent.code_environment_id = 'managed-code';
    req.config = {
      endpoints: {
        [EModelEndpoint.agents]: {
          statefulCodeSessions: {
            environments: [
              {
                id: 'managed-code',
                name: 'Managed code',
                type: 'managed',
                baseURL: 'https://code.example.com/v1',
              },
            ],
          },
        },
      },
    } as NonNullable<typeof req.config>;

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        requestBody: {
          conversationId: 'conversation-1',
          codeEnvironmentMode: 'without_attached',
        },
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
        statefulSessionsAvailable: true,
      },
      db,
    );

    expect(result.codeEnvAvailable).toBe(true);
    expect(result.toolDefinitions?.map(({ name }) => name)).toEqual(
      expect.arrayContaining(['bash_tool', 'read_file']),
    );
    expect(loadTools).toHaveBeenLastCalledWith(
      expect.objectContaining({ attachedEnvironmentOptOut: false }),
    );
  });

  it('honors without-attached when the configured environment is no longer visible', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [Tools.execute_code];
    agent.stateful_code_sessions = true;
    agent.code_environment_id = 'revoked-vm';
    req.config = {
      endpoints: {
        [EModelEndpoint.agents]: {
          statefulCodeSessions: { environments: [] },
        },
      },
    } as unknown as NonNullable<typeof req.config>;

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        requestBody: {
          conversationId: 'conversation-1',
          codeEnvironmentMode: 'without_attached',
        },
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
        statefulSessionsAvailable: true,
      },
      db,
    );

    expect(result.codeEnvAvailable).toBe(false);
    expect(result.toolDefinitions?.map(({ name }) => name)).not.toEqual(
      expect.arrayContaining(['bash_tool', 'read_file', 'create_file', 'edit_file']),
    );
  });

  it('keeps an implicit managed stateful route enabled during attached opt-out', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [Tools.execute_code];
    agent.stateful_code_sessions = true;
    delete agent.code_environment_id;
    process.env.CODE_ENVIRONMENT_DECISION_VERSION = '1';
    process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'https://stateful-code.example.com/v1/';
    req.config = {
      endpoints: {
        [EModelEndpoint.agents]: {
          statefulCodeSessions: { environments: [] },
        },
      },
    } as unknown as NonNullable<typeof req.config>;

    try {
      const result = await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          requestBody: {
            conversationId: 'conversation-1',
            codeEnvironmentMode: 'without_attached',
          },
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: false,
          codeEnvAvailable: true,
          statefulSessionsAvailable: true,
        },
        db,
      );

      expect(result.codeEnvAvailable).toBe(true);
      expect(result.statefulCodeSessions).toBe(true);
      expect(result.toolDefinitions?.map(({ name }) => name)).toEqual(
        expect.arrayContaining(['bash_tool', 'read_file']),
      );
    } finally {
      delete process.env.CODE_ENVIRONMENT_DECISION_VERSION;
      delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
    }
  });

  it('honors attached opt-out when no implicit managed route is deployed', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [Tools.execute_code];
    agent.stateful_code_sessions = true;
    delete agent.code_environment_id;
    req.config = {
      endpoints: {
        [EModelEndpoint.agents]: {
          statefulCodeSessions: { environments: [] },
        },
      },
    } as unknown as NonNullable<typeof req.config>;

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        requestBody: {
          conversationId: 'conversation-1',
          codeEnvironmentMode: 'without_attached',
        },
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: false,
        codeEnvAvailable: true,
        statefulSessionsAvailable: true,
      },
      db,
    );

    expect(result.codeEnvAvailable).toBe(false);
    expect(result.statefulCodeSessions).toBe(false);
    expect(result.toolDefinitions?.map(({ name }) => name)).not.toEqual(
      expect.arrayContaining(['bash_tool', 'read_file']),
    );
  });

  it('keeps legacy opt-out classification when the deployment opts out of the protocol', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [Tools.execute_code];
    agent.stateful_code_sessions = true;
    delete agent.code_environment_id;
    process.env.CODE_ENVIRONMENT_DECISION_VERSION = '0';
    process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'https://stateful-code.example.com/v1/';
    req.config = {
      endpoints: {
        [EModelEndpoint.agents]: {
          statefulCodeSessions: { environments: [] },
        },
      },
    } as unknown as NonNullable<typeof req.config>;

    try {
      const result = await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          requestBody: {
            conversationId: 'conversation-1',
            codeEnvironmentMode: 'without_attached',
          },
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: false,
          codeEnvAvailable: true,
          statefulSessionsAvailable: true,
        },
        db,
      );

      expect(result.codeEnvAvailable).toBe(false);
      expect(result.statefulCodeSessions).toBe(false);
    } finally {
      delete process.env.CODE_ENVIRONMENT_DECISION_VERSION;
      delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
    }
  });

  it('routes code-file priming through the stateful profile before tools load', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['execute_code'];
    agent.stateful_code_sessions = true;
    agent.stateful_code_environment = 'agent-user';
    process.env.LIBRECHAT_CODE_BASEURL_STATEFUL = 'https://stateful-code.example.com/v1/';

    try {
      const result = await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          codeEnvAvailable: true,
          statefulSessionsAvailable: true,
        },
        db,
      );

      expect(loadTools).toHaveBeenCalledWith(
        expect.objectContaining({
          codeExecutionContext: expect.objectContaining({
            baseUrl: 'https://stateful-code.example.com/v1',
            executionProfile: 'stateful',
            statefulSessions: true,
          }),
        }),
      );
      expect(result.codeExecutionContext).toEqual(
        expect.objectContaining({
          baseUrl: 'https://stateful-code.example.com/v1',
          executionProfile: 'stateful',
        }),
      );
    } finally {
      delete process.env.LIBRECHAT_CODE_BASEURL_STATEFUL;
    }
  });

  it('routes a restored machine selection before file priming and tool discovery', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['execute_code'];
    agent.stateful_code_sessions = true;
    agent.code_environment_id = 'application-vm';
    agent.code_environment_ids = ['runtime-vm'];
    req.config = {
      endpoints: {
        agents: {
          statefulCodeSessions: {
            allowEnvironmentSelection: true,
            environments: ['application-vm', 'runtime-vm'].map((id) => ({
              id,
              name: id,
              type: 'attached',
              owner: 'deployment',
              baseURL: `https://${id}.example.com/v1`,
              workerId: `worker-${id}`,
            })),
          },
        },
      },
    } as NonNullable<typeof req.config>;
    req.resolvedConversation = {
      conversationId: 'chat-runtime',
      codeWorkspaces: [
        { environmentId: 'application-vm', workspaceId: 'primary' },
        { environmentId: 'runtime-vm', workspaceId: 'primary', agentIds: [agent.id] },
      ],
    };
    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        conversationId: 'chat-runtime',
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
        statefulSessionsAvailable: true,
        requestBody: {
          codeWorkspaces: [{ environmentId: 'application-vm', workspaceId: 'primary' }],
        },
      },
      db,
    );
    expect(loadTools).toHaveBeenCalledWith(
      expect.objectContaining({
        codeExecutionContext: expect.objectContaining({
          environmentId: 'runtime-vm',
          baseUrl: 'https://runtime-vm.example.com/v1',
          bridgeWorkerId: 'worker-runtime-vm',
        }),
      }),
    );
    expect(result.codeExecutionContext?.environmentId).toBe('runtime-vm');
    expect(agent.code_environment_id).toBe('application-vm');
    /* The liveness probe inside priming authenticates to this route the way its uploads
     * do, which needs the request to mint from and the route's worker to bind to. */
    expect(primeResources).toHaveBeenCalledWith(
      expect.objectContaining({
        req,
        codeBaseUrl: 'https://runtime-vm.example.com/v1',
        codeExecutionProfile: 'stateful',
        codeBridgeWorkerId: 'worker-runtime-vm',
      }),
    );
  });

  it.each([false, true])(
    'uses the validated attached workspace operation ceiling: protectedEdit=%s',
    async (protectedEdit) => {
      const { agent, req, res, loadTools, db } = createMocks();
      agent.tools = ['execute_code'];
      agent.stateful_code_sessions = true;
      agent.code_environment_id = 'personal-vm';
      req.config = {
        endpoints: {
          [EModelEndpoint.agents]: {
            statefulCodeSessions: {
              environments: [
                {
                  id: 'personal-vm',
                  name: 'Personal VM',
                  type: 'attached',
                  baseURL: 'https://code.example.com/v1',
                  owner: 'deployment',
                  workerId: 'worker-a',
                  configSchema: {
                    limits: { maxCommandTimeoutMs: 120_000 },
                  },
                },
              ],
            },
          },
        },
      } as NonNullable<typeof req.config>;
      if (protectedEdit)
        req.config.filters = {
          files: {
            pii: {
              customPatterns: [{ id: 'test', label: 'test', regex: 'secret' }],
              fields: ['content'],
            },
          },
        };
      const codeExecutionContext: CodeExecutionContext = {
        baseUrl: 'https://code.example.com/v1',
        codeSessionKey: 'execute_code:stateful:route:session',
        executionProfile: 'stateful',
        statefulSessions: true,
        environmentId: 'personal-vm',
        environmentType: 'attached',
        bridgeWorkerId: 'worker-a',
        codeEnvironmentConfigSchema: {
          limits: { maxCommandTimeoutMs: 120_000 },
        },
        codeWorkspace: {
          environmentId: 'personal-vm',
          workspaceId: 'project-a',
          operations: ['read_file', 'list_files', 'execute_command'],
          environment: { fingerprint: 'a'.repeat(64), repo: 'owner/project', actions: ['check'] },
          linkedWorktrees: true,
        },
      };
      if (protectedEdit) codeExecutionContext.codeWorkspace!.operations.push('edit_file');
      loadTools.mockResolvedValue({
        tools: [],
        toolContextMap: {},
        dynamicToolContextMap: {},
        toolDefinitions: [],
        hasDeferredTools: false,
        codeExecutionContext,
      });

      const result = await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          codeEnvAvailable: true,
          statefulSessionsAvailable: true,
        },
        db,
      );

      expect(result.codeExecutionContext).toBe(codeExecutionContext);
      expect(result.toolDefinitions?.map(({ name }) => name).sort()).toEqual([
        'bash_tool',
        'list_workspace_files',
        'read_file',
      ]);
      const bashTool = result.toolDefinitions?.find(({ name }) => name === 'bash_tool');
      expect(bashTool?.parameters).toMatchObject({
        properties: { environmentAction: { enum: ['check'] } },
        required: [],
      });
      expect(bashTool?.description).toContain('owner/project');
      expect(
        (bashTool?.parameters as { properties?: { timeoutMs?: { maximum?: number } } })?.properties
          ?.timeoutMs?.maximum,
      ).toBe(120_000);
      expect(
        (bashTool?.parameters as { properties?: { cwd?: { description?: string } } })?.properties
          ?.cwd?.description,
      ).toContain('.worktrees/<name>');
    },
  );

  it.each([
    { ['q' + '_mcp_z'.repeat(4000)]: { approval_mode: 'ask' as const } },
    Object.fromEntries(
      Array.from({ length: 1025 }, (_, i) => [`${i}`, { approval_mode: 'ask' as const }]),
    ),
    Object.fromEntries(
      Array.from({ length: 129 }, (_, i) => [
        `${i}`.padEnd(256, 'é'),
        { approval_mode: 'ask' as const },
      ]),
    ),
  ])(
    'rejects legacy option-limit violations before loading tools or priming resources',
    async (tool_options) => {
      const { agent, req, res, loadTools, db } = createMocks();
      agent.tool_options = tool_options;
      const primeCalls = jest.mocked(primeResources).mock.calls.length;
      await expect(
        initializeAgent(
          {
            req,
            res,
            agent,
            loadTools,
            endpointOption: { endpoint: EModelEndpoint.agents },
            allowedProviders: new Set([Providers.OPENAI]),
            isInitialAgent: true,
          },
          db,
        ),
      ).rejects.toMatchObject({ code: 'AGENT_TOOL_OPTIONS_LIMIT_EXCEEDED' });
      expect(loadTools).not.toHaveBeenCalled();
      expect(primeResources).toHaveBeenCalledTimes(primeCalls);
    },
  );

  it('rejects a stateful environment excluded by deployment policy', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['execute_code'];
    agent.stateful_code_sessions = true;
    agent.stateful_code_environment = 'conversation';
    req.config = {
      endpoints: {
        [EModelEndpoint.agents]: {
          statefulCodeSessions: { allowedEnvironments: ['user'] },
        },
      },
    } as NonNullable<typeof req.config>;

    let error;
    try {
      await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          codeEnvAvailable: true,
          statefulSessionsAvailable: true,
        },
        db,
      );
    } catch (caught) {
      error = caught;
    }

    expect(error).toMatchObject({
      code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED,
      message: 'Stateful code environment is not allowed by this deployment: conversation',
    });
    expect(isFatalAgentInitializationError(error)).toBe(true);
    expect(loadTools).not.toHaveBeenCalled();
  });

  it('uses an explicit stateful environment allowlist when req.config is unavailable', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['execute_code'];
    agent.stateful_code_sessions = true;
    agent.stateful_code_environment = 'conversation';
    req.config = undefined;

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          codeEnvAvailable: true,
          statefulSessionsAvailable: true,
          allowedStatefulCodeEnvironments: ['user'],
        },
        db,
      ),
    ).rejects.toMatchObject({ code: ErrorTypes.STATEFUL_CODE_ENVIRONMENT_NOT_ALLOWED });
    expect(loadTools).not.toHaveBeenCalled();
  });

  it('upgrades read_file to the skill-aware description when active skills are in scope', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['execute_code'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const author = { toString: () => req.user?.id } as unknown as import('mongoose').Types.ObjectId;

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
        accessibleSkillIds: [skillId],
      },
      {
        ...db,
        listSkillsByAccess: jest.fn().mockResolvedValue({
          skills: [
            {
              _id: skillId,
              name: 'data-cleaner',
              description: 'Clean tabular data.',
              author,
            },
          ],
          has_more: false,
          after: null,
        }),
      },
    );

    const readFile = result.toolDefinitions?.find((d) => d.name === 'read_file');
    expect(readFile?.description).toContain('{skillName}/{filePath}');
    expect(readFile?.description).toContain('skills/{skillName}/');
    expect(readFile?.description).toContain('SKILL.md');
    const names = result.toolDefinitions?.map((d) => d.name) ?? [];
    expect(names).toContain('skill');
    expect(names).toContain('create_file');
    expect(names).toContain('edit_file');
  });

  it('keeps skill authoring tools hidden for read-only skill access', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const author = { toString: () => req.user?.id } as unknown as import('mongoose').Types.ObjectId;

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: false,
        accessibleSkillIds: [skillId],
        skillAuthoringAvailable: false,
      },
      {
        ...db,
        listSkillsByAccess: jest.fn().mockResolvedValue({
          skills: [
            {
              _id: skillId,
              name: 'read-only-skill',
              description: 'Read-only skill.',
              author,
            },
          ],
          has_more: false,
          after: null,
        }),
      },
    );

    const names = result.toolDefinitions?.map((d) => d.name) ?? [];
    expect(names).toContain('skill');
    expect(names).toContain('read_file');
    expect(names).not.toContain('create_file');
    expect(names).not.toContain('edit_file');
    expect(names).not.toContain('bash_tool');
    expect(result.skillAuthoringAvailable).toBe(false);
  });

  it('registers skill authoring tools for first-time skill creators', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = [];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        accessibleSkillIds: [],
        skillAuthoringAvailable: true,
        codeEnvAvailable: false,
      },
      db,
    );

    const names = (result.toolDefinitions ?? []).map((d) => d.name);
    expect(names).toContain('create_file');
    expect(names).toContain('edit_file');
    expect(names).toContain('read_file');
    expect(names).not.toContain('bash_tool');
    const readFile = result.toolDefinitions?.find((d) => d.name === 'read_file');
    expect(readFile?.description).toContain('skills/{skillName}/');
    expect(readFile?.description).toContain('SKILL.md');
    const createFile = result.toolDefinitions?.find((d) => d.name === 'create_file');
    expect(createFile?.description).toContain('skills/');
    expect(result.skillAuthoringAvailable).toBe(true);
    expect(result.fileAuthoringToolNames).toEqual(new Set(['create_file', 'edit_file']));
  });

  it('does not register bash_tool + read_file when codeEnvAvailable=false', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['execute_code'];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: false,
      },
      db,
    );

    const names = (result.toolDefinitions ?? []).map((d) => d.name);
    expect(names).not.toContain('bash_tool');
    expect(names).not.toContain('read_file');
    expect(names).not.toContain('create_file');
    expect(names).not.toContain('edit_file');
  });

  it('does not register bash_tool + read_file when agent does not request execute_code', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['web_search'];

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      db,
    );

    const names = (result.toolDefinitions ?? []).map((d) => d.name);
    expect(names).not.toContain('bash_tool');
    expect(names).not.toContain('read_file');
    expect(names).not.toContain('create_file');
    expect(names).not.toContain('edit_file');
  });

  it('narrows codeEnvAvailable on InitializedAgent to the per-agent effective value', async () => {
    /* The admin-level `params.codeEnvAvailable` is AND-ed with
       `agent.tools.includes('execute_code')` and stored on the returned
       agent. Downstream runtime code (JS controllers, `primeInvokedSkills`)
       reads the narrowed value from the stored context so skills-only
       agents never accidentally trip sandbox-side logic. */
    const { agent, req, res, loadTools, db } = createMocks();

    // Admin cap on, agent asks for execute_code → effective true.
    agent.tools = ['execute_code'];
    const execAgent = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      db,
    );
    expect(execAgent.codeEnvAvailable).toBe(true);

    // Admin cap on, agent does NOT ask for execute_code → effective false.
    agent.tools = ['web_search'];
    const skillsOnlyAgent = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      db,
    );
    expect(skillsOnlyAgent.codeEnvAvailable).toBe(false);

    // Admin cap off, agent asks for execute_code → still effective false.
    agent.tools = ['execute_code'];
    const capOffAgent = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: false,
      },
      db,
    );
    expect(capOffAgent.codeEnvAvailable).toBe(false);

    // Neither → effective false.
    agent.tools = ['web_search'];
    const neitherAgent = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: false,
      },
      db,
    );
    expect(neitherAgent.codeEnvAvailable).toBe(false);
  });

  it('allows Google provider tools alongside execute_code definitions', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.GOOGLE,
      overrideProvider: Providers.GOOGLE,
      model: 'gemini-3.5-flash',
    });
    agent.tools = ['execute_code'];

    /* Surface an options.tools array from the provider config — this is
       the `googleSearch` / `urlContext` built-in LLM tooling that
       Google/Vertex exposes via provider options. */
    mockGetProviderConfig.mockReturnValue({
      getOptions: jest.fn().mockResolvedValue({
        llmConfig: { model: 'gemini-3.5-flash', maxTokens: 4096 },
        tools: [{ googleSearch: {} }],
      } satisfies InitializeResultBase),
      overrideProvider: Providers.GOOGLE,
    });

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.GOOGLE]),
          isInitialAgent: true,
          codeEnvAvailable: true,
        },
        db,
      ),
    ).resolves.toEqual(
      expect.objectContaining({
        tools: [{ googleSearch: {} }],
        model_parameters: expect.objectContaining({
          includeServerSideToolInvocations: true,
        }),
        toolDefinitions: expect.arrayContaining([
          expect.objectContaining({ name: 'bash_tool' }),
          expect.objectContaining({ name: 'read_file' }),
        ]),
      }),
    );
  });

  it('combines Google provider tools with structured external tools', async () => {
    const structuredTool = {
      name: 'weather',
      description: 'Get weather',
      schema: { type: 'object', properties: {} },
    };
    const providerTool = { googleSearch: {} };
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.GOOGLE,
      overrideProvider: Providers.GOOGLE,
      model: 'gemini-3.5-flash',
      providerTools: [providerTool],
      structuredTools: [structuredTool],
    });
    agent.tools = ['weather'];

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.GOOGLE]),
          isInitialAgent: true,
          codeEnvAvailable: false,
        },
        db,
      ),
    ).resolves.toEqual(
      expect.objectContaining({
        tools: [structuredTool, providerTool],
        model_parameters: expect.objectContaining({
          includeServerSideToolInvocations: true,
        }),
      }),
    );
  });
});

describe('initializeAgent — code-generated file thread filter (regression)', () => {
  /* Sibling-branched conversation regression. Pre-fix the priming chain
   * filtered code-generated files by `messageId IN threadMessageIds`,
   * which excluded files whose creator messageId lived on a sibling
   * branch (preserved on the File record by `processCodeOutput` for
   * provenance). The fix anchors `getCodeGeneratedFiles` on
   * `threadFileIds` instead — file_ids referenced by the thread's
   * `messages.files[]` arrays. This block locks the new contract at
   * the integration boundary: assert the right call shape, not the
   * underlying Mongo query (covered separately by
   * `data-schemas/methods/file.spec`). */

  beforeEach(() => {
    jest.clearAllMocks();
    mockExtractLibreChatParams.mockReset();
    mockGetThreadData.mockReset();
  });

  function setupExecuteCodeAgent() {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: Providers.OPENAI,
    });
    agent.tools = ['execute_code'];

    /* `resendFiles: true` is the gate that opens the thread-file
     * priming block in initialize.ts. Without it the whole
     * codeGeneratedFiles fetch is skipped. */
    mockExtractLibreChatParams.mockReturnValue({
      resendFiles: true,
      maxContextTokens: undefined,
      modelOptions: { model: 'test-model' },
    });

    return { agent, req, res, loadTools, db };
  }

  it('provisions code files for a skill tool that never names execute_code', async () => {
    /**
     * `bash_tool` reads the code environment but is not an `EToolResources` key, so an
     * agent that gets it only through a skill built no provisioning state and invoked
     * the tool against an empty sandbox. Execution-time eligibility already counted it.
     */
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();
    agent.tools = ['web_search'];
    const { Types } = await import('mongoose');
    const skillId = new Types.ObjectId();
    const getSkillByName = jest.fn().mockResolvedValue({
      _id: skillId,
      name: 'sandbox-skill',
      body: 'body of sandbox-skill',
      author: { toString: () => req.user!.id } as unknown as import('mongoose').Types.ObjectId,
      allowedTools: ['bash_tool'],
    });
    mockGetThreadData.mockReturnValue({ messageIds: ['msgN'], fileIds: ['file-1'] });
    const getCodeGeneratedFiles = jest.fn().mockResolvedValue([]);

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: 'msgN',
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
        accessibleSkillIds: [skillId],
        manualSkills: ['sandbox-skill'],
      },
      {
        ...db,
        getCodeGeneratedFiles,
        getSkillByName,
        listSkillsByAccess: async () => ({ skills: [], has_more: false, after: null }),
      },
    );

    expect(getCodeGeneratedFiles).toHaveBeenCalledTimes(1);
  });

  it('passes threadFileIds (not threadMessageIds) to getCodeGeneratedFiles', async () => {
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    /* Simulate the branched scenario: parent message N is a sibling
     * regeneration. `getThreadData` walks back from N and collects
     * messageIds [N, root] plus fileIds referenced by N.files[]. */
    mockGetThreadData.mockReturnValue({
      messageIds: ['msgN', 'msgRoot'],
      fileIds: ['file-pptx-skill', 'file-output-csv'],
    });

    const getCodeGeneratedFiles = jest.fn().mockResolvedValue([]);
    const getUserCodeFiles = jest.fn().mockResolvedValue([]);
    const getMessages = jest
      .fn()
      .mockResolvedValue([{ messageId: 'msgN', parentMessageId: 'msgRoot', files: [] }]);

    const dbWithThreadCalls: InitializeAgentDbMethods = {
      ...db,
      getMessages,
      getCodeGeneratedFiles,
      getUserCodeFiles,
    };

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: 'msgN',
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      dbWithThreadCalls,
    );

    expect(getCodeGeneratedFiles).toHaveBeenCalledTimes(1);
    expect(getCodeGeneratedFiles).toHaveBeenCalledWith(
      'conv-1',
      ['file-pptx-skill', 'file-output-csv'],
      { userId: 'user-1', tenantId: undefined },
    );
    /* Both functions now share the same primary anchor — symmetric
     * design that closes the sibling-branch hole. */
    expect(getUserCodeFiles).toHaveBeenCalledWith(['file-pptx-skill', 'file-output-csv'], {
      userId: 'user-1',
      tenantId: undefined,
    });
  });

  it('selects messages.attachments alongside messages.files (regression)', async () => {
    /* Code-execution outputs land on `messages.attachments` via
     * `processCodeOutput`; user uploads land on `messages.files`.
     * Selecting only `files` silently dropped every code-output
     * file_id from the thread walk, so the next turn's
     * `tool_resources.execute_code.file_ids` came up empty and the
     * sandbox saw `_injected_files: []`. The visible symptom: "the
     * previous file isn't persisted between executions" on a single
     * linear thread. Lock the select string so a future field
     * trim doesn't silently re-introduce the bug. */
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    mockGetThreadData.mockReturnValue({ messageIds: [], fileIds: [] });

    const getCodeGeneratedFiles = jest.fn().mockResolvedValue([]);
    const getUserCodeFiles = jest.fn().mockResolvedValue([]);
    const getMessages = jest.fn().mockResolvedValue([]);

    const dbWithThreadCalls: InitializeAgentDbMethods = {
      ...db,
      getMessages,
      getCodeGeneratedFiles,
      getUserCodeFiles,
    };

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: 'msgN',
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      dbWithThreadCalls,
    );

    expect(getMessages).toHaveBeenCalledTimes(1);
    const [, selectFields] = getMessages.mock.calls[0];
    /* Asserting on a substring instead of exact equality keeps the
     * test resilient to future ordering / new fields, while still
     * catching a regression where `attachments` is dropped. */
    expect(selectFields).toMatch(/\battachments\b/);
    expect(selectFields).toMatch(/\bfiles\b/);
    expect(selectFields).toMatch(/\bmessageId\b/);
    expect(selectFields).toMatch(/\bparentMessageId\b/);
  });

  it('skips the code-generated fetch entirely when threadFileIds is empty', async () => {
    /* Empty `messages.files[]` across the thread — nothing to look up.
     * The function returns early without hitting Mongo, mirroring the
     * pre-fix behavior for empty-thread cases. */
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    mockGetThreadData.mockReturnValue({
      messageIds: ['msgN', 'msgRoot'],
      fileIds: [],
    });

    const getCodeGeneratedFiles = jest.fn().mockResolvedValue([]);
    const getUserCodeFiles = jest.fn().mockResolvedValue([]);
    const getMessages = jest
      .fn()
      .mockResolvedValue([{ messageId: 'msgN', parentMessageId: 'msgRoot', files: [] }]);

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: 'msgN',
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      { ...db, getMessages, getCodeGeneratedFiles, getUserCodeFiles },
    );

    expect(getCodeGeneratedFiles).toHaveBeenCalledWith('conv-1', [], {
      userId: 'user-1',
      tenantId: undefined,
    });
    /* `getUserCodeFiles` is gated on a non-empty array at the call site,
     * so it shouldn't be invoked at all. `getCodeGeneratedFiles`'s own
     * empty-guard is exercised by data-schemas tests. */
    expect(getUserCodeFiles).not.toHaveBeenCalled();
  });

  it('charges a file appearing in both sets against the allowance once', async () => {
    /* An embedded attachment still missing the active code route is hydrated for delivery
     * and returned as a provisioning candidate. Charging its bytes twice would spend an
     * allowance the request never uses and drop a different candidate that fits. */
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const shared = { file_id: 'shared', filename: 'a.csv', bytes: 400 };
    const deferredOnly = { file_id: 'deferred', filename: 'b.csv', bytes: 100 };
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    /* Delivery has admitted the shared file; deferred screening sees only new ids. */
    filterFilesByEndpointRuntimeConfig
      .mockReturnValueOnce([shared])
      .mockReturnValueOnce([deferredOnly]);
    const getDeferredProvisionFiles = jest.fn().mockResolvedValue([shared, deferredOnly]);
    const getConvoFiles = jest.fn().mockResolvedValue(['shared', 'deferred']);
    const getToolFilesByIds = jest.fn().mockResolvedValue([shared]);

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      {
        ...db,
        getDeferredProvisionFiles,
        getConvoFiles,
        getToolFilesByIds,
        getFiles: jest.fn().mockResolvedValue([shared, deferredOnly]),
      },
    );

    const chargedToDeferred = filterFilesByEndpointRuntimeConfig.mock.calls
      .map(([, params]) => (params as { consumedBytes?: number }).consumedBytes)
      .find((bytes) => bytes !== undefined);
    expect(chargedToDeferred).toBe(400);
    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenNthCalledWith(
      2,
      expect.anything(),
      expect.objectContaining({ files: [deferredOnly], consumedBytes: 400 }),
    );

    /* The persistent screening runs inside the callback, and must see the two unique
     * files rather than three. */
    const { primeResources } = jest.requireMock('../resources') as { primeResources: jest.Mock };
    const lastCall = primeResources.mock.calls[primeResources.mock.calls.length - 1];
    const screen = lastCall?.[0].screenPersistentFiles as (files: unknown[]) => unknown[];
    filterFilesByEndpointRuntimeConfig.mockClear();
    filterFilesByEndpointRuntimeConfig.mockReturnValueOnce([]);
    screen([]);
    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({ consumedBytes: 500 }),
    );
  });

  it('screens persistent agent files under the remaining size allowance and content policy', async () => {
    /* These are read inside primeResources, so the caller never sees them. Both checks it
     * applied to this turn's other files have to reach them through the callback. */
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const { primeResources } = jest.requireMock('../resources') as { primeResources: jest.Mock };
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      db,
    );

    const screen = primeResources.mock.calls[0][0].screenPersistentFiles as (
      files: unknown[],
    ) => unknown[];
    expect(typeof screen).toBe('function');

    filterFilesByEndpointRuntimeConfig.mockClear();
    const persistent = [{ file_id: 'persistent-1', filename: 'notes.csv', bytes: 10 }];
    filterFilesByEndpointRuntimeConfig.mockReturnValueOnce(persistent);

    expect(screen(persistent)).toEqual(persistent);
    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({ consumedBytes: expect.any(Number) }),
    );
  });

  it('drops a persistent agent file the content policy now refuses', async () => {
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const { primeResources } = jest.requireMock('../resources') as { primeResources: jest.Mock };
    const { assertModelBoundContent } = jest.requireMock('../../middleware/modelBoundContent') as {
      assertModelBoundContent: jest.Mock;
    };
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      db,
    );

    const screen = primeResources.mock.calls[0][0].screenPersistentFiles as (
      files: unknown[],
    ) => unknown[];
    const persistent = [
      {
        file_id: 'blocked-1',
        filename: 'secrets.bin',
        bytes: 10,
        type: 'application/octet-stream',
      },
    ];
    filterFilesByEndpointRuntimeConfig.mockReturnValueOnce(persistent);
    assertModelBoundContent.mockImplementationOnce(() => {
      throw new Error('content policy');
    });

    expect(screen(persistent)).toEqual([]);
  });

  it('finds deferred files from the conversation when no anchor is supplied', async () => {
    /* The Responses API always continues via `previous_response_id` and passes a null
     * parentMessageId, and chat completions may omit it. Without an anchor there is no
     * thread walk, so the conversation's own file refs are the only available scope. */
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    const getMessages = jest.fn().mockResolvedValue([]);
    const getConvoFiles = jest.fn().mockResolvedValue(['convo-file-1']);
    const getDeferredProvisionFiles = jest.fn().mockResolvedValue([]);

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: null,
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      { ...db, getMessages, getConvoFiles, getDeferredProvisionFiles },
    );

    expect(getMessages).not.toHaveBeenCalled();
    expect(getDeferredProvisionFiles).toHaveBeenCalledWith(
      ['convo-file-1'],
      expect.anything(),
      expect.objectContaining({ code: true }),
    );
  });

  it('takes no conversation files for a turn sent at the root', async () => {
    /* A root turn has no history: the conversation's file refs belong to sibling roots, such
     * as the first message edited or retried without its files, and must not come back. */
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    const getMessages = jest.fn().mockResolvedValue([]);
    const getConvoFiles = jest.fn().mockResolvedValue(['sibling-root-file']);
    const getDeferredProvisionFiles = jest.fn().mockResolvedValue([]);
    const getToolFilesByIds = jest.fn().mockResolvedValue([]);

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: Constants.NO_PARENT as string,
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      { ...db, getMessages, getConvoFiles, getDeferredProvisionFiles, getToolFilesByIds },
    );

    expect(getConvoFiles).not.toHaveBeenCalled();
    expect(getMessages).not.toHaveBeenCalled();
    expect(getDeferredProvisionFiles).not.toHaveBeenCalled();
    for (const [ids] of getToolFilesByIds.mock.calls) {
      expect(ids).toEqual([]);
    }
  });

  it('keeps an anchored branch scoped to itself when it references no files', async () => {
    /* Widening an empty branch to the conversation would provision a sibling branch's
     * attachments, sending files this branch never mentioned to the Code API or RAG. */
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    const getMessages = jest.fn().mockResolvedValue([{ messageId: 'm1' }]);
    const getConvoFiles = jest.fn().mockResolvedValue(['sibling-branch-file']);
    const getDeferredProvisionFiles = jest.fn().mockResolvedValue([]);
    mockGetThreadData.mockReturnValueOnce({ fileIds: [] });

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: 'parent-1',
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      { ...db, getMessages, getConvoFiles, getDeferredProvisionFiles },
    );

    expect(getDeferredProvisionFiles).not.toHaveBeenCalled();
  });

  it('prefers the thread scope for deferred files when an anchor is supplied', async () => {
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    const getMessages = jest.fn().mockResolvedValue([{ messageId: 'm1' }]);
    const getConvoFiles = jest.fn().mockResolvedValue(['convo-file-1']);
    const getDeferredProvisionFiles = jest.fn().mockResolvedValue([]);
    mockGetThreadData.mockReturnValueOnce({ fileIds: ['thread-file-1'] });

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: 'parent-1',
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      { ...db, getMessages, getConvoFiles, getDeferredProvisionFiles },
    );

    expect(getDeferredProvisionFiles).toHaveBeenCalledWith(
      ['thread-file-1'],
      expect.anything(),
      expect.objectContaining({ code: true }),
    );
  });

  it('skips the thread walk when parentMessageId is an empty string', async () => {
    /* An empty anchor can never match a parent chain, so walking the
     * conversation only buys an unbounded read whose result is discarded.
     * `req.body.parentMessageId` reaches this layer unnormalized. */
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    const getMessages = jest.fn().mockResolvedValue([]);
    const getConvoFiles = jest.fn().mockResolvedValue([]);

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: '',
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      { ...db, getMessages, getConvoFiles },
    );

    expect(getMessages).not.toHaveBeenCalled();
    expect(mockGetThreadData).not.toHaveBeenCalled();
    /* The conversation read is unconditional and must survive the guard. */
    expect(getConvoFiles).toHaveBeenCalledTimes(1);
  });

  it('dispatches the convo-file read and the thread walk concurrently', async () => {
    /* Both reads gate the model call, so serializing them costs
     * time-to-first-token on every turn. Holding BOTH unresolved is what
     * makes this fail under either ordering: whichever runs first blocks,
     * and the second is never dispatched.
     *
     * DELETE this test, do not repair it, if the thread walk ever gains a
     * data dependency on the convo file ids — serializing becomes correct. */
    const { agent, req, res, loadTools, db } = setupExecuteCodeAgent();

    let releaseConvoFiles!: (fileIds: string[]) => void;
    let releaseMessages!: (messages: Array<{ messageId: string }>) => void;
    const getConvoFiles = jest
      .fn()
      .mockReturnValue(new Promise<string[]>((resolve) => (releaseConvoFiles = resolve)));
    const getMessages = jest
      .fn()
      .mockReturnValue(
        new Promise<Array<{ messageId: string }>>((resolve) => (releaseMessages = resolve)),
      );

    const initialized = initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        conversationId: 'conv-1',
        parentMessageId: 'msgN',
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        codeEnvAvailable: true,
      },
      { ...db, getConvoFiles, getMessages },
    );

    /* Drain pending microtasks so the mocked chain runs up to the first
     * genuinely-pending await. */
    await new Promise((resolve) => setImmediate(resolve));

    expect(getConvoFiles).toHaveBeenCalledTimes(1);
    expect(getMessages).toHaveBeenCalledTimes(1);

    releaseConvoFiles([]);
    releaseMessages([]);
    await initialized;
  });
});

describe('initializeAgent — run-scoped MCP tool definitions', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('carries mcpAvailableTools from the loadTools result onto the initialized agent', async () => {
    /** Regression guard for the request-scoped MCP/PTC handoff: dropping this
     *  field at the destructure boundary forces per-call reinitialization
     *  downstream and can storm the MCP circuit breaker. */
    const { agent, req, res, loadTools, db } = createMocks();
    const mcpTool = 'list_tables_mcp_ClickHouse';
    const mcpAvailableTools = {
      ClickHouse: {
        [mcpTool]: {
          type: 'function' as const,
          function: {
            name: mcpTool,
            description: 'List tables',
            parameters: { type: 'object' as const, properties: {} },
          },
        },
      },
    };
    loadTools.mockResolvedValue({
      tools: [],
      toolContextMap: {},
      dynamicToolContextMap: {},
      userMCPAuthMap: undefined,
      toolRegistry: undefined,
      toolDefinitions: [],
      hasDeferredTools: false,
      mcpAvailableTools,
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.mcpAvailableTools).toEqual(mcpAvailableTools);
  });

  it('retains the resolved collision audit on the initialized agent', async () => {
    /** Deferred/event-driven execution reuses this snapshot instead of
     *  repeating the merged-registry read — a transient failure there
     *  would fail-closed a tool the turn already advertised. */
    const { agent, req, res, loadTools, db } = createMocks();
    const rawServerName = 'Connector: Company';
    const accessibleNames = [rawServerName, 'plain_server'];
    (req as { config: { mcpConfig?: Record<string, unknown> } }).config = {
      mcpConfig: { [rawServerName]: {} },
    };
    agent.tools = [`search${Constants.mcp_delimiter}${rawServerName}`];
    const getAccessibleMcpServerNames = jest.fn(async () => accessibleNames);

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      { ...db, getAccessibleMcpServerNames },
    );

    expect(result.accessibleMcpServerNames).toEqual(accessibleNames);
    expect(loadTools).toHaveBeenCalledWith(
      expect.objectContaining({ accessibleMcpServerNames: accessibleNames }),
    );
  });

  it('keeps valid authored limits through symbol-only server normalization and chat admission', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      structuredTools: [{ name: 'web_search' }],
      loadedToolDefinitions: [{ name: 'web_search' }],
    });
    const names = Array.from({ length: 1023 }, (_, i) => `${`${i}`.padEnd(58, 'q')}_mcp_!`);
    agent.tools = ['web_search'];
    agent.tool_options = Object.fromEntries([
      ...names.map((name) => [name, { approval_mode: 'ask' as const }]),
      ['web_search', { approval_mode: 'ask' as const }],
    ]);
    req.config!.mcpConfig = { '!': { type: 'stdio', command: 'node', args: [] } };
    db.getAccessibleMcpServerNames = jest.fn().mockResolvedValue(['!']);
    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );
    expect(loadTools).toHaveBeenCalledWith(
      expect.objectContaining({
        tool_options: expect.objectContaining({
          [names[0].replace(/!$/, 'server_33')]: { approval_mode: 'ask' },
        }),
      }),
    );
    expect(
      canAgentGraphPause({ policy: { enabled: true, mode: 'bypass' }, agents: [result] }),
    ).toBe(true);
  });

  it('threads the normalized MCP request body into tool discovery', async () => {
    const { agent, req, res, loadTools, db } = createMocks();
    agent.tools = ['custom_tool'];
    const requestBody = {
      messageId: 'message-1',
      conversationId: 'conversation-1',
      parentMessageId: 'parent-1',
    };

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        requestBody,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    expect(loadTools).toHaveBeenCalledWith(expect.objectContaining({ requestBody }));
  });

  it('unions snapshot config names into the audit when the merged read omits them', async () => {
    /** The registry's merged read tolerates config-server init failures and
     *  can silently drop config-only servers — the heal audit must restore
     *  them from the request's config snapshot or a collision goes unseen
     *  while the audit still claims completeness. */
    const { agent, req, res, loadTools, db } = createMocks();
    const rawServerName = 'Connector: Company';
    (req as { config: { mcpConfig?: Record<string, unknown> } }).config = {
      mcpConfig: { [rawServerName]: {} },
    };
    agent.tools = [`search${Constants.mcp_delimiter}${rawServerName}`];
    const getAccessibleMcpServerNames = jest.fn(async () => ['db_only_server']);

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      { ...db, getAccessibleMcpServerNames },
    );

    expect(result.accessibleMcpServerNames).toEqual(['db_only_server', rawServerName]);
  });
});

describe('initializeAgent — authorized run file snapshots', () => {
  const resourceMock = jest.requireMock('../resources') as { primeResources: jest.Mock };
  const filterMock = jest.requireMock('~/files') as {
    filterFilesByEndpointRuntimeConfig: jest.Mock;
  };
  const realResources = jest.requireActual<typeof import('../resources')>('../resources');
  const realFilters = jest.requireActual<typeof import('~/files/filter')>('~/files/filter');

  const inputFile = (overrides: Partial<TFile> = {}): TFile => ({
    file_id: 'current-pdf',
    user: 'user-1',
    filename: 'current.pdf',
    filepath: '/uploads/current.pdf',
    type: 'application/pdf',
    source: FileSources.local,
    bytes: 20,
    usage: 1,
    embedded: false,
    object: 'file',
    llmDeliveryPath: 'provider',
    metadata: { destinationChosen: false },
    ...overrides,
  });

  beforeEach(() => {
    jest.clearAllMocks();
    resourceMock.primeResources.mockReset().mockImplementation(realResources.primeResources);
    filterMock.filterFilesByEndpointRuntimeConfig
      .mockReset()
      .mockImplementation(realFilters.filterFilesByEndpointRuntimeConfig);
  });

  afterEach(() => {
    resourceMock.primeResources
      .mockReset()
      .mockResolvedValue({ attachments: [], tool_resources: undefined });
    filterMock.filterFilesByEndpointRuntimeConfig.mockReset().mockReturnValue([]);
  });

  function setup() {
    const result = createMocks();
    result.agent.tools = [Tools.execute_code, Tools.file_search];
    result.agent.endpoint = EModelEndpoint.openAI;
    return result;
  }

  it.each([undefined, 'Extracted document contents'])(
    'advertises a queued file before tool execution with extracted text %p',
    async (text) => {
      const { agent, req, loadTools, db } = setup();
      if (req.config == null) throw new Error('Missing test configuration');
      req.config.fileConfig = {
        endpoints: {
          [EModelEndpoint.openAI]: {
            defaultLLMDeliveryPath: { overrides: { 'application/pdf': 'text' } },
          },
        },
      };
      loadTools.mockResolvedValue({ toolDefinitions: [{ name: Tools.execute_code }] });
      const file = inputFile({ filename: 'report.pdf', text });
      const result = await initializeAgent(
        {
          req,
          agent,
          loadTools,
          authorizedRunFiles: [file],
          allowedProviders: new Set([Providers.OPENAI]),
          codeEnvAvailable: true,
        },
        db,
      );

      expect(result.dynamicToolContextMap?.queued_code_files).toContain('/mnt/data/report.pdf');
      expect(result.dynamicToolContextMap?.queued_code_files).toContain('read or edit');
      expect(result.dynamicToolContextMap?.queued_code_files).not.toContain(file.filepath);
      expect(result.provisionState?.codeEnvDestinations?.get(file.file_id)).toBe('report.pdf');
      expect(result.provisionState?.codeEnvFiles).toHaveLength(1);
      expect(result.requestAttachments[0].llmDeliveryPath).toBe('text');
      expect(result.requestAttachments[0].text).toBe(text);
      expect(db.getConvoFiles).not.toHaveBeenCalled();
      expect(db.getToolFilesByIds).not.toHaveBeenCalled();
    },
  );

  it('does not advertise code paths when code execution is disabled', async () => {
    const { agent, req, loadTools, db } = setup();
    const result = await initializeAgent(
      {
        req,
        agent,
        loadTools,
        authorizedRunFiles: [inputFile()],
        allowedProviders: new Set([Providers.OPENAI]),
        codeEnvAvailable: false,
      },
      db,
    );
    expect(result.fileConsumers?.executeCode).toBe(false);
    expect(result.dynamicToolContextMap?.queued_code_files).toBeUndefined();
  });

  it.each([undefined, 'Extracted document contents'])(
    'advertises an earlier upload after code is toggled back on with extracted text %p',
    async (text) => {
      const { agent, req, loadTools, db } = setup();
      agent.tools = [Tools.execute_code];
      const params = {
        req,
        agent,
        loadTools,
        allowedProviders: new Set([Providers.OPENAI]),
        codeEnvAvailable: true,
      };
      await initializeAgent({ ...params, authorizedRunFiles: [] }, db);

      const file = inputFile({ filename: 'report.pdf', text });
      agent.tools = [];
      const disabled = await initializeAgent({ ...params, authorizedRunFiles: [file] }, db);
      expect(disabled.fileConsumers?.executeCode).toBe(false);
      expect(disabled.dynamicToolContextMap?.queued_code_files).toBeUndefined();
      expect(disabled.provisionState?.codeEnvFiles ?? []).toEqual([]);

      agent.tools = [Tools.execute_code];
      (db.getConvoFiles as jest.Mock).mockResolvedValue([file.file_id]);
      (db.getFiles as jest.Mock).mockResolvedValue([file]);
      const getDeferredProvisionFiles = jest.fn().mockResolvedValue([file]);
      const getMessages = jest.fn().mockResolvedValue([{ messageId: 'upload-turn' }]);
      mockGetThreadData.mockReturnValueOnce({ fileIds: [file.file_id] });
      const enabled = await initializeAgent(
        { ...params, conversationId: 'conv-1', parentMessageId: 'upload-turn' },
        { ...db, getMessages, getDeferredProvisionFiles },
      );

      expect(enabled.fileConsumers?.executeCode).toBe(true);
      expect(enabled.requestAttachments).toEqual([]);
      expect(enabled.dynamicToolContextMap?.queued_code_files).toContain('/mnt/data/report.pdf');
      expect(enabled.provisionState?.codeEnvFiles.map((entry) => entry.file_id)).toEqual([
        file.file_id,
      ]);
      expect(getDeferredProvisionFiles).toHaveBeenCalledWith(
        [file.file_id],
        expect.anything(),
        expect.objectContaining({ code: true, hydrateProvisioned: true }),
      );
    },
  );

  it('reuses current inputs without reading parent history or counting their usage again', async () => {
    const { agent, req, loadTools, db } = setup();
    const file = inputFile();
    const getMessages = jest.fn();
    const getDeferredProvisionFiles = jest.fn();
    const result = await initializeAgent(
      {
        req,
        agent,
        loadTools,
        conversationId: 'parent-conversation',
        parentMessageId: 'previous-parent-message',
        authorizedRunFiles: [file],
        allowedProviders: new Set([Providers.OPENAI]),
        codeEnvAvailable: true,
        fileSearchAvailable: true,
      },
      { ...db, getMessages, getDeferredProvisionFiles },
    );
    expect(result.requestAttachments.map((entry) => entry.file_id)).toEqual([file.file_id]);
    expect(result.provisionState?.codeEnvFiles.map((entry) => entry.file_id)).toEqual([
      file.file_id,
    ]);
    expect(result.provisionState?.vectorDBFiles.map((entry) => entry.file_id)).toEqual([
      file.file_id,
    ]);
    expect(result.requestAttachments[0]).not.toBe(file);
    expect(result.provisionState?.agentScopedFileIds.size).toBe(0);
    expect(getMessages).not.toHaveBeenCalled();
    expect(getDeferredProvisionFiles).not.toHaveBeenCalled();
    expect(db.getConvoFiles).not.toHaveBeenCalled();
    expect(db.getToolFilesByIds).not.toHaveBeenCalled();
    expect(db.getFiles).not.toHaveBeenCalled();
    expect(db.updateFilesUsage).not.toHaveBeenCalled();
  });

  it('still authorizes and primes the child agent own setup files separately', async () => {
    const { agent, req, loadTools, db } = setup();
    const shared = inputFile();
    const setupFile = inputFile({
      file_id: 'child-setup',
      filename: 'setup.txt',
      type: 'text/plain',
      text: 'child setup instructions',
      llmDeliveryPath: 'text',
      context: FileContext.agents,
    });
    if (req.config == null) throw new Error('Missing test configuration');
    req.config.endpoints = { ...req.config.endpoints };
    req.config.endpoints.agents = configSchema.parse({
      version: '1.3.9',
      endpoints: { agents: { capabilities: [AgentCapabilities.context] } },
    }).endpoints?.agents;
    agent.tools?.push(EToolResources.context);
    agent.tool_resources = { context: { file_ids: [setupFile.file_id] } };
    (db.getFiles as jest.Mock).mockResolvedValue([setupFile]);
    const filterFilesByAgentAccess = jest.fn(async ({ files }: { files: TFile[] }) => files);
    const result = await initializeAgent(
      {
        req,
        agent,
        loadTools,
        conversationId: 'parent-conversation',
        authorizedRunFiles: [shared],
        allowedProviders: new Set([Providers.OPENAI]),
        codeEnvAvailable: true,
        fileSearchAvailable: true,
      },
      { ...db, filterFilesByAgentAccess },
    );
    expect(result.requestAttachments.map((entry) => entry.file_id)).toEqual([shared.file_id]);
    expect(result.agentContextAttachments.map((entry) => entry.file_id)).toEqual([
      setupFile.file_id,
    ]);
    expect(result.provisionState?.agentScopedFileIds).toEqual(new Set([setupFile.file_id]));
    expect(filterFilesByAgentAccess).toHaveBeenCalledWith(
      expect.objectContaining({ agentId: agent.id, userId: 'user-1', files: [setupFile] }),
    );
    expect(db.getFiles).toHaveBeenCalledTimes(1);
    expect(db.getConvoFiles).not.toHaveBeenCalled();
  });

  it('treats an empty authorized snapshot as no shared inputs', async () => {
    const { agent, req, loadTools, db } = setup();
    (db.getConvoFiles as jest.Mock).mockResolvedValue(['unrelated-history']);
    const result = await initializeAgent(
      {
        req,
        agent,
        loadTools,
        conversationId: 'parent-conversation',
        authorizedRunFiles: [],
        allowedProviders: new Set([Providers.OPENAI]),
        codeEnvAvailable: true,
      },
      db,
    );
    expect(result.requestAttachments).toEqual([]);
    expect(result.provisionState).toBeUndefined();
    expect(db.getConvoFiles).not.toHaveBeenCalled();
  });

  it.each([{ user: 'foreign-user' }, { tenantId: 'foreign-tenant' }])(
    'rejects an incorrectly scoped snapshot before priming: %o',
    async (difference) => {
      const { agent, req, loadTools, db } = setup();
      await expect(
        initializeAgent(
          {
            req,
            agent,
            loadTools,
            authorizedRunFiles: [inputFile(difference)],
            allowedProviders: new Set([Providers.OPENAI]),
            codeEnvAvailable: true,
          },
          db,
        ),
      ).rejects.toThrow('authenticated owner');
      expect(resourceMock.primeResources).not.toHaveBeenCalled();
    },
  );

  it('applies the child endpoint policy to the supplied snapshot', async () => {
    const { agent, req, loadTools, db } = setup();
    if (req.config == null) throw new Error('Missing test configuration');
    req.config.fileConfig = { endpoints: { [EModelEndpoint.openAI]: { disabled: true } } };
    const result = await initializeAgent(
      {
        req,
        agent,
        loadTools,
        authorizedRunFiles: [inputFile()],
        allowedProviders: new Set([Providers.OPENAI]),
        codeEnvAvailable: true,
      },
      db,
    );
    expect(result.requestAttachments).toEqual([]);
    expect(result.provisionState).toBeUndefined();
  });

  it('checks current content policy before a shared text file reaches a child', async () => {
    const { agent, req, loadTools, db } = setup();
    if (req.config == null) throw new Error('Missing test configuration');
    req.config.filters = {
      files: {
        pii: {
          starterPatterns: [],
          customPatterns: [{ id: 'private', label: 'private value', regex: 'PRIVATE-[A-Z]+' }],
        },
      },
    };
    await expect(
      initializeAgent(
        {
          req,
          agent,
          loadTools,
          authorizedRunFiles: [inputFile({ llmDeliveryPath: 'text', text: 'PRIVATE-SECRET' })],
          allowedProviders: new Set([Providers.OPENAI]),
          codeEnvAvailable: true,
        },
        db,
      ),
    ).rejects.toMatchObject({ code: 'content_filter_block' });
    expect(resourceMock.primeResources).not.toHaveBeenCalled();
  });

  it('returns only exact current request IDs for seeding a shared-file manifest', async () => {
    const { agent, req, loadTools, db } = setup();
    const current = inputFile();
    const historical = inputFile({ file_id: 'history-file', embedded: true });
    mockExtractLibreChatParams.mockReturnValueOnce({
      resendFiles: true,
      modelOptions: { model: agent.model },
    });
    (db.getFiles as jest.Mock).mockResolvedValue([current, historical]);
    (db.getConvoFiles as jest.Mock).mockResolvedValue([historical.file_id]);
    (db.getToolFilesByIds as jest.Mock).mockResolvedValue([historical]);
    const result = await initializeAgent(
      {
        req,
        agent,
        loadTools,
        conversationId: 'parent-conversation',
        requestFiles: [{ file_id: current.file_id } as IMongoFile],
        allowedProviders: new Set([Providers.OPENAI]),
        codeEnvAvailable: true,
        fileSearchAvailable: true,
      },
      db,
    );
    expect(result.requestAttachments.map((entry) => entry.file_id)).toEqual([
      current.file_id,
      historical.file_id,
    ]);
    expect(result.currentRequestAttachments.map((entry) => entry.file_id)).toEqual([
      current.file_id,
    ]);
    expect(result.currentRequestAttachments[0].user).toBe('user-1');
  });
});

/**
 * Provider-native web search is gated on what the provider builder produced, not
 * on `model_parameters.web_search`: an endpoint's `defaultParams`, `customParams`
 * defaults and `addParams` reach the same switch, and `addParams` is applied last.
 */
describe('initializeAgent — provider-native web search role gate', () => {
  const OPENAI_SEARCH = { type: 'web_search' };

  beforeEach(() => {
    jest.clearAllMocks();
  });

  const roleWithWebSearch = (use: boolean) =>
    jest.fn().mockResolvedValue({
      name: 'USER',
      permissions: { [PermissionTypes.WEB_SEARCH]: { [Permissions.USE]: use } },
    });

  const roleGatedReq = () =>
    ({ user: { id: 'user-1', role: 'USER' }, config: {} }) as unknown as ServerRequest;

  const run = async ({
    provider = Providers.OPENAI,
    providerTools = [OPENAI_SEARCH],
    getRoleByName,
    params = {},
  }: {
    provider?: Providers;
    providerTools?: unknown[];
    getRoleByName?: jest.Mock;
    params?: Partial<Parameters<typeof initializeAgent>[0]>;
  }) => {
    const { agent, res, loadTools, db } = createMocks({ provider, providerTools });
    return initializeAgent(
      {
        req: roleGatedReq(),
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([provider]),
        isInitialAgent: true,
        ...params,
      },
      { ...db, getRoleByName },
    );
  };

  it.each([
    ['OpenAI', Providers.OPENAI, OPENAI_SEARCH],
    ['Anthropic', Providers.ANTHROPIC, { type: 'web_search_20250305', name: 'web_search' }],
    ['Google', Providers.GOOGLE, { googleSearch: {} }],
  ])(
    'strips the %s native search tool when the role denies WEB_SEARCH',
    async (_label, provider, nativeTool) => {
      const result = await run({
        provider: provider as Providers,
        providerTools: [nativeTool],
        getRoleByName: roleWithWebSearch(false),
      });
      expect(result.tools).not.toContainEqual(nativeTool);
    },
  );

  it.each([
    ['OpenAI', Providers.OPENAI, OPENAI_SEARCH],
    ['Anthropic', Providers.ANTHROPIC, { type: 'web_search_20250305', name: 'web_search' }],
    ['Google', Providers.GOOGLE, { googleSearch: {} }],
  ])(
    'keeps the %s native search tool when the role grants WEB_SEARCH',
    async (_label, provider, nativeTool) => {
      const result = await run({
        provider: provider as Providers,
        providerTools: [nativeTool],
        getRoleByName: roleWithWebSearch(true),
      });
      expect(result.tools).toContainEqual(nativeTool);
    },
  );

  /** An agent that stores `web_search: false` still gets native search when its
   *  endpoint's `addParams` turns it on, so the stored value cannot short-circuit
   *  the gate. */
  it('strips endpoint-enabled search for a denied role even when the agent stores false', async () => {
    mockExtractLibreChatParams.mockReturnValueOnce({
      resendFiles: false,
      maxContextTokens: undefined,
      modelOptions: { model: 'test-model', web_search: false },
    });

    const result = await run({ getRoleByName: roleWithWebSearch(false) });

    expect(result.tools).not.toContainEqual(OPENAI_SEARCH);
  });

  it('keeps native search when the external pipeline capability is disabled', async () => {
    const getRoleByName = roleWithWebSearch(true);
    const result = await run({
      getRoleByName,
      params: {
        req: {
          ...roleGatedReq(),
          config: { endpoints: { agents: { capabilities: [AgentCapabilities.file_search] } } },
        } as ServerRequest,
      },
    });

    expect(result.tools).toContainEqual(OPENAI_SEARCH);
    expect(getRoleByName).toHaveBeenCalledTimes(1);
    expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('Restore the role grant'));
  });

  it('explains a blocked native request even when the caller supplies the denial', async () => {
    const result = await run({
      params: { resolveWebSearchGrant: jest.fn().mockResolvedValue(false) },
    });

    expect(result.tools).not.toContainEqual(OPENAI_SEARCH);
    expect(logger.warn).toHaveBeenCalledWith(
      expect.stringContaining('removing interface.webSearch does not reset stored permissions'),
    );
  });

  it('reads no role when the built config turns no native search on', async () => {
    const getRoleByName = roleWithWebSearch(false);
    const resolveWebSearchGrant = jest.fn().mockResolvedValue(false);
    mockExtractLibreChatParams.mockReturnValueOnce({
      resendFiles: false,
      maxContextTokens: undefined,
      modelOptions: { model: 'test-model', web_search: true },
    });

    await run({ providerTools: [], getRoleByName, params: { resolveWebSearchGrant } });

    expect(getRoleByName).not.toHaveBeenCalled();
    expect(resolveWebSearchGrant).not.toHaveBeenCalled();
  });

  /** OpenRouter receives web search as `modelKwargs.plugins`, not as a tool, so
   *  the plugin alone has to trigger the gate. */
  it('strips the OpenRouter web search plugin when the role denies WEB_SEARCH', async () => {
    const { agent, res, loadTools, db } = createMocks({ provider: Providers.OPENAI });
    const llmConfig = {
      model: agent.model,
      modelKwargs: { plugins: [{ id: 'web' }, { id: 'file-parser' }] },
    };
    mockGetProviderConfig.mockReturnValue({
      getOptions: jest.fn().mockResolvedValue({ llmConfig }),
      overrideProvider: Providers.OPENAI,
    });
    const getRoleByName = roleWithWebSearch(false);

    await initializeAgent(
      {
        req: roleGatedReq(),
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      { ...db, getRoleByName },
    );

    expect(getRoleByName).toHaveBeenCalledTimes(1);
    expect(llmConfig.modelKwargs.plugins).toEqual([{ id: 'file-parser' }]);
  });

  /** The OpenAI-compatible and Responses routes reach the initializer with
   *  `runtime` and no `req`; their resolver joins the grants memoized on their
   *  own request, so the initializer must not read the role itself. */
  it('uses the caller resolver instead of reading the role', async () => {
    const getRoleByName = roleWithWebSearch(true);
    const resolveWebSearchGrant = jest.fn().mockResolvedValue(false);

    const result = await run({ getRoleByName, params: { resolveWebSearchGrant } });

    expect(resolveWebSearchGrant).toHaveBeenCalledTimes(1);
    expect(getRoleByName).not.toHaveBeenCalled();
    expect(result.tools).not.toContainEqual(OPENAI_SEARCH);
  });

  it('keeps native search when the caller resolver grants it', async () => {
    const resolveWebSearchGrant = jest.fn().mockResolvedValue(true);

    const result = await run({ params: { resolveWebSearchGrant } });

    expect(result.tools).toContainEqual(OPENAI_SEARCH);
  });

  it('denies native search when the caller resolver throws', async () => {
    const resolveWebSearchGrant = jest.fn().mockRejectedValue(new Error('role store down'));

    const result = await run({ params: { resolveWebSearchGrant } });

    expect(result.tools).not.toContainEqual(OPENAI_SEARCH);
  });

  it('authorizes the runtime user when the caller passes runtime and no req', async () => {
    const getRoleByName = roleWithWebSearch(false);

    const result = await run({
      getRoleByName,
      params: {
        req: undefined,
        runtime: {
          user: { id: 'user-1', role: 'USER' } as never,
          appConfig: {} as never,
          requestBody: {},
          turnStartedAt: 1000,
        },
      },
    });

    expect(getRoleByName).toHaveBeenCalledWith('USER', undefined);
    /** One read, not one per grant: without a `req` there is no per-request
     *  cache to dedupe the three permission checks. */
    expect(getRoleByName).toHaveBeenCalledTimes(1);
    expect(result.tools).not.toContainEqual(OPENAI_SEARCH);
  });

  it('applies no role gate when neither a resolver nor a role lookup is wired', async () => {
    const result = await run({});

    expect(result.tools).toContainEqual(OPENAI_SEARCH);
  });
});

describe('initializeAgent — linked instructions', () => {
  const link: AgentInstructionsPrompt = {
    source: 'native',
    groupId: 'group-1',
    selection: { type: 'production' },
  };

  const flush = () => new Promise((resolve) => setImmediate(resolve));

  /** `ResolveLinkedInstructions` is a callable that also carries a `recordUse`
   *  method (see `../instructions/linked`); a bare `jest.fn()` has no such
   *  property, so tests build the mock the same shape the real resolver has. */
  type ResolveLinkedInstructionsMock = jest.Mock<
    ReturnType<ResolveLinkedInstructions>,
    Parameters<ResolveLinkedInstructions>
  > & { recordUse: jest.Mock };
  function makeResolveLinkedInstructions(): ResolveLinkedInstructionsMock {
    const resolve = jest.fn() as unknown as ResolveLinkedInstructionsMock;
    return Object.assign(resolve, { recordUse: jest.fn() });
  }

  const run = async ({
    agentOverrides,
    reqOverrides,
    params = {},
    loadToolsOverride,
  }: {
    agentOverrides?: Partial<Agent>;
    reqOverrides?: Partial<ServerRequest>;
    params?: Partial<Parameters<typeof initializeAgent>[0]>;
    loadToolsOverride?: (loadTools: ReturnType<typeof createMocks>['loadTools']) => void;
  }) => {
    const { agent, req, res, loadTools, db } = createMocks({});
    Object.assign(agent, agentOverrides);
    Object.assign(req, reqOverrides);
    loadToolsOverride?.(loadTools);
    return initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        ...params,
      },
      db,
    );
  };

  beforeEach(() => {
    (logger.warn as jest.Mock).mockClear?.();
  });

  it('resolves a linked agent, still applies special-vars substitution, and records exactly one usage', async () => {
    const resolveLinkedInstructions = makeResolveLinkedInstructions();
    resolveLinkedInstructions.mockResolvedValue({
      status: 'resolved',
      prompt: 'Hello {{current_user}}, be concise.',
      facts: { source: 'native', groupId: 'group-1', promptId: 'prompt-1' },
    });

    const result = await run({
      agentOverrides: { instructionsPrompt: link },
      reqOverrides: { user: { id: 'user-1', name: 'Ada' } as never },
      params: { resolveLinkedInstructions },
    });
    await flush();

    expect(resolveLinkedInstructions).toHaveBeenCalledWith(expect.objectContaining({ link }));
    expect(result.instructions).toBe('Hello Ada, be concise.');
    expect(result.instructionsPromptFacts).toEqual({
      source: 'native',
      groupId: 'group-1',
      promptId: 'prompt-1',
    });
    expect(resolveLinkedInstructions.recordUse).toHaveBeenCalledTimes(1);
    expect(resolveLinkedInstructions.recordUse).toHaveBeenCalledWith({
      source: 'native',
      groupId: 'group-1',
      promptId: 'prompt-1',
    });
  });

  it('falls back to empty instructions with a warning, and records no usage, when the link is unavailable', async () => {
    const resolveLinkedInstructions = makeResolveLinkedInstructions();
    resolveLinkedInstructions.mockResolvedValue({ status: 'unavailable', reason: 'timeout' });

    const result = await run({
      agentOverrides: { instructionsPrompt: link, instructions: 'stale inline text' },
      params: { resolveLinkedInstructions },
    });
    await flush();

    expect(result.instructions).toBe('');
    expect(result.instructionsPromptFacts).toBeUndefined();
    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('group-1'));
    expect(resolveLinkedInstructions.recordUse).not.toHaveBeenCalled();
  });

  it('falls back to empty instructions with a warning, and records no usage, when a Langfuse link is disabled', async () => {
    const langfuseLink: AgentInstructionsPrompt = {
      source: 'langfuse',
      groupId: 'group-1',
      selection: { type: 'production' },
    };
    const resolveLinkedInstructions = makeResolveLinkedInstructions();
    resolveLinkedInstructions.mockResolvedValue({ status: 'unavailable', reason: 'disabled' });

    const result = await run({
      agentOverrides: { instructionsPrompt: langfuseLink, instructions: 'stale inline text' },
      params: { resolveLinkedInstructions },
    });
    await flush();

    expect(result.instructions).toBe('');
    expect(result.instructionsPromptFacts).toBeUndefined();
    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('group-1'));
    expect(resolveLinkedInstructions.recordUse).not.toHaveBeenCalled();
  });

  it('resolves a linked Langfuse agent and records exactly one usage with version-shaped facts', async () => {
    const langfuseLink: AgentInstructionsPrompt = {
      source: 'langfuse',
      groupId: 'group-1',
      selection: { type: 'production' },
    };
    const resolveLinkedInstructions = makeResolveLinkedInstructions();
    resolveLinkedInstructions.mockResolvedValue({
      status: 'resolved',
      prompt: 'Hello {{current_user}}, be concise.',
      facts: { source: 'langfuse', groupId: 'group-1', version: 3 },
    });

    const result = await run({
      agentOverrides: { instructionsPrompt: langfuseLink },
      reqOverrides: { user: { id: 'user-1', name: 'Ada' } as never },
      params: { resolveLinkedInstructions },
    });
    await flush();

    expect(resolveLinkedInstructions).toHaveBeenCalledWith(
      expect.objectContaining({ link: langfuseLink }),
    );
    expect(result.instructions).toBe('Hello Ada, be concise.');
    expect(result.instructionsPromptFacts).toEqual({
      source: 'langfuse',
      groupId: 'group-1',
      version: 3,
    });
    expect(resolveLinkedInstructions.recordUse).toHaveBeenCalledTimes(1);
    expect(resolveLinkedInstructions.recordUse).toHaveBeenCalledWith({
      source: 'langfuse',
      groupId: 'group-1',
      version: 3,
    });
  });

  it('resolves a linked Langfuse agent normally, but records no usage, when recordLinkedPromptUsage is false (resume)', async () => {
    const langfuseLink: AgentInstructionsPrompt = {
      source: 'langfuse',
      groupId: 'group-1',
      selection: { type: 'exact', version: 3 },
    };
    const resolveLinkedInstructions = makeResolveLinkedInstructions();
    resolveLinkedInstructions.mockResolvedValue({
      status: 'resolved',
      prompt: 'Fixed Langfuse instructions.',
      facts: { source: 'langfuse', groupId: 'group-1', version: 3 },
    });

    const result = await run({
      agentOverrides: { instructionsPrompt: langfuseLink },
      params: { resolveLinkedInstructions, recordLinkedPromptUsage: false },
    });
    await flush();

    expect(result.instructions).toBe('Fixed Langfuse instructions.');
    expect(resolveLinkedInstructions).toHaveBeenCalledWith(
      expect.objectContaining({ link: langfuseLink }),
    );
    expect(resolveLinkedInstructions.recordUse).not.toHaveBeenCalled();
  });

  it('falls back to empty instructions with a warning when no resolver is provided', async () => {
    const result = await run({
      agentOverrides: { instructionsPrompt: link, instructions: 'stale inline text' },
    });

    expect(result.instructions).toBe('');
    expect(result.instructionsPromptFacts).toBeUndefined();
    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining('group-1'));
  });

  it('leaves an unlinked agent unchanged, never calls the resolver, and records no usage', async () => {
    const resolveLinkedInstructions = makeResolveLinkedInstructions();

    const result = await run({
      agentOverrides: { instructions: 'Be helpful.' },
      params: { resolveLinkedInstructions },
    });
    await flush();

    expect(resolveLinkedInstructions).not.toHaveBeenCalled();
    expect(result.instructions).toBe('Be helpful.');
    expect(result.instructionsPromptFacts).toBeUndefined();
    expect(resolveLinkedInstructions.recordUse).not.toHaveBeenCalled();
  });

  it('resolves and initializes normally, but records no usage, when recordLinkedPromptUsage is false', async () => {
    const resolveLinkedInstructions = makeResolveLinkedInstructions();
    resolveLinkedInstructions.mockResolvedValue({
      status: 'resolved',
      prompt: 'Fixed instructions.',
      facts: { source: 'native', groupId: 'group-1', promptId: 'prompt-1' },
    });

    const result = await run({
      agentOverrides: { instructionsPrompt: link },
      params: { resolveLinkedInstructions, recordLinkedPromptUsage: false },
    });
    await flush();

    expect(result.instructions).toBe('Fixed instructions.');
    expect(resolveLinkedInstructions).toHaveBeenCalledWith(expect.objectContaining({ link }));
    expect(resolveLinkedInstructions.recordUse).not.toHaveBeenCalled();
  });

  it('records no usage when initializeAgent throws after a successful resolution', async () => {
    const resolveLinkedInstructions = makeResolveLinkedInstructions();
    resolveLinkedInstructions.mockResolvedValue({
      status: 'resolved',
      prompt: 'Fixed instructions.',
      facts: { source: 'native', groupId: 'group-1', promptId: 'prompt-1' },
    });
    const failure = new Error('boom after resolution');

    await expect(
      run({
        agentOverrides: { instructionsPrompt: link },
        params: { resolveLinkedInstructions },
        loadToolsOverride: (loadTools) =>
          loadTools.mockResolvedValue({
            tools: [],
            toolContextMap: {},
            dynamicToolContextMap: {},
            toolDefinitions: [],
            hasDeferredTools: false,
            // Rejects well after the instructions block has resolved and set
            // `agent.instructions`, so the throw happens on the way OUT.
            repositoryInstructionSource: { load: jest.fn().mockRejectedValue(failure) },
          }),
      }),
    ).rejects.toBe(failure);
    await flush();

    expect(resolveLinkedInstructions.recordUse).not.toHaveBeenCalled();
  });

  it('does not throw when the resolver is a plain function with no recordUse (a successful init still returns normally)', async () => {
    // `resolveLinkedInstructions` is typed as a plain callable in
    // `InitializeAgentParams`; a caller-supplied function that matches the
    // type but not the real resolver's `Object.assign(resolve, { recordUse })`
    // shape must not throw after initialization has already succeeded.
    const resolveLinkedInstructions: ResolveLinkedInstructions = jest.fn().mockResolvedValue({
      status: 'resolved',
      prompt: 'Fixed instructions.',
      facts: { source: 'native', groupId: 'group-1', promptId: 'prompt-1' },
    }) as unknown as ResolveLinkedInstructions;

    const result = await run({
      agentOverrides: { instructionsPrompt: link },
      params: { resolveLinkedInstructions },
    });
    await flush();

    expect(result.instructions).toBe('Fixed instructions.');
  });

  it('does not produce an unhandled rejection when the resolution rejects before it is awaited', async () => {
    const unhandled: unknown[] = [];
    const onUnhandledRejection = (reason: unknown): void => {
      unhandled.push(reason);
    };
    process.on('unhandledRejection', onUnhandledRejection);
    try {
      const rejection = new Error('rejected before the instructions block awaits it');
      const resolveLinkedInstructions = makeResolveLinkedInstructions();
      // Rejects on the same tick it's called — well before `initializeAgent`
      // reaches the instructions block, since that only happens after tool
      // loading (delayed below) and several other steps.
      resolveLinkedInstructions.mockImplementation(() => Promise.reject(rejection));

      await expect(
        run({
          agentOverrides: { instructionsPrompt: link },
          params: { resolveLinkedInstructions },
          loadToolsOverride: (loadTools) =>
            loadTools.mockImplementation(
              () =>
                new Promise((resolve) => {
                  setTimeout(
                    () =>
                      resolve({
                        tools: [],
                        toolContextMap: {},
                        dynamicToolContextMap: {},
                        toolDefinitions: [],
                        hasDeferredTools: false,
                      }),
                    10,
                  );
                }),
            ),
        }),
      ).rejects.toBe(rejection);

      // Give the process a turn to report an unhandled rejection, if any occurred.
      await flush();
    } finally {
      process.off('unhandledRejection', onUnhandledRejection);
    }
    expect(unhandled).toEqual([]);
  });
});

describe('initializeAgent — linked instructions and the agent-definition content policy', () => {
  const link: AgentInstructionsPrompt = {
    source: 'native',
    groupId: 'group-1',
    selection: { type: 'production' },
  };
  const blockingAgentInstructionsFilters: FiltersConfig = {
    agentInstructions: {
      pii: {
        starterPatterns: [],
        customPatterns: [{ id: 'secret', label: 'secret value', regex: 'SECRET-[A-Z]+' }],
        fields: ['instructions'],
      },
    },
  };

  it('blocks a stored inline instructions field that trips the policy when there is no link', async () => {
    const { agent, req, res, loadTools, db } = createMocks({});
    agent.instructions = 'Contains SECRET-VALUE marker';
    Object.assign(req, { config: { filters: blockingAgentInstructionsFilters } });

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
        },
        db,
      ),
    ).rejects.toThrow();
  });

  it('excludes the stored inline instructions from that scan when the agent has a valid link', async () => {
    const { agent, req, res, loadTools, db } = createMocks({});
    Object.assign(agent, {
      instructionsPrompt: link,
      instructions: 'Contains SECRET-VALUE marker',
    });
    Object.assign(req, { config: { filters: blockingAgentInstructionsFilters } });
    const resolveLinkedInstructions = jest.fn().mockResolvedValue({
      status: 'resolved',
      prompt: 'Safe resolved prompt.',
      facts: { source: 'native', groupId: 'group-1', promptId: 'prompt-1' },
    });
    Object.assign(resolveLinkedInstructions, { recordUse: jest.fn() });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
        resolveLinkedInstructions:
          resolveLinkedInstructions as unknown as ResolveLinkedInstructions,
      },
      db,
    );

    expect(result.instructions).toBe('Safe resolved prompt.');
  });

  it('never calls the resolver when the definition-content check rejects a field other than instructions', async () => {
    const { agent, req, res, loadTools, db } = createMocks({});
    Object.assign(agent, {
      instructionsPrompt: link,
      // The stored inline `instructions` are excluded from the scan by the
      // link (see the test above), but `description` is not — the check
      // must still run, and reject, before the resolver is ever started.
      description: 'Contains SECRET-VALUE marker',
    });
    Object.assign(req, {
      config: {
        filters: {
          agentInstructions: {
            pii: {
              starterPatterns: [],
              customPatterns: [{ id: 'secret', label: 'secret value', regex: 'SECRET-[A-Z]+' }],
              fields: ['description'],
            },
          },
        },
      },
    });
    const resolveLinkedInstructions = jest.fn().mockResolvedValue({
      status: 'resolved',
      prompt: 'Safe resolved prompt.',
      facts: { source: 'native', groupId: 'group-1', promptId: 'prompt-1' },
    });
    Object.assign(resolveLinkedInstructions, { recordUse: jest.fn() });

    await expect(
      initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent: true,
          resolveLinkedInstructions:
            resolveLinkedInstructions as unknown as ResolveLinkedInstructions,
        },
        db,
      ),
    ).rejects.toThrow();

    expect(resolveLinkedInstructions).not.toHaveBeenCalled();
  });
});

describe('initializeAgent tool-routed text fallback', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  const routedCsv = () =>
    ({
      file_id: 'csv-file',
      filename: 'sales.csv',
      type: 'text/csv',
      text: 'region,total',
      llmDeliveryPath: 'none',
      metadata: { destinationChosen: false },
    }) as IMongoFile;

  /** A tool serves a file only once it holds it, so these carry the evidence provisioning
   *  writes: vectors for file search, a sandbox pointer for code execution. */
  const embeddedCsv = () => ({ ...routedCsv(), embedded: true }) as IMongoFile;
  const sandboxCsv = () =>
    ({
      ...routedCsv(),
      metadata: {
        destinationChosen: false,
        codeEnvRef: {
          kind: 'user',
          id: 'user_1',
          storage_session_id: 'session_1',
          file_id: 'sandbox_file_1',
        },
      },
    }) as IMongoFile;

  async function initializeWith({
    tools,
    csv,
    textFallbackWithoutTools = true,
    provider = Providers.OPENAI,
    overrideProvider,
    supportedMimeTypes,
    softFailure = false,
    fileSearchAvailable = true,
    fileContextCharLimit,
    useResponsesApi,
  }: {
    tools: string[];
    csv: IMongoFile;
    textFallbackWithoutTools?: boolean;
    provider?: string;
    overrideProvider?: string;
    supportedMimeTypes?: string[];
    softFailure?: boolean;
    fileSearchAvailable?: boolean;
    fileContextCharLimit?: number;
    useResponsesApi?: boolean;
  }) {
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const { agent, req, res, loadTools, db } = createMocks({
      provider,
      overrideProvider,
      loadedToolDefinitions: tools.includes(EToolResources.file_search)
        ? [{ name: EToolResources.file_search }]
        : [],
    });
    if (useResponsesApi != null) {
      mockGetProviderConfig.mockReturnValue({
        overrideProvider: overrideProvider ?? provider,
        getOptions: jest
          .fn()
          .mockResolvedValue({ llmConfig: { model: agent.model, useResponsesApi } }),
      });
    }
    (primeResources as jest.Mock).mockImplementationOnce(async ({ attachments }) => {
      const files = await attachments;
      return {
        attachments: files,
        requestAttachments: files,
        agentContextAttachments: [],
        tool_resources: {},
      };
    });
    agent.tools = tools;
    if (softFailure) loadTools.mockResolvedValue(undefined);
    req.config = {
      fileConfig: {
        fileContextCharLimit,
        endpoints: {
          [provider]: {
            defaultLLMDeliveryPath: { overrides: { 'text/csv': 'none' } },
            textFallbackWithoutTools,
            ...(supportedMimeTypes != null && { supportedMimeTypes }),
          },
        },
      },
    } as unknown as ServerRequest['config'];
    (db.getFiles as jest.Mock).mockResolvedValueOnce([csv]);
    filterFilesByEndpointRuntimeConfig.mockImplementationOnce(
      (_config: ServerRequest['config'], { files }: { files: IMongoFile[] }) => files,
    );

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        requestFiles: [csv],
        codeEnvAvailable: true,
        fileSearchAvailable,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([provider]),
        isInitialAgent: true,
      },
      db,
    );
    return { result, filterFilesByEndpointRuntimeConfig };
  }

  it.each([true, false])(
    'admits Azure PDFs with the final Responses mode %s',
    async (useResponsesApi) => {
      const pdf = { ...routedCsv(), type: 'application/pdf', text: undefined };
      const { result, filterFilesByEndpointRuntimeConfig } = await initializeWith({
        tools: [],
        csv: pdf,
        provider: EModelEndpoint.azureOpenAI,
        overrideProvider: Providers.OPENAI,
        useResponsesApi,
      });
      expect(result.deliveryRouting.useResponsesApi).toBe(useResponsesApi);
      expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
        expect.anything(),
        expect.objectContaining({
          files: [{ ...pdf, llmDeliveryPath: useResponsesApi ? 'provider' : 'text' }],
        }),
      );
    },
  );

  it('keeps fallback out of the prompt when file search loads and holds the file', async () => {
    const csv = embeddedCsv();
    const { result } = await initializeWith({ tools: [EToolResources.file_search], csv });
    expect(result.fileConsumers).toEqual({ executeCode: false, fileSearch: true });
    expect(result.requestAttachments).toEqual([csv]);
  });

  it('delivers fallback text when file search runs but never received the file', async () => {
    /* The plain-chat File Search toggle: the upload names no destination, so nothing files it
     * under a tool resource and the vector store stays empty. Withholding the text for the
     * toggle alone left the attachment readable by neither the model nor the tool. */
    const csv = routedCsv();
    const { result } = await initializeWith({ tools: [EToolResources.file_search], csv });
    expect(result.fileConsumers).toEqual({ executeCode: false, fileSearch: true });
    expect(result.requestAttachments).toEqual([{ ...csv, llmDeliveryPath: 'text' }]);
    expect(csv.llmDeliveryPath).toBe('none');
  });

  it('falls back after file search soft-fails and admits the returned text copy', async () => {
    const csv = routedCsv();
    const { result } = await initializeWith({
      tools: [EToolResources.file_search],
      csv,
      softFailure: true,
    });
    expect(result.fileConsumers).toEqual({ executeCode: false, fileSearch: false });
    expect(result.requestAttachments).toEqual([{ ...csv, llmDeliveryPath: 'text' }]);
    expect(csv.llmDeliveryPath).toBe('none');
  });

  it('rejects fallback text that exceeds admission after a reader soft-fails', async () => {
    await expect(
      initializeWith({
        tools: [EToolResources.file_search],
        csv: routedCsv(),
        softFailure: true,
        fileContextCharLimit: 3,
      }),
    ).rejects.toMatchObject({ name: 'AgentAttachmentLimitError' });
  });

  it('hands endpoint filtering a text copy when the agent runs no tool that can read the file', async () => {
    const csv = routedCsv();

    const { result, filterFilesByEndpointRuntimeConfig } = await initializeWith({ tools: [], csv });

    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({ files: [{ ...csv, llmDeliveryPath: 'text' }] }),
    );
    expect(result.fileConsumers).toEqual({ executeCode: false, fileSearch: false });
    expect(csv.llmDeliveryPath).toBe('none');
  });

  it('hands endpoint filtering the provider route a tool-routed file takes on this turn', async () => {
    /* Admission reads the route, so a record left for tools that this endpoint sends to the
     * provider must reach filtering, limits and inspection as a provider file. */
    const image = {
      file_id: 'image-file',
      filename: 'chart.png',
      type: 'image/png',
      llmDeliveryPath: 'none',
      metadata: { destinationChosen: false },
    } as IMongoFile;

    const { filterFilesByEndpointRuntimeConfig } = await initializeWith({
      tools: [],
      csv: image,
    });

    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({ files: [{ ...image, llmDeliveryPath: 'provider' }] }),
    );
    expect(image.llmDeliveryPath).toBe('none');
  });

  it('keeps media a custom endpoint opted into on its provider route before the provider swap', async () => {
    /* The encoders send OpenAI-format media to a custom endpoint that lists the type, so the
     * route has to read that endpoint's dialect from config, not the name still in `provider`. */
    const video = {
      file_id: 'video-file',
      filename: 'clip.mp4',
      type: 'video/mp4',
      llmDeliveryPath: 'provider',
      metadata: { destinationChosen: false },
    } as IMongoFile;

    const { filterFilesByEndpointRuntimeConfig } = await initializeWith({
      tools: [],
      csv: video,
      provider: 'MyGateway',
      overrideProvider: Providers.OPENAI,
      supportedMimeTypes: ['video/mp4'],
    });

    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({ files: [video] }),
    );
  });

  it('resolves a custom endpoint agent under the endpoint its upload was routed by', async () => {
    /* Uploads resolve the agent's saved provider, which for a custom endpoint is its name.
     * Initialization later swaps the provider for the backing client, so an opt-in set only
     * on the custom endpoint must still be read under that name, here and after the swap. */
    const csv = routedCsv();

    const { result, filterFilesByEndpointRuntimeConfig } = await initializeWith({
      tools: [],
      csv,
      provider: 'MyGateway',
      overrideProvider: Providers.OPENAI,
    });

    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({ files: [{ ...csv, llmDeliveryPath: 'text' }] }),
    );
    expect(result.provider).toBe(Providers.OPENAI);
    expect(result.endpoint).toBe('MyGateway');
  });

  it('leaves the file on its tool route where the endpoint has not enabled the fallback', async () => {
    const csv = routedCsv();

    const { filterFilesByEndpointRuntimeConfig } = await initializeWith({
      tools: [],
      csv,
      textFallbackWithoutTools: false,
    });

    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({ files: [csv] }),
    );
  });

  it('leaves the file to Run Code when the sandbox already holds it', async () => {
    const csv = sandboxCsv();

    const { result, filterFilesByEndpointRuntimeConfig } = await initializeWith({
      tools: [EToolResources.execute_code],
      csv,
    });

    expect(filterFilesByEndpointRuntimeConfig).toHaveBeenCalledWith(
      expect.anything(),
      expect.objectContaining({ files: [csv] }),
    );
    expect(result.fileConsumers).toEqual({ executeCode: true, fileSearch: false });
  });
});

describe('initializeAgent turn delivery routing', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('settles the routing once, after the provider swap and the Responses API decision', async () => {
    const { agent, req, res, loadTools, db } = createMocks({ provider: 'MyClaude' });
    req.config = {
      fileConfig: { endpoints: { MyClaude: { supportedMimeTypes: ['video/mp4'] } } },
      endpoints: { custom: [{ name: 'MyClaude', provider: 'anthropic' }] },
    } as unknown as ServerRequest['config'];
    mockGetProviderConfig.mockReturnValue({
      overrideProvider: Providers.ANTHROPIC,
      getOptions: jest
        .fn()
        .mockResolvedValue({ llmConfig: { model: 'test-model', useResponsesApi: true } }),
    });

    const result = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set(['MyClaude']),
        isInitialAgent: true,
      },
      db,
    );

    expect(result.provider).toBe(Providers.ANTHROPIC);
    expect(result.deliveryRouting).toMatchObject({
      endpoint: 'MyClaude',
      endpointProvider: 'anthropic',
      useResponsesApi: true,
      sttConfigured: false,
    });
    expect(result.deliveryRouting.endpointConfig.supportedMimeTypes).toEqual([/video\/mp4/]);
  });

  it('resolves the provider and its options before any attachment is loaded', async () => {
    const { filterFilesByEndpointRuntimeConfig } = jest.requireMock('~/files') as {
      filterFilesByEndpointRuntimeConfig: jest.Mock;
    };
    const { agent, req, res, loadTools, db } = createMocks();
    const getOptions = jest.fn().mockResolvedValue({ llmConfig: { model: 'test-model' } });
    mockGetProviderConfig.mockReturnValue({ overrideProvider: Providers.OPENAI, getOptions });
    const file = {
      file_id: 'file-1',
      filename: 'notes.txt',
      type: 'text/plain',
      bytes: 10,
      text: 'notes',
      llmDeliveryPath: 'text',
    } as IMongoFile;
    (db.getFiles as jest.Mock).mockResolvedValueOnce([file]);
    filterFilesByEndpointRuntimeConfig.mockImplementationOnce(
      (_config: ServerRequest['config'], { files }: { files: IMongoFile[] }) => files,
    );

    await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        requestFiles: [file],
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI]),
        isInitialAgent: true,
      },
      db,
    );

    const [optionsOrder] = getOptions.mock.invocationCallOrder;
    const [filesOrder] = (db.getFiles as jest.Mock).mock.invocationCallOrder;
    const [toolsOrder] = loadTools.mock.invocationCallOrder;
    expect(optionsOrder).toBeLessThan(filesOrder);
    expect(filesOrder).toBeLessThan(toolsOrder);
  });
});

describe('initializeAgent — inference trust boundary', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it.each([true, false])(
    'projects saved settings and request overrides (initial: %s)',
    async (isInitialAgent) => {
      const { agent, req, res, loadTools, db } = createMocks({
        provider: Providers.OPENAI,
        model: 'gpt-4o-mini',
      });
      Object.assign(agent.model_parameters, {
        temperature: 0.2,
        apiKey: 'untrusted-secret',
        modelKwargs: { model: 'gpt-4o', service_tier: 'flex' },
        configuration: { baseURL: 'https://unchecked.invalid' },
        callbacks: ['not-user-configurable'],
        fallbacks: [{ provider: 'openAI', clientOptions: { model: 'gpt-4o' } }],
        unknownConstructorField: true,
      });
      mockExtractLibreChatParams.mockImplementation(realUtils.extractLibreChatParams);

      await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: {
            endpoint: EModelEndpoint.agents,
            model_parameters: { temperature: 0.4, modelKwargs: { model: 'gpt-4o' } },
          },
          allowedProviders: new Set([Providers.OPENAI]),
          isInitialAgent,
        },
        db,
      );

      const { results } = mockGetProviderConfig.mock;
      const { getOptions } = results[results.length - 1].value;
      expect(getOptions).toHaveBeenCalledWith(
        expect.objectContaining({
          model_parameters: {
            model: 'gpt-4o-mini',
            temperature: isInitialAgent ? 0.4 : 0.2,
          },
        }),
      );
    },
  );

  it.each(['custom', 'anthropic', 'google'])(
    'retains canonical settings and endpoint identity for same-agent memory reentry (%s)',
    async (mode) => {
      const { agent, req, res, loadTools, db } = createMocks({
        provider: 'Gateway',
        overrideProvider: Providers.OPENAI,
        model: 'permitted',
      });
      Object.assign(agent.model_parameters, { min_p: 0.7, modelKwargs: { min_p: 0.9 } });
      const getOptions = jest
        .fn()
        .mockImplementation(async ({ model_parameters, inferenceParameters }) => ({
          llmConfig: {
            model: model_parameters.model,
            apiKey: 'trusted-key',
            modelKwargs: { min_p: inferenceParameters?.min_p ?? 0.1 },
          },
          configOptions: { baseURL: 'https://trusted.invalid' },
        }));
      mockGetProviderConfig.mockImplementation(({ provider }) => {
        if (provider !== 'Gateway') throw new Error('Lost original endpoint identity');
        return {
          getOptions,
          overrideProvider: Providers.OPENAI,
          customEndpointConfig: {
            customParams: {
              defaultParamsEndpoint: mode,
              paramDefinitions: [
                { key: 'min_p', type: 'number', default: 0.1, range: { min: 0, max: 1 } },
              ],
            },
          },
        };
      });
      mockExtractLibreChatParams.mockImplementation(realUtils.extractLibreChatParams);
      const params = {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI, 'Gateway']),
        isInitialAgent: true,
      };
      const main = await initializeAgent(params, db);
      const mainConfig = main.model_parameters;
      expect(mainConfig).toMatchObject({ modelKwargs: { min_p: 0.7 } });
      for (let attempt = 0; attempt < 3; attempt++) {
        const memory = await initializeAgent(
          { ...params, agent: { ...main }, isInitialAgent: false },
          db,
        );
        expect(memory.model_parameters).toMatchObject({ modelKwargs: { min_p: 0.7 } });
        expect(memory).not.toBe(main);
        expect(main.model_parameters).toBe(mainConfig);
        expect(getOptions).toHaveBeenLastCalledWith(
          expect.objectContaining({
            endpoint: 'Gateway',
            model_parameters: { model: 'permitted' },
            inferenceParameters: { min_p: 0.7 },
          }),
        );
      }
      await expect(
        initializeAgent(
          {
            ...params,
            agent: main,
            allowedProviders: new Set([Providers.OPENAI]),
            isInitialAgent: false,
          },
          db,
        ),
      ).rejects.toThrow('invalid_agent_provider');
    },
  );

  it('uses the trusted URL profile before projecting saved and request caching controls', async () => {
    const key = 'TEST_INFERENCE_GATEWAY_URL';
    const previous = process.env[key];
    process.env[key] = 'https://openrouter.ai/api/v1';
    try {
      const { agent, req, res, loadTools, db } = createMocks({
        provider: 'Gateway',
        overrideProvider: Providers.OPENAI,
        model: 'permitted',
      });
      Object.assign(agent.model_parameters, { promptCache: false, promptCacheTtl: '1h' });
      const endpoint = {
        name: 'Gateway',
        apiKey: 'synthetic-key',
        baseURL: '${TEST_INFERENCE_GATEWAY_URL}',
        models: { default: ['permitted'], fetch: false },
      };
      if (req.config == null) throw new Error('Expected the request configuration fixture');
      req.config.endpoints = { custom: [endpoint] };
      const getOptions = jest
        .fn()
        .mockResolvedValue({ llmConfig: { model: 'permitted', promptCache: false } });
      mockGetProviderConfig.mockReturnValue({
        getOptions,
        overrideProvider: Providers.OPENAI,
        customEndpointConfig: endpoint,
      });
      mockExtractLibreChatParams.mockImplementation(realUtils.extractLibreChatParams);
      await initializeAgent(
        {
          req,
          res,
          agent,
          loadTools,
          endpointOption: { endpoint: EModelEndpoint.agents },
          allowedProviders: new Set([Providers.OPENAI, 'Gateway']),
          isInitialAgent: true,
        },
        db,
      );
      expect(getOptions).toHaveBeenCalledWith(
        expect.objectContaining({
          endpoint: 'Gateway',
          model_parameters: { model: 'permitted', promptCache: false, promptCacheTtl: '1h' },
        }),
      );
    } finally {
      if (previous === undefined) delete process.env[key];
      else process.env[key] = previous;
    }
  });

  it('constructs custom request kwargs only from administrator-declared inference values', async () => {
    const { agent, req, res, loadTools, db } = createMocks({
      provider: 'Gateway',
      overrideProvider: Providers.OPENAI,
      model: 'permitted',
    });
    Object.assign(agent.model_parameters, { min_p: 0.1, modelKwargs: { model: 'restricted' } });
    const getOptions = jest.fn().mockResolvedValue({
      llmConfig: {
        model: 'permitted',
        apiKey: 'trusted-key',
        configuration: { baseURL: 'https://trusted.invalid' },
        modelKwargs: { seed: 7 },
      },
    });
    mockGetProviderConfig.mockReturnValue({
      getOptions,
      overrideProvider: Providers.OPENAI,
      customEndpointConfig: {
        customParams: {
          defaultParamsEndpoint: 'custom',
          paramDefinitions: [{ key: 'min_p', type: 'number', range: { min: 0, max: 1 } }],
        },
      },
    });
    mockExtractLibreChatParams.mockImplementation(realUtils.extractLibreChatParams);
    const initialized = await initializeAgent(
      {
        req,
        res,
        agent,
        loadTools,
        endpointOption: { endpoint: EModelEndpoint.agents },
        allowedProviders: new Set([Providers.OPENAI, 'Gateway']),
        isInitialAgent: true,
      },
      db,
    );

    expect(getOptions).toHaveBeenCalledWith(
      expect.objectContaining({
        model_parameters: { model: 'permitted' },
        inferenceParameters: { min_p: 0.1 },
      }),
    );
    expect(initialized.model_parameters).toMatchObject({
      model: 'permitted',
      apiKey: 'trusted-key',
      configuration: { baseURL: 'https://trusted.invalid' },
      modelKwargs: { seed: 7 },
    });
  });
});