clawmini 0.0.1

package/docs/13_discord_typing_indicators/prd.md

@@ -0,0 +1,41 @@
+# Discord Typing Indicators (Heartbeat) PRD
+
+## Vision
+Improve the user experience in the Discord adapter by providing visual feedback when an AI agent is processing a request. By leveraging Discord's native "typing" indicator, users will clearly see that the daemon is working on their command and has not stalled, even during long-running LLM inferences or background operations.
+
+## Background
+Currently, when a user sends a message to the Clawmini daemon via Discord, there can be a significant delay between the user's message and the agent's response, especially for complex tasks. Without any visual feedback during this delay, users might assume the command was lost or the bot crashed. Discord supports a `sendTyping()` API for channels/DMs, which displays a "Bot is typing..." indicator for up to 10 seconds. To maintain the typing indicator for longer commands, the bot needs to continuously emit this signal.
+
+## Use Cases
+*   **Long-Running Commands:** A user asks the agent to perform an extensive codebase search and refactoring task. The Discord bot displays the typing indicator for the entire 30+ seconds it takes the daemon to respond, reassuring the user.
+*   **Preventing Double Inputs:** Seeing the typing indicator discourages users from repeatedly sending the same command or asking "are you there?".
+
+## Requirements
+
+### 1. Daemon Event Emission
+*   The daemon must emit a `DAEMON_EVENT_HEARTBEAT` (or similar) internal event while a command is actively running.
+*   In `src/daemon/message.ts` (specifically around `executeDirectMessage` where `runCommand` is called), an interval should be established to emit this heartbeat event every ~5 seconds.
+*   The interval MUST be reliably cleared once the command execution finishes (both on success and error).
+*   The heartbeat event payload must include at least the `chatId`.
+
+### 2. tRPC Subscription Endpoint
+*   The daemon's `AppRouter` (`src/daemon/router.ts`) must expose a new `waitForTyping` subscription endpoint.
+*   This endpoint will listen to the internal `daemonEvents` for the `DAEMON_EVENT_HEARTBEAT` event.
+*   It should filter events by `chatId` (similar to the existing `waitForMessages` endpoint) and yield to connected clients.
+
+### 3. Discord Adapter Integration
+*   The Discord forwarder (`src/adapter-discord/forwarder.ts`) must subscribe to the new `waitForTyping` endpoint.
+*   Upon receiving a typing event for an active chat, the adapter must fetch the corresponding Discord DM channel (using `client.users.fetch` and `user.createDM()`).
+*   The adapter must call `dm.sendTyping()`.
+*   The forwarder must handle potential errors from the `waitForTyping` subscription, similar to how it handles the `waitForMessages` stream, implementing automatic retries with exponential backoff if the connection drops.
+
+## Non-Functional Requirements
+*   **Performance:** The interval and additional local SSE connection must have a negligible footprint.
+*   **Reliability:** The interval in the daemon must be properly cleaned up in a `finally` block or similar mechanism to prevent orphaned intervals from leaking memory or causing phantom typing indicators.
+*   **Backwards Compatibility:** Existing clients (CLI, Web interface) must not be negatively impacted by this new feature. The separation of the typing stream from the `waitForMessages` stream guarantees that the persistent message model remains intact.
+
+## Implementation Steps
+1.  **Daemon Events (`src/daemon/events.ts`):** Define the new `DAEMON_EVENT_TYPING` event string.
+2.  **Daemon Message Logic (`src/daemon/message.ts`):** Wrap the `runCommand` execution in `executeDirectMessage` with a `setInterval` that emits the typing event every 5000ms. Ensure the interval is cleared via `clearInterval` when the command concludes.
+3.  **tRPC Router (`src/daemon/router.ts`):** Add the `waitForTyping` subscription endpoint to the `AppRouter`.
+4.  **Discord Adapter (`src/adapter-discord/forwarder.ts`):** Implement the `waitForTyping` subscription loop alongside the existing `waitForMessages` loop, triggering `dm.sendTyping()` when an event is received.

package/docs/13_discord_typing_indicators/questions.md

@@ -0,0 +1,6 @@
+# Questions
+## Question 1
+Q: How would you prefer the typing heartbeat to be transmitted over tRPC?
+- Option A: Add a new `waitForTyping` subscription endpoint specifically for typing events. This clearly separates persistent messages from ephemeral UI state but requires clients to open an additional subscription.
+- Option B: Introduce a temporary message type (e.g., `{ role: 'typing' }`) that gets emitted via the existing `waitForMessages` subscription (but isn't saved to the chat's JSONL file). This avoids a second subscription connection but mixes UI state into the chat model.
+Recommendation: Option A is recommended. It keeps the persistent `ChatMessage` types pure and avoids unexpectedly breaking existing clients (like the CLI) that expect all incoming messages from `waitForMessages` to be saveable, renderable chat logs. Creating an additional SSE connection over the local Unix socket is very lightweight.

