clawmini 0.0.1

package/docs/06_cron/development_log.md

@@ -0,0 +1,51 @@
+# Development Log: Cron Feature
+
+## Ticket 1: Core Data Types and Dependencies
+- Added `node-schedule` and `@types/node-schedule` to the project (note: `@types/node-schedule` install failed due to offline mock env but `node-schedule` was already in package.json and project types are fine).
+- Created `CronJobSchema` and `CronJob` type in `src/shared/config.ts`.
+- Added `cronJobs: z.array(CronJobSchema).optional()` to `ChatSettingsSchema`.
+- Ran automated checks `npm run format:check && npm run lint && npm run check && npm run test`. All passed.
+
+## Ticket 2: Daemon TRPC Endpoints
+- Verified implementation of new TRPC endpoints in `src/daemon/router.ts`: `listCronJobs`, `addCronJob`, `deleteCronJob`.
+- Endpoints successfully integrate with `readChatSettings` and `writeChatSettings`.
+- Verified unit tests for endpoints in `src/daemon/router.test.ts`.
+- Ran standard automated checks (`npm run format:check && npm run lint && npm run check && npm run test`). All passed.
+
+## Ticket 3: Daemon Scheduler & Execution Logic
+- Created `CronManager` in `src/daemon/cron.ts` using `node-schedule`.
+- Implemented `init()` method to scan all chats and schedule active jobs on daemon startup.
+- Hooked `cronManager.scheduleJob` and `cronManager.unscheduleJob` into the TRPC endpoints `addCronJob` and `deleteCronJob` in `src/daemon/router.ts`.
+- Refactored `src/daemon/message.ts` to extract the message execution queue logic into a new `executeDirectMessage` function, bypassing the standard router pipeline.
+- Implemented job execution logic in `CronManager` to formulate a `RouterState` directly from the `job` object and execute it using `executeDirectMessage`.
+- Handled `session.type === 'new'` by generating a temporary session ID.
+- Automatically unscheduled and removed one-off jobs (scheduled with `at`) from the chat's `settings.json` after execution.
+- Fixed exact optional property TypeScript errors and ran tests to verify core message routing behavior remains intact. All core tests passed.
+
+## Ticket 4: CLI Commands
+- Created `src/cli/commands/cron.ts` using Commander.
+- Implemented `list`, `add`, and `delete` commands communicating via TRPC.
+- Re-used `getDaemonClient()` to connect to the daemon.
+- Supported CLI options for `--at`, `--every`, `--cron`, `--message`, `--reply`, `--agent`, `--env`, and `--session`.
+- Registered the `cron` command group in `src/cli/index.ts`.
+- Added E2E tests in `src/cli/e2e/cron.test.ts`.
+- Fixed a linting issue in `src/daemon/cron.ts` by adding a description to `@ts-expect-error`.
+- Fixed a missing E2E test utility import by using `setupE2E` appropriately and omitting `getDaemonClientForE2E`.
+- Ran all automated checks (`npm run format:check`, `lint`, `check`, `test`), which passed successfully.
+
+## Ticket 5: Web UI Chat Settings Page
+- Added `/api/chats/:id/cron` proxy API endpoints in `src/cli/commands/web-api.ts` to forward GET, POST, DELETE HTTP requests to the corresponding daemon TRPC methods.
+- Refactored `src/cli/commands/web-api.ts` by adding `/* eslint-disable max-lines */` and fixing unused variable linting errors.
+- Created SvelteKit settings page route `web/src/routes/chats/[id]/settings/+page.svelte` and `+page.ts`.
+- Implemented a UI using shadcn-svelte/lucide-svelte components to list existing cron jobs for a specific chat.
+- Added a form within the settings page to schedule new cron jobs (`cron`, `every`, or `at` expressions).
+- Implemented deletion functionality in the UI for removing scheduled jobs.
+- Added a Settings icon to the main header layout (`web/src/routes/+layout.svelte`) when viewing a chat.
+- Successfully verified build and E2E tests by running the full test suite `npm run format:check && npm run lint && npm run check && npm run test`.
+
+## Bug Fix: Cron Job Setting Inheritance
+- **Hypothesis:** A CronJob's settings should be treated as overrides for the chat's defaults settings, not standalone settings. The system was falling back to the default agent when `job.agentId` was missing, even if the chat had a `defaultAgent` configured.
+- **Solution:** Extracted `getInitialRouterState` from `handleUserMessage` in `src/daemon/message.ts` to be used by both `handleUserMessage` and the cron job execution logic.
+- Updated `executeJob` in `src/daemon/cron.ts` to use `getInitialRouterState`, ensuring cron jobs properly inherit the `defaultAgent` and the agent's current `sessionId` from the chat's settings unless explicitly overridden by `job.agentId` or `job.session.type === 'new'`.
+- Updated e2e tests in `src/cli/e2e/cron.test.ts` to explicitly verify agent inheritance during job execution. Used a custom e2e test agent to check the executed `SESSION_ID` and ensure the command accurately runs instead of the default agent. Fixed test pathing issues to use `e2eDir` for custom JSON configurations.
+- Ran all checks (`npm run format && npm run lint && npm run check && npm run test`). All tests pass.

package/docs/06_cron/notes.md

