🛠️ feat: Add Slack Gateway Transport Adapters (#17616)

* 🛠️ feat: Add Slack Gateway Transport Adapters

* fix: Share Gateway Execution Wire Contracts and Preserve Stop Scope

* fix: Align Gateway Transport and Installation Contracts

* fix: Centralize Gateway Policy and Durable Stop Observations

* docs: Clarify Transport Adapter and Runtime Ownership

* fix: Separate Stop Event Identity From Execution Authority

* build: align gateway lock with current workspace toolchain

* 🛠️ fix: Cache Gateway Dependencies Across Shared CI Jobs
This commit is contained in:
Dustin Healy 2026-11-10 21:04:05 -08:00 • committed by GitHub
parent 1081a92f02
commit 5081850280
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
43 changed files with 4399 additions and 109 deletions

52
.github/workflows/channel-gateway.yml vendored Normal file
View file

@ -0,0 +1,52 @@
name: Channel Gateway
on:
pull_request:
paths:
- 'packages/channel-gateway/**'
- 'packages/data-provider/**'
- 'package.json'
- 'package-lock.json'
- 'scripts/typecheck.mts'
- '.github/workflows/channel-gateway.yml'
push:
branches: [dev]
paths:
- 'packages/channel-gateway/**'
- 'packages/data-provider/**'
- 'package.json'
- 'package-lock.json'
- 'scripts/typecheck.mts'
- '.github/workflows/channel-gateway.yml'
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
gateway:
runs-on: ubuntu-latest
timeout-minutes: 15
env:
SCARF_ANALYTICS: 'false'
HUSKY: '0'
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: '24.22.1'
cache: npm
- name: Install gateway and shared contracts
run: npm ci --ignore-scripts --no-audit --workspace @librechat/channel-gateway --workspace librechat-data-provider --include-workspace-root=false
- name: Build shared contracts
run: npm run build --workspace librechat-data-provider
- name: Typecheck gateway
run: npm run typecheck --workspace @librechat/channel-gateway
- name: Test gateway
run: npm run test:ci --workspace @librechat/channel-gateway
- name: Build gateway
run: npm run build --workspace @librechat/channel-gateway

View file

@ -117,6 +117,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: node-modules-e2e-${{ runner.os }}-24.22.1-${{ hashFiles('package-lock.json') }}

View file

@ -75,6 +75,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: node-modules-e2e-${{ runner.os }}-24.22.1-${{ hashFiles('package-lock.json') }}
- name: Install dependencies
@ -94,6 +95,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: ${{ steps.cache-node-modules.outputs.cache-primary-key }}
- run: google-chrome --version

View file

@ -51,6 +51,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: node-modules-e2e-${{ runner.os }}-24.22.1-${{ hashFiles('package-lock.json') }}
- name: Install dependencies
@ -72,6 +73,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: ${{ steps.cache-node-modules.outputs.cache-primary-key }}
- name: Install lockfile-pinned Chromium

View file

@ -58,6 +58,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: node-modules-e2e-${{ runner.os }}-24.22.1-${{ hashFiles('package-lock.json') }}

View file

@ -215,6 +215,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: node-modules-e2e-${{ runner.os }}-24.22.1-${{ hashFiles('package-lock.json') }}
@ -472,6 +473,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: node-modules-e2e-${{ runner.os }}-24.22.1-${{ hashFiles('package-lock.json') }}
@ -619,6 +621,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: node-modules-e2e-${{ runner.os }}-24.22.1-${{ hashFiles('package-lock.json') }}

View file

@ -181,6 +181,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: node-modules-e2e-${{ runner.os }}-24.22.1-${{ hashFiles('package-lock.json') }}
@ -203,6 +204,7 @@ jobs:
packages/data-provider/node_modules
packages/data-schemas/node_modules
packages/api/node_modules
packages/channel-gateway/node_modules
api/node_modules
key: ${{ steps.cache-node-modules.outputs.cache-primary-key }}

View file

@ -3,6 +3,7 @@ import userEvent from '@testing-library/user-event';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { act, cleanup, render, screen, waitFor, within } from '@testing-library/react';
import { dataService, request, QueryKeys, MutationKeys } from 'librechat-data-provider';
import { SLACK_CHANNEL_BOT_SCOPES, SLACK_CHANNEL_BOT_EVENTS } from 'librechat-data-provider';
import type { AgentChannel, SlackChannelManifest } from 'librechat-data-provider';
import Channels from '../Channels';
@ -30,11 +31,16 @@ const pending: AgentChannel = {
};
const manifest: SlackChannelManifest = {
display_information: { name: 'Test agent' },
features: { bot_user: { display_name: 'Test agent' } },
oauth_config: { scopes: { bot: ['app_mentions:read'] } },
features: {
bot_user: { display_name: 'test_agent' },
agent_view: { agent_description: 'Test agent' },
app_home: { messages_tab_enabled: true, messages_tab_read_only_enabled: false },
},
oauth_config: { scopes: { bot: [...SLACK_CHANNEL_BOT_SCOPES] } },
settings: {
socket_mode_enabled: true,
event_subscriptions: { bot_events: ['app_mention'] },
event_subscriptions: { bot_events: [...SLACK_CHANNEL_BOT_EVENTS] },
interactivity: { is_enabled: true },
org_deploy_enabled: false,
token_rotation_enabled: false,
},

View file

@ -23,24 +23,18 @@ type DryTask = {
};
const TURBO = resolve(repoRoot, 'node_modules/.bin/turbo');
const rootScripts = (
JSON.parse(readFileSync(resolve(repoRoot, 'package.json'), 'utf8')) as {
scripts: Record<string, string>;
}
).scripts;
/** The workspaces `npm run test:turbo` selects, read from the script itself. */
const SUITES = [...rootScripts['test:turbo'].matchAll(/--filter=(\S+)/g)].map((match) => match[1]);
function plan(
task: string,
env: Record<string, string> = {},
filters: string[] = SUITES,
discoverAll = false,
): Map<string, DryTask> {
const base = { ...process.env };
delete base.VITE_ENABLE_LOGGER;
const useRunner = task === 'test:ci' && !discoverAll;
const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
const result = spawnSync(
TURBO,
['run', task, '--dry=json', ...filters.map((name) => `--filter=${name}`)],
useRunner ? npm : TURBO,
useRunner ? ['run', 'test:turbo', '--', '--dry=json'] : ['run', task, '--dry=json'],
{
cwd: repoRoot,
encoding: 'utf8',
@ -55,6 +49,10 @@ function plan(
return new Map(tasks.map((entry) => [entry.taskId, entry]));
}
function suites(tasks: Map<string, DryTask>): DryTask[] {
return [...tasks.values()].filter((entry) => entry.taskId.endsWith('#test:ci'));
}
function get(tasks: Map<string, DryTask>, id: string): DryTask {
const entry = tasks.get(id);
expect(entry, `${id} is in the plan`).toBeDefined();
@ -68,14 +66,15 @@ test.describe('the parallel test runner', () => {
});
test('the runner covers every workspace with a test suite @scenario:test-turbo-covers-every-workspace-suite', () => {
const everySuite = [...plan('test:ci', {}, []).keys()].filter((id) => id.endsWith('#test:ci'));
expect(SUITES.map((name) => `${name}#test:ci`).sort()).toEqual(everySuite.sort());
const everySuite = suites(plan('test:ci', {}, true)).map((entry) => entry.taskId);
const selected = suites(plan('test:ci')).map((entry) => entry.taskId);
expect(selected.sort()).toEqual(everySuite.sort());
});
test('every suite runs instead of replaying a cached result @scenario:test-turbo-always-runs-every-suite', () => {
const tasks = plan('test:ci');
for (const name of SUITES) {
expect(get(tasks, `${name}#test:ci`).resolvedTaskDefinition.cache, name).toBe(false);
for (const suite of suites(tasks)) {
expect(suite.resolvedTaskDefinition.cache, suite.taskId).toBe(false);
}
});
@ -87,6 +86,9 @@ test.describe('the parallel test runner', () => {
expect(get(tasks, '@librechat/api#test:ci').dependencies).toEqual(
expect.arrayContaining(['librechat-data-provider#build', '@librechat/data-schemas#build']),
);
expect(get(tasks, '@librechat/channel-gateway#test:ci').dependencies).toContain(
'librechat-data-provider#build',
);
expect(get(tasks, '@librechat/backend#test:ci').dependencies).toEqual(
expect.arrayContaining([
'librechat-data-provider#build',
@ -107,11 +109,11 @@ test.describe('the parallel test runner', () => {
'TMPDIR',
];
const tasks = plan('test:ci', Object.fromEntries(names.map((name) => [name, '/tmp/x'])));
for (const suite of SUITES) {
const passed = (get(tasks, `${suite}#test:ci`).environmentVariables.passthrough ?? []).map(
(entry) => entry.slice(0, entry.indexOf('=')),
for (const suite of suites(tasks)) {
const passed = (suite.environmentVariables.passthrough ?? []).map((entry) =>
entry.slice(0, entry.indexOf('=')),
);
expect(passed, suite).toEqual(expect.arrayContaining(names));
expect(passed, suite.taskId).toEqual(expect.arrayContaining(names));
}
});
});

668
package-lock.json generated
View file

@ -10068,6 +10068,10 @@
"resolved": "api",
"link": true
},
"node_modules/@librechat/channel-gateway": {
"resolved": "packages/channel-gateway",
"link": true
},
"node_modules/@librechat/chat": {
"resolved": "packages/chat",
"link": true
@ -16437,6 +16441,93 @@
"dev": true,
"license": "(Unlicense OR Apache-2.0)"
},
"node_modules/@slack/logger": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/@slack/logger/-/logger-5.0.0.tgz",
"integrity": "sha512-VGXhmmgsAo9shdQYh4tFDndd+7nsgp0Y5h0UPDaUp8K359pBasI6YdkMqFW3mCOxLQkq09qj7o7cq6f3DuXcJQ==",
"license": "MIT",
"dependencies": {
"@types/node": ">=20"
},
"engines": {
"node": ">= 20",
"npm": ">=9.6.4"
}
},
"node_modules/@slack/socket-mode": {
"version": "3.1.0",
"resolved": "https://registry.npmjs.org/@slack/socket-mode/-/socket-mode-3.1.0.tgz",
"integrity": "sha512-F9T+FKbtsYRKV23X8l6WW1fx7ncqsMufg+HLA4ffHf/MvZSCvPunFw576ekmY0Q03kgTAIByTKDJxnM+wn1okg==",
"license": "MIT",
"dependencies": {
"@slack/logger": "^5.0.0",
"@slack/web-api": "^8.2.0",
"@types/node": ">=20",
"eventemitter3": "^5"
},
"engines": {
"node": ">=20",
"npm": ">=9.6.4"
},
"peerDependencies": {
"undici": "^7.0.0 || ^8.0.0"
}
},
"node_modules/@slack/types": {
"version": "3.2.0",
"resolved": "https://registry.npmjs.org/@slack/types/-/types-3.2.0.tgz",
"integrity": "sha512-IN4gdtlzQt8UJoj+1v+qAHeR4TxHO0KMlIs841SFfDQAcFFnsrWaGsEAE4goxVt8O/JOAFaGGdrFTzhNBop/Fg==",
"license": "MIT",
"engines": {
"node": ">= 20",
"npm": ">=9.6.4"
}
},
"node_modules/@slack/web-api": {
"version": "8.2.0",
"resolved": "https://registry.npmjs.org/@slack/web-api/-/web-api-8.2.0.tgz",
"integrity": "sha512-bIW8/8BLD/HLuHLIA2LfA7AhSokzui4swCbMJuwoRJxn/kzHVla6YEKLvN1nCFHK/DfX7g+4Wj3ess/ZSh/tWQ==",
"license": "MIT",
"dependencies": {
"@slack/logger": "^5.0.0",
"@slack/types": "^3.2.0",
"@types/node": ">=20",
"@types/retry": "0.12.5",
"eventemitter3": "^5.0.1",
"p-queue": "^6.6.2",
"p-retry": "^4.6.2",
"retry": "^0.13.1"
},
"engines": {
"node": ">= 20",
"npm": ">=9.6.4"
}
},
"node_modules/@slack/web-api/node_modules/@types/retry": {
"version": "0.12.5",
"resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.5.tgz",
"integrity": "sha512-3xSjTp3v03X/lSQLkczaN9UIEwJMoMCA1+Nb5HfbJEQWogdeQIyVtTvxPXDQjZ5zws8rFQfVfRdz03ARihPJgw==",
"license": "MIT"
},
"node_modules/@slack/web-api/node_modules/p-retry": {
"version": "4.6.2",
"resolved": "https://registry.npmjs.org/p-retry/-/p-retry-4.6.2.tgz",
"integrity": "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==",
"license": "MIT",
"dependencies": {
"@types/retry": "0.12.0",
"retry": "^0.13.1"
},
"engines": {
"node": ">=8"
}
},
"node_modules/@slack/web-api/node_modules/p-retry/node_modules/@types/retry": {
"version": "0.12.0",
"resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.0.tgz",
"integrity": "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==",
"license": "MIT"
},
"node_modules/@smithy/chunked-blob-reader": {
"version": "5.2.0",
"resolved": "https://registry.npmjs.org/@smithy/chunked-blob-reader/-/chunked-blob-reader-5.2.0.tgz",
@ -38804,19 +38895,6 @@
"integrity": "sha512-cEmp9QeXXRmjj/rVp9oyiqcvyocWab/HaoN4+bwFeZ7QzykJD6L3yD4v12K1x0tHpqRqVpJevN3gW7kyM39Bqg==",
"license": "MIT"
},
"node_modules/string_decoder": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
"integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
"dependencies": {
"safe-buffer": "~5.1.0"
}
},
"node_modules/string_decoder/node_modules/safe-buffer": {
"version": "5.1.2",
"resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
"integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="
},
"node_modules/string-argv": {
"version": "0.3.2",
"resolved": "https://registry.npmjs.org/string-argv/-/string-argv-0.3.2.tgz",
@ -38952,6 +39030,19 @@
"url": "https://github.com/sponsors/ljharb"
}
},
"node_modules/string_decoder": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
"integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
"dependencies": {
"safe-buffer": "~5.1.0"
}
},
"node_modules/string_decoder/node_modules/safe-buffer": {
"version": "5.1.2",
"resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
"integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g=="
},
"node_modules/stringify-entities": {
"version": "4.0.4",
"resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz",
@ -42740,6 +42831,179 @@
}
}
},
"packages/channel-gateway": {
"name": "@librechat/channel-gateway",
"version": "0.1.0",
"license": "MIT",
"dependencies": {
"@slack/socket-mode": "3.1.0",
"@slack/types": "3.2.0",
"@slack/web-api": "8.2.0",
"librechat-data-provider": "*",
"prom-client": "^15.1.3",
"undici": "^7.30.1",
"zod": "^4.6.7"
},
"devDependencies": {
"@babel/preset-env": "^7.21.5",
"@babel/preset-typescript": "^7.21.0",
"@types/jest": "^29.5.2",
"@types/node": "^24.12.4",
"babel-jest": "^30.2.0",
"jest": "^30.2.0",
"tsdown": "^0.22.2",
"typescript": "^5.8.3"
},
"engines": {
"node": ">=24"
}
},
"packages/channel-gateway/node_modules/get-tsconfig": {
"version": "5.0.0-beta.5",
"resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-5.0.0-beta.5.tgz",
"integrity": "sha512-/6gFNr0N04nob252sTQxyFLi3eKFRqIg1I87YcqAMT1i6SQrSF6KujUEQrtrjMV0H/eejTCltLdDSTEMzHbnsQ==",
"dev": true,
"license": "MIT",
"dependencies": {
"resolve-pkg-maps": "^1.0.0"
},
"engines": {
"node": ">=20.20.0"
},
"funding": {
"url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
}
},
"packages/channel-gateway/node_modules/picomatch": {
"version": "4.0.7",
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz",
"integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=12"
},
"funding": {
"url": "https://github.com/sponsors/jonschlinkert"
}
},
"packages/channel-gateway/node_modules/tsdown": {
"version": "0.22.2",
"resolved": "https://registry.npmjs.org/tsdown/-/tsdown-0.22.2.tgz",
"integrity": "sha512-VX9gsyKXsTnBZjnIM4jsHl9aRv+GfgkE/k1hQslilaBfZMlaw3JuGR+6yhiU0QxWBtOCDnTjwOSoXzgB7Rr50g==",
"dev": true,
"license": "MIT",
"dependencies": {
"ansis": "^4.3.1",
"cac": "^7.0.0",
"defu": "^6.1.7",
"empathic": "^2.0.1",
"hookable": "^6.1.1",
"import-without-cache": "^0.4.0",
"obug": "^2.1.1",
"picomatch": "^4.0.4",
"rolldown": "~1.1.0",
"rolldown-plugin-dts": "^0.25.2",
"tinyexec": "^1.2.4",
"tinyglobby": "^0.2.17",
"tree-kill": "^1.2.2",
"unconfig-core": "^7.5.0",
"semver": "^7.8.1"
},
"bin": {
"tsdown": "dist/run.mjs"
},
"engines": {
"node": "^22.18.0 || >=24.0.0"
},
"funding": {
"url": "https://github.com/sponsors/sxzz"
},
"peerDependencies": {
"@arethetypeswrong/core": "^0.18.1",
"@tsdown/css": "0.22.2",
"@tsdown/exe": "0.22.2",
"@vitejs/devtools": "*",
"publint": "^0.3.8",
"tsx": "*",
"typescript": "^5.0.0 || ^6.0.0",
"unplugin-unused": "^0.5.0",
"unrun": "*"
},
"peerDependenciesMeta": {
"@arethetypeswrong/core": {
"optional": true
},
"@tsdown/css": {
"optional": true
},
"@tsdown/exe": {
"optional": true
},
"@vitejs/devtools": {
"optional": true
},
"publint": {
"optional": true
},
"tsx": {
"optional": true
},
"typescript": {
"optional": true
},
"unplugin-unused": {
"optional": true
},
"unrun": {
"optional": true
}
}
},
"packages/channel-gateway/node_modules/tsdown/node_modules/rolldown-plugin-dts": {
"version": "0.25.2",
"resolved": "https://registry.npmjs.org/rolldown-plugin-dts/-/rolldown-plugin-dts-0.25.2.tgz",
"integrity": "sha512-nMhN/R+vmR8GM45ZW1FWMSjRTSDDn/6w4GTf8RNrEFCBdl8B1kySWrU1ixPtbwzXoRlcO+R/S88VgXuJQwfdDg==",
"dev": true,
"license": "MIT",
"dependencies": {
"dts-resolver": "^3.0.0",
"get-tsconfig": "5.0.0-beta.5",
"obug": "^2.1.1",
"@babel/generator": "8.0.0-rc.6",
"@babel/helper-validator-identifier": "8.0.0-rc.6",
"@babel/parser": "8.0.0-rc.6",
"ast-kit": "^3.0.0-beta.1",
"birpc": "^4.0.0"
},
"engines": {
"node": "^22.18.0 || >=24.0.0"
},
"funding": {
"url": "https://github.com/sponsors/sxzz"
},
"peerDependencies": {
"@typescript/native-preview": ">=7.0.0-dev.20260325.1",
"rolldown": "^1.0.0",
"typescript": "^5.0.0 || ^6.0.0",
"vue-tsc": "~3.2.0",
"@ts-macro/tsc": "^0.3.6"
},
"peerDependenciesMeta": {
"@typescript/native-preview": {
"optional": true
},
"typescript": {
"optional": true
},
"vue-tsc": {
"optional": true
},
"@ts-macro/tsc": {
"optional": true
}
}
},
"packages/chat": {
"name": "@librechat/chat",
"version": "0.1.0",
@ -45635,6 +45899,384 @@
"name": "@librechat/code",
"version": "0.1.0-librechat.a3207a75",
"license": "Apache-2.0"
},
"packages/channel-gateway/node_modules/@babel/generator": {
"version": "8.0.0-rc.6",
"resolved": "https://registry.npmjs.org/@babel/generator/-/generator-8.0.0-rc.6.tgz",
"integrity": "sha512-6mIzgVK8DgEzvIapoQwhXTMnnkuE4STQmVv9H03i/tZ2ml8oev3TRvZJgTenK2Bsq0YWNtzOrFdTyNzCMFtjJQ==",
"dev": true,
"license": "MIT",
"dependencies": {
"@babel/parser": "^8.0.0-rc.6",
"@babel/types": "^8.0.0-rc.6",
"@jridgewell/gen-mapping": "^0.3.12",
"@jridgewell/trace-mapping": "^0.3.28",
"@types/jsesc": "^2.5.0",
"jsesc": "^3.0.2"
},
"engines": {
"node": "^22.18.0 || >=24.11.0"
}
},
"packages/channel-gateway/node_modules/@babel/helper-string-parser": {
"version": "8.0.8",
"resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-8.0.8.tgz",
"integrity": "sha512-fVM+gSuKbdv9cpmyRNh5EvsDHUZCdxQH3FdnFKSkNYHpbsn95bbrxm+ES3MVeQjcqwi2O5ur/DjLfmTQaO60ng==",
"dev": true,
"license": "MIT",
"engines": {
"node": "^22.18.0 || >=24.11.0"
}
},
"packages/channel-gateway/node_modules/@babel/helper-validator-identifier": {
"version": "8.0.0-rc.6",
"resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-8.0.0-rc.6.tgz",
"integrity": "sha512-nVJ+1JcCgntv8d78rRo++o2wuODT0Irknx2BF8Np4Ft2CRgjLqIs4qzSZ8b66yGbBdMWGmZBO9WEZv1hhNiSpg==",
"dev": true,
"license": "MIT",
"engines": {
"node": "^22.18.0 || >=24.11.0"
}
},
"packages/channel-gateway/node_modules/@babel/parser": {
"version": "8.0.0-rc.6",
"resolved": "https://registry.npmjs.org/@babel/parser/-/parser-8.0.0-rc.6.tgz",
"integrity": "sha512-rOS8IpdO7mQELkTPlCsTgPejO0bFuZdEDCGQJouYbYf9e1FLTym7Fei2pEjq8q7MWbX0ravcd7QQYKs1TxOuog==",
"dev": true,
"license": "MIT",
"dependencies": {
"@babel/types": "^8.0.0-rc.6"
},
"bin": {
"parser": "bin/babel-parser.js"
},
"engines": {
"node": "^22.18.0 || >=24.11.0"
}
},
"packages/channel-gateway/node_modules/@babel/types": {
"version": "8.1.0",
"resolved": "https://registry.npmjs.org/@babel/types/-/types-8.1.0.tgz",
"integrity": "sha512-8V8aSTDx012YPmDQF30vrokyxVFdRAU2YBS2VzrnfLAGkP8floVnjckwgFcD0Jrvf6GWMSRdCrYVsk3tyMwZRg==",
"dev": true,
"license": "MIT",
"dependencies": {
"@babel/helper-string-parser": "^8.0.8",
"@babel/helper-validator-identifier": "^8.0.6"
},
"engines": {
"node": "^22.18.0 || >=24.11.0"
}
},
"packages/channel-gateway/node_modules/@babel/types/node_modules/@babel/helper-validator-identifier": {
"version": "8.0.6",
"resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-8.0.6.tgz",
"integrity": "sha512-HYx0YmuchRxRSpnjvcNffnPS8DCauKNmnumIuHG3jnQAVewRA7kfJGwF13ayEpSZs7s4R/oBH4eppuXcAQd5JQ==",
"dev": true,
"license": "MIT",
"engines": {
"node": "^22.18.0 || >=24.11.0"
}
},
"packages/channel-gateway/node_modules/@oxc-project/types": {
"version": "0.139.0",
"resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.139.0.tgz",
"integrity": "sha512-r9gHphtCs+1M7J0pw6Sn/hh/Wpa/iQrOOkrNAlVLF/gHq+/CJmHIWKKUUhdWjcD6CIa8idarspCsASiXCXvFUw==",
"dev": true,
"license": "MIT",
"funding": {
"url": "https://github.com/sponsors/Boshen"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-android-arm64": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.1.5.tgz",
"integrity": "sha512-lZg8fqIv2v7FF237bwMgzGZEJvGL79/s5knJ/i6FmsGF4XXlzccZ4jb+TrFIxtSSxFtIpdsgrPZeMk1I9AFcyQ==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-darwin-arm64": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.1.5.tgz",
"integrity": "sha512-51Bnx9pNiMRKSUNtBfySkNJ9vMU9Hh3I1ozDd6gyPPYzaXCfnptUcEZxXGYFn+ul2dtcMUiqGR1Yai2K10uoTw==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-darwin-x64": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.1.5.tgz",
"integrity": "sha512-Tm+gbfC0aHu1tBA/JvKQh32S0K6YgCHkiAF4/W6xX0K0RmNuc94VeK419dJoE65R5aRxmo+noZQSWrAMF6yb6g==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-freebsd-x64": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.1.5.tgz",
"integrity": "sha512-JMzDKCCXq93YccG5gz3hvOs1oXRKAf0XYpfOS88e+wZrC8Iugj6j68867vrYZkvpDDpKn/KoKORThmchMpF6TA==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"freebsd"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-linux-arm-gnueabihf": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.1.5.tgz",
"integrity": "sha512-uML21j2K5TfPGutKxub+M+nLjZIrWjXQ5Grx4lCe/nimTj9B4L63zHpjXLl4y0L3mcm2htEQIb06oCG/szerNw==",
"cpu": [
"arm"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-linux-arm64-gnu": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.1.5.tgz",
"integrity": "sha512-navSiuTMogvnQoZoM/v+l3ZWo50/NTwSHSzheABx/RCnmUPaKwq9qSo4Br2OYRs21+Fz8uFqITZM3H4opOB0/Q==",
"cpu": [
"arm64"
],
"dev": true,
"libc": [
"glibc"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-linux-arm64-musl": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.1.5.tgz",
"integrity": "sha512-lAryqH7IteztmCXQXk0etKj4wBQ7Gx5S6LjKhsgp9zb8I5bsuvU/2llH1hDQcjsFeqIsovMVN339/8pUDDBXxA==",
"cpu": [
"arm64"
],
"dev": true,
"libc": [
"musl"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-linux-ppc64-gnu": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.1.5.tgz",
"integrity": "sha512-fsK/sNBnxzBlL4O1JNrZakVQxPspqpED5dLtNsZS9oOKmtSpdNIzxH2kkol5HYTWJN47sE20ztMJPxfZ89qGOg==",
"cpu": [
"ppc64"
],
"dev": true,
"libc": [
"glibc"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-linux-s390x-gnu": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.1.5.tgz",
"integrity": "sha512-gLYb4BIadlfTOYT5gO503n8zQjXflgzpD0FcyKh0Mzx3rqCZKnHoJWV9xe1KXUJ5lx2JfcSHr/mhzS0PC/McAA==",
"cpu": [
"s390x"
],
"dev": true,
"libc": [
"glibc"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-linux-x64-gnu": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.1.5.tgz",
"integrity": "sha512-FjcpEKUyJygHgs1o50VYNvkt5+7Le/VEdYt0AkRpkL33MnyQfwr8l5mXwMmfmTbyMPr5vJLC+8/Gd9gXnwU1QQ==",
"cpu": [
"x64"
],
"dev": true,
"libc": [
"glibc"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-linux-x64-musl": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.1.5.tgz",
"integrity": "sha512-Me+PfPI2TMeOQk0gYWfLQZtTktrmzbr8cDboqX83XKc7UrgAi55gF+2dUkWdxd19n55Essp2yeca+O9N5rBxHg==",
"cpu": [
"x64"
],
"dev": true,
"libc": [
"musl"
],
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-openharmony-arm64": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.1.5.tgz",
"integrity": "sha512-yc5WrLzXks6zCQfn9Oxr8pORKyl/pF+QjHmW/Qx3qu0oyrrNC+y2JLTU1E2rcWYAmzlnqngWXHQjy51VzW70Vw==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"openharmony"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-win32-arm64-msvc": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.1.5.tgz",
"integrity": "sha512-gHv82k63z4qpV5+Q1y/12KrK0ltWBukVDI8nZcbT7Tt/ZlOIVwppazneq0F93oDxTo3IgAMEDIoQh3E2n6mVsw==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/@rolldown/binding-win32-x64-msvc": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.1.5.tgz",
"integrity": "sha512-tTZuDBPw85tEN5PQi1pnEBzDy0Z49HtScLAbD5t6hyeU92A95pRWaSMw1GZZi/RwgSgUIl0xrSlXIT/9QzvYSA==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": "^20.19.0 || >=22.12.0"
}
},
"packages/channel-gateway/node_modules/rolldown": {
"version": "1.1.5",
"resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.1.5.tgz",
"integrity": "sha512-t9z29cJjXf/vxQ8dyhCSpt6H6aSwHTk8cT5I3iy6SMXuFpk5mB6PL6XfC8PCwrPTx93udwKUm9HRteAlTGBLiA==",
"dev": true,
"license": "MIT",
"dependencies": {
"@oxc-project/types": "=0.139.0",
"@rolldown/pluginutils": "^1.0.0"
},
"bin": {
"rolldown": "bin/cli.mjs"
},
"engines": {
"node": "^20.19.0 || >=22.12.0"
},
"optionalDependencies": {
"@rolldown/binding-android-arm64": "1.1.5",
"@rolldown/binding-darwin-arm64": "1.1.5",
"@rolldown/binding-darwin-x64": "1.1.5",
"@rolldown/binding-freebsd-x64": "1.1.5",
"@rolldown/binding-linux-arm-gnueabihf": "1.1.5",
"@rolldown/binding-linux-arm64-gnu": "1.1.5",
"@rolldown/binding-linux-arm64-musl": "1.1.5",
"@rolldown/binding-linux-ppc64-gnu": "1.1.5",
"@rolldown/binding-linux-s390x-gnu": "1.1.5",
"@rolldown/binding-linux-x64-gnu": "1.1.5",
"@rolldown/binding-linux-x64-musl": "1.1.5",
"@rolldown/binding-openharmony-arm64": "1.1.5",
"@rolldown/binding-wasm32-wasi": "1.1.5",
"@rolldown/binding-win32-arm64-msvc": "1.1.5",
"@rolldown/binding-win32-x64-msvc": "1.1.5"
}
}
}
}

View file

@ -112,7 +112,7 @@
"test:config": "jest --config config/jest.config.js",
"test:dependencies": "node --test scripts/dependencies.test.mjs",
"test:all": "npm run test:client && npm run test:api && npm run test:packages:api && npm run test:packages:data-provider && npm run test:packages:data-schemas && npm run test:packages:chat",
"test:turbo": "turbo run test:ci --concurrency=2 --filter=@librechat/frontend --filter=@librechat/client --filter=@librechat/backend --filter=@librechat/api --filter=librechat-data-provider --filter=@librechat/data-schemas --filter=@librechat/chat",
"test:turbo": "turbo run test:ci --concurrency=2",
"e2e:update": "npm run e2e:prepare && playwright test --config=e2e/playwright.config.local.ts --update-snapshots",
"e2e:report": "npx playwright show-report e2e/playwright-report",
"lint:fix": "npm run build:client-package && eslint . --fix --pass-on-unpruned-suppressions",

View file

@ -4,13 +4,6 @@ import mongoose from 'mongoose';
import { Readable } from 'node:stream';
import { MongoMemoryReplSet } from 'mongodb-memory-server';
import { createHash, createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
import {
PermissionBits,
Permissions,
PermissionTypes,
FileSources,
channelConfigSchema,
} from 'librechat-data-provider';
import {
createModels,
createMethods,
@ -21,11 +14,23 @@ import {
tenantStorage,
runAsSystem,
} from '@librechat/data-schemas';
import {
PermissionBits,
Permissions,
PermissionTypes,
FileSources,
channelConfigSchema,
CHANNEL_RUN_MAX_JSON_BYTES,
CHANNEL_DELIVERY_PARTS_HARD_MAX,
CHANNEL_DELIVERY_TEXT_MAX_CHARS,
CHANNEL_DELIVERY_PRESENTATION_MAX_BYTES,
} from 'librechat-data-provider';
import type {
ChannelRunAdmission,
ChannelIdentityResult,
ChannelRunSnapshot,
ChannelRunSummary,
ChannelDeliveryPlan,
} from 'librechat-data-provider';
import type { IUser, ChannelRunRecord } from '@librechat/data-schemas';
import type { ChannelResponseCredentialDependencies } from './credentials';
@ -253,6 +258,7 @@ beforeEach(async () => {
app.post('/service/:channelId/runs/claim', runs.claim);
app.post('/service/:channelId/runs/stop-thread', runs.stopThread);
app.post('/service/:channelId/runs/:runId/yield', runs.yieldLease);
app.post('/service/:channelId/runs/:runId/renew', runs.renew);
app.post('/service/:channelId/runs/:runId/advance', runs.advance);
app.post('/service/:channelId/runs/:runId/response/prepare', runs.prepareResponse);
app.post('/service/:channelId/runs/:runId/response/bind', runs.bindResponse);
@ -609,6 +615,30 @@ it.each(['per_user', 'shared'] as const)(
}),
);
it.each([500, 300_000, 300_001])(
'bounds native Stop clock lead of %dms using the service policy',
(lead) =>
scoped(async () => {
await link('U1', users[0]);
const admission = event();
const admitted = await post('runs').send(admission).expect(201);
await post('runs/claim').send({ owner: 'worker' }).expect(200);
fakeNow = Date.now() + 10;
const accepted = lead <= 300_000;
await post('runs/stop-thread')
.send({
actor: admission.actor,
externalThreadKey: admission.externalThreadKey,
externalChannelId: admission.externalChannelId,
eventAt: fakeNow + lead,
})
.expect(accepted ? 202 : 400);
expect(
(await storage.read(tenantId, 'channel', admitted.body.runId))?.cancellationRequested,
).toBe(accepted);
})(),
);
it(
'native Stop resolves only the current actor lane and ignores stale or foreign clicks',
scoped(async () => {
@ -816,6 +846,63 @@ it(
.expect(409);
}),
);
it(
'returns a persisted maximum-part plan through claim and fenced mutation within the shared wire budget',
scoped(async () => {
await link('U1', users[0]);
const admitted = await post('runs').send(event()).expect(201);
const claimed = await post('runs/claim').send({ owner: 'worker-A' }).expect(200);
const fence = claimed.body.fence;
const route = `runs/${admitted.body.runId}`;
await post(`${route}/advance`).send({ fence }).expect(200);
await bindFixtureResponse(
(await storage.read(tenantId, 'channel', admitted.body.runId))!,
'reply-1',
);
await storage.saveSnapshot(
tenantId,
fence,
{ status: 'completed', responseId: 'reply-1', text: 'Answer', elapsedMs: 1 },
Date.now(),
);
const plan: ChannelDeliveryPlan = {
revision: 'plan-1',
rendererVersion: 'test',
parts: Array.from({ length: CHANNEL_DELIVERY_PARTS_HARD_MAX }, (_, i) => ({
operationId: `part-${i}`,
kind: 'message',
required: true,
text: '\u0000'.repeat(CHANNEL_DELIVERY_TEXT_MAX_CHARS),
presentation: {
format: 'slack-blocks-v1',
payload: JSON.stringify({
text: 'x'.repeat(CHANNEL_DELIVERY_PRESENTATION_MAX_BYTES - 1000),
}),
},
})),
};
await storage.savePlan(tenantId, fence, plan, Date.now());
// Delivery leases are reclaimed on expiry; the polling-only yield route does not release them.
fakeNow = claimed.body.leaseExpiresAt + 1;
const lease = await post('runs/claim').send({ owner: 'worker-B' }).expect(200);
expect(lease.body.run.plan.parts).toHaveLength(CHANNEL_DELIVERY_PARTS_HARD_MAX);
expect(lease.body.fence.owner).toBe('worker-B');
for (const bytes of [
Buffer.byteLength(lease.text),
Buffer.byteLength(
(
await post(`${route}/begin`)
.send({ fence: lease.body.fence, operationId: 'part-0' })
.expect(200)
).text,
),
]) {
expect(bytes).toBeGreaterThan(2 * 1024 * 1024);
expect(bytes).toBeLessThan(CHANNEL_RUN_MAX_JSON_BYTES);
}
}),
);
function post(path: string) {
return request(app)
.post(`/service/channel/${path}`)
@ -1660,3 +1747,65 @@ it(
).toBe(false);
}),
);
it(
'returns distinct claim, renewal and pre-credential cancellation contracts through real handlers',
scoped(async () => {
await link('U1', users[0]);
const admitted = await post('runs').send(event()).expect(201);
const claimed = await post('runs/claim').send({ owner: 'worker' }).expect(200);
expect(Object.keys(claimed.body).sort()).toEqual(['fence', 'leaseExpiresAt', 'run']);
const base = `runs/${admitted.body.runId}`;
const renewed = await post(`${base}/renew`).send({ fence: claimed.body.fence }).expect(200);
expect(Object.keys(renewed.body).sort()).toEqual(['fence', 'leaseExpiresAt']);
expect(renewed.body.fence).toEqual(claimed.body.fence);
await post(`${base}/cancel`)
.send({ actor: event().actor, revision: 'revision-1', externalChannelId: 'C1' })
.expect(202);
const prepared = await post(`${base}/response/prepare`)
.send({ fence: claimed.body.fence })
.expect(200);
expect(Object.keys(prepared.body)).toEqual(['settled']);
expect(prepared.body.settled).toMatchObject({
runId: admitted.body.runId,
state: 'delivering',
cancellationRequested: true,
snapshot: { status: 'cancelled' },
});
expect(responseCredential).not.toHaveBeenCalled();
expect(invoked).toHaveLength(0);
}),
);
it.each([0, 1])('keeps Stop retries bound across relinking to account %i', (target) =>
scoped(async () => {
const linked = await link('U1', users[0]);
fakeNow = Date.now() + 1000;
const admission = event();
await post('runs').send(admission).expect(201);
await post('runs/claim').send({ owner: 'first-worker' }).expect(200);
const stop = {
actor: admission.actor,
externalThreadKey: admission.externalThreadKey,
externalChannelId: admission.externalChannelId,
eventAt: fakeNow + 60000,
};
await post('runs/stop-thread').send(stop).expect(202);
value(
await authority.identity.revoke(
{ tenantId, userId: users[0].id, accountLabel: 'A' },
linked.linkId,
linked.revision,
),
);
await link('U1', users[target]);
fakeNow += 1000;
const second = await post('runs').send(event('U1', 'after-relink')).expect(201);
const claimed = await post('runs/claim').send({ owner: 'second-worker' }).expect(200);
expect(claimed.body.run.runId).toBe(second.body.runId);
await post('runs/stop-thread').send(stop).expect(200, { cancellationRequested: false });
expect(
(await storage.read(tenantId, 'channel', second.body.runId))?.cancellationRequested,
).toBe(false);
})(),
);

View file

@ -2,12 +2,46 @@ import { buildSlackChannelManifest } from './manifest';
const binding = { name: 'Test Agent', tenantId: 'tenant-a', channelId: 'channel-a' };
it.each(['socket_mode', 'webhook'] as const)(
'installs the DM and native Stop capabilities consumed by the %s gateway',
(transport) => {
const manifest = buildSlackChannelManifest({
...binding,
transport,
gatewayUrl: 'https://gateway.example',
});
expect(manifest.oauth_config.scopes.bot).toContain('im:history');
expect(manifest.settings.event_subscriptions.bot_events).toEqual(
expect.arrayContaining(['message.im', 'agent_session_stopped']),
);
expect(manifest.features).toMatchObject({
agent_view: { agent_description: 'Test Agent' },
app_home: { messages_tab_enabled: true, messages_tab_read_only_enabled: false },
});
},
);
it('produces valid Slack display and bot names for long, Unicode and punctuated Agent titles', () => {
for (const name of ['An Agent With Spaces!', '界'.repeat(100), 'x'.repeat(100), ' ']) {
const manifest = buildSlackChannelManifest({ ...binding, name });
expect([...manifest.display_information.name].length).toBeGreaterThan(0);
expect([...manifest.display_information.name].length).toBeLessThanOrEqual(35);
expect(manifest.features.bot_user.display_name).toMatch(/^[a-z0-9._-]{1,80}$/);
}
});
it('declares only bot capabilities used by channels, without public ingress in Socket Mode', () => {
const manifest = buildSlackChannelManifest(binding);
expect(manifest.settings.socket_mode_enabled).toBe(true);
expect(manifest.settings.interactivity).toEqual({ is_enabled: true });
expect(manifest.settings.event_subscriptions).toEqual({
bot_events: ['app_mention', 'reaction_added', 'reaction_removed'],
bot_events: [
'app_mention',
'message.im',
'agent_session_stopped',
'reaction_added',
'reaction_removed',
],
});
expect(manifest.oauth_config.scopes.bot).toEqual([
'app_mentions:read',
@ -16,6 +50,7 @@ it('declares only bot capabilities used by channels, without public ingress in S
'reactions:write',
'files:write',
'im:write',
'im:history',
]);
expect(JSON.stringify(manifest)).not.toMatch(/users:read|channels:history|user_scope/);
});

View file

@ -1,15 +1,10 @@
export interface SlackChannelManifest {
display_information: { name: string };
features: { bot_user: { display_name: string } };
oauth_config: { scopes: { bot: string[] } };
settings: {
socket_mode_enabled: boolean;
event_subscriptions: { bot_events: string[]; request_url?: string };
interactivity: { is_enabled: boolean; request_url?: string };
org_deploy_enabled: false;
token_rotation_enabled: false;
};
}
import {
DEFAULT_CHANNEL_GATEWAY_POLICY,
SLACK_CHANNEL_BOT_SCOPES,
SLACK_CHANNEL_BOT_EVENTS,
} from 'librechat-data-provider';
import type { SlackChannelManifest } from 'librechat-data-provider';
export type { SlackChannelManifest } from 'librechat-data-provider';
/** Declarative installation requirements only; generating a manifest grants no Slack access. */
export function buildSlackChannelManifest(input: {
@ -19,7 +14,7 @@ export function buildSlackChannelManifest(input: {
transport?: 'socket_mode' | 'webhook';
gatewayUrl?: string;
}): SlackChannelManifest {
const socket = input.transport !== 'webhook';
const socket = (input.transport ?? DEFAULT_CHANNEL_GATEWAY_POLICY.transport) === 'socket_mode';
let gateway: string | undefined;
if (!socket) {
const url = new URL(input.gatewayUrl ?? '');
@ -29,26 +24,30 @@ export function buildSlackChannelManifest(input: {
gateway = url.toString().replace(/\/+$/, '');
}
const binding = `${encodeURIComponent(input.tenantId)}/${encodeURIComponent(input.channelId)}`;
const name = input.name.slice(0, 80);
const title = input.name.trim() || 'LibreChat';
const name = [...title].slice(0, 35).join('');
const botName =
title
.toLowerCase()
.replace(/[^a-z0-9._-]+/g, '_')
.replace(/^_+|_+$/g, '')
.slice(0, 80) || 'librechat_agent';
return {
display_information: { name },
features: { bot_user: { display_name: name } },
features: {
bot_user: { display_name: botName },
agent_view: { agent_description: [...title].slice(0, 300).join('') },
app_home: { messages_tab_enabled: true, messages_tab_read_only_enabled: false },
},
oauth_config: {
scopes: {
bot: [
'app_mentions:read',
'chat:write',
'reactions:read',
'reactions:write',
'files:write',
'im:write',
],
bot: [...SLACK_CHANNEL_BOT_SCOPES],
},
},
settings: {
socket_mode_enabled: socket,
event_subscriptions: {
bot_events: ['app_mention', 'reaction_added', 'reaction_removed'],
bot_events: [...SLACK_CHANNEL_BOT_EVENTS],
...(!socket ? { request_url: `${gateway}/slack/events/${binding}` } : {}),
},
interactivity: {

View file

@ -1,7 +1,15 @@
import { z } from 'zod';
import { ChannelRunConflict } from '@librechat/data-schemas';
import { responseReviewDecisionSchema } from 'librechat-data-provider';
import {
responseReviewDecisionSchema,
CHANNEL_DELIVERY_PARTS_HARD_MAX,
CHANNEL_DELIVERY_TEXT_MAX_CHARS,
CHANNEL_DELIVERY_PRESENTATION_MAX_BYTES,
} from 'librechat-data-provider';
import type {
ChannelRunLease,
ChannelRunLeaseRenewal,
ChannelResponsePreparation,
ChannelRunPrincipal,
ChannelRunAdmission,
ChannelRunView,
@ -77,8 +85,10 @@ const presentationSchema = z
format: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
payload: z
.string()
.max(64_000)
.refine((value) => Buffer.byteLength(value, 'utf8') <= 64_000)
.max(CHANNEL_DELIVERY_PRESENTATION_MAX_BYTES)
.refine(
(value) => Buffer.byteLength(value, 'utf8') <= CHANNEL_DELIVERY_PRESENTATION_MAX_BYTES,
)
.refine((value) => {
try {
const parsed: unknown = JSON.parse(value);
@ -103,7 +113,7 @@ const planBody = z
operationId: id,
kind: z.enum(['message', 'artifact']),
required: z.boolean(),
text: z.string().max(40_000),
text: z.string().max(CHANNEL_DELIVERY_TEXT_MAX_CHARS),
presentation: presentationSchema.optional(),
artifactId: id.optional(),
traceUrl: z.string().url().optional(),
@ -113,7 +123,7 @@ const planBody = z
.refine((part) => !part.traceUrl || (part.kind === 'message' && !part.required)),
)
.min(1)
.max(100),
.max(CHANNEL_DELIVERY_PARTS_HARD_MAX),
})
.strict(),
})
@ -317,10 +327,10 @@ export function createChannelRunHandlers(deps: ChannelRunDependencies): ChannelR
await deps.storage.finishAuthorityLost(run.tenantId, fence, now());
}
const guarded = (handler: Parameters<ChannelServiceGuard>[0]) =>
deps.guard(async (req, res, channel) => {
deps.guard(async (req, res, channel, config) => {
res.set('Cache-Control', 'no-store');
try {
await handler(req, res, channel);
await handler(req, res, channel, config);
} catch (error) {
if (error instanceof ChannelDisclosureError) {
res
@ -415,13 +425,18 @@ export function createChannelRunHandlers(deps: ChannelRunDependencies): ChannelR
return run;
}
return {
stopThread: guarded(async (req, res, channel) => {
stopThread: guarded(async (req, res, channel, config) => {
const observedAt = now();
const parsed = z
.object({
actor: actorSchema,
externalThreadKey: id,
externalChannelId: id,
eventAt: z.number().int().positive().max(now()),
eventAt: z
.number()
.int()
.positive()
.max(observedAt + config.signatureToleranceSeconds * 1000),
})
.strict()
.safeParse(req.body);
@ -446,14 +461,15 @@ export function createChannelRunHandlers(deps: ChannelRunDependencies): ChannelR
principal,
admission: { actor, externalThreadKey, externalChannelId },
};
const run = await deps.storage.readActiveThread(scope, eventAt);
const observation = await deps.storage.observeThreadStop(scope, eventAt, observedAt);
const run = observation?.run;
if (!run || !(await hasAuthority(channel, run))) {
res.json({ cancellationRequested: false });
return;
}
const accepted = await deps.storage.requestCancel(scope, run.runId, {
epoch: run.leaseEpoch,
before: eventAt,
before: observation!.before,
});
res.status(accepted ? 202 : 200).json({ cancellationRequested: accepted });
}),
@ -600,9 +616,9 @@ export function createChannelRunHandlers(deps: ChannelRunDependencies): ChannelR
}
res.json({
run: await presentRun(channel, run),
fence: { runId: run.runId, owner: run.leaseOwner, epoch: run.leaseEpoch },
fence: { runId: run.runId, owner: run.leaseOwner!, epoch: run.leaseEpoch },
leaseExpiresAt: run.leaseExpiresAt,
});
} satisfies ChannelRunLease);
}),
renew: guarded(async (req, res, channel) => {
const parsed = fenceBody.safeParse(req.body);
@ -614,7 +630,10 @@ export function createChannelRunHandlers(deps: ChannelRunDependencies): ChannelR
res.status(409).json({ error: 'stale_fence' });
return;
}
res.json({ fence: binding.fence, leaseExpiresAt: at + leaseMs });
res.json({
fence: binding.fence,
leaseExpiresAt: at + leaseMs,
} satisfies ChannelRunLeaseRenewal);
}),
yieldLease: guarded(async (req, res, channel) => {
const parsed = fenceBody.safeParse(req.body);
@ -648,7 +667,9 @@ export function createChannelRunHandlers(deps: ChannelRunDependencies): ChannelR
binding.fence,
now(),
);
res.json({ settled: await presentRun(channel, settled) });
res.json({
settled: await presentRun(channel, settled),
} satisfies ChannelResponsePreparation);
return;
}
if (run.cancellationRequested && !run.execution.responseId) {
@ -685,7 +706,7 @@ export function createChannelRunHandlers(deps: ChannelRunDependencies): ChannelR
? {}
: { previous_response_id: run.execution!.parentMessageId }),
},
});
} satisfies ChannelResponsePreparation);
}),
bindResponse: guarded(async (req, res, channel) => {
const parsed = z.object({ fence: fenceSchema, responseId: id }).strict().safeParse(req.body);

View file

@ -342,7 +342,13 @@ it.each([undefined, '', ' '])(
);
it('uses one policy snapshot and supplies the verified webhook credentials only to the authenticated bundle', async () => {
const config = jest.fn(async () => ({ enabled: true, transport: 'webhook' as const }));
const config = jest.fn(async () => ({
enabled: true,
transport: 'webhook' as const,
nativeSessions: true,
lifecycleReactions: true,
signatureToleranceSeconds: 60,
}));
deps.config = config;
const id = await createChannel();
config.mockClear();
@ -365,6 +371,14 @@ it('uses one policy snapshot and supplies the verified webhook credentials only
.expect(200);
expect(config).toHaveBeenCalledTimes(1);
expect(result.body.credentials.signingSecret).toBe('private-signing-secret');
expect(result.body.gateway).toEqual({
version: 1,
transport: 'webhook',
nativeSessions: true,
lifecycleReactions: true,
signatureToleranceSeconds: 60,
});
expect(result.body.gateway).not.toHaveProperty('enabled');
});
it('fails closed if an existing socket-mode channel is switched to webhook transport without a secret', async () => {

View file

@ -2,7 +2,13 @@ import { z } from 'zod';
import { nanoid } from 'nanoid';
import { timingSafeEqual } from 'node:crypto';
import { runAsSystem, tenantStorage } from '@librechat/data-schemas';
import {
channelConfigSchema,
channelGatewayWirePolicySchema,
CHANNEL_GATEWAY_POLICY_VERSION,
} from 'librechat-data-provider';
import type { AgentChannelMethods, AgentChannelRecord } from '@librechat/data-schemas';
import type { ChannelConfig, ChannelServiceBundle } from 'librechat-data-provider';
import type { Request, Response, RequestHandler } from 'express';
import type { ChannelServiceGuard } from './types';
import { encryptCredential, decryptCredential } from '~/crypto/credentials';
@ -21,12 +27,6 @@ function authenticatedUserId(req: Request): string | undefined {
return undefined;
}
interface ChannelConfig {
enabled: boolean;
gatewayUrl?: string;
transport?: 'socket_mode' | 'webhook';
}
function validSigningSecret(config: ChannelConfig, secret?: string): boolean {
return config.transport !== 'webhook' || Boolean(secret?.trim());
}
@ -34,7 +34,10 @@ function validSigningSecret(config: ChannelConfig, secret?: string): boolean {
export interface ChannelDependencies {
db: AgentChannelMethods;
serviceToken: () => string | undefined;
config: (req: Request, channel?: AgentChannelRecord) => Promise<ChannelConfig | undefined>;
config: (
req: Request,
channel?: AgentChannelRecord,
) => Promise<Partial<ChannelConfig> | undefined>;
getAgent: (agentId: string) => Promise<{ id: string; name?: string | null } | null>;
deleteApiKey: (id: string, userId: string) => Promise<boolean>;
verifySlackToken: (token: string) => Promise<SlackIdentity | null>;
@ -154,12 +157,12 @@ export function createChannelHandlers(deps: ChannelDependencies): {
): RequestHandler =>
async (req, res) => {
try {
const config = await deps.config(req);
if (!config?.enabled) {
const loaded = await deps.config(req);
if (!loaded?.enabled) {
res.status(404).json({ error: 'channels_disabled' });
return;
}
await handler(req, res, config);
await handler(req, res, channelConfigSchema.parse(loaded));
} catch (error) {
deps.logError(getSafeErrorMetadata(error));
res.status(503).json({ error: 'channel_operation_failed' });
@ -378,12 +381,12 @@ export function createChannelHandlers(deps: ChannelDependencies): {
return;
}
await tenantStorage.run({ tenantId: channel.tenantId || undefined }, async () => {
const config = await deps.config(req, channel);
if (!config?.enabled) {
const loaded = await deps.config(req, channel);
if (!loaded?.enabled) {
res.status(404).json({ error: 'channels_disabled' });
return;
}
await handler(req, res, channel, config);
await handler(req, res, channel, channelConfigSchema.parse(loaded));
});
} catch (error) {
deps.logError(getSafeErrorMetadata(error));
@ -392,11 +395,18 @@ export function createChannelHandlers(deps: ChannelDependencies): {
};
const service: ChannelServiceGuard = (handler) =>
serviceWithConfig((req, res, channel) => handler(req, res, channel));
serviceWithConfig((req, res, channel, config) => handler(req, res, channel, config));
const bundle = serviceWithConfig(async (_req, res, channel, config) => {
const agent = await deps.getAgent(channel.agentId);
if (!agent || !channel.encryptedBotToken) {
const slack = channel.slack;
if (
!agent ||
!channel.encryptedBotToken ||
!slack?.teamId ||
!slack.appId ||
!slack.botUserId
) {
res.status(404).json({ error: 'channel_not_found' });
return;
}
@ -412,10 +422,18 @@ export function createChannelHandlers(deps: ChannelDependencies): {
return;
}
res.json({
channel: publicChannel(channel),
channel: {
...publicChannel(channel),
revision: channel.revision ?? channel.channelId,
slack,
},
credentials: { botToken, signingSecret },
agent: { id: agent.id, name: agent.name ?? 'Agent' },
});
gateway: channelGatewayWirePolicySchema.parse({
version: CHANNEL_GATEWAY_POLICY_VERSION,
...config,
}),
} satisfies ChannelServiceBundle);
});
const getThread = service(async (_req, res) => {

View file

@ -14,8 +14,14 @@ export interface ChannelMessage {
langfuseDestinationIds?: string[] | null;
}
import type { AgentChannelRecord } from '@librechat/data-schemas';
import type { ChannelConfig } from 'librechat-data-provider';
import type { Request, Response, RequestHandler } from 'express';
export type ChannelServiceGuard = (
handler: (req: Request, res: Response, channel: AgentChannelRecord) => Promise<void>,
handler: (
req: Request,
res: Response,
channel: AgentChannelRecord,
config: ChannelConfig,
) => Promise<void>,
) => RequestHandler;

View file

@ -235,7 +235,16 @@ describe('createEndpointsConfigService', () => {
'exposes only channel availability to the agent builder when enabled=%s',
async (enabled) => {
const channels =
enabled == null ? undefined : { enabled, leaseMs: 60_000, cleanup: { batchSize: 25 } };
enabled == null
? undefined
: {
enabled,
leaseMs: 60_000,
cleanup: { batchSize: 25 },
nativeSessions: true,
lifecycleReactions: true,
signatureToleranceSeconds: 60,
};
const deps = createMockDeps({
loadDefaultEndpointsConfig: jest.fn().mockResolvedValue({
[EModelEndpoint.agents]: { userProvide: false, order: 0 },

View file

@ -0,0 +1,24 @@
# Slack transport adapters
This private workspace contains the transport adapters for Agent Channels. The executable consumer is the [standalone gateway runtime in #17618](https://github.com/LibreChat-AI/LibreChat/pull/17618), which composes these adapters with native presentation, HTTP and Socket Mode ingress, durable workers, process lifecycle and container packaging.
The adapter build produces four internal modules:
| Module | Responsibility |
| -------- | -------------------------------------------------------------------------------------------- |
| `client` | Private service authentication, channel/run identity checks and bounded API responses |
| `config` | Process bindings and resolution of the server-owned gateway policy |
| `events` | Original-byte webhook authentication, installation challenges and scoped event normalization |
| `slack` | Bounded provider calls, conservative uncertain-write outcomes and artifact transport |
The application defaults `endpoints.agents.channels.enabled` to `false`. Enable the capability in a deployment that includes the matching executable consumer. These adapter artifacts are internal dependencies; deploying the runnable gateway also requires its entry point, presentation layer and durable worker.
## Consumer contract
Before opening ingress, fetch the private channel bundle, validate its versioned gateway policy and call `resolveGatewayConfig`. The server selects Socket Mode or webhook transport; an optional process transport assertion must match. Missing or unsupported policy fails closed. Application and gateway must both support policy version 1.
Webhook consumers pass the original bounded bytes and signature headers to `parseWebhookRequest`, including installation verification requests. Only an authenticated `challenge` result may be echoed. Ordinary callbacks retain workspace/app binding checks; interactions also require current actor and action validation. Socket consumers must establish the authenticated app binding before dispatching events.
Forward native Stop with its original occurrence time and complete actor/channel/thread scope. The application owns bounded clock-skew normalization and the durable first-observation target, epoch and cutoff. Retained observation identity follows the external actor/thread across account relinks and channel/agent revisions; it is separate from the versioned execution principal. A retry cannot select a later lane or run. The observation joins account-erasure admission and channel serialization fences; cancellation still requires current authority and the exact lease fence. Optional native-session emission does not revoke cancellation for an existing session.
The runnable consumer preserves canonical execution identities and frozen delivery receipts across restarts. An uncertain required provider write requires reconciliation rather than a blind repeat. The standalone runtime's HTTP/Socket, worker, process and container checks validate that composition in addition to the adapter tests here.

View file

@ -0,0 +1,17 @@
export default {
testEnvironment: 'node',
testMatch: ['<rootDir>/src/**/*.spec.ts'],
transform: {
'\\.[jt]s$': [
'babel-jest',
{
presets: [
['@babel/preset-env', { targets: { node: 'current' } }],
'@babel/preset-typescript',
],
},
],
},
testTimeout: 15000,
restoreMocks: true,
};

View file

@ -0,0 +1,37 @@
{
"name": "@librechat/channel-gateway",
"version": "0.1.0",
"private": true,
"description": "Slack transport adapters for LibreChat Agent Channels",
"type": "module",
"scripts": {
"build": "tsdown",
"build:watch": "tsdown --watch",
"typecheck": "node ../../scripts/typecheck.mts",
"test": "jest --watch",
"test:ci": "jest --ci --runInBand"
},
"dependencies": {
"@slack/socket-mode": "3.1.0",
"@slack/types": "3.2.0",
"@slack/web-api": "8.2.0",
"undici": "^7.30.1",
"librechat-data-provider": "*",
"prom-client": "^15.1.3",
"zod": "^4.6.7"
},
"devDependencies": {
"@babel/preset-env": "^7.21.5",
"@babel/preset-typescript": "^7.21.0",
"@types/jest": "^29.5.2",
"@types/node": "^24.12.4",
"babel-jest": "^30.2.0",
"jest": "^30.2.0",
"tsdown": "^0.22.2",
"typescript": "^5.8.3"
},
"engines": {
"node": ">=24"
},
"license": "MIT"
}

View file

@ -0,0 +1,533 @@
import { createHash } from 'node:crypto';
import {
CHANNEL_RUN_MAX_JSON_BYTES,
DEFAULT_CHANNEL_GATEWAY_POLICY,
CHANNEL_DELIVERY_TEXT_MAX_CHARS,
CHANNEL_DELIVERY_PARTS_HARD_MAX,
CHANNEL_DELIVERY_PRESENTATION_MAX_BYTES,
} from 'librechat-data-provider';
import type { ChannelArtifact, ChannelRunFence, ChannelRunView } from 'librechat-data-provider';
import type { ChannelBundle, ResponseGrant } from './types';
import { ChannelClient, ServiceError, boundedBody } from './client';
import { loadConfig } from './config';
const config = loadConfig({
CHANNEL_SERVICE_TOKEN: 'private-service-token',
CHANNEL_TENANT_ID: 'tenant-1',
CHANNEL_ID: 'channel-1',
LIBRECHAT_INTERNAL_URL: 'http://127.0.0.1:3080/',
});
const json = (value: object | null, status = 200) =>
new Response(JSON.stringify(value), { status, headers: { 'Content-Type': 'application/json' } });
const fence: ChannelRunFence = { runId: 'run-1', owner: 'worker-1', epoch: 1 };
const grant: ResponseGrant = {
apiKey: 'sk-bound-private-test',
requestKey: 'channel:run-1',
request: { model: 'agent-1', input: 'private-user-prompt', background: true, store: true },
};
const response = {
id: 'resp_123',
object: 'response',
model: 'agent-1',
background: true,
store: true,
status: 'in_progress',
};
const bundle: ChannelBundle = {
channel: {
channelId: 'channel-1',
tenantId: 'tenant-1',
agentId: 'agent-1',
createdBy: 'user-1',
type: 'slack',
status: 'active',
credentialMode: 'per_user',
revision: 'revision-1',
slack: { teamId: 'T1', appId: 'A1', botUserId: 'U1' },
},
agent: { id: 'agent-1' },
credentials: { botToken: 'private-slack-token' },
gateway: { version: 1, ...DEFAULT_CHANNEL_GATEWAY_POLICY },
};
const run: ChannelRunView = {
runId: 'run-1',
channelId: 'channel-1',
revision: 'revision-1',
state: 'executing',
sequence: 1,
cancellationRequested: false,
receipts: [],
admission: {
eventId: 'event-1',
externalChannelId: 'C1',
externalMessageKey: 'C1:123.456',
externalThreadKey: 'C1:123.456',
actor: { teamId: 'T1', appId: 'A1', externalUserId: 'U1' },
input: 'private-user-prompt',
},
};
describe('ChannelClient service boundary', () => {
test.each([
undefined,
{ ...bundle.gateway, version: 2 },
{ version: 1 },
{ ...bundle.gateway, nativeSessions: 'true' },
{ ...bundle.gateway, signatureToleranceSeconds: 301 },
])('rejects missing or unsupported authoritative gateway policy %#', async (gateway) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () => json({ ...bundle, gateway }));
await expect(new ChannelClient(config, transport).channel()).rejects.toThrow(
'Unsupported channel gateway policy',
);
});
test('returns a valid worker-bound claim', async () => {
const lease = { run, fence, leaseExpiresAt: Date.now() + 60_000 };
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () => json(lease));
await expect(new ChannelClient(config, transport).claim(fence.owner)).resolves.toEqual(lease);
});
test.each([
{ fence: { ...fence, runId: 'other-run' } },
{ fence: { ...fence, owner: 'other-worker' } },
{ fence: { ...fence, epoch: 0 } },
{ fence: { ...fence, epoch: 1.5 } },
{ run: { ...run, channelId: 'other-channel' } },
{ run: { ...run, revision: '' } },
{ run: { ...run, admission: { ...run.admission, externalThreadKey: 'foreign:123' } } },
{ run: { ...run, admission: null } },
{ leaseExpiresAt: 0 },
{ leaseExpiresAt: 'future' },
])('rejects an inconsistent claimed lease %#', async (change) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () =>
json({ run, fence, leaseExpiresAt: Date.now() + 60_000, ...change }),
);
await expect(new ChannelClient(config, transport).claim(fence.owner)).rejects.toThrow();
});
test.each([
{ fence: { ...fence, runId: 'other-run' } },
{ fence: { ...fence, owner: 'other-worker' } },
{ fence: { ...fence, epoch: 2 } },
{ leaseExpiresAt: 0 },
])('rejects a renewal that changes the fence %#', async (change) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () =>
json({ fence, leaseExpiresAt: Date.now() + 60_000, ...change }),
);
await expect(new ChannelClient(config, transport).renew(fence)).rejects.toThrow();
});
test('rejects settlement for another run before exposing it to the worker', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () => json({ settled: { ...run, runId: 'other-run' } }));
await expect(new ChannelClient(config, transport).prepare(fence)).rejects.toThrow();
});
test.each([
{ settled: { ...run, channelId: 'other-channel' } },
{ settled: null },
{ settled: run, apiKey: grant.apiKey },
{ ...grant, request: { ...grant.request, store: false } },
{ ...grant, request: undefined },
])('fails closed on ambiguous or malformed successful preparation %#', async (value) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () => json(value));
await expect(new ChannelClient(config, transport).prepare(fence)).rejects.toThrow();
expect(transport).toHaveBeenCalledTimes(1);
});
test('reads a valid maximal-part plan above the old service cap through claim and mutation', async () => {
const largeRun: ChannelRunView = {
...run,
plan: {
revision: 'revision-1',
rendererVersion: 'test',
parts: Array.from({ length: CHANNEL_DELIVERY_PARTS_HARD_MAX }, (_, i) => ({
operationId: `part-${i}`,
kind: 'message',
required: true,
text: '\u0000'.repeat(CHANNEL_DELIVERY_TEXT_MAX_CHARS),
presentation: {
format: 'slack-blocks-v1',
payload: JSON.stringify({
text: 'x'.repeat(CHANNEL_DELIVERY_PRESENTATION_MAX_BYTES - 1000),
}),
},
})),
},
};
expect(Buffer.byteLength(JSON.stringify(largeRun))).toBeGreaterThan(2 * 1024 * 1024);
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementationOnce(async () =>
json({ run: largeRun, fence, leaseExpiresAt: Date.now() + 60_000 }),
)
.mockImplementationOnce(async () => json(largeRun));
const client = new ChannelClient(config, transport);
await expect(client.claim(fence.owner)).resolves.toMatchObject({ fence, run: largeRun });
await expect(client.mutate(fence, 'advance')).resolves.toEqual(largeRun);
});
test('uses service credentials only for the authorized channel/tenant and prohibits redirects', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(json(bundle));
await expect(new ChannelClient(config, transport).channel()).resolves.toEqual(bundle);
const [url, init] = transport.mock.calls[0];
expect(url).toBe('http://127.0.0.1:3080/api/channels/service/slack/tenant-1/channel-1');
expect(new Headers(init?.headers).get('authorization')).toBe('Bearer private-service-token');
expect(new Headers(init?.headers).get('X-Tenant-Id')).toBe('tenant-1');
expect(init?.redirect).toBe('error');
expect(init?.method).toBe('GET');
});
test('omits tenant header for the single-tenant placeholder', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(json({}));
await new ChannelClient({ ...config, CHANNEL_TENANT_ID: '_' }, transport).request('/test');
expect(new Headers(transport.mock.calls[0][1]?.headers).has('X-Tenant-Id')).toBe(false);
});
test.each([
{ channel: { ...bundle.channel, channelId: 'foreign' } },
{ channel: { ...bundle.channel, tenantId: 'foreign' } },
{ channel: { ...bundle.channel, status: 'disabled' } },
{ channel: { ...bundle.channel, revision: '' } },
{ channel: { ...bundle.channel, slack: { ...bundle.channel.slack, appId: '' } } },
{ credentials: { botToken: '' } },
{ agent: { id: 'foreign' } },
])('rejects changed/inactive channel binding %#', async (change) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(json({ ...bundle, ...change }));
await expect(new ChannelClient(config, transport).channel()).rejects.toThrow(
'Invalid active channel binding',
);
});
test('204 claim/yield is absence, not a JSON or operational failure', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () => new Response(null, { status: 204 }));
const client = new ChannelClient(config, transport);
await expect(client.claim('worker-1')).resolves.toBeNull();
await expect(client.yield(fence)).resolves.toBeNull();
expect(transport.mock.calls.map(([url]) => url)).toEqual([
'http://127.0.0.1:3080/api/channels/service/channel-1/runs/claim',
'http://127.0.0.1:3080/api/channels/service/channel-1/runs/run-1/yield',
]);
});
test('fenced mutation sends its fence and rejects a foreign run', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValueOnce(json(run))
.mockResolvedValueOnce(json({ ...run, runId: 'foreign' }));
const client = new ChannelClient(config, transport);
await expect(client.mutate(fence, 'advance')).resolves.toEqual(run);
expect(JSON.parse(String(transport.mock.calls[0][1]?.body))).toEqual({ fence });
await expect(client.mutate(fence, 'advance')).rejects.toThrow('Channel run identity changed');
});
test.each([400, 401, 403, 409, 500])(
'does not expose untrusted HTTP %s response data',
async (status) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(
json({ error: 'private-upstream-message', token: 'private-upstream-token' }, status),
);
try {
await new ChannelClient(config, transport).claim('worker-1');
throw new Error('unexpected success');
} catch (error) {
expect(error).toBeInstanceOf(ServiceError);
expect(String(error)).toBe(`Error: Channel service returned HTTP ${status}`);
expect(error).toHaveProperty('code', '');
}
},
);
test('allows only the explicit actor-link-required error code on 403', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(json({ error: 'channel_link_required', secret: 'private-value' }, 403));
await expect(new ChannelClient(config, transport).claim('worker-1')).rejects.toMatchObject({
status: 403,
code: 'channel_link_required',
});
});
test('malformed and oversized bodies fail safely', async () => {
const chunk = Buffer.alloc(64 * 1024, 'x');
let remaining = CHANNEL_RUN_MAX_JSON_BYTES + 1;
const oversized = new ReadableStream<Uint8Array>({
pull(controller) {
if (remaining === 0) return controller.close();
const size = Math.min(remaining, chunk.length);
controller.enqueue(chunk.subarray(0, size));
remaining -= size;
},
});
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValueOnce(new Response('private-malformed-value'))
.mockResolvedValueOnce(new Response(oversized));
const client = new ChannelClient(config, transport);
await expect(client.claim('worker-1')).rejects.toThrow('Invalid channel service response');
await expect(client.claim('worker-1')).rejects.toThrow('Remote response exceeds size limit');
});
});
describe('bound Responses lifecycle', () => {
test('reads valid persisted Response content beyond the previous service cap', async () => {
const large = { ...response, output: '\u0000'.repeat(400_000) };
expect(Buffer.byteLength(JSON.stringify(large))).toBeGreaterThan(2 * 1024 * 1024);
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () => json(large));
await expect(new ChannelClient(config, transport).response(grant, 'create')).resolves.toEqual(
large,
);
});
test('uses only the run-bound key, stable creation idempotency and exact returned identity', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () => json(response));
const client = new ChannelClient(config, transport);
await client.response(grant, 'create');
await client.response({ ...grant, responseId: response.id }, 'read');
await client.response({ ...grant, responseId: response.id }, 'cancel');
const [create, read, cancel] = transport.mock.calls;
expect(create[0]).toBe('http://127.0.0.1:3080/api/agents/v1/responses');
expect(JSON.parse(String(create[1]?.body))).toEqual({ ...grant.request, stream: false });
expect(new Headers(create[1]?.headers).get('Idempotency-Key')).toBe('channel:run-1');
expect(read[0]).toBe(create[0] + '/resp_123');
expect(read[1]?.method).toBe('GET');
expect(new Headers(read[1]?.headers).has('Idempotency-Key')).toBe(false);
expect(cancel[0]).toBe(create[0] + '/resp_123/cancel');
expect(cancel[1]?.body).toBe('{}');
for (const [, init] of transport.mock.calls) {
expect(new Headers(init?.headers).get('authorization')).toBe('Bearer sk-bound-private-test');
expect(new Headers(init?.headers).get('X-Tenant-Id')).toBe('tenant-1');
}
});
test.each([
{ apiKey: 'shared-api-key' },
{ requestKey: '' },
{ requestKey: 'unsafe\nkey' },
{ requestKey: 'x'.repeat(257) },
])('rejects invalid run credential before HTTP %#', async (change) => {
const transport = jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>();
await expect(
new ChannelClient(config, transport).response({ ...grant, ...change }, 'create'),
).rejects.toThrow('Invalid run-bound response credential');
expect(transport).not.toHaveBeenCalled();
});
test.each([undefined, 'foreign', 'resp_../x', 'resp_x?secret', 'resp_x\n'])(
'rejects read/cancel identity %s before HTTP',
async (responseId) => {
const transport = jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>();
const client = new ChannelClient(config, transport);
await expect(client.response({ ...grant, responseId }, 'read')).rejects.toThrow(
'Invalid Response identity',
);
await expect(client.response({ ...grant, responseId }, 'cancel')).rejects.toThrow(
'Invalid Response identity',
);
expect(transport).not.toHaveBeenCalled();
},
);
test.each([
{ id: 'resp_foreign' },
{ id: 'not-response' },
{ model: 'foreign' },
{ object: 'other' },
{ store: false },
{ background: false },
{ store: 'false' },
{ background: 'false' },
{ status: 'unexpected' },
])('rejects changed Responses identity/state %#', async (change) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(json({ ...response, ...change }));
await expect(
new ChannelClient(config, transport).response({ ...grant, responseId: response.id }, 'read'),
).rejects.toThrow('Responses identity or state changed');
});
test('never silently retries an uncertain creation', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockRejectedValue(new Error('network'));
await expect(new ChannelClient(config, transport).response(grant, 'create')).rejects.toThrow();
expect(transport).toHaveBeenCalledTimes(1);
});
});
describe('authorized artifact content', () => {
const content = Buffer.from('fixture content');
const artifact: ChannelArtifact = {
artifactId: 'artifact-1',
filename: 'résumé.csv',
mediaType: 'text/csv',
bytes: content.length,
sha256: createHash('sha256').update(content).digest('hex'),
};
const headers = () => ({
'Content-Type': 'application/octet-stream',
'X-Artifact-Filename': encodeURIComponent(artifact.filename),
'X-Artifact-SHA256': artifact.sha256,
'X-Artifact-Media-Type': artifact.mediaType,
});
test('fetches only fenced server content and verifies exact metadata, length and hash', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(new Response(content, { headers: headers() }));
await expect(new ChannelClient(config, transport).artifact(fence, artifact)).resolves.toEqual(
content,
);
const [url, init] = transport.mock.calls[0];
expect(url).toBe(
'http://127.0.0.1:3080/api/channels/service/channel-1/runs/run-1/artifacts/artifact-1',
);
expect(init?.body).toBe(JSON.stringify({ fence }));
expect(new Headers(init?.headers).get('authorization')).toBe('Bearer private-service-token');
});
test.each([
{ artifactId: '' },
{ artifactId: 'x'.repeat(513) },
{ filename: '' },
{ filename: '../private' },
{ filename: 'unsafe\\file' },
{ filename: 'file\nname' },
{ filename: 'file\u200bname' },
{ filename: 'é'.repeat(361) },
{ bytes: -1 },
{ bytes: 0.5 },
{ bytes: 50 * 1024 * 1024 + 1 },
{ sha256: 'bad' },
{ sha256: 'A'.repeat(64) },
])('rejects invalid descriptors before HTTP %#', async (change) => {
const transport = jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>();
await expect(
new ChannelClient(config, transport).artifact(fence, { ...artifact, ...change }),
).rejects.toThrow('Invalid artifact descriptor');
expect(transport).not.toHaveBeenCalled();
});
test.each(['X-Artifact-Filename', 'X-Artifact-SHA256', 'X-Artifact-Media-Type', 'Content-Type'])(
'rejects mismatched %s',
async (name) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(
new Response(content, { headers: { ...headers(), [name]: 'private-mismatch' } }),
);
await expect(new ChannelClient(config, transport).artifact(fence, artifact)).rejects.toThrow(
'Artifact metadata changed',
);
},
);
test.each([
Buffer.from('short'),
Buffer.from('x'.repeat(content.length)),
Buffer.concat([content, Buffer.from('extra')]),
])('rejects changed content %#', async (body) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(new Response(body, { headers: headers() }));
await expect(new ChannelClient(config, transport).artifact(fence, artifact)).rejects.toThrow();
});
test('rejects malformed filename encoding and does not expose server errors', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValueOnce(
new Response(content, { headers: { ...headers(), 'X-Artifact-Filename': '%zz' } }),
)
.mockResolvedValueOnce(new Response('private-secret', { status: 403 }));
const client = new ChannelClient(config, transport);
await expect(client.artifact(fence, artifact)).rejects.toThrow('Artifact metadata changed');
await expect(client.artifact(fence, artifact)).rejects.toThrow(
'Channel service returned HTTP 403',
);
});
test('bounded reader cancels the stream after exceeding its cap', async () => {
const cancel = jest.fn();
const body = new ReadableStream<Uint8Array>({
start(controller) {
controller.enqueue(Buffer.from('too large'));
},
cancel,
});
await expect(boundedBody(new Response(body), 2)).rejects.toThrow(
'Remote response exceeds size limit',
);
expect(cancel).toHaveBeenCalledTimes(1);
});
});
test('renewal returns only the renewed fence and deadline, without inventing a run snapshot', async () => {
const renewed = { fence, leaseExpiresAt: Date.now() + 60_000 };
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(json(renewed));
const value = await new ChannelClient(config, transport).renew(fence);
expect(value).toEqual(renewed);
expect(value).not.toHaveProperty('run');
});
test('preparation distinguishes canonical settlement from execution credentials', async () => {
const settled = {
...run,
state: 'delivering' as const,
cancellationRequested: true,
snapshot: { status: 'cancelled' as const, text: '', elapsedMs: 0 },
};
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValueOnce(json({ settled }))
.mockResolvedValueOnce(json(grant));
const client = new ChannelClient(config, transport);
const first = await client.prepare(fence);
if (!first.settled) throw new Error('Expected canonical unstarted cancellation');
expect(first.settled).toEqual(settled);
expect(first).not.toHaveProperty('apiKey');
const next = await client.prepare(fence);
if (next.settled) throw new Error('Expected credential-bearing preparation');
expect(next.apiKey).toBe(grant.apiKey);
expect(transport).toHaveBeenCalledTimes(2);
});
test('Stop and cancel retain the complete external-channel scope at the service boundary', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () => json({ cancellationRequested: true }));
const client = new ChannelClient(config, transport);
const actor = run.admission.actor;
await client.stop(actor, 'C1:123.456', 1234, 'C1');
await client.cancel(run.runId, actor, run.revision, 'C1');
expect(transport.mock.calls.map(([, init]) => JSON.parse(String(init?.body)))).toEqual([
{ actor, externalThreadKey: 'C1:123.456', externalChannelId: 'C1', eventAt: 1234 },
{ actor, revision: run.revision, externalChannelId: 'C1' },
]);
});

