clawmini 0.0.1

package/docs/08_agent_api/tickets.md

@@ -0,0 +1,104 @@
+# Agent API Tickets
+
+## Step 1: Configuration Updates
+**Description:** Update the global settings schema to support the new `api` configuration option.
+**Tasks:**
+- Modify `src/shared/config.ts` (or relevant config file) to add an `api` property to the `SettingsSchema`.
+- The `api` property should accept:
+  - `false` (default): Web server does not start.
+  - `true`: Web server starts on `127.0.0.1:3000` (or similar default).
+  - An object `{ host: string, port: number }`: Web server starts on the specified host and port.
+- Add/update tests for config parsing to ensure the new `api` property is handled correctly.
+**Verification:**
+- Run `npm run format:check && npm run lint && npm run check && npm run test`
+**Status:** Completed
+
+## Step 2: Daemon HTTP Server
+**Description:** Optionally start an HTTP server in the daemon to expose the tRPC router based on configuration.
+**Tasks:**
+- Modify `src/daemon/index.ts` to check the `api` configuration.
+- If enabled, start an HTTP server (e.g., using `@trpc/server/adapters/node-http` or similar depending on the existing setup).
+- Bind the tRPC router to this HTTP server.
+- Ensure the server gracefully shuts down when the daemon stops.
+**Verification:**
+- Add unit/e2e tests to verify the HTTP server starts with the correct config and responds to tRPC requests.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`
+**Status:** Completed
+
+## Step 3: Agent Execution Context & Token Security
+**Description:** Inject context and secure tokens into agent processes and validate them on the HTTP server.
+**Tasks:**
+- Implement a secure token generation and validation mechanism (e.g., HMAC with a secret or a simple JWT). The token must encode `chatId`, `agentId`, `sessionId`, and a `timestamp`.
+- Update the daemon's tRPC context/middleware to validate `CLAW_API_TOKEN` (e.g., from the `Authorization` header) for HTTP requests, ensuring requests are scoped to the authorized chat/agent.
+- Modify the agent spawning logic (likely in `src/daemon/message.ts` or related) to generate this token.
+- Inject `CLAW_API_URL` and `CLAW_API_TOKEN` into the environment variables (`env`) of the spawned agent process.
+**Verification:**
+- Add unit tests for token generation and validation.
+- Add integration tests verifying that spawned agents receive the correct environment variables.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`
+**Status:** Completed
+
+## Step 4: `clawmini export-lite` Command
+**Description:** Add a new CLI command to export the standalone `clawmini-lite` client script.
+**Tasks:**
+- Create the source for `clawmini-lite` as a standalone, zero-dependency Node.js script (using native `fetch`).
+- Add a new command `export-lite` to the CLI (`src/cli/commands/export-lite.ts` or similar).
+- The command should output the script to the current directory by default, or to a specified path, or to stdout if `--stdout` is passed.
+**Verification:**
+- Add CLI tests to verify `clawmini export-lite` correctly writes the script file or outputs to stdout.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`
+**Status:** Completed
+
+## Step 5: `clawmini-lite` Client Functionality
+**Description:** Implement the functionality within the exported `clawmini-lite` script.
+**Tasks:**
+- Ensure the `clawmini-lite` script reads `CLAW_API_URL` and `CLAW_API_TOKEN` from `process.env`.
+- Implement a lightweight tRPC client (using `fetch`) inside the script.
+- Implement the supported subcommands:
+  - `log <message>`: Appends a `{type: "log"}` message to the chat.
+  - `jobs list`: Lists cron jobs for the chat.
+  - `jobs add <...>`: Adds a job for the chat.
+  - `jobs delete <id>`: Deletes a job from the chat.
+**Verification:**
+- Add e2e tests that execute the exported `clawmini-lite` script as a subprocess against a running daemon HTTP server to verify all subcommands work correctly.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`
+**Status:** Completed
+
+## Issue 1: Refactor repeated `chatId` resolution in `router.ts`
+**Priority:** High
+**Description:** DRY violation in `src/daemon/router.ts`. The logic to resolve `chatId` (checking `input.chatId`, `ctx.tokenPayload.chatId`, or `getDefaultChatId()`) and calling `checkScope(ctx, chatId)` is duplicated 4 times across endpoints.
+**Tasks:**
+- Create an async helper `resolveAndCheckChatId(ctx: Context, inputChatId?: string): Promise<string>` that performs this logic.
+- Replace the repeated logic in `logMessage`, `listCronJobs`, `addCronJob`, and `deleteCronJob` with a single call to this helper.
+**Verification:**
+- Run checks from `docs/CHECKS.md` to ensure all tests pass.
+**Status:** Completed
+
+## Issue 2: Refactor API settings parsing in `index.ts`
+**Priority:** Medium
+**Description:** DRY violation in `src/daemon/index.ts`. The parsing of API settings duplicates logic present in `getApiContext` in `src/daemon/auth.ts`.
+**Tasks:**
+- Import and use `getApiContext` in `src/daemon/index.ts` instead of manually checking `typeof parsed.data.api`.
+**Verification:**
+- Run checks from `docs/CHECKS.md` to ensure all tests pass.
+**Status:** Completed
+
+## Issue 3: Remove unnecessary `console.error` in `checkScope`
+**Priority:** Low
+**Description:** `checkScope` in `src/daemon/router.ts` uses `console.error` before throwing a TRPCError. This is unnecessary since it's an API validation failure that should be handled gracefully.
+**Tasks:**
+- Remove the `console.error` call in `checkScope`.
+**Verification:**
+- Run checks from `docs/CHECKS.md` to ensure all tests pass.
+**Status:** Completed
+
+## Issue 4: Prevent Timing Attacks on Token Validation
+**Priority:** High
+**Description:** The token validation in `src/daemon/auth.ts` uses strict equality (`!==`) to compare the provided HMAC signature against the expected signature. This exposes the daemon to timing attacks, where an attacker could potentially guess the signature character by character based on comparison times.
+**Tasks:**
+- Replace the strict equality check (`signature !== expectedHmac`) with a constant-time comparison using `crypto.timingSafeEqual`.
+- Ensure the strings are converted to Buffers before comparison.
+- Add a length check to prevent `timingSafeEqual` from throwing if the lengths differ.
+**Verification:**
+- Run checks from `docs/CHECKS.md` to ensure all tests pass, including the `auth.test.ts` which should still succeed for valid tokens and fail for tampered ones.
+**Status:** Completed

