From 5081850280a1189243b6ffef7c69671f6fa93e8f Mon Sep 17 00:00:00 2001 From: Dustin Healy <54083382+dustinhealy@users.noreply.github.com> Date: Tue, 10 Nov 2026 21:04:05 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=9B=A0=EF=B8=8F=20feat:=20Add=20Slack=20G?= =?UTF-8?q?ateway=20Transport=20Adapters=20(#17616)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🛠️ 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 --- .github/workflows/channel-gateway.yml | 52 ++ .github/workflows/codegraph-e2e-votes.yml | 1 + .github/workflows/frontend-review.yml | 2 + .github/workflows/lighthouse.yml | 2 + .github/workflows/playwright-bombadil.yml | 1 + .github/workflows/playwright-mock.yml | 3 + .github/workflows/static-checks.yml | 2 + .../Agents/__tests__/Channels.spec.tsx | 12 +- e2e/specs/mock/scenarios/turbo-cache.spec.ts | 40 +- package-lock.json | 668 +++++++++++++++++- package.json | 2 +- packages/api/src/channels/authority.spec.ts | 163 ++++- packages/api/src/channels/manifest.spec.ts | 37 +- packages/api/src/channels/manifest.ts | 47 +- packages/api/src/channels/runs.ts | 53 +- packages/api/src/channels/service.spec.ts | 16 +- packages/api/src/channels/service.ts | 52 +- packages/api/src/channels/types.ts | 8 +- .../src/endpoints/config/endpoints.spec.ts | 11 +- packages/channel-gateway/README.md | 24 + packages/channel-gateway/jest.config.mjs | 17 + packages/channel-gateway/package.json | 37 + packages/channel-gateway/src/client.spec.ts | 533 ++++++++++++++ packages/channel-gateway/src/client.ts | 450 ++++++++++++ packages/channel-gateway/src/config.spec.ts | 164 +++++ packages/channel-gateway/src/config.ts | 98 +++ packages/channel-gateway/src/events.spec.ts | 271 +++++++ packages/channel-gateway/src/events.ts | 203 ++++++ packages/channel-gateway/src/slack.spec.ts | 467 ++++++++++++ packages/channel-gateway/src/slack.ts | 504 +++++++++++++ packages/channel-gateway/src/types.ts | 39 + packages/channel-gateway/tsconfig.json | 14 + packages/channel-gateway/tsdown.config.mjs | 12 + packages/data-provider/src/config.spec.ts | 38 + packages/data-provider/src/config.ts | 33 +- .../data-provider/src/types/channelRuns.ts | 33 + packages/data-provider/src/types/channels.ts | 39 +- .../src/methods/channelProtocol.spec.ts | 30 +- .../src/methods/channelProtocol.ts | 10 + .../src/methods/channelRun.spec.ts | 193 +++++ .../data-schemas/src/methods/channelRun.ts | 103 ++- .../data-schemas/src/models/channelRun.ts | 23 + scripts/sort-imports.mts | 1 + 43 files changed, 4399 insertions(+), 109 deletions(-) create mode 100644 .github/workflows/channel-gateway.yml create mode 100644 packages/channel-gateway/README.md create mode 100644 packages/channel-gateway/jest.config.mjs create mode 100644 packages/channel-gateway/package.json create mode 100644 packages/channel-gateway/src/client.spec.ts create mode 100644 packages/channel-gateway/src/client.ts create mode 100644 packages/channel-gateway/src/config.spec.ts create mode 100644 packages/channel-gateway/src/config.ts create mode 100644 packages/channel-gateway/src/events.spec.ts create mode 100644 packages/channel-gateway/src/events.ts create mode 100644 packages/channel-gateway/src/slack.spec.ts create mode 100644 packages/channel-gateway/src/slack.ts create mode 100644 packages/channel-gateway/src/types.ts create mode 100644 packages/channel-gateway/tsconfig.json create mode 100644 packages/channel-gateway/tsdown.config.mjs diff --git a/.github/workflows/channel-gateway.yml b/.github/workflows/channel-gateway.yml new file mode 100644 index 0000000000..031d6fddf1 --- /dev/null +++ b/.github/workflows/channel-gateway.yml @@ -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 diff --git a/.github/workflows/codegraph-e2e-votes.yml b/.github/workflows/codegraph-e2e-votes.yml index 5928d36265..4ce57125ef 100644 --- a/.github/workflows/codegraph-e2e-votes.yml +++ b/.github/workflows/codegraph-e2e-votes.yml @@ -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') }} diff --git a/.github/workflows/frontend-review.yml b/.github/workflows/frontend-review.yml index 652f48676d..5bddf5bd18 100644 --- a/.github/workflows/frontend-review.yml +++ b/.github/workflows/frontend-review.yml @@ -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 diff --git a/.github/workflows/lighthouse.yml b/.github/workflows/lighthouse.yml index 2231960531..9f8518aed9 100644 --- a/.github/workflows/lighthouse.yml +++ b/.github/workflows/lighthouse.yml @@ -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 diff --git a/.github/workflows/playwright-bombadil.yml b/.github/workflows/playwright-bombadil.yml index 7eed3ab9dd..cf10b39163 100644 --- a/.github/workflows/playwright-bombadil.yml +++ b/.github/workflows/playwright-bombadil.yml @@ -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') }} diff --git a/.github/workflows/playwright-mock.yml b/.github/workflows/playwright-mock.yml index 02b2313210..274b4b6f9a 100644 --- a/.github/workflows/playwright-mock.yml +++ b/.github/workflows/playwright-mock.yml @@ -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') }} diff --git a/.github/workflows/static-checks.yml b/.github/workflows/static-checks.yml index 1da85a7b9c..f4a3795300 100644 --- a/.github/workflows/static-checks.yml +++ b/.github/workflows/static-checks.yml @@ -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 }} diff --git a/client/src/components/SidePanel/Agents/__tests__/Channels.spec.tsx b/client/src/components/SidePanel/Agents/__tests__/Channels.spec.tsx index 5beb1c6414..5c94dc90e1 100644 --- a/client/src/components/SidePanel/Agents/__tests__/Channels.spec.tsx +++ b/client/src/components/SidePanel/Agents/__tests__/Channels.spec.tsx @@ -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, }, diff --git a/e2e/specs/mock/scenarios/turbo-cache.spec.ts b/e2e/specs/mock/scenarios/turbo-cache.spec.ts index c020ce21b3..8d70705a53 100644 --- a/e2e/specs/mock/scenarios/turbo-cache.spec.ts +++ b/e2e/specs/mock/scenarios/turbo-cache.spec.ts @@ -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; - } -).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 = {}, - filters: string[] = SUITES, + discoverAll = false, ): Map { 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): DryTask[] { + return [...tasks.values()].filter((entry) => entry.taskId.endsWith('#test:ci')); +} + function get(tasks: Map, 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)); } }); }); diff --git a/package-lock.json b/package-lock.json index c120cf01dd..560b3c2d7b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -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" + } } } } diff --git a/package.json b/package.json index c4c647af22..268c6d5ba3 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/packages/api/src/channels/authority.spec.ts b/packages/api/src/channels/authority.spec.ts index 51c2be55eb..86b00ee34a 100644 --- a/packages/api/src/channels/authority.spec.ts +++ b/packages/api/src/channels/authority.spec.ts @@ -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); + })(), +); diff --git a/packages/api/src/channels/manifest.spec.ts b/packages/api/src/channels/manifest.spec.ts index e4c54bc27e..b85a0cb77e 100644 --- a/packages/api/src/channels/manifest.spec.ts +++ b/packages/api/src/channels/manifest.spec.ts @@ -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/); }); diff --git a/packages/api/src/channels/manifest.ts b/packages/api/src/channels/manifest.ts index 5d8c0798c7..4f0104a887 100644 --- a/packages/api/src/channels/manifest.ts +++ b/packages/api/src/channels/manifest.ts @@ -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: { diff --git a/packages/api/src/channels/runs.ts b/packages/api/src/channels/runs.ts index f416b461e2..3f7ed81315 100644 --- a/packages/api/src/channels/runs.ts +++ b/packages/api/src/channels/runs.ts @@ -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[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); diff --git a/packages/api/src/channels/service.spec.ts b/packages/api/src/channels/service.spec.ts index a2206d04c5..52e6d6630d 100644 --- a/packages/api/src/channels/service.spec.ts +++ b/packages/api/src/channels/service.spec.ts @@ -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 () => { diff --git a/packages/api/src/channels/service.ts b/packages/api/src/channels/service.ts index bbcaf9866f..feb0e62d5f 100644 --- a/packages/api/src/channels/service.ts +++ b/packages/api/src/channels/service.ts @@ -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; + config: ( + req: Request, + channel?: AgentChannelRecord, + ) => Promise | undefined>; getAgent: (agentId: string) => Promise<{ id: string; name?: string | null } | null>; deleteApiKey: (id: string, userId: string) => Promise; verifySlackToken: (token: string) => Promise; @@ -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) => { diff --git a/packages/api/src/channels/types.ts b/packages/api/src/channels/types.ts index 728d5fbe68..8706c1279f 100644 --- a/packages/api/src/channels/types.ts +++ b/packages/api/src/channels/types.ts @@ -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, + handler: ( + req: Request, + res: Response, + channel: AgentChannelRecord, + config: ChannelConfig, + ) => Promise, ) => RequestHandler; diff --git a/packages/api/src/endpoints/config/endpoints.spec.ts b/packages/api/src/endpoints/config/endpoints.spec.ts index 086558630e..cd4e525859 100644 --- a/packages/api/src/endpoints/config/endpoints.spec.ts +++ b/packages/api/src/endpoints/config/endpoints.spec.ts @@ -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 }, diff --git a/packages/channel-gateway/README.md b/packages/channel-gateway/README.md new file mode 100644 index 0000000000..387b07f788 --- /dev/null +++ b/packages/channel-gateway/README.md @@ -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. diff --git a/packages/channel-gateway/jest.config.mjs b/packages/channel-gateway/jest.config.mjs new file mode 100644 index 0000000000..df0da8a916 --- /dev/null +++ b/packages/channel-gateway/jest.config.mjs @@ -0,0 +1,17 @@ +export default { + testEnvironment: 'node', + testMatch: ['/src/**/*.spec.ts'], + transform: { + '\\.[jt]s$': [ + 'babel-jest', + { + presets: [ + ['@babel/preset-env', { targets: { node: 'current' } }], + '@babel/preset-typescript', + ], + }, + ], + }, + testTimeout: 15000, + restoreMocks: true, +}; diff --git a/packages/channel-gateway/package.json b/packages/channel-gateway/package.json new file mode 100644 index 0000000000..c80dba4f9a --- /dev/null +++ b/packages/channel-gateway/package.json @@ -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" +} diff --git a/packages/channel-gateway/src/client.spec.ts b/packages/channel-gateway/src/client.spec.ts new file mode 100644 index 0000000000..04d435e896 --- /dev/null +++ b/packages/channel-gateway/src/client.spec.ts @@ -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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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({ + 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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>(); + 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, Parameters>(); + 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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>(); + 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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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({ + 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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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' }, + ]); +}); diff --git a/packages/channel-gateway/src/client.ts b/packages/channel-gateway/src/client.ts new file mode 100644 index 0000000000..c35a7a4702 --- /dev/null +++ b/packages/channel-gateway/src/client.ts @@ -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, +): 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 { + 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 { + const headers: Record = { + 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(response: Response, empty?: T): Promise { + 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(path: string, body?: object, signal?: AbortSignal, empty?: T): Promise { + return this.decode(await this.raw(path, body, signal), empty); + } + async channel(signal?: AbortSignal): Promise { + const value = await this.request( + `/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(suffix: string, body: object, signal?: AbortSignal, empty?: T): Promise { + return this.request(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 { + const result = await this.runs( + `/${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 { + const lease = await this.runs('/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 { + const lease = await this.runs( + `/${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 { + return this.runs(`/${encodeURIComponent(fence.runId)}/yield`, { fence }, signal, null); + } + async prepare(fence: ChannelRunFence, signal?: AbortSignal): Promise { + const result = await this.runs( + `/${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 { + 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 { + const receipt = await this.runs( + `/${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( + actor: string, + suffix = '', + body?: object, + signal?: AbortSignal, + ): Promise { + const result = await this.request>( + `${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 { + 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( + 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 { + 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; + } +} diff --git a/packages/channel-gateway/src/config.spec.ts b/packages/channel-gateway/src/config.spec.ts new file mode 100644 index 0000000000..f2fb2eb23d --- /dev/null +++ b/packages/channel-gateway/src/config.spec.ts @@ -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'); + }, + ); +}); diff --git a/packages/channel-gateway/src/config.ts b/packages/channel-gateway/src/config.ts new file mode 100644 index 0000000000..3dd26a35a6 --- /dev/null +++ b/packages/channel-gateway/src/config.ts @@ -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; +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 }; +} diff --git a/packages/channel-gateway/src/events.spec.ts b/packages/channel-gateway/src/events.spec.ts new file mode 100644 index 0000000000..91152c06b4 --- /dev/null +++ b/packages/channel-gateway/src/events.spec.ts @@ -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)); +}); diff --git a/packages/channel-gateway/src/events.ts b/packages/channel-gateway/src/events.ts new file mode 100644 index 0000000000..155a57b43b --- /dev/null +++ b/packages/channel-gateway/src/events.ts @@ -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; +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, + }, + }; +} diff --git a/packages/channel-gateway/src/slack.spec.ts b/packages/channel-gateway/src/slack.spec.ts new file mode 100644 index 0000000000..69b6cc9e7c --- /dev/null +++ b/packages/channel-gateway/src/slack.spec.ts @@ -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, Parameters>().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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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, Parameters>(); + 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, Parameters>() + .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, Parameters>() + .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, Parameters>() + .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); + }); +}); diff --git a/packages/channel-gateway/src/slack.ts b/packages/channel-gateway/src/slack.ts new file mode 100644 index 0000000000..ff0c4f1fc3 --- /dev/null +++ b/packages/channel-gateway/src/slack.ts @@ -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, + private readonly logger?: Logger, + private readonly transport: typeof fetch = fetch, + ) {} + + private async call( + token: string, + method: string, + payload: Record, + signal?: AbortSignal, + once = false, + ): Promise { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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 { + await this.call(token, 'views.open', { trigger_id: triggerId, view }, signal); + } + + async updateView( + token: string, + viewId: string, + view: SlackView, + hash?: string, + signal?: AbortSignal, + ): Promise { + 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 { + 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 { + 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 { + 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 { + 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'); + } +} diff --git a/packages/channel-gateway/src/types.ts b/packages/channel-gateway/src/types.ts new file mode 100644 index 0000000000..0a19a10a3c --- /dev/null +++ b/packages/channel-gateway/src/types.ts @@ -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 })), +}; diff --git a/packages/channel-gateway/tsconfig.json b/packages/channel-gateway/tsconfig.json new file mode 100644 index 0000000000..1d3c63d2cc --- /dev/null +++ b/packages/channel-gateway/tsconfig.json @@ -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"] +} diff --git a/packages/channel-gateway/tsdown.config.mjs b/packages/channel-gateway/tsdown.config.mjs new file mode 100644 index 0000000000..1bdfc246da --- /dev/null +++ b/packages/channel-gateway/tsdown.config.mjs @@ -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 }, +}); diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts index 4857fc1ee0..66d382b839 100644 --- a/packages/data-provider/src/config.spec.ts +++ b/packages/data-provider/src/config.spec.ts @@ -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({ diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts index d11fc72b0a..6807cdedc9 100644 --- a/packages/data-provider/src/config.ts +++ b/packages/data-provider/src/config.ts @@ -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; +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; + /** 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; /** 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() diff --git a/packages/data-provider/src/types/channelRuns.ts b/packages/data-provider/src/types/channelRuns.ts index 7dc416537e..9e0ec0c425 100644 --- a/packages/data-provider/src/types/channelRuns.ts +++ b/packages/data-provider/src/types/channelRuns.ts @@ -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 }; diff --git a/packages/data-provider/src/types/channels.ts b/packages/data-provider/src/types/channels.ts index 4c8c5791e6..92bd087cc8 100644 --- a/packages/data-provider/src/types/channels.ts +++ b/packages/data-provider/src/types/channels.ts @@ -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; +} diff --git a/packages/data-schemas/src/methods/channelProtocol.spec.ts b/packages/data-schemas/src/methods/channelProtocol.spec.ts index ae935b696f..389be5a5c6 100644 --- a/packages/data-schemas/src/methods/channelProtocol.spec.ts +++ b/packages/data-schemas/src/methods/channelProtocol.spec.ts @@ -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); +}); diff --git a/packages/data-schemas/src/methods/channelProtocol.ts b/packages/data-schemas/src/methods/channelProtocol.ts index 2b24a9abbf..5b8bbf0d7c 100644 --- a/packages/data-schemas/src/methods/channelProtocol.ts +++ b/packages/data-schemas/src/methods/channelProtocol.ts @@ -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', diff --git a/packages/data-schemas/src/methods/channelRun.spec.ts b/packages/data-schemas/src/methods/channelRun.spec.ts index 433f25c35b..d64f453685 100644 --- a/packages/data-schemas/src/methods/channelRun.spec.ts +++ b/packages/data-schemas/src/methods/channelRun.spec.ts @@ -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( diff --git a/packages/data-schemas/src/methods/channelRun.ts b/packages/data-schemas/src/methods/channelRun.ts index aea41895a9..334b8835ee 100644 --- a/packages/data-schemas/src/methods/channelRun.ts +++ b/packages/data-schemas/src/methods/channelRun.ts @@ -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; read(tenantId: string, channelId: string, runId: string): Promise; readActiveThread(scope: ChannelLaneScope, before: number): Promise; + /** 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 ( diff --git a/packages/data-schemas/src/models/channelRun.ts b/packages/data-schemas/src/models/channelRun.ts index 86d4ecd4e3..047765137c 100644 --- a/packages/data-schemas/src/models/channelRun.ts +++ b/packages/data-schemas/src/models/channelRun.ts @@ -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('ChannelLane', schema); diff --git a/scripts/sort-imports.mts b/scripts/sort-imports.mts index f003c88b8d..2768f594b1 100644 --- a/scripts/sort-imports.mts +++ b/scripts/sort-imports.mts @@ -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));