@open-everywhere/adapters 0.5.0 → 0.6.0

package/agent/meetings/native-http.ts

@@ -0,0 +1,72 @@
+// Shared plumbing for the native-transcript readers (OPE-2471): an injectable fetch, a capped body read, and
+// a small token cache. Every reader is host code that calls one vendor API with the organisation's own
+// credential; nothing here enters a sandbox, and no response text is ever echoed into a thread.
+
+/** The fetch a reader uses. Injected in tests with recorded fixtures; the live one is the global fetch. */
+export type NativeFetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+/** How long ONE vendor call may take. A call that runs out throws, and core counts the read as "the platform
+ *  did not answer": OE checks again on the next sweep. It bounds each call only: a read makes up to a few calls
+ *  in sequence, and the meeting sweep bounds a whole tick with its own time budget (meetings/native-recap.ts). */
+const NATIVE_CALL_TIMEOUT_MS = 30_000;
+
+/** The live fetch every reader uses by default: the global fetch with a per-call timeout. */
+export const timedFetch: NativeFetch = (url, init) => fetch(url, { ...init, signal: AbortSignal.timeout(NATIVE_CALL_TIMEOUT_MS) });
+
+/** The largest body a reader accepts: a three-hour transcript is well under 2 MB. */
+const MAX_NATIVE_BODY_BYTES = 8 * 1024 * 1024;
+
+/** Read a response body as text, refusing one larger than the cap. */
+export async function readCappedText(res: Response): Promise<string> {
+  const declared = Number(res.headers.get("content-length") ?? "0");
+  if (Number.isFinite(declared) && declared > MAX_NATIVE_BODY_BYTES) throw new Error(`response body is ${declared} bytes, over the ${MAX_NATIVE_BODY_BYTES}-byte cap`);
+  const text = await res.text();
+  if (text.length > MAX_NATIVE_BODY_BYTES) throw new Error(`response body is over the ${MAX_NATIVE_BODY_BYTES}-byte cap`);
+  return text;
+}
+
+/** Read a JSON body, or `{}` when it does not parse (an error body need not be JSON). */
+export async function readJsonLoose(res: Response): Promise<Record<string, unknown>> {
+  try {
+    const v = JSON.parse(await readCappedText(res)) as unknown;
+    return v !== null && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** A thrown error a reader turns into "the platform did not answer, check again later". Never echoes a body. */
+export function unexpectedStatus(what: string, status: number): Error {
+  return new Error(`${what} answered HTTP ${status}`);
+}
+
+interface CachedToken {
+  readonly token: string;
+  readonly expiresAt: number;
+}
+
+/**
+ * A per-process access-token cache, keyed by the caller (credential + subject). A token is reused until one
+ * minute before it expires. The key never holds the secret itself: callers pass a non-secret key.
+ */
+export class TokenCache {
+  readonly #tokens = new Map<string, CachedToken>();
+  get(key: string, now: number): string | undefined {
+    const t = this.#tokens.get(key);
+    return t !== undefined && t.expiresAt - 60_000 > now ? t.token : undefined;
+  }
+  set(key: string, token: string, expiresInSeconds: unknown, now: number): void {
+    const s = typeof expiresInSeconds === "number" && Number.isFinite(expiresInSeconds) && expiresInSeconds > 0 ? expiresInSeconds : 300;
+    this.#tokens.set(key, { token, expiresAt: now + s * 1000 });
+  }
+}
+
+/** True when `raw` is an https URL on `host` or one of its subdomains. A reader sends its token only there. */
+export function onHost(raw: string, host: string): boolean {
+  try {
+    const u = new URL(raw);
+    return u.protocol === "https:" && u.port === "" && (u.hostname === host || u.hostname.endsWith(`.${host}`));
+  } catch {
+    return false;
+  }
+}

package/agent/meetings/native-meet.ts

@@ -0,0 +1,173 @@
+// The Google Meet native-transcript reader (OPE-2471): the Meet REST API v2, read through the organisation's
+// service account with domain-wide delegation, acting as the meeting's organiser.
+//
+//   1. token:       a JWT signed with the service account's key (RS256), `sub` = the organiser, scope
+//                   `meetings.space.readonly`, exchanged at oauth2.googleapis.com/token
+//   2. records:     GET /v2/conferenceRecords?filter=space.meeting_code="<code>" — one per session
+//   3. transcripts: GET /v2/<record>/transcripts — state STARTED, ENDED or FILE_GENERATED
+//   4. entries:     GET /v2/<transcript>/entries — the spoken lines, each naming a participant
+//   5. names:       GET /v2/<record>/participants — the participants' display names
+//
+// WHAT THE ADMIN GRANTS: the Google Meet REST API on the service account's Cloud project, and domain-wide
+// delegation of `https://www.googleapis.com/auth/meetings.space.readonly` to the service account's client id
+// in the Workspace Admin console. The meeting needs transcription on. Google keeps transcript entries for 30
+// days after the conference ends, so an older record is `expired`.
+
+import { createSign } from "node:crypto";
+import type { NativeTranscriptResult, NativeTranscriptSource, NativeMeetingRef, NativeReadContext, NativeTranscriptSegment } from "@open-everywhere/core/agent/adapter-api.js";
+import { TokenCache, onHost, readJsonLoose, unexpectedStatus, type NativeFetch, timedFetch } from "./native-http.js";
+
+const MEET = "https://meet.googleapis.com/v2";
+const TOKEN_URI = "https://oauth2.googleapis.com/token";
+export const MEET_SCOPE = "https://www.googleapis.com/auth/meetings.space.readonly";
+const MAX_PAGES = 100;
+
+export const MEET_ACCESS_HINT =
+  "In the Google Workspace Admin console, grant the service account's client id domain-wide delegation of https://www.googleapis.com/auth/meetings.space.readonly, and enable the Google Meet REST API in its Cloud project.";
+
+const b64url = (v: string | Buffer): string => Buffer.from(v).toString("base64url");
+
+/** The signed JWT-bearer assertion for one organiser. The test verifies its signature from the token request. */
+function meetAssertion(key: { readonly client_email: string; readonly private_key: string }, subject: string, nowMs: number): string {
+  const iat = Math.floor(nowMs / 1000);
+  const head = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const claims = b64url(JSON.stringify({ iss: key.client_email, sub: subject, scope: MEET_SCOPE, aud: TOKEN_URI, iat, exp: iat + 3600 }));
+  const signer = createSign("RSA-SHA256");
+  signer.update(`${head}.${claims}`);
+  return `${head}.${claims}.${b64url(signer.sign(key.private_key))}`;
+}
+
+interface Record_ {
+  readonly name: string;
+  readonly startTime?: string;
+  readonly endTime?: string;
+  readonly expireTime?: string;
+}
+
+function str(o: unknown, k: string): string | undefined {
+  const v = (o as Record<string, unknown> | null)?.[k];
+  return typeof v === "string" ? v : undefined;
+}
+
+export function meetTranscriptSource(fetchImpl: NativeFetch = timedFetch, now: () => number = Date.now): NativeTranscriptSource {
+  const tokens = new TokenCache();
+
+  async function token(keyJson: string, subject: string): Promise<string | NativeTranscriptResult> {
+    let key: { client_email: string; private_key: string };
+    try {
+      const k = JSON.parse(keyJson) as Record<string, unknown>;
+      if (typeof k.client_email !== "string" || typeof k.private_key !== "string") throw new Error("shape");
+      key = { client_email: k.client_email, private_key: k.private_key };
+    } catch {
+      return { status: "refused", reason: "credential", hint: "The stored service-account key is not a Google JSON key file." };
+    }
+    const cacheKey = `${key.client_email}\n${subject}`;
+    const cached = tokens.get(cacheKey, now());
+    if (cached !== undefined) return cached;
+    let assertion: string;
+    try {
+      assertion = meetAssertion(key, subject, now());
+    } catch {
+      return { status: "refused", reason: "credential", hint: "The stored service-account key's private key does not sign." };
+    }
+    const res = await fetchImpl(TOKEN_URI, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion }).toString(),
+    });
+    const body = await readJsonLoose(res);
+    if (!res.ok) {
+      // `unauthorized_client`: the delegation for this scope is not granted. Anything else on a 4xx is the key.
+      if (body.error === "unauthorized_client") return { status: "refused", reason: "access-off", hint: MEET_ACCESS_HINT };
+      if (res.status >= 400 && res.status < 500) return { status: "refused", reason: "credential", hint: "Google refused the service account's key, or the organiser is not a user in the Workspace." };
+      throw unexpectedStatus("the Google token endpoint", res.status);
+    }
+    if (typeof body.access_token !== "string") throw unexpectedStatus("the Google token endpoint", res.status);
+    tokens.set(cacheKey, body.access_token, body.expires_in, now());
+    return body.access_token;
+  }
+
+  type Got = { readonly ok: true; readonly body: Record<string, unknown> } | { readonly ok: false; readonly result: NativeTranscriptResult };
+
+  async function get(url: string, bearer: string, what: string): Promise<Got> {
+    if (!onHost(url, "meet.googleapis.com")) throw new Error(`${what}: refusing to send the token off meet.googleapis.com`);
+    const res = await fetchImpl(url, { headers: { authorization: `Bearer ${bearer}` } });
+    if (res.status === 401) return { ok: false, result: { status: "refused", reason: "credential", hint: "Google refused the service account's token." } };
+    if (res.status === 403) return { ok: false, result: { status: "refused", reason: "access-off", hint: MEET_ACCESS_HINT } };
+    if (res.status === 404) return { ok: false, result: { status: "refused", reason: "expired" } };
+    if (!res.ok) throw unexpectedStatus(what, res.status);
+    return { ok: true, body: await readJsonLoose(res) };
+  }
+
+  /** Every page of a list, by `nextPageToken`. A refusal on any page is the answer. */
+  async function list(base: string, field: string, bearer: string, what: string): Promise<unknown[] | NativeTranscriptResult> {
+    const out: unknown[] = [];
+    let pageToken: string | undefined;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const sep = base.includes("?") ? "&" : "?";
+      const got = await get(`${base}${sep}pageSize=100${pageToken !== undefined ? `&pageToken=${encodeURIComponent(pageToken)}` : ""}`, bearer, what);
+      if (!got.ok) return got.result;
+      const items = got.body[field];
+      if (Array.isArray(items)) out.push(...items);
+      pageToken = str(got.body, "nextPageToken");
+      if (pageToken === undefined || pageToken === "") break;
+    }
+    return out;
+  }
+
+  return {
+    platform: "meet",
+    disclosure: "OE reads the transcript Google Meet made, through the Meet REST API, with the organisation's own service account acting as the organiser (domain-wide delegation, read-only).",
+    async read(ref: NativeMeetingRef, ctx: NativeReadContext): Promise<NativeTranscriptResult> {
+      const m = ctx.policy.meet;
+      if (m === undefined) return { status: "refused", reason: "credential", hint: "The meeting policy declares no Google Meet credential." };
+      const subject = ref.organiserEmail;
+      if (subject === undefined || !m.domains.includes(subject.slice(subject.lastIndexOf("@") + 1))) return { status: "refused", reason: "not-found" };
+      const tok = await token(await ctx.secret(m.serviceAccountKeyRef), subject);
+      if (typeof tok !== "string") return tok;
+
+      const filter = `space.meeting_code = "${ref.roomId}"`;
+      const listed = await list(`${MEET}/conferenceRecords?filter=${encodeURIComponent(filter)}`, "conferenceRecords", tok, "the Meet conference list");
+      if (!Array.isArray(listed)) return listed.status === "refused" && listed.reason === "expired" ? { status: "refused", reason: "not-found" } : listed;
+      const records: Record_[] = listed
+        .map((r) => ({ name: str(r, "name") ?? "", ...(str(r, "startTime") ? { startTime: str(r, "startTime")! } : {}), ...(str(r, "endTime") ? { endTime: str(r, "endTime")! } : {}), ...(str(r, "expireTime") ? { expireTime: str(r, "expireTime")! } : {}) }))
+        .filter((r) => r.name.startsWith("conferenceRecords/") && (ref.startedAfter === undefined || Date.parse(r.startTime ?? "") >= ref.startedAfter))
+        .sort((a, b) => Date.parse(b.startTime ?? "") - Date.parse(a.startTime ?? ""));
+      const rec = records[0];
+      // No session yet, or the session is on now.
+      if (rec === undefined || rec.endTime === undefined) return { status: "pending" };
+      if (rec.expireTime !== undefined && Date.parse(rec.expireTime) <= now()) return { status: "refused", reason: "expired" };
+
+      const transcripts = await list(`${MEET}/${rec.name}/transcripts`, "transcripts", tok, "the Meet transcript list");
+      if (!Array.isArray(transcripts)) return transcripts;
+      if (transcripts.length === 0) return { status: "refused", reason: "not-transcribed" };
+      const done = transcripts.filter((t) => str(t, "state") === "ENDED" || str(t, "state") === "FILE_GENERATED");
+      if (done.length < transcripts.length) return { status: "pending" };
+
+      const people = await list(`${MEET}/${rec.name}/participants`, "participants", tok, "the Meet participant list");
+      if (!Array.isArray(people)) return people;
+      const names = new Map<string, string>();
+      for (const p of people) {
+        const o = p as Record<string, unknown>;
+        const who = str(o.signedinUser, "displayName") ?? str(o.anonymousUser, "displayName") ?? str(o.phoneUser, "displayName");
+        const name = str(o, "name");
+        if (name !== undefined && who !== undefined) names.set(name, who);
+      }
+
+      const start = Date.parse(rec.startTime ?? "");
+      const segments: NativeTranscriptSegment[] = [];
+      for (const t of done) {
+        const entries = await list(`${MEET}/${str(t, "name")}/entries`, "transcriptEntries", tok, "the Meet transcript entries");
+        if (!Array.isArray(entries)) return entries;
+        for (const e of entries) {
+          const text = str(e, "text");
+          if (text === undefined) continue;
+          const at = Date.parse(str(e, "startTime") ?? "");
+          segments.push({ speaker: names.get(str(e, "participant") ?? "") ?? "", text, ...(Number.isFinite(at) && Number.isFinite(start) ? { startMs: Math.max(0, at - start) } : {}) });
+        }
+      }
+      segments.sort((a, b) => (a.startMs ?? 0) - (b.startMs ?? 0));
+      return { status: "ready", segments, ...(rec.startTime !== undefined ? { startedAt: rec.startTime } : {}), endedAt: rec.endTime };
+    },
+  };
+}

