clawmini 0.0.1

package/docs/15_sandbox_policies/prd.md

@@ -0,0 +1,163 @@
+# Product Requirements Document: Sandbox Policies
+
+## Vision
+To provide a secure, extensible framework that empowers AI agents to request and execute sensitive or network-dependent operations safely from within a restricted sandbox. By enabling asynchronous, user-approved requests, agents can seamlessly integrate privileged tasks into their workflows without compromising system integrity.
+
+## Product/Market Background
+AI agents often operate within highly restricted sandbox environments to prevent unintended destructive actions or unauthorized network communication. However, this safety comes at the cost of utility; an agent might deduce a solution that requires network access (e.g., sending an email or moving a file to a networked read-only volume) but is unable to act on it. By introducing a formal "request-and-approve" policy workflow, users retain full control via a familiar chat interface, while agents gain the ability to perform complex, privileged tasks.
+
+## Use Cases
+
+### 1. Moving Files to a Network-Enabled Directory
+An agent needs to compile or transfer a file into a read-only area accessible by network-enabled host commands (e.g., `/home/users/has-network`). The agent generates the file and requests permission to move it. The user reviews the request and approves the move. (Note: Binaries are generally not supported for these workflows).
+
+### 2. Sending an Email
+An agent compiles a status report and wants to email it to stakeholders. It uses the CLI to request permission to send the email, explicitly passing the file payload. The user previews the requested action in their chat UI and approves the action, which executes safely.
+
+### 3. Agent Workflow Orchestration
+An automated script inside the sandbox coordinates a multi-step process. It makes an approval request via the CLI, which returns immediately. The agent relies on an automatically injected chat message from the daemon to know when the request is approved or rejected before proceeding with the next steps in its conversation.
+
+## Inspirational Flow Example
+
+The following scenario illustrates an end-to-end interaction using this feature:
+
+1. **Discovery:** The user tells the LLM about a new capability. The LLM calls `clawmini requests list` to see what is available, along with descriptions.
+2. **Schema Generation:** The LLM then calls `clawmini request send-email --help` to execute the underlying command with `--help` and read its output to learn about the expected arguments.
+3. **Execution Request:** On a user's request, the LLM initiates the action. It explicitly tags a file for snapshotting and passes the rest of the arguments opaquely:
+   `clawmini request send-email --file body_txt=./body.txt -- --to foo@bar.com --subject hi --body "{{body_txt}}"`
+4. **Agent Acknowledgment:** The CLI command returns immediately, outputting: *"Submitted request (ID: 32). You will get a message in the chat if the user approves or rejects."* The daemon stores the request on disk to survive restarts.
+5. **User Preview & Decision:** The user sees a message in their chat interface: *"Request #32: Agent wants to run `send-email` with args: `--to foo@bar.com --subject hi --body /tmp/snapshot/.../body.txt`... use `/approve 32` or `/reject 32`..."* The preview also includes the contents of the file, abbreviated to ~500 characters (or up to ~2000 characters total across multiple files), providing the user with immediate context for what is being sent.
+6. **Resolution:** The user responds with `/reject 32 make it more formal`. (The system verifies this command originated from the user, not the agent).
+7. **Agent Feedback Loop:** The daemon automatically injects a message into the active chat session: `[Request 32] User rejected with message: make it more formal`. The agent can then adjust its inputs and try again.
+
+## Proposed Experience & CLI Design
+
+### Registration (JSON Configuration)
+Users will register new commands in a concise JSON configuration file (e.g., `policies.json`). The framework adopts a **"Dumb Pipes, Smart Endpoints"** philosophy. The configuration avoids complex argument parsing. Instead, it merely provides a description and points to an executable wrapper script. If users want to restrict the flags an agent can use, they enforce those restrictions within their wrapper script. When the agent requests help for a command, the framework executes the wrapper script with `--help` and returns the output to the agent.
+
+```json
+{
+  "actions": {
+    "promote-file": {
+      "description": "Move a file to the network-enabled read-only area.",
+      "execute": {
+        "environment": "host",
+        "command": "./scripts/promote-file.sh"
+      }
+    },
+    "send-email": {
+      "description": "Send an email.",
+      "execute": {
+        "environment": "sandbox",
+        "command": "./scripts/send-email-wrapper.py"
+      }
+    }
+  }
+}
+```
+
+### Security & Sanitization Strategy
+
+To ensure robust security against command injection, path traversal, and race conditions, the system employs the following mechanisms:
+
+1. **Direct Exec Arrays (No Shell Injection):** The system completely bypasses shell string concatenation. The daemon executes commands directly via an OS-level exec array (e.g., `spawn('script.sh', ['--to', 'admin@foo.com'])`). This treats all arguments as pure literal data, making classic shell injection (like passing `&& rm -rf /`) impossible.
+2. **Explicit Named Variable Map for Files:** The daemon does not attempt to parse or guess which arguments are file paths. Instead, the LLM must explicitly declare files using `clawmini` flags (e.g., `--file var_name=./path`). The daemon validates and snapshots the file, then safely interpolates the absolute path of the snapshot into the opaque arguments array (replacing `{{var_name}}`). This provides structural safety without brittle naming conventions.
+3. **Immediate Snapshotting & TOCTOU Prevention:** To prevent Time-of-Check to Time-of-Use (TOCTOU) race conditions involving symlinks, the daemon resolves the real path (equivalent to `O_NOFOLLOW` and `realpath`) and creates the secure snapshot *immediately* upon receiving the request, before the user is ever prompted. The user reviews and approves the exact snapshot, not the live file, guaranteeing that background processes in the sandbox cannot swap the file during the approval window.
+
+### Clawmini CLI (Agent View)
+
+The agent interacts with the `clawmini-lite` CLI using the POSIX standard `--` separator. Everything before `--` is processed by the daemon for security routing and snapshotting. Everything after `--` is passed opaquely to the target script.
+
+**1. Discovery**
+- `clawmini-lite requests list`: Outputs all registered policies and their descriptions.
+- `clawmini-lite request <cmd> --help`: Executes the underlying command defined in the JSON configuration with the `--help` flag and outputs the result.
+
+**2. Making a Request (Named Variable Mapping)**
+```bash
+# Agent explicitly maps body_txt to a sandbox file, then uses it in the opaque args
+clawmini-lite request send-email \
+  --file body_txt=./report.txt \
+  -- \
+  --to admin@example.com --subject "Daily Report" --body "{{body_txt}}"
+```
+
+Behind the scenes:
+1. `clawmini-lite` parses `--file body_txt=./report.txt`.
+2. The daemon verifies the path is inside the agent's directory, rejects it if it's a symlink, and snapshots it to a secure location (e.g., `/tmp/snapshots/123_report.txt`).
+3. The daemon takes the opaque arguments `["--to", "admin@example.com", "--subject", "Daily Report", "--body", "{{body_txt}}"]` and performs a precise string replacement on array elements to swap `{{body_txt}}` with the safe snapshot path.
+4. The CLI returns immediately with the pending Request ID and exits.
+5. The daemon persists the request and routes the preview to the user's chat UI.
+6. Upon approval, the daemon `spawn`s the script with the safe argument array.
+
+**3. Asynchronous Resolution & Automatic Messaging**
+When the agent makes a request, the CLI immediately returns the Request ID and exits. The daemon tracks the request. Once the user resolves the request (approves or rejects), the daemon *automatically* injects a system message back into the active chat session. This message includes the "Approved/Rejected" status, any `stdout`/`stderr` from the executed command, and any feedback strings provided by the user upon rejection.
+
+### User Interface & Interactions
+
+All requests are routed to the user's primary chat UI for review. To prevent unauthorized execution, the system relies on specific slash commands that must originate directly from the user.
+
+When a request is made, the daemon presents the user with a preview message (e.g., "Request #32: Agent wants to run `send-email` with args..."). The preview displays the snapshot paths and includes abbreviated file contents (~500 chars per file, up to ~2000 chars total) so the user can see exactly what data is being requested.
+
+Users can respond with:
+- `/approve <id>`: Approve and execute the request.
+- `/reject <id> [reason]`: Reject the request, optionally providing a natural language reason (e.g., `/reject 32 tone needs to be more formal`) so the agent can learn and retry.
+- `/pending`: View a summarized list of all active pending requests.
+
+## Requirements
+
+### Core Requirements
+1. **CLI Extensibility:** Agents must have access to a `clawmini` CLI binary inside their environment.
+2. **Configuration:** Users define permissible actions via a centralized JSON configuration providing a `command` and `description` string. The framework acts as a "dumb pipe" for arguments.
+3. **Explicit File Templating & Snapshotting:** Agents declare files using `--file name=path` prior to the `--` argument separator. The daemon strictly bounds the path to the agent's directory, creates a secure snapshot (rejecting symlinks entirely to prevent TOCTOU), and replaces `{{name}}` in the opaque arguments with the snapshot's absolute path. Enforce strict file size limits on snapshots (e.g., max 5MB).
+4. **Chat Integration & Previews:** Requests must be routed to the user's Chat UI, showing the requested command, the snapshot paths, the exact opaque arguments, and abbreviated file contents to aid review.
+5. **Execution Engine:** Approved actions must execute safely using direct OS exec arrays (`spawn`), not shell execution.
+6. **Automatic Callbacks:** The daemon must automatically inject a message into the active chat session when a request is approved (along with command output) or rejected (along with user feedback).
+7. **State Management:** Request state should be saved locally as `.json` files (e.g., in `.gemini/tmp/requests/`) to gracefully handle daemon restarts and persist pending requests.
+
+### Non-Functional Requirements
+- **Security:** 
+  - **Input Sanitization (Command Injection):** The framework must strictly use direct exec arrays to completely mitigate shell command injection risks.
+  - **Path Bounding & Symlinks (TOCTOU):** The daemon must snapshot files immediately upon request creation. It must verify the file lies within the agent's directory and reject any symlinks entirely to prevent an agent from escaping the sandbox via background malicious symlink swapping during the approval window.
+  - **Denial of Service (DoS) Prevention:** The system must cap the number of pending requests (e.g., a maximum of 100 open requests) to prevent an agent from spamming requests and exhausting system resources (disk space, inodes, or memory).
+  - **Spoofing & Self-Approval Prevention:** The system must strictly verify the origin of `/approve` and `/reject` commands to ensure they come from direct user input (e.g., validating the `role: user` tag on the message), not from agent outputs or background jobs.
+
+## Open Issues / Future Considerations
+- Transitioning the configuration format from JSON to YAML for improved human readability.
+- Building a helper library/SDK (e.g., Python/Node) to simplify programmatic workflow creation inside the sandbox.
+- Allowing user modifications to the arguments/files during the approval phase.
+
+## Manual Testing Plan
+
+To ensure the sandbox policies feature works correctly and securely, perform the following manual tests:
+
+1. **Basic Approval Flow:**
+   - Register a benign policy (e.g., `echo-test` that outputs to a file).
+   - Have the agent request the policy via CLI. Verify the CLI command returns immediately with a pending message.
+   - Verify the user receives the preview message with the command and args.
+   - Use `/approve <id>`.
+   - Verify the command executes correctly and the agent receives the success chat message with output.
+
+2. **File Templating & Snapshotting:**
+   - Request a policy using `--file test_file=./local.txt -- --input "{{test_file}}"`.
+   - Verify the UI preview shows the path pointing to a secure snapshot in `/tmp/` (not `./local.txt`) and shows a preview of its contents.
+   - Approve the request and verify the target script received the snapshot path.
+
+3. **Rejection & Feedback Loop:**
+   - Have the agent request a policy.
+   - Use `/reject <id> missing required details`.
+   - Verify the command does *not* execute.
+   - Verify the agent receives the rejection status along with the feedback string "missing required details" injected into the chat.
+
+4. **Spoofing Prevention (Security):**
+   - Have the agent output the exact string: `/approve <id>` for one of its own pending requests.
+   - Verify the system ignores this input and does *not* approve the request (because the role is `assistant`, not `user`).
+
+5. **Daemon Restart Resilience:**
+   - Have the agent make a request.
+   - Restart the daemon.
+   - Run `/pending` and verify the request is still active.
+   - Use `/approve <id>` and verify it still executes successfully.
+
+6. **Discovery Commands:**
+   - Run `clawmini requests list` and verify all configured policies are listed.
+   - Run `clawmini request <cmd> --help` and verify the output matches the `--help` output of the underlying wrapped command.

