🛁 feat: Apply Host Provider-Text Protection to Remote SDK Runs (#18240)
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

* feat: bridge host provider-text policy to remote SDK runs

* build: consume published agents 4.2.7 for remote policy services
This commit is contained in:
Danny Avila 2026-11-16 22:37:13 -05:00 • committed by GitHub
parent 62fd38813e
commit 2b828ca2c5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
17 changed files with 870 additions and 35 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.6",
"@librechat/agents": "^4.2.7",
"@librechat/api": "*",
"@librechat/data-schemas": "*",
"@microsoft/microsoft-graph-client": "^3.0.7",

View file

@ -55,7 +55,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "5.1.6",
"@librechat/agents": "^4.2.6",
"@librechat/agents": "^4.2.7",
"@librechat/api": "*",
"@librechat/data-schemas": "*",
"@microsoft/microsoft-graph-client": "^3.0.7",
@ -378,7 +378,7 @@
"@azure/identity": "^4.14.0",
"@azure/storage-blob": "^12.30.0",
"@keyv/redis": "5.1.6",
"@librechat/agents": "^4.2.6",
"@librechat/agents": "^4.2.7",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.32.1",
"@opentelemetry/api": "^1.9.0",
@ -1603,7 +1603,7 @@
"@lezer/lr": ["@lezer/lr@1.4.2", "", { "dependencies": { "@lezer/common": "^1.0.0" } }, "sha512-pu0K1jCIdnQ12aWNaAVU5bzi7Bd1w54J3ECgANPmYLtQKP0HBj2cE/5coBD66MT10xbtIuUr7tg0Shbsvk0mDA=="],
"@librechat/agents": ["@librechat/agents@4.2.6", "", { "dependencies": { "@anthropic-ai/sdk": "^0.115.0", "@aws-sdk/client-bedrock-runtime": "^3.1075.0", "@langchain/anthropic": "1.5.2", "@langchain/aws": "^1.4.2", "@langchain/core": "1.2.8", "@langchain/deepseek": "^1.1.3", "@langchain/google-common": "2.2.0", "@langchain/google-gauth": "2.2.0", "@langchain/google-genai": "2.2.0", "@langchain/google-vertexai": "2.2.0", "@langchain/langgraph": "1.4.8", "@langchain/mistralai": "^1.2.0", "@langchain/openai": "1.5.8", "@langchain/textsplitters": "^1.0.1", "@langchain/xai": "^1.4.3", "@langfuse/core": "^5.10.1", "@langfuse/langchain": "^5.10.1", "@langfuse/otel": "^5.10.1", "@langfuse/tracing": "^5.10.1", "@opentelemetry/context-async-hooks": "^2.9.0", "@opentelemetry/sdk-node": "^0.220.0", "@types/diff": "^7.0.2", "ai-tokenizer": "^1.0.6", "axios": "^1.20.0", "cheerio": "^1.2.0", "diff": "^9.0.0", "dotenv": "^16.4.7", "https-proxy-agent": "^7.0.6", "mathjs": "^15.2.0", "nanoid": "^3.3.18", "okapibm25": "^1.4.1", "openai": "^6.46.0", "reova": "^0.4.1", "socks-proxy-agent": "^8.0.5", "uuid": "^11.1.1", "zod": "4.6.7", "zod-to-json-schema": "3.25.2" }, "peerDependencies": { "@anthropic-ai/sandbox-runtime": "^0.0.78" }, "optionalPeers": ["@anthropic-ai/sandbox-runtime"] }, "sha512-UWp0UjIrXIt/tdO5BWDaTRpVQFN6yEHwmDdAregs1yHN/X/8GHu2D3ParQB0ze3NR3nm7Mkps/K0VB476oA7UQ=="],
"@librechat/agents": ["@librechat/agents@4.2.7", "", { "dependencies": { "@anthropic-ai/sdk": "^0.115.0", "@aws-sdk/client-bedrock-runtime": "^3.1075.0", "@langchain/anthropic": "1.5.2", "@langchain/aws": "^1.4.2", "@langchain/core": "1.2.8", "@langchain/deepseek": "^1.1.3", "@langchain/google-common": "2.2.0", "@langchain/google-gauth": "2.2.0", "@langchain/google-genai": "2.2.0", "@langchain/google-vertexai": "2.2.0", "@langchain/langgraph": "1.4.8", "@langchain/mistralai": "^1.2.0", "@langchain/openai": "1.5.8", "@langchain/textsplitters": "^1.0.1", "@langchain/xai": "^1.4.3", "@langfuse/core": "^5.10.1", "@langfuse/langchain": "^5.10.1", "@langfuse/otel": "^5.10.1", "@langfuse/tracing": "^5.10.1", "@opentelemetry/context-async-hooks": "^2.9.0", "@opentelemetry/sdk-node": "^0.220.0", "@types/diff": "^7.0.2", "ai-tokenizer": "^1.0.6", "axios": "^1.20.0", "cheerio": "^1.2.0", "diff": "^9.0.0", "dotenv": "^16.4.7", "https-proxy-agent": "^7.0.6", "mathjs": "^15.2.0", "nanoid": "^3.3.18", "okapibm25": "^1.4.1", "openai": "^6.46.0", "reova": "^0.4.1", "socks-proxy-agent": "^8.0.5", "uuid": "^11.1.1", "zod": "4.6.7", "zod-to-json-schema": "3.25.2" }, "peerDependencies": { "@anthropic-ai/sandbox-runtime": "^0.0.78" }, "optionalPeers": ["@anthropic-ai/sandbox-runtime"] }, "sha512-j6TfPPZhiEHMFyT7xVc1y3Hh+w+l9YOkMf/0IlJU/GDoyH+DUyVElU9fjdmUVNSMcCHOQb0diHS7B9sQSofD8g=="],
"@librechat/api": ["@librechat/api@workspace:packages/api"],

View file

@ -154,27 +154,27 @@ acceptance target remains the main chat's functionality and experience, with mea
Using native events and the native renderer proves only the behaviors tested below. Missing
adapters and unverified behaviors remain release gates for products that depend on them.
| Main-chat capability | This bridge | Remaining work / verification |
| ----------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Saved agent identity, role authorization, picker | Reuses the existing registration and picker | Remote enrollment/discovery is not implemented; operators configure deployments. |
| Text and tool-step rendering, persistence | Verified with a minimal Run and a custom graph in real LibreChat | Deterministic models were used; repeat with production providers and representative workloads. |
| Reasoning, citations, rich/custom tool events | Native event transport is available | Provider-specific and rich-content end-to-end parity has not been verified. |
| Custom graph, nested SDK node, conditional refinement | Verified in another process | Broader graphs, parallel branches, and large checkpoints need workload acceptance tests. |
| Approval after browser reload and worker restart | Approve verified with host Mongo checkpoints | Edit/reject, ask-user questions, and repeated/batched interruptions need remote browser tests. |
| Stop and browser reconnection to an active job | Verified; stop reaches the worker abort signal and persists no error | Cancellation is cooperative and cannot undo completed tool effects. |
| 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 | 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 | 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. |
| Context pruning, compaction, summaries, cache/fading policy | Worker can use SDK features; terminal context metadata is returned | Host configuration and continuation policy are not automatically installed on the worker. Main-chat behavioral/performance parity is not established. |
| Token usage, cost/balance accounting | Native model events can be transported | Arbitrary worker model attribution and nested usage/balance enforcement need an explicit contract and tests; do not assume billing parity. |
| Tracing and tenant trace/export/redaction policy | Worker can configure SDK tracing itself | Host tracing callbacks and tenant export policy are not automatically inherited. Correlated, policy-safe tracing remains an integration gap. |
| Schedules/background/Responses callers | The bridge returns a Run through the common execution seam | Full lifecycle acceptance for these callers has not been performed. |
| Console Assistant and Schema Advisor | No product cutover in this change | Wire Schema Advisor, close its required gaps, then adopt shared chat components and compare performance. |
| Main-chat capability | This bridge | Remaining work / verification |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Saved agent identity, role authorization, picker | Reuses the existing registration and picker | Remote enrollment/discovery is not implemented; operators configure deployments. |
| Text and tool-step rendering, persistence | Verified with a minimal Run and a custom graph in real LibreChat | Deterministic models were used; repeat with production providers and representative workloads. |
| Reasoning, citations, rich/custom tool events | Native event transport is available | Provider-specific and rich-content end-to-end parity has not been verified. |
| Custom graph, nested SDK node, conditional refinement | Verified in another process | Broader graphs, parallel branches, and large checkpoints need workload acceptance tests. |
| Approval after browser reload and worker restart | Approve verified with host Mongo checkpoints | Edit/reject, ask-user questions, and repeated/batched interruptions need remote browser tests. |
| Stop and browser reconnection to an active job | Verified; stop reaches the worker abort signal and persists no error | Cancellation is cooperative and cannot undo completed tool effects. |
| 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; worker owns the graph/model/tools | SDK `HostChatModel` and `createHostModelService` are available; remote model transport and builder wiring are still required to make settings authoritative. |
| 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. |
| Context pruning, compaction, summaries, cache/fading policy | Worker can use SDK features; terminal context metadata is returned | Host configuration and continuation policy are not automatically installed on the worker. Main-chat behavioral/performance parity is not established. |
| Token usage, cost/balance accounting | Native model events can be transported | Arbitrary worker model attribution and nested usage/balance enforcement need an explicit contract and tests; do not assume billing parity. |
| Tracing and tenant trace/export/redaction policy | Worker can configure SDK tracing itself | Host tracing callbacks and tenant export policy are not automatically inherited. Correlated, policy-safe tracing remains an integration gap. |
| Schedules/background/Responses callers | The bridge returns a Run through the common execution seam | Full lifecycle acceptance for these callers has not been performed. |
| Console Assistant and Schema Advisor | No product cutover in this change | Wire Schema Advisor, close its required gaps, then adopt shared chat components and compare performance. |
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;
@ -221,3 +221,80 @@ Caller-owned function tools (`clientDelegatedToolNames`) are not host tools. Rem
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.
## Host provider-text service
Programmatic hosts can pass `hostServices.providerText` to `createRemoteSdkRun` from
`@librechat/api/sdk`. This is the exact binding returned by the SDK's
`createHostProviderTextService({ identity, policy, admission, inspectionTimeoutMs })`.
Create the binding from authenticated identity and a trusted host policy. Reuse a
`ProviderTextAdmission` object across all runs belonging to the host-selected quota
(typically a tenant/runtime), including reconnects. Configure its concurrency and
byte limits and the host inspection deadline explicitly; the transport does not
invent or reset those SDK-owned limits. This capability object contains callbacks
and is supplied by the host integration, not reconstructed from YAML or worker data.
```js
const { ProviderTextAdmission, createHostProviderTextService } = require('@librechat/agents');
const { createRemoteSdkRun } = require('@librechat/api/sdk');
// Retain with the host tenant/runtime registry, outside per-request code.
const admission = new ProviderTextAdmission({
maxConcurrentInspections: 4,
maxBufferedBytes: 4 * 1024 * 1024,
});
const run = await createRemoteSdkRun({
config,
identity,
remote,
hostServices: {
providerText: createHostProviderTextService({
identity,
policy: trustedHostOutputPolicy,
admission,
inspectionTimeoutMs: 5000,
}),
},
});
```
Both sides require SDK 4.2.7 and the new bridge's `providerText: 1` capability.
Protected runs fail before factory admission on older workers. The worker receives
`config.providerTextProtection`; its factory must retain that exact policy on its
returned SDK graph. Omitting it fails before model execution. Custom graphs remain
trusted code and must install it on every applicable SDK Run. Main-chat's model/PII
rejection in saved-agent dispatch stays in place: this output-text adapter does not
supply input/model callbacks, authoritative builder model selection, host model
credentials, or policy for model calls made outside the SDK. SDK 4.2.7 also provides
`HostChatModel` and `createHostModelService` for host-owned model execution; those
contracts still need authenticated transport and saved-agent integration before
this guard can be removed.
The worker buffers a complete model attempt through the same SDK release boundary
as local execution, then sends one `policy.providerText` RPC. Only canonical approved
text reaches the normal event handlers and terminal snapshot. Known policy failure
codes use the SDK's versioned, sanitized envelope. A cancelled or timed-out host
inspector keeps its SDK admission and memory charges until its underlying work
settles; observe `admission.snapshot()` for retained work and drain/terminate a hung
owner instead of replacing its quota. These quotas remain process-local.
Candidate RPCs are encrypted before entering the existing bounded/recoverable
transport. Each host execution holds a volatile X25519 private key; each request
uses a fresh ephemeral X25519 key, HKDF-SHA256 and AES-256-GCM. Recovery logs contain
ciphertext and public keys, never the candidate plaintext or the host private key.
Authentication still comes from the signed execution binding and TLS; encryption
is not an authorization mechanism. The host drops its key reference at terminal
cleanup. Existing same-host/same-worker reconnect can replay the encrypted request
or canonical reply without rerunning inspection. Host-process adoption remains
unsupported, and ciphertext is still sensitive retained data subject to journal
TTL, deletion and access controls. This does not change the retention policy for
other event/checkpoint data already carried by the bridge.
The existing `maxFrameBytes` and `maxBufferedBytes` bound encrypted frames as well.
Base64/envelope overhead reduces the maximum candidate fitting a frame; oversized
attempts fail closed, without plaintext fallback or unbounded chunking. Align
transport limits and SDK policy limits with the workload before enabling it.
Run the separate-process example benchmark with `SDK_BENCHMARK_PROTECTION=true`
to compare the same deterministic custom graph locally and remotely with a
pass-through inspection policy; this is a transport measurement, not PII validation.

View file

@ -130,3 +130,17 @@ Run `npm run test:cache-integration:sdk --workspace=@librechat/api` against loca
fault-injection tests, and the Redis Playwright lane's `remote-sdk-recovery.spec.ts` for a real
LibreChat custom-graph approval, wire outage, reconnection and saved-history test. Set
`SDK_RUNTIME_RECOVERY=true` for `benchmark.cjs` to include Redis journal overhead.
## Protected provider-text benchmark
With SDK 4.2.7 and this bridge on both sides, run
`SDK_BENCHMARK_PROTECTION=true node examples/sdk-runtime/benchmark.cjs` against the
example worker. Add `SDK_RUNTIME_RECOVERY=true` to include Redis recovery. Both
local and remote executions use the same deterministic pass-through output policy;
the remote path adds host inspection through the SDK contract. This benchmark does
not implement a production PII detector or enable protected saved-agent chat.
See [host provider-text services](../../docs/sdk/agents.md#host-provider-text-service)
for admission ownership, encrypted journal payloads, and the remaining model/input
policy guards. The existing factories retain `input.config`, including the new
provider-text protection adapter, for both the minimal and custom-graph examples.

View file

@ -4,6 +4,7 @@ const { Run, Providers } = require('@librechat/agents');
const { AIMessageChunk, HumanMessage } = require('@librechat/agents/langchain/messages');
const { tool } = require('@librechat/agents/langchain/tools');
const { FakeChatModel } = require('@langchain/core/utils/testing');
const { ChatGenerationChunk } = require('@langchain/core/outputs');
const {
Annotation,
StateGraph,
@ -89,6 +90,15 @@ async function createExampleRun(input, { complex = true, stepDelayMs = 0 } = {})
},
],
});
model._streamResponseChunks = async function* (messages) {
const { generations } = await this._generate(messages);
for (const generation of generations) {
yield new ChatGenerationChunk({
...generation,
text: typeof generation.message.content === 'string' ? generation.message.content : '',
});
}
};
run.Graph.overrideModel = model;
}
if (complex) {

View file

@ -1,10 +1,34 @@
const { performance } = require('node:perf_hooks');
const { randomUUID } = require('node:crypto');
const { GraphEvents, Providers } = require('@librechat/agents');
const {
GraphEvents,
Providers,
ProviderTextAdmission,
createHostProviderTextService,
} = require('@librechat/agents');
const { HumanMessage } = require('@librechat/agents/langchain/messages');
const { createRemoteSdkRun } = require('@librechat/api/sdk');
const { createExampleRun } = require('./agent.cjs');
const protectedOutput = process.env.SDK_BENCHMARK_PROTECTION === 'true';
const admission = new ProviderTextAdmission({
maxConcurrentInspections: 4,
maxBufferedBytes: 4194304,
});
// A deterministic pass-through policy measures bridge cost, not production PII detection.
const policy = {
version: 1,
timeoutMs: 10000,
maxAttemptBytes: 1048576,
maxBufferedBytes: 4194304,
classify: () => 'prose',
inspect: ({ content }) => ({
version: 1,
ok: true,
value: { content, replacements: 0, categories: [] },
}),
};
async function measure(remote) {
const identity = {
runtimeId: process.env.SDK_RUNTIME_ID || 'remote-example',
@ -17,6 +41,7 @@ async function measure(remote) {
const started = performance.now();
const config = {
runId: identity.runId,
...(protectedOutput && { providerTextProtection: policy }),
returnContent: true,
tokenCounter: () => 1,
customHandlers: {
@ -36,6 +61,16 @@ async function measure(remote) {
? await createRemoteSdkRun({
config,
identity,
...(protectedOutput && {
hostServices: {
providerText: createHostProviderTextService({
identity,
policy,
admission,
inspectionTimeoutMs: 5000,
}),
},
}),
remote: {
url: process.env.SDK_RUNTIME_URL || 'ws://127.0.0.1:8804/sdk',
secret: process.env.SDK_RUNTIME_SECRET || '',
@ -74,6 +109,7 @@ async function main() {
JSON.stringify(
{
mode: 'deterministic custom graph, five warm samples',
protectedOutput,
local,
remote,
median: {

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.6",
"@librechat/agents": "^4.2.7",
"@librechat/api": "*",
"@librechat/data-schemas": "*",
"@microsoft/microsoft-graph-client": "^3.0.7",
@ -9479,9 +9479,9 @@
}
},
"node_modules/@librechat/agents": {
"version": "4.2.6",
"resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-4.2.6.tgz",
"integrity": "sha512-UWp0UjIrXIt/tdO5BWDaTRpVQFN6yEHwmDdAregs1yHN/X/8GHu2D3ParQB0ze3NR3nm7Mkps/K0VB476oA7UQ==",
"version": "4.2.7",
"resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-4.2.7.tgz",
"integrity": "sha512-j6TfPPZhiEHMFyT7xVc1y3Hh+w+l9YOkMf/0IlJU/GDoyH+DUyVElU9fjdmUVNSMcCHOQb0diHS7B9sQSofD8g==",
"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.6",
"@librechat/agents": "^4.2.7",
"@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.6",
"@librechat/agents": "^4.2.7",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.32.1",
"@opentelemetry/api": "^1.9.0",

View file

@ -6,6 +6,8 @@ import { tool } from '@librechat/agents/langchain/tools';
import { FakeChatModel as TestModel } from '@langchain/core/utils/testing';
import { HumanMessage, AIMessageChunk } from '@librechat/agents/langchain/messages';
import {
createHostProviderTextService,
ProviderTextAdmission,
Run,
Providers,
GraphEvents,
@ -1114,3 +1116,128 @@ it('rejects an old host transport before constructing the worker graph', async (
await runtime.close();
}
});
describe('remote host provider-text protection', () => {
const binding = () =>
createHostProviderTextService({
identity,
admission: new ProviderTextAdmission({
maxConcurrentInspections: 2,
maxBufferedBytes: 16384,
}),
inspectionTimeoutMs: 1000,
policy: {
version: 1,
timeoutMs: 10000,
maxAttemptBytes: 8192,
maxBufferedBytes: 16384,
classify: () => 'prose',
inspect: ({ content }) => ({
version: 1,
ok: true,
value: {
content: content.replaceAll('PRIVATE', '[redacted]'),
replacements: 1,
categories: [],
},
}),
},
});
it('releases only host-approved output through real remote SDK handlers and final persistence', async () => {
const runtime = await fixture(async (input) => {
const run = await factory(input);
run.Graph!.overrideModel = new FakeChatModel({ responses: ['PRIVATE prose'], sleep: 1 });
return run;
});
const visible: string[] = [];
try {
const run = await createRemoteSdkRun({
config: {
...hostConfig(),
customHandlers: {
[GraphEvents.ON_MESSAGE_DELTA]: {
handle: async (_event, data) => {
visible.push(JSON.stringify(data));
},
},
},
},
identity,
remote: runtime.remote,
hostServices: { providerText: binding() },
});
const content = await run.processStream({ messages: [new HumanMessage('go')] }, invocation());
expect(JSON.stringify(content)).toContain('[redacted]');
expect(JSON.stringify(content)).not.toContain('PRIVATE');
expect(visible.join('')).toContain('[redacted]');
expect(visible.join('')).not.toContain('PRIVATE');
expect(JSON.stringify(run.getRunMessages())).not.toContain('PRIVATE');
} finally {
await runtime.close();
}
});
it('fails before model execution when a trusted factory omits the supplied protection', async () => {
const runtime = await fixture((input) =>
factory({ ...input, config: { ...input.config, providerTextProtection: undefined } }),
);
try {
const run = await createRemoteSdkRun({
config: hostConfig(),
identity,
remote: runtime.remote,
hostServices: { providerText: binding() },
});
await expect(
run.processStream({ messages: [new HumanMessage('go')] }, invocation()),
).rejects.toThrow('SDK runtime execution failed');
expect(run.getRunMessages()).toEqual([]);
} finally {
await runtime.close();
}
});
});
it('rejects a worker without protected-text capability before factory admission', async () => {
const server = new WebSocketServer({ port: 0, host: '127.0.0.1' });
await new Promise<void>((resolve) => server.once('listening', resolve));
const methods: string[] = [];
server.on('connection', (socket) =>
createSdkPeer(socket, {
maxFrameBytes: 65536,
maxBufferedBytes: 131072,
timeoutMs: 2000,
onClose: () => undefined,
onFrame: async () => undefined,
onCall: async (method) => {
methods.push(method);
return { transportVersion: 2, hostTools: 2 };
},
}),
);
const providerText = createHostProviderTextService({
identity,
policy: {
version: 1,
timeoutMs: 1000,
maxAttemptBytes: 4096,
maxBufferedBytes: 8192,
classify: () => 'prose',
inspect: () => ({ version: 1, ok: false, error: { code: 'blocked' } }),
},
});
try {
const run = await createRemoteSdkRun({
config: hostConfig(),
identity,
remote: { url: `ws://127.0.0.1:${(server.address() as AddressInfo).port}`, secret },
hostServices: { providerText },
});
await expect(run.processStream({ messages: [] }, invocation())).rejects.toThrow(
'SDK runtime execution failed',
);
expect(methods).toEqual(['capabilities']);
} finally {
for (const socket of server.clients) socket.terminate();
await new Promise<void>((resolve) => server.close(() => resolve()));
}
});

View file

@ -13,6 +13,7 @@ import {
} from '@librechat/agents';
import type { RunConfig, RunInterruptResult, RunStep, RunStepClosedEvent } from '@librechat/agents';
import type {
RemoteSdkHostServices,
RemoteSdkOptions,
RemoteSdkSnapshot,
RemoteSdkStart,
@ -26,6 +27,7 @@ import { connectRecoveringSdkSocket } from './recovery/client';
import { remoteSdkLimits, isRemoteSdkSecret } from './types';
import { createHostToolService } from './hostTools';
import { createSnapshotReceiver } from './snapshot';
import { createHostPolicyChannel } from './policy';
import { createSdkPeer } from './peer';
/** Construct a real local Run whose execution is delegated to one operator-trusted runtime. */
@ -34,15 +36,17 @@ export async function createRemoteSdkRun({
identity,
remote,
resumeState,
hostServices,
}: {
config: RunConfig;
hostServices?: RemoteSdkHostServices;
identity: Readonly<SdkAgentIdentity>;
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)
if (config.providerTextProtection && !hostServices?.providerText)
throw new Error('Remote SDK provider protection requires a supported policy adapter');
identity = Object.freeze({ ...identity });
const limits = remoteSdkLimits(remote);
@ -208,6 +212,9 @@ export async function createRemoteSdkRun({
})
: await legacy();
const execution = new AbortController();
const providerText = hostServices?.providerText
? createHostPolicyChannel(hostServices.providerText, limits)
: undefined;
const terminal = createSnapshotReceiver(limits.maxBufferedBytes);
snapshot = undefined;
let settled = false;
@ -261,6 +268,13 @@ export async function createRemoteSdkRun({
onCall: async (method, data, _timeoutMs, signal) => {
if (execution.signal.aborted || options.signal?.aborted)
throw new Error('SDK runtime execution stopped');
if (method === 'policy.providerText') {
if (!providerText) throw new Error('Host provider policy is unavailable');
return providerText.inspect(
data,
signal ? AbortSignal.any([execution.signal, signal]) : execution.signal,
);
}
if (method === 'tools') {
if (!toolHandler || !descriptors.length) throw new Error('Host tools are unavailable');
hostToolInvoke ??= createHostToolService({
@ -387,6 +401,7 @@ export async function createRemoteSdkRun({
'agents' in config.graphConfig ? config.graphConfig.agents[0] : config.graphConfig;
const start: RemoteSdkStart = {
transportVersion: 2,
providerText: providerText?.descriptor,
hostTools: descriptors.length ? descriptors : undefined,
operation,
input,
@ -425,9 +440,12 @@ export async function createRemoteSdkRun({
const capabilities = (await peer.call('capabilities', null)) as {
transportVersion?: number;
hostTools?: number;
providerText?: number;
};
if (capabilities?.transportVersion !== 2)
throw new Error('Worker transport capability unavailable');
if (providerText && capabilities?.providerText !== 1)
throw new Error('Worker provider policy capability unavailable');
if (descriptors.length) {
if (capabilities?.hostTools !== 2)
throw new Error('Worker host tool capability unavailable');
@ -441,6 +459,7 @@ export async function createRemoteSdkRun({
return snapshot.content?.filter((part) => part != null);
} finally {
execution.abort();
providerText?.dispose();
// A failed/cancelled remote run may leave host cleanup running. Keep the host
// execution enrolled until those handlers drain, even if the wire has closed.
await Promise.allSettled([...hostInvocations]);

View file

@ -0,0 +1,240 @@
import { randomUUID } from 'node:crypto';
import { EventEmitter } from 'node:events';
import { createHostProviderTextService, ProviderTextAdmission } from '@librechat/agents';
import type { ProviderTextProtection } from '@librechat/agents';
import type WebSocket from 'ws';
import { createHostPolicyChannel, createWorkerProviderTextPolicy } from './policy';
import { RecoverySocket, createMemoryRecoveryLog } from './recovery/socket';
import { createPolicyReceiver, createPolicySender } from './sealed';
import { remoteSdkLimits } from './types';
const identity = { runtimeId: 'runtime', agentId: 'agent', runId: 'run', userId: 'user' };
const limits = remoteSdkLimits({ maxFrameBytes: 8192 });
const request = { version: 1 as const, identity, content: 'PRIVATE candidate' };
function fixture(overrides: Partial<ProviderTextProtection> = {}) {
const admission = new ProviderTextAdmission({
maxConcurrentInspections: 1,
maxBufferedBytes: 8192,
});
const bound = createHostProviderTextService({
identity,
admission,
inspectionTimeoutMs: 100,
policy: {
version: 1,
timeoutMs: 1000,
maxAttemptBytes: 8192,
maxBufferedBytes: 16384,
classify: () => 'prose',
inspect: () => ({
version: 1,
ok: true,
value: { content: 'approved', replacements: 1, categories: [] },
}),
...overrides,
},
});
const host = createHostPolicyChannel(bound, limits);
const call = jest.fn(async (_method, data, _timeoutMs, signal) => host.inspect(data, signal));
const worker = createWorkerProviderTextPolicy({
descriptor: host.descriptor,
identity,
peer: { call },
limits,
});
const inspect = (content: string, signal = new AbortController().signal) =>
worker.inspect({
version: 1,
content,
target: { source: 'message', field: 'text', provenance: 'model' },
signal,
});
return { host, worker, call, admission, inspect };
}
it('seals raw requests before RPC and returns only approved text', async () => {
const f = fixture();
try {
expect(await f.inspect(request.content)).toMatchObject({
ok: true,
value: { content: 'approved' },
});
expect(f.call).toHaveBeenCalledTimes(1);
expect(f.call.mock.calls[0][0]).toBe('policy.providerText');
expect(JSON.stringify(f.call.mock.calls)).not.toContain('PRIVATE');
expect(f.admission.snapshot()).toMatchObject({ inspections: 0, bufferedBytes: 0 });
} finally {
f.host.dispose();
}
});
it('forwards cancellation and retains host admission until an ignoring inspector drains', async () => {
let release!: () => void;
const held = new Promise<void>((resolve) => {
release = resolve;
});
const f = fixture({
inspect: async () => {
await held;
return {
version: 1,
ok: true,
value: { content: 'late PRIVATE', replacements: 0, categories: [] },
};
},
});
const controller = new AbortController();
const result = Promise.resolve(f.inspect(request.content, controller.signal)).catch(
(error: Error) => error,
);
try {
controller.abort();
expect(await result).toMatchObject({ code: 'cancelled' });
expect(f.call.mock.calls[0][3]).toBe(controller.signal);
expect(f.admission.snapshot().retainedInspections).toBe(1);
await expect(f.inspect(request.content)).rejects.toMatchObject({ code: 'overflow' });
release();
await new Promise((resolve) => setImmediate(resolve));
expect(f.admission.snapshot().inspections).toBe(0);
} finally {
release();
f.host.dispose();
}
});
it('uses host deadlines without a worker cancellation and sanitizes inspector errors', async () => {
const f = fixture({
inspect: () => {
throw new Error('PRIVATE credential');
},
});
try {
await expect(f.inspect(request.content)).rejects.toMatchObject({
code: 'unavailable',
message: 'Provider text protection: unavailable',
});
} finally {
f.host.dispose();
}
let release!: () => void;
const held = new Promise<void>((resolve) => {
release = resolve;
});
const timed = fixture({
inspect: async () => {
await held;
return { version: 1, ok: false, error: { code: 'blocked' } };
},
});
try {
await expect(timed.inspect(request.content)).rejects.toMatchObject({ code: 'timeout' });
expect(timed.admission.snapshot().retainedInspections).toBe(1);
} finally {
release();
timed.host.dispose();
}
});
it('validates the authenticated identity after decryption, before policy inspection', async () => {
const inspect = jest.fn<
ReturnType<ProviderTextProtection['inspect']>,
Parameters<ProviderTextProtection['inspect']>
>(() => ({ version: 1, ok: false, error: { code: 'blocked' } }));
const f = fixture({ inspect });
const seal = createPolicySender(f.host.descriptor.publicKey, limits.maxFrameBytes);
try {
expect(
await f.host.inspect(
seal(JSON.stringify({ ...request, identity: { ...identity, userId: 'foreign' } })),
),
).toEqual({ version: 1, ok: false, error: { code: 'incompatible' } });
expect(inspect).not.toHaveBeenCalled();
} finally {
f.host.dispose();
}
});
it('rejects tampering, foreign run keys, malformed envelopes and disposed receivers', () => {
const receiver = createPolicyReceiver(1024);
const other = createPolicyReceiver(1024);
const seal = createPolicySender(receiver.publicKey, 1024);
const payload = seal(request.content);
expect(receiver.open(payload)).toBe(request.content);
expect(seal(request.content)).not.toEqual(payload);
expect(() => other.open(payload)).toThrow();
for (const changed of [
null,
{},
{ ...payload, version: 2 },
{ ...payload, tag: Buffer.alloc(16).toString('base64') },
{ ...payload, nonce: Buffer.alloc(12).toString('base64') },
{ ...payload, ciphertext: 'invalid' },
{ ...payload, publicKey: other.publicKey },
]) {
expect(() => receiver.open(changed)).toThrow();
}
receiver.dispose();
other.dispose();
expect(() => receiver.open(payload)).toThrow();
});
it('bounds payloads before encryption/decryption and handles a large candidate without a regex stack overflow', () => {
const receiver = createPolicyReceiver(4);
const seal = createPolicySender(receiver.publicKey, 4);
expect(() => seal('too large')).toThrow();
const large = createPolicySender(receiver.publicKey, 262144)('x'.repeat(262144));
expect(() => receiver.open(large)).toThrow();
const largeReceiver = createPolicyReceiver(262144);
expect(
largeReceiver.open(createPolicySender(largeReceiver.publicKey, 262144)('x'.repeat(262144))),
).toHaveLength(262144);
receiver.dispose();
largeReceiver.dispose();
});
it('replays encrypted inspection frames without putting raw candidates or private keys in the recovery log', async () => {
const receiver = createPolicyReceiver(8192);
const seal = createPolicySender(receiver.publicKey, 8192);
const log = createMemoryRecoveryLog(32768);
const socket = new RecoverySocket({
log,
maxFrameBytes: 8192,
maxBufferedBytes: 32768,
onDisconnect: () => undefined,
onFailure: (error) => {
throw error;
},
});
const payload = seal(JSON.stringify(request));
try {
socket.send(
JSON.stringify({
type: 'call',
id: randomUUID(),
method: 'policy.providerText',
data: payload,
}),
);
await socket.flush();
const entries = await log.read(0);
expect(JSON.stringify(entries)).not.toContain(request.content);
expect(JSON.stringify(entries)).not.toContain('privateKey');
const wire = Object.assign(new EventEmitter(), {
readyState: 1,
bufferedAmount: 0,
send: jest.fn(),
close: jest.fn(),
terminate: jest.fn(),
});
socket.attach(wire as unknown as WebSocket, randomUUID(), 0);
await socket.flush();
const published = String(wire.send.mock.calls[0][0]);
expect(published).not.toContain(request.content);
const replay = JSON.parse(published.slice(published.indexOf('\n') + 1));
expect(JSON.parse(receiver.open(replay.data))).toEqual(request);
expect(replay.data).toEqual(payload);
} finally {
receiver.dispose();
socket.terminate();
}
});

View file

@ -0,0 +1,93 @@
import { z } from 'zod';
import {
createHostProviderTextProtection,
serializeProviderTextProtectionError,
deserializeProviderTextProtectionError,
ProviderTextProtectionError,
} from '@librechat/agents';
import type { HostProviderTextRequest } from '@librechat/agents';
import type { RemoteSdkHostServices, RemoteSdkStart, RemoteSdkLimits } from './types';
import type { SdkAgentIdentity } from './identity';
import type { SdkRpc } from './peer';
import { createPolicyReceiver, createPolicySender } from './sealed';
export const policyDescriptorSchema = z
.object({
version: z.literal(1),
publicKey: z.string().length(60),
limits: z
.object({
version: z.literal(1),
timeoutMs: z.number().int().positive().max(2_147_483_647),
maxAttemptBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
maxBufferedBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
})
.strict(),
})
.strict();
/** Only sanitized failures and approved canonical text enter the peer's reply/logging path. */
export function createHostPolicyChannel(
providerText: NonNullable<RemoteSdkHostServices['providerText']>,
limits: RemoteSdkLimits,
) {
const receiver = createPolicyReceiver(limits.maxFrameBytes);
return {
descriptor: {
version: 1 as const,
publicKey: receiver.publicKey,
limits: providerText.descriptor,
},
dispose: receiver.dispose,
inspect: async (data: unknown, signal?: AbortSignal) => {
try {
let request: HostProviderTextRequest;
try {
request = JSON.parse(receiver.open(data)) as HostProviderTextRequest;
} catch {
throw new ProviderTextProtectionError('incompatible');
}
const content = await providerText.service.inspect(request, signal);
return { version: 1 as const, ok: true as const, content };
} catch (error) {
return serializeProviderTextProtectionError(error);
}
},
};
}
export function createWorkerProviderTextPolicy(options: {
descriptor: NonNullable<RemoteSdkStart['providerText']>;
identity: Readonly<SdkAgentIdentity>;
peer: { call: SdkRpc };
limits: RemoteSdkLimits;
}) {
const descriptor = policyDescriptorSchema.parse(options.descriptor);
const seal = createPolicySender(descriptor.publicKey, options.limits.maxFrameBytes);
return createHostProviderTextProtection({
identity: options.identity,
descriptor: descriptor.limits,
service: {
version: 1,
inspect: async (request, signal) => {
let payload: ReturnType<typeof seal>;
try {
payload = seal(JSON.stringify(request));
} catch {
throw new ProviderTextProtectionError('overflow');
}
const result = await options.peer.call(
'policy.providerText',
payload,
options.limits.maxRunMs,
signal,
);
const success = z
.object({ version: z.literal(1), ok: z.literal(true), content: z.string() })
.safeParse(result);
if (!success.success) throw deserializeProviderTextProtectionError(result);
return success.data.content;
},
},
});
}

View file

@ -6,6 +6,8 @@ import { setTimeout as delay } from 'node:timers/promises';
import { FakeChatModel as TestModel } from '@langchain/core/utils/testing';
import { HumanMessage, AIMessageChunk } from '@librechat/agents/langchain/messages';
import {
createHostProviderTextService,
ProviderTextAdmission,
Run,
Providers,
FakeChatModel,
@ -104,6 +106,12 @@ async function fixture(makeRun = factory, ownerId?: string) {
maxBatchFrames: 64,
maxBatchBytes: 1048576,
});
const journalEntries: string[] = [];
const append = journal.append.bind(journal);
journal.append = (session, lease, id, payloads, terminal) => {
journalEntries.push(...payloads);
return append(session, lease, id, payloads, terminal);
};
const sessionScopes = new Map<string, string>();
const read = journal.read.bind(journal);
journal.read = (session, after, count) => {
@ -162,6 +170,7 @@ async function fixture(makeRun = factory, ownerId?: string) {
return false;
},
createRun,
journalEntries,
errors,
connections: () => connections,
drop: () => {
@ -789,3 +798,61 @@ it('does not publish a session admitted concurrently with shutdown', async () =>
release();
await expect(admission).rejects.toThrow('closed');
});
it('recovers a policy reply after a wire outage without repeating inspection or journaling raw output', async () => {
const raw = 'PRIVATE-PROVIDER-CANDIDATE';
const runtime = await fixture(async (input) => {
const run = await factory(input);
run.Graph!.overrideModel = new FakeChatModel({ responses: [raw], sleep: 1 });
return run;
});
const admission = new ProviderTextAdmission({
maxConcurrentInspections: 1,
maxBufferedBytes: 16384,
});
const inspect = jest.fn(async () => {
runtime.drop();
await delay(50);
return {
version: 1 as const,
ok: true as const,
value: { content: 'approved prose', replacements: 1, categories: [] },
};
});
const providerText = createHostProviderTextService({
identity,
admission,
inspectionTimeoutMs: 2000,
policy: {
version: 1,
timeoutMs: 10000,
maxAttemptBytes: 8192,
maxBufferedBytes: 16384,
classify: () => 'prose',
inspect,
},
});
try {
const run = await createRemoteSdkRun({
config: hostConfig(async () => undefined),
identity,
remote: runtime.remote,
hostServices: { providerText },
});
const content = await run.processStream(
{ messages: [new HumanMessage('go')] },
{ version: 'v2', configurable: { thread_id: identity.conversationId } },
);
expect(JSON.stringify(content)).toContain('approved prose');
expect(JSON.stringify(run.getRunMessages())).not.toContain(raw);
expect(runtime.connections()).toBeGreaterThan(1);
expect(runtime.createRun).toHaveBeenCalledTimes(1);
expect(inspect).toHaveBeenCalledTimes(1);
expect(runtime.journalEntries.join('')).toContain('policy.providerText');
expect(runtime.journalEntries.join('')).not.toContain(raw);
expect(runtime.errors).toEqual([]);
expect(admission.snapshot().inspections).toBe(0);
} finally {
await runtime.close();
}
});

View file

@ -0,0 +1,118 @@
import { z } from 'zod';
import {
createPublicKey,
generateKeyPairSync,
diffieHellman,
hkdfSync,
randomBytes,
createCipheriv,
createDecipheriv,
} from 'node:crypto';
import type { KeyObject } from 'node:crypto';
const context = Buffer.from('librechat-sdk-provider-text/v1');
const base64 = z.string().regex(/^[A-Za-z0-9+/]*={0,2}$/);
const publicKeySchema = base64.length(60);
const envelopeSchema = z
.object({
version: z.literal(1),
publicKey: publicKeySchema,
nonce: base64.length(16),
tag: base64.length(24),
ciphertext: base64,
})
.strict();
type Envelope = z.infer<typeof envelopeSchema>;
function publicKey(value: string): KeyObject {
const key = createPublicKey({
key: Buffer.from(publicKeySchema.parse(value), 'base64'),
format: 'der',
type: 'spki',
});
if (key.asymmetricKeyType !== 'x25519') throw new Error('Invalid SDK policy key');
return key;
}
function deriveKey(privateKey: KeyObject, peerKey: KeyObject, nonce: Buffer): Buffer {
const secret = diffieHellman({ privateKey, publicKey: peerKey });
try {
return Buffer.from(hkdfSync('sha256', secret, nonce, context, 32));
} finally {
secret.fill(0);
}
}
/** Per-run private key stays on the host; recovery journals receive ciphertext and public keys only. */
export function createPolicyReceiver(maxBytes: number): {
publicKey: string;
open(envelope: unknown): string;
dispose(): void;
} {
const pair = generateKeyPairSync('x25519');
let privateKey: KeyObject | undefined = pair.privateKey;
return {
publicKey: pair.publicKey.export({ format: 'der', type: 'spki' }).toString('base64'),
open: (input) => {
if (!privateKey) throw new Error('SDK policy receiver closed');
const envelope = envelopeSchema.parse(input);
if (envelope.ciphertext.length > Math.ceil(maxBytes / 3) * 4)
throw new Error('SDK policy payload exceeds limit');
const nonce = Buffer.from(envelope.nonce, 'base64');
const key = deriveKey(privateKey, publicKey(envelope.publicKey), nonce);
try {
const decipher = createDecipheriv('aes-256-gcm', key, nonce);
decipher.setAAD(context);
decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
const ciphertext = Buffer.from(envelope.ciphertext, 'base64');
if (ciphertext.length > maxBytes) throw new Error('SDK policy payload exceeds limit');
const pending = decipher.update(ciphertext);
try {
const final = decipher.final();
const plaintext = Buffer.concat([pending, final]);
try {
return plaintext.toString('utf8');
} finally {
plaintext.fill(0);
final.fill(0);
}
} finally {
pending.fill(0);
}
} finally {
key.fill(0);
}
},
dispose: () => {
privateKey = undefined;
},
};
}
/** Encrypt before handing the candidate to a peer, queue, or replay log. */
export function createPolicySender(
receiverKey: string,
maxBytes: number,
): (text: string) => Envelope {
const recipient = publicKey(receiverKey);
return (text) => {
if (Buffer.byteLength(text) > maxBytes) throw new Error('SDK policy payload exceeds limit');
const pair = generateKeyPairSync('x25519');
const nonce = randomBytes(12);
const key = deriveKey(pair.privateKey, recipient, nonce);
try {
const cipher = createCipheriv('aes-256-gcm', key, nonce);
cipher.setAAD(context);
const ciphertext = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
return {
version: 1,
publicKey: pair.publicKey.export({ format: 'der', type: 'spki' }).toString('base64'),
nonce: nonce.toString('base64'),
tag: cipher.getAuthTag().toString('base64'),
ciphertext: ciphertext.toString('base64'),
};
} finally {
key.fill(0);
}
};
}

View file

@ -15,6 +15,7 @@ import type { Server } from 'node:http';
import type { RemoteSdkFactoryInput, RemoteSdkLimits, RemoteSdkStart, SdkRun } from './types';
import type { RuntimeRecoveryOptions } from './recovery/server';
import type { SdkAgentIdentity } from './identity';
import { policyDescriptorSchema, createWorkerProviderTextPolicy } from './policy';
import { createRuntimeRecovery, recoveryClaimSchema } from './recovery/server';
import { remoteSdkLimits, isRemoteSdkSecret } from './types';
import { RECOVERY_HEADER_BYTES } from './recovery/socket';
@ -44,6 +45,7 @@ const claimSchema = z.object({
});
const startSchema = z.object({
transportVersion: z.literal(2),
providerText: policyDescriptorSchema.optional(),
hostTools: z
.array(
z.object({
@ -263,7 +265,8 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
throw new Error('Unexpected runtime frame');
},
onCall: async (method, data) => {
if (method === 'capabilities') return { transportVersion: 2, hostTools: 2 };
if (method === 'capabilities')
return { transportVersion: 2, hostTools: 2, providerText: 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');
@ -336,6 +339,14 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
service: workerTools.service,
})
: undefined;
const providerTextProtection = request.providerText
? createWorkerProviderTextPolicy({
descriptor: request.providerText,
identity,
peer,
limits,
})
: undefined;
const execute = async () => {
await recovered?.begin();
const run = await options.createRun({
@ -347,6 +358,7 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
hooks,
humanInTheLoop: request.humanInTheLoop,
streamLimits: request.streamLimits,
providerTextProtection,
},
compileOptions: request.checkpoint
? { checkpointer: new RemoteSdkCheckpointer(peer.call) }
@ -360,6 +372,11 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
run.Graph?.defaultAgentId !== identity.agentId
)
throw new Error('SDK runtime run identity mismatch');
if (
providerTextProtection &&
run.Graph.providerTextProtection !== providerTextProtection
)
throw new Error('SDK runtime omitted required provider protection');
if (hostTools) {
const names = new Set(
run.Graph.agentContexts

View file

@ -1,4 +1,6 @@
import type {
createHostProviderTextService,
HostProviderTextDescriptor,
HostToolDescriptor,
HostToolBindings,
Run,
@ -51,8 +53,14 @@ 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];
/** Explicit host-owned capabilities; never reconstructed from worker claims or YAML. */
export interface RemoteSdkHostServices {
providerText?: ReturnType<typeof createHostProviderTextService>;
}
export interface RemoteSdkStart {
transportVersion: 2;
providerText?: { version: 1; publicKey: string; limits: HostProviderTextDescriptor };
hostTools?: HostToolDescriptor[];
operation: 'start' | 'resume';
input: IState;
@ -89,7 +97,15 @@ 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'>;
config: Pick<
RunConfig,
| 'runId'
| 'customHandlers'
| 'hooks'
| 'humanInTheLoop'
| 'streamLimits'
| 'providerTextProtection'
>;
compileOptions: NonNullable<RunConfig['graphConfig']['compileOptions']>;
signal: AbortSignal;
agent: RemoteSdkStart['agent'];

View file

@ -3,6 +3,7 @@ export { createRemoteSdkRun } from './agents/remoteSdk/client';
export type { RemoteSdkServerOptions } from './agents/remoteSdk/server';
export type { SdkAgentIdentity } from './agents/remoteSdk/identity';
export type {
RemoteSdkHostServices,
RemoteSdkOptions,
RemoteSdkResumeState,
RemoteSdkFactoryInput,