@open-everywhere/provider-teams 0.3.0 → 0.5.0

package/agent/app-manifest.ts

@@ -20,6 +20,10 @@ export const TEAMS_DEPLOY_HOST_PLACEHOLDER = "YOUR-DEPLOY-URL";
 /** The app name the manifest carries when neither an explicit name nor `identity.name` is given. */
 export const TEAMS_DEFAULT_APP_NAME = "Open Everywhere";
 
+/** The manifest's accent colour: the brand ink (brand/README.md). It was Discord's blurple, a
+ *  leftover with no tie to this project. Teams draws it behind an icon with a transparent area. */
+export const TEAMS_BRAND_ACCENT_COLOR = "#1a1a1a";
+
 /** Teams' limit on `name.short`. A longer one fails the package upload. */
 export const TEAMS_APP_NAME_MAX = 30;
 
@@ -80,7 +84,7 @@ export function teamsAppManifestTemplate(opts: TeamsAppManifestOptions = {}): st
           "conversation until that channel is confirmed team-wide.",
       },
       icons: { color: "color.png", outline: "outline.png" },
-      accentColor: "#5865F2",
+      accentColor: TEAMS_BRAND_ACCENT_COLOR,
       bots: [
         {
           botId: "{{MICROSOFT_APP_ID}}",
@@ -118,6 +122,7 @@ export const TEAMS_APP_CONSOLE_URL = "https://admin.teams.microsoft.com";
 /** The ordered steps, from the manifest to an installed app. */
 export const TEAMS_APP_MANIFEST_STEPS: readonly string[] = [
   "Save the manifest below as manifest.json in the teams-app/ directory, beside color.png and outline.png.",
+  "Keep color.png and outline.png unless you set identity.name and chose your own icon: they are the project mark, the default avatar. A checkout without teams-app/ gets both from https://raw.githubusercontent.com/open-everywhere/open-everywhere/main/teams-app/color.png and https://raw.githubusercontent.com/open-everywhere/open-everywhere/main/teams-app/outline.png. To use your own icon, replace both (color 192x192; outline 32x32, white on transparent).",
   "Replace {{MICROSOFT_APP_ID}} with the Azure Bot's Application (client) ID (MICROSOFT_APP_ID) — it appears three times and must match everywhere.",
   "Replace {{DEVELOPER_NAME}} with your org's name.",
   "Zip it flat: zip -j app.zip manifest.json color.png outline.png (Teams requires the manifest at the zip root).",

package/agent/approvals/teams-card.ts

@@ -0,0 +1,188 @@
+// Pure Teams renderers + the action-data codec for the approval card (OPE-2424) — the Teams sibling
+// of core's card.ts (Slack Block Kit) and the Discord bundle's discord-card.ts. PURE by the same
+// doctrine: no I/O, nothing async. The card is a CODE-RENDERED VIEW of the FROZEN args, never model
+// text. The I/O half (the Connector poster and the invoke handler) lives in teams-flow.ts.
+//
+// Teams differs from Slack and Discord in three ways, and all three are handled here:
+//   - The card is an ADAPTIVE CARD attachment on a message activity. The body is TextBlocks, and the
+//     buttons are `Action.Execute` actions.
+//   - `Action.Execute` (Universal Actions), not `Action.Submit`. A tap arrives as an `invoke` activity
+//     named `adaptiveCard/action`, and the HTTP response to that invoke can carry a REPLACEMENT card
+//     (the decided render) or a message only the clicker sees (a refusal). That is the same response
+//     shape Discord's interaction reply has, so the click path maps one resolution to one response.
+//   - The payload rides the action's `data` object, not an id string. The org rides there too, for
+//     the reason Slack puts it in the button `value`: the click handler needs the org BEFORE it can
+//     look the row up. The data key is distinct from eve's own HITL key (`eve_input`), so the front
+//     route can tell an OE approval tap from an eve HITL answer without a second check.
+
+import type { CardOptionTone, PendingActionRow } from "@open-everywhere/core/agent/adapter-api.js";
+import { approvalLabel, pendingCardLayout, plainSummaryForRow } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The `invoke` activity name Teams gives an `Action.Execute` tap. */
+export const TEAMS_ADAPTIVE_CARD_ACTION_INVOKE = "adaptiveCard/action";
+
+/** The `verb` every OE approval action carries. The decision rides `data`, so one verb covers all. */
+export const OE_TEAMS_APPROVAL_VERB = "oe-approval";
+
+/** The `data` key every OE approval action carries. Distinct from eve's HITL key (`eve_input`). */
+export const OE_TEAMS_APPROVAL_DATA_KEY = "oe_teams_approval";
+
+/** The Adaptive Card attachment content type. */
+export const TEAMS_ADAPTIVE_CARD_CONTENT_TYPE = "application/vnd.microsoft.card.adaptive";
+
+/** Universal Actions (`Action.Execute`) need schema 1.4 or later. */
+const ADAPTIVE_CARD_VERSION = "1.4";
+
+/**
+ * Every verb a Teams approval action can carry — the same closed set the Discord bundle uses, and a
+ * SUBSET of core's `ApprovalDecision`. `contradict` is the judge-lift notice's one button: it decides
+ * nothing, it records an overrule of a verdict whose act has already run.
+ */
+export type TeamsApprovalDecision = "approve" | "reject" | "approve_session" | "contradict";
+
+/** The closed verb set as a VALUE, so build and parse cannot drift apart. */
+const TEAMS_APPROVAL_DECISIONS: readonly TeamsApprovalDecision[] = ["approve", "reject", "approve_session", "contradict"];
+
+/** One decoded OE approval action payload. */
+export interface TeamsApprovalAction {
+  readonly id: string;
+  readonly decision: TeamsApprovalDecision;
+  readonly org: string;
+}
+
+/** One Adaptive Card element or action. Loosely typed on purpose, as card.ts's SlackBlock is. */
+export interface AdaptiveElement {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+/** One rendered Adaptive Card. */
+export interface TeamsAdaptiveCard {
+  readonly type: "AdaptiveCard";
+  readonly $schema: string;
+  readonly version: string;
+  readonly body: readonly AdaptiveElement[];
+  readonly actions?: readonly AdaptiveElement[];
+}
+
+/** The `data` object of one OE approval action. */
+export function buildTeamsApprovalData(row: Pick<PendingActionRow, "id" | "org">, decision: TeamsApprovalDecision): Record<string, unknown> {
+  return { [OE_TEAMS_APPROVAL_DATA_KEY]: { id: row.id, decision, org: row.org } };
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function nonEmpty(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * Decode an OE approval payload from an action's `data` object. Returns null for anything else —
+ * a foreign data object, a missing id or org, or a decision outside the closed set — so a caller
+ * reads "not parseable" as "not ours" with no second check (core's parseApprovalAction does the same).
+ */
+export function parseTeamsApprovalData(data: unknown): TeamsApprovalAction | null {
+  if (!isObject(data)) return null;
+  const payload = data[OE_TEAMS_APPROVAL_DATA_KEY];
+  if (!isObject(payload)) return null;
+  const id = nonEmpty(payload["id"]);
+  const org = nonEmpty(payload["org"]);
+  const decision = payload["decision"];
+  if (!id || !org || typeof decision !== "string") return null;
+  if (!TEAMS_APPROVAL_DECISIONS.includes(decision as TeamsApprovalDecision)) return null;
+  return { id, decision: decision as TeamsApprovalDecision, org };
+}
+
+function textBlock(text: string, extra: Record<string, unknown> = {}): AdaptiveElement {
+  return { type: "TextBlock", text, wrap: true, ...extra };
+}
+
+function card(body: readonly AdaptiveElement[], actions?: readonly AdaptiveElement[]): TeamsAdaptiveCard {
+  return {
+    type: "AdaptiveCard",
+    $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+    version: ADAPTIVE_CARD_VERSION,
+    body,
+    ...(actions && actions.length > 0 ? { actions } : {}),
+  };
+}
+
+function execute(row: Pick<PendingActionRow, "id" | "org">, title: string, decision: TeamsApprovalDecision, style?: "positive" | "destructive"): AdaptiveElement {
+  return {
+    type: "Action.Execute",
+    title,
+    verb: OE_TEAMS_APPROVAL_VERB,
+    data: buildTeamsApprovalData(row, decision),
+    ...(style ? { style } : {}),
+  };
+}
+
+/** The shared card body: header, then one TextBlock per summary line, then the provenance line. */
+function cardBody(header: string, summaryLines: readonly string[], footer: string): AdaptiveElement[] {
+  return [
+    textBlock(header, { weight: "Bolder", size: "Medium" }),
+    ...summaryLines.map((line) => textBlock(line)),
+    textBlock(footer, { isSubtle: true, size: "Small" }),
+  ];
+}
+
+/** An approval card's body: the PLAIN SENTENCE first (OPE-2434), then the `Approval requested: <kind>` label, the summary lines and the provenance line. The sentence went through core's `plainValue`, so it carries no markdown a TextBlock would render. */
+function approvalCardBody(row: PendingActionRow, summaryLines: readonly string[], footer: string): AdaptiveElement[] {
+  return [
+    textBlock(plainSummaryForRow(row), { weight: "Bolder", size: "Medium" }),
+    textBlock(approvalLabel(row.kind), { isSubtle: true, size: "Small", spacing: "None" }),
+    ...summaryLines.map((line) => textBlock(line)),
+    textBlock(footer, { isSubtle: true, size: "Small" }),
+  ];
+}
+
+const OPTION_STYLE: Record<CardOptionTone, "positive" | "destructive" | undefined> = { primary: "positive", danger: "destructive", neutral: undefined };
+
+/**
+ * The card for a still-pending action: the plain sentence, the summary, "requested by / expires", and one `Action.Execute` per layout option. Mirrors card.ts's pendingCardBlocks. The requester is the Bot Framework principal id, because an Adaptive Card mention needs the person's display name, and the frozen row carries only the id.
+ * The OPTIONS come from core's card layout (OPE-53, OPE-2363: only a ROUTINE's card gets the middle grant option), so Slack, Discord and Teams cannot disagree, and OPE-2456's extra option lands here with no change.
+ */
+export function pendingTeamsCard(row: PendingActionRow, summaryLines: readonly string[]): TeamsAdaptiveCard {
+  const layout = pendingCardLayout(row, summaryLines);
+  const actions = layout.options.map((o) => execute(row, o.label, o.verb, OPTION_STYLE[o.tone]));
+  return card(approvalCardBody(row, summaryLines, `Requested by ${layout.requestedBy} · ${layout.expiry}`), actions);
+}
+
+/**
+ * The card once a decision has landed: the same sentence and summary, no actions, one outcome line. It decides
+ * nothing — it renders what the caller already CAS-decided. `deciderLabel` is the name the click
+ * activity carried, when the caller has one; the row's principal id otherwise.
+ */
+export function decidedTeamsCard(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string, deciderLabel?: string): TeamsAdaptiveCard {
+  const who = deciderLabel ?? row.decidedBy ?? "unknown";
+  const decided =
+    row.status === "approved"
+      ? `✅ Approved by ${who} · ${outcomeLine}`
+      : row.status === "rejected"
+        ? `❌ Rejected by ${who}${outcomeLine === "rejected" ? "" : ` · ${outcomeLine}`}`
+        : "⏰ Expired";
+  return card(approvalCardBody(row, summaryLines, decided));
+}
+
+/**
+ * The judge-lift notice (OPE-1103 on Discord, OPE-2424 here): the trace of an act the armed judge
+ * lifted, with the one "This should not have run" button. NOT an approval card — no Approve, no
+ * Reject, no expiry line — because the act has already run.
+ */
+export function judgeLiftNoticeTeamsCard(row: PendingActionRow, summaryLines: readonly string[], outcomeLine: string): TeamsAdaptiveCard {
+  return card(
+    cardBody(
+      `Ran without asking: ${row.kind}`,
+      summaryLines,
+      `⚡ Auto-approved by the approval judge — no card was posted and this has already run · ${outcomeLine}`,
+    ),
+    [execute(row, "This should not have run", "contradict", "destructive")],
+  );
+}
+
+/** One Adaptive Card as a message-activity attachment. */
+export function teamsCardAttachment(c: TeamsAdaptiveCard): { readonly contentType: string; readonly content: TeamsAdaptiveCard } {
+  return { contentType: TEAMS_ADAPTIVE_CARD_CONTENT_TYPE, content: c };
+}