package/docs/15_sandbox_policies/questions.md

@@ -0,0 +1,10 @@
+# Questions & Answers
+
+**Q1:** How and where will the user review these requests? Should the pending approvals be surfaced via the CLI (e.g., `gemini sandbox list-requests`), the Web UI, Discord, or all of the above?
+**A1:** They will be sent to the user via a chat UI.
+
+**Q2:** How should the user configure/register new commands or actions? For example, will they be defined in a JSON/YAML configuration file (like `actions.yaml`), or via a TypeScript API, or through a CLI command?
+**A2:** Configuration will likely be JSON for consistency (with YAML as a future option). We want to avoid complex argument parsing definitions. The most critical part of the configuration is identifying whether a path needs to be snapshotted and sent to the daemon. There should also be a file size limit for snapshot transfers.
+
+**Q3:** When a user approves or rejects an action, where and how should the callback execute? For instance, does it run a local script natively on the host, or does it execute a command back inside the sandbox, or simply send an event/message back to the agent in the chat?
+**A3:** If approved, the action executes a command configured by the user, which can run either in the agent's environment or on the host. Upon completion or rejection, a callback is triggered. This callback can either be a command executed in the agent's environment or a message sent directly to the agent.

package/docs/15_sandbox_policies/tickets.md

@@ -0,0 +1,196 @@
+# Sandbox Policies Tickets
+
+This document breaks down the implementation of the Sandbox Policies feature into ordered, self-contained milestones.
+
+## Ticket 1: Core Configuration and Request State Management
+
+**Description:** Define the data structures for policy configurations and requests, and implement persistent state management for requests so they survive daemon restarts.
+**Tasks:**
+
+- Define TypeScript types for `policies.json` configuration.
+- Define types for Request states (`Pending`, `Approved`, `Rejected`).
+- Implement a `RequestStore` service that saves, loads, and lists requests from a persistent directory (e.g., `.gemini/tmp/requests/`).
+  **Verification:**
+- Write unit tests for `RequestStore` verifying save, load, list operations, and graceful handling of corrupted files.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 2: File Snapshotting and Security Layer
+
+**Description:** Implement the core security mechanisms to prevent TOCTOU attacks and command injection.
+**Tasks:**
+
+- Implement a secure file snapshotting utility that takes a requested file path, resolves its realpath (preventing symlink attacks), verifies it is within the allowed sandbox/workspace, and copies it to a secure temporary directory.
+- Implement argument interpolation logic to safely replace named variables (e.g., `{{file_var}}`) in an arguments array with the absolute paths of the generated snapshots.
+- Create a safe execution wrapper using `spawn` (direct exec array, no shell concatenation).
+  **Verification:**
+- Write unit tests for the snapshotting utility, specifically testing path traversal attempts and symlink resolution.
+- Write unit tests for the argument interpolation logic.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 3: Daemon Request Service
+
+**Description:** Build the central service within the daemon that processes incoming requests, utilizing the security layer and state management.
+**Tasks:**
+
+- Create a `PolicyRequestService` that receives raw request data (command name, file mappings, opaque args).
+- Integrate the file snapshotting and argument interpolation into the service.
+- Enforce the maximum limit of pending requests (e.g., max 100 open requests) to prevent DoS.
+- Store the resulting pending request using the `RequestStore`.
+  **Verification:**
+- Write unit tests for `PolicyRequestService`, ensuring it correctly coordinates snapshotting and storage, and properly rejects requests when the pending limit is reached.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 4: CLI Agent Commands
+
+**Description:** Expose the sandbox policies to the agent via the `clawmini` CLI.
+**Tasks:**
+
+- Implement `clawmini requests list` to fetch and display available policies and descriptions.
+- Implement `clawmini request <cmd> --help` to execute the underlying command with `--help` and print the output.
+- Implement `clawmini request <cmd> [--file name=path...] -- [args...]` to parse inputs and submit the request to the `PolicyRequestService` in the daemon, returning the Request ID immediately.
+  **Verification:**
+- Write tests for the CLI commands, verifying correct argument parsing (especially the `--` separator) and interaction with the daemon service.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 5: Chat UI Routing and User Slash Commands
+
+**Description:** Surface requests to the user for review and provide commands to act on them.
+**Tasks:**
+
+- Implement logic to intercept new pending requests and route a preview message to the Chat UI.
+- The preview message must include the command, the opaque arguments, and abbreviated contents (~500 chars) of any snapshotted files.
+- Implement user slash commands: `/approve <id>`, `/reject <id> [reason]`, and `/pending`.
+- Implement strict spoofing prevention: ensure these commands only trigger if the message originates from the user (`role: user`).
+  **Verification:**
+- Write unit tests for the preview message generation (ensuring files are abbreviated correctly).
+- Write tests for the slash commands, explicitly testing the spoofing prevention mechanism.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 6: Execution and Feedback Loop
+
+**Description:** Complete the workflow by executing approved requests and notifying the agent of the outcome.
+**Tasks:**
+
+- Connect the `/approve` command to the safe execution wrapper (`spawn`) implemented in Ticket 2.
+- Implement an automatic feedback mechanism that injects a system/tool message back into the active chat session upon resolution.
+- For approvals: include the `stdout`/`stderr` of the executed command.
+- For rejections: include the user's rejection reason (if provided).
+  **Verification:**
+- Write integration tests simulating the full end-to-end flow: request creation -> user approval -> execution -> feedback injection.
+- Write integration tests for the rejection flow.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 7: Code Review Fixes
+
+**Description:** Address code review feedback to improve performance and code quality.
+**Tasks:**
+
+- **High Priority:** In `src/daemon/routers/slash-policies.ts`, use `store.load(id)` instead of `store.list().find()` to fetch single requests in `/approve` and `/reject`, avoiding O(N) file reads.
+- **Medium Priority:** In `src/daemon/request-store.ts`, extract the duplicated `ENOENT` error checking logic into a reusable helper function to adhere to DRY principles.
+- **Low Priority:** In `src/cli/commands/request.ts`, simplify the opaque arguments fallback logic for argument extraction.
+  **Verification:**
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 8: Policy Utils Improvements
+
+**Description:** Address security and maintainability feedback for snapshotting utilities.
+**Tasks:**
+
+- Define the maximum snapshot size (5MB) as a named constant in `src/daemon/policy-utils.ts`.
+- Update `createSnapshot` to receive the agent's directory instead of the workspace root, and strictly verify the file is within the agent's directory.
+- Refactor snapshot generation to reject symlinks completely using `fs.lstat` instead of resolving them to prevent TOCTOU attacks.
+- Ensure the newly generated unique snapshot filename does not already exist before copying.
+  **Verification:**
+- Update and run unit tests for `policy-utils.ts` to assert symlinks are rejected and the agent directory is respected.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 9: Policy Request Metadata & Validation Enhancements
+
+**Description:** Improve request ID generation and data integrity.
+**Tasks:**
+
+- Update request ID generation to use a short, typing-friendly string (e.g., 3 random alphanumeric characters) instead of UUIDs.
+- Update `PolicyRequest` to include `chatId` and `agentId`, and populate these fields upon request creation in `policy-request-service.ts`.
+- Update `request-store.ts` to validate the incoming JSON schema using Zod when loading requests from disk.
+  **Verification:**
+- Update unit tests for `policy-request-service.ts` and `request-store.ts` to assert ID format, metadata presence, and Zod validation.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 10: Router State & Configuration Fixes
+
+**Description:** Fix router pipeline handling to ensure processes are not incorrectly killed and that agents receive the correct feedback messages.
+**Tasks:**
+
+- Modify `src/daemon/routers.ts` to make `slash-policies` a dynamically loaded router (added via config) rather than a hardcoded step, and remove inline `await import(...)` statements by moving them to top-level imports.
+- Update `slash-policies.ts` to ensure `action: 'stop'` is no longer returned for `/approve`, `/reject`, or error cases.
+- For approvals/rejections, update the `state.message` so the agent receives the correct confirmation/output string, and return it without stopping the pipeline.
+- For user errors (e.g., missing ID), set `state.reply` and return an empty `message`.
+- Ensure `appendMessage` is provided with the correct `replyTo` parameter targeting the user's incoming message ID.
+- During approval/rejection, verify that the `req.chatId` matches the current `state.chatId`.
+  **Verification:**
+- Run integration tests simulating the new router behavior, verifying the agent message generation and that the pipeline does not stop.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 11: CLI Commands Relocation
+
+**Description:** Move the sandbox request commands to the lite CLI so they are accessible by the agent.
+**Tasks:**
+
+- Relocate `requestCmd` and `requestsCmd` from `src/cli/index.ts` to `src/cli/lite.ts`.
+  **Verification:**
+- Manually run `clawmini-lite --help` to verify the `request` commands are present.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+  **Status:** completed
+
+## Ticket 12: Router Slash Policies DRY Refactoring
+
+**Priority:** High
+**Description:** Address DRY violation in `src/daemon/routers/slash-policies.ts`.
+**Tasks:**
+- Extract the common request loading and validation logic shared between the `/approve` and `/reject` branches into a helper function (e.g., `loadAndValidateRequest`).
+**Verification:**
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** completed
+
+## Ticket 13: Secure and Collision-Resistant Request ID Generation
+
+**Priority:** High
+**Description:** Improve the Request ID generation to be more secure and resistant to collisions in `src/daemon/policy-request-service.ts`.
+**Tasks:**
+- Replace `randomBytes(2).toString('hex').slice(0, 3)` with a slightly longer secure string (e.g., 6 characters) or check against existing IDs in the `RequestStore` to ensure uniqueness before assigning the ID.
+**Verification:**
+- Update tests for `policy-request-service.ts`.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** completed
+
+## Ticket 14: Extract Preview Message Formatting
+
+**Priority:** Medium
+**Description:** Improve Separation of Concerns in `src/daemon/router.ts` by extracting the `previewContent` generation logic.
+**Tasks:**
+- Move the inline string formatting and dynamic file reading used to generate the preview message in `createPolicyRequest` to a new helper function `generateRequestPreview` in `src/daemon/policy-utils.ts`.
+- Import `node:fs/promises` properly rather than dynamically inside the loop if moving to a utility file.
+**Verification:**
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** completed
+
+## Ticket 15: Modernize String Replacement
+
+**Priority:** Low
+**Description:** Modernize the argument interpolation string replacement in `src/daemon/policy-utils.ts`.
+**Tasks:**
+- Refactor `interpolateArgs` to use `replaceAll(variable, snapshotPath)` instead of `.split(variable).join(snapshotPath)`.
+**Verification:**
+- Ensure tests still pass.
+- Run `npm run format:check && npm run lint && npm run check && npm run test`.
+**Status:** completed