package/agent/meetings/native-sources.ts

@@ -0,0 +1,14 @@
+// Boot registration of the three native-transcript readers (OPE-2471). Each one reads only when the meeting
+// policy's `native` block declares its platform and a member approves a `meeting.recap` card, so registering
+// all three is harmless on a deployment that uses none.
+
+import { registerNativeTranscriptSource } from "@open-everywhere/core/agent/adapter-api.js";
+import { teamsTranscriptSource } from "./native-teams.js";
+import { meetTranscriptSource } from "./native-meet.js";
+import { zoomTranscriptSource } from "./native-zoom.js";
+
+export function registerNativeTranscriptSources(): void {
+  registerNativeTranscriptSource(teamsTranscriptSource());
+  registerNativeTranscriptSource(meetTranscriptSource());
+  registerNativeTranscriptSource(zoomTranscriptSource());
+}

package/agent/meetings/native-teams.ts

@@ -0,0 +1,119 @@
+// The Microsoft Teams native-transcript reader (OPE-2471): Microsoft Graph `callTranscript`, read app-only
+// with the organisation's Entra app registration (client credentials).
+//
+//   1. token:      POST login.microsoftonline.com/<tenant>/oauth2/v2.0/token (client_credentials, `.default`)
+//   2. meeting:    GET /users/<organiser>/onlineMeetings?$filter=JoinWebUrl eq '<link>'
+//   3. transcripts: GET /users/<organiser>/onlineMeetings/<id>/transcripts
+//   4. content:    GET …/transcripts/<id>/content?$format=text/vtt — WebVTT with `<v Speaker>` voice spans
+//
+// WHAT THE ADMIN GRANTS (docs/capabilities/meetings.md says it exactly): the application permissions
+// `OnlineMeetings.Read.All` and `OnlineMeetingTranscript.Read.All` with admin consent, and an application
+// access policy that covers the organisers (Graph refuses app-only meeting reads without one). A 403 at any
+// step is the `access-off` refusal: the grant, the policy, or the tenant's transcript switches are off.
+//
+// Graph names a transcript only after the meeting ends, so "no transcript yet" is `pending`, and the watch's
+// deadline turns a meeting that was never transcribed into a plain sentence in the thread.
+
+import type { NativeTranscriptResult, NativeTranscriptSource, NativeMeetingRef, NativeReadContext } from "@open-everywhere/core/agent/adapter-api.js";
+import { parseWebVtt } from "@open-everywhere/core/agent/adapter-api.js";
+import { TokenCache, onHost, readCappedText, readJsonLoose, unexpectedStatus, type NativeFetch, timedFetch } from "./native-http.js";
+
+const GRAPH = "https://graph.microsoft.com/v1.0";
+const LOGIN = "https://login.microsoftonline.com";
+const MAX_PAGES = 10;
+
+/** The fixed hint for a 403: what an admin grants. Never response text. */
+export const TEAMS_ACCESS_HINT =
+  "In Microsoft Entra, grant the app OnlineMeetings.Read.All and OnlineMeetingTranscript.Read.All (application, admin consent), and add an application access policy that covers the organiser (Grant-CsApplicationAccessPolicy). The Teams meeting policy must allow transcription.";
+
+interface Transcript {
+  readonly id: string;
+  readonly createdDateTime?: string;
+  readonly endDateTime?: string;
+}
+
+export function teamsTranscriptSource(fetchImpl: NativeFetch = timedFetch, now: () => number = Date.now): NativeTranscriptSource {
+  const tokens = new TokenCache();
+
+  async function token(tenant: string, clientId: string, secret: string): Promise<string | NativeTranscriptResult> {
+    const key = `${tenant}\n${clientId}`;
+    const cached = tokens.get(key, now());
+    if (cached !== undefined) return cached;
+    const res = await fetchImpl(`${LOGIN}/${encodeURIComponent(tenant)}/oauth2/v2.0/token`, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ client_id: clientId, client_secret: secret, scope: "https://graph.microsoft.com/.default", grant_type: "client_credentials" }).toString(),
+    });
+    const body = await readJsonLoose(res);
+    if (res.status === 400 || res.status === 401) return { status: "refused", reason: "credential", hint: "Microsoft Entra refused the app's client id or client secret." };
+    if (!res.ok || typeof body.access_token !== "string") throw unexpectedStatus("the Entra token endpoint", res.status);
+    tokens.set(key, body.access_token, body.expires_in, now());
+    return body.access_token;
+  }
+
+  /** One Graph GET. A refusal comes back as a result; anything unexpected throws (checked again later). */
+  async function graph(url: string, bearer: string, what: string, on404: NativeTranscriptResult): Promise<Response | NativeTranscriptResult> {
+    if (!onHost(url, "graph.microsoft.com")) throw new Error(`${what}: refusing to send the token off graph.microsoft.com`);
+    const res = await fetchImpl(url, { headers: { authorization: `Bearer ${bearer}` } });
+    if (res.status === 401) return { status: "refused", reason: "credential", hint: "Microsoft Graph refused the app's token." };
+    if (res.status === 403) return { status: "refused", reason: "access-off", hint: TEAMS_ACCESS_HINT };
+    if (res.status === 404) return on404;
+    if (!res.ok) throw unexpectedStatus(what, res.status);
+    return res;
+  }
+
+  return {
+    platform: "teams",
+    disclosure: "OE reads the transcript Microsoft Teams made, through Microsoft Graph, with the organisation's own Entra app registration (not any person's account).",
+    async read(ref: NativeMeetingRef, ctx: NativeReadContext): Promise<NativeTranscriptResult> {
+      const t = ctx.policy.teams;
+      if (t === undefined) return { status: "refused", reason: "credential", hint: "The meeting policy declares no Teams credential." };
+      if (ref.tenantId === undefined || ref.organizerId === undefined || !t.tenants.includes(ref.tenantId)) return { status: "refused", reason: "not-found" };
+      const tok = await token(ref.tenantId, t.clientId, await ctx.secret(t.clientSecretRef));
+      if (typeof tok !== "string") return tok;
+      const user = `${GRAPH}/users/${encodeURIComponent(ref.organizerId)}/onlineMeetings`;
+
+      const filter = `JoinWebUrl eq '${ref.url.replace(/'/g, "''")}'`;
+      const found = await graph(`${user}?$filter=${encodeURIComponent(filter)}`, tok, "the Graph meeting lookup", { status: "refused", reason: "not-found" });
+      if (!(found instanceof Response)) return found;
+      const meetings = (await readJsonLoose(found)).value;
+      const meetingId = Array.isArray(meetings) && typeof (meetings[0] as { id?: unknown } | undefined)?.id === "string" ? (meetings[0] as { id: string }).id : undefined;
+      if (meetingId === undefined) return { status: "refused", reason: "not-found" };
+
+      const transcripts: Transcript[] = [];
+      let next: string | undefined = `${user}/${encodeURIComponent(meetingId)}/transcripts`;
+      for (let page = 0; next !== undefined && page < MAX_PAGES; page++) {
+        const listed = await graph(next, tok, "the Graph transcript list", { status: "refused", reason: "not-found" });
+        if (!(listed instanceof Response)) return listed;
+        const body = await readJsonLoose(listed);
+        for (const v of Array.isArray(body.value) ? body.value : []) {
+          const o = v as Record<string, unknown>;
+          if (typeof o.id === "string") {
+            transcripts.push({
+              id: o.id,
+              ...(typeof o.createdDateTime === "string" ? { createdDateTime: o.createdDateTime } : {}),
+              ...(typeof o.endDateTime === "string" ? { endDateTime: o.endDateTime } : {}),
+            });
+          }
+        }
+        next = typeof body["@odata.nextLink"] === "string" ? body["@odata.nextLink"] : undefined;
+      }
+      // A recurring meeting keeps one join link, so its transcripts span every occurrence: newest first, and
+      // only a session that started inside the ask's window.
+      const eligible = transcripts
+        .filter((x) => ref.startedAfter === undefined || (x.createdDateTime !== undefined && Date.parse(x.createdDateTime) >= ref.startedAfter))
+        .sort((a, b) => Date.parse(b.createdDateTime ?? "") - Date.parse(a.createdDateTime ?? ""));
+      const pick = eligible[0];
+      // No transcript yet (the meeting has not ended), or one Teams is still writing.
+      if (pick === undefined || pick.endDateTime === undefined) return { status: "pending" };
+
+      const content = await graph(`${user}/${encodeURIComponent(meetingId)}/transcripts/${encodeURIComponent(pick.id)}/content?$format=text/vtt`, tok, "the Graph transcript content", {
+        status: "refused",
+        reason: "expired",
+      });
+      if (!(content instanceof Response)) return content;
+      const segments = parseWebVtt(await readCappedText(content));
+      return { status: "ready", segments, ...(pick.createdDateTime !== undefined ? { startedAt: pick.createdDateTime } : {}), endedAt: pick.endDateTime };
+    },
+  };
+}

