clawmini 0.0.8 → 0.0.9

package/docs/guides/discord_adapter_setup.md

@@ -11,7 +11,7 @@ This guide describes how to set up and configure the Discord adapter for Clawmin
 
 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**.
+3. Give your application a name (e.g., "Clawmini-Bot") and click **Create**. (Optional: Set the App Icon using [this default avatar image](./assets/clawmini-avatar.png)).
 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.

package/docs/guides/google_chat_adapter_setup.md

@@ -34,9 +34,19 @@ This step is optional, but recommended.
 4. Navigate to the Google Chat API configuration page.
 5. Uncheck **Build this Chat app as a Workspace add-on**.
 6. Provide App Information (Name, Avatar URL, Description).
+   * **Avatar URL:** You can use [this default avatar image](./assets/clawmini-avatar.png).
 7. Under **Interactive features**, optionally check **Join spaces and group conversations**.
 8. Under **Connection settings**, select **Cloud Pub/Sub**.
 9. Set the Pub/Sub topic to the topic you created earlier (e.g., `projects/YOUR_PROJECT_ID/topics/chat`).
+10. Under **Slash commands**, click **Add a slash command** to configure the following supported commands (Command IDs can be any unique number, but these are recommended):
+    - **Name:** `/new`, **Command ID:** `1`, **Description:** Clear previous context and start a new conversation thread.
+    - **Name:** `/stop`, **Command ID:** `2`, **Description:** Stop all running commands and drop any queued messages.
+    - **Name:** `/approve`, **Command ID:** `3`, **Description:** Approve a specific pending agent request. (Usage: `/approve [policy_id]`)
+    - **Name:** `/reject`, **Command ID:** `4`, **Description:** Reject a specific pending agent request. (Usage: `/reject [policy_id] [rationale]`)
+    - **Name:** `/pending`, **Command ID:** `5`, **Description:** View any pending permission requests from your agent.
+    - **Name:** `/show`, **Command ID:** `6`, **Description:** Show the debug view.
+    - **Name:** `/hide`, **Command ID:** `7`, **Description:** Hide the debug view.
+    - **Name:** `/debug`, **Command ID:** `8`, **Description:** Toggle the debug view.
 
 ## Step 4: Setup Application Default Credentials (ADC)
 