package/docs/CHECKS.md

@@ -0,0 +1,9 @@
+# Automated Checks
+
+Run the following command to ensure all code quality checks and tests pass after making changes to the codebase:
+
+```bash
+npm run format:check && npm run lint && npm run check && npm run test
+```
+
+*Note: You can also use `npm run format` and `npm run lint:fix` to automatically fix formatting and linting issues before running these checks.*

package/docs/guides/discord_adapter_setup.md

@@ -0,0 +1,69 @@
+# Discord Adapter Setup Guide
+
+This guide describes how to set up and configure the Discord adapter for Clawmini.
+
+## Prerequisites
+
+- A Discord account.
+- A Clawmini daemon running locally (the adapter communicates with it via TRPC over Unix sockets).
+
+## Step 1: Create a Discord Bot
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications).
+2. Click **New Application**.
+3. Give your application a name (e.g., "Clawmini-Bot") and click **Create**.
+4. In the left sidebar, click **Bot**.
+5. Under **Bot Token**, click **Reset Token** (or **Copy Token**) to retrieve your bot's token. **Save this token securely; you will need it later.**
+6. Scroll down to the **Privileged Gateway Intents** section.
+7. Enable **Message Content Intent**. This is required for the bot to read DM messages.
+8. Click **Save Changes**.
+
+## Step 2: Get Your Discord User ID
+
+The adapter only responds to messages from a single authorized user. To find your Discord User ID:
+
+1. Open Discord and go to **User Settings** (the gear icon at the bottom left).
+2. Go to **Advanced**.
+3. Enable **Developer Mode**.
+4. Right-click on your profile picture or username in a server or DM and select **Copy User ID**.
+
+## Step 3: Invite the Bot to Your Direct Messages
+
+Discord bots cannot initiate a DM conversation with a user unless the user has first interacted with the bot.
+
+1. In the Discord Developer Portal, go to **OAuth2** -> **URL Generator**.
+2. Select the `bot` scope.
+3. If prompted for an **Installation Method**, ensure you select **Guild Install**. The `bot` scope is not valid for "User Install" and will cause an error.
+4. Select the `Send Messages` and `Read Message History` permissions under **Bot Permissions**.
+5. Copy the generated URL and paste it into your browser.
+6. Select your personal server (or any server you share with the bot) to invite the bot.
+7. Once the bot is in a shared server, you can right-click the bot and select **Message** to start a DM conversation.
+
+## Step 4: Configure the Adapter
+
+The adapter requires a configuration file with your bot token and user ID. You can generate a template configuration file by running the `init` command:
+
+```bash
+npx clawmini-adapter-discord init
+```
+
+This will create a `config.json` file at `.clawmini/adapters/discord/config.json`. Open this file and replace the placeholders with your actual bot token and user ID:
+
+```json
+{
+  "botToken": "YOUR_DISCORD_BOT_TOKEN",
+  "authorizedUserId": "YOUR_DISCORD_USER_ID",
+  "chatId": "default"
+}
+```
+*(Note: `chatId` defaults to `"default"`. You can change this if you want the bot to associate with a different chat).*
+
+## Step 5: Start the Adapter
+
+Ensure the Clawmini daemon is running, then start the Discord adapter:
+
+```bash
+npx clawmini-adapter-discord
+```
+
+The adapter will now forward authorized Discord DM messages to your Clawmini daemon and vice versa.