package/docs/13_discord_typing_indicators/tickets.md

@@ -0,0 +1,60 @@
+# Discord Typing Indicators Tickets
+
+## Ticket 1: Define Daemon Event
+**Status**: Completed
+
+**Description**:
+Define the new `DAEMON_EVENT_TYPING` event string in the daemon's event definitions.
+
+**Tasks**:
+- Update `src/daemon/events.ts` to include a new `DAEMON_EVENT_TYPING` event constant.
+- Define the payload type for this event, which must include at least the `chatId` (string).
+
+**Verification**:
+- Verify the code compiles without errors by running `npm run check`.
+- Run all checks: `npm run format:check && npm run lint && npm run check && npm run test`.
+
+## Ticket 2: Add tRPC Subscription Endpoint
+**Status**: Completed
+
+**Description**:
+Expose a new `waitForTyping` subscription endpoint on the daemon's `AppRouter` to allow clients to listen for typing events.
+
+**Tasks**:
+- Update `src/daemon/router.ts` to add a `waitForTyping` subscription endpoint.
+- The endpoint should filter internal `DAEMON_EVENT_TYPING` events by `chatId` and yield them to connected clients.
+
+**Verification**:
+- Add or update unit tests to verify the `waitForTyping` subscription yields events for the correct `chatId` (e.g., in `src/daemon/router.test.ts`).
+- Run all checks: `npm run format:check && npm run lint && npm run check && npm run test`.
+
+## Ticket 3: Emit Typing Events During Command Execution
+**Status**: Completed
+
+**Description**:
+Update the daemon's message execution logic to periodically emit the typing event while a command is running.
+
+**Tasks**:
+- In `src/daemon/message.ts`, locate the `executeDirectMessage` function where `runCommand` is called.
+- Before `runCommand` executes, set up a `setInterval` that emits the `DAEMON_EVENT_TYPING` event every 5000ms.
+- Ensure the interval is cleared via `clearInterval` in a `finally` block to prevent orphaned intervals on both success and error.
+
+**Verification**:
+- Add or update tests to ensure the interval is set up and torn down correctly during command execution (e.g., in `src/daemon/message.test.ts` or `src/daemon/message-agent.test.ts`).
+- Run all checks: `npm run format:check && npm run lint && npm run check && npm run test`.
+
+## Ticket 4: Discord Adapter Integration
+**Status**: Completed
+
+**Description**:
+Integrate the typing event subscription into the Discord adapter to provide visual feedback to users.
+
+**Tasks**:
+- Update `src/adapter-discord/forwarder.ts` to implement a `waitForTyping` subscription loop alongside the existing `waitForMessages` loop.
+- Upon receiving a typing event for a chat, fetch the corresponding Discord DM channel using `client.users.fetch` and `user.createDM()`.
+- Call `dm.sendTyping()` to display the indicator in Discord.
+- Ensure potential errors from the `waitForTyping` subscription are handled gracefully with automatic retries and exponential backoff, identical to `waitForMessages`.
+
+**Verification**:
+- Add or update tests in `src/adapter-discord/forwarder.test.ts` to verify the new subscription loop acts as expected, errors are handled, and `dm.sendTyping` is triggered.
+- Run all checks: `npm run format:check && npm run lint && npm run check && npm run test`.

package/docs/14_interruptions/development_log.md

