Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { z } from 'zod';
import { DynamicStructuredTool } from '@langchain/core/tools';
import { HumanMessage, AIMessage } from '@langchain/core/messages';
import { CallbackManager } from '@langchain/core/callbacks/manager';
import { encryptV3, logger, mergeConfigOverrides } from '@librechat/data-schemas';
import {
EModelEndpoint,
FileSources,
PrincipalType,
MAX_SUBAGENT_DEPTH,
MAX_SUBAGENT_RUN_CONFIGS,
} from 'librechat-data-provider';
import type {
CompactionSemanticIndex,
SubagentTaskConfig,
SubagentConfig,
AgentInputs,
} from '@librechat/agents';
import type { AppConfig, ConfigOverrideLayer, IUser } from '@librechat/data-schemas';
import type { SummarizationConfig, TEndpoint } from 'librechat-data-provider';
import type { BaseMessage } from '@langchain/core/messages';
import type { OpenAI } from 'openai';
import type { ModelBoundChatModelCallback } from '~/middleware/modelBoundContent';
import type { OpenAIConfiguration, AzureOptions } from '~/types';
import { clearToolApprovalHooks, registerToolApprovalHook } from '~/agents/hitl/hooks';
import { executionFixture } from '~/schedules/authorization/execution.helper';
import { createRun, isAskUserQuestionAdminDisabled } from '~/agents/run';
import { initializeOpenAI } from '~/endpoints/openai/initialize';
import { createSecretRebindingGuard } from '~/app/rebinding';
import { getOpenAIConfig } from '~/endpoints/openai/config';
// Mock winston logger — `format` must be callable 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(),
},
}));
/** Spy on the real `resolveHeaders` instead of replacing it — the templated-header
* case below only proves anything if the actual substitution runs. */
jest.mock('~/utils/env', () => {
const actual = jest.requireActual<typeof import('~/utils/env')>('~/utils/env');
return { ...actual, resolveHeaders: jest.fn(actual.resolveHeaders) };
});
jest.mock('@librechat/data-schemas', () => ({
...jest.requireActual('@librechat/data-schemas'),
decryptV3: jest.fn((value: string) => {
if (value === 'v3:test:sk-tenant-1') {
return 'sk-tenant-1';
}
throw new Error('bad decrypt');
}),
encryptV3: jest.fn((value: string) => `v3:test:${value}`),
logger: {
debug: jest.fn(),
warn: jest.fn(),
error: jest.fn(),
info: jest.fn(),
},
}));
// Mock Run.create to capture the graphConfig it receives
jest.mock('@librechat/agents', () => {
const actual = jest.requireActual('@librechat/agents');
return {
...actual,
Run: {
create: jest.fn().mockResolvedValue({
processStream: jest.fn().mockResolvedValue(undefined),
}),
},
};
});
// Stub the durable checkpointer so the HITL-enabled path doesn't need a live Mongo.
jest.mock('~/agents/checkpointer', () => ({
getAgentCheckpointer: jest.fn().mockResolvedValue({}),
}));
import { ChatOpenAI } from '@librechat/agents/llm/openai';
import { ChatOpenRouter } from '@librechat/agents/llm/openrouter';
import {
Run,
Providers,
HookRegistry,
ToolNode,
Constants,
buildChildInputs,
InMemorySubagentTaskStore,
buildSubagentToolParams,
executeHooks,
} from '@librechat/agents';
/** Minimal RunAgent factory */
function makeAgent(
overrides?: Record<string, unknown>,
): Record<string, unknown> & { id: string; provider: string; model: string } {
return {
id: 'agent_1',
provider: 'openAI',
endpoint: 'openAI',
model: 'gpt-4o',
tools: [],
model_parameters: { model: 'gpt-4o' },
maxContextTokens: 100_000,
toolContextMap: {},
...overrides,
};
}
describe('isAskUserQuestionAdminDisabled', () => {
it('applies includedTools precedence and the filteredTools fallback', () => {
expect(isAskUserQuestionAdminDisabled(undefined)).toBe(false);
expect(isAskUserQuestionAdminDisabled({ includedTools: ['calculator'] } as AppConfig)).toBe(
true,
);
expect(
isAskUserQuestionAdminDisabled({ includedTools: ['ask_user_question'] } as AppConfig),
).toBe(false);
expect(
isAskUserQuestionAdminDisabled({ filteredTools: ['ask_user_question'] } as AppConfig),
).toBe(true);
});
});
type TestRunAgent = ReturnType<typeof makeAgent> & {
subagentAgentConfigs?: TestRunAgent[];
};
type BuildChildInput = Parameters<typeof buildChildInputs>[0];
function makeSubagentChain(hops: number): TestRunAgent {
const agents = Array.from({ length: hops + 1 }, (_, index) =>
makeAgent({
id: `agent_chain_${index}`,
name: `Chain ${index}`,
}),
) as TestRunAgent[];
for (let index = 0; index < hops; index++) {
const child = agents[index + 1];
agents[index].subagents = { enabled: true, allowSelf: false, agent_ids: [child.id] };
agents[index].subagentAgentConfigs = [child];
}
return agents[0];
}
function makeLayeredSubagentDag(width: number, depth: number): TestRunAgent {
const root = makeAgent({ id: 'agent_dag_root', name: 'DAG Root' }) as TestRunAgent;
const layers: TestRunAgent[][] = [[root]];
for (let level = 1; level <= depth; level++) {
layers.push(
Array.from({ length: width }, (_, index) =>
makeAgent({
id: `agent_dag_${level}_${index}`,
name: `DAG ${level}.${index}`,
}),
) as TestRunAgent[],
);
}
for (let level = 0; level < depth; level++) {
const children = layers[level + 1];
for (const agent of layers[level]) {
agent.subagents = {
enabled: true,
allowSelf: false,
agent_ids: children.map((child) => child.id),
};
agent.subagentAgentConfigs = children;
}
}
return root;
}
/** Helper: call createRun and return the captured agentInputs array */
async function callAndCapture(
opts: {
agents?: ReturnType<typeof makeAgent>[];
summarizationConfig?: SummarizationConfig;
summarizeOnly?: boolean;
initialSummary?: { text: string; tokenCount: number };
appConfig?: AppConfig;
messages?: BaseMessage[];
discoveredToolNames?: string[];
compactionSemanticIndex?: CompactionSemanticIndex;
subagentTasks?: SubagentTaskConfig;
modelCallbacks?: readonly ModelBoundChatModelCallback[];
user?: IUser;
tenantId?: string;
requestBody?: Parameters<typeof createRun>[0]['requestBody'];
steering?: Parameters<typeof createRun>[0]['steering'];
customHandlers?: Parameters<typeof createRun>[0]['customHandlers'];
} = {},
) {
const agents = opts.agents ?? [makeAgent()];
const signal = new AbortController().signal;
await createRun({
agents: agents as never,
signal,
summarizationConfig: opts.summarizationConfig,
summarizeOnly: opts.summarizeOnly,
initialSummary: opts.initialSummary,
appConfig: opts.appConfig,
messages: opts.messages,
discoveredToolNames: opts.discoveredToolNames,
compactionSemanticIndex: opts.compactionSemanticIndex,
subagentTasks: opts.subagentTasks,
modelCallbacks: opts.modelCallbacks,
user: opts.user,
tenantId: opts.tenantId,
requestBody: opts.requestBody,
steering: opts.steering,
customHandlers: opts.customHandlers,
streaming: true,
streamUsage: true,
});
const createMock = Run.create as jest.Mock;
expect(createMock).toHaveBeenCalledTimes(1);
const callArgs = createMock.mock.calls[0][0];
return callArgs.graphConfig.agents as Array<Record<string, unknown>>;
}
/** Minimal AppConfig with a single custom endpoint for testing provider resolution. */
type TestCustomEndpoint = Partial<TEndpoint> & {
name: string;
baseURL: string;
apiKey: string;
};
/**
* Shape of summarization parameters used in tests. The LibreChat config
* schema restricts yaml `parameters` to primitive values, but the SDK
* passes any record through as-is — tests need the wider shape to exercise
* cross-endpoint `configuration` merging.
*/
type TestSummarizationParameters = Record<string, unknown> & {
configuration?: Record<string, unknown>;
};
/**
* Minimal AppConfig fixture for testing. Only `endpoints` is read by
* `resolveSummarizationProvider`; other required AppConfig fields are
* filled with empty/default values so the shape matches without needing
* `as unknown as AppConfig`.
*/
function makeAppConfig(customEndpoints: TestCustomEndpoint[]): AppConfig {
return {
config: {},
fileStrategy: FileSources.local,
imageOutputType: 'png',
endpoints: {
[EModelEndpoint.custom]: customEndpoints,
},
};
}
beforeEach(() => {
jest.clearAllMocks();
delete process.env.LANGFUSE_PUBLIC_KEY;
delete process.env.LANGFUSE_SECRET_KEY;
delete process.env.LANGFUSE_BASE_URL;
delete process.env.LANGFUSE_BASEURL;
delete process.env.LANGFUSE_HOST;
delete process.env.LANGFUSE_FANOUT_ENABLED;
delete process.env.LANGFUSE_FANOUT_COLLECTOR_URL;
delete process.env.LANGFUSE_FANOUT_CENTRAL_MEDIA_UPLOAD_DISABLED;
delete process.env.LANGFUSE_FANOUT_TENANT_DESTINATIONS;
delete process.env.LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED;
delete process.env.LANGFUSE_TRACING_ENABLED;
delete process.env.LANGFUSE_SAMPLE_RATE;
process.env.TENANT_ISOLATION_STRICT = 'true';
});
describe('compaction semantic index forwarding', () => {
it('forwards one host-derived snapshot to every top-level agent input', async () => {
const compactionSemanticIndex = [
{
type: 'activity_phase',
sourceMessageId: 'message-1',
sourceContentIndex: 3,
revision: 2,
status: 'committed',
text: 'Verified the release state',
},
] satisfies CompactionSemanticIndex;
const agents = await callAndCapture({
agents: [makeAgent({ id: 'agent_1' }), makeAgent({ id: 'agent_2' })],
compactionSemanticIndex,
});
expect(agents).toHaveLength(2);
expect(agents[0].compactionSemanticIndex).toBe(compactionSemanticIndex);
expect(agents[1].compactionSemanticIndex).toBe(compactionSemanticIndex);
});
it('does not leak the parent history index into an isolated subagent', async () => {
const compactionSemanticIndex = [
{
type: 'activity_phase',
sourceMessageId: 'message-1',
sourceContentIndex: 3,
revision: 2,
status: 'committed',
text: 'Verified the release state',
},
] satisfies CompactionSemanticIndex;
const child = makeAgent({ id: 'agent_child' });
const [root] = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
subagentAgentConfigs: [child],
}),
],
compactionSemanticIndex,
});
const [childConfig] = root.subagentConfigs as Array<Record<string, unknown>>;
expect(root.compactionSemanticIndex).toBe(compactionSemanticIndex);
expect(childConfig.agentInputs).not.toHaveProperty('compactionSemanticIndex');
});
});
afterAll(() => {
delete process.env.TENANT_ISOLATION_STRICT;
});
// ---------------------------------------------------------------------------
// Suite: agent endpoint projection
// ---------------------------------------------------------------------------
describe('agent endpoint projection', () => {
it('preserves each logical endpoint independently from its resolved provider', async () => {
const agents = await callAndCapture({
agents: [
makeAgent({ id: 'sales-copilot', provider: 'bedrock', endpoint: 'bedrock' }),
makeAgent({ id: 'dwaine', provider: 'openAI', endpoint: 'DWAINE' }),
],
});
expect(agents).toEqual(
expect.arrayContaining([
expect.objectContaining({
agentId: 'sales-copilot',
endpoint: 'bedrock',
provider: 'bedrock',
}),
expect.objectContaining({
agentId: 'dwaine',
endpoint: 'DWAINE',
provider: 'openAI',
}),
]),
);
});
});
// ---------------------------------------------------------------------------
// Suite: custom endpoint stream usage defaults
// ---------------------------------------------------------------------------
describe('custom endpoint stream usage defaults', () => {
it('disables streamUsage by default for OpenAI-compatible custom endpoints', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ endpoint: 'LiteLLM' })],
});
const clientOptions = agents[0].clientOptions as Record<string, unknown>;
expect(clientOptions.streamUsage).toBe(false);
expect(clientOptions.usage).toBe(true);
});
it('respects explicit streamUsage from endpoint-resolved model parameters', async () => {
const agents = await callAndCapture({
agents: [
makeAgent({
endpoint: 'LiteLLM',
model_parameters: {
model: 'gpt-4o',
streamUsage: true,
},
}),
],
});
const clientOptions = agents[0].clientOptions as Record<string, unknown>;
expect(clientOptions.streamUsage).toBe(true);
expect(clientOptions.usage).toBe(true);
});
});
describe('model-level callbacks', () => {
it('propagates guards through root, fallback, summary, eager, lazy, and graph clients', async () => {
const modelCallback: ModelBoundChatModelCallback = {
name: 'librechat-model-bound-content-filter',
raiseError: true,
awaitHandlers: true,
handleChatModelStart: jest.fn(),
};
const eagerChild = makeAgent({ id: 'agent_eager', name: 'Eager child' });
const lazyResolve = jest
.fn()
.mockResolvedValue(makeAgent({ id: 'agent_lazy', name: 'Lazy child' }));
const graphMember = makeAgent({ id: 'agent_graph', name: 'Graph member' });
const graphDefinition = {
type: 'guarded_team',
name: 'Guarded team',
description: 'Exercises graph member client options',
agent_ids: [graphMember.id],
edges: [],
entry_agent_id: graphMember.id,
result_agent_id: graphMember.id,
};
const agents = await callAndCapture({
modelCallbacks: [modelCallback],
summarizationConfig: {
provider: 'anthropic',
model: 'claude-test',
parameters: {
fallbacks: [{ provider: 'openAI', clientOptions: { temperature: 0 } }],
} as unknown as SummarizationConfig['parameters'],
},
agents: [
makeAgent({
model_parameters: {
model: 'gpt-4o',
fallbacks: [{ provider: 'anthropic', clientOptions: { temperature: 0 } }],
},
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [eagerChild.id, 'agent_lazy'],
graphs: [graphDefinition],
},
subagentAgentConfigs: [eagerChild],
lazySubagentConfigs: [
{
id: 'agent_lazy',
name: 'Lazy child',
description: 'Resolves only when selected',
configId: 'agent_lazy:1:fingerprint',
resolve: lazyResolve,
},
],
subagentGraphConfigs: [{ definition: graphDefinition, memberConfigs: [graphMember] }],
}),
],
});
const root = agents[0];
const rootOptions = root.clientOptions as Record<string, unknown>;
expect(rootOptions.callbacks).toEqual([modelCallback]);
expect(
(
(rootOptions.fallbacks as Array<Record<string, unknown>>)[0].clientOptions as Record<
string,
unknown
>
).callbacks,
).toEqual([modelCallback]);
const summary = root.summarizationConfig as Record<string, unknown>;
const summaryParameters = summary.parameters as Record<string, unknown>;
expect(summaryParameters.callbacks).toEqual([modelCallback]);
expect(
(
(summaryParameters.fallbacks as Array<Record<string, unknown>>)[0].clientOptions as Record<
string,
unknown
>
).callbacks,
).toEqual([modelCallback]);
const configs = root.subagentConfigs as Array<Record<string, unknown>>;
const eager = configs.find((config) => config.type === 'agent_eager');
expect(
((eager?.agentInputs as Record<string, unknown>).clientOptions as Record<string, unknown>)
.callbacks,
).toEqual([modelCallback]);
const lazy = configs.find((config) => config.type === 'agent_lazy');
const lazyInputs = await (
lazy?.resolveAgentInputs as (context: never) => Promise<Record<string, unknown>>
)({ signal: new AbortController().signal } as never);
expect((lazyInputs.clientOptions as Record<string, unknown>).callbacks).toEqual([
modelCallback,
]);
const graph = configs.find((config) => config.type === 'guarded_team');
const [member] = graph?.agents as Array<Record<string, unknown>>;
expect((member.clientOptions as Record<string, unknown>).callbacks).toEqual([modelCallback]);
});
it('preserves a pre-existing callback manager when installing model guards', async () => {
const existingLLMStart = jest.fn();
const existingManager = CallbackManager.fromHandlers({ handleLLMStart: existingLLMStart });
const modelCallback: ModelBoundChatModelCallback = {
name: 'librechat-model-bound-content-filter',
raiseError: true,
awaitHandlers: true,
handleChatModelStart: jest.fn(),
};
const agents = await callAndCapture({
modelCallbacks: [modelCallback],
agents: [
makeAgent({
model_parameters: {
model: 'gpt-4o',
callbacks: existingManager,
},
}),
],
});
const callbacks = (agents[0].clientOptions as { callbacks: CallbackManager }).callbacks;
expect(callbacks).toBeInstanceOf(CallbackManager);
expect(callbacks).not.toBe(existingManager);
expect(callbacks.handlers).toEqual(
expect.arrayContaining([
expect.objectContaining({ handleLLMStart: existingLLMStart }),
modelCallback,
]),
);
expect(existingManager.handlers).toHaveLength(1);
});
});
// ---------------------------------------------------------------------------
// Suite 1: reserveRatio
// ---------------------------------------------------------------------------
describe('reserveRatio', () => {
it('applies ratio from config using baseContextTokens, capped at maxContextTokens', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ baseContextTokens: 200_000, maxContextTokens: 200_000 })],
summarizationConfig: { reserveRatio: 0.03, provider: 'anthropic', model: 'claude' },
});
// Math.round(200000 * 0.97) = 194000, min(200000, 194000) = 194000
expect(agents[0].maxContextTokens).toBe(194_000);
});
it('never exceeds user-configured maxContextTokens even when ratio computes higher', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ baseContextTokens: 200_000, maxContextTokens: 50_000 })],
summarizationConfig: { reserveRatio: 0.03, provider: 'anthropic', model: 'claude' },
});
// Math.round(200000 * 0.97) = 194000, but min(50000, 194000) = 50000
expect(agents[0].maxContextTokens).toBe(50_000);
});
it('falls back to maxContextTokens when ratio is not set', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ maxContextTokens: 100_000, baseContextTokens: 200_000 })],
summarizationConfig: { provider: 'anthropic', model: 'claude' },
});
expect(agents[0].maxContextTokens).toBe(100_000);
});
it('falls back to maxContextTokens when ratio is 0', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ maxContextTokens: 100_000, baseContextTokens: 200_000 })],
summarizationConfig: { reserveRatio: 0, provider: 'anthropic', model: 'claude' },
});
expect(agents[0].maxContextTokens).toBe(100_000);
});
it('falls back to maxContextTokens when ratio is 1', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ maxContextTokens: 100_000, baseContextTokens: 200_000 })],
summarizationConfig: { reserveRatio: 1, provider: 'anthropic', model: 'claude' },
});
expect(agents[0].maxContextTokens).toBe(100_000);
});
it('falls back to maxContextTokens when baseContextTokens is undefined', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ maxContextTokens: 100_000 })],
summarizationConfig: { reserveRatio: 0.05, provider: 'anthropic', model: 'claude' },
});
expect(agents[0].maxContextTokens).toBe(100_000);
});
it('clamps to 1024 minimum but still capped at maxContextTokens', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ baseContextTokens: 500, maxContextTokens: 2000 })],
summarizationConfig: { reserveRatio: 0.99, provider: 'anthropic', model: 'claude' },
});
// Math.round(500 * 0.01) = 5 → clamped to 1024, min(2000, 1024) = 1024
expect(agents[0].maxContextTokens).toBe(1024);
});
});
// ---------------------------------------------------------------------------
// Suite 2: maxSummaryTokens passthrough
// ---------------------------------------------------------------------------
describe('maxSummaryTokens passthrough', () => {
it('forwards global maxSummaryTokens value', async () => {
const agents = await callAndCapture({
summarizationConfig: {
provider: 'anthropic',
model: 'claude',
maxSummaryTokens: 4096,
},
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.maxSummaryTokens).toBe(4096);
});
});
// ---------------------------------------------------------------------------
// Suite 3: summarizationEnabled resolution
// ---------------------------------------------------------------------------
describe('summarizationEnabled resolution', () => {
it('true with provider + model + enabled', async () => {
const agents = await callAndCapture({
summarizationConfig: {
enabled: true,
provider: 'anthropic',
model: 'claude-3-haiku',
},
});
expect(agents[0].summarizationEnabled).toBe(true);
});
it('false when provider is empty string', async () => {
const agents = await callAndCapture({
summarizationConfig: {
enabled: true,
provider: '',
model: 'claude-3-haiku',
},
});
expect(agents[0].summarizationEnabled).toBe(false);
});
it('false when enabled is explicitly false', async () => {
const agents = await callAndCapture({
summarizationConfig: {
enabled: false,
provider: 'anthropic',
model: 'claude-3-haiku',
},
});
expect(agents[0].summarizationEnabled).toBe(false);
});
it('true with self-summarize default when summarizationConfig is undefined', async () => {
const agents = await callAndCapture({
summarizationConfig: undefined,
});
expect(agents[0].summarizationEnabled).toBe(true);
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('openAI');
expect(config.model).toBe('gpt-4o');
});
it('false when the effective context budget is below the viable minimum', async () => {
/**
* A tiny user-set maxContextTokens re-triggers summarization on every
* graph step until the recursion limit aborts the run; the guard falls
* back to plain pruning instead.
*/
const agents = await callAndCapture({
agents: [makeAgent({ maxContextTokens: 10 })],
summarizationConfig: {
enabled: true,
provider: 'anthropic',
model: 'claude-3-haiku',
},
});
expect(agents[0].summarizationEnabled).toBe(false);
});
it('true at exactly the 1024-token viable minimum', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ maxContextTokens: 1024 })],
summarizationConfig: {
enabled: true,
provider: 'anthropic',
model: 'claude-3-haiku',
},
});
expect(agents[0].summarizationEnabled).toBe(true);
});
});
// ---------------------------------------------------------------------------
// Suite 4: summarizationConfig field passthrough
// ---------------------------------------------------------------------------
describe('summarizationConfig field passthrough', () => {
it('all fields pass through to agentInputs', async () => {
const agents = await callAndCapture({
summarizationConfig: {
enabled: true,
trigger: { type: 'token_ratio', value: 0.8 },
provider: 'anthropic',
model: 'claude-3-haiku',
parameters: { temperature: 0.2 },
prompt: 'Summarize this conversation',
updatePrompt: 'Update the existing summary with new messages',
reserveRatio: 0.1,
maxSummaryTokens: 4096,
retainRecent: { turns: 5, tokens: 40000 },
},
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config).toBeDefined();
// `enabled` is not forwarded to the agent-level config — it is resolved
// into the separate `summarizationEnabled` boolean on the agent input.
expect(agents[0].summarizationEnabled).toBe(true);
expect(config.trigger).toEqual({ type: 'token_ratio', value: 0.8 });
expect(config.provider).toBe('anthropic');
expect(config.model).toBe('claude-3-haiku');
expect(config.parameters).toEqual({ temperature: 0.2 });
expect(config.prompt).toBe('Summarize this conversation');
expect(config.updatePrompt).toBe('Update the existing summary with new messages');
expect(config.reserveRatio).toBe(0.1);
expect(config.maxSummaryTokens).toBe(4096);
expect(config.retainRecent).toEqual({ turns: 5, tokens: 40000 });
});
it('uses self-summarize default when no config provided', async () => {
const agents = await callAndCapture({
summarizationConfig: undefined,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config).toBeDefined();
// `enabled` is resolved into `summarizationEnabled`, not forwarded on config
expect(agents[0].summarizationEnabled).toBe(true);
expect(config.provider).toBe('openAI');
expect(config.model).toBe('gpt-4o');
});
it('preserves `token_ratio` trigger with `value: 0` (documented, extreme-but-valid)', async () => {
const agents = await callAndCapture({
summarizationConfig: {
enabled: true,
trigger: { type: 'token_ratio', value: 0 },
},
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.trigger).toEqual({ type: 'token_ratio', value: 0 });
});
it.each([
['remaining_tokens', 500],
['messages_to_refine', 4],
] as const)('passes %s trigger through unchanged', async (type, value) => {
const agents = await callAndCapture({
summarizationConfig: {
enabled: true,
trigger: { type, value },
},
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.trigger).toEqual({ type, value });
});
});
// ---------------------------------------------------------------------------
// Suite: reasoning effort translation
// ---------------------------------------------------------------------------
const OPENROUTER_MODEL = 'openai/gpt-5.6';
const ADAPTIVE_CLAUDE_MODEL = 'anthropic/claude-sonnet-4.6';
/** Agent whose resolved client options already carry a reasoning configuration. */
function makeReasoningAgent(overrides: {
azureOptions?: AzureOptions;
provider: string;
endpoint: string;
model: string;
model_parameters: Record<string, unknown>;
}) {
return makeAgent({
...overrides,
provider: overrides.provider as never,
endpoint: overrides.endpoint,
model: overrides.model,
model_parameters: overrides.model_parameters as never,
});
}
describe('summarization reasoning effort', () => {
it.each(['medium', 'low'])(
'overrides an inherited OpenRouter reasoning object with %s, leaving the agent untouched',
async (reasoningEffort) => {
const agents = await callAndCapture({
agents: [
makeReasoningAgent({
provider: Providers.OPENROUTER,
endpoint: 'OpenRouter',
model: OPENROUTER_MODEL,
model_parameters: {
model: OPENROUTER_MODEL,
modelKwargs: { reasoning: { effort: 'max' } },
},
}),
],
summarizationConfig: {
provider: 'OpenRouter',
model: OPENROUTER_MODEL,
parameters: { reasoning_effort: reasoningEffort },
},
});
const mainClientOptions = agents[0].clientOptions as Record<string, unknown>;
const summaryConfig = agents[0].summarizationConfig as Record<string, unknown>;
expect(mainClientOptions.modelKwargs).toEqual({ reasoning: { effort: 'max' } });
expect(summaryConfig.parameters).toEqual({ reasoning: { effort: reasoningEffort } });
/** The SDK spreads `parameters` onto the agent's own client options. */
const summaryModel = new ChatOpenRouter({
...mainClientOptions,
...(summaryConfig.parameters as Record<string, unknown>),
apiKey: 'test-key',
model: summaryConfig.model as string,
});
const request = summaryModel.invocationParams();
expect(request.reasoning).toEqual({ effort: reasoningEffort });
expect(request.reasoning_effort).toBeUndefined();
},
);
it('overrides an inherited OpenAI reasoning object', async () => {
const agents = await callAndCapture({
agents: [
makeReasoningAgent({
provider: EModelEndpoint.openAI,
endpoint: EModelEndpoint.openAI,
model: 'gpt-5.6',
model_parameters: { model: 'gpt-5.6', reasoning: { effort: 'high' } },
}),
],
summarizationConfig: {
provider: EModelEndpoint.openAI,
model: 'gpt-5.6',
parameters: { reasoning_effort: 'low' },
},
});
const mainClientOptions = agents[0].clientOptions as Record<string, unknown>;
const summaryConfig = agents[0].summarizationConfig as Record<string, unknown>;
expect(mainClientOptions.reasoning).toEqual({ effort: 'high' });
expect(summaryConfig.parameters).toEqual({ reasoning: { effort: 'low' } });
const summaryModel = new ChatOpenAI({
...mainClientOptions,
...(summaryConfig.parameters as Record<string, unknown>),
apiKey: 'test-key',
model: summaryConfig.model as string,
} as never);
const request = summaryModel.invocationParams() as Record<string, unknown>;
/** Chat Completions re-emits the object as the scalar the API expects. */
expect(request.reasoning_effort).toBe('low');
});
it('maps effort to verbosity for OpenRouter adaptive Anthropic models', async () => {
const agents = await callAndCapture({
agents: [
makeReasoningAgent({
provider: Providers.OPENROUTER,
endpoint: 'OpenRouter',
model: ADAPTIVE_CLAUDE_MODEL,
model_parameters: {
model: ADAPTIVE_CLAUDE_MODEL,
verbosity: 'max',
modelKwargs: { reasoning: { enabled: true } },
},
}),
],
summarizationConfig: {
provider: 'OpenRouter',
model: ADAPTIVE_CLAUDE_MODEL,
parameters: { reasoning_effort: 'low' },
},
});
const summaryConfig = agents[0].summarizationConfig as Record<string, unknown>;
expect(summaryConfig.parameters).toEqual({
verbosity: 'low',
reasoning: { enabled: true },
});
});
it('turns adaptive thinking off for reasoning_effort "none"', async () => {
const agents = await callAndCapture({
agents: [
makeReasoningAgent({
provider: Providers.OPENROUTER,
endpoint: 'OpenRouter',
model: ADAPTIVE_CLAUDE_MODEL,
model_parameters: {
model: ADAPTIVE_CLAUDE_MODEL,
modelKwargs: { reasoning: { enabled: true } },
},
}),
],
summarizationConfig: {
provider: 'OpenRouter',
model: ADAPTIVE_CLAUDE_MODEL,
parameters: { reasoning_effort: 'none' },
},
});
const summaryConfig = agents[0].summarizationConfig as Record<string, unknown>;
expect(summaryConfig.parameters).toEqual({ reasoning: { enabled: false } });
const summaryModel = new ChatOpenRouter({
...(agents[0].clientOptions as Record<string, unknown>),
...(summaryConfig.parameters as Record<string, unknown>),
apiKey: 'test-key',
model: ADAPTIVE_CLAUDE_MODEL,
});
expect(summaryModel.invocationParams().reasoning).toEqual({ enabled: false });
});
it('translates for a custom endpoint that resolves to OpenRouter by baseURL', async () => {
const appConfig = makeAppConfig([
{ name: 'Router', baseURL: 'https://openrouter.ai/api/v1', apiKey: 'router-key' },
]);
const agents = await callAndCapture({
summarizationConfig: {
provider: 'Router',
model: OPENROUTER_MODEL,
parameters: { reasoning_effort: 'low' },
},
appConfig,
});
const summaryConfig = agents[0].summarizationConfig as Record<string, unknown>;
expect(summaryConfig.provider).toBe(Providers.OPENROUTER);
expect(summaryConfig.parameters).toMatchObject({ reasoning: { effort: 'low' } });
expect(summaryConfig.parameters).not.toHaveProperty('reasoning_effort');
});
it('leaves parameters untouched for providers with no reasoning_effort concept', async () => {
const agents = await callAndCapture({
summarizationConfig: {
provider: EModelEndpoint.anthropic,
model: 'claude-3-haiku',
parameters: { reasoning_effort: 'low' },
},
});
const summaryConfig = agents[0].summarizationConfig as Record<string, unknown>;
expect(summaryConfig.parameters).toEqual({ reasoning_effort: 'low' });
});
it('leaves unrelated parameters and an unset effort untouched', async () => {
const agents = await callAndCapture({
agents: [
makeReasoningAgent({
provider: Providers.OPENROUTER,
endpoint: 'OpenRouter',
model: OPENROUTER_MODEL,
model_parameters: { model: OPENROUTER_MODEL },
}),
],
summarizationConfig: {
provider: 'OpenRouter',
model: OPENROUTER_MODEL,
parameters: { temperature: 0.2, streaming: false, reasoning_effort: '' },
},
});
const summaryConfig = agents[0].summarizationConfig as Record<string, unknown>;
expect(summaryConfig.parameters).toEqual({
temperature: 0.2,
streaming: false,
reasoning_effort: '',
});
});
});
type CapturedRequest = {
url: URL;
headers: Headers;
body: OpenAI.ChatCompletionCreateParams & OpenAI.Responses.ResponseCreateParams;
};
async function compactSummary(
agents: Array<Record<string, unknown>>,
requests: CapturedRequest[] = [],
messages: BaseMessage[] = [
new HumanMessage('Compute 1 + 1.'),
new AIMessage('2'),
new HumanMessage('Compute 2 + 2.'),
new AIMessage('4'),
new HumanMessage('Compute 3 + 3.'),
new AIMessage('6'),
],
) {
const summaryConfig = agents[0].summarizationConfig as NonNullable<
AgentInputs['summarizationConfig']
>;
const clientOptions = agents[0].clientOptions as { configuration?: OpenAIConfiguration };
const configuration = {
...((summaryConfig.parameters?.configuration ??
clientOptions.configuration) as OpenAIConfiguration),
};
summaryConfig.parameters = { ...summaryConfig.parameters, configuration };
configuration.fetch = async (url, init) => {
requests.push({
url: new URL(String(url)),
headers: new Headers(init?.headers),
body: JSON.parse(String(init?.body)),
});
const text = 'The user asked for arithmetic and the assistant calculated four.';
return Response.json({
id: 'summary-response',
model: 'summary-production',
object: 'response',
status: 'completed',
choices: [{ index: 0, message: { role: 'assistant', content: text }, finish_reason: 'stop' }],
output: [
{
type: 'message',
id: 'msg_summary',
role: 'assistant',
status: 'completed',
content: [{ type: 'output_text', text, annotations: [] }],
},
],
usage: {
prompt_tokens: 20,
completion_tokens: 10,
input_tokens: 20,
output_tokens: 10,
total_tokens: 30,
},
});
};
const actual = jest.requireActual<typeof import('@librechat/agents')>('@librechat/agents');
const runConfig = (Run.create as jest.Mock).mock.calls[0][0] as Parameters<typeof Run.create>[0];
const run = await actual.Run.create({
...runConfig,
graphConfig: { ...runConfig.graphConfig, agents: agents as unknown as AgentInputs[] },
tokenCounter: (message) => String(message.content).length,
});
await run.processStream(
{ messages },
{ version: 'v2', configurable: { thread_id: 'azure-summary-test' } },
);
return { requests };
}
describe('manual compaction recency', () => {
it('skips a fully retained conversation without calling the summarizer', async () => {
const agents = await callAndCapture({
summarizeOnly: true,
summarizationConfig: { model: 'gpt-4o', parameters: { streaming: false } },
});
const requests: CapturedRequest[] = [];
await expect(
compactSummary(agents, requests, [
new HumanMessage('Compute 1 + 1.'),
new AIMessage('2'),
new HumanMessage('Compute 2 + 2.'),
new AIMessage('4'),
]),
).rejects.toMatchObject({
name: 'ManualSummarizationSkippedError',
reason: 'nothing_to_summarize',
});
expect(requests).toHaveLength(0);
});
});
describe('Azure deployment alias', () => {
/** `initializeAgent` maps an Azure Responses agent to the OpenAI provider. */
const azureAstraAgent = () => {
const { llmConfig, configOptions } = getOpenAIConfig(
'test-azure-key',
{
azure: {
azureOpenAIApiInstanceName: 'test-instance',
azureOpenAIApiDeploymentName: 'production-deployment',
azureOpenAIApiVersion: '2025-04-01-preview',
azureOpenAIApiKey: 'test-azure-key',
},
modelOptions: { model: 'gpt-6-astra', max_tokens: 2048 },
},
EModelEndpoint.azureOpenAI,
);
return makeReasoningAgent({
provider: EModelEndpoint.openAI,
endpoint: EModelEndpoint.azureOpenAI,
model: 'gpt-6-astra',
model_parameters: { ...llmConfig, configuration: configOptions },
});
};
/** The SDK spreads `parameters` onto the agent's client options, then sets `model`. */
const summaryRequestModel = (
clientOptions: Record<string, unknown>,
summaryConfig: Record<string, unknown>,
) => {
const summaryModel = new ChatOpenAI({
...clientOptions,
...((summaryConfig.parameters as Record<string, unknown> | undefined) ?? {}),
apiKey: 'test-key',
model: summaryConfig.model as string,
} as never);
return (summaryModel.invocationParams() as Record<string, unknown>).model;
};
it("keeps the Astra agent's API mode and deployment alias out of a custom-endpoint summarizer", async () => {
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig: makeAppConfig([
{
name: 'Gateway',
apiKey: 'gateway-key',
baseURL: 'https://gateway.example/v1',
models: { default: ['gpt-4.1-mini'] },
},
]),
summarizeOnly: true,
summarizationConfig: {
provider: 'Gateway',
model: 'gpt-4.1-mini',
parameters: { streaming: false },
},
});
expect((agents[0].clientOptions as Record<string, unknown>).modelKwargs).toEqual({
model: 'production-deployment',
max_output_tokens: 2048,
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
const { url, headers, body } = requests[0];
expect(url.origin + url.pathname).toBe('https://gateway.example/v1/chat/completions');
expect(headers.get('api-key')).toBeNull();
expect(body.model).toBe('gpt-4.1-mini');
expect(body).not.toHaveProperty('include');
});
it.each([
{ useModelAsDeploymentName: undefined, deployment: 'env-deployment' },
{ useModelAsDeploymentName: 'true', deployment: 'gpt-41-mini' },
])(
'resolves a different summary model through the legacy Azure environment to $deployment',
async ({ useModelAsDeploymentName, deployment }) => {
jest.replaceProperty(process, 'env', {
...process.env,
AZURE_API_KEY: 'env-key',
AZURE_OPENAI_API_INSTANCE_NAME: 'env-instance',
AZURE_OPENAI_API_DEPLOYMENT_NAME: 'env-deployment',
AZURE_OPENAI_API_VERSION: '2024-10-21',
AZURE_USE_MODEL_AS_DEPLOYMENT_NAME: useModelAsDeploymentName,
});
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig: makeAppConfig([]),
summarizeOnly: true,
summarizationConfig: { model: 'gpt-4.1-mini', parameters: { streaming: false } },
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
const { url, headers, body } = requests[0];
expect(url.origin + url.pathname).toBe(
`https://env-instance.openai.azure.com/openai/deployments/${deployment}/chat/completions`,
);
expect(headers.get('api-key')).toBe('env-key');
expect(body.model).toBe(deployment);
},
);
it('applies summarization base URL and API key overrides to an Azure summary deployment', async () => {
const appConfig = makeAppConfig([]);
appConfig.endpoints![EModelEndpoint.azureOpenAI] = {
isValid: true,
errors: [],
modelNames: ['gpt-6-astra', 'gpt-4.1-mini'],
modelGroupMap: { 'gpt-6-astra': { group: 'main' }, 'gpt-4.1-mini': { group: 'summary' } },
groupMap: {
main: {
apiKey: 'test-azure-key',
instanceName: 'test-instance',
version: '2025-04-01-preview',
models: { 'gpt-6-astra': { deploymentName: 'production-deployment' } },
},
summary: {
apiKey: 'summary-key',
instanceName: 'summary-instance',
version: '2024-10-21',
models: { 'gpt-4.1-mini': { deploymentName: 'summary-production' } },
},
},
};
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig,
summarizeOnly: true,
summarizationConfig: {
model: 'gpt-4.1-mini',
parameters: {
streaming: false,
apiKey: 'gateway-key',
baseURL: 'https://summary-gateway.example/openai/deployments/${DEPLOYMENT_NAME}',
},
},
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
const { url, headers } = requests[0];
expect(url.origin + url.pathname).toBe(
'https://summary-gateway.example/openai/deployments/summary-production/chat/completions',
);
expect(headers.get('api-key')).toBe('gateway-key');
});
it.each([
{ model: 'gpt-6-astra', initialResponses: true, useResponsesApi: true },
{ model: 'gpt-4.1', initialResponses: false, useResponsesApi: false },
{ model: 'gpt-6-astra', initialResponses: true, useResponsesApi: false },
{ model: 'gpt-4.1', initialResponses: false, useResponsesApi: true },
])(
'uses same-model Azure transport overrides for $model',
async ({ model, initialResponses, useResponsesApi }) => {
const { llmConfig, configOptions } = getOpenAIConfig(
'resolved-user-key',
{
azure: {
azureOpenAIApiKey: 'resolved-user-key',
azureOpenAIApiInstanceName: 'user-instance',
azureOpenAIApiDeploymentName: 'user-deployment',
azureOpenAIApiVersion: '2024-10-21',
},
modelOptions: { model, max_tokens: 1536 },
headers: { 'X-Request': 'resolved-user-header' },
},
EModelEndpoint.azureOpenAI,
);
const agents = await callAndCapture({
agents: [
makeReasoningAgent({
endpoint: EModelEndpoint.azureOpenAI,
provider: initialResponses ? Providers.OPENAI : Providers.AZURE,
model,
model_parameters: { ...llmConfig, configuration: configOptions },
}),
],
appConfig: makeAppConfig([]),
summarizeOnly: true,
summarizationConfig: {
model,
parameters: {
streaming: false,
apiKey: 'override-key',
useResponsesApi,
baseURL:
'https://summary-instance.openai.azure.com/openai/deployments/${DEPLOYMENT_NAME}',
},
},
});
expect(agents[0].summarizationEnabled).toBe(true);
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
expect(requests[0].url.origin + requests[0].url.pathname).toBe(
useResponsesApi
? 'https://summary-instance.openai.azure.com/openai/v1/responses'
: 'https://summary-instance.openai.azure.com/openai/deployments/user-deployment/chat/completions',
);
expect(requests[0].headers.get('api-key')).toBe('override-key');
expect(requests[0].headers.get('X-Request')).toBe('resolved-user-header');
expect(requests[0].body.model).toBe('user-deployment');
const chatTokenKey = model === 'gpt-6-astra' ? 'max_completion_tokens' : 'max_tokens';
expect(requests[0].body[useResponsesApi ? 'max_output_tokens' : chatTokenKey]).toBe(1536);
expect((agents[0].clientOptions as Record<string, unknown>).configuration).toEqual(
configOptions,
);
},
);
it.each(['root', 'lazy'])(
'retains Azure identity and resolved headers for a %s self-summary',
async (kind) => {
jest.replaceProperty(process, 'env', {
...process.env,
AZURE_API_KEY: 'user_provided',
SUMMARY_HEADER_SECRET: 'must-not-leak',
});
const user = { id: 'user-1', username: '${SUMMARY_HEADER_SECRET}' };
const appConfig = makeAppConfig([]);
appConfig.endpoints!.all = {
headers: {
'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
'X-Tenant': '{{LIBRECHAT_USER_TENANTID}}',
'X-User': '{{LIBRECHAT_USER_USERNAME}}',
},
};
const getUserKeyValues = jest.fn().mockResolvedValue({
apiKey: JSON.stringify({
azureOpenAIApiKey: 'user-key',
azureOpenAIApiInstanceName: 'user-instance',
azureOpenAIApiDeploymentName: 'user-deployment',
azureOpenAIApiVersion: '2024-10-21',
}),
});
const options = await initializeOpenAI({
endpoint: EModelEndpoint.azureOpenAI,
model_parameters: { model: 'gpt-6-astra' },
runtime: { appConfig, user, requestBody: {} },
db: { getUserKeyValues },
} as unknown as Parameters<typeof initializeOpenAI>[0]);
const azureAgent = {
...makeReasoningAgent({
endpoint: EModelEndpoint.azureOpenAI,
provider: Providers.OPENAI,
model: 'gpt-6-astra',
azureOptions: options.azureOptions,
model_parameters: { ...options.llmConfig, configuration: options.configOptions },
}),
id: 'azure-child',
};
const lazyParent = makeAgent({
id: 'parent',
summarization: { enabled: false },
subagents: { enabled: true, allowSelf: false },
lazySubagentConfigs: [
{
id: azureAgent.id,
name: 'Azure child',
description: 'Lazy Azure child',
configId: 'azure-child:1:test',
resolve: jest.fn().mockResolvedValue(azureAgent),
},
],
});
const captured = await callAndCapture({
agents: kind === 'lazy' ? [lazyParent] : [azureAgent],
appConfig,
user: user as IUser,
tenantId: 'tenant-1',
requestBody: { conversationId: 'conversation-1' },
summarizeOnly: true,
summarizationConfig: {
parameters: {
streaming: false,
baseURL:
'https://${INSTANCE_NAME}.openai.azure.com/openai/deployments/${DEPLOYMENT_NAME}',
},
},
});
let selected = captured[0];
if (kind === 'lazy') {
const [child] = captured[0].subagentConfigs as Array<Record<string, unknown>>;
selected = await (
child.resolveAgentInputs as (context: never) => Promise<Record<string, unknown>>
)({ signal: new AbortController().signal } as never);
selected.summarizeOnly = true;
}
const agents = [selected];
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
expect(requests[0].url.origin + requests[0].url.pathname).toBe(
'https://user-instance.openai.azure.com/openai/v1/responses',
);
expect(requests[0].body.model).toBe('user-deployment');
expect(requests[0].headers.get('api-key')).toBe('user-key');
expect(requests[0].headers.get('X-Conversation')).toBe('conversation-1');
expect(requests[0].headers.get('X-Tenant')).toBe('tenant-1');
expect(requests[0].headers.get('X-User')).toBe('${SUMMARY_HEADER_SECRET}');
const mainConfiguration = (agents[0].clientOptions as Record<string, unknown>)
.configuration as OpenAIConfiguration;
expect(new Headers(mainConfiguration?.defaultHeaders as HeadersInit).get('X-User')).toBe(
'${SUMMARY_HEADER_SECRET}',
);
expect(getUserKeyValues).toHaveBeenCalledTimes(1);
},
);
it.each([
{ parameterCap: undefined, expected: 512 },
{ parameterCap: '128', expected: 512 },
{ parameterCap: 0, expected: 512 },
{ parameterCap: 256, expected: 256 },
])(
'honors the summary token cap with parameter cap $parameterCap',
async ({ parameterCap, expected }) => {
const agents = await callAndCapture({
agents: [azureAstraAgent()],
summarizeOnly: true,
summarizationConfig: {
maxSummaryTokens: 512,
parameters: {
streaming: false,
...(parameterCap !== undefined ? { maxSummaryTokens: parameterCap } : {}),
},
},
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
expect(requests[0].body.max_output_tokens).toBe(expected);
expect(requests[0].body.model).toBe('production-deployment');
},
);
it.each([
{ nested: false, useResponsesApi: true },
{ nested: true, useResponsesApi: true },
{ nested: false, useResponsesApi: false },
])(
'normalizes final Azure transport (nested: $nested, Responses: $useResponsesApi)',
async ({ nested, useResponsesApi }) => {
const model = 'gpt-4.1-mini';
const appConfig = makeAppConfig([]);
appConfig.endpoints!.azureOpenAI = {
isValid: true,
errors: [],
modelNames: [model],
modelGroupMap: { [model]: { group: 'summary' } },
groupMap: {
summary: {
apiKey: 'summary-key',
instanceName: 'summary-instance',
version: '2024-10-21',
models: { [model]: { deploymentName: 'summary-production' } },
addParams: { useResponsesApi: !useResponsesApi },
},
},
};
const baseURL =
'https://${INSTANCE_NAME}.openai.azure.com/openai/deployments/${DEPLOYMENT_NAME}?api-version=2025-04-01-preview';
const parameters = {
streaming: false,
useResponsesApi,
...(nested
? { configuration: { baseURL, defaultHeaders: { 'X-Override': 'yes' } } }
: { baseURL }),
} as unknown as SummarizationConfig['parameters'];
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig,
summarizeOnly: true,
summarizationConfig: { model, parameters },
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
expect(requests[0].url.origin + requests[0].url.pathname).toBe(
useResponsesApi
? 'https://summary-instance.openai.azure.com/openai/v1/responses'
: 'https://summary-instance.openai.azure.com/openai/deployments/summary-production/chat/completions',
);
expect(requests[0].headers.get('api-key')).toBe('summary-key');
expect(requests[0].body.model).toBe('summary-production');
if (nested) expect(requests[0].headers.get('X-Override')).toBe('yes');
if (useResponsesApi)
expect(requests[0].url.searchParams.get('api-version')).toBe('2025-04-01-preview');
},
);
it.each([EModelEndpoint.azureOpenAI, EModelEndpoint.openAI])(
'disables an invalid %s summary URL before constructing a run client',
async (provider) => {
jest.replaceProperty(process, 'env', { ...process.env, OPENAI_API_KEY: 'summary-key' });
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig: makeAppConfig([]),
summarizeOnly: true,
summarizationConfig: {
provider,
model: 'gpt-6-astra',
parameters: { streaming: false, baseURL: 'not a URL' },
},
});
expect(agents[0].summarizationEnabled).toBe(false);
const requests: CapturedRequest[] = [];
await expect(compactSummary(agents, requests)).rejects.toThrow(
'Compaction skipped: summarization is not enabled for this agent',
);
expect(requests).toHaveLength(0);
},
);
it('keeps the deployment alias when the summarizer runs the agent model', async () => {
const agents = await callAndCapture({ agents: [azureAstraAgent()] });
const mainClientOptions = agents[0].clientOptions as Record<string, unknown>;
const summaryConfig = agents[0].summarizationConfig as Record<string, unknown>;
expect(summaryConfig.parameters).toBeUndefined();
expect(summaryRequestModel(mainClientOptions, summaryConfig)).toBe('production-deployment');
});
it.each<{
model: string;
deployed: boolean;
proxy?: string;
parameters?: SummarizationConfig['parameters'];
}>([
{ model: 'gpt-4.1-mini', deployed: false, proxy: undefined },
{ model: 'gpt-4.1-mini', deployed: true, proxy: undefined },
{ model: 'gpt-6-astra', deployed: true, proxy: undefined },
{ model: 'gpt-4.1-mini', deployed: false, proxy: 'https://summary-gateway.example/v1' },
{
model: 'gpt-6-astra',
deployed: true,
parameters: { useResponsesApi: false, apiKey: 'override-key' },
},
{
model: 'gpt-4.1-mini',
deployed: false,
parameters: { baseURL: 'https://per-summary.example/v1', useResponsesApi: true },
},
])(
'honors explicit OpenAI for $model (Azure deployed: $deployed, proxy: $proxy)',
async ({ model, deployed, proxy, parameters }) => {
jest.replaceProperty(process, 'env', {
...process.env,
OPENAI_API_KEY: 'openai-summary-key',
OPENAI_REVERSE_PROXY: proxy,
});
const appConfig = makeAppConfig([]);
appConfig.endpoints!.all = { headers: { 'X-Global': 'global' } };
appConfig.endpoints!.openAI = { headers: { 'X-Summary': 'openai' } };
appConfig.endpoints!.azureOpenAI = {
isValid: true,
errors: [],
modelNames: deployed ? [model] : [],
modelGroupMap: deployed ? { [model]: { group: 'azure' } } : {},
groupMap: {
azure: {
apiKey: 'test-azure-key',
instanceName: 'test-instance',
version: '2025-04-01-preview',
models: { [model]: { deploymentName: 'production-deployment' } },
},
},
};
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig,
summarizeOnly: true,
summarizationConfig: {
provider: EModelEndpoint.openAI,
model,
parameters: { streaming: false, ...parameters },
},
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
const { url, headers, body } = requests[0];
const baseURL = parameters?.baseURL ?? proxy;
expect(url.origin).toBe(
typeof baseURL === 'string' ? new URL(baseURL).origin : 'https://api.openai.com',
);
const usesResponses = parameters?.useResponsesApi ?? model === 'gpt-6-astra';
expect(url.pathname).toBe(usesResponses ? '/v1/responses' : '/v1/chat/completions');
expect(url.search).toBe('');
expect(headers.get('authorization')).toBe(
`Bearer ${parameters?.apiKey ?? 'openai-summary-key'}`,
);
expect(headers.has('api-key')).toBe(false);
expect(headers.get('X-Global')).toBe('global');
expect(headers.get('X-Summary')).toBe('openai');
expect(body.model).toBe(model);
expect(body).not.toHaveProperty('max_output_tokens', 2048);
expect((agents[0].clientOptions as OpenAIConfiguration)?.apiKey).toBe('test-azure-key');
},
);
it.each([
{ setting: 'OPENAI_API_KEY', value: undefined, model: 'gpt-4.1-mini' },
{ setting: 'OPENAI_API_KEY', value: 'user_provided', model: 'gpt-4.1-nano' },
{ setting: 'OPENAI_REVERSE_PROXY', value: 'user_provided', model: 'gpt-4o-mini' },
])(
'runs the agent without summarization, not through Azure, when $setting is $value',
async ({ setting, value, model }) => {
jest.replaceProperty(process, 'env', {
...process.env,
OPENAI_API_KEY: 'openai-summary-key',
[setting]: value,
});
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig: makeAppConfig([]),
summarizeOnly: true,
summarizationConfig: {
provider: EModelEndpoint.openAI,
model,
parameters: { streaming: false },
},
});
expect(agents[0].summarizationEnabled).toBe(false);
expect(logger.warn).toHaveBeenCalledWith(
`[createRun] Summarization with OpenAI model "${model}" is disabled for Azure OpenAI agents: it needs a server-configured OpenAI API key and base URL.`,
);
const requests: CapturedRequest[] = [];
await expect(compactSummary(agents, requests)).rejects.toThrow(
'Compaction skipped: summarization is not enabled for this agent',
);
expect(requests).toHaveLength(0);
},
);
it('reports an unreachable OpenAI summarizer once per tenant across runs', async () => {
jest.replaceProperty(process, 'env', { ...process.env, OPENAI_API_KEY: undefined });
const run = (tenantId?: string) =>
callAndCapture({
agents: [azureAstraAgent()],
appConfig: makeAppConfig([]),
tenantId,
summarizationConfig: { provider: EModelEndpoint.openAI, model: 'o4-mini' },
});
for (const tenantId of [undefined, undefined, 'tenant-a', 'tenant-a', 'tenant-b']) {
(Run.create as jest.Mock).mockClear();
await run(tenantId);
}
const warnings = (logger.warn as jest.Mock).mock.calls.filter(([message]) =>
String(message).includes('"o4-mini"'),
);
expect(warnings.map(([, meta]) => meta)).toEqual([
undefined,
{ tenantId: 'tenant-a' },
{ tenantId: 'tenant-b' },
]);
});
it('expands environment placeholders in OpenAI and Azure summarizer credentials', async () => {
jest.replaceProperty(process, 'env', {
...process.env,
OPENAI_API_KEY: 'openai-summary-key',
SUMMARY_OPENAI_KEY: 'expanded-openai-key',
SUMMARY_OPENAI_URL: 'https://expanded-gateway.example/v1',
SUMMARY_AZURE_KEY: 'expanded-azure-key',
});
const appConfig = makeAppConfig([]);
appConfig.endpoints![EModelEndpoint.azureOpenAI] = {
isValid: true,
errors: [],
modelNames: ['gpt-6-astra', 'gpt-4.1-mini'],
modelGroupMap: { 'gpt-6-astra': { group: 'main' }, 'gpt-4.1-mini': { group: 'summary' } },
groupMap: {
main: {
apiKey: 'test-azure-key',
instanceName: 'test-instance',
version: '2025-04-01-preview',
models: { 'gpt-6-astra': { deploymentName: 'production-deployment' } },
},
summary: {
apiKey: 'summary-key',
instanceName: 'summary-instance',
version: '2024-10-21',
models: { 'gpt-4.1-mini': { deploymentName: 'summary-production' } },
},
},
};
const compact = async (summarizationConfig: SummarizationConfig) => {
(Run.create as jest.Mock).mockClear();
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig,
summarizeOnly: true,
summarizationConfig,
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
return requests[0];
};
const openAI = await compact({
provider: EModelEndpoint.openAI,
model: 'gpt-4.1-mini',
parameters: {
streaming: false,
apiKey: '${SUMMARY_OPENAI_KEY}',
baseURL: '${SUMMARY_OPENAI_URL}',
},
});
expect(openAI.url.origin).toBe('https://expanded-gateway.example');
expect(openAI.headers.get('authorization')).toBe('Bearer expanded-openai-key');
const azure = await compact({
model: 'gpt-4.1-mini',
parameters: { streaming: false, apiKey: '${SUMMARY_AZURE_KEY}' },
});
expect(azure.url.origin).toBe('https://summary-instance.openai.azure.com');
expect(azure.headers.get('api-key')).toBe('expanded-azure-key');
});
it("leaves Azure's reserved URL templates to the summary deployment", async () => {
jest.replaceProperty(process, 'env', {
...process.env,
INSTANCE_NAME: 'host-instance',
DEPLOYMENT_NAME: 'host-deployment',
SUMMARY_GATEWAY_PATH: 'openai',
});
const appConfig = makeAppConfig([]);
appConfig.endpoints![EModelEndpoint.azureOpenAI] = {
isValid: true,
errors: [],
modelNames: ['gpt-6-astra', 'gpt-4.1-mini'],
modelGroupMap: { 'gpt-6-astra': { group: 'main' }, 'gpt-4.1-mini': { group: 'summary' } },
groupMap: {
main: {
apiKey: 'test-azure-key',
instanceName: 'test-instance',
version: '2025-04-01-preview',
models: { 'gpt-6-astra': { deploymentName: 'production-deployment' } },
},
summary: {
apiKey: 'summary-key',
instanceName: 'summary-instance',
version: '2024-10-21',
models: { 'gpt-4.1-mini': { deploymentName: 'summary-production' } },
},
},
};
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig,
summarizeOnly: true,
summarizationConfig: {
model: 'gpt-4.1-mini',
parameters: {
streaming: false,
baseURL:
'https://${INSTANCE_NAME}.openai.azure.com/${SUMMARY_GATEWAY_PATH}/deployments/${DEPLOYMENT_NAME}',
},
},
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
const { url } = requests[0];
expect(url.origin + url.pathname).toBe(
'https://summary-instance.openai.azure.com/openai/deployments/summary-production/chat/completions',
);
});
it('expands Azure-reserved names as ordinary variables for an OpenAI summarizer', async () => {
jest.replaceProperty(process, 'env', {
...process.env,
OPENAI_API_KEY: 'openai-summary-key',
INSTANCE_NAME: 'gateway-host',
});
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig: makeAppConfig([]),
summarizeOnly: true,
summarizationConfig: {
provider: EModelEndpoint.openAI,
model: 'gpt-4.1-mini',
parameters: { streaming: false, baseURL: 'https://${INSTANCE_NAME}.example/v1' },
},
});
expect(agents[0].summarizationEnabled).toBe(true);
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
expect(requests[0].url.origin).toBe('https://gateway-host.example');
});
it('disables summarization when a credential placeholder has no environment value', async () => {
jest.replaceProperty(process, 'env', { ...process.env, OPENAI_API_KEY: 'openai-summary-key' });
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig: makeAppConfig([]),
summarizeOnly: true,
summarizationConfig: {
provider: EModelEndpoint.openAI,
model: 'gpt-4.1',
parameters: { streaming: false, apiKey: '${UNSET_SUMMARY_KEY}' },
},
});
expect(agents[0].summarizationEnabled).toBe(false);
const requests: CapturedRequest[] = [];
await expect(compactSummary(agents, requests)).rejects.toThrow(
'Compaction skipped: summarization is not enabled for this agent',
);
expect(requests).toHaveLength(0);
});
it.each([
{
name: 'an inherited summary model absent from the Azure map',
agent: () => azureAstraAgent(),
summarizationConfig: { model: 'gpt-5.4-nano' },
env: {},
reason: 'Model named "gpt-5.4-nano" not found in configuration.',
},
{
name: 'an explicit Azure summary model absent from the map on a non-Azure agent',
agent: () => makeAgent(),
summarizationConfig: { provider: EModelEndpoint.azureOpenAI, model: 'gpt-5.4-mini' },
env: {},
reason: 'Model named "gpt-5.4-mini" not found in configuration.',
},
{
name: 'a mapped summary group whose base URL is user-provided',
agent: () => azureAstraAgent(),
summarizationConfig: { model: 'gpt-4.1' },
env: { AZURE_OPENAI_BASEURL: 'user_provided' },
reason: 'it needs a server-configured Azure OpenAI API key and base URL.',
},
{
name: 'a mapped summary group with an empty API key',
agent: () => azureAstraAgent(),
summarizationConfig: { model: 'gpt-4.1-nano' },
env: {},
summaryApiKey: '',
reason: 'it needs a server-configured Azure OpenAI API key and base URL.',
},
{
name: 'a legacy Azure environment whose key is user-provided',
agent: () => azureAstraAgent(),
summarizationConfig: { model: 'gpt-4o' },
env: { AZURE_API_KEY: 'user_provided' },
legacyEnvironment: true,
reason: 'it needs a server-configured Azure OpenAI API key and base URL.',
},
])('disables summarization for $name', async (target) => {
const { agent, summarizationConfig, env, reason } = target;
jest.replaceProperty(process, 'env', { ...process.env, ...env });
const appConfig = makeAppConfig([]);
appConfig.endpoints![EModelEndpoint.azureOpenAI] = target.legacyEnvironment
? undefined
: {
isValid: true,
errors: [],
modelNames: ['gpt-6-astra', 'gpt-4.1', 'gpt-4.1-nano'],
modelGroupMap: {
'gpt-6-astra': { group: 'main' },
'gpt-4.1': { group: 'summary' },
'gpt-4.1-nano': { group: 'summary' },
},
groupMap: {
main: {
apiKey: 'test-azure-key',
instanceName: 'test-instance',
version: '2025-04-01-preview',
models: { 'gpt-6-astra': { deploymentName: 'production-deployment' } },
},
summary: {
apiKey: target.summaryApiKey ?? 'summary-key',
instanceName: 'summary-instance',
version: '2024-10-21',
models: {
'gpt-4.1': { deploymentName: 'summary-production' },
'gpt-4.1-nano': { deploymentName: 'summary-nano' },
},
},
},
};
const agents = await callAndCapture({
agents: [agent()],
appConfig,
summarizeOnly: true,
summarizationConfig: { ...summarizationConfig, parameters: { streaming: false } },
});
expect(agents[0].summarizationEnabled).toBe(false);
expect(logger.warn).toHaveBeenCalledWith(
`[createRun] Summarization with Azure OpenAI model "${summarizationConfig.model}" is disabled: ${reason}`,
);
const requests: CapturedRequest[] = [];
await expect(compactSummary(agents, requests)).rejects.toThrow(
'Compaction skipped: summarization is not enabled for this agent',
);
expect(requests).toHaveLength(0);
});
it("sends a summary deployment to its own resource when only the agent's group sets a base URL", async () => {
const agentBaseURL =
'https://agent-instance.openai.azure.com/openai/deployments/${DEPLOYMENT_NAME}';
const appConfig = makeAppConfig([]);
appConfig.endpoints![EModelEndpoint.azureOpenAI] = {
isValid: true,
errors: [],
modelNames: ['gpt-4.1', 'gpt-4.1-mini'],
modelGroupMap: { 'gpt-4.1': { group: 'main' }, 'gpt-4.1-mini': { group: 'summary' } },
groupMap: {
main: {
apiKey: 'test-azure-key',
instanceName: 'agent-instance',
baseURL: agentBaseURL,
version: '2024-10-21',
models: { 'gpt-4.1': { deploymentName: 'agent-deployment' } },
},
summary: {
apiKey: 'summary-key',
instanceName: 'summary-instance',
version: '2024-10-21',
models: { 'gpt-4.1-mini': { deploymentName: 'summary-production' } },
},
},
};
const { llmConfig, configOptions } = getOpenAIConfig(
'test-azure-key',
{
reverseProxyUrl: agentBaseURL,
azure: {
azureOpenAIApiInstanceName: 'agent-instance',
azureOpenAIApiDeploymentName: 'agent-deployment',
azureOpenAIApiVersion: '2024-10-21',
azureOpenAIApiKey: 'test-azure-key',
},
modelOptions: { model: 'gpt-4.1' },
},
EModelEndpoint.azureOpenAI,
);
const agents = await callAndCapture({
agents: [
makeReasoningAgent({
provider: EModelEndpoint.azureOpenAI,
endpoint: EModelEndpoint.azureOpenAI,
model: 'gpt-4.1',
model_parameters: { ...llmConfig, configuration: configOptions },
}),
],
appConfig,
summarizeOnly: true,
summarizationConfig: { model: 'gpt-4.1-mini', parameters: { streaming: false } },
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
const { url, headers, body } = requests[0];
expect(url.origin + url.pathname).toBe(
'https://summary-instance.openai.azure.com/openai/deployments/summary-production/chat/completions',
);
expect(headers.get('api-key')).toBe('summary-key');
expect(body.model).toBe('summary-production');
});
it('sends no empty api-version to a serverless summary group without a version', async () => {
const appConfig = makeAppConfig([]);
appConfig.endpoints![EModelEndpoint.azureOpenAI] = {
isValid: true,
errors: [],
modelNames: ['gpt-6-astra', 'Phi-4'],
modelGroupMap: { 'gpt-6-astra': { group: 'main' }, 'Phi-4': { group: 'serverless' } },
groupMap: {
main: {
apiKey: 'test-azure-key',
instanceName: 'test-instance',
version: '2025-04-01-preview',
models: { 'gpt-6-astra': { deploymentName: 'production-deployment' } },
},
serverless: {
apiKey: 'serverless-key',
baseURL: 'https://phi-instance.services.ai.azure.com/models',
serverless: true,
models: { 'Phi-4': true },
},
},
};
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig,
summarizeOnly: true,
summarizationConfig: { model: 'Phi-4', parameters: { streaming: false } },
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
const { url, headers } = requests[0];
expect(url.origin + url.pathname).toBe(
'https://phi-instance.services.ai.azure.com/models/chat/completions',
);
expect(url.search).toBe('');
expect(headers.get('api-key')).toBe('serverless-key');
});
it.each([
{ summaryModel: 'gpt-4.1-mini', instance: 'test-instance', provider: undefined },
{
summaryModel: 'gpt-4.1-mini',
instance: 'summary-instance',
provider: EModelEndpoint.azureOpenAI,
},
{ summaryModel: 'gpt-6-astra-2026-09-03', instance: 'summary-instance', provider: undefined },
])(
'compacts with $summaryModel on $instance using its configured deployment',
async ({ summaryModel, instance, provider }) => {
const appConfig = makeAppConfig([]);
appConfig.endpoints![EModelEndpoint.azureOpenAI] = {
isValid: true,
errors: [],
modelNames: ['gpt-6-astra', summaryModel],
modelGroupMap: { 'gpt-6-astra': { group: 'main' }, [summaryModel]: { group: 'summary' } },
groupMap: {
main: {
apiKey: 'test-azure-key',
instanceName: 'test-instance',
version: '2025-04-01-preview',
models: { 'gpt-6-astra': { deploymentName: 'production-deployment' } },
},
summary: {
apiKey: 'summary-key',
instanceName: instance,
baseURL: `https://${instance}.openai.azure.com`,
version: '2025-04-01-preview',
additionalHeaders: { 'X-Summary-Group': 'summary' },
models: { [summaryModel]: { deploymentName: 'summary-production' } },
},
},
};
const agents = await callAndCapture({
agents: [azureAstraAgent()],
appConfig,
summarizeOnly: true,
summarizationConfig: { model: summaryModel, provider, parameters: { streaming: false } },
});
const { requests } = await compactSummary(agents);
expect(requests).toHaveLength(1);
const { url, headers, body } = requests[0];
const usesResponses = summaryModel.startsWith('gpt-6-astra');
expect(url.origin).toBe(`https://${instance}.openai.azure.com`);
expect(url.pathname).toBe(
usesResponses
? '/openai/v1/responses'
: '/openai/deployments/summary-production/chat/completions',
);
expect(headers.get('api-key')).toBe('summary-key');
expect(headers.get('X-Summary-Group')).toBe('summary');
expect(body.model).toBe('summary-production');
expect(body).not.toHaveProperty('max_output_tokens', 2048);
expect((agents[0].clientOptions as OpenAIConfiguration)?.apiKey).toBe('test-azure-key');
},
);
});
// ---------------------------------------------------------------------------
// Suite 5: Multi-agent + per-agent overrides
// ---------------------------------------------------------------------------
describe('multi-agent + per-agent overrides', () => {
it('normalizes missing persisted edges before creating the SDK graph', async () => {
await createRun({
agents: [makeAgent({ id: 'agent_1' }), makeAgent({ id: 'agent_2' })] as never,
signal: new AbortController().signal,
streaming: true,
streamUsage: true,
});
const createMock = Run.create as jest.Mock;
const runConfig = createMock.mock.calls[0][0] as {
graphConfig: { type: string; edges: unknown[] };
};
expect(runConfig.graphConfig).toMatchObject({
type: 'multi-agent',
edges: [],
});
});
it('different agents get different effectiveMaxContextTokens', async () => {
const agents = await callAndCapture({
agents: [
makeAgent({ id: 'agent_1', baseContextTokens: 200_000, maxContextTokens: 100_000 }),
makeAgent({ id: 'agent_2', baseContextTokens: 100_000, maxContextTokens: 50_000 }),
],
summarizationConfig: {
reserveRatio: 0.1,
provider: 'anthropic',
model: 'claude',
},
});
// agent_1: Math.round(200000 * 0.9) = 180000, but capped at user's maxContextTokens (100000)
expect(agents[0].maxContextTokens).toBe(100_000);
// agent_2: Math.round(100000 * 0.9) = 90000, but capped at user's maxContextTokens (50000)
expect(agents[1].maxContextTokens).toBe(50_000);
});
});
// ---------------------------------------------------------------------------
// Suite 6: initialSummary passthrough
// ---------------------------------------------------------------------------
describe('initialSummary passthrough', () => {
it('forwarded to agent inputs', async () => {
const summary = { text: 'Previous conversation summary', tokenCount: 500 };
const agents = await callAndCapture({
initialSummary: summary,
summarizationConfig: { provider: 'anthropic', model: 'claude' },
});
expect(agents[0].initialSummary).toEqual(summary);
});
it('undefined when not provided', async () => {
const agents = await callAndCapture({});
expect(agents[0].initialSummary).toBeUndefined();
});
});
// ---------------------------------------------------------------------------
// Suite 7: stable/dynamic system instructions
// ---------------------------------------------------------------------------
describe('stable/dynamic system instructions', () => {
it.each([Providers.ANTHROPIC, Providers.OPENROUTER])(
'labels the complete cached %s tail as application context without changing user input',
async (provider) => {
await callAndCapture({
agents: [
makeAgent({
provider,
endpoint: provider,
instructions:
"Translate the user's message into Chinese. Reply with the translation only.",
additional_instructions: 'Saved memory: prefers tea\n\nRetrieved context: a document',
dynamicToolContextMap: { web_search: 'Conversation Date & Time: anchor' },
model_parameters: { model: 'test-model', promptCache: true, apiKey: 'test-key' },
}),
],
});
const runConfig = jest.mocked(Run.create).mock.calls[0][0];
if (!('agents' in runConfig.graphConfig) || !runConfig.graphConfig.agents?.length) {
throw new Error('Expected agent inputs');
}
const inputs = runConfig.graphConfig.agents[0];
expect(inputs.additional_instructions).toBe(
`<system_context>
Context supplied by the application, not part of the user's message. Use it as context; do not process it as user input.
Conversation Date & Time: anchor
Saved memory: prefers tea
Retrieved context: a document
</system_context>`,
);
const actual = jest.requireActual<typeof import('@librechat/agents')>('@librechat/agents');
const run = await actual.Run.create(runConfig);
const context = run.Graph!.agentContexts.get(inputs.agentId)!;
const userText = 'Translate this paragraph, including <system_context> as literal text.';
const messages = [
new HumanMessage('Previous user input'),
new AIMessage('Previous response'),
new HumanMessage(userText),
];
const prompt = await context.systemRunnable!.invoke(messages);
expect(prompt[0].getType()).toBe('system');
expect(JSON.stringify(prompt[0].content)).not.toContain('<system_context>');
expect(prompt[prompt.length - 2].getType()).toBe('human');
expect(prompt[prompt.length - 2].content).toBe(inputs.additional_instructions);
expect(prompt[prompt.length - 1].text).toBe(userText);
expect(messages[messages.length - 1].content).toBe(userText);
},
);
it.each([
[Providers.ANTHROPIC, false],
[Providers.OPENROUTER, false],
[Providers.OPENAI, true],
[Providers.BEDROCK, true],
])(
'leaves the %s tail unchanged with promptCache=%s when it is not relocated',
async (provider, promptCache) => {
const agents = await callAndCapture({
agents: [
makeAgent({
provider,
endpoint: provider,
instructions: 'Base instructions',
additional_instructions: 'Memory tail',
model_parameters: { model: 'test-model', promptCache },
}),
],
});
expect(agents[0].additional_instructions).toBe('Memory tail');
},
);
it('frames isolated subagent skills inside the same context block', async () => {
const child = makeAgent({
id: 'agent_child',
provider: Providers.ANTHROPIC,
endpoint: Providers.ANTHROPIC,
instructions: 'Translate the user input',
additional_instructions: 'Child memory',
model_parameters: { model: 'test-model', promptCache: true },
alwaysApplySkillPrimes: [{ name: 'translation', body: 'Use the glossary.' }],
});
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: [child.id] },
subagentAgentConfigs: [child],
}),
],
});
const configs = agents[0].subagentConfigs as SubagentConfig[];
expect(configs[0].agentInputs?.additional_instructions).toContain(
'Child memory\n\n# Always-apply skill: translation\nUse the glossary.\n</system_context>',
);
expect(
configs[0].agentInputs?.additional_instructions?.match(/<system_context>/g),
).toHaveLength(1);
expect(child.additional_instructions).toBe('Child memory');
});
it('does not add a context carrier for an empty cached tail', async () => {
const agents = await callAndCapture({
agents: [
makeAgent({
provider: Providers.ANTHROPIC,
endpoint: Providers.ANTHROPIC,
instructions: 'Translate the user input',
model_parameters: { model: 'test-model', promptCache: true },
}),
],
});
expect(agents[0].additional_instructions).toBeUndefined();
});
it('keeps static tool and agent instructions separate from dynamic runtime tail', async () => {
const agents = await callAndCapture({
agents: [
makeAgent({
instructions: 'Base instructions',
additional_instructions: 'Memory tail',
toolContextMap: { web_search: 'Static tool instructions' },
dynamicToolContextMap: { web_search: 'Conversation Date & Time: anchor' },
}),
],
});
expect(agents[0].instructions).toBe('Static tool instructions\nBase instructions');
expect(agents[0].additional_instructions).toBe('Conversation Date & Time: anchor\nMemory tail');
});
});
// ---------------------------------------------------------------------------
// Suite 8: custom-endpoint provider resolution
// ---------------------------------------------------------------------------
describe('custom-endpoint provider resolution', () => {
it('remaps a custom endpoint name to openAI and injects baseURL/apiKey', async () => {
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('openAI');
expect(config.model).toBe('llama3');
const parameters = config.parameters as Record<string, unknown>;
expect(parameters).toMatchObject({
configuration: { baseURL: 'http://localhost:11434/v1' },
apiKey: 'ollama-key',
});
});
it('matches Ollama case-insensitively (via normalizeEndpointName)', async () => {
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('openAI');
expect((config.parameters as Record<string, unknown>).apiKey).toBe('ollama-key');
});
it('resolves non-Ollama endpoints on exact-case match', async () => {
const appConfig = makeAppConfig([
{ name: 'Together', baseURL: 'https://api.together.ai/v1', apiKey: 'together-key' },
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Together', model: 'mixtral' },
appConfig,
});
expect((agents[0].summarizationConfig as Record<string, unknown>).provider).toBe('openAI');
});
it('does not match non-Ollama endpoints with different casing', async () => {
const appConfig = makeAppConfig([
{ name: 'Together', baseURL: 'https://api.together.ai/v1', apiKey: 'together-key' },
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'together', model: 'mixtral' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('together');
expect(config.parameters).toBeUndefined();
});
it('leaves known SDK providers untouched', async () => {
const appConfig = makeAppConfig([]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'anthropic', model: 'claude' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('anthropic');
expect(config.parameters).toBeUndefined();
});
it('preserves unknown provider names when appConfig is missing', async () => {
const agents = await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('Ollama');
expect(config.parameters).toBeUndefined();
});
it('leaves unrecognized names untouched when no matching custom endpoint exists', async () => {
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'nonexistent', model: 'foo' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('nonexistent');
expect(config.parameters).toBeUndefined();
});
it('extracts ${ENV_VAR} references in custom endpoint credentials', async () => {
process.env.TEST_OLLAMA_KEY = 'resolved-key-value';
try {
const appConfig = makeAppConfig([
{
name: 'Ollama',
baseURL: 'http://localhost:11434/v1',
apiKey: '${TEST_OLLAMA_KEY}',
},
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const parameters = config.parameters as Record<string, unknown>;
expect(parameters.apiKey).toBe('resolved-key-value');
} finally {
delete process.env.TEST_OLLAMA_KEY;
}
});
it('keeps raw provider when apiKey is marked user_provided', async () => {
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'user_provided' },
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
/**
* Keep the raw name so the SDK raises "Unsupported LLM provider: Ollama"
* rather than silently remapping to `openAI` and routing summaries to the
* default backend. (User-provided creds cannot be resolved here — the
* async DB lookup is out of scope for this synchronous code path.)
*/
expect(config.provider).toBe('Ollama');
expect(config.parameters).toBeUndefined();
});
it('keeps raw provider when env var reference cannot be resolved', async () => {
delete process.env.UNSET_TEST_KEY;
const appConfig = makeAppConfig([
{
name: 'Ollama',
baseURL: 'http://localhost:11434/v1',
apiKey: '${UNSET_TEST_KEY}',
},
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('Ollama');
expect(config.parameters).toBeUndefined();
});
it('keeps raw provider when partial env var reference (prefix/suffix) stays unresolved', async () => {
delete process.env.UNSET_TEST_SEGMENT;
const appConfig = makeAppConfig([
{
name: 'Ollama',
baseURL: 'https://${UNSET_TEST_SEGMENT}.example.com/v1',
apiKey: 'ollama-key',
},
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('Ollama');
/** Even though the baseURL is a partial-match pattern, it must not be forwarded. */
expect(config.parameters).toBeUndefined();
});
it('merges overrides alongside user-supplied parameters', async () => {
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const agents = await callAndCapture({
summarizationConfig: {
provider: 'Ollama',
model: 'llama3',
parameters: { temperature: 0.2 },
},
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const parameters = config.parameters as Record<string, unknown>;
expect(parameters).toMatchObject({
temperature: 0.2,
apiKey: 'ollama-key',
});
const configuration = parameters.configuration as Record<string, unknown>;
expect(configuration.baseURL).toBe('http://localhost:11434/v1');
});
it('forwards custom-endpoint headers as configuration.defaultHeaders', async () => {
const appConfig = makeAppConfig([
{
name: 'Ollama',
baseURL: 'http://localhost:11434/v1',
apiKey: 'ollama-key',
headers: { 'X-Custom-Header': 'value-123' },
},
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const parameters = config.parameters as Record<string, unknown>;
const configuration = parameters.configuration as Record<string, unknown>;
const defaultHeaders = configuration.defaultHeaders as Record<string, string>;
expect(defaultHeaders['X-Custom-Header']).toBe('value-123');
});
it('runs custom-endpoint headers through resolveHeaders (not forwarded raw)', async () => {
const { resolveHeaders } = jest.requireMock('~/utils/env') as {
resolveHeaders: jest.Mock;
};
resolveHeaders.mockClear();
const appConfig = makeAppConfig([
{
name: 'Ollama',
baseURL: 'http://localhost:11434/v1',
apiKey: 'ollama-key',
headers: { Authorization: 'Bearer ${TEST_PORTKEY_KEY}' },
},
]);
await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
/**
* Templated header values must go through the same `resolveHeaders`
* pipeline the main agent flow uses, so `${VAR}`/`{{BODY_FIELD}}`
* references don't get forwarded verbatim to the summarization backend.
*/
const call = resolveHeaders.mock.calls.find(
(args: unknown[]) =>
(args[0] as { headers?: Record<string, string> }).headers?.Authorization ===
'Bearer ${TEST_PORTKEY_KEY}',
);
expect(call).toBeDefined();
});
it('uses the authoritative run tenant in custom-endpoint summarization headers', async () => {
const appConfig = makeAppConfig([
{
name: 'Tenant Gateway',
baseURL: 'https://gateway.example.com/v1',
apiKey: 'gateway-key',
headers: { 'X-Tenant-ID': '{{LIBRECHAT_USER_TENANT_ID}}' },
},
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Tenant Gateway', model: 'summary-model' },
appConfig,
user: { id: 'user-1', tenantId: 'stale-user-tenant' } as IUser,
tenantId: 'request-tenant',
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const parameters = config.parameters as Record<string, unknown>;
const configuration = parameters.configuration as Record<string, unknown>;
expect(configuration.defaultHeaders).toEqual({ 'X-Tenant-ID': 'request-tenant' });
});
it('forwards PROXY env var into summarization client configuration', async () => {
const originalProxy = process.env.PROXY;
process.env.PROXY = 'http://proxy.internal:3128';
try {
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const parameters = config.parameters as Record<string, unknown>;
const configuration = parameters.configuration as Record<string, unknown>;
/** getOpenAIConfig wires proxy through to fetchOptions.dispatcher (undici ProxyAgent). */
expect(configuration.fetchOptions).toBeDefined();
} finally {
if (originalProxy === undefined) {
delete process.env.PROXY;
} else {
process.env.PROXY = originalProxy;
}
}
});
it('skips overrides when summarization targets the same endpoint as the agent', async () => {
/**
* When summarization provider matches the agent's endpoint, we rely on
* the SDK's self-summarize path (which reuses agentContext.clientOptions).
* Overriding here would shallow-replace the agent's resolved configuration
* (dynamic headers, proxy/fetch options) with yaml-only config.
*/
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const agents = await callAndCapture({
agents: [makeAgent({ provider: 'openAI', endpoint: 'Ollama' })],
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.provider).toBe('openAI');
/** No overrides injected — SDK will pull from agentContext.clientOptions. */
expect(config.parameters).toBeUndefined();
});
it('skips overrides when endpoints differ only by case for Ollama', async () => {
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const agents = await callAndCapture({
agents: [makeAgent({ provider: 'openAI', endpoint: 'Ollama' })],
summarizationConfig: { provider: 'ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.parameters).toBeUndefined();
});
it('applies overrides when summarization targets a different endpoint than the agent', async () => {
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
{ name: 'Together', baseURL: 'https://api.together.ai/v1', apiKey: 'together-key' },
]);
const agents = await callAndCapture({
agents: [makeAgent({ provider: 'openAI', endpoint: 'Ollama' })],
summarizationConfig: { provider: 'Together', model: 'mixtral' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const parameters = config.parameters as Record<string, unknown>;
expect(parameters.apiKey).toBe('together-key');
expect((parameters.configuration as Record<string, unknown>).baseURL).toBe(
'https://api.together.ai/v1',
);
});
it('deep-merges user configuration with endpoint-resolved configuration', async () => {
/**
* User-supplied `parameters.configuration.defaultQuery` must merge with —
* not replace — the resolved `configuration` (baseURL, defaultHeaders).
*/
const appConfig = makeAppConfig([
{
name: 'Ollama',
baseURL: 'http://localhost:11434/v1',
apiKey: 'ollama-key',
headers: { 'X-Required-Header': 'keep-me' },
},
]);
const parameters: TestSummarizationParameters = {
configuration: { defaultQuery: { 'api-version': '2024-06-01' } },
};
const agents = await callAndCapture({
summarizationConfig: {
provider: 'Ollama',
model: 'llama3',
parameters: parameters as SummarizationConfig['parameters'],
},
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const resolvedParameters = config.parameters as Record<string, unknown>;
const configuration = resolvedParameters.configuration as Record<string, unknown>;
/** Endpoint defaults preserved... */
expect(configuration.baseURL).toBe('http://localhost:11434/v1');
expect((configuration.defaultHeaders as Record<string, string>)['X-Required-Header']).toBe(
'keep-me',
);
/** ...alongside the user's additions. */
expect(configuration.defaultQuery).toEqual({ 'api-version': '2024-06-01' });
});
it('user-supplied configuration.baseURL overrides resolved baseURL', async () => {
/**
* Deep-merge still lets user keys win on conflict — if a user explicitly
* sets `configuration.baseURL` in their summarization parameters, it
* must override the baseURL resolved from the endpoint config.
*/
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const parameters: TestSummarizationParameters = {
configuration: { baseURL: 'https://user-override.example.com/v1' },
};
const agents = await callAndCapture({
summarizationConfig: {
provider: 'Ollama',
model: 'llama3',
parameters: parameters as SummarizationConfig['parameters'],
},
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const resolvedParameters = config.parameters as Record<string, unknown>;
const configuration = resolvedParameters.configuration as Record<string, unknown>;
expect(configuration.baseURL).toBe('https://user-override.example.com/v1');
});
it('user-supplied summarization.parameters override endpoint defaults', async () => {
/**
* `getOpenAIConfig` defaults `streaming: true`, but a user who sets
* `summarization.parameters.streaming: false` in their config has
* explicitly opted out; the user's setting must win over endpoint
* defaults injected from the custom endpoint config.
*/
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const agents = await callAndCapture({
summarizationConfig: {
provider: 'Ollama',
model: 'llama3',
parameters: { streaming: false },
},
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
const parameters = config.parameters as Record<string, unknown>;
expect(parameters.streaming).toBe(false);
/** Endpoint defaults still injected for the rest. */
expect(parameters.apiKey).toBe('ollama-key');
});
it('does not leak model/modelName from getOpenAIConfig defaults', async () => {
const appConfig = makeAppConfig([
{ name: 'Ollama', baseURL: 'http://localhost:11434/v1', apiKey: 'ollama-key' },
]);
const agents = await callAndCapture({
summarizationConfig: { provider: 'Ollama', model: 'llama3' },
appConfig,
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.model).toBe('llama3');
const parameters = config.parameters as Record<string, unknown>;
/** Summarization.model must win — parameters must not carry a stale model/modelName. */
expect(parameters.model).toBeUndefined();
expect(parameters.modelName).toBeUndefined();
});
});
// ---------------------------------------------------------------------------
// Suite: built-in provider request shaping (#15598)
// ---------------------------------------------------------------------------
/**
* A built-in provider produces no custom-endpoint config, so `getOpenAIConfig`
* was skipped entirely and the summarizer learned neither which API its model
* takes nor whether its endpoint is first-party. The agents SDK defaults its
* model-specific constraints off without that declaration, so configured
* parameters reached the model unshaped.
*
* These assert the declaration LibreChat emits, which is the half it owns; the
* SDK's honoring of it is covered by its own tests.
*/
describe('built-in provider request shaping', () => {
const anthropicAgent = () =>
makeAgent({
provider: 'anthropic',
endpoint: 'anthropic',
model: 'claude-sonnet-4.6',
model_parameters: { model: 'claude-sonnet-4.6' },
});
const summarizeWith = async (
parameters?: Record<string, unknown>,
model = 'gpt-6-astra',
appConfig = makeAppConfig([]),
): Promise<Record<string, unknown>> => {
const agents = await callAndCapture({
agents: [anthropicAgent()],
appConfig,
summarizationConfig: {
provider: 'openAI',
model,
parameters: parameters as SummarizationConfig['parameters'],
},
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
return config.parameters as Record<string, unknown>;
};
it('declares the first-party endpoint for a cross-provider built-in summarizer', async () => {
expect(await summarizeWith(undefined, 'gpt-4o')).toMatchObject({ firstPartyEndpoint: true });
});
it('routes a Responses-only model to the Responses API', async () => {
expect(await summarizeWith()).toMatchObject({
firstPartyEndpoint: true,
useResponsesApi: true,
});
});
it('keeps the declaration alongside a translated reasoning effort', async () => {
/**
* The reachable failure from #15598: `resolveReasoningParams` translates the
* scalar effort for the summarizer, and without the declaration an effort
* the model rejects reached it verbatim.
*/
expect(await summarizeWith({ reasoning_effort: 'minimal' })).toMatchObject({
firstPartyEndpoint: true,
reasoning: { effort: 'minimal' },
});
});
it('does not claim a first-party endpoint behind a user configuration.baseURL', async () => {
const parameters = await summarizeWith({
configuration: { baseURL: 'https://gateway.internal/v1' },
});
expect(parameters.firstPartyEndpoint).toBeUndefined();
expect(parameters.configuration).toMatchObject({
baseURL: 'https://gateway.internal/v1',
fetchOptions: { dispatcher: expect.any(Object) },
});
});
it('does not claim a first-party endpoint behind a user baseURL', async () => {
expect(await summarizeWith({ baseURL: 'https://gateway.internal/v1' })).toEqual({
baseURL: 'https://gateway.internal/v1',
configuration: { fetchOptions: { dispatcher: expect.any(Object) } },
});
});
it('adds only transport policy while leaving credentials and model selection to the client', async () => {
const parameters = await summarizeWith();
expect(parameters.apiKey).toBeUndefined();
expect(parameters.model).toBeUndefined();
expect(parameters.modelName).toBeUndefined();
expect(parameters.streaming).toBeUndefined();
expect(parameters.configuration).toEqual({
fetchOptions: { dispatcher: expect.any(Object) },
});
});
it.each([
{ bodyTimeout: 900_000, headersTimeout: 300_000 },
{ bodyTimeout: 1_800_000, headersTimeout: 120_000 },
{ bodyTimeout: 0, headersTimeout: 0 },
])('forwards the cross-provider timeout policy %j', async (transportTimeouts) => {
const appConfig = makeAppConfig([]);
appConfig.endpoints!.agents = {
modelResponseBodyTimeoutMs: transportTimeouts.bodyTimeout,
modelResponseHeadersTimeoutMs: transportTimeouts.headersTimeout,
};
const parameters = await summarizeWith(undefined, 'gpt-4o', appConfig);
const expected = getOpenAIConfig('unused', { transportTimeouts });
const configuration = parameters.configuration as NonNullable<OpenAIConfiguration>;
expect(configuration.fetchOptions?.dispatcher).toBe(
expected.configOptions?.fetchOptions?.dispatcher,
);
});
it('leaves a same-endpoint summarizer on the agent client options', async () => {
const agents = await callAndCapture({
appConfig: makeAppConfig([]),
summarizationConfig: { provider: 'openAI', model: 'gpt-6-astra' },
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.parameters).toBeUndefined();
});
it('routes a reasoning model the way the agent flow would', async () => {
/** `getOpenAIConfig` reads the effort from modelOptions, not from the merged
* parameters, so it has to be handed the summarizer's own effort. */
expect(await summarizeWith({ reasoning_effort: 'medium' }, 'gpt-5.6')).toMatchObject({
firstPartyEndpoint: true,
useResponsesApi: true,
reasoning: { effort: 'medium' },
});
});
it('withholds the declaration when a reverse proxy serves the built-in endpoint', async () => {
process.env.OPENAI_REVERSE_PROXY = 'https://gateway.internal/v1';
try {
expect(await summarizeWith()).toEqual({
configuration: { fetchOptions: { dispatcher: expect.any(Object) } },
});
} finally {
delete process.env.OPENAI_REVERSE_PROXY;
}
});
it('withholds the declaration when the base URL is user-provided', async () => {
process.env.OPENAI_REVERSE_PROXY = 'user_provided';
try {
expect(await summarizeWith()).toEqual({
configuration: { fetchOptions: { dispatcher: expect.any(Object) } },
});
} finally {
delete process.env.OPENAI_REVERSE_PROXY;
}
});
it('declares nothing for an agent whose custom endpoint normalized to openAI', async () => {
/**
* `initializeAgent` rewrites a custom-endpoint agent's provider to `openAI`
* while its endpoint keeps the custom name. With summarization omitted, the
* summarizer reuses that agent's client — which points at the gateway, not
* at OpenAI.
*/
const agents = await callAndCapture({
agents: [
makeAgent({
provider: 'openAI',
endpoint: 'MyGateway',
model: 'gpt-6-astra',
model_parameters: { model: 'gpt-6-astra' },
}),
],
appConfig: makeAppConfig([
{ name: 'MyGateway', baseURL: 'https://gateway.internal/v1', apiKey: 'gw-key' },
]),
summarizationConfig: { model: 'gpt-6-astra' },
});
const config = agents[0].summarizationConfig as Record<string, unknown>;
expect(config.parameters).toBeUndefined();
});
});
// ---------------------------------------------------------------------------
// Suite 8: subagentConfigs
// ---------------------------------------------------------------------------
describe('subagentConfigs', () => {
it('is undefined when subagents are not enabled', async () => {
const agents = await callAndCapture({});
expect(agents[0].subagentConfigs).toBeUndefined();
});
it('keeps the poll tool available for existing tasks after spawning is disabled', async () => {
const agents = await callAndCapture({
subagentTasks: {
store: new InMemorySubagentTaskStore(),
scopeId: 'existing-task-scope',
},
});
expect(agents[0].subagentConfigs).toBeUndefined();
expect(agents[0].toolDefinitions).toEqual(
expect.arrayContaining([expect.objectContaining({ name: 'check_background_task' })]),
);
});
it('adds self-spawn when enabled and allowSelf defaults to true', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ subagents: { enabled: true } })],
});
const configs = agents[0].subagentConfigs as Array<Record<string, unknown>>;
expect(Array.isArray(configs)).toBe(true);
expect(configs).toHaveLength(1);
expect(configs[0]).toMatchObject({ self: true, type: 'self' });
});
it('omits self-spawn when allowSelf is false', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ subagents: { enabled: true, allowSelf: false } })],
});
expect(agents[0].subagentConfigs).toBeUndefined();
});
it('adds explicit subagent configs with agentInputs', async () => {
const child = makeAgent({
id: 'agent_child',
name: 'Researcher',
description: 'Deep web research',
});
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
subagentAgentConfigs: [child],
}),
],
});
const configs = agents[0].subagentConfigs as Array<Record<string, unknown>>;
expect(configs).toHaveLength(1);
expect(configs[0]).toMatchObject({
type: 'agent_child',
name: 'Researcher',
description: 'Deep web research',
});
expect(configs[0].agentInputs).toBeDefined();
expect(configs[0].self).toBeUndefined();
});
it('adds explicit lazy subagent descriptors without eager agent inputs', async () => {
const resolve = jest
.fn()
.mockResolvedValue(
makeAgent({ id: 'agent_child', name: 'Researcher', description: 'Deep web research' }),
);
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
lazySubagentConfigs: [
{
id: 'agent_child',
name: 'Researcher',
description: 'Deep web research',
configId: 'agent_child:3:fingerprint',
resolve,
},
],
}),
],
});
const configs = agents[0].subagentConfigs as Array<Record<string, unknown>>;
expect(configs).toHaveLength(1);
expect(configs[0]).toMatchObject({
type: 'agent_child',
configId: 'agent_child:3:fingerprint',
allowNested: true,
});
expect(configs[0].agentInputs).toBeUndefined();
expect(configs[0].resolveAgentInputs).toBeInstanceOf(Function);
expect(resolve).not.toHaveBeenCalled();
const childInputs = await (
configs[0].resolveAgentInputs as (context: never) => Promise<{
name?: string;
}>
)({ signal: new AbortController().signal } as never);
expect(resolve).toHaveBeenCalledTimes(1);
expect(childInputs.name).toBe('Researcher');
});
it.each([
['foreground', undefined],
[
'detached',
{
store: new InMemorySubagentTaskStore(),
scopeId: 'file-context-task-scope',
} satisfies SubagentTaskConfig,
],
])("preserves a lazy child's prepared File Context in %s execution", async (_mode, tasks) => {
const fileContext = 'Attached document(s):\n```md\n# "child.txt"\nChild-only facts\n\n```';
const resolve = jest.fn().mockResolvedValue(
makeAgent({
id: 'agent_child',
name: 'Researcher',
additional_instructions: fileContext,
}),
);
const agents = await callAndCapture({
subagentTasks: tasks,
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
lazySubagentConfigs: [
{
id: 'agent_child',
name: 'Researcher',
description: 'Uses private File Context',
configId: 'agent_child:3:fingerprint',
resolve,
},
],
}),
],
});
const [config] = agents[0].subagentConfigs as Array<Record<string, unknown>>;
const childInputs = await (
config.resolveAgentInputs as (context: never) => Promise<Record<string, unknown>>
)({ signal: new AbortController().signal } as never);
expect(childInputs.additional_instructions).toBe(fileContext);
});
it('preserves prepared File Context for an eager legacy subagent', async () => {
const fileContext = 'Attached document(s):\n```md\n# "child.txt"\nLegacy child facts\n\n```';
const child = makeAgent({
id: 'agent_child',
name: 'Researcher',
additional_instructions: fileContext,
});
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
subagentAgentConfigs: [child],
}),
],
});
const [config] = agents[0].subagentConfigs as Array<Record<string, unknown>>;
const childInputs = config.agentInputs as Record<string, unknown>;
expect(childInputs.additional_instructions).toBe(fileContext);
});
it('uses a fresh expansion budget for each lazy descriptor resolution', async () => {
const nestedDescriptors = Array.from({ length: 99 }, (_, index) => ({
id: `agent_nested_${index}`,
name: `Nested ${index}`,
description: 'Nested lazy child',
configId: `agent_nested_${index}:1:fingerprint`,
resolve: jest.fn(),
}));
const resolve = jest.fn().mockResolvedValue(
makeAgent({
id: 'agent_child',
subagents: { enabled: true, allowSelf: false },
lazySubagentConfigs: nestedDescriptors,
}),
);
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
lazySubagentConfigs: [
{
id: 'agent_child',
name: 'Child',
description: 'Lazy child',
configId: 'agent_child:1:fingerprint',
resolve,
},
],
}),
],
});
const resolveAgentInputs = (agents[0].subagentConfigs as Array<Record<string, unknown>>)[0]
.resolveAgentInputs as (context: never) => Promise<unknown>;
const context = { signal: new AbortController().signal } as never;
await expect(resolveAgentInputs(context)).resolves.toBeDefined();
await expect(resolveAgentInputs(context)).resolves.toBeDefined();
expect(resolve).toHaveBeenCalledTimes(2);
});
it('uses pristine top-level inputs for a graph resolved by a lazy child', async () => {
const topLevelMember = makeAgent({
id: 'agent_top_level_member',
hasDeferredTools: true,
toolDefinitions: [{ name: 'tool_search' }],
toolRegistry: new Map([['deep_tool', { name: 'deep_tool', defer_loading: true }]]),
});
const definition = {
type: 'late_team',
name: 'Late team',
description: 'Resolves after the parent input is built',
agent_ids: [topLevelMember.id],
edges: [],
entry_agent_id: topLevelMember.id,
result_agent_id: topLevelMember.id,
};
const resolve = jest.fn().mockResolvedValue(
makeAgent({
id: 'agent_lazy_parent',
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
subagentGraphConfigs: [{ definition, memberConfigs: [topLevelMember] }],
}),
);
const parent = makeAgent({
id: 'agent_parent',
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_lazy_parent'] },
lazySubagentConfigs: [
{
id: 'agent_lazy_parent',
name: 'Lazy parent',
description: 'Lazy graph owner',
configId: 'agent_lazy_parent:1:fingerprint',
resolve,
},
],
});
const agents = await callAndCapture({
agents: [topLevelMember, parent],
messages: [],
discoveredToolNames: ['deep_tool'],
});
const lazyConfig = (agents[1].subagentConfigs as Array<Record<string, unknown>>)[0];
const resolvedInputs = await (
lazyConfig.resolveAgentInputs as (context: never) => Promise<Record<string, unknown>>
)({ signal: new AbortController().signal } as never);
const graphConfig = (resolvedInputs.subagentConfigs as Array<Record<string, unknown>>)[0];
const memberInput = (graphConfig.agents as Array<Record<string, unknown>>)[0];
const memberRegistry = memberInput.toolRegistry as Map<string, { defer_loading?: boolean }>;
expect(
(agents[0].toolRegistry as Map<string, { defer_loading?: boolean }>).get('deep_tool'),
).toMatchObject({ defer_loading: false });
expect(memberRegistry.get('deep_tool')).toMatchObject({ defer_loading: true });
expect(memberInput.toolDefinitions).toEqual([{ name: 'tool_search' }]);
});
it('builds lazy graph inputs from initialized members instead of capability metadata', async () => {
const childId = 'agent_lazy_capability_parent';
const memberId = 'agent_lazy_capability_member';
const metadata = makeAgent({ id: memberId, codeEnvAvailable: true });
const initializedMember = makeAgent({
id: memberId,
codeEnvAvailable: true,
toolDefinitions: [{ name: 'initialized_tool' }],
toolRegistry: new Map([['initialized_tool', { name: 'initialized_tool' }]]),
});
const definition = {
type: 'capability_team',
name: 'Capability team',
description: 'Uses the initialized member runtime',
agent_ids: [childId, memberId],
edges: [{ from: childId, to: memberId, edgeType: 'direct' as const }],
entry_agent_id: childId,
result_agent_id: memberId,
};
const resolve = jest.fn().mockImplementation(async () => {
const initializedChild = makeAgent({
id: childId,
toolDefinitions: [{ name: 'child_tool' }],
toolRegistry: new Map([['child_tool', { name: 'child_tool' }]]),
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
});
initializedChild.subagentGraphConfigs = [
{ definition, memberConfigs: [initializedChild, initializedMember] },
];
return initializedChild;
});
const agents = await callAndCapture({
agents: [
makeAgent({
id: 'agent_parent',
subagents: {
enabled: true,
allowSelf: false,
agent_ids: [childId],
},
lazySubagentConfigs: [
{
id: childId,
name: 'Lazy capability parent',
description: 'Resolves its team on selection',
configId: `${childId}:1:fingerprint`,
subagentGraphMemberMetadata: [metadata],
resolve,
},
],
}),
],
});
const lazyConfig = (agents[0].subagentConfigs as Array<Record<string, unknown>>)[0];
const resolvedInputs = await (
lazyConfig.resolveAgentInputs as (context: never) => Promise<Record<string, unknown>>
)({ signal: new AbortController().signal } as never);
const graphConfig = (resolvedInputs.subagentConfigs as Array<Record<string, unknown>>)[0];
const memberInputs = graphConfig.agents as Array<Record<string, unknown>>;
expect(memberInputs[0].toolDefinitions).toEqual([{ name: 'child_tool' }]);
expect(memberInputs[0].toolRegistry).toEqual(new Map([['child_tool', { name: 'child_tool' }]]));
expect(memberInputs[1].toolDefinitions).toEqual([{ name: 'initialized_tool' }]);
expect(memberInputs[1].toolRegistry).toEqual(
new Map([['initialized_tool', { name: 'initialized_tool' }]]),
);
});
it('builds an explicit saved-agent team as one graph subagent config', async () => {
const researcher = makeAgent({
id: 'agent_researcher',
name: 'Researcher',
recursion_limit: 30,
});
const writer = makeAgent({
id: 'agent_writer',
name: 'Writer',
recursion_limit: 24,
subagents: { enabled: true, agent_ids: ['agent_nested'] },
subagentAgentConfigs: [makeAgent({ id: 'agent_nested' })],
});
const definition = {
type: 'research_team',
name: 'Research team',
description: 'Researches and writes a final answer',
agent_ids: ['agent_researcher', 'agent_writer'],
edges: [{ from: 'agent_researcher', to: 'agent_writer', edgeType: 'direct' as const }],
entry_agent_id: 'agent_researcher',
result_agent_id: 'agent_writer',
};
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
subagentGraphConfigs: [{ definition, memberConfigs: [researcher, writer] }],
}),
],
});
const configs = agents[0].subagentConfigs as Array<Record<string, unknown>>;
expect(configs).toHaveLength(1);
expect(configs[0]).toMatchObject({
kind: 'graph',
type: 'research_team',
name: 'Research team',
description: 'Researches and writes a final answer',
edges: definition.edges,
entryAgentId: 'agent_researcher',
resultAgentId: 'agent_writer',
maxTurns: 8,
});
const memberInputs = configs[0].agents as Array<Record<string, unknown>>;
expect(memberInputs.map((member) => member.agentId)).toEqual([
'agent_researcher',
'agent_writer',
]);
expect(memberInputs.every((member) => member.subagentConfigs == null)).toBe(true);
});
it('builds a one-member graph subagent without edges', async () => {
const member = makeAgent({ id: 'agent_solo', name: 'Solo' });
const definition = {
type: 'solo_team',
name: 'Solo team',
description: 'Runs one isolated graph member',
agent_ids: ['agent_solo'],
edges: [],
entry_agent_id: 'agent_solo',
result_agent_id: 'agent_solo',
};
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
subagentGraphConfigs: [{ definition, memberConfigs: [member] }],
}),
],
});
expect(agents[0].subagentConfigs).toEqual([
expect.objectContaining({
kind: 'graph',
type: 'solo_team',
agents: [expect.objectContaining({ agentId: 'agent_solo' })],
edges: [],
entryAgentId: 'agent_solo',
resultAgentId: 'agent_solo',
}),
]);
});
it('normalizes an explicit false excludeResults value before SDK validation', async () => {
const researcher = makeAgent({ id: 'agent_researcher' });
const writer = makeAgent({ id: 'agent_writer' });
const definition = {
type: 'default_results_team',
name: 'Default results team',
description: 'Uses the default edge result behavior',
agent_ids: ['agent_researcher', 'agent_writer'],
edges: [
{
from: 'agent_researcher',
to: 'agent_writer',
edgeType: 'direct' as const,
excludeResults: false,
},
],
entry_agent_id: 'agent_researcher',
result_agent_id: 'agent_writer',
};
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
subagentGraphConfigs: [{ definition, memberConfigs: [researcher, writer] }],
}),
],
});
const [config] = agents[0].subagentConfigs as Array<Record<string, unknown>>;
expect(config.edges).toEqual([
{ from: 'agent_researcher', to: 'agent_writer', edgeType: 'direct' },
]);
});
it("adds each graph member's always-apply skills to its isolated context", async () => {
const member = makeAgent({
id: 'agent_skilled_member',
additional_instructions: 'Keep the response concise.',
alwaysApplySkillPrimes: [
{ name: 'member-workflow', body: 'Follow the member-specific workflow.' },
],
});
const definition = {
type: 'skilled_team',
name: 'Skilled team',
description: 'Runs a member with its own always-apply skill',
agent_ids: ['agent_skilled_member'],
edges: [],
entry_agent_id: 'agent_skilled_member',
result_agent_id: 'agent_skilled_member',
};
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
subagentGraphConfigs: [{ definition, memberConfigs: [member] }],
}),
],
});
const [config] = agents[0].subagentConfigs as Array<Record<string, unknown>>;
const [memberInput] = config.agents as Array<Record<string, unknown>>;
expect(memberInput.additional_instructions).toBe(
'Keep the response concise.\n\n' +
'# Always-apply skill: member-workflow\nFollow the member-specific workflow.',
);
});
it('isolates a parent graph member before discovered tools mutate the parent registry', async () => {
const agent = makeAgent({
id: 'agent_parent',
name: 'Parent',
hasDeferredTools: true,
toolDefinitions: [{ name: 'tool_search' }],
toolRegistry: new Map([['deep_tool', { name: 'deep_tool', defer_loading: true }]]),
});
const definition = {
type: 'self_team',
name: 'Self team',
description: 'Runs the parent as an isolated graph member',
agent_ids: ['agent_parent'],
edges: [],
entry_agent_id: 'agent_parent',
result_agent_id: 'agent_parent',
};
agent.subagents = { enabled: true, allowSelf: false, graphs: [definition] };
agent.subagentGraphConfigs = [{ definition, memberConfigs: [agent] }];
const agents = await callAndCapture({
agents: [agent],
messages: [],
discoveredToolNames: ['deep_tool'],
});
const parentRegistry = agents[0].toolRegistry as Map<string, { defer_loading?: boolean }>;
const graphConfig = (agents[0].subagentConfigs as Array<Record<string, unknown>>)[0];
const memberInputs = graphConfig.agents as Array<Record<string, unknown>>;
const memberRegistry = memberInputs[0].toolRegistry as Map<string, { defer_loading?: boolean }>;
expect(parentRegistry.get('deep_tool')?.defer_loading).toBe(false);
expect(memberRegistry.get('deep_tool')?.defer_loading).toBe(true);
expect(memberInputs[0].toolDefinitions).toEqual([{ name: 'tool_search' }]);
});
it('snapshots graph members before an earlier top-level input mutates them', async () => {
const earlierAgent = makeAgent({
id: 'agent_earlier',
name: 'Earlier',
hasDeferredTools: true,
toolDefinitions: [{ name: 'tool_search' }],
toolRegistry: new Map([['deep_tool', { name: 'deep_tool', defer_loading: true }]]),
});
const definition = {
type: 'cross_root_team',
name: 'Cross-root team',
description: 'Uses an earlier top-level agent as an isolated member',
agent_ids: ['agent_earlier'],
edges: [],
entry_agent_id: 'agent_earlier',
result_agent_id: 'agent_earlier',
};
const laterAgent = makeAgent({
id: 'agent_later',
name: 'Later',
subagents: { enabled: true, allowSelf: false, graphs: [definition] },
subagentGraphConfigs: [{ definition, memberConfigs: [earlierAgent] }],
});
const agents = await callAndCapture({
agents: [earlierAgent, laterAgent],
messages: [],
discoveredToolNames: ['deep_tool'],
});
const earlierRegistry = agents[0].toolRegistry as Map<string, { defer_loading?: boolean }>;
const laterGraph = (agents[1].subagentConfigs as Array<Record<string, unknown>>)[0];
const memberInputs = laterGraph.agents as Array<Record<string, unknown>>;
const memberRegistry = memberInputs[0].toolRegistry as Map<string, { defer_loading?: boolean }>;
expect(earlierRegistry.get('deep_tool')?.defer_loading).toBe(false);
expect(memberRegistry.get('deep_tool')?.defer_loading).toBe(true);
expect(memberInputs[0].toolDefinitions).toEqual([{ name: 'tool_search' }]);
});
it('preserves explicit nested subagents across the SDK child graph boundary', async () => {
const grandchild = makeAgent({ id: 'agent_grandchild', name: 'Grandchild' });
const child = makeAgent({
id: 'agent_child',
name: 'Child',
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_grandchild'] },
subagentAgentConfigs: [grandchild],
});
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
subagentAgentConfigs: [child],
}),
],
});
expect(agents[0].maxSubagentDepth).toBe(MAX_SUBAGENT_DEPTH);
const childConfig = (agents[0].subagentConfigs as BuildChildInput[])[0];
expect(childConfig.allowNested).toBe(true);
const childInputs = buildChildInputs(childConfig, 'agent_child', MAX_SUBAGENT_DEPTH);
expect(childInputs.maxSubagentDepth).toBe(MAX_SUBAGENT_DEPTH - 1);
expect(childInputs.subagentConfigs).toHaveLength(1);
expect(childInputs.subagentConfigs?.[0]).toMatchObject({
type: 'agent_grandchild',
allowNested: true,
});
});
it('prunes shared-agent cycles per traversal path without dropping valid edges', async () => {
const left = makeAgent({
id: 'agent_left',
name: 'Left',
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_shared'] },
}) as TestRunAgent;
const right = makeAgent({
id: 'agent_right',
name: 'Right',
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_shared'] },
}) as TestRunAgent;
const shared = makeAgent({
id: 'agent_shared',
name: 'Shared',
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_left'] },
}) as TestRunAgent;
left.subagentAgentConfigs = [shared];
right.subagentAgentConfigs = [shared];
shared.subagentAgentConfigs = [left];
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: {
enabled: true,
allowSelf: false,
agent_ids: ['agent_left', 'agent_right'],
},
subagentAgentConfigs: [left, right],
}),
],
});
const rootConfigs = agents[0].subagentConfigs as BuildChildInput[];
const rootConfigsByType = new Map(rootConfigs.map((config) => [config.type, config]));
const leftConfig = rootConfigsByType.get('agent_left');
const rightConfig = rootConfigsByType.get('agent_right');
if (!leftConfig || !rightConfig) {
throw new Error('Expected both root subagent configs');
}
const leftInputs = buildChildInputs(leftConfig, 'agent_left', MAX_SUBAGENT_DEPTH);
const rightInputs = buildChildInputs(rightConfig, 'agent_right', MAX_SUBAGENT_DEPTH);
const leftShared = leftInputs.subagentConfigs?.[0] as BuildChildInput | undefined;
const rightShared = rightInputs.subagentConfigs?.[0] as BuildChildInput | undefined;
if (
!leftShared ||
!rightShared ||
leftInputs.maxSubagentDepth == null ||
rightInputs.maxSubagentDepth == null
) {
throw new Error('Expected both shared subagent configs');
}
const leftSharedInputs = buildChildInputs(
leftShared,
'agent_shared',
leftInputs.maxSubagentDepth,
);
const rightSharedInputs = buildChildInputs(
rightShared,
'agent_shared',
rightInputs.maxSubagentDepth,
);
expect(leftSharedInputs.subagentConfigs).toBeUndefined();
expect(rightSharedInputs.subagentConfigs).toHaveLength(1);
expect(rightSharedInputs.subagentConfigs?.[0]).toMatchObject({ type: 'agent_left' });
});
it('combines self-spawn and explicit subagents when both enabled', async () => {
const child = makeAgent({ id: 'agent_child', name: 'Helper' });
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, agent_ids: ['agent_child'] },
subagentAgentConfigs: [child],
}),
],
});
const configs = agents[0].subagentConfigs as Array<Record<string, unknown>>;
expect(configs).toHaveLength(2);
expect(configs[0].self).toBe(true);
expect(configs[1].type).toBe('agent_child');
});
it('skips a child that points at the parent itself', async () => {
const self = makeAgent({ id: 'agent_1' });
const agents = await callAndCapture({
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_1'] },
subagentAgentConfigs: [self],
}),
],
});
expect(agents[0].subagentConfigs).toBeUndefined();
});
it('does NOT leak the parent run `initialSummary` into an explicit child (Codex P1 regression)', async () => {
/**
* `buildAgentInput` is a shared factory that always stamps the parent
* run's `initialSummary` on the returned AgentInputs. When it's reused
* to build a subagent child's inputs, `buildSubagentConfigs` must clear
* that field — otherwise the child inherits unrelated conversation
* context, defeating the isolation contract (and burning extra tokens).
*/
const summary = { text: 'parent conversation summary', tokenCount: 99 };
const child = makeAgent({ id: 'agent_child', name: 'Child' });
const agents = await callAndCapture({
initialSummary: summary,
agents: [
makeAgent({
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
subagentAgentConfigs: [child],
}),
],
});
const parent = agents[0];
/** The parent itself keeps the summary — that's how it receives
* cross-turn context. */
expect(parent.initialSummary).toEqual(summary);
const childConfig = (parent.subagentConfigs as Array<Record<string, unknown>>)[0];
const childInputs = childConfig.agentInputs as {
initialSummary?: unknown;
discoveredTools?: unknown;
};
expect(childInputs.initialSummary).toBeUndefined();
expect(childInputs.discoveredTools).toBeUndefined();
});
it('rejects subagent graphs deeper than MAX_SUBAGENT_DEPTH before Run.create', async () => {
await expect(
createRun({
agents: [makeSubagentChain(MAX_SUBAGENT_DEPTH + 1)] as never,
signal: new AbortController().signal,
streaming: true,
streamUsage: true,
}),
).rejects.toThrow(`maximum depth of ${MAX_SUBAGENT_DEPTH}`);
expect(logger.warn).toHaveBeenCalledWith(
'[createRun] Subagent graph depth limit exceeded',
expect.objectContaining({
agentId: `agent_chain_${MAX_SUBAGENT_DEPTH + 1}`,
depth: MAX_SUBAGENT_DEPTH + 1,
maxSubagentDepth: MAX_SUBAGENT_DEPTH,
}),
);
expect(Run.create).not.toHaveBeenCalled();
});
it('rejects layered DAGs that exceed MAX_SUBAGENT_RUN_CONFIGS expanded entries', async () => {
await expect(
createRun({
agents: [makeLayeredSubagentDag(3, MAX_SUBAGENT_DEPTH)] as never,
signal: new AbortController().signal,
streaming: true,
streamUsage: true,
}),
).rejects.toThrow(`maximum of ${MAX_SUBAGENT_RUN_CONFIGS} expanded entries`);
expect(logger.warn).toHaveBeenCalledWith(
'[createRun] Subagent run configuration limit exceeded',
expect.objectContaining({
expandedConfigCount: MAX_SUBAGENT_RUN_CONFIGS + 1,
maxSubagentRunConfigs: MAX_SUBAGENT_RUN_CONFIGS,
rootAgentIds: ['agent_dag_root'],
}),
);
expect(Run.create).not.toHaveBeenCalled();
});
});
/**
* Captures the top-level `Run.create` config (not just agentInputs) so tests
* can assert presence/absence of run-level options.
*/
async function callAndCaptureRunConfig({
overrides,
user,
tenantId,
appConfig,
}: {
overrides?: Record<string, unknown>;
user?: Record<string, unknown>;
tenantId?: string;
appConfig?: AppConfig;
} = {}): Promise<Record<string, unknown>> {
const agents = [makeAgent(overrides)];
const signal = new AbortController().signal;
await createRun({
agents: agents as never,
signal,
streaming: true,
streamUsage: true,
user: user as never,
tenantId,
appConfig,
});
const createMock = Run.create as jest.Mock;
expect(createMock).toHaveBeenCalledTimes(1);
return createMock.mock.calls[0][0] as Record<string, unknown>;
}
// ---------------------------------------------------------------------------
// Suite: Langfuse run config
// ---------------------------------------------------------------------------
const exportTelemetry = (plan: string, reason: string, tenantId?: string) => ({
...(tenantId ? { 'librechat.tenant.id': tenantId } : {}),
'librechat.langfuse.export_plan': plan,
'librechat.langfuse.export_reason': reason,
});
describe('Langfuse run config', () => {
it('passes deterministic Langfuse trace config without tenant metadata by default', async () => {
const callArgs = await callAndCaptureRunConfig();
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
librechatTraceAttributes: exportTelemetry('central_only', 'fanout_disabled'),
});
});
it('adds the explicit request tenant id to Langfuse trace metadata and tags', async () => {
const callArgs = await callAndCaptureRunConfig({
user: {
id: 'user-1',
},
tenantId: 'tenant-1',
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
librechatTraceAttributes: exportTelemetry('central_only', 'fanout_disabled', 'tenant-1'),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
it('falls back to a full user tenant id for direct createRun callers', async () => {
const callArgs = await callAndCaptureRunConfig({
user: {
tenantId: 'tenant-2',
},
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
librechatTraceAttributes: exportTelemetry('central_only', 'fanout_disabled', 'tenant-2'),
metadata: { 'librechat.tenant.id': 'tenant-2' },
tags: ['tenant:tenant-2'],
});
});
it('forwards the requesting user and trace context into the Langfuse run config', async () => {
await createRun({
agents: [makeAgent()] as never,
signal: new AbortController().signal,
streaming: true,
streamUsage: true,
user: { id: 'user-1', email: '[email protected]', role: 'ADMIN' } as never,
conversationId: 'convo-1',
requestBody: { conversationId: 'convo-stale' },
traceContext: { endpoint: 'agents', spec: 'support-bot' },
appConfig: {
langfuse: {
trace: {
userIdField: 'email',
userMetadataFields: ['role'],
conversationMetadataFields: ['conversationId', 'endpoint', 'provider', 'model', 'spec'],
},
},
} as unknown as AppConfig,
});
const createMock = Run.create as jest.Mock;
expect(createMock).toHaveBeenCalledTimes(1);
const callArgs = createMock.mock.calls[0][0] as Record<string, unknown>;
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
userId: '[email protected]',
metadata: {
'librechat.user.role': 'ADMIN',
'librechat.conversation.id': 'convo-1',
'librechat.endpoint': 'agents',
'librechat.provider': 'openAI',
'librechat.model': 'gpt-4o',
'librechat.spec': 'support-bot',
},
librechatTraceAttributes: exportTelemetry('central_only', 'fanout_disabled'),
});
});
it('adds tenant Langfuse credentials from tenant-scoped app config', async () => {
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://langfuse-fanout-collector:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'eu',
},
} as unknown as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
publicKey: 'pk-tenant-1',
secretKey: 'sk-tenant-1',
baseUrl: 'http://langfuse-fanout-collector:4318/tenant/eu',
metadata: { 'librechat.tenant.id': 'tenant-1' },
librechatTraceAttributes: {
...exportTelemetry('tenant_fanout', 'configured', 'tenant-1'),
'librechat.langfuse.tenant_export.enabled': 'true',
'librechat.langfuse.destination': 'eu',
},
tags: ['tenant:tenant-1'],
});
});
it('uses central env Langfuse config when deployment fanout is not enabled', async () => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_BASE_URL = 'https://central.langfuse.example';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'eu',
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
publicKey: 'pk-central',
secretKey: 'sk-central',
baseUrl: 'https://central.langfuse.example',
librechatTraceAttributes: exportTelemetry('central_only', 'fanout_disabled', 'tenant-1'),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
it('uses deployment fanout collector URL without auth when only tenant keys are configured', async () => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_BASE_URL = 'https://central.langfuse.example';
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318',
librechatTraceAttributes: exportTelemetry(
'central_only',
'destination_unconfigured',
'tenant-1',
),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
it('routes tenant fanout traces to the configured tenant destination', async () => {
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'us',
},
} as AppConfig,
});
expect(callArgs.langfuse).toMatchObject({
publicKey: 'pk-tenant-1',
secretKey: 'sk-tenant-1',
baseUrl: 'http://collector-from-env:4318/tenant/us',
metadata: { 'librechat.tenant.id': 'tenant-1' },
librechatTraceAttributes: {
...exportTelemetry('tenant_fanout', 'configured', 'tenant-1'),
'librechat.langfuse.tenant_export.enabled': 'true',
'librechat.langfuse.destination': 'us',
},
});
});
it('normalizes trailing slashes when building the tenant-scoped fanout URL', async () => {
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318/';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'eu',
},
} as AppConfig,
});
expect((callArgs.langfuse as { baseUrl?: string } | undefined)?.baseUrl).toBe(
'http://collector-from-env:4318/tenant/eu',
);
});
it.each(['1', 'yes', 'on'])(
'routes tenant fanout traces when global fanout is %s',
async (value) => {
process.env.LANGFUSE_FANOUT_ENABLED = value;
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'us',
},
} as AppConfig,
});
expect(callArgs.langfuse).toMatchObject({
publicKey: 'pk-tenant-1',
secretKey: 'sk-tenant-1',
baseUrl: 'http://collector-from-env:4318/tenant/us',
librechatTraceAttributes: {
...exportTelemetry('tenant_fanout', 'configured', 'tenant-1'),
'librechat.langfuse.tenant_export.enabled': 'true',
'librechat.langfuse.destination': 'us',
},
});
},
);
it.each(['false', '0', 'no', 'off'])(
'uses central env Langfuse config when global fanout is %s',
async (value) => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_BASE_URL = 'https://central.langfuse.example';
process.env.LANGFUSE_FANOUT_ENABLED = value;
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'eu',
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
publicKey: 'pk-central',
secretKey: 'sk-central',
baseUrl: 'https://central.langfuse.example',
librechatTraceAttributes: exportTelemetry('central_only', 'fanout_disabled', 'tenant-1'),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
},
);
it('does not append a tenant route to baseUrl when fanout is disabled', async () => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_BASE_URL = 'https://central.langfuse.example';
process.env.LANGFUSE_FANOUT_ENABLED = 'false';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'eu',
},
} as AppConfig,
});
expect(callArgs.langfuse).toMatchObject({
publicKey: 'pk-central',
secretKey: 'sk-central',
baseUrl: 'https://central.langfuse.example',
librechatTraceAttributes: exportTelemetry('central_only', 'fanout_disabled', 'tenant-1'),
});
expect(callArgs.langfuse).not.toMatchObject({
baseUrl: 'http://collector-from-env:4318/tenant/eu',
});
});
it('uses central env Langfuse config when fanout has no collector URL', async () => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_BASE_URL = 'https://central.langfuse.example';
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'eu',
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
publicKey: 'pk-central',
secretKey: 'sk-central',
baseUrl: 'https://central.langfuse.example',
librechatTraceAttributes: exportTelemetry(
'central_only',
'collector_unconfigured',
'tenant-1',
),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
it('uses deployment fanout collector URL without auth when the tenant destination is not configured', async () => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_BASE_URL = 'https://central.langfuse.example';
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
process.env.LANGFUSE_FANOUT_TENANT_DESTINATIONS = 'eu=https://cloud.langfuse.com';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'unconfigured',
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318',
librechatTraceAttributes: exportTelemetry(
'central_only',
'destination_unconfigured',
'tenant-1',
),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
it('uses deployment fanout collector URL without auth when tenant Langfuse config has no keys', async () => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_BASE_URL = 'https://central.langfuse.example';
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: { enabled: true },
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318',
librechatTraceAttributes: exportTelemetry('central_only', 'missing_credentials', 'tenant-1'),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
it('uses deployment fanout collector URL without auth when app config is missing under fanout env', async () => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_BASE_URL = 'https://central.langfuse.example';
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318',
librechatTraceAttributes: exportTelemetry('central_only', 'tenant_disabled', 'tenant-1'),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
it('uses deployment fanout collector URL without auth when tenant fanout export is disabled', async () => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_BASE_URL = 'https://central.langfuse.example';
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
process.env.LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED = 'true';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318',
librechatTraceAttributes: exportTelemetry('central_only', 'emergency_disabled', 'tenant-1'),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
it('does not disable tenant fanout export for a blank emergency toggle', async () => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
process.env.LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED = ' ';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'eu',
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318/tenant/eu',
metadata: { 'librechat.tenant.id': 'tenant-1' },
publicKey: 'pk-tenant-1',
secretKey: 'sk-tenant-1',
tags: ['tenant:tenant-1'],
librechatTraceAttributes: {
...exportTelemetry('tenant_fanout', 'configured', 'tenant-1'),
'librechat.langfuse.tenant_export.enabled': 'true',
'librechat.langfuse.destination': 'eu',
},
});
});
it.each(['true', '1', 'yes', 'on'])(
'uses deployment fanout collector URL without auth when the emergency toggle is %s',
async (value) => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
process.env.LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED = value;
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'eu',
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318',
librechatTraceAttributes: exportTelemetry('central_only', 'emergency_disabled', 'tenant-1'),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
},
);
it.each(['false', '0', 'no', 'off'])(
'routes tenant fanout traces when the emergency toggle is %s',
async (value) => {
process.env.LANGFUSE_PUBLIC_KEY = 'pk-central';
process.env.LANGFUSE_SECRET_KEY = 'sk-central';
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
process.env.LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED = value;
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: true,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
destination: 'eu',
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318/tenant/eu',
metadata: { 'librechat.tenant.id': 'tenant-1' },
publicKey: 'pk-tenant-1',
secretKey: 'sk-tenant-1',
tags: ['tenant:tenant-1'],
librechatTraceAttributes: {
...exportTelemetry('tenant_fanout', 'configured', 'tenant-1'),
'librechat.langfuse.tenant_export.enabled': 'true',
'librechat.langfuse.destination': 'eu',
},
});
},
);
it('keeps central collector tracing when tenant Langfuse export is disabled', async () => {
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: false,
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
},
} as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318',
librechatTraceAttributes: exportTelemetry('central_only', 'tenant_disabled', 'tenant-1'),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
it('keeps central collector tracing when tenant Langfuse enabled is the string false', async () => {
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://collector-from-env:4318';
const callArgs = await callAndCaptureRunConfig({
tenantId: 'tenant-1',
appConfig: {
langfuse: {
enabled: 'false',
publicKey: 'pk-tenant-1',
secretKey: encryptV3('sk-tenant-1'),
},
} as unknown as AppConfig,
});
expect(callArgs.langfuse).toEqual({
deterministicTraceId: true,
baseUrl: 'http://collector-from-env:4318',
librechatTraceAttributes: exportTelemetry('central_only', 'tenant_disabled', 'tenant-1'),
metadata: { 'librechat.tenant.id': 'tenant-1' },
tags: ['tenant:tenant-1'],
});
});
});
// ---------------------------------------------------------------------------
// Suite: toolOutputReferences gating
// ---------------------------------------------------------------------------
describe('toolOutputReferences gating', () => {
it('passes toolOutputReferences when agent has codeEnvAvailable=true', async () => {
const callArgs = await callAndCaptureRunConfig({
overrides: { codeEnvAvailable: true },
});
expect(callArgs.toolOutputReferences).toEqual({ enabled: true });
});
it('omits toolOutputReferences when codeEnvAvailable is false', async () => {
const callArgs = await callAndCaptureRunConfig({
overrides: { codeEnvAvailable: false },
});
expect(callArgs).not.toHaveProperty('toolOutputReferences');
});
it('omits toolOutputReferences when codeEnvAvailable is unset', async () => {
const callArgs = await callAndCaptureRunConfig();
expect(callArgs).not.toHaveProperty('toolOutputReferences');
});
it('enables toolOutputReferences if any agent in a multi-agent run has codeEnvAvailable=true', async () => {
const signal = new AbortController().signal;
await createRun({
agents: [
makeAgent({ id: 'agent_a', codeEnvAvailable: false }),
makeAgent({ id: 'agent_b', codeEnvAvailable: true }),
] as never,
signal,
streaming: true,
streamUsage: true,
});
const createMock = Run.create as jest.Mock;
const callArgs = createMock.mock.calls[0][0] as Record<string, unknown>;
expect(callArgs.toolOutputReferences).toEqual({ enabled: true });
});
it('enables toolOutputReferences when only a subagent has codeEnvAvailable=true', async () => {
/**
* Real scenario: a parent agent without `execute_code` spawns a
* subagent that does have it. The SDK's shared tool-output
* reference registry serves every ToolNode in the run, so the
* subagent's `bash_tool` benefits from the run-level flag — and
* without this gate looking at `subagentAgentConfigs`, the
* subagent's `{{tool<idx>turn<turn>}}` placeholders would pass
* through unsubstituted.
*/
const signal = new AbortController().signal;
const subagent = makeAgent({ id: 'agent_child', codeEnvAvailable: true });
await createRun({
agents: [
makeAgent({
id: 'agent_parent',
codeEnvAvailable: false,
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
subagentAgentConfigs: [subagent],
}),
] as never,
signal,
streaming: true,
streamUsage: true,
});
const createMock = Run.create as jest.Mock;
const callArgs = createMock.mock.calls[0][0] as Record<string, unknown>;
expect(callArgs.toolOutputReferences).toEqual({ enabled: true });
});
it('enables toolOutputReferences when a transitively-nested subagent has codeEnvAvailable=true', async () => {
/**
* Multi-level delegation (parent → child → grandchild): only the
* grandchild has `codeEnvAvailable`. Verifies the recursion
* descends past one level of `subagentAgentConfigs`.
*/
const signal = new AbortController().signal;
const grandchild = makeAgent({ id: 'agent_grandchild', codeEnvAvailable: true });
const child = makeAgent({
id: 'agent_child',
codeEnvAvailable: false,
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_grandchild'] },
subagentAgentConfigs: [grandchild],
});
await createRun({
agents: [
makeAgent({
id: 'agent_parent',
codeEnvAvailable: false,
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },
subagentAgentConfigs: [child],
}),
] as never,
signal,
streaming: true,
streamUsage: true,
});
const createMock = Run.create as jest.Mock;
const callArgs = createMock.mock.calls[0][0] as Record<string, unknown>;
expect(callArgs.toolOutputReferences).toEqual({ enabled: true });
});
it('enables tool output references from a lazy graph member metadata descriptor', async () => {
const signal = new AbortController().signal;
const graphMember = makeAgent({
id: 'agent_lazy_graph_member',
codeEnvAvailable: true,
statefulCodeSessions: true,
});
const lazyChild = {
...makeAgent({ id: 'agent_lazy_child', codeEnvAvailable: false }),
configId: 'agent_lazy_child:v1',
subagentGraphMemberMetadata: [graphMember],
resolve: jest.fn(),
};
await createRun({
agents: [
makeAgent({
id: 'agent_parent',
codeEnvAvailable: false,
subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_lazy_child'] },
lazySubagentConfigs: [lazyChild],
}),
] as never,
signal,
streaming: true,
streamUsage: true,
});
const createMock = Run.create as jest.Mock;
const callArgs = createMock.mock.calls[0][0] as Record<string, unknown>;
expect(callArgs.toolOutputReferences).toEqual({ enabled: true });
/**
* Stateful routing is intentionally agent-scoped. A lazy graph member must
* not promote its execution profile into run-global SDK configuration.
*/
expect(callArgs.toolExecution).toBeUndefined();
expect(lazyChild.resolve).not.toHaveBeenCalled();
});
it('terminates and omits toolOutputReferences for a cyclic agent tree with no codeenv', async () => {
/**
* Cycle safety: `A → B → A`, neither has `codeEnvAvailable`. The
* `visited` set in `anyAgentHasCodeEnv` must short-circuit the
* recursion — without it this would stack-overflow before
* `Run.create` is reached. Mirrors the cycle-safety pattern
* `buildSubagentConfigs` already uses elsewhere in this module.
*/
const signal = new AbortController().signal;
type CyclicAgent = ReturnType<typeof makeAgent> & {
subagentAgentConfigs?: ReturnType<typeof makeAgent>[];
};
const a = makeAgent({ id: 'agent_a', codeEnvAvailable: false }) as CyclicAgent;
const b = makeAgent({ id: 'agent_b', codeEnvAvailable: false }) as CyclicAgent;
a.subagentAgentConfigs = [b];
b.subagentAgentConfigs = [a];
await createRun({
agents: [a] as never,
signal,
streaming: true,
streamUsage: true,
});
const createMock = Run.create as jest.Mock;
const callArgs = createMock.mock.calls[0][0] as Record<string, unknown>;
expect(callArgs).not.toHaveProperty('toolOutputReferences');
});
});
// ---------------------------------------------------------------------------
// Suite: deferred-tool replay on HITL resume (Codex G3)
//
// The resume path rebuilds the graph with `messages: []` (state comes from the
// durable checkpoint), so the in-turn `tool_search` results that mark a deferred
// tool discovered aren't on the critical path. createRun's `discoveredToolNames`
// input replays those names — captured at pause — so the paused deferred tool is
// promoted back into `toolDefinitions` (and `defer_loading` flipped) and its schema
// is restored to the rebuilt model binding.
// ---------------------------------------------------------------------------
describe('createRun deferred-tool replay (HITL resume)', () => {
/** Agent whose discoverable `deep_tool` lives ONLY in the registry (deferred). */
const makeDeferredAgent = (registryExtra: Array<[string, Record<string, unknown>]> = []) => {
const toolRegistry = new Map<string, Record<string, unknown>>([
['deep_tool', { name: 'deep_tool', defer_loading: true }],
...registryExtra,
]);
return makeAgent({
hasDeferredTools: true,
// tool_search is in definitions; the discoverable deep_tool is NOT (deferred).
toolDefinitions: [{ name: 'tool_search' }],
toolRegistry,
});
};
const captureAgents = async (
agent: ReturnType<typeof makeAgent>,
extra: Record<string, unknown>,
) => {
const signal = new AbortController().signal;
await createRun({
agents: [agent] as never,
signal,
streaming: true,
streamUsage: true,
...extra,
});
const createMock = Run.create as jest.Mock;
const callArgs = createMock.mock.calls[0][0];
return callArgs.graphConfig.agents as Array<Record<string, unknown>>;
};
const defNames = (agents: Array<Record<string, unknown>>): string[] =>
(agents[0].toolDefinitions as Array<{ name: string }>).map((d) => d.name);
it('promotes a replayed discovered tool into toolDefinitions when messages is empty (resume)', async () => {
const agents = await captureAgents(makeDeferredAgent(), {
messages: [],
discoveredToolNames: ['deep_tool'],
});
expect(defNames(agents)).toContain('deep_tool');
});
it('does NOT include the deferred tool without replayed names (the bug being fixed)', async () => {
const agents = await captureAgents(makeDeferredAgent(), { messages: [] });
expect(defNames(agents)).not.toContain('deep_tool');
});
it('flips defer_loading=false on the replayed tool so the model binds it', async () => {
const agents = await captureAgents(makeDeferredAgent(), {
messages: [],
discoveredToolNames: ['deep_tool'],
});
const registry = agents[0].toolRegistry as Map<string, { defer_loading?: boolean }>;
expect(registry.get('deep_tool')?.defer_loading).toBe(false);
});
it('unions replayed names with names extracted from message history', async () => {
const toolSearchResult = {
_getType: () => 'tool',
name: 'tool_search',
content: JSON.stringify({ tools: [{ name: 'from_history' }] }),
};
const agents = await captureAgents(
makeDeferredAgent([['from_history', { name: 'from_history', defer_loading: true }]]),
{ messages: [toolSearchResult], discoveredToolNames: ['deep_tool'] },
);
const names = defNames(agents);
expect(names).toContain('deep_tool'); // replayed
expect(names).toContain('from_history'); // extracted from messages
});
it('ignores replayed names when the agent has no deferred tools (inert)', async () => {
const agents = await captureAgents(
makeAgent({ hasDeferredTools: false, toolDefinitions: [], toolRegistry: new Map() }),
{ messages: [], discoveredToolNames: ['deep_tool'] },
);
expect(defNames(agents)).not.toContain('deep_tool');
});
});
// ---------------------------------------------------------------------------
// Suite: HITL wiring gated to resumable callers (Codex J3)
//
// Tool-approval policy must apply to every caller, while only an interactive
// caller may pause for an 'ask' decision. API-key endpoints have no resume surface.
// ---------------------------------------------------------------------------
describe('HITL wiring is gated on hitlCapable', () => {
const hitlAppConfig = {
config: {},
fileStrategy: FileSources.local,
imageOutputType: 'png',
endpoints: {
[EModelEndpoint.agents]: { toolApproval: { enabled: true } },
},
} as unknown as AppConfig;
const runAndGetConfig = async (extra: Record<string, unknown>) => {
await createRun({
agents: [makeAgent()] as never,
signal: new AbortController().signal,
appConfig: hitlAppConfig,
streaming: true,
streamUsage: true,
...extra,
});
const createMock = Run.create as jest.Mock;
return createMock.mock.calls[0][0] as Record<string, unknown>;
};
it('attaches humanInTheLoop when the caller is hitlCapable and approval is enabled', async () => {
const config = await runAndGetConfig({ hitlCapable: true });
expect(config.humanInTheLoop).toBeDefined();
expect(config.hooks).toBeDefined();
});
it.each([
[
{ enabled: true, mode: 'bypass', deny: ['delete_*'], allow: ['delete_file'] },
'delete_file',
'deny',
],
[{ enabled: true, mode: 'dontAsk', allow: ['read_*'] }, 'read_file', 'allow'],
[{ enabled: true, mode: 'dontAsk', allow: ['read_*'] }, 'write_file', 'deny'],
[{ enabled: true, mode: 'default' }, 'write_file', 'ask'],
] as const)('evaluates headless tool policy for %s on %s', async (policy, toolName, decision) => {
const appConfig = {
...hitlAppConfig,
endpoints: { [EModelEndpoint.agents]: { toolApproval: policy } },
} as unknown as AppConfig;
const config = await runAndGetConfig({ hitlCapable: false, appConfig });
expect(config).not.toHaveProperty('humanInTheLoop');
expect(
(config.graphConfig as { compileOptions?: { checkpointer?: unknown } }).compileOptions
?.checkpointer,
).toBeUndefined();
const result = await executeHooks({
registry: config.hooks as HookRegistry,
input: {
hook_event_name: 'PreToolUse',
runId: 'headless-test',
toolName,
toolInput: {},
toolUseId: 'call-1',
},
matchQuery: toolName,
});
expect(result.decision).toBe(decision);
});
it.each([
{ policy: { enabled: true, mode: 'bypass', deny: ['delete_record'] }, name: 'delete_record' },
{ policy: { enabled: true, mode: 'default' }, name: 'read_record' },
] as const)(
'blocks a real SDK direct tool before execution for $name',
async ({ policy, name }) => {
const config = await runAndGetConfig({
appConfig: {
...hitlAppConfig,
endpoints: { [EModelEndpoint.agents]: { toolApproval: policy } },
} as unknown as AppConfig,
});
const body = jest.fn(async () => 'executed');
const tool = new DynamicStructuredTool({
name,
description: 'A test-only tool',
schema: z.object({}),
func: body,
});
const node = new ToolNode({
tools: [tool],
agentId: 'agent_1',
hookRegistry: config.hooks as HookRegistry,
});
const result = await node.invoke(
{
messages: [
new AIMessage({ content: '', tool_calls: [{ id: 'call-1', name, args: {} }] }),
],
},
{ configurable: { run_id: 'headless-test', thread_id: 'thread-1' } },
);
expect(body).not.toHaveBeenCalled();
expect(JSON.stringify(result)).toContain('Blocked:');
},
);
it.each([false, true])(
'enforces the enrolled ceiling in a real SDK ToolNode with approval enabled=%s',
async (enabled) => {
const f = await executionFixture();
const agent = makeAgent({
id: 'root',
toolRegistry: new Map([
[
'query_mcp_warehouse',
{ name: 'query_mcp_warehouse', toolType: 'mcp', serverName: 'warehouse' },
],
]),
});
await createRun({
agents: [agent] as never,
signal: new AbortController().signal,
scheduledMCPExecution: f.execution,
appConfig: {
...hitlAppConfig,
endpoints: {
agents: { toolApproval: { enabled, mode: 'bypass', deny: ['query_mcp_warehouse'] } },
},
} as unknown as AppConfig,
});
const config = (Run.create as jest.Mock).mock.calls[0][0];
expect(config).not.toHaveProperty('humanInTheLoop');
for (const name of ['action_write', 'execute_code', 'query_mcp_warehouse']) {
const body = jest.fn(async () => 'executed');
const tool = new DynamicStructuredTool({
name,
description: 'Boundary regression',
schema: z.object({}),
func: body,
});
const node = new ToolNode({ tools: [tool], agentId: 'root', hookRegistry: config.hooks });
const result = await node.invoke(
{
messages: [
new AIMessage({ content: '', tool_calls: [{ id: 'call-1', name, args: {} }] }),
],
},
{ configurable: { run_id: 'scheduled', thread_id: 'thread' } },
);
if (name === 'query_mcp_warehouse' && !enabled) expect(body).toHaveBeenCalledTimes(1);
else {
expect(body).not.toHaveBeenCalled();
expect(JSON.stringify(result)).toContain('Blocked:');
}
}
},
);
it.each([true, false])(
'withholds detached task/wakeup capabilities only for enrolled=%s',
async (enrolled) => {
const f = await executionFixture();
if (!enrolled) f.snapshot.enrollment = null;
const execution = (await f.factory.resolve(f.identity, 'invoke'))!;
const tasks = {
store: new InMemorySubagentTaskStore(),
scopeId: 'scheduled-tasks',
completionDelivery: 'wakeup' as const,
};
const root = makeAgent({
id: 'root',
subagents: { enabled: true, allowSelf: false, agent_ids: ['child'] },
subagentAgentConfigs: [makeAgent({ id: 'child' })],
});
await createRun({
agents: [root] as never,
signal: new AbortController().signal,
scheduledMCPExecution: execution,
subagentTasks: tasks,
appConfig: {
...hitlAppConfig,
endpoints: { agents: { toolApproval: { enabled: false } } },
} as unknown as AppConfig,
});
const config = (Run.create as jest.Mock).mock.calls[0][0];
expect(config.subagentTasks).toBe(enrolled ? undefined : tasks);
const params = buildSubagentToolParams(config.graphConfig.agents[0].subagentConfigs, {
background: config.subagentTasks != null,
threadContinuation: true,
});
expect(
Object.prototype.hasOwnProperty.call(params.schema.properties ?? {}, 'run_in_background'),
).toBe(!enrolled);
expect(
Object.prototype.hasOwnProperty.call(params.schema.properties ?? {}, 'subagent_thread_id'),
).toBe(!enrolled);
const agent = config.graphConfig.agents[0];
expect(agent.subagentConfigs).toEqual([
expect.objectContaining({ type: 'child', allowNested: true }),
]);
const names = (agent.toolDefinitions ?? []).map((tool: { name: string }) => tool.name);
expect(names.includes('check_background_task')).toBe(!enrolled);
},
);
it.each([false, true])(
'retains mandatory denial receipts with remembered conversation approval=%s',
async (remembered) => {
const f = await executionFixture();
const recorder = jest.fn(async () => true);
await createRun({
agents: [makeAgent({ id: 'root' })] as never,
signal: new AbortController().signal,
scheduledMCPExecution: f.execution,
recordScheduledMCPDenial: recorder,
toolApprovalAllows: remembered ? ['write_action_api'] : undefined,
appConfig: {
...hitlAppConfig,
endpoints: {
agents: {
toolApproval: { enabled: remembered, mode: 'default', allowAlways: remembered },
},
},
} as unknown as AppConfig,
});
const config = (Run.create as jest.Mock).mock.calls[0][0];
const body = jest.fn(async () => 'side effect');
const action = new DynamicStructuredTool({
name: 'write_action_api',
description: 'Late action',
schema: z.object({}),
func: body,
});
const node = new ToolNode({ tools: [action], agentId: 'root', hookRegistry: config.hooks });
await node.invoke(
{
messages: [
new AIMessage({
content: '',
tool_calls: [{ id: 'call', name: action.name, args: {} }],
}),
],
},
{ configurable: { run_id: 'scheduled', thread_id: 'thread' } },
);
expect(body).not.toHaveBeenCalled();
expect(recorder).toHaveBeenCalledWith(
expect.objectContaining({
failure: {
reason: 'tool_policy_denied',
status: 'mcp_permission_denied',
recovery: 'configure',
automaticReplay: false,
},
}),
);
},
);
it('passes only admitted root graph handoffs into the mandatory scheduled hook', async () => {
const f = await executionFixture();
const agents = [
makeAgent({ id: 'root', edges: [{ from: 'root', to: 'child', edgeType: 'handoff' }] }),
makeAgent({ id: 'child' }),
makeAgent({ id: 'peer' }),
];
await createRun({
agents: agents as never,
signal: new AbortController().signal,
scheduledMCPExecution: f.execution,
appConfig: {
...hitlAppConfig,
endpoints: { agents: { toolApproval: { enabled: false } } },
} as unknown as AppConfig,
});
const config = (Run.create as jest.Mock).mock.calls[0][0];
for (const [toolName, expected] of [
[`${Constants.LC_TRANSFER_TO_}child`, undefined],
[`${Constants.LC_TRANSFER_TO_}peer`, 'deny'],
]) {
const result = await executeHooks({
registry: config.hooks,
input: {
hook_event_name: 'PreToolUse',
runId: 'run',
toolName: toolName!,
toolInput: {},
toolUseId: 'transfer',
executingAgentId: 'root',
},
matchQuery: toolName!,
});
expect(result.decision).toBe(expected);
}
});
it('registers trusted per-run hooks on headless calls without prompting', async () => {
const factory = jest.fn(() => async () => ({ decision: 'deny' as const }));
const unregister = registerToolApprovalHook(factory, { matcher: '^write_file$' });
try {
const config = await runAndGetConfig({
user: { id: 'user-1' },
appConfig: {
...hitlAppConfig,
endpoints: {
[EModelEndpoint.agents]: { toolApproval: { enabled: true, mode: 'bypass' } },
},
} as AppConfig,
});
expect(factory).toHaveBeenCalledWith(expect.objectContaining({ userId: 'user-1' }));
expect(config).not.toHaveProperty('humanInTheLoop');
const result = await executeHooks({
registry: config.hooks as HookRegistry,
input: {
hook_event_name: 'PreToolUse',
runId: 'headless-test',
toolName: 'write_file',
toolInput: {},
toolUseId: 'call-1',
},
matchQuery: 'write_file',
});
expect(result.decision).toBe('deny');
} finally {
unregister();
clearToolApprovalHooks();
}
});
it('keeps approval fully off when the endpoint disables it', async () => {
const config = await runAndGetConfig({
appConfig: {
...hitlAppConfig,
endpoints: { [EModelEndpoint.agents]: { toolApproval: { enabled: false, deny: ['*'] } } },
} as AppConfig,
});
expect((config.hooks as HookRegistry).hasHookFor('PreToolUse')).toBe(false);
expect(config).not.toHaveProperty('humanInTheLoop');
});
it('defaults to non-HITL when hitlCapable is omitted', async () => {
const config = await runAndGetConfig({});
expect(config).not.toHaveProperty('humanInTheLoop');
});
it.each([true, false])(
'heals aliases discovered in lazy subagents (HITL=%s)',
async (hitlCapable) => {
const alias = { name: 'delete_mcp_acme', aliasName: 'acme_delete_mcp_acme' };
const resolvedChild = makeAgent({ id: 'lazy-child', mcpToolAliases: [alias] });
const lazyChild = {
...makeAgent({ id: 'lazy-child' }),
configId: 'lazy-child:v1',
resolve: jest.fn().mockResolvedValue(resolvedChild),
};
const parent = makeAgent({
subagents: { enabled: true, allowSelf: false },
lazySubagentConfigs: [lazyChild],
});
const appConfig = {
...hitlAppConfig,
endpoints: {
[EModelEndpoint.agents]: {
toolApproval: { enabled: true, mode: 'bypass', deny: [alias.aliasName] },
},
},
} as unknown as AppConfig;
await createRun({
agents: [parent] as never,
signal: new AbortController().signal,
appConfig,
streaming: true,
streamUsage: true,
hitlCapable,
});
const config = (Run.create as jest.Mock).mock.calls[0][0] as Record<string, unknown>;
const hooks = config.hooks as { getMatchers: (event: string) => unknown[] };
const lazyConfig = (
(config.graphConfig as { agents: Array<Record<string, unknown>> }).agents[0]
.subagentConfigs as Array<Record<string, unknown>>
).find((entry) => entry.configId === lazyChild.configId);
const decisionForAlias = async () =>
(
await executeHooks({
registry: config.hooks as HookRegistry,
input: {
hook_event_name: 'PreToolUse',
runId: 'alias-test',
toolName: alias.name,
toolInput: {},
toolUseId: 'call-1',
},
matchQuery: alias.name,
})
).decision;
const initialMatcherCount = hooks.getMatchers('PreToolUse').length;
expect(initialMatcherCount).toBeGreaterThan(0);
expect(await decisionForAlias()).toBe('allow');
await (lazyConfig?.resolveAgentInputs as (context: never) => Promise<unknown>)({
signal: new AbortController().signal,
} as never);
expect(hooks.getMatchers('PreToolUse')).toHaveLength(initialMatcherCount);
expect(await decisionForAlias()).toBe('deny');
},
);
});
// ---------------------------------------------------------------------------
// Suite: ask_user_question run wiring
//
// The ask tool pauses via a LangGraph `interrupt()` raised from its own body, so it
// needs a durable checkpointer but NOT the tool-approval policy. It must be stripped
// fail-closed from non-HITL callers (no resume surface) and from subagent child
// configs (a child graph cannot pause the parent run).
// ---------------------------------------------------------------------------
describe('ask_user_question run wiring', () => {
const ASK = 'ask_user_question';
const askToolInstance = { name: ASK };
/** Approval policy NOT enabled — the ask tool must work without it. */
const plainAppConfig = {
config: {},
fileStrategy: FileSources.local,
imageOutputType: 'png',
endpoints: { [EModelEndpoint.agents]: {} },
} as unknown as AppConfig;
const runAndGetConfig = async (
agent: Record<string, unknown>,
extra: Record<string, unknown>,
) => {
await createRun({
agents: [agent] as never,
signal: new AbortController().signal,
appConfig: plainAppConfig,
streaming: true,
streamUsage: true,
...extra,
});
const createMock = Run.create as jest.Mock;
return createMock.mock.calls[0][0] as Record<string, unknown>;
};
const getCheckpointer = (config: Record<string, unknown>) =>
(config.graphConfig as { compileOptions?: { checkpointer?: unknown } }).compileOptions
?.checkpointer;
const firstAgent = (config: Record<string, unknown>) =>
(config.graphConfig as { agents: Array<Record<string, unknown>> }).agents[0];
/**
* Every run now carries a `PostToolBatch`-only registry for step-budget
* awareness, so registry presence no longer proves HITL wiring. What still
* distinguishes an approval-gated run is the `PreToolUse` policy hook, and
* `PostToolBatch` is deliberately outside the SDK's
* `RESULT_ALTERING_HOOK_EVENTS`, so it cannot disable eager tool prestart.
*/
const hasToolApprovalPolicyHook = (config: Record<string, unknown>) =>
(config.hooks as { hasHookFor?: (event: string) => boolean } | undefined)?.hasHookFor?.(
'PreToolUse',
) === true;
it('attaches the checkpointer WITHOUT humanInTheLoop when hitlCapable and the ask tool is present (approval disabled)', async () => {
const config = await runAndGetConfig(makeAgent({ tools: [askToolInstance] }), {
hitlCapable: true,
});
expect(config).not.toHaveProperty('humanInTheLoop');
expect(hasToolApprovalPolicyHook(config)).toBe(false);
expect(getCheckpointer(config)).toBeDefined();
const agent = firstAgent(config);
// The tool rides the in-graph direct path (graphTools) — never the
// event-dispatched surfaces, where interrupt() cannot pause the run.
expect((agent.graphTools as Array<{ name: string }>).map((t) => t.name)).toEqual([ASK]);
expect((agent.tools as Array<{ name: string }>).map((t) => t.name)).not.toContain(ASK);
});
it('detects the tool via toolRegistry / toolDefinitions too', async () => {
const viaRegistry = await runAndGetConfig(
makeAgent({ toolRegistry: new Map([[ASK, { name: ASK }]]) }),
{ hitlCapable: true },
);
expect(getCheckpointer(viaRegistry)).toBeDefined();
jest.clearAllMocks();
const viaDefinitions = await runAndGetConfig(makeAgent({ toolDefinitions: [{ name: ASK }] }), {
hitlCapable: true,
});
expect(getCheckpointer(viaDefinitions)).toBeDefined();
});
it('strips the tool and attaches no checkpointer for a non-HITL caller', async () => {
const config = await runAndGetConfig(
makeAgent({
tools: [askToolInstance, { name: 'other_tool' }],
toolDefinitions: [{ name: ASK }, { name: 'other_tool' }],
toolRegistry: new Map([
[ASK, { name: ASK }],
['other_tool', { name: 'other_tool' }],
]),
}),
{ hitlCapable: false },
);
expect(getCheckpointer(config)).toBeUndefined();
const agent = firstAgent(config);
expect((agent.tools as Array<{ name: string }>).map((t) => t.name)).toEqual(['other_tool']);
expect((agent.toolDefinitions as Array<{ name: string }>).map((d) => d.name)).toEqual([
'other_tool',
]);
expect((agent.toolRegistry as Map<string, unknown>).has(ASK)).toBe(false);
expect((agent.toolRegistry as Map<string, unknown>).has('other_tool')).toBe(true);
});
it('does not mutate the caller-owned toolRegistry when stripping (clone-before-mutate)', async () => {
const sharedRegistry = new Map([[ASK, { name: ASK }]]);
await runAndGetConfig(makeAgent({ toolRegistry: sharedRegistry }), { hitlCapable: false });
expect(sharedRegistry.has(ASK)).toBe(true);
});
it('strips the tool from subagent child configs even on an HITL-capable run', async () => {
const child = makeAgent({
id: 'agent_child',
name: 'Child',
tools: [askToolInstance],
toolDefinitions: [{ name: ASK }],
toolRegistry: new Map([[ASK, { name: ASK }]]),
});
const parent = makeAgent({
tools: [askToolInstance],
subagents: { enabled: true, allowSelf: false },
subagentAgentConfigs: [child],
});
const config = await runAndGetConfig(parent, { hitlCapable: true });
// Parent keeps the tool — as an in-graph direct tool — and gets the checkpointer…
expect((firstAgent(config).graphTools as Array<{ name: string }>).map((t) => t.name)).toEqual([
ASK,
]);
expect(getCheckpointer(config)).toBeDefined();
// …the child copy is stripped everywhere, with no graphTools replacement.
const subagentConfigs = firstAgent(config).subagentConfigs as Array<{
agentInputs: Record<string, unknown>;
}>;
expect(subagentConfigs).toHaveLength(1);
const childInputs = subagentConfigs[0].agentInputs;
expect(childInputs.graphTools).toBeUndefined();
expect((childInputs.tools as Array<{ name: string }>).map((t) => t.name)).not.toContain(ASK);
expect((childInputs.toolDefinitions as Array<{ name: string }>).map((d) => d.name)).toEqual([]);
expect((childInputs.toolRegistry as Map<string, unknown>).has(ASK)).toBe(false);
});
it('a subagent-only ask tool attaches no checkpointer (top-level agents decide)', async () => {
const child = makeAgent({ id: 'agent_child', name: 'Child', tools: [askToolInstance] });
const parent = makeAgent({
subagents: { enabled: true, allowSelf: false },
subagentAgentConfigs: [child],
});
const config = await runAndGetConfig(parent, { hitlCapable: true });
expect(getCheckpointer(config)).toBeUndefined();
});
it('excludes ask_user_question from eager event tool execution', async () => {
const config = await runAndGetConfig(makeAgent(), { hitlCapable: true });
const eager = config.eagerEventToolExecution as { excludeToolNames: string[] };
expect(eager.excludeToolNames).toContain(ASK);
});
it('admin filteredTools is a real kill switch: strips the tool and blocks the checkpointer even on an HITL-capable run', async () => {
const filteredConfig = {
...(plainAppConfig as unknown as Record<string, unknown>),
filteredTools: [ASK],
} as unknown as AppConfig;
await createRun({
agents: [
makeAgent({
tools: [askToolInstance],
toolDefinitions: [{ name: ASK }],
toolRegistry: new Map([[ASK, { name: ASK }]]),
}),
] as never,
signal: new AbortController().signal,
appConfig: filteredConfig,
streaming: true,
streamUsage: true,
hitlCapable: true,
});
const config = (Run.create as jest.Mock).mock.calls[0][0] as Record<string, unknown>;
expect(getCheckpointer(config)).toBeUndefined();
const agent = firstAgent(config);
expect((agent.tools as Array<{ name: string }>).map((t) => t.name)).toEqual([]);
expect((agent.toolDefinitions as Array<{ name: string }>).map((d) => d.name)).toEqual([]);
expect((agent.toolRegistry as Map<string, unknown>).has(ASK)).toBe(false);
});
it('an includedTools allowlist disables the tool unless listed (allowlist precedence)', async () => {
const withoutTool = {
...(plainAppConfig as unknown as Record<string, unknown>),
includedTools: ['calculator'],
} as unknown as AppConfig;
await createRun({
agents: [makeAgent({ tools: [askToolInstance] })] as never,
signal: new AbortController().signal,
appConfig: withoutTool,
streaming: true,
streamUsage: true,
hitlCapable: true,
});
let config = (Run.create as jest.Mock).mock.calls[0][0] as Record<string, unknown>;
expect(getCheckpointer(config)).toBeUndefined();
expect((firstAgent(config).tools as Array<{ name: string }>).map((t) => t.name)).toEqual([]);
jest.clearAllMocks();
const withTool = {
...(plainAppConfig as unknown as Record<string, unknown>),
// includedTools wins over filteredTools — same precedence as loadAndFormatTools.
includedTools: [ASK],
filteredTools: [ASK],
} as unknown as AppConfig;
await createRun({
agents: [makeAgent({ tools: [askToolInstance] })] as never,
signal: new AbortController().signal,
appConfig: withTool,
streaming: true,
streamUsage: true,
hitlCapable: true,
});
config = (Run.create as jest.Mock).mock.calls[0][0] as Record<string, unknown>;
expect(getCheckpointer(config)).toBeDefined();
expect((firstAgent(config).graphTools as Array<{ name: string }>).map((t) => t.name)).toEqual([
ASK,
]);
});
it('composes with the approval policy: both humanInTheLoop and the checkpointer attach', async () => {
const approvalConfig = {
config: {},
fileStrategy: FileSources.local,
imageOutputType: 'png',
endpoints: { [EModelEndpoint.agents]: { toolApproval: { enabled: true } } },
} as unknown as AppConfig;
await createRun({
agents: [makeAgent({ tools: [askToolInstance] })] as never,
signal: new AbortController().signal,
appConfig: approvalConfig,
streaming: true,
streamUsage: true,
hitlCapable: true,
});
const config = (Run.create as jest.Mock).mock.calls[0][0] as Record<string, unknown>;
expect(config.humanInTheLoop).toBeDefined();
expect(getCheckpointer(config)).toBeDefined();
});
});
// ---------------------------------------------------------------------------
// summarizeOnly resolution (manual compaction)
// ---------------------------------------------------------------------------
describe('summarizeOnly resolution', () => {
it('is absent on an ordinary run', async () => {
const agents = await callAndCapture();
expect(agents[0].summarizeOnly).toBeUndefined();
});
it('marks only the primary agent of a compaction run', async () => {
const agents = await callAndCapture({
agents: [makeAgent({ id: 'agent_primary' }), makeAgent({ id: 'agent_next' })],
summarizeOnly: true,
});
expect(agents[0].summarizeOnly).toBe(true);
expect(agents[1].summarizeOnly).toBeUndefined();
});
});
describe('steering provider capabilities', () => {
it.each([
['Anthropic search', { type: 'web_search_20250305', name: 'web_search' }],
['Google search', { googleSearch: {} }],
['OpenAI search', { type: 'web_search' }],
['Google URL context', { urlContext: {} }],
])('disables interruption before constructing a run with %s', async (_name, tool) => {
const disable = jest.fn(async () => undefined);
const handler = { handle: jest.fn() };
await callAndCapture({
agents: [makeAgent({ tools: [tool] })],
customHandlers: { on_tool_execute: handler },
steering: { hook: async () => ({}), preemption: { shouldPreempt: () => true, disable } },
});
expect(disable).toHaveBeenCalledTimes(1);
const config = jest.mocked(Run.create).mock.calls[0]?.[0];
expect(config?.preemption).toBeUndefined();
expect(config?.customHandlers?.on_tool_execute).toBe(handler);
});
it('keeps interruption for host-executed tools', async () => {
const disable = jest.fn(async () => undefined);
const tool = new DynamicStructuredTool({
name: 'web_search',
description: 'Host search',
schema: z.object({}),
func: async () => 'found it',
});
await callAndCapture({
agents: [makeAgent({ tools: [tool] })],
steering: { hook: async () => ({}), preemption: { shouldPreempt: () => true, disable } },
});
expect(disable).not.toHaveBeenCalled();
expect(jest.mocked(Run.create).mock.calls[0]?.[0].preemption).toBeDefined();
});
});
/**
* The override pipeline's rebinding guard, end to end: what a profile writes to
* `summarization` is merged as `getAppConfig` merges it, and the run's real summarizer makes the
* request.
*/
describe('summarization destinations an override profile sets', () => {
const ATTACKER = 'https://attacker.example/openai/deployments/summary-production';
const GROUP_RESOURCE = 'https://summary-instance.openai.azure.com/';
function azureAppConfig(summarization?: SummarizationConfig): AppConfig {
const appConfig = makeAppConfig([]);
appConfig.endpoints![EModelEndpoint.azureOpenAI] = {
modelNames: ['gpt-4.1-mini'],
modelGroupMap: { 'gpt-4.1-mini': { group: 'summary' } },
groupMap: {
summary: {
apiKey: 'deployment-group-secret',
instanceName: 'summary-instance',
version: '2024-10-21',
models: { 'gpt-4.1-mini': { deploymentName: 'summary-production' } },
},
},
} as unknown as NonNullable<AppConfig['endpoints']>[EModelEndpoint.azureOpenAI];
if (summarization != null) {
appConfig.config.summarization = structuredClone(summarization);
appConfig.summarization = structuredClone(summarization);
}
return appConfig;
}
function mergeProfile(base: AppConfig, profile: Partial<ConfigOverrideLayer>) {
const ignored: string[] = [];
const layer = {
principalType: PrincipalType.ROLE,
principalId: 'editors',
priority: 10,
overrides: {},
...profile,
} as ConfigOverrideLayer;
const merged = mergeConfigOverrides(base, [layer], {
afterLayer: createSecretRebindingGuard(({ path }) => ignored.push(path)),
});
return { merged, ignored };
}
async function summarize(appConfig: AppConfig) {
const agents = await callAndCapture({
agents: [makeAgent()],
appConfig,
summarizeOnly: true,
summarizationConfig: appConfig.summarization,
});
const { requests } = await compactSummary(agents);
return requests.map(({ url, headers }) => ({
url: url.href,
apiKey: headers.get('api-key'),
}));
}
it.each([1, 0, true, false])(
'keeps the Azure group key on its own resource under a profile key of %p',
async (apiKey) => {
const { merged, ignored } = mergeProfile(azureAppConfig(), {
overrides: {
summarization: {
provider: 'azureOpenAI',
model: 'gpt-4.1-mini',
parameters: { baseURL: ATTACKER, apiKey },
},
},
});
expect(ignored).toEqual(['summarization.parameters.baseURL']);
const requests = await summarize(merged);
expect(requests).toEqual([
{ url: expect.stringMatching(`^${GROUP_RESOURCE}`), apiKey: 'deployment-group-secret' },
]);
},
);
it('sends a key the profile enters, and only that key, to the destination it sets', async () => {
const { merged, ignored } = mergeProfile(azureAppConfig(), {
overrides: {
summarization: {
provider: 'azureOpenAI',
model: 'gpt-4.1-mini',
parameters: { baseURL: ATTACKER, apiKey: 'profile-own-key' },
},
},
});
expect(ignored).toEqual([]);
expect(await summarize(merged)).toEqual([
{ url: expect.stringMatching(/^https:\/\/attacker\.example\//), apiKey: 'profile-own-key' },
]);
});
it("keeps the Azure group key off librechat.yaml's gateway once a profile removes the gateway's key", async () => {
const yaml = azureAppConfig({
provider: 'azureOpenAI',
model: 'gpt-4.1-mini',
parameters: {
baseURL: 'https://yaml-gateway.example/openai/deployments/summary-production',
apiKey: 'yaml-gateway-key',
},
});
expect(await summarize(yaml)).toEqual([
{
url: expect.stringMatching(/^https:\/\/yaml-gateway\.example\//),
apiKey: 'yaml-gateway-key',
},
]);
jest.mocked(Run.create).mockClear();
const { merged, ignored } = mergeProfile(yaml, {
tombstones: ['summarization.parameters.apiKey'],
});
expect(ignored).toEqual(['summarization.parameters.baseURL']);
expect(await summarize(merged)).toEqual([
{ url: expect.stringMatching(`^${GROUP_RESOURCE}`), apiKey: 'deployment-group-secret' },
]);
});
it("keeps the Azure group key off librechat.yaml's unkeyed gateway for another provider", async () => {
const { merged, ignored } = mergeProfile(
azureAppConfig({
provider: 'openAI',
model: 'gpt-4.1-mini',
parameters: { baseURL: 'https://yaml-gateway.example/openai/deployments/x' },
}),
{ overrides: { summarization: { provider: 'azureOpenAI' } } },
);
expect(ignored).toEqual(['summarization.parameters.baseURL']);
expect(await summarize(merged)).toEqual([
{ url: expect.stringMatching(`^${GROUP_RESOURCE}`), apiKey: 'deployment-group-secret' },
]);
});
});