clawmini 0.0.1

package/docs/04_agents/prd.md

@@ -0,0 +1,47 @@
+# Product Requirements Document: Multiple Agents Support
+
+## Vision
+To enhance the flexibility of `clawmini` by allowing users to define and interact with multiple distinct agents within a single workspace. This enables multi-agent workflows where different tasks can be delegated to differently-configured agents (e.g., different LLM models, varying temperature settings, or distinct operating directories).
+
+## Product/Market Background
+Currently, `clawmini` supports a single, globally defined `defaultAgent` in the workspace `.clawmini/settings.json`. While effective for simple use cases, power users need the ability to maintain concurrent chats with different configurations. By treating the workspace `defaultAgent` as a base configuration and allowing specific agents to extend and override it, users gain maximum flexibility with minimal boilerplate.
+
+## Use Cases
+- A user wants one chat to use a fast, lightweight model (e.g., for quick queries) and another to use a slower, "thinking" model (e.g., for complex reasoning), seamlessly switching between them or creating them via the Web UI.
+- A user wants an agent to execute its commands within a specific subdirectory of the project instead of the project root.
+- A user wants to define specialized agents with different prompt instructions injected via environment variables.
+
+## Requirements
+
+### 1. Agent Configuration
+- **Storage Location**: Agents must be stored in `.clawmini/agents/<agentId>/settings.json`.
+- **Schema**:
+  - `commands`: Inherits and overrides individual command strings (`new`, `append`, `getSessionId`, `getMessageContent`) from the global `defaultAgent.commands`.
+  - `env`: Key-value pairs that extend/override the global `defaultAgent.env`.
+  - `directory`: The absolute or relative path (from the workspace root) used as the `cwd` when executing the agent's commands. Defaults to `./<agentId>`.
+- **Resolution Logic**: When an agent's command is executed, its configuration must be deep-merged over the workspace `defaultAgent` configuration.
+
+### 2. CLI Interface
+Add a new command group: `clawmini agents` with the following subcommands:
+- `add <name> [--directory <dir>] [--env <key=value>...]`: Creates a new agent.
+- `update <name> [--directory <dir>] [--env <key=value>...]`: Updates an existing agent.
+- `delete <name>`: Deletes the agent and its directory under `.clawmini/agents/<name>`.
+- `list`: Lists all configured agents.
+
+Update the `messages` command:
+- `clawmini messages send [--agent <name>] "message"`: The `--agent` flag updates the chat's `.clawmini/chats/<chatId>/settings.json` so that subsequent messages in the chat use this agent. If omitted, it defaults to the existing agent for the chat, or the global `defaultAgent` if none is set. If the specified agent does not exist, the command must fail and output an error message (e.g., "Error: agent '<name>' does not exist").
+
+### 3. Web UI Integration
+- **Agent Creation**: A form to create new agents (providing name, and optional directory/env variables) must be added to the Web UI.
+- **Chat Creation**: When creating a new chat, the user must be presented with a dropdown to select the initial agent for that chat. The default option should be the workspace's default agent.
+- **Backend API**: New REST API endpoints (e.g., `/api/agents`) must be implemented to support listing, creating, updating, and deleting agents from the UI.
+
+### 4. Daemon Updates
+- The daemon message handler (`src/daemon/message.ts`) must read the targeted chat's configuration to identify its active agent.
+- It must then fetch the specified agent's configuration from `.clawmini/agents/<agentId>/settings.json` (falling back to just the global settings if the agent is "default").
+- It must apply the agent-specific `env` and `commands` overrides over the global `defaultAgent` configuration.
+- It must use the agent's `directory` as the `cwd` for the spawned child process.
+
+## Security & Constraints
+- **Path Traversal**: Ensure that agent creation validates the `<name>` to prevent directory traversal attacks (e.g., rejecting `../`).
+- **Data Integrity**: When merging the configurations, it must be a pure override, ensuring that sensitive command definitions in the global settings are not corrupted.

package/docs/04_agents/questions.md

@@ -0,0 +1,13 @@
+# Questions
+
+**Q1: For the `clawmini agents add <name>` command, should it take any other flags (like `--directory`, `--env`) or just the name, defaulting the directory to `./<name>` and leaving other settings empty for the user to edit manually?**
+A: Let's let it provide `--directory ./path/to/dir` and `--env FOO=bar`
+
+**Q2: The prompt mentions that agent config overrides the workspace `defaultAgent` settings. When resolving commands (like `new`, `append`), do we overwrite the whole object or just individual properties? For example, if `defaultAgent.commands.new` is set globally, and the agent only overrides `env`, does the agent inherit the `commands.new` from the global `defaultAgent`?**
+A: Yes, the agent should inherit commands from `defaultAgent.commands` and be able to override commands individually.
+
+**Q3: The UI needs to allow users to create new agents. Should the web UI creation form also support specifying the `directory` and `env` variables, matching the CLI?**
+A: Yes, but as with the flags they should be optional.
+
+**Q4: Should there be a CLI command to update an existing agent's settings, like `clawmini agents update <name> --env FOO=baz`, or is it expected that users manually edit the `.clawmini/agents/<name>/settings.json` file?**
+A: Sure, let's add an update command too.