@@ -0,0 +1,50 @@
+# Development Log - 14_interruptions
+
+## Progress
+- **Step 1: Update Queue Management**
+  - Updated `src/daemon/queue.ts` to support aborting tasks via `AbortController`, clearing the queue, and extracting pending tasks.
+  - Ensured `enqueue` tracks `textPayload` for tasks to enable future batching.
+  - Wrote comprehensive unit tests in `src/daemon/queue.test.ts` ensuring all states and rejections are handled properly.
+  - Added `.catch` suppression in `message.ts` to gracefully handle `AbortError` and other rejections if `noWait` is enabled.
+  - Discovered and fixed an issue with macOS UNIX socket path length limits (`EINVAL`) during e2e testing by shortening test directory names (`e2e-env`, `e2e-discord`, `e2e-exp-lite`).
+  - Tests successfully verify sequential and aborted behavior without unhandled rejections.
+
+- **Step 2: Update Command Execution with AbortSignal**
+  - Updated `RunCommandFn` signature in `src/daemon/message.ts` to include `signal?: AbortSignal | undefined`.
+  - Updated `runCommand` in `src/daemon/router.ts` and `src/daemon/cron.ts`, passing `signal` to `child_process.spawn`.
+  - Added error handlers to the `spawn` process resolving promises to handle `err.name === 'AbortError'` cleanly by rejecting the promise.
+  - Plumbed `signal` down from `queue.enqueue` callback through `executeDirectMessage` and `runExtractionCommand`.
+  - Ran validation checks to ensure tests continue to pass and `tsconfig.json` requirements (`exactOptionalPropertyTypes`) are met.
+
+- **Step 3: Implement Interruption Routers**
+  - Added `action?: 'stop' | 'interrupt' | 'continue'` to `RouterState` interface in `src/daemon/routers/types.ts`.
+  - Created `@clawmini/slash-stop` router (`src/daemon/routers/slash-stop.ts`) to handle `/stop` command, which sets `action: 'stop'` and provides an acknowledgment reply.
+  - Created `@clawmini/slash-interrupt` router (`src/daemon/routers/slash-interrupt.ts`) to handle `/interrupt` command, which sets `action: 'interrupt'` and provides an acknowledgment reply.
+  - Plumbed `action` property parsing into the fallback shell execution logic within `executeCustomRouter` (`src/daemon/routers.ts`).
+  - Added `slashStop` and `slashInterrupt` to the `executeRouterPipeline` in `src/daemon/routers.ts`.
+  - Added the new routers to the default settings initialization list in `src/cli/commands/init.ts`.
+  - Wrote full test coverage in `src/daemon/routers/slash-stop.test.ts` and `src/daemon/routers/slash-interrupt.test.ts`, and updated `src/daemon/routers.test.ts`.
+  - Ensured all tests pass and typing is correct.
+
+- **Step 4: Integrate Interruptions in Message Handler**
+  - Updated `src/daemon/message.ts` to intercept `stop` and `interrupt` actions from the `RouterState` inside `executeDirectMessage`.
+  - For `stop`, called `queue.abortCurrent()` and `queue.clear()`, avoiding queuing any new tasks.
+  - For `interrupt`, called `queue.abortCurrent()` and batching any pending tasks by extracting their payloads via `queue.extractPending()` and concatenating them into the new message.
+  - Updated `queue.enqueue()` call in `executeDirectMessage` to accept `state.message` as `textPayload` for the new task.
+  - Resolved type checking errors regarding `any` usage in `src/daemon/queue.ts` where `reject` expected `unknown`.
+  - Created new unit tests `src/daemon/message-interruption.test.ts` to cover the queue aborting and batching flow.
+  - Tests verify that stopping avoids queuing and clears the queue, while interrupting aggregates pending task messages.
+  - All format, lint, type-check, and vitest suites successfully pass.
+
+## Next Steps
+- Interruption handling feature is complete.
+
+## Step 5: Final Checks
+- Ran code quality checks (`npm run format:check && npm run lint && npm run check && npm run test`).
+- Fixed type issues with `exactOptionalPropertyTypes: true` on `currentPayload` in `src/daemon/queue.ts`.
+- Addressed code formatting issues.
+- Confirmed all formatting, linting, type-checking, and tests now pass perfectly.
+## Bug Fix: Map Router Action State in Message Handler
+- **Hypothesis:** When `/stop` or `/interrupt` is sent, the router correctly sets `finalState.action = 'stop'`. However, `handleUserMessage` converts this `finalState` into a new `directState` object before passing it to `executeDirectMessage`. If `action` is not mapped over to the new object, the queue handler never receives the `action === 'stop'` flag and therefore never calls `queue.abortCurrent()`.
+- **Plan:** Update `src/daemon/message.ts` where `directState` is constructed to map `if (finalState.action !== undefined) directState.action = finalState.action;`.
+- **Result:** Applied the mapping fix and verified all tests pass. Interruption signals now properly reach the execution queue and instantly terminate running processes.

package/docs/14_interruptions/notes.md