package/docs/09_agent_fallbacks/development_log.md

@@ -0,0 +1,52 @@
+# Development Log - Agent Fallbacks
+
+## 2026-03-03
+
+- Initializing development log.
+- Starting on Ticket 1: Configuration Schema and Type Updates.
+- Discovered pre-existing test failure in `src/cli/e2e/messages.test.ts` (`should maintain atomic ordering of user and log messages with --no-wait`). Proceeding with Ticket 1 as it is unrelated to this failure.
+- Updated `src/shared/config.ts` with `FallbackSchema` and `fallbacks` in `AgentSchema`.
+- Verified schema with a temporary unit test.
+- Ticket 1 complete.
+
+- Refactored `src/daemon/message.ts`:
+  - Updated `prepareCommandAndEnv` to merge base agent with fallback overrides.
+  - Refactored `executeDirectMessage` to include a nested retry loop (base attempt + fallback attempts).
+  - Implemented failure detection (non-zero exit code or empty extracted message content).
+- Added `src/daemon/message-fallbacks.test.ts` with unit tests covering base failures, empty extraction, and multiple retries.
+- Verified all checks and tests pass (including pre-existing flakiness in E2E tests which resolved themselves).
+- Ticket 2 complete.
+
+- Implemented exponential backoff logic in `src/daemon/message.ts`:
+  - Added `calculateDelay` helper with doubling logic and 15s cap.
+  - Added `sleep` helper.
+  - Integrated backoff into the retry loop in `executeDirectMessage`.
+- Added unit tests for `calculateDelay` in `src/daemon/message-fallbacks.test.ts`.
+- Verified all checks and tests pass.
+- Ticket 3 complete.
+
+## 2026-03-03 (continued)
+
+- Starting on Ticket 4: UX Retry Notifications.
+- Identifying insertion point in `src/daemon/message.ts` for retry log messages.
+- Implemented `retry-delay` log message in `executeDirectMessage`.
+- Added unit test in `src/daemon/message-fallbacks.test.ts` to verify the log message is appended before the sleep delay.
+- Verified all checks and tests pass.
+- Ticket 4 complete.
+
+- Starting on Ticket 5: Comprehensive E2E Validation.
+- Planning E2E test cases for various fallback scenarios:
+  - Base fails (exit code), fallback succeeds via env override.
+  - Base fails (empty content), fallback succeeds via command override.
+  - Exponential backoff (checking log messages).
+  - Exhausted fallbacks (all fail).
+- Implemented Ticket 5:
+  - Discovered that "retrying" log messages were not appearing when moving between execution configurations (base -> fallback).
+  - Updated `calculateDelay` in `src/daemon/message.ts` to support an `isFallback` flag, ensuring a delay (and thus a log message) is triggered when starting a fallback if `delayMs` is present.
+  - Fixed `logMsg` construction to always include `stdout` property, as per `CommandLogMessage` definition and `napkin.md` notes.
+  - Created `src/cli/e2e/fallbacks.test.ts` to house all fallback-related E2E tests, keeping `src/cli/e2e/messages.test.ts` within the `max-lines` limit.
+  - Updated existing E2E test `should handle full multi-message session workflow` to expect `stdout` in log messages.
+  - Verified all checks (`npm run format:check && npm run lint && npm run check && npm run test`) pass.
+- Ticket 5 complete.
+
+ALL DONE

