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 { getRequestId, getTenantId, getUserId } from '@librechat/data-schemas';
import { Constants, EModelEndpoint, ReasoningEffort } from 'librechat-data-provider';
import type { AgentTriggerExecutionHostDeps, AgentTriggerFetch } from './host';
import {
EVENT_ACTOR_DETACHED_COMPLETION_SOURCE,
EVENT_ACTOR_DETACHED_COMPLETION_TYPE,
} from './detachedAction';
import { createAgentTriggerEnvelope, getAgentTriggerIdempotencyKey } from './envelope';
import { AgentTriggerExecutionError, createAgentTriggerExecutionHost } from './host';
const createFireEnvelope = () =>
createAgentTriggerEnvelope({
mode: 'fire',
requestId: 'request-1',
deliveryId: 'delivery-1',
receivedAt: 20,
principal: { id: 'user-1', role: 'member', tenantId: 'tenant-1' },
target: { agentId: 'agent-1' },
run: {
conversationId: 'scheduled-conversation-1',
timezone: 'Europe/Paris',
chatProjectId: 'project-1',
files: [{ file_id: 'file-1' }],
metadata: { manual: false },
},
event: {
id: 'event-1',
type: 'resource.ready',
occurredAt: 10,
source: { id: 'source-1', type: 'webhook' },
payload: { resourceId: 'resource-1' },
},
input: 'Handle the ready resource.',
});
const createSteerEnvelope = () =>
createAgentTriggerEnvelope({
mode: 'steer',
requestId: 'request-2',
deliveryId: 'delivery-2',
receivedAt: 30,
principal: { id: 'user-1', role: 'member', tenantId: 'tenant-1' },
target: {
agentId: 'agent-1',
conversationId: 'conversation-1',
generationCreatedAt: 25,
preempt: true,
},
event: {
id: 'event-2',
type: 'opponent.moved',
occurredAt: 21,
source: { id: 'game-1', type: 'mcp' },
},
input: 'The opponent moved. Take your turn.',
});
const createContinueEnvelope = () =>
createAgentTriggerEnvelope({
mode: 'continue',
requestId: 'request-3',
deliveryId: 'delivery-3',
receivedAt: 35,
principal: { id: 'user-1', role: 'member', tenantId: 'tenant-1' },
target: {
agentId: 'agent-1',
conversationId: 'conversation-1',
parentMessageId: 'response-1',
},
event: {
id: 'event-3',
type: 'subagent.completed',
occurredAt: 31,
source: { id: 'subagent-completion', type: 'internal' },
},
input: 'Collect the completed child task.',
});
function response(payload: unknown, init?: ResponseInit): Response {
return new Response(JSON.stringify(payload), {
status: 200,
headers: { 'content-type': 'application/json' },
...init,
});
}
function fetchMock(implementation: AgentTriggerFetch): jest.MockedFunction<AgentTriggerFetch> {
return jest.fn(implementation);
}
function deps(
fetcher: jest.MockedFunction<AgentTriggerFetch>,
overrides: Partial<AgentTriggerExecutionHostDeps> = {},
): AgentTriggerExecutionHostDeps {
return {
getBaseUrl: () => 'http://127.0.0.1:3080',
mintToken: () => 'signed-token',
fetch: fetcher,
...overrides,
};
}
function expectExecutionError(error: unknown, expected: Partial<AgentTriggerExecutionError>): void {
expect(error).toBeInstanceOf(AgentTriggerExecutionError);
expect(error).toMatchObject(expected);
}
describe('createAgentTriggerExecutionHost fire adapter', () => {
it('rejects malformed serialized envelopes through its promise contract', async () => {
const host = createAgentTriggerExecutionHost(deps(fetchMock(async () => response({}))));
const malformed = { ...createFireEnvelope() };
Reflect.deleteProperty(malformed, 'requestId');
await expect(host.dispatch(malformed)).rejects.toThrow('requestId must be a non-empty string');
});
it('starts a new run with stable identity, principal context, and no source coupling', async () => {
const envelope = createFireEnvelope();
const idempotencyKey = getAgentTriggerIdempotencyKey(envelope);
const fetcher = fetchMock(async () =>
response({
streamId: 'stream-1',
conversationId: 'conversation-1',
generationCreatedAt: 40,
status: 'started',
}),
);
const mintToken = jest.fn(() => {
expect(getUserId()).toBe('user-1');
expect(getTenantId()).toBe('tenant-1');
expect(getRequestId()).toBe(idempotencyKey);
return 'signed-token';
});
const host = createAgentTriggerExecutionHost(
deps(fetcher, {
getBaseUrl: () => 'https://chat.example.test/base/?ignored=true',
mintToken,
getTimezone: async () => ' America/New_York ',
}),
);
await expect(host.dispatch(envelope)).resolves.toEqual({
mode: 'fire',
streamId: 'stream-1',
conversationId: 'conversation-1',
generationCreatedAt: 40,
status: 'started',
});
expect(fetcher).toHaveBeenCalledTimes(1);
const [input, init] = fetcher.mock.calls[0];
expect(String(input)).toBe('https://chat.example.test/base/api/agents/chat/agents');
const headers = new Headers(init?.headers);
expect(headers.get('authorization')).toBe('Bearer signed-token');
expect(headers.get('x-lc-agent-trigger')).toBe('1');
expect(headers.get('x-request-id')).toBe(idempotencyKey);
expect(headers.get('x-librechat-generation-protocol')).toBe('2');
expect(headers.get('user-agent')).toContain('LibreChat-Agent-Trigger/1');
expect(JSON.parse(String(init?.body))).toEqual({
text: envelope.input,
endpoint: EModelEndpoint.agents,
agent_id: envelope.target.agentId,
parentMessageId: Constants.NO_PARENT,
isContinued: false,
isRegenerate: false,
clientRequestId: idempotencyKey,
generationProtocolVersion: 2,
agentTrigger: {
version: envelope.version,
deliveryId: envelope.deliveryId,
event: {
id: envelope.event.id,
type: envelope.event.type,
occurredAt: envelope.event.occurredAt,
source: envelope.event.source,
},
metadata: { manual: false },
},
newConversationId: 'scheduled-conversation-1',
chatProjectId: 'project-1',
files: [{ file_id: 'file-1' }],
timezone: 'Europe/Paris',
});
expect(mintToken).toHaveBeenCalledWith(envelope.principal, envelope);
});
it('reuses the same generation identity when an ambiguous delivery is retried', async () => {
const envelope = createFireEnvelope();
const fetcher = fetchMock(
jest
.fn()
.mockResolvedValueOnce(
response({
streamId: 'stream-1',
conversationId: 'conversation-1',
generationCreatedAt: 40,
status: 'started',
}),
)
.mockResolvedValueOnce(
response({
streamId: 'stream-1',
conversationId: 'conversation-1',
generationCreatedAt: 40,
status: 'resumed',
}),
),
);
const host = createAgentTriggerExecutionHost(deps(fetcher));
await host.dispatch(envelope);
await expect(host.dispatch(envelope)).resolves.toMatchObject({
status: 'resumed',
conversationId: 'conversation-1',
});
const bodies = fetcher.mock.calls.map(([, init]) => JSON.parse(String(init?.body)) as unknown);
expect(bodies).toEqual([
expect.objectContaining({
clientRequestId: getAgentTriggerIdempotencyKey(envelope),
}),
expect.objectContaining({
clientRequestId: getAgentTriggerIdempotencyKey(envelope),
}),
]);
});
it('classifies a server rejection as definite and preserves retry guidance', async () => {
expect.hasAssertions();
const fetcher = fetchMock(async () =>
response(
{ code: 'SERVER_NOT_READY', error: 'Try shortly.' },
{ status: 503, headers: { 'retry-after': '2' } },
),
);
const host = createAgentTriggerExecutionHost(deps(fetcher));
await host.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'fire',
certainty: 'definite',
retryable: true,
code: 'SERVER_NOT_READY',
status: 503,
retryAfter: '2',
});
});
});
it('does not mark an authorization rejection retryable', async () => {
expect.hasAssertions();
const fetcher = fetchMock(async () => response({ code: 'FORBIDDEN' }, { status: 403 }));
const host = createAgentTriggerExecutionHost(deps(fetcher));
await host.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
certainty: 'definite',
retryable: false,
code: 'FORBIDDEN',
status: 403,
});
});
});
it('retries an expired delivery token so the next attempt can remint it', async () => {
expect.hasAssertions();
const fetcher = fetchMock(async () => response({ code: 'UNAUTHORIZED' }, { status: 401 }));
const host = createAgentTriggerExecutionHost(deps(fetcher));
await host.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'fire',
certainty: 'definite',
retryable: true,
code: 'UNAUTHORIZED',
status: 401,
});
});
});
it('treats malformed success as ambiguous because the generation may have started', async () => {
expect.hasAssertions();
const fetcher = fetchMock(async () => response({ status: 'started' }));
const host = createAgentTriggerExecutionHost(deps(fetcher));
await host.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'fire',
certainty: 'ambiguous',
retryable: true,
code: 'INVALID_RESPONSE',
status: 200,
});
});
});
it('keeps the timeout active while reading the accepted response body', async () => {
expect.hasAssertions();
const fetcher = fetchMock(async (_input, init) => {
const signal = init?.signal;
return new Response(
new ReadableStream({
start(controller) {
const abort = () => controller.error(new Error('body aborted'));
if (signal?.aborted === true) {
abort();
} else {
signal?.addEventListener('abort', abort, { once: true });
}
},
}),
);
});
const host = createAgentTriggerExecutionHost(deps(fetcher, { timeoutMs: 10 }));
await host.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
certainty: 'ambiguous',
retryable: true,
code: 'TIMEOUT',
status: 200,
});
});
});
it('applies the timeout while asynchronous setup is still pending', async () => {
expect.hasAssertions();
const fetcher = fetchMock(async () => response({}));
const host = createAgentTriggerExecutionHost(
deps(fetcher, {
mintToken: () => new Promise<string>(() => undefined),
timeoutMs: 10,
}),
);
await host.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'fire',
certainty: 'definite',
retryable: true,
code: 'TIMEOUT',
});
});
expect(fetcher).not.toHaveBeenCalled();
});
it('releases a prepared result that arrives after setup has timed out', async () => {
let finishPreparation!: (value: {
status: 'ready';
input: string;
parentMessageId: string;
releaseOnDefiniteFailure: () => Promise<void>;
}) => void;
const preparation = new Promise<{
status: 'ready';
input: string;
parentMessageId: string;
releaseOnDefiniteFailure: () => Promise<void>;
}>((resolve) => {
finishPreparation = resolve;
});
const releaseOnDefiniteFailure = jest.fn(async () => undefined);
const fetcher = fetchMock(async () => response({}));
const host = createAgentTriggerExecutionHost(
deps(fetcher, {
prepareContinue: () => preparation,
timeoutMs: 10,
}),
);
await expect(host.dispatch(createContinueEnvelope())).rejects.toMatchObject({
mode: 'continue',
certainty: 'definite',
retryable: true,
code: 'TIMEOUT',
});
finishPreparation({
status: 'ready',
input: 'late durable child result',
parentMessageId: 'response-1',
releaseOnDefiniteFailure,
});
await new Promise<void>((resolve) => setImmediate(resolve));
expect(releaseOnDefiniteFailure).toHaveBeenCalledTimes(1);
expect(fetcher).not.toHaveBeenCalled();
});
it('starts independent token, timezone, and origin setup concurrently', async () => {
let resolveToken!: (value: string) => void;
let resolveTimezone!: (value: string) => void;
const token = new Promise<string>((resolve) => {
resolveToken = resolve;
});
const timezone = new Promise<string>((resolve) => {
resolveTimezone = resolve;
});
const mintToken = jest.fn(() => token);
const getTimezone = jest.fn(() => timezone);
const getBaseUrl = jest.fn(() => 'http://127.0.0.1:3080');
const fetcher = fetchMock(async () =>
response({
status: 'started',
streamId: 'stream-1',
conversationId: 'conversation-1',
}),
);
const host = createAgentTriggerExecutionHost({
mintToken,
getTimezone,
getBaseUrl,
fetch: fetcher,
});
const pending = host.dispatch(createFireEnvelope());
await Promise.resolve();
await Promise.resolve();
expect(mintToken).toHaveBeenCalledTimes(1);
expect(getTimezone).toHaveBeenCalledTimes(1);
expect(getBaseUrl).toHaveBeenCalledTimes(1);
expect(fetcher).not.toHaveBeenCalled();
resolveToken('signed-token');
resolveTimezone('UTC');
await expect(pending).resolves.toMatchObject({
mode: 'fire',
status: 'started',
});
});
it('observes caller cancellation while asynchronous setup is pending', async () => {
expect.hasAssertions();
const fetcher = fetchMock(async () => response({}));
const host = createAgentTriggerExecutionHost(
deps(fetcher, { mintToken: () => new Promise<string>(() => undefined) }),
);
const controller = new AbortController();
const pending = host.dispatch(createFireEnvelope(), {
signal: controller.signal,
});
controller.abort();
await pending.catch((error: unknown) => {
expectExecutionError(error, {
mode: 'fire',
certainty: 'definite',
retryable: true,
code: 'ABORTED',
});
});
expect(fetcher).not.toHaveBeenCalled();
});
it('marks thrown setup dependency failures retryable without sending', async () => {
expect.hasAssertions();
const fetcher = fetchMock(async () => response({}));
const host = createAgentTriggerExecutionHost(
deps(fetcher, {
mintToken: () => new Promise<string>(() => undefined),
getTimezone: async () => Promise.reject(new Error('timezone store unavailable')),
}),
);
await host.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'fire',
certainty: 'definite',
retryable: true,
code: 'SETUP_FAILED',
});
});
expect(fetcher).not.toHaveBeenCalled();
});
it('cancels an oversized success body instead of buffering it without a bound', async () => {
expect.hasAssertions();
const host = createAgentTriggerExecutionHost(
deps(fetchMock(async () => response({ padding: 'x'.repeat(70 * 1024) }))),
);
await host.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'fire',
certainty: 'ambiguous',
retryable: true,
code: 'RESPONSE_TOO_LARGE',
status: 200,
});
});
});
it('rejects invalid host configuration before making a network request', async () => {
const fetcher = fetchMock(async () => response({}));
const host = createAgentTriggerExecutionHost(
deps(fetcher, { getBaseUrl: () => 'file:///tmp/not-http' }),
);
await host.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
certainty: 'definite',
retryable: false,
code: 'INVALID_BASE_URL',
});
});
expect(fetcher).not.toHaveBeenCalled();
});
it('distinguishes pre-connect failures from unknown network outcomes', async () => {
expect.hasAssertions();
const refused = new TypeError('fetch failed');
Object.assign(refused, { cause: { code: 'ECONNREFUSED' } });
const preconnect = createAgentTriggerExecutionHost(
deps(fetchMock(async () => Promise.reject(refused))),
);
const reset = createAgentTriggerExecutionHost(
deps(fetchMock(async () => Promise.reject(new TypeError('connection reset')))),
);
await preconnect.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
certainty: 'definite',
retryable: true,
code: 'NETWORK_ERROR',
});
});
await reset.dispatch(createFireEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
certainty: 'ambiguous',
retryable: true,
code: 'NETWORK_ERROR',
});
});
});
it('does not send when the delivery was already aborted', async () => {
const fetcher = fetchMock(async () => response({}));
const host = createAgentTriggerExecutionHost(deps(fetcher));
const controller = new AbortController();
controller.abort();
await host
.dispatch(createFireEnvelope(), { signal: controller.signal })
.catch((error: unknown) => {
expectExecutionError(error, {
certainty: 'definite',
retryable: true,
code: 'ABORTED',
});
});
expect(fetcher).not.toHaveBeenCalled();
});
});
describe('createAgentTriggerExecutionHost continue adapter', () => {
it('appends an idempotent turn to the exact existing conversation branch', async () => {
const envelope = createContinueEnvelope();
const idempotencyKey = getAgentTriggerIdempotencyKey(envelope);
const fetcher = fetchMock(async () =>
response({
streamId: 'conversation-1',
conversationId: 'conversation-1',
generationCreatedAt: 50,
status: 'started',
}),
);
const host = createAgentTriggerExecutionHost(deps(fetcher));
await expect(host.dispatch(envelope)).resolves.toEqual({
mode: 'continue',
streamId: 'conversation-1',
conversationId: 'conversation-1',
generationCreatedAt: 50,
status: 'started',
});
const [input, init] = fetcher.mock.calls[0];
expect(String(input)).toBe('http://127.0.0.1:3080/api/agents/chat/agents');
expect(JSON.parse(String(init?.body))).toEqual({
agentCompletion: { version: 1, sourceId: 'subagent-completion' },
text: envelope.input,
endpoint: EModelEndpoint.agents,
agent_id: 'agent-1',
parentMessageId: 'response-1',
conversationId: 'conversation-1',
isContinued: false,
isRegenerate: false,
clientRequestId: idempotencyKey,
generationProtocolVersion: 2,
});
});
it.each([undefined, 'ask', 'acceptEdits', 'fullAccess'] as const)(
'forwards prepared coding mode %s without trusting the event payload',
async (mode) => {
const envelope = createContinueEnvelope();
envelope.event.payload = { codeApprovalMode: 'fullAccess' };
const fetcher = fetchMock(async () =>
response({
streamId: 'conversation-1',
conversationId: 'conversation-1',
status: 'started',
}),
);
const host = createAgentTriggerExecutionHost(
deps(fetcher, {
prepareContinue: async () => ({
status: 'ready',
input: 'durable result',
parentMessageId: 'response-1',
codeApprovalMode: mode,
}),
}),
);
await host.dispatch(envelope);
const body = JSON.parse(String(fetcher.mock.calls[0][1]?.body));
expect(body.codeApprovalMode).toBe(mode);
if (mode === undefined) expect(body).not.toHaveProperty('codeApprovalMode');
},
);
it('carries a prepared queued-turn payload and settles it after admission', async () => {
const envelope = createContinueEnvelope();
envelope.event.payload = { codeApprovalMode: 'fullAccess' };
const admitted = {
mode: 'continue' as const,
streamId: 'conversation-1',
conversationId: 'conversation-1',
generationCreatedAt: 50,
status: 'started' as const,
};
const settleOnAdmission = jest.fn(async () => undefined);
const getBaseUrl = jest.fn(() => 'http://127.0.0.1:3080');
const admissionSource = {
source: 'agent-queued-turn',
sourceId: 'queued-turn-1',
claimId: 'queued-delivery-1',
claimBy: 'queued-worker-1',
};
const prepareContinue = jest.fn(async () => ({
status: 'ready' as const,
input: 'queued user turn',
parentMessageId: 'latest-response',
expectedPredecessorCreatedAt: 49,
files: [{ file_id: 'file-1' }],
quotes: ['quoted context'],
manualSkills: ['research'],
codeApprovalMode: 'acceptEdits' as const,
reasoningOverride: { key: 'reasoning_effort' as const, value: ReasoningEffort.high },
admissionSource,
settleOnAdmission,
}));
const fetcher = fetchMock(async () => response(admitted));
const host = createAgentTriggerExecutionHost(
deps(fetcher, {
prepareContinue,
getBaseUrl,
}),
);
await expect(host.dispatch(envelope, { attempt: 3, maxAttempts: 3 })).resolves.toEqual(
admitted,
);
expect(JSON.parse(String(fetcher.mock.calls[0][1]?.body))).toMatchObject({
text: 'queued user turn',
parentMessageId: 'latest-response',
expectedPredecessorCreatedAt: 49,
files: [{ file_id: 'file-1' }],
quotes: ['quoted context'],
manualSkills: ['research'],
codeApprovalMode: 'acceptEdits',
reasoningOverride: { key: 'reasoning_effort', value: ReasoningEffort.high },
agentContinuationAdmission: admissionSource,
});
expect(getBaseUrl).toHaveBeenCalledWith({ localOnly: true });
expect(prepareContinue).toHaveBeenCalledWith(envelope, {
idempotencyKey: getAgentTriggerIdempotencyKey(envelope),
attempt: 3,
maxAttempts: 3,
});
expect(settleOnAdmission).toHaveBeenCalledWith(admitted);
});
it('keeps a prepared queued turn claimed when admission settlement is unavailable', async () => {
const releaseOnDefiniteFailure = jest.fn(async () => undefined);
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () =>
response({
mode: 'continue',
streamId: 'conversation-1',
conversationId: 'conversation-1',
status: 'started',
}),
),
{
prepareContinue: async () => ({
status: 'ready',
input: 'queued user turn',
parentMessageId: 'response-1',
releaseOnDefiniteFailure,
settleOnAdmission: async () => {
throw new Error('mongo unavailable');
},
}),
},
),
);
await expect(host.dispatch(createContinueEnvelope())).rejects.toMatchObject({
certainty: 'ambiguous',
retryable: true,
code: 'PREPARATION_SETTLEMENT_FAILED',
});
expect(releaseOnDefiniteFailure).not.toHaveBeenCalled();
});
it('carries server-resolved binding identity only on bound child continuations', async () => {
const base = createContinueEnvelope();
if (base.mode !== 'continue') {
throw new Error('Expected a continue envelope');
}
const envelope = {
...base,
event: { ...base.event, payload: { blob: 'x'.repeat(4096) } },
expectedAction: {
toolName: 'submit_move',
argumentSubset: { gameId: 'game-1', expectedPly: 7 },
},
target: {
...base.target,
bindingId: `evtbind_${'a'.repeat(48)}`,
sourceKeyId: 'source-key',
},
};
const fetcher = fetchMock(async () =>
response({
streamId: 'conversation-1',
conversationId: 'conversation-1',
status: 'started',
}),
);
await createAgentTriggerExecutionHost(deps(fetcher)).dispatch(envelope);
const headers = fetcher.mock.calls[0][1]?.headers as Record<string, string>;
expect(headers['x-lc-agent-event-binding']).toBe(`evtbind_${'a'.repeat(48)}`);
expect(headers['x-lc-agent-event-source-key']).toBe('source-key');
/** The unbounded source payload never rides the delivery body; the actor
* binds an invocation from event identity alone. */
expect(JSON.parse(String(fetcher.mock.calls[0][1]?.body))).toMatchObject({
agentEventDelivery: {
deliveryKey: getAgentTriggerIdempotencyKey(envelope),
event: {
id: envelope.event.id,
type: envelope.event.type,
occurredAt: envelope.event.occurredAt,
source: envelope.event.source,
},
expectedAction: envelope.expectedAction,
},
});
expect(
JSON.parse(String(fetcher.mock.calls[0][1]?.body)).agentEventDelivery.event,
).not.toHaveProperty('payload');
});
it('projects only the bounded internal detached-completion authority', async () => {
const base = createContinueEnvelope();
if (base.mode !== 'continue') {
throw new Error('Expected a continue envelope');
}
const completion = {
version: 1 as const,
invocationId: 'original-delivery-1',
generationCreatedAt: 1_787_000_000_000,
wakeGenerationCreatedAt: 1_787_000_000_000,
taskId: 'event-actor-task-1',
idempotencyKey: 'a'.repeat(64),
};
const envelope = {
...base,
target: {
...base.target,
bindingId: 'binding-1',
sourceKeyId: 'source-key-1',
},
event: {
id: completion.taskId,
type: EVENT_ACTOR_DETACHED_COMPLETION_TYPE,
occurredAt: completion.generationCreatedAt + 1,
source: {
id: EVENT_ACTOR_DETACHED_COMPLETION_SOURCE,
type: 'internal',
},
payload: completion,
},
expectedAction: { toolName: 'submit_move' },
};
const fetcher = fetchMock(async () =>
response({
streamId: 'conversation-1',
conversationId: 'conversation-1',
generationCreatedAt: completion.generationCreatedAt + 2,
status: 'started',
}),
);
const getBaseUrl = jest.fn(() => 'http://127.0.0.1:3080');
await createAgentTriggerExecutionHost(deps(fetcher, { getBaseUrl })).dispatch(envelope);
expect(getBaseUrl).toHaveBeenCalledWith({ localOnly: true });
const body = JSON.parse(String(fetcher.mock.calls[0][1]?.body));
expect(body.clientRequestId).toBe(getAgentTriggerIdempotencyKey(envelope));
expect(body.agentEventDelivery).toMatchObject({
deliveryKey: getAgentTriggerIdempotencyKey(envelope),
internalCompletion: completion,
});
expect(body.agentEventDelivery.event).not.toHaveProperty('payload');
});
it.each(['PARENT_NOT_READY', 'EVENT_ACTOR_NOT_READY'])(
'retries without consuming the logical delivery for temporary admission code %s',
async (code) => {
expect.hasAssertions();
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () =>
response({ code, error: 'The actor is still busy.' }, { status: 409 }),
),
),
);
await host.dispatch(createContinueEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'continue',
certainty: 'definite',
retryable: true,
deferWithoutAttempt: true,
code,
status: 409,
});
});
},
);
it('releases a prepared durable result after a definite admission rejection', async () => {
const releaseOnDefiniteFailure = jest.fn(async () => undefined);
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () => response({ code: 'AGENT_NOT_FOUND' }, { status: 404 })),
{
prepareContinue: async () => ({
status: 'ready',
input: 'durable child result',
parentMessageId: 'response-1',
releaseOnDefiniteFailure,
}),
},
),
);
await expect(host.dispatch(createContinueEnvelope())).rejects.toMatchObject({
certainty: 'definite',
code: 'AGENT_NOT_FOUND',
});
expect(releaseOnDefiniteFailure).toHaveBeenCalledTimes(1);
});
it('retains a prepared durable result after an ambiguous admission outcome', async () => {
const releaseOnDefiniteFailure = jest.fn(async () => undefined);
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () => Promise.reject(new Error('connection reset'))),
{
prepareContinue: async () => ({
status: 'ready',
input: 'durable child result',
parentMessageId: 'response-1',
releaseOnDefiniteFailure,
}),
},
),
);
await expect(host.dispatch(createContinueEnvelope())).rejects.toMatchObject({
certainty: 'ambiguous',
code: 'NETWORK_ERROR',
});
expect(releaseOnDefiniteFailure).not.toHaveBeenCalled();
});
it('retains a prepared durable result when a retry gets a definite 5xx response', async () => {
const releaseOnDefiniteFailure = jest.fn(async () => undefined);
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () =>
response(
{ code: 'SERVER_NOT_READY', error: 'Generation is finalizing.' },
{ status: 503, headers: { 'retry-after': '1' } },
),
),
{
prepareContinue: async () => ({
status: 'ready',
input: 'durable child result',
parentMessageId: 'response-1',
releaseOnDefiniteFailure,
}),
},
),
);
await expect(host.dispatch(createContinueEnvelope())).rejects.toMatchObject({
certainty: 'definite',
retryable: true,
code: 'SERVER_NOT_READY',
status: 503,
});
expect(releaseOnDefiniteFailure).not.toHaveBeenCalled();
});
it('releases a prepared durable result when parent state fails before admission', async () => {
const releaseOnDefiniteFailure = jest.fn(async () => undefined);
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () =>
response(
{
code: 'PARENT_STATE_UNAVAILABLE',
error: 'Parent state is unavailable.',
},
{ status: 503, headers: { 'retry-after': '1' } },
),
),
{
prepareContinue: async () => ({
status: 'ready',
input: 'durable child result',
parentMessageId: 'response-1',
releaseOnDefiniteFailure,
}),
},
),
);
await expect(host.dispatch(createContinueEnvelope())).rejects.toMatchObject({
certainty: 'definite',
retryable: true,
code: 'PARENT_STATE_UNAVAILABLE',
status: 503,
});
expect(releaseOnDefiniteFailure).toHaveBeenCalledTimes(1);
});
it('retains a prepared durable result when an earlier admitted run was replaced', async () => {
const releaseOnDefiniteFailure = jest.fn(async () => undefined);
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () => response({ code: 'RUN_REPLACED' }, { status: 409 })),
{
prepareContinue: async () => ({
status: 'ready',
input: 'durable child result',
parentMessageId: 'response-1',
releaseOnDefiniteFailure,
}),
},
),
);
await expect(host.dispatch(createContinueEnvelope())).rejects.toMatchObject({
certainty: 'definite',
retryable: false,
code: 'RUN_REPLACED',
status: 409,
});
expect(releaseOnDefiniteFailure).not.toHaveBeenCalled();
});
it('rejects a mismatched continued conversation as an ambiguous outcome', async () => {
expect.hasAssertions();
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () =>
response({
streamId: 'other',
conversationId: 'other',
status: 'started',
}),
),
),
);
await host.dispatch(createContinueEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'continue',
certainty: 'ambiguous',
retryable: true,
code: 'INVALID_RESPONSE',
});
});
});
});
describe('createAgentTriggerExecutionHost steer adapter', () => {
it('steers through the authenticated admission route with a strict v2 receipt', async () => {
const envelope = createSteerEnvelope();
const idempotencyKey = getAgentTriggerIdempotencyKey(envelope);
const mintToken = jest.fn(() => {
expect(getUserId()).toBe('user-1');
expect(getTenantId()).toBe('tenant-1');
expect(getRequestId()).toBe(idempotencyKey);
return 'signed-token';
});
const fetcher = fetchMock(async () =>
response(
{
status: 'queued',
conversationId: 'conversation-1',
steerId: 'steer-1',
position: 1,
preempt: true,
preemptRevision: 4,
generationProtocolVersion: 2,
},
{ status: 202 },
),
);
const host = createAgentTriggerExecutionHost(
deps(fetcher, {
getBaseUrl: () => 'https://chat.example.test/base/',
mintToken,
}),
);
await expect(host.dispatch(envelope)).resolves.toEqual({
mode: 'steer',
status: 'queued',
conversationId: 'conversation-1',
steerId: 'steer-1',
position: 1,
preempt: true,
preemptRevision: 4,
});
expect(fetcher).toHaveBeenCalledTimes(1);
const [input, init] = fetcher.mock.calls[0];
expect(String(input)).toBe('https://chat.example.test/base/api/agents/chat/steer/deliver');
const headers = new Headers(init?.headers);
expect(headers.get('authorization')).toBe('Bearer signed-token');
expect(headers.get('x-lc-agent-trigger')).toBe('1');
expect(headers.get('x-request-id')).toBe(idempotencyKey);
expect(headers.get('x-librechat-generation-protocol')).toBe('2');
expect(JSON.parse(String(init?.body))).toEqual({
agentId: 'agent-1',
conversationId: 'conversation-1',
generationCreatedAt: 25,
text: envelope.input,
clientSteerId: idempotencyKey,
preempt: true,
generationProtocolVersion: 2,
});
expect(mintToken).toHaveBeenCalledWith(envelope.principal, envelope);
});
it('surfaces temporary steer backpressure as a retryable definite rejection', async () => {
expect.hasAssertions();
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () =>
response(
{ code: 'STEER_QUEUE_FULL', generationProtocolVersion: 2 },
{ status: 429, headers: { 'retry-after': '3' } },
),
),
),
);
await host.dispatch(createSteerEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
certainty: 'definite',
retryable: true,
code: 'STEER_QUEUE_FULL',
status: 429,
retryAfter: '3',
});
});
});
it('retries a steer while the same generation is paused for human review', async () => {
expect.hasAssertions();
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () =>
response({ code: 'RUN_PAUSED', generationProtocolVersion: 2 }, { status: 409 }),
),
),
);
await host.dispatch(createSteerEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'steer',
certainty: 'definite',
retryable: true,
code: 'RUN_PAUSED',
status: 409,
});
});
});
it('retries a missing strict route during a rolling deployment without mutating legacy state', async () => {
expect.hasAssertions();
const host = createAgentTriggerExecutionHost(
deps(fetchMock(async () => response('Not Found', { status: 404 }))),
);
await host.dispatch(createSteerEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'steer',
certainty: 'definite',
retryable: true,
code: 'STEER_ADMISSION_UNAVAILABLE',
status: 404,
});
});
});
it('classifies a reset during steer admission as ambiguous and safe to retry', async () => {
expect.hasAssertions();
const host = createAgentTriggerExecutionHost(
deps(fetchMock(async () => Promise.reject(new Error('connection reset')))),
);
await host.dispatch(createSteerEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'steer',
certainty: 'ambiguous',
retryable: true,
code: 'NETWORK_ERROR',
});
});
});
it('refuses to retry a success that lacks the v2 receipt guarantee', async () => {
expect.hasAssertions();
const host = createAgentTriggerExecutionHost(
deps(
fetchMock(async () =>
response(
{
status: 'queued',
conversationId: 'conversation-1',
steerId: 'steer-1',
position: 1,
preempt: false,
generationProtocolVersion: 1,
},
{ status: 202 },
),
),
),
);
await host.dispatch(createSteerEnvelope()).catch((error: unknown) => {
expectExecutionError(error, {
mode: 'steer',
certainty: 'ambiguous',
retryable: false,
code: 'STEER_IDEMPOTENCY_UNAVAILABLE',
status: 202,
});
});
});
});