clawmini 0.0.3 → 0.0.5

package/docs/22_adapter_multi_chat/development_log.md

@@ -0,0 +1,76 @@
+# Development Log
+
+## Session 1
+- Initialised Ticket 1: Update State and Config Schemas for Multi-Chat Support.
+- Verified schema changes for Discord and Google Chat adapters in git diff.
+- Identified test failures in `npm run validate`.
+- Fixed `channelChatMap` to be an object instead of a string array in test and code logic for `src/adapter-discord/client.test.ts`, `src/adapter-discord/client.ts`, `src/adapter-discord/state.test.ts`, `src/adapter-discord/forwarder.ts`.
+- Updated schema typing to allow undefined explicitly where required, maintaining strict structural compatibility.
+- Re-run `npm run validate`, successfully passing all checks.
+- Completed Ticket 1 in `tickets.md` and committed all changes.
+
+## Session 2
+- Started work on Ticket 2: Implement "First Contact" Protocol (Discord).
+- Refactored `startDiscordIngestion` in `src/adapter-discord/client.ts` to implement the required First Contact logic:
+  - Check if `targetChatId` is mapped for a given channel.
+  - If not, verify if it's the very first message processed by the adapter by checking if `channelChatMap` is empty.
+  - Automatically map the first channel to `config.chatId` (default) and process the message.
+  - If it's not the first message, reply with a strict, non-processed warning indicating the channel is unmapped and block the message from daemon propagation.
+- Verified and fixed Discord tests to ensure correct behaviour:
+  - Ensured routing commands correctly populate `channelChatMap`.
+  - Added new mock properties `mockMessage.reply` and modified expected return shapes so subsequent tests relying on default properties (like `channelChatMap`) don't fail.
+- When mocking discord.js Messages, ensure they match the properties required by the code paths (e.g. `channelId`, `attachments`, `reply`).
+- Confirmed all checks (`npm run validate`) pass properly.
+
+## Session 3
+- Started work on Ticket 3: Implement Dynamic Subscriptions (Discord Forwarder).
+- Updated `startDaemonToDiscordForwarder` in `src/adapter-discord/forwarder.ts` to:
+  - Establish `trpc.waitForMessages.subscribe` for each chat mapped in `state.channelChatMap`.
+  - Track `lastSyncedMessageIds` for each daemon chat independently rather than globally.
+  - Set up an `fs.watch` event listener on `state.json` to dynamically synchronize subscriptions on changes.
+  - Correctly extract the target `channelId` to post messages by doing a reverse lookup on `state.channelChatMap`.
+- Resolved a Vitest unhandled rejection hook failure where a thrown Error during `syncSubscriptions` wasn't properly caught within an async boundary.
+- Fixed a bug causing an infinite loop in Vitest caused by `setInterval` inside `vi.runAllTimersAsync()` by refactoring tests to use `vi.advanceTimersByTimeAsync(30000)` instead.
+- Confirmed all checks (`npm run validate`) pass properly.
+
+## Session 4
+- Started work on Ticket 5: Add Google Chat Space Subscription Config & State Schemas.
+- Updated `GoogleChatStateSchema` in `src/adapter-google-chat/state.ts` to use an object for `channelChatMap` handling space subscriptions (`chatId`, `subscriptionId`, `expirationDate`).
+- Added schema migration paths in `readGoogleChatState` to support single-chat legacy formats and migrated `driveOauthTokens` to `oauthTokens`.
+- Replaced `driveOauthClientId` and `driveOauthClientSecret` with generic `oauthClientId` and `oauthClientSecret` in `src/adapter-google-chat/config.ts`.
+- Updated `src/adapter-google-chat/auth.ts` to use `getUserAuthClient()` matching the required new OAuth flows and multiple scopes for Drive and Chat readonly.
+- Updated `src/adapter-google-chat/index.ts` to initialize `getUserAuthClient()` when OAuth secrets are present.
+- Updated numerous test files to accommodate the structural schema changes and OAuth renaming.
+- Successfully verified tests passing using `npm run validate`.
+- Marked Ticket 5 as Completed.
+
+## Session 5
+- Implemented Ticket 6: Space Subscription Lifecycle (`ADDED_TO_SPACE` & `REMOVED_FROM_SPACE`).
+- Extracted `handleAddedToSpace` and `handleRemovedFromSpace` into `src/adapter-google-chat/subscriptions.ts` to keep `client.ts` clean and below the line limits.
+- Extracted `handleCardClicked` into `src/adapter-google-chat/cards.ts` to reduce `client.ts` file length.
+- Added API calls to `https://workspaceevents.googleapis.com/v1/subscriptions` using the Google User's OAuth tokens to dynamically subscribe to `google.workspace.chat.message.v1.created` when the bot is added to spaces.
+- Intercepted `ADDED_TO_SPACE` and `REMOVED_FROM_SPACE` early in the Google Chat ingestion pipeline to bypass the first contact unmapped warnings.
+- Updated `client.test.ts` to simulate and test subscriptions logic accurately using mock fetch interactions.
+- Resolved various TypeScript alignment errors around strict typing of `mappedChatId` and nested objects inside the state JSON configuration.
+
+## Session 6
+- Implemented Ticket 7: Dual-Pipeline Pub/Sub Worker Logic.
+- Updated `startGoogleChatIngestion` in `src/adapter-google-chat/client.ts` to process native Bot Events and Workspace Events.
+- Implemented a 60-second LRU cache (using Map) to deduplicate Message IDs and drop duplicate messages when the bot is mentioned and triggering both pipelines.
+- Added explicit sender type check to drop messages from `BOT` to prevent infinite reply loops.
+- Added tests simulating Workspace Event payloads and Bot Event payloads.
+- Verified test coverage for duplicate IDs and BOT message dropping.
+- Fixed linter warnings about missing `const` and explicit `any` types.
+- Fixed maximum line constraints by simplifying logical conditionals.
+- Ran `npm run validate` which passed format, lint, check, and unit/E2E tests.
+
+## Session 7
+- Implemented Ticket 8: Background Renewal Cron for Subscriptions.
+- Created `src/adapter-google-chat/cron.ts` to run a `setInterval` cron task every hour.
+- Logic checks `channelChatMap` in `state.json` and patches subscriptions expiring in less than 48 hours to extend TTL to 7 days.
+- Extracted and reused `getUserAuthClient` logic to grab access tokens.
+- Created unit tests in `src/adapter-google-chat/cron.test.ts` to verify the cron executes and triggers fetches accurately based on mocked expiration dates.
+- Updated `src/adapter-google-chat/index.ts` to import and start the cron on adapter initialization.
+- Fixed TS compilation and ESLint strict type-checking issues with `unknown` casting in mock types.
+- Ran `npm run format` and `npm run validate` which passed all format, lint, check, and tests.
+- Marked Ticket 8 as Completed.

