diff --git a/e2e/specs/mock/scenarios/button-roles.spec.ts b/e2e/specs/mock/scenarios/button-roles.spec.ts index 79894f8d1d..74afd103d5 100644 --- a/e2e/specs/mock/scenarios/button-roles.spec.ts +++ b/e2e/specs/mock/scenarios/button-roles.spec.ts @@ -3,7 +3,7 @@ import type { Locator, Page } from '@playwright/test'; import type { ThemeDefinition } from '../../../../packages/data-provider/src/themes/types'; import { clickHouseTheme } from '../../../../packages/client/src/theme/themes/clickhouse'; import { NEW_CHAT_PATH } from '../helpers'; -import { probeStyle } from './style.helpers'; +import { normalizeColor, probeStyle } from './style.helpers'; /** * The shared Button reads its label weight, its default and small heights and its primary fill @@ -77,9 +77,9 @@ test.describe('theme button roles', () => { expect(await probeStyle(page, 'bg-button-primary', 'background-color')).toBe( await probeStyle(page, 'bg-surface-inverted', 'background-color'), ); - expect(await probeStyle(page, 'bg-button-primary-hover', 'background-color')).toBe( - await probeStyle(page, 'bg-surface-inverted-hover', 'background-color'), - ); + expect( + await normalizeColor(page, 'rgb(var(--button-primary-hover, var(--surface-inverted-hover)))'), + ).toBe(await normalizeColor(page, 'rgb(var(--surface-inverted-hover))')); }); test('ClickHouse buttons take Click UI weight, height and primary fill @scenario:clickhouse-buttons-follow-click-ui', async ({ diff --git a/e2e/specs/mock/scenarios/field-variants.spec.ts b/e2e/specs/mock/scenarios/field-variants.spec.ts index f0d76ea837..550a79d55f 100644 --- a/e2e/specs/mock/scenarios/field-variants.spec.ts +++ b/e2e/specs/mock/scenarios/field-variants.spec.ts @@ -4,7 +4,7 @@ import { expect, test } from '@playwright/test'; import type { Page } from '@playwright/test'; import { clickHouseTheme } from '../../../../packages/client/src/theme/themes/clickhouse'; import { NEW_CHAT_PATH } from '../helpers'; -import { probeStyle } from './style.helpers'; +import { normalizeColor, probeStyle } from './style.helpers'; /** * The field and nav variants are rendered from the built primitives (server-side markup, the @@ -291,8 +291,8 @@ for (const theme of THEMES) { const secondary = await probeStyle(page, 'text-text-secondary', 'color'); const primary = await probeStyle(page, 'text-text-primary', 'color'); - const navHover = await probeStyle(page, 'bg-surface-nav-hover', 'background-color'); - const navSelected = await probeStyle(page, 'bg-surface-nav-selected', 'background-color'); + const navHover = await normalizeColor(page, 'rgb(var(--surface-nav-hover))'); + const navSelected = await normalizeColor(page, 'rgb(var(--surface-nav-selected))'); const rest = await styleOf(page, '#rest', ['color', 'background-color']); expect(rest['color']).toBe(secondary); diff --git a/e2e/specs/mock/scenarios/style.helpers.ts b/e2e/specs/mock/scenarios/style.helpers.ts index 79c1605470..faaf2ace3f 100644 --- a/e2e/specs/mock/scenarios/style.helpers.ts +++ b/e2e/specs/mock/scenarios/style.helpers.ts @@ -59,6 +59,7 @@ export function probePlaceholderColor(page: Page): Promise { * Normalise a colour expression — `rgb(227 227 227 / 1)`, `color-mix(...)`, a * token triplet — to the form `getComputedStyle` returns, by letting the browser * compute it. Comparing two normalised values compares colours, not spellings. + * Use a role expression for state-only utilities whose base class may not be emitted. */ export function normalizeColor(page: Page, value: string): Promise { return page.evaluate((color) => { diff --git a/package-lock.json b/package-lock.json index 560b3c2d7b..53f98543d5 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19887,6 +19887,7 @@ "version": "4.0.4", "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "license": "MIT", "dependencies": { "@types/unist": "*" } @@ -32320,6 +32321,7 @@ "version": "2.0.1", "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.1.tgz", "integrity": "sha512-aJEUyzZ6TzlsX2s5B4Of7lN7EQtAxvtradMMglCQDyaTFgse6CmtmdJ15ElnVRlCg1vpNyVtbem0PWzlNieZsA==", + "license": "MIT", "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", @@ -32360,6 +32362,7 @@ "version": "3.0.0", "resolved": "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-3.0.0.tgz", "integrity": "sha512-dgQEX5Amaq+DuUqf26jJqSK9qgixgd6rYDHAv4aTBuA92cTknZlKpPfa86Z/s8Dj8xsAQpFfBmPUHWJBWqS4Bw==", + "license": "MIT", "dependencies": { "mdast-util-from-markdown": "^2.0.0", "mdast-util-gfm-autolink-literal": "^2.0.0", @@ -33019,6 +33022,7 @@ "version": "3.0.0", "resolved": "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz", "integrity": "sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==", + "license": "MIT", "dependencies": { "micromark-extension-gfm-autolink-literal": "^2.0.0", "micromark-extension-gfm-footnote": "^2.0.0", @@ -42840,6 +42844,9 @@ "@slack/types": "3.2.0", "@slack/web-api": "8.2.0", "librechat-data-provider": "*", + "mdast-util-from-markdown": "2.0.1", + "mdast-util-gfm": "3.0.0", + "micromark-extension-gfm": "3.0.0", "prom-client": "^15.1.3", "undici": "^7.30.1", "zod": "^4.6.7" @@ -42848,6 +42855,7 @@ "@babel/preset-env": "^7.21.5", "@babel/preset-typescript": "^7.21.0", "@types/jest": "^29.5.2", + "@types/mdast": "4.0.4", "@types/node": "^24.12.4", "babel-jest": "^30.2.0", "jest": "^30.2.0", diff --git a/packages/api/src/channels/service.spec.ts b/packages/api/src/channels/service.spec.ts index 52e6d6630d..7205b1fac3 100644 --- a/packages/api/src/channels/service.spec.ts +++ b/packages/api/src/channels/service.spec.ts @@ -348,6 +348,7 @@ it('uses one policy snapshot and supplies the verified webhook credentials only nativeSessions: true, lifecycleReactions: true, signatureToleranceSeconds: 60, + maxDeliveryParts: 1, })); deps.config = config; const id = await createChannel(); @@ -378,6 +379,7 @@ it('uses one policy snapshot and supplies the verified webhook credentials only lifecycleReactions: true, signatureToleranceSeconds: 60, }); + expect(result.body.delivery).toEqual({ maxDeliveryParts: 1 }); expect(result.body.gateway).not.toHaveProperty('enabled'); }); diff --git a/packages/api/src/channels/service.ts b/packages/api/src/channels/service.ts index feb0e62d5f..eaafaf20dc 100644 --- a/packages/api/src/channels/service.ts +++ b/packages/api/src/channels/service.ts @@ -429,6 +429,7 @@ export function createChannelHandlers(deps: ChannelDependencies): { }, credentials: { botToken, signingSecret }, agent: { id: agent.id, name: agent.name ?? 'Agent' }, + delivery: { maxDeliveryParts: config.maxDeliveryParts }, gateway: channelGatewayWirePolicySchema.parse({ version: CHANNEL_GATEWAY_POLICY_VERSION, ...config, diff --git a/packages/channel-gateway/README.md b/packages/channel-gateway/README.md index 387b07f788..1e5fb6e3e0 100644 --- a/packages/channel-gateway/README.md +++ b/packages/channel-gateway/README.md @@ -1,15 +1,18 @@ # 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. +This private workspace contains transport, native presentation and private interaction 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: +The adapter build produces seven 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 | +| 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 | +| `render` | Deterministic bounded answer/progress plans and durable presentation replay | +| `identity` | Actor-private account-link tickets and exact-account confirmation | +| `review` | Current actor/action validation, native forms and immutable saved-decision retry | 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. diff --git a/packages/channel-gateway/jest.config.mjs b/packages/channel-gateway/jest.config.mjs index df0da8a916..4b577bc19a 100644 --- a/packages/channel-gateway/jest.config.mjs +++ b/packages/channel-gateway/jest.config.mjs @@ -12,6 +12,9 @@ export default { }, ], }, + transformIgnorePatterns: [ + '/node_modules/(?!mdast-util-|micromark|decode-named-character-reference|devlop|longest-streak|unist-util-|zwitch|character-(?:entities|reference)|parse-entities|stringify-entities|is-(?:alphanumerical|alphabetical|decimal|hexadecimal)|ccount|markdown-table|escape-string-regexp)', + ], testTimeout: 15000, restoreMocks: true, }; diff --git a/packages/channel-gateway/package.json b/packages/channel-gateway/package.json index c80dba4f9a..63c2015ee5 100644 --- a/packages/channel-gateway/package.json +++ b/packages/channel-gateway/package.json @@ -15,15 +15,19 @@ "@slack/socket-mode": "3.1.0", "@slack/types": "3.2.0", "@slack/web-api": "8.2.0", - "undici": "^7.30.1", "librechat-data-provider": "*", + "mdast-util-from-markdown": "2.0.1", + "mdast-util-gfm": "3.0.0", + "micromark-extension-gfm": "3.0.0", "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/mdast": "4.0.4", "@types/node": "^24.12.4", "babel-jest": "^30.2.0", "jest": "^30.2.0", diff --git a/packages/channel-gateway/src/client.spec.ts b/packages/channel-gateway/src/client.spec.ts index 04d435e896..768506b853 100644 --- a/packages/channel-gateway/src/client.spec.ts +++ b/packages/channel-gateway/src/client.spec.ts @@ -82,6 +82,37 @@ describe('ChannelClient service boundary', () => { 'Unsupported channel gateway policy', ); }); + test.each([0, 101, 1.5, '1', null])( + 'rejects malformed delivery budget %p', + async (maxDeliveryParts) => { + const transport = jest + .fn, Parameters>() + .mockResolvedValue(json({ ...bundle, delivery: { maxDeliveryParts } })); + await expect(new ChannelClient(config, transport).channel()).rejects.toThrow( + 'Invalid channel delivery policy', + ); + }, + ); + test('reads the server-selected reduced delivery budget', async () => { + const transport = jest + .fn, Parameters>() + .mockResolvedValue(json({ ...bundle, delivery: { maxDeliveryParts: 1 } })); + expect((await new ChannelClient(config, transport).channel()).delivery).toEqual({ + maxDeliveryParts: 1, + }); + }); + test('preserves identity domain results and null absence without converting conflicts to exceptions', async () => { + const transport = jest + .fn, Parameters>() + .mockResolvedValueOnce(json({ ok: false, error: { code: 'changed' } })) + .mockResolvedValueOnce(json({ ok: true, value: null })); + const client = new ChannelClient(config, transport); + await expect(client.identity('U1', '/confirm', {})).resolves.toEqual({ + ok: false, + error: { code: 'changed' }, + }); + await expect(client.identity('U1')).resolves.toEqual({ ok: true, value: null }); + }); test('returns a valid worker-bound claim', async () => { const lease = { run, fence, leaseExpiresAt: Date.now() + 60_000 }; const transport = jest @@ -181,7 +212,10 @@ describe('ChannelClient service boundary', () => { const transport = jest .fn, Parameters>() .mockResolvedValue(json(bundle)); - await expect(new ChannelClient(config, transport).channel()).resolves.toEqual(bundle); + await expect(new ChannelClient(config, transport).channel()).resolves.toEqual({ + ...bundle, + delivery: { maxDeliveryParts: 100 }, + }); 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'); diff --git a/packages/channel-gateway/src/client.ts b/packages/channel-gateway/src/client.ts index c35a7a4702..51348601d3 100644 --- a/packages/channel-gateway/src/client.ts +++ b/packages/channel-gateway/src/client.ts @@ -2,6 +2,7 @@ import { createHash } from 'node:crypto'; import { CHANNEL_RUN_MAX_JSON_BYTES, channelGatewayWirePolicySchema, + channelStorageConfigSchema, } from 'librechat-data-provider'; import type { ChannelRunActor, @@ -35,6 +36,11 @@ export class ServiceError extends Error { } } +/** Expected stale/authorization failures may be acknowledged privately; outages must propagate. */ +export function expectedServiceFailure(error: unknown): boolean { + return error instanceof ServiceError && [400, 403, 404, 409, 410].includes(error.status); +} + const validId = (value: unknown): value is string => typeof value === 'string' && /^[\w:.-]{1,256}$/.test(value); @@ -157,7 +163,11 @@ export class ChannelClient { 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 }; + const delivery = channelStorageConfigSchema + .pick({ maxDeliveryParts: true }) + .safeParse(value.delivery === undefined ? {} : value.delivery); + if (!delivery.success) throw new Error('Invalid channel delivery policy'); + return { ...value, gateway: policy.data, delivery: delivery.data }; } async runs(suffix: string, body: object, signal?: AbortSignal, empty?: T): Promise { return this.request(this.root + '/runs' + suffix, body, signal, empty); @@ -334,19 +344,17 @@ export class ChannelClient { signal, ); } - async identity( + identity( actor: string, suffix = '', body?: object, signal?: AbortSignal, - ): Promise { - const result = await this.request>( + ): Promise> { + return 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, diff --git a/packages/channel-gateway/src/identity.spec.ts b/packages/channel-gateway/src/identity.spec.ts new file mode 100644 index 0000000000..f3349a45ef --- /dev/null +++ b/packages/channel-gateway/src/identity.spec.ts @@ -0,0 +1,299 @@ +import { DEFAULT_CHANNEL_GATEWAY_POLICY } from 'librechat-data-provider'; +import type { ChannelLinkView } from 'librechat-data-provider'; +import type { ChannelBundle } from './types'; +import { IdentityFlow, safeIdentityTicket, safePrivateURL, validActorView } from './identity'; +import { ChannelClient } from './client'; +import { loadConfig } from './config'; +import { SlackClient } from './slack'; + +const config = loadConfig({ + CHANNEL_SERVICE_TOKEN: 'test-service', + CHANNEL_TENANT_ID: 'tenant', + CHANNEL_ID: 'binding', +}); +const bundle: ChannelBundle = { + gateway: { version: 1, ...DEFAULT_CHANNEL_GATEWAY_POLICY }, + 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' }, +}; +const view = (): ChannelLinkView => ({ + identity: { + tenantId: 'tenant', + channelId: 'binding', + channelRevision: 'r1', + teamId: 'T1', + externalUserId: 'U1', + agentId: 'agent', + }, + linkId: 'link', + revision: 'l1', + state: 'accepted', + expiresAtMs: Date.now() + 60000, + accountLabel: 'Personal account', +}); +const json = (body: object) => + new Response(JSON.stringify(body), { headers: { 'Content-Type': 'application/json' } }); +function setup() { + const backend = jest.fn, Parameters>(); + const slack = jest + .fn, Parameters>() + .mockImplementation(async () => json({ ok: true })); + return { + backend, + slack, + flow: new IdentityFlow( + new ChannelClient(config, backend), + new SlackClient(config, undefined, slack), + ), + }; +} +function posted(transport: ReturnType['slack']) { + return new URLSearchParams(String(transport.mock.calls[0][1]?.body)); +} + +describe('private identity linking', () => { + test('concurrent accepted reads produce one confirmation and one private stale acknowledgement', async () => { + const { backend, slack, flow } = setup(); + let reads = 0; + let confirms = 0; + let release: () => void = () => {}; + const bothRead = new Promise((resolve) => { + release = resolve; + }); + backend.mockImplementation(async (url) => { + if (String(url).endsWith('/confirm')) { + confirms++; + return json( + confirms === 1 + ? { ok: true, value: { ...view(), state: 'active' } } + : { ok: false, error: { code: 'changed' } }, + ); + } + reads++; + if (reads === 2) release(); + await bothRead; + return json({ ok: true, value: view() }); + }); + const reference = JSON.stringify({ linkId: 'link', revision: 'l1' }); + await Promise.all([ + flow.confirm('C1', 'U1', reference, bundle), + flow.confirm('C1', 'U1', reference, bundle), + ]); + const texts = slack.mock.calls.map( + ([, init]) => new URLSearchParams(String(init?.body)).get('text')!, + ); + expect(texts.filter((text) => text.includes('link is confirmed'))).toHaveLength(1); + expect(texts.filter((text) => text.includes('stale'))).toHaveLength(1); + expect(backend.mock.calls.every(([url]) => String(url).includes('/identity/U1'))).toBe(true); + expect( + slack.mock.calls.every( + ([url, init]) => + String(url).includes('chat.postEphemeral') && + new URLSearchParams(String(init?.body)).get('user') === 'U1', + ), + ).toBe(true); + }); + + test.each([ + 'invalid_ticket', + 'expired', + 'changed', + 'forbidden', + 'already_linked', + 'confirmation_required', + 'revoked', + 'unavailable', + ])( + 'preserves domain failure %s across lookup, ticket and confirmation without claiming success', + async (code) => { + for (const phase of ['lookup', 'ticket', 'confirm']) { + const { backend, slack, flow } = setup(); + if (phase !== 'lookup') + backend.mockResolvedValueOnce( + json({ ok: true, value: phase === 'ticket' ? null : view() }), + ); + backend.mockResolvedValueOnce(json({ ok: false, error: { code } })); + if (phase === 'confirm') + await flow.confirm( + 'C1', + 'U1', + JSON.stringify({ linkId: 'link', revision: 'l1' }), + bundle, + ); + else await flow.prompt('C1', 'U1', bundle); + expect(posted(slack).get('text')).toContain('stale or unavailable'); + expect(posted(slack).get('text')).not.toContain('link is confirmed'); + expect(slack).toHaveBeenCalledTimes(1); + } + }, + ); + + test.each([400, 403, 404, 409, 410])( + 'expected HTTP %i is private unavailability, not a failed interaction', + async (status) => { + const { backend, slack, flow } = setup(); + backend.mockResolvedValueOnce(new Response('{}', { status })); + await flow.prompt('C1', 'U1', bundle); + expect(posted(slack).get('text')).toContain('stale or unavailable'); + }, + ); + + test('a confirmation HTTP conflict is acknowledged, while service outages still propagate', async () => { + const { backend, slack, flow } = setup(); + backend + .mockResolvedValueOnce(json({ ok: true, value: view() })) + .mockResolvedValueOnce(new Response('{}', { status: 409 })); + await flow.confirm('C1', 'U1', JSON.stringify({ linkId: 'link', revision: 'l1' }), bundle); + expect(posted(slack).get('text')).toContain('stale or unavailable'); + backend.mockResolvedValueOnce(new Response('{}', { status: 503 })); + await expect(flow.prompt('C1', 'U1', bundle)).rejects.toThrow(); + expect(slack).toHaveBeenCalledTimes(1); + }); + + test('accepted account requires explicit actor-private Slack confirmation', async () => { + const { backend, slack, flow } = setup(); + backend.mockResolvedValueOnce(json({ ok: true, value: view() })); + await flow.prompt('C1', 'U1', bundle); + const payload = posted(slack); + expect(String(slack.mock.calls[0][0])).toContain('chat.postEphemeral'); + expect(payload.get('user')).toBe('U1'); + expect(payload.get('blocks')).toContain('channel_link_confirm'); + expect(payload.get('blocks')).not.toContain('test-service'); + expect(backend).toHaveBeenCalledTimes(1); + }); + + test('a browser ticket is private and the original command is not replayed', async () => { + const { backend, slack, flow } = setup(); + const ticket = { + url: `https://chat.example/channels/link#${'a'.repeat(43)}`, + expiresAtMs: Date.now() + 60000, + }; + backend + .mockResolvedValueOnce(json({ ok: true, value: null })) + .mockResolvedValueOnce(json({ ok: true, value: ticket })); + await flow.prompt('C1', 'U1', bundle); + expect(posted(slack).get('text')).toContain('will not run automatically'); + expect(backend.mock.calls.map(([url]) => String(url))).toEqual([ + `${config.LIBRECHAT_INTERNAL_URL}/api/channels/service/binding/identity/U1`, + `${config.LIBRECHAT_INTERNAL_URL}/api/channels/service/binding/identity/U1/ticket`, + ]); + }); + + test.each([ + 'externalUserId', + 'channelRevision', + 'teamId', + 'agentId', + 'tenantId', + 'channelId', + ] as const)('rejects mismatched %s', async (field) => { + const { backend, slack, flow } = setup(); + const other = view(); + other.identity[field] = 'other'; + backend.mockResolvedValueOnce(json({ ok: true, value: other })); + await expect(flow.prompt('C1', 'U1', bundle)).rejects.toThrow(); + expect(slack).not.toHaveBeenCalled(); + }); + + test.each(['email@example.com', 'label\nunsafe', 'label\u202eunsafe', ''])( + 'does not disclose unsafe account label %p', + async (label) => { + const { backend, slack, flow } = setup(); + const linked = view(); + linked.accountLabel = label; + backend.mockResolvedValueOnce(json({ ok: true, value: linked })); + await expect(flow.prompt('C1', 'U1', bundle)).rejects.toThrow(); + expect(slack).not.toHaveBeenCalled(); + }, + ); + + test('stale link confirmation does not mutate identity', async () => { + const { backend, slack, flow } = setup(); + backend.mockResolvedValueOnce(json({ ok: true, value: view() })); + await flow.confirm('C1', 'U1', JSON.stringify({ linkId: 'link', revision: 'old' }), bundle); + expect(backend).toHaveBeenCalledTimes(1); + expect(posted(slack).get('text')).toContain('stale'); + }); + + test('confirmation is verified active and never admits the earlier command', async () => { + const { backend, slack, flow } = setup(); + backend + .mockResolvedValueOnce(json({ ok: true, value: view() })) + .mockResolvedValueOnce(json({ ok: true, value: { ...view(), state: 'active' } })); + await flow.confirm('C1', 'U1', JSON.stringify({ linkId: 'link', revision: 'l1' }), bundle); + expect(String(backend.mock.calls[1][0])).toContain('/identity/U1/confirm'); + expect(posted(slack).get('text')).toContain('earlier request was not run'); + expect(backend).toHaveBeenCalledTimes(2); + }); + + test('unconfirmed mutation does not claim success', async () => { + const { backend, slack, flow } = setup(); + backend.mockImplementation(async () => json({ ok: true, value: view() })); + await expect( + flow.confirm('C1', 'U1', JSON.stringify({ linkId: 'link', revision: 'l1' }), bundle), + ).rejects.toThrow('not committed'); + expect(slack).not.toHaveBeenCalled(); + }); + + test('expired identity cannot be confirmed', () => { + const expired = view(); + expired.expiresAtMs = Date.now() - 1; + expect(validActorView(expired, 'tenant', 'U1', bundle)).toBe(false); + }); + test.each([ + 'https://example.com/x#token', + 'https://user:pass@example.com/x', + 'javascript:alert(1)', + 'http://example.com/x', + 'https://example.com/x|bad', + ])('rejects unsafe private URL %s', (url) => expect(safePrivateURL(url)).toBe(false)); + test('allows loopback browser fixture without permitting arbitrary HTTP', () => + expect(safePrivateURL('http://127.0.0.1:3088/channels/link')).toBe(true)); + test('rejects ticket query and expiry', () => { + expect( + safeIdentityTicket({ + url: `https://chat.example/channels/link?ticket=leak#${'a'.repeat(43)}`, + expiresAtMs: Date.now() + 1000, + }), + ).toBe(false); + expect( + safeIdentityTicket({ + url: `https://chat.example/channels/link#${'a'.repeat(43)}`, + expiresAtMs: Date.now() - 1, + }), + ).toBe(false); + }); +}); + +test('an unavailable prior identity issues a fresh private ticket without replaying the original request', async () => { + const { backend, slack, flow } = setup(); + backend + .mockResolvedValueOnce(json({ ok: true, value: { ...view(), state: 'unavailable' } })) + .mockResolvedValueOnce( + json({ + ok: true, + value: { + url: `https://chat.example/channels/link#${'b'.repeat(43)}`, + expiresAtMs: Date.now() + 60000, + }, + }), + ); + await flow.prompt('C1', 'U1', bundle); + expect(backend.mock.calls.map(([url]) => String(url).split('/').at(-1))).toEqual([ + 'U1', + 'ticket', + ]); + expect(posted(slack).get('text')).toContain('will not run automatically'); + expect(posted(slack).get('user')).toBe('U1'); +}); diff --git a/packages/channel-gateway/src/identity.ts b/packages/channel-gateway/src/identity.ts new file mode 100644 index 0000000000..b43564ef09 --- /dev/null +++ b/packages/channel-gateway/src/identity.ts @@ -0,0 +1,261 @@ +import { z } from 'zod'; +import type { ChannelLinkView, ChannelLinkTicket } from 'librechat-data-provider'; +import type { SlackClient, SlackBlocks } from './slack'; +import type { ChannelClient } from './client'; +import type { ChannelBundle } from './types'; +import { expectedServiceFailure } from './client'; + +const confirmationSchema = z + .object({ linkId: z.string().min(1), revision: z.string().min(1) }) + .strict(); + +export function safePrivateURL(raw: string): boolean { + if (raw.length > 2048 || /[<>|\p{Cc}\p{Cf}]/u.test(raw)) return false; + try { + const url = new URL(raw); + return ( + !url.username && + !url.password && + !url.hash && + (url.protocol === 'https:' || + (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) + ); + } catch { + return false; + } +} + +export function safeIdentityTicket(ticket: ChannelLinkTicket, now = Date.now()): boolean { + try { + const url = new URL(ticket.url); + if ( + ticket.expiresAtMs <= now || + url.search || + !url.pathname.endsWith('/channels/link') || + !/^#[A-Za-z0-9_-]{43}$/.test(url.hash) + ) + return false; + url.hash = ''; + return safePrivateURL(url.toString()); + } catch { + return false; + } +} + +export function validActorView( + view: ChannelLinkView | null, + tenantId: string, + actorId: string, + bundle: ChannelBundle, + now = Date.now(), +): view is ChannelLinkView { + if (!view) return false; + const identity = view.identity; + return ( + identity?.tenantId === tenantId && + identity.channelId === bundle.channel.channelId && + identity.teamId === bundle.channel.slack.teamId && + identity.externalUserId === actorId && + identity.agentId === bundle.agent.id && + identity.channelRevision === bundle.channel.revision && + !!view.linkId && + !!view.revision && + view.expiresAtMs > now + ); +} + +function safeAccountLabel(label: string | undefined): label is string { + return !!label?.trim() && [...label].length <= 200 && !/[@\p{Cc}\p{Cf}]/u.test(label); +} + +export class IdentityFlow { + constructor( + private readonly client: ChannelClient, + private readonly slack: SlackClient, + ) {} + + async notify( + channelId: string, + actorId: string, + text: string, + bundle: ChannelBundle, + button?: { label: string; action: string; value?: string; url?: string }, + signal?: AbortSignal, + ): Promise { + const blocks: SlackBlocks = [{ type: 'section', text: { type: 'plain_text', text } }]; + if (button) + blocks.push({ + type: 'actions', + elements: [ + { + type: 'button', + text: { type: 'plain_text', text: button.label }, + action_id: button.action, + ...(button.value ? { value: button.value } : {}), + ...(button.url ? { url: button.url } : {}), + }, + ], + }); + await this.slack.ephemeral( + bundle.credentials.botToken, + { + channel: channelId, + user: actorId, + text: text.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>'), + blocks, + }, + signal, + ); + } + + private unavailable( + channelId: string, + actorId: string, + bundle: ChannelBundle, + signal?: AbortSignal, + ) { + return this.notify( + channelId, + actorId, + 'This account-link action is stale or unavailable. Retry your mention to check your own account link. The original request was not run.', + bundle, + undefined, + signal, + ); + } + + private async withAvailability( + channelId: string, + actorId: string, + bundle: ChannelBundle, + signal: AbortSignal | undefined, + work: () => Promise, + ): Promise { + try { + await work(); + } catch (error) { + if (!expectedServiceFailure(error)) throw error; + await this.unavailable(channelId, actorId, bundle, signal); + } + } + + async prompt( + channelId: string, + actorId: string, + bundle: ChannelBundle, + signal?: AbortSignal, + ): Promise { + return this.withAvailability(channelId, actorId, bundle, signal, async () => { + const current = await this.client.identity( + actorId, + '', + undefined, + signal, + ); + if (!current.ok) return this.unavailable(channelId, actorId, bundle, signal); + const view = current.value; + if (view?.state === 'accepted') { + if ( + !validActorView(view, this.client.config.CHANNEL_TENANT_ID, actorId, bundle) || + !safeAccountLabel(view.accountLabel) + ) + throw new Error('Accepted account identity cannot be safely confirmed'); + const label = `Confirm linking ${view.accountLabel} to you`; + return this.notify( + channelId, + actorId, + `${label}. Confirm only if this is the account you intended to use. Then retry your mention.`, + bundle, + { + label: [...label].length <= 75 ? label : 'Confirm the account shown above', + action: 'channel_link_confirm', + value: JSON.stringify({ linkId: view.linkId, revision: view.revision }), + }, + signal, + ); + } + if (view?.state === 'active') { + if (!validActorView(view, this.client.config.CHANNEL_TENANT_ID, actorId, bundle)) + throw new Error('Channel account link changed'); + return this.notify( + channelId, + actorId, + 'Your account is linked, but this channel has not authorized this request. Check your channel access with its owner, then retry your mention.', + bundle, + undefined, + signal, + ); + } + const issued = await this.client.identity(actorId, '/ticket', {}, signal); + if (!issued.ok) return this.unavailable(channelId, actorId, bundle, signal); + const ticket = issued.value; + if (!safeIdentityTicket(ticket)) throw new Error('Invalid private account-link ticket'); + await this.notify( + channelId, + actorId, + 'Link your account in the browser, then mention me again to confirm the exact account here in Slack. Your original request will not run automatically.', + bundle, + { label: 'Link your account', action: 'channel_link_open', url: ticket.url }, + signal, + ); + }); + } + + async confirm( + channelId: string, + actorId: string, + value: string, + bundle: ChannelBundle, + signal?: AbortSignal, + ): Promise { + if (value.length > 1024) throw new Error('Invalid account confirmation reference'); + const confirmation = confirmationSchema.parse(JSON.parse(value)); + return this.withAvailability(channelId, actorId, bundle, signal, async () => { + const current = await this.client.identity( + actorId, + '', + undefined, + signal, + ); + if (!current.ok) return this.unavailable(channelId, actorId, bundle, signal); + const view = current.value; + if ( + !validActorView(view, this.client.config.CHANNEL_TENANT_ID, actorId, bundle) || + view.linkId !== confirmation.linkId || + view.revision !== confirmation.revision || + view.state !== 'accepted' + ) { + return this.notify( + channelId, + actorId, + 'This confirmation is stale or does not belong to you. Please retry your mention to check your own account link.', + bundle, + undefined, + signal, + ); + } + const result = await this.client.identity( + actorId, + '/confirm', + confirmation, + signal, + ); + if (!result.ok) return this.unavailable(channelId, actorId, bundle, signal); + const confirmed = result.value; + if ( + !validActorView(confirmed, this.client.config.CHANNEL_TENANT_ID, actorId, bundle) || + confirmed.linkId !== confirmation.linkId || + confirmed.state !== 'active' + ) + throw new Error('Account confirmation not committed'); + await this.notify( + channelId, + actorId, + 'Your account link is confirmed. Please retry your mention; the earlier request was not run.', + bundle, + undefined, + signal, + ); + }); + } +} diff --git a/packages/channel-gateway/src/render.spec.ts b/packages/channel-gateway/src/render.spec.ts new file mode 100644 index 0000000000..cacd6fd9cf --- /dev/null +++ b/packages/channel-gateway/src/render.spec.ts @@ -0,0 +1,779 @@ +import type { ChannelArtifact, ChannelRunView } from 'librechat-data-provider'; +import { + chunkText, + safeMrkdwn, + rendererVersion, + makeSlackPlan, + validArtifact, + renderAgentAnswer, + supportedRenderer, + presentationFormat, + durableSlackMessage, + renderSlackDocument, + safeSummarySessionURL, + accountingPriceDescription, +} from './render'; + +function run(): ChannelRunView { + return { + runId: 'run-12345678', + channelId: 'channel-1', + revision: 'revision-1', + state: 'delivering', + sequence: 1, + admission: { + actor: { teamId: 'T1', appId: 'A1', externalUserId: 'U1' }, + eventId: 'event-1', + externalChannelId: 'C1', + externalThreadKey: 'C1:123.456', + externalMessageKey: 'C1:123.457', + input: 'hello', + }, + cancellationRequested: false, + receipts: [], + snapshot: { + text: 'Hello **world**', + status: 'completed', + elapsedMs: 1250, + responseId: 'resp_1', + }, + }; +} + +const artifact: ChannelArtifact = { + artifactId: 'opaque-file-1', + filename: 'report.txt', + mediaType: 'text/plain', + bytes: 10, + sha256: 'a'.repeat(64), +}; + +describe('Slack answer rendering', () => { + it('parses balanced and escaped link parentheses without touching literal code', () => { + expect(safeMrkdwn('[docs](https://example.com/Foo_(bar))')).toBe( + '', + ); + expect(safeMrkdwn('[docs](https://example.com/a_(b_(c)))')).toBe( + '', + ); + expect(safeMrkdwn(String.raw`[docs](https://example.com/a\(b\))`)).toBe( + '', + ); + expect(safeMrkdwn('`[docs](https://example.com/Foo_(bar))`')).toBe( + '`[docs](https://example.com/Foo_(bar))`', + ); + expect(safeMrkdwn('[unsafe](javascript:alert(1))')).toBe('unsafe'); + expect(safeMrkdwn('[unfinished](https://example.com/a_(b)')).toBe( + '[unfinished](', + ); + }); + + it.each([1, 2, 3, 100])('keeps required text and artifact groups within budget %i', (budget) => { + const view = run(); + view.snapshot!.artifacts = [artifact]; + const plan = makeSlackPlan(view, false, budget); + expect(plan.parts.length).toBeLessThanOrEqual(budget); + expect(plan.parts[0].required).toBe(true); + expect(plan.parts[0].text).toContain('Hello'); + if (plan.parts.some((part) => part.kind === 'artifact')) + expect(plan.parts.some((part) => part.operationId.endsWith(':artifact-status'))).toBe(true); + else expect(plan.parts[0].text).toContain('omitted'); + }); + + it('reflows rich blocks and explicitly bounds oversized required output under a reduced budget', () => { + const view = run(); + view.snapshot!.text = 'answer '.repeat(15000); + const plan = makeSlackPlan(view, false, 1); + expect(plan.parts).toHaveLength(1); + expect(plan.parts[0].text).toContain('Reply shortened'); + expect(Buffer.byteLength(plan.parts[0].text)).toBeLessThan(40000); + expect(view.snapshot!.text.length).toBe(105000); + }); + + it.each([2795, 2799, 2800, 2801])( + 'keeps complete formatting tokens at the %i-byte boundary', + (prefix) => { + for (const token of [ + [ + '[docs](https://example.com/Foo_(bar)?x=1&y=2)', + '', + ], + ['`code <@U1> **literal**`', '`code <@U1> **literal**`'], + ['**bold words**', '*bold words*'], + ['**bold\nwords**', '*bold\nwords*'], + ['_italic words_', '_italic words_'], + ['~strike words~', '~strike words~'], + ['&', '&'], + ]) { + const source = 'x'.repeat(prefix) + ' ' + token[0] + ' tail'; + const blocks = renderSlackDocument(source).flatMap((message) => message.blocks ?? []); + const texts = blocks.flatMap((block) => + block.type === 'section' ? [block.text.text] : [], + ); + expect(texts.some((text) => text.includes(token[1]))).toBe(true); + expect(texts.every((text) => Buffer.byteLength(text) <= 2800)).toBe(true); + expect(texts.join('')).toBe(safeMrkdwn(source)); + } + }, + ); + + it('preserves UTF8 and large atomic tokens with bounded explicit plain-text fallback', () => { + const source = '🙂'.repeat(699) + '[docs](https://example.com/a_(b))'; + const texts = renderSlackDocument(source) + .flatMap((message) => message.blocks ?? []) + .flatMap((block) => (block.type === 'section' ? [block.text.text] : [])); + expect(texts.join('')).toBe(safeMrkdwn(source)); + expect(texts.every((text) => Buffer.byteLength(text) <= 2800)).toBe(true); + for (const [large, plain] of [ + [ + '[docs](https://example.com/' + 'a'.repeat(3000) + ')', + 'docs (https://example.com/' + 'a'.repeat(3000) + ')', + ], + ['`' + 'x'.repeat(3000) + '`', 'x'.repeat(3000)], + ['**' + 'x'.repeat(3000) + '**', 'x'.repeat(3000)], + ]) { + const blocks = renderSlackDocument(large).flatMap((message) => message.blocks ?? []); + expect( + blocks.every((block) => block.type === 'section' && block.text.type === 'plain_text'), + ).toBe(true); + expect( + blocks.flatMap((block) => (block.type === 'section' ? [block.text.text] : [])).join(''), + ).toBe(plain); + } + }); + + it('uses GFM link grammar for nested labels, references and autolinks', () => { + const url = 'https://example.com/__file__?q=**value**'; + expect(safeMrkdwn('[outer **bold** and `code`](' + url + ' "title")')).toBe( + '<' + url + '|outer bold and code>', + ); + const source = '[guide][DOC] and [doc]\n\n[doc]: ' + url + ' "title"'; + expect(safeMrkdwn(source)).toBe('<' + url + '|guide> and <' + url + '|doc>\n\n'); + expect(renderAgentAnswer(source)[0].blocks).toEqual([{ type: 'markdown', text: source }]); + expect(renderSlackDocument(source)[0].text).toBe('<' + url + '|guide> and <' + url + '|doc>'); + // Bare autolinks exclude trailing Markdown punctuation under GFM. + expect(safeMrkdwn(url + 'end')).toBe('<' + url + 'end>'); + expect(safeMrkdwn('<' + url + '>')).toBe('<' + url + '>'); + expect(safeMrkdwn('`[doc]`\n\n[doc]: ' + url)).toBe('`[doc]`\n\n'); + }); + + it('sanitizes reference targets and oversized fallback without resurrecting credentials', () => { + const source = '[label][secret]\n\n[secret]: https://user:password@example.com/private'; + for (const messages of [renderSlackDocument(source), renderAgentAnswer(source)]) { + expect(JSON.stringify(messages)).not.toContain('password'); + expect(messages[0].text).toContain('label'); + } + const large = '**' + 'x'.repeat(3000) + ' [private](https://user:password@example.com)**'; + const messages = renderSlackDocument(large); + expect(JSON.stringify(messages)).not.toContain('password'); + expect( + messages + .flatMap((message) => message.blocks ?? []) + .every((block) => block.type === 'section' && block.text.type === 'plain_text'), + ).toBe(true); + expect(messages.map((message) => message.plain).join('')).toContain('private'); + }); + + it('bounds escaped semantic fallback and keeps safe link destinations readable', () => { + const view = run(); + view.snapshot!.text = ('&'.repeat(3000) + ' [docs](https://example.com/__file__)\n\n').repeat( + 8, + ); + const plan = makeSlackPlan(view, false, 1); + expect(plan.parts).toHaveLength(1); + const message = durableSlackMessage(plan.parts[0], rendererVersion); + expect(Buffer.byteLength(message.text)).toBeLessThanOrEqual(39000); + expect(message.text).toContain('Reply shortened'); + const plain = message.blocks + ?.flatMap((block) => (block.type === 'section' ? [block.text.text] : [])) + .join(''); + expect(plain).toContain('docs (https://example.com/__file__)'); + expect(plain).not.toContain(' { + const view = run(); + view.snapshot!.artifacts = [artifact, { ...artifact, artifactId: 'bad', filename: '../bad' }]; + view.snapshot!.summary = { + version: 1, + scope: 'actor_lane', + includesCurrent: true, + throughSequence: 1, + expectedRuns: 1, + observedRuns: 1, + priorRuns: 0, + costUSD: { coverage: 'unavailable', coveredRuns: 0 }, + elapsedMs: { coverage: 'unavailable', coveredRuns: 0 }, + tokens: { coverage: 'unavailable', coveredRuns: 0 }, + session: { url: 'https://chat.example.com/c/session' }, + }; + for (const budget of [1, 2, 3, 4, 5, 6]) { + const plan = makeSlackPlan(view, false, budget); + expect(plan.parts).toHaveLength(Math.min(budget, 5)); + expect(plan.parts[0].required).toBe(true); + if (plan.parts.some((part) => part.kind === 'artifact')) + expect(plan.parts.some((part) => part.operationId.endsWith(':artifact-status'))).toBe(true); + for (const part of plan.parts) + expect(() => durableSlackMessage(part, rendererVersion)).not.toThrow(); + expect(makeSlackPlan(view, false, budget)).toEqual(plan); + if (budget >= 4) expect(plan.parts.some((part) => part.traceUrl)).toBe(true); + } + }); + + it('reflows reduced-budget output as bounded plain text without splitting formatted block syntax', () => { + const view = run(); + view.snapshot!.text = + 'x'.repeat(38990) + ' [docs](https://example.com/a_(b)) ' + 'tail '.repeat(500); + const plan = makeSlackPlan(view, false, 1); + expect(plan.parts).toHaveLength(1); + const message = durableSlackMessage(plan.parts[0], rendererVersion); + expect( + message.blocks?.every( + (block) => block.type === 'section' && block.text.type === 'plain_text', + ), + ).toBe(true); + expect(message.text).toContain('Reply shortened'); + expect(Buffer.byteLength(message.text)).toBeLessThan(40000); + expect(supportedRenderer('slack-structured-v5')).toBe(true); + expect(() => + durableSlackMessage( + { + ...plan.parts[0], + presentation: { + format: presentationFormat, + payload: JSON.stringify([ + { type: 'section', text: { type: 'mrkdwn', text: 'legacy' } }, + ]), + }, + }, + 'slack-structured-v5', + ), + ).not.toThrow(); + }); + + it('preserves existing formatting when an omission notice fits and bounds every serialized fallback', () => { + const view = run(); + view.snapshot!.artifacts = [artifact]; + const part = makeSlackPlan(view, false, 1).parts[0]; + const message = durableSlackMessage(part, rendererVersion); + expect( + message.blocks?.some( + (block) => + block.type === 'section' && + block.text.type === 'mrkdwn' && + block.text.text.includes('*world*'), + ), + ).toBe(true); + expect( + message.blocks?.some( + (block) => + block.type === 'section' && + block.text.type === 'plain_text' && + block.text.text.includes('omitted'), + ), + ).toBe(true); + view.snapshot!.text = '\u0000'.repeat(15000); + for (const generated of makeSlackPlan(view, false, 1).parts) { + if (generated.presentation) + expect(Buffer.byteLength(generated.presentation.payload)).toBeLessThanOrEqual(64000); + expect(() => durableSlackMessage(generated, rendererVersion)).not.toThrow(); + } + }); + + it.each([ + '__file__', + '**file**', + 'a__b__c?x=__query__&y=**query**', + 'a`b`c', + 'a_(b_(c))__name__', + 'a**file**?q=__x__', + ])('never formats the destination %s after constructing a link', (path) => { + const url = 'https://example.com/' + path; + const source = '[docs](' + url + ')'; + const wire = '<' + url.replaceAll('&', '&') + '|docs>'; + expect(safeMrkdwn(source)).toBe(wire); + expect(renderAgentAnswer(source)[0].blocks).toEqual([{ type: 'markdown', text: source }]); + const long = renderAgentAnswer('x'.repeat(12001) + ' ' + source); + expect( + long + .flatMap((message) => message.blocks ?? []) + .some((block) => block.type === 'section' && block.text.text.includes(wire)), + ).toBe(true); + }); + + it('formats prose around immutable link/code atoms and keeps fence line boundaries', () => { + const link = '[docs](https://example.com/__file__)'; + expect(safeMrkdwn('**Before ' + link + ' `__literal__` after**')).toBe( + '*Before `__literal__` after*', + ); + expect(safeMrkdwn('```txt\n__literal__\n```\n# ' + link)).toBe( + '```txt\n__literal__\n```\n**', + ); + const forged = '\0' + 'a'.repeat(64) + ':0\0'; + expect(safeMrkdwn(forged + link)).toBe( + forged.replaceAll('\0', '\ufffd') + '', + ); + const unmatched = Array.from({ length: 256 }, (_, i) => 'x' + '`'.repeat(i + 1) + 'y').join(''); + expect(safeMrkdwn(unmatched)).toBe(unmatched); + }); + + it.each([2790, 2795, 2800, 2805])( + 'retains source atom boundaries through enclosing styles at offset %i', + (offset) => { + const source = + '**Before [docs](https://example.com/__file__?q=**value**) `__literal__` after**'; + const expected = + '*Before `__literal__` after*'; + const messages = renderSlackDocument('x'.repeat(offset) + source); + const sections = messages + .flatMap((message) => message.blocks ?? []) + .flatMap((block) => (block.type === 'section' ? [block.text] : [])); + expect( + sections.some((section) => section.type === 'mrkdwn' && section.text.includes(expected)), + ).toBe(true); + expect(sections.map((section) => section.text).join('')).toBe('x'.repeat(offset) + expected); + const oversized = renderSlackDocument( + '**' + 'x'.repeat(offset) + ' [docs](https://example.com/**path**) after**', + ); + expect( + oversized + .flatMap((message) => message.blocks ?? []) + .every((block) => block.type === 'section' && block.text.type === 'plain_text'), + ).toBe(true); + }, + ); + + it('converts prose but leaves code syntax untouched', () => { + expect( + safeMrkdwn( + '# Title\n**bold** __bold__ [site](https://example.com/a?x=1&y=2)\n```js\n**literal**\n```', + ), + ).toBe( + '*Title*\n*bold* *bold* \n```js\n**literal**\n```', + ); + }); + + it('escapes native mentions and rejects unsafe links without dropping the label', () => { + const rendered = safeMrkdwn( + ' <@U1> <#C1> [bad](javascript:alert) [credentials](https://user:secret@example.com) [safe](https://example.com)', + ); + expect(rendered).toContain('<!here> <@U1> <#C1> bad credentials'); + expect(rendered).toContain(''); + expect(rendered).not.toContain('javascript:'); + expect(rendered).not.toContain('secret'); + for (const mention of ['', '<@U1>', '<#C1>']) { + const message = renderAgentAnswer(mention)[0]; + expect(message.blocks?.[0].type).toBe('section'); + expect(message.text).not.toContain(mention); + } + }); + + it('uses native markdown only for bounded final answers', () => { + const messages = renderAgentAnswer('# Title\n\n**Bold** and [site](https://example.com)'); + expect(messages).toHaveLength(1); + expect(messages[0].blocks).toEqual([ + { type: 'markdown', text: '# Title\n\n**Bold** and [site](https://example.com)' }, + ]); + expect(renderAgentAnswer('a'.repeat(12001))[0].blocks?.[0].type).toBe('section'); + }); + + it('renders headings, tables, code and dividers without losing the fallback', () => { + const messages = renderSlackDocument( + '# Title\n\n| A | B |\n| --- | :---: |\n| 1 | 2 |\n\n```ts\nconst x = "<@U1>";\n```\n\n---\n\nDone', + ); + expect(messages.flatMap((message) => message.blocks?.map((block) => block.type))).toEqual([ + 'header', + 'table', + 'rich_text', + 'divider', + 'section', + ]); + expect(messages.map((message) => message.text).join('\n')).toContain( + 'const x = "<@U1>";', + ); + expect( + messages.flatMap((message) => message.blocks).find((block) => block?.type === 'rich_text'), + ).toEqual({ + type: 'rich_text', + elements: [ + { + type: 'rich_text_preformatted', + elements: [{ type: 'text', text: 'const x = "<@U1>";' }], + }, + ], + }); + }); + + it('falls back to prose for malformed and oversized tables', () => { + for (const value of [ + '| A | B |\n| --- | --- |\n| only one |', + '| A |\n| --- |\n' + '| row |\n'.repeat(21), + ]) { + expect( + renderSlackDocument(value) + .flatMap((message) => message.blocks) + .some((block) => block?.type === 'table'), + ).toBe(false); + } + }); + + it('bounds UTF-8 chunks and reopens long code fences', () => { + const value = '🙂'.repeat(5000); + expect(chunkText(value, 2800).join('')).toBe(value); + for (const chunk of chunkText(value, 2800)) { + expect(Buffer.byteLength(chunk)).toBeLessThanOrEqual(2800); + expect(chunk).not.toContain('\ufffd'); + } + const messages = renderSlackDocument('```\n' + value + '\n```'); + const blocks = messages.flatMap((message) => message.blocks ?? []); + expect(blocks.length).toBeGreaterThan(1); + for (const block of blocks) { + expect(block.type).toBe('rich_text'); + } + for (const message of messages) { + expect(Buffer.byteLength(message.text)).toBeLessThanOrEqual(39000); + expect((message.text.match(/```/g) ?? []).length % 2).toBe(0); + } + }); + + it('retains empty fences and obeys the forty-block payload budget', () => { + for (const value of ['```\n```', '# heading\n\n'.repeat(100)]) { + for (const message of renderSlackDocument(value)) { + expect((message.blocks ?? []).length).toBeLessThanOrEqual(40); + } + const view = run(); + view.snapshot!.text = value; + for (const part of makeSlackPlan(view).parts) { + expect(() => durableSlackMessage(part, rendererVersion)).not.toThrow(); + } + } + }); +}); + +describe('immutable Slack plans', () => { + it('creates deterministic parts, feedback and persisted final presentation', () => { + const view = run(); + const plan = makeSlackPlan(view, true); + expect(plan).toEqual(makeSlackPlan(view, true)); + expect(plan.revision).toMatch(/^[a-f0-9]{64}$/); + expect(plan.rendererVersion).toBe(rendererVersion); + expect(plan.parts[0].operationId).toBe('run-12345678:reply:0'); + expect(plan.parts[0].required).toBe(true); + expect(plan.parts[0].presentation?.format).toBe(presentationFormat); + expect(durableSlackMessage(plan.parts[0], rendererVersion).blocks?.at(-1)?.type).toBe( + 'context_actions', + ); + const saved = structuredClone(plan.parts[0]); + view.snapshot!.text = 'Changed after the operation started'; + expect(durableSlackMessage(saved, rendererVersion).text).toContain('Hello *world*'); + expect(durableSlackMessage(saved, rendererVersion).text).not.toContain('Changed'); + view.plan = plan; + expect(() => makeSlackPlan(view, true)).toThrow('must not be regenerated'); + }); + + it.each(['slack-structured-v2', 'slack-structured-v3', 'slack-structured-v4'])( + 'recovers %s without rerendering', + (version) => { + const part = makeSlackPlan(run()).parts[0]; + expect(durableSlackMessage(part, version).text).toBe(part.text); + expect(supportedRenderer(version)).toBe(true); + }, + ); + + it('preserves persisted Unicode payloads counted by code points, not UTF-16 units', () => { + const part = makeSlackPlan(run()).parts[0]; + part.presentation = { + format: presentationFormat, + payload: JSON.stringify([{ type: 'markdown', text: '🙂'.repeat(12000) }]), + }; + expect(durableSlackMessage(part, 'slack-structured-v3').blocks).toHaveLength(1); + }); + + it('preserves v5 frozen content even when user text resembles an obsolete generated footer', () => { + const frozen = { + operationId: 'legacy', + kind: 'message' as const, + required: true, + text: 'User content\n\n_This run · ID example_\n', + }; + expect(durableSlackMessage(frozen, 'slack-structured-v5').text).toBe(frozen.text); + expect( + durableSlackMessage( + { + ...frozen, + presentation: { + format: presentationFormat, + payload: JSON.stringify([ + { type: 'section', text: { type: 'mrkdwn', text: frozen.text } }, + ]), + }, + }, + 'slack-structured-v5', + ).text, + ).toBe(frozen.text); + }); + + it('recovers legacy text but refuses structured presentation with a legacy or unknown renderer', () => { + const part = makeSlackPlan(run()).parts[0]; + expect(() => durableSlackMessage(part, 'slack-text-v1')).toThrow(); + expect(() => durableSlackMessage(part, 'future')).toThrow(); + delete part.presentation; + expect(durableSlackMessage(part, 'slack-text-v1')).toEqual({ text: part.text }); + expect(supportedRenderer('slack-text-v1')).toBe(true); + expect(supportedRenderer('future')).toBe(false); + }); + + it.each([ + 'null', + '{}', + '[]', + '[{}]', + '[{"type":"unknown"}]', + '[{"type":"divider","url":"https://example.com"}]', + '[{"type":"section","text":{"type":"html","text":"wrong"}}]', + '[{"type":"rich_text","elements":[]}]', + '[{"type":"table","rows":[[{"type":"raw_text","text":"x"}],[]]}]', + '[{"type":"divider"}] {}', + ' '.repeat(64001), + ])('rejects corrupt or unsupported persisted block shapes', (payload) => { + const part = makeSlackPlan(run()).parts[0]; + part.presentation = { format: presentationFormat, payload }; + expect(() => durableSlackMessage(part, rendererVersion)).toThrow(); + }); + + it('strips provider diagnostics on failures and cancellation and does not attach their artifacts', () => { + for (const status of ['failed', 'cancelled'] as const) { + const view = run(); + view.snapshot!.status = status; + view.snapshot!.text = 'secret diagnostic'; + view.snapshot!.artifacts = [artifact]; + const plan = makeSlackPlan(view, true); + expect(plan.parts.some((part) => part.kind === 'artifact')).toBe(false); + expect(plan.parts.map((part) => part.text).join()).not.toContain('secret diagnostic'); + expect( + durableSlackMessage(plan.parts[0], rendererVersion).blocks?.some( + (block) => block.type === 'context_actions', + ), + ).toBe(false); + } + }); + + it('requires a terminal snapshot and a completed Responses cursor', () => { + const view = run(); + view.snapshot!.status = 'running'; + expect(() => makeSlackPlan(view)).toThrow('terminal'); + view.snapshot!.status = 'completed'; + delete view.snapshot!.responseId; + expect(() => makeSlackPlan(view)).toThrow('cursor'); + }); + + it('handles empty answers and unavailable attachments without claiming success text', () => { + const view = run(); + view.snapshot!.text = ' '; + view.snapshot!.artifactsUnavailable = true; + const plan = makeSlackPlan(view, true); + expect(plan.parts[0].text).toContain('finished without a text reply'); + expect(plan.parts[0].text).toContain('Attachments are unavailable'); + expect( + durableSlackMessage(plan.parts[0], rendererVersion).blocks?.some( + (block) => block.type === 'context_actions', + ), + ).toBe(false); + }); + + it('bounds, deduplicates and validates optional artifact operations', () => { + const view = run(); + view.snapshot!.artifacts = [ + artifact, + artifact, + { ...artifact, artifactId: 'bad', filename: '../secret' }, + ]; + const plan = makeSlackPlan(view); + expect(plan.parts.filter((part) => part.kind === 'artifact')).toEqual([ + { + operationId: 'run-12345678:artifact:0', + kind: 'artifact', + required: false, + artifactId: artifact.artifactId, + text: artifact.filename, + }, + ]); + expect(plan.parts.find((part) => part.operationId.endsWith(':artifact-status'))?.required).toBe( + false, + ); + expect( + plan.parts.find((part) => part.operationId.endsWith(':artifact-unavailable')), + ).toBeDefined(); + for (const filename of ['../x', 'a\\b', 'a\u0000b', 'a\u200eb']) { + expect(validArtifact({ ...artifact, filename })).toBe(false); + } + expect(validArtifact({ ...artifact, bytes: 50 * 1024 * 1024 + 1 })).toBe(false); + expect(validArtifact({ ...artifact, sha256: 'A'.repeat(64) })).toBe(false); + }); +}); + +describe('accounting and actor-lane summary', () => { + it('never presents partial costs or malformed values as the run total', () => { + const accounting = { + status: 'available', + currency: 'USD', + amount: '0.05', + basis: 'provider_reported', + coverage: 'complete', + reason: 'priced', + calls: [], + } as const; + expect(accountingPriceDescription({ ...accounting, calls: [] })).toBe( + '$0.05 USD (provider reported)', + ); + for (const value of ['-1', 'NaN', '1e8', '1\n', '00.1']) { + expect(accountingPriceDescription({ ...accounting, amount: value, calls: [] })).toBe( + 'Cost unavailable', + ); + } + expect(accountingPriceDescription({ ...accounting, coverage: 'partial', calls: [] })).toBe( + 'Cost unavailable', + ); + }); + + it('qualifies partial thread totals and only renders backend-authorized session URLs', () => { + const view = run(); + view.sequence = 3; + view.snapshot!.summary = { + version: 1, + scope: 'actor_lane', + includesCurrent: true, + throughSequence: 3, + expectedRuns: 3, + observedRuns: 2, + priorRuns: 1, + costUSD: { + coverage: 'partial', + coveredRuns: 2, + knownValue: '0.04', + basis: 'application_billing', + }, + elapsedMs: { coverage: 'partial', coveredRuns: 1, knownValue: 5000 }, + tokens: { coverage: 'unavailable', coveredRuns: 0 }, + session: { url: 'https://chat.example.com/c/session' }, + }; + const part = makeSlackPlan(view).parts[0]; + expect(part.text).toContain('known $0.04 USD (application billing; partial 2/3 runs)'); + expect(part.text).toContain('known 5.0s processing (partial 1/3)'); + expect(part.text).toContain('tokens unavailable'); + const context = durableSlackMessage(part, rendererVersion).blocks?.find( + (block) => block.type === 'context', + ); + expect(JSON.stringify(context)).not.toContain('View session'); + const plan = makeSlackPlan(view); + expect(plan.parts.filter((part) => part.traceUrl)).toEqual([ + expect.objectContaining({ + kind: 'message', + required: false, + traceUrl: 'https://chat.example.com/c/session', + }), + ]); + expect( + plan.parts + .filter((part) => part.required) + .map((part) => JSON.stringify(part)) + .join(), + ).not.toContain('https://chat.example.com/c/session'); + expect(JSON.stringify(context)).toContain('known $0.04'); + view.snapshot!.summary.throughSequence = 4; + expect(makeSlackPlan(view).parts[0].text).toContain('Your thread: totals unavailable'); + }); + + it.each([ + 'http://example.com/session', + 'https://localhost/session', + 'https://foo.local/session', + 'https://127.0.0.1/session', + 'https://[::1]/session', + 'https://user:secret@example.com/session', + 'https://example.com/session?token=secret', + 'https://example.com/session#secret', + 'https://example.com/evil|mention', + ])('rejects unsafe session URL %s', (url) => { + expect(safeSummarySessionURL(url)).toBe(false); + }); + + it('does not repeat one-run totals in the visible footer', () => { + const view = run(); + view.snapshot!.summary = { + version: 1, + scope: 'actor_lane', + includesCurrent: true, + throughSequence: 1, + expectedRuns: 1, + observedRuns: 1, + priorRuns: 0, + costUSD: { coverage: 'unavailable', coveredRuns: 0 }, + elapsedMs: { coverage: 'unavailable', coveredRuns: 0 }, + tokens: { coverage: 'unavailable', coveredRuns: 0 }, + }; + const message = durableSlackMessage(makeSlackPlan(view).parts[0], rendererVersion); + expect(message.text).toContain('Your thread'); + expect(JSON.stringify(message.blocks)).not.toContain('Your thread'); + }); +}); + +describe('presentation boundaries', () => { + it.each([ + '`__init__ [docs](./README.md)`', + '``a `tick` __init__ [docs](./README.md)``', + '```md\n[docs](./README.md) __init__\n```', + '~~~md\n[docs](./README.md) __init__\n~~~', + '````md\n``` __init__ [docs](./README.md)\n````', + '```md\n[docs](./README.md) __init__', + ])('preserves literal code %s in native blocks and escaped fallback', (code) => { + expect(safeMrkdwn(code)).toBe(code); + expect(renderAgentAnswer(code)[0].blocks).toEqual([{ type: 'markdown', text: code }]); + const document = renderSlackDocument(code); + expect(JSON.stringify(document)).toContain('__init__'); + expect(JSON.stringify(document)).toContain('[docs](./README.md)'); + }); + it.each(['&'.repeat(12000), '🙂'.repeat(12000), '<'.repeat(12000)])( + 'bounds converted native fallback, including expanding text', + (answer) => { + const view = run(); + view.snapshot!.text = answer; + for (const part of makeSlackPlan(view, true).parts) { + expect(part.text.length).toBeLessThanOrEqual(40000); + expect(Buffer.byteLength(part.text)).toBeLessThanOrEqual(39000); + expect(() => durableSlackMessage(part, rendererVersion)).not.toThrow(); + } + }, + ); +}); + +test('legacy required footer recovery removes embedded trace capability while preserving answer and metrics', () => { + const url = 'https://chat.example.com/c/session'; + const part = { + operationId: 'old:reply:0', + kind: 'message' as const, + required: true, + text: `Answer\n\n_This run · ID old_\n_This run: Cost unavailable_\n<${url}|View session>`, + presentation: { + format: presentationFormat, + payload: JSON.stringify([ + { type: 'section', text: { type: 'mrkdwn', text: 'Answer' } }, + { + type: 'context', + elements: [ + { type: 'mrkdwn', text: `Cost unavailable · Run old · <${url}|View session>` }, + ], + }, + ]), + }, + }; + const snapshot = structuredClone(part); + for (const version of ['slack-structured-v2', 'slack-structured-v3', 'slack-structured-v4']) { + const message = durableSlackMessage(part, version); + expect(JSON.stringify(message)).not.toContain(url); + expect(message.text).toContain('Answer'); + expect(message.text).toContain('Cost unavailable'); + } + expect(part).toEqual(snapshot); +}); diff --git a/packages/channel-gateway/src/render.ts b/packages/channel-gateway/src/render.ts new file mode 100644 index 0000000000..6b72e167fa --- /dev/null +++ b/packages/channel-gateway/src/render.ts @@ -0,0 +1,1014 @@ +import { z } from 'zod'; +import { isIP } from 'node:net'; +import { createHash } from 'node:crypto'; +import { gfm } from 'micromark-extension-gfm'; +import { gfmFromMarkdown } from 'mdast-util-gfm'; +import { fromMarkdown } from 'mdast-util-from-markdown'; +import { channelStorageConfigSchema } from 'librechat-data-provider'; +import type { + ChannelArtifact, + ChannelRunView, + ChannelRunUsage, + ChannelRunSummary, + ChannelDeliveryPart, + ChannelDeliveryPlan, + ResponseAccounting, +} from 'librechat-data-provider'; +import type { Nodes, Root, Definition } from 'mdast'; + +export const rendererVersion = 'slack-structured-v6'; +export const presentationFormat = 'slack-blocks-v1'; +export const artifactFailureNotice = + 'One or more attachments could not be confirmed. The answer is preserved; uncertain uploads will not be duplicated automatically.'; +const chunkLimit = 39_000; +const presentationLimit = 64_000; +const supportedStructured = new Set([ + rendererVersion, + 'slack-structured-v5', + 'slack-structured-v4', + 'slack-structured-v3', + 'slack-structured-v2', +]); + +function withinCharacters(value: string, limit: number): boolean { + let count = 0; + for (let index = 0; index < value.length; index++) { + if (++count > limit) { + return false; + } + if ((value.codePointAt(index) ?? 0) > 0xffff) { + index++; + } + } + return true; +} + +const boundedText = (limit: number, empty = false) => + z.string().refine((value) => (empty || value.length > 0) && withinCharacters(value, limit)); +const text = (type: T, limit: number) => + z.strictObject({ type: z.literal(type), text: boundedText(limit) }); +const feedbackButton = z.strictObject({ + text: text('plain_text', 75), + value: z.enum(['+1', '-1']), + accessibility_label: boundedText(75), +}); +const blockSchema = z.discriminatedUnion('type', [ + z.strictObject({ type: z.literal('markdown'), text: boundedText(12_000) }), + z.strictObject({ + type: z.literal('section'), + text: z.union([text('mrkdwn', 3000), text('plain_text', 3000)]), + expand: z.boolean().optional(), + }), + z.strictObject({ type: z.literal('header'), text: text('plain_text', 150) }), + z.strictObject({ type: z.literal('divider') }), + z.strictObject({ type: z.literal('context'), elements: z.array(text('mrkdwn', 3000)).length(1) }), + z.strictObject({ + type: z.literal('rich_text'), + elements: z + .array( + z.strictObject({ + type: z.literal('rich_text_preformatted'), + elements: z.array(text('text', 3000)).length(1), + }), + ) + .length(1), + }), + z.strictObject({ + type: z.literal('table'), + rows: z + .array( + z + .array(z.strictObject({ type: z.literal('raw_text'), text: boundedText(3000, true) })) + .min(1) + .max(20), + ) + .min(1) + .max(20) + .refine((rows) => rows.every((row) => row.length === rows[0].length)), + }), + z.strictObject({ + type: z.literal('context_actions'), + elements: z + .array( + z.strictObject({ + type: z.literal('feedback_buttons'), + action_id: z.literal('channel_feedback'), + positive_button: feedbackButton.refine((button) => button.value === '+1'), + negative_button: feedbackButton.refine((button) => button.value === '-1'), + }), + ) + .length(1), + }), +]); +const blocksSchema = z.array(blockSchema).min(1).max(40); +export type SlackBlock = z.infer; +export interface SlackMessage { + text: string; + blocks?: SlackBlock[]; +} + +/** Semantic text is construction state, never part of a durable or SDK message. */ +interface RenderedMessage extends SlackMessage { + plain: string; +} + +/** Every presentation path uses the same block and serialized-payload boundary. */ +function presentationFor(message: SlackMessage): ChannelDeliveryPart['presentation'] { + const blocks = blocksSchema.safeParse(message.blocks); + if (!blocks.success) return undefined; + const payload = JSON.stringify(blocks.data); + if (Buffer.byteLength(payload) > presentationLimit) return undefined; + return { format: presentationFormat, payload }; +} + +export function supportedRenderer(version: string): boolean { + return version === 'slack-text-v1' || supportedStructured.has(version); +} + +/** Legacy plans embedded session links in required footers; never replay that capability. */ +function legacyMessage(text: string, blocks?: SlackBlock[]): SlackMessage { + const footer = text.lastIndexOf('\n\n_This run · ID '); + const fallback = + footer < 0 + ? text + : text.slice(0, footer) + text.slice(footer).replace(/\n<[^>\r\n]+\|View session>/g, ''); + return { + text: fallback, + ...(blocks + ? { + blocks: blocks.map((block) => + block.type === 'context' + ? { + ...block, + elements: block.elements.map((element) => ({ + ...element, + text: element.text.replace(/ · <[^>\r\n]+\|View session>/g, ''), + })), + } + : block, + ), + } + : {}), + }; +} + +export function durableSlackMessage(part: ChannelDeliveryPart, renderer: string): SlackMessage { + const preserve = + renderer === rendererVersion || renderer === 'slack-structured-v5' || !!part.traceUrl; + if (!part.presentation) { + return preserve ? { text: part.text } : legacyMessage(part.text); + } + if ( + !supportedStructured.has(renderer) || + part.presentation.format !== presentationFormat || + Buffer.byteLength(part.presentation.payload) > presentationLimit + ) { + throw new Error('Unsupported durable presentation'); + } + try { + const blocks = blocksSchema.parse(JSON.parse(part.presentation.payload)); + return preserve ? { text: part.text, blocks } : legacyMessage(part.text, blocks); + } catch { + throw new Error('Invalid persisted Slack blocks'); + } +} + +export function escapeSlackText(value: string): string { + return value.replace(/&/g, '&').replace(//g, '>'); +} + +function displayUrl(raw: string): boolean { + try { + const url = new URL(raw); + return ( + ['http:', 'https:'].includes(url.protocol) && + !!url.hostname && + !url.username && + !url.password && + !/[<>|\s]/.test(raw) + ); + } catch { + return false; + } +} + +interface InlineDocument { + text: string; + plain: string; + spans: { start: number; end: number }[]; + replacements: { start: number; end: number; plain: string }[]; +} + +interface MarkdownDocument { + source: string; + root: Root; + definitions: Map; +} + +function bounds(node: Nodes): [number, number] { + const start = node.position?.start.offset; + const end = node.position?.end.offset; + if (start === undefined || end === undefined) throw new Error('Missing Markdown position'); + return [start, end]; +} + +function parseMarkdown(source: string): MarkdownDocument { + const root = fromMarkdown(source, { + // Slack renders no HTML; keep HTML-looking mentions as text, not opaque HTML blocks. + extensions: [gfm(), { disable: { null: ['htmlFlow', 'htmlText'] } }], + mdastExtensions: [gfmFromMarkdown()], + }); + const definitions = new Map(); + const pending: Nodes[] = [root]; + while (pending.length) { + const node = pending.pop()!; + if (node.type === 'definition' && !definitions.has(node.identifier)) + definitions.set(node.identifier, node); + if ('children' in node) + for (let index = node.children.length - 1; index >= 0; index--) + pending.push(node.children[index]); + } + return { source, root, definitions }; +} + +function labelText(node: Nodes): string { + let text = ''; + const pending: Nodes[] = [node]; + while (pending.length) { + const child = pending.pop()!; + if ('children' in child) { + for (let index = child.children.length - 1; index >= 0; index--) + pending.push(child.children[index]); + } else if ('value' in child) text += child.value; + else if ('alt' in child) text += child.alt ?? ''; + else if (child.type === 'break') text += '\n'; + } + return text; +} + +/** Parse once; the AST owns grammar and emitted links/code never reenter a formatter. */ +function inlineDocument(document: MarkdownDocument, initial: Nodes, wire = true): InlineDocument { + const output: InlineDocument = { text: '', plain: '', spans: [], replacements: [] }; + type Task = + | { node: Nodes } + | { text: string; plain: string; atomic?: boolean } + | { end: { start: number; end: number } }; + const pending: Task[] = [{ node: initial }]; + const raw = (node: Nodes) => document.source.slice(...bounds(node)); + const literal = (value: string): Task => ({ + text: wire ? escapeSlackText(value) : value, + plain: value, + }); + while (pending.length) { + const task = pending.pop()!; + if ('end' in task) { + task.end.end = output.text.length; + continue; + } + if ('text' in task) { + const start = output.text.length; + output.text += task.text; + output.plain += task.plain; + const end = output.text.length; + if (task.atomic) output.spans.push({ start, end }); + if (task.plain !== decodeSlackText(task.text)) + output.replacements.push({ start, end, plain: task.plain }); + continue; + } + const node = task.node; + if ( + node.type === 'link' || + node.type === 'image' || + node.type === 'linkReference' || + node.type === 'imageReference' + ) { + const target = 'url' in node ? node : document.definitions.get(node.identifier); + const label = labelText(node); + const url = target?.url; + if (url && displayUrl(url)) { + pending.push({ + text: wire + ? '<' + + escapeSlackText(url) + + (label === url ? '' : '|' + escapeSlackText(label || url)) + + '>' + : raw(node), + plain: label && label !== url ? label + ' (' + url + ')' : url, + atomic: true, + }); + } else { + // An unsafe autolink's label can itself contain credentials. + pending.push(literal(url && label === url ? 'Link unavailable' : label)); + } + continue; + } + if (node.type === 'definition') { + if (!wire && displayUrl(node.url)) pending.push(literal(raw(node))); + continue; + } + if (node.type === 'code' || node.type === 'inlineCode') { + pending.push({ + text: wire ? escapeSlackText(raw(node)) : raw(node), + plain: node.value, + atomic: true, + }); + continue; + } + if (node.type === 'text') { + pending.push(wire ? literal(node.value) : literal(raw(node))); + continue; + } + if (!('children' in node)) { + pending.push(literal(node.type === 'break' && wire ? '\n' : raw(node))); + continue; + } + const style = wire + ? ( + { strong: '*', emphasis: '_', delete: '~', heading: '*' } as Partial< + Record + > + )[node.type] + : undefined; + const children = node.children; + const [start, end] = bounds(node); + const tasks: Task[] = []; + if (style) tasks.push({ text: style, plain: '' }); + let cursor = style && children.length ? bounds(children[0])[0] : start; + for (const child of children) { + const [childStart, childEnd] = bounds(child); + if (cursor < childStart) tasks.push(literal(document.source.slice(cursor, childStart))); + tasks.push({ node: child }); + cursor = childEnd; + } + if (!style && cursor < end) tasks.push(literal(document.source.slice(cursor, end))); + if (style) { + const span = { start: output.text.length, end: 0 }; + output.spans.push(span); + tasks.push({ text: style, plain: '' }, { end: span }); + } + for (let index = tasks.length - 1; index >= 0; index--) pending.push(tasks[index]); + } + return output; +} + +function decodeSlackText(value: string): string { + return value.replace(/&(amp|lt|gt);/g, (_match, entity: string) => { + if (entity === 'amp') return '&'; + if (entity === 'lt') return '<'; + return '>'; + }); +} + +function plainSlice(document: InlineDocument, start: number, end: number): string { + let plain = ''; + let cursor = start; + for (const replacement of document.replacements) { + if (replacement.end <= start) continue; + if (replacement.start >= end) break; + plain += decodeSlackText(document.text.slice(cursor, replacement.start)) + replacement.plain; + cursor = replacement.end; + } + return plain + decodeSlackText(document.text.slice(cursor, end)); +} + +export function safeMrkdwn(value: string): string { + const document = parseMarkdown(value); + return inlineDocument(document, document.root).text; +} + +/** Byte limits are stricter than Slack's character limits and never split a code point. */ +export function chunkText(value: string, limit: number): string[] { + if (!Number.isInteger(limit) || limit < 4) { + throw new Error('Invalid chunk limit'); + } + const chunks: string[] = []; + let remaining = Buffer.from(value); + while (remaining.length > limit) { + let boundary = remaining.subarray(0, limit + 1).lastIndexOf(10); + if (boundary <= 0) { + boundary = limit; + while ((remaining[boundary] & 0xc0) === 0x80) { + boundary--; + } + } + chunks.push(remaining.subarray(0, boundary).toString()); + remaining = remaining.subarray(boundary + (remaining[boundary] === 10 ? 1 : 0)); + } + if (remaining.length || !chunks.length) { + chunks.push(remaining.toString()); + } + return chunks; +} + +/** Recognize wire-format atoms before enforcing Slack's per-section byte limit. */ +function mrkdwnChunks(document: InlineDocument, limit: number): string[] | null { + const value = document.text; + const protectedEnds = new Map(document.spans.map((span) => [span.start, span.end])); + const chunks: string[] = []; + let chunk = ''; + let bytes = 0; + let cursor = 0; + const addText = (text: string) => { + for (const character of text) { + const size = Buffer.byteLength(character); + if (bytes + size > limit) { + chunks.push(chunk); + chunk = ''; + bytes = 0; + } + chunk += character; + bytes += size; + } + }; + for (let index = 0; index < value.length; ) { + let end = protectedEnds.get(index); + if (end === undefined && value[index] === '&') { + if (value.startsWith('&', index)) end = index + 5; + else if (value.startsWith('<', index) || value.startsWith('>', index)) end = index + 4; + } + if (end === undefined) { + index++; + continue; + } + const atom = value.slice(index, end); + const size = Buffer.byteLength(atom); + if (size > limit) return null; + addText(value.slice(cursor, index)); + if (bytes + size > limit) { + chunks.push(chunk); + chunk = ''; + bytes = 0; + } + chunk += atom; + bytes += size; + cursor = end; + index = end; + } + addText(value.slice(cursor)); + if (chunk || !chunks.length) chunks.push(chunk); + return chunks; +} + +/** Escape before packing so entity expansion also obeys the wire byte budget. */ +function plainChunks(value: string, limit: number): string[] { + return ( + mrkdwnChunks( + { text: escapeSlackText(value), plain: value, spans: [], replacements: [] }, + limit, + ) ?? [] + ).map(decodeSlackText); +} + +function plainMessage(value: string): RenderedMessage { + return { + text: escapeSlackText(value), + plain: value, + blocks: plainChunks(value, 2800).map((chunk) => ({ + type: 'section', + text: { type: 'plain_text', text: chunk }, + })), + }; +} + +export function renderSlackDocument(markdown: string): RenderedMessage[] { + const document = parseMarkdown(markdown); + const parts: RenderedMessage[] = []; + let current: RenderedMessage = { text: '', plain: '', blocks: [] }; + const flush = () => { + if (current.text || current.blocks?.length) { + parts.push(current); + current = { text: '', plain: '', blocks: [] }; + } + }; + const add = (fallback: string, block: SlackBlock, plain: string) => { + if ( + (current.blocks?.length ?? 0) >= 40 || + Buffer.byteLength(current.text + fallback) + 2 > chunkLimit + ) + flush(); + const separator = current.text ? '\n\n' : ''; + current.text += separator + fallback; + current.plain += separator + plain; + current.blocks?.push(block); + }; + const prose = (node: Nodes) => { + const inline = inlineDocument(document, node); + const formatted = mrkdwnChunks(inline, 2800); + if (!formatted) { + for (const chunk of plainChunks(inline.plain, 2800)) { + if (chunk.trim()) + add( + escapeSlackText(chunk), + { + type: 'section', + text: { type: 'plain_text', text: chunk }, + }, + chunk, + ); + } + return; + } + let offset = 0; + for (const chunk of formatted) { + if (chunk.trim()) + add( + chunk, + { + type: 'section', + text: { type: 'mrkdwn', text: chunk }, + expand: true, + }, + plainSlice(inline, offset, offset + chunk.length), + ); + offset += chunk.length; + } + }; + for (const node of document.root.children) { + if (node.type === 'definition') continue; + if (node.type === 'code') { + for (const chunk of plainChunks(node.value, 2700)) { + if (!chunk) + add( + '```\n\n```', + { + type: 'section', + text: { type: 'mrkdwn', text: '```\n\n```' }, + }, + '', + ); + else + add( + '```\n' + escapeSlackText(chunk) + '\n```', + { + type: 'rich_text', + elements: [ + { type: 'rich_text_preformatted', elements: [{ type: 'text', text: chunk }] }, + ], + }, + chunk, + ); + } + continue; + } + if (node.type === 'table') { + const rows = node.children.map((row) => + row.children.map((cell) => ({ + type: 'raw_text', + text: inlineDocument(document, cell).plain, + })), + ); + const inline = inlineDocument(document, node); + const block = blockSchema.safeParse({ type: 'table', rows }); + if (block.success && Buffer.byteLength(inline.text) <= 2800) { + flush(); + add(inline.text, block.data, inline.plain); + flush(); + } else prose(node); + continue; + } + if (node.type === 'thematicBreak') { + add('────────', { type: 'divider' }, '────────'); + continue; + } + if (node.type === 'heading') { + const inline = inlineDocument(document, node); + if ( + inline.plain && + withinCharacters(inline.plain, 150) && + Buffer.byteLength(inline.text) <= 2800 + ) { + add( + inline.text, + { type: 'header', text: { type: 'plain_text', text: inline.plain } }, + inline.plain, + ); + continue; + } + } + prose(node); + } + flush(); + return parts.length + ? parts + : [ + { + text: '_(the agent returned an empty reply)_', + plain: '(the agent returned an empty reply)', + }, + ]; +} + +export function renderAgentAnswer(value: string): RenderedMessage[] { + if (!value.trim() || !withinCharacters(value, 12_000) || /<[@!#]/.test(value)) { + return renderSlackDocument(value); + } + const document = parseMarkdown(value); + const fallback = inlineDocument(document, document.root); + if (Buffer.byteLength(fallback.text) > chunkLimit) return renderSlackDocument(value); + const native = inlineDocument(document, document.root, false).text; + if (!withinCharacters(native, 12000)) return renderSlackDocument(value); + return [ + { text: fallback.text, plain: fallback.plain, blocks: [{ type: 'markdown', text: native }] }, + ]; +} + +const decimal = /^(0|[1-9][0-9]{0,63})(\.[0-9]{1,18})?$/; +const model = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/; +const validAmount = (value?: string): value is string => + typeof value === 'string' && value.length <= 64 && decimal.test(value); +const validBasis = (basis?: string): boolean => + basis === 'application_billing' || basis === 'provider_reported'; + +export function accountingPriceDescription(accounting?: ResponseAccounting): string { + if ( + accounting?.status === 'available' && + accounting.currency === 'USD' && + accounting.coverage === 'complete' && + accounting.reason === 'priced' && + validAmount(accounting.amount) && + validBasis(accounting.basis) + ) { + return `$${accounting.amount} USD (${accounting.basis?.replaceAll('_', ' ')})`; + } + return 'Cost unavailable'; +} + +function accountingDescription(accounting?: ResponseAccounting): string { + const labels = new Set(); + for (const call of accounting?.calls ?? []) { + if ( + !['provider_reported', 'runtime_reported'].includes(call.modelSource) || + !call.model || + !model.test(call.model) + ) { + continue; + } + labels.add( + (call.provider && model.test(call.provider) ? call.provider + '/' : '') + call.model, + ); + if (labels.size === 4) { + break; + } + } + return ( + accountingPriceDescription(accounting) + (labels.size ? ' · ' + [...labels].join(', ') : '') + ); +} + +function validUsage( + usage?: Pick, +): boolean { + return ( + !!usage && + [usage.inputTokens, usage.outputTokens, usage.totalTokens].every( + (value) => Number.isSafeInteger(value) && value >= 0, + ) && + usage.totalTokens - usage.inputTokens === usage.outputTokens + ); +} + +function validSummary( + summary: ChannelRunSummary | undefined, + sequence: number, +): summary is ChannelRunSummary { + return ( + !!summary && + summary.version === 1 && + summary.scope === 'actor_lane' && + summary.includesCurrent && + Number.isSafeInteger(sequence) && + sequence > 0 && + summary.throughSequence === sequence && + summary.expectedRuns === sequence && + summary.priorRuns >= 0 && + summary.observedRuns > 0 && + summary.observedRuns <= sequence && + Number.isSafeInteger(summary.observedRuns) && + summary.observedRuns - 1 === summary.priorRuns + ); +} + +function validCoverage(coverage: string, covered: number, summary: ChannelRunSummary): boolean { + return ( + Number.isSafeInteger(covered) && + covered >= 0 && + covered <= summary.observedRuns && + ((coverage === 'complete' && covered === summary.expectedRuns) || + (coverage === 'partial' && covered > 0 && covered < summary.expectedRuns) || + (coverage === 'unavailable' && covered === 0)) + ); +} + +export function safeSummarySessionURL(raw: string): boolean { + try { + const url = new URL(raw); + const host = url.hostname.toLowerCase().replace(/\.$/, ''); + return ( + raw.length <= 2048 && + url.protocol === 'https:' && + !url.username && + !url.password && + !url.search && + !url.hash && + !/[<>|\s]/.test(raw) && + !!host && + !isIP(host.replace(/^\[|\]$/g, '')) && + host.includes('.') && + !/\.(localhost|local|localdomain|internal|lan|home|test|invalid|example)$/.test(host) + ); + } catch { + return false; + } +} + +function shortRunId(id: string): string { + return model.test(id) && !/[/:]/.test(id) + ? id.slice(0, 8) + : createHash('sha256').update(id).digest('hex').slice(0, 8); +} + +function threadDetails(run: ChannelRunView): string[] { + const summary = run.snapshot?.summary; + if (!validSummary(summary, run.sequence)) { + return ['Your thread: totals unavailable']; + } + const parts = [`Your thread · ${summary.expectedRuns} runs`]; + const cost = summary.costUSD; + let price = 'cost unavailable'; + if (validCoverage(cost.coverage, cost.coveredRuns, summary) && validBasis(cost.basis)) { + if (cost.coverage === 'complete' && validAmount(cost.value)) { + price = `$${cost.value} USD (${cost.basis?.replaceAll('_', ' ')})`; + } else if (cost.coverage === 'partial' && validAmount(cost.knownValue)) { + price = `known $${cost.knownValue} USD (${cost.basis?.replaceAll('_', ' ')}; partial ${cost.coveredRuns}/${summary.expectedRuns} runs)`; + } + } + parts.push(price); + const elapsed = summary.elapsedMs; + if ( + validCoverage(elapsed.coverage, elapsed.coveredRuns, summary) && + elapsed.coverage === 'complete' && + Number.isFinite(elapsed.value) && + (elapsed.value ?? -1) >= 0 + ) { + parts.push(`${((elapsed.value ?? 0) / 1000).toFixed(1)}s processing`); + } else if ( + validCoverage(elapsed.coverage, elapsed.coveredRuns, summary) && + elapsed.coverage === 'partial' && + Number.isFinite(elapsed.knownValue) && + (elapsed.knownValue ?? -1) >= 0 + ) { + parts.push( + `known ${((elapsed.knownValue ?? 0) / 1000).toFixed(1)}s processing (partial ${elapsed.coveredRuns}/${summary.expectedRuns})`, + ); + } else { + parts.push('time unavailable'); + } + const tokens = summary.tokens; + if ( + validCoverage(tokens.coverage, tokens.coveredRuns, summary) && + tokens.coverage === 'complete' && + validUsage(tokens.value) + ) { + parts.push(`${tokens.value?.totalTokens} tokens`); + } else if ( + validCoverage(tokens.coverage, tokens.coveredRuns, summary) && + tokens.coverage === 'partial' && + validUsage(tokens.knownValue) + ) { + parts.push( + `known ${tokens.knownValue?.totalTokens} tokens (partial ${tokens.coveredRuns}/${summary.expectedRuns})`, + ); + } else { + parts.push('tokens unavailable'); + } + return parts; +} + +function appendFooter(parts: RenderedMessage[], run: ChannelRunView): void { + const snapshot = run.snapshot; + if (!snapshot) { + throw new Error('Missing run snapshot'); + } + const id = shortRunId(run.runId); + const elapsed = + Number.isFinite(snapshot.elapsedMs) && snapshot.elapsedMs > 0 + ? `${(snapshot.elapsedMs / 1000).toFixed(1)}s` + : ''; + const labels = [accountingPriceDescription(snapshot.accounting), elapsed, 'Run ' + id].filter( + Boolean, + ); + const summary = snapshot.summary; + let line = labels.join(' · '); + const details = threadDetails(run); + if (!validSummary(summary, run.sequence) || summary.expectedRuns > 1) { + line += '\n' + details.slice(0, 2).join(' · '); + } + const usage = + validUsage(snapshot.usage) && snapshot.usage + ? ` · ${snapshot.usage.totalTokens} tokens (${snapshot.usage.inputTokens} in / ${snapshot.usage.outputTokens} out)` + : ''; + const fallback = safeMrkdwn( + `\n\n_This run · ID ${id}${elapsed ? ' · ' + elapsed : ''}${usage}_\n_This run: ${accountingDescription(snapshot.accounting)}_\n_${details.join(' · ')}_`, + ); + let last = parts[parts.length - 1]; + if ( + !last || + (last.blocks?.length ?? 0) >= 40 || + Buffer.byteLength(last.text + fallback) > chunkLimit + ) { + last = { text: '', plain: '', blocks: [] }; + parts.push(last); + } + const footer = parseMarkdown(fallback); + last.plain = + (last.plain ?? decodeSlackText(last.text)) + inlineDocument(footer, footer.root).plain; + last.text += fallback; + (last.blocks ??= []).push({ type: 'context', elements: [{ type: 'mrkdwn', text: line }] }); +} + +function appendFeedback(parts: RenderedMessage[]): void { + let last = parts[parts.length - 1]; + if (!last || (last.blocks?.length ?? 0) >= 40) { + last = { text: 'Answer feedback', plain: 'Answer feedback', blocks: [] }; + parts.push(last); + } + (last.blocks ??= []).push({ + type: 'context_actions', + elements: [ + { + type: 'feedback_buttons', + action_id: 'channel_feedback', + positive_button: { + text: { type: 'plain_text', text: 'Helpful' }, + value: '+1', + accessibility_label: 'Mark this answer helpful', + }, + negative_button: { + text: { type: 'plain_text', text: 'Not helpful' }, + value: '-1', + accessibility_label: 'Mark this answer not helpful', + }, + }, + ], + }); +} + +export function validArtifact(artifact: ChannelArtifact): boolean { + return ( + artifact.artifactId.length > 0 && + Buffer.byteLength(artifact.artifactId) <= 512 && + artifact.filename.length > 0 && + Buffer.byteLength(artifact.filename) <= 720 && + !artifact.filename.includes('/') && + !/[\\\p{Cc}\p{Cf}]/u.test(artifact.filename) && + Number.isSafeInteger(artifact.bytes) && + artifact.bytes >= 0 && + artifact.bytes <= 50 * 1024 * 1024 && + /^[a-f0-9]{64}$/.test(artifact.sha256) + ); +} + +export function makeSlackPlan( + run: ChannelRunView, + native = false, + maxDeliveryParts = channelStorageConfigSchema.shape.maxDeliveryParts.parse(undefined), +): ChannelDeliveryPlan { + const budget = channelStorageConfigSchema.shape.maxDeliveryParts.parse(maxDeliveryParts); + if (run.plan) { + throw new Error('Existing delivery plans must not be regenerated'); + } + const snapshot = run.snapshot; + if (!snapshot || !['completed', 'failed', 'cancelled'].includes(snapshot.status)) { + throw new Error('Missing terminal snapshot'); + } + if (snapshot.status === 'completed' && !snapshot.responseId) { + throw new Error('Completed snapshot has no response cursor'); + } + const empty = snapshot.status === 'completed' && !snapshot.text.trim(); + let answer = snapshot.text; + if (snapshot.status === 'failed') { + answer = + 'Sorry — something went wrong while talking to the agent. Please try again in a moment.'; + } else if (snapshot.status === 'cancelled') { + answer = 'This request was cancelled.'; + } + if (empty) { + answer = + 'The Agent finished without a text reply.' + + (snapshot.artifacts?.length + ? ' Attachments are subject to this channel’s delivery limits.' + : ''); + } + if (snapshot.artifactsUnavailable) { + answer += '\n\nAttachments are unavailable. The answer is preserved.'; + } + let messages = native ? renderAgentAnswer(answer) : renderSlackDocument(answer); + appendFooter(messages, run); + if (native && snapshot.status === 'completed' && !empty) { + appendFeedback(messages); + } + if (messages.length > budget) { + const notice = + '\n\nReply shortened to fit this channel’s delivery limit. The full answer remains in the saved execution.'; + const plain = plainChunks( + messages.map((message) => message.plain).join('\n\n'), + chunkLimit - Buffer.byteLength(notice), + ); + const selected = plain.slice(0, budget); + if (plain.length > budget) selected[selected.length - 1] += notice; + messages = selected.map(plainMessage); + } + if (!messages.length || messages.length > 64) { + throw new Error('Durable answer exceeds part budget'); + } + const parts: ChannelDeliveryPart[] = messages.map((message, index) => { + const presentation = presentationFor(message); + return { + operationId: `${run.runId}:reply:${index}`, + kind: 'message', + required: true, + text: message.text, + ...(presentation ? { presentation } : {}), + }; + }); + const summary = snapshot.summary; + const traceUrl = validSummary(summary, run.sequence) && summary.session?.url; + if (traceUrl && safeSummarySessionURL(traceUrl)) { + parts.push({ + operationId: `${run.runId}:trace:0`, + kind: 'message', + required: false, + text: safeMrkdwn(`[View session](${traceUrl})`), + traceUrl, + }); + } + const seen = new Set(); + let invalid = false; + if (snapshot.status === 'completed') { + for (const [index, artifact] of (snapshot.artifacts ?? []).entries()) { + if (index >= 20 || !validArtifact(artifact) || seen.has(artifact.artifactId)) { + invalid = true; + continue; + } + seen.add(artifact.artifactId); + parts.push({ + operationId: `${run.runId}:artifact:${index}`, + kind: 'artifact', + required: false, + artifactId: artifact.artifactId, + text: artifact.filename, + }); + } + } + if (seen.size) { + parts.push({ + operationId: `${run.runId}:artifact-status`, + kind: 'message', + required: false, + text: artifactFailureNotice, + }); + } + if (invalid) { + parts.push({ + operationId: `${run.runId}:artifact-unavailable`, + kind: 'message', + required: false, + text: 'One or more attachments are unavailable. The answer is preserved.', + }); + } + if (parts.length > budget) { + const required = parts.filter((part) => part.required); + const remaining = budget - required.length; + // Artifact delivery and its failure notice form a group. Never publish uploads without it. + const optional = parts.filter( + (part) => + !part.required && + part.kind !== 'artifact' && + !part.operationId.endsWith(':artifact-status'), + ); + const artifacts = parts.filter((part) => part.kind === 'artifact'); + const status = parts.find((part) => part.operationId.endsWith(':artifact-status')); + const selected = remaining >= 2 && status ? [...artifacts.slice(0, remaining - 1), status] : []; + selected.push(...optional.slice(0, remaining - selected.length)); + parts.splice(0, parts.length, ...required, ...selected); + const last = required[required.length - 1]; + const notice = + '\n\nSome attachments or session links were omitted by this channel’s delivery limit.'; + last.text += notice; + const message = durableSlackMessage(last, rendererVersion); + const blocks = message.blocks && [ + ...message.blocks, + { + type: 'section' as const, + text: { type: 'plain_text' as const, text: notice.trim() }, + }, + ]; + // Preserve formatting when it fits; fallback obeys the same block and payload boundary. + last.presentation = + presentationFor({ text: last.text, blocks }) ?? + presentationFor(plainMessage(messages[required.length - 1].plain + notice)); + } + const plan = { revision: '', rendererVersion, parts }; + plan.revision = createHash('sha256').update(JSON.stringify(plan)).digest('hex'); + return plan; +} diff --git a/packages/channel-gateway/src/review.spec.ts b/packages/channel-gateway/src/review.spec.ts new file mode 100644 index 0000000000..61b0decbb2 --- /dev/null +++ b/packages/channel-gateway/src/review.spec.ts @@ -0,0 +1,626 @@ +import { DEFAULT_CHANNEL_GATEWAY_POLICY } from 'librechat-data-provider'; +import type { ResponseReviewDecision } from 'librechat-data-provider'; +import type { ChannelBundle, Review } from './types'; +import type { ReviewInteraction } from './review'; +import { ReviewFlow, nativeDecision, reviewModal, simpleChoices } from './review'; +import { ChannelClient } from './client'; +import { loadConfig } from './config'; +import { SlackClient } from './slack'; + +const config = loadConfig({ + CHANNEL_SERVICE_TOKEN: 'test-service', + CHANNEL_TENANT_ID: 'tenant', + CHANNEL_ID: 'binding', +}); +const bundle: ChannelBundle = { + gateway: { version: 1, ...DEFAULT_CHANNEL_GATEWAY_POLICY }, + 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' }, +}; +const ref = () => ({ + runId: 'run', + revision: 'r1', + actionId: 'action', + channelId: 'C1', + actorId: 'U1', + expiresAt: Date.now() + 60000, +}); +const interaction = (): ReviewInteraction => ({ + teamId: 'T1', + appId: 'A1', + actorId: 'U1', + channelId: 'C1', + triggerId: 'trigger', +}); +const action = (expiresAt = Date.now() + 60000): NonNullable => ({ + actionId: 'action', + expiresAt, + payload: { + type: 'tool_approval', + action_requests: [{ name: 'read_data', arguments: { table: 'public' }, tool_call_id: 'call' }], + review_configs: [ + { action_name: 'read_data', tool_call_id: 'call', allowed_decisions: ['approve', 'reject'] }, + ], + }, +}); +const question = (expiresAt = Date.now() + 60000): NonNullable => ({ + actionId: 'action', + expiresAt, + payload: { + type: 'ask_user_question', + question: { + question: 'Which one?', + options: [ + { label: 'One', value: 'first' }, + { label: 'Two', value: 'second' }, + ], + }, + }, +}); +const json = (body: object) => + new Response(JSON.stringify(body), { headers: { 'Content-Type': 'application/json' } }); +const receipt = () => + json({ responseId: 'resp_one', actionId: 'action', intentId: 'intent', status: 'queued' }); +function setup(gatewayConfig = config) { + const backend = jest.fn, Parameters>(); + const slack = jest + .fn, Parameters>() + .mockImplementation(async () => json({ ok: true, view: { id: 'view' } })); + return { + backend, + slack, + flow: new ReviewFlow( + new ChannelClient(gatewayConfig, backend), + new SlackClient(gatewayConfig, undefined, slack), + ), + }; +} +const approvalValues = { tool_0: { decision: { selected_option: { value: 'approve' } } } }; +function submission(reference = ref()): ReviewInteraction { + return { + ...interaction(), + view: { + callbackId: 'channel_native_review', + privateMetadata: JSON.stringify(reference), + values: approvalValues, + }, + }; +} + +describe('native review rendering and validation', () => { + test('tool arguments are shown only in a plain-text private modal', () => { + const reference = ref(); + const modal = reviewModal(reference, action(reference.expiresAt)); + expect(JSON.stringify(modal)).toContain('Arguments:'); + expect(JSON.stringify(modal)).not.toContain('mrkdwn'); + expect(nativeDecision(action(), approvalValues)).toEqual({ + actionId: 'action', + decisions: [{ tool_call_id: 'call', decision: 'approve', scope: 'once' }], + }); + }); + test('does not invent unsupported approval decisions', () => { + const pending = action(); + if (pending.payload.type !== 'tool_approval') throw new Error(); + pending.payload.review_configs[0].allowed_decisions = ['edit', 'respond']; + expect(reviewModal(ref(), pending)).toBeNull(); + expect(() => nativeDecision(pending, approvalValues)).toThrow(); + }); + test('joins approval configuration by tool call ID, never position', () => { + const pending = action(); + if (pending.payload.type !== 'tool_approval') throw new Error(); + pending.payload.action_requests.push({ + name: 'read_data', + arguments: {}, + tool_call_id: 'second', + }); + pending.payload.review_configs.unshift({ + action_name: 'read_data', + tool_call_id: 'second', + allowed_decisions: ['reject'], + }); + expect(() => + nativeDecision(pending, { + ...approvalValues, + tool_1: { decision: { selected_option: { value: 'approve' } } }, + }), + ).toThrow('not allowed'); + }); + test('uses ordinal values but sends the original answer', () => { + const pending = question(); + expect(simpleChoices(pending)).toBe(true); + expect( + nativeDecision(pending, { question_0: { choice: { selected_option: { value: '1' } } } }), + ).toEqual({ actionId: 'action', answer: 'second' }); + expect(() => + nativeDecision(pending, { question_0: { choice: { selected_option: { value: '-1' } } } }), + ).toThrow(); + }); + test('cannot submit a written and selected answer or repeated single choice', () => { + expect(() => + nativeDecision(question(), { + question_0_text: { answer: { value: 'text' } }, + question_0: { choice: { selected_option: { value: '0' } } }, + }), + ).toThrow(); + expect(() => + nativeDecision(question(), { + question_0: { choice: { selected_options: [{ value: '0' }, { value: '1' }] } }, + }), + ).toThrow(); + }); + test('supports multiple independently keyed questions and multiple selections', () => { + const pending: NonNullable = { + actionId: 'action', + expiresAt: ref().expiresAt, + payload: { + type: 'ask_user_question', + question: { question: 'First' }, + questions: [ + { id: 'a', question: 'First' }, + { + id: 'b', + question: 'Select', + multiSelect: true, + options: [ + { label: '1', value: 'one' }, + { label: '2', value: 'two' }, + ], + }, + ], + }, + }; + expect( + nativeDecision(pending, { + question_0_text: { answer: { value: 'hello' } }, + question_1: { choice: { selected_options: [{ value: '0' }, { value: '1' }] } }, + }), + ).toEqual({ actionId: 'action', answers: { a: 'hello', b: 'one, two' } }); + expect(simpleChoices(pending)).toBe(false); + }); + test('oversized content uses browser fallback instead of truncating a decision', () => { + const pending = action(); + if (pending.payload.type !== 'tool_approval') throw new Error(); + pending.payload.action_requests[0].arguments = 'a'.repeat(3000); + expect(reviewModal(ref(), pending)).toBeNull(); + }); +}); + +describe('actor-bound review handling', () => { + test('propagates the acknowledgement deadline through authorized requests', async () => { + const { backend, flow } = setup(); + const reference = ref(); + const controller = new AbortController(); + backend + .mockResolvedValueOnce( + json({ actionId: 'action', pendingAction: action(reference.expiresAt) }), + ) + .mockResolvedValueOnce(receipt()); + await flow.submit(submission(reference), bundle, controller.signal); + const signals = backend.mock.calls.map(([, init]) => init?.signal); + expect(signals).toHaveLength(2); + controller.abort(); + expect(signals.every((signal) => signal?.aborted)).toBe(true); + }); + + test('private choice uses the exact authorized option and actor', async () => { + const { backend, flow } = setup(); + const reference = ref(); + backend + .mockResolvedValueOnce( + json({ actionId: 'action', pendingAction: question(reference.expiresAt) }), + ) + .mockResolvedValueOnce(receipt()); + await flow.choice(JSON.stringify({ ...reference, choice: 1 }), interaction(), bundle); + expect(JSON.parse(String(backend.mock.calls[1][1]?.body))).toMatchObject({ + actor: { externalUserId: 'U1' }, + externalChannelId: 'C1', + decision: { actionId: 'action', answer: 'second' }, + }); + }); + + test.each([409, 403, 404, 410])( + 'stale private choice read %i sends a private unavailable notice', + async (status) => { + const { backend, slack, flow } = setup(); + backend.mockResolvedValueOnce(new Response('{}', { status })); + await expect( + flow.choice(JSON.stringify({ ...ref(), choice: 1 }), interaction(), bundle), + ).resolves.toBeUndefined(); + expect(backend).toHaveBeenCalledTimes(1); + expect(JSON.stringify(slack.mock.calls)).toContain('unavailable'); + }, + ); + + test('a concurrent decision conflict is unavailable while unexpected failures still propagate', async () => { + const { backend, slack, flow } = setup(); + const reference = ref(); + backend + .mockResolvedValueOnce( + json({ actionId: 'action', pendingAction: question(reference.expiresAt) }), + ) + .mockResolvedValueOnce(new Response('{}', { status: 409 })); + await flow.choice(JSON.stringify({ ...reference, choice: 1 }), interaction(), bundle); + expect(JSON.stringify(slack.mock.calls)).toContain('unavailable'); + backend.mockResolvedValueOnce(new Response('{}', { status: 503 })); + await expect( + flow.choice(JSON.stringify({ ...reference, choice: 1 }), interaction(), bundle), + ).rejects.toThrow(); + }); + + test('batch headings are preserved and oversized headings fall back to the browser', () => { + const pending = question(); + if (pending.payload.type !== 'ask_user_question') throw new Error(); + pending.payload.questions = [{ id: 'env', header: 'Environment', ...pending.payload.question }]; + expect(JSON.stringify(reviewModal(ref(), pending))).toContain('Environment'); + const prompt = pending.payload.question; + pending.payload.questions = Array.from({ length: 20 }, (_, i) => ({ + id: String(i), + header: 'Environment', + description: 'Context', + ...prompt, + })); + expect(reviewModal(ref(), pending)).toBeNull(); + pending.payload.questions = [{ id: 'env', ...pending.payload.question }]; + pending.payload.questions[0].header = 'x'.repeat(151); + expect(reviewModal(ref(), pending)).toBeNull(); + }); + + test('a choice button cannot replace an already saved decision', async () => { + const { backend, flow } = setup(); + const reference = ref(); + backend.mockResolvedValueOnce( + json({ + actionId: 'action', + pendingAction: question(reference.expiresAt), + pendingDecision: { intentId: 'intent', decision: { actionId: 'action', answer: 'first' } }, + }), + ); + await flow.choice(JSON.stringify({ ...reference, choice: 1 }), interaction(), bundle); + expect(backend).toHaveBeenCalledTimes(1); + }); + + test('a saved intent cannot be swapped or resurrected', async () => { + const { backend, flow } = setup(); + const reference = { ...ref(), savedIntentId: 'original' }; + backend.mockResolvedValueOnce( + json({ + actionId: 'action', + pendingAction: action(reference.expiresAt), + pendingDecision: { intentId: 'different', decision: { actionId: 'action', decisions: [] } }, + }), + ); + expect(await flow.submit(submission(reference), bundle)).toMatchObject({ + response_action: 'update', + view: { title: { text: 'Review unavailable' } }, + }); + expect(backend).toHaveBeenCalledTimes(1); + }); + + test('stale revision prevents cancellation from reaching the backend', async () => { + const { backend, flow } = setup(); + await flow.control( + 'channel_run_cancel', + JSON.stringify({ runId: 'run', revision: 'old' }), + interaction(), + bundle, + ); + expect(backend).not.toHaveBeenCalled(); + }); + + test('uses only validated client branding for both modal and private browser recovery labels', async () => { + const title = 'A'.repeat(40); + const branding = (APP_TITLE: string) => + loadConfig({ + CHANNEL_SERVICE_TOKEN: config.CHANNEL_SERVICE_TOKEN, + CHANNEL_TENANT_ID: config.CHANNEL_TENANT_ID, + CHANNEL_ID: config.CHANNEL_ID, + APP_TITLE, + }); + for (const invalid of ['A'.repeat(41), 'A'.repeat(76)]) + expect(() => branding(invalid)).toThrow('APP_TITLE'); + const { backend, slack, flow } = setup(branding(title)); + const reference = ref(); + backend.mockResolvedValueOnce( + json({ + url: 'https://chat.example/review', + actionId: 'action', + pendingAction: action(reference.expiresAt), + }), + ); + slack.mockResolvedValueOnce(json({ ok: false, error: 'invalid_arguments' })); + await flow.control( + 'channel_run_review', + JSON.stringify({ runId: 'run', revision: 'r1' }), + interaction(), + bundle, + ); + expect(slack).toHaveBeenCalledTimes(2); + const modal = new URLSearchParams(String(slack.mock.calls[0][1]?.body)).get('view')!; + const fallback = new URLSearchParams(String(slack.mock.calls[1][1]?.body)); + expect(modal).toContain('Open in ' + title); + expect(fallback.get('blocks')).toContain('Review in ' + title); + expect(fallback.get('text')).toContain(title); + expect(('Open in ' + title).length).toBeLessThanOrEqual(75); + expect(('Review in ' + title).length).toBeLessThanOrEqual(75); + }); + + test('opens the modal only after actor-authorized lookup', async () => { + const { backend, slack, flow } = setup(); + const reference = ref(); + backend.mockResolvedValueOnce( + json({ + url: 'https://chat.example/review', + actionId: 'action', + pendingAction: action(reference.expiresAt), + }), + ); + await flow.control( + 'channel_run_review', + JSON.stringify({ runId: 'run', revision: 'r1' }), + interaction(), + bundle, + ); + const request = JSON.parse(String(backend.mock.calls[0][1]?.body)); + expect(request).toEqual({ + actor: { teamId: 'T1', appId: 'A1', externalUserId: 'U1' }, + revision: 'r1', + externalChannelId: 'C1', + }); + expect(String(slack.mock.calls[0][0])).toContain('views.open'); + }); + test.each(['teamId', 'appId'] as const)('foreign %s never reaches backend', async (field) => { + const { backend, flow } = setup(); + const wrong = interaction(); + wrong[field] = 'foreign'; + await expect( + flow.control( + 'channel_run_review', + JSON.stringify({ runId: 'run', revision: 'r1' }), + wrong, + bundle, + ), + ).rejects.toThrow(); + expect(backend).not.toHaveBeenCalled(); + }); + test('foreign actor metadata never reaches backend', async () => { + const { backend, flow } = setup(); + expect(await flow.submit(submission({ ...ref(), actorId: 'other' }), bundle)).toMatchObject({ + response_action: 'update', + view: { title: { text: 'Review unavailable' } }, + }); + expect(backend).not.toHaveBeenCalled(); + }); + test('expired or changed action cannot be submitted', async () => { + const { backend, flow } = setup(); + const reference = ref(); + backend.mockResolvedValueOnce( + json({ actionId: 'other', pendingAction: action(reference.expiresAt) }), + ); + expect(await flow.submit(submission(reference), bundle)).toMatchObject({ + response_action: 'update', + }); + expect(backend).toHaveBeenCalledTimes(1); + }); + test('accepted decision clears modal, without falsely claiming execution', async () => { + const { backend, slack, flow } = setup(); + const reference = ref(); + backend + .mockResolvedValueOnce( + json({ actionId: 'action', pendingAction: action(reference.expiresAt) }), + ) + .mockResolvedValueOnce(receipt()); + expect(await flow.submit(submission(reference), bundle)).toEqual({ response_action: 'clear' }); + const payload = new URLSearchParams(String(slack.mock.calls[0]?.[1]?.body)); + expect(payload.get('text')).toBe('Tool call approved.'); + expect(payload.get('text')).not.toContain('completed'); + }); + test('saved decision replaces stale editable modal before any retry', async () => { + const { backend, flow } = setup(); + const reference = ref(); + const saved: ResponseReviewDecision = { + actionId: 'action', + decisions: [{ tool_call_id: 'call', decision: 'reject', scope: 'once' }], + }; + backend.mockResolvedValueOnce( + json({ + actionId: 'action', + pendingAction: action(reference.expiresAt), + pendingDecision: { intentId: 'intent', decision: saved }, + }), + ); + const result = await flow.submit(submission(reference), bundle); + expect(result).toMatchObject({ + response_action: 'update', + view: { submit: { text: 'Retry continuation' } }, + }); + expect(JSON.stringify(result)).toContain('Tool call declined'); + expect(backend).toHaveBeenCalledTimes(1); + }); + test('retry sends the immutable saved decision, ignoring edited form state', async () => { + const { backend, flow } = setup(); + const reference = { ...ref(), savedIntentId: 'intent' }; + const saved: ResponseReviewDecision = { + actionId: 'action', + decisions: [{ tool_call_id: 'call', decision: 'reject', scope: 'once' }], + }; + backend + .mockResolvedValueOnce( + json({ + actionId: 'action', + pendingAction: action(reference.expiresAt), + pendingDecision: { intentId: 'intent', decision: saved }, + }), + ) + .mockResolvedValueOnce(receipt()); + expect(await flow.submit(submission(reference), bundle)).toEqual({ response_action: 'clear' }); + expect(JSON.parse(String(backend.mock.calls[1][1]?.body)).decision).toEqual(saved); + }); + test('ambiguous submission failure reports uncertainty and no raw error', async () => { + const { backend, flow } = setup(); + const reference = ref(); + backend + .mockResolvedValueOnce( + json({ actionId: 'action', pendingAction: action(reference.expiresAt) }), + ) + .mockRejectedValueOnce(new Error('private key credentials')); + const result = await flow.submit(submission(reference), bundle); + expect(result).toMatchObject({ + response_action: 'update', + view: { title: { text: 'Submission unconfirmed' } }, + }); + expect(JSON.stringify(result)).not.toContain('private key'); + }); + test('OAuth review falls back to a private configurable link, never posting auth URL', async () => { + const { backend, slack, flow } = setup(); + backend.mockResolvedValueOnce(json({ actionId: 'oauth', url: 'https://chat.example/review' })); + await flow.control( + 'channel_run_review', + JSON.stringify({ runId: 'run', revision: 'r1' }), + interaction(), + bundle, + ); + expect(String(slack.mock.calls[0][0])).toContain('chat.postEphemeral'); + const payload = new URLSearchParams(String(slack.mock.calls[0][1]?.body)); + expect(payload.get('blocks')).toContain('Review in LibreChat'); + }); +}); + +describe('bounded recoverable review presentation', () => { + test.each([201, 2000])( + 'keeps a %i-character free-text question outside the short input label', + (size) => { + const reference = ref(); + const pending = question(reference.expiresAt); + if (pending.payload.type !== 'ask_user_question') throw new Error(); + pending.payload.question = { question: 'Q'.repeat(size) }; + const modal = reviewModal(reference, pending)!; + expect(modal.blocks).toContainEqual({ + type: 'section', + text: { type: 'plain_text', text: 'Q'.repeat(size) }, + }); + expect(modal.blocks.filter((block) => block.type === 'input')).toEqual([ + expect.objectContaining({ label: { type: 'plain_text', text: 'Your answer' } }), + ]); + }, + ); + test('a large saved batch has a bounded receipt and retries only the same complete decision', async () => { + const { backend, slack, flow } = setup(); + const reference = ref(); + const pending = action(reference.expiresAt); + if (pending.payload.type !== 'tool_approval') throw new Error(); + pending.payload.action_requests = Array.from({ length: 100 }, (_, i) => ({ + name: `tool_${i}`, + arguments: {}, + tool_call_id: `call_${i}`, + })); + const saved: ResponseReviewDecision = { + actionId: 'action', + decisions: pending.payload.action_requests.map((call) => ({ + tool_call_id: call.tool_call_id, + decision: 'reject', + scope: 'once', + })), + }; + const review = { + url: 'https://chat.example/review', + actionId: 'action', + pendingAction: pending, + pendingDecision: { intentId: 'saved', decision: saved }, + }; + backend.mockImplementation(async () => json(review)); + await flow.control( + 'channel_run_review', + JSON.stringify({ runId: 'run', revision: 'r1' }), + interaction(), + bundle, + ); + const modal = JSON.parse( + new URLSearchParams(String(slack.mock.calls[0][1]?.body)).get('view')!, + ); + expect(modal.blocks.length).toBeLessThanOrEqual(100); + expect(JSON.stringify(modal.blocks)).toContain('declined: 100'); + const updated = await flow.submit(submission(reference), bundle); + expect(updated.response_action).toBe('update'); + if (updated.response_action !== 'update') throw new Error(); + expect(updated.view.blocks.length).toBeLessThanOrEqual(99); + backend.mockReset().mockResolvedValueOnce(json(review)).mockResolvedValueOnce(receipt()); + const savedReference = { ...reference, savedIntentId: 'saved' }; + await flow.submit(submission(savedReference), bundle); + expect(JSON.parse(String(backend.mock.calls[1][1]?.body)).decision).toEqual(saved); + }); + test.each(['question', 'tool'] as const)( + 'validation identifies a later invalid %s input', + async (kind) => { + const { backend, flow } = setup(); + const reference = ref(); + const pending = action(reference.expiresAt); + const input = submission(reference); + if (kind === 'tool') { + if (pending.payload.type !== 'tool_approval') throw new Error(); + pending.payload.action_requests.push({ + name: 'second', + arguments: {}, + tool_call_id: 'second', + }); + pending.payload.review_configs.push({ + action_name: 'second', + tool_call_id: 'second', + allowed_decisions: ['approve', 'reject'], + }); + } else { + pending.payload = { + type: 'ask_user_question', + question: { question: 'First' }, + questions: [ + { id: 'a', question: 'First' }, + { id: 'b', question: 'Second', options: [{ label: 'One', value: 'one' }] }, + ], + }; + input.view!.values = { question_0_text: { answer: { value: 'first answered' } } }; + } + backend.mockResolvedValueOnce(json({ actionId: 'action', pendingAction: pending })); + const result = await flow.submit(input, bundle); + expect(result.response_action).toBe('errors'); + if (result.response_action !== 'errors') throw new Error(); + expect(Object.keys(result.errors)).toEqual([kind === 'tool' ? 'tool_1' : 'question_1']); + expect(backend).toHaveBeenCalledTimes(1); + }, + ); + test('a rejected modal open falls back to the actor-private browser link without submitting a decision', async () => { + const { backend, slack, flow } = setup(); + const reference = ref(); + backend.mockResolvedValueOnce( + json({ + url: 'https://chat.example/review', + actionId: 'action', + pendingAction: action(reference.expiresAt), + }), + ); + slack.mockResolvedValueOnce(json({ ok: false, error: 'invalid_arguments' })); + await flow.control( + 'channel_run_review', + JSON.stringify({ runId: 'run', revision: 'r1' }), + interaction(), + bundle, + ); + expect(slack.mock.calls.map(([url]) => String(url).split('/').at(-1))).toEqual([ + 'views.open', + 'chat.postEphemeral', + ]); + const notification = new URLSearchParams(String(slack.mock.calls[1][1]?.body)); + expect(notification.get('user')).toBe('U1'); + expect(notification.get('blocks')).toContain('https://chat.example/review'); + expect(backend).toHaveBeenCalledTimes(1); + }); +}); diff --git a/packages/channel-gateway/src/review.ts b/packages/channel-gateway/src/review.ts new file mode 100644 index 0000000000..d6f54eca45 --- /dev/null +++ b/packages/channel-gateway/src/review.ts @@ -0,0 +1,639 @@ +import { z } from 'zod'; +import type { Agents, ChannelRunActor, ResponseReviewDecision } from 'librechat-data-provider'; +import type { PlainTextElement, ModalView, InputBlock, Button } from '@slack/types'; +import type { SlackClient, SlackBlocks } from './slack'; +import type { ChannelBundle, Review } from './types'; +import type { ChannelClient } from './client'; +import { ServiceError, expectedServiceFailure as expectedFailure } from './client'; +import { IdentityFlow, safePrivateURL } from './identity'; + +type PendingAction = NonNullable; +type Question = Agents.AskUserQuestionRequest & + Partial>; +export interface ReviewInteraction { + teamId: string; + appId: string; + actorId: string; + channelId: string; + triggerId?: string; + view?: { callbackId: string; privateMetadata: string; values?: ReviewValues }; +} +export type ReviewValues = Record< + string, + Record< + string, + { value?: string; selected_option?: { value: string }; selected_options?: { value: string }[] } + > +>; +export type ReviewAck = + | { response_action: 'clear' } + | { response_action: 'update'; view: ModalView } + | { response_action: 'errors'; errors: Record }; +const controlSchema = z + .object({ runId: z.string().min(1).max(256), revision: z.string().min(1).max(256) }) + .strict(); +const referenceSchema = controlSchema + .extend({ + actionId: z.string().min(1).max(256), + channelId: z.string().min(1).max(256), + actorId: z.string().min(1).max(256), + expiresAt: z.number().finite(), + savedIntentId: z.string().min(1).optional(), + }) + .strict(); +const choiceSchema = referenceSchema.extend({ choice: z.number().int().min(0).max(3) }).strict(); +type Reference = z.infer; +const modalContentLimit = 99; // Slack allows 100 blocks; reserve one for browser recovery. +class NativeDecisionError extends Error { + constructor( + readonly blockId: string, + message: string, + ) { + super(message); + } +} +const plain = (text: string): PlainTextElement => ({ type: 'plain_text', text }); +const questions = (payload: Agents.AskUserQuestionInterruptPayload): Question[] => + payload.questions?.length ? payload.questions : [payload.question]; +const unavailable = () => + notice( + 'Review unavailable', + 'This action changed, expired, or is no longer authorized. A previous decision may already have been accepted and cannot be replaced. Close this window and check the latest thread status before trying again.', + ); +function notice(title: string, text: string): ReviewAck { + return { + response_action: 'update', + view: { + type: 'modal', + title: plain(title), + close: plain('Close'), + blocks: [{ type: 'section', text: plain(text) }], + }, + }; +} +function parseReference(value: string): Reference { + if (value.length > 3000) throw new Error('Invalid private review reference'); + return referenceSchema.parse(JSON.parse(value)); +} +function actor(interaction: ReviewInteraction, bundle: ChannelBundle): ChannelRunActor { + if ( + !interaction.actorId || + interaction.teamId !== bundle.channel.slack.teamId || + interaction.appId !== bundle.channel.slack.appId + ) + throw new Error('Review actor binding changed'); + return { + teamId: interaction.teamId, + appId: interaction.appId, + externalUserId: interaction.actorId, + }; +} +function validReference( + ref: Reference, + interaction: ReviewInteraction, + bundle: ChannelBundle, +): boolean { + return ( + ref.actorId === interaction.actorId && + (!interaction.channelId || ref.channelId === interaction.channelId) && + ref.revision === bundle.channel.revision && + ref.expiresAt > Date.now() + ); +} +function matches( + ref: Reference, + review: Review, +): review is Review & { pendingAction: PendingAction } { + return ( + !!review.pendingAction && + review.actionId === ref.actionId && + review.pendingAction.actionId === ref.actionId && + review.pendingAction.expiresAt === ref.expiresAt + ); +} +export function simpleChoices(action: PendingAction): boolean { + const payload = action.payload; + if ( + payload.type !== 'ask_user_question' || + payload.questions?.length || + payload.question.multiSelect + ) + return false; + const question = payload.question; + return ( + !!question.options?.length && + question.options.length <= 4 && + question.question.length <= 2800 && + (question.description?.length ?? 0) <= 2800 && + question.options.every((option) => !!option.label && option.label.length <= 75) + ); +} + +export function reviewModal(ref: Reference, action: PendingAction): ModalView | null { + if (action.actionId !== ref.actionId || !action.expiresAt || action.expiresAt <= Date.now()) + throw new Error('Review expired'); + const blocks: SlackBlocks = []; + const payload = action.payload; + if (payload.type === 'ask_user_question') { + const batch = questions(payload); + if (!batch.length || batch.length > 20) return null; + for (const [i, question] of batch.entries()) { + if ( + !question.question || + question.question.length > 2000 || + (question.description?.length ?? 0) > 2000 || + (question.options?.length ?? 0) > 100 + ) + return null; + if (question.header) { + if (question.header.length > 150) return null; + blocks.push({ type: 'header', text: plain(question.header) }); + } + blocks.push({ type: 'section', text: plain(question.question) }); + if (question.options?.length) { + if (question.options.some((option) => !option.label || option.label.length > 75)) + return null; + const options = question.options.map((option, n) => ({ + text: plain(option.label), + value: String(n), + })); + const element: InputBlock['element'] = question.multiSelect + ? { type: 'multi_static_select', action_id: 'choice', options } + : { type: 'static_select', action_id: 'choice', options }; + blocks.push({ + type: 'input', + block_id: `question_${i}`, + label: plain('Choose an answer'), + optional: true, + element, + }); + } + if (question.description) blocks.push({ type: 'section', text: plain(question.description) }); + blocks.push({ + type: 'input', + block_id: `question_${i}_text`, + label: plain(question.options?.length ? 'Or write an answer' : 'Your answer'), + optional: !!question.options?.length, + element: { + type: 'plain_text_input', + action_id: 'answer', + multiline: true, + max_length: 3000, + }, + }); + } + } else if (payload.type === 'tool_approval') { + if (!payload.action_requests.length || payload.action_requests.length > 20) return null; + for (const [i, call] of payload.action_requests.entries()) { + const text = `${call.name}\n${call.description ?? ''}\nArguments: ${typeof call.arguments === 'string' ? call.arguments : JSON.stringify(call.arguments)}`; + const allowed = + payload.review_configs.find((config) => config.tool_call_id === call.tool_call_id) + ?.allowed_decisions ?? []; + const options = [...new Set(allowed)] + .filter((value) => value === 'approve' || value === 'reject') + .map((value) => ({ text: plain(value === 'approve' ? 'Approve' : 'Decline'), value })); + if (text.length > 2800 || !options.length) return null; + blocks.push( + { type: 'section', text: plain(text) }, + { + type: 'input', + block_id: `tool_${i}`, + label: plain('Decision for this call only'), + element: { type: 'radio_buttons', action_id: 'decision', options }, + }, + ); + } + } else return null; + if (blocks.length > modalContentLimit) return null; + return { + type: 'modal', + callback_id: 'channel_native_review', + private_metadata: JSON.stringify(ref), + title: plain('Agent needs your input'), + submit: plain('Send answer'), + close: plain('Not now'), + blocks, + }; +} + +export function nativeDecision( + action: PendingAction, + values: ReviewValues, +): ResponseReviewDecision { + const payload = action.payload; + if (payload.type === 'tool_approval') { + return { + actionId: action.actionId, + decisions: payload.action_requests.map((call, i) => { + const decision = values[`tool_${i}`]?.decision?.selected_option?.value; + const allowed = payload.review_configs.find( + (config) => config.tool_call_id === call.tool_call_id, + )?.allowed_decisions; + if ((decision !== 'approve' && decision !== 'reject') || !allowed?.includes(decision)) + throw new NativeDecisionError(`tool_${i}`, 'Decision not allowed'); + return { tool_call_id: call.tool_call_id, decision, scope: 'once' }; + }), + }; + } + const answers: Record = {}; + const batch = questions(payload); + if (!batch.length || batch.length > 20) throw new Error('Invalid question batch'); + let single = ''; + for (const [i, question] of batch.entries()) { + const key = `question_${i}`; + let answer = values[`${key}_text`]?.answer?.value?.trim() ?? ''; + const field = values[key]?.choice; + const input = answer || !question.options?.length ? `${key}_text` : key; + const selected = [ + ...(field?.selected_options ?? []), + ...(field?.selected_option ? [field.selected_option] : []), + ]; + if ( + (answer && selected.length) || + (!question.multiSelect && selected.length > 1) || + new Set(selected.map((option) => option.value)).size !== selected.length || + answer.length > 3000 + ) + throw new NativeDecisionError(input, 'Choose or write one answer'); + if (selected.length) + answer = selected + .map((option) => { + if (!/^(0|[1-9][0-9]*)$/.test(option.value)) + throw new NativeDecisionError(key, 'Invalid choice'); + const selectedOption = question.options?.[Number(option.value)]; + if (!selectedOption) throw new NativeDecisionError(key, 'Invalid choice'); + return selectedOption.value; + }) + .join(', '); + if (!answer) throw new NativeDecisionError(input, 'Answer required'); + if (payload.questions?.length) { + if (!question.id || Object.hasOwn(answers, question.id)) + throw new NativeDecisionError(input, 'Invalid question identifier'); + Object.defineProperty(answers, question.id, { value: answer, enumerable: true }); + } else single = answer; + } + return payload.questions?.length + ? { actionId: action.actionId, answers } + : { actionId: action.actionId, answer: single }; +} + +function decisionReceipt( + ref: Reference, + action: PendingAction, + decision: ResponseReviewDecision, +): ModalView { + const blocks: SlackBlocks = [ + { + type: 'section', + text: plain( + 'Your decision is saved. Continuation is not confirmed. Retry sends only this same saved decision; it cannot change the approval or answer.', + ), + }, + ]; + if (action.payload.type === 'tool_approval') + for (const call of action.payload.action_requests.slice(0, 20)) { + const accepted = decision.decisions?.find( + (item) => item.tool_call_id === call.tool_call_id, + )?.decision; + let label = 'Decision received'; + if (accepted === 'approve') label = 'Tool call approved'; + if (accepted === 'reject') label = 'Tool call declined'; + blocks.push({ + type: 'section', + text: plain(`${label}: ${[...call.name].slice(0, 200).join('')}`), + }); + } + if (action.payload.type === 'tool_approval' && action.payload.action_requests.length > 20) { + blocks.push({ type: 'section', text: plain(decisionConfirmation(action, decision)) }); + } + if (blocks.length > modalContentLimit) throw new Error('Saved review exceeds modal budget'); + return { + type: 'modal', + title: plain('Decision received'), + close: plain('Close'), + callback_id: 'channel_native_review', + private_metadata: JSON.stringify(ref), + submit: plain('Retry continuation'), + blocks, + }; +} +function decisionConfirmation(action: PendingAction, decision: ResponseReviewDecision): string { + if (action.payload.type !== 'tool_approval') return 'Answer received.'; + const approved = decision.decisions?.filter((item) => item.decision === 'approve').length ?? 0; + const declined = decision.decisions?.filter((item) => item.decision === 'reject').length ?? 0; + if (approved === 1 && !declined) return 'Tool call approved.'; + if (declined === 1 && !approved) return 'Tool call declined.'; + return `Tool calls approved: ${approved}; declined: ${declined}.`; +} + +export class ReviewFlow { + private readonly identity: IdentityFlow; + constructor( + private readonly client: ChannelClient, + private readonly slack: SlackClient, + ) { + this.identity = new IdentityFlow(client, slack); + } + + private get appTitle(): string { + return this.client.config.APP_TITLE; + } + + async control( + actionId: string, + value: string, + interaction: ReviewInteraction, + bundle: ChannelBundle, + signal?: AbortSignal, + ): Promise { + const caller = actor(interaction, bundle); + if (value.length > 1024 || !interaction.channelId) throw new Error('Invalid run control'); + const control = controlSchema.parse(JSON.parse(value)); + if (control.revision !== bundle.channel.revision) + return this.reject(interaction, bundle, signal); + try { + if (actionId === 'channel_run_cancel') { + if ( + !( + await this.client.cancel( + control.runId, + caller, + control.revision, + interaction.channelId, + signal, + ) + ).cancellationRequested + ) + throw new Error('Cancellation was not accepted'); + return this.identity.notify( + interaction.channelId, + interaction.actorId, + 'Cancellation requested. Work that has already completed cannot be undone; the final status will appear in this thread.', + bundle, + undefined, + signal, + ); + } + if (actionId !== 'channel_run_review' && actionId !== 'channel_native_write') + throw new Error('Unsupported run control'); + let review: Review; + try { + review = await this.client.review( + control.runId, + caller, + control.revision, + interaction.channelId, + signal, + ); + } catch (error) { + if (!(error instanceof ServiceError && error.status === 400)) throw error; + review = await this.client.review( + control.runId, + caller, + control.revision, + undefined, + signal, + ); + } + if (review.pendingAction && interaction.triggerId) { + if (!review.pendingAction.expiresAt) throw new Error('Review expiry unavailable'); + const ref: Reference = { + ...control, + actionId: review.actionId, + channelId: interaction.channelId, + actorId: interaction.actorId, + expiresAt: review.pendingAction.expiresAt, + }; + if (!matches(ref, review) || !validReference(ref, interaction, bundle)) + throw new Error('Review changed'); + let modal: ModalView | null; + if (review.pendingDecision) { + if ( + !review.pendingDecision.intentId || + review.pendingDecision.decision.actionId !== ref.actionId + ) + throw new Error('Invalid saved decision'); + ref.savedIntentId = review.pendingDecision.intentId; + modal = decisionReceipt(ref, review.pendingAction, review.pendingDecision.decision); + } else if (actionId !== 'channel_native_write' && simpleChoices(review.pendingAction)) { + return this.choices(ref, review.pendingAction, bundle, signal); + } else modal = reviewModal(ref, review.pendingAction); + if (modal) { + if (safePrivateURL(review.url)) { + modal.blocks.push({ + type: 'actions', + elements: [ + { + type: 'button', + text: plain(`Open in ${this.appTitle}`), + action_id: 'channel_run_open', + url: review.url, + }, + ], + }); + } + try { + await this.slack.openView( + bundle.credentials.botToken, + interaction.triggerId, + modal, + signal, + ); + return; + } catch (error) { + if (signal?.aborted) throw error; + // No decision was submitted. The actor-private browser path remains usable. + } + } + } + if (!safePrivateURL(review.url) || !review.actionId) + throw new Error('Invalid private review link'); + await this.identity.notify( + interaction.channelId, + interaction.actorId, + `Review this request in ${this.appTitle}. Approval or sign-in happens there; no action was approved in Slack.`, + bundle, + { label: `Review in ${this.appTitle}`, action: 'channel_run_open', url: review.url }, + signal, + ); + } catch (error) { + if (!expectedFailure(error)) throw error; + await this.reject(interaction, bundle, signal); + } + } + + private async reject( + interaction: ReviewInteraction, + bundle: ChannelBundle, + signal?: AbortSignal, + ): Promise { + await this.identity.notify( + interaction.channelId, + interaction.actorId, + 'This action is unavailable, expired, or not authorized for you. Check the latest reply in this thread.', + bundle, + undefined, + signal, + ); + } + + private async choices( + ref: Reference, + action: PendingAction, + bundle: ChannelBundle, + signal?: AbortSignal, + ): Promise { + if (action.payload.type !== 'ask_user_question') throw new Error('Invalid question'); + const question = action.payload.question; + const buttons: Button[] = (question.options ?? []).map((option, choice) => ({ + type: 'button', + text: plain(option.label), + action_id: `channel_native_choice_${choice}`, + value: JSON.stringify({ ...ref, choice }), + })); + buttons.push({ + type: 'button', + text: plain('Write an answer'), + action_id: 'channel_native_write', + value: JSON.stringify({ runId: ref.runId, revision: ref.revision }), + }); + const blocks: SlackBlocks = [{ type: 'section', text: plain(question.question) }]; + if (question.description) blocks.push({ type: 'section', text: plain(question.description) }); + blocks.push({ type: 'actions', elements: buttons }); + await this.slack.ephemeral( + bundle.credentials.botToken, + { + channel: ref.channelId, + user: ref.actorId, + text: 'The Agent has a question for you.', + blocks, + }, + signal, + ); + } + + async choice( + value: string, + interaction: ReviewInteraction, + bundle: ChannelBundle, + signal?: AbortSignal, + ): Promise { + const caller = actor(interaction, bundle); + if (value.length > 3000) throw new Error('Invalid private choice'); + const ref = choiceSchema.parse(JSON.parse(value)); + if (!validReference(ref, interaction, bundle)) return this.reject(interaction, bundle, signal); + try { + const review = await this.client.review( + ref.runId, + caller, + ref.revision, + ref.channelId, + signal, + ); + if ( + !matches(ref, review) || + review.pendingDecision || + !simpleChoices(review.pendingAction) || + review.pendingAction.payload.type !== 'ask_user_question' + ) + return this.reject(interaction, bundle, signal); + const option = review.pendingAction.payload.question.options?.[ref.choice]; + if (!option) throw new Error('Private choice changed'); + await this.client.decide( + ref.runId, + caller, + ref.revision, + ref.channelId, + { actionId: ref.actionId, answer: option.value }, + signal, + ); + await this.identity.notify( + ref.channelId, + ref.actorId, + 'Answer received.', + bundle, + undefined, + signal, + ); + } catch (error) { + if (!expectedFailure(error)) throw error; + await this.reject(interaction, bundle, signal); + } + } + + async submit( + interaction: ReviewInteraction, + bundle: ChannelBundle, + signal?: AbortSignal, + ): Promise { + const caller = actor(interaction, bundle); + if (interaction.view?.callbackId !== 'channel_native_review') + throw new Error('Invalid native review submission'); + const ref = parseReference(interaction.view.privateMetadata); + if (!validReference(ref, interaction, bundle)) return unavailable(); + try { + const review = await this.client.review( + ref.runId, + caller, + ref.revision, + ref.channelId, + signal, + ); + if (!matches(ref, review)) return unavailable(); + let decision: ResponseReviewDecision; + if (review.pendingDecision) { + const saved = review.pendingDecision; + if ( + !saved.intentId || + saved.decision.actionId !== ref.actionId || + (ref.savedIntentId && ref.savedIntentId !== saved.intentId) + ) + return unavailable(); + if (!ref.savedIntentId) + return { + response_action: 'update', + view: decisionReceipt( + { ...ref, savedIntentId: saved.intentId }, + review.pendingAction, + saved.decision, + ), + }; + decision = saved.decision; + } else { + if (ref.savedIntentId || !interaction.view.values) return unavailable(); + try { + decision = nativeDecision(review.pendingAction, interaction.view.values); + } catch (error) { + if (!(error instanceof NativeDecisionError)) throw error; + return { + response_action: 'errors', + errors: { + [error.blockId]: + 'Choose or write one answer for this question, or a decision for this tool.', + }, + }; + } + } + await this.client.decide(ref.runId, caller, ref.revision, ref.channelId, decision, signal); + // Decorative acknowledgement cannot turn an accepted decision into a failed submission. + void this.identity + .notify( + ref.channelId, + ref.actorId, + decisionConfirmation(review.pendingAction, decision), + bundle, + undefined, + signal, + ) + .catch(() => {}); + return { response_action: 'clear' }; + } catch (error) { + return expectedFailure(error) + ? unavailable() + : notice( + 'Submission unconfirmed', + "The decision submission was not confirmed. It may already be saved. Close this window and reopen the thread's review to check its current state and retry only the saved decision. Do not assume the tool ran or repeat the task.", + ); + } + } +} diff --git a/packages/channel-gateway/tsdown.config.mjs b/packages/channel-gateway/tsdown.config.mjs index 1bdfc246da..5a66c1503a 100644 --- a/packages/channel-gateway/tsdown.config.mjs +++ b/packages/channel-gateway/tsdown.config.mjs @@ -1,7 +1,15 @@ import { defineConfig } from 'tsdown'; export default defineConfig({ - entry: ['src/client.ts', 'src/config.ts', 'src/events.ts', 'src/slack.ts'], + entry: [ + 'src/client.ts', + 'src/config.ts', + 'src/events.ts', + 'src/slack.ts', + 'src/render.ts', + 'src/identity.ts', + 'src/review.ts', + ], platform: 'node', format: ['cjs'], dts: false, diff --git a/packages/data-provider/src/types/channels.ts b/packages/data-provider/src/types/channels.ts index 92bd087cc8..64646061bd 100644 --- a/packages/data-provider/src/types/channels.ts +++ b/packages/data-provider/src/types/channels.ts @@ -1,4 +1,4 @@ -import type { ChannelGatewayWirePolicy } from '../config'; +import type { ChannelStorageConfig, ChannelGatewayWirePolicy } from '../config'; export const SLACK_CHANNEL_BOT_SCOPES = [ 'app_mentions:read', @@ -64,4 +64,6 @@ export interface ChannelServiceBundle { credentials: { botToken: string; signingSecret?: string }; agent: { id: string; name?: string }; gateway: ChannelGatewayWirePolicy; + /** Absent on older servers: retain the shared default; never infer a replica-local limit. */ + delivery?: Pick; }