@open-everywhere/provider-google-chat 0.0.0-stage → 0.8.0

package/agent/channels/google-chat.ts

@@ -0,0 +1,194 @@
+// The GOOGLE CHAT surface — the agent as a Google Chat app (OPE-2442). A custom `defineChannel` HTTP transport
+// (eve ships no Google Chat channel): `POST /eve/v1/google-chat` is the app's HTTP endpoint. The eve-free
+// orchestration is google-chat-front.ts; this file is the live wiring — the store, the config, and the two seat
+// dispatches.
+//
+// THE LOOP:
+//   POST /eve/v1/google-chat
+//     → handleGoogleChatRequest (google-chat-front.ts) holds the route's order, and a test pins it:
+//     → the surface SHIPS OFF: a disabled policy (or one with no audience) answers 503 before the body is read
+//     → the bearer token is verified against Google's keys and the policy's audience (fail closed: 401)
+//     → the body is read ONCE, capped (413), and the route acknowledges `{}` (no synchronous message) so a slow seat
+//       never makes Google time the event out; the rest runs in the background
+//     → parse, dedupe on the message name, route: a mention in a space diverts into the standing seat of the
+//       domain whose `reach` lists `google-chat/<workspace>/<space id>` — the same
+//       `divertInboundToUnifiedWindow` every chat surface's front door uses; the person's own DM with the app
+//       diverts into their DM seat (channels/dm-seat.ts)
+//     → the seat answers with `reply`, which the post arm (google-chat-post-arm.ts) sends into the same space
+//       and thread, as the app.
+//
+// Spend, the wake ingress row, provider-selection admission, rate-limit retry and the audit of the wake all ride
+// the shared divert. Nothing here re-implements them.
+
+import { auditErrorDetail } from "@open-everywhere/core/agent/adapter-api.js";
+import { defineChannel, POST, type RouteHandlerArgs } from "eve/channels";
+import {
+  appendAudit,
+  claimRuntimeRotation,
+  carryTailForward,
+  deploymentOrg,
+  divertInboundToUnifiedWindow,
+  divertToUnifiedWindow,
+  dmWindowRegistryKey,
+  getConfig,
+  getOperationalStore,
+  getOrCreateDmSeat,
+  grainUsesUnifiedWindow,
+  mintRotationToken,
+  mintWakeId,
+  receiptEventTime,
+  recordWakeTail,
+  resolveWakeTrustFromContext,
+  shouldRotate,
+  spreadVendorTs,
+  stampMintedRuntime,
+  supervisorGrainFor,
+  tailAuthorGrain,
+  touchDmSeat,
+  withEndsTurnFinalChannel,
+  type BindableContext,
+  type UnifiedWindowWake,
+  type WakeMessageInput,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { googleChatPolicy } from "../policy.js";
+import { handleGoogleChatRequest, renderGoogleChatWake, type GoogleChatFrontDeps, type GoogleChatWakePlan } from "./google-chat-front.js";
+
+const ROUTE = "/eve/v1/google-chat";
+/** How long a message name stays claimed — longer than Google's retry window. */
+const DEDUPE_TTL_MS = 24 * 60 * 60 * 1000;
+
+function log(msg: string): void {
+  console.log(`[open-everywhere:google-chat] ${msg}`);
+}
+
+function authContext(auth: { attributes?: Readonly<Record<string, string>>; principalId?: string }): BindableContext {
+  return { channel: { kind: "google-chat" }, session: { auth: { current: auth as never } } };
+}
+
+/** The tail row both seats file after the wake landed: the trigger only. */
+function tailRow(plan: GoogleChatWakePlan, atIso: string) {
+  return {
+    kind: "wake" as const,
+    at: atIso,
+    from: "human" as const,
+    trust: plan.trigger.trust,
+    ...tailAuthorGrain(plan.ingested[0] ?? { trust: plan.trigger.trust }),
+    author: plan.trigger.author,
+    authorId: plan.trigger.authorId ?? "",
+    id: plan.trigger.id,
+    platform: "google-chat",
+    container: plan.surfaceKey,
+    ...(plan.origin.thread !== undefined ? { threadRoot: plan.origin.thread } : {}),
+    text: plan.trigger.body,
+  };
+}
+
+/** The ROOM dispatch: the domain's standing seat, through the shared inbound divert. */
+async function liveDispatchRoom(plan: GoogleChatWakePlan, to: RouteHandlerArgs["to"]): Promise<void> {
+  const org = deploymentOrg();
+  const store = getOperationalStore();
+  const grain = supervisorGrainFor(plan.surfaceKey, getConfig().loadDomains());
+  const atIso = new Date().toISOString();
+  const perContainer = (gen: number): string => `google-chat:${plan.surfaceKey}:oe-sup:g${gen}`;
+  // OPE-599: claim the runtime-change rotation BEFORE the row read, and unconditionally.
+  const runtimeChanged = await claimRuntimeRotation({ org, registryKey: grain.registryKey, surfaceKey: plan.surfaceKey, domainName: grain.domainName, atIso });
+  const existing = await store.getChannelSession(org, grain.registryKey);
+  let token: string;
+  let tail: readonly WakeMessageInput[] = [];
+  if (!existing) {
+    const row = await store.rotateChannelSession(org, grain.registryKey, mintRotationToken(grain, 1, () => perContainer(1)), atIso);
+    await stampMintedRuntime({ org, registryKey: grain.registryKey, surfaceKey: plan.surfaceKey, domainName: grain.domainName, atIso });
+    token = row.token;
+  } else if (shouldRotate(existing, atIso, { runtimeChanged })) {
+    const gen = existing.generation + 1;
+    tail = await carryTailForward(org, grain.registryKey, existing.token);
+    token = (await store.rotateChannelSession(org, grain.registryKey, mintRotationToken(grain, gen, () => perContainer(gen)), atIso)).token;
+  } else {
+    token = existing.token;
+  }
+  const wakeId = mintWakeId();
+  const rendered = renderGoogleChatWake(plan, wakeId, tail);
+  const window: UnifiedWindowWake = { wakeId, origin: plan.origin, addressing: "direct-mention", ...spreadVendorTs(receiptEventTime(Date.now())) };
+  await divertInboundToUnifiedWindow(to, {
+    message: rendered.message,
+    ...(rendered.context.length > 0 ? { context: rendered.context } : {}),
+    token,
+    window,
+    surfaceKey: plan.surfaceKey,
+    auth: plan.auth as unknown as { attributes?: Record<string, unknown> },
+  });
+  await store.touchChannelSession(org, grain.registryKey, atIso).catch(() => undefined);
+  await recordWakeTail(org, grain.registryKey, token, tailRow(plan, atIso)).catch(() => undefined);
+}
+
+/** The DM dispatch: the person's own DM seat. */
+async function liveDispatchDm(plan: GoogleChatWakePlan, to: RouteHandlerArgs["to"]): Promise<void> {
+  const org = deploymentOrg();
+  const atIso = new Date().toISOString();
+  const seat = await getOrCreateDmSeat(org, { surfaceKey: plan.surfaceKey }, atIso);
+  const wakeId = mintWakeId();
+  const rendered = renderGoogleChatWake(plan, wakeId, seat.freshGeneration ? seat.tail : undefined);
+  await divertToUnifiedWindow(to, {
+    message: rendered.message,
+    ...(rendered.context.length > 0 ? { context: rendered.context } : {}),
+    token: seat.token,
+    window: { wakeId, origin: plan.origin, addressing: "direct-mention", ...spreadVendorTs(receiptEventTime(Date.now())) },
+    // Byte-exactly the surface named inside the DM token — the privacy fence both admission gates match on.
+    surfaceKey: plan.surfaceKey,
+    auth: plan.auth as unknown as { attributes?: Record<string, unknown> },
+  });
+  await touchDmSeat(org, plan.surfaceKey, atIso).catch(() => undefined);
+  await recordWakeTail(org, dmWindowRegistryKey(plan.surfaceKey), seat.token, tailRow(plan, atIso)).catch(() => undefined);
+}
+
+/** The live front deps over this request's `to`. */
+function liveGoogleChatFrontDeps(to: RouteHandlerArgs["to"]): GoogleChatFrontDeps {
+  return {
+    policy: googleChatPolicy,
+    markSeen: (key) => getOperationalStore().markEventSeen(deploymentOrg(), key, new Date().toISOString(), DEDUPE_TTL_MS),
+    roomHasSeat: (surfaceKey) => {
+      try {
+        return grainUsesUnifiedWindow(supervisorGrainFor(surfaceKey, getConfig().loadDomains()));
+      } catch {
+        return false;
+      }
+    },
+    wakeTrust: (auth, sender) => resolveWakeTrustFromContext(authContext(auth), { id: sender, isBot: false }, { principalFallback: true }),
+    dispatchRoom: (plan) => liveDispatchRoom(plan, to),
+    dispatchDm: (plan) => liveDispatchDm(plan, to),
+    audit: (row) =>
+      appendAudit({
+        org: deploymentOrg(),
+        platform: "google-chat",
+        workspace: row.workspace,
+        ...(row.surface ? { surface: row.surface } : {}),
+        ...(row.principalId ? { principalId: row.principalId } : {}),
+        action: row.action,
+        detail: row.detail,
+      }).catch(() => undefined),
+  };
+}
+
+const channel = defineChannel({
+  routes: [
+    POST(ROUTE, (req, { to, waitUntil }) =>
+      handleGoogleChatRequest(req, waitUntil, liveGoogleChatFrontDeps(to), {
+        log,
+        // The event was acknowledged and its name claimed, so a retry is a duplicate: this row is the only trace
+        // of the lost message. The error class only: an error message can carry message content.
+        onFailure: (err, policy) =>
+          appendAudit({
+            org: deploymentOrg(),
+            platform: "google-chat",
+            workspace: policy.workspace,
+            action: "google-chat.wake_failed",
+            detail: { error: auditErrorDetail(err instanceof Error ? err.name : "error").error },
+          })
+            .then(() => undefined)
+            .catch(() => undefined),
+      }),
+    ),
+  ],
+});
+
+export default withEndsTurnFinalChannel(channel);

package/agent/contributions.ts

@@ -0,0 +1,16 @@
+// THE CONTRIBUTION MANIFEST for `@open-everywhere/provider-google-chat` (OPE-2442) — the curated catalogue of
+// everything this package OFFERS an app's eve slot tree. `oe build` reads it; the app's `roster.config.ts` decides
+// about it, and `roster.lock.json` records the review. See packages/providers/github/agent/contributions.ts for why
+// the manifest is curated, import-free data.
+//
+// ERASABLE SYNTAX ONLY (no `enum`, no `namespace`) — `oe build` loads this with a bare import.
+
+export const CONTRIBUTIONS = {
+  schemaVersion: 1,
+  package: "@open-everywhere/provider-google-chat",
+  register: "agent/register.js#registerGoogleChatProvider",
+  contributions: [
+    // ── channels ─────────────────────────────────────────────────────────────────────────────────
+    { kind: "channel", name: "google-chat", module: "agent/channels/google-chat.js", summary: "Google Chat — the agent as a Chat app: @mentions in spaces and direct messages in, threaded replies out." },
+  ],
+} as const;

package/agent/docs-generated.ts

@@ -0,0 +1,120 @@
+// GENERATED by `npx tsx scripts/docs-generate.ts` from docs/deploy/surfaces/google-chat.md — DO NOT HAND-EDIT.
+// Edit the markdown under docs/ and re-run the generator; `npm run lint:docs` fails the
+// build if this file and its sources ever disagree. See scripts/docs-generate.ts for why the
+// manual is compiled in at all (docs/ does not exist on disk in a hosted deployment).
+
+import type { DocEntry } from "@open-everywhere/core/agent/adapter-api.js";
+
+export const PROVIDER_DOCS: readonly DocEntry[] = [
+  {
+    title: "Google Chat",
+    path: "docs/deploy/surfaces/google-chat.md",
+    summary: "Put the agent in Google Chat as a Chat app. People @mention it in a space or send it a direct message, and it answers in the same thread. Google Chat reaches the same two chiefs of staff as every other chat surface:",
+    markdown: [
+      "# Google Chat",
+      "",
+      "Put the agent in Google Chat as a Chat app. People @mention it in a space or send it a direct message, and it",
+      "answers in the same thread. Google Chat reaches the same two chiefs of staff as every other chat surface:",
+      "",
+      "- A **space** belongs to a domain. An @mention of the app in a space wakes that domain's standing seat, exactly as a",
+      "  message in one of the domain's Slack or Teams channels would.",
+      "- A **direct message** with the app wakes the person's own DM seat.",
+      "",
+      "Google Chat is the surface for an organisation that runs Google Workspace. It ships **off**: until a policy enables",
+      "it, the endpoint answers every delivery with `503`.",
+      "",
+      "## What it does and does not do",
+      "",
+      "- **Every event is verified before it is read.** Google Chat sends each event with a bearer token. The route checks",
+      "  the token's signature against Google's published keys, its issuer, its expiry, and its audience against the",
+      "  policy's `audience`. A token for any other audience, or (in endpoint-URL mode) from any Google account other than",
+      "  `chat@system.gserviceaccount.com`, is refused `401` and writes no audit row.",
+      "- **Addressed only.** The HTTP endpoint gets a space message only when it @-mentions the app, or invokes one of its",
+      "  slash commands. The surface has no ambient leg: room chatter never reaches it. (A Workspace Events subscription",
+      "  would deliver the rest; this surface does not use one yet.)",
+      "- **Trust comes from the policy, never from a name.** A sender binds `internal` only when Google's event names a",
+      "  Workspace domain id (`sender.domainId`) that the policy lists in `internalDomainIds`. Everyone else binds",
+      "  `external`: shared memory routes to the read-only `public` layer, and the turn is marked as carrying a",
+      "  non-member's words. ⚠ The mapping from your Workspace to its domain id is not documented as stable by Google.",
+      "  Read the id from a real event: every `google-chat.admitted` and `google-chat.refused` audit row records the",
+      "  sender's `domainId`. A DM-only deployment can start with an empty list: the first internal person's DM is refused",
+      "  `external-dm`, and its refused row carries their domain id.",
+      "- **Direct messages are for internal people only.** A DM seat reads its person's private layer, so a DM from an",
+      "  `external` sender is refused (`external-dm`). Set `directMessages: false` to refuse every DM (`dm-off`).",
+      "- **Group chats are refused** (`group-chat`). A group chat has no domain to own it and is not one person's DM.",
+      "- **A space with no seat is refused**, not dropped in silence (`no-domain`): put its surface key in a domain's",
+      "  `reach`, or run a standing-seat window that gives an undeclared space its own solo seat.",
+      "- **Bots never wake a seat.** A message from any bot, the app's own included, is dropped. That is the loop guard.",
+      "- **Replies only, into the conversation that woke the seat.** The reply posts into the trigger's space and thread,",
+      "  as the app. The space and thread are frozen at the gate from the verified event; the model never names one. The",
+      "  app can post only into a space it is a member of. A reply longer than one Chat message goes out as consecutive",
+      "  messages in the same thread.",
+      "",
+      "## How it fits the planes",
+      "",
+      "| Plane | What Google Chat uses |",
+      "|---|---|",
+      "| Surface | The `google-chat` provider bundle (`packages/providers/google-chat`): identity mapper, capability manifest, post arm, wake-origin codec, host-notice transport. A space's surface key is `google-chat/<workspace>/<space id>` and goes in a domain's `reach` like any channel. |",
+      "| Seat | A space mention diverts into the domain's standing seat through the same `divertInboundToUnifiedWindow` every chat surface uses; a DM diverts into the person's DM seat (`channels/dm-seat.ts`). Spend caps, the wake ingress row, provider selection and rate-limit retry ride the shared divert. |",
+      "| Identity | The principal is the sender's Chat user resource name (`users/<id>`). The workspace is the policy's `workspace` segment. Visibility is always `private`. |",
+      "| Audit | `google-chat.admitted` (space, seat kind, trust, the sender's domain id, whether it was a thread reply), `google-chat.refused` (the reason and the sender's domain id), and `google-chat.wake_failed`. The reply itself writes the shared `reply.post` row. |",
+      "| Egress | The reply and a host notice (an approval outcome note, the judge-lift notice) are the only outbound calls, to `chat.googleapis.com`, with a `chat.bot` token minted from the app's service-account key at `oauth2.googleapis.com`. The token endpoint is pinned: the key file's own `token_uri` is ignored. |",
+      "",
+      "## What an operator must provision",
+      "",
+      "Nothing below is created by Open Everywhere.",
+      "",
+      "1. **A Google Cloud project** with the Google Chat API enabled.",
+      "2. **A service account** in that project, and a JSON key for it. The app posts its replies as this account.",
+      "3. **The Chat app configuration** (Google Chat API → Configuration): give the app a name and avatar, turn on",
+      "   \"Receive 1:1 messages\" and \"Join spaces and group conversations\", choose **HTTP endpoint URL** as the connection",
+      "   setting, and set it to `https://<your deployment host>/eve/v1/google-chat`. Choose the **Authentication audience**:",
+      "   \"HTTP endpoint URL\" (recommended) or \"Project number\". Make the app visible to the people or groups who should",
+      "   use it.",
+      "4. **The secret**, in the secret store, never in a file or the environment of a commit:",
+      "   ```sh",
+      "   npx oe secret set GOOGLE_CHAT_SERVICE_ACCOUNT_KEY   # the service account's JSON key, whole",
+      "   ```",
+      "   (The resolver falls back to an environment variable of the same name, and warns when it does.)",
+      "5. **The policy**, in `agent/google-chat/policy.ts`, by pull request: set `enabled: true`, the `audience` that",
+      "   matches step 3 (`{ kind: \"endpoint-url\", url: \"https://<host>/eve/v1/google-chat\" }` or",
+      "   `{ kind: \"project-number\", projectNumber: \"<number>\" }`), your `workspace` segment, and your",
+      "   `internalDomainIds`.",
+      "6. **The seats.** For each space, add its surface key (`google-chat/<workspace>/<space id>`, the id after",
+      "   `spaces/` in the space's URL) to the owning domain's `reach` in `agent/memory/config/domains/`. A multi-source",
+      "   window requires every source vouched, so also declare the space in `agent/identity/surfaces.ts`. 🔴 The vouch",
+      "   does **not** make an outside sender internal: the mapper states each message's trust itself, from the policy.",
+      "7. **Add the app** to each space (`@<app name>` → Add).",
+      "",
+      "## Settings",
+      "",
+      "| Field | Meaning |",
+      "|---|---|",
+      "| `enabled` | The master switch. Off answers `503` to every delivery and refuses every reply. |",
+      "| `audience` | The audience every event's token must carry. `null` refuses every delivery; an enabled policy without one fails the boot. |",
+      "| `workspace` | The workspace segment of every surface key (lowercase, `a-z`, `0-9`, `-`). |",
+      "| `internalDomainIds` | The Workspace domain ids whose people bind `internal`. Empty: everybody binds `external`. |",
+      "| `directMessages` | May an internal person wake their own DM seat? |",
+      "",
+      "## What is not built yet",
+      "",
+      "- **Cards**: an approval asked from Google Chat takes the venue walk to a card-capable room in the same domain. A",
+      "  Chat card with a button needs the `CARD_CLICKED` tap answered.",
+      "- **Reading a space** (`read_channel`, `read_thread`) and a seat catch-up: listing a space's messages needs user",
+      "  authentication or the admin-approved `chat.app.messages.readonly` app scope, which the app does not request.",
+      "- **Ambient messages, name-drops and edits**: they need a Workspace Events subscription.",
+      "- **Edit, reactions, stop, files, proactive posts and routines.** Each is declared, with its reason, in the",
+      "  [chat-surface contract](../../extending/chat-surface-contract.md)'s parity tables.",
+      "- **The Workspace add-on event format.** The route reads the classic Chat app event; an app built as a Google",
+      "  Workspace add-on wraps its events differently and is not supported.",
+      "",
+      "## Verification",
+      "",
+      "The unit packs (`test:google-chat-auth`, `test:google-chat-front`, `test:google-chat-post-arm`) and the app-level",
+      "`test:google-chat-integration` drive the token check, the gate, the reply and the binding offline. There is no",
+      "live e2e leg yet: one needs a Google Workspace test tenant with the app published to it, a fixture this repository",
+      "cannot create.",
+      "",
+    ].join("\n"),
+  },
+];

package/agent/policy.ts

@@ -0,0 +1,101 @@
+// THE GOOGLE CHAT POLICY (OPE-2442) — the schema, its validation and the registry. The app's own
+// `agent/google-chat/policy.ts` declares the values and calls `registerGoogleChatPolicy` at boot (through
+// `agent/lib/register-config.ts`), so every change is a reviewed pull request.
+//
+// 🔴 THE SURFACE SHIPS OFF. `DEFAULT_GOOGLE_CHAT_POLICY.enabled` is false, and the route answers 503 to every
+// delivery until a policy enables it AND names the audience Google signs each event for. An external ingress
+// that nobody configured must not be reachable.
+//
+// 🔴 TRUST IS TYPED CODE, NEVER AN ENVIRONMENT VARIABLE. `internalDomainIds` is the list of Google Workspace
+// domain ids whose people bind `internal`; it is a trust declaration, so it lives here and changes by pull
+// request. Nothing here is a secret: the app's service-account key lives in the secret store
+// (`npx oe secret set GOOGLE_CHAT_SERVICE_ACCOUNT_KEY`).
+
+/** Which audience Google Chat puts in the bearer token of each event — the app's "Authentication audience"
+ *  setting in the Google Cloud console. */
+export type GoogleChatAudience =
+  /** "Project number": the token is self-signed by `chat@system.gserviceaccount.com` for the project number. */
+  | { readonly kind: "project-number"; readonly projectNumber: string }
+  /** "HTTP endpoint URL": the token is a Google OIDC id token for the exact endpoint URL. */
+  | { readonly kind: "endpoint-url"; readonly url: string };
+
+export interface GoogleChatPolicy {
+  /** The master switch. Off answers 503 to every delivery and refuses every reply. */
+  readonly enabled: boolean;
+  /** The audience every event's token must carry. Null refuses every delivery (fail closed). */
+  readonly audience: GoogleChatAudience | null;
+  /** The workspace segment of every Google Chat surface key (`google-chat/<workspace>/<space id>`). */
+  readonly workspace: string;
+  /**
+   * The Google Workspace domain ids (`sender.domainId` on a Chat event) whose people bind `internal`. Everyone
+   * else binds `external`. Empty: everybody binds external.
+   */
+  readonly internalDomainIds: readonly string[];
+  /** May a person wake their own DM seat by messaging the app directly? An `external` person never can. */
+  readonly directMessages: boolean;
+}
+
+export const DEFAULT_GOOGLE_CHAT_POLICY: GoogleChatPolicy = {
+  enabled: false,
+  audience: null,
+  workspace: "workspace",
+  internalDomainIds: [],
+  directMessages: true,
+};
+
+const WORKSPACE_SEGMENT = /^[a-z0-9][a-z0-9-]{0,62}$/u;
+const PROJECT_NUMBER = /^[0-9]{1,20}$/u;
+const DOMAIN_ID = /^[A-Za-z0-9_-]{1,64}$/u;
+
+/** Every problem with `policy`, or empty when it is valid. Pure. */
+export function validateGoogleChatPolicy(policy: GoogleChatPolicy): readonly string[] {
+  const problems: string[] = [];
+  if (!WORKSPACE_SEGMENT.test(policy.workspace)) {
+    problems.push(`workspace "${policy.workspace}" must be a lowercase segment (a-z, 0-9, "-"), at most 63 characters.`);
+  }
+  for (const id of policy.internalDomainIds) {
+    if (!DOMAIN_ID.test(id)) problems.push(`internalDomainIds entry "${id}" is not a Google Workspace domain id.`);
+  }
+  const a = policy.audience;
+  if (a !== null) {
+    if (a.kind === "project-number") {
+      if (!PROJECT_NUMBER.test(a.projectNumber)) problems.push("audience.projectNumber must be the numeric Google Cloud project number.");
+    } else if (a.kind === "endpoint-url") {
+      let url: URL | undefined;
+      try {
+        url = new URL(a.url);
+      } catch {
+        url = undefined;
+      }
+      if (url?.protocol !== "https:") problems.push("audience.url must be the app's https endpoint URL.");
+    } else {
+      problems.push(`audience.kind must be "project-number" or "endpoint-url".`);
+    }
+  }
+  if (policy.enabled && a === null) problems.push("an enabled policy must name its audience — without it no event can be verified.");
+  return problems;
+}
+
+let registered: GoogleChatPolicy = DEFAULT_GOOGLE_CHAT_POLICY;
+
+/** Register this deployment's policy. Throws on an invalid policy, so a bad file fails the boot. */
+export function registerGoogleChatPolicy(policy: GoogleChatPolicy): void {
+  const problems = validateGoogleChatPolicy(policy);
+  if (problems.length > 0) throw new Error(`agent/google-chat/policy.ts is invalid:\n  - ${problems.join("\n  - ")}`);
+  registered = policy;
+}
+
+/** The registered policy (the shipped default — off — until the app registers one). */
+export function googleChatPolicy(): GoogleChatPolicy {
+  return registered;
+}
+
+/** The surface key of one space: `google-chat/<workspace>/<space id>`. */
+export function googleChatSurfaceKey(policy: GoogleChatPolicy, space: string): string {
+  return `google-chat/${policy.workspace}/${spaceId(space)}`;
+}
+
+/** The id after `spaces/`. */
+function spaceId(space: string): string {
+  return space.slice(space.indexOf("/") + 1);
+}

package/agent/provider-events.ts

@@ -0,0 +1,18 @@
+// GOOGLE CHAT's event inventory (OPE-2442). See the core module's header
+// (packages/core/agent/routines/provider-events.ts) for what the three routing states mean.
+//
+// 🔴 THE GOOGLE CHAT BUNDLE REGISTERS NO EVENT NORMALIZER, so every row is `routing: "none"` and the declaration
+// names no `source`. A message event is CONVERSATION — it wakes a seat through the surface's gate — and a routine
+// subscribed to raw Chat events would bypass that gate.
+
+import type { ProviderEventDeclaration } from "@open-everywhere/core/agent/adapter-api.js";
+
+export const GOOGLE_CHAT_PROVIDER_EVENTS: ProviderEventDeclaration = {
+  doc: "https://developers.google.com/workspace/chat/receive-respond-interactions",
+  events: [
+    { event: "MESSAGE", routing: "none", match: [], scope: [], note: "an @mention in a space or a direct message — the front's conversation leg, through the gate, never a routine" },
+    { event: "ADDED_TO_SPACE", routing: "none", match: [], scope: [], note: "the app was added to a space — acknowledged and dropped; a space wakes nothing until a domain's `reach` lists it" },
+    { event: "REMOVED_FROM_SPACE", routing: "none", match: [], scope: [], note: "the app was removed from a space — acknowledged and dropped" },
+    { event: "CARD_CLICKED", routing: "none", match: [], scope: [], note: "a card button tap — acknowledged and dropped; the surface posts no card yet" },
+  ],
+};

package/agent/register.ts

@@ -0,0 +1,48 @@
+// registerGoogleChatProvider — the ONE boot entry of @open-everywhere/provider-google-chat (OPE-2442). The app's
+// generated selection table imports it STATICALLY and `registerDefaultAdapters()` calls it once at boot; every
+// seam the bundle implements registers here and nowhere else.
+//
+// What Google Chat registers (and what it deliberately does NOT):
+//   • identity mapper     — bindGoogleChat (channels/google-chat-identity.ts)
+//   • capability manifest — { midTurnPost: true, reactions: false, closingProseDropped: true }: `reply` is the
+//                           wired verb (the unified dispatch through the post arm), the app sets no reactions,
+//                           and a seat's turn-final text is dropped, so `reply` is the only way out
+//   • post arm            — googleChatPostArm: the reply, into the trigger's space and thread
+//   • wake-origin codec   — the stored-data google-chat arm (channels/google-chat-origin-codec.ts)
+//   • surface message ops — googleChatMessageOps: a host notice is one more message in the space
+//   • credential probe    — "configured" = the policy is enabled (no environment read)
+//   • NO read adapter (the app cannot list a space's messages), NO card poster, NO reaction surface, NO routine
+//     dispatch — each is declared, with its reason, in surface-parity.ts.
+
+import {
+  registerCapabilityManifest,
+  registerIdentityMapper,
+  registerPostArm,
+  registerProviderDocs,
+  registerProviderEvents,
+  registerSurfaceCredentialProbe,
+  registerSurfaceMessageOps,
+  registerSurfaceParity,
+  registerWakeOriginCodec,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { PROVIDER_DOCS } from "./docs-generated.js";
+import { GOOGLE_CHAT_SURFACE_PARITY } from "./surface-parity.js";
+import { GOOGLE_CHAT_PROVIDER_EVENTS } from "./provider-events.js";
+import { googleChatPolicy } from "./policy.js";
+import { bindGoogleChat } from "./channels/google-chat-identity.js";
+import { googleChatPostArm } from "./channels/google-chat-post-arm.js";
+import { googleChatWakeOriginCodec } from "./channels/google-chat-origin-codec.js";
+import { googleChatMessageOps } from "./channels/google-chat-message-ops.js";
+
+/** Perform ALL of the Google Chat bundle's registrations. Idempotent (each register call replaces). */
+export function registerGoogleChatProvider(): void {
+  registerIdentityMapper("google-chat", bindGoogleChat);
+  registerCapabilityManifest("google-chat", { midTurnPost: true, reactions: false, closingProseDropped: true });
+  registerSurfaceParity("google-chat", GOOGLE_CHAT_SURFACE_PARITY);
+  registerProviderEvents("google-chat", GOOGLE_CHAT_PROVIDER_EVENTS);
+  registerPostArm(googleChatPostArm);
+  registerWakeOriginCodec("google-chat", googleChatWakeOriginCodec);
+  registerSurfaceMessageOps(googleChatMessageOps);
+  registerSurfaceCredentialProbe("google-chat", () => googleChatPolicy().enabled);
+  registerProviderDocs("google-chat", PROVIDER_DOCS);
+}

package/agent/surface-parity.ts

@@ -0,0 +1,64 @@
+// GOOGLE CHAT's surface-parity declaration (OPE-2442). See the core module's header
+// (packages/core/agent/identity/surface-parity.ts) for what the three cell shapes mean.
+//
+// The first cut is the addressed path: an @mention in a space or a direct message wakes a seat, and the seat
+// answers in the same thread. Google Chat's HTTP endpoint delivers a space message only when it @-mentions the
+// app. Ambient messages, edits and space reads need a Workspace Events subscription or the admin-approved
+// `chat.app.messages.readonly` scope, which this cut does not request. So every vendor-side gap below is "not
+// built yet": none of them is a platform limit. Two kinds of row are not gaps: `mpim` is a policy refusal (a group
+// chat has no domain to own it and is not one person's DM), and `search`, `origin-placement-carry`,
+// `engaged-row-promotion` and `seat-context-admission` do not apply to this surface by design.
+
+import type { SurfaceParityDeclaration } from "@open-everywhere/core/agent/adapter-api.js";
+
+export const GOOGLE_CHAT_SURFACE_PARITY: SurfaceParityDeclaration = {
+  // --- registration seams (§7.1) ---------------------------------------------------------------
+  "identity-mapper": "supported",
+  "capability-manifest": "supported",
+  "post-arm": "supported",
+  "wake-origin-codec": "supported",
+  "origin-placement-carry": {
+    unsupported: "the placement is INSIDE the conversation identity: `threadRef` keys on the thread name, the very thread a reply posts into, so two origins of one conversation already agree on placement",
+  },
+  "read-adapter": { unsupported: "not built yet — listing a space's messages needs user authentication or the admin-approved `chat.app.messages.readonly` app scope, which the app does not request" },
+  "reaction-feedback-ingest": { unsupported: "not built yet — the HTTP endpoint carries no reaction event; a Workspace Events subscription would" },
+  "ancillary-ops": { supported: "text only — a host notice is one more message in the space; no edit, file or reaction" },
+  "ambient-engagement-seam": { unsupported: "not built yet — the HTTP endpoint delivers a space message only on an @mention; a Workspace Events subscription would deliver the rest" },
+  "engaged-row-promotion": { unsupported: "no ambient leg — every Google Chat wake is addressed (`direct-mention`)" },
+  "owned-thread-ingress": { supported: "the space leg takes the inbound divert; only a reply inside an existing thread (`threadReply`) is thread-scoped" },
+  "thread-done-reaction": { unsupported: "not built yet — the app sets no reactions (no `setReaction` in the ancillary ops)" },
+
+  // --- wake legs and conversation shapes -------------------------------------------------------
+  "addressed-leg": "supported",
+  "ambient-leg": { unsupported: "not built yet — the HTTP endpoint delivers a space message only on an @mention; a Workspace Events subscription would deliver the rest" },
+  "seat-catch-up": { unsupported: "not built yet — the app does not list a space's messages (see the read adapter row)" },
+  "seat-context-admission": { unsupported: "the wake fills no context-line slot — the seat reads only the addressed message and its carried tail" },
+  "approval-card": {
+    unsupported: "not built yet — a Chat card with a button needs the CARD_CLICKED tap answered; a governed act asked from Google Chat takes the venue walk to a card-capable room in the same domain",
+  },
+  "judge-lift-notice": { supported: "the shared text render, posted into the space — no button yet, so the overrule is spelled out in words" },
+  "out-of-office-cover": { unsupported: "not built yet — the space route does not call `coverForWake`, and the surface takes no ambient messages" },
+  "name-drop-mention": { unsupported: "not built yet — a message that names the app without an @mention never reaches the HTTP endpoint; a Workspace Events subscription would deliver it" },
+  "message-edit-wake": { unsupported: "not built yet — the HTTP endpoint sends no event for an edited message; a Workspace Events subscription would" },
+  threads: { supported: "a reply posts into the trigger's own thread (`REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD`)" },
+  rooms: { supported: "a space is a surface a domain's `reach` lists (`google-chat/<workspace>/<space id>`)" },
+  dm: { supported: "the person's own direct message with the app wakes their DM seat — internal people only" },
+  mpim: { unsupported: "policy: a group chat is refused (`group-chat`) — it has no domain to own it and is not one person's DM" },
+
+  // --- core verbs (§7.2) -----------------------------------------------------------------------
+  reply: "supported",
+  edit_reply: { unsupported: "not built yet — the arm registers no edit; Chat's `messages.patch` would carry one" },
+  react: { unsupported: "not built yet — no outbound reaction transport is wired" },
+  no_reply: "supported",
+  read_channel: { unsupported: "not built yet — listing a space's messages needs user authentication or the admin-approved `chat.app.messages.readonly` app scope, which the app does not request" },
+  read_thread: { unsupported: "not built yet — the same message-list scope as `read_channel`" },
+  search: { unsupported: "no work-search adapter — Google Chat is a chat surface, not a work corpus" },
+  post_message: { unsupported: "not built yet — no routine dispatch is registered, so the agent answers only in a conversation somebody started" },
+  dm_person: { unsupported: "not built yet — the app cannot open a DM a person did not start" },
+  set_dm_delivery: { unsupported: "not built yet — a Google Chat DM is never a proactive delivery channel" },
+  stop: { unsupported: "not built yet — the app reads no reactions, so there is no stop trigger" },
+  ack_stop_glyph: { unsupported: "not built yet — the app sets no reactions" },
+  ack_cancel_note: { supported: "a message in the space, through the host-notice transport" },
+  stand_down: { unsupported: "not built yet — remove the app from the space instead" },
+  post_file: { unsupported: "not built yet — the reply carries text only" },
+};

package/dist/agent/channels/google-chat-auth.d.ts

@@ -0,0 +1,39 @@
+import { type JWTVerifyGetKey } from "jose";
+import type { GoogleChatAudience } from "../policy.js";
+/** The service account Google Chat signs its events as. */
+export declare const CHAT_ISSUER_ACCOUNT = "chat@system.gserviceaccount.com";
+export type GoogleChatTokenVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface GoogleChatVerifyDeps {
+    /** The key resolvers, injectable so a test signs with its own key. Live default: Google's JWKS. */
+    readonly chatSystemKeys?: JWTVerifyGetKey;
+    readonly googleOidcKeys?: JWTVerifyGetKey;
+}
+/**
+ * Verify one event's bearer token against the policy's audience. Fail closed: no header, a malformed token,
+ * a bad signature, a wrong issuer or audience, an expired token, or (endpoint-URL mode) a token for any
+ * account but Google Chat's own is refused.
+ */
+export declare function verifyGoogleChatToken(authorization: string | undefined, audience: GoogleChatAudience | null, deps?: GoogleChatVerifyDeps): Promise<GoogleChatTokenVerdict>;
+interface ServiceAccountKey {
+    readonly clientEmail: string;
+    readonly privateKey: string;
+}
+/** Parse the key JSON. Throws a key-free error on anything that is not a service-account key. */
+export declare function parseServiceAccountKey(raw: string): ServiceAccountKey;
+export interface GoogleChatTokenDeps {
+    readonly fetch?: typeof fetch;
+    /** The raw key JSON. Live default: the operator secret store. */
+    readonly serviceAccountKey?: () => Promise<string>;
+    readonly now?: () => number;
+}
+/** Forget the cached access token (tests). */
+export declare function resetGoogleChatTokenCache(): void;
+/** A `chat.bot` access token for the app's service account, cached until a minute before it expires. */
+export declare function googleChatAccessToken(deps?: GoogleChatTokenDeps): Promise<string>;
+export {};
+//# sourceMappingURL=google-chat-auth.d.ts.map

package/dist/agent/channels/google-chat-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-chat-auth.d.ts","sourceRoot":"","sources":["../../../agent/channels/google-chat-auth.ts"],"names":[],"mappings":"AAYA,OAAO,EAAuD,KAAK,eAAe,EAAE,MAAM,MAAM,CAAC;AAEjG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,oCAAoC,CAAC;AAarE,MAAM,MAAM,sBAAsB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7G,MAAM,WAAW,oBAAoB;IACnC,mGAAmG;IACnG,QAAQ,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,cAAc,CAAC,EAAE,eAAe,CAAC;CAC3C;AAUD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,EACnC,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,sBAAsB,CAAC,CAqBjC;AAID,UAAU,iBAAiB;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,iGAAiG;AACjG,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAYrE;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAID,8CAA8C;AAC9C,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,wGAAwG;AACxG,wBAAsB,qBAAqB,CAAC,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B3F"}