package/agent/meetings/native-zoom.ts

@@ -0,0 +1,98 @@
+// The Zoom native-transcript reader (OPE-2471): the cloud recording's audio transcript, read with the
+// organisation's own Server-to-Server OAuth app.
+//
+//   1. token:      POST zoom.us/oauth/token?grant_type=account_credentials&account_id=<account> (Basic auth)
+//   2. recording:  GET api.zoom.us/v2/meetings/<meeting id>/recordings — the newest session's files
+//   3. transcript: the `TRANSCRIPT` file's `download_url`, with the token — WebVTT whose cues start
+//                  "Speaker Name: text"
+//
+// WHAT THE ADMIN GRANTS: a Server-to-Server OAuth app on the org's Zoom account with the scope
+// `cloud_recording:read:list_recording_files:admin` (classic scope: `recording:read:admin`), and, in the
+// account settings, cloud recording with "Create audio transcript" on. Zoom needs a paid plan for both.
+//
+// HOW READY IS LEARNED: Zoom has a `recording.transcript_completed` webhook, and it is reported unreliable;
+// OE polls this endpoint instead (meetings/native-recap.ts). Zoom writes the transcript after the recording,
+// so a recording without a transcript file is `pending` until a day after it ended, then `not-transcribed`.
+// The token goes only to zoom.us hosts: a `download_url` anywhere else is refused, never fetched.
+
+import type { NativeTranscriptResult, NativeTranscriptSource, NativeMeetingRef, NativeReadContext } from "@open-everywhere/core/agent/adapter-api.js";
+import { parseWebVtt } from "@open-everywhere/core/agent/adapter-api.js";
+import { TokenCache, onHost, readCappedText, readJsonLoose, unexpectedStatus, type NativeFetch, timedFetch } from "./native-http.js";
+
+const API = "https://api.zoom.us/v2";
+const TOKEN = "https://zoom.us/oauth/token";
+/** After this long with a finished recording and no transcript file, the transcript is not coming. */
+export const ZOOM_TRANSCRIPT_GRACE_MS = 24 * 60 * 60_000;
+
+export const ZOOM_ACCESS_HINT =
+  "In the Zoom App Marketplace, give the Server-to-Server OAuth app the scope cloud_recording:read:list_recording_files:admin (classic: recording:read:admin), and turn on cloud recording with Create audio transcript in the account settings.";
+
+interface RecordingFile {
+  readonly file_type?: string;
+  readonly status?: string;
+  readonly download_url?: string;
+  readonly recording_end?: string;
+}
+
+export function zoomTranscriptSource(fetchImpl: NativeFetch = timedFetch, now: () => number = Date.now): NativeTranscriptSource {
+  const tokens = new TokenCache();
+
+  async function token(accountId: string, clientId: string, secret: string): Promise<string | NativeTranscriptResult> {
+    const key = `${accountId}\n${clientId}`;
+    const cached = tokens.get(key, now());
+    if (cached !== undefined) return cached;
+    const res = await fetchImpl(`${TOKEN}?grant_type=account_credentials&account_id=${encodeURIComponent(accountId)}`, {
+      method: "POST",
+      headers: { authorization: `Basic ${Buffer.from(`${clientId}:${secret}`).toString("base64")}` },
+    });
+    const body = await readJsonLoose(res);
+    if (res.status === 400 || res.status === 401) return { status: "refused", reason: "credential", hint: "Zoom refused the Server-to-Server app's account id, client id or client secret." };
+    if (!res.ok || typeof body.access_token !== "string") throw unexpectedStatus("the Zoom token endpoint", res.status);
+    tokens.set(key, body.access_token, body.expires_in, now());
+    return body.access_token;
+  }
+
+  return {
+    platform: "zoom",
+    disclosure: "OE reads the audio transcript of the meeting's Zoom cloud recording, through the Zoom API, with the organisation's own Server-to-Server OAuth app (not any person's account).",
+    async read(ref: NativeMeetingRef, ctx: NativeReadContext): Promise<NativeTranscriptResult> {
+      const z = ctx.policy.zoom;
+      if (z === undefined) return { status: "refused", reason: "credential", hint: "The meeting policy declares no Zoom credential." };
+      const tok = await token(z.accountId, z.clientId, await ctx.secret(z.clientSecretRef));
+      if (typeof tok !== "string") return tok;
+
+      const res = await fetchImpl(`${API}/meetings/${encodeURIComponent(ref.roomId)}/recordings`, { headers: { authorization: `Bearer ${tok}` } });
+      const body = await readJsonLoose(res);
+      if (res.status === 401) return { status: "refused", reason: "credential", hint: "Zoom refused the app's token." };
+      if (res.status === 403) return { status: "refused", reason: "access-off", hint: ZOOM_ACCESS_HINT };
+      if (res.status === 404) {
+        // 3301 "This recording does not exist": no cloud recording yet (or never). 3001: no such meeting on this account.
+        if (body.code === 3001) return { status: "refused", reason: "not-found" };
+        return { status: "pending" };
+      }
+      // A missing scope can come back as a 400 (code 4711, "does not contain scopes") as well as a 403; code 200 is "no permission".
+      if (res.status === 400 && (body.code === 200 || body.code === 4711)) return { status: "refused", reason: "access-off", hint: ZOOM_ACCESS_HINT };
+      if (!res.ok) throw unexpectedStatus("the Zoom recordings endpoint", res.status);
+
+      const startedAt = typeof body.start_time === "string" ? body.start_time : undefined;
+      // A recurring meeting answers with its newest session: one from before the ask's window is not the meeting asked for.
+      if (ref.startedAfter !== undefined && (startedAt === undefined || Date.parse(startedAt) < ref.startedAfter)) return { status: "pending" };
+      const files = (Array.isArray(body.recording_files) ? body.recording_files : []) as RecordingFile[];
+      const transcript = files.find((f) => f.file_type === "TRANSCRIPT");
+      if (transcript === undefined || transcript.status !== "completed" || typeof transcript.download_url !== "string") {
+        const ends = files.map((f) => Date.parse(f.recording_end ?? "")).filter((t) => Number.isFinite(t));
+        const finished = files.length > 0 && files.every((f) => f.status === "completed") && ends.length > 0;
+        if (transcript === undefined && finished && now() - Math.max(...ends) > ZOOM_TRANSCRIPT_GRACE_MS) return { status: "refused", reason: "not-transcribed" };
+        return { status: "pending" };
+      }
+      if (!onHost(transcript.download_url, "zoom.us")) throw new Error("the Zoom transcript download_url is not on zoom.us, so the token is not sent there");
+      const dl = await fetchImpl(transcript.download_url, { headers: { authorization: `Bearer ${tok}` } });
+      if (dl.status === 404) return { status: "refused", reason: "expired" };
+      if (dl.status === 401 || dl.status === 403) return { status: "refused", reason: "access-off", hint: ZOOM_ACCESS_HINT };
+      if (!dl.ok) throw unexpectedStatus("the Zoom transcript download", dl.status);
+      const segments = parseWebVtt(await readCappedText(dl), { namePrefix: true });
+      const ends = files.map((f) => f.recording_end).filter((t): t is string => typeof t === "string").sort();
+      return { status: "ready", segments, ...(startedAt !== undefined ? { startedAt } : {}), ...(ends.length > 0 ? { endedAt: ends[ends.length - 1]! } : {}) };
+    },
+  };
+}