package/docs/09_agent_fallbacks/notes.md

@@ -0,0 +1,40 @@
+# Agent Fallbacks Research Notes
+
+## Current State
+
+**Agent Configuration (`src/shared/config.ts`)**
+- `AgentSchema` currently has `commands`, `env`, and `directory`.
+- No fallback logic exists.
+
+**Execution Logic (`src/daemon/message.ts`)**
+- `executeDirectMessage` runs the main command (either `new` or `append`).
+- `mainResult` gives `stdout`, `stderr`, and `exitCode`.
+- If `exitCode === 0`:
+  - It tries to extract the session ID (if `getSessionId` is defined).
+  - It tries to extract the message content (if `getMessageContent` is defined).
+- The `logMsg` is created and appended to the chat.
+
+## Proposed Changes for Fallbacks
+
+**Configuration**
+- Add an array of `fallbacks` to `AgentSchema`.
+- Each fallback could have:
+  - `commands` (Partial override of `new`, `append`, `getMessageContent`, `getSessionId`)
+  - `env` (Partial override of environment variables, e.g., `$MODEL`)
+  - `delayMs` (Optional backoff time before executing the fallback)
+
+**Detection of Errors**
+- Failure condition 1: `mainResult.exitCode !== 0`.
+- Failure condition 2: `getMessageContent` results in an empty string (`result.trim() === ''`).
+
+**Execution Loop**
+- Wrap the main execution block in `executeDirectMessage` inside a retry loop.
+- The loop tries the base agent configuration first.
+- If it fails, and there are fallbacks left, it picks the next fallback, merges its `env` and `commands` into the base agent config.
+- Before running the fallback, if a delay is specified, it appends a message to the chat: "Error running agent, retrying in N seconds..." and waits.
+- Empty fallback config just reruns the original command.
+
+## Questions for PRD
+- Should the retry message be a standard system message or replace the previous message?
+- Are fallbacks evaluated one-by-one in sequence, or is there a max retry count for a single fallback?
+- Should we add a `timeout` configuration for the command itself as part of failure detection?

package/docs/09_agent_fallbacks/prd.md