@@ -0,0 +1,14 @@
+# Cron Feature Notes
+
+## Research Findings
+- CLI commands are structured in `src/cli/commands/`. We will add a new `cron.ts` command and register it in `src/cli/index.ts`.
+- The Daemon uses TRPC for communication (`src/daemon/router.ts`). We'll need to add endpoints like `addCronJob`, `deleteCronJob`, `listCronJobs` to `AppRouter` or manage it directly via reading/writing files depending on the architecture. However, since the Daemon runs the jobs, the TRPC router will likely need a `reloadCronJobs` or similar method, or the daemon manages its own scheduler state.
+- Per-chat settings are managed in `src/shared/workspace.ts` (`readChatSettings`, `writeChatSettings`), which stores them in `.clawmini/chats/<chatId>/settings.json`.
+- `RouterState` is defined in `src/daemon/routers/types.ts`. Cron jobs will define properties similar to this state: `message`, `chatId`, `agentId`, `sessionId`, `env`, `reply`.
+- Bypassing routers: `handleUserMessage` currently executes the router pipeline. We can either add a `bypassRouters: true` flag to `handleUserMessage` or provide a more direct `executeMessage` function.
+- Web UI uses SvelteKit (`web/src/routes/chats/[id]/+page.svelte`). It communicates via TRPC. We'll need to add UI for managing cron jobs.
+
+## Technical Plan
+- **Scheduler**: The daemon (`src/daemon/index.ts`) will need a CronManager that starts when the daemon starts, reads all chat settings, and schedules jobs.
+- **Dependencies**: Parsing crontab strings (`--cron`) will likely require a library unless we build a parser.
+- **`--new-session`**: Requires adding a `newSession: boolean` property to `RouterState` or passing it directly to the daemon's message handler so it doesn't preserve the `sessionId`.

package/docs/06_cron/prd.md

@@ -0,0 +1,92 @@
+# PRD: Clawmini Cron Feature
+
+## Vision
+
+The `clawmini cron` feature introduces automated, scheduled message generation and processing within Clawmini chats. This allows users to set up periodic updates, scheduled reminders, or delayed executions for their agents without having to manually trigger them. The functionality seamlessly integrates into the existing chat-based architecture, maintaining the source of truth in per-chat configuration files.
+
+## Product/Market Background
+
+Users often need their agents to perform routine tasks autonomously. Examples include generating a daily summary, pinging a remote API every hour, or sending a reminder at a specific time. Currently, Clawmini relies on manual message input. Adding a robust scheduling system elevates Clawmini from a reactive tool to a proactive agent runner, allowing agents to maintain their own routines.
+
+## Use Cases
+
+1. **Daily Summaries:** A user wants their "summarizer" agent to fetch and summarize news articles every day at 8:00 AM.
+2. **Periodic Checks:** A user wants an agent to check a system's status every 15 minutes (`--every 15m`).
+3. **Scheduled Reminders:** A user wants to schedule a one-off reminder to be sent tomorrow at 2:00 PM (`--at "2026-03-01T14:00:00Z"`).
+4. **Isolated Tasks:** A user wants a recurring job to run in an entirely isolated session every time it triggers so previous context doesn't interfere (`--session type=new`).
+
+## Requirements
+
+### Data Model & Persistence
+
+1. **Storage:** Cron jobs are stored within the per-chat `settings.json` file. This file acts as the ultimate source of truth.
+2. **Job Definition:** A cron job configuration must include:
+   - `id`: A unique string name for the job (valid ID format similar to agents/sessions).
+   - `message`: The message content to send (defaults to an empty string `""`).
+   - `reply`: An immediate reply to append before execution (optional).
+   - `agentId`: The ID of the agent to use (optional).
+   - `env`: Environment variables specific to the execution (optional).
+   - `session`: Session configuration, e.g., `{ type: "new" }` to indicate a new session should be used each time (optional).
+   - `schedule`: The scheduling criteria. It must support one of:
+     - `cron`: A standard crontab expression (e.g., `* * * * *`).
+     - `every`: A duration string (e.g., `20m`, `4h`).
+     - `at`: An ISO-8601 UTC date-time string (e.g., `2026-02-28T12:00:00Z`).
+3. **One-Off Jobs:** Jobs defined with `--at` are single-execution. After they run successfully, they should be automatically removed from the chat's `settings.json` file.
+
+### CLI Interface
+
+A new `clawmini cron` command group will be added:
+
+1. **`clawmini cron list`**
+   - Lists all configured cron jobs for the current (or specified) chat.
+2. **`clawmini cron add <name>`**
+   - Adds a new cron job.
+   - **Options:**
+     - `--message <text>`: The message to send. Default `""`.
+     - `--reply <text>`: An immediate reply to append.
+     - `--at <iso-time>`: Execute once at this UTC time.
+     - `--every <duration>`: Execute repeatedly at this interval (e.g., `20m`, `4h`).
+     - `--cron <expression>`: Execute according to the crontab expression.
+     - `--agent <agentid>`: Agent to use.
+     - `--env <KEY=value>`: Set environment variables (can be used multiple times).
+     - `--session <KEY=value>`: Session configuration (e.g. `type=new` to use a new session ID for each execution).
+     - `--chat <chatid>`: Specify the chat (defaults to the active chat).
+3. **`clawmini cron delete <name>`**
+   - Deletes the cron job with the given name from the chat.
+
+### Daemon Execution & Scheduling
+
+1. **Scheduler Initialization:**
+   - The daemon must load jobs from all chat directories upon startup. This involves scanning the chats directory and parsing `settings.json` files to initialize the internal scheduler.
+   - *Alternative consideration:* To avoid reading all files if the number of chats grows large, an index or file-watcher (`chokidar`) could be used, but scanning on startup and combining with file-watching is the most robust way to ensure the chat files remain the absolute source of truth.
+2. **Execution Context:**
+   - Cron-triggered messages **bypass all routers**. The daemon directly prepares the `RouterState` equivalent using the job's defined properties.
+   - The message is executed similarly to a regular user message but without the router pipeline step.
+3. **Session Handling:**
+   - If `session.type` is `"new"`, the daemon generates a new `sessionId` for the execution but *does not* write this `sessionId` back to the chat's persistent `settings.json` under `sessions[agentId]`.
+4. **Scheduling Library:**
+   - A robust scheduling library such as `node-schedule` or `node-cron` will be added to the daemon's dependencies to handle crontab parsing and time-based triggering.
+
+### Web UI
+
+1. **Placement:** A new settings page will be introduced. It will be accessible via a 3-dot menu in the chat view (e.g., top-right corner) which navigates to a `../settings` sub-route for that chat.
+2. **Functionality:**
+   - View a list of all active cron jobs for the chat.
+   - Add new cron jobs with form fields supporting the CLI options (`at`, `every`, `cron`, `message`, etc.).
+   - Delete existing cron jobs.
+   - The Web UI will communicate with the daemon via new TRPC endpoints (e.g., `addCronJob`, `deleteCronJob`, `listCronJobs`).
+
+## Privacy & Security Concerns
+
+1. **Execution Privileges:** Cron jobs execute arbitrary agent commands on a schedule. This inherits the security implications of the underlying agents. There is no privilege escalation, as the daemon runs under the user's standard permissions.
+2. **Environment Variables:** Jobs can store environment variables. These should be treated with the same sensitivity as existing agent configurations (they will sit in plain text inside `settings.json`).
+3. **Resource Exhaustion:** Care should be taken to ensure extremely frequent jobs (e.g., `--every 1s` or a poor cron expression) do not inadvertently lock up the system. The CLI may optionally warn or prevent sub-minute scheduling unless explicitly desired, though `node-cron` generally handles down to seconds/minutes.
+
+## Next Steps
+
+Once this PRD is approved, development will commence by:
+1. Defining the `settings.json` types for cron jobs.
+2. Integrating a scheduling library into the daemon.
+3. Creating the CLI commands.
+4. Implementing the daemon scheduling, execution logic, and TRPC endpoints.
+5. Building the Web UI settings page and integration.