View file

@ -0,0 +1,450 @@
import { createHash } from 'node:crypto';
import {
CHANNEL_RUN_MAX_JSON_BYTES,
channelGatewayWirePolicySchema,
} from 'librechat-data-provider';
import type {
ChannelRunActor,
ChannelRunAdmission,
ChannelRunView,
ChannelRunFence,
ChannelLinkView,
ChannelLinkTicket,
ChannelIdentityResult,
ChannelArtifact,
ResponseReviewDecision,
ResponseReviewDecisionReceipt,
} from 'librechat-data-provider';
import type {
ChannelBundle,
Lease,
LeaseRenewal,
ResponseGrant,
ResponsePreparation,
Review,
BackgroundResponse,
} from './types';
import type { GatewayConfig } from './config';
export class ServiceError extends Error {
constructor(
readonly status: number,
readonly code = '',
) {
super(`Channel service returned HTTP ${status}`);
}
}
const validId = (value: unknown): value is string =>
typeof value === 'string' && /^[\w:.-]{1,256}$/.test(value);
function validFence(
value: ChannelRunFence | undefined,
expected: Partial<ChannelRunFence>,
): boolean {
return Boolean(
value &&
validId(value.runId) &&
validId(value.owner) &&
Number.isSafeInteger(value.epoch) &&
value.epoch > 0 &&
(expected.runId === undefined || value.runId === expected.runId) &&
(expected.owner === undefined || value.owner === expected.owner) &&
(expected.epoch === undefined || value.epoch === expected.epoch),
);
}
export async function boundedBody(response: Response, limit: number): Promise<Buffer> {
if (!response.body) return Buffer.alloc(0);
const reader = response.body.getReader();
const chunks: Uint8Array[] = [];
let bytes = 0;
try {
while (true) {
const { value, done } = await reader.read();
if (done) break;
bytes += value.byteLength;
if (bytes > limit) throw new Error('Remote response exceeds size limit');
chunks.push(value);
}
return Buffer.concat(chunks, bytes);
} finally {
await reader.cancel().catch(() => {});
reader.releaseLock();
}
}
export class ChannelClient {
readonly root: string;
private readonly base: string;
constructor(
readonly config: GatewayConfig,
private readonly transport: typeof fetch = fetch,
) {
this.base = config.LIBRECHAT_INTERNAL_URL.replace(/\/$/, '');
this.root = `/api/channels/service/${encodeURIComponent(config.CHANNEL_ID)}`;
}
private async raw(
path: string,
body: object | undefined,
signal?: AbortSignal,
key = this.config.CHANNEL_SERVICE_TOKEN,
requestKey?: string,
timeout = this.config.API_CALL_TIMEOUT_MS,
): Promise<Response> {
const headers: Record<string, string> = {
Authorization: `Bearer ${key}`,
'Content-Type': 'application/json',
};
if (this.config.CHANNEL_TENANT_ID !== '_')
headers['X-Tenant-Id'] = this.config.CHANNEL_TENANT_ID;
if (requestKey) headers['Idempotency-Key'] = requestKey;
return this.transport(this.base + path, {
method: body === undefined ? 'GET' : 'POST',
headers,
body: body === undefined ? undefined : JSON.stringify(body),
redirect: 'error',
signal: AbortSignal.any([AbortSignal.timeout(timeout), ...(signal ? [signal] : [])]),
});
}
private async decode<T>(response: Response, empty?: T): Promise<T> {
if (response.status === 204 && empty !== undefined) return empty;
const bytes = await boundedBody(response, response.ok ? CHANNEL_RUN_MAX_JSON_BYTES : 64 * 1024);
if (!response.ok) {
let code = '';
try {
const failure: { error?: string } = JSON.parse(bytes.toString());
if (response.status === 403 && failure.error === 'channel_link_required')
code = failure.error;
} catch {
/* Untrusted error bodies are never exposed. */
}
throw new ServiceError(response.status, code);
}
try {
const value: T = JSON.parse(bytes.toString());
return value;
} catch {
throw new Error('Invalid channel service response');
}
}
async request<T>(path: string, body?: object, signal?: AbortSignal, empty?: T): Promise<T> {
return this.decode<T>(await this.raw(path, body, signal), empty);
}
async channel(signal?: AbortSignal): Promise<ChannelBundle> {
const value = await this.request<ChannelBundle>(
`/api/channels/service/slack/${encodeURIComponent(this.config.CHANNEL_TENANT_ID)}/${encodeURIComponent(this.config.CHANNEL_ID)}`,
undefined,
signal,
);
const { channel, agent, credentials } = value;
if (
channel?.channelId !== this.config.CHANNEL_ID ||
(channel.tenantId ?? '_') !== this.config.CHANNEL_TENANT_ID ||
channel.type !== 'slack' ||
channel.status !== 'active' ||
!channel.revision ||
!channel.slack?.teamId ||
!channel.slack.appId ||
!channel.slack.botUserId ||
!credentials?.botToken ||
!agent?.id ||
channel.agentId !== agent.id
)
throw new Error('Invalid active channel binding');
const policy = channelGatewayWirePolicySchema.safeParse(value.gateway);
if (!policy.success) throw new Error('Unsupported channel gateway policy');
return { ...value, gateway: policy.data };
}
async runs<T>(suffix: string, body: object, signal?: AbortSignal, empty?: T): Promise<T> {
return this.request<T>(this.root + '/runs' + suffix, body, signal, empty);
}
private assertRun(run: ChannelRunView | undefined, runId: string): asserts run is ChannelRunView {
if (
!run ||
typeof run !== 'object' ||
run.runId !== runId ||
run.channelId !== this.config.CHANNEL_ID ||
!validId(run.revision) ||
!Number.isSafeInteger(run.sequence) ||
run.sequence < 1 ||
![
'queued',
'executing',
'requires_action',
'delivering',
'delivered',
'failed',
'cancelled',
'blocked',
].includes(run.state) ||
typeof run.cancellationRequested !== 'boolean' ||
!Array.isArray(run.receipts) ||
!validId(run.admission?.externalChannelId) ||
typeof run.admission?.externalThreadKey !== 'string' ||
!run.admission.externalThreadKey.startsWith(run.admission.externalChannelId + ':') ||
!validId(run.admission.actor?.teamId) ||
!validId(run.admission.actor?.appId) ||
!validId(run.admission.actor?.externalUserId)
)
throw new Error('Channel run identity changed');
}
private assertGrant(grant: ResponseGrant): void {
if (
!grant ||
typeof grant !== 'object' ||
typeof grant.apiKey !== 'string' ||
!grant.apiKey.startsWith('sk-bound-') ||
/[\r\n]/.test(grant.apiKey) ||
typeof grant.requestKey !== 'string' ||
!grant.requestKey ||
grant.requestKey.length > 256 ||
/[\r\n]/.test(grant.requestKey) ||
typeof grant.request?.model !== 'string' ||
!grant.request.model ||
typeof grant.request.input !== 'string' ||
grant.request.background !== true ||
grant.request.store !== true
)
throw new Error('Invalid run-bound response credential');
}
async mutate(
fence: ChannelRunFence,
action: string,
body: object = {},
signal?: AbortSignal,
): Promise<ChannelRunView> {
const result = await this.runs<ChannelRunView>(
`/${encodeURIComponent(fence.runId)}/${action}`,
{ ...body, fence },
signal,
);
this.assertRun(result, fence.runId);
return result;
}
admit(
input: ChannelRunAdmission,
signal?: AbortSignal,
): Promise<{ runId: string; duplicate: boolean }> {
return this.runs('', input, signal);
}
async claim(owner: string, signal?: AbortSignal): Promise<Lease | null> {
const lease = await this.runs<Lease | null>('/claim', { owner }, signal, null);
if (lease === null) return null;
if (
!validFence(lease?.fence, { owner }) ||
!Number.isSafeInteger(lease.leaseExpiresAt) ||
lease.leaseExpiresAt <= 0
)
throw new Error('Invalid channel run lease');
this.assertRun(lease.run, lease.fence.runId);
return lease;
}
async renew(fence: ChannelRunFence, signal?: AbortSignal): Promise<LeaseRenewal> {
const lease = await this.runs<LeaseRenewal>(
`/${encodeURIComponent(fence.runId)}/renew`,
{ fence },
signal,
);
if (
!validFence(lease?.fence, fence) ||
!Number.isSafeInteger(lease.leaseExpiresAt) ||
lease.leaseExpiresAt <= 0
)
throw new Error('Invalid channel run lease');
return lease;
}
yield(fence: ChannelRunFence, signal?: AbortSignal): Promise<null> {
return this.runs(`/${encodeURIComponent(fence.runId)}/yield`, { fence }, signal, null);
}
async prepare(fence: ChannelRunFence, signal?: AbortSignal): Promise<ResponsePreparation> {
const result = await this.runs<ResponsePreparation>(
`/${encodeURIComponent(fence.runId)}/response/prepare`,
{ fence },
signal,
);
if (!result || typeof result !== 'object') throw new Error('Invalid Response preparation');
if ('settled' in result) {
this.assertRun(result.settled, fence.runId);
if ('apiKey' in result) throw new Error('Invalid Response preparation');
} else this.assertGrant(result);
return result;
}
review(
runId: string,
actor: ChannelRunActor,
revision: string,
externalChannelId?: string,
signal?: AbortSignal,
): Promise<Review> {
return this.runs(
`/${encodeURIComponent(runId)}/review`,
{ actor, revision, ...(externalChannelId ? { externalChannelId } : {}) },
signal,
);
}
async decide(
runId: string,
actor: ChannelRunActor,
revision: string,
externalChannelId: string,
decision: ResponseReviewDecision,
signal?: AbortSignal,
): Promise<ResponseReviewDecisionReceipt> {
const receipt = await this.runs<ResponseReviewDecisionReceipt>(
`/${encodeURIComponent(runId)}/review/decision`,
{ actor, revision, externalChannelId, decision },
signal,
);
if (
!receipt.intentId ||
!receipt.responseId ||
receipt.actionId !== decision.actionId ||
!['queued', 'settled'].includes(receipt.status)
)
throw new Error('Invalid decision receipt');
return receipt;
}
cancel(
runId: string,
actor: ChannelRunActor,
revision: string,
externalChannelId: string,
signal?: AbortSignal,
): Promise<{ cancellationRequested: boolean }> {
return this.runs(
`/${encodeURIComponent(runId)}/cancel`,
{ actor, revision, externalChannelId },
signal,
);
}
stop(
actor: ChannelRunActor,
externalThreadKey: string,
eventAt: number,
externalChannelId: string,
signal?: AbortSignal,
): Promise<{ cancellationRequested: boolean }> {
return this.runs(
'/stop-thread',
{ actor, externalThreadKey, externalChannelId, eventAt },
signal,
);
}
async identity<T extends ChannelLinkView | ChannelLinkTicket | null>(
actor: string,
suffix = '',
body?: object,
signal?: AbortSignal,
): Promise<T> {
const result = await this.request<ChannelIdentityResult<T>>(
`${this.root}/identity/${encodeURIComponent(actor)}${suffix}`,
body,
signal,
);
if (!result.ok) throw new Error('Channel identity unavailable or changed');
return result.value;
}
async response(
grant: ResponseGrant,
method: 'create' | 'read' | 'cancel',
signal?: AbortSignal,
): Promise<BackgroundResponse> {
this.assertGrant(grant);
const id = grant.responseId;
if (
(id !== undefined || method !== 'create') &&
(!id || !/^resp_[A-Za-z0-9_-]{1,250}$/.test(id))
)
throw new Error('Invalid Response identity');
const suffix =
method === 'create'
? ''
: `/${encodeURIComponent(id!)}${method === 'cancel' ? '/cancel' : ''}`;
let body: object | undefined;
if (method === 'cancel') body = {};
if (method === 'create') body = { ...grant.request, stream: false };
const value = await this.decode<BackgroundResponse>(
await this.raw(
'/api/agents/v1/responses' + suffix,
body,
signal,
grant.apiKey,
method === 'create' ? grant.requestKey : undefined,
method === 'create' ? this.config.AGENT_INVOKE_TIMEOUT_MS : this.config.API_CALL_TIMEOUT_MS,
),
);
if (
!/^resp_[A-Za-z0-9_-]{1,250}$/.test(value.id) ||
value.model !== grant.request.model ||
value.object !== 'response' ||
value.store !== true ||
value.background !== true ||
(id && value.id !== id) ||
![
'queued',
'in_progress',
'requires_action',
'completed',
'failed',
'incomplete',
'cancelled',
].includes(value.status)
)
throw new Error('Responses identity or state changed');
return value;
}
async artifact(
fence: ChannelRunFence,
artifact: ChannelArtifact,
signal?: AbortSignal,
): Promise<Buffer> {
if (
!artifact.artifactId ||
artifact.artifactId.length > 512 ||
!artifact.filename ||
Buffer.byteLength(artifact.filename) > 720 ||
!Number.isSafeInteger(artifact.bytes) ||
artifact.bytes < 0 ||
artifact.bytes > 50 * 1024 * 1024 ||
!/^[a-f0-9]{64}$/.test(artifact.sha256) ||
/[/\\\p{Cc}\p{Cf}]/u.test(artifact.filename)
)
throw new Error('Invalid artifact descriptor');
const response = await this.raw(
`${this.root}/runs/${encodeURIComponent(fence.runId)}/artifacts/${encodeURIComponent(artifact.artifactId)}`,
{ fence },
signal,
);
if (!response.ok) {
await response.body?.cancel();
throw new ServiceError(response.status);
}
let filename: string;
try {
filename = decodeURIComponent(response.headers.get('X-Artifact-Filename') ?? '');
} catch {
await response.body?.cancel();
throw new Error('Artifact metadata changed');
}
if (
filename !== artifact.filename ||
response.headers.get('X-Artifact-SHA256') !== artifact.sha256 ||
response.headers.get('X-Artifact-Media-Type') !== artifact.mediaType ||
response.headers.get('Content-Type')?.split(';')[0] !== 'application/octet-stream'
) {
await response.body?.cancel();
throw new Error('Artifact metadata changed');
}
const bytes = await boundedBody(response, artifact.bytes);
if (
bytes.length !== artifact.bytes ||
createHash('sha256').update(bytes).digest('hex') !== artifact.sha256
)
throw new Error('Artifact content changed');
return bytes;
}
}