@@ -0,0 +1,55 @@
+# Product Requirements Document (PRD): Agent Fallbacks
+
+## 1. Vision
+To enhance the reliability and resilience of the Gemini CLI application by providing robust fallback mechanisms when agent commands fail. This will allow the application to automatically recover from transient issues, rate limits, or specific command failures, ensuring a smoother user experience.
+
+## 2. Product/Market Background
+In AI-driven CLI applications or agentic frameworks, execution errors are common due to external dependencies like API quotas, network timeouts, or model availability. Currently, if an agent fails (e.g., due to an empty response or an error code), the interaction stops, and the user must manually diagnose and retry. By introducing configurable fallbacks, agents can automatically retry operations or switch to alternative configurations (e.g., swapping a `$MODEL` environment variable to use a less restricted model) without user intervention.
+
+## 3. Use Cases
+- **Transient Network Errors:** An agent's curl command to an API fails due to a temporary network blip. The fallback simply re-runs the exact same command after a short delay.
+- **Quota Exceeded/Rate Limits:** An agent hits a rate limit for an expensive AI model. A fallback changes the `$MODEL` environment variable to a cheaper, higher-quota model and retries.
+- **Command Tuning:** An agent's primary prompt strategy fails to produce parsable output (resulting in an empty extracted message). The fallback tries a slightly modified `new` or `append` command with stronger formatting instructions.
+
+## 4. Requirements
+
+### 4.1 Configuration
+- Expand the `AgentSchema` in `src/shared/config.ts` to support an array of `fallbacks`.
+- A fallback configuration object will contain:
+  - `commands`: Optional partial override for `new`, `append`, `getSessionId`, and `getMessageContent`.
+  - `env`: Optional partial override of environment variables.
+  - `retries`: Optional integer denoting how many times this specific fallback (or the base configuration, if an empty fallback object is provided) should be retried before giving up. Defaults to 1.
+  - `delayMs`: Optional base delay in milliseconds before initiating a retry. Defaults to 1000ms.
+
+### 4.2 Error Detection
+An agent execution is considered "failed" if:
+1. The main command's exit code is not zero (`mainResult.exitCode !== 0`).
+2. The `getMessageContent` extraction command yields an empty string (`result.trim() === ''`) after successful execution.
+
+*Note: Command execution timeouts are explicitly out of scope for this feature.*
+
+### 4.3 Execution Logic & Retries
+- When a failure is detected, the daemon (`src/daemon/message.ts`) must evaluate the fallbacks in the order they are defined.
+- Before executing a fallback, its `env` and `commands` are merged with the original agent configuration.
+- Retries for a given fallback will use an **exponential backoff** strategy.
+  - Delay calculation: `delayMs * (2 ^ (attempt - 1))`.
+  - The maximum delay between retries must be capped at 15 seconds (15,000ms).
+- If all retries for a fallback fail, the system moves to the next fallback in the array.
+- If all fallbacks are exhausted and the final attempt fails, the standard failure behavior occurs (logging the final error to the user).
+
+### 4.4 Notifications / UX
+- Upon detecting a failure that will be retried, a new "log" message must be appended to the chat history.
+- The log message format should be: `"Error running agent, retrying in <N> seconds..."` where `<N>` is the computed delay for the current attempt.
+- This log message is immediately sent to the user and persists in the chat history.
+
+## 5. Security, Privacy, and Accessibility Concerns
+- **Security:** Ensure that merged environment variables do not inadvertently leak secrets into logs. Standard logging practices for command execution must continue to sanitize or hide sensitive variables if applicable.
+- **Privacy:** Fallback configurations must reside within the existing user-controlled settings files. No new telemetry or external reporting is introduced.
+- **Accessibility:** Ensure that the retry log messages are clear and easily readable in terminal outputs or web interfaces, avoiding excessive spam (the exponential backoff helps mitigate rapid-fire log spam).
+
+## 6. Development Strategy
+1. **Schema Update:** Update `AgentSchema` in `src/shared/config.ts` to include `fallbacks`.
+2. **Refactor Execution:** In `src/daemon/message.ts`, refactor the core execution inside `executeDirectMessage` to be callable within a retry loop.
+3. **Implement Backoff & Retry Logic:** Add the loop with the exponential backoff calculation (capped at 15s) and fallback iteration.
+4. **Log Messaging:** Integrate the retry notification log message generation into the retry loop.
+5. **Testing:** Update unit tests (`daemon/message.test.ts` or similar) and e2e tests (`cli/e2e/messages.test.ts`) to verify failure detection, correct merging of fallback config, exponential backoff timing logic, and log message creation.

package/docs/09_agent_fallbacks/questions.md

@@ -0,0 +1,10 @@
+# PRD Questions
+
+**Q1: Are fallbacks evaluated strictly one-by-one in the array sequence (meaning each fallback configuration only gets one attempt before moving to the next), or should a single fallback have its own retry count (e.g., trying the exact same fallback multiple times before giving up)?**
+A1: Let's add an optional retry count per fallback; defaults to 1.
+
+**Q2: For the notification message ("Error running agent, retrying in N seconds..."), should this be appended as a new system message to the chat that remains in the history, or should we update/replace a temporary message, or just include it as standard `stderr` output in the final message log?**
+A2: This should be a new "log" message in the chat that is immediately sent to the user and persists.
+
+**Q3: Should the delay for fallbacks and their retries use a fixed delay or an exponential backoff strategy? Additionally, should we add a command execution `timeoutMs` to detect if an agent hangs and trigger a fallback based on that timeout?**
+A3: Use whatever is recommended for retries, but cap the retry delay at something reasonable (15s). No timeout is needed for the commands themselves.

