paperclip-plugin-google-chat 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Measured Assets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# paperclip-plugin-google-chat
+
+Bidirectional **Google Chat** integration for [Paperclip](https://github.com/paperclipai/paperclip).
+
+- **Outbound** — posts issue / approval / agent-failure notifications to Google Chat spaces, driven by Paperclip domain events. Agents can also push messages on demand via registered tools (`post_to_google_chat`, `escalate_to_human`, `send_briefing`).
+- **Inbound** — a Google Chat app delivers events to the plugin's webhook endpoint; slash commands (`/status`, `/issues`, `/agents`, `/report`, `/objective`) query or drive Paperclip from a space.
+
+Built on the first-party [Paperclip plugin SDK](https://github.com/paperclipai/paperclip/tree/master/packages/plugins/sdk) (`apiVersion: 1`). No external relay service required — Paperclip terminates the webhook and makes the outbound calls itself.
+
+> Status: **0.1.0 — scaffold.** Outbound notifications + tools and inbound command routing are implemented and unit-tested. The space→company `/connect` mapping and the Chat REST API reply path are on the roadmap (see below).
+
+## Why a plugin (not a Cloudflare Worker + curl)
+
+Everything this needs is a first-class SDK primitive, so the whole bridge lives inside Paperclip:
+
+| Need | SDK capability |
+|------|----------------|
+| Receive Google Chat events | `webhooks.receive` |
+| Post to a space | `http.outbound` (`ctx.http.fetch`) |
+| Keep the webhook URL secret | `secrets.read-ref` (`ctx.secrets.resolve`) |
+| Notify on issue/approval/agent events | `events.subscribe` |
+| Let agents push messages | `agent.tools.register` |
+| Daily digest | `jobs.schedule` |
+
+The Google Chat webhook URL is **never stored in plaintext** — config holds a Paperclip secret *reference* (a UUID), resolved at runtime.
+
+## Install
+
+```bash
+# from a checkout of this repo
+npm install
+npm run build
+# then register the built plugin with your Paperclip instance
+paperclipai plugin install /absolute/path/to/paperclip-plugin-google-chat
+```
+
+## Configure
+
+1. **Create an incoming webhook** in your Google Chat space (Space → *Apps & integrations* → *Webhooks*). Copy the URL.
+2. In Paperclip, store it as a **company secret** (Settings → Secrets, or `POST /api/companies/{companyId}/secrets`). You get back a UUID.
+3. In the plugin's settings, paste that UUID into **`defaultWebhookUrlRef`** (and optionally `approvalsWebhookUrlRef` / `errorsWebhookUrlRef` / `digestWebhookUrlRef` for per-category routing).
+4. Toggle which events notify (`notifyOnIssueCompleted`, `notifyOnApprovalRequested`, …) and, if you want inbound commands, set up a Google Chat **app** pointing its HTTP endpoint at this plugin's webhook URL, then set `allowedSpaceIds` / `allowedUserEmails`.
+
+### Config keys
+
+See [`src/config.ts`](src/config.ts) for the full schema. All credential fields are **secret references**, not raw values.
+
+## Slash commands
+
+| Command | Action | Restricted |
+|---------|--------|:---:|
+| `/status` | Open-issue + active-agent snapshot | |
+| `/issues` | List open issues | |
+| `/agents` | Agent roster + state | |
+| `/report` | Generate a status report | |
+| `/objective <text>` | Set/queue an objective | ✅ allowlist |
+| `/help` | Command help | |
+
+Mutating commands require the sender's email to be in `allowedUserEmails`.
+
+## Architecture
+
+```
+src/
+  manifest.ts    capabilities + webhook/tool/job declarations
+  config.ts      config schema + validator (secret-ref based)
+  google-chat.ts outbound client (incoming webhooks) + pure formatters
+  events.ts      domain-event → notification mapping
+  commands.ts    inbound event parsing + slash-command router
+  tools.ts       agent-callable tool handlers
+  worker.ts      definePlugin() wiring: setup / onWebhook / onHealth
+```
+
+Pure logic (formatting, parsing, routing, validation) is separated from the SDK-facing worker so it is unit-tested without a running Paperclip (`tests/`).
+
+## Develop
+
+```bash
+npm install
+npm test         # vitest — pure-logic unit tests
+npm run typecheck
+npm run build
+```
+
+## Roadmap
+
+- **`/connect <company>`** — map a Google Chat space to a Paperclip company and persist it in plugin state (today inbound commands assume a single company scope).
+- **Chat REST API path** — threaded, per-space replies and message reads via a service-account key (`serviceAccountKeyRef`); today replies post via the configured incoming webhook.
+- **Cards v2** — richer notification/approval cards with interactive buttons (`useCards`).
+- **Inbound verification** — validate Google's signed bearer token, not just a shared `verificationTokenRef`.
+
+## License
+
+MIT © Measured Assets

package/dist/commands.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Inbound Google Chat event handling.
+ *
+ * A Google Chat *app* delivers events as JSON POSTs. The shapes we care about:
+ *
+ *   { type: "MESSAGE", space: { name, type }, user: { email, displayName },
+ *     message: { text, argumentText, slashCommand?, thread } }
+ *   { type: "ADDED_TO_SPACE" | "REMOVED_FROM_SPACE", ... }
+ *   { type: "CARD_CLICKED", ... }
+ *
+ * We translate a `MESSAGE` whose text begins with a slash into a Paperclip action.
+ * Parsing and authorization are pure functions; the side-effecting handlers take an
+ * injected `CommandDeps` so they can be unit-tested without the SDK.
+ */
+import type { GoogleChatConfig } from "./config.js";
+export interface ChatEvent {
+    type?: string;
+    space?: {
+        name?: string;
+        type?: string;
+    };
+    user?: {
+        email?: string;
+        displayName?: string;
+    };
+    message?: {
+        text?: string;
+        argumentText?: string;
+        thread?: {
+            name?: string;
+        };
+    };
+}
+export interface ParsedCommand {
+    command: string;
+    args: string;
+    spaceId: string;
+    userEmail: string;
+    threadKey?: string;
+    raw: string;
+}
+/** Extract a `/command args` from a Chat MESSAGE event. Returns null if not a command. */
+export declare function parseChatEvent(event: ChatEvent): ParsedCommand | null;
+/** Space-level allowlist (who may issue ANY command). */
+export declare function isSpaceAllowed(spaceId: string, config: GoogleChatConfig): boolean;
+/** User-level allowlist (who may issue MUTATING commands). */
+export declare function isUserAllowed(email: string, config: GoogleChatConfig): boolean;
+/** Commands that change Paperclip state (require user allowlist). */
+export declare const MUTATING_COMMANDS: Set<string>;
+/**
+ * Side-effecting dependencies the router needs. Implemented in the worker against
+ * the Paperclip SDK; mocked in tests.
+ */
+export interface CommandDeps {
+    listIssues(): Promise<Array<{
+        title?: string;
+        status?: string;
+    }>>;
+    listAgents(): Promise<Array<{
+        name?: string;
+        status?: string;
+    }>>;
+    setObjective(text: string): Promise<string>;
+    buildReport(): Promise<string>;
+}
+/**
+ * Route a parsed command to a reply string. Returns the text to post back to the
+ * space. Authorization is enforced here; unknown commands return help.
+ */
+export declare function handleCommand(parsed: ParsedCommand, config: GoogleChatConfig, deps: CommandDeps): Promise<string>;

package/dist/commands.js

@@ -0,0 +1,105 @@
+/**
+ * Inbound Google Chat event handling.
+ *
+ * A Google Chat *app* delivers events as JSON POSTs. The shapes we care about:
+ *
+ *   { type: "MESSAGE", space: { name, type }, user: { email, displayName },
+ *     message: { text, argumentText, slashCommand?, thread } }
+ *   { type: "ADDED_TO_SPACE" | "REMOVED_FROM_SPACE", ... }
+ *   { type: "CARD_CLICKED", ... }
+ *
+ * We translate a `MESSAGE` whose text begins with a slash into a Paperclip action.
+ * Parsing and authorization are pure functions; the side-effecting handlers take an
+ * injected `CommandDeps` so they can be unit-tested without the SDK.
+ */
+/** Extract a `/command args` from a Chat MESSAGE event. Returns null if not a command. */
+export function parseChatEvent(event) {
+    if (event.type !== "MESSAGE")
+        return null;
+    const text = (event.message?.text ?? "").trim();
+    if (!text.startsWith("/"))
+        return null;
+    const withoutSlash = text.slice(1);
+    const spaceIdx = withoutSlash.search(/\s/);
+    const command = (spaceIdx === -1 ? withoutSlash : withoutSlash.slice(0, spaceIdx)).toLowerCase();
+    const args = spaceIdx === -1 ? "" : withoutSlash.slice(spaceIdx + 1).trim();
+    const spaceName = event.space?.name ?? "";
+    const spaceId = spaceName.startsWith("spaces/") ? spaceName.slice("spaces/".length) : spaceName;
+    return {
+        command,
+        args,
+        spaceId,
+        userEmail: event.user?.email ?? "",
+        threadKey: event.message?.thread?.name,
+        raw: text,
+    };
+}
+/** Space-level allowlist (who may issue ANY command). */
+export function isSpaceAllowed(spaceId, config) {
+    const allow = config.allowedSpaceIds ?? [];
+    return allow.length === 0 || allow.includes(spaceId);
+}
+/** User-level allowlist (who may issue MUTATING commands). */
+export function isUserAllowed(email, config) {
+    const allow = config.allowedUserEmails ?? [];
+    return allow.length === 0 || allow.includes(email);
+}
+/** Commands that change Paperclip state (require user allowlist). */
+export const MUTATING_COMMANDS = new Set(["objective", "report", "approve"]);
+const HELP_TEXT = [
+    "*Paperclip — Google Chat commands*",
+    "`/status` — fleet + issue snapshot",
+    "`/issues` — open issues",
+    "`/agents` — agent roster + state",
+    "`/report` — generate a status report",
+    "`/objective <text>` — set/queue an objective (restricted)",
+    "`/help` — this message",
+].join("\n");
+/**
+ * Route a parsed command to a reply string. Returns the text to post back to the
+ * space. Authorization is enforced here; unknown commands return help.
+ */
+export async function handleCommand(parsed, config, deps) {
+    if (config.enableCommands === false)
+        return ""; // silently ignore when disabled
+    if (!isSpaceAllowed(parsed.spaceId, config)) {
+        return "This space is not authorized to issue commands.";
+    }
+    if (MUTATING_COMMANDS.has(parsed.command) && !isUserAllowed(parsed.userEmail, config)) {
+        return `You (${parsed.userEmail || "unknown"}) are not authorized to run /${parsed.command}.`;
+    }
+    switch (parsed.command) {
+        case "help":
+            return HELP_TEXT;
+        case "status": {
+            const [issues, agents] = await Promise.all([deps.listIssues(), deps.listAgents()]);
+            const open = issues.filter((i) => i.status !== "done" && i.status !== "completed").length;
+            const running = agents.filter((a) => a.status === "running" || a.status === "active").length;
+            return `*Status* — ${open} open issues · ${running}/${agents.length} agents active`;
+        }
+        case "issues": {
+            const issues = await deps.listIssues();
+            if (issues.length === 0)
+                return "No issues.";
+            return issues
+                .slice(0, 20)
+                .map((i) => `• ${i.title ?? "(untitled)"}${i.status ? ` _(${i.status})_` : ""}`)
+                .join("\n");
+        }
+        case "agents": {
+            const agents = await deps.listAgents();
+            if (agents.length === 0)
+                return "No agents.";
+            return agents.map((a) => `• ${a.name ?? "(unnamed)"} — ${a.status ?? "unknown"}`).join("\n");
+        }
+        case "report":
+            return await deps.buildReport();
+        case "objective": {
+            if (!parsed.args)
+                return "Usage: /objective <text>";
+            return await deps.setObjective(parsed.args);
+        }
+        default:
+            return HELP_TEXT;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Instance configuration for the Google Chat plugin.
+ *
+ * Secret values (Google Chat incoming-webhook URLs, an optional service-account
+ * key) are NEVER stored here in plaintext. The config holds **secret references**
+ * — opaque UUIDs minted by Paperclip's secret store — which the worker resolves at
+ * runtime via `ctx.secrets.resolve(ref)`. This mirrors the Telegram plugin's
+ * `telegramBotTokenRef` pattern and keeps credentials out of config exports/logs.
+ */
+export interface GoogleChatConfig {
+    /** Secret ref → a Google Chat *incoming webhook* URL for the default space. */
+    defaultWebhookUrlRef?: string;
+    /** Optional per-category routing. Each is a secret ref to a space webhook URL. */
+    approvalsWebhookUrlRef?: string;
+    errorsWebhookUrlRef?: string;
+    digestWebhookUrlRef?: string;
+    /**
+     * Optional secret ref → a Google service-account JSON key. Only needed for the
+     * Chat REST API (threaded replies, reading messages). Plain incoming webhooks do
+     * not require it. Left unset = webhook-only mode.
+     */
+    serviceAccountKeyRef?: string;
+    notifyOnIssueCreated?: boolean;
+    notifyOnIssueCompleted?: boolean;
+    notifyOnApprovalRequested?: boolean;
+    notifyOnAgentRunFailed?: boolean;
+    /** Use Cards v2 formatting instead of plain text where supported. */
+    useCards?: boolean;
+    /** Master switch for inbound slash commands. */
+    enableCommands?: boolean;
+    /**
+     * Shared verification token. Google Chat includes a bearer/verification token on
+     * each request; we compare it to reject forged webhook deliveries. Stored as a
+     * secret ref. (For production, prefer verifying the Google-signed bearer JWT.)
+     */
+    verificationTokenRef?: string;
+    /** Allowlist of Google Chat space IDs permitted to issue commands. Empty = all. */
+    allowedSpaceIds?: string[];
+    /** Allowlist of user emails permitted to issue mutating commands. Empty = all. */
+    allowedUserEmails?: string[];
+    digestMode?: boolean;
+    /** 24h "HH:MM" local time for the daily digest. */
+    dailyDigestTime?: string;
+}
+export declare const DEFAULT_CONFIG: GoogleChatConfig;
+/** JSON-schema fragment surfaced in Paperclip's plugin settings UI. */
+export declare const INSTANCE_CONFIG_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly defaultWebhookUrlRef: {
+            readonly type: "string";
+            readonly title: "Default space webhook (secret ref)";
+            readonly description: "Secret reference to a Google Chat incoming-webhook URL. Create the secret in Paperclip, paste the returned UUID here.";
+        };
+        readonly approvalsWebhookUrlRef: {
+            readonly type: "string";
+            readonly title: "Approvals space webhook (secret ref)";
+        };
+        readonly errorsWebhookUrlRef: {
+            readonly type: "string";
+            readonly title: "Errors space webhook (secret ref)";
+        };
+        readonly digestWebhookUrlRef: {
+            readonly type: "string";
+            readonly title: "Digest space webhook (secret ref)";
+        };
+        readonly serviceAccountKeyRef: {
+            readonly type: "string";
+            readonly title: "Service-account key (secret ref, optional)";
+            readonly description: "Only required for the Chat REST API (threaded replies). Webhook-only mode leaves this blank.";
+        };
+        readonly notifyOnIssueCreated: {
+            readonly type: "boolean";
+            readonly title: "Notify on issue created";
+            readonly default: false;
+        };
+        readonly notifyOnIssueCompleted: {
+            readonly type: "boolean";
+            readonly title: "Notify on issue completed";
+            readonly default: true;
+        };
+        readonly notifyOnApprovalRequested: {
+            readonly type: "boolean";
+            readonly title: "Notify on approval requested";
+            readonly default: true;
+        };
+        readonly notifyOnAgentRunFailed: {
+            readonly type: "boolean";
+            readonly title: "Notify on agent run failed";
+            readonly default: true;
+        };
+        readonly useCards: {
+            readonly type: "boolean";
+            readonly title: "Use Cards v2 formatting";
+            readonly default: false;
+        };
+        readonly enableCommands: {
+            readonly type: "boolean";
+            readonly title: "Enable inbound slash commands";
+            readonly default: true;
+        };
+        readonly verificationTokenRef: {
+            readonly type: "string";
+            readonly title: "Verification token (secret ref)";
+        };
+        readonly allowedSpaceIds: {
+            readonly type: "array";
+            readonly title: "Allowed space IDs";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly allowedUserEmails: {
+            readonly type: "array";
+            readonly title: "Allowed user emails";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly digestMode: {
+            readonly type: "boolean";
+            readonly title: "Enable daily digest";
+            readonly default: false;
+        };
+        readonly dailyDigestTime: {
+            readonly type: "string";
+            readonly title: "Daily digest time (HH:MM)";
+            readonly default: "08:00";
+        };
+    };
+};
+/** Pure validator used by the worker's `onValidateConfig` hook and unit tests. */
+export declare function validateConfig(config: GoogleChatConfig): {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+};

package/dist/config.js

@@ -0,0 +1,73 @@
+/**
+ * Instance configuration for the Google Chat plugin.
+ *
+ * Secret values (Google Chat incoming-webhook URLs, an optional service-account
+ * key) are NEVER stored here in plaintext. The config holds **secret references**
+ * — opaque UUIDs minted by Paperclip's secret store — which the worker resolves at
+ * runtime via `ctx.secrets.resolve(ref)`. This mirrors the Telegram plugin's
+ * `telegramBotTokenRef` pattern and keeps credentials out of config exports/logs.
+ */
+export const DEFAULT_CONFIG = {
+    notifyOnIssueCreated: false,
+    notifyOnIssueCompleted: true,
+    notifyOnApprovalRequested: true,
+    notifyOnAgentRunFailed: true,
+    useCards: false,
+    enableCommands: true,
+    allowedSpaceIds: [],
+    allowedUserEmails: [],
+    digestMode: false,
+    dailyDigestTime: "08:00",
+};
+/** JSON-schema fragment surfaced in Paperclip's plugin settings UI. */
+export const INSTANCE_CONFIG_SCHEMA = {
+    type: "object",
+    properties: {
+        defaultWebhookUrlRef: {
+            type: "string",
+            title: "Default space webhook (secret ref)",
+            description: "Secret reference to a Google Chat incoming-webhook URL. Create the secret in Paperclip, paste the returned UUID here.",
+        },
+        approvalsWebhookUrlRef: { type: "string", title: "Approvals space webhook (secret ref)" },
+        errorsWebhookUrlRef: { type: "string", title: "Errors space webhook (secret ref)" },
+        digestWebhookUrlRef: { type: "string", title: "Digest space webhook (secret ref)" },
+        serviceAccountKeyRef: {
+            type: "string",
+            title: "Service-account key (secret ref, optional)",
+            description: "Only required for the Chat REST API (threaded replies). Webhook-only mode leaves this blank.",
+        },
+        notifyOnIssueCreated: { type: "boolean", title: "Notify on issue created", default: false },
+        notifyOnIssueCompleted: { type: "boolean", title: "Notify on issue completed", default: true },
+        notifyOnApprovalRequested: { type: "boolean", title: "Notify on approval requested", default: true },
+        notifyOnAgentRunFailed: { type: "boolean", title: "Notify on agent run failed", default: true },
+        useCards: { type: "boolean", title: "Use Cards v2 formatting", default: false },
+        enableCommands: { type: "boolean", title: "Enable inbound slash commands", default: true },
+        verificationTokenRef: { type: "string", title: "Verification token (secret ref)" },
+        allowedSpaceIds: { type: "array", title: "Allowed space IDs", items: { type: "string" } },
+        allowedUserEmails: { type: "array", title: "Allowed user emails", items: { type: "string" } },
+        digestMode: { type: "boolean", title: "Enable daily digest", default: false },
+        dailyDigestTime: { type: "string", title: "Daily digest time (HH:MM)", default: "08:00" },
+    },
+};
+/** Pure validator used by the worker's `onValidateConfig` hook and unit tests. */
+export function validateConfig(config) {
+    const errors = [];
+    const warnings = [];
+    if (config.dailyDigestTime && !/^([01]\d|2[0-3]):[0-5]\d$/.test(config.dailyDigestTime)) {
+        errors.push("dailyDigestTime must be 24h HH:MM, e.g. 08:00");
+    }
+    if (config.digestMode && !config.digestWebhookUrlRef && !config.defaultWebhookUrlRef) {
+        errors.push("digestMode is on but no digest/default webhook secret ref is set");
+    }
+    const anyNotify = config.notifyOnIssueCreated ||
+        config.notifyOnIssueCompleted ||
+        config.notifyOnApprovalRequested ||
+        config.notifyOnAgentRunFailed;
+    if (anyNotify && !config.defaultWebhookUrlRef) {
+        warnings.push("Notifications are enabled but no defaultWebhookUrlRef is set — category routing only.");
+    }
+    if (config.serviceAccountKeyRef === "") {
+        warnings.push("serviceAccountKeyRef is an empty string; leave it unset for webhook-only mode.");
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}

package/dist/constants.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Stable identifiers for the Google Chat plugin. Keeping these in one place keeps
+ * the manifest, worker, and tests in sync (the kitchen-sink reference plugin uses
+ * the same convention).
+ */
+export declare const PLUGIN_ID = "google-chat";
+export declare const PLUGIN_VERSION = "0.1.0";
+/** Webhook endpoint keys declared in the manifest and matched in `onWebhook`. */
+export declare const WEBHOOK_KEYS: {
+    /** Google Chat app events (MESSAGE, ADDED_TO_SPACE, CARD_CLICKED, …) POST here. */
+    readonly chatEvents: "chat-events";
+};
+/** Agent-callable tool names. */
+export declare const TOOL_NAMES: {
+    readonly postMessage: "post_to_google_chat";
+    readonly escalateToHuman: "escalate_to_human";
+    readonly sendBriefing: "send_briefing";
+};
+/** Scheduled job keys. */
+export declare const JOB_KEYS: {
+    readonly dailyDigest: "daily-digest";
+};
+/**
+ * Domain events we translate into Google Chat notifications. The host emits these;
+ * we subscribe via `ctx.events.on`. Names mirror the kitchen-sink event surface.
+ */
+export declare const DOMAIN_EVENTS: {
+    readonly issueCreated: "issue.created";
+    readonly issueUpdated: "issue.updated";
+    readonly issueCompleted: "issue.completed";
+    readonly approvalRequested: "approval.requested";
+    readonly agentRunFailed: "agent.run.failed";
+};

package/dist/constants.js

@@ -0,0 +1,33 @@
+/**
+ * Stable identifiers for the Google Chat plugin. Keeping these in one place keeps
+ * the manifest, worker, and tests in sync (the kitchen-sink reference plugin uses
+ * the same convention).
+ */
+export const PLUGIN_ID = "google-chat";
+export const PLUGIN_VERSION = "0.1.0";
+/** Webhook endpoint keys declared in the manifest and matched in `onWebhook`. */
+export const WEBHOOK_KEYS = {
+    /** Google Chat app events (MESSAGE, ADDED_TO_SPACE, CARD_CLICKED, …) POST here. */
+    chatEvents: "chat-events",
+};
+/** Agent-callable tool names. */
+export const TOOL_NAMES = {
+    postMessage: "post_to_google_chat",
+    escalateToHuman: "escalate_to_human",
+    sendBriefing: "send_briefing",
+};
+/** Scheduled job keys. */
+export const JOB_KEYS = {
+    dailyDigest: "daily-digest",
+};
+/**
+ * Domain events we translate into Google Chat notifications. The host emits these;
+ * we subscribe via `ctx.events.on`. Names mirror the kitchen-sink event surface.
+ */
+export const DOMAIN_EVENTS = {
+    issueCreated: "issue.created",
+    issueUpdated: "issue.updated",
+    issueCompleted: "issue.completed",
+    approvalRequested: "approval.requested",
+    agentRunFailed: "agent.run.failed",
+};

package/dist/events.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Domain-event → Google Chat notification mapping.
+ *
+ * The host emits domain events (issue lifecycle, approvals, agent runs). We
+ * subscribe in the worker and turn each into a `{ routeKey, text }` notification,
+ * gated by the per-event config toggles. The mapping is pure so it can be tested
+ * without the SDK; the worker performs the actual `postToWebhook`.
+ */
+import type { GoogleChatConfig } from "./config.js";
+import { type RouteKey } from "./google-chat.js";
+/** Loose shape of a host PluginEvent payload. */
+export interface DomainEvent {
+    type: string;
+    data?: Record<string, unknown>;
+}
+export interface Notification {
+    routeKey: RouteKey;
+    text: string;
+}
+/**
+ * Map a domain event to a notification, or null if the event is unmapped or its
+ * config toggle is off.
+ */
+export declare function mapEventToNotification(event: DomainEvent, config: GoogleChatConfig): Notification | null;

package/dist/events.js

@@ -0,0 +1,49 @@
+/**
+ * Domain-event → Google Chat notification mapping.
+ *
+ * The host emits domain events (issue lifecycle, approvals, agent runs). We
+ * subscribe in the worker and turn each into a `{ routeKey, text }` notification,
+ * gated by the per-event config toggles. The mapping is pure so it can be tested
+ * without the SDK; the worker performs the actual `postToWebhook`.
+ */
+import { DOMAIN_EVENTS } from "./constants.js";
+import { formatAgentRunFailed, formatApprovalRequested, formatIssueCompleted, formatIssueCreated, } from "./google-chat.js";
+function asIssue(data) {
+    const d = data ?? {};
+    return {
+        id: typeof d.id === "string" ? d.id : undefined,
+        title: typeof d.title === "string" ? d.title : undefined,
+        status: typeof d.status === "string" ? d.status : undefined,
+        url: typeof d.url === "string" ? d.url : undefined,
+    };
+}
+/**
+ * Map a domain event to a notification, or null if the event is unmapped or its
+ * config toggle is off.
+ */
+export function mapEventToNotification(event, config) {
+    switch (event.type) {
+        case DOMAIN_EVENTS.issueCreated:
+            if (!config.notifyOnIssueCreated)
+                return null;
+            return { routeKey: "default", text: formatIssueCreated(asIssue(event.data)) };
+        case DOMAIN_EVENTS.issueCompleted:
+            if (!config.notifyOnIssueCompleted)
+                return null;
+            return { routeKey: "default", text: formatIssueCompleted(asIssue(event.data)) };
+        case DOMAIN_EVENTS.approvalRequested:
+            if (!config.notifyOnApprovalRequested)
+                return null;
+            return { routeKey: "approvals", text: formatApprovalRequested(asIssue(event.data)) };
+        case DOMAIN_EVENTS.agentRunFailed: {
+            if (!config.notifyOnAgentRunFailed)
+                return null;
+            const d = event.data ?? {};
+            const agentName = typeof d.agentName === "string" ? d.agentName : "agent";
+            const errorMsg = typeof d.error === "string" ? d.error : "unknown error";
+            return { routeKey: "errors", text: formatAgentRunFailed(agentName, errorMsg) };
+        }
+        default:
+            return null;
+    }
+}