package/docs/guides/sandbox_policies.md

@@ -0,0 +1,76 @@
+# Sandbox Policies Guide
+
+The Sandbox Policies feature provides a secure framework for AI agents operating within restricted sandbox environments to request and execute sensitive or network-dependent operations. Using a formal "request-and-approve" workflow, users retain full control via their chat interface while agents gain the ability to perform complex, privileged tasks like sending emails or promoting files to external systems.
+
+## Registering a Policy
+
+Policies are configured centrally in a JSON file located at `.clawmini/policies.json`. This configuration maps an easy-to-use policy command name to the actual script or binary you want to run when the request is approved. 
+
+The framework treats the command execution as a "dumb pipe". It executes the specified script using a secure execution wrapper (bypassing the shell to prevent injection attacks) and interpolates safe, verified file paths.
+
+### Example Configuration
+
+Create or update `.clawmini/policies.json` in your workspace root:
+
+```json
+{
+  "policies": {
+    "send-email": {
+      "description": "Sends an email using the specified body file.",
+      "command": "./.clawmini/policy-scripts/send-email.sh",
+      "args": ["--agent-email"],
+      "allowHelp": true
+    }
+  }
+}
+```
+
+In this example, the `send-email` policy uses a wrapper script located at `./.clawmini/policy-scripts/send-email.sh`. Any arguments defined in `args` will be prepended to the arguments the agent passes. The `allowHelp` flag must be set to `true` to enable the `--help` discovery feature for this policy.
+
+## Agent Access via clawmini-lite
+
+Agents running within their environment can interact with the Policies feature using the `clawmini-lite` CLI.
+
+1. **Discovery:**
+   Agents can view available policies and their descriptions:
+   ```bash
+   clawmini-lite requests list
+   ```
+
+2. **Help Documentation:**
+   If a policy is configured with `"allowHelp": true`, agents can query it for help. This securely passes the `--help` flag to the underlying wrapper command and returns the output to the agent:
+   ```bash
+   clawmini-lite request send-email --help
+   ```
+   If `"allowHelp"` is missing or set to `false`, the agent will receive an error stating that `--help` is not supported.
+
+3. **Submitting a Request:**
+   Agents can submit a request to run a policy. The `--file` flag maps a file within the agent's sandbox to a variable name, which can be interpolated into the opaque arguments using `{{variable_name}}`. This ensures files are securely snapshotted to prevent TOCTOU (Time-of-Check to Time-of-Use) attacks.
+   ```bash
+   clawmini-lite request send-email --file body_txt=./report.txt -- --to admin@example.com --subject "Daily Report" --body "{{body_txt}}"
+   ```
+   The CLI returns a request ID immediately without blocking.
+
+## User Interaction
+
+When an agent creates a request, the daemon intercepts it and sends a preview message to your chat session. This message includes the command, the requested arguments, and a truncated preview of the files involved.
+
+You can then review and interact with the pending request using the following slash commands in your chat:
+
+- **List Pending Requests:**
+  ```text
+  /pending
+  ```
+  *Lists all active pending requests that need review.*
+
+- **Approve a Request:**
+  ```text
+  /approve <request_id>
+  ```
+  *Approves the request. The configured script executes securely, and the STDOUT/STDERR results are automatically sent back to the agent in the chat.*
+
+- **Reject a Request:**
+  ```text
+  /reject <request_id> [reason]
+  ```
+  *Rejects the request. You can provide an optional natural language reason (e.g., `/reject 123 Tone needs to be more formal`) to help the agent correct its output and try again.*