View file

@ -0,0 +1,164 @@
import { DEFAULT_CHANNEL_GATEWAY_POLICY, channelConfigSchema } from 'librechat-data-provider';
import { loadConfig, resolveGatewayConfig } from './config';
const required = {
CHANNEL_SERVICE_TOKEN: 'private-service-token',
CHANNEL_TENANT_ID: 'tenant-1',
CHANNEL_ID: 'channel-1',
};
describe('gateway configuration', () => {
test('loads generic deployment defaults without private branding or optional Slack authority', () => {
expect(loadConfig(required)).toMatchObject({
APP_TITLE: 'LibreChat',
PORT: 8080,
LISTEN_HOST: '0.0.0.0',
LIBRECHAT_INTERNAL_URL: 'http://localhost:3080',
SLACK_API_BASE_URL: 'https://slack.com/api/',
});
expect(loadConfig(required)).not.toHaveProperty('SLACK_TRANSPORT');
expect(
resolveGatewayConfig(
loadConfig({ ...required, SLACK_APP_TOKEN: 'test-app-token' }),
DEFAULT_CHANNEL_GATEWAY_POLICY,
).SLACK_TRANSPORT,
).toBe(channelConfigSchema.parse({}).transport);
});
test('supports legacy binding aliases and equal canonical/legacy values', () => {
const legacy = {
CHANNEL_SERVICE_TOKEN: required.CHANNEL_SERVICE_TOKEN,
SLACK_SOCKET_TENANT_ID: 'tenant-1',
SLACK_SOCKET_CHANNEL_ID: 'channel-1',
};
expect(loadConfig(legacy)).toMatchObject(required);
expect(loadConfig({ ...legacy, ...required })).toMatchObject(required);
});
test.each(['CHANNEL_TENANT_ID', 'CHANNEL_ID'])(
'never falls back from an explicitly empty canonical %s',
(name) => {
expect(() =>
loadConfig({
...required,
[name]: '',
SLACK_SOCKET_TENANT_ID: 'tenant-1',
SLACK_SOCKET_CHANNEL_ID: 'channel-1',
}),
).toThrow();
},
);
test('conflicting bindings fail without disclosing either identifier', () => {
expect(() =>
loadConfig({ ...required, SLACK_SOCKET_CHANNEL_ID: 'private-other-channel' }),
).toThrow('Conflicting channel bindings');
});
test('requires durable actor-bound execution and Socket Mode app token', () => {
expect(() => loadConfig({ ...required, DURABLE_RUNS_ENABLED: 'false' })).toThrow(
'Actor-bound durable execution is required',
);
expect(() =>
resolveGatewayConfig(loadConfig(required), DEFAULT_CHANNEL_GATEWAY_POLICY),
).toThrow('SLACK_APP_TOKEN is required');
expect(
resolveGatewayConfig(
loadConfig({
...required,
SLACK_TRANSPORT: 'socket_mode',
SLACK_APP_TOKEN: 'private-app-token',
}),
DEFAULT_CHANNEL_GATEWAY_POLICY,
).SLACK_TRANSPORT,
).toBe('socket_mode');
});
test.each(['LIBRECHAT_INTERNAL_URL', 'SLACK_API_BASE_URL'])(
'rejects unsafe %s values without echoing them',
(name) => {
for (const value of [
'ftp://private.example',
'https://private-user:private-password@example.com',
'https://example.com?token=private-secret',
'https://example.com#private-secret',
'private-invalid-value',
]) {
try {
loadConfig({ ...required, [name]: value });
throw new Error('accepted invalid configuration');
} catch (error) {
expect(error).toBeInstanceOf(Error);
expect(String(error)).not.toContain(value);
expect(String(error)).not.toContain('private-secret');
expect(String(error)).not.toContain('private-password');
expect(String(error)).not.toContain('accepted invalid configuration');
}
}
},
);
test.each(['PORT', 'API_CALL_TIMEOUT_MS', 'AGENT_INVOKE_TIMEOUT_MS'])(
'validates numeric %s bounds without echoing submitted values',
(name) => {
for (const value of ['0', '-1', '1.2', 'private-input']) {
expect(() => loadConfig({ ...required, [name]: value })).toThrow(
`Invalid gateway configuration: ${name}`,
);
}
expect(() => loadConfig({ ...required, PORT: '65536' })).toThrow('PORT');
},
);
test.each(['x/y', 'x\\y', 'x?y', 'x#y', 'x:y', 'x y', 'x\ny'])(
'rejects path/header syntax in binding %s',
(value) => {
expect(() => loadConfig({ ...required, CHANNEL_ID: value })).toThrow('CHANNEL_ID');
},
);
test('allows single-tenant binding while the server selects webhook ingress without a local default', () => {
const config = loadConfig({ ...required, CHANNEL_TENANT_ID: '_' });
expect(config.CHANNEL_TENANT_ID).toBe('_');
expect(
resolveGatewayConfig(config, { ...DEFAULT_CHANNEL_GATEWAY_POLICY, transport: 'webhook' })
.SLACK_TRANSPORT,
).toBe('webhook');
expect(() =>
resolveGatewayConfig(
loadConfig({
...required,
SLACK_TRANSPORT: 'socket_mode',
SLACK_APP_TOKEN: 'test-app-token',
}),
{ ...DEFAULT_CHANNEL_GATEWAY_POLICY, transport: 'webhook' },
),
).toThrow('does not match channel policy');
});
test.each([
'SLACK_NATIVE_SESSIONS',
'SLACK_LIFECYCLE_REACTIONS',
'SLACK_SIGNATURE_TOLERANCE_SECS',
])('rejects an independently managed %s policy override', (key) => {
expect(() => loadConfig({ ...required, [key]: 'false' })).toThrow('librechat.yaml');
});
test.each(['', '<@everyone>', 'Name|URL', 'private\nsecret', 'x'.repeat(41)])(
'rejects unsafe app title %s',
(APP_TITLE) => {
expect(() => loadConfig({ ...required, APP_TITLE })).toThrow('APP_TITLE');
},
);
test.each(['127.0.0.1', '::1', 'localhost', '0.0.0.0'])('allows listener %s', (LISTEN_HOST) => {
expect(loadConfig({ ...required, LISTEN_HOST }).LISTEN_HOST).toBe(LISTEN_HOST);
});
test.each(['example.com', '127.0.0.1:8088', 'http://localhost', '[::1]', ' ', '127.0.0.1\n'])(
'rejects invalid listener %s',
(LISTEN_HOST) => {
expect(() => loadConfig({ ...required, LISTEN_HOST })).toThrow('LISTEN_HOST');
},
);
});