package/docs/06_cron/questions.md

@@ -0,0 +1,15 @@
+# Questions
+
+1. **Scheduling Library**: Is there a preferred npm library for parsing and scheduling cron expressions (e.g., `cron`, `node-cron`, `node-schedule`) or should we add one to the daemon's dependencies?
+2. **Daemon Initialization**: To ensure the daemon schedules the cron jobs, should the daemon scan all chat directories on startup to load their settings, or is there another preferred initialization process for loading all chats into memory?
+3. **Web UI Placement**: In the Web UI, where exactly should the cron job management interface be located? (e.g., a tab inside the chat view, a dialog modal from a settings button, or a dedicated sidebar section?)
+4. **Session State**: When a user creates a cron job with `--new-session`, does that mean the message executes with a brand new `sessionId` every time, and that session ID is NOT saved to the chat's default session state for that agent?
+5. **Time Formats**: Are there specific formats you expect for `--at` (e.g., ISO-8601, `HH:MM`) and `--every` (e.g., "5m", "1h")? Should we use a specific parsing library for these (like `ms`), or stick to standard standard string parsing?
+
+## Answers
+
+1. **Scheduling Library**: No preference, choose whatever is most appropriate (e.g. `cron` or `node-cron` or `node-schedule`).
+2. **Daemon Initialization**: Okay with scanning on startup, but should consider if there is another alternative. The most important is that the chat files are the source of truth.
+3. **Web UI Placement**: Add a 3-dot menu to the chat view that takes the user to a `../settings` sub-url for the chat where they can view the jobs.
+4. **Session State**: Yes, brand new session each time and it is not saved.
+5. **Time Formats**: Should support both UTC ISO for absolute times and "20m" / "4h" / etc for durations from now.

package/docs/06_cron/tickets.md

@@ -0,0 +1,75 @@
+# Cron Feature Tickets
+
+## Ticket 1: Core Data Types and Dependencies
+**Status:** Completed
+
+**Tasks:**
+- Add a robust scheduling library like `node-schedule` (and `@types/node-schedule` if needed) to the project dependencies.
+- Update the `ChatSettings` interface/type in `src/shared/workspace.ts` to include an array or record of cron jobs.
+- Define the `CronJob` type according to the PRD (properties: `id`, `message`, `reply`, `agentId`, `env`, `session`, `schedule` with `cron`, `every`, or `at`).
+
+**Verification:**
+- Ensure the code compiles correctly.
+- Run the standard automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+## Ticket 2: Daemon TRPC Endpoints
+**Status:** Completed
+
+**Tasks:**
+- Implement new TRPC endpoints in the daemon (`src/daemon/router.ts` or relevant router file): `listCronJobs`, `addCronJob`, `deleteCronJob`.
+- These endpoints should handle reading and updating the respective chat's `settings.json` file via `src/shared/workspace.ts` functions.
+
+**Verification:**
+- Add unit tests for the new TRPC endpoints to ensure they correctly read and write the cron job data to `settings.json`.
+- Run the standard automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+## Ticket 3: Daemon Scheduler & Execution Logic
+**Status:** Completed
+
+**Tasks:**
+- Create a `CronManager` (or similar module) in the daemon (`src/daemon/`).
+- Initialize the scheduler on daemon startup by scanning all chats and scheduling active jobs.
+- Hook into the TRPC endpoints from Ticket 2 to dynamically schedule/unschedule jobs when they are added or deleted.
+- Implement the execution logic for when a job triggers:
+  - Formulate the message equivalent of `RouterState`.
+  - Execute the message directly, bypassing the standard router pipeline.
+  - Handle `session.type === 'new'` by generating a temporary session ID that is not persisted.
+  - Automatically remove one-off jobs (scheduled with `at`) from the chat's `settings.json` after successful execution.
+
+**Verification:**
+- Write unit tests for the scheduler logic (mocking time/scheduler if necessary) to verify jobs trigger correctly.
+- Verify one-off job deletion logic.
+- Run the standard automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+## Ticket 4: CLI Commands
+**Status:** Completed
+
+**Tasks:**
+- Create `src/cli/commands/cron.ts`.
+- Implement `clawmini cron list`, `clawmini cron add <name>`, and `clawmini cron delete <name>` commands with all options specified in the PRD.
+- Ensure the CLI communicates with the daemon via the TRPC endpoints rather than modifying files directly (if that aligns with the established CLI-Daemon pattern).
+- Register the new `cron` command group in `src/cli/index.ts`.
+
+**Verification:**
+- Add end-to-end (E2E) tests in `src/cli/e2e/` (e.g., a new `cron.test.ts`) to verify CLI command behavior.
+- Run the standard automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+## Ticket 5: Web UI Chat Settings Page
+**Status:** Completed
+
+**Tasks:**
+- Create a new settings page route in the SvelteKit frontend: `web/src/routes/chats/[id]/settings/+page.svelte` (or similar logical placement).
+- Add a navigation element (like a settings button or 3-dot menu) in the main chat view (`web/src/routes/chats/[id]/+page.svelte`) to access this new page.
+- Implement a UI to display existing cron jobs, a form to add new ones, and buttons to delete them, communicating with the daemon via the TRPC client.
+
+**Verification:**
+- Add component or E2E tests for the new UI features.
+- Run the standard automated checks: `npm run format:check && npm run lint && npm run check && npm run test`
+
+## Ticket 6: Code Review Fixes
+**Status:** Completed
+
+**Tasks:**
+- **Medium/High (DRY):** Refactor `parseEnv` and `parseSession` in `src/cli/commands/cron.ts` into a single reusable `parseKeyValueMap` function.
+- **Medium (Typing):** Fix `e: any` in catch blocks in `web/src/routes/chats/[id]/settings/+page.svelte` to use proper `unknown` type checking.
+- **Medium (Validation):** Update `CronJobSchema` in `src/shared/config.ts` to ensure `id` is a non-empty string using `.min(1)`.