package/docs/04_agents/tickets.md

@@ -0,0 +1,107 @@
+# Agents Feature Tickets
+
+## Ticket 1: Core Configuration and Workspace Utility for Agents
+**Description**: Define the `Agent` schema and add workspace utilities to manage agent configurations.
+**Tasks**:
+- Update `src/shared/config.ts` to include the `Agent` schema (with `commands`, `env`, and `directory` fields).
+- Add utility functions to `src/shared/workspace.ts` to manage agent configurations (e.g., `getAgent`, `listAgents`, `writeAgentSettings`, `deleteAgent`).
+- Ensure agent IDs are validated to prevent directory traversal attacks (e.g., rejecting paths with `../`).
+- Add comprehensive unit tests in `src/shared/workspace.test.ts`.
+**Verification**: 
+Run automated checks:
+```bash
+npm run format:check && npm run lint && npm run check && npm run test
+```
+**Status**: Complete
+
+## Ticket 2: Daemon Support for Agent Execution
+**Description**: Update the daemon message handler to respect agent configurations and directory paths.
+**Tasks**:
+- Update `src/daemon/message.ts` to read the chat's active agent and merge its configuration over the global `defaultAgent` settings.
+- Apply the merged `env` and `commands` to the agent execution.
+- Adjust the child process execution to use the agent's `directory` as its `cwd` (resolving it relative to the workspace root, defaulting to `./<agentId>`).
+- Add tests in `src/daemon/message.test.ts` to verify merging and directory assignment.
+**Verification**: 
+Run automated checks:
+```bash
+npm run format:check && npm run lint && npm run check && npm run test
+```
+**Status**: Complete
+
+## Ticket 3: Agent CLI Commands (Add, Update, Delete, List)
+**Description**: Implement the `clawmini agents` command group.
+**Tasks**:
+- Create `src/cli/commands/agents.ts` with subcommands: `add`, `update`, `delete`, and `list`.
+- Parse `--directory` and `--env` flags for `add` and `update` commands.
+- Register the `agents` command group in the main CLI entrypoint (`src/cli/index.ts`).
+**Verification**: 
+Run automated checks:
+```bash
+npm run format:check && npm run lint && npm run check && npm run test
+```
+**Status**: Complete
+
+## Ticket 4: CLI Support for Selecting an Agent per Chat
+**Description**: Update the CLI to allow switching the active agent for a specific chat.
+**Tasks**:
+- Update the `send` command in `src/cli/commands/messages.ts` to accept an `--agent <name>` flag.
+- Validate that the requested agent exists; fail with a clear error if it doesn't.
+- Update the chat's `.clawmini/chats/<chatId>/settings.json` to persist the selected agent for future messages.
+**Verification**: 
+Run automated checks:
+```bash
+npm run format:check && npm run lint && npm run check && npm run test
+```
+**Status**: Complete
+
+## Ticket 5: Web UI API Endpoints for Agents
+**Description**: Build REST API endpoints in the web project to manage agents.
+**Tasks**:
+- Create endpoints (e.g., `/api/agents` and `/api/agents/:id`) to handle fetching, creating, updating, and deleting agents from the Web UI.
+- Use the shared workspace utilities to interact with the file system securely.
+**Verification**: 
+Run automated checks:
+```bash
+npm run format:check && npm run lint && npm run check && npm run test
+```
+**Status**: Complete
+
+## Ticket 6: Web UI Integration for Agent Management & Chat Creation
+**Description**: Build the frontend components for users to interact with agents.
+**Tasks**:
+- Add a new dialog or dedicated page in the UI to view, create, and manage agents (supporting `directory` and `env` configurations).
+- Update the "New Chat" flow to include a dropdown for selecting the chat's initial agent.
+- Integrate the frontend with the API endpoints created in Ticket 5.
+**Verification**: 
+Run automated checks:
+```bash
+npm run format:check && npm run lint && npm run check && npm run test
+```
+**Status**: Complete
+
+## Ticket 7: Fix handleUserMessage Dependency on Global Default Agent
+**Description**: `handleUserMessage` incorrectly asserts that the global `defaultAgent.commands.new` must be defined, failing if a custom agent has its own `commands.new` but the global default agent doesn't.
+**Tasks**:
+- Modify `src/daemon/message.ts` to merge the active agent configuration before asserting that `commands.new` is defined.
+**Verification**:
+Run automated checks.
+**Status**: Complete
+
+## Ticket 8: DRY Violations in agents.ts Command Error Handling
+**Description**: The error handling (`catch` block with `console.error` and `process.exit`) and `isValidAgentId` checks are repeated across multiple subcommands in `src/cli/commands/agents.ts`.
+**Tasks**:
+- Extract a helper function for error handling in `agents.ts`.
+- Extract a helper function for asserting valid agent IDs that throws the appropriate error.
+**Verification**:
+Run automated checks.
+**Status**: Complete
+
+## Ticket 9: DRY Violations in web.ts API Endpoints
+**Description**: Reading/parsing JSON bodies and sending JSON error responses are repeated multiple times in `src/cli/commands/web.ts`.
+**Tasks**:
+- Create a `parseJsonBody(req)` helper function.
+- Create a `sendJsonResponse(res, statusCode, data)` or similar helper.
+- Update the API routes to use these helpers.
+**Verification**:
+Run automated checks.
+**Status**: Complete