package/docs/22_adapter_multi_chat/notes.md

@@ -0,0 +1,42 @@
+# Notes on Adapter Multi-Chat Support
+
+## Current State
+
+### Discord Adapter
+- The bot initializes a single `daemon-to-discord` forwarder, listening to a single `chatId` (configured in `config.chatId` or falling back to `'default'`).
+- In `src/adapter-discord/index.ts`, the incoming message handler explicitly ignores messages that occur in a guild (`if (message.guild) return;`). It only processes DMs.
+- It validates the sender against `config.authorizedUserId`.
+- When forwarding to the daemon, it always uses `config.chatId`.
+
+### Google Chat Adapter
+- The bot initializes a single forwarder, listening to `config.chatId` or `'default'`.
+- It maintains an `activeSpaceName` in state which determines where the forwarder sends replies. This means it essentially only supports a 1:1 mapping between one daemon chat and one active Google Chat space at a time.
+- Incoming messages from Pub/Sub (ingestion) are sent to the single `chatId`.
+
+## Requirements for Multi-Chat Support
+
+1. **Mapping Configuration**:
+   - We need a way to map an external context (e.g., Discord Channel ID, Discord Thread ID, Google Space ID) to a specific Daemon Chat ID.
+   - This mapping could be stored in the adapter's state (`state.json`) so it persists across restarts.
+2. **Dynamic Subscriptions**:
+   - The forwarder functions (`startDaemonToDiscordForwarder` and `startDaemonToGoogleChatForwarder`) currently subscribe to a single `chatId` via `trpc.waitForMessages.subscribe`.
+   - To support multiple chats, the adapter must maintain a dynamic list of subscriptions, adding new ones as new mappings are created.
+3. **Handling Incoming Messages**:
+   - **Discord**: Remove the `if (message.guild) return;` block. Allow messages in channels/threads, but *only* if the user is authorized and perhaps if the bot is explicitly mentioned or configured to listen to that channel.
+   - When an incoming message arrives, determine its external context ID (e.g. `message.channelId` in Discord).
+   - Look up the mapped Daemon Chat ID. If none exists, use a default behavior (e.g., use the user's default chat, or create a new chat for that context).
+4. **User Commands for Routing**:
+   - The user needs a way to say "route this channel to chat X" or "route this channel to agent Y".
+   - This could be implemented via adapter-level chat commands (e.g., `!chat <id>`, `!agent <id>`).
+   - The adapter would need to validate these IDs against the daemon's TRPC API (`trpc.getChats`, `trpc.getAgents`).
+
+## Space Subscriptions (Google Chat) Research
+- `src/adapter-google-chat/state.ts`: The `GoogleChatStateSchema` needs its `channelChatMap` updated to store subscription info alongside the chat ID. It should be: `channelChatMap: z.record(z.string(), z.object({ chatId: z.string().nullable().optional(), subscriptionId: z.string().optional(), expirationDate: z.string().optional() })).optional()`. We need a migration to convert existing `Record<string, string>` formats into this object format.
+- `src/adapter-google-chat/auth.ts`: Currently handles Bot auth (Service Account) and Drive Auth (OAuth2 with offline access). We need to adapt the OAuth flow to request Google Chat scopes (likely `https://www.googleapis.com/auth/chat.messages.readonly` or similar depending on the exact event subscription) and capture the refresh token for the user. 
+- `src/adapter-google-chat/client.ts`: The `startGoogleChatIngestion` function currently handles `MESSAGE` and `CARD_CLICKED` events. We must update it to:
+  1. Handle `ADDED_TO_SPACE` natively (if `space.type !== "DIRECT_MESSAGE"`) to create space subscriptions using the globally saved user OAuth tokens and save the result to state.
+  2. Handle `REMOVED_FROM_SPACE` to cleanly delete the subscription and state entry.
+  3. Distinguish between Workspace Events (via the `ce-type` Pub/Sub attribute) and native Bot Events.
+  4. Deduplicate messages based on Message ID using a 60-second in-memory cache to prevent processing the same message twice when the bot is `@mentioned` in a subscribed space.
+  5. Drop messages where `sender === 'BOT'` to prevent infinite loops.
+- Background Renewal: We need to implement a mechanism (e.g., an hourly `setInterval` inside the adapter process or a separate cron) to check `expirationDate` of space subscriptions and renew those expiring in < 48 hours via `PATCH /v1/subscriptions/{id}`.

package/docs/22_adapter_multi_chat/prd.md

@@ -0,0 +1,76 @@
+# Product Requirements Document: Adapter Multi-Chat Support
+
+## Vision
+To provide a seamless, multi-threaded conversational experience across chat platforms (Discord and Google Chat) by allowing users to map distinct channels or spaces to different internal daemon chats or agents. This ensures users can context-switch effectively without mixing separate tasks or agent workflows in a single monolithic adapter stream.
+
+## Product/Market Background
+Currently, the Clawmini bot integrates with external messaging platforms (Discord, Google Chat) using a simple 1:1 mapping strategy. The adapter connects to a single default daemon chat, meaning every message sent to the bot on that platform—regardless of the specific channel or thread—gets funneled into the same daemon conversation. As power users leverage specialized agents or distinct long-running chats, they need the ability to maintain concurrent, isolated workflows by directing different Discord channels or Google Chat spaces to different backend chats.
+
+## Use Cases
+1. **Context Separation:** A user is in a Discord server and creates two channels: `#coding-help` and `#general-research`. They want `#coding-help` routed to a dedicated coding chat/agent, and `#general-research` routed to their default chat.
+2. **On-the-Fly Agent Spawning:** A user in Google Chat wants to consult an expert agent for a specific topic. They create a new Space, invite the bot, and use `/agent expert-coder` to immediately spin up a new chat session bound to that Space.
+3. **Safe Defaults:** A user accidentally starts talking to the bot in a new channel without configuring it. The bot intercepts the message, warns them that the channel isn't configured, and provides instructions on how to route the channel.
+4. **Reliable Google Chat Event Subscriptions:** A user adds the bot to a new Space, expecting it to process all messages in that space (not just `@mentions`). The bot uses user-level OAuth to subscribe to Workspace Events natively, keeping the subscription alive in the background so no messages are missed.
+
+## Requirements
+
+### 1. Adapter State & 1:1 Mapping
+- **State Schema Updates:** The `state.json` schema for both adapters must be updated:
+  - Add `channelChatMap: Record<string, string>` to map external context IDs (Channel ID / Space ID) to Daemon Chat IDs.
+  - Change `lastSyncedMessageId: string` to `lastSyncedMessageIds: Record<string, string>` to track the sync state for each individual chat independently.
+  - **Google Chat Specific:** Add `spaceSubscriptions: Record<string, { subscriptionId: string, expirationDate: string, refreshToken: string }>` to manage the lifecycle of user-level space event subscriptions.
+- **Strict 1:1 Mapping Constraint:** To prevent "echo" loops where a single daemon message broadcasts to multiple external channels, multiple channels/spaces **cannot** be mapped to the same daemon chat. If a user attempts to route a channel to a chat that is already mapped elsewhere, the bot will reject the command with an error indicating which channel is currently using it.
+
+### 2. The "First Contact" Protocol
+- **Detection:** When an incoming message is received from an authorized user in a context (channel/space) that does not exist in the `channelChatMap`.
+- **Interception:** If the message is *not* a routing command (i.e. not starting with `/chat` or `/agent`), the message is **not** forwarded to the daemon.
+- **Onboarding Reply:** The bot replies with an instructional message:
+  - "This channel/space is not currently mapped to a specific chat."
+  - "To route this channel to an existing chat, use `/chat <chat-id>`."
+  - "To route this channel to a specific agent, use `/agent <agent-id>`."
+- **Persistent Warning:** The bot will continue to intercept and reply with this warning for every subsequent message until the user explicitly runs `/chat` or `/agent` to configure the channel. There is no automatic fallback.
+
+### 3. Routing Commands
+- **Command Handling:** The adapters must intercept messages starting with `/chat` and `/agent` *before* sending them to the daemon.
+- **`/chat [chat-id]`**:
+  - Fetches the list of all chats via `trpc.getChats.query()`.
+  - If no `[chat-id]` is provided, or if the provided ID does not exist, replies with a formatted list of all available chats.
+  - Checks if `[chat-id]` is already mapped to a *different* channel in `channelChatMap`. If so, returns an error.
+  - If valid and available, updates `channelChatMap` to map the current channel/space to `[chat-id]`.
+  - Replies with confirmation: "This channel is now routed to chat: `[chat-id]`."
+- **`/agent [agent-id]`**:
+  - Fetches the list of all agents via `trpc.getAgents.query()`.
+  - If no `[agent-id]` is provided, or if the provided ID does not exist, replies with a formatted list of all available agents.
+  - If `[agent-id]` exists, generates a new chat ID formatted as `<agent-id>-<adapter-name>`. If a chat with that ID already exists, it appends a number (e.g., `<agent-id>-<adapter-name>-1`, `-2`, etc.) until a unique ID is found.
+  - Uses a TRPC endpoint to explicitly instruct the daemon to create the new chat and assign the specified agent to it.
+  - Updates `channelChatMap` to point to the newly generated chat ID.
+  - Replies with confirmation: "Created new chat and routed this channel to it: `<new-chat-id>` using agent `[agent-id]`."
+
+### 4. Dynamic Forwarding Subscriptions
+- **Forwarder Adjustments:** Currently, the forwarders establish a single subscription to the default `chatId` using `trpc.waitForMessages.subscribe`.
+- **Multi-Subscription:** The forwarders must be updated to manage subscriptions for *all* `chatIds` actively mapped in `channelChatMap`.
+- **Dynamic Updates:** When a command (`/chat` or `/agent`) updates the map, the forwarder must dynamically establish a subscription to the newly mapped `chatId`. It must track `lastSyncedMessageIds[chatId]` independently to resume correctly.
+
+### 5. Platform-Specific Details
+- **Discord:**
+  - Remove the restriction that ignores messages in guilds (`if (message.guild) return;`).
+  - Continue to rigorously enforce the `authorizedUserId` check. Only process commands and messages from the authorized user.
+  - **Mention Requirement:** Introduce a new adapter configuration property `requireMention` (boolean, defaults to `false`).
+    - If `false` (default): The bot responds to all messages from the authorized user in a mapped channel (assuming most channels are just the user + bot).
+    - If `true`: The bot will only process messages in mapped *Guild (Server) channels* if the bot is explicitly `@mentioned` (or the message is a direct reply to the bot). Direct Messages (DMs) bypass this check and are always processed.
+- **Google Chat (Space Subscriptions):**
+  - **OAuth Upgrade:** Rename legacy `driveOauthClientId`, `driveOauthClientSecret`, and `driveOauthTokens` to generic `oauthClientId`, `oauthClientSecret`, and `oauthTokens` in state and config. Update the OAuth flow in `auth.ts` to request a combined scope array: `['https://www.googleapis.com/auth/drive.file', 'https://www.googleapis.com/auth/chat.messages.readonly']` and `access_type=offline` to capture a user-level Refresh Token. Ensure `index.ts` unconditionally initializes the `getUserAuthClient()` flow if OAuth credentials exist, regardless of the `driveUploadEnabled` setting.
+  - **`ADDED_TO_SPACE` Creation:** Intercept `ADDED_TO_SPACE` events natively. For non-DM spaces, use the globally stored user OAuth tokens to generate an Access Token and `POST https://workspaceevents.googleapis.com/v1/subscriptions` to subscribe to `google.workspace.chat.message.v1.created` using the configured notification endpoint topic. Save `subscriptionId` and `expirationDate` to the channel's entry in `channelChatMap` in `state.json`.
+  - **Background Renewal Cron:** Establish a daily recurring task that checks `channelChatMap` entries for expirations < 48 hours away. For those nearing expiration, fetch a fresh Access Token using the globally saved user OAuth tokens and `PATCH /v1/subscriptions/{id}` to renew the `ttl`, then save the new `expirationDate`.
+  - **`REMOVED_FROM_SPACE` Cleanup:** Intercept removal events to gracefully issue a `DELETE` request for the corresponding subscription ID and remove the subscription fields (or the entire entry if `chatId` is not set) from `channelChatMap` in `state.json`.
+  - **Dual-Pipeline Ingestion & Deduplication:** The Pub/Sub worker will receive both native Bot Events and new Workspace Events (from space subscriptions). It must:
+    1. Identify the source via the `ce-type` attribute (if `google.workspace.chat.message.v1.created`, parse as Workspace Event; else, native Bot Event).
+    2. Explicitly drop messages where the sender is `BOT` to prevent infinite reply loops.
+    3. Maintain a 60-second in-memory LRU cache of processed Message IDs. If a bot `@mention` causes an event in both pipelines, drop the duplicate.
+    4. Send all replies via the Bot's Service Account (not the user's token).
+
+## Privacy, Security & Accessibility
+- **Authorization:** Only the explicitly `authorizedUserId` (Discord) or authorized emails (Google Chat) can trigger the First Contact protocol or use the `/chat` and `/agent` commands. All other users in the channel are strictly ignored.
+- **Information Disclosure:** Validating chat and agent IDs prevents users from accidentally creating junk records in the state. 
+- **Noise Reduction:** The persistent warning and strict requirement for manual configuration prevents random channel chatter from polluting backend contexts. The `requireMention` setting in Discord provides an opt-in safety net for shared public channels.
+- **Google Chat User Tokens:** User Refresh Tokens must be securely persisted locally in `state.json` solely for the purpose of maintaining space subscriptions. They must not be transmitted externally. The adapter must strictly reply to Google Chat using the bot's service account, keeping the user's identity decoupled from bot actions.e user's identity decoupled from bot actions.he bot's service account, keeping the user's identity decoupled from bot actions.e user's identity decoupled from bot actions.