@@ -0,0 +1,38 @@
+# Interruptions Feature Notes
+
+## Current Architecture
+
+*   **Message Processing:** Handled in `src/daemon/message.ts`. It takes user input, runs it through routers to determine the active agent and format the command, and queues it up for execution.
+*   **Execution Queue:** Managed in `src/daemon/queue.ts`. Currently, it's a simple Promise chain:
+    ```typescript
+    export class Queue {
+      private queue: Promise<void> = Promise.resolve();
+      enqueue(task: Task): Promise<void> {
+        const next = this.queue.then(task).catch(() => {});
+        this.queue = next;
+        return next;
+      }
+    }
+    ```
+    This queue is per-directory. It does not currently have functionality to cancel running tasks or clear pending tasks.
+*   **Command Execution:** `runCommand` (used by `executeDirectMessage`) runs via `child_process.spawn`. It doesn't currently accept an `AbortSignal`.
+*   **Routers:** Located in `src/daemon/routers/` (e.g., `slash-command.ts`, `slash-new.ts`). They can mutate the `RouterState`, which determines the actual command and message sent to the agent.
+
+## Implementation Requirements
+
+1.  **AbortController Integration:**
+    *   Update `RunCommandFn` and `runCommand` in `src/cli/client.ts` (or daemon runner) to accept an `AbortSignal`.
+    *   Pass the signal to `child_process.spawn(..., { signal })` so the OS sends a kill signal (typically `SIGTERM` or `SIGKILL`) when aborted.
+2.  **Queue Management:**
+    *   Add the ability to track the currently running task's `AbortController` in the `Queue` class.
+    *   Add a method to `Queue` (e.g., `abortCurrent()`) to trigger the abort.
+    *   Potentially add a method to clear the queue if the user wants to cancel all pending messages (`/stop`).
+3.  **Router Support:**
+    *   Create or update routers to parse interruption commands (e.g., `/stop`, `/interrupt`).
+    *   The router needs a way to signal back to the message handler that an interruption is requested *before* the message is queued.
+    *   Update `executeRouterPipeline` or `RouterState` to include an `interrupt` flag or an `action: 'stop' | 'interrupt'` payload.
+4.  **Message Handler Logic (`handleUserMessage` / `executeDirectMessage`):**
+    *   Before queueing the new message, check if the `RouterState` requested an interruption.
+    *   If yes, call the queue's abort method.
+    *   Send an automatic reply (log message) to the chat confirming the abortion or interruption.
+    *   Queue the new message (if not just `/stop`).

package/docs/14_interruptions/prd.md

@@ -0,0 +1,46 @@
+# Product Requirements Document: Process Interruptions
+
+## 1. Vision
+To enhance the Gemini CLI's responsiveness and user control by allowing users to seamlessly halt or interrupt long-running background tasks (agents). Users should be able to abandon a task entirely or interrupt it to inject new context/instructions without waiting for the current task to finish.
+
+## 2. Product/Market Background
+Currently, the CLI processes messages in a sequential queue per directory. Once a command starts via `child_process.spawn`, it runs to completion (or failure). If an agent goes down the wrong path or a user realizes they forgot a crucial detail, they cannot intervene until the agent finishes. Providing explicit `/stop` and `/interrupt` commands gives users back control over long-running LLM processes.
+
+## 3. Use Cases
+1.  **Runaway Agent:** A user asks an agent to "refactor the auth flow." The agent starts heavily modifying files incorrectly. The user quickly types `/stop` to kill the process and discard any queued follow-ups.
+2.  **Course Correction:** A user tasks the agent with "implementing the login page." Mid-execution, the user realizes they forgot to mention using TailwindCSS. They type `/interrupt also ensure you use Tailwind CSS.` The current agent run is killed, and the new context is batched with any other pending queued messages into a single, comprehensive follow-up task.
+
+## 4. Requirements
+
+### 4.1 Functional Requirements
+1.  **Slash Commands:**
+    *   `/stop`: Kills the currently running task in the active queue and clears all other pending, unprocessed messages in that queue.
+    *   `/interrupt [optional extra text]`: Kills the currently running task. Any text appended to the command is batched together with any other pending messages in the queue into a single, new message task.
+2.  **Process Termination:**
+    *   The system must send a termination signal (`SIGTERM`) to the underlying spawned process when an interruption is requested.
+3.  **Queue Management:**
+    *   The `Queue` (`src/daemon/queue.ts`) must support tracking the active task's `AbortController` and provide an interface to abort it.
+    *   The `Queue` must support clearing its pending tasks (for the `/stop` command).
+    *   The `Queue` must support batching pending tasks (for the `/interrupt` command).
+4.  **Router Integration:**
+    *   A new or existing router must parse `/stop` and `/interrupt` commands.
+    *   The router must set a flag or action on the `RouterState` (e.g., `action: 'stop' | 'interrupt'`) so the main message handler knows to invoke the queue interruption logic.
+    *   The router should provide a simple acknowledgment back to the user via the existing `reply` field on the `RouterState` (e.g., `reply: "[@clawmini/interrupt] Task interrupted."`).
+
+### 4.2 Technical Implementation Details
+*   **Daemon/Client Communication:** Update `runCommand` (and `RunCommandFn`) to accept and respect an `AbortSignal`. Pass this signal down to `spawn`.
+*   **Message Processing (`src/daemon/message.ts`):** In `handleUserMessage` or `executeDirectMessage`, check the resulting `RouterState`. If it indicates an interruption:
+    1.  Call the queue's abort method.
+    2.  If `/stop`, clear the queue.
+    3.  If `/interrupt`, fetch pending queue items, merge their message strings, append the new message string, and enqueue this combined payload as a single task.
+
+### 4.3 Out of Scope
+*   Handling complex fallback termination signals (e.g., escalating from `SIGTERM` to `SIGKILL` if the process hangs). We will start with standard `SIGTERM`.
+*   Interrupting tasks that are purely synchronous/CPU-bound within the Node daemon itself (this primarily targets spawned child processes).
+
+## 5. Security & Privacy
+*   Process termination should only affect child processes spawned by the current workspace queue. It must not leak signals to sibling projects or the host daemon.
+*   Path traversal and command injection risks remain unchanged, as the inputs are standard chat messages routed normally.
+
+## 6. Accessibility
+*   No new UI elements are required; the interface is purely text-based (slash commands) and relies on existing text rendering for router replies.