package/docs/05_routers/development_log.md

@@ -0,0 +1,13 @@
+# Development Log
+
+## 2026-02-27 - Routers Feature
+- **Ticket 1 Completed:** Updated `src/shared/config.ts` to add the `routers` property (an optional array of strings) to both `SettingsSchema` and `ChatSettingsSchema`. Ran the required formatting, linting, and testing checks, which all passed successfully.
+- **Ticket 2 Completed:** Updated `CommandLogMessage` schema in `src/shared/chats.ts` to support the optional `source?: 'router'` property. Added a unit test case for it in `src/shared/chats.test.ts`. Ran all checks and they passed successfully.
+- **Ticket 3 Completed:** Implemented internal logic for the built-in routers `@clawmini/slash-new` and `@clawmini/slash-command` in `src/daemon/routers/slash-new.ts` and `src/daemon/routers/slash-command.ts`. Created robust unit tests, handling edge cases like path traversal attempts via regex definition and `pathIsInsideDir`. Successfully resolved TS, formatting, and linting errors. All automated checks and tests passing successfully.
+- **Ticket 4 Completed:** Created `src/daemon/routers.ts` to implement the `executeRouterPipeline` function. It sequentially iterates through defined routers, applies built-in handlers (`@clawmini/slash-new` and `@clawmini/slash-command`), and executes custom shell command routers while gracefully parsing standard output for JSON state merges. Wrote thorough tests in `src/daemon/routers.test.ts` to verify state mutations and silent failure handling for custom scripts. All automated checks and unit tests successfully passed.
+- **Ticket 5 Completed:** Integrated the router pipeline into `handleUserMessage` in `src/daemon/message.ts`. Passed the initial state through `executeRouterPipeline`, and applied resulting changes to the message, agent, session, and environment before enqueueing the task. Included injection of a router reply `CommandLogMessage` if one is returned by the pipeline. Updated `src/daemon/message.test.ts` with tests covering router integration. Verified logic and automated checks to ensure all pass.
+- **Bug Fixes:**
+  - Fixed an issue where the `/new` command wasn't actually saving the updated session ID to the chat's `settings.json`. The settings are now persisted immediately after the router pipeline executes.
+  - Implemented logic to skip sending the message to the model (queueing) if the processed message ends up being empty (e.g., when the user only types `/new`).
+  - Updated tests to handle `crypto.randomUUID()` mocking accurately.
+  - Ensured the original message content is appended to the chat timeline, even if the router pipeline modifies the message content sent to the agent.

package/docs/05_routers/notes.md