package/eslint.config.js

@@ -0,0 +1,47 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import { defineConfig } from 'eslint/config';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+export default defineConfig([
+  {
+    ignores: [
+      'dist',
+      'node_modules',
+      '.cladding',
+      '.clawmini',
+      '**/.svelte-kit',
+      '**/build',
+      'web/.svelte-kit',
+      'test-workspace*',
+    ],
+  },
+  {
+    files: ['**/*.{js,mjs,cjs,ts,mts,cts}'],
+    plugins: { js },
+    extends: ['js/recommended'],
+    languageOptions: {
+      globals: globals.browser,
+      parserOptions: {
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  tseslint.configs.recommended,
+  // Your custom rules
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      'max-lines': ['error', { max: 300, skipBlankLines: true, skipComments: true }],
+    },
+  },
+  {
+    files: ['**/*.test.ts', '**/*.spec.ts'],
+    rules: {
+      'max-lines': 'off',
+    },
+  },
+  eslintConfigPrettier,
+]);

package/napkin.md

@@ -0,0 +1,21 @@
+- **When you need to create or write multiline content to files**, use the native `write_file` tool instead of heredocs (`cat << EOF`) in `run_shell_command` to avoid whitespace/newline truncation or escaping issues.
+- **When you need `fetch`, `Response`, or `Headers`**, rely exclusively on global Web APIs (`globalThis.Request`, `globalThis.Response`, `globalThis.Headers`) built directly into Node 18+ instead of using `undici` or external polyfills.
+- **When you need to build a custom `fetch` wrapper for tRPC client adapters over UNIX sockets**, define the signature as `(input: string | URL | globalThis.Request, init?: unknown): Promise<globalThis.Response>` to satisfy TypeScript requirements. Note that the `httpLink` adapter still requires a valid `url` property (e.g., `http://localhost`) even if your interceptor ignores it.
+- **When you need to test CLI instances that spin up background daemon processes**, use fully isolated E2E tests with `node:child_process.spawn` pointing to the pre-compiled `dist/cli/index.mjs` entry point.
+- **When you need to run E2E CLI commands**, always run them in an isolated sandbox temporary directory (`cwd: e2eDir`) to prevent polluting the developer workspace with generated files or daemon logs.
+- **When you need to tear down E2E tests**, explicitly run a cleanup command (e.g., `pkill -f "dist/daemon/index.mjs"`) in the `afterAll` hook to prevent zombie daemon processes from persisting.
+- **When testing code that relies on `node:child_process.spawn`** and passing callbacks for side effects, consider mocking `spawn` inside the test and providing a matching mock implementation of your callback directly in the test suite.
+- **When using Zod 4 for Record validation with string keys and string values**, use `z.record(z.string(), z.string())` rather than `z.record(z.string())`, as the newer Zod version requires two arguments for records when explicit types are needed.
+- Updated logMsg construction to map extracted content directly to `content`, and preserve the raw output in `stdout` as per the new `CommandLogMessage` structure.
+- **When building multi-target projects with tsdown and other bundlers (like Vite)**, ensure `tsdown` runs _first_ if `clean: true` is enabled in `tsdown.config.ts`, otherwise it will delete the artifacts output by other tools into the `dist` directory.
+- **When integrating a separate frontend framework directory (like SvelteKit in `web/`) into a root TypeScript project**: Ensure the root `tsconfig.json` uses `exclude` to ignore the directory so its browser-specific globals (like `HTMLElement`) don't fail the Node.js focused root type-check. Instead, use an npm workspace or run the directory's own check script (e.g., `npm run check --prefix web`) alongside the root check.
+- **When adding a frontend directory that relies on Prettier**: Extend the root `package.json` `format` and `format:check` scripts to explicitly include its source paths (e.g., `"web/src/**/*.ts"`) so that the root scripts maintain full codebase coverage.
+- **When managing a separate embedded project (like SvelteKit in `web/`)**: Prefer setting it up as an **npm workspace** (by adding `"workspaces": ["web"]`) in the root `package.json` rather than maintaining duplicate `node_modules` and `package-lock.json` files. This unifies dependency resolution, hoists shared packages, and allows commands to be run from the root using the `-w web` flag (e.g., `npm run check -w web`).
+- **When testing a root project with an embedded frontend workspace (like `web/`)**: Ensure the root project has a `vitest.config.ts` that explicitly excludes the frontend directory (e.g., `exclude: ['web/**']`). This prevents the root Node-based test runner from inappropriately picking up the frontend browser tests and crashing. Chain the root test script to also execute the workspace tests (e.g., `"test": "vitest run && npm run test -w web"`) to execute both environments completely and cleanly.
+- **When creating test files for SvelteKit routes**: Do not prefix the test filename with `+` (e.g., `+page.svelte.spec.ts`). SvelteKit's router may try to interpret it. Always name test files without the `+`, like `page.svelte.spec.ts` for `+page.svelte`.
+- Modified Sidebar.MenuButton in app-sidebar.svelte to use the child snippet and pass props to the anchor tag, resolving the wrapping issue and making the entire line item clickable.\n- Updated layout containers in +layout.svelte and +page.svelte to use 'h-svh' and proper 'flex-col overflow-hidden' behavior to confine scrolling to the message container and pin the chat header/input.
+- Added a 'Debug view' toggle in the chat header, backed by a new Svelte 5 appState singleton. When off (default), logs only display the message content. When on, they show the full command, stdout, and stderr as previously configured.
+- **shadcn-svelte commands:** Always use the `-y` flag when adding a component (e.g., `npx shadcn-svelte@latest add -y <component>`) to bypass the interactive prompt.\n- **Svelte Check:** Always run `npm run check -w web` instead of `npx svelte-check` to run Svelte diagnostics.
+- Added shadcn-svelte dialog for chat creation and replaced native window.prompt.
+- **E2E and Unit Test File Splitting:** When splitting `.test.ts` files, remember that `vi.mock()` must be at the top level of the file where the module is imported. Moving it to a shared setup utility will break mocking in Vitest.\nAlso, when splitting tests that share an environment setup (like E2E tests building dist), ensure tests run sequentially using `fileParallelism: false` in `vitest.config.ts` to prevent race conditions on shared global processes.
+- **E2E Tests Performance Optimization:** To make E2E tests run faster, moved the `npm run build` command out of the repeated E2E file setup and into a Vitest `globalSetup` hook (`src/cli/e2e/global-setup.ts`). Restored `fileParallelism: true` to `vitest.config.ts`, so test files run concurrently in workers while sharing a single initial build output. This dropped test suite execution time from ~50s down to ~18s.