@open-everywhere/provider-teams 0.0.0-stage → 0.1.1

package/agent/channels/teams-catch-up.ts

@@ -0,0 +1,244 @@
+// teams-catch-up — Teams' registered SEAT CATCH-UP FETCH (OPE-1726): the seat's own channel (or reply
+// chain) since its last wake, normalized for core's shared catch-up path
+// (channels/seat-catch-up.ts).
+//
+// 🔴 THIS IS THE SURFACE WHOSE OWN HEADER SAID IT COULD NOT DO THIS, and the correction is worth
+// stating: `teams-supervisor.ts` records "NO PLATFORM-FETCH backscroll", which is true of the BOT
+// CONNECTOR — the transport a Teams activity arrives on carries no history API at all. Teams reads
+// its history over MICROSOFT GRAPH instead, which is a different credential and a different
+// transport, and `read_channel` has used it since the read adapter landed. The catch-up uses the same
+// one, so the seat reads exactly what a person asking it to `read_channel` would.
+//
+// WHAT "THE SEAT'S CONTAINER" IS HERE. Graph addresses a channel read as
+// `/teams/{team}/channels/{channel}/messages`, so BOTH ids are needed and neither is derivable from
+// the other. The request's `container` therefore carries them joined as `<teamId>/<channelId>` —
+// {@link parseTeamsCatchUpContainer} is the one place that spelling is written down. `threadRoot`
+// present ⇒ this wake sits in a reply chain, and the read ADDS that chain's replies to the channel's
+// own top-level messages — Graph serves the two from different endpoints and neither holds the other.
+//
+// 🔴 THAT `<teamId>` IS THE MICROSOFT 365 GROUP ID, NOT THE ONE THE ACTIVITY CARRIES. An inbound
+// activity's `channelData.team.id` is the BOT CONNECTOR's team id (`19:…@thread.tacv2`), which Graph
+// does not address — it keeps that spelling as a team's `internalId`. `channels/teams-graph-team-id.ts`
+// resolves the one into the other before the wake is dispatched (OPE-1808). Handing the raw activity
+// id to the URLs below is a 404, and the catch below turns a 404 into an empty window — which is why
+// the audit row this read writes states the status, and not only the count.
+//
+// 🔴 THE VENDOR CANNOT FILTER BY TIME on these endpoints (Graph channel messages support no
+// `$filter` on `createdDateTime` and no `$orderby`), so the bound is applied on this side and again
+// by the shared path.
+//
+// FAIL-SOFT PER RESOURCE: one Graph endpoint refusing does not erase messages returned by the other.
+// If every requested endpoint fails, the fetch propagates to core's shared fail-soft boundary, which
+// keeps the wake alive and records `seat.catch_up outcome=failed` (OPE-1842).
+//
+// 🔴 FAIL-SOFT WITHOUT A ROW IS A BLIND SPOT, AND OPE-1817 IS WHAT IT COSTS. Every outcome below —
+// a 404, a 200 with an empty page, a page the since-bound excluded, an unparsable container — used
+// to reach the seat as the SAME empty list, so a red on a live ship could not say which one
+// happened. {@link TEAMS_CATCH_UP_ACTION} now records one row per GRAPH CALL: the resource, the
+// status, the RAW Graph count and the KEPT count. `raw=0` is Graph answering nothing; `raw>0,
+// kept=0` is this side's bound or visibility gate. NO MESSAGE BODIES AND NO AUTHOR NAMES go in the
+// row — the ids it carries are the same addressing ids `teams.dispatched` already records.
+
+import { channelMessagesUrl, fetchGraphPages, liveTeamsGraphRequest, teamsTimedLinesFromRaw, threadRepliesUrl, type TeamsGraphRequester, type TeamsRenderedLine } from "./teams-read.js";
+import { appendAudit, catchUpSender, deploymentOrg, type AuditInput, type NormalizedMessage, type SeatCatchUpFetch } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** One page's worth. The catch-up window is "since the seat last woke", and a channel that collected
+ *  more than this in that window is one core's token cap would trim regardless. */
+const CATCH_UP_LIMIT = 100;
+
+/** Split the `<teamId>/<channelId>` container this surface's catch-up is addressed by. Returns
+ *  undefined for anything else rather than guessing a half — a partial address would read another
+ *  team's channel, the silent mis-address the wake-container design refuses. */
+export function parseTeamsCatchUpContainer(container: string): { teamId: string; channelId: string } | undefined {
+  const slash = container.indexOf("/");
+  if (slash <= 0) return undefined;
+  const teamId = container.slice(0, slash);
+  const channelId = container.slice(slash + 1);
+  if (!teamId || !channelId) return undefined;
+  return { teamId, channelId };
+}
+
+/**
+ * Normalize ONE rendered Graph line, applying the VISIBILITY GATE every fetch adapter owes core: a
+ * line with no text, no message id, no readable create time or NO ATTRIBUTABLE AUTHOR is dropped.
+ * 🔴 THE AUTHOR ARM IS THE LOAD-BEARING ONE. `teams-read.ts toIntermediate` produces three shapes —
+ * a person (`authorId` set), an application (`bot` set), and NEITHER, which is a message Graph gave
+ * no `from` for (a removed account, a tenant-side redaction). Without this arm that third shape would
+ * reach {@link catchUpSender} with no bot signal and enter the seat as an unattributed PERSON, which
+ * is exactly the body a seat must never be handed — the gate is what makes the shared rule's
+ * "an absent signal is a person" safe on this surface. An APPLICATION author (`bot`) is KEPT and tagged
+ * — attributable machine awareness the domain's admission policy then accepts or refuses — and the
+ * deployment's own bot id resolves `self`.
+ */
+function normalizeLine(
+  l: TeamsRenderedLine & { readonly createdMs: number },
+  selfActorId: string | undefined,
+  threadRoot: string | undefined,
+): NormalizedMessage | undefined {
+  const text = l.text.trim();
+  if (text.length === 0 || l.createdMs <= 0 || l.ts.length === 0) return undefined;
+  if (l.authorId === undefined && l.bot !== true) return undefined; // unattributable sender ⇒ fail closed
+  const isSelf = selfActorId !== undefined && l.authorId === selfActorId;
+  return {
+    // 🔴 `ts` ON A RENDERED TEAMS LINE IS THE MESSAGE ID, not a timestamp (teams-read.ts
+    // `toIntermediate` puts `m.id` there and keeps the time on `createdMs`). So the id slot takes it
+    // directly and the time comes from the timed variant — reading `ts` as a date is the mistake this
+    // comment exists to stop.
+    id: l.ts,
+    ms: l.createdMs,
+    // The bot's OWN posts carry no author id, matching every other surface's normalized shape.
+    ...(isSelf || l.authorId === undefined ? {} : { authorId: l.authorId }),
+    // THE SHARED SENDER RULE (OPE-1857): this surface contributes the vendor's own signal — the
+    // rendered line's `bot` bit, which Graph sets from the message's `from` identity set — and core
+    // decides what it means.
+    sender: catchUpSender({ self: isSelf, bot: l.bot }),
+    // A reply chain's messages are thread-scoped; a channel read is top-level.
+    ...(threadRoot ? { type: "thread" as const, threadId: threadRoot } : { type: "channel" as const }),
+    text,
+  };
+}
+
+/** Injected seam so the fetch drives offline in tests; defaults to the live Graph transport. */
+export interface TeamsCatchUpDeps {
+  readonly request: TeamsGraphRequester;
+  /** The deployment's own Entra object id, so its prior posts read as `self`. Absent ⇒ they arrive
+   *  tagged `bot` (an application author), which is visible and honest, never a crash. */
+  readonly selfActorId?: string;
+  /** The audit writer. Injected so the contract test reads the row this fetch emits instead of a
+   *  store; live callers get {@link appendAudit}, which never throws by its own contract. */
+  readonly audit?: (entry: AuditInput) => Promise<void>;
+}
+
+const liveDeps: TeamsCatchUpDeps = { request: liveTeamsGraphRequest };
+
+/** The audit action this read records under. One family, one spelling — a query for the next red
+ *  ship is `action = "teams.catch_up"` and nothing else. */
+export const TEAMS_CATCH_UP_ACTION = "teams.catch_up";
+
+/** The `<platform>/<workspace>/<surface>` domain-grain key the shared path hands down, split for the
+ *  audit row's own WHERE columns. Returns undefined for an absent key or a non-Teams one rather than
+ *  guessing a workspace — the row then says `unknown`, which is a fact, not a filled-in blank.
+ *  Pure; exported so the contract test pins the parse rather than re-deriving it. */
+export function teamsCatchUpScopeFromChannelKey(channelKey: string | undefined): { workspace: string; surface: string } | undefined {
+  if (!channelKey) return undefined;
+  const parts = channelKey.split("/");
+  if (parts.length !== 3 || parts[0] !== "teams" || !parts[1] || !parts[2]) return undefined;
+  return { workspace: parts[1], surface: parts[2] };
+}
+
+/** The HTTP status inside the requester's own thrown message (`… (HTTP 404) for <url> — <body>`), or
+ *  undefined when the failure carried none (a transport throw, an abort). ONLY the three digits are
+ *  read: the message also carries a slice of the vendor's response body, which never enters a row. */
+function httpStatusOf(err: unknown): number | undefined {
+  const m = /\(HTTP (\d{3})\)/.exec(err instanceof Error ? err.message : String(err));
+  return m ? Number(m[1]) : undefined;
+}
+
+/** The Graph resource path, host and query stripped — what the row names so the next red ship can
+ *  see WHICH call this read made without reconstructing it from the ids. */
+function graphPathOf(url: string): string {
+  const q = url.indexOf("?");
+  const bare = q < 0 ? url : url.slice(0, q);
+  const base = bare.indexOf("/v1.0/");
+  return base < 0 ? bare : bare.slice(base + "/v1.0".length);
+}
+
+/** The fetch, with its seams exposed so the contract test drives it with no network. */
+export async function fetchTeamsCatchUpWindow(
+  req: { container: string; threadRoot?: string; sinceMs: number; channelKey?: string },
+  deps: TeamsCatchUpDeps = liveDeps,
+): Promise<readonly NormalizedMessage[]> {
+  const scope = teamsCatchUpScopeFromChannelKey(req.channelKey);
+  const record = async (detail: Readonly<Record<string, unknown>>): Promise<void> => {
+    try {
+      await (deps.audit ?? appendAudit)({
+        org: deploymentOrg(),
+        platform: "teams",
+        workspace: scope?.workspace ?? "unknown",
+        ...(scope ? { surface: scope.surface } : {}),
+        action: TEAMS_CATCH_UP_ACTION,
+        detail: { ...detail, since: new Date(req.sinceMs).toISOString() },
+      });
+    } catch {
+      /* the row is diagnostics; losing it must not cost the seat its catch-up */
+    }
+  };
+
+  const target = parseTeamsCatchUpContainer(req.container);
+  if (!target) {
+    // The ONE outcome that never reaches Graph: a container this surface cannot split into the two
+    // ids every Graph URL needs. Recorded so it reads differently from an empty room.
+    await record({ status: "unaddressable", resource: "none", raw: 0, kept: 0 });
+    return [];
+  }
+
+  // 🔴 TWO CALLS, NOT A CHOICE BETWEEN THEM (OPE-1817). Graph splits one channel's history across two
+  // endpoints and neither is a superset of the other:
+  //   • `/channels/{c}/messages` returns the CHAIN ROOTS only — a reply is never in it;
+  //   • `/channels/{c}/messages/{root}/replies` returns that ONE chain's replies, and not the root.
+  // The seat is CHANNEL-grain (its session hangs off the domain key), while the wake it is answering
+  // sits in ONE reply chain. So both halves are the seat's own window, the two answers never overlap,
+  // and core's shared path orders, bounds and caps the union (channels/seat-catch-up.ts). Reading only
+  // the channel is what ship #206 and #207 measured: a chain that HAD carried the message read empty.
+  // Reading only the chain would drop every top-level message the channel collected — the same defect
+  // pointed the other way.
+  const reads: Array<{ readonly resource: "channel-messages" | "thread-replies"; readonly url: string; readonly threadRoot?: string }> = [
+    { resource: "channel-messages", url: channelMessagesUrl(target.teamId, target.channelId) },
+    ...(req.threadRoot ? [{ resource: "thread-replies" as const, url: threadRepliesUrl(target.teamId, target.channelId, req.threadRoot), threadRoot: req.threadRoot }] : []),
+  ];
+
+  const out: NormalizedMessage[] = [];
+  let failedReads = 0;
+  for (const read of reads) {
+    // Fail-soft PER READ, and it covers the normalization too: one endpoint refusing — or one
+    // malformed page — must not throw away what the other read returned. When every read fails the
+    // shared boundary below this adapter owns the wake-level fail-soft behavior.
+    try {
+      const raw = await fetchGraphPages(deps.request, read.url, CATCH_UP_LIMIT);
+      let kept = 0;
+      for (const line of teamsTimedLinesFromRaw(raw)) {
+        const n = normalizeLine(line, deps.selfActorId, read.threadRoot);
+        if (!n || n.ms < req.sinceMs) continue;
+        out.push(n);
+        kept++;
+      }
+      // `raw` is what GRAPH returned; `kept` is what survived the visibility gate and the since-bound.
+      // The two together are the whole diagnosis: raw 0 is the vendor's answer, raw>0 with kept 0 is ours.
+      await record({ status: "ok", resource: read.resource, path: graphPathOf(read.url), raw: raw.length, kept });
+    } catch (err) {
+      failedReads++;
+      const status = httpStatusOf(err);
+      await record({ status: "error", resource: read.resource, path: graphPathOf(read.url), raw: 0, kept: 0, ...(status === undefined ? {} : { httpStatus: status }) });
+    }
+  }
+  // Preserve the two-endpoint partial-read contract: one refusing endpoint must not erase what the
+  // other returned. When EVERY attempted read failed, however, propagate to the shared boundary so
+  // its seat.catch_up row says `failed` rather than falsely describing the channel as quiet.
+  if (failedReads === reads.length) throw new Error("Teams catch-up: every Graph read failed");
+  return out;
+}
+
+/**
+ * A Graph message's `createdDateTime` carries MILLISECOND grain (OPE-1847,
+ * `core/agent/channels/seat-catch-up.ts` {@link SeatCatchUpDeclaration.timestampPrecisionMs}).
+ * 🔴 ONE MILLISECOND IS NOT ZERO WIDENING. The road widens the LOWER bound by nothing here and the
+ * UPPER bound by exactly one millisecond, so a message stamped at the trigger's own instant is
+ * INSIDE the window and `excludeId` is the only thing that removes the trigger. A rendered Teams
+ * line carries the Graph message id in its `ts` slot, which is the value the wake path passes as
+ * `excludeId`.
+ * 🔴 IT IS STILL DECLARED, and the parity test requires it. The declaration is what makes "this
+ * surface needs the finest unit" a CHECKED claim rather than an omission, and an omission is
+ * indistinguishable from the GitHub and Notion defect this whole mechanism exists to close.
+ */
+export const TEAMS_TIMESTAMP_PRECISION_MS = 1;
+
+/** Teams' registered {@link SeatCatchUpFetch} — the one thing this surface contributes to the shared path. */
+export const teamsSeatCatchUpFetch: SeatCatchUpFetch = (req) =>
+  fetchTeamsCatchUpWindow({
+    container: req.container,
+    ...(req.threadRoot ? { threadRoot: req.threadRoot } : {}),
+    sinceMs: req.sinceMs,
+    // The domain-grain key the row is filed under. Dropped before OPE-1817, which left every row
+    // this read writes unattributable to a surface.
+    ...(req.channelKey ? { channelKey: req.channelKey } : {}),
+  });