@@ -0,0 +1,40 @@
+# Notes: Routers Feature
+
+## Current Architecture
+- **Messages**: Users send messages through the CLI (`cli/client.ts` or `daemon/router.ts`), which get processed by `daemon/message.ts`.
+- **Agents**: Agents handle messages. Each agent has its own `new` and `append` command. Agents might be assigned by default or manually overridden.
+- **Sessions**: Chat instances maintain sessions, and an agent can have multiple sessions in a chat.
+- **Config Files**: Settings live in `.clawmini/settings.json` (global workspace) and `.clawmini/chats/ID/settings.json` (per-chat).
+
+## Router Concept
+A router acts as a middleware pipeline that intercepts the user's message before it's passed to the queue for the agent to process.
+- **Input**: `{ message: string, chatId?: string, agentId?: string, sessionId?: string, env?: object }` (or similar JSON representation of current state).
+- **Output**: Returns a JSON object specifying modifications.
+- **Built-in Routers**:
+  - `@clawmini/slash-new`: Detects `/new` prefix. Modifies `sessionId` to a new random UUID.
+  - `@clawmini/slash-command`: Detects slash prefixes (e.g. `/foo`) and replaces the command with file content from `.clawmini/commands/foo.md`.
+
+## Execution Flow
+1. User sends message `M1`.
+2. System loads defined `routers` array from local chat `settings.json`, falling back to global `settings.json`.
+3. For each router `R` in `routers`:
+   - System invokes `R` (likely spawning a subprocess, or handling natively if built-in).
+   - `R` receives `{ message: "...", ... }` via stdin (or argument).
+   - `R` outputs `{ message: "new text", agent: "coder", env: { ... } }` via stdout.
+   - System merges output back into state.
+4. Final state is passed to `handleUserMessage` in `src/daemon/message.ts`.
+
+## Possible Output Properties for a Router
+- `message` (string): Replace or modify the message text.
+- `agent` (string): Re-route the message to a different agent ID.
+- `session` (string): Specify a specific session ID to use (like `/new`).
+- `env` (Record<string, string>): Inject environment variables to pass to the agent process.
+- `cwd` (string): Override the execution directory for the agent.
+- `abort` (boolean): If true, stop processing the message entirely (don't invoke any agent, just log it or drop it).
+- `reply` (string): Immediately log a response to the user and (optionally) `abort`. Useful for simple query commands without invoking an LLM.
+
+## Implementation details to discover
+- How should built-in routers be differentiated from user-defined ones? User-defined could be shell scripts or executables, while `@clawmini/...` are handled natively in TypeScript.
+- Should user-defined routers receive input via `stdin` or environment variable? stdin seems best for JSON.
+- Is there a timeout for routers?
+- Should the `routers` array allow arguments? Like `["@clawmini/slash-command", "./my-router.sh"]`.

package/docs/05_routers/prd.md

@@ -0,0 +1,55 @@
+# Product Requirements Document: Routers
+
+## Vision
+The Routers feature aims to provide an extensible, middleware-like pipeline for processing user messages before they reach an agent. By allowing users to define a sequence of routers, they can dynamically alter message content, target specific agents or sessions, inject environment variables, and add automated replies. This gives users powerful, scriptable control over the routing logic of their chat sessions.
+
+## Product/Market Background
+Currently, Clawmini routes a user's message directly to an agent based on static chat settings. While effective, it lacks the flexibility to adapt to dynamic conditions—such as creating a new session from a slash command (e.g., `/new`), expanding macros or file contents (e.g., `/command`), or redirecting messages based on content analysis (e.g., sending simple questions to a fast model and complex ones to a reasoning model). Routers solve this by introducing an interception layer.
+
+## Use Cases
+1. **Starting Fresh (`/new`)**: A user types `/new` at the beginning of a message. A router intercepts this, generates a new session UUID, and redirects the message to this new session, effectively clearing the context window for the agent.
+2. **Text Expansion (`/command`)**: A user types `/foo` in their message. A router intercepts this, reads the contents of `.clawmini/commands/foo.md`, and replaces `/foo` with the file's content before passing it to the agent.
+3. **Dynamic Agent Routing**: A user writes a custom shell script router that analyzes the message length. If the message is short, it sets `agent: "fast-model"`. If long, it sets `agent: "reasoning-model"`.
+4. **Environment Injection**: A custom router looks up a specific context (e.g., the current git branch) and injects it as an environment variable (`env: { GIT_BRANCH: "main" }`) for the agent to use.
+5. **Immediate Replies**: A router detects a simple query (e.g., `/ping`) and immediately responds with `reply: "pong"` without ever invoking the heavier agent process.
+
+## Requirements
+
+### Configuration
+1. **Settings Definition**: Routers are defined as an array of strings under the `routers` key in `.clawmini/settings.json` (global) or `.clawmini/chats/ID/settings.json` (per-chat).
+2. **Opt-in Nature**: Built-in routers are not enabled by default. Users must explicitly add them to the `routers` array.
+3. **Execution Order**: Routers defined in the array execute sequentially, in the order they are listed.
+
+### Router Execution
+1. **Built-in Routers**: Strings prefixed with `@clawmini/` map to internal TypeScript functions.
+   - `@clawmini/slash-new`: Checks if the message starts with `/new`. If so, creates a new session ID (random UUID), sets the session property, and removes `/new` from the message.
+   - `@clawmini/slash-command`: Checks if the message contains a slash command (e.g., `/foo` or `/foo:bar`). It looks for a matching file in `.clawmini/commands/` (`.clawmini/commands/foo.md` or `.clawmini/commands/foo/bar.md`). If found, it replaces the slash command with the file's contents.
+2. **Custom Shell Routers**: Strings not prefixed with `@clawmini/` are treated as shell commands executed in the workspace root.
+3. **Input Mechanism**: The system serializes the current state (e.g., `{ "message": "...", "chatId": "...", "agentId": "...", "sessionId": "...", "env": {} }`) to JSON and passes it to the shell command via `stdin`.
+4. **Output Processing**: The system reads the stdout of the shell command, expecting a JSON object.
+
+### Router Capabilities (Output Properties)
+Routers can return a JSON object with any of the following properties to modify the state for the next router or the final agent execution:
+- `message` (string): Replaces the original user message text.
+- `agent` (string): Overrides the target agent ID for this message.
+- `session` (string): Specifies a specific session ID to use.
+- `env` (Record<string, string>): Injects or overrides environment variables for the agent process.
+- `reply` (string): A text response to be injected into the chat timeline immediately before the agent's response.
+
+### Chat Timeline Integration
+1. **Reply Injection**: If a router returns a `reply` string, a new `ChatMessage` must be appended to the chat log *before* the agent is invoked.
+2. **Reply Format**: This injected message must have `role: 'log'` and a new property `source: 'router'`.
+
+### Error Handling
+1. **Silent Failure**: If a custom shell router exits with a non-zero code, fails to output valid JSON, or times out, the system should log an error for debugging purposes (e.g., console log or internal debug log) but must *not* halt processing. It should continue passing the current (unmodified by the failing router) state to the next router or agent.
+
+## Privacy, Security & Accessibility Concerns
+- **Security (Shell Execution)**: Custom routers are executed as shell commands. This carries inherent risks if malicious commands are placed in the `settings.json`. However, this is consistent with Clawmini's existing trust model where users control their local `.clawmini` configuration and workspace scripts.
+- **Security (Path Traversal)**: The `@clawmini/slash-command` router must ensure it does not allow path traversal (e.g., `/../../../etc/passwd`) when looking up command files. It must rigidly confine lookups to the `.clawmini/commands/` directory.
+
+## Implementation Plan
+1. Update schema definitions in `src/shared/config.ts` to support the `routers` array.
+2. Update `ChatMessage` schema in `src/shared/chats.ts` to support the optional `source: 'router'` property for log messages.
+3. Create a new `src/daemon/routers.ts` file to handle the pipeline execution (parsing settings, running built-in vs shell routers, managing state transitions).
+4. Implement the `@clawmini/slash-new` and `@clawmini/slash-command` internal functions.
+5. Integrate the pipeline into `handleUserMessage` in `src/daemon/message.ts` before the queue execution.

package/docs/05_routers/questions.md

@@ -0,0 +1,21 @@
+# Questions for Routers Feature
+
+## Q1
+**Question**: How should user-defined routers be executed? For example, should the string in the `routers` array be treated as a shell command where the system passes the current state as a JSON string via `stdin` and expects the modified JSON object on `stdout`?
+**Answer**: Yes, as a shell command executed in the workspace root. We may have some built-in ones (all prefixed with "@clawmini") that just map to internal functions.
+
+## Q2
+**Question**: When a router returns its output JSON, what specific properties should we support merging back into the state? Beyond `message`, `agent`, `session`, and `env`, are there others you'd like to support? (e.g., `abort` to cancel the message entirely, `reply` to send a response back immediately without invoking an agent, or `cwd` to change the agent's working directory?)
+**Answer**: `reply` is interesting for the router to inject a message about what it did. `abort` could be useful but we'll hold off for now. We will stick to `message`, `agent`, `session`, `env`, and `reply`.
+
+## Q3
+**Question**: If a router returns a `reply` property, should that reply be inserted as an independent message in the chat timeline, or should it be appended to the current log message? If it is a separate message, what role should it have (`log`, `system`, etc.)?
+**Answer**: Injected into the timeline before the agent's response. It should be an independent message with `role: 'log'` and `source: 'router'`.
+
+## Q4
+**Question**: Regarding the built-in routers `@clawmini/slash-new` and `@clawmini/slash-command`, should these be enabled by default for all chats if the user does not specify a `routers` array in `settings.json`, or should users have to explicitly opt-in to them?
+**Answer**: Explicit opt in.
+
+## Q5
+**Question**: If a user-defined shell router returns a non-zero exit code or fails to output valid JSON, how should the system handle it? Should it silently fail and pass the original un-routed message to the agent, or should it log an error message to the user and halt the message processing entirely?
+**Answer**: Log an error (debug-only?), but continue on.