package/docs/22_adapter_multi_chat/questions.md

@@ -0,0 +1,16 @@
+# Questions
+
+1. **Explicit Routing Syntax:** To allow users to specify a chat or agent for a channel, what syntax should be used?
+   - **Answer:** We generally use slash commands, so `/chat <id>` or `/agent <id>`. If we use `/agent <id>`, we should create a new chat named `<agent-id>-<adapter-name>-1` and display it to the user so they know which chat it is.
+
+2. **New Contexts Default Behavior:** When a user sends a message in a *new* Discord channel or Google Chat space (where no mapping exists yet), what is the default behavior?
+   - **Answer:** The first message from a user (if not a `/chat` or `/agent` command) should be ignored in terms of passing it to the daemon. Instead, the bot should reply telling the user to use `/chat` or `/agent` to configure the channel, or inform them that if they continue talking, it will use the default chat (and explicitly state which chat that is).
+
+3. **Discord Scope:** In Discord, should we respond to *all* messages in a channel from authorized users, or only when the bot is `@mentioned`?
+   - **Answer:** We will respond to all messages from the authorized user in the mapped channel without requiring a `@mention`, as the new-channel onboarding flow explicitly tells them they can "continue talking" to use the default chat. (Bot and unauthorized user messages will continue to be ignored).
+
+4. **Validation API:** To validate if a user-specified chat or agent exists, should the adapters use new or existing TRPC queries (e.g., `trpc.getChats` / `trpc.getAgents`)?
+   - **Answer:** Using the existing list queries (`trpc.getChats` / `trpc.getAgents`) is fine because there won't be a massive number of entities to filter through.
+
+5. **Mapping Storage:** Should the mapping of `(Adapter Channel/Space ID) -> (Daemon Chat ID)` be stored in the adapter's local `state.json`?
+   - **Answer:** Yes, it should be added to the adapter's existing `state.json`.