package/docs/09_agent_fallbacks/tickets.md

@@ -0,0 +1,88 @@
+# Tickets for Agent Fallbacks
+
+## Ticket 1: Configuration Schema and Type Updates
+**Status:** completed
+
+### Task
+Update `src/shared/config.ts` to include the `fallbacks` property in `AgentSchema`.
+- Create `FallbackSchema` with optional:
+  - `commands`: Partial override for `new`, `append`, `getSessionId`, and `getMessageContent`.
+  - `env`: `z.record(z.string(), z.string())` for environment overrides.
+  - `retries`: `z.number().int().min(0)` (default 1).
+  - `delayMs`: `z.number().int().min(0)` (default 1000).
+- Update `AgentSchema` to include an optional `fallbacks: z.array(FallbackSchema)`.
+- Update `Agent` type.
+
+### Verification
+- Run `npm run check` to ensure type consistency.
+- Follow `./docs/CHECKS.md`: `npm run format:check && npm run lint`.
+- (Optional) Verify with a small script that `AgentSchema.parse` handles a sample agent with multiple fallbacks.
+
+---
+
+## Ticket 2: Refactor Execution Loop and Error Detection
+**Status:** completed
+
+### Task
+Refactor `executeDirectMessage` in `src/daemon/message.ts` to support a retry loop and implement failure detection.
+- **Failure Detection**: A run is failed if:
+  1. `mainResult.exitCode !== 0`
+  2. OR `getMessageContent` returns an empty string (`result.trim() === ''`).
+- **Loop Structure**:
+  - Wrap the inner queue task logic in a loop that iterates through:
+    1. Base configuration (first attempt).
+    2. Each entry in `agent.fallbacks`.
+  - For each fallback, support multiple attempts based on its `retries` count.
+- Update `prepareCommandAndEnv` (or implement a new helper) to handle merging of the base agent with fallback overrides (`commands` and `env`).
+
+### Verification
+- Run existing tests `npm run test` to ensure no regressions.
+- Add unit tests in `src/daemon/message-fallbacks.test.ts` mocking `runCommand` to fail once and then succeed, verifying the loop triggers.
+- Follow `./docs/CHECKS.md`.
+
+---
+
+## Ticket 3: Exponential Backoff Logic
+**Status:** completed
+
+### Task
+Implement the exponential backoff timing logic within the retry loop.
+- **Delay Calculation**: `delay = delayMs * (2 ^ (attempt - 1))`.
+- **Constraint**: Cap maximum delay at 15,000ms.
+- **Implementation**: Use a `Promise`-based delay/sleep function before re-executing a command.
+- Ensure the base `delayMs` defaults to 1000 if not provided in the fallback.
+
+### Verification
+- Add unit tests for the delay calculation logic to ensure it doubles correctly and caps at 15s.
+- Follow `./docs/CHECKS.md`.
+
+---
+
+## Ticket 4: UX Retry Notifications
+**Status:** completed
+
+### Task
+Integrate log messages for retries into the execution loop in `src/daemon/message.ts`.
+- Before waiting for a retry delay, append a "log" message to the chat: `"Error running agent, retrying in <N> seconds..."`.
+- Ensure the message is appended and persisted so the user can see the progress.
+- Ensure the final successful (or final failed) output replaces or follows these retry logs correctly in the UI.
+
+### Verification
+- Run E2E or manual tests to confirm the "retrying in..." message appears in the `messages.json` of the chat during a failure.
+- Follow `./docs/CHECKS.md`.
+
+---
+
+## Ticket 5: Comprehensive E2E Validation
+**Status:** completed
+
+### Task
+Add E2E tests in `src/cli/e2e/messages.test.ts` to verify all fallback scenarios.
+- **Scenario 1**: Base fails (exit code), fallback with env override succeeds.
+- **Scenario 2**: Base succeeds but `getMessageContent` is empty, fallback with modified command succeeds.
+- **Scenario 3**: Multiple retries for a single fallback (exponential backoff check).
+- **Scenario 4**: All fallbacks exhausted, final failure reported.
+
+### Verification
+- Run `npm run test` and ensure all E2E tests pass.
+- Final check of `./docs/CHECKS.md`.

package/docs/09_discord_adapter/development_log.md

