🐕‍🦺 feat: Run Authorized Host Tools From Remote SDK Agents (#18189)
Some checks are pending
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Backend Unit Tests / backend (push) Blocked by required conditions
Channel Gateway / gateway (push) Waiting to run
Codegraph E2E Vote Gate / Gate (push) Waiting to run
Codegraph E2E Votes / vote (shard 1/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 10/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 2/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 3/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 4/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 5/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 6/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 7/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 8/10) (push) Waiting to run
Codegraph E2E Votes / vote (shard 9/10) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/chat (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions
Frontend Unit Tests / frontend (push) Blocked by required conditions
Playwright E2E Tests / Codegraph select (push) Waiting to run
Playwright E2E Tests / Shard timings (push) Waiting to run
Playwright E2E Tests / e2e () (push) Blocked by required conditions
Playwright E2E Tests / MCP list_changed (replica count 1) (push) Blocked by required conditions
Playwright E2E Tests / MCP list_changed (replica count 2) (push) Blocked by required conditions
Playwright E2E Tests / MCP Apps (browser and server) (push) Waiting to run
Playwright E2E Tests / e2e (push) Blocked by required conditions
Playwright Shard Timings / Record shard timings (push) Waiting to run
Docker Dev Images Build / publish (push) Waiting to run
Sync Helm Chart Tags / Ignore non-main push (push) Waiting to run
Sync Helm Chart Tags / Sync chart tags (push) Waiting to run

* feat: execute remote SDK host tools through the shared harness

* fix: allow host tool execution within the configured run budget

* fix: reject unsupported client-owned tool dispatch
This commit is contained in:
Danny Avila 2026-11-15 09:42:41 -05:00 • committed by GitHub
parent b4d984a69e
commit 9363db541e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 706 additions and 25 deletions

View file

@ -40,7 +40,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "5.1.6",
"@librechat/agents": "^4.2.3",
"@librechat/agents": "^4.2.4",
"@librechat/api": "*",
"@librechat/data-schemas": "*",
"@microsoft/microsoft-graph-client": "^3.0.7",

View file

@ -162,7 +162,7 @@ adapters and unverified behaviors remain release gates for products that depend
| Model/PII/provider-text protection | Remote execution is blocked when these host policies are active | A supported host policy adapter is required before protected deployments can enable remote execution. |
| 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; worker owns the graph/model/tools | Other builder settings are not automatically applied. A runtime capability/configuration contract is needed to make controls authoritative. |
| Host MCP, web/code/browser tools, user tool credentials | Not automatically available inside the worker | Supply authorized runtime tools today; shared host-tool adapters remain missing. |
| 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. |
| Foreground/nested/detached subagents | Worker may construct its own SDK graph | Native configured compositions are rejected; detached child checkpoint threads/context/usage sinks are not integrated. |
@ -175,3 +175,32 @@ adapters and unverified behaviors remain release gates for products that depend
Do not enable a workflow on the assumption that a native chat control is honored remotely. Its
required rows must be implemented and verified first. Keep this matrix current as adapters land;
transport success alone is insufficient to mark a product migration complete.
### Host tool execution
With SDK 4.2.4+, a host agent's schema tools bind to its existing authenticated tool handler.
The bridge negotiates `hostTools: 1` before starting the worker; an older worker cannot silently
ignore required host tools. Factories install `input.hostTools.toolDefinitions` on the matching
SDK agent; supplied config already contains the execution handler. Missing definitions fail
before graph execution. Worker-owned direct tools may use `graphTools` alongside host schemas.
Tool-policy hooks and approve/edit/reject remain native SDK behavior. Host execution uses the
signed root identity and host invocation configuration; runtime payloads cannot provide host
credentials or choose an unbound tool. Incremental receipts retain the SDK's early-completion
gate. Result and session-refresh callbacks are acknowledged before the final RPC settles, on
success or failure. Recovery replays wire frames without re-invoking the host handler.
Child-agent execution subjects are explicitly rejected until the host can authorize their
registered tool ownership. Uploaded file authorization, model/PII policy, steering, accounting
and tracing adapters retain the limitations in the matrix above. A tool reference does not
itself grant access to domain data; the existing host tool implementation must authorize it.
Host tool execution uses `maxRunMs` for its RPC lifetime. `rpcTimeoutMs` continues to bound
control, checkpoint and notification RPCs; a healthy long-running tool must not fail solely
because it exceeds that shorter control timeout. The run's cancellation/deadline still aborts
both sides cooperatively.
Caller-owned function tools (`clientDelegatedToolNames`) are not host tools. Remote SDK
execution rejects that configuration until an explicit ownership/continuation adapter is
available; their schemas must never be reinterpreted as permission to execute on the host.
Native Responses execution without a remote SDK binding retains its existing behavior.

View file

@ -38,7 +38,13 @@ async function createExampleRun(input, { complex = true, stepDelayMs = 0 } = {})
{
agentId: input.identity.agentId,
provider: Providers.OPENAI,
tools: [inspect],
...(input.hostTools
? {
tools: [],
graphTools: [inspect],
toolDefinitions: input.hostTools.toolDefinitions,
}
: { tools: [inspect] }),
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',

View file

@ -1,7 +1,7 @@
const { Run, Providers, FakeChatModel } = require('@librechat/agents');
/** Smallest key-free example: a real SDK Run, streamed through the native Agents UI. */
async function createMinimalRun({ config, compileOptions, identity, agent, signal }) {
async function createMinimalRun({ config, compileOptions, identity, agent, signal, hostTools }) {
const run = await Run.create({
...config,
returnContent: true,
@ -16,6 +16,7 @@ async function createMinimalRun({ config, compileOptions, identity, agent, signa
provider: Providers.OPENAI,
instructions: agent.instructions,
tools: [],
toolDefinitions: hostTools?.toolDefinitions,
clientOptions: { model: 'gpt-4.1-mini' },
},
],

10
package-lock.json generated
View file

@ -70,7 +70,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "5.1.6",
"@librechat/agents": "^4.2.3",
"@librechat/agents": "^4.2.4",
"@librechat/api": "*",
"@librechat/data-schemas": "*",
"@microsoft/microsoft-graph-client": "^3.0.7",
@ -9479,9 +9479,9 @@
}
},
"node_modules/@librechat/agents": {
"version": "4.2.3",
"resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-4.2.3.tgz",
"integrity": "sha512-nLZlff0YAXi26a1P9V5ydSEEjKsyMZi0WtEW2fo0xBipDvK9n5uvFExU9WK5z6YinLzJD6MY7gcpl2wQYh69Uw==",
"version": "4.2.4",
"resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-4.2.4.tgz",
"integrity": "sha512-ld9vZelnhzOQLxmb1Y8+IgKkWOIWydb1UWPoEZqh+FHdVtiSPywEfrajXjNIZsQiGPccGt6kj0of3M3TBQPPHA==",
"license": "MIT",
"dependencies": {
"@anthropic-ai/sdk": "^0.115.0",
@ -42444,7 +42444,7 @@
"@azure/identity": "^4.14.0",
"@azure/storage-blob": "^12.30.0",
"@keyv/redis": "5.1.6",
"@librechat/agents": "^4.2.3",
"@librechat/agents": "^4.2.4",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.32.1",
"@opentelemetry/api": "^1.9.0",

View file

@ -120,7 +120,7 @@
"@azure/identity": "^4.14.0",
"@azure/storage-blob": "^12.30.0",
"@keyv/redis": "5.1.6",
"@librechat/agents": "^4.2.3",
"@librechat/agents": "^4.2.4",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.32.1",
"@opentelemetry/api": "^1.9.0",

View file

@ -660,4 +660,139 @@ describe('remote SDK runtime bridge', () => {
).rejects.toThrow();
},
);
it('does not reinterpret client-owned functions as host-executable tools', async () => {
const createRun = jest.fn(factory);
const runtime = await fixture(createRun);
try {
await expect(
createRemoteSdkRun({
config: { ...hostConfig(), clientDelegatedToolNames: ['browser_function'] },
identity,
remote: runtime.remote,
}),
).rejects.toThrow('ownership adapter');
expect(createRun).not.toHaveBeenCalled();
} finally {
await runtime.close();
}
});
it('fails before tool execution when a factory omits required host schemas', async () => {
const runtime = await fixture();
const handle = jest.fn();
try {
const config = hostConfig();
config.graphConfig = {
type: 'standard',
llmConfig: { provider: Providers.OPENAI },
toolDefinitions: [{ name: 'inspect', description: 'Inspect' }],
};
config.customHandlers = { [GraphEvents.ON_TOOL_EXECUTE]: { handle } };
const run = await createRemoteSdkRun({ config, identity, remote: runtime.remote });
await expect(
run.processStream({ messages: [new HumanMessage('inspect')] }, invocation()),
).rejects.toThrow('SDK runtime execution failed');
expect(handle).not.toHaveBeenCalled();
} finally {
await runtime.close();
}
});
it('executes authorized host tools and delivers a fast result before the batch settles', async () => {
const definitions = [
{
name: 'echo',
description: 'echo',
parameters: { type: 'object' as const, properties: { text: { type: 'string' as const } } },
},
];
const createRun = async (input: RemoteSdkFactoryInput) => {
const run = await Run.create({
...input.config,
tokenCounter: () => 1,
returnContent: true,
graphConfig: {
type: 'standard',
agents: [
{
agentId: input.identity.agentId,
provider: Providers.OPENAI,
tools: [],
toolDefinitions: input.hostTools?.toolDefinitions,
},
],
},
});
run.Graph!.overrideTestModel(['tools'], 5, [
{ id: 'fast', name: 'echo', args: { text: 'fast' }, type: 'tool_call' },
{ id: 'slow', name: 'echo', args: { text: 'slow' }, type: 'tool_call' },
]);
return run;
};
const runtime = await fixture(createRun, { rpcTimeoutMs: 100, maxRunMs: 5000 });
let release!: () => void;
const held = new Promise<void>((resolve) => {
release = resolve;
});
let first!: () => void;
const ready = new Promise<void>((resolve) => {
first = resolve;
});
let calls = 0;
try {
const config = hostConfig();
config.graphConfig = {
type: 'standard',
llmConfig: { provider: Providers.OPENAI },
toolDefinitions: definitions,
};
config.customHandlers = {
[GraphEvents.ON_TOOL_EXECUTE]: {
handle: async (_event, data) => {
const batch = data as import('@librechat/agents').ToolExecuteBatchRequest;
calls++;
expect(batch.agentId).toBe(identity.agentId);
expect(batch.userId).toBe(identity.userId);
batch.onResult?.({ toolCallId: 'fast', status: 'success', content: 'fast' });
await held;
batch.resolve([
{ toolCallId: 'slow', status: 'success', content: 'slow' },
{ toolCallId: 'fast', status: 'success', content: 'fast' },
]);
},
},
[GraphEvents.ON_RUN_STEP_COMPLETED]: {
handle: async (_event, data) => {
if (JSON.stringify(data).includes('fast')) first();
},
},
};
const run = await createRemoteSdkRun({
config,
identity,
remote: { ...runtime.remote, rpcTimeoutMs: 100, maxRunMs: 5000 },
});
const result = run.processStream({ messages: [new HumanMessage('tools')] }, invocation());
const completed = result.catch((error) => {
first();
return error as Error;
});
let timeout: ReturnType<typeof setTimeout> | undefined;
try {
await Promise.race([
ready,
new Promise((_, reject) => {
timeout = setTimeout(() => reject(new Error('No early tool completion')), 5000);
}),
]);
} finally {
clearTimeout(timeout);
}
await new Promise((resolve) => setTimeout(resolve, 200));
release();
expect(await completed).not.toBeInstanceOf(Error);
expect(calls).toBe(1);
} finally {
release?.();
await runtime.close();
}
});
});

View file

@ -24,6 +24,7 @@ import type { SdkAgentIdentity } from './identity';
import { hydrateResumeRunSteps, createContentIndexOffsetHandlers } from '../hitl/resume';
import { connectRecoveringSdkSocket } from './recovery/client';
import { remoteSdkLimits, isRemoteSdkSecret } from './types';
import { createHostToolService } from './hostTools';
import { createSdkPeer } from './peer';
/** Construct a real local Run whose execution is delegated to one operator-trusted runtime. */
@ -38,6 +39,8 @@ export async function createRemoteSdkRun({
remote: RemoteSdkOptions;
resumeState?: RemoteSdkResumeState;
}): ReturnType<typeof Run.create> {
if (config.clientDelegatedToolNames?.length)
throw new Error('Remote SDK client-owned tools require a supported ownership adapter');
if (config.providerTextProtection)
throw new Error('Remote SDK provider protection requires a supported policy adapter');
identity = Object.freeze({ ...identity });
@ -96,6 +99,14 @@ export async function createRemoteSdkRun({
const saver = candidate instanceof BaseCheckpointSaver ? candidate : undefined;
if (config.humanInTheLoop?.enabled && !saver)
throw new Error('Remote SDK approvals require a host checkpointer');
const agentConfig =
'agents' in config.graphConfig ? config.graphConfig.agents[0] : config.graphConfig;
const descriptors = (agentConfig.toolDefinitions ?? []).map((definition) => ({
definition,
reference: definition.name,
}));
const toolHandler = config.customHandlers?.[GraphEvents.ON_TOOL_EXECUTE];
if (descriptors.length && !toolHandler) throw new Error('Host tool handler is unavailable');
let invoked = false;
const execute = async (
operation: RemoteSdkStart['operation'],
@ -187,6 +198,7 @@ export async function createRemoteSdkRun({
);
else resolve(value);
};
let hostToolInvoke: ReturnType<typeof createHostToolService> | undefined;
const peer = createSdkPeer(socket, {
...limits,
timeoutMs: limits.rpcTimeoutMs,
@ -220,6 +232,25 @@ export async function createRemoteSdkRun({
onCall: async (method, data) => {
if (execution.signal.aborted || options.signal?.aborted)
throw new Error('SDK runtime execution stopped');
if (method === 'tools') {
if (!toolHandler || !descriptors.length) throw new Error('Host tools are unavailable');
hostToolInvoke ??= createHostToolService({
identity,
tools: descriptors,
handler: toolHandler,
graph,
metadata: options.metadata,
configurable: {
...options.configurable,
user_id: identity.userId,
run_id: identity.runId,
thread_id: threadId,
},
peer,
signal: execution.signal,
});
return hostToolInvoke(data);
}
if (method === 'hook') {
if (config.hooks == null) throw new Error('Host hooks are unavailable');
const args = data as {
@ -320,6 +351,7 @@ export async function createRemoteSdkRun({
const agent =
'agents' in config.graphConfig ? config.graphConfig.agents[0] : config.graphConfig;
const start: RemoteSdkStart = {
hostTools: descriptors.length ? descriptors : undefined,
operation,
input,
resume,
@ -353,7 +385,14 @@ export async function createRemoteSdkRun({
streamLimits: config.streamLimits,
agent: { id: identity.agentId, name: agent?.name, instructions: agent?.instructions },
};
void peer.call('run', start).catch(() => finish());
void (async () => {
if (descriptors.length) {
const capabilities = (await peer.call('capabilities', null)) as { hostTools?: number };
if (capabilities?.hostTools !== 1)
throw new Error('Worker host tool capability unavailable');
}
await peer.call('run', start);
})().catch(() => finish());
});
try {
snapshot = await result;

View file

@ -0,0 +1,111 @@
import type { HostToolRequest, HostToolSessionUpdate } from '@librechat/agents';
import { createHostToolService, createWorkerToolService } from './hostTools';
const identity = {
runtimeId: 'runtime',
agentId: 'agent',
runId: 'run',
userId: 'user',
tenantId: 'tenant',
};
const tools = [{ reference: 'bound', definition: { name: 'inspect' } }];
function setup() {
const handle = jest.fn(async (_event, data) => {
data.resolve([{ toolCallId: 'call', status: 'success', content: 'ok' }]);
});
const controller = new AbortController();
const invoke = createHostToolService({
identity,
tools,
handler: { handle },
configurable: { privateCredential: 'host-secret' },
peer: { call: async () => null },
signal: controller.signal,
});
const input = {
id: 'c420977d-63df-4dd8-bb75-344d00334818',
incremental: false,
request: {
version: 1,
identity,
calls: [{ reference: 'bound', call: { id: 'call', name: 'inspect', args: {} } }],
},
};
return { handle, controller, invoke, input };
}
it.each(['userId', 'tenantId', 'runId', 'agentId'] as const)(
'rejects foreign %s before dispatch',
async (key) => {
const { handle, invoke, input } = setup();
await expect(
invoke({
...input,
request: { ...input.request, identity: { ...identity, [key]: 'other' } },
}),
).rejects.toThrow('identity');
expect(handle).not.toHaveBeenCalled();
},
);
it('rejects unbound references and unsupported child attribution', async () => {
const { handle, invoke, input } = setup();
await expect(
invoke({ ...input, request: { ...input.request, executingAgentId: 'child' } }),
).rejects.toThrow('subject');
await expect(
invoke({
...input,
request: {
...input.request,
calls: [{ reference: 'other', call: { id: 'call', name: 'inspect', args: {} } }],
},
}),
).rejects.toThrow('capability');
expect(handle).not.toHaveBeenCalled();
});
it('uses only host-owned invocation configuration and honors cancellation', async () => {
const { handle, controller, invoke, input } = setup();
await invoke({
...input,
request: { ...input.request, configurable: { privateCredential: 'forged' } },
});
expect(handle.mock.calls[0][1].configurable).toEqual({ privateCredential: 'host-secret' });
controller.abort();
await expect(invoke(input)).rejects.toThrow();
expect(handle).toHaveBeenCalledTimes(1);
});
it('delivers refreshed host session state before propagating an execution failure', async () => {
const updates: HostToolSessionUpdate[] = [];
const worker = createWorkerToolService({ call: async (_method, data) => host(data) });
const host = createHostToolService({
identity,
tools,
configurable: {},
signal: new AbortController().signal,
peer: {
call: async (method, data) =>
worker.accept(data, method === 'tool.session' ? 'session' : 'result'),
},
handler: {
handle: async (_event, data) => {
const batch = data as import('@librechat/agents').ToolExecuteBatchRequest;
batch.toolCalls[0].codeSessionContext = { session_id: 'refreshed' };
throw new Error('execution failed after provisioning');
},
},
});
const request: HostToolRequest = {
version: 1,
identity,
executingAgentId: identity.agentId,
calls: [{ reference: 'bound', call: { id: 'call', name: 'inspect', args: {} } }],
};
await expect(
worker.service.invoke(request, undefined, {
onSessionUpdate: (update) => {
updates.push(update);
},
}),
).rejects.toThrow('execution failed');
expect(updates[0].context.codeSessionContext?.session_id).toBe('refreshed');
});

View file

@ -0,0 +1,212 @@
import { z } from 'zod';
import { randomUUID } from 'node:crypto';
import { GraphEvents } from '@librechat/agents';
import type {
EventHandler,
HostToolDescriptor,
HostToolRequest,
HostToolService,
HostToolEvents,
HostToolSessionUpdate,
ToolExecuteResult,
} from '@librechat/agents';
import type { SdkAgentIdentity } from './identity';
import type { SdkRpc } from './peer';
const toolResultSchema = z.object({
id: z.string().uuid(),
result: z
.object({ toolCallId: z.string().min(1), status: z.enum(['success', 'error']) })
.passthrough(),
});
/** Local credentials/configuration are supplied by the authenticated host, never by the worker. */
export function createHostToolService(options: {
identity: Readonly<SdkAgentIdentity>;
tools: HostToolDescriptor[];
handler: EventHandler;
graph?: Parameters<EventHandler['handle']>[3];
configurable: Record<string, unknown>;
metadata?: Record<string, unknown>;
peer: { call: SdkRpc };
signal: AbortSignal;
}): (data: unknown) => Promise<ToolExecuteResult[]> {
const references = new Map(options.tools.map((t) => [t.definition.name, t.reference]));
return async (data: unknown): Promise<ToolExecuteResult[]> => {
const envelope = z
.object({
id: z.string().uuid(),
incremental: z.boolean(),
request: z.object({
version: z.literal(1),
identity: z.record(z.string(), z.unknown()),
executingAgentId: z.string().optional(),
executionContext: z.unknown().optional(),
callerCapabilityProjection: z.unknown().optional(),
calls: z
.array(
z.object({
reference: z.string(),
call: z
.object({
id: z.string().min(1),
name: z.string(),
args: z.record(z.string(), z.unknown()),
})
.passthrough(),
}),
)
.min(1),
}),
})
.parse(data);
const request = envelope.request as HostToolRequest;
for (const key of [
'runtimeId',
'agentId',
'runId',
'userId',
'tenantId',
'conversationId',
] as const)
if (request.identity[key] !== options.identity[key])
throw new Error('Host tool identity mismatch');
if (
request.executionContext !== undefined ||
(request.executingAgentId !== undefined &&
request.executingAgentId !== options.identity.agentId)
)
throw new Error('Host tool execution subject is unsupported');
const ids = new Set<string>();
for (const { call, reference } of request.calls) {
if (references.get(call.name) !== reference || ids.has(call.id))
throw new Error('Host tool capability mismatch');
ids.add(call.id);
}
options.signal.throwIfAborted();
const notifications: Promise<unknown>[] = [];
let active = true;
let resolve!: (results: ToolExecuteResult[]) => void;
let reject!: (error: Error) => void;
const result = new Promise<ToolExecuteResult[]>((yes, no) => {
resolve = yes;
reject = no;
});
// Install rejection handling before invoking a handler that may reject synchronously.
void result.catch(() => undefined);
try {
await options.handler.handle(
GraphEvents.ON_TOOL_EXECUTE,
{
toolCalls: request.calls.map((c) => c.call),
userId: options.identity.userId,
agentId: options.identity.agentId,
configurable: options.configurable,
metadata: options.metadata,
callerCapabilityProjection: request.callerCapabilityProjection,
signal: options.signal,
resolve,
reject,
...(envelope.incremental
? {
onResult: (value: ToolExecuteResult) => {
if (!active || options.signal.aborted) return;
if (!ids.has(value.toolCallId))
throw new Error('Invalid incremental tool receipt');
const notice = options.peer.call('tool.result', {
id: envelope.id,
result: value,
});
void notice.catch(() => undefined);
notifications.push(notice);
},
}
: {}),
},
options.metadata,
options.graph,
);
const results = await result;
active = false;
await Promise.all(notifications);
options.signal.throwIfAborted();
return results;
} finally {
active = false;
for (const { call } of request.calls) {
notifications.push(
options.peer.call('tool.session', {
id: envelope.id,
update: {
toolCallId: call.id,
context: {
codeSessionContext: call.codeSessionContext,
codeSessionBaselineId: call.codeSessionBaselineId,
retainCodeSessionInputs: call.retainCodeSessionInputs,
runtimeSessionHint: call.runtimeSessionHint,
},
},
}),
);
}
await Promise.all(notifications);
}
};
}
export function createWorkerToolService(peer: { call: SdkRpc }): {
service: HostToolService;
accept: (data: unknown, kind?: 'result' | 'session') => null;
} {
const pending = new Map<string, HostToolEvents>();
return {
service: {
version: 1,
invoke: async (request, signal, events) => {
signal?.throwIfAborted();
const id = randomUUID();
if (events) pending.set(id, events);
try {
return (await peer.call('tools', {
id,
request,
incremental: Boolean(events?.onResult),
})) as ToolExecuteResult[];
} finally {
pending.delete(id);
}
},
},
accept: (data, kind = 'result') => {
if (kind === 'session') {
const value = z
.object({
id: z.string().uuid(),
update: z
.object({
toolCallId: z.string(),
context: z
.object({
codeSessionContext: z.unknown().optional(),
codeSessionBaselineId: z.string().optional(),
retainCodeSessionInputs: z.literal(true).optional(),
runtimeSessionHint: z.string().optional(),
})
.strict(),
})
.strict(),
})
.parse(data);
const events = pending.get(value.id);
if (!events) throw new Error('Unknown tool session invocation');
events.onSessionUpdate(value.update as HostToolSessionUpdate);
return null;
}
const value = toolResultSchema.parse(data);
const handler = pending.get(value.id);
if (!handler) throw new Error('Unknown tool result invocation');
handler.onResult?.(value.result as ToolExecuteResult);
return null;
},
};
}

View file

@ -1,8 +1,3 @@
export interface SdkAgentIdentity {
readonly agentId: string;
readonly runtimeId: string;
readonly runId: string;
readonly conversationId?: string;
readonly userId: string;
readonly tenantId?: string;
}
import type { ExecutionIdentity } from '@librechat/agents';
export type SdkAgentIdentity = Readonly<ExecutionIdentity>;

View file

@ -14,7 +14,7 @@ export interface SdkSocket {
once(event: 'close' | 'error', listener: () => void): this;
}
export type SdkRpc = (method: string, data: unknown) => Promise<unknown>;
export type SdkRpc = (method: string, data: unknown, timeoutMs?: number) => Promise<unknown>;
export type SdkFrame =
| { type: 'call'; id: string; method: string; data: unknown }
| { type: 'result'; id: string; data: unknown; failed?: boolean }
@ -150,6 +150,10 @@ export function createSdkPeer(
// Hooks observe all earlier events and can reserve content slots for later ones.
// Ordinary RPCs stay reentrant; replies above always bypass this barrier.
if (frame.method === 'hook') queue = queue.then(dispatch);
else if (frame.method === 'tools')
queue = queue.then(() => {
void dispatch();
});
else void dispatch();
return;
}
@ -170,13 +174,14 @@ export function createSdkPeer(
socket.close(1011);
});
});
const call: SdkRpc = async (method, data) => {
const call: SdkRpc = async (method, data, timeoutMs = options.timeoutMs) => {
if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw failure();
const id = randomUUID();
return new Promise((resolve, reject) => {
const timer = setTimeout(() => {
pending.delete(id);
reject(failure());
}, options.timeoutMs);
}, timeoutMs);
timer.unref();
pending.set(id, {
resolve: (value) => {

View file

@ -459,4 +459,103 @@ describe('live SDK recovery', () => {
next.close();
}
});
it.each(['approve', 'edit', 'reject'] as const)(
'resumes native host-tool %s and recovers without repeating the effect',
async (decision) => {
const runtime = await fixture(async (input) => {
const run = await Run.create({
...input.config,
tokenCounter: () => 1,
returnContent: true,
graphConfig: {
type: 'standard',
compileOptions: input.compileOptions,
agents: [
{
agentId: input.identity.agentId,
provider: Providers.OPENAI,
tools: [],
toolDefinitions: input.hostTools?.toolDefinitions,
},
],
},
});
run.Graph!.overrideTestModel(['host tool'], 5, [
{ id: 'host-inspect', name: 'inspect', args: {}, type: 'tool_call' },
]);
return run;
});
let effects = 0;
try {
const hooks = new HookRegistry();
hooks.register('PreToolUse', { hooks: [async () => ({ decision: 'ask' })] });
const config: RunConfig = {
...hostConfig(async () => undefined),
hooks,
humanInTheLoop: { enabled: true },
graphConfig: {
type: 'standard',
llmConfig: { provider: Providers.OPENAI },
compileOptions: { checkpointer: new MemorySaver() },
toolDefinitions: [
{
name: 'inspect',
description: 'Inspect',
parameters: { type: 'object', properties: {} },
},
],
},
customHandlers: {
[GraphEvents.ON_TOOL_EXECUTE]: {
handle: async (_event, data) => {
const batch = data as import('@librechat/agents').ToolExecuteBatchRequest;
effects++;
if (decision === 'edit') expect(batch.toolCalls[0].args.value).toBe('edited');
runtime.drop();
batch.resolve([
{
toolCallId: 'host-inspect',
status: 'success',
content: 'host inspection complete',
},
]);
},
},
},
};
const run = await createRemoteSdkRun({ config, identity, remote: runtime.remote });
const invocation = {
version: 'v2' as const,
configurable: { thread_id: identity.conversationId },
};
await run.processStream({ messages: [new HumanMessage('inspect')] }, invocation);
expect(run.getInterrupt()?.payload.type).toBe('tool_approval');
expect(effects).toBe(0);
const restored = await createRemoteSdkRun({
config,
identity,
remote: runtime.remote,
resumeState: {
content: run.Graph!.getContentParts() ?? [],
steps: run.Graph!.createRunStepResumeState().steps.map((e) => e.step),
},
});
await restored.resume(
{
'host-inspect': {
type: decision,
...(decision === 'edit' ? { updatedInput: { value: 'edited' } } : {}),
...(decision === 'reject' ? { reason: 'declined' } : {}),
},
},
invocation,
);
expect(effects).toBe(decision === 'reject' ? 0 : 1);
expect(runtime.createRun).toHaveBeenCalledTimes(2);
expect(runtime.connections()).toBeGreaterThanOrEqual(decision === 'reject' ? 2 : 3);
} finally {
await runtime.close();
}
},
);
});

View file

@ -2,7 +2,13 @@ import { z } from 'zod';
import jwt from 'jsonwebtoken';
import { createServer } from 'node:http';
import WebSocket, { WebSocketServer } from 'ws';
import { Run, HookRegistry, HOOK_EVENTS, GraphEvents } from '@librechat/agents';
import {
Run,
createHostToolBindings,
HookRegistry,
HOOK_EVENTS,
GraphEvents,
} from '@librechat/agents';
import type { EventHandler, AggregatedHookResult, HookOutput } from '@librechat/agents';
import type { Duplex } from 'node:stream';
import type { Server } from 'node:http';
@ -12,6 +18,7 @@ import type { SdkAgentIdentity } from './identity';
import { createRuntimeRecovery, recoveryClaimSchema } from './recovery/server';
import { remoteSdkLimits, isRemoteSdkSecret } from './types';
import { RECOVERY_HEADER_BYTES } from './recovery/socket';
import { createWorkerToolService } from './hostTools';
import { RemoteSdkCheckpointer } from './checkpoint';
import { createSdkPeer } from './peer';
@ -35,6 +42,14 @@ const claimSchema = z.object({
exp: z.number(),
});
const startSchema = z.object({
hostTools: z
.array(
z.object({
reference: z.string().min(1),
definition: z.object({ name: z.string().min(1) }).passthrough(),
}),
)
.optional(),
operation: z.enum(['start', 'resume']),
input: z.object({ messages: z.array(z.unknown()) }).passthrough(),
resume: z.unknown().optional(),
@ -233,6 +248,10 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
if (!running) active.delete(controller);
};
transport.once('close', cleanup);
const workerTools = createWorkerToolService({
call: (method, data) =>
peer.call(method, data, method === 'tools' ? limits.maxRunMs : undefined),
});
const peer = createSdkPeer(transport, {
...limits,
timeoutMs: limits.rpcTimeoutMs,
@ -242,6 +261,9 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
throw new Error('Unexpected runtime frame');
},
onCall: async (method, data) => {
if (method === 'capabilities') return { hostTools: 1 };
if (method === 'tool.result') return workerTools.accept(data);
if (method === 'tool.session') return workerTools.accept(data, 'session');
if (method !== 'run' || started) throw new Error('SDK execution already admitted');
started = true;
const request = startSchema.parse(data) as RemoteSdkStart;
@ -305,13 +327,21 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
],
});
}
const hostTools = request.hostTools?.length
? createHostToolBindings({
identity,
tools: request.hostTools,
service: workerTools.service,
})
: undefined;
const execute = async () => {
await recovered?.begin();
const run = await options.createRun({
identity,
hostTools,
config: {
runId: identity.runId,
customHandlers: handlers,
customHandlers: { ...handlers, ...hostTools?.customHandlers },
hooks,
humanInTheLoop: request.humanInTheLoop,
streamLimits: request.streamLimits,
@ -328,6 +358,15 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
run.Graph?.defaultAgentId !== identity.agentId
)
throw new Error('SDK runtime run identity mismatch');
if (hostTools) {
const names = new Set(
run.Graph.agentContexts
.get(identity.agentId)
?.toolDefinitions?.map((t) => t.name),
);
if (hostTools.toolDefinitions.some((t) => !names.has(t.name)))
throw new Error('SDK runtime omitted required host tools');
}
const callerOptions = {
...request.options,
version: 'v2' as const,

View file

@ -1,4 +1,12 @@
import type { Run, RunConfig, EventHandler, IState, HookEvent } from '@librechat/agents';
import type {
HostToolDescriptor,
HostToolBindings,
Run,
RunConfig,
EventHandler,
IState,
HookEvent,
} from '@librechat/agents';
import type { SdkAgentIdentity } from './identity';
export interface RemoteSdkRecoveryOptions {
@ -42,6 +50,7 @@ export type SdkRunInput = Parameters<SdkRun['processStream']>[0];
export type SdkRunOptions = Parameters<SdkRun['processStream']>[1];
export type SdkEventData = Parameters<EventHandler['handle']>[1];
export interface RemoteSdkStart {
hostTools?: HostToolDescriptor[];
operation: 'start' | 'resume';
input: IState;
resume?: unknown;
@ -74,6 +83,7 @@ export interface RemoteSdkSnapshot {
runSteps?: ReturnType<NonNullable<SdkRun['Graph']>['createRunStepResumeState']>;
}
export interface RemoteSdkFactoryInput {
hostTools?: HostToolBindings;
identity: Readonly<SdkAgentIdentity>;
/** Host-owned event, hook, and checkpoint adapters. Retain these in the returned Run. */
config: Pick<RunConfig, 'runId' | 'customHandlers' | 'hooks' | 'humanInTheLoop' | 'streamLimits'>;