package/docs/22_adapter_multi_chat/tickets.md

@@ -0,0 +1,164 @@
+# Tickets for Adapter Multi-Chat Support
+
+## Ticket 1: Update State and Config Schemas for Multi-Chat Support
+**Status**: Completed
+
+**Description**: 
+Update the state and configuration schemas for both the Discord and Google Chat adapters to prepare for multi-chat mapping and independent state tracking.
+
+**Tasks**:
+- Update adapter state schemas in `src/adapter-discord` and `src/adapter-google-chat` to replace `lastSyncedMessageId: string` with `lastSyncedMessageIds: Record<string, string>`.
+- Add `channelChatMap: Record<string, string>` to the state schemas to map external context IDs (Channel ID / Space ID) to Daemon Chat IDs.
+- Update the Discord adapter config schema to include an optional `requireMention: boolean` property, defaulting to `false`.
+- Ensure backwards compatibility or safe migration for existing `state.json` files.
+
+**Verification**:
+- Verify schema changes by running tests that instantiate the adapters with updated and legacy configurations.
+- Run `npm run validate` (which includes `npm run format`, `npm run lint:fix`, type-checking, and tests).
+
+---
+
+## Ticket 2: Implement First Contact Protocol and Message Pre-processing
+**Status**: Completed
+
+**Description**: 
+Adjust the message ingestion pipeline for both adapters to handle incoming messages in new contexts and implement platform-specific filtering rules.
+
+**Tasks**:
+- **Discord**: Remove the `if (message.guild) return;` block to allow processing messages in server channels/threads.
+- **Discord**: Implement logic to enforce the `requireMention` config flag. If true, ignore messages in guild channels unless the bot is explicitly `@mentioned` or directly replied to. DM behavior remains unaffected.
+- **Both Adapters**: Implement the "First Contact" protocol. Before forwarding a message to the daemon, check if the external context ID (Discord channel ID or Google Chat space ID) exists in `channelChatMap`.
+- If unmapped and the message is *not* a routing command (`/chat` or `/agent`), intercept the message, do not forward it, and reply with the instructional warning: "This channel/space is not currently mapped...".
+
+**Verification**:
+- Write unit tests for Discord message filtering (e.g., verifying `requireMention` behavior for guilds vs DMs).
+- Write unit tests for the First Contact protocol interception logic.
+- Run `npm run validate`.
+
+---
+
+## Ticket 3: Implement Routing Commands (`/chat` and `/agent`)
+**Status**: Completed
+
+**Description**: 
+Allow users to dynamically map their current external context (channel/space) to a specific daemon chat or a new chat with a specific agent.
+
+**Tasks**:
+- Intercept and handle the `/chat [chat-id]` command:
+  - Fetch available chats via `trpc.getChats.query()`. Reply with a formatted list if the provided ID is missing or invalid.
+  - Enforce the **Strict 1:1 Mapping Constraint**: Return an error if the requested chat is already mapped to a different channel.
+  - Upon success, update `channelChatMap` to point the current channel to the requested chat, save state, and reply with confirmation.
+- Intercept and handle the `/agent [agent-id]` command:
+  - Fetch available agents via `trpc.getAgents.query()`. Reply with a formatted list if the provided ID is missing or invalid.
+  - If valid, generate a unique chat ID (`<agent-id>-<adapter-name>[-n]`).
+  - Instruct the daemon to create the new chat and assign the agent.
+  - Update `channelChatMap` to point to the newly created chat ID, save state, and reply with confirmation.
+
+**Verification**:
+- Write unit tests for command parsing, list formatting, and 1:1 constraint validation.
+- Mock TRPC endpoints in tests to verify correct interaction with the daemon for fetching lists and creating chats.
+- Run `npm run validate`.
+
+---
+
+## Ticket 4: Implement Dynamic Forwarding Subscriptions
+**Status**: Completed
+
+**Description**: 
+Refactor the daemon-to-adapter forwarding logic to support multiple concurrent subscriptions and dynamic updates based on `channelChatMap`.
+
+**Tasks**:
+- Refactor `startDaemonToDiscordForwarder` and `startDaemonToGoogleChatForwarder` to manage a dynamic pool of `trpc.waitForMessages.subscribe` subscriptions instead of a single static one.
+- The forwarders should iterate over unique `chatIds` in `channelChatMap` and establish a subscription for each.
+- Implement an event or polling mechanism so that when `channelChatMap` changes (e.g., a new routing command is executed), the forwarder dynamically establishes subscriptions for newly mapped chats.
+- Ensure the forwarder uses and updates `lastSyncedMessageIds[chatId]` independently for each subscription to prevent message loss on restart.
+
+**Verification**:
+- Write integration or unit tests verifying that multiple mocked subscriptions can run concurrently and route daemon messages to the correct mapped external channels.
+- Verify that state updates dynamically trigger new subscriptions without requiring an adapter restart.
+- Run `npm run validate`.
+
+---
+
+## Ticket 5: Add Google Chat Space Subscription Config & State Schemas
+**Status**: Completed
+
+**Description**: 
+Update the schemas to support user-level Space Subscriptions for Workspace Events.
+
+**Tasks**:
+- Update `GoogleChatStateSchema` in `src/adapter-google-chat/state.ts` using `zod` to expand `channelChatMap` to store subscription data: `z.record(z.string(), z.object({ chatId: z.string().nullable().optional(), subscriptionId: z.string().optional(), expirationDate: z.string().optional() })).optional()`.
+- Ensure migrations cleanly default `channelChatMap` to handle single-chat legacy formats if present.
+- Rename legacy `driveOauthClientId`, `driveOauthClientSecret`, and `driveOauthTokens` to generic `oauthClientId`, `oauthClientSecret`, and `oauthTokens` across schemas.
+- Update `src/adapter-google-chat/auth.ts` to request a combined scope array: `['https://www.googleapis.com/auth/drive.file', 'https://www.googleapis.com/auth/chat.messages.readonly']` and `access_type=offline`. Rename `getDriveAuthClient` to `getUserAuthClient`.
+- Update `src/adapter-google-chat/index.ts` to invoke `getUserAuthClient()` if OAuth credentials exist, removing the dependency on `driveUploadEnabled !== false`.
+
+**Verification**:
+- Add unit tests for schema parsing and single-chat legacy migrations for `channelChatMap` subscriptions.
+- Run `npm run validate`.
+
+---
+
+## Ticket 6: Implement Space Subscription Lifecycle (`ADDED_TO_SPACE` & `REMOVED_FROM_SPACE`)
+**Status**: Completed
+
+**Description**: 
+Handle Google Chat bot events to automatically create and tear down Space Subscriptions when the bot is added to or removed from a Space.
+
+**Tasks**:
+- Update `startGoogleChatIngestion` in `src/adapter-google-chat/client.ts` to intercept `ADDED_TO_SPACE` events.
+- If the space type is not `DIRECT_MESSAGE`:
+  1. Generate a new Access Token using the saved user Refresh Token.
+  2. Perform a `POST` request to `https://workspaceevents.googleapis.com/v1/subscriptions` to subscribe to `google.workspace.chat.message.v1.created` for the target space.
+  3. Save the returned subscription info (`subscriptionId`, `expirationDate`) into `state.json` under the channel's entry in `channelChatMap`.
+- Intercept `REMOVED_FROM_SPACE` events:
+  1. Look up the `subscriptionId` in `channelChatMap`.
+  2. Generate an Access Token and send a `DELETE` request to remove the subscription.
+  3. Delete the subscription fields from the channel's entry in `channelChatMap`, and delete the entry entirely if `chatId` is not set.
+
+**Verification**:
+- Add unit tests mocking the Google Workspace Events API to ensure `ADDED_TO_SPACE` correctly creates subscriptions and writes to state.
+- Add unit tests mocking `REMOVED_FROM_SPACE` deletion.
+- Run `npm run validate`.
+
+---
+
+## Ticket 7: Dual-Pipeline Pub/Sub Worker Logic
+**Status**: Completed
+
+**Description**: 
+Refactor message ingestion to correctly process native Bot Events alongside the newly configured Workspace Events coming from the same Pub/Sub topic, ensuring no duplication or loops.
+
+**Tasks**:
+- Update `startGoogleChatIngestion` in `src/adapter-google-chat/client.ts`.
+- Read the `ce-type` attribute of the Pub/Sub message. If it equals `google.workspace.chat.message.v1.created`, parse the payload as a Workspace Event. Otherwise, parse as a native Bot Event.
+- Explicitly check the sender of the event. If the sender is `BOT`, `message.ack()` and drop it immediately to prevent infinite reply loops.
+- Implement an in-memory 60-second LRU cache (or Map with cleanup) to store `Message ID`s. If a message ID has already been seen (because an `@mention` triggers both pipelines), drop the duplicate.
+- Ensure all outbound replies continue to use the Bot's Service Account, not the user token.
+
+**Verification**:
+- Add tests mocking Workspace Event payloads vs Bot Event payloads, verifying both are formatted and forwarded properly.
+- Add tests simulating an identical Message ID arriving twice in quick succession and verify only one daemon interaction occurs.
+- Add tests verifying messages from `BOT` are dropped.
+- Run `npm run validate`.
+
+---
+
+## Ticket 8: Background Renewal Cron for Subscriptions
+**Status**: Completed
+
+**Description**: 
+Implement a background process to prevent active Space Subscriptions from expiring after their default 7-day TTL.
+
+**Tasks**:
+- Implement a recurring background task (e.g., an hourly `setInterval` or cron script) in the Google Chat adapter.
+- Parse `channelChatMap` from `state.json`.
+- Identify subscriptions where `expirationDate` is less than 48 hours away.
+- For expiring subscriptions, use the globally stored user OAuth tokens to fetch an Access Token.
+- `PATCH https://workspaceevents.googleapis.com/v1/subscriptions/{subscriptionId}?updateMask=ttl` with `{ "ttl": "604800s" }`.
+- Update `state.json` with the newly returned `expirationDate`.
+
+**Verification**:
+- Add unit tests for the background renewal logic using fake timers to verify renewals trigger when dates are close.
+- Mock the PATCH request and verify state updates.
+- Run `npm run validate`.

