clawmini 0.0.1

package/docs/02_sessions/development_log.md

@@ -0,0 +1,79 @@
+# Development Log - Sessions Feature
+
+## Progress
+
+- Picked up Ticket 1: Update Configuration Schema & Types
+- Picked up Ticket 2: CLI Flag for Sessions
+- Picked up Ticket 3: State Storage Utilities
+
+## Completed Ticket 3
+
+- Implemented `getChatSettingsPath` and `getAgentSessionSettingsPath` path resolution functions.
+- Implemented asynchronous storage utilities `readChatSettings`, `writeChatSettings`, `readAgentSessionSettings`, and `writeAgentSessionSettings` using `node:fs/promises` in `src/shared/workspace.ts`.
+- Created robust test suite `src/shared/workspace.test.ts` to ensure utility correctness, path resolution, and error handling for nonexistent/invalid files.
+- `npm run check` and `npm run test` both completed successfully.
+
+## Completed Ticket 2
+
+- Added `-s, --session <id>` flag to the CLI `messages send` command in `src/cli/commands/messages.ts`.
+- Updated tRPC `send-message` schema in `src/daemon/router.ts` to accept an optional `sessionId` string parameter.
+- Added an E2E test in `src/cli/e2e.test.ts` verifying flag parsing and successful payload transmission to the daemon.
+- All checks (`npm run lint`, `npm run check`, `npm run test`) passed.
+
+## Completed Ticket 1
+
+- Updated `SettingsSchema` in `src/shared/config.ts` to include `append`, `getSessionId`, and `getMessageContent` commands.
+- Verified that `z.record(z.string(), z.string())` is correctly used.
+- Verified `npm run check` and `npm run test` passed.
+
+## Completed Ticket 4
+
+- Updated `handleUserMessage` in `src/daemon/message.ts` to accept an optional `sessionId`.
+- Implemented session resolution logic matching `chatSettings.sessions[agentId]` if `sessionId` is omitted.
+- Implemented environment variable injection and command fallback (`commands.append` vs `commands.new`) depending on whether agent session settings exist.
+- Passed `sessionId` via TRPC mutation in `src/daemon/router.ts`.
+- Updated unit tests in `src/daemon/message.test.ts` heavily mocking `readChatSettings`, `readAgentSessionSettings`, and `spawn` ensuring test isolation by separating cache directories.
+- All checks (`npm run check`, `npm run test`) passed.
+
+## Completed Ticket 5
+
+- Modified `runCommand` signature in `src/daemon/message.ts` to return an object `{ stdout, stderr, exitCode }` instead of resolving `void` and internally calling `appendMessage`. Added support for an optional `stdin` argument.
+- Implemented extraction logic inside `handleUserMessage`: after the main command finishes, we spawn `getSessionId` and `getMessageContent` by invoking `runCommand` with `stdin: mainResult.stdout`.
+- Updates the Chat Settings and Agent Session Settings correctly using `writeChatSettings` and `writeAgentSessionSettings` respectively, upon successful execution of `getSessionId`.
+- Propagates any error messages from the extraction commands to `extractionError` which gets gracefully concatenated to `stderr` of the main log output.
+- Refactored `runCommand` in `src/daemon/router.ts` and `src/daemon/message.test.ts` to adhere to the new signature and support piping to `stdin`.
+- Verified changes with extensive unit tests covering the multi-command spawning behavior and state file persistence logic in `src/daemon/message.test.ts`.
+- `npm run check`, `npm run test`, and `npm run lint` all passed successfully.
+
+## Completed Ticket 6
+
+- Added `extractedMessage?: string` to the `CommandLogMessage` interface in `src/shared/chats.ts`.
+- Removed TODO comments in `src/daemon/message.ts` regarding `extractedMessage`.
+- Wrote full multi-message session E2E test in `src/cli/e2e.test.ts` verifying that `commands.new`, `commands.append`, `commands.getSessionId`, and `commands.getMessageContent` execute as expected and are safely captured.
+- Tested failure scenarios to ensure extraction errors gracefully fallback into `stderr` and preserve the `chat.jsonl` atomic ordering without breaking the log syntax.
+- `npm run check`, `npm run build`, `npm run lint`, and `npm run test` all pass. This concludes the Sessions Feature implementation!
+
+# Fix Session ID bug
+
+## Hypotheses
+
+1. The bug refers to where `writeAgentSessionSettings` is called with an empty `env: {}`. We probably need to set `SESSION_ID: extractedSessionId` in the `env` object.
+
+## Implementation
+
+The issue indicates that we need to set the extracted session ID in the environment of the initial agent session settings.
+
+In `src/daemon/message.ts`, the daemon creates initial agent session settings by writing an empty `env: {}` object when `getSessionId` successfully extracts the session ID from the `new` command's output.
+
+We update this logic to save the extracted session ID as `SESSION_ID` in the `env` object:
+
+```typescript
+await writeAgentSessionSettings(
+  agentId,
+  extractedSessionId,
+  { env: { SESSION_ID: extractedSessionId } },
+  cwd
+);
+```
+
+This ensures that on subsequent messages for the same session (using the `append` command), the daemon injects ``into the child process's environment variables. We also updated the corresponding unit test in`message.test.ts` to verify this new behavior.

package/docs/02_sessions/notes.md