package/docs/05_routers/tickets.md

@@ -0,0 +1,109 @@
+# Routers Feature Tickets
+
+## Ticket 1: Update Configuration Schema
+**Description:** 
+Update the schema definitions in `src/shared/config.ts` to support a new `routers` property. This should be an optional array of strings, available in both global (`.clawmini/settings.json`) and per-chat settings.
+
+**Verification:**
+- Ensure type definitions are updated.
+- Verify that default settings parsing still succeeds.
+- Run the full suite of automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+**Status:** Complete
+
+---
+
+## Ticket 2: Update ChatMessage Schema
+**Description:** 
+Update the `ChatMessage` schema in `src/shared/chats.ts` to support an optional `source` property. This property should allow the literal value `'router'` for messages where `role` is `'log'`.
+
+**Verification:**
+- Update `src/shared/chats.test.ts` to test the new schema properties.
+- Run the full suite of automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+**Status:** Complete
+
+---
+
+## Ticket 3: Implement Built-in Routers
+**Description:** 
+Implement the internal logic for the built-in routers `@clawmini/slash-new` and `@clawmini/slash-command`.
+- `@clawmini/slash-new`: Detects if the message starts with `/new`, removes it from the message text, and generates a new random UUID for the session.
+- `@clawmini/slash-command`: Detects slash commands (e.g., `/foo` or `/foo:bar`) and replaces them with the contents of the matching file in `.clawmini/commands/`. **Crucial:** Implement strict path traversal protection to ensure only files within `.clawmini/commands/` can be read.
+
+**Verification:**
+- Create dedicated unit tests for these built-in router functions.
+- Run the full suite of automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+**Status:** Complete
+
+---
+
+## Ticket 4: Create Router Pipeline Execution Logic
+**Description:** 
+Create a new file `src/daemon/routers.ts` to handle the middleware pipeline execution.
+- Implement a function that takes an initial state (`message`, `chatId`, `agentId`, `sessionId`, `env`).
+- Fetch the `routers` array from the current settings.
+- Iterate through the routers sequentially:
+  - For built-in routers, call the respective internal functions.
+  - For custom routers, execute them as shell commands passing the current JSON state to `stdin` and parsing `stdout` as JSON.
+- Merge valid output properties (`message`, `agent`, `session`, `env`, `reply`) into the state for the next step.
+- Implement silent failure handling (non-zero exits, invalid JSON, timeouts should log errors but not halt the pipeline).
+
+**Verification:**
+- Create `src/daemon/routers.test.ts` to test both built-in router invocation and custom shell script execution (using mock scripts).
+- Run the full suite of automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+**Status:** Complete
+
+---
+
+## Ticket 5: Integrate Router Pipeline into Message Handling
+**Description:** 
+Integrate the router pipeline into `handleUserMessage` in `src/daemon/message.ts`.
+- Before adding the message to the queue for agent execution, pass the current state through the router pipeline.
+- Apply the resulting state changes (updated `message`, `agentId`, `sessionId`, `env`).
+- If the pipeline returns a `reply` string, inject a new `ChatMessage` with `role: 'log'` and `source: 'router'` into the chat timeline immediately before the agent is invoked.
+
+**Verification:**
+- Update `src/daemon/message.test.ts` to verify that routing modifications apply correctly (e.g., sessions are changed, text is replaced) and replies are properly injected into the timeline.
+- Run the full suite of automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+**Status:** Complete
+
+---
+
+## Ticket 6: Fix Custom Router Timeout Handle (High Priority)
+**Description:** 
+The custom router shell execution in `src/daemon/routers.ts` sets a 10-second timeout, but it doesn't clear this timeout (`clearTimeout`) if the execution finishes (either successfully or with an error) before the timeout expires. This causes the Node.js event loop to stay active longer than necessary, acting as a potential memory leak and blocking process exit.
+
+**Verification:**
+- Ensure `clearTimeout` is called on both successful exit and error paths.
+- Run the full suite of automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+**Status:** Complete
+
+---
+
+## Ticket 7: Refactor Web API Monolithic Handler (Medium Priority)
+**Description:** 
+The HTTP server implementation in `src/cli/commands/web.ts` handles all `/api/agents` and `/api/chats` routes within a single, monolithic 300+ line `if/else` block inside the `request` event callback. This violates clear organization and SRP. Also, utility functions like `parseJsonBody` and `sendJsonResponse` are instantiated inside the action scope instead of at the module level.
+Extract the route handling into discrete functions (e.g., `handleApiAgents`, `handleApiChats`) and move the utilities outside the `webCmd.action` closure.
+
+**Verification:**
+- Verify all web API routes still work via `npm run test` or similar.
+- Run the full suite of automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+**Status:** Complete
+
+---
+
+## Ticket 8: Improve Error UX in Agents Web UI (Low Priority)
+**Description:** 
+In `web/src/routes/agents/+page.svelte`, errors from the API are currently surfaced to the user using the browser's native `alert()` function. This is a poor user experience. Replace `alert()` with a modern approach, such as displaying an inline error message within the modal or form.
+
+**Verification:**
+- Simulate an error (e.g., trying to create a duplicate agent) and ensure the error message is displayed within the UI instead of an alert dialog.
+- Run the full suite of automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+**Status:** Complete