package/docs/23_custom_token_env/development_log.md

@@ -0,0 +1,31 @@
+# Development Log
+
+## Initialization
+- Started working on "Step 1: Update Agent Schema".
+- Added `apiTokenEnvVar` and `apiUrlEnvVar` to `AgentSchema` in `src/shared/config.ts`.
+- Ran `npm run format && npm run lint:fix && npm run validate`.
+- Validations failed initially due to zombie processes on the e2e test port, so killed zombie node and daemon processes and retried successfully.
+- Marked Step 1 as completed in `tickets.md`.
+
+## Step 2: Update Lite Client Resolution Logic
+- Updated `src/cli/lite.ts` to dynamically resolve authentication environment variables.
+- Read pointer variables `CLAW_LITE_API_VAR` and `CLAW_LITE_URL_VAR` to resolve the `API_TOKEN` and `API_URL` respectively.
+- Updated error handling to log out the expected dynamically resolved variable names instead of the hardcoded names if missing.
+- Ran `npm run format && npm run lint:fix && npm run validate` which succeeded.
+- Marked Step 2 as completed in `tickets.md`.
+
+## Step 3: Update Daemon Environment Variable Injection
+- Updated `src/daemon/agent/agent-session.ts` in `buildExecutionContext`.
+- Added logic to check if `currentAgent.apiTokenEnvVar` and `currentAgent.apiUrlEnvVar` are defined.
+- Injected token/URL into custom variables and updated pointer variables `CLAW_LITE_API_VAR` and `CLAW_LITE_URL_VAR`.
+- If custom variables are not defined, gracefully falls back to `CLAW_API_TOKEN` and `CLAW_API_URL` respectively.
+- Ran validations (`npm run format && npm run lint:fix && npm run validate`), all tests passed.
+- Marked Step 3 as completed in `tickets.md`.
+
+## Step 4: Add and Update E2E Tests
+- Added a new E2E test in `src/cli/e2e/daemon.test.ts` to verify injection and functioning of custom `apiTokenEnvVar` and `apiUrlEnvVar`.
+- Created an agent with customized pointer variables and used it to send messages.
+- Verified that `lite` dynamically correctly leverages `CLAW_LITE_API_VAR` and `CLAW_LITE_URL_VAR` to securely interact with the Daemon APIs.
+- Reviewed `export-lite-func.test.ts` and `requests.test.ts`, confirming they inherently verify the fallback/default behavior remains completely intact.
+- Ran formatting and final validation checks (`npm run validate`); all 380 E2E tests successfully pass.
+- Marked Step 4 as completed in `tickets.md`.