@@ -0,0 +1,95 @@
+# Development Log - Discord Adapter
+
+## 2026-03-03 - Tuesday
+
+### Initial Session Start
+- Identified `09_discord_adapter` as the active feature folder.
+- Starting Step 1: Scaffold Discord Adapter.
+
+### Step 1: Scaffold Discord Adapter
+- **Goal:** Create basic structure and build setup for the Discord adapter.
+- **Tasks:**
+  - Create `src/adapter-discord` directory. (Done)
+  - Create `src/adapter-discord/index.ts`. (Done)
+  - Update `tsdown.config.ts` to include the new entry point. (Done)
+  - Add `discord.js` to `package.json`. (Done)
+- **Status:** Completed. Verified with `npm run build` and `node dist/adapter-discord/index.mjs`. All tests and checks passed.
+
+### Step 2: Configuration & Security Implementation
+- **Goal:** Define configuration schema and loading logic.
+- **Tasks:**
+  - Create `src/adapter-discord/config.ts` with Zod schema. (Done)
+  - Implement configuration loading from `.clawmini/adapters/discord/config.json`. (Done)
+  - Add `isAuthorized(userId: string)` helper. (Done)
+  - Add unit tests in `src/adapter-discord/config.test.ts`. (Done)
+- **Status:** Completed. Verified with unit tests and full automated checks.
+
+### Step 3: TRPC Client Connection
+- **Goal:** Implement TRPC client to connect to the daemon.
+- **Tasks:**
+  - Create `src/adapter-discord/client.ts`. (Done)
+  - Implement a TRPC client that connects to the daemon via the Unix socket. (Done)
+  - Create unit tests in `src/adapter-discord/client.test.ts`. (Done)
+- **Status:** Completed. Verified with unit tests. All checks and tests passed.
+
+### Step 4: Discord to Daemon Forwarding
+- **Goal:** Forward authorized Discord DM messages to the Clawmini daemon.
+- **Tasks:**
+  - Initialize `discord.js` client in `src/adapter-discord/index.ts`. (Done)
+  - Implement `messageCreate` listener for DMs. (Done)
+  - Integrate with `readDiscordConfig` and `isAuthorized`. (Done)
+  - Implement TRPC `sendMessage` forwarding. (Done)
+  - Create comprehensive unit tests in `src/adapter-discord/index.test.ts`. (Done)
+- **Status:** Completed. Verified with mocked `discord.js` tests. All checks and tests passed.
+
+### Step 5: Daemon Message Observation Enhancement
+- **Goal:** Update the daemon to support real-time message observation via TRPC.
+- **Tasks:**
+  - Create `src/daemon/events.ts` with a global `EventEmitter` for the daemon.
+  - Create `src/daemon/chats.ts` as a daemon-specific wrapper for `shared/chats.ts` that emits `message-appended` events.
+  - Update `src/daemon/message.ts` and `src/daemon/router.ts` to use the new `chats.ts` wrapper.
+  - Add `getMessages` and `waitForMessages` (long-polling) endpoints to the TRPC router in `src/daemon/router.ts`.
+  - Update existing daemon tests (`message-extraction.test.ts`, `message-queue.test.ts`, `message-router.test.ts`) to mock the new `./chats.js` module.
+  - Create comprehensive unit tests in `src/daemon/observation.test.ts`.
+- **Status:** Completed. Verified with unit tests. All checks and tests passed.
+
+### Step 6: Daemon to Discord Forwarding
+- **Goal:** Forward messages from the Clawmini daemon back to the authorized Discord user.
+- **Tasks:**
+  - Create `src/adapter-discord/forwarder.ts` with the observation loop logic.
+  - Implement long-polling using `waitForMessages` TRPC endpoint.
+  - Implement message chunking for Discord's 2000 character limit.
+  - Update `src/adapter-discord/index.ts` to start the forwarder when the client is ready.
+  - Create comprehensive unit tests in `src/adapter-discord/forwarder.test.ts`.
+- **Status:** Completed. Verified with unit tests. All checks and tests passed.
+
+### Step 7: State Management & Startup Sync
+- **Goal:** Implement persistent state to track synced messages and ensure no messages are missed on startup.
+- **Tasks:**
+  - Create `src/adapter-discord/state.ts` for `.clawmini/adapters/discord/state.json` management.
+  - Implement `lastSyncedMessageId` tracking and persistence.
+  - Update `src/adapter-discord/forwarder.ts` to load initial state and update it during the forwarding loop.
+  - Create unit tests for state management.
+- **Status:** Completed. Verified with unit tests and full automated checks.
+
+### Step 8: Debouncing & Robustness
+- **Goal:** Improve adapter reliability with message aggregation and error handling.
+- **Tasks:**
+  - Create `Debouncer` utility in `src/adapter-discord/utils.ts`.
+  - Use `Debouncer` in `src/adapter-discord/index.ts` to aggregate messages sent within 1 second.
+  - Implement exponential backoff for daemon connection retries in `src/adapter-discord/forwarder.ts`.
+  - Add/Update unit tests for debouncing and backoff logic.
+- **Status:** Completed. Verified with unit tests and full automated checks.
+
+### Step 9: Documentation
+- **Goal:** Create setup documentation for the Discord adapter.
+- **Tasks:**
+  - Create `./docs/guides/discord_adapter_setup.md` with instructions for bot creation, token retrieval, and configuration. (Done)
+- **Status:** Completed. Documentation created and verified.
+
+## Final Review
+- All steps for the Discord adapter are completed.
+- Unit and integration tests cover all core components (client, config, forwarder, state, utils, index).
+- TRPC observation enhancement implemented in daemon to support real-time message forwarding.
+- State management ensures no messages are missed during restarts.
+- Setup documentation provided.

