The Open Framework for Building Agents
feat(eve): add guided Teams Connect setup (#3243)
OwenKephart0fa8916e9ce8
diff --git a/.changeset/managed-teams-setup.md b/.changeset/managed-teams-setup.mdnew file mode 100644index 000000000..6679401d7--- /dev/null+++ b/.changeset/managed-teams-setup.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Add guided Microsoft Teams setup through `eve add channel/teams`. The flow delegates app creation, installation, and Activity routing to the Vercel Connect CLI, then scaffolds the Connect-backed channel.diff --git a/apps/docs/registry.json b/apps/docs/registry.jsonindex 3690c9c36..aafcec5c0 100644--- a/apps/docs/registry.json+++ b/apps/docs/registry.json@@ -1680,24 +1680,22 @@"name": "channel/teams","type": "registry:item","title": "Microsoft Teams",- "description": "Bring your agent into Teams chats and channels.",- "envVars": {- "TEAMS_APP_ID": "",- "TEAMS_APP_PASSWORD": ""- },- "files": [- {- "path": "registry/channels/teams.ts",- "type": "registry:file",- "target": "agent/channels/teams.ts"- }- ],+ "description": "Run an eve agent as a managed Microsoft Teams bot, with guided Vercel Connect setup.","meta": {"eve": {+ "setup": {+ "command": "eve",+ "package": "eve",+ "bin": "eve",+ "args": ["integration", "setup", "teams"]+ },+ "requires": ">=0.53.0","docs": "/docs/channels/teams","implementation": "native"}- }+ },+ "dependencies": ["@vercel/connect@>=2.1.0"],+ "devDependencies": ["vercel@>=58.5.1"]},{"name": "channel/telegram",diff --git a/apps/docs/scripts/validate-channel-registry.ts b/apps/docs/scripts/validate-channel-registry.tsindex 1e4836d89..b73067fee 100644--- a/apps/docs/scripts/validate-channel-registry.ts+++ b/apps/docs/scripts/validate-channel-registry.ts@@ -43,12 +43,14 @@ const registrySlugsByCatalogSlug: Readonly<Record<string, string>> = {};const setupKindsByCatalogSlug: Readonly<Record<string, string>> = {+ slack: "slack",discord: "discord",github: "github","linear-agent": "linear",eve: "web",linq: "linq",photon: "photon",+ teams: "teams",};const adapterDependenciesByCatalogSlug: Readonly<Record<string, string>> = {@@ -129,8 +131,6 @@ for (const [index, item] of items.entries()) {const entry = registryEntries[index];if (entry === undefined) throw new Error(`Unexpected channel registry item "${item.name}".`);- const registrySlug = expectedSlugs[index];-if (entry.slug === "eve") {if (item.dependencies?.some((dependency) => dependency === "ai" || dependency.startsWith("ai@"))@@ -146,20 +146,9 @@ for (const [index, item] of items.entries()) {}}- if (- entry.slug === "slack" ||- entry.slug === "discord" ||- entry.slug === "github" ||- entry.slug === "linear-agent" ||- entry.slug === "eve" ||- entry.slug === "linq" ||- entry.slug === "photon"- ) {- const expectedArgs = [- "integration",- "setup",- setupKindsByCatalogSlug[entry.slug] ?? registrySlug,- ];+ const setupKind = setupKindsByCatalogSlug[entry.slug];+ if (setupKind !== undefined) {+ const expectedArgs = ["integration", "setup", setupKind];if (JSON.stringify(setups) !==JSON.stringify([{ command: "eve", package: "eve", bin: "eve", args: expectedArgs }])diff --git a/docs/channels/teams.mdx b/docs/channels/teams.mdxindex a4763d79a..748a71d25 100644--- a/docs/channels/teams.mdx+++ b/docs/channels/teams.mdx@@ -14,6 +14,35 @@ import { teamsChannel } from "eve/channels/teams";export default teamsChannel();```+### Vercel Connect++For a managed Teams bot on Vercel, run:++```bash+eve add channel/teams+```++The guided flow runs the Vercel Connect CLI, which takes you through managed+Microsoft Teams app creation and installation. It routes verified Activities to+`/eve/v1/teams` and writes:++```ts title="agent/channels/teams.ts"+import { connectTeamsCredentials } from "@vercel/connect/eve";+import { teamsChannel } from "eve/channels/teams";++export default teamsChannel({+ credentials: connectTeamsCredentials("microsoft-teams/my-agent"),+});+```++Vercel Connect owns the Microsoft administrator consent and app installation+flow. After deployment, mention the bot in a channel or send it a personal+message.++### Portable credentials++To manage the bot registration and credentials yourself, configure:+```bashMICROSOFT_APP_ID=...MICROSOFT_APP_PASSWORD=...diff --git a/packages/eve/src/setup/integrations/registry.ts b/packages/eve/src/setup/integrations/registry.tsindex 077867e7c..383e787b1 100644--- a/packages/eve/src/setup/integrations/registry.ts+++ b/packages/eve/src/setup/integrations/registry.ts@@ -10,6 +10,7 @@ import {} from "./self-modification/setup.js";import { SHOPIFY_SETUP } from "./shopify/setup.js";import { SLACK_SETUP } from "./slack/setup.js";+import { TEAMS_SETUP } from "./teams/setup.js";import type { SetupIntegration } from "./types.js";import { WEB_SETUP } from "./web/setup.js";@@ -23,6 +24,7 @@ export const SETUP_INTEGRATIONS: readonly SetupIntegration[] = [LINEAR_SETUP,LINQ_SETUP,PHOTON_SETUP,+ TEAMS_SETUP,SHOPIFY_SETUP,SELF_MODIFICATION_SETUP,SELF_MODIFICATION_PRODUCTION_SETUP,diff --git a/packages/eve/src/setup/integrations/teams/connect.test.ts b/packages/eve/src/setup/integrations/teams/connect.test.tsnew file mode 100644index 000000000..ebc9dff86--- /dev/null+++ b/packages/eve/src/setup/integrations/teams/connect.test.ts@@ -0,0 +1,97 @@+import { describe, expect, it, vi } from "vitest";++import type { ChannelSetupLog } from "#setup/cli/index.js";+import { parseCreatedTeamsConnector, provisionTeamsConnector } from "./connect.js";++function log(): ChannelSetupLog {+ return {+ message: vi.fn(),+ info: vi.fn(),+ success: vi.fn(),+ warning: vi.fn(),+ error: vi.fn(),+ commandOutput: vi.fn(),+ };+}++describe("Microsoft Teams Connect provisioning", () => {+ it("parses a connector created by the Vercel CLI", () => {+ expect(+ parseCreatedTeamsConnector(JSON.stringify({ id: "scl_teams", uid: "microsoft-teams/agent" })),+ ).toEqual({ id: "scl_teams", uid: "microsoft-teams/agent" });+ expect(parseCreatedTeamsConnector("invalid")).toBeUndefined();+ });++ it("delegates app creation to Connect and registers the trigger destination", async () => {+ const runVercelCaptureStdout = vi.fn(async () => ({+ ok: true as const,+ stdout: JSON.stringify({ id: "scl_teams", uid: "microsoft-teams/agent" }),+ stderr: "",+ }));+ const runVercel = vi.fn(async () => true);++ await expect(+ provisionTeamsConnector({+ name: "Agent",+ log: log(),+ project: { orgId: "team_123", projectId: "prj_123" },+ projectRoot: "/project",+ deps: { runVercel, runVercelCaptureStdout },+ }),+ ).resolves.toEqual({ id: "scl_teams", uid: "microsoft-teams/agent" });++ expect(runVercelCaptureStdout).toHaveBeenCalledWith(+ [+ "connect",+ "create",+ "microsoft-teams",+ "--name",+ "Agent",+ "-F",+ "json",+ "--scope",+ "team_123",+ ],+ expect.objectContaining({ cwd: "/project", nonInteractive: true }),+ );+ expect(runVercel).toHaveBeenCalledWith(+ [+ "connect",+ "attach",+ "microsoft-teams/agent",+ "--project",+ "prj_123",+ "--environment",+ "production",+ "--triggers",+ "--trigger-path",+ "/eve/v1/teams",+ "--yes",+ "--scope",+ "team_123",+ ],+ expect.objectContaining({ cwd: "/project", nonInteractive: true }),+ );+ });++ it("reports the recovery command when trigger registration fails", async () => {+ const runVercelCaptureStdout = vi.fn(async () => ({+ ok: true as const,+ stdout: JSON.stringify({ id: "scl_teams", uid: "microsoft-teams/agent" }),+ stderr: "",+ }));+ const runVercel = vi.fn(async () => false);++ await expect(+ provisionTeamsConnector({+ name: "Agent",+ log: log(),+ project: { orgId: "team_123", projectId: "prj_123" },+ projectRoot: "/project",+ deps: { runVercel, runVercelCaptureStdout },+ }),+ ).rejects.toThrow(+ "vercel connect attach microsoft-teams/agent --project prj_123 --environment production --triggers --trigger-path /eve/v1/teams --yes --scope team_123",+ );+ });+});diff --git a/packages/eve/src/setup/integrations/teams/connect.ts b/packages/eve/src/setup/integrations/teams/connect.tsnew file mode 100644index 000000000..dfaf14232--- /dev/null+++ b/packages/eve/src/setup/integrations/teams/connect.ts@@ -0,0 +1,109 @@+import { createPromptCommandOutput, withPhase, type ChannelSetupLog } from "#setup/cli/index.js";+import type { VercelProjectReference } from "#setup/project-resolution.js";+import { runVercel, runVercelCaptureStdout } from "#setup/primitives/run-vercel.js";+import { z } from "zod";++export const TEAMS_TRIGGER_PATH = "/eve/v1/teams";++export interface TeamsConnectorRef {+ id: string;+ uid: string;+}++export interface ProvisionTeamsConnectorDeps {+ runVercel: typeof runVercel;+ runVercelCaptureStdout: typeof runVercelCaptureStdout;+}++const TeamsConnectorSchema = z.object({+ id: z.string().min(1),+ uid: z.string().min(1),+});++export function parseCreatedTeamsConnector(stdout: string): TeamsConnectorRef | undefined {+ try {+ const parsed = TeamsConnectorSchema.safeParse(JSON.parse(stdout));+ return parsed.success ? parsed.data : undefined;+ } catch {+ return undefined;+ }+}++/** Creates and installs a Teams app through the Vercel Connect CLI. */+export async function provisionTeamsConnector(input: {+ name: string;+ log: ChannelSetupLog;+ project: VercelProjectReference;+ projectRoot: string;+ signal?: AbortSignal;+ deps?: ProvisionTeamsConnectorDeps;+}): Promise<TeamsConnectorRef> {+ const deps = input.deps ?? { runVercel, runVercelCaptureStdout };+ const onOutput = createPromptCommandOutput(input.log);+ const result = await withPhase(input.log, "Creating Microsoft Teams connector…", () =>+ deps.runVercelCaptureStdout(+ [+ "connect",+ "create",+ "microsoft-teams",+ "--name",+ input.name,+ "-F",+ "json",+ "--scope",+ input.project.orgId,+ ],+ {+ cwd: input.projectRoot,+ nonInteractive: true,+ onOutput,+ signal: input.signal,+ },+ ),+ );+ input.signal?.throwIfAborted();+ if (!result.ok) {+ const detail = [result.stderr, result.stdout].find(+ (value): value is string => value !== undefined && value.trim().length > 0,+ );+ throw new Error(+ detail+ ? `Microsoft Teams connector creation failed:\n${detail}`+ : "Microsoft Teams connector creation failed.",+ );+ }+ const connector = parseCreatedTeamsConnector(result.stdout);+ if (connector === undefined)+ throw new Error("Vercel returned an invalid Microsoft Teams connector.");++ const attachArgs = [+ "connect",+ "attach",+ connector.uid,+ "--project",+ input.project.projectId,+ "--environment",+ "production",+ "--triggers",+ "--trigger-path",+ TEAMS_TRIGGER_PATH,+ "--yes",+ "--scope",+ input.project.orgId,+ ];+ const attached = await withPhase(input.log, "Connecting Microsoft Teams activities…", () =>+ deps.runVercel(attachArgs, {+ cwd: input.projectRoot,+ nonInteractive: true,+ onOutput,+ signal: input.signal,+ }),+ );+ input.signal?.throwIfAborted();+ if (!attached) {+ throw new Error(+ `Microsoft Teams connector was created, but its trigger destination could not be registered. Run \`vercel ${attachArgs.join(" ")}\`.`,+ );+ }+ return connector;+}diff --git a/packages/eve/src/setup/integrations/teams/setup.test.ts b/packages/eve/src/setup/integrations/teams/setup.test.tsnew file mode 100644index 000000000..613605edb--- /dev/null+++ b/packages/eve/src/setup/integrations/teams/setup.test.ts@@ -0,0 +1,54 @@+import { describe, expect, it, vi } from "vitest";++import { createFakePrompter } from "#internal/testing/fake-prompter.js";+import { headlessAsker, withAnswers } from "#setup/ask.js";+import { integrationSetupEnvironment } from "../shared/environment.js";+import { createSetupContexts } from "../shared/ui.js";+import { applyTeamsSetup, prepareTeamsSetup, type TeamsSetupDeps } from "./setup.js";++function deps(): TeamsSetupDeps {+ return {+ provisionConnector: vi.fn(async () => ({+ id: "scl_teams",+ uid: "microsoft-teams/agent",+ })),+ runVercel: vi.fn(),+ runVercelCaptureStdout: vi.fn(),+ writeTextFile: vi.fn(async () => {}),+ };+}++function contexts(answers: Record<string, unknown>) {+ return createSetupContexts({+ appRoot: "/project",+ asker: withAnswers(answers)(headlessAsker()),+ environment: integrationSetupEnvironment("authenticated", { kind: "unresolved" }),+ prompter: createFakePrompter().prompter,+ resolveVercelProject: vi.fn(async () => ({ orgId: "team", projectId: "project" })),+ });+}++describe("Microsoft Teams setup", () => {+ it("delegates setup to the Connect CLI and scaffolds its connector", async () => {+ const effects = deps();+ const ctx = contexts({ "teams.bot-name": " Agent " });++ const plan = await prepareTeamsSetup(ctx.prepare);+ expect(effects.provisionConnector).not.toHaveBeenCalled();+ await expect(applyTeamsSetup(plan, ctx.apply, effects)).resolves.toMatchObject({+ deploymentRequired: true,+ });++ expect(effects.provisionConnector).toHaveBeenCalledWith(+ expect.objectContaining({+ name: "Agent",+ project: { orgId: "team", projectId: "project" },+ }),+ );+ expect(effects.writeTextFile).toHaveBeenCalledWith(+ "/project/agent/channels/teams.ts",+ expect.stringContaining('connectTeamsCredentials("microsoft-teams/agent")'),+ { force: undefined },+ );+ });+});diff --git a/packages/eve/src/setup/integrations/teams/setup.ts b/packages/eve/src/setup/integrations/teams/setup.tsnew file mode 100644index 000000000..7977e9f7f--- /dev/null+++ b/packages/eve/src/setup/integrations/teams/setup.ts@@ -0,0 +1,89 @@+import { join } from "node:path";++import { text } from "#setup/ask.js";+import type { VercelProjectReference } from "#setup/project-resolution.js";+import { runVercel, runVercelCaptureStdout } from "#setup/primitives/run-vercel.js";+import { writeTextFile } from "#setup/scaffold/files.js";++import { provisionTeamsConnector } from "./connect.js";+import {+ defineSetupIntegration,+ type SetupApplyContext,+ type SetupPrepareContext,+} from "../types.js";++export interface TeamsSetupDeps {+ provisionConnector: typeof provisionTeamsConnector;+ runVercel: typeof runVercel;+ runVercelCaptureStdout: typeof runVercelCaptureStdout;+ writeTextFile: typeof writeTextFile;+}++const defaultDeps: TeamsSetupDeps = {+ provisionConnector: provisionTeamsConnector,+ runVercel,+ runVercelCaptureStdout,+ writeTextFile,+};++function connectTemplate(uid: string): string {+ return `import { connectTeamsCredentials } from "@vercel/connect/eve";+import { teamsChannel } from "eve/channels/teams";++export default teamsChannel({+ credentials: connectTeamsCredentials(${JSON.stringify(uid)}),+});+`;+}++export interface TeamsSetupPlan {+ name: string;+ project: VercelProjectReference;+}++export async function prepareTeamsSetup(context: SetupPrepareContext): Promise<TeamsSetupPlan> {+ const name = await context.asker.ask(+ text({+ key: "teams.bot-name",+ message: "Microsoft Teams bot name",+ detected: "eve agent",+ required: true,+ validate: (value) => (value.trim().length === 0 ? "A bot name is required." : null),+ }),+ );+ const project = await context.resolveVercelProject("Microsoft Teams");+ return { name: name.trim(), project };+}++export async function applyTeamsSetup(+ plan: TeamsSetupPlan,+ context: SetupApplyContext,+ deps: TeamsSetupDeps = defaultDeps,+) {+ const connector = await deps.provisionConnector({+ ...plan,+ log: context.presenter.log,+ projectRoot: context.appRoot,+ signal: context.signal,+ deps,+ });+ await deps.writeTextFile(+ join(context.appRoot, "agent/channels/teams.ts"),+ connectTemplate(connector.uid),+ { force: context.force },+ );+ context.presenter.log.success("Scaffolded channel: teams");+ context.presenter.nextSteps([+ "Deploy the agent.",+ "Mention the bot in a channel, or send it a message in a personal chat.",+ ]);+ return { facts: [], deploymentRequired: true as const };+}++export const TEAMS_SETUP = defineSetupIntegration({+ kind: "teams",+ label: "Microsoft Teams",+ hint: "Managed Teams bot with Vercel Connect",+ prepare: prepareTeamsSetup,+ apply: applyTeamsSetup,+});