package/docs/06_agent_templates/development_log.md

@@ -0,0 +1,38 @@
+# Development Log: Agent Templates
+
+## Step 1: Update CLI flag parsing for `clawmini agent add`
+- [x] Read tickets.md
+- [x] Read `src/cli/commands/agents.ts` to see how `agent add` currently works.
+- [x] Add the `--template <name>` flag to `clawmini agent add`.
+- [x] Update `src/cli/e2e/agents.test.ts` to verify the new flag.
+- [x] Run validations and fix any formatting issues.
+
+## Step 2: Implement template resolution and copy logic
+- [x] Add `resolveTemplatePath` to `src/shared/workspace.ts` which checks local `.clawmini/templates/` first, and then falls back to `dist/templates/` (using relative path from dist/shared to templates folder).
+- [x] Add `copyTemplate` to `src/shared/workspace.ts` to recursively copy template files into the target agent directory if the directory is empty.
+- [x] Implement comprehensive unit tests in `src/shared/workspace.test.ts`.
+- [x] Run code quality checks (`npm run lint`, `check`, `test`). All pass.
+
+## Step 3: Process template configuration (`settings.json`)
+- [x] Wire up `copyTemplate` to the `clawmini agent add` command in `src/cli/commands/agents.ts`.
+- [x] Implement logic to read, validate, and process `settings.json` from the newly copied template directory.
+- [x] Ensure that the `directory` setting from the template is ignored with a warning and CLI flags correctly override template settings.
+- [x] Delete `settings.json` from the agent's working directory after processing.
+- [x] Create a dedicated E2E test in `src/cli/e2e/agents.test.ts` to verify the complete `--template` flow.
+- [x] Ensure all code quality checks, including Prettier, ESLint, and TypeScript, are passing successfully.
+
+## Bug Fix: Template not found
+### Hypotheses
+1. `__dirname` resolution is incorrect when running via CLI, pointing to the wrong path.
+2. The folder `templates/default` exists but `fsPromises.stat` fails.
+
+### Exploration
+By adding debug output to the `Template not found` error, it was clear that `../../templates` was resolving to the project root directory from a depth that was flatter than `src/shared`. Since the bundler output `dist/cli/index.mjs` was flattening the chunk structure, the `__dirname` relative to the bundle entrypoint was pointing directly to `dist/cli` rather than `dist/shared`.
+
+### Resolution
+The bug was resolved by updating `resolveTemplatePath` to iterate over several common potential depth paths:
+- `__dirname/templates`
+- `__dirname/../templates`
+- `__dirname/../../templates`
+
+This successfully fixes the bug in the CLI.