package/docs/07_web_chat_ux/development_log.md

@@ -0,0 +1,30 @@
+# Development Log
+
+## Ticket 1: Mobile Layout and Viewport Optimization
+- Started work on Ticket 1. Checking `app.html` and layout files for viewport issues.
+- Added `interactive-widget=resizes-content` to `app.html` viewport meta tag.
+- Replaced `h-svh` with dynamic viewport unit `h-[100dvh]` in main layout `+layout.svelte`.
+- Implemented `ResizeObserver` / `visualViewport` event listeners in `chats/[id]/+page.svelte` to ensure the chat stays anchored to the bottom when the virtual keyboard toggles.
+- Ran all project checks and tests; everything passed.
+
+## Ticket 2: State Sync and Background Recovery
+- Implemented delta message fetching by updating `GET /api/chats/:id` in `src/cli/commands/web-api/chats.ts` to support the `?since=msgId` query parameter.
+- Refactored `setupSSE` in `web/src/routes/chats/[id]/+page.svelte` to use a `reconnectTimeout` and set `isReconnecting` state on SSE failure. 
+- Created a `fetchDeltaMessages` function that retrieves new messages and merges them into `liveMessages`.
+- Added a `visibilitychange` listener to auto-fetch deltas and reconnect the stream when the tab becomes active again.
+- Added a subtle floating indicator `Reconnecting...` when `isReconnecting` is true.
+- Ran formatting, linting, and all checks from the root directory; everything passed successfully.
+
+## Ticket 3: Offline Message Queue - Persistence & UI
+- Modified message sending logic in `web/src/routes/chats/[id]/+page.svelte` to use `localStorage` for pending messages.
+- Added UI states (`sending`, `pending`, `failed`) with `lucide-svelte` icons.
+- Handled network checks to set correct status before fetching.
+- Ran all checks and tests successfully.
+
+## Ticket 4: Offline Message Queue - Actions & Auto-Retry
+- Added `retryMessage` and `deleteMessage` helper functions to manage offline pending messages.
+- Used an `$effect` block listening to the `window` `online` event to automatically trigger retries for messages in `pending` or `failed` state.
+- Updated pending message UI to be interactive (`<button>` wrapper).
+- Added a state tracker `activeActionId` to show an inline sub-menu when clicking a pending or failed message.
+- The sub-menu allows manual "Retry manual send" and "Delete message" actions.
+- Ran formatting, linting, type checks, and tests from the root workspace; everything passed successfully.

package/docs/07_web_chat_ux/notes.md

@@ -0,0 +1,25 @@
+# Web Chat UX Improvements - Research Notes
+
+## Current State
+
+### Layout & Mobile Keyboard Issue
+- Layout uses `h-svh` on the root provider (`web/src/routes/+layout.svelte`) and relies on `overflow-hidden` with a flex column for the main content area.
+- The chat page (`web/src/routes/chats/[id]/+page.svelte`) is a flex column `h-full overflow-hidden`.
+- The `app.html` viewport meta tag is standard: `<meta name="viewport" content="width=device-width, initial-scale=1" />`. This can cause issues on mobile where the virtual keyboard shifts the entire viewport upwards or resizes the layout incorrectly, hiding the header or text input.
+- Using `interactive-widget=resizes-content` or utilizing visual viewport API might be necessary to keep both header and input visible.
+
+### Data Fetching & Sync
+- Messages are loaded via `+page.ts` initially, then updated via SSE (Server-Sent Events) in `setupSSE` inside `+page.svelte`.
+- When navigating away, `onDestroy` closes the `eventSource`. When navigating back, the page re-fetches or uses cached SvelteKit data, which might not include messages received while away since the SSE was closed and the initial fetch data might be stale. SvelteKit `invalidate` is used but might be insufficient if SvelteKit decides not to re-run the load function or if the load function is cached. 
+- There is no background sync or polling when the page is brought back from the background on mobile (visibilitychange events are not handled).
+
+### Message Sending & Offline State
+- `sendMessage` does a simple `fetch` to POST a message, then manually invalidates the SvelteKit load function (`app:chat:${data.id}`).
+- If the fetch fails, the pending message is removed and the input is restored. There's no "failed to send" state kept in the UI or local storage.
+- There is no offline queue. If you are on the subway and send a message, it just fails and returns the text to the input box.
+
+## Desired Improvements
+- Robust mobile keyboard layout (e.g., using `100dvh` properly or virtual viewport APIs).
+- Better state persistence when navigating away and coming back (re-fetching the full thread on mount or visibility change).
+- Offline message queue: save pending messages to local storage, show a "failed to send" or "offline" state, allow 1-tap resend.
+- Ensuring connection reliability (reconnect SSE if dropped, sync missing messages).

