🎮 feat: Use Saved-Agent Host Models in Remote SDK Runtimes (#18261)

This commit is contained in:
Danny Avila 2026-11-18 06:16:00 -05:00 • committed by GitHub
parent 85d0b310a9
commit dc07a93343
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
21 changed files with 706 additions and 52 deletions

View file

@ -5055,6 +5055,7 @@ class AgentClient extends BaseClient {
activityPhase?.handlers(offsetHandlers) ??
(activityLabel ? createAssistantPhaseStampingHandlers(offsetHandlers) : offsetHandlers);
const createRunPromise = createRun({
sdkModelHost: this.options.req?.app?.locals?.sdkModelHost,
scheduledMCPExecution: getScheduleMCPExecution(getMCPRequestContext(this.options.req)),
recordScheduledMCPDenial: createScheduledMCPPolicyRecorder(
getScheduleMCPExecution(getMCPRequestContext(this.options.req)),
@ -5872,6 +5873,7 @@ class AgentClient extends BaseClient {
activityPhase?.handlers(offsetHandlers) ??
(activityLabel ? createAssistantPhaseStampingHandlers(offsetHandlers) : offsetHandlers);
run = await createRun({
sdkModelHost: this.options.req?.app?.locals?.sdkModelHost,
sdkResumeState: { content: seedContent, steps: runSteps },
scheduledMCPExecution: getScheduleMCPExecution(getMCPRequestContext(this.options.req)),
recordScheduledMCPDenial: createScheduledMCPPolicyRecorder(

View file

@ -1120,6 +1120,7 @@ const executeOpenAIChatCompletion = async (envelope, { req, res }) => {
const initialSessions = buildInitialToolSessions({ agents: runAgents });
const run = await createRun({
sdkModelHost: req?.app?.locals?.sdkModelHost,
agents: runAgents,
messages: formattedMessages,
indexTokenCountMap,

View file

@ -1189,6 +1189,7 @@ const executeResponse = async (envelope, { req, res }) => {
const userMCPAuthMap = mergedMCPAuthMap;
const run = await createRun({
sdkModelHost: req?.app?.locals?.sdkModelHost,
...(await responseRuntime.graphOptions(runAgents)),
agents: runAgents,
messages: responseRuntime.graphMessages(formattedMessages),
@ -1418,6 +1419,7 @@ const executeResponse = async (envelope, { req, res }) => {
const userMCPAuthMap = mergedMCPAuthMap;
const run = await createRun({
sdkModelHost: req?.app?.locals?.sdkModelHost,
...(await responseRuntime.graphOptions(runAgents)),
agents: runAgents,
messages: responseRuntime.graphMessages(formattedMessages),

View file

@ -69,6 +69,7 @@ const {
waitForKeyvRedisClient,
warnOnUnreachableDeliveryPaths,
createCodeApiUploadRegistry,
createSdkModelHost,
createRequestSanitizer,
reportEndpointOverrides,
} = require('@librechat/api');
@ -262,6 +263,7 @@ const startServer = async () => {
await initializeFavorites(await loadCustomConfig(false, { storageSelection: true }));
registerShutdownTask('favorites persistence', closeFavorites, { priority: -100 });
const appConfig = await getAppConfig({ baseOnly: true });
app.locals.sdkModelHost = createSdkModelHost(appConfig?.endpoints?.agents?.sdkHostModels);
await configureSubagentTaskRouting(appConfig?.endpoints?.agents?.subagentActivity);
registerBackgroundTaskShutdown({
interruptGraceMs: appConfig?.endpoints?.agents?.backgroundTasks?.shutdownInterruptGraceMs,

View file

@ -107,7 +107,7 @@ credentials. Keep secrets separate per trusted runtime deployment and restrict n
The `@librechat/api/sdk` entry exports `createRemoteSdkServer` and `createRemoteSdkRun`. The server
factory must return an actual `@librechat/agents` Run with the supplied run and saved-agent IDs,
and preserve supplied handlers, hooks, checkpointer, and cancellation signal. Workers own their
installed tools and custom graph. Model configuration and credentials remain worker-owned unless the caller supplies the explicit host model binding below. Host model callbacks,
installed tools and custom graph. Model configuration and credentials remain worker-owned unless the operator enables saved-agent host models or the caller supplies the explicit host model binding below. Host model callbacks,
provider clients, native tool registries, and arbitrary RunConfig closures do not cross the wire.
Remote execution therefore fails closed on deployments with active model-bound content/PII
protection until its saved-agent adapter is wired. Explicit programmatic provider-text and model bindings are described below.
@ -165,7 +165,7 @@ adapters and unverified behaviors remain release gates for products that depend
| Host-worker connection recovery | Opt-in same-worker live reattachment; durable terminal replay after restart | No host-process adoption, live cross-worker migration, or arbitrary in-flight graph restart. Started executions never automatically rerun. |
| Model/PII/provider-text protection | Explicit SDK host-service adapter supports protected provider text; saved-agent model/PII guard remains | Builder models, input/model callbacks and product policy wiring remain required before protected product rollout. |
| Stream circuit breakers and tool-policy hooks | Forwarded to the worker; hook failure stops execution | Domain tools must also authorize signed caller identity; trusted factories must retain the supplied adapters. |
| Agent-builder model, parameters, tools, capabilities | Name/instructions/identity are passed; explicit host model binding and host schema tools are available | Native model transport is implemented; saved-agent builder wiring is still required to make settings authoritative. |
| Agent-builder model, parameters, tools, capabilities | Opt-in saved-agent primary model settings execute on the host; host schema tools are available | Worker must retain the host model/profile. Fallbacks, local graph tools, and context/summary policy still require adapters. |
| Host MCP, web/code/browser tools, user tool credentials | Authorized root-agent schema tools execute through host RPC | Host credentials remain local; child-agent authorization and broader host-service parity remain separate integrations. |
| Uploaded files, generated artifacts, download authorization | Message data can cross the wire | Host file services, sandbox storage, and artifact authorization do not have remote adapters; attachment/file parity is not established. |
| Live steering and mid-stream preemption | Not integrated | A remote execution-control adapter and acceptance tests are required. |
@ -355,6 +355,48 @@ duplicate trace spans; transport tests do not establish production accounting or
This transport binds one host model per execution. Multi-model routing and per-child model
ownership are not implemented by this binding.
Saved-agent builder/model/PII wiring is still gated. This programmatic transport does not select
builder models, instantiate provider credentials from a browser, or remove the existing protected
saved-agent guard. Those require authenticated product wiring and end-to-end policy acceptance.
### Saved-agent builder models
Operators can opt individual remote registrations into the authenticated saved-agent model path:
```yaml
endpoints:
agents:
sdkHostModels:
maxConcurrentCalls: 32
maxBufferedRequestBytes: 67108864
timeoutMs: 60000
maxRequestBytes: 4194304
maxResponseBytes: 4194304
sdkRuntimes:
schema-advisor:
roles: [ADMIN]
remote:
url: wss://runtime.example/sdk
secret: ${SDK_RUNTIME_SECRET}
hostModel: true
```
Both switches are explicit; existing registrations retain their worker model behavior. The host
uses the saved agent's already-resolved provider, model parameters, credentials, and intrinsic
callbacks. Only the public provider/model/streaming profile and authorized tool schemas reach the
worker. The worker factory must use `input.agent.model` when constructing its primary agent and
retain `input.hostModel` as `run.Graph.overrideModel`; the minimal and custom-graph examples show
both. A mismatched profile or missing `builderModel: 1` capability fails before graph execution.
Upgrade workers before enabling this option. Trusted custom graph code must use the supplied
facade for every applicable model call; this is not isolation from arbitrary operator code.
One admission owner is created at server startup and shared across chat, resume, Responses and
OpenAI-compatible routes. Cancellation does not free capacity until retained provider work settles.
These budgets are per server process, not a cluster quota or per-tenant fairness mechanism. Restart
is required to change the process-wide budgets. Existing transport frame and buffer limits also
apply; the model byte budgets do not enlarge them. Embedders using `createRun` or
`createAgentChatCompletion` inject the same long-lived `sdkModelHost` dependency into every caller.
This selects the primary model; it does not establish full main-chat parity. Active model/PII
protection still fails closed because root admission callbacks and deferred persistence need an
explicit remote lifecycle adapter. Local executable/graph tools and configured provider fallbacks
also fail closed in this mode rather than being silently discarded. Context pruning, summary and
compaction policy, child/multi-model routing, files, accounting and tracing remain separate parity
work. Intrinsic callback execution is covered; production billing and trace ownership are not yet
accepted end to end.

View file

@ -162,3 +162,13 @@ when supplied; neither needs a provider credential for a host-owned model.
See [host model transport](../../docs/sdk/agents.md#host-model-transport) for streaming credit,
encryption, cancellation, callback ownership, and the remaining builder/policy rollout gates.
### Use the saved agent's host model
Enable `endpoints.agents.sdkHostModels: {}` and `remote.hostModel: true` on the operator's
runtime registration to select the saved agent's primary model and parameters. Both examples
consume `input.agent.model` and retain `input.hostModel`; model credentials stay in LibreChat.
The custom graph keeps its plan/review/refine nodes and uses the host-authorized tool schemas.
This mode requires updated workers with `builderModel: 1`. It currently rejects active model/PII
protection, local graph tools and provider fallbacks; see [the parity matrix](../../docs/sdk/agents.md#main-chat-parity-and-rollout-gates)
and [configuration](../../docs/sdk/agents.md#saved-agent-builder-models) before enabling it.

View file

@ -22,7 +22,7 @@ async function createExampleRun(input, { complex = true, stepDelayMs = 0 } = {})
const run = await Run.create({
...input.config,
returnContent: true,
tokenCounter: live ? undefined : () => 1,
tokenCounter: live || input.agent.model ? undefined : () => 1,
graphConfig: {
type: 'standard',
signal: input.signal,
@ -30,19 +30,21 @@ async function createExampleRun(input, { complex = true, stepDelayMs = 0 } = {})
agents: [
{
agentId: input.identity.agentId,
provider: Providers.OPENAI,
provider: input.agent.model?.provider ?? Providers.OPENAI,
...(input.hostTools
? {
tools: [],
graphTools: [inspect],
graphTools: input.agent.model ? [] : [inspect],
toolDefinitions: input.hostTools.toolDefinitions,
}
: { tools: [inspect] }),
instructions: `${input.agent.instructions ?? ''}\nInspect the request using inspect_example, then explain the findings.`,
: { tools: input.agent.model ? [] : [inspect] }),
instructions: input.agent.model
? input.agent.instructions
: `${input.agent.instructions ?? ''}\nInspect the request using inspect_example, then explain the findings.`,
clientOptions: {
model: process.env.SDK_EXAMPLE_MODEL || 'gpt-4.1-mini',
model: input.agent.model?.name ?? (process.env.SDK_EXAMPLE_MODEL || 'gpt-4.1-mini'),
apiKey: process.env.OPENAI_API_KEY,
streaming: live,
streaming: input.agent.model?.streaming ?? live,
},
},
],
@ -104,37 +106,33 @@ function createExampleModel(complex = true) {
throw new Error('Host model did not receive the example tool schema');
return model;
};
model._generate = async (messages) => ({
generations: [
{
text: '',
message: new AIMessageChunk(
!complex
? { content: 'Hello from the separate SDK runtime.' }
: messages.some((message) => message.getType() === 'tool')
? {
content: messages.some(
(message) =>
message.getType() === 'human' &&
message.content === 'Summarize the reviewed findings concisely.',
)
? 'Custom graph complete: inspected the fixture, reviewed the findings, and prepared the result.'
: 'Inspection complete; reviewing the findings.',
}
: {
content: 'I will inspect the fixture.',
tool_calls: [
{
id: 'example-inspection',
name: 'inspect_example',
args: { topic: 'runtime bridge' },
},
],
},
),
},
],
});
model._generate = async (messages) => {
let response = { content: 'Hello from the separate SDK runtime.' };
if (complex && messages.some((message) => message.getType() === 'tool')) {
const reviewed = messages.some(
(message) =>
message.getType() === 'human' &&
message.content === 'Summarize the reviewed findings concisely.',
);
response = {
content: reviewed
? 'Custom graph complete: inspected the fixture, reviewed the findings, and prepared the result.'
: 'Inspection complete; reviewing the findings.',
};
} else if (complex) {
response = {
content: 'I will inspect the fixture.',
tool_calls: [
{
id: 'example-inspection',
name: 'inspect_example',
args: { topic: 'runtime bridge' },
},
],
};
}
return { generations: [{ text: '', message: new AIMessageChunk(response) }] };
};
model._streamResponseChunks = async function* (messages) {
const { generations } = await this._generate(messages);
for (const generation of generations) {

View file

@ -13,7 +13,7 @@ async function createMinimalRun({
const run = await Run.create({
...config,
returnContent: true,
tokenCounter: () => 1,
tokenCounter: agent.model ? undefined : () => 1,
graphConfig: {
type: 'standard',
signal,
@ -21,11 +21,14 @@ async function createMinimalRun({
agents: [
{
agentId: identity.agentId,
provider: Providers.OPENAI,
provider: agent.model?.provider ?? Providers.OPENAI,
instructions: agent.instructions,
tools: [],
toolDefinitions: hostTools?.toolDefinitions,
clientOptions: { model: 'gpt-4.1-mini' },
clientOptions: {
model: agent.model?.name ?? 'gpt-4.1-mini',
streaming: agent.model?.streaming ?? true,
},
},
],
},

View file

@ -818,6 +818,22 @@ endpoints:
# # (optional) Assistant Capabilities available to all users. Omit the ones you wish to exclude. Defaults to list below.
# capabilities: ["code_interpreter", "retrieval", "actions", "tools", "image_vision"]
# agents:
# # Optional primary-model execution for remote SDK agents. Budgets are per process.
# # Restart to change budgets; workers must support builderModel: 1.
# # Model/PII protection, local graph tools and provider fallbacks remain gated.
# sdkHostModels:
# maxConcurrentCalls: 32
# maxBufferedRequestBytes: 67108864
# timeoutMs: 60000
# maxRequestBytes: 4194304
# maxResponseBytes: 4194304
# sdkRuntimes:
# schema-advisor:
# roles: [ADMIN]
# remote:
# url: wss://runtime.example/sdk
# secret: ${SDK_RUNTIME_SECRET}
# hostModel: true
# # Maximum provider response-body inactivity for Agent model calls. Defaults to 15 minutes;
# # each received chunk resets the timer. Set to 0 to disable the idle timeout.
# modelResponseBodyTimeoutMs: 900000

View file

@ -104,3 +104,6 @@ export * from './queuedTurns';
export * from './queuedTurnHttp';
export * from './files/index';
export { captureAuthoredSkills, restoreAuthoredSkills } from './authored';
export { createSdkModelHost } from './remoteSdk/builder';
export type { SdkModelHost } from './remoteSdk/builder';

View file

@ -1,4 +1,5 @@
import type { LocatorTraversalReporter } from '../../protection/diagnostics';
import type { SdkModelHost } from '../remoteSdk/builder';
/**
* OpenAI-compatible chat completions service for agents.
*
@ -86,6 +87,7 @@ import { createSafeUser } from '~/utils';
* Dependencies for the chat completion service
*/
export interface ChatCompletionDependencies {
sdkModelHost?: SdkModelHost;
readonly onTraversalFailure?: LocatorTraversalReporter;
/** Get agent by ID */
getAgent: (params: { id: string }) => Promise<Agent | null>;
@ -297,6 +299,7 @@ type CreateRunAppConfig = Pick<
>;
type CreateRunFn = (params: {
sdkModelHost?: SdkModelHost;
agents: unknown[];
messages: unknown[];
runId: string;
@ -898,6 +901,7 @@ export async function createAgentChatCompletion(
*/
const safeUser: Record<string, unknown> = { ...createSafeUser(reqUser), id: userId };
const run = await deps.createRun({
sdkModelHost: deps.sdkModelHost,
agents: [initializedAgent],
messages,
runId: requestId,

View file

@ -4,6 +4,7 @@ import { randomUUID } from 'node:crypto';
import WebSocket, { WebSocketServer } from 'ws';
import { tool } from '@librechat/agents/langchain/tools';
import { ChatGenerationChunk } from '@langchain/core/outputs';
import { agentsEndpointSchema } from 'librechat-data-provider';
import { FakeChatModel as TestModel } from '@langchain/core/utils/testing';
import { HumanMessage, AIMessageChunk } from '@librechat/agents/langchain/messages';
import {
@ -18,11 +19,15 @@ import {
MemorySaver,
HookRegistry,
} from '@librechat/agents';
import type { AppConfig, IUser } from '@librechat/data-schemas';
import type { RunConfig } from '@librechat/agents';
import type { AddressInfo } from 'node:net';
import type { RemoteSdkServerOptions } from './server';
import type { RemoteSdkFactoryInput } from './types';
import { createSdkAgentRun, resolveSdkAgentBinding } from '../sdk';
import { createRun as createHostRun } from '../run';
import { createRemoteSdkServer } from './server';
import { createSdkModelHost } from './builder';
import { createRemoteSdkRun } from './client';
import { createSdkPeer } from './peer';
@ -1200,7 +1205,7 @@ describe('remote host provider-text protection', () => {
});
});
it.each(['providerText', 'model'] as const)(
it.each(['providerText', 'model', 'builderModel'] as const)(
'rejects a worker without %s capability before factory admission',
async (capability) => {
const server = new WebSocketServer({ port: 0, host: '127.0.0.1' });
@ -1215,7 +1220,11 @@ it.each(['providerText', 'model'] as const)(
onFrame: async () => undefined,
onCall: async (method) => {
methods.push(method);
return { transportVersion: 2, hostTools: 2 };
return {
transportVersion: 2,
hostTools: 2,
...(capability === 'builderModel' ? { hostModel: 1 } : {}),
};
},
}),
);
@ -1236,7 +1245,20 @@ it.each(['providerText', 'model'] as const)(
identity,
remote: { url: `ws://127.0.0.1:${(server.address() as AddressInfo).port}`, secret },
hostServices:
capability === 'providerText' ? { providerText } : { model: nativeModelBinding() },
capability === 'providerText'
? { providerText }
: {
model: nativeModelBinding(),
...(capability === 'builderModel'
? {
modelProfile: {
provider: Providers.OPENAI,
name: 'host-native',
streaming: true,
},
}
: {}),
},
});
await expect(run.processStream({ messages: [] }, invocation())).rejects.toThrow(
'SDK runtime execution failed',
@ -1316,3 +1338,175 @@ it('refuses a worker factory that drops the required host model', async () => {
await runtime.close();
}
});
describe('saved-agent builder host model', () => {
it('uses the resolved saved-agent configuration through the production createRun path', async () => {
const runtime = await fixture(async (input) => {
const run = await factory(input);
run.Graph!.overrideModel = input.hostModel;
const context = run.Graph!.agentContexts.get(identity.agentId)!;
context.provider = input.agent.model!.provider;
context.clientOptions = {
model: input.agent.model!.name,
streaming: input.agent.model!.streaming,
};
return run;
});
try {
const endpoint = agentsEndpointSchema.parse({
sdkHostModels: {},
sdkRuntimes: {
custom: { remote: { ...runtime.remote, hostModel: true }, roles: ['ADMIN'] },
},
});
const native = new TestModel({});
native._streamResponseChunks = async function* () {
yield new ChatGenerationChunk({
text: 'builder reply',
message: new AIMessageChunk({ content: 'builder reply' }),
});
};
const initialize = jest.fn(() => native);
const delta = jest.fn();
const run = await createHostRun({
runId: identity.runId,
conversationId: identity.conversationId,
signal: new AbortController().signal,
tokenCounter: () => 1,
user: { id: identity.userId, role: 'ADMIN', tenantId: identity.tenantId } as IUser,
appConfig: { endpoints: { agents: endpoint } } as AppConfig,
sdkModelHost: createSdkModelHost(endpoint.sdkHostModels, initialize),
agents: [
{
id: identity.agentId,
name: 'Builder agent',
description: '',
created_at: 0,
avatar: null,
provider: Providers.OPENAI,
model: 'gpt-4.1',
model_parameters: {
model: 'gpt-4.1',
temperature: 0.25,
maxContextTokens: null,
max_context_tokens: null,
max_output_tokens: null,
top_p: null,
frequency_penalty: null,
presence_penalty: null,
},
sdk_runtime: { id: 'custom', protocolVersion: 1 },
},
],
customHandlers: { [GraphEvents.ON_MESSAGE_DELTA]: { handle: delta } },
});
await run.processStream({ messages: [new HumanMessage('hello')] }, invocation());
expect(initialize).toHaveBeenCalledWith(
expect.objectContaining({
provider: Providers.OPENAI,
clientOptions: expect.objectContaining({ model: 'gpt-4.1', temperature: 0.25 }),
}),
);
expect(delta).toHaveBeenCalled();
} finally {
await runtime.close();
}
});
it.each([false, true])(
'streams the saved model with a matching worker profile (mismatch=%s)',
async (mismatch) => {
let received: RemoteSdkFactoryInput | undefined;
const runtime = await fixture(async (input) => {
received = input;
const run = await factory(input);
run.Graph!.overrideModel = input.hostModel;
const context = run.Graph!.agentContexts.get(identity.agentId)!;
context.provider = input.agent.model!.provider;
context.clientOptions = {
model: mismatch ? 'worker-model' : input.agent.model!.name,
streaming: input.agent.model!.streaming,
};
return run;
});
try {
const endpoint = agentsEndpointSchema.parse({
sdkHostModels: {},
sdkRuntimes: {
custom: { remote: { ...runtime.remote, hostModel: true }, roles: ['ADMIN'] },
},
});
const registration = resolveSdkAgentBinding(
[{ id: identity.agentId, sdk_runtime: { id: 'custom', protocolVersion: 1 } }],
endpoint,
'ADMIN',
)!;
const native = new TestModel({});
native._streamResponseChunks = async function* () {
yield new ChatGenerationChunk({
text: 'host reply',
message: new AIMessageChunk({ content: 'host reply' }),
});
};
const generate = jest.spyOn(native, '_streamResponseChunks');
const modelHost = createSdkModelHost(endpoint.sdkHostModels, () => native);
const cfg = hostConfig();
if (!('agents' in cfg.graphConfig)) throw new Error('Missing agent config');
cfg.graphConfig.agents[0].clientOptions = {
model: 'saved-builder-model',
apiKey: 'secret-never-sent',
temperature: 0.2,
};
const run = await createSdkAgentRun({ config: cfg, identity, registration, modelHost });
const promise = run.processStream({ messages: [new HumanMessage('hello')] }, invocation());
if (mismatch) {
await expect(promise).rejects.toThrow('SDK runtime execution failed');
expect(generate).not.toHaveBeenCalled();
} else {
await expect(promise).resolves.toBeDefined();
expect(generate).toHaveBeenCalled();
expect(run.getRunMessages()?.length).toBeGreaterThan(0);
}
expect(received!.agent.model).toEqual({
provider: Providers.OPENAI,
name: 'saved-builder-model',
streaming: true,
});
expect(JSON.stringify(received!.agent)).not.toContain('secret-never-sent');
} finally {
await runtime.close();
}
},
);
it('keeps protected saved-agent deployments gated even with host execution enabled', () => {
const endpoint = agentsEndpointSchema.parse({
sdkRuntimes: {
custom: {
remote: { url: 'ws://localhost:9999', secret, hostModel: true },
roles: ['ADMIN'],
},
},
});
expect(() =>
resolveSdkAgentBinding(
[{ id: identity.agentId, sdk_runtime: { id: 'custom', protocolVersion: 1 } }],
endpoint,
'ADMIN',
true,
),
).toThrow(expect.objectContaining({ code: 'sdk_runtime_policy_unsupported' }));
});
it('requires the shared host owner instead of falling back to a worker-owned model', async () => {
await expect(
createSdkAgentRun({
config: hostConfig(),
identity,
registration: {
binding: { id: 'custom', protocolVersion: 1 },
remote: { url: 'ws://localhost:9999', secret, hostModel: true },
},
}),
).rejects.toMatchObject({ code: 'sdk_runtime_unavailable' });
});
});

View file

@ -0,0 +1,165 @@
import { z } from 'zod';
import { Providers } from '@librechat/agents';
import { HumanMessage } from '@langchain/core/messages';
import { tool } from '@librechat/agents/langchain/tools';
import { FakeChatModel } from '@langchain/core/utils/testing';
import { agentsEndpointSchema } from 'librechat-data-provider';
import type { RunConfig } from '@librechat/agents';
import { createSdkModelHost } from './builder';
const identity = { runtimeId: 'runtime', runId: 'run', agentId: 'agent', userId: 'user' };
const limits = agentsEndpointSchema.parse({ sdkHostModels: {} }).sdkHostModels!;
const config = (): RunConfig => ({
runId: identity.runId,
graphConfig: {
type: 'standard',
agents: [
{
agentId: identity.agentId,
provider: Providers.OPENAI,
clientOptions: {
model: 'builder-model',
apiKey: 'host-secret',
temperature: 0.25,
streaming: true,
},
tools: [],
toolDefinitions: [
{
name: 'lookup',
description: 'Authorized lookup',
parameters: { type: 'object', properties: {} },
},
],
},
],
},
});
const request = () => ({
version: 1 as const,
identity,
reference: 'primary',
messages: [new HumanMessage('hello')],
toolNames: [],
});
it('is disabled until the host owner is configured', () => {
expect(createSdkModelHost(undefined)).toBeUndefined();
});
it('keeps native builder parameters and callbacks on the host, exposing only the public profile and schemas', async () => {
const callback = { name: 'host-policy', handleChatModelStart: jest.fn() };
const cfg = config();
if (!('agents' in cfg.graphConfig)) throw new Error('Missing agent config');
Object.assign(cfg.graphConfig.agents[0].clientOptions!, { callbacks: [callback] });
const native = new FakeChatModel({ callbacks: [callback] });
native.bindTools = () => native;
const initialize = jest.fn(() => native);
const host = createSdkModelHost(limits, initialize)!;
const binding = host.bind(cfg, identity);
expect(initialize).toHaveBeenCalledWith({
provider: Providers.OPENAI,
clientOptions: cfg.graphConfig.agents[0].clientOptions,
});
expect(binding.modelProfile).toEqual({
provider: Providers.OPENAI,
name: 'builder-model',
streaming: true,
});
expect(JSON.stringify(binding)).not.toContain('host-secret');
expect(binding.model!.descriptor.tools[0].function.name).toBe('lookup');
await binding.model!.service.invoke(request());
expect(callback.handleChatModelStart).toHaveBeenCalledTimes(1);
expect(host.snapshot().calls).toBe(0);
});
it('shares admission across users and rebuilt turns, retaining capacity until abandoned provider work settles', async () => {
let release!: () => void;
let entered!: () => void;
const started = new Promise<void>((resolve) => {
entered = resolve;
});
const pending = new Promise<void>((resolve) => {
release = resolve;
});
const native = new FakeChatModel({});
native.bindTools = () => native;
const generate = native._generate.bind(native);
native._generate = async (...args) => {
entered();
await pending;
return generate(...args);
};
const host = createSdkModelHost({ ...limits, maxConcurrentCalls: 1 }, () => native)!;
const abort = new AbortController();
const first = host.bind(config(), identity, abort.signal).model!;
const call = first.service.invoke(request());
await started;
abort.abort();
await expect(call).rejects.toMatchObject({ code: 'cancelled' });
expect(host.snapshot()).toMatchObject({ calls: 1, retainedCalls: 1 });
const secondIdentity = { ...identity, runId: 'second-run', userId: 'second-user' };
const second = host.bind(config(), secondIdentity).model!;
await expect(
second.service.invoke({ ...request(), identity: secondIdentity }),
).rejects.toMatchObject({ code: 'overflow' });
release();
await new Promise((resolve) => setImmediate(resolve));
expect(host.snapshot().calls).toBe(0);
await expect(
second.service.invoke({ ...request(), identity: secondIdentity }),
).resolves.toBeDefined();
});
it('keeps callback rejection authoritative and sanitizes the provider-facing error', async () => {
const log = jest.spyOn(console, 'error').mockImplementation(() => undefined);
const native = new FakeChatModel({
callbacks: [
{
name: 'host-policy',
raiseError: true,
awaitHandlers: true,
handleChatModelStart: () => {
throw new Error('private rejection details');
},
},
],
});
native.bindTools = () => native;
const host = createSdkModelHost(limits, () => native)!;
const binding = host.bind(config(), identity);
try {
await expect(binding.model!.service.invoke(request())).rejects.not.toThrow(
'private rejection details',
);
expect(host.snapshot().calls).toBe(0);
} finally {
log.mockRestore();
}
});
it.each(['fallback', 'tools', 'graphTools', 'identity', 'missingModel'] as const)(
'rejects unsupported %s before initializing a provider',
(feature) => {
const cfg = config();
if (!('agents' in cfg.graphConfig)) throw new Error('Missing agent config');
const agent = cfg.graphConfig.agents[0];
if (feature === 'fallback')
Object.assign(agent.clientOptions!, {
fallbacks: [{ provider: Providers.OPENAI, clientOptions: { model: 'fallback' } }],
});
if (feature === 'tools')
agent.tools = [
tool(async () => 'ok', { name: 'local', description: 'Local tool', schema: z.object({}) }),
];
if (feature === 'graphTools')
agent.graphTools = [
tool(async () => 'ok', { name: 'local', description: 'Local tool', schema: z.object({}) }),
];
if (feature === 'identity') agent.agentId = 'another-agent';
if (feature === 'missingModel') delete agent.clientOptions!.model;
const initialize = jest.fn(() => new FakeChatModel({}));
expect(() => createSdkModelHost(limits, initialize)!.bind(cfg, identity)).toThrow('cannot use');
expect(initialize).not.toHaveBeenCalled();
},
);

View file

@ -0,0 +1,103 @@
import { BaseChatModel } from '@langchain/core/language_models/chat_models';
import { initializeModel, createHostModelService, HostModelAdmission } from '@librechat/agents';
import type { TAgentsEndpoint } from 'librechat-data-provider';
import type { RunConfig } from '@librechat/agents';
import type { RemoteSdkHostServices } from './types';
import type { SdkAgentIdentity } from './identity';
type Limits = NonNullable<NonNullable<TAgentsEndpoint>['sdkHostModels']>;
export interface SdkModelHost {
snapshot(): ReturnType<HostModelAdmission['snapshot']>;
bind(
config: RunConfig,
identity: Readonly<SdkAgentIdentity>,
signal?: AbortSignal,
): RemoteSdkHostServices;
}
export class SdkHostModelError extends Error {
readonly code = 'sdk_runtime_model_unsupported';
constructor() {
super('This SDK runtime cannot use the configured host model.');
this.name = 'SdkHostModelError';
}
}
/** One owner per server process, injected into every caller. Never recreate admission per turn. */
export function createSdkModelHost(
limits: Limits | undefined,
createModel: typeof initializeModel = initializeModel,
): SdkModelHost | undefined {
if (!limits) return undefined;
const admission = new HostModelAdmission({
maxConcurrentCalls: limits.maxConcurrentCalls,
maxRequestBytes: limits.maxBufferedRequestBytes,
});
return {
snapshot: () => admission.snapshot(),
bind(
config: RunConfig,
identity: Readonly<SdkAgentIdentity>,
signal?: AbortSignal,
): RemoteSdkHostServices {
const agents = 'agents' in config.graphConfig ? config.graphConfig.agents : undefined;
const agent = agents?.[0];
const modelName = agent?.clientOptions?.model;
// Local graph tools and fallback models need explicit host adapters; never silently drop them.
if (
!agent ||
agents?.length !== 1 ||
agent.agentId !== identity.agentId ||
!agent.clientOptions ||
typeof modelName !== 'string' ||
!modelName ||
('fallbacks' in agent.clientOptions &&
Array.isArray(agent.clientOptions.fallbacks) &&
agent.clientOptions.fallbacks.length > 0) ||
agent.tools?.length ||
agent.graphTools?.length
)
throw new SdkHostModelError();
signal?.throwIfAborted();
const model = createModel({ provider: agent.provider, clientOptions: agent.clientOptions });
if (!(model instanceof BaseChatModel)) throw new SdkHostModelError();
const modelProfile = {
provider: agent.provider,
name: modelName,
streaming: agent.clientOptions?.streaming !== false,
};
return {
modelProfile,
model: createHostModelService({
identity,
model,
descriptor: {
version: 1,
reference: 'primary',
provider: modelProfile.provider,
model: modelProfile.name,
streaming: modelProfile.streaming,
tools: (agent.toolDefinitions ?? []).map((definition) => ({
type: 'function' as const,
function: {
...definition,
parameters: definition.parameters ?? { type: 'object', properties: {} },
},
})),
},
admission,
limits: {
timeoutMs: limits.timeoutMs,
maxRequestBytes: limits.maxRequestBytes,
maxResponseBytes: limits.maxResponseBytes,
},
config: {
signal,
metadata: { agentId: identity.agentId, run_id: identity.runId },
},
}),
};
},
};
}

View file

@ -45,6 +45,8 @@ export async function createRemoteSdkRun({
remote: RemoteSdkOptions;
resumeState?: RemoteSdkResumeState;
}): ReturnType<typeof Run.create> {
if (hostServices?.modelProfile && !hostServices.model)
throw new Error('Builder model profile requires a host model');
if (config.clientDelegatedToolNames?.length)
throw new Error('Remote SDK client-owned tools require a supported ownership adapter');
if (config.providerTextProtection && !hostServices?.providerText)
@ -455,7 +457,12 @@ export async function createRemoteSdkRun({
checkpoint: Boolean(saver),
humanInTheLoop: config.humanInTheLoop,
streamLimits: config.streamLimits,
agent: { id: identity.agentId, name: agent?.name, instructions: agent?.instructions },
agent: {
id: identity.agentId,
name: agent?.name,
instructions: agent?.instructions,
model: hostServices?.modelProfile,
},
};
void (async () => {
const capabilities = (await peer.call('capabilities', null)) as {
@ -463,9 +470,12 @@ export async function createRemoteSdkRun({
hostTools?: number;
providerText?: number;
hostModel?: number;
builderModel?: number;
};
if (capabilities?.transportVersion !== 2)
throw new Error('Worker transport capability unavailable');
if (hostServices?.modelProfile && capabilities?.builderModel !== 1)
throw new Error('Worker builder model capability unavailable');
if (hostServices?.model && capabilities?.hostModel !== 1)
throw new Error('Worker host model capability unavailable');
if (providerText && capabilities?.providerText !== 1)

View file

@ -95,6 +95,14 @@ const startSchema = z.object({
id: z.string(),
name: z.string().optional(),
instructions: z.string().optional(),
model: z
.object({
provider: z.string().min(1),
name: z.string().min(1),
streaming: z.boolean(),
})
.strict()
.optional(),
}),
});
@ -278,7 +286,13 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
},
onCall: async (method, data, _timeoutMs, signal) => {
if (method === 'capabilities')
return { transportVersion: 2, hostTools: 2, providerText: 1, hostModel: 1 };
return {
transportVersion: 2,
hostTools: 2,
providerText: 1,
hostModel: 1,
builderModel: 1,
};
if (method === 'model.chunk') return workerModel.accept(data, signal);
if (method === 'tool.result') return workerTools.accept(data);
if (method === 'tool.session') return workerTools.accept(data, 'session');
@ -361,6 +375,16 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
})
: undefined;
const hostModel = request.model ? workerModel.bind(identity, request.model) : undefined;
const profile = request.agent.model;
if (
profile &&
(!hostModel ||
request.model?.descriptor.provider !== profile.provider ||
request.model.descriptor.model !== profile.name ||
request.model.descriptor.streaming !== profile.streaming)
) {
throw new Error('SDK runtime builder model mismatch');
}
const execute = async () => {
await recovered?.begin();
const run = await options.createRun({
@ -394,6 +418,16 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
throw new Error('SDK runtime omitted required provider protection');
if (hostModel && run.Graph.overrideModel !== hostModel)
throw new Error('SDK runtime omitted required host model');
if (profile) {
const context = run.Graph.agentContexts.get(identity.agentId);
if (
context?.provider !== profile.provider ||
context.clientOptions?.model !== profile.name ||
(context.clientOptions?.streaming !== false) !== profile.streaming
) {
throw new Error('SDK runtime omitted required builder model configuration');
}
}
if (hostTools) {
const names = new Set(
run.Graph.agentContexts

View file

@ -1,4 +1,5 @@
import type {
AgentInputs,
createHostProviderTextService,
createHostModelService,
HostModelDescriptor,
@ -22,6 +23,8 @@ export interface RemoteSdkRecoveryOptions {
maxJournalBytes: number;
}
export interface RemoteSdkOptions {
/** Opt in to the saved-agent host model, configured by the operator. */
hostModel?: boolean;
recovery?: RemoteSdkRecoveryOptions;
url: string;
secret: string;
@ -56,8 +59,16 @@ export type SdkRun = Awaited<ReturnType<typeof Run.create>>;
export type SdkRunInput = Parameters<SdkRun['processStream']>[0];
export type SdkRunOptions = Parameters<SdkRun['processStream']>[1];
export type SdkEventData = Parameters<EventHandler['handle']>[1];
/** Public primary-model configuration required by the worker graph. */
export interface RemoteSdkModelProfile {
provider: AgentInputs['provider'];
name: string;
streaming: boolean;
}
/** Explicit host-owned capabilities; never reconstructed from worker claims or YAML. */
export interface RemoteSdkHostServices {
modelProfile?: RemoteSdkModelProfile;
model?: ReturnType<typeof createHostModelService>;
providerText?: ReturnType<typeof createHostProviderTextService>;
}
@ -77,7 +88,7 @@ export interface RemoteSdkStart {
checkpoint: boolean;
humanInTheLoop?: RunConfig['humanInTheLoop'];
streamLimits?: RunConfig['streamLimits'];
agent: { id: string; name?: string; instructions?: string };
agent: { id: string; name?: string; instructions?: string; model?: RemoteSdkModelProfile };
}
export interface RemoteSdkSnapshot {
state?: {

View file

@ -69,6 +69,7 @@ import type { MCPToolAlias } from '~/tools/classification';
import type { ReviewedToolApprovals } from './hitl/modes';
import type { SubagentUsageEvent } from '~/agents/usage';
import type { ProvisionState } from '~/agents/resources';
import type { SdkModelHost } from './remoteSdk/builder';
import type { RunFileSession } from './files/session';
import type { SdkAgentRuntimeLoader } from './sdk';
import type { RunFadingTiers } from './fading';
@ -2324,6 +2325,7 @@ export async function createRun({
toolInputValidationErrors,
sessionStartSource,
loadSdkRuntime,
sdkModelHost,
sdkResumeState,
streaming = true,
streamUsage = true,
@ -2480,6 +2482,7 @@ export async function createRun({
/** Request-scoped tool input failures consumed by the completion handler. */
toolInputValidationErrors?: Map<string, ToolInputValidationError>;
loadSdkRuntime?: SdkAgentRuntimeLoader;
sdkModelHost?: SdkModelHost;
sdkResumeState?: import('./remoteSdk/types').RemoteSdkResumeState;
} & Pick<
RunConfig,
@ -3335,6 +3338,7 @@ export async function createRun({
registration,
config: runConfig,
loadModule: loadSdkRuntime,
modelHost: sdkModelHost,
resumeState: sdkResumeState,
signal,
identity: {

View file

@ -7,6 +7,7 @@ import type { Agent, SdkRuntimeBinding, TAgentsEndpoint } from 'librechat-data-p
import type { RunConfig } from '@librechat/agents';
import type { RemoteSdkOptions, RemoteSdkResumeState } from './remoteSdk/types';
import type { SdkAgentIdentity } from './remoteSdk/identity';
import type { SdkModelHost } from './remoteSdk/builder';
import { createRemoteSdkRun } from './remoteSdk/client';
export type { SdkAgentIdentity } from './remoteSdk/identity';
@ -114,6 +115,7 @@ export async function createSdkAgentRun({
identity,
signal,
resumeState,
modelHost,
loadModule = requireRuntime,
}: {
registration: SdkRegistration;
@ -121,6 +123,7 @@ export async function createSdkAgentRun({
identity: Omit<SdkAgentIdentity, 'runtimeId' | 'runId'>;
signal?: AbortSignal;
resumeState?: RemoteSdkResumeState;
modelHost?: SdkModelHost;
loadModule?: SdkAgentRuntimeLoader;
}): ReturnType<typeof Run.create> {
signal?.throwIfAborted();
@ -133,10 +136,16 @@ export async function createSdkAgentRun({
runtimeId: registration.binding.id,
});
if (registration.remote != null) {
if (registration.remote.hostModel && !modelHost) {
throw new SdkAgentRuntimeError('sdk_runtime_unavailable');
}
return createRemoteSdkRun({
config,
identity: boundIdentity,
resumeState,
hostServices: registration.remote.hostModel
? modelHost?.bind(config, boundIdentity, signal)
: undefined,
remote: { ...registration.remote, secret: extractEnvVariable(registration.remote.secret) },
});
}

View file

@ -3522,6 +3522,35 @@ describe('complete channel operator configuration', () => {
});
describe('remote SDK runtime configuration', () => {
it('opts into builder models with bounded process-wide admission', () => {
expect(agentsEndpointSchema.parse({}).sdkHostModels).toBeUndefined();
const result = agentsEndpointSchema.parse({
sdkHostModels: {},
sdkRuntimes: {
runtime: {
remote: { url: 'wss://runtime.example/sdk', secret: 'secret', hostModel: true },
},
},
});
expect(result.sdkHostModels).toEqual({
maxConcurrentCalls: 32,
maxBufferedRequestBytes: 67108864,
timeoutMs: 60000,
maxRequestBytes: 4194304,
maxResponseBytes: 4194304,
});
expect(result.sdkRuntimes?.runtime).toMatchObject({ remote: { hostModel: true } });
for (const field of Object.keys(result.sdkHostModels!)) {
expect(agentsEndpointSchema.safeParse({ sdkHostModels: { [field]: 0 } }).success).toBe(false);
expect(
agentsEndpointSchema.safeParse({ sdkHostModels: { [field]: Number.MAX_SAFE_INTEGER } })
.success,
).toBe(false);
}
expect(agentsEndpointSchema.safeParse({ sdkHostModels: { unknown: true } }).success).toBe(
false,
);
});
it('keeps module registrations and supplies remote transport defaults', () => {
const result = agentsEndpointSchema.parse({
sdkRuntimes: {

View file

@ -1896,6 +1896,17 @@ export const agentsEndpointSchema = baseEndpointSchema
.merge(
z.object({
/* agents specific */
/** Process-wide admission, shared across users, runtimes and resumed turns. */
sdkHostModels: z
.object({
maxConcurrentCalls: z.number().int().min(1).max(10000).default(32),
maxBufferedRequestBytes: z.number().int().min(1024).max(1073741824).default(67108864),
timeoutMs: z.number().int().min(100).max(86400000).default(60000),
maxRequestBytes: z.number().int().min(1024).max(67108864).default(4194304),
maxResponseBytes: z.number().int().min(1024).max(67108864).default(4194304),
})
.strict()
.optional(),
/** Trusted server-side SDK modules. Unconfigured runtimes cannot execute. */
sdkRuntimes: z
.record(
@ -1916,6 +1927,7 @@ export const agentsEndpointSchema = baseEndpointSchema
.url()
.regex(/^wss?:\/\//),
secret: z.string().min(1),
hostModel: z.boolean().optional(),
recovery: z
.object({
routes: z