package/docs/14_interruptions/questions.md

@@ -0,0 +1,12 @@
+# Questions for Interruptions Feature
+
+1. **Queue behavior on Interrupt:** When a process is interrupted (via `/stop` or `/interrupt`), should we also clear any *other* pending messages currently in the queue for that directory, or just kill the currently active one?
+    *   **Answer:** With `/stop`, kill the current task and ignore/clear any pending new messages that haven't been processed yet. With `/interrupt`, stop the current task and batch any other pending messages together into one new message.
+
+2. **Command Syntax:** You mentioned `/interrupt borrow` vs `/stop`. Could you clarify the exact syntax and expected behavior of the slash commands you want to support by default? (e.g., what does `borrow` do specifically?).
+    *   **Answer:** "borrow" was just a transcription error. The syntax is `/interrupt` or `/interrupt [extra text]` (e.g., `/interrupt oh also remember to...`), and `/stop`.
+3. **Signal Type:** When we send a kill signal, Node.js's `AbortController` with `spawn` defaults to `SIGTERM`. Is this sufficient, or do we need a more aggressive force-kill (`SIGKILL`) or a tiered approach?
+    *   **Answer:** Start with `SIGTERM` and see how it works.
+
+4. **System Messages:** Should the automatic reply ("task aborted" or "task interrupted") be appended as a standard `CommandLogMessage` in the chat history?
+    *   **Answer:** Keep it simple; use the existing `reply` field that routers can provide.

package/docs/14_interruptions/tickets.md