package/docs/09_discord_adapter/notes.md

@@ -0,0 +1,18 @@
+# Research Notes for Discord Adapter
+
+## Architecture
+- The daemon handles running commands and stores messages in `.gemini/chats/<chat_id>/chat.jsonl`.
+- The CLI (`src/cli/client.ts`) communicates with the daemon via TRPC over a Unix socket (`http://localhost` using a custom fetch with `socketPath`).
+- The TRPC router (`src/daemon/router.ts`) exposes endpoints like `sendMessage` to trigger an agent run.
+- There is currently no TRPC endpoint to *read* messages or *subscribe* to new messages, though `src/shared/chats.ts` provides `getMessages` and `listChats` to read from the filesystem directly.
+- The adapter will be a new top-level entry point (e.g., `src/adapter-discord/`) or a CLI command (e.g. `clawmini-lite discord-adapter`). The prompt implies a standalone CLI (`its own src/adapter-discord/ CLI`).
+
+## Requirements Extracted
+- **Security:** Ensure ONLY one configured user can communicate with it. Messages from other users must be ignored or logged as an error.
+- **Bi-directional forwarding:**
+  - Discord -> Daemon: Listen for messages from Discord (via discord.js or similar), verify user ID, send via TRPC `sendMessage` (or equivalent).
+  - Daemon -> Discord: Watch for new messages in the `chat.jsonl` file (or add a TRPC subscription), and send them to the Discord user via the bot.
+- **Startup Sync:** Upon startup, check for any missed messages in both directions.
+- **Debouncing:** Debounce incoming messages to prevent duplication.
+- **Configuration:** Needs a Discord Bot Token, a single allowed Discord User ID, and potentially the Chat ID to sync with (or it could sync with a specific chat or the default chat).
+- **Documentation:** Step-by-step setup instructions in `./docs/guides/discord_adapter_setup.md`.

package/docs/09_discord_adapter/prd.md