View file

@ -0,0 +1,98 @@
import { z } from 'zod';
import { isIP } from 'node:net';
import { channelGatewayPolicySchema } from 'librechat-data-provider';
import type { ChannelGatewayPolicy } from 'librechat-data-provider';
const identifier = z
.string()
.min(1)
.max(256)
.regex(/^[^/\\?#\s:]+$/);
const positive = (fallback: number) => z.coerce.number().int().positive().default(fallback);
const environment = z.object({
PORT: positive(8080).refine((value) => value <= 65535),
LISTEN_HOST: z
.string()
.refine((value) => value === 'localhost' || !!isIP(value))
.default('0.0.0.0'),
LIBRECHAT_INTERNAL_URL: z.url().default('http://localhost:3080'),
CHANNEL_SERVICE_TOKEN: z.string().min(1),
CHANNEL_TENANT_ID: identifier,
CHANNEL_ID: identifier,
APP_TITLE: z
.string()
.trim()
.min(1)
.max(40)
.regex(/^[^<>|\p{Cc}]+$/u)
.default('LibreChat'),
/** Optional deployment assertion; the service policy selects the actual ingress. */
SLACK_TRANSPORT: z.enum(['socket_mode', 'webhook']).optional(),
SLACK_APP_TOKEN: z.string().optional(),
SLACK_API_BASE_URL: z.url().default('https://slack.com/api/'),
API_CALL_TIMEOUT_MS: positive(10000),
AGENT_INVOKE_TIMEOUT_MS: positive(120000),
});
export type GatewayConfig = z.infer<typeof environment>;
export type GatewayRuntimeConfig = GatewayConfig & {
SLACK_TRANSPORT: ChannelGatewayPolicy['transport'];
};
export function loadConfig(env: NodeJS.ProcessEnv): GatewayConfig {
if (
['SLACK_NATIVE_SESSIONS', 'SLACK_LIFECYCLE_REACTIONS', 'SLACK_SIGNATURE_TOLERANCE_SECS'].some(
(key) => env[key] !== undefined,
)
)
throw new Error(
'Configure gateway features and signature policy in librechat.yaml channel settings',
);
const input = {
...env,
CHANNEL_TENANT_ID: env.CHANNEL_TENANT_ID ?? env.SLACK_SOCKET_TENANT_ID,
CHANNEL_ID: env.CHANNEL_ID ?? env.SLACK_SOCKET_CHANNEL_ID,
};
for (const [name, alias] of [
['CHANNEL_TENANT_ID', 'SLACK_SOCKET_TENANT_ID'],
['CHANNEL_ID', 'SLACK_SOCKET_CHANNEL_ID'],
]) {
if (env[name] !== undefined && env[alias] && env[name] !== env[alias])
throw new Error('Conflicting channel bindings');
}
if (env.DURABLE_RUNS_ENABLED === 'false')
throw new Error('Actor-bound durable execution is required');
const parsed = environment.safeParse(input);
if (!parsed.success)
throw new Error(
`Invalid gateway configuration: ${[...new Set(parsed.error.issues.map((issue) => String(issue.path[0])))].join(', ')}`,
);
const config = parsed.data;
const backend = new URL(config.LIBRECHAT_INTERNAL_URL);
const slack = new URL(config.SLACK_API_BASE_URL);
for (const url of [backend, slack]) {
if (
!['http:', 'https:'].includes(url.protocol) ||
url.username ||
url.password ||
url.search ||
url.hash
)
throw new Error('Invalid gateway service URL');
}
return config;
}
/** Bootstrap settings cannot override the server's current installation/ingress policy. */
export function resolveGatewayConfig(
config: GatewayConfig,
value: ChannelGatewayPolicy,
): GatewayRuntimeConfig {
const parsed = channelGatewayPolicySchema.safeParse(value);
if (!parsed.success) throw new Error('Invalid channel gateway policy');
const policy = parsed.data;
if (config.SLACK_TRANSPORT && config.SLACK_TRANSPORT !== policy.transport)
throw new Error('Gateway transport does not match channel policy');
if (policy.transport === 'socket_mode' && !config.SLACK_APP_TOKEN)
throw new Error('SLACK_APP_TOKEN is required for Socket Mode');
return { ...config, SLACK_TRANSPORT: policy.transport };
}

View file

@ -0,0 +1,271 @@
import { createHmac } from 'node:crypto';
import { DEFAULT_CHANNEL_GATEWAY_POLICY } from 'librechat-data-provider';
import type { ChannelBundle } from './types';
import {
eventTimestampUs,
normalizeEvent,
parseEnvelope,
verifySignature,
parseWebhookRequest,
} from './events';
const bundle: ChannelBundle = {
channel: {
channelId: 'binding',
tenantId: 'tenant',
agentId: 'agent',
createdBy: 'owner',
type: 'slack',
status: 'active',
credentialMode: 'per_user',
revision: 'r1',
slack: { teamId: 'T1', appId: 'A1', botUserId: 'B1' },
},
agent: { id: 'agent' },
credentials: { botToken: 'test-bot', signingSecret: 'test-signing' },
gateway: { version: 1, ...DEFAULT_CHANNEL_GATEWAY_POLICY, transport: 'webhook' },
};
const envelope = (event: object) => ({
type: 'event_callback',
event_id: 'E1',
team_id: 'T1',
api_app_id: 'A1',
event: {
type: 'app_mention',
user: 'U1',
channel: 'C1',
ts: '1793000000.123456',
text: '<@B1> hello',
...event,
},
});
const normalize = (event: object) => normalizeEvent(parseEnvelope(envelope(event), bundle), bundle);
describe('authenticated Slack webhook protocol', () => {
const now = 1_793_000_000_000;
const signed = (body: Buffer, seconds = now / 1000) => ({
signature:
'v0=' +
createHmac('sha256', bundle.credentials.signingSecret!)
.update(`v0:${seconds}:`)
.update(body)
.digest('hex'),
timestamp: String(seconds),
contentType: 'application/json',
});
const challenge = Buffer.from(
JSON.stringify({
type: 'url_verification',
challenge: 'verified-challenge',
token: 'deprecated-token',
}),
);
test('authenticates a setup challenge before exposing only its bounded challenge value', () => {
expect(parseWebhookRequest(challenge, signed(challenge), bundle, false, now)).toEqual({
ok: true,
request: { kind: 'challenge', challenge: 'verified-challenge' },
});
expect(parseWebhookRequest(challenge, {}, bundle, false, now)).toEqual({
ok: false,
status: 401,
code: 'invalid_signature',
});
expect(
parseWebhookRequest(
Buffer.concat([challenge, Buffer.from(' ')]),
signed(challenge),
bundle,
false,
now,
),
).toMatchObject({ ok: false, status: 401 });
expect(
parseWebhookRequest(
challenge,
signed(challenge),
{ ...bundle, gateway: { ...bundle.gateway, transport: 'socket_mode' } },
false,
now,
),
).toMatchObject({ ok: false, status: 400 });
});
test('uses the server policy freshness window for every payload including challenges', () => {
const policy = { ...bundle, gateway: { ...bundle.gateway, signatureToleranceSeconds: 60 } };
expect(
parseWebhookRequest(challenge, signed(challenge, now / 1000 - 61), policy, false, now),
).toMatchObject({ ok: false, status: 401 });
expect(
parseWebhookRequest(challenge, signed(challenge, now / 1000 - 59), policy, false, now),
).toMatchObject({ ok: true });
});
test('retains callback app/team binding and enforces the distinct interactive form contract', () => {
const valid = Buffer.from(JSON.stringify(envelope({})));
expect(parseWebhookRequest(valid, signed(valid), bundle, false, now)).toMatchObject({
ok: true,
request: { kind: 'event' },
});
const foreign = Buffer.from(JSON.stringify({ ...envelope({}), api_app_id: 'A2' }));
expect(parseWebhookRequest(foreign, signed(foreign), bundle, false, now)).toMatchObject({
ok: false,
status: 400,
});
const form = Buffer.from(
new URLSearchParams({ payload: JSON.stringify({ type: 'view_submission' }) }).toString(),
);
expect(
parseWebhookRequest(
form,
{ ...signed(form), contentType: 'application/x-www-form-urlencoded' },
bundle,
true,
now,
),
).toMatchObject({ ok: true, request: { kind: 'interaction' } });
expect(parseWebhookRequest(challenge, signed(challenge), bundle, true, now)).toMatchObject({
ok: false,
status: 400,
});
const duplicate = Buffer.from(form.toString() + '&' + form.toString());
expect(
parseWebhookRequest(
duplicate,
{ ...signed(duplicate), contentType: 'application/x-www-form-urlencoded' },
bundle,
true,
now,
),
).toMatchObject({ ok: false, status: 400 });
});
});
describe('Slack message normalization', () => {
test('binds actor, admission identity and thread to the exact envelope', () => {
expect(normalize({ thread_ts: '1792999999.654321' })).toEqual({
kind: 'message',
admission: {
eventId: 'E1',
externalChannelId: 'C1',
externalThreadKey: 'C1:1792999999.654321',
externalMessageKey: 'C1:1793000000.123456',
actor: { teamId: 'T1', appId: 'A1', externalUserId: 'U1' },
input: 'hello',
},
});
});
test('new mentions use their message as the thread root; DMs require no mention', () => {
expect(normalize({})).toMatchObject({
admission: { externalThreadKey: 'C1:1793000000.123456' },
});
expect(normalize({ type: 'message', channel_type: 'im', text: 'hello' })).toMatchObject({
kind: 'message',
admission: { input: 'hello' },
});
});
test.each([
{ user: undefined },
{ user: 'B1' },
{ bot_id: 'other-bot' },
{ subtype: 'message_changed' },
{ subtype: 'bot_message' },
{ type: 'message', channel_type: 'channel' },
{ text: '<@B1> ' },
{ channel: undefined },
{ ts: undefined },
])('ignores bot, subtype, unrelated or incomplete message %p', (event) =>
expect(normalize(event)).toBeNull(),
);
test.each(['team_id', 'api_app_id'])('rejects another %s before normalization', (field) =>
expect(() => parseEnvelope({ ...envelope({}), [field]: 'other' }, bundle)).toThrow(),
);
test('native Stop carries its actor and occurrence time, not receipt time', () => {
expect(
normalize({
type: 'agent_session_stopped',
thread_ts: '1792999999.5',
event_ts: '1793000001.123456',
}),
).toEqual({
kind: 'stop',
externalChannelId: 'C1',
actor: { teamId: 'T1', appId: 'A1', externalUserId: 'U1' },
externalThreadKey: 'C1:1792999999.5',
eventAt: 1793000001123,
});
});
test('native Stop without actor is ignored and without thread/time is rejected', () => {
expect(normalize({ type: 'agent_session_stopped', user: undefined })).toBeNull();
expect(() => normalize({ type: 'agent_session_stopped' })).toThrow('Invalid native Stop');
});
test('reaction retains exact message handle and microsecond event ordering', () => {
expect(
normalize({
type: 'reaction_removed',
reaction: 'thumbsup',
item: { type: 'message', channel: 'C9', ts: '1792999998.2' },
event_ts: '1793000000.000001',
}),
).toEqual({
kind: 'reaction',
reaction: {
eventId: 'E1',
eventTimestampUs: 1793000000000001,
externalMessageKey: 'C9:1792999998.2',
externalUserId: 'U1',
reaction: 'thumbsup',
action: 'removed',
},
});
expect(
normalize({
type: 'reaction_added',
reaction: 'thumbsup',
item: { type: 'file', file: 'F1' },
event_ts: '1793000000.1',
}),
).toBeNull();
});
});
describe('Slack request authenticity', () => {
const body = Buffer.from('{"hello":"world"}');
const timestamp = '1793000000';
const signature =
'v0=' +
createHmac('sha256', 'test-secret').update(`v0:${timestamp}:`).update(body).digest('hex');
test('verifies exact raw bytes and a fresh timestamp', () =>
expect(verifySignature(body, signature, timestamp, 'test-secret', 300, 1793000000000)).toBe(
true,
));
test('rejects altered bytes, secret, expired or future timestamp', () => {
expect(
verifySignature(
Buffer.from('changed'),
signature,
timestamp,
'test-secret',
300,
1793000000000,
),
).toBe(false);
expect(verifySignature(body, signature, timestamp, 'wrong', 300, 1793000000000)).toBe(false);
expect(verifySignature(body, signature, timestamp, 'test-secret', 300, 1793000301000)).toBe(
false,
);
expect(verifySignature(body, signature, timestamp, 'test-secret', 300, 1792999699000)).toBe(
false,
);
});
test.each(['v0=x', 'v1=' + 'a'.repeat(64), '', 'v0=' + 'A'.repeat(64)])(
'rejects malformed signature %s without timing exception',
(invalid) =>
expect(verifySignature(body, invalid, timestamp, 'test-secret', 300, 1793000000000)).toBe(
false,
),
);
test.each(['1', '-1.1', '1.1234567', '9999999999.123456', '0.0', 'nan'])(
'rejects unsafe event timestamp %s',
(value) => expect(() => eventTimestampUs(value)).toThrow(),
);
test('pads microseconds exactly without floating-point rounding', () =>
expect(eventTimestampUs('1793000000.1')).toBe(1793000000100000));
});

View file

@ -0,0 +1,203 @@
import { z } from 'zod';
import { createHmac, timingSafeEqual } from 'node:crypto';
import type { ChannelRunAdmission, ChannelReactionEvent } from 'librechat-data-provider';
import type { ChannelBundle } from './types';
const address = z
.string()
.min(1)
.max(256)
.regex(/^[^:\s/\\]+$/);
const timestamp = z.string().regex(/^\d{1,10}\.\d{1,6}$/);
const eventSchema = z.object({
type: z.string(),
user: address.optional(),
bot_id: z.string().optional(),
subtype: z.string().optional(),
text: z.string().max(100000).optional(),
channel: address.optional(),
channel_type: z.string().optional(),
ts: timestamp.optional(),
thread_ts: timestamp.optional(),
event_ts: timestamp.optional(),
reaction: z.string().max(256).optional(),
item: z.unknown().optional(),
});
const envelopeSchema = z.object({
type: z.literal('event_callback'),
event_id: z.string().min(1).max(256),
team_id: address,
api_app_id: address,
event: eventSchema,
});
export type SlackEnvelope = z.infer<typeof envelopeSchema>;
export const SLACK_REQUEST_MAX_BYTES = 1024 * 1024;
export type SlackWebhookRequest =
| { kind: 'challenge'; challenge: string }
| { kind: 'event'; envelope: SlackEnvelope }
| { kind: 'interaction'; payload: unknown };
export type SlackWebhookResult =
| { ok: true; request: SlackWebhookRequest }
| {
ok: false;
status: 400 | 401 | 413;
code: 'invalid_signature' | 'invalid_payload' | 'payload_too_large';
};
export type NormalizedEvent =
| { kind: 'message'; admission: ChannelRunAdmission }
| { kind: 'reaction'; reaction: ChannelReactionEvent }
| {
kind: 'stop';
externalChannelId: string;
actor: ChannelRunAdmission['actor'];
externalThreadKey: string;
eventAt: number;
};
export function eventTimestampUs(value: string): number {
if (!/^\d{1,10}\.\d{1,6}$/.test(value)) throw new Error('Invalid Slack event timestamp');
const [seconds, fraction] = value.split('.');
const result = Number(seconds) * 1000000 + Number(fraction.padEnd(6, '0'));
if (!Number.isSafeInteger(result) || result <= 0)
throw new Error('Invalid Slack event timestamp');
return result;
}
export function verifySignature(
body: Buffer,
signature: string,
timestamp: string,
secret: string,
toleranceSecs: number,
now = Date.now(),
): boolean {
if (
!secret ||
!/^\d{1,12}$/.test(timestamp) ||
!/^v0=[a-f0-9]{64}$/.test(signature) ||
Math.abs(now / 1000 - Number(timestamp)) > toleranceSecs
)
return false;
const digest = createHmac('sha256', secret).update(`v0:${timestamp}:`).update(body).digest('hex');
return timingSafeEqual(Buffer.from(signature), Buffer.from('v0=' + digest));
}
export function parseEnvelope(body: unknown, bundle: ChannelBundle): SlackEnvelope {
const envelope = envelopeSchema.parse(body);
if (
envelope.team_id !== bundle.channel.slack.teamId ||
envelope.api_app_id !== bundle.channel.slack.appId
)
throw new Error('Slack workspace or application mismatch');
return envelope;
}
/** Every webhook payload, including installation challenges, must authenticate its original bytes. */
export function parseWebhookRequest(
body: Buffer,
headers: { signature?: unknown; timestamp?: unknown; contentType?: unknown },
bundle: ChannelBundle,
interactive: boolean,
now = Date.now(),
): SlackWebhookResult {
if (body.byteLength > SLACK_REQUEST_MAX_BYTES)
return { ok: false, status: 413, code: 'payload_too_large' };
if (
typeof headers.signature !== 'string' ||
typeof headers.timestamp !== 'string' ||
!verifySignature(
body,
headers.signature,
headers.timestamp,
bundle.credentials.signingSecret ?? '',
bundle.gateway.signatureToleranceSeconds,
now,
)
)
return { ok: false, status: 401, code: 'invalid_signature' };
if (bundle.gateway.transport !== 'webhook')
return { ok: false, status: 400, code: 'invalid_payload' };
try {
if (interactive) {
if (
typeof headers.contentType !== 'string' ||
headers.contentType.split(';')[0].trim() !== 'application/x-www-form-urlencoded'
)
return { ok: false, status: 400, code: 'invalid_payload' };
const form = new URLSearchParams(body.toString());
if (form.getAll('payload').length !== 1)
return { ok: false, status: 400, code: 'invalid_payload' };
const payload: unknown = JSON.parse(form.get('payload') ?? '');
return { ok: true, request: { kind: 'interaction', payload } };
}
const value: unknown = JSON.parse(body.toString());
const challenge = z
.object({ type: z.literal('url_verification'), challenge: z.string().min(1).max(2048) })
.safeParse(value);
if (challenge.success)
return { ok: true, request: { kind: 'challenge', challenge: challenge.data.challenge } };
return { ok: true, request: { kind: 'event', envelope: parseEnvelope(value, bundle) } };
} catch {
return { ok: false, status: 400, code: 'invalid_payload' };
}
}
export function normalizeEvent(
envelope: SlackEnvelope,
bundle: ChannelBundle,
): NormalizedEvent | null {
const event = envelope.event;
if (!event.user || event.bot_id || event.user === bundle.channel.slack.botUserId) return null;
const actor = {
teamId: envelope.team_id,
appId: envelope.api_app_id,
externalUserId: event.user,
};
if (event.type === 'reaction_added' || event.type === 'reaction_removed') {
const item = z
.object({ type: z.literal('message'), channel: address, ts: timestamp })
.safeParse(event.item);
if (!item.success || !event.reaction || !event.event_ts) return null;
return {
kind: 'reaction',
reaction: {
eventId: envelope.event_id,
eventTimestampUs: eventTimestampUs(event.event_ts),
externalMessageKey: `${item.data.channel}:${item.data.ts}`,
externalUserId: event.user,
reaction: event.reaction,
action: event.type === 'reaction_added' ? 'added' : 'removed',
},
};
}
if (event.type === 'agent_session_stopped') {
if (!event.channel || !event.thread_ts || !event.event_ts)
throw new Error('Invalid native Stop event');
return {
kind: 'stop',
externalChannelId: event.channel,
actor,
externalThreadKey: `${event.channel}:${event.thread_ts}`,
eventAt: Math.floor(eventTimestampUs(event.event_ts) / 1000),
};
}
if (!event.channel || !event.ts || event.subtype) return null;
let message = '';
if (event.type === 'app_mention')
message = event.text?.split(`<@${bundle.channel.slack.botUserId}>`).join('').trim() ?? '';
else if (event.type === 'message' && event.channel_type === 'im')
message = event.text?.trim() ?? '';
if (!message) return null;
return {
kind: 'message',
admission: {
eventId: envelope.event_id,
externalChannelId: event.channel,
externalThreadKey: `${event.channel}:${event.thread_ts ?? event.ts}`,
externalMessageKey: `${event.channel}:${event.ts}`,
actor,
input: message,
},
};
}

View file

@ -0,0 +1,467 @@
import { SlackClient, SlackWriteError, validSlackUploadURL } from './slack';
const config = { SLACK_API_BASE_URL: 'http://127.0.0.1:8080/api/', API_CALL_TIMEOUT_MS: 2000 };
const token = 'private-test-token';
const message = { channel: 'C123', text: 'Answer', thread_ts: '123.456' };
const success = (body: object) =>
new Response(JSON.stringify({ ok: true, ...body }), {
headers: { 'Content-Type': 'application/json' },
});
const receipt = () => success({ channel: 'C123', ts: '123.789' });
describe('SlackClient', () => {
test.each([
'service_unavailable',
'request_timeout',
'team_added_to_org',
'future_platform_outage',
])(
'treats %s conservatively across creates, idempotent updates and durable writes',
async (code) => {
const fixture = () =>
jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>().mockImplementation(
async () =>
new Response(JSON.stringify({ ok: false, error: code }), {
headers: { 'Content-Type': 'application/json', 'Retry-After': '0.001' },
}),
);
const create = fixture();
await expect(
new SlackClient(config, undefined, create).postMessage(token, message),
).rejects.toMatchObject({ outcome: 'unknown' });
expect(create).toHaveBeenCalledTimes(1);
const update = fixture();
await expect(
new SlackClient(config, undefined, update).updateMessage(token, {
...message,
ts: '123.456',
}),
).rejects.toMatchObject({ outcome: 'retryable' });
expect(update).toHaveBeenCalledTimes(3);
const durable = fixture();
await expect(
new SlackClient(config, undefined, durable).updateMessageOnce(token, {
...message,
ts: '123.456',
}),
).rejects.toMatchObject({ outcome: 'unknown' });
expect(durable).toHaveBeenCalledTimes(1);
},
);
test('posts once with safe rendering defaults and no token in its body', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(receipt());
const client = new SlackClient(config, undefined, transport);
await expect(client.postMessage(token, message)).resolves.toEqual({
channel: 'C123',
ts: '123.789',
});
expect(transport).toHaveBeenCalledTimes(1);
const [url, init] = transport.mock.calls[0];
expect(url).toBe(`${config.SLACK_API_BASE_URL}chat.postMessage`);
expect(new Headers(init?.headers).get('authorization')).toBe(`Bearer ${token}`);
expect(String(init?.body)).toContain('unfurl_links=false');
expect(String(init?.body)).not.toContain(token);
expect(init?.redirect).toBe('error');
});
test.each([
['network', () => Promise.reject(new Error('secret content')), 'unknown'],
['5xx', () => Promise.resolve(new Response('secret content', { status: 503 })), 'unknown'],
[
'HTTP timeout',
() => Promise.resolve(new Response('secret content', { status: 408 })),
'unknown',
],
[
'HTTP conflict',
() => Promise.resolve(new Response('secret content', { status: 409 })),
'unknown',
],
[
'HTTP too early',
() => Promise.resolve(new Response('secret content', { status: 425 })),
'unknown',
],
['invalid JSON', () => Promise.resolve(new Response('secret content')), 'unknown'],
[
'empty successful response',
() => Promise.resolve(new Response(null, { status: 204 })),
'unknown',
],
[
'internal error',
() => Promise.resolve(success({ ok: false, error: 'internal_error' })),
'unknown',
],
[
'rejected',
() => Promise.resolve(success({ ok: false, error: 'channel_not_found' })),
'permanent',
],
[
'HTTP rejection',
() => Promise.resolve(new Response('secret content', { status: 403 })),
'permanent',
],
[
'platform rate limited',
() =>
Promise.resolve(
new Response(JSON.stringify({ ok: false, error: 'ratelimited' }), {
headers: { 'Content-Type': 'application/json', 'Retry-After': '2' },
}),
),
'retryable',
],
[
'rate limited',
() => Promise.resolve(new Response('', { status: 429, headers: { 'retry-after': '2' } })),
'retryable',
],
[
'rate limited without header',
() => Promise.resolve(new Response('', { status: 429 })),
'retryable',
],
])('does not retry a create on %s', async (_name, response, outcome) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(response);
const warn = jest.fn();
const client = new SlackClient(config, { warn, info: jest.fn(), error: jest.fn() }, transport);
await expect(client.postMessage(token, message)).rejects.toMatchObject({ outcome });
expect(transport).toHaveBeenCalledTimes(1);
expect(JSON.stringify(warn.mock.calls)).not.toContain('secret');
expect(JSON.stringify(warn.mock.calls)).not.toContain(token);
});
test('retries only a known update and returns its exact handle', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockRejectedValueOnce(new Error('connection reset'))
.mockResolvedValue(success({ channel: 'C123', ts: '123.456' }));
await expect(
new SlackClient(config, undefined, transport).updateMessage(token, {
...message,
ts: '123.456',
}),
).resolves.toEqual({ channel: 'C123', ts: '123.456' });
expect(transport).toHaveBeenCalledTimes(2);
});
test('retries an idempotent update after a platform rate limit', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValueOnce(
new Response(JSON.stringify({ ok: false, error: 'ratelimited' }), {
headers: { 'Content-Type': 'application/json', 'Retry-After': '0.001' },
}),
)
.mockResolvedValue(success({ channel: 'C123', ts: '123.456' }));
await expect(
new SlackClient(config, undefined, transport).updateMessage(token, {
...message,
ts: '123.456',
}),
).resolves.toEqual({ channel: 'C123', ts: '123.456' });
expect(transport).toHaveBeenCalledTimes(2);
});
test.each(['2', '60'])(
'preserves platform Retry-After=%s for durable progress without a hidden retry',
async (seconds) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(
async () =>
new Response(JSON.stringify({ ok: false, error: 'ratelimited' }), {
headers: { 'Content-Type': 'application/json', 'Retry-After': seconds },
}),
);
await expect(
new SlackClient(config, undefined, transport).updateMessageOnce(token, {
...message,
ts: '123.456',
}),
).rejects.toMatchObject({ outcome: 'retryable', retryAfterMs: Number(seconds) * 1000 });
expect(transport).toHaveBeenCalledTimes(1);
},
);
test('does not shorten a long retry-after or sleep on the process', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(new Response('', { status: 429, headers: { 'retry-after': '60' } }));
await expect(
new SlackClient(config, undefined, transport).reaction(
token,
'add',
'C123',
'123.456',
'eyes',
),
).rejects.toMatchObject({ outcome: 'retryable', retryAfterMs: 60000 });
expect(transport).toHaveBeenCalledTimes(1);
});
test.each([
['network failure', () => Promise.reject(new Error('uncertain')), 'unknown'],
[
'internal failure',
() => Promise.resolve(success({ ok: false, error: 'internal_error' })),
'unknown',
],
['HTTP failure', () => Promise.resolve(new Response('', { status: 503 })), 'unknown'],
[
'rate limit',
() => Promise.resolve(new Response('', { status: 429, headers: { 'retry-after': '1' } })),
'retryable',
],
])('does not retry durable progress after %s', async (_name, response, outcome) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(response);
const client = new SlackClient(config, undefined, transport);
await expect(
client.updateMessageOnce(token, { ...message, ts: '123.456' }),
).rejects.toMatchObject({ outcome });
expect(transport).toHaveBeenCalledTimes(1);
});
test.each([
['add', 'already_reacted'],
['remove', 'no_reaction'],
] as const)('accepts the idempotent reaction %s state', async (action, error) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(success({ ok: false, error }));
await expect(
new SlackClient(config, undefined, transport).reaction(
token,
action,
'C123',
'123.456',
'eyes',
),
).resolves.toBeUndefined();
expect(transport).toHaveBeenCalledTimes(1);
});
test('invalid/mismatched message receipts are unknown and not replayed', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(success({ channel: 'OTHER', ts: '123.789' }));
await expect(
new SlackClient(config, undefined, transport).postMessage(token, message),
).rejects.toMatchObject({ outcome: 'unknown' });
expect(transport).toHaveBeenCalledTimes(1);
});
test.each(['invalid_blocks', 'invalid_attachments'])(
'uses text fallback only after explicit %s rejection',
async (error) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValueOnce(success({ ok: false, error }))
.mockResolvedValueOnce(receipt());
await expect(
new SlackClient(config, undefined, transport).deliverPart(token, {
...message,
blocks: [{ type: 'section', text: { type: 'mrkdwn', text: 'Answer' } }],
}),
).resolves.toEqual({ channel: 'C123', ts: '123.789' });
expect(transport).toHaveBeenCalledTimes(2);
const fallback = new URLSearchParams(String(transport.mock.calls[1][1]?.body));
expect(fallback.get('blocks')).toBe('[]');
expect(fallback.get('text')).toBe(message.text);
},
);
test.each([
() => Promise.reject(new Error('network failure')),
() => Promise.resolve(new Response('invalid_blocks')),
() => Promise.resolve(success({ ok: false, error: 'internal_error' })),
() => Promise.resolve(success({ ok: false, error: 'not_in_channel' })),
])('never uses rich fallback on ambiguous or unrelated failure %#', async (implementation) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(implementation);
await expect(
new SlackClient(config, undefined, transport).deliverPart(token, {
...message,
blocks: [{ type: 'section', text: { type: 'mrkdwn', text: 'Answer' } }],
}),
).rejects.toBeInstanceOf(SlackWriteError);
expect(transport).toHaveBeenCalledTimes(1);
});
test('does not replay a text-only payload or retry uncertain fallback', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValueOnce(success({ ok: false, error: 'invalid_blocks' }))
.mockResolvedValueOnce(success({ ok: false, error: 'invalid_blocks' }))
.mockRejectedValueOnce(new Error('network'));
const client = new SlackClient(config, undefined, transport);
await expect(client.deliverPart(token, message)).rejects.toMatchObject({
code: 'invalid_blocks',
});
expect(transport).toHaveBeenCalledTimes(1);
await expect(
client.deliverPart(token, { ...message, blocks: [{ type: 'divider' }] }),
).rejects.toMatchObject({ outcome: 'unknown' });
expect(transport).toHaveBeenCalledTimes(3);
});
test('rejects a native loader without the Stop subscription', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(
success({ warnings: ['missing_agent_session_stopped_event_subscription'] }),
);
await expect(
new SlackClient(config, undefined, transport).setSessionStatus(token, {
channel: 'C123',
threadTs: '123.456',
status: 'processing',
}),
).rejects.toMatchObject({ outcome: 'permanent' });
});
test.each([
['invalid_arguments', 'invalid_arguments'],
['private-untrusted-error', 'platform_error'],
])('retains only allowlisted diagnostic metadata for %s', async (error, reason) => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(success({ ok: false, error, secret: 'private-provider-payload' }));
const warn = jest.fn();
const client = new SlackClient(config, { info: jest.fn(), warn, error: jest.fn() }, transport);
await expect(
client.setSessionStatus(token, {
channel: 'C123',
threadTs: '123.456',
status: 'active',
title: 'private-title',
}),
).rejects.toThrow();
expect(warn).toHaveBeenCalledWith(
`slack_api_call_failed:agents.sessions.setStatus:200:${reason}`,
);
expect(JSON.stringify(warn.mock.calls)).not.toContain('private-');
expect(JSON.stringify(warn.mock.calls)).not.toContain(token);
});
test('uses no public reply or external response URL for ephemeral and modal writes', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockImplementation(async () => success({}));
const client = new SlackClient(config, undefined, transport);
await client.ephemeral(token, { ...message, user: 'U123' });
await client.openView(token, 'trigger', {
type: 'modal',
title: { type: 'plain_text', text: 'Review' },
blocks: [],
});
await client.updateView(
token,
'view',
{ type: 'modal', title: { type: 'plain_text', text: 'Review' }, blocks: [] },
'hash',
);
expect(transport.mock.calls.map(([url]) => url)).toEqual(
['chat.postEphemeral', 'views.open', 'views.update'].map(
(method) => config.SLACK_API_BASE_URL + method,
),
);
expect(String(transport.mock.calls[0][1]?.body)).toContain('user=U123');
});
test('cancels before an external write when the fence is already lost', async () => {
const transport = jest.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>();
await expect(
new SlackClient(config, undefined, transport).postMessage(
token,
message,
AbortSignal.abort(),
),
).rejects.toBeInstanceOf(SlackWriteError);
expect(transport).not.toHaveBeenCalled();
});
test('returns an allocated ID even for an invalid capability so it can be checkpointed', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValue(success({ file_id: 'F123', upload_url: 'https://evil.example/upload' }));
const client = new SlackClient(config, undefined, transport);
await expect(client.allocateArtifact(token, 'report.csv', 3)).resolves.toEqual({
fileId: 'F123',
uploadUrl: 'https://evil.example/upload',
});
await expect(
client.uploadArtifact('https://evil.example/upload', Buffer.from('abc')),
).rejects.toMatchObject({ outcome: 'permanent' });
expect(transport).toHaveBeenCalledTimes(1);
});
test('uploads bytes without bot credentials or redirects and validates the final receipt', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValueOnce(new Response('ok'))
.mockResolvedValueOnce(success({ files: [{ id: 'F123' }] }));
const client = new SlackClient(config, undefined, transport);
await client.uploadArtifact('https://files.slack.com/upload/capability', Buffer.from('abc'));
expect(new Headers(transport.mock.calls[0][1]?.headers).has('authorization')).toBe(false);
expect(transport.mock.calls[0][1]?.redirect).toBe('error');
await expect(
client.completeArtifact(token, {
channel: 'C123',
threadTs: '123.456',
fileId: 'F123',
filename: 'file.txt',
}),
).resolves.toBeUndefined();
});
test('holds uncertain binary upload and completion without implicit retries', async () => {
const transport = jest
.fn<ReturnType<typeof fetch>, Parameters<typeof fetch>>()
.mockResolvedValueOnce(new Response('', { status: 503 }))
.mockResolvedValueOnce(success({ files: [{ id: 'OTHER' }] }));
const client = new SlackClient(config, undefined, transport);
await expect(
client.uploadArtifact('https://files.slack.com/upload/capability', Buffer.from('abc')),
).rejects.toMatchObject({ outcome: 'unknown' });
await expect(
client.completeArtifact(token, {
channel: 'C123',
threadTs: '123.456',
fileId: 'F123',
filename: 'file.txt',
}),
).rejects.toMatchObject({ outcome: 'unknown' });
expect(transport).toHaveBeenCalledTimes(2);
});
});
describe('validSlackUploadURL', () => {
test.each(['https://files.slack.com/upload?q=capability', 'http://127.0.0.1:8080/upload'])(
'allows the existing production/fixture boundary: %s',
(url) => {
expect(validSlackUploadURL(url, config.SLACK_API_BASE_URL)).toBe(true);
},
);
test.each([
'https://files.slack.com.evil.example/a',
'https://files.slack.com:8443/a',
'https://user:pass@files.slack.com/a',
'https://files.slack.com/a#fragment',
'http://localhost:8080/a',
'http://127.0.0.1:9999/a',
'https://10.0.0.1/a',
'ftp://files.slack.com/a',
])('rejects %s', (url) => {
expect(validSlackUploadURL(url, config.SLACK_API_BASE_URL)).toBe(false);
});
});