package/docs/06_agent_templates/notes.md

@@ -0,0 +1,25 @@
+# Agent Templates Research Notes
+
+## Current Implementation
+
+- `clawmini agent add <id>` is handled in `src/cli/commands/agents.ts`.
+  - It currently accepts `--directory` and `--env`.
+  - It uses `getAgent` to check existence.
+  - It uses `writeAgentSettings(id, agentData)` to persist the configuration, which internally calls `ensureAgentWorkDir(agentId, data.directory, startDir)`.
+- `ensureAgentWorkDir` (in `src/shared/workspace.ts`) resolves the directory (either `<workspace-root>/<agent-id>` or the custom directory) and creates it using `fsPromises.mkdir` if it doesn't exist.
+- Agent configurations (`AgentSettings` / `AgentSchema`) are stored at `.clawmini/agents/<id>/settings.json`.
+- There is a root-level `templates/` folder in the project which might be intended for built-in templates.
+
+## Required Changes
+
+- Add `--template <name>` flag to `clawmini agent add`.
+- Define template resolution order:
+  1. `.clawmini/templates/<name>`
+  2. Built-in template (e.g., `templates/<name>`)
+- The copy logic must:
+  - Copy the contents of the resolved template folder into the agent's working directory.
+  - This should likely occur only when creating the work dir (or if the directory is empty).
+  - Look for `settings.json` in the newly copied workdir.
+  - If it exists and is valid `AgentSettings` (validates with `AgentSchema`), use it as the base configuration for the agent.
+  - Remove `settings.json` from the working directory after using it.
+- Flags passed explicitly to `clawmini agent add` (like `--env` or `--directory`) should probably override values from the template's `settings.json`.

package/docs/06_agent_templates/prd.md

@@ -0,0 +1,34 @@
+# Agent Templates
+
+## Vision
+To provide a smooth and predictable onboarding experience for new agents by enabling pre-configured templates. These templates give users a solid starting point for their agents, complete with files and configurations, saving time and reducing errors when setting up boilerplate environments.
+
+## Product / Market Background
+Currently, users add agents with `clawmini agent add <id>`, which creates a raw configuration and optionally an empty working directory. As the system scales and use-cases expand, users often need specialized agents (e.g., specific prompting frameworks, pre-installed tool configurations, or project structures). Allowing folder templates bridges this gap by letting users seed an agent's working directory with necessary files and configurations.
+
+## Use Cases
+1. **Quickstart Default:** A user creates an agent with `clawmini agent add foo --template default`. The `default` template provides an initial structure (e.g., standard files or instructions) ready for immediate use.
+2. **Custom Workflows:** A user defines a project-specific template in `.clawmini/templates/my-custom-agent` and uses `clawmini agent add bar --template my-custom-agent` to initialize an agent with standard tools tailored for their current workspace.
+3. **Configuration Inheritance:** A template provides default environment variables or descriptions in a `settings.json` file. When the agent is created, these settings are merged, saving the user from manually typing out complex environment parameters.
+
+## Requirements
+1. **CLI Flag (`--template <name>`):** The `clawmini agent add <id>` command must accept an optional `--template <name>` flag.
+2. **Template Resolution:**
+   - First, search in `.clawmini/templates/<name>`.
+   - If not found locally, search in built-in templates. Built-in templates will be located at a package-level `templates/` directory (accessible via `import.meta.url` or standard path resolution relative to `dist/cli`).
+3. **Directory Constraints:**
+   - If the agent's resolved working directory already exists and is **not empty**, the command MUST fail, preventing accidental overwrites.
+4. **Copy Process:**
+   - The entire contents of the resolved template folder must be copied to the new agent's working directory recursively.
+5. **Configuration Handling (`settings.json`):**
+   - After copying, if a `settings.json` file exists in the copied directory, it must be read and validated against `AgentSchema` (ignoring strict workspace checks during read).
+   - If valid, this configuration becomes the default state of the new agent.
+   - **Important:** If the template's `settings.json` includes a `directory` field, it MUST be explicitly ignored, and a warning should be printed to the user indicating that template directory configurations are ignored. If no `--directory` flag is specified, the agent's working directory will be created in the default folder (`./<agent-id>`).
+   - The CLI flags (`--env`, `--directory`) provided by the user MUST override matching values from the template's `settings.json`.
+   - The `settings.json` file MUST be removed from the agent's working directory after processing.
+6. **Built-in Templates Accessibility:**
+   - The build process must be updated or source code logic must guarantee that the `templates/` folder is accessible by the CLI binary after the project is built. Since `tsdown` is used, resolving `templates/` relative to `__dirname` or using a copy-plugin might be necessary. Given Node's `import.meta.url`, resolving paths to `../../../templates` from the built code is a common approach.
+
+## Open / Technical Concerns
+- Built-in template location: Ensuring `dist/` execution properly resolves the `templates/` folder. A reliable method like `path.join(path.dirname(fileURLToPath(import.meta.url)), '../../templates')` should be tested during implementation.
+- Race conditions: Validating the target directory is empty before starting the asynchronous copy process.