package/agent/channels/teams-connector.ts

@@ -0,0 +1,183 @@
+// teams-connector — the ONE place a Teams Bot Framework Connector write leaves this host (OPE-1237).
+//
+// BEFORE THIS, every Teams write (`dispatchTeamsReply`, `liveTeamsPost`, `editTeamsMessage`,
+// `openTeamsPersonalConversation`, `deliverTeamsDirectMessage` in teams-post-arm.ts) called eve's own
+// `sendTeamsActivity`/`replyToTeamsActivity`/`updateTeamsActivity`/`callTeamsConnectorApi`
+// (`eve/channels/teams`) directly. eve's `callTeamsConnectorApi` is a bare `fetch` with no 429
+// handling, and — unlike GitHub's raw fetch, which this repo already owned before OPE-1235 —
+// it also THROWS AWAY the response headers before returning
+// (`node_modules/eve/dist/src/public/channels/teams/api.js`: `{body, ok, status}`, no `headers`), so
+// there was no way to read a `Retry-After` even by wrapping eve's own return value. Honouring it
+// means doing the Connector fetch host-side, the same move OPE-1235 made for GitHub's write seam
+// (providers/github/agent/channels/github-post-arm.ts's `githubWrite`) and OPE-1211 made for Slack's
+// (providers/slack/agent/channels/slack-web-api.ts).
+//
+// TOKEN RESOLUTION STAYS eve's: `resolveTeamsAccessToken` (the client-credentials OAuth flow, with
+// eve's own in-process cache and refresh-safety margin) is reused UNCHANGED. Reimplementing that flow
+// host-side would duplicate real behaviour for no backoff benefit — this ticket's claim is the
+// CONNECTOR request (one per write, where a 429 costs a lost reply), not the OAuth token mint (held
+// warm for its whole life, the same "low exposure, different ticket" shape OPE-1288 states for
+// Linear's mint).
+//
+// WHAT IT DOES, and only this — mirrors github-post-arm.ts's `githubWrite`:
+//   • Builds the request — the Connector base (serviceUrl), the path, the bearer token, a JSON body.
+//   • Honours a 429's `Retry-After` through `channels/rate-limit-retry.ts`'s `withRetryAfter`,
+//     bounded in attempts, in one wait, and in total wait.
+//   • Ends an outlasted 429 in the NAMED `RateLimitExhaustedError`.
+//   • Parses the response body the same way eve's own `parseResponseBody` does (empty → null,
+//     JSON → parsed, otherwise the raw text) so every call site's `res.body` reads exactly as it did
+//     when eve returned it.
+
+import { resolveTeamsAccessToken } from "eve/channels/teams";
+import { withRetryAfter, type RateLimitRetryOptions } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The subset of the global `fetch` this seam uses — injectable so a test drives it without Teams. */
+export type TeamsFetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+/** Transport and retry seams. A test injects them; live code passes none and takes the shared
+ *  defaults from `channels/rate-limit-retry.ts`. */
+export interface TeamsConnectorDeps {
+  readonly fetch?: TeamsFetchLike;
+  readonly retry?: Pick<RateLimitRetryOptions, "maxAttempts" | "capMs" | "fallbackMs" | "totalBudgetMs" | "sleep" | "now">;
+}
+
+/** Mirrors eve's `TeamsApiResponse` — the shape every write call site in teams-post-arm.ts reads. */
+export interface TeamsConnectorResult {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly body: unknown;
+}
+
+function trimTrailingSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+/** Mirrors eve's `parseResponseBody`: empty body → null, JSON → parsed, otherwise the raw text. */
+async function parseTeamsResponseBody(res: Response): Promise<unknown> {
+  const text = await res.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Issue one Bot Framework Connector REST call under a client-credentials bearer token, with the 429
+ * backoff applied.
+ *
+ * `operation` is the vendor route name `RateLimitExhaustedError` reports on exhaustion — never the
+ * resolved path, which would put a conversation id into a failure that promises every field on it is
+ * safe to log (the same discipline `githubWrite`'s `operation` follows).
+ */
+export async function teamsConnectorWrite(
+  input: {
+    readonly operation: string;
+    readonly serviceUrl: string;
+    readonly path: string;
+    readonly method?: "GET" | "POST" | "PUT" | "DELETE";
+    readonly body?: unknown;
+  },
+  deps: TeamsConnectorDeps = {},
+): Promise<TeamsConnectorResult> {
+  const token = await resolveTeamsAccessToken();
+  const send = (): Promise<Response> =>
+    (deps.fetch ?? (globalThis.fetch as TeamsFetchLike))(`${trimTrailingSlash(input.serviceUrl)}${input.path}`, {
+      method: input.method ?? "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json; charset=utf-8" },
+      ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
+    });
+  const res = await withRetryAfter(send, { ...deps.retry, surface: "teams", operation: input.operation });
+  return { ok: res.ok, status: res.status, body: await parseTeamsResponseBody(res) };
+}
+
+/** Narrows eve's `toPostedActivity` (`{id, raw}`) to just `{id}` — the ONLY field any call site in
+ *  this package reads (`rg '\.raw'` over the teams package: zero hits). An activity id is always a
+ *  string when present; anything else (including a missing field) reports the empty string,
+ *  matching eve's own fallback. */
+function toPostedTeamsActivity(body: unknown): { id: string } {
+  const id = body !== null && typeof body === "object" && typeof (body as { id?: unknown }).id === "string" ? (body as { id: string }).id : "";
+  return { id };
+}
+
+/** Mirrors eve's `formatConnectorErrorBody` — a bounded, safe-to-log rendering of a Connector error
+ *  body for `updateTeamsActivityBackedOff`'s error message. */
+function formatTeamsConnectorErrorBody(body: unknown): string {
+  const text = typeof body === "string" ? body : JSON.stringify(body);
+  if (text === undefined || text.length === 0) return "empty response body";
+  return text.length <= 1000 ? text : `${text.slice(0, 997)}...`;
+}
+
+// --- HOST-SIDE EQUIVALENTS OF eve's sendTeamsActivity/replyToTeamsActivity/updateTeamsActivity ---
+//
+// Every write call site in this package (teams-post-arm.ts, teams-front.ts's fail-soft notice)
+// dispatches through one of these instead of eve's own transport — see this file's header for why.
+// The URL template, HTTP method and every thrown error string below match eve's own implementation
+// exactly (verified against `eve/dist/src/public/channels/teams/api.js`), so this is a backoff
+// added, not a behaviour changed for any call site that exists today. One divergence, currently
+// inert: eve serializes a write body through `JSON.stringify(parseJsonObject(body))`, which THROWS
+// for a non-plain-object/non-JSON-serializable body; `teamsConnectorWrite` (above) does a bare
+// `JSON.stringify(body)`. Every call site in this repo passes a plain `{type, text, ...}` literal, so
+// the two are equivalent today — but a future caller passing something `parseJsonObject` would
+// reject (a class instance, a `Map`) would silently behave differently here than it would have under
+// eve.
+
+/** Mirrors eve's `sendTeamsActivity` — `POST /v3/conversations/{id}/activities`. */
+export async function sendTeamsActivityBackedOff(
+  input: { readonly serviceUrl: string; readonly conversationId: string; readonly body: unknown },
+  deps: TeamsConnectorDeps = {},
+): Promise<{ id: string }> {
+  const res = await teamsConnectorWrite(
+    {
+      operation: "conversations.activities.send",
+      serviceUrl: input.serviceUrl,
+      path: `/v3/conversations/${encodeURIComponent(input.conversationId)}/activities`,
+      body: input.body,
+    },
+    deps,
+  );
+  if (!res.ok) throw new Error(`Teams send activity failed with HTTP ${res.status}.`);
+  return toPostedTeamsActivity(res.body);
+}
+
+/** Mirrors eve's `replyToTeamsActivity` — `POST /v3/conversations/{id}/activities/{activityId}`. */
+export async function replyToTeamsActivityBackedOff(
+  input: { readonly serviceUrl: string; readonly conversationId: string; readonly activityId: string; readonly body: unknown },
+  deps: TeamsConnectorDeps = {},
+): Promise<{ id: string }> {
+  const res = await teamsConnectorWrite(
+    {
+      operation: "conversations.activities.reply",
+      serviceUrl: input.serviceUrl,
+      path: `/v3/conversations/${encodeURIComponent(input.conversationId)}/activities/${encodeURIComponent(input.activityId)}`,
+      body: input.body,
+    },
+    deps,
+  );
+  if (!res.ok) throw new Error(`Teams reply activity failed with HTTP ${res.status}.`);
+  return toPostedTeamsActivity(res.body);
+}
+
+/** Mirrors eve's `updateTeamsActivity` — `PUT /v3/conversations/{id}/activities/{activityId}`. */
+export async function updateTeamsActivityBackedOff(
+  input: { readonly serviceUrl: string; readonly conversationId: string; readonly activityId: string; readonly body: unknown },
+  deps: TeamsConnectorDeps = {},
+): Promise<{ id: string }> {
+  const res = await teamsConnectorWrite(
+    {
+      operation: "conversations.activities.update",
+      serviceUrl: input.serviceUrl,
+      path: `/v3/conversations/${encodeURIComponent(input.conversationId)}/activities/${encodeURIComponent(input.activityId)}`,
+      method: "PUT",
+      body: input.body,
+    },
+    deps,
+  );
+  if (!res.ok) {
+    throw new Error(
+      `Teams update activity failed with HTTP ${res.status} for conversation "${input.conversationId}" activity "${input.activityId}": ${formatTeamsConnectorErrorBody(res.body)}`,
+    );
+  }
+  return toPostedTeamsActivity(res.body);
+}