From 9363db541ecd4e23ab6a41dca47ca48ee2bd418e Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Sun, 15 Nov 2026 09:42:41 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=95=E2=80=8D=F0=9F=A6=BA=20feat:=20Run?= =?UTF-8?q?=20Authorized=20Host=20Tools=20From=20Remote=20SDK=20Agents=20(?= =?UTF-8?q?#18189)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- api/package.json | 2 +- docs/sdk/agents.md | 31 ++- examples/sdk-runtime/agent.cjs | 8 +- examples/sdk-runtime/minimal.cjs | 3 +- package-lock.json | 10 +- packages/api/package.json | 2 +- .../api/src/agents/remoteSdk/bridge.spec.ts | 135 +++++++++++ packages/api/src/agents/remoteSdk/client.ts | 41 +++- .../src/agents/remoteSdk/hostTools.spec.ts | 111 +++++++++ .../api/src/agents/remoteSdk/hostTools.ts | 212 ++++++++++++++++++ packages/api/src/agents/remoteSdk/identity.ts | 11 +- packages/api/src/agents/remoteSdk/peer.ts | 11 +- .../runtime.cache_integration.spec.ts | 99 ++++++++ packages/api/src/agents/remoteSdk/server.ts | 43 +++- packages/api/src/agents/remoteSdk/types.ts | 12 +- 15 files changed, 706 insertions(+), 25 deletions(-) create mode 100644 packages/api/src/agents/remoteSdk/hostTools.spec.ts create mode 100644 packages/api/src/agents/remoteSdk/hostTools.ts diff --git a/api/package.json b/api/package.json index 1affaca307..b076b68eee 100644 --- a/api/package.json +++ b/api/package.json @@ -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", diff --git a/docs/sdk/agents.md b/docs/sdk/agents.md index 40e7740d73..24b931d223 100644 --- a/docs/sdk/agents.md +++ b/docs/sdk/agents.md @@ -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. diff --git a/examples/sdk-runtime/agent.cjs b/examples/sdk-runtime/agent.cjs index 1c74bac685..c74ff48d6f 100644 --- a/examples/sdk-runtime/agent.cjs +++ b/examples/sdk-runtime/agent.cjs @@ -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', diff --git a/examples/sdk-runtime/minimal.cjs b/examples/sdk-runtime/minimal.cjs index 3ef0422f41..ba461795be 100644 --- a/examples/sdk-runtime/minimal.cjs +++ b/examples/sdk-runtime/minimal.cjs @@ -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' }, }, ], diff --git a/package-lock.json b/package-lock.json index 088d388668..038b10d672 100644 --- a/package-lock.json +++ b/package-lock.json @@ -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", diff --git a/packages/api/package.json b/packages/api/package.json index a5f20a1f0c..c9fc824e0a 100644 --- a/packages/api/package.json +++ b/packages/api/package.json @@ -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", diff --git a/packages/api/src/agents/remoteSdk/bridge.spec.ts b/packages/api/src/agents/remoteSdk/bridge.spec.ts index 3a23500ae5..b2d4cf9688 100644 --- a/packages/api/src/agents/remoteSdk/bridge.spec.ts +++ b/packages/api/src/agents/remoteSdk/bridge.spec.ts @@ -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((resolve) => { + release = resolve; + }); + let first!: () => void; + const ready = new Promise((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 | 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(); + } + }); }); diff --git a/packages/api/src/agents/remoteSdk/client.ts b/packages/api/src/agents/remoteSdk/client.ts index d27bc1549e..a872ff84b3 100644 --- a/packages/api/src/agents/remoteSdk/client.ts +++ b/packages/api/src/agents/remoteSdk/client.ts @@ -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 { + 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 | 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; diff --git a/packages/api/src/agents/remoteSdk/hostTools.spec.ts b/packages/api/src/agents/remoteSdk/hostTools.spec.ts new file mode 100644 index 0000000000..cd89c79f3a --- /dev/null +++ b/packages/api/src/agents/remoteSdk/hostTools.spec.ts @@ -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'); +}); diff --git a/packages/api/src/agents/remoteSdk/hostTools.ts b/packages/api/src/agents/remoteSdk/hostTools.ts new file mode 100644 index 0000000000..c8d97b5fd4 --- /dev/null +++ b/packages/api/src/agents/remoteSdk/hostTools.ts @@ -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; + tools: HostToolDescriptor[]; + handler: EventHandler; + graph?: Parameters[3]; + configurable: Record; + metadata?: Record; + peer: { call: SdkRpc }; + signal: AbortSignal; +}): (data: unknown) => Promise { + const references = new Map(options.tools.map((t) => [t.definition.name, t.reference])); + return async (data: unknown): Promise => { + 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(); + 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[] = []; + let active = true; + let resolve!: (results: ToolExecuteResult[]) => void; + let reject!: (error: Error) => void; + const result = new Promise((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(); + 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; + }, + }; +} diff --git a/packages/api/src/agents/remoteSdk/identity.ts b/packages/api/src/agents/remoteSdk/identity.ts index 1c7ec4d205..f289ca792a 100644 --- a/packages/api/src/agents/remoteSdk/identity.ts +++ b/packages/api/src/agents/remoteSdk/identity.ts @@ -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; diff --git a/packages/api/src/agents/remoteSdk/peer.ts b/packages/api/src/agents/remoteSdk/peer.ts index faf19ff442..ad00c3c792 100644 --- a/packages/api/src/agents/remoteSdk/peer.ts +++ b/packages/api/src/agents/remoteSdk/peer.ts @@ -14,7 +14,7 @@ export interface SdkSocket { once(event: 'close' | 'error', listener: () => void): this; } -export type SdkRpc = (method: string, data: unknown) => Promise; +export type SdkRpc = (method: string, data: unknown, timeoutMs?: number) => Promise; 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) => { diff --git a/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts b/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts index 84c6ad2fdc..e8d7d51055 100644 --- a/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts +++ b/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts @@ -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(); + } + }, + ); }); diff --git a/packages/api/src/agents/remoteSdk/server.ts b/packages/api/src/agents/remoteSdk/server.ts index 488f0a3fd3..f306397aed 100644 --- a/packages/api/src/agents/remoteSdk/server.ts +++ b/packages/api/src/agents/remoteSdk/server.ts @@ -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, diff --git a/packages/api/src/agents/remoteSdk/types.ts b/packages/api/src/agents/remoteSdk/types.ts index 981c8a6e78..4a73adb8fc 100644 --- a/packages/api/src/agents/remoteSdk/types.ts +++ b/packages/api/src/agents/remoteSdk/types.ts @@ -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[0]; export type SdkRunOptions = Parameters[1]; export type SdkEventData = Parameters[1]; export interface RemoteSdkStart { + hostTools?: HostToolDescriptor[]; operation: 'start' | 'resume'; input: IState; resume?: unknown; @@ -74,6 +83,7 @@ export interface RemoteSdkSnapshot { runSteps?: ReturnType['createRunStepResumeState']>; } export interface RemoteSdkFactoryInput { + hostTools?: HostToolBindings; identity: Readonly; /** Host-owned event, hook, and checkpoint adapters. Retain these in the returned Run. */ config: Pick;