package/docs/06_agent_templates/questions.md

@@ -0,0 +1,11 @@
+# Agent Templates Questions and Answers
+
+**Q1:** Where are the "built-in templates" located? Is it the `templates/` folder at the root of the project?
+**A1:** Wherever makes the most sense. The project is built to `./dist` with `npm run build`, so it must maintain access to the templates.
+*(Note: I will propose copying the `templates/` folder to `dist/templates` during the build process, or resolving from `dist/../templates` in the source code.)*
+
+**Q2:** If the template's `settings.json` includes a `directory` field, should it be ignored, used as the default unless overridden by an explicit `--directory` flag, or something else?
+**A2:** The `directory` field should always be ignored, likely with a warning.
+
+**Q3:** Should the agent creation (and template copying) fail if the destination working directory already exists and is not empty?
+**A3:** Yes, it should fail if the directory is not empty.

package/docs/06_agent_templates/tickets.md

@@ -0,0 +1,49 @@
+# Agent Templates Tickets
+
+## Step 1: Update CLI flag parsing for `clawmini agent add`
+- **Description:** Add the `--template <name>` flag to the `clawmini agent add` command. Ensure it correctly parses alongside existing flags like `--directory` and `--env`.
+- **Verification:** 
+  - Update or add tests in `src/cli/e2e/agents.test.ts` to verify the `--template` flag is parsed and passed to the handler correctly.
+  - Run `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Completed
+
+## Step 2: Implement template resolution and copy logic
+- **Description:** 
+  - Implement a function to resolve the template path, checking `.clawmini/templates/<name>` first, then falling back to a built-in `templates/<name>` folder relative to the built CLI executable.
+  - Add logic to check if the target agent working directory exists and is **not empty**. If it is not empty, the command must fail to prevent overwriting.
+  - Recursively copy the contents of the resolved template folder into the new agent's working directory.
+- **Verification:** 
+  - Add unit tests verifying correct resolution order (local workspace vs. built-in), successful file copying to an empty directory, and failure when the target directory is not empty.
+  - Verify that built-in templates are correctly resolved from the compiled `dist/` directory.
+  - Run `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Completed
+
+## Step 3: Process template configuration (`settings.json`)
+- **Description:** 
+  - After copying the template files, check for a `settings.json` in the newly created agent working directory.
+  - If present, read and validate it against `AgentSchema`.
+  - If the template's `settings.json` includes a `directory` field, ignore it, print a warning to the user, and use the default `./<agent-id>` or the one provided by `--directory`.
+  - Merge the configuration: CLI flags (`--env`, `--directory`) MUST override values from the template's `settings.json`.
+  - Remove the `settings.json` file from the agent's working directory after processing.
+  - Pass the resulting merged configuration to `writeAgentSettings`.
+- **Verification:** 
+  - Add unit tests for the configuration merging logic, ensuring CLI flags override template settings and that the `directory` field in the template is ignored with a warning.
+  - Verify `settings.json` is deleted from the working directory after creation.
+  - Add/update an end-to-end test in `src/cli/e2e/agents.test.ts` for `clawmini agent add <id> --template <name>` simulating the entire flow.
+  - Run `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Completed
+
+## Issue 1 (High): Extract template settings logic
+- **Description:** Move the complex template settings merging and validation logic out of the CLI command handler (`src/cli/commands/agents.ts`) and into a dedicated function in `src/shared/workspace.ts` (e.g., `applyTemplateSettings`). This improves separation of concerns.
+- **Verification:** Ensure tests pass. Run `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Completed
+
+## Issue 2 (Medium): DRY up directory checking in `resolveTemplatePath`
+- **Description:** In `src/shared/workspace.ts`, the `try/catch` block for checking if a directory exists using `fsPromises.stat(dir).isDirectory()` is duplicated. Extract this into a helper function `async function isDirectory(path: string): Promise<boolean>`.
+- **Verification:** Ensure tests pass. Run `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Completed
+
+## Issue 3 (Low): Use asynchronous `fs` methods consistently
+- **Description:** Replace synchronous `fs.existsSync` calls with asynchronous alternatives or `try/catch` blocks using `fsPromises` in `src/cli/commands/agents.ts` and `src/shared/workspace.ts` for consistency.
+- **Verification:** Ensure tests pass. Run `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Completed