package/docs/23_custom_token_env/notes.md

@@ -0,0 +1,16 @@
+# Notes on Custom Token Env
+
+## Current Behavior
+- The daemon securely authenticates with the Agent API using a dynamically generated HMAC token (`CLAW_API_TOKEN`).
+- `src/daemon/agent/agent-session.ts` injects `CLAW_API_URL` and `CLAW_API_TOKEN` into the environment of the executed agent process.
+- `src/cli/lite.ts` (which compiles to `clawmini-lite.js`) reads these via `process.env.CLAW_API_URL` and `process.env.CLAW_API_TOKEN`.
+- E2E tests (`src/cli/e2e/`) check for `CLAW_API_TOKEN=` in the environment variables.
+
+## Issue
+- Gemini CLI strips out environment variables that include `TOKEN`, `KEY`, `SECRET`, etc., unless they have the `GEMINI_CLI_` prefix.
+- Therefore, when Clawmini runs Gemini CLI as an agent, `CLAW_API_TOKEN` is stripped, and `clawmini-lite.js` (used for fallbacks or tool usage) cannot authenticate.
+
+## Solution Direction
+- Allow configuring an alternative env var name to pass the token (e.g., `GEMINI_CLI_CLAW_API_TOKEN`).
+- If this is configured, the daemon must inject the token using this alternative name.
+- We need a way to tell `clawmini-lite.js` which environment variable contains the token, since it won't be `CLAW_API_TOKEN` anymore. This pointer variable itself must not contain the words `TOKEN`, `KEY`, or `SECRET` to avoid being stripped.