@@ -0,0 +1,69 @@
+# Implementation Tickets: Process Interruptions
+
+## Step 1: Update Queue Management
+**Description:** Update the `Queue` class to support aborting the currently running task, clearing pending tasks, and retrieving pending tasks for batching.
+**Tasks:**
+- Modify `src/daemon/queue.ts` to track an `AbortController` for the currently executing task.
+- Add a method `abortCurrent()` that triggers the `AbortController`.
+- Add a method `clear()` or `clearQueue()` that removes all pending, non-executing tasks.
+- Add a method to retrieve and remove pending tasks (e.g., `extractPending()`) to allow for batching.
+- Update `src/daemon/queue.test.ts` to cover these new methods and ensure promises are handled correctly without unhandled rejections.
+**Verification:**
+- Run: `npm run format:check && npm run lint && npm run check && npm run test`
+**Status:** Complete
+
+## Step 2: Update Command Execution with AbortSignal
+**Description:** Plumb the `AbortSignal` down to the actual process execution so that `child_process.spawn` can terminate the task.
+**Tasks:**
+- Locate where `runCommand` or `RunCommandFn` is defined and used (likely in `src/cli/client.ts`, `src/daemon/message.ts`, or similar).
+- Update the signature to accept an `AbortSignal`.
+- Pass the `signal` option to `child_process.spawn`.
+- Ensure that the resulting promise resolves or rejects cleanly when aborted (catching `AbortError` or checking process termination signal).
+- Add or update relevant unit tests to verify the abort behavior.
+**Verification:**
+- Run: `npm run format:check && npm run lint && npm run check && npm run test`
+**Status:** Complete
+
+## Step 3: Implement Interruption Routers
+**Description:** Create slash command routers to detect `/stop` and `/interrupt` commands from the user and signal the intended action via the `RouterState`.
+**Tasks:**
+- Update the `RouterState` interface (e.g., in `src/daemon/routers.ts`) to include an `action: 'stop' | 'interrupt' | 'continue'` field or similar interrupt flag.
+- Create a new router for `/stop` (e.g., `src/daemon/routers/slash-stop.ts`) that sets the action to 'stop' and provides an acknowledgment in the `reply` field.
+- Create a new router for `/interrupt` (e.g., `src/daemon/routers/slash-interrupt.ts`) that sets the action to 'interrupt' and provides an acknowledgment.
+- Update `src/daemon/routers/index.ts` to include the new routers in the pipeline.
+- Write unit tests for the new routers in the appropriate `.test.ts` files.
+**Verification:**
+- Run: `npm run format:check && npm run lint && npm run check && npm run test`
+**Status:** Complete
+
+## Step 4: Integrate Interruptions in Message Handler
+**Description:** Wire up the router states to the queue methods within the main message processing loop.
+**Tasks:**
+- Update the message handling logic in `src/daemon/message.ts` (e.g., `handleUserMessage` or `executeDirectMessage`).
+- After router execution, check the `RouterState` for interruption commands.
+- If `action === 'stop'`: call `queue.abortCurrent()` and `queue.clear()`. Do not enqueue a new task.
+- If `action === 'interrupt'`: call `queue.abortCurrent()`, extract pending tasks via `queue.extractPending()`, concatenate their text payloads with the new user message, and enqueue the combined payload as a single new task.
+- Ensure the system replies to the user with the router's acknowledgment message.
+- Update tests in `src/daemon/message.test.ts` (or similar) to verify the end-to-end interruption flow.
+**Verification:**
+- Run: `npm run format:check && npm run lint && npm run check && npm run test`
+**Status:** Complete
+
+## Step 5: DRY Violation - Extract shared spawn logic
+**Description:** The logic for `spawn` and wrapping it in a Promise for `runCommand` is duplicated in `src/daemon/cron.ts`, `src/daemon/router.ts`, and `src/daemon/message-test-utils.ts`. Extract it into a shared utility function.
+**Tasks:**
+- Create `src/daemon/utils/spawn.ts` or a suitable shared location.
+- Extract the common `runCommand` Promise wrapper logic there.
+- Update `cron.ts`, `router.ts`, and `message-test-utils.ts` to use this new utility.
+- Ensure type definitions (`RunCommandFn` etc) are imported correctly.
+**Status:** Complete
+**Priority:** High
+
+## Step 6: DRY Violation - Consolidate slash command routers
+**Description:** `slash-stop.ts` and `slash-interrupt.ts` are almost identical. Refactor to use a shared factory or utility for creating these static action routers to follow DRY principles.
+**Tasks:**
+- Create a shared utility function in `src/daemon/routers/utils.ts` (or similar) that generates these basic slash command routers.
+- Update `slash-stop.ts` and `slash-interrupt.ts` to use this utility.
+- Verify tests still pass.
+**Status:** Complete
+**Priority:** Medium

package/docs/15_sandbox_policies/development_log.md