View file

@ -0,0 +1,504 @@
import { isIP } from 'node:net';
import { setTimeout as delay } from 'node:timers/promises';
import { WebClient, LogLevel, WebAPIPlatformError, WebAPIRateLimitedError } from '@slack/web-api';
import type { Block, KnownBlock, View } from '@slack/types';
import type { WebAPICallResult } from '@slack/web-api';
import type { GatewayConfig } from './config';
import type { Logger } from './types';
export type SlackBlocks = (Block | KnownBlock)[];
export type SlackView = View;
export type SlackWriteOutcome = 'permanent' | 'retryable' | 'unknown';
export interface SlackMessage {
channel: string;
text: string;
thread_ts?: string;
blocks?: SlackBlocks;
}
export interface SlackMessageReceipt {
channel: string;
ts: string;
}
interface SlackResult extends WebAPICallResult {
channel?: unknown;
ts?: unknown;
warning?: unknown;
warnings?: unknown;
file_id?: unknown;
upload_url?: unknown;
files?: unknown;
}
export class SlackWriteError extends Error {
constructor(
readonly outcome: SlackWriteOutcome,
readonly retryAfterMs = 0,
readonly code: 'invalid_blocks' | 'invalid_attachments' | '' = '',
) {
super(`Slack write ${outcome}`);
this.name = 'SlackWriteError';
}
}
const updates = new Set([
'chat.update',
'reactions.add',
'reactions.remove',
'agents.sessions.setStatus',
]);
const methods = new Set([
...updates,
'chat.postMessage',
'chat.postEphemeral',
'conversations.open',
'views.open',
'views.update',
'files.getUploadURLExternal',
'files.completeUploadExternal',
]);
const diagnosticCodes = new Set([
'invalid_arguments',
'invalid_arg_name',
'invalid_post_type',
'invalid_json',
'invalid_blocks',
'invalid_attachments',
'missing_scope',
'not_allowed',
'channel_not_found',
'thread_not_found',
'invalid_thread_ts',
'invalid_status',
'invalid_auth',
'not_authed',
'unknown_method',
'method_not_supported_for_channel_type',
'internal_error',
'fatal_error',
'ratelimited',
'service_unavailable',
]);
/** Only explicit method/authorization rejections prove that Slack did not execute a write. */
const permanentRejections = new Set([
'invalid_arguments',
'invalid_arg_name',
'invalid_post_type',
'invalid_json',
'invalid_blocks',
'invalid_attachments',
'missing_scope',
'not_allowed',
'channel_not_found',
'thread_not_found',
'invalid_thread_ts',
'invalid_status',
'invalid_auth',
'not_authed',
'token_expired',
'token_revoked',
'account_inactive',
'no_permission',
'not_in_channel',
'is_archived',
'user_not_found',
'unknown_method',
'method_not_supported_for_channel_type',
]);
const permanentHttpRejections = new Set([400, 401, 403, 404, 405, 406, 410, 413, 414, 415, 422]);
const mutedLogger = {
debug() {},
info() {},
warn() {},
error() {},
setLevel() {},
setName() {},
getLevel: () => LogLevel.ERROR,
};
/** Signed upload capabilities stay in memory; only Slack or exact loopback fixtures may receive bytes. */
export function validSlackUploadURL(raw: string, apiBase: string): boolean {
try {
const url = new URL(raw);
if (url.username || url.password || url.hash) return false;
if (url.protocol === 'https:' && url.host === 'files.slack.com') return true;
const base = new URL(apiBase);
const host = url.hostname.replace(/^\[|\]$/g, '');
const loopback = isIP(host) && (host === '::1' || host.startsWith('127.'));
return Boolean(
loopback && url.protocol === 'http:' && base.protocol === 'http:' && url.host === base.host,
);
} catch {
return false;
}
}
export class SlackClient {
constructor(
private readonly config: Pick<GatewayConfig, 'SLACK_API_BASE_URL' | 'API_CALL_TIMEOUT_MS'>,
private readonly logger?: Logger,
private readonly transport: typeof fetch = fetch,
) {}
private async call(
token: string,
method: string,
payload: Record<string, unknown>,
signal?: AbortSignal,
once = false,
): Promise<SlackResult> {
const boundedSignal = AbortSignal.any([
AbortSignal.timeout(this.config.API_CALL_TIMEOUT_MS),
...(signal ? [signal] : []),
]);
for (let attempt = 0; ; attempt++) {
let status = 0;
let retryAfterMs = 0;
let validEnvelope = false;
const client = new WebClient(token, {
slackApiUrl: this.config.SLACK_API_BASE_URL.replace(/\/?$/, '/'),
retryConfig: { retries: 0 },
rejectRateLimitedCalls: true,
allowAbsoluteUrls: false,
logger: mutedLogger,
fetch: async (url, init) => {
const response = await this.transport(url, {
...init,
signal: boundedSignal,
redirect: 'error',
});
status = response.status;
const seconds = Number(response.headers.get('retry-after'));
retryAfterMs = Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 0;
const reader = response.body?.getReader();
const chunks: Uint8Array[] = [];
let bytes = 0;
try {
while (reader) {
const chunk = await reader.read();
if (chunk.done) break;
bytes += chunk.value.byteLength;
if (bytes > 1024 * 1024) throw new Error('Slack response too large');
chunks.push(chunk.value);
}
} finally {
await reader?.cancel();
reader?.releaseLock();
}
const text = Buffer.concat(chunks).toString('utf8');
try {
const envelope: { ok?: unknown; error?: unknown } = JSON.parse(text);
validEnvelope = Boolean(
envelope &&
(envelope.ok === true ||
(envelope.ok === false && typeof envelope.error === 'string')),
);
} catch {
/* The SDK maps malformed bodies to a platform error; that is not a rejection. */
}
return new Response(text, { status: response.status, headers: response.headers });
},
});
try {
boundedSignal.throwIfAborted();
return await client.apiCall(method, payload);
} catch (error) {
if (
error instanceof WebAPIPlatformError &&
((method === 'reactions.add' && error.data.error === 'already_reacted') ||
(method === 'reactions.remove' && error.data.error === 'no_reaction'))
)
return { ok: true };
const uncertain: SlackWriteOutcome = !once && updates.has(method) ? 'retryable' : 'unknown';
let outcome: SlackWriteOutcome = uncertain;
if (
status === 429 ||
error instanceof WebAPIRateLimitedError ||
(error instanceof WebAPIPlatformError &&
validEnvelope &&
error.data.error === 'ratelimited')
) {
outcome = 'retryable';
if (error instanceof WebAPIRateLimitedError) retryAfterMs = error.retryAfter * 1000;
} else if (error instanceof WebAPIPlatformError && validEnvelope) {
outcome = permanentRejections.has(error.data.error) ? 'permanent' : uncertain;
} else if (permanentHttpRejections.has(status)) {
outcome = 'permanent';
}
const code =
validEnvelope &&
error instanceof WebAPIPlatformError &&
(error.data.error === 'invalid_blocks' || error.data.error === 'invalid_attachments')
? error.data.error
: '';
const failure = new SlackWriteError(outcome, retryAfterMs, code);
const operation = methods.has(method) ? method : 'unknown';
let reason = status ? 'http_error' : 'transport_error';
if (boundedSignal.aborted) reason = 'cancelled';
if (error instanceof WebAPIPlatformError && validEnvelope)
reason = diagnosticCodes.has(error.data.error) ? error.data.error : 'platform_error';
this.logger?.warn(`slack_api_call_failed:${operation}:${status}:${reason}`);
const wait = retryAfterMs || 200 * 2 ** attempt;
if (
once ||
!updates.has(method) ||
outcome !== 'retryable' ||
attempt >= 2 ||
wait > 5000 ||
boundedSignal.aborted
)
throw failure;
try {
await delay(wait, undefined, { signal: boundedSignal });
} catch {
throw failure;
}
}
}
}
async postMessage(
token: string,
message: SlackMessage,
signal?: AbortSignal,
): Promise<SlackMessageReceipt> {
const result = await this.call(
token,
'chat.postMessage',
{
...message,
parse: 'none',
unfurl_links: false,
unfurl_media: false,
},
signal,
);
return this.messageReceipt(result, message.channel);
}
/** A rejected rich payload created nothing; only that explicit rejection permits a text fallback. */
async deliverPart(
token: string,
message: SlackMessage,
signal?: AbortSignal,
): Promise<SlackMessageReceipt> {
try {
return await this.postMessage(token, message, signal);
} catch (error) {
if (
!message.blocks?.length ||
!(error instanceof SlackWriteError) ||
(error.code !== 'invalid_blocks' && error.code !== 'invalid_attachments')
)
throw error;
return this.postMessage(token, { ...message, blocks: [] }, signal);
}
}
async updateMessage(
token: string,
message: SlackMessage & { ts: string },
signal?: AbortSignal,
): Promise<SlackMessageReceipt> {
const result = await this.call(token, 'chat.update', { ...message, parse: 'none' }, signal);
const receipt = this.messageReceipt(result, message.channel);
if (receipt.ts !== message.ts) throw new SlackWriteError('unknown');
return receipt;
}
/** Durable progress has its own persisted attempt; even an update must not hide another write. */
async updateMessageOnce(
token: string,
message: SlackMessage & { ts: string },
signal?: AbortSignal,
): Promise<SlackMessageReceipt> {
const result = await this.call(
token,
'chat.update',
{ ...message, parse: 'none' },
signal,
true,
);
const receipt = this.messageReceipt(result, message.channel);
if (receipt.ts !== message.ts) throw new SlackWriteError('unknown');
return receipt;
}
private messageReceipt(result: SlackResult, channel: string): SlackMessageReceipt {
if (
result.channel !== channel ||
typeof result.ts !== 'string' ||
!/^\d+\.\d+$/.test(result.ts)
)
throw new SlackWriteError('unknown');
return { channel, ts: result.ts };
}
async ephemeral(
token: string,
message: SlackMessage & { user: string },
signal?: AbortSignal,
): Promise<void> {
await this.call(
token,
'chat.postEphemeral',
{
...message,
parse: 'none',
unfurl_links: false,
unfurl_media: false,
},
signal,
);
}
async openConversation(token: string, user: string, signal?: AbortSignal): Promise<string> {
const result = await this.call(token, 'conversations.open', { users: user }, signal);
if (
!result.channel ||
typeof result.channel !== 'object' ||
!('id' in result.channel) ||
typeof result.channel.id !== 'string' ||
!result.channel.id
)
throw new SlackWriteError('unknown');
return result.channel.id;
}
async openView(
token: string,
triggerId: string,
view: SlackView,
signal?: AbortSignal,
): Promise<void> {
await this.call(token, 'views.open', { trigger_id: triggerId, view }, signal);
}
async updateView(
token: string,
viewId: string,
view: SlackView,
hash?: string,
signal?: AbortSignal,
): Promise<void> {
await this.call(
token,
'views.update',
{ view_id: viewId, view, ...(hash ? { hash } : {}) },
signal,
);
}
async reaction(
token: string,
action: 'add' | 'remove',
channel: string,
ts: string,
name: string,
signal?: AbortSignal,
): Promise<void> {
await this.call(token, `reactions.${action}`, { channel, timestamp: ts, name }, signal);
}
async setSessionStatus(
token: string,
session: {
channel: string;
threadTs: string;
status: 'processing' | 'suspended' | 'active' | 'closed';
title?: string;
},
signal?: AbortSignal,
): Promise<void> {
const result = await this.call(
token,
'agents.sessions.setStatus',
{
channel_id: session.channel,
thread_ts: session.threadTs,
status: session.status,
...(session.title?.trim()
? { title: [...session.title.trim()].slice(0, 200).join('') }
: {}),
},
signal,
);
if (
result.warning === 'missing_agent_session_stopped_event_subscription' ||
(Array.isArray(result.warnings) &&
result.warnings.includes('missing_agent_session_stopped_event_subscription'))
) {
this.logger?.warn('slack_native_status_missing_stop_subscription');
throw new SlackWriteError('permanent');
}
}
async allocateArtifact(
token: string,
filename: string,
bytes: number,
signal?: AbortSignal,
): Promise<{ fileId: string; uploadUrl: string }> {
const result = await this.call(
token,
'files.getUploadURLExternal',
{ filename, length: bytes },
signal,
);
if (
typeof result.file_id !== 'string' ||
!result.file_id ||
result.file_id.length > 128 ||
typeof result.upload_url !== 'string'
)
throw new SlackWriteError('unknown');
// Checkpoint the known ID before validating its upload capability.
return { fileId: result.file_id, uploadUrl: result.upload_url };
}
async uploadArtifact(url: string, data: Uint8Array, signal?: AbortSignal): Promise<void> {
if (!validSlackUploadURL(url, this.config.SLACK_API_BASE_URL))
throw new SlackWriteError('permanent');
try {
const response = await this.transport(url, {
method: 'POST',
body: Buffer.from(data),
headers: { 'Content-Type': 'application/octet-stream' },
redirect: 'error',
signal: AbortSignal.any([
AbortSignal.timeout(this.config.API_CALL_TIMEOUT_MS),
...(signal ? [signal] : []),
]),
});
await response.body?.cancel();
if (response.status !== 200) throw new SlackWriteError('unknown');
} catch {
throw new SlackWriteError('unknown');
}
}
async completeArtifact(
token: string,
file: { channel: string; threadTs: string; fileId: string; filename: string },
signal?: AbortSignal,
): Promise<void> {
const result = await this.call(
token,
'files.completeUploadExternal',
{
files: [{ id: file.fileId, title: file.filename }],
channel_id: file.channel,
thread_ts: file.threadTs,
},
signal,
);
if (
!Array.isArray(result.files) ||
result.files.length !== 1 ||
!result.files[0] ||
typeof result.files[0] !== 'object' ||
!('id' in result.files[0]) ||
result.files[0].id !== file.fileId
)
throw new SlackWriteError('unknown');
}
}