package/docs/23_custom_token_env/prd.md

@@ -0,0 +1,42 @@
+# Product Requirements Document: Custom Token Environment Variables
+
+## 1. Vision
+Enable Clawmini to integrate seamlessly with strict sandboxes and external CLI tools (like Gemini CLI) that aggressively filter or strip environment variables containing sensitive keywords such as `TOKEN`, `KEY`, or `SECRET`. By allowing agents to configure custom names for the API URL and API Token environment variables, Clawmini ensures that injected authentication details reach the target agent process without being discarded by intermediate wrappers.
+
+## 2. Product/Market Background
+Clawmini securely authenticates spawned agents with its API using a dynamically generated HMAC token passed via the `CLAW_API_TOKEN` environment variable. The agent uses the lightweight `clawmini-lite.js` script to execute tasks (e.g., fallbacks, tool usage). However, some agents—such as the Gemini CLI—employ strict security measures that strip out environment variables matching sensitive keyword patterns unless explicitly prefixed (e.g., `GEMINI_CLI_`). This behavior breaks Clawmini's authentication flow because `CLAW_API_TOKEN` is stripped before `clawmini-lite.js` runs.
+
+## 3. Use Cases
+- **Running Gemini CLI as an Agent:** A user configures Gemini CLI as a Clawmini agent. They define `apiTokenEnvVar: 'GEMINI_CLI_CLAW_API_TOKEN'` in the agent configuration so that the authentication token bypasses Gemini CLI's environment variable filter.
+- **Custom URL Overrides:** A user is running an agent inside an environment where `CLAW_API_URL` conflicts with an existing system variable or is stripped, and they need to map it to a custom variable name like `CUSTOM_API_HOST`.
+
+## 4. Requirements
+
+### 4.1. Configuration (`src/shared/config.ts`)
+- Update the `AgentSchema` (and corresponding `Agent` type) to include two new optional string properties:
+  - `apiTokenEnvVar`: Specifies an alternative environment variable name for the API token.
+  - `apiUrlEnvVar`: Specifies an alternative environment variable name for the API URL.
+
+### 4.2. Daemon Injection (`src/daemon/agent/agent-session.ts`)
+- When spawning an agent, check if `agent.apiTokenEnvVar` and/or `agent.apiUrlEnvVar` are set.
+- If `apiTokenEnvVar` is defined:
+  - Inject the token into the specified custom environment variable (e.g., `GEMINI_CLI_CLAW_API_TOKEN`) instead of `CLAW_API_TOKEN`.
+  - Inject a "pointer" environment variable named `CLAW_LITE_API_VAR` whose value is the name of the custom token variable (e.g., `"GEMINI_CLI_CLAW_API_TOKEN"`). This pointer must *not* be stripped by target tools, hence avoiding keywords like `TOKEN`.
+- If `apiUrlEnvVar` is defined:
+  - Inject the API URL into the specified custom environment variable instead of `CLAW_API_URL`.
+  - Also ensure that `clawmini-lite.js` knows where to look for the URL (e.g., using another pointer variable like `CLAW_LITE_URL_VAR`, or encoding both in a structured way). Given the structure, a matching pointer for the URL `CLAW_LITE_URL_VAR` should be introduced.
+
+### 4.3. Lite Client Updates (`src/cli/lite.ts`)
+- `clawmini-lite.js` must be updated to dynamically resolve the environment variable names used for authentication.
+- Read the pointer variables first (`process.env.CLAW_LITE_API_VAR` and `process.env.CLAW_LITE_URL_VAR`).
+- If `CLAW_LITE_API_VAR` is set, read the token from `process.env[process.env.CLAW_LITE_API_VAR]`. Fallback to `process.env.CLAW_API_TOKEN` if the pointer is not set.
+- If `CLAW_LITE_URL_VAR` is set, read the URL from `process.env[process.env.CLAW_LITE_URL_VAR]`. Fallback to `process.env.CLAW_API_URL` if the pointer is not set.
+- Ensure appropriate error handling if the resolved variables are missing or empty.
+
+### 4.4. Security Considerations
+- The introduction of custom environment variables does not alter the fundamental HMAC authentication model. The token remains dynamically generated per execution and is only valid for its intended scope.
+- The pointer variables (`CLAW_LITE_API_VAR`, `CLAW_LITE_URL_VAR`) must not contain sensitive strings like `TOKEN` to ensure they bypass downstream filters.
+
+### 4.5. Testing
+- **E2E Tests:** Update `src/cli/e2e/daemon.test.ts`, `src/cli/e2e/export-lite-func.test.ts`, and `src/cli/e2e/requests.test.ts` to accommodate or verify the fallback logic. 
+- Write a specific test case that configures an agent with `apiTokenEnvVar` and `apiUrlEnvVar`, ensuring the daemon properly injects the custom and pointer variables, and verifying that a mock `clawmini-lite.js` invocation successfully authenticates using the redirected variables.

package/docs/23_custom_token_env/questions.md