@@ -0,0 +1,95 @@
+# Development Log
+
+## Ticket 1: Core Configuration and Request State Management
+Starting implementation of Ticket 1.
+
+**Notes:**
+- Created `src/shared/policies.ts` defining `PolicyConfig`, `PolicyDefinition`, `PolicyRequest`, and `RequestState`.
+- Implemented `RequestStore` in `src/daemon/request-store.ts` to manage requests persistently under `.clawmini/tmp/requests`.
+- Added unit tests for `RequestStore` covering normal operations and graceful handling of corrupted JSON files.
+- Ensured all tests, types, and formatting pass. Ticket 1 is complete.
+
+## Ticket 2: File Snapshotting and Security Layer
+**Notes:**
+- `src/daemon/policy-utils.ts` and `src/daemon/policy-utils.test.ts` implement snapshotting, argument interpolation, and safe execution.
+- Verified test coverage and passed formatting/linting checks.
+- Ticket 2 is complete.
+
+## Ticket 3: Daemon Request Service
+**Notes:**
+- Created `src/daemon/policy-request-service.ts` and `src/daemon/policy-request-service.test.ts`.
+- The service enforces maximum limit of pending requests (100).
+- Handled snapshot generation for mapping file paths using `createSnapshot`.
+- Stored requested payloads via `RequestStore`.
+- Authored passing unit tests for request creation, rejection (on threshold), and argument interpolation handling.
+- Ensured all codebase formatting, linting, and tests passed via the required checks.
+- Ticket 3 is complete.
+## Ticket 4: CLI Agent Commands
+**Notes:**
+- Implemented `clawmini requests list` to view available policies.
+- Implemented `clawmini request <cmd> [--help] [--file name=path] -- [args]` to spawn policies or send them as requests to the daemon.
+- Added `listPolicies` and `createPolicyRequest` to the daemon's AppRouter.
+- Handled Commander's excess argument parsing correctly to allow passing opaque arguments without errors.
+- Created `src/cli/e2e/requests.test.ts` which tests the entire flow successfully.
+- Ticket 4 is complete.
+
+## Ticket 5: Chat UI Routing and User Slash Commands
+**Notes:**
+- Implemented `slashPolicies` router in `src/daemon/routers/slash-policies.ts` to process user messages directly.
+- The router acts as an interceptor for `/approve <id>`, `/reject <id> [reason]`, and `/pending` commands.
+- It guarantees strict spoofing prevention by being integrated natively into the router pipeline via `executeRouterPipeline` which strictly evaluates user inputs (`role: 'user'`).
+- In `src/daemon/router.ts`, updated `createPolicyRequest` to generate and append a preview message inside the chat when requests are generated.
+- The preview correctly abbreviates snapshotted file contents to 500 characters and handles failures safely.
+- Wrote full unit test coverage for the preview message and the slash command router spoofing prevention mechanisms.
+- Verified test suite and all quality checks successfully passed (`npm run format:check && npm run lint && npm run check && npm run test`).
+- Ticket 5 is complete.
+
+## Ticket 6: Execution and Feedback Loop
+**Notes:**
+- Implemented execution logic inside `src/daemon/routers/slash-policies.ts` for `/approve`.
+- It dynamically reads the corresponding policy configuration, interpolates all arguments (both policy args and opaque user args) via `interpolateArgs`, and spawns the safe child process wrapper (`executeSafe`).
+- Integrated automated system log messages. Upon resolving the request (approving or rejecting), a `CommandLogMessage` is constructed and injected into the target chat via `appendMessage` so the agent receives the feedback (`stdout`/`stderr` for approvals, rejection reason for rejections).
+- Fixed unused variable lint error and unexpected any warnings in `src/daemon/router-policy-request.test.ts`.
+- Added complete coverage unit tests for the `/approve` and `/reject` flows within `src/daemon/routers/slash-policies.test.ts`.
+- All checks (`npm run format:check && npm run lint && npm run check && npm run test`) pass. Ticket 6 is complete.
+
+## Ticket 8: Policy Utils Improvements
+**Notes:**
+- Exported `MAX_SNAPSHOT_SIZE` constant (5MB) in `src/daemon/policy-utils.ts` and enforced its usage.
+- Refactored `createSnapshot` to receive `agentDir` instead of `workspaceRoot`.
+- Enforced strict symlink rejection by replacing `fs.realpath` with `fs.lstat` during snapshot creation, rejecting any symlinks to avoid TOCTOU attacks.
+- Modified the snapshot logic to guarantee unique filenames by leveraging `fs.constants.COPYFILE_EXCL` within a retry loop to prevent silent overwrites.
+- Updated `PolicyRequestService` and the `createPolicyRequest` router TRPC procedure to retrieve and pass `agentDir`.
+- Fully updated and expanded `policy-utils.test.ts` to assert against symlink rejection and new size limit constants.
+- Successfully ran all tests, including formatting, linting, type checks, and full unit test suites. Ticket 8 is complete.
+
+## Ticket 9: Policy Request Metadata & Validation Enhancements
+**Notes:**
+- Updated request ID generation to use a 3-character random alphanumeric string using `crypto.randomBytes`.
+- Added `chatId` and `agentId` to `PolicyRequest` and properly populated them inside `createRequest` via `src/daemon/router.ts`.
+- Implemented `PolicyRequestSchema` utilizing Zod within `request-store.ts` to validate disk reads dynamically.
+- Handled mock tests properly in `policy-request-service.test.ts`, `router-policy-request.test.ts`, and `request-store.test.ts` adapting to the new metadata fields.
+- Successfully executed formatting, linting, unit tests, and integration tests (`npm run format`, `npm run lint:fix`, `npm run check`, `npm run test`).
+- Ticket 9 is complete.
+
+## Ticket 10: Router State & Configuration Fixes
+**Notes:**
+- Updated `src/daemon/routers.ts` to execute `slash-policies` dynamically as part of the router pipeline loop, removing hardcoded top-level logic.
+- Extended `RouterState` interface in `src/daemon/routers/types.ts` to explicitly include `messageId` tracking the user's incoming message ID.
+- Passed `messageId` properly down to the state configuration within `src/daemon/message.ts` via `getInitialRouterState` and `handleUserMessage`.
+- Modified `src/daemon/routers/slash-policies.ts` so that `/approve`, `/reject`, and error flows no longer force an abrupt `action: 'stop'`. 
+- Ensured errors update `state.reply` with `state.message` cleared, while correct executions update `state.message` safely.
+- Validated `req.chatId` matches the incoming request context to prevent unauthorized cross-chat executions.
+- Updated all unit tests across the test suite to include mock `messageId` and adapted the modified assertions for success and error behaviors.
+- All code checks format, lint, tests compiled correctly and successfully passed without exceptions.
+- Ticket 10 is complete.
+
+## Ticket 11: CLI Commands Relocation
+**Notes:**
+- Relocated `request` and `requests` commands from `src/cli/index.ts` to `src/cli/lite.ts`.
+- Deleted `src/cli/commands/request.ts`.
+- Updated `request` and `requests` logic to use `createTRPCClient` configured in `clawmini-lite` via `CLAW_API_URL` and `CLAW_API_TOKEN` instead of using the local Unix Socket daemon client.
+- Updated `src/cli/e2e/requests.test.ts` to test against the exported `clawmini-lite` client by starting the daemon with an API server enabled and obtaining an API token via a mock `env-dumper` agent.
+- Resolved a path validation security error in `requests.test.ts` by ensuring `dummy.txt` test files correctly live inside the mock agent's directory, conforming to `policy-utils.ts` security limits from Ticket 8.
+- Ran formatting, lint checks, type checks, and tests successfully (`npm run format && npm run lint:fix && npm run check && npm run test`).
+- Ticket 11 is complete.

