clawmini 0.0.1

package/docs/09_discord_adapter/tickets.md

@@ -0,0 +1,116 @@
+# Tickets: Discord Adapter for Clawmini
+
+## Step 1: Scaffold Discord Adapter
+- **Description:** 
+  - Create the `src/adapter-discord` directory.
+  - Create a basic entry point in `src/adapter-discord/index.ts` that logs a startup message.
+  - Update `tsdown.config.ts` to include the new entry point.
+  - Add `discord.js` to `package.json` dependencies.
+- **Verification:**
+  - `npm run check` passes.
+  - `npm run build` generates `dist/adapter-discord/index.mjs`.
+  - Running `node dist/adapter-discord/index.mjs` prints the startup message.
+- **Status:** completed
+
+## Step 2: Configuration & Security Implementation
+- **Description:** 
+  - Define the configuration schema using Zod in `src/adapter-discord/config.ts`.
+  - Implement logic to load configuration from `.clawmini/adapters/discord/config.json`.
+  - Implement an `isAuthorized(userId: string)` helper to filter Discord messages.
+- **Verification:**
+  - Unit tests in `src/adapter-discord/config.test.ts` for schema validation and file loading.
+  - Unit tests for the authorization filter.
+  - `npm run format:check && npm run lint && npm run check && npm run test` passes.
+- **Status:** completed
+
+## Step 3: TRPC Client Connection
+- **Description:** 
+  - Implement a TRPC client in `src/adapter-discord/client.ts` that connects to the daemon via the Unix socket, leveraging the shared logic in `src/shared/fetch.ts` if possible.
+- **Verification:**
+  - Integration test mocking the Unix socket and verifying TRPC calls from the adapter client.
+  - `npm run check && npm run test` passes.
+- **Status:** completed
+
+## Step 4: Discord to Daemon Forwarding
+- **Description:** 
+  - Initialize the `discord.js` client in `src/adapter-discord/index.ts`.
+  - Listen for `messageCreate` events in DM channels.
+  - Validate the sender using the authorized user ID.
+  - Forward the message content to the daemon using the `sendMessage` TRPC endpoint.
+- **Verification:**
+  - Mocked `discord.js` event test verifying that receiving a DM triggers a TRPC `sendMessage` call.
+  - `npm run format:check && npm run lint && npm run check && npm run test` passes.
+- **Status:** completed
+
+## Step 5: Daemon Message Observation Enhancement
+- **Description:** 
+  - Update `src/daemon/router.ts` and related files to support message observation. 
+  - Since TRPC 11 is used, consider adding an SSE or long-polling endpoint if full subscriptions aren't trivial in the current Unix socket setup, or just a `getMessagesAfter(timestamp)` endpoint.
+  - *Note:* The PRD suggests "message subscription/observation mechanism".
+- **Verification:**
+  - Unit/Integration tests for the new observation endpoint.
+  - Verify that sending a message via TRPC results in the observer being notified.
+  - `npm run check && npm run test` passes.
+- **Status:** completed
+
+## Step 6: Daemon to Discord Forwarding
+- **Description:** 
+  - In the adapter, use the new observation mechanism to listen for new messages from the daemon.
+  - When a new message is received, send it to the authorized user's Discord DM channel using the bot client.
+- **Verification:**
+  - Integration test verifying that a message appearing in the daemon's observation stream is forwarded to the Discord mock client.
+  - `npm run check && npm run test` passes.
+- **Status:** completed
+
+## Step 7: State Management & Startup Sync
+- **Description:** 
+  - Implement `src/adapter-discord/state.ts` to manage `.clawmini/adapters/discord/state.json`.
+  - Track the `lastSyncedMessageId` or timestamp.
+  - On adapter startup, fetch all messages from the daemon after the stored cursor and send them to Discord.
+- **Verification:**
+  - Unit tests for state persistence.
+  - Integration test for the startup sync logic.
+  - `npm run check && npm run test` passes.
+- **Status:** completed
+
+## Step 8: Debouncing & Robustness
+- **Description:** 
+  - Add debouncing logic to handle rapid Discord messages (if necessary for the daemon's message queue).
+  - Improve error handling (e.g., bot reconnect logic, daemon connection retry).
+- **Verification:**
+  - Unit tests for debouncing.
+  - `npm run format:check && npm run lint && npm run check && npm run test` passes.
+- **Status:** completed
+
+## Step 9: Documentation
+- **Description:** 
+  - Create `./docs/guides/discord_adapter_setup.md` with full setup instructions.
+- **Verification:**
+  - File exists and contains clear steps for Bot creation, Token retrieval, and Configuration.
+- **Status:** completed
+
+## Issue 1: Performance bug in `waitForMessages`
+- **Priority:** High
+- **Description:** 
+  - In `src/daemon/router.ts`, `waitForMessages` reads the entire `chat.jsonl` file to check for new messages even when `input.lastMessageId` is undefined. This causes unnecessary and expensive file I/O operations every time the long-polling request fires.
+  - Fix by wrapping the initial `getMessages` call in an `if (input.lastMessageId)` block.
+- **Status:** completed
+
+## Issue 2: `chunkString` breaks multi-byte characters (emojis/unicode)
+- **Priority:** High
+- **Description:** 
+  - In `src/adapter-discord/forwarder.ts`, `chunkString` uses `String.prototype.slice()` directly. This splits strings by UTF-16 code units rather than code points, which will corrupt emojis and special characters if they land on a chunk boundary.
+  - Fix by using `Array.from(str)` to safely count and chunk by unicode characters.
+- **Status:** completed
+
+## Issue 3: Redundant existence check in `initDiscordConfig`
+- **Priority:** Medium
+- **Description:** 
+  - `fs.existsSync(configDir)` check is redundant in `initDiscordConfig` (`src/adapter-discord/config.ts`) because `fsPromises.mkdir(configDir, { recursive: true })` handles existing directories natively.
+- **Status:** completed
+
+## Issue 4: Unnecessary `GatewayIntentBits.Guilds` requested
+- **Priority:** Low
+- **Description:** 
+  - In `src/adapter-discord/index.ts`, `GatewayIntentBits.Guilds` is requested but the bot explicitly ignores all guild messages (`if (message.guild) return;`). It should be removed to follow the principle of least privilege.
+- **Status:** completed

package/docs/10_file_attachments/development_log.md

@@ -0,0 +1,55 @@
+# Development Log
+
+- Implemented Ticket 1: Configuration Updates.
+- Added optional `files` string property (defaulting to `"./attachments"`) to `SettingsSchema` and `AgentSchema` in `src/shared/config.ts`.
+- Added optional `maxAttachmentSizeMB` number property (defaulting to `25`) to `DiscordConfigSchema` in `src/adapter-discord/config.ts`.
+- Added unit tests for these new properties in `src/shared/config.test.ts` and `src/adapter-discord/config.test.ts`.
+- Updated test for `Agent Settings read/write` in `src/shared/workspace.test.ts` to accommodate the default `files` parameter.
+- Ran all verification checks (`npm run format:check && npm run lint && npm run check && npm run test`), successfully passing.
+
+- Implemented Ticket 2: TRPC Schema and Discord Adapter Download.
+- Updated `sendMessage` payload schema in `src/daemon/router.ts` to accept an optional array of strings for `files`.
+- Modified `src/adapter-discord/index.ts` to download Discord attachments to a temporary directory (`.gemini/tmp/discord-files/`), respecting the `maxAttachmentSizeMB` limit.
+- Updated `messageDebouncer` in the Discord adapter to aggregate both message content and temporary file paths before forwarding to the daemon.
+- Added comprehensive unit tests in `src/adapter-discord/index.test.ts` for downloading attachments, size limit enforcement, and updated mock dependencies appropriately.
+- Fixed a minor logging bug regarding the fallback default for `maxAttachmentSizeMB`.
+- Re-ran all tests and formatting checks successfully.
+
+- Implemented Ticket 3: Daemon Processing of Incoming Files.
+- Updated `sendMessage` schema in `src/daemon/router.ts` to include an optional `adapter` property.
+- Modified the Discord adapter in `src/adapter-discord/index.ts` to explicitly provide `adapter: 'discord'`.
+- Intercepted incoming file paths in `src/daemon/router.ts` immediately before `handleUserMessage`.
+- Moved temporary files into the configured agent's `files` directory (namespaced by the adapter name).
+- Implemented file name collision resolution using a timestamp suffix.
+- Appended the finalized relative file paths to the user's message context automatically.
+- Added comprehensive unit tests in `src/daemon/router.test.ts` to cover file moving logic, collision handling, and message text formatting.
+- Updated the existing mock configurations and fixed linting warnings (e.g. `import('node:fs').Stats`, unused errors).
+- All checks (`npm run format:check && npm run lint && npm run check && npm run test`) pass successfully.
+
+- Implemented Ticket 4: Outgoing Files via CLI & Daemon (Agent to User).
+- Updated the internal `CommandLogMessage` schema in `src/shared/chats.ts` to include an optional `file` property.
+- Modified the `logMessage` endpoint in `src/daemon/router.ts` to accept an optional `file` path, with robust path traversal validation ensuring the file resolves inside the agent workspace.
+- Disabled `max-lines` for `src/daemon/router.ts` due to expanded file logging checks.
+- Updated `messagesCmd` in `src/cli/commands/messages.ts` to parse a new `-f, --file <path>` argument.
+- Enhanced `clawmini-lite log` command in `src/cli/lite.ts` to support the `--file` flag and pass it to the `logMessage` endpoint.
+- Added comprehensive unit tests in `src/daemon/router.test.ts` verifying path validation and log schemas.
+- Expanded end-to-end tests in `src/cli/e2e/messages.test.ts` and `src/cli/e2e/export-lite-func.test.ts` for explicit file handling and logging functionalities.
+- Ran all format, lint, and type checking pipelines successfully.
+
+- Implemented Ticket 5: Discord Adapter Forwarding Outgoing Files.
+- Updated `src/adapter-discord/forwarder.ts` to check for `message.file` when processing log messages from the daemon.
+- Updated `dm.send()` to include file attachments using the `files` array option in Discord.js.
+- Handled the 2000 character limit by correctly splitting messages into chunks, attaching the file only to the final chunk.
+- Updated existing forwarder tests in `src/adapter-discord/forwarder.test.ts` to use object payloads instead of string values.
+- Added comprehensive test cases ensuring files are forwarded, chunked messages handle attachments correctly, and empty messages with just file paths work without errors.
+- Ran formatting, linting, and tests successfully.
+
+- Implemented Ticket 7: Path Validation Security Enhancements.
+- Updated `sendMessage` mutation in `src/daemon/router.ts` to strictly validate `targetDir` is within the workspace using `pathIsInsideDir`.
+- Ensured all incoming `files` are strictly inside `$WORKSPACE/.clawmini/tmp/` and actually exist via `fs.access`.
+- Updated `logMessage` mutation to forbid absolute paths and path traversal `..` in the `file` input.
+- Validated that the resolved file path in `logMessage` stays strictly within both the agent's folder and the overall workspace.
+- Enforced file existence checks on disk before persisting log entries.
+- Modified `src/cli/commands/messages.ts` (CLI send command) to automatically copy attached files to `.clawmini/tmp` prior to submitting them to the daemon.
+- Enhanced tests in `src/daemon/router.test.ts` to assert security validations for both `sendMessage` and `logMessage`.
+- Tests all run successfully including format, lint, type checking, and test suites.- Implemented Ticket 6: Code Critique and Fixes. Fixed DRY violation in src/daemon/router.ts when resolving agent.directory by creating resolveAgentDir and getUniquePath utilities. Other tasks in Ticket 6 were already completed.

package/docs/10_file_attachments/notes.md

@@ -0,0 +1,59 @@
+# File Attachments - Research Notes
+
+## Current Architecture
+- Incoming messages from Discord are received in `src/adapter-discord/index.ts` via `Events.MessageCreate`.
+- Only `message.content` is currently processed and added to the debouncer, then sent to the daemon via `trpc.sendMessage.mutate`.
+- The daemon appends a `UserMessage` to the chat log (`chat.jsonl`).
+- The agent is executed and logs the result as a `CommandLogMessage` (or a router log).
+- `src/adapter-discord/forwarder.ts` subscribes to new messages via `trpc.waitForMessages`. It reads `CommandLogMessage` logs and forwards `message.content` via `dm.send()`.
+
+## Missing Features for Attachments
+1. **Downloading incoming attachments:**
+   - Discord's `message.attachments` contains attachments.
+   - We need to download them locally to a directory.
+   - Proposed location: `[workspace_root]/.gemini/chats/[chatId]/files/` or a temporary directory like `.gemini/tmp/discord-files/`.
+2. **Referencing attachments in the input message:**
+   - Once downloaded, we need to append or prepend `File attached: <path>` to the user's message before sending it to the daemon.
+3. **Path Translation:**
+   - The user noted that the agent might be running in a VM/container with different absolute paths.
+   - If we save the file to the host's `/home/user/workspace/discord-files/...` and pass this absolute path, the container won't find it.
+   - **Solution ideas:**
+     - Use relative paths from the workspace root (e.g., `.gemini/chats/default/files/file.txt`).
+     - Introduce path mapping in the configuration (e.g., `pathMappings: [{ host: '/home/user/...', container: '/workspace/...' }]`).
+4. **Outgoing attachments:**
+   - The agent will output `File attached: <path>`.
+   - The Discord adapter needs to parse this from the `content` or have it explicitly represented in the `CommandLogMessage` schema.
+   - It will need to read the file from the filesystem and attach it using `dm.send({ files: [path] })`.
+
+## Refined approach (Q1)
+- Agent settings will define a `files` directory (e.g., `./attachments`).
+- Discord adapter saves incoming files to a temporary location: `.clawmini/adapters/discord/files/foo.png`.
+- The adapter includes the paths to these temp files in the RPC message sent to the daemon.
+- The daemon intercepts these paths, moves the files into the agent's configured `files` directory, namespaced by the adapter (e.g., `./attachments/discord/foo.png`), and prepends these final relative/absolute paths to the user message.
+
+## Refined approach (Q2)
+- To avoid absolute path mapping issues for containerized agents, pass the file paths relative to the agent's working directory (e.g., `./attachments/discord/foo.png`), leveraging the fact that the agent executes within its specific folder.
+
+## Refined approach (Q3)
+- For outgoing files, instead of relying on parsing log messages, agents will use the `clawmini-lite` client to explicitly send a file back: `clawmini-lite messages send --file ./path/to/file "here you go"`.
+- This API call will be authenticated via `$CLAW_API_TOKEN`, routed to the daemon, and appended to the chat, subsequently picked up by the adapter and sent to Discord.
+
+## Refined approach (Q4)
+- File limits: allow configuration in discord adapter settings, with reasonable defaults (e.g. 10MB or 25MB).
+- Default agent files directory: `./attachments`.
+
+## Path Validation Security Enhancements
+Based on the new request, strict path validation is required for both incoming and outgoing files to ensure security and prevent path traversal or leaking arbitrary files.
+
+**For incoming messages (User -> Agent):**
+- In `sendMessage` TRPC endpoint (`src/daemon/router.ts`), before processing `input.data.files`:
+  - Verify every file path exists.
+  - Verify every file path is strictly located within `$WORKSPACE/.clawmini/tmp/`.
+  - Verify that the target directory (`targetDir`) where files are being moved is strictly within `$WORKSPACE`.
+
+**For outgoing files (Agent -> User):**
+- In `logMessage` TRPC endpoint (`src/daemon/router.ts`), when processing `input.file`:
+  - Ensure `input.file` is a relative path (e.g., does not start with `/` or `C:\`).
+  - Ensure the resolved path is within the agent's designated directory.
+  - Ensure the resolved path is within the overall `$WORKSPACE`.
+  - Ensure the file actually exists on the filesystem *before* resolving it or recording it in the log message.

package/docs/10_file_attachments/prd.md

@@ -0,0 +1,73 @@
+# Product Requirements Document (PRD): File Attachments
+
+## 1. Vision
+Enable seamless sharing of files and attachments between users (via Discord) and the backend agents executing inside containers or local environments. This functionality provides a crucial building block for multimodal interactions and more sophisticated workflows where agents manipulate, review, or generate binary/text artifacts.
+
+## 2. Product/Market Background
+Currently, the Discord adapter receives incoming text messages and forwards them to the Clawmini daemon. The daemon writes these to `chat.jsonl` and invokes the configured agent, capturing stdout/stderr as logs and text responses.
+However, modern generative AI and bot interactions often involve files—such as sending a source code file to be debugged, an image to be analyzed, or requesting the bot to generate and return a PDF.
+
+By supporting attachments natively:
+- **Users** can simply upload files in Discord and get them analyzed by an agent.
+- **Agents** can generate files (logs, assets, exported data) and send them explicitly back to the user on Discord.
+
+## 3. Use Cases
+- **User to Agent (Incoming):** A user drag-and-drops an image or a `.csv` file into a Discord DM. The agent receives the path to the file on its local filesystem, reads it, processes it, and returns an analysis in text.
+- **Agent to User (Outgoing):** An agent is tasked with scraping a website and generating a `.zip` archive. Once complete, the agent uses the `clawmini-lite` CLI tool to send the archive directly back to the user on Discord alongside a confirmation message.
+
+## 4. Requirements
+
+### 4.1 Configuration Updates
+1. **Agent Configuration (`SettingsSchema` / `AgentSchema`)**
+   - Agents should support a new configuration property for defining the files directory, with a default of `./attachments`.
+     - Example: `files: "./attachments"`
+
+2. **Discord Adapter Configuration (`DiscordConfigSchema`)**
+   - The Discord adapter should support configurable file size limits for incoming files to prevent abuse or disk space exhaustion.
+   - New optional config values:
+     - `maxAttachmentSizeMB`: e.g., default `25` (to match Discord's standard limits).
+
+### 4.2 Incoming File Attachments (Discord -> Agent)
+1. **Adapter Processing:**
+   - On receiving a `MessageCreate` event with `message.attachments`, the Discord adapter will download the files to a local, temporary directory (e.g., `.clawmini/adapters/discord/files/`).
+   - The adapter will construct a message payload to send to the daemon via TRPC (`sendMessage.mutate`) that includes both the user's text and a list of temporary file paths.
+     - *Note: This implies extending the TRPC payload or embedding the file data/paths in a structured way.*
+
+2. **Daemon Processing:**
+   - The daemon intercepts the TRPC message containing the temporary file paths.
+   - It resolves the target agent and determines the agent's `files` directory (defaulting to `./attachments`).
+   - The daemon moves the temporary files from the adapter's directory to the agent's files directory, namespaced by the adapter (e.g., `./attachments/discord/<filename>`).
+   - The daemon prepends or appends a standard reference to these files in the input message string provided to the agent:
+     - Example format: `Attached files:
+- ./attachments/discord/foo.png
+
+<user message>`
+   - The agent is then executed within its directory, allowing it to reliably find the files using the relative paths.
+
+### 4.3 Outgoing File Attachments (Agent -> Discord)
+1. **Agent Execution:**
+   - Rather than parsing text logs for magic strings (e.g., `File attached:`), agents will use an explicit API via the `clawmini-lite` client to send files back to the user.
+   - Example CLI usage: `clawmini-lite messages send --file ./attachments/out/foo.png "Here is your generated file."`
+
+2. **Daemon / CLI Integration:**
+   - The `clawmini-lite messages send` command will be updated to accept a `--file` flag.
+   - It will use the `$CLAW_API_TOKEN` and `$CLAW_API_URL` to authenticate and route the file-sending request to the daemon.
+   - The daemon will record a `CommandLogMessage` (or a new message type) in the `chat.jsonl` that explicitly defines the file path to be returned.
+
+3. **Discord Adapter Forwarding:**
+   - The `forwarder.ts` process, which subscribes to the `waitForMessages` TRPC endpoint, will read these new structured messages.
+   - If a message contains an outgoing file path, it will verify the file exists locally and attach it to the Discord DM using `dm.send({ content: message.content, files: [filePath] })`.
+
+### 4.4 Technical Constraints & Security
+- **File Limits:** Enforce `maxAttachmentSizeMB` in the Discord adapter. If a file exceeds this limit, ignore it or notify the user.
+- **Strict Path Validation (Incoming):** For incoming files, the daemon must verify that all provided temporary file paths exist and are strictly located within `$WORKSPACE/.clawmini/tmp/`. It must also ensure the target destination is within the `$WORKSPACE`.
+- **Strict Path Validation (Outgoing):** For outgoing files logged by the agent, the daemon must ensure the file path is a relative path, that it resolves to a location within the agent's subfolder and the overall `$WORKSPACE`, and that the file actually exists before processing the log.
+- **Path Traversal:** Ensure that file paths submitted by `clawmini-lite` or handled by the daemon do not allow directory traversal (e.g., `../../etc/passwd`). Validate that target paths stay within the `files` directory or the agent's workspace.
+- **File Name Collisions:** If two files with the same name are uploaded, standard conflict resolution should occur (e.g., appending a timestamp or UUID to the filename before saving to the agent's directory).
+
+## 5. Next Steps
+- Expand the TRPC `sendMessage` schema to accept file paths.
+- Update `adapter-discord` to handle downloads and configuration updates.
+- Update the daemon router pipeline to process and move incoming files.
+- Update `clawmini-lite` and the daemon to support explicit outbound file sharing.
+- Update the `adapter-discord` forwarder to handle outbound files.

package/docs/10_file_attachments/questions.md

@@ -0,0 +1,15 @@
+# File Attachments - Questions & Answers
+
+## Questions
+
+1. Where should downloaded incoming file attachments be stored on the host filesystem?
+**Answer:** They could be in a per-agent directory, like `./my-agent/attachments/discord/`. The agent settings can define a files directory (`./attachments`), and we can create folders/files as appropriate. The Discord adapter could save the file initially to `.clawmini/adapters/discord/files/foo.png`, then include those paths in the chat message to the daemon; then once the daemon figures out the agent's files directory it can move the file there (namespaced by the adapter) and prepend the file paths to the message.
+
+2. To handle path translation between the host (where the daemon runs) and the agent container/VM, should we just pass the file paths relative to the agent's working directory (e.g., `attachments/discord/foo.png`), or do we need explicit path mapping configurations in the agent's settings to map absolute host paths to absolute container paths?
+**Answer:** Yes, we should do something like `./attachments/discord/foo.png`, since we know that the agent will be run in its agent folder.
+
+3. For outgoing file attachments (from the agent back to Discord), how should the agent signal this to the daemon/adapter? Should the adapter parse a specific string format (e.g., `File attached: ./attachments/out/foo.png`) from the message content, or should we introduce a new command extraction method (like `getAttachedFiles`) in the agent's schema to explicitly parse out the file paths into a structured array on the `CommandLogMessage` payload?
+**Answer:** Perhaps we can use the clawmini-lite script to let agents send a file back to the user. For instance, `clawmini-lite messages send --file ./path/to/file "here you go"`. It would go to the corresponding chat, and be sent from the corresponding agent; according to the `$CLAW_API_TOKEN`.
+
+4. Are there any maximum file size limits or file type restrictions we should enforce, either when downloading from Discord or when an agent sends a file back via `clawmini-lite`? Also, what should the daemon do if an incoming message has attachments but the selected agent hasn't configured a `files` directory?
+**Answer:** For file size limits, we should let the user set limits in the discord adapter settings; but we should set reasonable defaults if none are specified. we should default to ./attachments as the file's directory.

package/docs/10_file_attachments/tickets.md

@@ -0,0 +1,88 @@
+# File Attachments Implementation Tickets
+
+## Ticket 1: Configuration Updates
+**Description:** Update the configuration schemas for both the Agent and the Discord Adapter to support file attachments.
+**Tasks:**
+- Update `SettingsSchema` / `AgentSchema` to include a new optional `files` string property (defaulting to `"./attachments"`).
+- Update `DiscordConfigSchema` to include an optional `maxAttachmentSizeMB` number property (defaulting to `25`).
+**Verification:**
+- Add unit tests validating the new properties and defaults in both schemas.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** Complete
+
+## Ticket 2: TRPC Schema and Discord Adapter Download
+**Description:** Update the message payload schema to accept file paths and implement downloading incoming attachments in the Discord adapter.
+**Tasks:**
+- Extend the TRPC `sendMessage` payload schema to optionally include a list of temporary file paths.
+- In `src/adapter-discord/index.ts` (or the relevant event handler), implement downloading of Discord `message.attachments` to a temporary directory (e.g., `.gemini/tmp/discord-files/`).
+- Enforce the `maxAttachmentSizeMB` limit during the download process.
+- Pass the downloaded temporary file paths to the daemon via the updated `sendMessage.mutate` TRPC call.
+**Verification:**
+- Write unit/integration tests for the Discord adapter verifying that attachments are correctly downloaded and size limits are respected.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** Complete
+
+## Ticket 3: Daemon Processing of Incoming Files
+**Description:** Implement the daemon logic to intercept the incoming temporary files, move them to the agent's workspace, and format the user message.
+**Tasks:**
+- Update the daemon's message processing pipeline (e.g., `src/daemon/router.ts` or relevant message handler) to intercept `sendMessage` requests containing file paths.
+- Resolve the target agent's `files` configuration directory.
+- Move the temporary files to the agent's files directory, namespacing them by the adapter (e.g., `<agent_files_dir>/discord/<filename>`).
+- Implement file name collision resolution (e.g., appending a timestamp or short UUID to duplicate filenames).
+- Prepend or append the list of finalized relative file paths to the user's input message text before passing it to the agent.
+**Verification:**
+- Add unit tests for the daemon's file moving logic, collision resolution, and message text formatting.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** Complete
+
+## Ticket 4: Outgoing Files via CLI & Daemon (Agent to User)
+**Description:** Enable agents to send files back to the user explicitly via the CLI, and update the daemon to record these paths.
+**Tasks:**
+- Update the `messages send` command in the `lite` CLI (`src/cli/commands/messages.ts` / `src/cli/lite.ts`) to accept a new `--file` argument.
+- Update the underlying API/TRPC endpoint used by the CLI to accept and process this outgoing file path.
+- In the daemon, implement path validation to ensure the provided file path does not contain directory traversal vulnerabilities (e.g., `../../`) and resolves within the agent's workspace.
+- Update the internal chat log schema (e.g., `CommandLogMessage`) to store the explicit outgoing file path.
+**Verification:**
+- Add unit tests for the CLI's `--file` argument parsing.
+- Add unit tests for the daemon's path traversal validation and log recording.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** Complete
+
+## Ticket 5: Discord Adapter Forwarding Outgoing Files
+**Description:** Update the Discord adapter's forwarder to read outgoing file paths from the chat log and send them as Discord attachments.
+**Tasks:**
+- Update `src/adapter-discord/forwarder.ts` to detect when a new message/log from the daemon contains an outgoing file path.
+- Read the file from the local filesystem.
+- Modify the `dm.send()` call to include the file as an attachment (`files: [path]`) alongside the message content.
+**Verification:**
+- Add tests for the forwarder verifying that messages with attached file paths result in the correct `dm.send` payload.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** Complete
+
+## Ticket 6: Code Critique and Fixes
+**Description:** Address DRY, YAGNI, naming, comments, and path violations in the initial file attachment implementation.
+**Tasks:**
+- High Priority: Update temporary download path for discord attachments to `.clawmini/adapters/discord/tmp` instead of `.gemini/tmp/discord-files`.
+- Medium Priority: Fix DRY violation and bug in `src/daemon/router.ts` where `sendMessage` did not correctly respect `agent.directory` when resolving the target files directory.
+- Medium Priority: Create a local `getUniquePath` utility in `src/daemon/router.ts` for DRYer renaming logic.
+- Low Priority: Remove `JSON.stringify` workaround in `src/adapter-discord/index.ts` Debouncer instantiation by updating the `Debouncer` class to accept an optional custom `isEqual` function.
+- Low Priority: Fix `any` typings in `src/adapter-discord/forwarder.ts` by using `MessageCreateOptions`.
+- Low Priority: Fix flaky e2e test `should maintain atomic ordering of user and log messages with --no-wait`.
+**Status:** Complete
+
+## Ticket 7: Path Validation Security Enhancements
+**Description:** Implement strict path validation and checks for incoming and outgoing file attachments to ensure security and prevent path traversal.
+**Tasks:**
+- Update `src/daemon/router.ts` (or relevant handler) for incoming files (`sendMessage` mutation):
+  - Verify that all files in `input.data.files` exist on the filesystem.
+  - Verify that all files are strictly within the `$WORKSPACE/.clawmini/tmp/` directory.
+  - Verify that the target directory (`targetDir`) where files will be moved is strictly within `$WORKSPACE`.
+- Update `src/daemon/router.ts` for outgoing files (`logMessage` mutation):
+  - Ensure `input.file` is a relative path.
+  - Ensure the file path resolves to a location within the agent's subfolder AND within `$WORKSPACE`.
+  - Verify the file actually exists on the filesystem *before* resolving it to an absolute path and recording it.
+- Ensure all relevant checks use a secure path comparison method (e.g., `pathIsInsideDir`).
+**Verification:**
+- Add unit tests verifying validation failures for absolute paths, non-existent files, files outside `.clawmini/tmp/` (for incoming), and files outside the agent folder/workspace (for outgoing).
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** Complete

package/docs/11_message_verbosity/development_log.md

@@ -0,0 +1,43 @@
+# Development Log: 11_message_verbosity
+
+## Ticket 1: Update Data Model
+- Updated `src/shared/chats.ts` to add the optional `level` property to the `CommandLogMessage` interface. The property can be `'default' | 'debug' | 'verbose'`.
+- Ran tests (`npm run format:check && npm run lint && npm run check && npm run test`) and confirmed that they all passed successfully.
+
+## Ticket 2: Update Daemon Message Generation
+- Modified `src/daemon/message.ts` to add `level: 'verbose'` conditionally when generating `CommandLogMessage` objects for router, retry, and main results if `NO_REPLY_NECESSARY` is present in their contents.
+- Fixed TypeScript `exactOptionalPropertyTypes` constraint by conditionally spreading the `level` property and using `delete logMsg.level` instead of setting it to `undefined`.
+- Added unit tests in `src/daemon/message-verbosity.test.ts` to verify log messages correctly receive the `verbose` level when `NO_REPLY_NECESSARY` is printed.
+- Configured ESLint overrides and formatting in the new test file to resolve linting failures.
+- Ran all required validation checks (`npm run format:check`, `npm run lint`, `npm run check`, `npm run test`) and confirmed full suite success.
+
+## Ticket 3: Update Web UI State Management
+- Replaced the boolean `debugView` with a string `verbosityLevel` (values: `'default' | 'debug' | 'verbose'`) in `web/src/lib/app-state.svelte.ts`.
+- Implemented temporary shims in `web/src/routes/+layout.svelte` and `web/src/routes/chats/[id]/+page.svelte` to translate the new string type back to the boolean checks expected by existing UI components in order to maintain a passing build until subsequent UI tickets are fulfilled.
+- Updated `web/src/routes/chats/[id]/page.svelte.spec.ts` to use `appState.verbosityLevel = 'verbose'`.
+- Verified changes by successfully running all typechecks and tests (`npm run check && npm run test`).
+
+## Ticket 4: Update Web UI Controls
+- Replaced the boolean `Switch` component in `web/src/routes/+layout.svelte` with a cyclical toggle button that iterates through `default`, `debug`, and `verbose` levels.
+- Added visual distinctions using `lucide-svelte` icons (`MessageSquare` for default, `Bug` for debug, `Terminal` for verbose) and varied text colors.
+- Ensured a dynamic `aria-label` is used for accessibility, indicating the current verbosity level.
+- Ran formatting, linting, type-checking, and tests (`npm run format:check && npm run lint && npm run check && npm run test`), all passing successfully.
+
+## Ticket 5: Update Web UI Message Filtering and Display
+- Updated `web/src/routes/chats/[id]/+page.svelte` to implement filtering and detailed views based on `verbosityLevel`.
+  - Added a `$derived` state `filteredMessages` to filter log messages appropriately for `default`, `debug`, and `verbose` levels.
+  - Distinct styling added for `verbose` messages (primary background tint with border).
+  - Detailed output (`command`, `stdout`, `stderr`, and `exitCode`) now display conditionally when in `verbose` mode.
+- Added `level` property to `CommandLogMessage` type in `web/src/lib/types.ts` to fix TypeScript issues and properly align with `shared/chats.ts`.
+- Updated `web/src/routes/chats/[id]/page.svelte.spec.ts` to include multiple test cases verifying the filtering behavior for `default`, `debug`, and `verbose` verbosity levels.
+- Ran formatting, linting, type-checking, and tests (`npm run format && npm run lint:fix && npm run check && npm run test`) and successfully passed all checks.
+
+## Ticket 6: Update Discord Forwarder
+- Modified `src/adapter-discord/forwarder.ts` to filter out `CommandLogMessage`s with `level: 'verbose'` from being forwarded to Discord.
+- Ensured that `writeDiscordState` is still correctly called for ignored verbose messages to keep `lastSyncedMessageId` updated, preventing an infinite loop or repeated fetches.
+- Updated unit tests in `src/adapter-discord/forwarder.test.ts` to mock and verify that verbose messages are ignored by `mockDm.send` but state gets updated via `writeDiscordState`.
+- Ran all required validation checks (`npm run format:check`, `npm run lint`, `npm run check`, `npm run test`) and confirmed they all passed successfully.
+
+## Ticket 7: Final Quality Check
+- Ran formatting, linting, type-checking, and tests (`npm run format:check && npm run lint && npm run check && npm run test`) across the entire repository.
+- Confirmed that all code meets the project's standards and all tests pass cleanly.

package/docs/11_message_verbosity/notes.md

@@ -0,0 +1,26 @@
+# Notes on Message Verbosity Feature
+
+## Current State
+- `CommandLogMessage` in `src/shared/chats.ts` currently does not have a `level` property.
+- WebUI has a boolean `appState.debugView` toggled by a `Switch` component (`web/src/routes/+layout.svelte` and `web/src/routes/chats/[id]/+page.svelte`). This toggle currently shows/hides stderr, exit codes, and command paths on log messages.
+- The Discord forwarder (`src/adapter-discord/forwarder.ts`) currently forwards all messages with `role: 'log'` as long as they have content or files.
+- Agent output is captured in `src/daemon/message.ts` via `runCommand`, putting `stdout` into the message `content`.
+- Some internal messages (like retry delays or router messages) are also stored as `CommandLogMessage`.
+
+## Requirements
+- Add `level` property to `CommandLogMessage` (optional).
+- Define enums for log levels (e.g., `default`, `debug`, `verbose`).
+- Replace the boolean toggle in the WebUI with a cyclic toggle button to switch between these three states, using good icons/colors.
+- Discord forwarder should ignore the most verbose setting by default.
+- Any message content containing `"NO_REPLY_NECESSARY"` should automatically be labeled as verbose.
+
+## Files to Update
+- **Data Model**: `src/shared/chats.ts` (Add `level` to `CommandLogMessage`, define `LogLevel` enum/type).
+- **Daemon Generation**: `src/daemon/message.ts`, `src/daemon/router.ts` (When generating a message, check if `"NO_REPLY_NECESSARY"` is in the content and set `level` to `'verbose'`. Otherwise maybe `'default'` or `'debug'` depending on the type of message - wait, the prompt says "To start, any message containing NO_REPLY_NECESSARY will be labeled as verbose").
+- **Web UI Data Model & Logic**: `web/src/lib/types.ts` (if exists), `web/src/lib/app-state.svelte.ts` (Change `debugView` to `verbosityLevel`), `web/src/routes/+layout.svelte` (Replace `Switch` with a 3-state icon button), `web/src/routes/chats/[id]/+page.svelte` (Filter or adjust display based on the selected level).
+- **Discord Forwarder**: `src/adapter-discord/forwarder.ts` (Skip forwarding if `level === 'verbose'`).
+
+## Open Questions
+- What should be the exact names of the levels? (e.g., `'default' | 'debug' | 'verbose'`)
+- What should determine if a message is `debug` vs `default` initially, other than the `NO_REPLY_NECESSARY` string rule? (Are standard agent responses `'default'`, and retry/error messages `'debug'`?)
+- In the Web UI, should a `'default'` message be visible across all levels, and `'verbose'` messages *only* visible at the `'verbose'` level? (i.e., Level filters: Default -> shows only Default; Debug -> shows Default + Debug; Verbose -> shows Default + Debug + Verbose)

package/docs/11_message_verbosity/prd.md

@@ -0,0 +1,44 @@
+# Feature: Message Verbosity Levels
+
+## Vision
+To provide users with more control over the signal-to-noise ratio in their interaction history by introducing message verbosity levels. This will allow the system to log detailed background actions or non-user-facing updates without cluttering the main conversation stream, while giving power users the ability to inspect exactly what the system is doing.
+
+## Product/Market Background
+Currently, all logs from the daemon (including agent responses, error messages, routing info, and executed commands) are grouped into a binary `debugView` toggle in the WebUI. Additionally, the Discord integration forwards every single log message to the user as long as it contains content or a file, which can lead to spam when agents are performing behind-the-scenes reasoning or repetitive tasks.
+
+By categorizing messages into `default`, `debug`, and `verbose` levels, we align with standard software logging paradigms. The user experience is simplified for the average user, while maintaining complete transparency for developers and advanced users.
+
+## Requirements
+
+### 1. Data Model (`CommandLogMessage`)
+- Introduce an optional `level` property to the `CommandLogMessage` interface in `src/shared/chats.ts`.
+- `level` should be of type `'default' | 'debug' | 'verbose'`.
+- If `level` is missing or undefined on an existing message, it should be treated as `'default'`.
+
+### 2. Message Generation (Daemon)
+- When generating a `CommandLogMessage` in the daemon (e.g., in `src/daemon/message.ts`), assign the `level` property based on the message content.
+- **Rule 1**: If the message content (e.g., agent stdout) contains the exact string `"NO_REPLY_NECESSARY"`, the message `level` must be set to `'verbose'`.
+- All other messages can default to `'default'` for now (future iterations may use `'debug'` for retry logs, etc.).
+
+### 3. Web UI Updates
+- **State Management**: Replace the boolean `appState.debugView` with a string `appState.verbosityLevel` (with values `'default' | 'debug' | 'verbose'`) in `web/src/lib/app-state.svelte.ts`. The default value should be `'default'`.
+- **UI Control**: Replace the `Switch` component in `web/src/routes/+layout.svelte` with a cyclical toggle button (e.g., an icon button that rotates between three distinct icons/colors representing Default, Debug, and Verbose states).
+- **Message Filtering & Display** (`web/src/routes/chats/[id]/+page.svelte`):
+  - **Visibility**:
+    - When `verbosityLevel` is `'default'`, only show messages with `level: 'default'` (or undefined).
+    - When `verbosityLevel` is `'debug'`, show messages with `level: 'default'` and `'debug'`.
+    - When `verbosityLevel` is `'verbose'`, show all messages.
+  - **Detail Level**:
+    - When `verbosityLevel` is `'default'` or `'debug'`, only display the message `content`. Hide the `command`, `stderr`, and `stdout` raw views.
+    - When `verbosityLevel` is `'verbose'`, reveal all message details including `command` and `stderr` (similar to the current `debugView = true` state).
+  - **Visual Distinction**: Verbose messages must look visually distinct from `default`/`debug` messages (e.g., using a distinct background color, border, or icon indicating it is a verbose background task).
+
+### 4. Discord Forwarder Updates
+- Modify `src/adapter-discord/forwarder.ts` to check the `level` property of incoming `CommandLogMessage`s.
+- Do not forward messages if their `level` is exactly `'verbose'`.
+- Messages with `level: 'default'`, `'debug'`, or undefined should still be forwarded as normal.
+
+## Privacy/Security/Accessibility Concerns
+- **Accessibility**: The new cyclical toggle button in the WebUI must have an appropriate `aria-label` that dynamically updates to indicate the current verbosity level state, ensuring screen reader users can interact with it effectively.
+- **Security**: No new security risks are introduced, as we are merely filtering the display of data the user already has access to.
+- **Privacy**: No new privacy concerns. Data is stored locally as before.

package/docs/11_message_verbosity/questions.md

@@ -0,0 +1,8 @@
+1. Should the new WebUI verbosity toggle control both which messages are visible (based on the message's `level` property) AND the level of detail shown for each message (e.g., hiding `stderr` and `command` on 'default', but showing them on 'debug'), or should it only control message visibility?
+- **Answer**: Yes. The toggle controls both which messages are visible and the level of detail shown for each message. 'verbose' setting shows stderr/command, and 'verbose' messages should also appear visually distinct from 'default' and 'debug' messages.
+2. For the `CommandLogMessage`'s `level` property, should it be explicitly defined for every message created by the daemon, or should it default to `'default'` if not specified? Also, when we label a message containing 'NO_REPLY_NECESSARY' as `'verbose'`, should the Discord forwarder only skip `'verbose'` messages, or should it also skip `'debug'` messages?
+- **Answer**: Default to 'default' if not specified. Discord forwarder should only skip 'verbose' messages for now.
+3. What should determine if a log message is classified as 'debug' instead of 'default' or 'verbose' initially? Do we have a specific type of message (e.g. error logs, retry delays, router logs) that should be mapped to the 'debug' level, or will everything remain 'default' except for messages containing 'NO_REPLY_NECESSARY' being mapped to 'verbose'?
+- **Answer**: We will handle that later. For now we will only introduce 'verbose' and 'default'.
+4. In the WebUI, when cycling the verbosity toggle, what should be the exact behavior of the three states: 1. Default (what is shown?), 2. Debug (what is shown?), 3. Verbose (what is shown?)? For instance, does Default show only 'default' level messages without command/stderr? Does Debug show both 'default' and 'debug' messages? Does Verbose show all messages and also reveal command/stderr details?
+- **Answer**: Default shows just message content for 'default' messages. Debug shows message content for 'default' and 'debug' messages. Verbose shows all messages, along with command and stderr details.

package/docs/11_message_verbosity/tickets.md

@@ -0,0 +1,33 @@
+# Message Verbosity Feature Tickets
+
+## 1. Update Data Model (Status: Complete)
+- **Task**: Update `src/shared/chats.ts` to add an optional `level` property (`'default' | 'debug' | 'verbose'`) to the `CommandLogMessage` interface.
+- **Verification**: Run `npm run check` and `npm run test` to ensure there are no TypeScript compilation errors resulting from this interface change.
+
+## 2. Update Daemon Message Generation (Status: Complete)
+- **Task**: Modify message generation logic in the daemon (e.g., `src/daemon/message.ts`) so that when a `CommandLogMessage` is generated, if its content includes the exact string `"NO_REPLY_NECESSARY"`, the `level` property is set to `'verbose'`.
+- **Verification**: Write/update tests in `src/daemon/` to verify this behavior, and run `npm run format:check && npm run lint && npm run check && npm run test`.
+
+## 3. Update Web UI State Management (Status: Complete)
+- **Task**: In `web/src/lib/app-state.svelte.ts` (or equivalent Web UI state file), replace the boolean `debugView` property with a string `verbosityLevel` initialized to `'default'`. The valid values should be `'default' | 'debug' | 'verbose'`.
+- **Verification**: Run `npm run check` and `npm run test` to verify state changes compile and pass tests.
+
+## 4. Update Web UI Controls (Status: Complete)
+- **Task**: In `web/src/routes/+layout.svelte`, replace the existing `Switch` component used for `debugView` with a cyclical toggle button. This button should rotate between the three states ('default', 'debug', 'verbose') using distinct icons/colors and must include a dynamic `aria-label` for accessibility.
+- **Verification**: Run `npm run check` and `npm run test`.
+
+## 5. Update Web UI Message Filtering and Display (Status: Complete)
+- **Task**: Update `web/src/routes/chats/[id]/+page.svelte` to implement filtering and detailed views based on `verbosityLevel`:
+  - `'default'` level: Show only `level: 'default'` (or undefined). Show only the message content.
+  - `'debug'` level: Show `level: 'default'` and `'debug'`. Show only the message content.
+  - `'verbose'` level: Show all messages. Reveal `command`, `stderr`, and `stdout` raw views.
+  - Ensure verbose messages look visually distinct (e.g., distinct background color, border, or icon).
+- **Verification**: Run `npm run check` and `npm run test`.
+
+## 6. Update Discord Forwarder (Status: Complete)
+- **Task**: Modify `src/adapter-discord/forwarder.ts` to check the `level` property of incoming `CommandLogMessage`s. Ensure that messages with `level: 'verbose'` are NOT forwarded to Discord.
+- **Verification**: Update Discord forwarder unit tests, then run `npm run check` and `npm run test`.
+
+## 7. Final Quality Check (Status: Complete)
+- **Task**: Ensure all code meets the project's formatting, linting, and testing standards.
+- **Verification**: Run `npm run format:check && npm run lint && npm run check && npm run test` and confirm everything passes cleanly.