@@ -0,0 +1,8 @@
+# Questions for Custom Token Env
+
+1. Since we need a way to tell `clawmini-lite.js` which environment variable contains the token, what should we name this "pointer" environment variable? It cannot contain `TOKEN`, `KEY`, or `SECRET` (e.g., `CLAW_API_TOKEN_VAR` would be stripped). Would something like `CLAW_LITE_API_VAR` or `CLAW_AUTH_ENV` work?
+   - **Answer:** `CLAW_LITE_API_VAR` is a good choice as it avoids sensitive words.
+2. Where should the configuration for the alternative environment variable name live? Should we add an `apiTokenEnvVar` property to the `Agent` schema, the `Environment` schema, or both (with Agent overriding Environment)?
+   - **Answer:** The `Agent` schema is the appropriate place. The property name should be `apiTokenEnvVar`.
+3. Does `CLAW_API_URL` pass through Gemini CLI without issues, or do we also need to support renaming the URL environment variable?
+   - **Answer:** It generally passes through without issues, but we should also allow the user to override it via an `apiUrlEnvVar` property on the `Agent` schema.

package/docs/23_custom_token_env/tickets.md

@@ -0,0 +1,54 @@
+# Tickets: Custom Token Environment Variables
+
+## Step 1: Update Agent Schema
+**Status**: Completed
+
+**Tasks:**
+- Update `src/shared/config.ts`.
+- Add `apiTokenEnvVar` (optional string) to `AgentSchema` and `Agent` type.
+- Add `apiUrlEnvVar` (optional string) to `AgentSchema` and `Agent` type.
+
+**Verification:**
+- Run `npm run format` and `npm run lint:fix`.
+- Run `npm run validate` to ensure type checking and tests pass.
+
+## Step 2: Update Lite Client Resolution Logic
+**Status**: Completed
+
+**Tasks:**
+- Update `src/cli/lite.ts` to dynamically resolve authentication environment variables.
+- Read pointer variables: `process.env.CLAW_LITE_API_VAR` and `process.env.CLAW_LITE_URL_VAR`.
+- Resolve token: If `CLAW_LITE_API_VAR` is set, use `process.env[process.env.CLAW_LITE_API_VAR]`. Otherwise, fallback to `process.env.CLAW_API_TOKEN`.
+- Resolve URL: If `CLAW_LITE_URL_VAR` is set, use `process.env[process.env.CLAW_LITE_URL_VAR]`. Otherwise, fallback to `process.env.CLAW_API_URL`.
+- Ensure appropriate error handling if the resolved variables are missing or empty.
+
+**Verification:**
+- Run `npm run format` and `npm run lint:fix`.
+- Run `npm run validate` to ensure code compiles.
+
+## Step 3: Update Daemon Environment Variable Injection
+**Status**: Completed
+
+**Tasks:**
+- Update `src/daemon/agent/agent-session.ts`.
+- When spawning an agent, check for `agent.apiTokenEnvVar` and `agent.apiUrlEnvVar`.
+- If `apiTokenEnvVar` is defined, inject the token into the custom variable and set `CLAW_LITE_API_VAR` to the custom variable name. Do not inject `CLAW_API_TOKEN`.
+- If `apiUrlEnvVar` is defined, inject the URL into the custom variable and set `CLAW_LITE_URL_VAR` to the custom variable name. Do not inject `CLAW_API_URL`.
+- If they are not defined, inject `CLAW_API_TOKEN` and `CLAW_API_URL` as usual.
+
+**Verification:**
+- Run `npm run format` and `npm run lint:fix`.
+- Run `npm run validate` to ensure tests still pass.
+
+## Step 4: Add and Update E2E Tests
+**Status**: Completed
+
+**Tasks:**
+- Update existing E2E tests (e.g., `src/cli/e2e/daemon.test.ts`, `src/cli/e2e/export-lite-func.test.ts`, `src/cli/e2e/requests.test.ts`) if they explicitly check for the hardcoded `CLAW_API_TOKEN` but shouldn't, or update them to verify default behavior remains intact.
+- Add a new specific test case configuring an agent with both `apiTokenEnvVar` and `apiUrlEnvVar`.
+- Verify that the daemon correctly injects the custom variables and the pointer variables (`CLAW_LITE_API_VAR`, `CLAW_LITE_URL_VAR`).
+- Verify that an invocation of `clawmini-lite` via the CLI or mock successfully authenticates using these redirected variables.
+
+**Verification:**
+- Run `npm run format` and `npm run lint:fix`.
+- Run `npm run validate` to verify all new and existing tests pass successfully.

package/docs/guides/discord_adapter_setup.md

@@ -53,10 +53,12 @@ This will create a `config.json` file at `.clawmini/adapters/discord/config.json
 {
   "botToken": "YOUR_DISCORD_BOT_TOKEN",
   "authorizedUserId": "YOUR_DISCORD_USER_ID",
-  "chatId": "default"
+  "chatId": "default",
+  "requireMention": false
 }
 ```
-*(Note: `chatId` defaults to `"default"`. You can change this if you want the bot to associate with a different chat).*
+
+_(Note: `chatId` defaults to `"default"`. You can change this if you want the bot to associate with a different chat. `requireMention` defaults to `false` and can be set to `true` if you only want the bot to respond when explicitly mentioned)._
 
 ## Step 5: Start the Adapter
 
@@ -67,3 +69,14 @@ npx clawmini-adapter-discord
 ```
 
 The adapter will now forward authorized Discord DM messages to your Clawmini daemon and vice versa.
+
+## Routing and Creating Chats
+
+By default, the adapter connects to a single chat (the one specified as `chatId` in your `config.json`). However, you can create new Discord channels (or use different DMs) to map to separate Clawmini chats.
+
+1. Create a new Text Channel in your Discord server (or open a new DM group).
+2. Invite the bot to the channel if necessary.
+3. Send the command `/agent [agent-id]` to automatically create a new Clawmini chat with that agent and map it to the current Discord channel.
+4. Alternatively, use `/chat [chat-id]` to map that specific Discord channel to an existing Clawmini chat.
+
+_Note: Each Discord channel can only be mapped to one Clawmini chat, and each Clawmini chat can only be mapped to one channel/space across all adapters._