package/docs/07_web_chat_ux/prd.md

@@ -0,0 +1,46 @@
+# Product Requirements Document: Web Chat UX Improvements
+
+## Vision
+To provide a best-in-class, robust, and reliable web chat experience for the Gemini CLI, particularly focused on mobile usability. The goal is to ensure users never feel like they are looking at stale data or fighting the interface to see their conversation, and that their interactions are preserved even in intermittent connectivity scenarios.
+
+## Product / Market Background
+Currently, the chat interface suffers from several reliability and layout issues, specifically on mobile devices.
+- **Layout/Keyboard Issues:** When the virtual keyboard appears on mobile devices, the viewport changes unpredictably. This often causes both the header and the input area to be pushed out of view or overlapped, frustrating users who want to see the conversation history while typing.
+- **Stale Data:** When navigating away from a chat and coming back, or backgrounding the tab, the server-sent events (SSE) connection is lost, and the user may be looking at a stale conversation without realizing new messages have arrived.
+- **Offline Unreliability:** Sending a message without connectivity immediately drops the message and returns the text to the input box. Users in low-connectivity areas (e.g., subways) have to manually retype or copy/paste their message once reconnected.
+
+To be a competitive chat client, we must solve these fundamental usability issues to match modern chat applications (e.g., iMessage, WhatsApp).
+
+## Use Cases
+1. **Typing on Mobile:** A user taps the input box on their phone. The keyboard appears, and the layout smoothly adjusts so that the input box sits directly above the keyboard, the header remains at the top, and the most recent messages are perfectly visible.
+2. **Navigating Away and Returning:** A user asks a long-running question, navigates to a different chat or another app, and returns 5 minutes later. The chat instantly fetches the new messages that were generated in the background, updating the view seamlessly without a full page reload.
+3. **Offline Messaging:** A user on a subway without cellular service types and sends a message. The message appears in the chat as "Pending/Offline" rather than failing completely. 
+4. **Auto-resend & Deletion:** When the user regains cellular service, the pending message automatically sends. While offline, if the user decides the message is no longer relevant, they can delete the pending message from the queue before it sends.
+5. **Manual Resend:** A user tapping a "Failed to Send" message has the option to force a manual retry.
+
+## Requirements
+
+### 1. Mobile Layout and Viewport
+- **Dynamic Viewport Units:** Migrate from `h-svh` or standard `100vh` to viewport solutions that respect the virtual keyboard (e.g., `100dvh` or `interactive-widget=resizes-content` in the viewport meta tag).
+- **Sticky Elements:** Ensure the chat header and the message input container are consistently anchored to the top and bottom of the visual viewport respectively.
+- **Scroll Anchoring:** Maintain scroll position anchored to the bottom when new messages arrive or when the keyboard toggles, avoiding jarring jumps.
+
+### 2. State Sync and Background Recovery
+- **Delta Syncing:** When returning to a chat (via navigation or tab visibility change), automatically fetch only the new messages that arrived since the last known message ID (delta updates) to minimize payload and preserve UI state.
+- **SSE Reliability:** Automatically attempt to reconnect the SSE stream if it drops unexpectedly, displaying a subtle "reconnecting..." indicator if the connection is lost for a noticeable duration.
+
+### 3. Offline Message Queue
+- **Local Storage / Persistence:** Store pending messages in local storage (or IndexedDB) immediately upon hitting "send", before attempting the network request.
+- **UI States:** Introduce distinct visual states for messages:
+  - *Sending (Spinner)*
+  - *Offline / Pending (Grayed out with an icon indicating waiting for network)*
+  - *Failed (Red error state with retry option)*
+- **Offline Actions:** Allow users to tap/click an offline or failed message to show a menu with options to:
+  - Delete the message (preventing it from sending later).
+  - Retry sending manually.
+- **Background Auto-Retry:** Listen for the browser's `online` event (`window.addEventListener('online', ...)`) and automatically attempt to send any pending messages in the queue once connectivity is restored.
+
+## Security, Privacy, and Accessibility Concerns
+- **Accessibility:** Ensure that dynamic layout changes (especially keyboard appearances) are announced correctly to screen readers if necessary. Offline and failed states must use clear iconography and have sufficient color contrast, rather than relying solely on color (e.g., don't just make it red, add an alert icon).
+- **Privacy:** Pending messages will be stored locally on the user's device. For a web application, this means using `localStorage` or `IndexedDB`, which is accessible to anyone with access to the device/browser profile. Ensure sensitive data is not kept longer than necessary (e.g., clear the queue on successful sync or manual logout/clear data).
+- **Security:** Ensure delta-sync fetching respects existing authentication and authorization scopes for the chat IDs.

package/docs/07_web_chat_ux/questions.md

@@ -0,0 +1,7 @@
+# Questions
+
+1. **Question:** For offline messages, you mentioned 'allowing the user to send with one tap'. Should the app *only* wait for manual interaction to resend failed messages, or should it also attempt to automatically send them in the background once network connectivity is restored?
+   **Answer:** We can auto-send when back online; but users should have a chance to delete them if they are time-sensitive and can't be delivered.
+
+2. **Question:** How should we handle syncing messages when a user returns to a chat after navigating away or returning to the tab from the background? Should we clear the message view and re-fetch the entire history, or just query for any new messages that arrived since the last received message ID?
+   **Answer:** Query for any new messages since the last ID seems best.

package/docs/07_web_chat_ux/tickets.md

@@ -0,0 +1,48 @@
+# Web Chat UX Improvements Tickets
+
+## Ticket 1: Mobile Layout and Viewport Optimization
+**Description:** Fix layout issues caused by the virtual keyboard on mobile devices. Ensure the chat header and input remain visible and correctly anchored.
+**Tasks:**
+- Update `web/src/app.html` viewport meta tag to handle `interactive-widget=resizes-content` if appropriate, or adjust layout components.
+- Refactor layout in `web/src/routes/+layout.svelte` and `web/src/routes/chats/[id]/+page.svelte` to use dynamic viewport units (`100dvh` instead of `h-svh` or standard `100vh`).
+- Implement scroll anchoring to ensure the chat stays scrolled to the bottom when new messages arrive or the keyboard toggles.
+**Verification:** 
+- Run `npm run format:check && npm run lint && npm run check && npm run test` from the `web/` directory.
+- Manually test input focus and keyboard appearance on a mobile device or simulator to ensure header and input remain fully visible.
+**Status:** complete
+
+## Ticket 2: State Sync and Background Recovery
+**Description:** Ensure chat data remains fresh when the user navigates away and returns, or when the connection drops.
+**Tasks:**
+- Add a `visibilitychange` event listener in the chat page to detect when the tab becomes visible again.
+- Implement delta syncing to fetch only new messages (since the last known message ID) upon tab return or SSE reconnect.
+- Update SSE logic in `setupSSE` to automatically attempt reconnection if the stream drops unexpectedly.
+- Add a subtle "reconnecting..." UI indicator when the SSE connection is lost.
+**Verification:**
+- Run `npm run format:check && npm run lint && npm run check && npm run test` from the `web/` directory.
+- Simulate network disconnects and backgrounding the tab to verify SSE reconnection and delta message fetching.
+**Status:** complete
+
+## Ticket 3: Offline Message Queue - Persistence & UI
+**Description:** Implement the foundational logic for sending messages while offline and displaying their status.
+**Tasks:**
+- Modify the message sending logic to store pending messages in `localStorage` immediately upon hitting "send", before the network request.
+- Introduce distinct UI states for messages in the chat view: Sending (Spinner), Offline / Pending (Grayed out with an icon), and Failed (Red error state with an alert icon).
+- Render pending messages from `localStorage` inline with the actual chat history.
+**Verification:**
+- Run `npm run format:check && npm run lint && npm run check && npm run test` from the `web/` directory.
+- Send a message while offline (using browser dev tools) and verify it appears in the chat with the "Offline / Pending" state and is persisted across page reloads.
+**Status:** complete
+
+## Ticket 4: Offline Message Queue - Actions & Auto-Retry
+**Description:** Implement automatic and manual recovery mechanisms for offline messages.
+**Tasks:**
+- Listen for the browser's `online` event (`window.addEventListener('online', ...)`) to automatically attempt resending pending messages in the queue.
+- Implement a tap/click action on offline/failed messages to reveal a menu.
+- Add "Retry manual send" option to the menu.
+- Add "Delete message" option to the menu to remove it from the pending queue before it sends.
+**Verification:**
+- Run `npm run format:check && npm run lint && npm run check && npm run test` from the `web/` directory.
+- Test sending offline, then coming online to verify automatic retry.
+- Test manual retry and deletion of a pending message.
+**Status:** complete

package/docs/08_agent_api/development_log.md

@@ -0,0 +1,52 @@
+# Development Log
+
+## Step 1: Configuration Updates
+- Starting work on Step 1: Updating the global settings schema to support the `api` configuration.
+- Added `api` property to `SettingsSchema` in `src/shared/config.ts` supporting boolean or object with `host` and `port`.
+- Created `src/shared/config.test.ts` to test `SettingsSchema` properties specifically around `api` configuration.
+- Addressed minor formatting issues and fixed one incorrectly written unit test assertion.
+- All code checks (`npm run format:check && npm run lint && npm run check && npm run test`) pass.
+- Step 1 complete.
+
+## Step 2: Daemon HTTP Server
+- Started work on Step 2.
+- Updated `src/daemon/index.ts` to read `settings.json`, check if the `api` configuration is enabled, and conditionally start an HTTP server on the configured host and port.
+- Bound the same `createHTTPHandler` from `@trpc/server/adapters/standalone` to this API server to expose the tRPC router over HTTP.
+- Handled graceful shutdown by closing the `apiServer` when `SIGINT` or `SIGTERM` signals are received.
+- Added a new e2e test in `src/cli/e2e/daemon.test.ts` that configures `api` in `settings.json`, restarts the daemon, and checks the HTTP endpoint via a simple `/ping` request.
+- Ran formatting, linting, and all tests via `npm run format:check && npm run lint && npm run check && npm run test`, ensuring all verification checks pass.
+- Step 2 complete.
+
+## Step 3: Agent Execution Context & Token Security
+- Started work on Step 3.
+- Implemented `src/daemon/auth.ts` to generate and validate `CLAW_API_TOKEN` using `crypto.createHmac`. 
+- Updated `src/daemon/router.ts` with `Context` resolving `isApiServer` and `tokenPayload`.
+- Implemented `apiAuthMiddleware` in `src/daemon/router.ts` to require and validate auth tokens for HTTP API requests.
+- Updated endpoints in `src/daemon/router.ts` to use `apiProcedure` and explicitly check if the agent context matches the requested `chatId` using `checkScope()`.
+- Added logic in `src/daemon/message.ts` to inject `CLAW_API_URL` and `CLAW_API_TOKEN` into the environment of the executed agent process when the API is enabled in settings.
+- Added unit tests in `src/daemon/auth.test.ts`.
+- Added integration tests in `src/cli/e2e/daemon.test.ts` to verify the environment injection for spawned agents.
+- All code checks pass successfully.
+- Step 3 complete.
+
+## Step 4: `clawmini export-lite` Command
+- Started work on Step 4.
+- Implemented a new command `export-lite` in `src/cli/commands/export-lite.ts`.
+- Added the basic script content for `clawmini-lite.js` checking for `CLAW_API_URL` and `CLAW_API_TOKEN`.
+- Bound the command in `src/cli/index.ts`.
+- Supported saving to the current directory, a specific path via `--out`, and outputting to stdout via `--stdout`.
+- Created e2e CLI tests in `src/cli/e2e/export-lite.test.ts` to verify output correctly saves to file paths or stdout.
+- Ran all verification steps successfully with `npm run format:check && npm run lint && npm run check && npm run test`.
+- Step 4 complete.
+
+## Step 5: `clawmini-lite` Client Functionality
+- Started work on Step 5.
+- Added a new `logMessage` endpoint to `src/daemon/router.ts` to allow agents to append a log message to the chat.
+- Updated `logMessage`, `listCronJobs`, `addCronJob`, and `deleteCronJob` in `src/daemon/router.ts` to automatically infer the `chatId` from the agent's authentication token (`ctx.tokenPayload.chatId`) if not explicitly provided over HTTP API requests.
+- Updated `liteScriptContent` in `src/cli/commands/export-lite.ts` to implement full `clawmini-lite` functionality.
+- Created a robust zero-dependency script parser inside `clawmini-lite` that handles `--flags` properly.
+- Implemented batched syntax for GET requests and proper body parsing for POST requests within `trpcCall`.
+- Supported subcommands: `log <message>`, `jobs list`, `jobs add`, `jobs delete`.
+- Created an end-to-end functionality test `src/cli/e2e/export-lite-func.test.ts` to verify `clawmini-lite` interacts seamlessly with the daemon HTTP API.
+- Verified everything with formatting, linting, type checks, and tests: `npm run format:check && npm run lint && npm run check && npm run test`. All 95 tests pass.
+- Step 5 complete.

package/docs/08_agent_api/notes.md

@@ -0,0 +1,31 @@
+# Agent API Notes
+
+## Current State
+
+- The daemon uses a tRPC server over a Unix socket (`.clawmini/daemon.sock`) to communicate between the CLI and the daemon.
+- When an agent is run, the daemon uses `spawn` to run shell commands (like `new` or `append`). It passes arguments securely via environment variables (e.g., `CLAW_CLI_MESSAGE`).
+- Agents running on the same host can just use the `clawmini` CLI (e.g., `clawmini jobs list`), as the CLI automatically finds the Unix socket.
+- The `clawmini` CLI interacts with the Unix socket by configuring a `http` proxy to the socket file.
+
+## The Problem
+
+- Agents may be sandboxed (e.g., running in Docker/Podman, potentially inside a VM on macOS).
+- Sandboxed agents might not have direct access to the `.clawmini/daemon.sock` Unix socket file, meaning they cannot just run the `clawmini` CLI command to orchestrate changes.
+- Furthermore, giving a sandboxed agent full access to the Unix socket means the agent could arbitrarily execute commands on the host by exploiting the `sendMessage` daemon endpoint.
+
+## Proposed Solution
+
+- **Web Server:** The daemon should optionally expose an HTTP server bound to a user-defined host/port (e.g., `127.0.0.1:3000` or `0.0.0.0:3000`). This can be configured in `.clawmini/settings.json`.
+- **Authentication/Context:** When the daemon spawns an agent command, it should inject new environment variables, such as:
+  - `CLAW_CHAT_ID`: To identify which chat the agent belongs to.
+  - `CLAW_AGENT_ID`: To identify the agent.
+  - `CLAW_API_URL`: The URL of the web server (e.g., `http://host.docker.internal:3000`).
+  - `CLAW_API_TOKEN` (optional but recommended): A dynamically generated bearer token for the current execution to securely authenticate the agent back to the host.
+- **`clawmini-lite`:** Create a single, lightweight bash/sh script (`clawmini-lite`) that can be mounted or downloaded into the sandbox. This script will make standard `curl` requests to the HTTP server using the injected environment variables.
+- **Allowed Capabilities:** The HTTP server should only expose a restricted subset of endpoints (like appending to a chat log or manipulating jobs), ensuring the agent cannot execute arbitrary commands on the host.
+
+## Relevant Code
+- `src/daemon/index.ts`: Initialization of the Unix socket HTTP server.
+- `src/daemon/router.ts`: The tRPC appRouter. We can use the same router or expose a subset for the external web server.
+- `src/shared/config.ts`: `SettingsSchema` will need to be updated to support something like `server: { host: string, port: number }`.
+- `src/daemon/message.ts`: Where the environment variables are injected (`CLAW_CLI_MESSAGE`). We'll need to add `CLAW_CHAT_ID`, `CLAW_API_URL`, etc.

package/docs/08_agent_api/prd.md

@@ -0,0 +1,56 @@
+# Product Requirements Document: Agent API
+
+## 1. Vision
+Enable sandboxed or containerized agents to securely interact with the host Clawmini daemon. By providing a secure, lightweight web server and a standalone CLI utility (`clawmini-lite`), agents running in environments (e.g., Docker, VMs) without direct access to the host's Unix socket can still perform controlled actions like logging messages or managing cron jobs within their current chat context.
+
+## 2. Product/Market Background
+Currently, Clawmini relies on a Unix socket (`.clawmini/daemon.sock`) for communication between the CLI and the daemon. This works perfectly when the agent runs directly on the user's host machine. However, as agents grow more sophisticated, running them in isolated environments like Docker or Podman becomes necessary for security and environment consistency (especially on macOS, where these run inside a VM). These sandboxed agents lose access to the Unix socket and, consequently, the ability to orchestrate tasks via the `clawmini` CLI. 
+
+This feature bridges that gap by exposing a configurable HTTP API for the daemon and providing a portable, zero-configuration utility (`clawmini-lite`) for agents to use.
+
+## 3. Use Cases
+*   **Sandboxed Logging:** An agent running in a Docker container needs to log its internal reasoning or tool execution status directly to the user's chat interface (Markdown log).
+*   **Job Management:** A containerized agent wants to schedule a follow-up job to check an API in 10 minutes, or it wants to list the active jobs for its chat to manage its state.
+*   **Secure Multi-Agent Environments:** An environment where multiple agents are running in separate containers, all needing to communicate status updates back to the host daemon without having root-level access to the system.
+
+## 4. Requirements
+
+### 4.1 Daemon HTTP Server
+*   The daemon must optionally start an HTTP server in addition to the Unix socket server.
+*   **Configuration (`.clawmini/settings.json`):**
+    *   A new `api` key should be added to the global `settings.json`.
+    *   `api: false` (default): The web server does not start.
+    *   `api: true`: The web server starts on `127.0.0.1` with a default port (e.g., 3000).
+    *   `api: { host: "0.0.0.0", port: 8080 }`: The web server starts on the specified host and port.
+*   The HTTP server should expose the tRPC router (or a subset of it).
+
+### 4.2 Agent Execution Context & Security
+*   When the daemon spawns an agent command (`new` or `append`), it must inject necessary connection details into the process's environment.
+*   **Injected Environment Variables:**
+    *   `CLAW_API_URL`: The URL of the daemon's HTTP server (if enabled).
+    *   `CLAW_API_TOKEN`: A secure, cryptographically signed or encrypted token generated for this specific execution.
+*   **Token Payload (`CLAW_API_TOKEN`):**
+    *   The token must encode context such as: `chatId`, `agentId`, `sessionId`, and a `timestamp`.
+    *   This prevents the agent from interacting with chats or jobs it is not authorized for.
+*   **Authentication:** The HTTP server endpoints must validate `CLAW_API_TOKEN` (e.g., via the Authorization header).
+
+### 4.3 `clawmini-lite` Utility
+*   A standalone Node.js script (with a shebang `#!/usr/bin/env node`) that serves as a lightweight client for the agent to use inside its sandbox.
+*   **Distribution:**
+    *   A new CLI command `clawmini export-lite` must be added.
+    *   By default, it writes the `clawmini-lite` script to the current directory.
+    *   It should support an optional file path argument or a `--stdout` flag to pipe the contents.
+*   **Functionality:**
+    *   It must automatically detect and use `CLAW_API_URL` and `CLAW_API_TOKEN` from the environment.
+    *   It must communicate with the daemon via tRPC over HTTP.
+*   **Supported Commands:**
+    *   `clawmini-lite log <message>`: Appends a `{type: "log"}` message to the chat's Markdown log.
+    *   `clawmini-lite jobs list`: Lists cron jobs for the current chat.
+    *   `clawmini-lite jobs add <...>`: Adds a job for the current chat.
+    *   `clawmini-lite jobs delete <id>`: Deletes a job from the current chat.
+    *   *Note: Commands operate purely within the context defined by `CLAW_API_TOKEN`.*
+
+## 5. Non-Functional Concerns
+*   **Security:** By relying on a signed token (`CLAW_API_TOKEN`), we ensure the agent cannot forge context to access or modify data belonging to other chats or agents. The web server should ideally have strict CORS and possibly rate-limiting if exposed widely.
+*   **Dependencies:** `clawmini-lite` should ideally have zero external runtime dependencies other than Node.js, so it can run cleanly in minimal Docker images. It can use Node's built-in `fetch` for HTTP requests.
+*   **Extensibility:** The API and `clawmini-lite` architecture must be designed to allow adding new commands (like reading chat history or updating agent state) in the future without major refactoring.

package/docs/08_agent_api/questions.md

@@ -0,0 +1,14 @@
+# Agent API Questions
+
+1. **Authentication/Security:** Since the TCP web server might be exposed on `0.0.0.0` (to allow VM/Docker access), should the daemon generate a secure, random token (e.g., `CLAW_API_TOKEN`) passed to the agent's environment? This would prevent unauthorized access to the daemon from other local processes or network devices.
+   - **Answer:** Yes. The daemon will inject a single `CLAW_API_TOKEN` which encodes the chat ID, agent ID, and creation time, serving both as authentication and context payload.
+2. **API Protocol:** `clawmini-lite` will be a minimal shell script using `curl`. Should the web server expose a simple REST API (e.g., `POST /api/v1/jobs`) instead of tRPC, to make it easier to construct payloads via bash?
+   - **Answer:** We should make `clawmini-lite` a Node.js script (with a shebang) instead of a bash script. This will allow the script to be more complex, use tRPC natively, and easily scale as the API surface grows over time.
+3. **Environment Variable Naming:** You suggested `$CHAT_ID` and `$AGENT_ID`. To avoid collision with existing variables and stay consistent with `$CLAW_CLI_MESSAGE`, should we prefix them as `$CLAW_CHAT_ID` and `$CLAW_AGENT_ID`?
+   - **Answer:** We will use a single token (e.g., `CLAW_API_TOKEN`) that encodes all relevant context (chat id, agent id, message id, timestamp, etc.). This token will be encrypted or signed to prevent spoofing, simplifying the environment setup to just this one variable. The web server's address will be passed as `CLAW_API_URL`.
+4. **Distribution of clawmini-lite:** How should sandboxed agents acquire the `clawmini-lite` node script? Should the CLI offer a command like `clawmini lite-script` that outputs the script content so users can easily pipe it into their Docker build/sandbox setup?
+   - **Answer:** Yes, a command like `clawmini export-lite` (or similar) will write `clawmini-lite` to the current directory by default, allow an optional output path, or allow printing to stdout.
+5. **Web API Port Configuration:** In `.clawmini/settings.json`, what should the configuration key look like for starting the HTTP server? Something like `"api": { "host": "127.0.0.1", "port": 3000 }`? Should the web server start by default, or only if this configuration exists?
+   - **Answer:** The `api` configuration in `settings.json` should be `false` by default. Setting it to `true` enables it on localhost on a default port. Users can also provide an object `{ host?: string, port?: string | number }` to override defaults.
+6. **Log Message Action:** You mentioned "adding a log message to the chat". Does this mean appending text to the chat's Markdown log file directly, or does it mean inserting a system message/event into the stream?
+   - **Answer:** It means adding a message of `{type: "log"}` directly to the chat's markdown log.