@@ -0,0 +1,57 @@
+# PRD: Discord Adapter for Clawmini
+
+## Vision
+To provide a seamless, secure, and optional way for users to interact with their Clawmini agents via Discord. This allows users to leverage Discord's mobile and desktop interfaces as a bridge to their local development workflows, while maintaining strict security through single-user authorization.
+
+## Product/Market Background
+Clawmini is a local-first agentic CLI tool. While the terminal and web interface are powerful, users often want to interact with their agents on the go or through familiar communication apps. Discord is a natural fit for developers, offering robust APIs, cross-platform support, and a structured environment (channels/threads) that maps well to chat-based agent interactions.
+
+## Use Cases
+- **Mobile Access:** A developer wants to check the status of a long-running task or trigger a quick agent action from their phone.
+- **Unified Interface:** A user wants to keep their agent interactions alongside their other developer communications in Discord.
+- **Asynchronous Interaction:** A user sends a message to an agent on Discord, goes offline, and checks the agent's detailed output later when they return to their workstation.
+
+## Requirements
+
+### 1. Discord Bot Adapter (CLI)
+- A new standalone CLI component located in `src/adapter-discord/`.
+- Communicates with the Clawmini daemon via TRPC over a Unix socket.
+- Manages a Discord Bot connection using a bot token provided in configuration.
+
+### 2. Security & Authorization
+- **Single User Lock:** The adapter MUST be configured with a specific Discord User ID.
+- **Strict Filtering:** The bot MUST ignore all messages (and log an error for unauthorized attempts) from any user other than the configured ID.
+- **Local Config:** Bot tokens and User IDs are stored locally in `.clawmini/adapters/discord/config.json`.
+
+### 3. Bi-directional Synchronization
+- **Discord -> Daemon:**
+  - Listen for DMs from the authorized user.
+  - Forward messages to the Clawmini daemon using the `sendMessage` TRPC endpoint.
+  - Map the Discord DM channel to a specific Clawmini chat (1:1 mapping).
+- **Daemon -> Discord:**
+  - The daemon will be updated to support a message subscription/observation mechanism.
+  - The adapter will subscribe to new messages from the daemon and forward them to the appropriate Discord channel.
+  - Support "replay" on startup: Check for messages in the daemon's history that haven't been synced to Discord yet.
+
+### 4. Reliability & State Management
+- **Sync State:** Store a local cursor (e.g., last synced message timestamp or ID) in `.clawmini/adapters/discord/state.json` to prevent duplicates and ensure no messages are missed during downtime.
+- **Debouncing:** Implement debouncing for incoming messages to handle rapid-fire inputs or redundant events.
+- **Startup Sync:** On launch, the adapter syncs any missed messages in both directions.
+
+### 5. Daemon Enhancements
+- Add a new TRPC endpoint or event-driven mechanism to the daemon to allow external adapters (and the `web` interface) to receive real-time message updates without polling the filesystem.
+
+### 6. Documentation
+- Provide a step-by-step setup guide in `./docs/guides/discord_adapter_setup.md` covering:
+  - Creating a Discord Application/Bot in the Developer Portal.
+  - Retrieving the Bot Token.
+  - Finding your Discord User ID.
+  - Configuring and running the adapter.
+
+## Privacy & Security
+- **No Data Exfiltration:** The adapter only forwards messages to the user's own Discord DM channel. No data is sent to third-party servers other than Discord's own infrastructure.
+- **Token Safety:** Bot tokens must never be logged or shared.
+- **Access Control:** The single-user lock is the primary defense against unauthorized agent access.
+
+## Accessibility
+- Leverages Discord's native accessibility features (screen readers, high contrast modes) for interacting with Clawmini.

package/docs/09_discord_adapter/questions.md

@@ -0,0 +1,16 @@
+# Questions for Discord Adapter
+
+1. **Adapter Scope:** Should the Discord adapter sync with only the `default` chat, or should the user be able to specify a `chatId` to sync with (or multiple)?
+   - **Answer:** There should always be a 1:1 mapping between discord channels/DMs and clawmini chats.
+
+2. **Daemon Output Synchronization:** Since the daemon writes messages directly to `.gemini/chats/<chatId>/chat.jsonl`, should the adapter simply tail/watch this file to detect new messages to forward to Discord, or should we add a new TRPC endpoint for reading/subscribing to messages?
+   - **Answer:** Let's add support to the daemon; and the CLI's `web` command should likely use the same endpoint to receive messages. We can move its logic for observing the chat's jsonl file to the daemon.
+
+3. **Persisting Sync State:** To know which messages were already forwarded upon startup, should the adapter store a local cursor (e.g. last read message ID or timestamp) in a file like `.gemini/discord-cursor.json`?
+   - **Answer:** Yes, let's let adapters store config + state in `.clawmini/adapters/discord/{config,state}.json`.
+
+4. **Discord Bot vs User Token:** I assume we are using a standard Discord Bot application (requires a bot token) rather than a selfbot (user token), which requires the user to create a bot in the Discord Developer Portal and invite it to a server or DM it directly. Is this correct?
+   - **Answer:** Yes, standard Discord Bot.
+
+5. **Direct Messages vs Channel:** Should the bot only respond to Direct Messages from the configured user, or also respond to messages in a specific channel where the configured user mentions the bot?
+   - **Answer:** Start with just DMs for now, but eventually support adding the bot to a server to respond in each channel. It must ignore any messages not from the configured user.