paperclip-plugin-google-chat 0.1.0 → 0.1.2

package/README.md

@@ -73,6 +73,23 @@ src/
 
 Pure logic (formatting, parsing, routing, validation) is separated from the SDK-facing worker so it is unit-tested without a running Paperclip (`tests/`).
 
+## Adapter compatibility (important)
+
+The plugin's **worker-side** features work with **any** adapter, because they run in the
+plugin worker, not the agent:
+
+- ✅ **Event notifications** (`events.subscribe` → Chat)
+- ✅ **Inbound slash commands** (`webhooks.receive`)
+- ✅ **Daily digest job** (`jobs.schedule`)
+
+The **agent tools** (`post_to_google_chat`, `escalate_to_human`, `send_briefing`) are only
+callable by adapters whose tool calls are routed **through Paperclip's tool dispatcher**. They
+are **not available to `claude_local` / `codex_local` "process" adapters**, which run the CLI
+(e.g. `claude -p`) as a black-box subprocess — Paperclip captures stdout but never sees the
+agent's individual tool calls, so plugin tools can't be surfaced to them. For a CLI-based
+fleet, drive Chat via the event/webhook features above, or give the agent its own posting
+mechanism (an MCP server, or a direct webhook `curl`).
+
 ## Develop
 
 ```bash

package/dist/constants.d.ts

@@ -4,7 +4,7 @@
  * the same convention).
  */
 export declare const PLUGIN_ID = "google-chat";
-export declare const PLUGIN_VERSION = "0.1.0";
+export declare const PLUGIN_VERSION = "0.1.2";
 /** 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. */
@@ -21,13 +21,17 @@ 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.
+ * Domain events we translate into Google Chat notifications. These are exact
+ * members of the host's `PLUGIN_EVENT_TYPES` catalog (@paperclipai/shared),
+ * verified against the deployed release. The host has NO `issue.completed` or
+ * `approval.requested`: completion is an `issue.updated` to a terminal status,
+ * and an approval request is `approval.created`.
  */
 export declare const DOMAIN_EVENTS: {
     readonly issueCreated: "issue.created";
     readonly issueUpdated: "issue.updated";
-    readonly issueCompleted: "issue.completed";
-    readonly approvalRequested: "approval.requested";
+    readonly approvalCreated: "approval.created";
     readonly agentRunFailed: "agent.run.failed";
 };
+/** Issue statuses treated as "completed" for notification purposes. */
+export declare const TERMINAL_ISSUE_STATUSES: Set<string>;

package/dist/constants.js

@@ -4,7 +4,7 @@
  * the same convention).
  */
 export const PLUGIN_ID = "google-chat";
-export const PLUGIN_VERSION = "0.1.0";
+export const PLUGIN_VERSION = "0.1.2";
 /** 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. */
@@ -21,13 +21,17 @@ 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.
+ * Domain events we translate into Google Chat notifications. These are exact
+ * members of the host's `PLUGIN_EVENT_TYPES` catalog (@paperclipai/shared),
+ * verified against the deployed release. The host has NO `issue.completed` or
+ * `approval.requested`: completion is an `issue.updated` to a terminal status,
+ * and an approval request is `approval.created`.
  */
 export const DOMAIN_EVENTS = {
     issueCreated: "issue.created",
     issueUpdated: "issue.updated",
-    issueCompleted: "issue.completed",
-    approvalRequested: "approval.requested",
+    approvalCreated: "approval.created",
     agentRunFailed: "agent.run.failed",
 };
+/** Issue statuses treated as "completed" for notification purposes. */
+export const TERMINAL_ISSUE_STATUSES = new Set(["done", "completed", "closed"]);

package/dist/events.js

@@ -6,7 +6,7 @@
  * 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 { DOMAIN_EVENTS, TERMINAL_ISSUE_STATUSES } from "./constants.js";
 import { formatAgentRunFailed, formatApprovalRequested, formatIssueCompleted, formatIssueCreated, } from "./google-chat.js";
 function asIssue(data) {
     const d = data ?? {};
@@ -27,11 +27,17 @@ export function mapEventToNotification(event, config) {
             if (!config.notifyOnIssueCreated)
                 return null;
             return { routeKey: "default", text: formatIssueCreated(asIssue(event.data)) };
-        case DOMAIN_EVENTS.issueCompleted:
+        case DOMAIN_EVENTS.issueUpdated: {
+            // The host has no `issue.completed`; completion surfaces as an update to a
+            // terminal status. Only notify on that transition, not every edit.
             if (!config.notifyOnIssueCompleted)
                 return null;
-            return { routeKey: "default", text: formatIssueCompleted(asIssue(event.data)) };
-        case DOMAIN_EVENTS.approvalRequested:
+            const issue = asIssue(event.data);
+            if (!issue.status || !TERMINAL_ISSUE_STATUSES.has(issue.status.toLowerCase()))
+                return null;
+            return { routeKey: "default", text: formatIssueCompleted(issue) };
+        }
+        case DOMAIN_EVENTS.approvalCreated:
             if (!config.notifyOnApprovalRequested)
                 return null;
             return { routeKey: "approvals", text: formatApprovalRequested(asIssue(event.data)) };

package/dist/manifest.d.ts

@@ -1,167 +1,10 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
 /**
  * Paperclip plugin manifest (apiVersion 1). Declares the capability grants the
  * host enforces and the surfaces the worker registers. Keep capabilities minimal —
- * the host blocks any API call whose capability is not declared here.
+ * the host blocks any API call whose capability is not declared here. The
+ * PaperclipPluginManifestV1 annotation makes tsc validate field names against the
+ * host schema (e.g. jobs[].jobKey), so manifest drift fails the build, not install.
  */
-declare const manifest: {
-    readonly id: "google-chat";
-    readonly apiVersion: 1;
-    readonly version: "0.1.0";
-    readonly displayName: "Google Chat";
-    readonly description: "Bidirectional Google Chat bridge: posts issue/agent/approval notifications to spaces and drives Paperclip from Chat slash commands.";
-    readonly author: "Measured Assets";
-    readonly categories: readonly ["connector", "automation"];
-    readonly capabilities: readonly ["companies.read", "projects.read", "issues.read", "issues.create", "issues.update", "issue.comments.read", "issue.comments.create", "agents.read", "agents.invoke", "agent.sessions.create", "agent.sessions.send", "goals.read", "events.subscribe", "jobs.schedule", "http.outbound", "secrets.read-ref", "webhooks.receive", "agent.tools.register", "activity.log.write", "plugin.state.read", "plugin.state.write", "instance.settings.register"];
-    readonly entrypoints: {
-        readonly worker: "./dist/worker.js";
-    };
-    readonly instanceConfigSchema: {
-        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";
-            };
-        };
-    };
-    readonly webhooks: readonly [{
-        readonly endpointKey: "chat-events";
-        readonly displayName: "Google Chat events";
-        readonly description: "Configure your Google Chat app's HTTP endpoint to POST events here (MESSAGE, ADDED_TO_SPACE, CARD_CLICKED).";
-    }];
-    readonly jobs: readonly [{
-        readonly key: "daily-digest";
-        readonly displayName: "Daily digest";
-        readonly description: "Posts a once-daily summary to the digest space when digestMode is enabled.";
-        readonly schedule: "0 * * * *";
-    }];
-    readonly tools: readonly [{
-        readonly name: "post_to_google_chat";
-        readonly displayName: "Post to Google Chat";
-        readonly description: "Post a plain-text or Markdown message to a configured Google Chat space.";
-        readonly parametersSchema: {
-            readonly type: "object";
-            readonly properties: {
-                readonly text: {
-                    readonly type: "string";
-                    readonly description: "Message body (Google Chat Markdown supported).";
-                };
-                readonly space: {
-                    readonly type: "string";
-                    readonly description: "Optional routing key: default | approvals | errors | digest. Defaults to 'default'.";
-                };
-            };
-            readonly required: readonly ["text"];
-        };
-    }, {
-        readonly name: "escalate_to_human";
-        readonly displayName: "Escalate to human (Google Chat)";
-        readonly description: "Post an escalation message to the approvals space and ask a human to respond.";
-        readonly parametersSchema: {
-            readonly type: "object";
-            readonly properties: {
-                readonly message: {
-                    readonly type: "string";
-                };
-                readonly issueId: {
-                    readonly type: "string";
-                    readonly description: "Optional Paperclip issue id for context.";
-                };
-            };
-            readonly required: readonly ["message"];
-        };
-    }, {
-        readonly name: "send_briefing";
-        readonly displayName: "Send briefing (Google Chat)";
-        readonly description: "Post a formatted briefing/report to the digest space (used by scheduled briefing routines).";
-        readonly parametersSchema: {
-            readonly type: "object";
-            readonly properties: {
-                readonly title: {
-                    readonly type: "string";
-                };
-                readonly body: {
-                    readonly type: "string";
-                };
-            };
-            readonly required: readonly ["body"];
-        };
-    }];
-};
+declare const manifest: PaperclipPluginManifestV1;
 export default manifest;

package/dist/manifest.js

@@ -3,7 +3,9 @@ import { JOB_KEYS, PLUGIN_ID, PLUGIN_VERSION, TOOL_NAMES, WEBHOOK_KEYS } from ".
 /**
  * Paperclip plugin manifest (apiVersion 1). Declares the capability grants the
  * host enforces and the surfaces the worker registers. Keep capabilities minimal —
- * the host blocks any API call whose capability is not declared here.
+ * the host blocks any API call whose capability is not declared here. The
+ * PaperclipPluginManifestV1 annotation makes tsc validate field names against the
+ * host schema (e.g. jobs[].jobKey), so manifest drift fails the build, not install.
  */
 const manifest = {
     id: PLUGIN_ID,
@@ -55,7 +57,7 @@ const manifest = {
     ],
     jobs: [
         {
-            key: JOB_KEYS.dailyDigest,
+            jobKey: JOB_KEYS.dailyDigest,
             displayName: "Daily digest",
             description: "Posts a once-daily summary to the digest space when digestMode is enabled.",
             // Hourly tick; the handler self-gates to the configured HH:MM.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclip-plugin-google-chat",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Bidirectional Google Chat integration for Paperclip — post agent/issue notifications to spaces and drive Paperclip from Chat slash commands.",
   "type": "module",
   "license": "MIT",