View file

@ -0,0 +1,39 @@
import type { ResponseReviewView } from 'librechat-data-provider';
export type { ChannelServiceBundle as ChannelBundle } from 'librechat-data-provider';
export type {
ChannelRunLease as Lease,
ChannelRunLeaseRenewal as LeaseRenewal,
ChannelResponseGrant as ResponseGrant,
ChannelResponsePreparation as ResponsePreparation,
} from 'librechat-data-provider';
export interface Review {
url: string;
actionId: string;
pendingAction?: ResponseReviewView['pendingAction'];
pendingDecision?: ResponseReviewView['pendingDecision'];
}
export interface BackgroundResponse {
id: string;
object: 'response';
model: string;
background: true;
store: true;
status:
| 'queued'
| 'in_progress'
| 'requires_action'
| 'completed'
| 'failed'
| 'incomplete'
| 'cancelled';
}
export interface Logger {
info(event: string): void;
warn(event: string): void;
error(event: string): void;
}
export const logger: Logger = {
info: (event) => console.info(JSON.stringify({ level: 'info', event })),
warn: (event) => console.warn(JSON.stringify({ level: 'warn', event })),
error: (event) => console.error(JSON.stringify({ level: 'error', event })),
};

View file

@ -0,0 +1,14 @@
{
"compilerOptions": {
"target": "ES2024",
"module": "ESNext",
"moduleResolution": "bundler",
"strict": true,
"noEmit": true,
"esModuleInterop": true,
"skipLibCheck": true,
"types": ["node", "jest"],
"lib": ["ES2024", "DOM", "DOM.Iterable"]
},
"include": ["src/**/*.ts"]
}

