@mercury-fw/channel-google-chat 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @mercury-fw/channel-google-chat
 
+## 0.2.0
+
+### Minor Changes
+
+- 8bed46b: - A turn carries a `Principal` (the person behind it and the provider that vouched for them) instead of the opaque `userId` and `wikiUserId`; the core derives every per-person id from it.
+  - Episodic memory follows the principal, not the channel: a session is captured whenever a provider vouched for the person. Google Chat keeps the ids it had; the terminal and the HTTP channel (until it authenticates its callers) send a principal nobody vouched for, so they stay out of episodic memory as before.
+  - The HTTP channel accepts a `conversationId` on `/turn` and `/confirm` only made of letters, digits, `-` and `_`, up to 128 characters once trimmed, and answers `400` otherwise: a client-chosen id can no longer reach another user's wiki notes, forge log lines or break the turn. An existing HTTP conversation whose id has other characters can still be read with `/conversation`, but not continued. `/conversation` keeps opening any session key `/conversations` lists, whatever channel it came from.
+  - The model's wiki read tools refuse a per-user id that isn't one path segment, as writes already did.
+  - `CHANNEL_API_VERSION` is 2: a channel written for version 1 is refused at load.
+  - The first-party channels declare their channel api version as a literal, so an older channel can't claim a newer contract it doesn't implement.
+
+## 0.1.3
+
+### Patch Changes
+
+- 5e09c69: - README: a section on connecting a new app to a Chat app that already exists (finding the service account and the subscription, creating a key, `mfw google-chat set-key`).
+  - README: how to list and delete the keys the old instances left behind, before the service account reaches its limit of 10.
+  - README: `--project` on the `keys create` command of the setup.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -35,6 +35,7 @@ channels: [googleChatChannel],
   - [6. Configure the consent screen (Cloud Console)](#6-configure-the-consent-screen-cloud-console)
   - [7. Configure the Chat app (Cloud Console)](#7-configure-the-chat-app-cloud-console)
   - [8. Start and try it](#8-start-and-try-it)
+- [Connecting an app to an existing Chat app](#connecting-an-app-to-an-existing-chat-app)
 - [When the subscription disappears](#when-the-subscription-disappears)
 
 ## Setting up the Chat app
@@ -45,7 +46,7 @@ Everything goes through `gcloud` except two pages of Cloud Console (steps 6 and
 
 - a Google Workspace Business or Enterprise account: Chat apps don't exist for personal Gmail accounts;
 - `gcloud` logged in with that account (`gcloud auth login <you@company.com>`), allowed to create projects and link a billing account;
-- the app with its dependencies installed (`bun install`), for `bunx mfw` in step 5.
+- the app with its dependencies installed (`bun install`), for `mfw` in step 5.
 
 ### 1. Name things
 
@@ -100,7 +101,7 @@ gcloud pubsub subscriptions add-iam-policy-binding "$SUBSCRIPTION" \
   --project="$PROJECT_ID" \
   --member="serviceAccount:${SA_EMAIL}" \
   --role="roles/pubsub.subscriber"
-gcloud iam service-accounts keys create key.json --iam-account="$SA_EMAIL"
+gcloud iam service-accounts keys create key.json --iam-account="$SA_EMAIL" --project="$PROJECT_ID"
 ```
 
 A service account takes a few seconds to become visible to the rest of Google Cloud: if the binding fails saying the account doesn't exist, wait a moment and run it again.
@@ -108,7 +109,7 @@ A service account takes a few seconds to become visible to the rest of Google Cl
 Then, from the app's folder, write the key and the subscription into its `.env` with the app's own CLI, and delete the key file. The command replaces the lines `mfw create` left empty (or an older key), puts the private key on one line the way the channel reads it, and never prints it:
 
 ```bash
-bunx mfw google-chat set-key key.json --subscription "projects/${PROJECT_ID}/subscriptions/${SUBSCRIPTION}"
+mfw google-chat set-key key.json --subscription "projects/${PROJECT_ID}/subscriptions/${SUBSCRIPTION}"
 rm key.json
 ```
 
@@ -139,14 +140,50 @@ Click **Save**. The field names here come from Google's own Pub/Sub quickstart;
 
 ### 8. Start and try it
 
-Start the app (`bunx mfw start`) and check that the channel came up without errors:
+Start the app (`mfw start`) and check that the channel came up without errors:
 
 ```bash
-bunx mfw logs mercury
+mfw logs mercury
 ```
 
 `[channel] google-chat started` with no `pubsub stream error` after it means Mercury is pulling from the subscription. Then, in Google Chat, start a new chat and search the app's name (it shows up only for the people and groups in **Visibility**), or add it to a space; write to it and it answers.
 
+## Connecting an app to an existing Chat app
+
+When the Chat app is already set up and the Mercury instance behind it changes (the app scaffolded again, or moved to another machine), the new app only needs a key of the service account and the subscription's name in its `.env`. It replaces the old instance, it doesn't run next to it: stop the old one first, two instances on one subscription split the conversations between them.
+
+If you don't have the project's id at hand, `gcloud projects list` shows it; then the service account and the subscription:
+
+```bash
+PROJECT_ID=<the project's id>
+gcloud iam service-accounts list --project="$PROJECT_ID"
+gcloud pubsub subscriptions list --project="$PROJECT_ID" --format="value(name)"
+```
+
+```bash
+SA_EMAIL=<the EMAIL column of the service account Mercury runs as>
+SUBSCRIPTION=<the part after subscriptions/>
+```
+
+Then, from the new app's folder, create a key, write it into the `.env` with the subscription, and delete the key file:
+
+```bash
+gcloud iam service-accounts keys create key.json --iam-account="$SA_EMAIL" --project="$PROJECT_ID"
+mfw google-chat set-key key.json --subscription "projects/${PROJECT_ID}/subscriptions/${SUBSCRIPTION}"
+rm key.json
+```
+
+The old instance's key stays valid until you delete it, and a service account holds at most 10 keys, after which `keys create` fails. List them and delete the ones no instance uses anymore:
+
+```bash
+gcloud iam service-accounts keys list --iam-account="$SA_EMAIL" --project="$PROJECT_ID" --managed-by=user
+gcloud iam service-accounts keys delete <KEY_ID> --iam-account="$SA_EMAIL" --project="$PROJECT_ID"
+```
+
+The key the new app uses is the one with the latest `CREATED_AT`.
+
+Start it and check it as in [step 8](#8-start-and-try-it).
+
 ## When the subscription disappears
 
 A subscription created before `--expiration-period=never` was in step 4 still has the default policy, and Pub/Sub deletes it after 31 days without a pull. The channel then logs `NOT_FOUND` on the subscription, while the topic, the service account and the Chat app's configuration are all still there.
@@ -177,7 +214,7 @@ gcloud pubsub subscriptions add-iam-policy-binding "$SUBSCRIPTION" \
   --role="roles/pubsub.subscriber"
 ```
 
-Then restart the app (`bunx mfw restart`). The messages sent while the subscription was missing are lost, though: Pub/Sub keeps messages only for a subscription that exists.
+Then restart the app (`mfw restart`). The messages sent while the subscription was missing are lost, though: Pub/Sub keeps messages only for a subscription that exists.
 
 If the topic is gone too, redo steps 3 to 5 and, in step 7, paste the new topic in **Connection settings**.
 

package/dist/index.d.ts

@@ -7,5 +7,5 @@
  * missing is a misconfiguration: `build()` throws and the loader skips this
  * channel fail-soft, leaving the rest of Mercury up.
  */
-import { type ChannelPlugin } from "@mercury-fw/channel-types";
+import type { ChannelPlugin } from "@mercury-fw/channel-types";
 export declare const googleChatChannel: ChannelPlugin;

package/google-chat-provider.ts

@@ -505,8 +505,11 @@ export function createGoogleChatProvider(deps: GoogleChatProviderDeps): GoogleCh
           multiUser: !event.isDirectMessage,
           text: markedInput,
           sessionKey,
-          userId: event.sender,
-          wikiUserId: encodeURIComponent(event.sender),
+          principal: {
+            id: event.sender,
+            provider: "google-chat",
+            ...(event.senderDisplayName ? { displayName: event.senderDisplayName } : {}),
+          },
           logPrefix: `[chat:${event.space}:${event.sender}] `,
         },
         sink,

package/index.ts

@@ -7,7 +7,7 @@
  * missing is a misconfiguration: `build()` throws and the loader skips this
  * channel fail-soft, leaving the rest of Mercury up.
  */
-import { CHANNEL_API_VERSION, type ChannelPlugin, type ChannelRuntimeContext } from "@mercury-fw/channel-types";
+import type { ChannelPlugin, ChannelRuntimeContext } from "@mercury-fw/channel-types";
 import { createGoogleChatProvider } from "./google-chat-provider.ts";
 
 /** Reads a required env var, failing loudly (caught by the channel loader) instead of silently degrading. */
@@ -20,7 +20,9 @@ function require(env: ChannelRuntimeContext["env"], name: string): string {
 }
 
 export const googleChatChannel: ChannelPlugin = {
-  apiVersion: CHANNEL_API_VERSION,
+  // The contract this channel is written for, as a literal: importing
+  // CHANNEL_API_VERSION would report whichever contract is installed.
+  apiVersion: 2,
   name: "google-chat",
   build: (ctx) => {
     // No subscription configured ⇒ this instance simply doesn't run Google Chat.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-google-chat",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,12 +31,12 @@
     "@google-cloud/pubsub": "^5.3.1"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.24.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.34.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.28.1",
+    "@mercury-fw/channel-types": "0.34.0",
     "@mercury-fw/typescript-config": "*",
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"
   }
 }