@@ -0,0 +1,40 @@
+# Notes for Sessions Feature
+
+## Current Implementation
+- **CLI Command**: `clawmini messages send "hi" [-c <chatId>]` sends a `send-message` mutation to the daemon.
+- **Daemon Handling**: `router.ts` reads the global `.clawmini/settings.json` to get agent config (`defaultAgent.commands.new`). It passes this to `handleUserMessage` in `message.ts`.
+- **Message Execution**: `handleUserMessage` sets the `CLAW_CLI_MESSAGE` environment variable and runs the command.
+- **Output Logging**: `router.ts` spawns the command, captures `stdout` and `stderr`, and saves a `CommandLogMessage` via `appendMessage`.
+- **Storage**: Chats are stored in `.clawmini/chats/<chatId>/chat.jsonl`.
+
+## Proposed Architecture
+- **Agent Configuration Update**: Agents need new commands in `.clawmini/settings.json`:
+  - `new`: Starts a new session.
+  - `append`: Appends to a session.
+  - `getSessionId`: A shell command that takes the stdout of `new` via stdin and prints the session ID.
+  - `getMessageContent`: A shell command that takes the stdout of `new` or `append` via stdin and prints the message content.
+- **Chat State**: Each chat gets a `settings.json` at `.clawmini/chats/<chatId>/settings.json`:
+  ```json
+  {
+    "defaultAgent": "default",
+    "sessions": {
+      "default": "<sessionId>" // The ID from --session or 'default'
+    }
+  }
+  ```
+- **Agent Session State**: Each agent session gets a `settings.json` at `.clawmini/agents/<agentId>/sessions/<sessionId>/settings.json`:
+  ```json
+  {
+    "env": {
+      "SESSION_ID": "<agent's internal session id>"
+    }
+  }
+  ```
+- **Execution Flow (`messages send`)**:
+  1. Determine `sessionId`: use `--session` if provided. Otherwise, read `.clawmini/chats/<chatId>/settings.json` to get `defaultAgent` and its associated `<sessionId>`. If still not found, use `'default'`.
+  2. Check if `.clawmini/agents/<agentId>/sessions/<sessionId>/settings.json` exists.
+  3. If it exists, execute `append` command (passing the internal `SESSION_ID` in `env` from the session's `settings.json`).
+  4. If session doesn't exist, execute `new`.
+  5. After `new`, run `getSessionId` passing `new`'s stdout via stdin. Save the extracted internal session ID to `.clawmini/agents/<agentId>/sessions/<sessionId>/settings.json`. Update chat's `settings.json` with the new `<sessionId>`.
+  6. After either `new` or `append`, run `getMessageContent` passing the stdout via stdin. Extract the message text.
+  7. Write output logs (`CommandLogMessage`) to `.clawmini/chats/<chatId>/chat.jsonl`, including both the raw stdout and the extracted message text (if any).

package/docs/02_sessions/prd.md

@@ -0,0 +1,75 @@
+# Product Requirements Document: Chat Sessions
+
+## 1. Vision & Goals
+
+Currently, sending a message to the agent always spawns a fresh process with no memory of the prior context unless the agent itself happens to maintain it invisibly. The "Sessions" feature introduces the capability for `clawmini` to persistently identify and track agent sessions, allowing users to send subsequent messages that extend an existing conversation.
+
+The primary goals of this feature are:
+- Introduce persistent session states for agent conversations.
+- Differentiate between starting a new session and appending to an existing one.
+- Enable `clawmini` to extract internal agent session IDs and message content from arbitrary outputs via shell commands.
+- Track mapping between `clawmini` chats and agent sessions locally.
+
+## 2. Product / Market Background
+
+AI agents (like LLMs or specialized CLI agents) often require state to maintain context across multiple turns of a conversation. By giving `clawmini` the ability to store a session identifier locally and pass it back to the agent in subsequent commands, we enable stateful conversational loops. This maps well to how users expect standard chat applications or LLM tools to operate.
+
+## 3. Use Cases
+
+1. **Continuing a Conversation**: A user runs `clawmini messages send "Hello"` and a new agent session is started. They then run `clawmini messages send "What did I just say?"` and the CLI sends the message to the same session, allowing the agent to reply accurately based on the history.
+2. **Multiple Agent States in One Chat**: A user can use `--session foo` to interact with session `foo`, then switch to `--session bar` within the same chat workspace.
+3. **Structured Agent Responses**: Agents returning complex structures (JSON, YAML, custom text) can have their exact message and session IDs extracted via standard shell pipelines (e.g., using `jq` or `grep`), without enforcing a rigid output format on the agent.
+
+## 4. Requirements
+
+### 4.1 CLI Interface Updates
+- Update the `messages send <message>` command to support an optional `--session <id>` flag.
+- **Session Resolution Logic:**
+  - If `--session` is provided, use that session ID.
+  - If not provided, read the chat's `settings.json` (at `.clawmini/chats/<chatId>/settings.json`) to find the active session for the `defaultAgent`.
+  - If no session is found in the chat settings, default to the ID `'default'`.
+
+### 4.2 Agent Configuration Updates
+Agents defined in `.clawmini/settings.json` will require updated fields:
+- `commands.new`: The command used to initialize a new session.
+- `commands.append`: The command used to append a message to an existing session.
+- `commands.getSessionId`: A shell command that takes the stdout of `new` via `stdin` and outputs the internal session ID.
+- `commands.getMessageContent`: A shell command that takes the stdout of `new` or `append` via `stdin` and outputs the text content to show to the user.
+
+### 4.3 Data Storage & State Management
+- **Chat State**: Maintained at `.clawmini/chats/<chatId>/settings.json`.
+  ```json
+  {
+    "defaultAgent": "default",
+    "sessions": {
+      "default": "<sessionId>"
+    }
+  }
+  ```
+- **Agent Session State**: Maintained at `.clawmini/agents/<agentId>/sessions/<sessionId>/settings.json`.
+  ```json
+  {
+    "env": {
+      "SESSION_ID": "<agent's internal session id>"
+    }
+  }
+  ```
+
+### 4.4 Execution Flow (Daemon)
+When a `send-message` request is processed by the daemon:
+1. Identify the target `chatId` and `sessionId` (based on the CLI request and chat settings).
+2. Determine if the agent session exists by checking for `.clawmini/agents/<defaultAgent>/sessions/<sessionId>/settings.json`.
+3. **If the session exists:**
+   - Construct the environment, injecting the agent's internal `SESSION_ID` from the session settings.
+   - Execute the `commands.append` command.
+4. **If the session does not exist:**
+   - Execute the `commands.new` command.
+5. **Post-Execution Extraction:**
+   - If a new session was started and `commands.getSessionId` is defined, spawn the `getSessionId` command, writing the `new` command's stdout to its `stdin`. Read the resulting output as the internal session ID. Save this to the agent session settings file, and update the chat settings file.
+   - If `commands.getMessageContent` is defined, spawn it, writing the `new`/`append` command's stdout to its `stdin`. Read the resulting output as the extracted message text.
+   - Persist the execution details in the chat log (`chat.jsonl`), including both the raw stdout and the extracted message text (if applicable).
+
+## 5. Non-Functional Concerns
+- **Dependencies**: No external JSON parsers (like `jsonpath-plus`) are required. The host system's shell environment (and tools like `jq` or `awk`) will be used via the agent's configured extraction commands.
+- **Error Handling**: Gracefully handle failures in the `getSessionId` or `getMessageContent` commands (e.g., command not found, pipeline failures). Log these errors to `chat.jsonl` as `stderr` so the user is informed of the extraction failure. Provide fallbacks where appropriate (e.g., using raw stdout if text extraction fails).
+- **Security**: The `SESSION_ID` read from `settings.json` and injected into the environment must not allow command injection; relying on `child_process.spawn` with `env` blocks is safe, provided we use it correctly without arbitrary string interpolation in the shell. Running arbitrary shell commands via `getSessionId` and `getMessageContent` follows the same security model as `new` and `append`.

package/docs/02_sessions/questions.md

@@ -0,0 +1,7 @@
+# Questions for Sessions Feature
+
+**Q1: What syntax or library should we use for the JSON queries in `getSessionId` and `getMessageContent`? Should we use a full JSONPath library (e.g., `jsonpath-plus`) or stick to simple dot-notation parsing to keep dependencies minimal?**
+A1: Actually, let's use shell commands for `getSessionId` and `getMessageContent` that execute with the output of `new`/`append` sent into them as stdin. This removes the dependency on jsonpath and any assumptions that the output is JSON (callers can use jq to parse).
+
+**Q2: How should the system generate or determine the `<sessionId>` assigned to a chat in `.clawmini/chats/<chatId>/settings.json`? Should it generate a UUID (e.g. `uuidv4`) for new sessions, or something else?**
+A2: For now, let's have a --session flag that can specify the session ID. If unspecified, first check the settings; then use 'default' if none

package/docs/02_sessions/tickets.md

@@ -0,0 +1,68 @@
+# Tickets: Sessions Feature
+
+## Ticket 1: Update Configuration Schema & Types
+**Description**: Update the agent configuration types and Zod schemas in `src/shared/config.ts` to support the new commands structure (`new`, `append`, `getSessionId`, `getMessageContent`). Ensure usage of Zod 4 best practices (e.g., `z.record(z.string(), z.string())` for records).
+**Verification**: 
+- `npm run check`
+- `npm run test`
+**Status**: complete
+
+## Ticket 2: CLI Flag for Sessions
+**Description**: Update the CLI `messages send` command in `src/cli/commands/messages.ts` to accept an optional `-s, --session <id>` flag. Pass the session ID to the TRPC `send-message` payload.
+**Verification**: 
+- Add E2E tests verifying flag parsing and payload structure.
+- `npm run test`
+- `npm run check`
+- `npm run lint`
+**Status**: complete
+
+## Ticket 3: State Storage Utilities
+**Description**: Implement read/write utilities in `src/shared/workspace.ts` to manage Chat State (`.clawmini/chats/<chatId>/settings.json`) and Agent Session State (`.clawmini/agents/<agentId>/sessions/<sessionId>/settings.json`). 
+**Verification**: 
+- Write unit tests for the new storage utility functions.
+- `npm run test`
+- `npm run check`
+**Status**: complete
+
+## Ticket 4: Daemon Session Resolution & Execution
+**Description**: Update `handleUserMessage` in `src/daemon/message.ts` to resolve the `sessionId` (CLI `--session` -> chat settings -> `'default'`). Check if the agent session state file exists. If it exists, execute `commands.append` (injecting `SESSION_ID` into the `env`). If not, execute `commands.new`.
+**Verification**: 
+- Add unit tests mocking `node:child_process.spawn` to verify correct commands and environment variables are used.
+- `npm run test`
+- `npm run check`
+**Status**: complete
+
+## Ticket 5: Command Extraction & State Updates
+**Description**: Implement the extraction logic in the daemon after the primary command finishes. Spawn `getSessionId` (if it was a new session) and `getMessageContent` (if defined), piping the main command's stdout to their stdin. Parse the outputs and update the Chat and Agent Session settings files.
+**Verification**: 
+- Add unit tests verifying stdin piping and correct state file updates upon success.
+- `npm run test`
+- `npm run check`
+**Status**: complete
+
+## Ticket 6: Logging & Final Integration
+**Description**: Update the `CommandLogMessage` structure in the chat log (`chat.jsonl`) to include both raw stdout and extracted message text. Gracefully handle extraction command failures by logging them as `stderr` in `chat.jsonl`. Complete the feature by writing an E2E test covering the full multi-message session workflow.
+**Verification**: 
+- Full suite of E2E tests in an isolated sandbox testing the daemon and CLI workflows.
+- `npm run build`
+- `npm run check`
+- `npm run lint`
+- `npm run test`
+**Status**: complete
+
+## Ticket 7: DRY Violation in `src/shared/workspace.ts`
+**Priority**: High
+**Description**: The read/write functions for `ChatSettings` and `AgentSessionSettings` contain duplicate file reading, JSON parsing, and directory creation logic. They also unnecessarily use synchronous `fs.existsSync` inside an async function.
+**Verification**:
+- Extract a generic `readJsonFile` and `writeJsonFile` utility.
+- Use `fsPromises.mkdir` natively (with `recursive: true` and swallowing `EEXIST` implicitly) instead of sync directory checking.
+- `npm run format`, `npm run lint`, `npm run check`, `npm run test`.
+**Status**: complete
+
+## Ticket 8: DRY Violation in `src/daemon/message.ts`
+**Priority**: Medium
+**Description**: `extractSessionId` and `extractMessageContent` contain nearly identical execution and error handling logic for running extraction commands.
+**Verification**:
+- Extract a generic `runExtractionCommand` utility.
+- `npm run format`, `npm run lint`, `npm run check`, `npm run test`.
+**Status**: complete

package/docs/03_web_interface/development_log.md

@@ -0,0 +1,60 @@
+# Development Log: Web Interface
+
+## Feb 24, 2026 - Initial SvelteKit Setup (Step 1)
+
+- Initialized a new SvelteKit application using the minimal Svelte 5 and Vite 7 template in the `web/` directory.
+- Installed `tailwindcss` (v4), `@tailwindcss/vite`, `lucide-svelte`, `clsx`, and `tailwind-merge` to fulfill the `shadcn-svelte` prerequisites.
+- Configured SvelteKit with `@sveltejs/adapter-static` using the `fallback: 'index.html'` option for single-page application (SPA) behavior.
+- Updated root `eslint.config.js` to ignore the `.svelte-kit` and `build` folders generated by the Vite build step, preventing linting errors on generated server artifacts.
+- Added a `build:web` command to the root `package.json` that hooks into the main `npm run build` command, compiling the Svelte SPA directly into the workspace `dist/web` directory where the Node.js server will serve it from.
+- All workspace checks passing successfully.
+
+## Feb 24, 2026 - Web Server Implementation (Step 2)
+
+- Implemented `clawmini web` command in `src/cli/commands/web.ts` using `node:http`.
+- The server binds to `127.0.0.1` and serves static files from `dist/web`, with a fallback to `dist/web/index.html` for SPA routing.
+- Added a basic mime type map to serve correct content types for static assets.
+- Addressed an issue where `tsdown`'s `clean: true` was deleting the `dist/web` directory generated by `build:web`. Updated root `package.json` build script to `tsdown && npm run build:web` to ensure static files are preserved.
+- Added E2E tests in `src/cli/e2e.test.ts` to verify the web server starts correctly, serves the `index.html` file, and falls back gracefully for unknown routes.
+- All workspace checks pass successfully.
+
+## Feb 24, 2026 - Implemented REST API Endpoints (Step 3)
+
+- Added routing logic to the Node.js server in `src/cli/commands/web.ts` to handle `/api/*` endpoints.
+- Implemented `GET /api/chats` to return a list of chats utilizing the shared `listChats` function.
+- Implemented `GET /api/chats/:id` to return the chat history utilizing the shared `getMessages` function.
+- Implemented `POST /api/chats/:id/messages` to receive JSON body `{"message": "..."}` and forward it to the daemon via the UNIX socket using `getDaemonClient().sendMessage.mutate`.
+- Added permissive CORS headers (`Access-Control-Allow-Origin`, etc.) to the API routes to allow frontend dev servers to proxy easily.
+- Added comprehensive integration tests in `src/cli/e2e.test.ts` to verify the endpoints correctly read from the file system, list chats, parse the JSON body, and interact with the daemon client.
+- Fixed minor TypeScript errors related to `RegExpMatchArray` bounds and potentially undefined arrays.
+- All verification steps and tests pass successfully.
+
+## Feb 24, 2026 - Server-Sent Events (SSE) Endpoint (Step 4)
+
+- Implemented `GET /api/chats/:id/stream` in `src/cli/commands/web.ts` to push real-time updates to connected clients.
+- Used `node:fs` module's `fs.watch` and `fs.createReadStream` to listen for file changes on the specific chat's `chat.jsonl` log file, handling chunking logic carefully to ensure individual messages are read and streamed accurately as Server-Sent Events.
+- Correctly ensured the stream correctly gracefully initializes a blank chat file using `createChat` if a stream request is made for an empty but valid route, preventing 404 read stream errors.
+- Created robust end-to-end integration tests within `e2e.test.ts` mapping the Web Server's child process flow, executing an programmatic file append, and reading the `EventSource` stream through native Fetch `body.getReader` methods to assert real-time event ingestion.
+- Ensured all standard lint, formatting, typescript compiler, and unit test checks ran smoothly.
+## Feb 25, 2026 - Frontend UI - Layout & Sidebar (Step 5)
+- Added missing shadcn-svelte UI components via the CLI.
+- Implemented the main layout in SvelteKit using Sidebar.Provider.
+- Implemented load function in SvelteKit to fetch /api/chats.
+- Added proxy to SvelteKit vite.config.ts for local dev.
+- Added vitest-browser tests for the AppSidebar.
+- Fixed SvelteKit adapter-static to allow SPA by removing prerender=true.
+## Feb 25, 2026 - Frontend UI - Chat Pane & Message Input (Step 6)
+- Created web/src/lib/types.ts defining ChatMessage, UserMessage, and CommandLogMessage.
+- Implemented web/src/routes/chats/[id]/+page.svelte with actual message history viewing.
+- Designed chat history UI differentiating user messages and log messages.
+- Formatted log message rendering to be mono-spaced and styled error blocks in red.
+- Created fixed bottom input area via fixed layout allowing scrolling of history above it.
+- Implemented sendMessage binding on forms to POST /api/chats/:id/messages endpoints.
+- Authored component specs ensuring distinct elements for different message kinds using vitest-browser-svelte.
+- Note to self: SvelteKit tests mirroring a Svelte route component like +page.svelte must not include a + in their test file name.
+## Feb 25, 2026 - Frontend UI - SSE Integration (Step 7)
+- Implemented standard EventSource logic in web/src/routes/chats/[id]/+page.svelte.
+- Refactored data.messages into liveMessages state array synced natively.
+- Connected the component mount and update lifecycle with the GET /api/chats/:id/stream SSE endpoint.
+- Correctly bounded EventSource.onmessage to parse JSON from the socket stream and append new messages.
+- Implemented automatic scroll pinning with Svelte's $effect primitive.

package/docs/03_web_interface/notes.md

@@ -0,0 +1,29 @@
+# Notes on Web Interface Feature
+
+## Current Architecture
+- `clawmini` is a CLI tool that runs a background daemon (`src/daemon/index.ts`).
+- Communication with the daemon currently happens over a UNIX socket via `tRPC` (`@trpc/server/adapters/standalone`).
+- Chat data is persisted in a local directory structure: `.clawmini/chats/<chat_id>/chat.jsonl`.
+- `src/shared/chats.ts` provides file-system utilities for reading/writing `ChatMessage`s (`UserMessage` or `CommandLogMessage`).
+
+## Web Interface Concept
+- A new command: `clawmini web` which will spawn an HTTP web server on a local TCP port (e.g., 8080).
+- **Backend (API)**:
+  - Needs to expose API endpoints for a generic Web UI to connect to.
+  - Can read the file system directly using `src/shared/chats.ts` functions or forward actions to the daemon via the existing tRPC socket (to execute commands, etc.).
+  - Real-time updates ("pushed any new messages when they arrive") will require either Server-Sent Events (SSE) or WebSockets. File watching (`chokidar` or `fs.watch`) on `chat.jsonl` files or tapping into the daemon's tRPC events can provide the trigger.
+- **Frontend (UI)**:
+  - Basic layout: Sidebar (list of chats), Main pane (Chatbox, list of messages).
+  - Must be served essentially as a "static" site. If the user hits `localhost:8080/chats/foo`, the server should serve the `index.html` fallback (SPA routing) so the frontend router handles the display.
+  - SvelteKit is preferred by the user. SvelteKit's `adapter-static` enables building an SPA that fits exactly this requirement (static files with client-side routing and fallbacks).
+
+## Technology Choices & Integration
+1.  **Frontend Framework**:
+    - **Svelte/SvelteKit** (Preferred): Excellent for small, reactive apps. We can build it as an SPA using `@sveltejs/adapter-static` with `fallback: 'index.html'`. The compiled output (HTML/JS/CSS) can be bundled into the `dist/web` directory when the CLI is built, and `clawmini web` will just serve these static files using a basic node server.
+    - **Vanilla/Web Components**: Easiest integration (no build step for the CLI besides basic TS compilation), but higher development cost for reactive features and UI components.
+    - **React (Vite)**: Similar to SvelteKit, requires a separate build step.
+2.  **API / HTTP Server**:
+    - We could use a lightweight web framework like `Express`, `Hono`, or `Fastify` for the `clawmini web` server.
+    - The server will serve the Svelte static files AND expose `/api/*` routes.
+3.  **Real-time Updates**:
+    - Server-Sent Events (SSE) over HTTP is simpler to implement than WebSockets since it works over standard HTTP without additional upgrade logic, perfect for a one-way "push" of new messages.

package/docs/03_web_interface/prd.md

@@ -0,0 +1,42 @@
+# PRD: Web Interface for Clawmini (`clawmini web`)
+
+## Vision
+The goal is to provide a local, web-based graphical user interface for `clawmini` that runs alongside the CLI. This interface will allow users to comfortably view their active workspaces, chat sessions, and command outputs in a richer, more persistent format than a standard terminal output.
+
+## Product/Market Background
+`clawmini` operates as a daemonized local AI agent. While the CLI is fast and scriptable, interpreting long chat histories, comparing multi-turn outputs, or simply managing multiple parallel chats can be cumbersome in a pure terminal environment. A dedicated Web UI bridges this gap, offering the ergonomics of modern web applications without compromising the local, file-based architecture of the CLI. The decision to use SvelteKit and Tailwind/shadcn-svelte aligns with modern rapid prototyping preferences, enabling a high-quality UI while shipping as a static asset.
+
+## Use Cases
+1.  **Visual Chat History:** A user wants to review a complex, multi-turn conversation with the agent, complete with distinct visual separation for user messages, daemon logs, and command execution results.
+2.  **Live Monitoring:** A user runs a long-running task via the CLI and wants to monitor the agent's progress and thought process in a dedicated browser tab.
+3.  **Chat Management:** A user wants to easily switch between different chat sessions (e.g., "feature-x", "bugfix-y") using a visual sidebar without needing to type `clawmini chats list` and `clawmini chats set-default`.
+4.  **API Extensibility:** A developer wants to build a custom dashboard that interacts with the `clawmini` local data. The web server must expose clean REST/SSE endpoints.
+
+## Requirements
+
+### Architecture
+1.  **Separate Server Process:** The `clawmini web` command will spin up a new Node.js HTTP server. This server runs independently but communicates with the existing `clawmini` daemon (via its UNIX socket) to execute actions.
+2.  **Static UI Assets:** The frontend will be a SvelteKit application built using `@sveltejs/adapter-static` with an `index.html` fallback. The compiled assets will be bundled into the CLI package (e.g., `dist/web`) and served statically by the `clawmini web` Node server.
+3.  **API Endpoints:** The Node server must expose `/api/*` endpoints to handle data requests from the frontend or third-party tools.
+    -   `GET /api/chats` - List available chats.
+    -   `GET /api/chats/:id` - Get history for a specific chat.
+    -   `POST /api/chats/:id/messages` - Send a new message to the daemon (proxied to the UNIX socket).
+
+### Real-Time Updates (SSE)
+1.  **Server-Sent Events:** The server must provide a `GET /api/chats/:id/stream` endpoint.
+2.  **File Watching:** This endpoint will use `node:fs` watchers on the respective `.clawmini/chats/:id/chat.jsonl` file. When the file is appended to by the daemon, the server must push the new `ChatMessage` to connected SSE clients.
+
+### User Interface (SvelteKit + TailwindCSS + shadcn-svelte)
+1.  **Layout:** A standard two-pane layout:
+    -   **Sidebar:** Lists all available chats. Highlights the currently selected chat.
+    -   **Main Area:** Displays the message history of the selected chat. Includes a text input area at the bottom to send new messages.
+2.  **Message Rendering:** Must differentiate between `UserMessage` and `CommandLogMessage` types visually. Command logs should ideally show standard output/error distinctly.
+3.  **Routing:** Standard SPA routing. Hitting `localhost:8080/chats/foo` directly must load the UI and fetch the `foo` chat history.
+
+### Constraints & Considerations
+-   **Security:** The web server runs locally. It should bind to `127.0.0.1` (localhost) by default to prevent unauthorized network access unless a specific host flag is provided.
+-   **Build Process:** The `package.json` needs to be updated to build the SvelteKit project into a static directory before or alongside the `tsdown` build for the CLI.
+
+## Non-Goals
+-   Authentication (it's a local development tool).
+-   Cloud syncing of chats (handled by git/filesystem natively if the user chooses).

package/docs/03_web_interface/questions.md

@@ -0,0 +1,8 @@
+# Questions for Web Interface Feature
+
+## Q1: Web Server vs Daemon Roles
+**Q:** Should `clawmini web` spin up a separate HTTP server process (e.g., at `localhost:8080`) that bridges to the existing Unix socket daemon, or should the daemon itself be modified to optionally listen on a TCP port and serve the web UI/API?
+**A:** `clawmini web` should spin up a separate HTTP server that communicates with the daemon via its Unix socket.
+\n## Q2: SvelteKit Integration\n**Q:** SvelteKit integration requires a dual-build setup with `@sveltejs/adapter-static`. Are you comfortable with this approach?\n**A:** Let's try SvelteKit and see how it goes.
+\n## Q3: Real-time Updates (SSE vs WebSockets)\n**Q:** Is an SSE approach driven by file-watching acceptable for pushing updates to the UI, or do you prefer WebSockets?\n**A:** Yes, SSE sounds great!
+\n## Q4: CSS Preferences\n**Q:** Should we strictly use vanilla CSS to keep dependencies light, or would you prefer a styling framework like TailwindCSS (v3 or v4)?\n**A:** Yeah, let's use tailwind + shadcn-svelte for ui.

package/docs/03_web_interface/tickets.md

@@ -0,0 +1,59 @@
+# Tickets: Web Interface (`clawmini web`)
+
+In general, prefer shadcn-svelte UI components when they exist.
+
+## Step 1: Initialize SvelteKit Frontend
+
+- **Description:** Scaffold a new SvelteKit project (e.g., in a `web/` directory) configured with `@sveltejs/adapter-static` and an `index.html` fallback. Set up TailwindCSS and shadcn-svelte. Update the root `package.json` to include a build script that compiles the SvelteKit app and outputs the static assets to `dist/web`.
+- **Verification:**
+  - Running `npm run build` at the root successfully generates `dist/web/index.html`.
+  - All standard checks pass: `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Complete
+
+## Step 2: Implement `clawmini web` Command & Static Server
+
+- **Description:** Create the `src/cli/commands/web.ts` command. Implement a local Node.js HTTP server that binds to `127.0.0.1` (with a configurable `--port` flag, defaulting to 8080). Configure the server to serve static files from `dist/web` and fallback to `dist/web/index.html` for unknown routes (to support SPA routing).
+- **Verification:**
+  - Add a CLI test that runs `clawmini web --port 8080` in the background, curls `http://127.0.0.1:8080/`, and asserts a 200 OK response containing the HTML.
+  - All standard checks pass: `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Complete
+
+## Step 3: Implement REST API Endpoints
+
+- **Description:** Add routing logic to the Node.js server for `/api/*`. Implement `GET /api/chats` (list chats), `GET /api/chats/:id` (get chat history), and `POST /api/chats/:id/messages` (send a message to the daemon via the UNIX socket using the existing tRPC client).
+- **Verification:**
+  - Add integration tests for the new HTTP API endpoints to verify they correctly read from the file system and forward messages to the daemon.
+  - All standard checks pass: `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Complete
+
+## Step 4: Implement Server-Sent Events (SSE) Endpoint
+
+- **Description:** Implement `GET /api/chats/:id/stream` in the web server. Use `node:fs` to watch the corresponding `.clawmini/chats/:id/chat.jsonl` file. Push new messages as Server-Sent Events to connected clients and ensure watchers are properly cleaned up on disconnect.
+- **Verification:**
+  - Write a test that connects to the SSE endpoint, simulates a daemon appending a message to the `chat.jsonl` file programmatically, and verifies the event is received.
+  - All standard checks pass: `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Complete
+
+## Step 5: Frontend UI - Layout & Sidebar
+
+- **Description:** In the SvelteKit app, build the main two-pane layout. Use the shadcn-svelte sidebar component to fetch and display the list of available chats from `GET /api/chats`. Add client-side routing to navigate to `/chats/:id` and visually highlight the active chat.
+- **Verification:**
+  - Add basic component/unit tests in the SvelteKit project to ensure the sidebar renders a mock list of chats correctly.
+  - All standard checks pass: `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Complete
+
+## Step 6: Frontend UI - Chat Pane & Message Input
+
+- **Description:** Implement the Main Area of the UI. Fetch and display the message history for the selected chat from `GET /api/chats/:id`. Differentiate visually between `UserMessage` and `CommandLogMessage` (e.g., standard output vs. standard error). Add a text input to post new messages via `POST /api/chats/:id/messages`.
+- **Verification:**
+  - Add component tests to verify that `UserMessage` and `CommandLogMessage` are rendered with distinct visual styles.
+  - All standard checks pass: `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Complete
+
+## Step 7: Frontend UI - SSE Integration
+
+- **Description:** Connect the SvelteKit frontend to the `GET /api/chats/:id/stream` endpoint using the `EventSource` API. Automatically append new messages to the chat history in real-time as they arrive. Implement basic auto-scrolling to the latest message.
+- **Verification:**
+  - Add a test or mock simulating an SSE message arrival and verify the UI state updates to include the new message.
+  - All standard checks pass: `npm run format:check && npm run lint && npm run check && npm run test`.
+- **Status:** Complete

package/docs/04_agents/development_log.md

@@ -0,0 +1,54 @@
+# Development Log
+
+## Ticket 1: Core Configuration and Workspace Utility for Agents
+
+- **Implementation**: 
+  - Extracted `AgentSchema` and `Agent` type to `src/shared/config.ts`.
+  - Added utility functions in `src/shared/workspace.ts`: `getAgent`, `listAgents`, `writeAgentSettings`, `deleteAgent`.
+  - Implemented `isValidAgentId` to prevent directory traversal attacks by disallowing paths with `../` or `/` or ``.
+  - Re-wrote `src/shared/workspace.test.ts` to include tests for all the new functionality and path resolution methods.
+- **Fixes**: Fixed a pre-existing lint issue in `src/cli/commands/web.ts` where a caught error `err` was unused.
+- **Verification**: Ran `npm run format && npm run lint && npm run check && npm run test`, all checks passed. Tests run smoothly, including E2E.
+
+
+## Ticket 2: Daemon Support for Agent Execution
+
+- **Implementation**: 
+  - Updated `src/daemon/message.ts` to fetch the chat`'s active agent and override the `defaultAgent` configurations dynamically.
+  - Resolved `directory` relative to the workspace root using `getWorkspaceRoot(cwd)` to securely scope execution paths.
+  - Allowed merging of custom agent `env` and `commands` correctly.
+  - Added test cases in `src/daemon/message.test.ts` to explicitly test configuration merging and working directory assignments.
+- **Fixes**: Fixed `message.test.ts` failing mock bindings after `getAgent` and `getWorkspaceRoot` were added to the `../shared/workspace.js` mock.
+- **Verification**: Ran `npm run format && npm run lint && npm run check && npm run test`, all checks passed. Tests run smoothly, including the e2e tests.
+\n## Ticket 3: Agent CLI Commands (Add, Update, Delete, List)\n\n- **Implementation**:\n  - Created `src/cli/commands/agents.ts` with `add`, `update`, `list`, and `delete` subcommands using commander.\n  - Added support for parsing multiple `--env KEY=VALUE` flags into an object record.\n  - Hooked up `--directory` flag to set the agent's `directory` setting.\n  - Imported and registered `agentsCmd` inside `src/cli/index.ts`.\n  - Wrote robust E2E tests in `src/cli/e2e.test.ts` simulating adding, listing, updating and deleting an agent.\n- **Verification**: Ran formatting, linting, type-check, and vitest test cases. All passed.
+
+## Ticket 4: CLI Support for Selecting an Agent per Chat
+
+- **Implementation**: 
+  - Updated `src/cli/commands/messages.ts` `send` command to include a new `-a, --agent <name>` flag.
+  - Implemented validation for the selected agent by leveraging `isValidAgentId` and verifying its existence using `getAgent`. If the agent fails validation, the CLI gracefully exits with a clear error message.
+  - Added logic to automatically persist the selected agent to the chat's `settings.json` file using `readChatSettings` and `writeChatSettings`.
+  - Added new E2E tests in `src/cli/e2e.test.ts` to ensure setting the agent works, persists, and using an invalid agent fails appropriately. Also increased the vitest `beforeAll` and `afterAll` hook timeouts for e2e tests from default to 30000ms.
+- **Verification**: Ran `npm run format && npm run lint && npm run check && npm run test`, all checks passed.
+
+
+## Ticket 5: Web UI API Endpoints for Agents
+
+- **Implementation**:
+  - Updated the internal HTTP server in `src/cli/commands/web.ts` to include REST endpoints for agent management under `/api/agents` and `/api/agents/:id`.
+  - Added support for `GET`, `POST` (create), `PUT`/`POST` (update), and `DELETE` on these endpoints.
+  - Used shared utilities `listAgents`, `getAgent`, `writeAgentSettings`, `deleteAgent`, and `isValidAgentId` from `src/shared/workspace.ts` to ensure interactions are secure.
+  - Added API testing to the `should run web command and serve static files` test block in `src/cli/e2e.test.ts` to ensure proper routing, data returning, and persistence.
+- **Verification**: Ran `npm run format && npm run lint && npm run check && npm run test`, fixed ESLint warnings for explicit `any` usage. All checks passed.
+
+## Ticket 6: Web UI Integration for Agent Management & Chat Creation
+
+- **Implementation**:
+  - Updated src/cli/commands/web.ts POST /api/chats endpoint to accept an optional agent parameter and save it into the chat settings via writeChatSettings.
+  - Updated the SvelteKit loader in web/src/routes/+layout.ts to fetch and expose the list of agents so it is globally accessible across the UI.
+  - Modified the New Chat dialog within web/src/lib/components/app/app-sidebar.svelte to include an optional dropdown for choosing an initial agent from the fetched agents list.
+  - Created a dedicated Agent Management page at web/src/routes/agents/+page.svelte featuring a clean grid layout of existing agents.
+  - Provided functionality within the Agents page to view, create, edit, and delete agents. Environment variables are managed efficiently through parsed multiline inputs.
+  - Added types and ensured strict TS compatibility across app-sidebar.svelte and the data properties in layout and test mock files.
+- **Fixes**: Reconciled a bug in Svelte tests where agents array was missing in mockData, and updated Svelte page properties type bindings.
+- **Verification**: Ran npm run format:check && npm run lint && npm run check && npm run test, all checks passed. UI changes are fully tested natively.

package/docs/04_agents/notes.md

@@ -0,0 +1,45 @@
+# Notes on Agents Feature
+
+## Current State
+
+- `settings.json` in the workspace root (`.clawmini/settings.json`) currently contains a `defaultAgent` object with the schema:
+  ```json
+  {
+    "defaultAgent": {
+      "commands": {
+        "new": "...",
+        "append": "...",
+        "getSessionId": "...",
+        "getMessageContent": "..."
+      },
+      "env": {
+        "KEY": "VALUE"
+      }
+    }
+  }
+  ```
+- Each chat has its own `settings.json` at `.clawmini/chats/<chatId>/settings.json`, which currently just maps a `defaultAgent` string to a session ID (wait, it just has `defaultAgent` pointing to an agent id as a string, e.g., `"defaultAgent": "my-agent"` or `"defaultAgent": "default"`. Let's verify this.)
+- Actually, `message.test.ts` shows `defaultAgent: 'my-agent'`.
+
+## Proposed Agents Feature
+- We need a `clawmini agents` command group with `add`, `delete`, `list`.
+- Agents will be stored at `.clawmini/agents/<id>/settings.json`.
+- The configuration structure for an agent in `.clawmini/agents/<id>/settings.json` will mirror the `defaultAgent` config, plus a new `directory` key:
+  ```json
+  {
+    "commands": { ... },
+    "env": { ... },
+    "directory": "./<agent_name>"
+  }
+  ```
+- Agent settings will act as overrides/extensions over the main `settings.json`'s `defaultAgent`.
+- `directory` will be used as the `cwd` when executing the agent's commands. It's either absolute or relative to the workspace root (parent of `.clawmini`).
+- The `clawmini messages send` command should get an `--agent <id>` flag to set the agent for a chat.
+- UI changes: The web UI should let users select the default agent when creating a chat. The web UI needs to create new agents as well.
+
+## Findings from Code
+- `src/shared/config.ts` will need to be updated to support an `Agent` schema.
+- `src/daemon/message.ts` (the daemon message handler) will need to be updated to merge the selected agent's config with the workspace's `defaultAgent` config and use the agent's `directory` as `cwd`.
+- The `src/cli/commands/messages.ts` will need an `--agent` flag that updates the chat's settings to use the specified agent, via `writeChatSettings` in `src/shared/workspace.ts`.
+- The UI is built with SvelteKit. We'll need a new route/dialog to create agents, and a way to choose an agent when creating a chat.
+- UI API endpoints: we'll probably need `/api/agents` to list and create agents, and `/api/agents/:id` to manage them.