View file

@ -0,0 +1,12 @@
import { defineConfig } from 'tsdown';
export default defineConfig({
entry: ['src/client.ts', 'src/config.ts', 'src/events.ts', 'src/slack.ts'],
platform: 'node',
format: ['cjs'],
dts: false,
outDir: 'dist',
clean: true,
checks: { circularDependency: true },
deps: { alwaysBundle: () => true },
});

View file

@ -3403,6 +3403,44 @@ describe('channel erasure configuration', () => {
});
describe('complete channel operator configuration', () => {
it('owns gateway feature and signature policy with behavior-preserving defaults', () => {
expect(agentsEndpointSchema.parse({ channels: {} }).channels).toMatchObject({
transport: 'socket_mode',
nativeSessions: false,
lifecycleReactions: false,
signatureToleranceSeconds: 300,
});
expect(
configSchema.parse({
version: '1.2.1',
endpoints: {
agents: {
channels: {
enabled: true,
transport: 'webhook',
nativeSessions: true,
lifecycleReactions: true,
signatureToleranceSeconds: 60,
},
},
},
}).endpoints?.agents?.channels,
).toMatchObject({
transport: 'webhook',
nativeSessions: true,
lifecycleReactions: true,
signatureToleranceSeconds: 60,
});
});
it.each([
{ nativeSessions: 'true' },
{ lifecycleReactions: 'false' },
{ signatureToleranceSeconds: 0 },
{ signatureToleranceSeconds: 301 },
{ signatureToleranceSeconds: 1.5 },
])('rejects malformed shared gateway policy %p', (channels) => {
expect(agentsEndpointSchema.safeParse({ channels }).success).toBe(false);
});
it('keeps channel execution disabled by default and accepts explicit enablement with runtime limits', () => {
expect(agentsEndpointSchema.parse({ channels: {} }).channels?.enabled).toBe(false);
const parsed = configSchema.parse({

View file

@ -1233,6 +1233,26 @@ export const CHANNEL_DELIVERY_PARTS_HARD_MAX = 100;
export const CHANNEL_ARTIFACT_FILES_HARD_MAX = 20;
export const CHANNEL_ARTIFACT_READ_TIMEOUT_HARD_MAX_MS = 60_000;
/** One policy controls installation, ingress and optional Slack effects across gateway replicas. */
export const channelGatewayPolicySchema = z.object({
transport: z.enum(['socket_mode', 'webhook']),
nativeSessions: z.boolean(),
lifecycleReactions: z.boolean(),
signatureToleranceSeconds: z.number().int().min(1).max(300),
});
export type ChannelGatewayPolicy = z.infer<typeof channelGatewayPolicySchema>;
export const DEFAULT_CHANNEL_GATEWAY_POLICY: ChannelGatewayPolicy = {
transport: 'socket_mode',
nativeSessions: false,
lifecycleReactions: false,
signatureToleranceSeconds: 300,
};
export const CHANNEL_GATEWAY_POLICY_VERSION = 1;
export const channelGatewayWirePolicySchema = channelGatewayPolicySchema.extend({
version: z.literal(CHANNEL_GATEWAY_POLICY_VERSION),
});
export type ChannelGatewayWirePolicy = z.infer<typeof channelGatewayWirePolicySchema>;
/** Storage work per claim transaction; shared by configuration and injected storage defaults. */
export const channelStorageConfigSchema = z.object({
erasureBatchSize: z.number().int().min(1).max(1000).default(250),
@ -1253,7 +1273,18 @@ export type ChannelStorageConfig = z.infer<typeof channelStorageConfigSchema>;
/** Channel runtime and operator policy; execution remains disabled by default. */
export const channelConfigSchema = channelStorageConfigSchema.extend({
enabled: z.boolean().default(false),
transport: z.enum(['socket_mode', 'webhook']).default('socket_mode'),
transport: channelGatewayPolicySchema.shape.transport.default(
DEFAULT_CHANNEL_GATEWAY_POLICY.transport,
),
nativeSessions: channelGatewayPolicySchema.shape.nativeSessions.default(
DEFAULT_CHANNEL_GATEWAY_POLICY.nativeSessions,
),
lifecycleReactions: channelGatewayPolicySchema.shape.lifecycleReactions.default(
DEFAULT_CHANNEL_GATEWAY_POLICY.lifecycleReactions,
),
signatureToleranceSeconds: channelGatewayPolicySchema.shape.signatureToleranceSeconds.default(
DEFAULT_CHANNEL_GATEWAY_POLICY.signatureToleranceSeconds,
),
gatewayUrl: z.string().url().optional(),
ticketLifetimeMs: z
.number()

View file

@ -1,5 +1,14 @@
import type { AccountingBasis, ResponseAccounting } from './responseAccounting';
export const CHANNEL_DELIVERY_TEXT_MAX_CHARS = 40_000;
export const CHANNEL_DELIVERY_PRESENTATION_MAX_BYTES = 64_000;
/**
* A run is stored in one document (at most 16 MiB). JSON escaping can expand
* strings sixfold; eightfold leaves room for the service's lease envelope.
* This is a protocol safety ceiling, not an operator rendering preference.
*/
export const CHANNEL_RUN_MAX_JSON_BYTES = 128 * 1024 * 1024;
/** Verified transport identities are supplied by the gateway, never by Agent output. */
export interface ChannelRunActor {
teamId: string;
@ -162,3 +171,27 @@ export interface ChannelRunView {
receipts: ChannelDeliveryReceipt[];
cancellationRequested: boolean;
}
/** Renewal extends a fence's lifetime without returning another run snapshot. */
export interface ChannelRunLeaseRenewal {
fence: ChannelRunFence;
leaseExpiresAt: number;
}
export interface ChannelRunLease extends ChannelRunLeaseRenewal {
run: ChannelRunView;
}
/** Credentials are absent when cancellation settles before execution starts. */
export interface ChannelResponseGrant {
settled?: never;
apiKey: string;
requestKey: string;
responseId?: string;
request: {
model: string;
input: string;
background: true;
store: true;
previous_response_id?: string;
};
}
export type ChannelResponsePreparation = ChannelResponseGrant | { settled: ChannelRunView };

View file

@ -1,3 +1,22 @@
import type { ChannelGatewayWirePolicy } from '../config';
export const SLACK_CHANNEL_BOT_SCOPES = [
'app_mentions:read',
'chat:write',
'reactions:read',
'reactions:write',
'files:write',
'im:write',
'im:history',
] as const;
export const SLACK_CHANNEL_BOT_EVENTS = [
'app_mention',
'message.im',
'agent_session_stopped',
'reaction_added',
'reaction_removed',
] as const;
export interface AgentChannel {
channelId: string;
tenantId?: string;
@ -21,12 +40,28 @@ export interface ActivateAgentChannel {
export interface SlackChannelManifest {
display_information: { name: string };
features: { bot_user: { display_name: string } };
features: {
bot_user: { display_name: string };
agent_view: { agent_description: string };
app_home: { messages_tab_enabled: true; messages_tab_read_only_enabled: false };
};
oauth_config: { scopes: { bot: string[] } };
settings: {
socket_mode_enabled: boolean;
event_subscriptions: { bot_events: string[] };
event_subscriptions: { bot_events: string[]; request_url?: string };
interactivity: { is_enabled: boolean; request_url?: string };
org_deploy_enabled: boolean;
token_rotation_enabled: boolean;
};
}
/** Private service projection; transport policy is authoritative, not independently inferred by replicas. */
export interface ChannelServiceBundle {
channel: AgentChannel & {
revision: string;
slack: { teamId: string; appId: string; botUserId: string };
};
credentials: { botToken: string; signingSecret?: string };
agent: { id: string; name?: string };
gateway: ChannelGatewayWirePolicy;
}

View file

@ -1,6 +1,6 @@
import type { ChannelDeliveryOutcome, ChannelRunSnapshot } from 'librechat-data-provider';
import type { ChannelRunRecord } from '~/models/channelRun';
import { deliveryDisposition, snapshotPatch } from './channelProtocol';
import { deliveryDisposition, snapshotPatch, stopScopeKey } from './channelProtocol';
function run(): ChannelRunRecord {
return {
@ -131,3 +131,31 @@ it('rejects duplicate receipt identities instead of treating an incomplete plan
current.receipts[1] = current.receipts[0];
expect(() => deliveryDisposition(current, 100)).toThrow('invalid_transition');
});
it('separates stable provider Stop identity from versioned execution authority', () => {
const source = run();
const expected = stopScopeKey(source);
expect(
stopScopeKey({
...source,
agentId: 'other-agent',
principal: {
userId: 'other-user',
channelRevision: 'other-revision',
linkId: 'other-link',
linkRevision: 'other-link-revision',
},
}),
).toBe(expected);
for (const changed of [
{ ...source, tenantId: 'other-tenant' },
{ ...source, channelId: 'other-channel' },
{ ...source, admission: { ...source.admission, externalThreadKey: 'C:other' } },
{ ...source, admission: { ...source.admission, externalChannelId: 'other-C' } },
...['teamId', 'appId', 'externalUserId'].map((field) => ({
...source,
admission: { ...source.admission, actor: { ...source.admission.actor, [field]: 'other' } },
})),
])
expect(stopScopeKey(changed)).not.toBe(expected);
});

View file

@ -58,6 +58,16 @@ export function laneKey(scope: ChannelLaneScope): string {
linkId: scope.principal.linkId ?? null,
});
}
/** Provider occurrence identity survives changes to the versioned execution principal. */
export function stopScopeKey(scope: ChannelLaneScope): string {
return digest({
tenantId: scope.tenantId,
channelId: scope.channelId,
actor: scope.admission.actor,
thread: scope.admission.externalThreadKey,
externalChannelId: scope.admission.externalChannelId,
});
}
export const activeStates: string[] = [
'queued',
'executing',

View file

@ -222,6 +222,198 @@ it('deduplicates equivalent nested event fields regardless of object constructio
expect(await mongoose.models.ChannelRun.countDocuments({ tenantId })).toBe(1);
}));
it('pins a skewed Stop to its first cutoff and epoch across retries and replicas', () =>
scope(async () => {
const input = event();
await storage.admit(input, 100);
const first = (await storage.claim(tenantId, 'channel', 'first', 101, 10))!;
const observed = await storage.observeThreadStop(input, 120, 105);
expect(observed).toMatchObject({
before: 105,
run: { runId: first.runId, leaseEpoch: first.leaseEpoch },
});
const replica = createChannelRunStorage(mongoose);
expect(await replica.observeThreadStop(input, 120, 110)).toMatchObject({
before: 105,
run: { leaseEpoch: first.leaseEpoch },
});
const replacement = (await storage.claim(tenantId, 'channel', 'second', 112, 1000))!;
expect(replacement.leaseEpoch).toBeGreaterThan(first.leaseEpoch);
expect(await replica.observeThreadStop(input, 120, 118)).toBeNull();
expect(
await storage.requestCancel(input, first.runId, { epoch: first.leaseEpoch, before: 105 }),
).toBe(false);
expect(await replica.observeThreadStop(input, 119, 121)).toBeNull();
const fresh = await replica.observeThreadStop(input, 122, 123);
expect(fresh).toMatchObject({
before: 122,
run: { runId: replacement.runId, leaseEpoch: replacement.leaseEpoch },
});
expect(
await storage.requestCancel(input, fresh!.run.runId, {
epoch: fresh!.run.leaseEpoch,
before: fresh!.before,
}),
).toBe(true);
}));
it('retains an empty Stop observation before lane creation and never targets a later run', () =>
scope(async () => {
const input = event();
expect(await storage.observeThreadStop(input, 120, 100)).toBeNull();
const admitted = await storage.admit(input, 101);
expect(admitted.run.sequence).toBe(1);
const first = (await storage.claim(tenantId, 'channel', 'first', 102, 1000))!;
expect(await createChannelRunStorage(mongoose).observeThreadStop(input, 120, 110)).toBeNull();
expect(await storage.observeThreadStop(input, 119, 121)).toBeNull();
expect((await storage.read(tenantId, 'channel', first.runId))?.cancellationRequested).toBe(
false,
);
expect(await storage.observeThreadStop(input, 122, 123)).toMatchObject({
run: { runId: first.runId },
before: 122,
});
}));
it('retains the first run target after it completes instead of cancelling the next actor turn', () =>
scope(async () => {
const input = event();
await storage.admit(input, 100);
const first = (await storage.claim(tenantId, 'channel', 'first', 101, 1000))!;
expect(await storage.observeThreadStop(input, 120, 105)).toMatchObject({
run: { runId: first.runId },
});
// Model the atomic finish transition; the assertion concerns durable Stop replay, not execution.
await mongoose.models.ChannelRun.updateOne(
{ runId: first.runId },
{ $set: { state: 'delivered' } },
);
await mongoose.models.ChannelLane.updateOne(
{ activeRunId: first.runId },
{ $unset: { activeRunId: '' } },
);
await storage.admit(event('next'), 106);
const next = (await storage.claim(tenantId, 'channel', 'second', 107, 1000))!;
expect(next.runId).not.toBe(first.runId);
expect(await storage.observeThreadStop(input, 120, 115)).toBeNull();
expect((await storage.read(tenantId, 'channel', next.runId))?.cancellationRequested).toBe(
false,
);
}));
it('keeps one external Stop observation across changes to the linked execution principal', () =>
scope(async () => {
const first = event('first');
const second = { ...event('second'), principal: { ...first.principal, userId: 'new-account' } };
await storage.admit(first, 100);
const a = (await storage.claim(tenantId, 'channel', 'a', 101, 1000))!;
expect(await storage.observeThreadStop(first, 120, 105)).toMatchObject({
run: { runId: a.runId },
});
await storage.admit(second, 106);
const b = (await storage.claim(tenantId, 'channel', 'b', 107, 1000))!;
expect(await storage.observeThreadStop(second, 120, 110)).toBeNull();
expect(await storage.observeThreadStop(second, 119, 110)).toBeNull();
expect((await storage.read(tenantId, 'channel', b.runId))?.cancellationRequested).toBe(false);
expect(await storage.observeThreadStop(second, 121, 111)).toMatchObject({
run: { runId: b.runId },
before: 111,
});
expect(
await mongoose.models.ChannelLane.countDocuments({
tenantId,
stopObservation: { $exists: true },
}),
).toBe(1);
expect(await storage.observeThreadStop(first, 120, 112)).toBeNull();
}));
it('serializes duplicate Stop observations across principal lanes without rebinding either target', () =>
scope(async () => {
const first = event('first');
const second = { ...event('second'), principal: { ...first.principal, userId: 'new-account' } };
await storage.admit(first, 100);
await storage.claim(tenantId, 'channel', 'a', 101, 1000);
await storage.admit(second, 102);
await storage.claim(tenantId, 'channel', 'b', 103, 1000);
const replica = createChannelRunStorage(mongoose);
const observations = await Promise.all([
storage.observeThreadStop(first, 120, 105),
replica.observeThreadStop(second, 120, 106),
]);
expect(observations.filter(Boolean)).toHaveLength(1);
expect(
await mongoose.models.ChannelLane.countDocuments({
tenantId,
stopObservation: { $exists: true },
}),
).toBe(1);
const replay = await Promise.all([
storage.observeThreadStop(first, 120, 108),
replica.observeThreadStop(second, 120, 109),
]);
expect(replay.filter(Boolean)).toHaveLength(1);
expect(replay.find(Boolean)?.run.runId).toBe(observations.find(Boolean)?.run.runId);
expect(replay.find(Boolean)?.before).toBe(observations.find(Boolean)?.before);
}));
it('preserves an absent Stop target through a principal transition', () =>
scope(async () => {
const first = event();
expect(await storage.observeThreadStop(first, 120, 100)).toBeNull();
const second = { ...event('next'), principal: { ...first.principal, userId: 'new-account' } };
await storage.admit(second, 101);
const claimed = (await storage.claim(tenantId, 'channel', 'b', 102, 1000))!;
expect(await storage.observeThreadStop(second, 120, 110)).toBeNull();
expect((await storage.read(tenantId, 'channel', claimed.runId))?.cancellationRequested).toBe(
false,
);
expect(await storage.observeThreadStop(second, 121, 111)).toMatchObject({
run: { runId: claimed.runId },
});
}));
it('does not couple Stop occurrences for distinct external actors', () =>
scope(async () => {
const first = event('first', 'one');
const second = event('second', 'two');
await storage.admit(first, 100);
const a = (await storage.claim(tenantId, 'channel', 'a', 101, 1000))!;
await storage.admit(second, 102);
const b = (await storage.claim(tenantId, 'channel', 'b', 103, 1000))!;
const observations = await Promise.all([
storage.observeThreadStop(first, 120, 105),
storage.observeThreadStop(second, 120, 106),
]);
expect(observations.map((o) => o?.run.runId)).toEqual([a.runId, b.runId]);
}));
it('owns legacy empty Stop lanes for erasure and cannot recreate them after account deletion', () =>
scope(async () => {
const user = await mongoose.models.User.create({
email: 'stop-erasure@example.com',
provider: 'local',
tenantId,
});
const input = { ...event(), principal: { ...event().principal, userId: String(user._id) } };
await storage.admit(input, 100);
// Retained legacy lane after run cleanup, before lane ownership was recorded.
await mongoose.models.ChannelRun.deleteMany({ tenantId });
await mongoose.models.ChannelLane.updateMany(
{ userId: input.principal.userId },
{ $unset: { userId: 1 } },
);
await storage.observeThreadStop(input, 120, 101);
await createUserMethods(mongoose).deleteUserById(input.principal.userId);
expect(await storage.observeThreadStop(input, 121, 110)).toBeNull();
expect(
await mongoose.models.ChannelLane.countDocuments({
tenantId,
userId: input.principal.userId,
}),
).toBe(0);
}));
it('atomically rejects a delayed cancellation after the observed run is reclaimed', () =>
scope(async () => {
await storage.admit(event(), 100);
@ -1280,6 +1472,7 @@ it('refuses every named underscore context before it can read or mutate tenantle
() => storage.listPendingMetadata(undefined, 10),
() => storage.requestCancel(input, run.runId),
() => storage.readActiveThread(input, 101),
() => storage.observeThreadStop(input, 101, 102),
() => storage.findDeliveredReply(input, 'C1:reply'),
])
await expect(tenantStorage.run({ tenantId: '_' }, async () => action())).rejects.toThrow(

View file

@ -18,6 +18,7 @@ import type { StoredResponseRecord } from '~/models/response';
import {
digest,
laneKey,
stopScopeKey,
activeStates,
assertReconciliation,
assertDeliveryEvidence,
@ -28,7 +29,7 @@ import {
leaseDeadline,
ChannelRunConflict,
} from './channelProtocol';
import { initializeChannelScope, touchChannelAuthority } from './channelScope';
import { initializeChannelScope, touchChannelAuthority, touchChannelScope } from './channelScope';
import { prepareChannelOwnerAdmission } from './channelOwner';
import { createChannelIndexGate } from './channelIndexes';
import { responseOwnerFilter } from './responseScope';
@ -74,6 +75,12 @@ export interface ChannelRunStorage {
): Promise<boolean>;
read(tenantId: string, channelId: string, runId: string): Promise<ChannelRunRecord | null>;
readActiveThread(scope: ChannelLaneScope, before: number): Promise<ChannelRunRecord | null>;
/** Persist one click's immutable target/cutoff; null means no eligible retained target. */
observeThreadStop(
scope: ChannelLaneScope,
eventAt: number,
observedAt: number,
): Promise<{ run: ChannelRunRecord; before: number } | null>;
prepareExecution(
tenantId: string,
fence: ChannelRunFence,
@ -1054,6 +1061,100 @@ export function createChannelRunStorage(
})
.lean();
},
async observeThreadStop(scope, eventAt, observedAt) {
if (!Number.isSafeInteger(eventAt) || eventAt <= 0 || !Number.isFinite(observedAt))
throw new ChannelRunConflict('invalid_transition');
const { tenantId, channelId } = scope;
const laneId = laneKey(scope);
const scopeId = stopScopeKey(scope);
const ownerAdmission = await prepareChannelOwnerAdmission(mongoose, {
userId: scope.principal.userId,
tenantId: tenantId === '_' ? undefined : tenantId,
});
await initializeChannelScope(mongoose, tenantId, channelId);
return transaction(async (session) => {
// Serialize occurrence ownership across principal lanes, including empty targets.
// This records an observation, not permission; the caller still checks live authority.
if (
!(await ownerAdmission(session)) ||
!(await touchChannelScope(mongoose, tenantId, channelId, session))
)
return null;
const previousLane = await lanes()
.findOne({ tenantId, channelId, 'stopObservation.scopeId': scopeId })
.session(session)
.lean();
let observation = previousLane?.stopObservation;
if (
observation &&
(observation.eventAt > eventAt ||
(observation.eventAt === eventAt && previousLane?.laneId !== laneId))
)
return null;
if (!observation || observation.eventAt < eventAt) {
const lane =
previousLane?.laneId === laneId
? previousLane
: await lanes().findOne({ tenantId, channelId, laneId }).session(session).lean();
const before = Math.min(eventAt, observedAt);
const run = lane?.activeRunId
? await runs()
.findOne({
tenantId,
channelId,
laneId,
runId: lane.activeRunId,
state: { $in: ['queued', 'executing', 'requires_action'] },
claimCheckedAt: { $lte: before },
receivedAt: { $lte: before },
})
.session(session)
.lean()
: null;
observation = {
scopeId,
eventAt,
before,
...(run ? { runId: run.runId, epoch: run.leaseEpoch } : {}),
};
// Persist even absence: a retried click must not acquire work admitted later.
// A newer click moves its one bounded observation to the current owning lane.
if (previousLane && previousLane.laneId !== laneId) {
await lanes().updateOne(
{ tenantId, channelId, laneId: previousLane.laneId },
{ $unset: { stopObservation: 1 } },
{ session },
);
}
await lanes().updateOne(
{ tenantId, laneId },
{
$set: { stopObservation: observation, userId: scope.principal.userId },
$setOnInsert: {
channelId,
nextSequence: 0,
},
},
{ upsert: true, session },
);
}
if (!observation.runId || observation.epoch == null) return null;
const run = await runs()
.findOne({
tenantId,
channelId,
laneId,
runId: observation.runId,
leaseEpoch: observation.epoch,
state: { $in: ['queued', 'executing', 'requires_action'] },
claimCheckedAt: { $lte: observation.before },
receivedAt: { $lte: observation.before },
})
.session(session)
.lean();
return run ? { run, before: observation.before } : null;
});
},
async requestCancel(scope, runId, observed) {
const { tenantId, channelId } = scope;
if (

View file

@ -45,6 +45,13 @@ export interface ChannelLaneRecord {
activeRunId?: string;
conversationId?: string;
responseId?: string;
stopObservation?: {
scopeId: string;
eventAt: number;
before: number;
runId?: string;
epoch?: number;
};
}
export function createChannelRunModel(
@ -169,10 +176,26 @@ export function createChannelLaneModel(
activeRunId: String,
conversationId: String,
responseId: String,
stopObservation: {
type: new Schema(
{
scopeId: { type: String, required: true },
eventAt: Number,
before: Number,
runId: String,
epoch: Number,
},
{ _id: false },
),
},
},
{ timestamps: true },
);
schema.index({ tenantId: 1, laneId: 1 }, { unique: true });
schema.index(
{ tenantId: 1, channelId: 1, 'stopObservation.scopeId': 1 },
{ partialFilterExpression: { 'stopObservation.scopeId': { $type: 'string' } } },
);
schema.index({ tenantId: 1, userId: 1 });
applyTenantIsolation(schema);
return mongoose.models.ChannelLane ?? mongoose.model<ChannelLaneRecord>('ChannelLane', schema);

View file

@ -35,6 +35,7 @@ const SOURCE_ROOTS = [
'packages/data-schemas/src',
'packages/client/src',
'packages/chat/src',
'packages/channel-gateway/src',
];
const SOURCE_DIRS = SOURCE_ROOTS.map((rel) => resolve(ROOT, rel));