package/agent/model/gateway.ts

@@ -8,6 +8,7 @@ import {
   type ModelBackend,
   type RoutedCallOptions,
   hostPlaneFetch,
+  hostPlanePolicy,
   liveIdentity,
   resolvePrimaryModel,
 } from "@open-everywhere/core/agent/adapter-api.js";
@@ -33,13 +34,46 @@ export function gatewayHost(baseUrl: string | undefined): string {
   }
 }
 
+/** The one host this deployment's gateway calls reach — what every host-plane push must keep declaring. */
+export const GATEWAY_TARGET_HOST = gatewayHost(GATEWAY_BASE_URL);
+
+/**
+ * THE HOST-PLANE UNION (OPE-2470). The proxy REPLACES its host plane on every push; it never merges
+ * (deploy/egress-proxy/control/handlers.ts `setHostPlane`). So this process keeps ONE host set, and every
+ * host-plane call goes through ONE fetch that pushes the whole set: the turn model and the meeting bot's
+ * non-gateway transcription routes never push lists that drop each other. A caller adds its hosts with
+ * {@link sharedHostPlaneFetch} at boot; a grown set builds a new fetch, which pushes the union on its next call.
+ */
+const HOST_PLANE_HOSTS: string[] = [GATEWAY_TARGET_HOST];
+let hostPlaneCurrent = hostPlaneFetch(HOST_PLANE_HOSTS);
+let hostPlaneBuiltFor = HOST_PLANE_HOSTS.length;
 /**
  * THE MODEL CALL'S TRANSPORT ON THE SELF-HOST PROXY TIER (OPE-2406). With an egress proxy wired, the model call goes out
- * on the app's HOST PLANE: the proxy decides it against the gateway host alone, never against a session's policy. That is
- * what lets a turn reach its model while the session stays default-deny. Off that tier it is `undefined` and the provider
- * keeps its default fetch, byte-identical to before.
+ * on the app's HOST PLANE: the proxy decides it against the host-plane list (the gateway host, plus the hosts of any
+ * non-gateway transcription route the app registers), never against a session's policy. That is what lets a turn reach
+ * its model while the session stays default-deny. Off that tier it is `undefined` and the provider keeps its default
+ * fetch, byte-identical to before. On it, the fetch always uses the newest union.
  */