@@ -143,3 +153,74 @@ By default, the adapter connects to a single chat (the one specified as `chatId`
 4. Alternatively, use `/chat [chat-id]` in that space to map it to an existing Clawmini chat.
 
 _Note: Each Space/DM can only be mapped to one Clawmini chat, and each Clawmini chat can only be mapped to one channel/space across all adapters._
+
+## Advanced Configuration
+
+Once the adapter is running, you can tune how it surfaces agent activity.
+None of this is required for basic use.
+
+### Visibility Settings (`config.json`)
+
+The adapter can publish agent activity — tool calls, subagent updates, policy
+decisions — into a per-turn GChat **thread** anchored on the triggering user
+message, edited in place as events arrive. The final agent reply still lands
+top-level. All settings are optional; defaults are shown.
+
+```json
+{
+  "visibility": {
+    "threads": true,
+    "threadLog": {
+      "maxToolPreview": 400,
+      "maxLogMessageChars": 3500,
+      "editDebounceMs": 1000
+    },
+    "jobs": "silent"
+  }
+}
+```
+
+- `threads` — global kill switch. Set to `false` to drop thread-log
+  activity (tool calls, subagent updates, policy decisions) entirely. The
+  final agent reply still posts top-level; debug-style firehose output is
+  only available via `filters` (e.g. `/show`).
+- `threadLog.maxToolPreview` — per-entry character cap on tool arguments
+  before `…[truncated]`.
+- `threadLog.maxLogMessageChars` — size budget for a single log message;
+  exceeding it rolls over to a fresh message in the same thread.
+- `threadLog.editDebounceMs` — coalescing window for burst activity. Higher
+  values reduce edit calls; lower values feel more live.
+- `jobs` — how cron-triggered (proactive) turns surface:
+  - `'silent'` (default) — the cron prompt is never posted. If the agent
+    replies, that reply becomes the thread anchor; if it stays silent,
+    nothing posts.
+  - `'header'` — a terse `🕒 <jobId>` heartbeat posts top-level and anchors
+    the activity log, making scheduled work visible even when the agent
+    doesn't reply.
+
+### Per-Space Overrides (`state.json`)
+
+The adapter's runtime state lives at
+`.clawmini/adapters/google-chat/state.json`. The `channelChatMap` entry for
+each space supports per-space overrides that take precedence over
+`config.json`:
+
+```json
+{
+  "channelChatMap": {
+    "spaces/AAA": {
+      "chatId": "my-chat",
+      "requireMention": true,
+      "threadsDisabled": true
+    }
+  }
+}
+```
+
+- `requireMention` — per-space mention gate (overrides the global `requireMention`).
+- `threadsDisabled` — when `true`, thread-log activity for this space is
+  dropped (same semantics as the global `visibility.threads: false`, scoped
+  to one space). The final agent reply still posts top-level.
+
+Most entries under `channelChatMap` are written automatically by the adapter
+as users run `/agent` or `/chat` (see [Routing and Creating Chats](#routing-and-creating-chats)); edit the file only to set these overrides.

package/docs/unified-startup/SPEC.md

@@ -0,0 +1,203 @@
+# Unified startup for clawmini
+
+**Status:** brainstorm. Not a decided plan — exploring the design space so we can pick a direction.
+
+## Problem
+
+Starting clawmini today requires three-to-four separate commands:
+
+```bash
+clawmini down && clawmini up            # restart daemon
+clawmini-adapter-discord                # adapter (foreground)
+clawmini-adapter-google-chat            # another adapter (foreground)
+clawmini web                            # web UI (foreground)
+```
+
+Each runs in its own terminal. If you're not tailing terminals, logs end up in `.clawmini/daemon.log` (for the backgrounded daemon) and nowhere for adapters (they go to whatever terminal you launched them in). Finding what went wrong means hopping between terminals or SSH sessions.
+
+Three things feel wrong:
+
+1. **Too many commands** to start a working setup.
+2. **Logs are hard to watch** — daemon logs go to a file you have to know about; adapter logs are scattered across terminals.
+3. **No clean upgrade path.** You can't currently tell a running agent "/update yourself" — there's no orchestrator that knows how to stop-upgrade-restart the full constellation.
+
+The user's goals (in priority order):
+1. One command to start everything, with logs visible by default.
+2. Still be able to run detached / in the background when wanted.
+3. Future: expose an "update" operation to the agent that safely rolls over the whole stack after an `npm install -g clawmini@latest`.
+
+## Design space
+
+The interesting axes:
+
+- **Process model:** single process (everything in one Node) vs. supervised children (one parent spawns daemon + adapters + web) vs. status-quo (each its own top-level process).
+- **Log model:** stdout in foreground vs. log files + `clawmini logs -f` command vs. both.
+- **Config for "what to start":** CLI flags (`clawmini run --discord --web`) vs. settings-driven (enabled services listed in `.clawmini/settings.json`) vs. auto-detect (adapter configured → start it).
+- **Backgrounding:** built-in `--detach` flag vs. rely on `nohup` / `screen` / system service manager vs. write a launchd/systemd template.
+
+These compose. Below I sketch four directions and note what each gets right / wrong.
+
+## Option A — `clawmini serve` (supervisor command)
+
+A new top-level command that becomes the one-and-only launcher:
+
+```bash
+clawmini serve                       # foreground, all enabled services, interleaved logs
+clawmini serve --detach              # daemonize, logs to .clawmini/logs/*.log
+clawmini serve --only daemon,web     # subset
+```
+
+`serve` spawns a parent process that:
+- Runs the daemon in-process (reuse `initDaemon()` directly — no subprocess needed).
+- Spawns `adapter-discord` / `adapter-google-chat` / `web` as child processes if configured/enabled.
+- Multiplexes their stdio into prefixed output lines (`[daemon] listening on ...`, `[discord] ready`, `[web] http://localhost:8080`).
+- On Ctrl-C, sends SIGTERM to children, calls daemon `shutdown()`, waits for clean exit.
+- On child crash, restarts with backoff (optional — or just log + exit).
+
+**How do we know which services to start?** Auto-detect based on what's configured in `.clawmini/`:
+- Daemon: always.
+- Web: always (or opt-out flag — it's basically free).
+- `adapter-discord`: if `.clawmini/adapters/discord/config.json` exists.
+- `adapter-google-chat`: if `.clawmini/adapters/google-chat/config.json` exists.
+
+Optional override via `--only`/`--exclude` flags.
+
+**Detach mode (`--detach`):** fork a supervisor into the background, open log files at `.clawmini/logs/{daemon,discord,google-chat,web}.log`, exit the foreground shell. `clawmini logs [-f] [--service <n>]` tails them.
+
+**Pros:**
+- One command. Matches mental model of `docker compose up`, `foreman start`, `overmind start`.
+- Logs are multiplexed and visible by default (addresses goal #1).
+- Backgrounding preserved via `--detach` (addresses goal #2).
+- Sets up the infrastructure needed for `/update`: there's now a single parent to SIGTERM, wait for, re-exec after upgrade (addresses goal #3).
+- Adapters don't need to change their main logic — they just get spawned by a different process.
+
+**Cons:**
+- `clawmini up` / `clawmini down` semantics get murky. Does `clawmini up` still work (daemon-only)? Do we deprecate it? Keep it as an alias?
+- Child-process log multiplexing is annoying to get right (line buffering, ANSI colors, interleaving).
+- Adapters become coupled to the supervisor's lifecycle — less flexible for people who want to run the discord adapter on a different host. (Probably fine: if you need that, you can still `npx clawmini-adapter-discord` manually.)
+
+## Option B — Teach the daemon to supervise adapters
+
+Same end result, different split: the daemon itself gains a service manager. On `clawmini up`, the daemon reads `.clawmini/settings.json`, sees which adapters are enabled, spawns them as children. On `clawmini down`, it kills them.
+
+```json
+// .clawmini/settings.json
+{
+  "services": {
+    "web": { "enabled": true, "port": 8080 },
+    "adapter-discord": { "enabled": true },
+    "adapter-google-chat": { "enabled": false }
+  }
+}
+```
+
+**Pros:**
+- No new top-level command; `clawmini up` / `clawmini down` keep meaning.
+- The daemon is already the stateful orchestrator; extending it to own adapter lifecycle is consistent.
+- Settings-driven: `clawmini services enable discord` toggles a flag, next `up` picks it up. Feels like `clawmini environments enable`.
+
+**Cons:**
+- The daemon runs detached already — logs for children would still go to files, not foreground. Doesn't directly solve goal #1 unless we also add a `clawmini logs -f` tail command *and* tell users to use it.
+- More responsibility in an already-complex process.
+- The daemon currently runs as a detached background process; if an adapter crashes the user has no visibility unless they're already tailing logs.
+
+**Variant B':** daemon supervises adapters *and* the `up` command runs in the foreground by default (only detaches if `--detach`). This converges with Option A but keeps the `up`/`down` command names.
+
+## Option C — Minimum-change: `clawmini logs` + better docs
+
+Leave the process model alone. Add:
+- `clawmini logs [-f] [--service <daemon|discord|google-chat|web>]` that tails `.clawmini/logs/*.log`.
+- Make adapters log to `.clawmini/logs/adapter-<name>.log` when started (respecting existing stdout for interactive use).
+- A one-liner helper script or Makefile-equivalent in the README: `clawmini start-all` shell function that backgrounds the four processes and tails their logs.
+
+**Pros:**
+- Cheap. Ships in a day.
+- Doesn't close any doors.
+
+**Cons:**
+- Doesn't really solve the "too many commands" feeling — users still orchestrate four things.
+- Makes goal #3 (`/update`) harder: no single parent to signal, no single source of truth for "what's running right now."
+
+## Option D — Single-process everything
+
+Bundle daemon + adapters + web into one Node process. `clawmini serve` imports each adapter module and starts its lifecycle inline. No subprocesses.
+
+**Pros:**
+- Simplest runtime model. One process, one log stream.
+- Fastest IPC (they're all in-process — but they already talk over a Unix socket, so this doesn't matter much in practice).
+
+**Cons:**
+- Ties adapter crashes to daemon crashes. A Discord.js bug that throws on an unhandled promise kills the daemon.
+- Harder to reason about memory limits / CPU.
+- Breaks the clean separation where adapters can run on different machines (over TCP) if we ever want that.
+- Adapters currently call the daemon over a Unix socket via a tRPC client — merging them means wiring them up differently in "local" mode vs. "remote" mode, which is more code, not less.
+
+I don't think this is the right call — but worth naming to frame the others against.
+
+## Directional preference (for discussion)
+
+**Option A (`clawmini serve` as supervisor of child processes)** is where I'd lean, for three reasons:
+
+1. It's the only option that unambiguously solves goal #1 (visible logs) without relying on a secondary `logs` command.
+2. It gives us a clean home for the `/update` operation (goal #3): the supervisor is the thing that knows how to stop, upgrade, and restart the whole constellation. No need to coordinate across multiple independent processes.
+3. It maps to patterns users already know (`docker compose up`, `overmind`, `foreman`), so there's no new mental model to learn.
+
+`clawmini up` / `clawmini down` stay as daemon-only commands for people who already have scripts using them — no deprecation needed short-term.
+
+The things I'd still want to pin down (see Open questions) are around how `serve` auto-detects what to run, and exactly what the `/update` protocol looks like.
+
+## Sketch: the `/update` flow (Option A assumed)
+
+Putting this down concretely to see if the design holds:
+
+1. Agent runs `clawmini-lite /update` (or a custom command that ends up sending this signal — TBD how the agent triggers it).
+2. The daemon receives the request and dispatches to a new handler: `updateSelf()`.
+3. `updateSelf` writes a "restart-requested" marker to `.clawmini/update-pending.json` with:
+   - Requested version (or `latest`).
+   - Timestamp.
+   - Which services were running (so restart is idempotent).
+4. The daemon shuts itself down (same path as `clawmini down`).
+5. The **supervisor** (not the daemon — the parent `clawmini serve` process) sees the daemon exit cleanly with the marker present. It:
+   - Stops all child adapters / web.
+   - Runs `npm install -g clawmini@<version>` (or `npm install clawmini@<version>` if local).
+   - Re-execs itself (`execvp`) with the new binary on PATH.
+6. On restart, the supervisor reads the marker, starts the same set of services, deletes the marker.
+7. Agent can notice the restart by the new version string in its next `/ping` response (or via a message from the supervisor once it's back up).
+
+**Why this structure:** the daemon cannot upgrade itself because it's the thing being replaced. It needs a parent that outlives the upgrade. The supervisor is exactly that parent.
+
+**Open edges:**
+- If clawmini is installed locally (in the workspace `node_modules`), who runs `npm install`? The supervisor's `cwd` is the workspace — `npm install clawmini@latest` there would update the local install. But if the user installed globally (`npm install -g clawmini`), the supervisor needs to run `npm install -g` — which may need sudo on some setups. We might detect the install location by inspecting `process.execPath` / `require.resolve('clawmini/package.json')`.
+- If the install fails mid-way, the supervisor needs a fallback ("old version still works, keep running it") rather than crash-looping.
+- If a user invokes `/update` while actively chatting with the agent, there's a dead period. Probably fine (announce it, then do it), but worth naming.
+- Agent trust: `/update` runs `npm install` which executes arbitrary scripts. This *is* a privileged operation. Needs the same policy approval flow as any other host-level command — not a built-in "agent can always do this."
+
+## Open questions
+
+1. **What does `clawmini up` / `clawmini down` mean after this ships?** Options: (a) deprecate and alias to `clawmini serve` / `clawmini serve --stop`, (b) keep as daemon-only commands forever, (c) redefine so `up` = `serve --detach` and `down` stops the supervisor. My instinct: (b) — don't break existing workflows; add `serve` alongside.
+2. **Auto-detect vs. explicit enable for services?** "Config file present" is a good default heuristic for adapters but ambiguous for web (no config file). Maybe: web is always on, adapters auto-detect, user can `--exclude` to suppress. Or add `services` to `settings.json` (Option B's idea) as an explicit override.
+3. **Log format.** Prefixed-line multiplexing is the standard approach; should we ship a JSON mode (`--log-format=json`) for machine consumers? Probably yes eventually, not for MVP.
+4. **Log files on disk even in foreground mode?** If `serve` is in the foreground and you `Ctrl+C`, do the logs persist? Teeing stdout to `.clawmini/logs/*.log` even in foreground mode makes post-mortems possible. Cheap to include.
+5. **Child restart policy.** If `adapter-discord` crashes, should the supervisor restart it? Backoff? Max retries? I'd say yes with exponential backoff capped at N retries, then give up and log — this is what users expect.
+6. **Adapter logs before they connect.** Currently `initGoogleChatConfig` needs to succeed before anything useful happens. The supervisor needs to surface config errors clearly, not just exit code 1.
+7. **How does the agent invoke `/update`?** Not a supervisor-design question per se, but: is `/update` a slash command that the daemon interprets, a built-in policy the agent can request, or something else? Easiest path: a router (like `@clawmini/slash-new`) that intercepts `/update` and calls the daemon's `updateSelf` tRPC method.
+8. **Does the supervisor need its own PID file / IPC socket?** If we want `clawmini serve --stop` to work from another terminal (instead of only Ctrl+C in the owning terminal), yes — we need a way to find the running supervisor and signal it.
+9. **Windows?** Currently the daemon uses a Unix socket; `detached: true` / `unref` semantics differ on Windows. Do we target Windows with this? Status quo is macOS/Linux; probably keep that scope.
+
+## Non-goals
+
+- Reinventing a process manager. If the above gets complicated, we just recommend `tmux` / `overmind` / a launchd plist in the docs and stop there.
+- Multi-host orchestration (adapter on server A, daemon on server B).
+- Hot-reload of adapters without restart.
+- Replacing `.clawmini/daemon.log` outright — it can keep existing as a compatibility artifact; `clawmini logs` just reads the new location.
+
+## Next steps (if we pick Option A)
+
+Rough shipping order that would let us validate before committing fully:
+
+1. **`clawmini serve` foreground-only, no backgrounding.** Spawn daemon inline + adapters as children + web. Multiplex logs with prefixes. Ctrl-C shuts everything cleanly. This is the MVP; it alone addresses goals #1 and #2 (users can `nohup clawmini serve &` if they want detach).
+2. **Auto-detect which adapters to start.** Look for config files; optional `--only` / `--exclude`.
+3. **`--detach` + `clawmini logs`.** First-class backgrounding with log tailing.
+4. **`/update` plumbing.** Supervisor-managed re-exec after `npm install`. Separate spec for that once serve is shipped.
+
+Each step is independently shippable and independently useful.

package/e2e/_helpers/test-environment.test.ts

@@ -0,0 +1,49 @@
+import { TestEnvironment } from './test-environment.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+describe('TestEnvironment', () => {
+  let env: TestEnvironment;
+
+  beforeEach(() => {
+    env = new TestEnvironment('test-env');
+  });
+
+  afterEach(async () => {
+    await env.teardown();
+  });
+
+  it('generates a unique id and creates an e2e directory', () => {
+    expect(env.id).toMatch(/^test-env-\d+-\d+$/);
+    expect(env.e2eDir).toContain(`clawmini-${env.id}`);
+  });
+
+  it('setup creates directory and init git', async () => {
+    await env.setup();
+    expect(fs.existsSync(env.e2eDir)).toBe(true);
+    expect(fs.existsSync(path.join(env.e2eDir, '.git'))).toBe(true);
+  });
+
+  it('updates settings', async () => {
+    await env.setup();
+    fs.mkdirSync(path.join(env.e2eDir, '.clawmini'), { recursive: true });
+
+    env.updateSettings({ api: { port: 8080 } });
+
+    const settingsPath = path.join(env.e2eDir, '.clawmini', 'settings.json');
+    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+
+    expect(settings.api.port).toBe(8080);
+  });
+
+  it('writes policies', async () => {
+    await env.setup();
+    env.writePolicies([{ name: 'test-policy' }]);
+
+    const policiesPath = path.join(env.e2eDir, '.clawmini', 'policies.json');
+    expect(fs.existsSync(policiesPath)).toBe(true);
+    const parsed = JSON.parse(fs.readFileSync(policiesPath, 'utf8'));
+    expect(parsed.policies[0].name).toBe('test-policy');
+  });
+});