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

package/agent/channels/google-chat-front.ts

@@ -0,0 +1,337 @@
+// google-chat-front — the eve-free core of the Google Chat surface's inbound path. One delivery in, one outcome
+// out: not configured, unauthorized, acknowledged and ignored, a duplicate, refused (audited, no model turn), or
+// admitted and delivered into a seat. The live wiring (google-chat.ts) supplies the store, the config and the two
+// seat dispatches.
+//
+// THE ORDER IS LOAD-BEARING:
+//   1. policy  — the surface SHIPS OFF. A disabled policy, or one with no audience, answers "not configured"
+//                before the body is read: an external ingress nobody configured is not reachable.
+//   2. verify  — the bearer token is checked against Google's keys and the policy's audience (fail closed).
+//                Nothing before it reads the body, and an unverified delivery writes no audit row.
+//   3. parse   — anything that is not a well-formed MESSAGE event from a HUMAN sender is acknowledged and
+//                dropped (an ADDED_TO_SPACE, a bot's own message, a CARD_CLICKED this surface does not use).
+//   4. dedupe  — the message's resource name is claimed once, so a retried event never wakes twice.
+//   5. route   — the person's own DM with the app wakes their DM seat (internal people only, and only while
+//                the policy allows direct messages); a group chat is refused; a space wakes the standing seat
+//                that owns `google-chat/<workspace>/<space id>`, only when the message @-mentions the app or
+//                is a slash command. With no standing-seat window for the space it is refused `no-domain`.
+//   6. wake    — the message's own text (the mention removed) renders as the graded trigger. An outside sender
+//                stamps the non-member carriage, exactly as a guest's message does on every chat surface.
+
+import {
+  mkMessageTrigger,
+  readCappedBody,
+  renderWake,
+  stampNonMemberChatAuth,
+  type IngestedChatMessage,
+  type NormalizedWake,
+  type UnifiedWakeOrigin,
+  type WakeMessageInput,
+  type WakeTrust,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { googleChatSurfaceKey, type GoogleChatPolicy } from "../policy.js";
+import { verifyGoogleChatToken, type GoogleChatVerifyDeps } from "./google-chat-auth.js";
+import { buildGoogleChatAuth, type OpenEverywhereGoogleChatAuth } from "./google-chat-identity.js";
+import { isMessageNameIn, isSpaceName, isThreadNameIn } from "./google-chat-rest.js";
+
+type GoogleChatOrigin = Extract<UnifiedWakeOrigin, { platform: "google-chat" }>;
+
+/** The largest message text that reaches the model; the rest is cut and the cut is said. */
+const GOOGLE_CHAT_MAX_INBOUND_CHARS = 20_000;
+
+/** Why the front refused a verified message. */
+export type GoogleChatRefusal = "group-chat" | "dm-off" | "external-dm" | "no-domain";
+
+export type GoogleChatFrontOutcome =
+  | { readonly kind: "not-configured" }
+  | { readonly kind: "unauthorized"; readonly reason: string }
+  | { readonly kind: "ignored"; readonly why: string }
+  | { readonly kind: "duplicate" }
+  | { readonly kind: "refused"; readonly reason: GoogleChatRefusal }
+  | { readonly kind: "admitted"; readonly route: "room" | "dm"; readonly surfaceKey: string };
+
+/** The parsed facts of one MESSAGE event — only what the gate and the wake read. */
+export interface GoogleChatMessageEvent {
+  readonly space: string;
+  readonly spaceKind: "space" | "dm" | "group";
+  readonly messageName: string;
+  readonly thread?: string;
+  readonly threadReply: boolean;
+  readonly sender: string;
+  readonly senderName?: string;
+  readonly domainId?: string;
+  /** The text with the app's mention removed (`argumentText`), else the whole text. */
+  readonly text: string;
+  /** Did the message @-mention the app, or invoke one of its slash commands? */
+  readonly addressed: boolean;
+  readonly createTime: string;
+}
+
+/** Everything one admitted message's dispatch needs. */
+export interface GoogleChatWakePlan {
+  readonly surfaceKey: string;
+  readonly route: "room" | "dm";
+  readonly auth: OpenEverywhereGoogleChatAuth;
+  readonly origin: GoogleChatOrigin;
+  readonly trigger: WakeMessageInput;
+  readonly trust: "internal" | "external";
+  readonly ingested: readonly IngestedChatMessage[];
+  readonly event: GoogleChatMessageEvent;
+}
+
+export interface GoogleChatFrontDeps extends GoogleChatVerifyDeps {
+  readonly policy: () => GoogleChatPolicy;
+  /** Durable first-sighting claim (true = first time). */
+  readonly markSeen: (key: string) => Promise<boolean>;
+  /** Does a windowed domain own this space's surface key? (supervisorGrainFor + grainUsesUnifiedWindow.) */
+  readonly roomHasSeat: (surfaceKey: string) => boolean;
+  /** The per-message trust tier, resolved through the shared resolver over this auth. */
+  readonly wakeTrust: (auth: OpenEverywhereGoogleChatAuth, sender: string) => WakeTrust;
+  readonly dispatchRoom: (plan: GoogleChatWakePlan) => Promise<void>;
+  readonly dispatchDm: (plan: GoogleChatWakePlan) => Promise<void>;
+  readonly audit: (row: { readonly action: string; readonly workspace: string; readonly surface?: string; readonly principalId?: string; readonly detail: Record<string, unknown> }) => Promise<void>;
+}
+
+function rec(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * Parse one event body. Undefined (with a reason) for anything this surface does not take: not JSON, not a
+ * MESSAGE, a malformed name, or a sender that is not a human. Pure.
+ */
+export function parseGoogleChatEvent(rawBody: string): { readonly event: GoogleChatMessageEvent } | { readonly ignored: string } {
+  let j: unknown;
+  try {
+    j = JSON.parse(rawBody);
+  } catch {
+    return { ignored: "not-json" };
+  }
+  const e = rec(j);
+  if (!e || e["type"] !== "MESSAGE") return { ignored: "not-a-message" };
+  const space = rec(e["space"]);
+  const message = rec(e["message"]);
+  const sender = rec(message?.["sender"]);
+  const spaceName = space?.["name"];
+  if (!space || !isSpaceName(spaceName) || !message) return { ignored: "malformed" };
+  const messageName = message["name"];
+  if (!isMessageNameIn(messageName, spaceName)) return { ignored: "malformed" };
+  const threadName = rec(message["thread"])?.["name"];
+  if (threadName !== undefined && !isThreadNameIn(threadName, spaceName)) return { ignored: "malformed" };
+  // A bot's message (including this app's own) never wakes a seat: that is the loop guard.
+  if (sender?.["type"] !== "HUMAN") return { ignored: "not-a-human" };
+  const senderName = str(sender["name"]);
+  if (senderName === undefined || !/^users\/[A-Za-z0-9_-]{1,128}$/u.test(senderName)) return { ignored: "malformed" };
+  const spaceType = str(space["spaceType"]) ?? (space["type"] === "DM" ? "DIRECT_MESSAGE" : "SPACE");
+  const spaceKind: GoogleChatMessageEvent["spaceKind"] =
+    spaceType === "DIRECT_MESSAGE" ? (space["singleUserBotDm"] === true ? "dm" : "group") : spaceType === "GROUP_CHAT" ? "group" : "space";
+  const annotations = Array.isArray(message["annotations"]) ? message["annotations"] : [];
+  const mentionsApp = annotations.some((a) => {
+    const an = rec(a);
+    return an?.["type"] === "USER_MENTION" && rec(rec(an["userMention"])?.["user"])?.["type"] === "BOT";
+  });
+  const slash = rec(message["slashCommand"]) !== undefined;
+  const text = (str(message["argumentText"]) ?? str(message["text"]) ?? "").trim();
+  const domainId = str(sender["domainId"]);
+  const displayName = str(sender["displayName"]);
+  return {
+    event: {
+      space: spaceName,
+      spaceKind,
+      messageName,
+      ...(threadName !== undefined ? { thread: threadName } : {}),
+      threadReply: message["threadReply"] === true && threadName !== undefined,
+      sender: senderName,
+      ...(displayName !== undefined ? { senderName: displayName } : {}),
+      ...(domainId !== undefined ? { domainId } : {}),
+      text,
+      addressed: mentionsApp || slash,
+      createTime: str(message["createTime"]) ?? str(e["eventTime"]) ?? new Date(0).toISOString(),
+    },
+  };
+}
+
+/** The sender's trust: internal only for a domain id the policy lists. */
+function googleChatSenderTrust(policy: GoogleChatPolicy, domainId: string | undefined): "internal" | "external" {
+  return domainId !== undefined && policy.internalDomainIds.includes(domainId) ? "internal" : "external";
+}
+
+/** Build the wake plan for a message the gate admitted. Pure apart from the trust resolver dep. */
+function planGoogleChatWake(
+  input: { readonly event: GoogleChatMessageEvent; readonly policy: GoogleChatPolicy; readonly route: "room" | "dm" },
+  wakeTrust: GoogleChatFrontDeps["wakeTrust"],
+): GoogleChatWakePlan {
+  const { event, policy, route } = input;
+  const trustTier = googleChatSenderTrust(policy, event.domainId);
+  const surfaceKey = googleChatSurfaceKey(policy, event.space);
+  const base = buildGoogleChatAuth({
+    workspace: policy.workspace,
+    space: event.space,
+    mode: route === "dm" ? "dm" : "channel",
+    trust: trustTier,
+    sender: event.sender,
+    ...(event.thread !== undefined ? { thread: event.thread } : {}),
+    messageName: event.messageName,
+  });
+  const trust = wakeTrust(base, event.sender);
+  const ingested: IngestedChatMessage[] = [{ trust, refuted: trustTier === "external" }];
+  const auth = stampNonMemberChatAuth(base as OpenEverywhereGoogleChatAuth & { attributes: Record<string, unknown> }, ingested, route === "dm" ? { dm: true } : { surfaceKey }) as OpenEverywhereGoogleChatAuth;
+  const body =
+    event.text === ""
+      ? "(the message had no text)"
+      : event.text.length > GOOGLE_CHAT_MAX_INBOUND_CHARS
+        ? `${event.text.slice(0, GOOGLE_CHAT_MAX_INBOUND_CHARS)}\n[… the message was cut at ${GOOGLE_CHAT_MAX_INBOUND_CHARS} characters]`
+        : event.text;
+  return {
+    surfaceKey,
+    route,
+    auth,
+    origin: {
+      platform: "google-chat",
+      workspace: policy.workspace,
+      space: event.space,
+      ...(event.thread !== undefined ? { thread: event.thread } : {}),
+      messageName: event.messageName,
+      ...(event.threadReply ? { threadReply: true as const } : {}),
+    },
+    trigger: {
+      from: "human",
+      author: event.senderName ?? event.sender,
+      authorId: event.sender,
+      id: event.messageName,
+      sentAt: event.createTime,
+      trust,
+      mention: true,
+      body,
+    },
+    trust: trustTier,
+    ingested,
+    event,
+  };
+}
+
+/** The NormalizedWake for an admitted message. */
+function buildGoogleChatWake(plan: GoogleChatWakePlan, wakeId: string, tail?: readonly WakeMessageInput[]): NormalizedWake {
+  return {
+    platform: "google-chat",
+    reason: plan.route === "dm" ? "dm" : "mention",
+    addressing: "direct-mention",
+    containerNoun: "space",
+    wakeId,
+    locus: { channel: { id: plan.origin.space }, ...(plan.origin.thread !== undefined ? { thread: { ts: plan.origin.thread } } : {}) },
+    backscroll: tail && tail.length > 0 ? tail : undefined,
+    trigger: mkMessageTrigger(plan.trigger),
+  };
+}
+
+/** Render a plan's wake. */
+export function renderGoogleChatWake(plan: GoogleChatWakePlan, wakeId: string, tail?: readonly WakeMessageInput[]): { message: string; context: readonly string[] } {
+  const r = renderWake(buildGoogleChatWake(plan, wakeId, tail));
+  return { message: r.message, context: r.context ?? [] };
+}
+
+/** Steps 1 and 2: is the surface configured, and is this delivery Google Chat's? */
+async function verifyGoogleChatDelivery(
+  authorization: string | undefined,
+  deps: Pick<GoogleChatFrontDeps, "policy" | "chatSystemKeys" | "googleOidcKeys">,
+): Promise<{ readonly ok: true; readonly policy: GoogleChatPolicy } | { readonly ok: false; readonly outcome: GoogleChatFrontOutcome }> {
+  const policy = deps.policy();
+  if (!policy.enabled || policy.audience === null) return { ok: false, outcome: { kind: "not-configured" } };
+  const verdict = await verifyGoogleChatToken(authorization, policy.audience, deps);
+  if (!verdict.ok) return { ok: false, outcome: { kind: "unauthorized", reason: verdict.reason } };
+  return { ok: true, policy };
+}
+
+/** Steps 3 to 6 for a delivery already VERIFIED. Never throws for a bad event; a dispatch failure propagates. */
+async function processVerifiedGoogleChatEvent(policy: GoogleChatPolicy, rawBody: string, deps: GoogleChatFrontDeps): Promise<GoogleChatFrontOutcome> {
+  const parsed = parseGoogleChatEvent(rawBody);
+  if ("ignored" in parsed) return { kind: "ignored", why: parsed.ignored };
+  const event = parsed.event;
+  if (event.spaceKind === "space" && !event.addressed) return { kind: "ignored", why: "not-addressed" };
+  if (!(await deps.markSeen(`google-chat:${event.messageName}`))) return { kind: "duplicate" };
+
+  const surfaceKey = googleChatSurfaceKey(policy, event.space);
+  const refuse = async (reason: GoogleChatRefusal): Promise<GoogleChatFrontOutcome> => {
+    await deps.audit({
+      action: "google-chat.refused",
+      workspace: policy.workspace,
+      surface: surfaceKey,
+      principalId: event.sender,
+      detail: { reason, space: event.space, domainId: event.domainId ?? null },
+    });
+    return { kind: "refused", reason };
+  };
+  if (event.spaceKind === "group") return refuse("group-chat");
+  const route: "room" | "dm" = event.spaceKind === "dm" ? "dm" : "room";
+  if (route === "dm") {
+    if (!policy.directMessages) return refuse("dm-off");
+    // A DM seat reads its person's private layer; an outside person never gets one.
+    if (googleChatSenderTrust(policy, event.domainId) !== "internal") return refuse("external-dm");
+  } else if (!deps.roomHasSeat(surfaceKey)) {
+    return refuse("no-domain");
+  }
+
+  const plan = planGoogleChatWake({ event, policy, route }, deps.wakeTrust);
+  if (route === "room") await deps.dispatchRoom(plan);
+  else await deps.dispatchDm(plan);
+  await deps.audit({
+    action: "google-chat.admitted",
+    workspace: policy.workspace,
+    surface: plan.surfaceKey,
+    principalId: event.sender,
+    detail: { space: event.space, route, trust: plan.trust, domainId: event.domainId ?? null, threadReply: event.threadReply },
+  });
+  return { kind: "admitted", route, surfaceKey: plan.surfaceKey };
+}
+
+/** The whole path in one call (the tests' entry): verify, then process. */
+export async function handleGoogleChatDelivery(authorization: string | undefined, rawBody: string, deps: GoogleChatFrontDeps): Promise<GoogleChatFrontOutcome> {
+  const v = await verifyGoogleChatDelivery(authorization, deps);
+  if (!v.ok) return v.outcome;
+  return processVerifiedGoogleChatEvent(v.policy, rawBody, deps);
+}
+
+/** The largest event body the route reads. A Chat message is at most 32 KB; the event wraps it. */
+export const GOOGLE_CHAT_INGRESS_MAX_BODY_BYTES = 512 * 1024;
+
+/**
+ * The whole HTTP route, eve-free so a test drives it. 🔴 THE ORDER IS THE DEFENCE: the policy (503) and the token
+ * (401) are checked BEFORE the body is read, so an unconfigured or unauthenticated caller cannot make the route
+ * read a byte. Then the body cap (413), then `{}` with the rest in the background (`waitUntil`).
+ */
+export async function handleGoogleChatRequest(
+  req: Request,
+  waitUntil: (p: Promise<unknown>) => void,
+  deps: GoogleChatFrontDeps,
+  hooks: { readonly log?: (msg: string) => void; readonly onFailure?: (err: unknown, policy: GoogleChatPolicy) => Promise<void> } = {},
+): Promise<Response> {
+  const log = hooks.log ?? (() => undefined);
+  const verified = await verifyGoogleChatDelivery(req.headers.get("authorization") ?? undefined, deps);
+  if (!verified.ok) {
+    if (verified.outcome.kind === "unauthorized") {
+      log(`delivery refused (401): ${verified.outcome.reason}`);
+      return new Response("unauthorized", { status: 401 });
+    }
+    return new Response("google chat surface not configured", { status: 503 });
+  }
+  const read = await readCappedBody(req, GOOGLE_CHAT_INGRESS_MAX_BODY_BYTES);
+  if ("tooLarge" in read) return new Response(`payload exceeds ${GOOGLE_CHAT_INGRESS_MAX_BODY_BYTES} bytes`, { status: 413 });
+  waitUntil(
+    processVerifiedGoogleChatEvent(verified.policy, read.body, deps)
+      .then((outcome) =>
+        log(
+          `event ${outcome.kind}${outcome.kind === "refused" ? ` (${outcome.reason})` : outcome.kind === "admitted" ? ` → ${outcome.route} ${outcome.surfaceKey}` : outcome.kind === "ignored" ? ` (${outcome.why})` : ""}`,
+        ),
+      )
+      .catch(async (err: unknown) => {
+        log(`event FAILED after the ack: ${err instanceof Error ? err.name : "error"}`);
+        await hooks.onFailure?.(err, verified.policy);
+      }),
+  );
+  // `{}` = no synchronous message. The seat answers through the post arm.
+  return new Response("{}", { status: 200, headers: { "content-type": "application/json" } });
+}

package/agent/channels/google-chat-identity.ts

@@ -0,0 +1,97 @@
+// Pure Google Chat → Open Everywhere identity capture. The front (google-chat-front.ts) stows the HOST-DECIDED
+// facts of one admitted event into the wake's auth `attributes`, and the mapper below interprets them into the
+// binding. The security-load-bearing reading lives here, in one tested place.
+//
+// THE GRAIN:
+//   • workspace  = the policy's `workspace` segment — one Google Workspace per deployment;
+//   • surface    = the space id (`spaces/<id>` → `<id>`), so a domain's `reach` lists `google-chat/<ws>/<id>`;
+//   • mode       = `dm` for the person's own direct message with the app, else `channel`;
+//   • visibility = ALWAYS `private`. A Chat space may be discoverable inside the org, but the event does not
+//                  prove it, so nothing said in a space flows up to a shared tier by visibility alone;
+//   • trust      = `internal` ONLY when the sender is a human whose Workspace domain id is one of the policy's
+//                  `internalDomainIds`. Everyone else is `external`;
+//   • principal  = the sender's Chat user resource name (`users/<id>`), never a display name or an email.
+//
+// §AUTH-ATTRIBUTE PROVENANCE: every attribute below is written by the front from the token-verified event and
+// the policy, never from the message text and never by a model.
+
+import type { BindableContext, IdentityMapper, RawIdentity } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The structural match for eve's SessionAuthContext. */
+export interface OpenEverywhereGoogleChatAuth {
+  readonly authenticator: string;
+  readonly principalId: string;
+  readonly principalType: string;
+  readonly attributes: Record<string, string>;
+}
+
+export interface GoogleChatIdentityInput {
+  readonly workspace: string;
+  /** The space resource name (`spaces/<id>`). */
+  readonly space: string;
+  readonly mode: "channel" | "dm";
+  readonly trust: "internal" | "external";
+  /** The sender's user resource name (`users/<id>`). */
+  readonly sender: string;
+  readonly thread?: string;
+  readonly messageName: string;
+}
+
+/** Build the auth context the Google Chat surface dispatches with. */
+export function buildGoogleChatAuth(input: GoogleChatIdentityInput): OpenEverywhereGoogleChatAuth {
+  return {
+    authenticator: "google-chat",
+    principalId: input.sender,
+    principalType: "google-chat-user",
+    attributes: {
+      gchat_workspace: input.workspace,
+      gchat_space: input.space,
+      gchat_surface: input.space.slice(input.space.indexOf("/") + 1),
+      gchat_mode: input.mode,
+      gchat_trust: input.trust,
+      gchat_message: input.messageName,
+      ...(input.thread !== undefined ? { gchat_thread: input.thread } : {}),
+    },
+  };
+}
+
+type AuthAttrs = Readonly<Record<string, string | readonly string[]>> | undefined;
+
+function authOf(ctx: BindableContext): { attributes?: AuthAttrs; principalId?: string } | null {
+  return ctx.session?.auth?.current ?? ctx.session?.auth?.initiator ?? null;
+}
+
+function attr(a: AuthAttrs, key: string): string | undefined {
+  const v = a?.[key];
+  const first = Array.isArray(v) ? v[0] : v;
+  return typeof first === "string" && first.length > 0 ? first : undefined;
+}
+
+/**
+ * The Google Chat identity mapper. FAIL CLOSED on every field it cannot read: no mode reads `channel`, no trust
+ * attribute reads `external`, and visibility is always `private`. `trustVerified` is set for a DM only when the
+ * front verified the sender internal, so a DM never lights the internal `dm` layer for an outsider.
+ */
+export const bindGoogleChat: IdentityMapper = (ctx): RawIdentity => {
+  const auth = authOf(ctx);
+  const a = auth?.attributes;
+  const mode = attr(a, "gchat_mode") === "dm" ? "dm" : "channel";
+  const internal = attr(a, "gchat_trust") === "internal";
+  const space = attr(a, "gchat_space");
+  const thread = attr(a, "gchat_thread");
+  const messageName = attr(a, "gchat_message");
+  const principalId = typeof auth?.principalId === "string" && auth.principalId.length > 0 ? auth.principalId : undefined;
+  return {
+    workspace: attr(a, "gchat_workspace"),
+    surface: attr(a, "gchat_surface"),
+    mode,
+    visibility: "private",
+    ...(internal ? { trust: "internal" as const, ...(mode === "dm" ? { trustVerified: true } : {}) } : { trust: "external" as const }),
+    ...(principalId ? { principalId } : {}),
+    // `channelId` is the space: the one address every shared room-notice path (an approval outcome note, a
+    // judge-lift notice) posts to through the surface message ops.
+    ...(space
+      ? { target: { space, channelId: space, ...(thread ? { thread } : {}), ...(messageName ? { messageName } : {}) } }
+      : {}),
+  };
+};

package/agent/channels/google-chat-message-ops.ts

@@ -0,0 +1,30 @@
+// google-chat-message-ops — the Google Chat surface's host-notice transport (SurfaceMessageOps). Core's shared
+// room-notice paths — an approval outcome note, the judge-lift notice, a stop or cancel note — post through
+// `SurfaceMessageOps.postText(channelId, text)`. On Google Chat the `channelId` is the space name the identity
+// mapper put in the binding's target. A `replyToMessageId` anchor is not followed: Google Chat threads a reply by
+// thread name, not by message, so the notice lands in the space as a new message.
+//
+// 🔴 TEXT ONLY. `editMessage` refuses: no card posts on this surface yet, so there is no card to close.
+
+import { markNotApplied, type SurfaceMessageOps } from "@open-everywhere/core/agent/adapter-api.js";
+import { googleChatPolicy, type GoogleChatPolicy } from "../policy.js";
+import { createGoogleChatMessage, type GoogleChatPostDeps } from "./google-chat-rest.js";
+
+export interface GoogleChatNoticeDeps extends GoogleChatPostDeps {
+  readonly policy?: () => GoogleChatPolicy;
+}
+
+/** Post one host notice into a space. Throws a token-free error when it cannot. */
+export async function postGoogleChatNotice(channelId: string, text: string, deps: GoogleChatNoticeDeps = {}): Promise<string> {
+  const policy = (deps.policy ?? googleChatPolicy)();
+  if (!policy.enabled) throw markNotApplied(new Error("the Google Chat surface is turned off."));
+  return createGoogleChatMessage({ space: channelId, text }, deps);
+}
+
+export const googleChatMessageOps: SurfaceMessageOps = {
+  platform: "google-chat",
+  postText: (channelId, text) => postGoogleChatNotice(channelId, text),
+  async editMessage() {
+    throw markNotApplied(new Error("editing a Google Chat message is not built yet."));
+  },
+};

package/agent/channels/google-chat-origin-codec.ts

@@ -0,0 +1,32 @@
+// The Google Chat UnifiedWakeOrigin codec. An origin is STORED DATA (the durable wake map), so this validator is a
+// compatibility contract with rows already on disk: it tolerates unknown extra fields, and it refuses any row whose
+// space, thread or message name is not Google's grammar, because the post arm builds its URL from them.
+//
+// THE CONVERSATION: `threadRef` keys on (space, thread). Every message in a Google Chat space carries a thread
+// name, even a top-level one, so the thread is part of the identity and placement lives inside it (no
+// `placementRef`). Only a positive `threadReply: true` makes an origin thread-scoped.
+
+import type { UnifiedWakeOrigin, WakeOriginCodec } from "@open-everywhere/core/agent/adapter-api.js";
+import { isMessageNameIn, isSpaceName, isThreadNameIn } from "./google-chat-rest.js";
+
+export type GoogleChatOrigin = Extract<UnifiedWakeOrigin, { platform: "google-chat" }>;
+
+const WORKSPACE_SEGMENT = /^[a-z0-9][a-z0-9-]{0,62}$/u;
+
+/** A task windowId is `[^:]+` (core channels/window-key.ts); Google names hold no colon, but fold one anyway. */
+const noColon = (s: string): string => s.replace(/:/g, "_");
+
+export const googleChatWakeOriginCodec: WakeOriginCodec<GoogleChatOrigin> = {
+  validate: (o) => {
+    if (typeof o.workspace !== "string" || !WORKSPACE_SEGMENT.test(o.workspace)) return false;
+    if (!isSpaceName(o.space)) return false;
+    if (o.thread !== undefined && !isThreadNameIn(o.thread, o.space)) return false;
+    if (o.messageName !== undefined && !isMessageNameIn(o.messageName, o.space)) return false;
+    // A thread reply with no thread is not a shape the front mints.
+    if (o.threadReply !== undefined && (o.threadReply !== true || o.thread === undefined)) return false;
+    return true;
+  },
+  threadRef: (o) => ({ channelKey: noColon(`google-chat/${o.space}`), threadKey: noColon(o.thread ?? o.space) }),
+  isThreadScoped: (o) => o.threadReply === true,
+  containerId: (o) => o.space,
+};

package/agent/channels/google-chat-post-arm.ts

@@ -0,0 +1,36 @@
+// google-chat-post-arm — the Google Chat surface's arm of the post-arms registry. One verb: answer the event that
+// woke the seat, in the same space and thread, as the app (google-chat-rest.ts). The space and thread come from
+// the stored origin, which the front froze from the token-verified event; the model never names one.
+//
+// 🔴 THE POLICY IS RE-READ AT SEND TIME. A surface turned off between the wake and the reply sends nothing, and
+// an origin minted under another workspace segment is refused.
+// NO EDIT, NO REACTION yet: the arm registers neither, and the capability manifest says so.
+
+import { markNotApplied, type PostArm, type UnifiedReplyDeps, type UnifiedWakeOrigin } from "@open-everywhere/core/agent/adapter-api.js";
+import { googleChatPolicy, type GoogleChatPolicy } from "../policy.js";
+import { createGoogleChatMessage, type GoogleChatPostDeps } from "./google-chat-rest.js";
+import { googleChatWakeOriginCodec, type GoogleChatOrigin } from "./google-chat-origin-codec.js";
+
+export interface GoogleChatReplyDeps extends GoogleChatPostDeps {
+  readonly policy?: () => GoogleChatPolicy;
+}
+
+/** Send one reply for a stored origin. Throws a token-free error when the reply did not go out. */
+export async function sendGoogleChatReply(origin: GoogleChatOrigin, text: string, deps: GoogleChatReplyDeps = {}): Promise<string> {
+  if (!googleChatWakeOriginCodec.validate(origin as unknown as Record<string, unknown>)) {
+    throw markNotApplied(new Error("reply couldn't post to Google Chat — the stored reply target is not a valid Google Chat origin."));
+  }
+  const policy = (deps.policy ?? googleChatPolicy)();
+  if (!policy.enabled) throw markNotApplied(new Error("reply couldn't post to Google Chat — the surface is turned off in agent/google-chat/policy.ts."));
+  if (origin.workspace !== policy.workspace) {
+    throw markNotApplied(new Error("reply couldn't post to Google Chat — the stored reply target belongs to another workspace."));
+  }
+  return createGoogleChatMessage({ space: origin.space, ...(origin.thread !== undefined ? { thread: origin.thread } : {}), text }, deps);
+}
+
+export const googleChatPostArm: PostArm = {
+  platform: "google-chat",
+  dispatchUnified: (origin: UnifiedWakeOrigin, text: string, _deps: UnifiedReplyDeps) => sendGoogleChatReply(origin as GoogleChatOrigin, text),
+  describeRedriveTarget: (origin) => `Google Chat ${(origin as GoogleChatOrigin).space}`,
+  redriveContainerId: (origin) => (origin as GoogleChatOrigin).space,
+};

package/agent/channels/google-chat-rest.ts

@@ -0,0 +1,87 @@
+// google-chat-rest — the ONE outbound call of the Google Chat surface: create a message in a space, as the app,
+// optionally inside a thread. The host is pinned (`chat.googleapis.com`), the space and thread names are
+// validated against Google's resource grammar before they reach a URL, and errors carry the HTTP status only.
+//
+// The app can post only into a space it is a member of, so this call cannot reach a space nobody added the app
+// to. A text longer than one Chat message is sent as consecutive messages in the same thread.
+
+import { friendlyOutboundText, markNotApplied } from "@open-everywhere/core/agent/adapter-api.js";
+import { googleChatAccessToken, type GoogleChatTokenDeps } from "./google-chat-auth.js";
+
+const CHAT_API = "https://chat.googleapis.com/v1";
+/** One Chat message's text limit is 4,096 characters; leave room for nothing else. */
+export const GOOGLE_CHAT_MAX_TEXT = 4000;
+
+const SPACE_NAME = /^spaces\/[A-Za-z0-9_-]{1,128}$/u;
+const THREAD_NAME = /^spaces\/[A-Za-z0-9_-]{1,128}\/threads\/[A-Za-z0-9_.-]{1,128}$/u;
+const MESSAGE_NAME = /^spaces\/[A-Za-z0-9_-]{1,128}\/messages\/[A-Za-z0-9_.-]{1,128}$/u;
+
+export function isSpaceName(v: unknown): v is string {
+  return typeof v === "string" && SPACE_NAME.test(v);
+}
+
+/** A thread name that belongs to `space` (a thread of another space is not a thread of this one). */
+export function isThreadNameIn(v: unknown, space: string): v is string {
+  return typeof v === "string" && THREAD_NAME.test(v) && v.startsWith(`${space}/threads/`);
+}
+
+export function isMessageNameIn(v: unknown, space: string): v is string {
+  return typeof v === "string" && MESSAGE_NAME.test(v) && v.startsWith(`${space}/messages/`);
+}
+
+/** Split `text` into Chat-sized pieces, preferring a newline near the limit, never inside a surrogate pair. */
+export function splitGoogleChatText(text: string, max = GOOGLE_CHAT_MAX_TEXT): readonly string[] {
+  const out: string[] = [];
+  let rest = text;
+  while (rest.length > max) {
+    const nl = rest.lastIndexOf("\n", max);
+    let cut = nl > max / 2 ? nl : max;
+    // Never cut through a surrogate pair: a lone half is not valid text, and Google may refuse the message.
+    const before = rest.charCodeAt(cut - 1);
+    if (before >= 0xd800 && before <= 0xdbff) cut -= 1;
+    out.push(rest.slice(0, cut));
+    rest = rest.slice(cut).replace(/^\n/u, "");
+  }
+  out.push(rest);
+  return out;
+}
+
+export interface GoogleChatPostDeps extends GoogleChatTokenDeps {}
+
+/**
+ * Post `text` into `space`, threaded under `thread` when given (a thread Google no longer knows falls back to
+ * a new thread). Returns the LAST created message name. A pre-flight refusal is definitive (`markNotApplied`).
+ */
+export async function createGoogleChatMessage(
+  input: { readonly space: string; readonly thread?: string; readonly text: string },
+  deps: GoogleChatPostDeps = {},
+): Promise<string> {
+  if (!isSpaceName(input.space)) throw markNotApplied(new Error("the Google Chat space name is not valid."));
+  if (input.thread !== undefined && !isThreadNameIn(input.thread, input.space)) {
+    throw markNotApplied(new Error("the Google Chat thread does not belong to the space."));
+  }
+  if (input.text.trim() === "") throw markNotApplied(new Error("a Google Chat message needs text."));
+  // THE FRIENDLY-NAMES GUARD (OPE-2482), on the one Google Chat write: every raw id renders as a name or
+  // plain words before the text is split and sent, so a post outside the registered arms is covered too.
+  const text = await friendlyOutboundText(input.text, "google-chat");
+  const token = await googleChatAccessToken(deps);
+  const doFetch = deps.fetch ?? fetch;
+  let thread = input.thread;
+  let last = "";
+  for (const piece of splitGoogleChatText(text)) {
+    const url = `${CHAT_API}/${input.space}/messages${thread !== undefined ? "?messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD" : ""}`;
+    const res = await doFetch(url, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json; charset=utf-8" },
+      body: JSON.stringify({ text: piece, ...(thread !== undefined ? { thread: { name: thread } } : {}) }),
+    });
+    if (!res.ok) throw new Error(`Google Chat refused the message (HTTP ${res.status}).`);
+    const body = (await res.json().catch(() => ({}))) as { name?: unknown; thread?: { name?: unknown } };
+    if (typeof body.name !== "string") throw new Error("Google Chat returned no message name.");
+    last = body.name;
+    // The pieces after the first follow the first one's thread, so a long answer stays together.
+    const created = body.thread?.name;
+    if (thread === undefined && isThreadNameIn(created, input.space)) thread = created;
+  }
+  return last;
+}