From fad2c51da41bb46c9cdd44a720cea4df0d47876b Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Fri, 13 Nov 2026 13:02:53 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=8F=87=20feat:=20Register=20SDK-Backed=20?= =?UTF-8?q?Agents=20for=20Native=20Chat=20(#18114)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: register SDK-backed agents through agent management * fix: gate SDK binding writes and preserve native lifecycle --- api/server/controllers/agents/v1.js | 30 ++- docs/sdk/agents.md | 93 +++++++ e2e/config/librechat.e2e.yaml | 4 + e2e/setup/sdk-runtime.cjs | 11 + e2e/specs/mock/agent-management-files.spec.ts | 85 +++++++ packages/api/openapi/agents.openapi.json | 75 ++++++ packages/api/src/agents/index.ts | 1 + packages/api/src/agents/management.ts | 1 + packages/api/src/agents/run.ts | 23 +- packages/api/src/agents/sdk.spec.ts | 229 ++++++++++++++++++ packages/api/src/agents/sdk.ts | 139 +++++++++++ packages/api/src/agents/validation.ts | 3 + packages/data-provider/src/config.ts | 12 + packages/data-provider/src/types/agents.ts | 13 + .../data-schemas/src/methods/agent.spec.ts | 18 ++ packages/data-schemas/src/methods/agent.ts | 1 + .../data-schemas/src/schema/agent.sdk.spec.ts | 28 +++ packages/data-schemas/src/schema/agent.ts | 10 + packages/data-schemas/src/types/agent.ts | 2 + 19 files changed, 775 insertions(+), 3 deletions(-) create mode 100644 docs/sdk/agents.md create mode 100644 e2e/setup/sdk-runtime.cjs create mode 100644 packages/api/src/agents/sdk.spec.ts create mode 100644 packages/api/src/agents/sdk.ts create mode 100644 packages/data-schemas/src/schema/agent.sdk.spec.ts diff --git a/api/server/controllers/agents/v1.js b/api/server/controllers/agents/v1.js index e1998f278b..32f16a0aa5 100644 --- a/api/server/controllers/agents/v1.js +++ b/api/server/controllers/agents/v1.js @@ -53,6 +53,8 @@ const { applyInstructionsPromptUnset, instructionsContentForScan, authorizeAgentRestore, + applySdkAgentBindingWrite, + getSdkAgentWriteErrorStatus, } = require('@librechat/api'); const { Time, @@ -765,6 +767,12 @@ const createAgentHandler = async (req, res) => { normalizeToolResourceFiles(req.body?.tool_resources); const validatedData = agentCreateSchema.parse(req.body); const { tools = [], ...agentData } = removeNullishValues(validatedData); + applySdkAgentBindingWrite( + agentData, + validatedData.sdk_runtime, + req.config?.endpoints?.agents, + req.user?.role, + ); if ( (!isCodeInterpreterCapabilityEnabled(req) || !tools.includes(Tools.execute_code)) && @@ -1109,6 +1117,12 @@ const updateAgentHandler = async (req, res) => { ...rest } = validatedData; let updateData = removeNullishValues(rest); + applySdkAgentBindingWrite( + updateData, + validatedData.sdk_runtime, + req.config?.endpoints?.agents, + req.user?.role, + ); if (codeEnvironmentIdField !== undefined) { updateData.code_environment_id = codeEnvironmentIdField; } @@ -1519,6 +1533,12 @@ const duplicateAgentHandler = async (req, res) => { id: newAgentId, author: userId, }); + applySdkAgentBindingWrite( + newAgentData, + newAgentData.sdk_runtime, + req.config?.endpoints?.agents, + req.user?.role, + ); if (!validateAgentCodeEnvironmentAllowlist(req, res, newAgentData.code_environment_ids)) { return; } @@ -1746,7 +1766,7 @@ const duplicateAgentHandler = async (req, res) => { if (error?.statusCode === 409) { return res.status(409).json({ error: error.message }); } - res.status(500).json({ error: error.message }); + res.status(getSdkAgentWriteErrorStatus(error)).json({ error: error.message }); } }; @@ -2096,6 +2116,12 @@ const revertAgentVersionHandler = async (req, res) => { if (!revertVersion) { return res.status(404).json({ error: `Version ${version_index} not found` }); } + applySdkAgentBindingWrite( + revertVersion, + revertVersion.sdk_runtime, + req.config?.endpoints?.agents, + req.user?.role, + ); if (!validateAgentCodeEnvironmentAllowlist(req, res, revertVersion.code_environment_ids)) { return; } @@ -2260,7 +2286,7 @@ const revertAgentVersionHandler = async (req, res) => { if (error?.statusCode === 409) { return res.status(409).json({ error: error.message }); } - res.status(500).json({ error: error.message }); + res.status(getSdkAgentWriteErrorStatus(error)).json({ error: error.message }); } }; /** diff --git a/docs/sdk/agents.md b/docs/sdk/agents.md new file mode 100644 index 0000000000..431f79a9f3 --- /dev/null +++ b/docs/sdk/agents.md @@ -0,0 +1,93 @@ +# Registering SDK-backed agents + +An SDK-backed agent is an ordinary saved agent with an operator-installed execution binding. +Create, discover, share, version, and delete it through the existing Agents Management API. +Select it in the normal agent picker; chat uses the native SDK handlers, persistence, approvals, +and cancellation paths. The runtime returns a real `@librechat/agents` `Run` instead of translating +events into a second chat protocol. + +## Install a trusted runtime + +Install the module in the LibreChat server environment and configure it in `librechat.yaml`: + +```yaml +endpoints: + agents: + sdkRuntimes: + schema-advisor: + module: ./runtimes/schema-advisor.cjs + roles: [ADMIN] +``` + +Paths resolve from the server working directory. Package names are supported too. Modules are +trusted server code with the server process's privileges; only operators configure them. +Agent requests cannot supply module paths, URLs, code, or credentials. Runtime use is disabled +unless its ID is configured and the authenticated caller's role is in `roles` (default: `ADMIN`). +The normal saved-agent permissions continue to apply. Restart the server after changing a module; +Node caches installed modules. + +The module exports this contract (types are exported by `@librechat/api`): + +```js +const { Run } = require('@librechat/agents'); + +module.exports = { + protocolVersion: 1, + async createRun({ config, identity }) { + // Use identity.agentId as the saved identity and identity.runId for this execution. + // Customize the graph with your SDK integration here. Retain the host-owned config: + // handlers, hooks, signal, checkpointing, policy, and usage callbacks. + return Run.create(config); + }, +}; +``` + +Use the server's installed SDK as a peer dependency so the returned Run uses the same SDK +instance as the host. The immutable identity contains `agentId`, `runtimeId`, `runId`, +`userId`, and optional `conversationId` and `tenantId`, all supplied by the server. Stateless +execution APIs do not invent a saved conversation identity. A module must not +replace authenticated identity or broaden the caller's tool permissions. A different run ID is +rejected before execution. + +## Register the agent + +Using the existing management credentials, create through `POST /api/agents/v1/agents`: + +```json +{ + "name": "Schema Advisor", + "provider": "openAI", + "model": "gpt-4.1", + "sdk_runtime": { "id": "schema-advisor", "protocolVersion": 1 } +} +``` + +Provider/model continue to use the host's native configured endpoint and model policies. +The response has the usual server-assigned agent ID and the binding. Use that ID in the agent +picker or existing execution APIs. `PATCH /api/agents/v1/agents/:id` can replace the binding; +`sdk_runtime: null` returns the agent to native execution. Ownership, sharing, and version access +are unchanged. The binding grants no authority by itself. + +## Compatibility and validation + +Protocol 1 runs inside the LibreChat process. It establishes saved identity and execution binding; +it does not claim remote process isolation or an HTTP registration/event-ingestion protocol. +Native agent chains and configured native subagent compositions containing a runtime binding +are rejected rather than silently ignoring execution bindings. A runtime can construct its own SDK graph while retaining the host configuration. + +Before enabling a runtime for a role, verify text/tool events, final persistence, retry, stop, +approval/resume when used, org switching, and latency against the same native agent. A factory +that drops the host's handlers or hooks does not satisfy the integration contract. Loading an +unknown module/version fails closed; normal agents require no runtime module or extra database read. + +## Rollout and rollback + +Deploy the supporting code to every replica before adding `sdkRuntimes` configuration and +registering bindings. Older servers do not understand this field and could execute the agent +as a native agent. Creation, update, duplication, and version restoration reject non-null +bindings unless the runtime is configured for the caller's role. + +Before downgrading any replica, remove the runtime configuration to stop new bindings and +clear existing bindings with `sdk_runtime: null`. Verify that no active runs or current agent +bindings depend on a runtime before the downgrade. Removing configuration alone disables +execution on supported servers; it does not rewrite stored agents. diff --git a/e2e/config/librechat.e2e.yaml b/e2e/config/librechat.e2e.yaml index dd4c863780..91590c6c83 100644 --- a/e2e/config/librechat.e2e.yaml +++ b/e2e/config/librechat.e2e.yaml @@ -180,6 +180,10 @@ endpoints: # Default capabilities plus run_in_background (off by default upstream) so the # background tool-call e2e can opt an MCP tool into detached dispatch. agents: + sdkRuntimes: + e2e-sdk: + module: ./e2e/setup/sdk-runtime.cjs + roles: [ADMIN] subagentActivity: contentRecoveryEnabled: true fileSharing: diff --git a/e2e/setup/sdk-runtime.cjs b/e2e/setup/sdk-runtime.cjs new file mode 100644 index 0000000000..3312665e34 --- /dev/null +++ b/e2e/setup/sdk-runtime.cjs @@ -0,0 +1,11 @@ +const { Run } = require('@librechat/agents'); + +module.exports = { + protocolVersion: 1, + async createRun({ config, identity }) { + if (!Object.isFrozen(identity) || identity.runId !== config.runId || !identity.userId) { + throw new Error('SDK runtime identity was not established by the host'); + } + return Run.create(config); + }, +}; diff --git a/e2e/specs/mock/agent-management-files.spec.ts b/e2e/specs/mock/agent-management-files.spec.ts index 20bf4dfae5..4a9129d9c8 100644 --- a/e2e/specs/mock/agent-management-files.spec.ts +++ b/e2e/specs/mock/agent-management-files.spec.ts @@ -1,4 +1,6 @@ import fs from 'fs'; +import jwt from 'jsonwebtoken'; +import { randomUUID } from 'crypto'; import path from 'path'; import mongoose from 'mongoose'; import { expect, test } from '@playwright/test'; @@ -72,6 +74,89 @@ test.describe('agent management file lifecycle', () => { } }); + test('registers an SDK agent and executes it through native chat and persistence', async ({ + request, + }) => { + const binding = { id: 'e2e-sdk', protocolVersion: 1 }; + const created = await request.post(agentsPath, { + headers, + data: { + name: 'SDK runtime agent', + provider: 'Mock Provider A', + model: 'mock-model-a', + sdk_runtime: binding, + }, + }); + expect(created.status(), await created.text()).toBe(201); + const agent = await created.json(); + expect(agent.sdk_runtime).toEqual(binding); + const secret = process.env.JWT_SECRET; + if (!secret) throw new Error('Test JWT secret is unavailable'); + const chatHeaders = { + Authorization: `Bearer ${jwt.sign({ id: managementUserId }, secret, { expiresIn: '5m' })}`, + 'X-Tenant-Id': managementTenantId, + 'User-Agent': 'Mozilla/5.0 Chrome/126.0.0.0 Safari/537.36', + }; + try { + const read = await request.get(`${agentsPath}/${agent.id}`, { headers }); + expect((await read.json()).sdk_runtime).toEqual(binding); + const run = async () => { + const admitted = await request.post('/api/agents/chat/agents', { + headers: chatHeaders, + data: { + text: 'E2E_REPLY:sdk-runtime', + sender: 'User', + isCreatedByUser: true, + parentMessageId: '00000000-0000-0000-0000-000000000000', + messageId: randomUUID(), + endpoint: 'agents', + agent_id: agent.id, + key: 'never', + isTemporary: false, + isRegenerate: false, + isContinued: false, + }, + }); + expect(admitted.status(), await admitted.text()).toBe(200); + const { streamId, conversationId } = await admitted.json(); + const stream = await request.get(`/api/agents/chat/stream/${streamId}`, { + headers: chatHeaders, + }); + expect(stream.status(), await stream.text()).toBe(200); + const saved = await request.get(`/api/messages/${conversationId}`, { + headers: chatHeaders, + }); + expect(saved.status(), await saved.text()).toBe(200); + return JSON.stringify(await saved.json()); + }; + expect(await run()).toContain('E2E reply sdk-runtime'); + const changed = await request.patch(`${agentsPath}/${agent.id}`, { + headers, + data: { sdk_runtime: { id: 'not-configured', protocolVersion: 1 } }, + }); + expect(changed.status(), await changed.text()).toBe(400); + // Simulate an existing binding whose operator configuration was removed. + await withMongo(async (db) => { + await db + .collection('agents') + .updateOne( + { id: agent.id, tenantId: managementTenantId }, + { $set: { sdk_runtime: { id: 'not-configured', protocolVersion: 1 } } }, + ); + }); + expect(await run()).not.toContain('E2E reply sdk-runtime'); + const cleared = await request.patch(`${agentsPath}/${agent.id}`, { + headers, + data: { sdk_runtime: null }, + }); + expect(cleared.status(), await cleared.text()).toBe(200); + expect((await cleared.json()).sdk_runtime).toBeNull(); + expect(await run()).toContain('E2E reply sdk-runtime'); + } finally { + await request.delete(`${agentsPath}/${agent.id}`, { headers }); + } + }); + for (const purpose of ['context', 'file_search', 'execute_code']) { test(`uploads, persists, lists and unlinks ${purpose} files`, async ({ request }) => { const created = await request.post(agentsPath, { diff --git a/packages/api/openapi/agents.openapi.json b/packages/api/openapi/agents.openapi.json index 70fc480355..e58559a50d 100644 --- a/packages/api/openapi/agents.openapi.json +++ b/packages/api/openapi/agents.openapi.json @@ -2381,6 +2381,31 @@ "AgentCreateRequest": { "type": "object", "properties": { + "sdk_runtime": { + "anyOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" + }, + "protocolVersion": { + "type": "number", + "const": 1 + } + }, + "required": [ + "id", + "protocolVersion" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, "name": { "type": [ "string", @@ -2872,6 +2897,31 @@ "AgentUpdateRequest": { "type": "object", "properties": { + "sdk_runtime": { + "anyOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" + }, + "protocolVersion": { + "type": "number", + "const": 1 + } + }, + "required": [ + "id", + "protocolVersion" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, "name": { "type": "string" }, @@ -3344,6 +3394,31 @@ "Agent": { "type": "object", "properties": { + "sdk_runtime": { + "anyOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" + }, + "protocolVersion": { + "type": "number", + "const": 1 + } + }, + "required": [ + "id", + "protocolVersion" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, "name": { "type": [ "string", diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.ts index 31129d3ef4..935dce7bd7 100644 --- a/packages/api/src/agents/index.ts +++ b/packages/api/src/agents/index.ts @@ -75,6 +75,7 @@ export * from './run'; export * from './fading'; export * from './publication'; export * from './runtime'; +export * from './sdk'; export * from './convoPersistence'; export * from './testHook'; export * from './tools'; diff --git a/packages/api/src/agents/management.ts b/packages/api/src/agents/management.ts index d331b226e4..16481b6d88 100644 --- a/packages/api/src/agents/management.ts +++ b/packages/api/src/agents/management.ts @@ -277,6 +277,7 @@ export function projectAgentManagementResponse( return agentManagementResponseSchema.parse({ id: source.id, provider: source.provider, + sdk_runtime: source.sdk_runtime, model: source.model, version: getVersion(source), createdAt: toTimestamp(source.createdAt), diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.ts index 9b90a9bde4..0e0dc492ca 100644 --- a/packages/api/src/agents/run.ts +++ b/packages/api/src/agents/run.ts @@ -69,6 +69,7 @@ import type { ReviewedToolApprovals } from './hitl/modes'; import type { SubagentUsageEvent } from '~/agents/usage'; import type { ProvisionState } from '~/agents/resources'; import type { RunFileSession } from './files/session'; +import type { SdkAgentRuntimeLoader } from './sdk'; import type { RunFadingTiers } from './fading'; import type * as t from '~/types'; import { @@ -122,6 +123,7 @@ import { applyCustomHandoffPromptKeyCompatibility } from '~/agents/handoffPrompt import { stripIntentFromToolRegistry, stripIntentFromToolDefinitions } from '~/agents/intent'; import { createAgentToolApprovalSession, bindRunToolApprovalSession } from './hitl/modes'; import { resolveConfigHeaders, resolveModelHeaders, mergeHeaders } from '~/utils/headers'; +import { createSdkAgentRun, resolveSdkAgentBinding, SdkAgentRuntimeError } from './sdk'; import { interruptToolHandler, supportsRunInterruption } from '~/agents/steering/tools'; import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm'; import { reportSubagentResolutionFailure } from '~/agents/failures/subagent'; @@ -2316,6 +2318,7 @@ export async function createRun({ toolApprovalAllows, toolInputValidationErrors, sessionStartSource, + loadSdkRuntime, streaming = true, streamUsage = true, }: { @@ -2470,11 +2473,13 @@ export async function createRun({ sessionStartSource?: string; /** Request-scoped tool input failures consumed by the completion handler. */ toolInputValidationErrors?: Map; + loadSdkRuntime?: SdkAgentRuntimeLoader; } & Pick< RunConfig, 'tokenCounter' | 'customHandlers' | 'indexTokenCountMap' | 'initialSessions' >): Promise> { const resolvedRunId = runId ?? randomUUID(); + const registration = resolveSdkAgentBinding(agents, appConfig?.endpoints?.agents, user?.role); const runFilesActive = runFiles?.activate( resolvedRunId, @@ -2548,6 +2553,9 @@ export async function createRun({ const preparedCodeFileAgents = new WeakSet(codeFileAgents.values()); const buildAgentInput = (agent: RunAgent, opts: { isSubagent?: boolean } = {}): AgentInputs => { + if (agent.id !== agents[0]?.id && agent.sdk_runtime != null) { + throw new SdkAgentRuntimeError('sdk_runtime_composition_unsupported'); + } if (!preparedCodeFileAgents.has(agent)) { if (agent.provisionState) agent.provisionState.codeEnvDestinations = undefined; codeFileAgents.set(agent.id, agent); @@ -3309,7 +3317,20 @@ export async function createRun({ // older versions ignore the field. ...(streamLimits && { streamLimits }), }; - const run = await Run.create(runConfig); + const run = registration + ? await createSdkAgentRun({ + registration, + config: runConfig, + loadModule: loadSdkRuntime, + signal, + identity: { + agentId: agents[0].id, + conversationId: conversationId ?? requestBody?.conversationId ?? undefined, + userId: user?.id ?? '', + tenantId: tenantId ?? user?.tenantId, + }, + }) + : await Run.create(runConfig); if (approvalWiring != null) bindRunToolApprovalSession(run, agentApprovalSession); runMCPToolAliases.set(run, mcpToolAliases); diff --git a/packages/api/src/agents/sdk.spec.ts b/packages/api/src/agents/sdk.spec.ts new file mode 100644 index 0000000000..e67f249b65 --- /dev/null +++ b/packages/api/src/agents/sdk.spec.ts @@ -0,0 +1,229 @@ +import { agentsEndpointSchema } from 'librechat-data-provider'; +import { HumanMessage } from '@librechat/agents/langchain/messages'; +import { Run, Providers, GraphEvents, FakeChatModel } from '@librechat/agents'; +import type { AppConfig, IUser } from '@librechat/data-schemas'; +import type { RunConfig } from '@librechat/agents'; +import { createSdkAgentRun, resolveSdkAgentBinding, applySdkAgentBindingWrite } from './sdk'; +import { agentManagementCreateSchema, projectAgentManagementResponse } from './management'; +import { createRun } from './run'; + +const binding = { id: 'schema-advisor', protocolVersion: 1 as const }; +const identity = { + agentId: 'agent_saved', + userId: 'authenticated', + tenantId: 'authorized', + conversationId: 'conversation', +}; +const endpoint = { + sdkRuntimes: { 'schema-advisor': { module: './approved.cjs', roles: ['ADMIN'] } }, +}; +function config(): RunConfig { + return { + runId: 'run_server', + skipCleanup: true, + tokenCounter: () => 1, + graphConfig: { + type: 'standard', + maxContextTokens: 100_000, + llmConfig: { provider: Providers.OPENAI, streaming: true, apiKey: 'test' }, + tools: [], + }, + }; +} +function args() { + return { registration: { binding, module: './approved.cjs' }, config: config(), identity }; +} + +describe('SDK agent registration and native execution', () => { + it('dispatches the root through the full host path, including isolated-input prebuilding', async () => { + const factory = jest.fn(async ({ config: cfg }: { config: RunConfig }) => { + const run = await Run.create(cfg); + if (!run.Graph) throw new Error('Missing graph'); + run.Graph.overrideModel = new FakeChatModel({ responses: ['Host SDK reply'] }); + return run; + }); + const deltas: string[] = []; + const run = await createRun({ + runId: 'host-sdk-run', + conversationId: identity.conversationId, + signal: new AbortController().signal, + messages: [new HumanMessage('hello')], + tokenCounter: () => 1, + user: { id: identity.userId, role: 'ADMIN', tenantId: identity.tenantId } as IUser, + appConfig: { endpoints: { agents: agentsEndpointSchema.parse(endpoint) } } as AppConfig, + agents: [ + { + id: identity.agentId, + name: 'SDK agent', + description: '', + created_at: 0, + avatar: null, + provider: Providers.OPENAI, + model: 'gpt-4.1', + model_parameters: { + model: 'gpt-4.1', + temperature: null, + maxContextTokens: null, + max_context_tokens: null, + max_output_tokens: null, + top_p: null, + frequency_penalty: null, + presence_penalty: null, + }, + sdk_runtime: binding, + }, + ], + customHandlers: { + [GraphEvents.ON_MESSAGE_DELTA]: { + handle: async () => { + deltas.push('delta'); + }, + }, + }, + loadSdkRuntime: () => ({ protocolVersion: 1, createRun: factory }), + }); + expect(factory).toHaveBeenCalledTimes(1); + await run.processStream({ messages: [new HumanMessage('hello')] }, { version: 'v2' }); + expect(deltas).toContain('delta'); + }); + it('gates all binding writes and retains explicit removal', () => { + const patch: { sdk_runtime?: typeof binding | null } = {}; + expect(() => applySdkAgentBindingWrite(patch, binding, undefined, 'ADMIN')).toThrow(); + expect(() => applySdkAgentBindingWrite(patch, binding, endpoint, 'USER')).toThrow(); + expect(patch).toEqual({}); + applySdkAgentBindingWrite(patch, binding, endpoint, 'ADMIN'); + expect(patch.sdk_runtime).toEqual(binding); + applySdkAgentBindingWrite(patch, undefined, undefined, undefined); + expect(patch.sdk_runtime).toEqual(binding); + applySdkAgentBindingWrite(patch, null, undefined, undefined); + expect(patch.sdk_runtime).toBeNull(); + }); + it('round-trips the binding through management without executable fields', () => { + const data = agentManagementCreateSchema.parse({ + name: 'Advisor', + provider: 'openAI', + model: 'gpt-4.1', + sdk_runtime: binding, + }); + expect( + projectAgentManagementResponse({ + ...data, + id: identity.agentId, + version: 1, + createdAt: '2026-11-13T00:00:00Z', + updatedAt: '2026-11-13T00:00:00Z', + }).sdk_runtime, + ).toEqual(binding); + expect( + agentManagementCreateSchema.safeParse({ + provider: 'openAI', + model: 'gpt-4.1', + sdk_runtime: { ...binding, module: './untrusted.cjs' }, + }).success, + ).toBe(false); + }); + it('leaves native agents on the existing path', () => { + expect(resolveSdkAgentBinding([{ id: 'native' }], undefined, 'USER')).toBeUndefined(); + }); + it('requires configured runtime and role', () => { + const agents = [{ id: identity.agentId, sdk_runtime: binding }]; + expect(resolveSdkAgentBinding(agents, endpoint, 'ADMIN')).toEqual({ + binding, + module: './approved.cjs', + }); + expect(() => resolveSdkAgentBinding(agents, endpoint, 'USER')).toThrow( + expect.objectContaining({ code: 'sdk_runtime_forbidden' }), + ); + expect(() => resolveSdkAgentBinding(agents, undefined, 'ADMIN')).toThrow( + expect.objectContaining({ code: 'sdk_runtime_unavailable' }), + ); + expect(() => + resolveSdkAgentBinding( + [{ id: 'saved', sdk_runtime: { ...binding, id: 'constructor' } }], + endpoint, + 'ADMIN', + ), + ).toThrow(expect.objectContaining({ code: 'sdk_runtime_unavailable' })); + }); + it('does not silently drop native chain members', () => { + expect(() => + resolveSdkAgentBinding( + [{ id: 'native' }, { id: 'sdk', sdk_runtime: binding }], + endpoint, + 'ADMIN', + ), + ).toThrow(expect.objectContaining({ code: 'sdk_runtime_composition_unsupported' })); + }); + it('runs a real SDK graph through native event handlers with immutable host identity', async () => { + const events: string[] = []; + const cfg = config(); + cfg.customHandlers = { + [GraphEvents.ON_MESSAGE_DELTA]: { + handle: async () => { + events.push('delta'); + }, + }, + }; + const factory = jest.fn(async (input: { config: RunConfig; identity: typeof identity }) => { + expect(Object.isFrozen(input.identity)).toBe(true); + const run = await Run.create(input.config); + if (!run.Graph) throw new Error('Missing graph'); + run.Graph.overrideModel = new FakeChatModel({ responses: ['Shared native events'] }); + return run; + }); + const run = await createSdkAgentRun({ + ...args(), + config: cfg, + loadModule: () => ({ protocolVersion: 1, createRun: factory }), + }); + expect(factory.mock.calls[0][0]).toEqual({ + config: cfg, + identity: { ...identity, runtimeId: binding.id, runId: cfg.runId }, + }); + await run.processStream( + { messages: [new HumanMessage('hello')] }, + { configurable: { thread_id: identity.conversationId }, version: 'v2' }, + ); + expect(events).toContain('delta'); + expect(run.getInterrupt()).toBeUndefined(); + }); + it('sanitizes module errors and rejects unsupported versions', async () => { + await expect( + createSdkAgentRun({ + ...args(), + loadModule: () => { + throw new Error('secret'); + }, + }), + ).rejects.toMatchObject({ + code: 'sdk_runtime_invalid', + message: 'The SDK agent runtime is unavailable for this request.', + }); + await expect( + createSdkAgentRun({ ...args(), loadModule: () => ({ protocolVersion: 2 }) }), + ).rejects.toMatchObject({ code: 'sdk_runtime_invalid' }); + }); + it('rejects replacement run identities', async () => { + await expect( + createSdkAgentRun({ + ...args(), + loadModule: () => ({ + protocolVersion: 1, + createRun: () => Run.create({ ...config(), runId: 'other' }), + }), + }), + ).rejects.toMatchObject({ code: 'sdk_runtime_identity_mismatch' }); + }); + it('does not load modules for aborted requests or missing principals', async () => { + const controller = new AbortController(); + controller.abort(); + const loadModule = jest.fn(); + await expect( + createSdkAgentRun({ ...args(), loadModule, signal: controller.signal }), + ).rejects.toThrow(); + await expect( + createSdkAgentRun({ ...args(), loadModule, identity: { ...identity, userId: '' } }), + ).rejects.toMatchObject({ code: 'sdk_runtime_identity_mismatch' }); + expect(loadModule).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/api/src/agents/sdk.ts b/packages/api/src/agents/sdk.ts new file mode 100644 index 0000000000..211c6f93dd --- /dev/null +++ b/packages/api/src/agents/sdk.ts @@ -0,0 +1,139 @@ +import { z } from 'zod'; +import { resolve } from 'node:path'; +import { Run } from '@librechat/agents'; +import { createRequire } from 'node:module'; +import type { Agent, SdkRuntimeBinding, TAgentsEndpoint } from 'librechat-data-provider'; +import type { RunConfig } from '@librechat/agents'; + +export interface SdkAgentIdentity { + readonly agentId: string; + readonly runtimeId: string; + readonly runId: string; + readonly conversationId?: string; + readonly userId: string; + readonly tenantId?: string; +} + +export interface SdkAgentRuntime { + protocolVersion: 1; + /** Retain the host config's handlers, hooks, signal, and run identity. */ + createRun(input: { + config: RunConfig; + identity: SdkAgentIdentity; + }): ReturnType; +} + +export type SdkAgentRuntimeLoader = (module: string) => unknown; + +type AgentBinding = Pick; +type RuntimeConfig = Pick, 'sdkRuntimes'>; + +export class SdkAgentRuntimeError extends Error { + constructor( + public readonly code: + | 'sdk_runtime_unavailable' + | 'sdk_runtime_forbidden' + | 'sdk_runtime_composition_unsupported' + | 'sdk_runtime_invalid' + | 'sdk_runtime_identity_mismatch', + ) { + super('The SDK agent runtime is unavailable for this request.'); + this.name = 'SdkAgentRuntimeError'; + } +} + +const runtimeModuleSchema = z.object({ + protocolVersion: z.literal(1), + createRun: z.custom((value) => typeof value === 'function'), +}); + +// Only operator configuration chooses modules. Node caches modules; no per-turn filesystem scan. +const requireRuntime = (module: string): unknown => + createRequire(resolve(process.cwd(), 'package.json'))(module); + +/** Classifies binding rejection at the legacy duplicate/restore error boundary. */ +export function getSdkAgentWriteErrorStatus(error: unknown): number { + return error instanceof z.ZodError && + error.issues.some((issue) => issue.path[0] === 'sdk_runtime') + ? 400 + : 500; +} + +/** Applies an explicit write only after the operator has enabled its execution binding. */ +export function applySdkAgentBindingWrite( + patch: { sdk_runtime?: SdkRuntimeBinding | null }, + binding: SdkRuntimeBinding | null | undefined, + endpoint: RuntimeConfig | undefined, + role: string | undefined, +): void { + if (binding === undefined) return; + if (binding != null) { + try { + resolveSdkAgentBinding([{ id: '', sdk_runtime: binding }], endpoint, role); + } catch (error) { + if (!(error instanceof SdkAgentRuntimeError)) throw error; + throw new z.ZodError([{ code: 'custom', path: ['sdk_runtime'], message: error.message }]); + } + } + patch.sdk_runtime = binding; +} + +export function resolveSdkAgentBinding( + agents: readonly AgentBinding[], + endpoint: RuntimeConfig | undefined, + role: string | undefined, +): { binding: SdkRuntimeBinding; module: string } | undefined { + if (!agents.some((agent) => agent.sdk_runtime != null)) return undefined; + const binding = agents[0]?.sdk_runtime; + if (agents.length !== 1 || binding == null || agents[0]?.subagents?.enabled === true) { + throw new SdkAgentRuntimeError('sdk_runtime_composition_unsupported'); + } + const configured = Object.prototype.hasOwnProperty.call(endpoint?.sdkRuntimes ?? {}, binding.id) + ? endpoint?.sdkRuntimes?.[binding.id] + : undefined; + if (binding.protocolVersion !== 1 || configured == null) { + throw new SdkAgentRuntimeError('sdk_runtime_unavailable'); + } + if (role == null || !configured.roles.includes(role)) { + throw new SdkAgentRuntimeError('sdk_runtime_forbidden'); + } + return { binding, module: configured.module }; +} + +/** Dispatch an already-authorized agent through its operator-installed SDK factory. */ +export async function createSdkAgentRun({ + registration, + config, + identity, + signal, + loadModule = requireRuntime, +}: { + registration: { binding: SdkRuntimeBinding; module: string }; + config: RunConfig; + identity: Omit; + signal?: AbortSignal; + loadModule?: SdkAgentRuntimeLoader; +}): ReturnType { + signal?.throwIfAborted(); + if (!identity.agentId || !identity.userId) { + throw new SdkAgentRuntimeError('sdk_runtime_identity_mismatch'); + } + let runtime: SdkAgentRuntime; + try { + runtime = runtimeModuleSchema.parse(loadModule(registration.module)); + } catch { + throw new SdkAgentRuntimeError('sdk_runtime_invalid'); + } + const run = await runtime.createRun({ + config, + identity: Object.freeze({ + ...identity, + runId: config.runId, + runtimeId: registration.binding.id, + }), + }); + if (!(run instanceof Run) || run.id !== config.runId) { + throw new SdkAgentRuntimeError('sdk_runtime_identity_mismatch'); + } + return run; +} diff --git a/packages/api/src/agents/validation.ts b/packages/api/src/agents/validation.ts index 35c2e58876..922b22072e 100644 --- a/packages/api/src/agents/validation.ts +++ b/packages/api/src/agents/validation.ts @@ -12,6 +12,7 @@ import { ErrorTypes, MAX_SUBAGENT_GRAPH_NODES, MAX_GRAPH_SUBAGENT_MEMBERS, + sdkRuntimeBindingSchema, } from 'librechat-data-provider'; import type { Agent, @@ -458,6 +459,7 @@ type AgentBaseShape = { code_workspace_id: z.ZodOptional; repositoryInstructions: z.ZodOptional>; git_identity: typeof agentGitIdentitySchema; + sdk_runtime: z.ZodOptional>; artifacts: z.ZodOptional; recursion_limit: z.ZodOptional; conversation_starters: z.ZodOptional>; @@ -469,6 +471,7 @@ type AgentBaseShape = { }; export const agentBaseSchema: z.ZodObject = z.object({ + sdk_runtime: sdkRuntimeBindingSchema.nullable().optional(), name: z.string().nullable().optional(), description: z.string().nullable().optional(), instructions: z.string().nullable().optional(), diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts index 2c7d2fe3c6..ffadbee007 100644 --- a/packages/data-provider/src/config.ts +++ b/packages/data-provider/src/config.ts @@ -1883,6 +1883,18 @@ export const agentsEndpointSchema = baseEndpointSchema .merge( z.object({ /* agents specific */ + /** Trusted server-side SDK modules. Unconfigured runtimes cannot execute. */ + sdkRuntimes: z + .record( + z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/), + z + .object({ + module: z.string().min(1), + roles: z.array(z.string().min(1)).min(1).default(['ADMIN']), + }) + .strict(), + ) + .optional(), hostFileEdits: hostFileEditLimitsSchema.optional(), /** Maximum provider error characters retained in unprotected terminal failures. */ maxProviderErrorChars: z diff --git a/packages/data-provider/src/types/agents.ts b/packages/data-provider/src/types/agents.ts index 5e5155f193..2127186af8 100644 --- a/packages/data-provider/src/types/agents.ts +++ b/packages/data-provider/src/types/agents.ts @@ -1109,6 +1109,15 @@ export const InstructionsPromptErrorCode = { export type InstructionsPromptErrorCode = (typeof InstructionsPromptErrorCode)[keyof typeof InstructionsPromptErrorCode]; +export const sdkRuntimeBindingSchema = z + .object({ + id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/), + protocolVersion: z.literal(1), + }) + .strict(); + +export type SdkRuntimeBinding = z.infer; + export type Agent = { _id?: string; id: string; @@ -1128,6 +1137,8 @@ export type Agent = { tool_kwargs?: Record; metadata?: Record; provider: AgentProvider; + /** Selects an operator-installed SDK runtime; never contains executable code or credentials. */ + sdk_runtime?: SdkRuntimeBinding | null; model: string | null; model_parameters: AgentModelParameters; conversation_starters?: string[]; @@ -1193,6 +1204,7 @@ export type Agent = { export type TAgentsMap = Record; export type AgentCreateParams = { + sdk_runtime?: SdkRuntimeBinding | null; git_identity?: AgentGitIdentity; name?: string | null; description?: string | null; @@ -1232,6 +1244,7 @@ export type AgentCreateParams = { >; export type AgentUpdateParams = { + sdk_runtime?: SdkRuntimeBinding | null; name?: string | null; description?: string | null; avatar?: AgentAvatar | null; diff --git a/packages/data-schemas/src/methods/agent.spec.ts b/packages/data-schemas/src/methods/agent.spec.ts index 855f3126b4..8456b903c7 100644 --- a/packages/data-schemas/src/methods/agent.spec.ts +++ b/packages/data-schemas/src/methods/agent.spec.ts @@ -3327,6 +3327,24 @@ describe('Agent Methods', () => { expect((await getAgent({ id: agentId }))?.name).toBe('Concurrent'); }); + test('restores SDK bindings and removes them when reverting to a native version', async () => { + const id = `agent_${uuidv4()}`; + await createAgent({ + id, + name: 'Native', + provider: 'test', + model: 'test-model', + author: new mongoose.Types.ObjectId(), + }); + const binding = { id: 'advisor', protocolVersion: 1 }; + await updateAgent({ id }, { sdk_runtime: binding }); + expect((await getAgent({ id }))?.sdk_runtime).toEqual(binding); + await revertAgentVersion({ id }, 0); + expect((await getAgent({ id }))?.sdk_runtime).toBeUndefined(); + await revertAgentVersion({ id }, 1); + expect((await getAgent({ id }))?.sdk_runtime).toEqual(binding); + }); + test('should unset a linked prompt-group instructions selection absent from the restored version', async () => { const agentId = `agent_${uuidv4()}`; const authorId = new mongoose.Types.ObjectId(); diff --git a/packages/data-schemas/src/methods/agent.ts b/packages/data-schemas/src/methods/agent.ts index 673bd13baa..17e0c21598 100644 --- a/packages/data-schemas/src/methods/agent.ts +++ b/packages/data-schemas/src/methods/agent.ts @@ -2778,6 +2778,7 @@ export function createAgentMethods( const unsetOnRestore: Record = {}; for (const field of [ + 'sdk_runtime', 'code_environment_id', 'code_workspace_id', 'code_environment_ids', diff --git a/packages/data-schemas/src/schema/agent.sdk.spec.ts b/packages/data-schemas/src/schema/agent.sdk.spec.ts new file mode 100644 index 0000000000..a5f80783c1 --- /dev/null +++ b/packages/data-schemas/src/schema/agent.sdk.spec.ts @@ -0,0 +1,28 @@ +import mongoose from 'mongoose'; +import agentSchema from './agent'; + +const Agent = mongoose.models.SdkBindingAgent ?? mongoose.model('SdkBindingAgent', agentSchema); +const base = { + id: 'agent_saved', + provider: 'openAI', + model: 'fixture', + author: new mongoose.Types.ObjectId(), +}; + +describe('SDK runtime binding storage', () => { + it('retains the binding without adding a nested identity', () => { + const binding = { id: 'advisor', protocolVersion: 1 }; + const doc = new Agent({ ...base, sdk_runtime: binding }); + expect(doc.validateSync()).toBeUndefined(); + expect(doc.toObject().sdk_runtime).toEqual(binding); + }); + it('rejects incomplete and incompatible bindings', () => { + for (const binding of [{ id: 'advisor' }, { id: 'advisor', protocolVersion: 2 }]) { + expect(new Agent({ ...base, sdk_runtime: binding }).validateSync()).toBeDefined(); + } + }); + it('preserves the native default and explicit removal', () => { + expect(new Agent(base).toObject().sdk_runtime).toBeUndefined(); + expect(new Agent({ ...base, sdk_runtime: null }).toObject().sdk_runtime).toBeNull(); + }); +}); diff --git a/packages/data-schemas/src/schema/agent.ts b/packages/data-schemas/src/schema/agent.ts index be6e471585..f947fd6712 100644 --- a/packages/data-schemas/src/schema/agent.ts +++ b/packages/data-schemas/src/schema/agent.ts @@ -25,6 +25,16 @@ const agentSchema: Schema = new Schema( type: String, required: true, }, + sdk_runtime: { + type: new Schema( + { + id: { type: String, required: true }, + protocolVersion: { type: Number, enum: [1], required: true }, + }, + { _id: false }, + ), + default: undefined, + }, model: { type: String, required: true, diff --git a/packages/data-schemas/src/types/agent.ts b/packages/data-schemas/src/types/agent.ts index 9fe0945970..97c600468a 100644 --- a/packages/data-schemas/src/types/agent.ts +++ b/packages/data-schemas/src/types/agent.ts @@ -8,6 +8,7 @@ import type { AgentSubagentsConfig, AgentGitIdentity, AgentInstructionsPrompt, + SdkRuntimeBinding, } from 'librechat-data-provider'; export interface ISupportContact { @@ -25,6 +26,7 @@ export interface IAgent extends Omit { source: string; }; provider: string; + sdk_runtime?: SdkRuntimeBinding | null; model: string; model_parameters?: Record; artifacts?: string;