-const HOST_PLANE_FETCH = hostPlaneFetch([gatewayHost(GATEWAY_BASE_URL)]);
+const HOST_PLANE_FETCH: typeof fetch | undefined =
+  hostPlaneCurrent === undefined
+    ? undefined
+    : (input, init) => {
+        if (hostPlaneBuiltFor !== HOST_PLANE_HOSTS.length) {
+          hostPlaneCurrent = hostPlaneFetch(HOST_PLANE_HOSTS);
+          hostPlaneBuiltFor = HOST_PLANE_HOSTS.length;
+        }
+        return hostPlaneCurrent!(input, init);
+      };
+
+/** Add `hosts` to this process's host plane and return the shared fetch (undefined off the proxy tier). */
+export function sharedHostPlaneFetch(hosts: readonly string[]): typeof fetch | undefined {
+  // Validate BEFORE the list grows: a wildcard host throws here, at registration, and never reaches the shared list,
+  // where it would fail every model turn at the next rebuild. A blank name is skipped.
+  const named = hosts.map((h) => h.trim()).filter((h) => h !== "");
+  if (HOST_PLANE_FETCH !== undefined) hostPlanePolicy([...HOST_PLANE_HOSTS, ...named]);
+  for (const h of named) if (!HOST_PLANE_HOSTS.includes(h)) HOST_PLANE_HOSTS.push(h);
+  return HOST_PLANE_FETCH;
+}
 
 /** The gateway provider this backend resolves model ids through — retargeted only when
  *  {@link GATEWAY_BASE_URL} names a different host. */
