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
🛰️ feat: Execute Generic Agent Trigger Deliveries (#14921)
Danny Avilaf8f118ef2970
diff --git a/api/server/controllers/agents/__tests__/steer.spec.js b/api/server/controllers/agents/__tests__/steer.spec.jsindex 1ff636e1d1..0da95294f4 100644--- a/api/server/controllers/agents/__tests__/steer.spec.js+++ b/api/server/controllers/agents/__tests__/steer.spec.js@@ -41,7 +41,7 @@ jest.mock('~/models', () => ({const { Permissions, PermissionTypes, PermissionBits } = require('librechat-data-provider');const SteerController = require('~/server/controllers/agents/steer');-const { SteerCancelController, SteerArmController } = SteerController;+const { SteerDeliveryController, SteerCancelController, SteerArmController } = SteerController;const GENERATION_PROTOCOL_HEADER = 'x-librechat-generation-protocol';@@ -60,6 +60,7 @@ function buildApp(user = { id: 'user-1', tenantId: 'tenant-1' }) {next();});app.post('/chat/steer', SteerController);+ app.post('/chat/steer/deliver', SteerDeliveryController);app.post('/chat/steer/cancel', SteerCancelController);app.post('/chat/steer/arm', SteerArmController);return app;@@ -100,6 +101,7 @@ describe('SteerController (wrapper)', () => {{ conversationId: 'c1', text: 'hello', files: [{ file_id: 'f1' }] },{generationProtocolVersion: 1,+ signal: expect.any(AbortSignal),getFiles: expect.any(Function),updateFilesUsage: expect.any(Function),checkAgentAccess: expect.any(Function),@@ -121,6 +123,44 @@ describe('SteerController (wrapper)', () => {expect(res.headers[GENERATION_PROTOCOL_HEADER]).toBe('1');});+ it('makes trigger delivery strict and fences it to the declared agent', async () => {+ mockHandleSteerRequest.mockResolvedValue({+ status: 202,+ body: { status: 'queued', generationProtocolVersion: 2 },+ });+ mockCheckAccess.mockResolvedValue(true);+ mockHasCapability.mockResolvedValue(true);++ await request(buildApp({ id: 'user-1', role: 'USER' }))+ .post('/chat/steer/deliver')+ .set('X-LibreChat-Generation-Protocol', '2')+ .send({+ agentId: 'agent-1',+ conversationId: 'c1',+ clientSteerId: 'delivery-1',+ text: 'move now',+ generationProtocolVersion: 2,+ });++ const options = mockHandleSteerRequest.mock.calls[0][2];+ expect(options).toEqual(+ expect.objectContaining({+ generationProtocolVersion: 2,+ requireIdempotentDelivery: true,+ signal: expect.any(AbortSignal),+ }),+ );+ await expect(+ options.checkAgentAccess({ agentId: 'agent-1', endpoint: 'agents' }),+ ).resolves.toBe(true);+ await expect(+ options.checkAgentAccess({ agentId: 'agent-other', endpoint: 'agents' }),+ ).resolves.toBe(false);+ await expect(+ options.checkAgentAccess({ agentId: 'agent-1', endpoint: 'openAI' }),+ ).resolves.toBe(false);+ });+it('500s with STEER_FAILED when the handler throws', async () => {mockHandleSteerRequest.mockRejectedValue(new Error('store down'));diff --git a/api/server/controllers/agents/steer.js b/api/server/controllers/agents/steer.jsindex 4ee163c3a7..5711154160 100644--- a/api/server/controllers/agents/steer.js+++ b/api/server/controllers/agents/steer.js@@ -103,22 +103,60 @@ const createAgentAccessCheck =* (`handleSteerRequest`), which returns the HTTP status + JSON body to* serialize verbatim. DB access and permission services are injected here.*/-const SteerController = async (req, res) => {+const runSteerController = async (req, res, requireIdempotentDelivery) => {+ const abortController = new AbortController();+ const abort = () => {+ if (!res.writableEnded) {+ abortController.abort();+ }+ };+ req.once('aborted', abort);+ res.once('close', abort);try {const generationProtocolVersion = getHostGenerationProtocol(req);+ const checkAgentAccess = createAgentAccessCheck(req);+ const expectedAgentId = requireIdempotentDelivery ? req.body?.agentId : undefined;const { status, body } = await handleSteerRequest(req.user ?? {}, req.body ?? {}, {generationProtocolVersion,+ signal: abortController.signal,+ ...(requireIdempotentDelivery && { requireIdempotentDelivery: true }),getFiles: db.getFiles,updateFilesUsage: db.updateFilesUsage,- checkAgentAccess: createAgentAccessCheck(req),+ checkAgentAccess: requireIdempotentDelivery+ ? async (run) =>+ typeof expectedAgentId === 'string' &&+ run.agentId === expectedAgentId &&+ isAgentsEndpoint(run.endpoint) &&+ (await checkAgentAccess(run))+ : checkAgentAccess,});+ if (res.destroyed || res.writableEnded) {+ return;+ }return sendProtocolResult(res, status, body);} catch (error) {logger.error('[SteerController] Failed to queue steer', error);+ if (res.destroyed || res.headersSent) {+ return;+ }return sendProtocolFailure(res, 500, 'STEER_FAILED');+ } finally {+ req.off('aborted', abort);+ res.off('close', abort);}};+const SteerController = (req, res) => runSteerController(req, res, false);++/**+ * Strict trigger-delivery endpoint. It shares the ordinary steer route's+ * authentication, limiters, PII filter, moderation, owner/tenant checks, and+ * agent ACL, while refusing any job/store path that cannot persist a durable+ * clientSteerId receipt. The dedicated path also fails closed on old replicas+ * during a rolling deploy: they return 404 instead of accepting a legacy steer.+ */+const SteerDeliveryController = (req, res) => runSteerController(req, res, true);+/*** POST /api/agents/chat/steer/cancel*@@ -163,5 +201,6 @@ const SteerArmController = async (req, res) => {};module.exports = SteerController;+module.exports.SteerDeliveryController = SteerDeliveryController;module.exports.SteerCancelController = SteerCancelController;module.exports.SteerArmController = SteerArmController;diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.jsindex 1f53181e6d..987fba06df 100644--- a/api/server/routes/agents/index.js+++ b/api/server/routes/agents/index.js@@ -913,6 +913,22 @@ router.post(SteerController,);+/**+ * @route POST /chat/steer/deliver+ * @desc Strict, idempotent steer admission for trusted event-delivery hosts+ * @access Private+ * @description Uses the same text-admission chain as an interactive steer,+ * then requires a v2 durable receipt and exact originating-agent identity.+ */+router.post(+ '/chat/steer/deliver',+ configMiddleware,+ ...steerLimiters,+ createMessageFilterPii({ getConfig: (req) => req.config?.messageFilter?.pii }),+ moderateText,+ SteerController.SteerDeliveryController,+);+/*** @route POST /chat/steer/cancel* @desc Remove a still-queued steer before injection (no model-bound content,diff --git a/packages/api/src/agents/envelope.ts b/packages/api/src/agents/envelope.tsindex ba544138ee..cb56cdfe42 100644--- a/packages/api/src/agents/envelope.ts+++ b/packages/api/src/agents/envelope.ts@@ -1,14 +1,15 @@import type { TEphemeralAgent } from 'librechat-data-provider';+import type { JsonPrimitive, JsonValue } from './json';import type { ChatCompletionRequest } from './openai';import type { ResponseRequest } from './responses';+import { AGENT_ENVELOPE_MAX_NESTING_DEPTH, cloneJsonValue } from './json';export const AGENT_RUN_ENVELOPE_VERSION = 1 as const;-export const AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH = 64;+export const AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH: number = AGENT_ENVELOPE_MAX_NESTING_DEPTH;export type AgentRunProtocol = 'chat.completions' | 'responses';-export type JsonPrimitive = string | number | boolean | null;-export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };+export type { JsonPrimitive, JsonValue };export interface AgentRunPrincipal {userId: string;@@ -91,105 +92,6 @@ function assertNonEmptyString(value: string | undefined, path: string): string {return value;}-function cloneJsonValue<T>(value: T, path: string, ancestors: WeakSet<object>, depth: number): T;-function cloneJsonValue(- value: unknown,- path: string,- ancestors: WeakSet<object>,- depth: number,-): unknown {- if (depth > AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH) {- throw new AgentRunEnvelopeError(- `${path} exceeds the maximum nesting depth of ${AGENT_RUN_ENVELOPE_MAX_NESTING_DEPTH}`,- );- }-- if (value === null || typeof value === 'string' || typeof value === 'boolean') {- return value;- }-- if (typeof value === 'number') {- if (!Number.isFinite(value)) {- throw new AgentRunEnvelopeError(`${path} must contain only finite numbers`);- }- return value;- }-- if (typeof value !== 'object') {- throw new AgentRunEnvelopeError(`${path} contains a non-JSON ${typeof value} value`);- }-- if (ancestors.has(value)) {- throw new AgentRunEnvelopeError(`${path} contains a circular reference`);- }-- ancestors.add(value);-- try {- const symbolKeys = Object.getOwnPropertySymbols(value);- if (symbolKeys.length > 0) {- throw new AgentRunEnvelopeError(`${path} contains symbol keys`);- }-- if (Array.isArray(value)) {- const cloned: unknown[] = new Array(value.length);- let clonedItemCount = 0;- for (const key of Object.getOwnPropertyNames(value)) {- if (key === 'length') {- continue;- }- const index = Number(key);- if (- !Number.isSafeInteger(index) ||- index < 0 ||- index >= value.length ||- String(index) !== key- ) {- throw new AgentRunEnvelopeError(`${path} contains non-index array properties`);- }- const descriptor = Object.getOwnPropertyDescriptor(value, key);- if (!descriptor || !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {- throw new AgentRunEnvelopeError(`${path}[${index}] must not be an accessor property`);- }- const itemValue: unknown = descriptor.value;- cloned[index] = cloneJsonValue(itemValue, `${path}[${index}]`, ancestors, depth + 1);- clonedItemCount++;- }- if (clonedItemCount !== value.length) {- throw new AgentRunEnvelopeError(`${path} contains sparse array entries`);- }- return cloned;- }-- const prototype = Object.getPrototypeOf(value);- if (prototype !== Object.prototype && prototype !== null) {- const typeName = value.constructor?.name ?? 'object';- throw new AgentRunEnvelopeError(`${path} contains a non-plain ${typeName} value`);- }-- const cloned: { [key: string]: unknown } = {};- for (const key of Object.getOwnPropertyNames(value)) {- const descriptor = Object.getOwnPropertyDescriptor(value, key);- if (descriptor?.enumerable !== true) {- throw new AgentRunEnvelopeError(`${path}.${key} must be an enumerable property`);- }- if (!Object.prototype.hasOwnProperty.call(descriptor, 'value')) {- throw new AgentRunEnvelopeError(`${path}.${key} must not be an accessor property`);- }- const propertyValue: unknown = descriptor.value;- Object.defineProperty(cloned, key, {- configurable: true,- enumerable: true,- writable: true,- value: cloneJsonValue(propertyValue, `${path}.${key}`, ancestors, depth + 1),- });- }- return cloned;- } finally {- ancestors.delete(value);- }-}-function createPrincipal(input: AgentRunPrincipalInput | null | undefined): AgentRunPrincipal {const userId = assertNonEmptyString(input?.id, 'principal.id');const principal: AgentRunPrincipal = { userId };@@ -233,7 +135,11 @@ export function createAgentRunEnvelope(input: CreateAgentRunEnvelopeInput): Agenreturn {...base,protocol: input.protocol,- payload: cloneJsonValue(input.payload, 'payload', new WeakSet(), 0),+ payload: cloneJsonValue(+ input.payload,+ 'payload',+ (message) => new AgentRunEnvelopeError(message),+ ),};}@@ -241,7 +147,11 @@ export function createAgentRunEnvelope(input: CreateAgentRunEnvelopeInput): Agenreturn {...base,protocol: input.protocol,- payload: cloneJsonValue(input.payload, 'payload', new WeakSet(), 0),+ payload: cloneJsonValue(+ input.payload,+ 'payload',+ (message) => new AgentRunEnvelopeError(message),+ ),};}diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.tsindex fb78376e8a..a91ec8fee0 100644--- a/packages/api/src/agents/index.ts+++ b/packages/api/src/agents/index.ts@@ -43,6 +43,7 @@ export * from './sender';export * from './hitl';export * from './hooks';export * from './steering';+export * from './triggers';export * from './activityLabels';export * from './activityPhases';export * from './reasoningLabels';diff --git a/packages/api/src/agents/json.ts b/packages/api/src/agents/json.tsnew file mode 100644index 0000000000..2f4846a888--- /dev/null+++ b/packages/api/src/agents/json.ts@@ -0,0 +1,109 @@+export const AGENT_ENVELOPE_MAX_NESTING_DEPTH = 64;++export type JsonPrimitive = string | number | boolean | null;+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };++type ErrorFactory = (message: string) => Error;++export function cloneJsonValue<T>(+ value: T,+ path: string,+ createError: ErrorFactory,+ ancestors: WeakSet<object> = new WeakSet(),+ depth = 0,+): T {+ if (depth > AGENT_ENVELOPE_MAX_NESTING_DEPTH) {+ throw createError(+ `${path} exceeds the maximum nesting depth of ${AGENT_ENVELOPE_MAX_NESTING_DEPTH}`,+ );+ }++ if (value === null || typeof value === 'string' || typeof value === 'boolean') {+ return value;+ }++ if (typeof value === 'number') {+ if (!Number.isFinite(value)) {+ throw createError(`${path} must contain only finite numbers`);+ }+ return value;+ }++ if (typeof value !== 'object') {+ throw createError(`${path} contains a non-JSON ${typeof value} value`);+ }++ if (ancestors.has(value)) {+ throw createError(`${path} contains a circular reference`);+ }++ ancestors.add(value);++ try {+ if (Object.getOwnPropertySymbols(value).length > 0) {+ throw createError(`${path} contains symbol keys`);+ }++ if (Array.isArray(value)) {+ const cloned: unknown[] = new Array(value.length);+ let clonedItemCount = 0;+ for (const key of Object.getOwnPropertyNames(value)) {+ if (key === 'length') {+ continue;+ }+ const index = Number(key);+ if (+ !Number.isSafeInteger(index) ||+ index < 0 ||+ index >= value.length ||+ String(index) !== key+ ) {+ throw createError(`${path} contains non-index array properties`);+ }+ const descriptor = Object.getOwnPropertyDescriptor(value, key);+ if (!descriptor || !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {+ throw createError(`${path}[${index}] must not be an accessor property`);+ }+ const itemValue: unknown = descriptor.value;+ cloned[index] = cloneJsonValue(+ itemValue,+ `${path}[${index}]`,+ createError,+ ancestors,+ depth + 1,+ );+ clonedItemCount++;+ }+ if (clonedItemCount !== value.length) {+ throw createError(`${path} contains sparse array entries`);+ }+ return cloned as T;+ }++ const prototype = Object.getPrototypeOf(value);+ if (prototype !== Object.prototype && prototype !== null) {+ throw createError(`${path} contains a non-plain object value`);+ }++ const cloned: { [key: string]: unknown } = {};+ for (const key of Object.getOwnPropertyNames(value)) {+ const descriptor = Object.getOwnPropertyDescriptor(value, key);+ if (descriptor?.enumerable !== true) {+ throw createError(`${path}.${key} must be an enumerable property`);+ }+ if (!Object.prototype.hasOwnProperty.call(descriptor, 'value')) {+ throw createError(`${path}.${key} must not be an accessor property`);+ }+ const propertyValue: unknown = descriptor.value;+ Object.defineProperty(cloned, key, {+ configurable: true,+ enumerable: true,+ writable: true,+ value: cloneJsonValue(propertyValue, `${path}.${key}`, createError, ancestors, depth + 1),+ });+ }+ return cloned as T;+ } finally {+ ancestors.delete(value);+ }+}diff --git a/packages/api/src/agents/steering/__tests__/request.spec.ts b/packages/api/src/agents/steering/__tests__/request.spec.tsindex 292728fe70..646e521ce6 100644--- a/packages/api/src/agents/steering/__tests__/request.spec.ts+++ b/packages/api/src/agents/steering/__tests__/request.spec.ts@@ -66,6 +66,19 @@ describe('handleSteerRequest (real in-memory job manager)', () => {expect(result.body.code).toBe('INVALID_CLIENT_STEER_ID');});+ it('requires a client correlation id when idempotent delivery is mandatory', async () => {+ const result = await handleSteerRequest(+ user,+ { conversationId: 'c1', text: 'valid text' },+ { requireIdempotentDelivery: true },+ );++ expect(result).toEqual({+ status: 400,+ body: { code: 'CLIENT_STEER_ID_REQUIRED' },+ });+ });+it('400s an invalid generation identity', async () => {const result = await handleSteerRequest(user, {conversationId: 'c1',@@ -669,6 +682,94 @@ describe('generation protocol bridge for steering mutations', () => {]);});+ it('rejects a v1 job before enqueue when the caller requires idempotent delivery', async () => {+ const streamId = 'steer-protocol-v1-idempotency-required';+ await GenerationJobManager.createJob(streamId, user.id, undefined, {+ initialMetadata: { generationProtocolVersion: 1 },+ });+ const receiptEnqueue = jest.spyOn(GenerationJobManager.steering, 'enqueueWithReceipt');+ const legacyEnqueue = jest.spyOn(GenerationJobManager.steering, 'enqueueVersioned');++ const result = await handleSteerRequest(+ user,+ {+ conversationId: streamId,+ clientSteerId: 'client-v1-requires-idempotency',+ text: 'must not be injected without a receipt',+ },+ { generationProtocolVersion: 2, requireIdempotentDelivery: true },+ );++ expect(result).toEqual({+ status: 409,+ body: { code: 'STEER_IDEMPOTENCY_UNAVAILABLE', generationProtocolVersion: 1 },+ });+ expect(receiptEnqueue).not.toHaveBeenCalled();+ expect(legacyEnqueue).not.toHaveBeenCalled();+ await expect(GenerationJobManager.steering.peek(streamId)).resolves.toEqual([]);+ });++ it('keeps ownership rejection ahead of the strict idempotency capability gate', async () => {+ const streamId = 'steer-protocol-v1-idempotency-foreign-owner';+ await GenerationJobManager.createJob(streamId, 'someone-else', undefined, {+ initialMetadata: { generationProtocolVersion: 1 },+ });++ const result = await handleSteerRequest(+ user,+ {+ conversationId: streamId,+ clientSteerId: 'client-v1-foreign-owner',+ text: 'must remain unauthorized',+ },+ { generationProtocolVersion: 2, requireIdempotentDelivery: true },+ );++ expect(result).toEqual({+ status: 403,+ body: { code: 'UNAUTHORIZED', generationProtocolVersion: 1 },+ });+ await expect(GenerationJobManager.steering.peek(streamId)).resolves.toEqual([]);+ });++ it('observes delivery cancellation after async admission and before enqueue', async () => {+ const streamId = 'steer-protocol-v2-aborted-admission';+ await GenerationJobManager.createJob(streamId, user.id, undefined, {+ initialMetadata: {+ agent_id: 'agent-1',+ endpoint: 'agents',+ generationProtocolVersion: 2,+ },+ });+ const controller = new AbortController();+ const receiptEnqueue = jest.spyOn(GenerationJobManager.steering, 'enqueueWithReceipt');++ const result = await handleSteerRequest(+ user,+ {+ conversationId: streamId,+ clientSteerId: 'client-v2-aborted-admission',+ text: 'must not land after the worker lease is cancelled',+ },+ {+ generationProtocolVersion: 2,+ requireIdempotentDelivery: true,+ signal: controller.signal,+ checkAgentAccess: async () => {+ controller.abort();+ return true;+ },+ },+ );++ expect(result).toEqual({+ status: 499,+ body: { code: 'STEER_ABORTED', generationProtocolVersion: 2 },+ });+ expect(receiptEnqueue).not.toHaveBeenCalled();+ await expect(GenerationJobManager.steering.peek(streamId)).resolves.toEqual([]);+ });+it('keeps v2 receipt replay and correlation broadcasts behind an exact v2 job marker', async () => {const streamId = 'steer-protocol-v2-job';await GenerationJobManager.createJob(streamId, user.id, undefined, {diff --git a/packages/api/src/agents/steering/request.ts b/packages/api/src/agents/steering/request.tsindex ab3b471a52..632a48799a 100644--- a/packages/api/src/agents/steering/request.ts+++ b/packages/api/src/agents/steering/request.ts@@ -125,6 +125,12 @@ export interface SteerRequestDeps {* and its rollout gate. Direct package callers that omit it retain the* current-package (v2) behavior. */generationProtocolVersion?: GenerationProtocolVersion;+ /** Refuse a legacy v1 enqueue that cannot persist `clientSteerId` receipts.+ * Background/event deliveries use this to make retrying an ambiguous+ * outcome safe instead of potentially injecting the same instruction twice. */+ requireIdempotentDelivery?: boolean;+ /** Best-effort cancellation observed immediately before durable mutation. */+ signal?: AbortSignal;/** Owner-scoped file fetch (`db.getFiles`-shaped). When present, every* client-supplied ref must resolve to an owned DB doc at enqueue and the* queued refs are replaced with DB-derived ones. */@@ -156,6 +162,10 @@ function parseExpectedGenerationCreatedAt(value: unknown): { value?: number; invreturn { value };}+function isAborted(signal: AbortSignal | undefined): boolean {+ return signal?.aborted === true;+}+/** Sanitizes client-supplied attachment refs via the shared ref picker;* a single unusable entry rejects the whole list (fail-loud for the client). */function sanitizeSteerFiles(rawFiles: unknown): SanitizedFilesResult {@@ -382,6 +392,9 @@ async function handleSteerRequestInternal() {return { status: 400, body: { code: 'INVALID_CLIENT_STEER_ID' } };}+ if (deps.requireIdempotentDelivery === true && typeof clientSteerId !== 'string') {+ return { status: 400, body: { code: 'CLIENT_STEER_ID_REQUIRED' } };+ }const { files, error: filesError } = sanitizeSteerFiles(body.files);if (filesError) {@@ -483,6 +496,9 @@ async function handleSteerRequestInternal(if (!isSteeringSupported()) {return { status: 501, body: { code: 'STEER_UNSUPPORTED' } };}+ if (deps.requireIdempotentDelivery === true && protocol.value !== 2) {+ return { status: 409, body: { code: 'STEER_IDEMPOTENCY_UNAVAILABLE' } };+ }let queuedFiles = files;if (files && deps.getFiles) {@@ -531,6 +547,9 @@ async function handleSteerRequestInternal(? { status: 409, body: { code: 'RUN_REPLACED' } }: { status: 404, body: { code: 'NO_ACTIVE_RUN' } };}+ if (isAborted(deps.signal)) {+ return { status: 499, body: { code: 'STEER_ABORTED' } };+ }/** Normal sends make resolved uploads durable before model execution. Do* the same before enqueue: once a 202 is visible, neither an upload-window* sweep nor a process crash may turn the accepted steer into text-only@@ -538,6 +557,9 @@ async function handleSteerRequestInternal(if (!(await markSteerFilesUsed(streamId, { files: queuedFiles }, user, deps))) {return { status: 503, body: { code: 'STEER_FILE_RETENTION_FAILED' } };}+ if (isAborted(deps.signal)) {+ return { status: 499, body: { code: 'STEER_ABORTED' } };+ }const item: SteerQueueItem = {steerId: randomUUID(),...(protocol.value === 2 && typeof clientSteerId === 'string' && { clientSteerId }),diff --git a/packages/api/src/agents/triggers/dispatch.spec.ts b/packages/api/src/agents/triggers/dispatch.spec.tsnew file mode 100644index 0000000000..b86ae40b20--- /dev/null+++ b/packages/api/src/agents/triggers/dispatch.spec.ts@@ -0,0 +1,114 @@+import type { AgentTriggerEnvelope } from './envelope';+import { AgentTriggerDispatchError, dispatchAgentTrigger } from './dispatch';+import { createAgentTriggerEnvelope } from './envelope';++describe('dispatchAgentTrigger', () => {+ const createFireInput = () => ({+ mode: 'fire' as const,+ requestId: 'request-1',+ deliveryId: 'delivery-1',+ receivedAt: 20,+ principal: { id: 'user-1' },+ target: { agentId: 'agent-1' },+ event: {+ id: 'event-1',+ type: 'resource.ready',+ occurredAt: 10,+ source: { id: 'source-1', type: 'webhook' },+ },+ input: 'Handle the ready resource.',+ });++ const fireEnvelope = () => createAgentTriggerEnvelope(createFireInput());++ it('routes fire deliveries with their stable idempotency identity and abort signal', async () => {+ const controller = new AbortController();+ const fire = jest.fn(async () => ({ status: 'accepted' as const }));+ const steer = jest.fn(async () => ({ status: 'accepted' as const }));+ const envelope = fireEnvelope();++ await expect(+ dispatchAgentTrigger(envelope, { fire, steer }, { signal: controller.signal }),+ ).resolves.toEqual({ status: 'accepted' });++ expect(fire).toHaveBeenCalledWith(envelope, {+ idempotencyKey: expect.stringMatching(/^trigger_[a-f0-9]{64}$/),+ signal: controller.signal,+ });+ expect(steer).not.toHaveBeenCalled();+ });++ it('routes steer deliveries without requiring a fire implementation detail', async () => {+ const fire = jest.fn(async () => 'fire');+ const steer = jest.fn(async () => 'steer');+ const envelope = createAgentTriggerEnvelope({+ ...createFireInput(),+ mode: 'steer',+ target: {+ agentId: 'agent-1',+ conversationId: 'conversation-1',+ generationCreatedAt: 15,+ },+ });++ await expect(dispatchAgentTrigger(envelope, { fire, steer })).resolves.toBe('steer');+ expect(steer).toHaveBeenCalledWith(envelope, {+ idempotencyKey: expect.stringMatching(/^trigger_[a-f0-9]{64}$/),+ });+ expect(fire).not.toHaveBeenCalled();+ });++ it('propagates handler failures without falling back to another mode', async () => {+ const error = new Error('fire rejected');+ const fire = jest.fn(async () => Promise.reject(error));+ const steer = jest.fn(async () => 'steer');++ await expect(dispatchAgentTrigger(fireEnvelope(), { fire, steer })).rejects.toBe(error);+ expect(fire).toHaveBeenCalledTimes(1);+ expect(steer).not.toHaveBeenCalled();+ });++ it('rejects unknown modes before deriving identity or calling a handler', () => {+ const fire = jest.fn(async () => 'fire');+ const steer = jest.fn(async () => 'steer');+ const envelope = {+ ...fireEnvelope(),+ mode: 'resume',+ } as unknown as AgentTriggerEnvelope;++ expect(() => dispatchAgentTrigger(envelope, { fire, steer })).toThrow(+ new AgentTriggerDispatchError('Unsupported agent trigger mode: resume'),+ );+ expect(fire).not.toHaveBeenCalled();+ expect(steer).not.toHaveBeenCalled();+ });++ it('rejects unknown envelope versions before deriving identity or calling a handler', () => {+ const fire = jest.fn(async () => 'fire');+ const steer = jest.fn(async () => 'steer');+ const envelope = {+ ...fireEnvelope(),+ version: 2,+ } as unknown as AgentTriggerEnvelope;++ expect(() => dispatchAgentTrigger(envelope, { fire, steer })).toThrow(+ new AgentTriggerDispatchError('Unsupported agent trigger envelope version: 2'),+ );+ expect(fire).not.toHaveBeenCalled();+ expect(steer).not.toHaveBeenCalled();+ });++ it('rejects malformed v1 envelopes before deriving identity or calling a handler', () => {+ const fire = jest.fn(async () => 'fire');+ const steer = jest.fn(async () => 'steer');+ const malformed = { ...fireEnvelope() };+ Reflect.deleteProperty(malformed, 'target');+ const envelope = malformed as unknown as AgentTriggerEnvelope;++ expect(() => dispatchAgentTrigger(envelope, { fire, steer })).toThrow(+ new AgentTriggerDispatchError('target must be an object'),+ );+ expect(fire).not.toHaveBeenCalled();+ expect(steer).not.toHaveBeenCalled();+ });+});diff --git a/packages/api/src/agents/triggers/dispatch.ts b/packages/api/src/agents/triggers/dispatch.tsnew file mode 100644index 0000000000..39b7a75107--- /dev/null+++ b/packages/api/src/agents/triggers/dispatch.ts@@ -0,0 +1,55 @@+import type {+ AgentFireTriggerEnvelope,+ AgentSteerTriggerEnvelope,+ AgentTriggerEnvelope,+} from './envelope';+import { getAgentTriggerIdempotencyKey, parseAgentTriggerEnvelope } from './envelope';++export interface AgentTriggerDispatchContext {+ idempotencyKey: string;+ signal?: AbortSignal;+}++export class AgentTriggerDispatchError extends TypeError {+ constructor(message: string) {+ super(message);+ this.name = 'AgentTriggerDispatchError';+ }+}++/**+ * Host-owned execution adapters. Each handler must enforce current authorization,+ * limits, persistence, and the supplied idempotency identity before accepting work.+ */+export interface AgentTriggerDispatchHandlers<FireResult, SteerResult> {+ fire: (+ envelope: AgentFireTriggerEnvelope,+ context: AgentTriggerDispatchContext,+ ) => Promise<FireResult>;+ steer: (+ envelope: AgentSteerTriggerEnvelope,+ context: AgentTriggerDispatchContext,+ ) => Promise<SteerResult>;+}++/** Routes a normalized trigger without coupling its source to an execution transport. */+export function dispatchAgentTrigger<FireResult, SteerResult>(+ envelope: unknown,+ handlers: AgentTriggerDispatchHandlers<FireResult, SteerResult>,+ options?: { signal?: AbortSignal },+): Promise<FireResult | SteerResult> {+ let normalized: AgentTriggerEnvelope;+ try {+ normalized = parseAgentTriggerEnvelope(envelope);+ } catch (error) {+ throw new AgentTriggerDispatchError(error instanceof Error ? error.message : String(error));+ }+ const context: AgentTriggerDispatchContext = {+ idempotencyKey: getAgentTriggerIdempotencyKey(normalized),+ ...(options?.signal != null && { signal: options.signal }),+ };+ if (normalized.mode === 'fire') {+ return handlers.fire(normalized, context);+ }+ return handlers.steer(normalized, context);+}diff --git a/packages/api/src/agents/triggers/envelope.spec.ts b/packages/api/src/agents/triggers/envelope.spec.tsnew file mode 100644index 0000000000..ad93e63230--- /dev/null+++ b/packages/api/src/agents/triggers/envelope.spec.ts@@ -0,0 +1,217 @@+import type { CreateAgentTriggerEnvelopeInput } from './envelope';+import {+ AGENT_TRIGGER_ENVELOPE_VERSION,+ AgentTriggerEnvelopeError,+ createAgentTriggerEnvelope,+ getAgentTriggerIdempotencyKey,+ parseAgentTriggerEnvelope,+} from './envelope';++describe('createAgentTriggerEnvelope', () => {+ const createFireInput = (): CreateAgentTriggerEnvelopeInput => ({+ mode: 'fire',+ requestId: 'request-1',+ deliveryId: 'subscription-1:event-1',+ receivedAt: 1_725_000_000_010,+ principal: {+ id: 'user-1',+ role: 'USER',+ tenantId: 'tenant-1',+ },+ target: { agentId: 'agent-1' },+ event: {+ id: 'event-1',+ type: 'work.ready',+ occurredAt: 1_725_000_000_000,+ source: { id: 'source-1', type: 'mcp' },+ payload: { resourceId: 'resource-1', attempt: 1 },+ },+ input: 'Inspect the ready work item.',+ });++ it('creates a detached, versioned fire envelope with a projected principal', () => {+ const input = createFireInput();+ const principal = input.principal as NonNullable<+ CreateAgentTriggerEnvelopeInput['principal']+ > & {+ password?: string;+ };+ principal.password = 'must-not-cross';+ const envelope = createAgentTriggerEnvelope(input);+ const payload = input.event.payload as { resourceId: string };+ payload.resourceId = 'changed-after-dispatch';++ expect(envelope).toEqual({+ version: AGENT_TRIGGER_ENVELOPE_VERSION,+ mode: 'fire',+ requestId: 'request-1',+ deliveryId: 'subscription-1:event-1',+ receivedAt: 1_725_000_000_010,+ principal: { userId: 'user-1', role: 'USER', tenantId: 'tenant-1' },+ target: { agentId: 'agent-1' },+ event: {+ id: 'event-1',+ type: 'work.ready',+ occurredAt: 1_725_000_000_000,+ source: { id: 'source-1', type: 'mcp' },+ payload: { resourceId: 'resource-1', attempt: 1 },+ },+ input: 'Inspect the ready work item.',+ });+ expect(JSON.parse(JSON.stringify(envelope))).toEqual(envelope);+ expect(JSON.stringify(envelope)).not.toContain('must-not-cross');+ });++ it('parses and detaches a serialized envelope', () => {+ const created = createAgentTriggerEnvelope(createFireInput());+ const serialized = JSON.parse(JSON.stringify(created)) as unknown;+ const parsed = parseAgentTriggerEnvelope(serialized);++ expect(parsed).toEqual(created);+ expect(parsed).not.toBe(serialized);+ expect(parsed.event).not.toBe((serialized as { event: object }).event);+ });++ it('requires a generation fence for steer deliveries', () => {+ const envelope = createAgentTriggerEnvelope({+ ...createFireInput(),+ mode: 'steer',+ target: {+ agentId: 'agent-1',+ conversationId: 'conversation-1',+ generationCreatedAt: 1_725_000_000_005,+ preempt: true,+ },+ });++ expect(envelope.mode).toBe('steer');+ expect(envelope.target).toEqual({+ agentId: 'agent-1',+ conversationId: 'conversation-1',+ generationCreatedAt: 1_725_000_000_005,+ preempt: true,+ });+ });++ it('builds a stable generation-compatible idempotency key per delivery target', () => {+ const first = createAgentTriggerEnvelope(createFireInput());+ const retry = createAgentTriggerEnvelope({+ ...createFireInput(),+ requestId: 'request-2',+ receivedAt: 1_725_000_000_020,+ });+ const anotherDelivery = createAgentTriggerEnvelope({+ ...createFireInput(),+ deliveryId: 'subscription-2:event-1',+ });+ const anotherSource = createAgentTriggerEnvelope({+ ...createFireInput(),+ event: {+ ...createFireInput().event,+ source: { id: 'source-2', type: 'webhook' },+ },+ });+ const anotherEvent = createAgentTriggerEnvelope({+ ...createFireInput(),+ event: { ...createFireInput().event, id: 'event-2' },+ });++ const firstKey = getAgentTriggerIdempotencyKey(first);+ expect(getAgentTriggerIdempotencyKey(retry)).toBe(firstKey);+ expect(getAgentTriggerIdempotencyKey(anotherDelivery)).not.toBe(firstKey);+ expect(getAgentTriggerIdempotencyKey(anotherSource)).not.toBe(firstKey);+ expect(getAgentTriggerIdempotencyKey(anotherEvent)).not.toBe(firstKey);+ expect(firstKey).toMatch(/^trigger_[a-f0-9]{64}$/);+ expect(firstKey).toMatch(/^[A-Za-z0-9_-]+$/);+ expect(firstKey.length).toBeLessThanOrEqual(128);+ });++ it.each([+ ['requestId', { requestId: ' ' }],+ ['deliveryId', { deliveryId: '' }],+ ['principal.id', { principal: undefined }],+ ['target.agentId', { target: { agentId: '' } }],+ ['event', { event: undefined }],+ ['event.id', { event: { ...createFireInput().event, id: '' } }],+ ['event.type', { event: { ...createFireInput().event, type: '' } }],+ ['event.source.id', { event: { ...createFireInput().event, source: { id: '', type: 'mcp' } } }],+ ['input', { input: '' }],+ ])('rejects an invalid %s', (_path, override) => {+ expect(() =>+ createAgentTriggerEnvelope({+ ...createFireInput(),+ ...override,+ } as CreateAgentTriggerEnvelopeInput),+ ).toThrow(AgentTriggerEnvelopeError);+ });++ it('rejects invalid timestamps and malformed steer controls', () => {+ expect(() =>+ createAgentTriggerEnvelope({+ ...createFireInput(),+ event: { ...createFireInput().event, occurredAt: Number.NaN },+ }),+ ).toThrow('event.occurredAt must be a non-negative integer timestamp');++ expect(() =>+ createAgentTriggerEnvelope({+ ...createFireInput(),+ mode: 'steer',+ target: {+ agentId: 'agent-1',+ conversationId: 'conversation-1',+ generationCreatedAt: -1,+ preempt: true,+ },+ }),+ ).toThrow('target.generationCreatedAt must be a non-negative integer timestamp');++ expect(() =>+ createAgentTriggerEnvelope({+ ...createFireInput(),+ mode: 'steer',+ target: {+ agentId: 'agent-1',+ conversationId: 'conversation-1',+ generationCreatedAt: 1,+ preempt: 'yes',+ },+ } as unknown as CreateAgentTriggerEnvelopeInput),+ ).toThrow('target.preempt must be a boolean');++ expect(() =>+ createAgentTriggerEnvelope({+ ...createFireInput(),+ mode: 'steer',+ target: undefined,+ } as unknown as CreateAgentTriggerEnvelopeInput),+ ).toThrow('target.agentId must be a non-empty string');+ });++ it('rejects non-JSON and circular event payloads', () => {+ expect(() =>+ createAgentTriggerEnvelope({+ ...createFireInput(),+ event: { ...createFireInput().event, payload: { callback: () => undefined } },+ } as unknown as CreateAgentTriggerEnvelopeInput),+ ).toThrow('event.payload.callback contains a non-JSON function value');++ const payload: { self?: object } = {};+ payload.self = payload;+ expect(() =>+ createAgentTriggerEnvelope({+ ...createFireInput(),+ event: { ...createFireInput().event, payload },+ } as unknown as CreateAgentTriggerEnvelopeInput),+ ).toThrow('event.payload.self contains a circular reference');+ });++ it('rejects unknown trigger modes at runtime', () => {+ expect(() =>+ createAgentTriggerEnvelope({+ ...createFireInput(),+ mode: 'resume',+ } as unknown as CreateAgentTriggerEnvelopeInput),+ ).toThrow('Unsupported agent trigger mode: resume');+ });+});diff --git a/packages/api/src/agents/triggers/envelope.ts b/packages/api/src/agents/triggers/envelope.tsnew file mode 100644index 0000000000..bdc761e604--- /dev/null+++ b/packages/api/src/agents/triggers/envelope.ts@@ -0,0 +1,296 @@+import { createHash } from 'node:crypto';+import type { AgentRunPrincipal, AgentRunPrincipalInput } from '../envelope';+import type { JsonValue } from '../json';+import { cloneJsonValue } from '../json';++export const AGENT_TRIGGER_ENVELOPE_VERSION = 1 as const;+export const AGENT_TRIGGER_IDEMPOTENCY_PREFIX = 'trigger_';++export type AgentTriggerMode = 'fire' | 'steer';++export interface AgentTriggerSource {+ /** Stable identity of the configured source, such as a webhook or schedule id. */+ id: string;+ /** Source adapter kind. Core dispatch does not interpret this value. */+ type: string;+}++export interface AgentTriggerEvent {+ /** Stable identity assigned by the source for this event occurrence. */+ id: string;+ type: string;+ /** Unix time in milliseconds recorded by the source. */+ occurredAt: number;+ /** Sanitized source data; adapters must omit credentials and transport secrets. */+ payload?: JsonValue;+ source: AgentTriggerSource;+}++interface AgentTriggerTarget {+ agentId: string;+}++/**+ * One fire delivery represents one new conversation for this agent; retries+ * reuse the delivery id instead of starting another conversation.+ */+export type AgentFireTarget = AgentTriggerTarget;++export interface AgentSteerTarget extends AgentTriggerTarget {+ /** Existing conversation whose active generation receives the input. */+ conversationId: string;+ /** Fences delivery to the generation observed by the event adapter. */+ generationCreatedAt: number;+ /** Request an interrupt when supported; otherwise delivery stays queued. */+ preempt?: boolean;+}++interface AgentTriggerEnvelopeBase {+ version: typeof AGENT_TRIGGER_ENVELOPE_VERSION;+ requestId: string;+ /** Stable across retries of one source-event-to-target delivery. */+ deliveryId: string;+ /** Unix time in milliseconds recorded by the receiving host. */+ receivedAt: number;+ principal: AgentRunPrincipal;+ event: AgentTriggerEvent;+ /** Host-rendered agent input; source payload remains available in `event.payload`. */+ input: string;+}++export interface AgentFireTriggerEnvelope extends AgentTriggerEnvelopeBase {+ mode: 'fire';+ target: AgentFireTarget;+}++export interface AgentSteerTriggerEnvelope extends AgentTriggerEnvelopeBase {+ mode: 'steer';+ target: AgentSteerTarget;+}++export type AgentTriggerEnvelope = AgentFireTriggerEnvelope | AgentSteerTriggerEnvelope;++interface CreateAgentTriggerEnvelopeBase {+ requestId: string;+ deliveryId: string;+ receivedAt: number;+ principal: AgentRunPrincipalInput | null | undefined;+ event: AgentTriggerEvent;+ input: string;+}++export type CreateAgentTriggerEnvelopeInput =+ | (CreateAgentTriggerEnvelopeBase & {+ mode: 'fire';+ target: AgentFireTarget;+ })+ | (CreateAgentTriggerEnvelopeBase & {+ mode: 'steer';+ target: AgentSteerTarget;+ });++export class AgentTriggerEnvelopeError extends TypeError {+ constructor(message: string) {+ super(message);+ this.name = 'AgentTriggerEnvelopeError';+ }+}++function error(message: string): AgentTriggerEnvelopeError {+ return new AgentTriggerEnvelopeError(message);+}++function requireString(value: unknown, path: string): string {+ if (typeof value !== 'string' || value.trim().length === 0) {+ throw error(`${path} must be a non-empty string`);+ }+ return value;+}++function requireTimestamp(value: unknown, path: string): number {+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {+ throw error(`${path} must be a non-negative integer timestamp`);+ }+ return value;+}++function requireRecord(value: unknown, path: string): Record<string, unknown> {+ if (value == null || typeof value !== 'object' || Array.isArray(value)) {+ throw error(`${path} must be an object`);+ }+ return value as Record<string, unknown>;+}++function createPrincipal(input: AgentRunPrincipalInput | null | undefined): AgentRunPrincipal {+ const principal: AgentRunPrincipal = {+ userId: requireString(input?.id, 'principal.id'),+ };+ if (input?.role != null) {+ principal.role = requireString(input.role, 'principal.role');+ }+ if (input?.tenantId != null) {+ principal.tenantId = requireString(input.tenantId, 'principal.tenantId');+ }+ return principal;+}++function createEvent(input: AgentTriggerEvent | null | undefined): AgentTriggerEvent {+ return {+ id: requireString(input?.id, 'event.id'),+ type: requireString(input?.type, 'event.type'),+ occurredAt: requireTimestamp(input?.occurredAt, 'event.occurredAt'),+ source: {+ id: requireString(input?.source?.id, 'event.source.id'),+ type: requireString(input?.source?.type, 'event.source.type'),+ },+ ...(input?.payload !== undefined && {+ payload: cloneJsonValue(input.payload, 'event.payload', error),+ }),+ };+}++export function createAgentTriggerEnvelope(+ input: CreateAgentTriggerEnvelopeInput,+): AgentTriggerEnvelope {+ const receivedMode: string = input.mode;+ const base: AgentTriggerEnvelopeBase = {+ version: AGENT_TRIGGER_ENVELOPE_VERSION,+ requestId: requireString(input.requestId, 'requestId'),+ deliveryId: requireString(input.deliveryId, 'deliveryId'),+ receivedAt: requireTimestamp(input.receivedAt, 'receivedAt'),+ principal: createPrincipal(input.principal),+ event: createEvent(input.event),+ input: requireString(input.input, 'input'),+ };++ if (input.mode === 'fire') {+ return {+ ...base,+ mode: input.mode,+ target: { agentId: requireString(input.target?.agentId, 'target.agentId') },+ };+ }++ if (input.mode === 'steer') {+ const target = input.target;+ if (target?.preempt != null && typeof target.preempt !== 'boolean') {+ throw error('target.preempt must be a boolean');+ }+ return {+ ...base,+ mode: input.mode,+ target: {+ agentId: requireString(target?.agentId, 'target.agentId'),+ conversationId: requireString(target?.conversationId, 'target.conversationId'),+ generationCreatedAt: requireTimestamp(+ target?.generationCreatedAt,+ 'target.generationCreatedAt',+ ),+ ...(target?.preempt != null && { preempt: target.preempt }),+ },+ };+ }++ throw error(`Unsupported agent trigger mode: ${receivedMode}`);+}++/**+ * Validates and detaches an envelope received from a queue or another process.+ * Unknown versions, modes, and malformed v1 fields fail closed before dispatch.+ */+export function parseAgentTriggerEnvelope(input: unknown): AgentTriggerEnvelope {+ const envelope = requireRecord(cloneJsonValue(input, 'envelope', error), 'envelope');+ if (envelope.version !== AGENT_TRIGGER_ENVELOPE_VERSION) {+ throw error(`Unsupported agent trigger envelope version: ${String(envelope.version)}`);+ }++ const mode = envelope.mode;+ if (mode !== 'fire' && mode !== 'steer') {+ throw error(`Unsupported agent trigger mode: ${String(mode)}`);+ }++ const principalInput = requireRecord(envelope.principal, 'principal');+ const principal: AgentRunPrincipal = {+ userId: requireString(principalInput.userId, 'principal.userId'),+ };+ if (principalInput.role != null) {+ principal.role = requireString(principalInput.role, 'principal.role');+ }+ if (principalInput.tenantId != null) {+ principal.tenantId = requireString(principalInput.tenantId, 'principal.tenantId');+ }++ const eventInput = requireRecord(envelope.event, 'event');+ const sourceInput = requireRecord(eventInput.source, 'event.source');+ const event: AgentTriggerEvent = {+ id: requireString(eventInput.id, 'event.id'),+ type: requireString(eventInput.type, 'event.type'),+ occurredAt: requireTimestamp(eventInput.occurredAt, 'event.occurredAt'),+ source: {+ id: requireString(sourceInput.id, 'event.source.id'),+ type: requireString(sourceInput.type, 'event.source.type'),+ },+ ...(eventInput.payload !== undefined && { payload: eventInput.payload as JsonValue }),+ };++ const base: AgentTriggerEnvelopeBase = {+ version: AGENT_TRIGGER_ENVELOPE_VERSION,+ requestId: requireString(envelope.requestId, 'requestId'),+ deliveryId: requireString(envelope.deliveryId, 'deliveryId'),+ receivedAt: requireTimestamp(envelope.receivedAt, 'receivedAt'),+ principal,+ event,+ input: requireString(envelope.input, 'input'),+ };+ const target = requireRecord(envelope.target, 'target');++ if (mode === 'fire') {+ return {+ ...base,+ mode,+ target: { agentId: requireString(target.agentId, 'target.agentId') },+ };+ }++ if (target.preempt != null && typeof target.preempt !== 'boolean') {+ throw error('target.preempt must be a boolean');+ }+ return {+ ...base,+ mode,+ target: {+ agentId: requireString(target.agentId, 'target.agentId'),+ conversationId: requireString(target.conversationId, 'target.conversationId'),+ generationCreatedAt: requireTimestamp(+ target.generationCreatedAt,+ 'target.generationCreatedAt',+ ),+ ...(target.preempt != null && { preempt: target.preempt }),+ },+ };+}++/**+ * Stable idempotency key for one target delivery. Its character set and length+ * are accepted by both generation `clientRequestId` and steering `clientSteerId`.+ */+export function getAgentTriggerIdempotencyKey(envelope: AgentTriggerEnvelope): string {+ const digest = createHash('sha256')+ .update(+ JSON.stringify([+ envelope.version,+ envelope.principal.tenantId ?? '',+ envelope.principal.userId,+ envelope.event.source.type,+ envelope.event.source.id,+ envelope.event.type,+ envelope.event.id,+ envelope.deliveryId,+ envelope.mode,+ envelope.target.agentId,+ envelope.mode === 'steer' ? envelope.target.conversationId : '',+ ]),+ )+ .digest('hex');+ return `${AGENT_TRIGGER_IDEMPOTENCY_PREFIX}${digest}`;+}diff --git a/packages/api/src/agents/triggers/host.spec.ts b/packages/api/src/agents/triggers/host.spec.tsnew file mode 100644index 0000000000..d94a935b05--- /dev/null+++ b/packages/api/src/agents/triggers/host.spec.ts@@ -0,0 +1,624 @@+import { Constants, EModelEndpoint } from 'librechat-data-provider';+import { getRequestId, getTenantId, getUserId } from '@librechat/data-schemas';+import type { AgentTriggerExecutionHostDeps, AgentTriggerFetch } from './host';+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' },+ 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.',+ });++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-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,+ timezone: 'America/New_York',+ });+ 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('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 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-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,+ });+ });+ });+});diff --git a/packages/api/src/agents/triggers/host.ts b/packages/api/src/agents/triggers/host.tsnew file mode 100644index 0000000000..a59be869b2--- /dev/null+++ b/packages/api/src/agents/triggers/host.ts@@ -0,0 +1,811 @@+import { tenantStorage } from '@librechat/data-schemas';+import { Constants, EModelEndpoint } from 'librechat-data-provider';+import type {+ AgentFireTriggerEnvelope,+ AgentSteerTriggerEnvelope,+ AgentTriggerEnvelope,+} from './envelope';+import type { AgentTriggerDispatchContext } from './dispatch';+import type { AgentRunPrincipal } from '../envelope';+import { dispatchAgentTrigger } from './dispatch';++const DEFAULT_FIRE_TIMEOUT_MS = 30_000;+const MAX_RESPONSE_BODY_BYTES = 64 * 1024;+const GENERATION_PROTOCOL_HEADER = 'x-librechat-generation-protocol';+const TRIGGER_USER_AGENT =+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' ++ '(KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36 LibreChat-Agent-Trigger/1';++const PRE_CONNECT_ERROR_CODES = new Set([+ 'ECONNREFUSED',+ 'ENOTFOUND',+ 'EAI_AGAIN',+ 'EHOSTUNREACH',+ 'ENETUNREACH',+ 'UND_ERR_CONNECT_TIMEOUT',+]);++type MaybePromise<T> = T | Promise<T>;+type FireStatus = 'started' | 'resumed' | 'replaced' | 'settled';++export type AgentTriggerFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;++export type AgentTriggerFailureCertainty = 'definite' | 'ambiguous';++export interface AgentTriggerExecutionErrorOptions {+ mode: 'fire' | 'steer';+ certainty: AgentTriggerFailureCertainty;+ retryable: boolean;+ code?: string;+ status?: number;+ retryAfter?: string;+}++/**+ * A typed delivery failure. `ambiguous` means the action may already be+ * committed; callers may retry only the same envelope so its idempotency key+ * remains unchanged.+ */+export class AgentTriggerExecutionError extends Error {+ readonly mode: 'fire' | 'steer';+ readonly certainty: AgentTriggerFailureCertainty;+ readonly retryable: boolean;+ readonly code?: string;+ readonly status?: number;+ readonly retryAfter?: string;++ constructor(message: string, options: AgentTriggerExecutionErrorOptions) {+ super(message);+ this.name = 'AgentTriggerExecutionError';+ this.mode = options.mode;+ this.certainty = options.certainty;+ this.retryable = options.retryable;+ this.code = options.code;+ this.status = options.status;+ this.retryAfter = options.retryAfter;+ }+}++export interface AgentTriggerFireResult {+ mode: 'fire';+ status: FireStatus;+ conversationId: string;+ streamId?: string;+ generationCreatedAt?: number;+}++export interface AgentTriggerSteerResult {+ mode: 'steer';+ status: 'queued';+ conversationId: string;+ steerId: string;+ position: number;+ preempt: boolean;+ preemptRevision?: number;+ replayed?: boolean;+ settled?: boolean;+ leftover?: boolean;+}++export type AgentTriggerExecutionResult = AgentTriggerFireResult | AgentTriggerSteerResult;++export interface AgentTriggerExecutionHostDeps {+ /** Trusted root URL for this LibreChat server. */+ getBaseUrl: () => string;+ /** Mint a short-lived token for the envelope's already-authenticated principal. */+ mintToken: (principal: AgentRunPrincipal, envelope: AgentTriggerEnvelope) => MaybePromise<string>;+ /** Optional user-timezone resolver for dynamic date variables in a new run. */+ getTimezone?: (+ principal: AgentRunPrincipal,+ envelope: AgentFireTriggerEnvelope,+ ) => MaybePromise<string | undefined>;+ fetch?: AgentTriggerFetch;+ /** Total bound for setup, admission, and the bounded response read. */+ timeoutMs?: number;+}++export interface AgentTriggerExecutionHost {+ dispatch: (+ envelope: unknown,+ options?: { signal?: AbortSignal },+ ) => Promise<AgentTriggerExecutionResult>;+}++interface AbortScope {+ signal: AbortSignal;+ abort: () => void;+ cleanup: () => void;+ timedOut: () => boolean;+}++interface BoundedResponseBody {+ text: string;+ truncated: boolean;+}++function executionError(+ message: string,+ options: AgentTriggerExecutionErrorOptions,+): AgentTriggerExecutionError {+ return new AgentTriggerExecutionError(message, options);+}++function requireTimeout(timeoutMs: number | undefined): number {+ const value = timeoutMs ?? DEFAULT_FIRE_TIMEOUT_MS;+ if (!Number.isSafeInteger(value) || value <= 0) {+ throw new TypeError('Agent trigger timeout must be a positive integer');+ }+ return value;+}++function abortScope(parent: AbortSignal | undefined, timeoutMs: number): AbortScope {+ const controller = new AbortController();+ let timeoutReached = false;+ const onAbort = () => controller.abort(parent?.reason);+ if (parent?.aborted === true) {+ onAbort();+ } else {+ parent?.addEventListener('abort', onAbort, { once: true });+ }+ const timeout = setTimeout(() => {+ timeoutReached = true;+ controller.abort();+ }, timeoutMs);+ return {+ signal: controller.signal,+ abort: () => controller.abort(),+ timedOut: () => timeoutReached,+ cleanup: () => {+ clearTimeout(timeout);+ parent?.removeEventListener('abort', onAbort);+ },+ };+}++function abortError(+ mode: 'fire' | 'steer',+ scope: AbortScope,+ parent: AbortSignal | undefined,+ stage: string,+ certainty: AgentTriggerFailureCertainty,+): AgentTriggerExecutionError {+ const code = abortCode(scope, parent, 'ABORTED');+ return executionError(+ `Agent trigger ${mode} was ${code === 'TIMEOUT' ? 'timed out' : 'aborted'} ${stage}`,+ {+ mode,+ certainty,+ retryable: true,+ code,+ },+ );+}++function observeAbort<T>(+ operation: () => MaybePromise<T>,+ mode: 'fire' | 'steer',+ scope: AbortScope,+ parent: AbortSignal | undefined,+): Promise<T> {+ if (scope.signal.aborted) {+ return Promise.reject(abortError(mode, scope, parent, 'before dispatch', 'definite'));+ }+ return new Promise<T>((resolve, reject) => {+ const onAbort = () => {+ scope.signal.removeEventListener('abort', onAbort);+ reject(abortError(mode, scope, parent, 'during setup', 'definite'));+ };+ scope.signal.addEventListener('abort', onAbort, { once: true });+ Promise.resolve()+ .then(operation)+ .then(+ (value) => {+ scope.signal.removeEventListener('abort', onAbort);+ resolve(value);+ },+ (error: unknown) => {+ scope.signal.removeEventListener('abort', onAbort);+ reject(error);+ },+ );+ });+}++async function setupValue<T>(+ operation: () => MaybePromise<T>,+ mode: 'fire' | 'steer',+ scope: AbortScope,+ parent: AbortSignal | undefined,+): Promise<T> {+ try {+ return await observeAbort(operation, mode, scope, parent);+ } catch (error) {+ if (error instanceof AgentTriggerExecutionError) {+ throw error;+ }+ throw executionError(+ `Agent trigger ${mode} setup failed: ${error instanceof Error ? error.message : String(error)}`,+ {+ mode,+ certainty: 'definite',+ retryable: true,+ code: 'SETUP_FAILED',+ },+ );+ }+}++async function readResponseBody(response: Response): Promise<BoundedResponseBody> {+ if (response.body == null) {+ return { text: '', truncated: false };+ }+ const reader = response.body.getReader();+ const decoder = new TextDecoder();+ let size = 0;+ const parts: string[] = [];+ try {+ while (true) {+ const chunk = await reader.read();+ if (chunk.done) {+ parts.push(decoder.decode());+ return { text: parts.join(''), truncated: false };+ }+ const remaining = MAX_RESPONSE_BODY_BYTES - size;+ if (chunk.value.byteLength > remaining) {+ if (remaining > 0) {+ parts.push(decoder.decode(chunk.value.subarray(0, remaining), { stream: true }));+ }+ parts.push(decoder.decode());+ await reader.cancel().catch(() => undefined);+ return { text: parts.join(''), truncated: true };+ }+ size += chunk.value.byteLength;+ parts.push(decoder.decode(chunk.value, { stream: true }));+ }+ } finally {+ reader.releaseLock();+ }+}++function errorCode(value: unknown): string | undefined {+ if (value == null || typeof value !== 'object' || !('code' in value)) {+ return undefined;+ }+ const code = value.code;+ return typeof code === 'string' && code.length > 0 ? code : undefined;+}++function errorMessage(value: unknown): string | undefined {+ if (value == null || typeof value !== 'object') {+ return undefined;+ }+ const record = value as Record<string, unknown>;+ for (const key of ['error', 'message', 'code']) {+ if (key in record) {+ const message = record[key];+ if (typeof message === 'string' && message.length > 0) {+ return message;+ }+ }+ }+ return undefined;+}++function parseJson(value: string): unknown {+ if (value.length === 0) {+ return undefined;+ }+ try {+ return JSON.parse(value) as unknown;+ } catch {+ return undefined;+ }+}++function fetchErrorCode(error: unknown): string | undefined {+ const read = (value: unknown): string | undefined => {+ if (value == null || typeof value !== 'object' || !('code' in value)) {+ return undefined;+ }+ const code = value.code;+ return typeof code === 'string' ? code : undefined;+ };+ if (error == null || typeof error !== 'object') {+ return undefined;+ }+ return ('cause' in error ? read(error.cause) : undefined) ?? read(error);+}++function isDefiniteConnectFailure(error: unknown): boolean {+ const code = fetchErrorCode(error);+ return (+ code != null &&+ (PRE_CONNECT_ERROR_CODES.has(code) || code.startsWith('ERR_TLS') || code.includes('CERT'))+ );+}++function isRetryableStatus(status: number): boolean {+ return status === 401 || status === 408 || status === 425 || status === 429 || status >= 500;+}++function isRetryableSteerRejection(status: number, code: string): boolean {+ return code === 'RUN_PAUSED' || isRetryableStatus(status);+}++function abortCode(scope: AbortScope, parent: AbortSignal | undefined, fallback: string): string {+ if (scope.timedOut()) {+ return 'TIMEOUT';+ }+ if (parent?.aborted === true) {+ return 'ABORTED';+ }+ return fallback;+}++function requireToken(value: unknown, mode: 'fire' | 'steer'): string {+ if (typeof value !== 'string' || value.length === 0 || /\s/.test(value)) {+ throw executionError('Agent trigger token mint returned an invalid token', {+ mode,+ certainty: 'definite',+ retryable: false,+ code: 'INVALID_TOKEN',+ });+ }+ return value;+}++function triggerUrl(baseUrl: string, path: string, mode: 'fire' | 'steer'): string {+ let url: URL;+ try {+ url = new URL(baseUrl);+ } catch {+ throw executionError('Agent trigger base URL is invalid', {+ mode,+ certainty: 'definite',+ retryable: false,+ code: 'INVALID_BASE_URL',+ });+ }+ if ((url.protocol !== 'http:' && url.protocol !== 'https:') || url.username || url.password) {+ throw executionError('Agent trigger base URL must be an HTTP(S) URL without credentials', {+ mode,+ certainty: 'definite',+ retryable: false,+ code: 'INVALID_BASE_URL',+ });+ }+ url.pathname = `${url.pathname.replace(/\/+$/, '')}${path}`;+ url.search = '';+ url.hash = '';+ return url.toString();+}++function fireUrl(baseUrl: string): string {+ return triggerUrl(baseUrl, `/api/agents/chat/${EModelEndpoint.agents}`, 'fire');+}++function steerUrl(baseUrl: string): string {+ return triggerUrl(baseUrl, '/api/agents/chat/steer/deliver', 'steer');+}++function requireString(value: unknown): string | undefined {+ return typeof value === 'string' && value.length > 0 ? value : undefined;+}++function requireSafeInteger(value: unknown): number | undefined {+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;+}++function fireStatus(value: unknown): FireStatus | undefined {+ return value === 'started' || value === 'resumed' || value === 'replaced' || value === 'settled'+ ? value+ : undefined;+}++function parseFireResult(payload: unknown): AgentTriggerFireResult | undefined {+ if (payload == null || typeof payload !== 'object') {+ return undefined;+ }+ const status = fireStatus('status' in payload ? payload.status : undefined);+ const conversationId = requireString(+ 'conversationId' in payload ? payload.conversationId : undefined,+ );+ if (status == null || conversationId == null) {+ return undefined;+ }+ const streamId = requireString('streamId' in payload ? payload.streamId : undefined);+ if (status !== 'settled' && streamId == null) {+ return undefined;+ }+ const generationCreatedAt = requireSafeInteger(+ 'generationCreatedAt' in payload ? payload.generationCreatedAt : undefined,+ );+ return {+ mode: 'fire',+ status,+ conversationId,+ ...(streamId != null && { streamId }),+ ...(generationCreatedAt != null && { generationCreatedAt }),+ };+}++async function fire(+ envelope: AgentFireTriggerEnvelope,+ context: AgentTriggerDispatchContext,+ deps: AgentTriggerExecutionHostDeps,+ timeoutMs: number,+): Promise<AgentTriggerFireResult> {+ const scope = abortScope(context.signal, timeoutMs);+ try {+ const [token, timezone, baseUrl] = await Promise.all([+ setupValue(+ () => deps.mintToken(envelope.principal, envelope),+ 'fire',+ scope,+ context.signal,+ ).then((value) => requireToken(value, 'fire')),+ setupValue(+ () => deps.getTimezone?.(envelope.principal, envelope),+ 'fire',+ scope,+ context.signal,+ ),+ setupValue(() => deps.getBaseUrl(), 'fire', scope, context.signal),+ ]).catch((error: unknown) => {+ scope.abort();+ throw error;+ });+ const url = fireUrl(baseUrl);+ const fetcher: AgentTriggerFetch = deps.fetch ?? globalThis.fetch;+ let response: Response;+ try {+ response = await fetcher(url, {+ method: 'POST',+ signal: scope.signal,+ headers: {+ Accept: 'application/json',+ Authorization: `Bearer ${token}`,+ 'Content-Type': 'application/json',+ 'User-Agent': TRIGGER_USER_AGENT,+ 'x-request-id': context.idempotencyKey,+ [GENERATION_PROTOCOL_HEADER]: '2',+ },+ body: JSON.stringify({+ text: envelope.input,+ endpoint: EModelEndpoint.agents,+ agent_id: envelope.target.agentId,+ parentMessageId: Constants.NO_PARENT,+ isContinued: false,+ isRegenerate: false,+ clientRequestId: context.idempotencyKey,+ generationProtocolVersion: 2,+ ...(typeof timezone === 'string' && timezone.trim().length > 0+ ? { timezone: timezone.trim() }+ : {}),+ }),+ });+ } catch (error) {+ const definite = isDefiniteConnectFailure(error);+ const message = error instanceof Error ? error.message : String(error);+ throw executionError(+ `Agent trigger fire ${definite ? 'could not connect' : 'has an unknown outcome'}: ${message}`,+ {+ mode: 'fire',+ certainty: definite ? 'definite' : 'ambiguous',+ retryable: true,+ code: abortCode(scope, context.signal, 'NETWORK_ERROR'),+ },+ );+ }++ let boundedBody: BoundedResponseBody = { text: '', truncated: false };+ try {+ boundedBody = await readResponseBody(response);+ } catch (error) {+ if (response.ok) {+ throw executionError(+ `Agent trigger fire response has an unknown outcome: ${+ error instanceof Error ? error.message : String(error)+ }`,+ {+ mode: 'fire',+ certainty: 'ambiguous',+ retryable: true,+ code: abortCode(scope, context.signal, 'INVALID_RESPONSE'),+ status: response.status,+ },+ );+ }+ }+ const payload = parseJson(boundedBody.text);+ if (!response.ok) {+ const message =+ errorMessage(payload) ?? (boundedBody.text.slice(0, 300) || 'request rejected');+ throw executionError(`Agent trigger fire was rejected (${response.status}): ${message}`, {+ mode: 'fire',+ certainty: 'definite',+ retryable: isRetryableStatus(response.status),+ code: errorCode(payload) ?? 'FIRE_REJECTED',+ status: response.status,+ ...(response.headers.get('retry-after') != null && {+ retryAfter: response.headers.get('retry-after') ?? undefined,+ }),+ });+ }+ if (boundedBody.truncated) {+ throw executionError('Agent trigger fire returned an oversized success response', {+ mode: 'fire',+ certainty: 'ambiguous',+ retryable: true,+ code: 'RESPONSE_TOO_LARGE',+ status: response.status,+ });+ }+ if (+ payload != null &&+ typeof payload === 'object' &&+ 'status' in payload &&+ payload.status === 'aborted'+ ) {+ throw executionError('Agent trigger fire was aborted before generation started', {+ mode: 'fire',+ certainty: 'definite',+ retryable: false,+ code: 'START_ABORTED',+ status: response.status,+ });+ }+ const result = parseFireResult(payload);+ if (result == null) {+ throw executionError('Agent trigger fire returned an invalid success response', {+ mode: 'fire',+ certainty: 'ambiguous',+ retryable: true,+ code: 'INVALID_RESPONSE',+ status: response.status,+ });+ }+ return result;+ } finally {+ scope.cleanup();+ }+}++function parseSteerResult(payload: unknown): AgentTriggerSteerResult | undefined {+ if (payload == null || typeof payload !== 'object' || !('status' in payload)) {+ return undefined;+ }+ if (payload.status !== 'queued') {+ return undefined;+ }+ const conversationId = requireString(+ 'conversationId' in payload ? payload.conversationId : undefined,+ );+ const steerId = requireString('steerId' in payload ? payload.steerId : undefined);+ const position = requireSafeInteger('position' in payload ? payload.position : undefined);+ if (+ conversationId == null ||+ steerId == null ||+ position == null ||+ !('preempt' in payload) ||+ typeof payload.preempt !== 'boolean'+ ) {+ return undefined;+ }+ const preemptRevision = requireSafeInteger(+ 'preemptRevision' in payload ? payload.preemptRevision : undefined,+ );+ return {+ mode: 'steer',+ status: 'queued',+ conversationId,+ steerId,+ position,+ preempt: payload.preempt,+ ...(preemptRevision != null && { preemptRevision }),+ ...('replayed' in payload &&+ typeof payload.replayed === 'boolean' && {+ replayed: payload.replayed,+ }),+ ...('settled' in payload &&+ typeof payload.settled === 'boolean' && {+ settled: payload.settled,+ }),+ ...('leftover' in payload &&+ typeof payload.leftover === 'boolean' && {+ leftover: payload.leftover,+ }),+ };+}++async function steer(+ envelope: AgentSteerTriggerEnvelope,+ context: AgentTriggerDispatchContext,+ deps: AgentTriggerExecutionHostDeps,+ timeoutMs: number,+): Promise<AgentTriggerSteerResult> {+ const scope = abortScope(context.signal, timeoutMs);+ try {+ const [token, baseUrl] = await Promise.all([+ setupValue(+ () => deps.mintToken(envelope.principal, envelope),+ 'steer',+ scope,+ context.signal,+ ).then((value) => requireToken(value, 'steer')),+ setupValue(() => deps.getBaseUrl(), 'steer', scope, context.signal),+ ]).catch((error: unknown) => {+ scope.abort();+ throw error;+ });+ const url = steerUrl(baseUrl);+ const fetcher: AgentTriggerFetch = deps.fetch ?? globalThis.fetch;+ let response: Response;+ try {+ response = await fetcher(url, {+ method: 'POST',+ signal: scope.signal,+ headers: {+ Accept: 'application/json',+ Authorization: `Bearer ${token}`,+ 'Content-Type': 'application/json',+ 'User-Agent': TRIGGER_USER_AGENT,+ 'x-request-id': context.idempotencyKey,+ [GENERATION_PROTOCOL_HEADER]: '2',+ },+ body: JSON.stringify({+ agentId: envelope.target.agentId,+ conversationId: envelope.target.conversationId,+ generationCreatedAt: envelope.target.generationCreatedAt,+ text: envelope.input,+ clientSteerId: context.idempotencyKey,+ preempt: envelope.target.preempt === true,+ generationProtocolVersion: 2,+ }),+ });+ } catch (error) {+ const definite = isDefiniteConnectFailure(error);+ throw executionError(+ `Agent trigger steer ${definite ? 'could not connect' : 'has an unknown outcome'}: ${+ error instanceof Error ? error.message : String(error)+ }`,+ {+ mode: 'steer',+ certainty: definite ? 'definite' : 'ambiguous',+ retryable: true,+ code: abortCode(scope, context.signal, 'NETWORK_ERROR'),+ },+ );+ }++ let boundedBody: BoundedResponseBody = { text: '', truncated: false };+ try {+ boundedBody = await readResponseBody(response);+ } catch (error) {+ if (response.ok) {+ throw executionError(+ `Agent trigger steer response has an unknown outcome: ${+ error instanceof Error ? error.message : String(error)+ }`,+ {+ mode: 'steer',+ certainty: 'ambiguous',+ retryable: true,+ code: abortCode(scope, context.signal, 'INVALID_RESPONSE'),+ status: response.status,+ },+ );+ }+ }++ const payload = parseJson(boundedBody.text);+ if (response.status !== 202) {+ const responseCode = errorCode(payload);+ const routeUnavailable = response.status === 404 && responseCode == null;+ const code = routeUnavailable+ ? 'STEER_ADMISSION_UNAVAILABLE'+ : (responseCode ?? 'STEER_REJECTED');+ throw executionError(+ `Agent trigger steer was rejected (${response.status}): ${errorMessage(payload) ?? code}`,+ {+ mode: 'steer',+ certainty: 'definite',+ retryable: routeUnavailable || isRetryableSteerRejection(response.status, code),+ code,+ status: response.status,+ ...(response.headers.get('retry-after') != null && {+ retryAfter: response.headers.get('retry-after') ?? undefined,+ }),+ },+ );+ }+ if (boundedBody.truncated) {+ throw executionError('Agent trigger steer returned an oversized success response', {+ mode: 'steer',+ certainty: 'ambiguous',+ retryable: true,+ code: 'RESPONSE_TOO_LARGE',+ status: response.status,+ });+ }+ if (+ payload == null ||+ typeof payload !== 'object' ||+ !('generationProtocolVersion' in payload) ||+ payload.generationProtocolVersion !== 2+ ) {+ throw executionError('Agent trigger steer was accepted without a v2 receipt guarantee', {+ mode: 'steer',+ certainty: 'ambiguous',+ retryable: false,+ code: 'STEER_IDEMPOTENCY_UNAVAILABLE',+ status: response.status,+ });+ }+ const parsed = parseSteerResult(payload);+ if (parsed == null) {+ throw executionError('Agent trigger steer returned an invalid success response', {+ mode: 'steer',+ certainty: 'ambiguous',+ retryable: true,+ code: 'INVALID_RESPONSE',+ status: response.status,+ });+ }+ if (parsed.conversationId !== envelope.target.conversationId) {+ throw executionError('Agent trigger steer returned a mismatched conversation', {+ mode: 'steer',+ certainty: 'ambiguous',+ retryable: true,+ code: 'INVALID_RESPONSE',+ status: response.status,+ });+ }+ return parsed;+ } finally {+ scope.cleanup();+ }+}++function runAsPrincipal<T>(+ envelope: AgentTriggerEnvelope,+ context: AgentTriggerDispatchContext,+ fn: () => Promise<T>,+): Promise<T> {+ return tenantStorage.run(+ {+ userId: envelope.principal.userId,+ tenantId: envelope.principal.tenantId,+ requestId: context.idempotencyKey,+ },+ fn,+ );+}++/**+ * Creates the trusted, source-neutral execution host. Schedules, webhooks,+ * queues, MCP adapters, and internal events all call the same `dispatch` and+ * therefore share authorization, idempotency, tenant, and failure semantics.+ */+export function createAgentTriggerExecutionHost(+ deps: AgentTriggerExecutionHostDeps,+): AgentTriggerExecutionHost {+ const timeoutMs = requireTimeout(deps.timeoutMs);+ return {+ dispatch: (envelope, options) =>+ Promise.resolve().then(() =>+ dispatchAgentTrigger(+ envelope,+ {+ fire: (normalized, context) =>+ runAsPrincipal(normalized, context, () => fire(normalized, context, deps, timeoutMs)),+ steer: (normalized, context) =>+ runAsPrincipal(normalized, context, () =>+ steer(normalized, context, deps, timeoutMs),+ ),+ },+ options,+ ),+ ),+ };+}diff --git a/packages/api/src/agents/triggers/index.ts b/packages/api/src/agents/triggers/index.tsnew file mode 100644index 0000000000..3c75f2ba09--- /dev/null+++ b/packages/api/src/agents/triggers/index.ts@@ -0,0 +1,3 @@+export * from './dispatch';+export * from './envelope';+export * from './host';