package/docs/15_sandbox_policies/notes.md

@@ -0,0 +1,33 @@
+# Sandbox Policies Research Notes
+
+## Current State
+- The product (clawmini/Gemini CLI) currently has a daemon that manages chats, messages, agents, and routing.
+- Adapters exist for Discord and Web UI.
+- CLI handles various commands: agents, chats, environments, jobs, messages.
+- There is currently no `sandbox` command in the CLI.
+
+## Feature Requirements
+- A `sandbox` CLI available to the agent inside its restricted environment.
+- The agent uses this CLI to request user approval for "sensitive actions" that require elevated privileges or network access.
+- Requests are asynchronous. AI agents don't block, but scripts/workflows could.
+- Examples of actions: 
+  - Move files to a read-only network-enabled directory.
+  - Send an email.
+- The system must capture/snapshot any files related to the request at the time it is made, storing them safely outside the sandbox to prevent tampering while waiting for approval.
+- User needs a way to register new commands/actions easily.
+- Support for callbacks when the user approves/rejects a request (to notify the agent or trigger a workflow).
+
+## Ambiguities / Open Questions
+- Where is the approval surfaced to the user? (Web UI, CLI, Discord?)
+- How are actions configured? (YAML, TS, JSON?)
+- Where do callbacks execute? (Inside sandbox or outside on host?)
+- How does the snapshot mechanism identify which files to capture? (Does the action definition specify file arguments?)
+
+## PR #71 Feedback Notes
+- **Constants:** Move max snapshot size limit to a constant.
+- **Security:** Ensure snapshots resolve to the *agent's directory*, not just the workspace root. Do not follow symlinks (reject them immediately with lstat). Ensure the generated snapshot filename does not already exist.
+- **Router Configuration:** The `slash-policies` router must be an optional router in `init.ts` and loaded dynamically via the pipeline like other routers, not hardcoded.
+- **Router State Handling:** Do not use `action: 'stop'` on `/approve` or `/reject` or error cases, as that kills running processes. Instead, use `{ message: '...' }` to update the message the agent sees, and empty message with `reply` for user errors. Include `messageId` for replies.
+- **Request Metadata & Validation:** Use shorter, typing-friendly IDs for requests instead of UUIDs. Save `chatId` and `agentId` with the request. Validate the chat ID matches when approving/rejecting. Add Zod validation to `request-store.ts` when loading from disk.
+- **Code Cleanup:** Remove inline `await import(...)` in `src/daemon/router.ts` and move them to top-level imports.
+- **CLI Commands:** The `request` and `requests` commands should be moved to `src/cli/lite.ts` so they are accessible by the agent.