@@ -86,6 +120,12 @@ export function applyGatewayOptions(
   return { ...options, providerOptions: { ...options.providerOptions, gateway: gatewayOpts } };
 }
 
+/** A gateway TRANSCRIPTION model, on the same provider (retarget and host-plane fetch included) the turn
+ *  model uses. The meeting bot's `gateway` route (meeting-gateway.ts) reads it. */
+export function gatewayTranscriptionModel(id: string): ReturnType<typeof provider.transcriptionModel> {
+  return provider.transcriptionModel(id);
+}
+
 /** The gateway ModelBackend (see core ModelBackend). */
 export function gatewayModelBackend(defaults?: Record<string, unknown>): ModelBackend<GatewayModel> {
   return {

package/agent/model/meeting-gateway.ts

@@ -0,0 +1,88 @@
+// The meeting bot's two model calls (OPE-2459): the `gateway` transcription route, and the recap completion.
+// Core owns both seams (meetings/transcription.ts); this file only fills them, so no meeting code calls a model SDK.
+//
+// TRANSCRIPTION (OPE-2470): one audio chunk per call, along the STACK'S TRANSCRIPTION ROLE — a primary route and a
+// fallback route (transcription-routes.ts), named per stack in the app's `agent/model/stacks.ts`. A provider outage
+// on the primary falls through to the fallback. The policy's route id stays `gateway` (core validates the id), but
+// the role decides where the audio goes, and the approval card's sentence is derived from the role. With a role
+// registered, the policy's `transcription.model` is NOT read.
+//
+// LEGACY: `registerGatewayMeetingModels(defaults)` with no role keeps the one-model route on the policy's
+// `transcription.model`, for an app that has no transcription role yet.
+//
+// RECAP: one tool-less completion on the scope's `utility` route — the same route and call shape the dream
+// judge uses. The prompt carries the fenced, untrusted transcript (core meetings/recap.ts).
+
+import { experimental_transcribe as transcribe, generateText, gateway } from "ai";
+import { registerMeetingCompletion, registerTranscriptionRoute, type MeetingCompletion, type TranscriptionInput, type TranscriptionRoute } from "@open-everywhere/core/agent/adapter-api.js";
+import { gatewayTranscriptionModel, type GatewayRoutedDefaults } from "./gateway.js";
+import { resolvedDreamCallSettings } from "./dream-judge.js";
+import { roleDisclosure, transcribeWithFallback, type RoleTranscript, type TranscriptionDeps, type TranscriptionRoleSpec } from "./transcription-routes.js";
+
+/** The injectable transcription call, so the legacy route is testable with no network. */
+export type TranscribeCall = (modelId: string, audio: Uint8Array, mediaType: string) => Promise<string>;
+
+// The SDK reads the container format from the bytes themselves, so the media type is not forwarded.
+const defaultTranscribe: TranscribeCall = async (modelId, audio) => {
+  const result = await transcribe({ model: gatewayTranscriptionModel(modelId), audio });
+  return result.text;
+};
+
+/** The legacy one-model route: the policy's `transcription.model` through the AI Gateway, with no fallback. */
+export function gatewayTranscriptionRoute(call: TranscribeCall = defaultTranscribe): TranscriptionRoute {
+  return {
+    id: "gateway",
+    disclosure: "Audio goes, one minute at a time, through this deployment's own AI Gateway to its transcription model.",
+    async transcribe(input, opts) {
+      if (input.kind !== "audio") throw new Error("the gateway transcription route transcribes audio — this bot sent text");
+      if (opts.model === undefined) throw new Error("the gateway transcription route needs transcription.model in the meeting policy");
+      return await call(opts.model, input.data, input.mediaType);
+    },
+  };
+}
+
+/**
+ * The stack route: the core seam's `transcribe` (text only), plus `transcribeTimed`, which keeps the word and segment
+ * timestamps for the speaker alignment (OPE-2469) and says which route answered.
+ */
+export interface TimedTranscriptionRoute extends TranscriptionRoute {
+  transcribeTimed(input: TranscriptionInput, opts: { readonly scope: string; readonly prompt?: string }): Promise<RoleTranscript>;
+}
+
+export function stackTranscriptionRoute(role: TranscriptionRoleSpec, deps: TranscriptionDeps = {}): TimedTranscriptionRoute {
+  const run = transcribeWithFallback(role, deps);
+  const timed: TimedTranscriptionRoute["transcribeTimed"] = async (input, opts) => {
+    if (input.kind !== "audio") throw new Error("the gateway transcription route transcribes audio — this bot sent text");
+    return await run({ audio: input.data, mediaType: input.mediaType, ...(opts.prompt !== undefined ? { prompt: opts.prompt } : {}) });
+  };
+  return {
+    id: "gateway",
+    disclosure: roleDisclosure(role),
+    transcribeTimed: timed,
+    async transcribe(input, opts) {
+      return (await timed(input, { scope: opts.scope })).text;
+    },
+  };
+}
+
+function gatewayMeetingCompletion(defaults: GatewayRoutedDefaults): MeetingCompletion {
+  return async (scope, prompt) => {
+    const s = resolvedDreamCallSettings(scope, defaults);
+    const { text } = await generateText({
+      model: gateway(s.id),
+      prompt,
+      ...(s.reasoning !== undefined ? { reasoning: s.reasoning } : {}),
+      ...(s.providerOptions !== undefined ? { providerOptions: s.providerOptions as Parameters<typeof generateText>[0]["providerOptions"] } : {}),
+    });
+    return text;
+  };
+}
+
+/**
+ * Boot registration from agent.ts, beside the dream judge: the recap rides the `utility` defaults, and the
+ * transcription route rides the stack's transcription role when the app passes one.
+ */
+export function registerGatewayMeetingModels(defaults: GatewayRoutedDefaults, transcription?: TranscriptionRoleSpec): void {
+  registerTranscriptionRoute(transcription === undefined ? gatewayTranscriptionRoute() : stackTranscriptionRoute(transcription));
+  registerMeetingCompletion(gatewayMeetingCompletion(defaults));
+}