@geminixiang/mama 0.2.0-beta.4 → 0.2.0-beta.6

package/README.md

@@ -3,70 +3,33 @@
 [![npm version](https://img.shields.io/npm/v/@geminixiang/mama.svg)](https://www.npmjs.com/package/@geminixiang/mama)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A multi-platform, multi-agent AI assistant for Slack, Telegram, and Discord — based on [pi-mom](https://github.com/badlogic/pi-mono), with the goal of merging improvements back upstream.
+A multi-platform AI assistant for Slack, Telegram, and Discord.
 
-## 📜 Attribution & Origins
-
-This project is a **forked and extended version** of the `mom` package from [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono) by Mario Zechner, licensed under MIT.
-
-- **Original project**: [pi-mom](https://github.com/badlogic/pi-mono/tree/main/packages/mom) (22K+ stars)
-- **Base version**: forked from pi-mom v0.57.1 (synchronized with `@mariozechner/*` packages)
-- **Primary motivation**: Internal services urgently needed a multi-platform bot — this fork enables rapid iteration while preparing changes to contribute back upstream
-
-## 🎯 Positioning & Roadmap
-
-| Aspect             | Description                                                                    |
-| ------------------ | ------------------------------------------------------------------------------ |
-| **Current Status** | Temporary standalone fork for urgent internal deployment                       |
-| **Ultimate Goal**  | Merge all improvements back into pi-mono monorepo                              |
-| **Unique Value**   | Multi-platform support (Slack + Telegram + Discord) to be contributed upstream |
-
-### Why a temporary fork?
-
-Our internal services urgently needed a multi-platform bot, and we couldn't wait for upstream release cycles. This fork allows us to:
-
-1. **Ship fast**: Deploy to production immediately while internal demand is high
-2. **Iterate freely**: Test multi-platform adapters (Slack, Telegram, Discord) without monorepo constraints
-3. **Contribute back**: All work here is intended to be merged into pi-mono — `mama` is not a replacement for `mom`
-
-### Contribution Philosophy 🔄
-
-> "This is not a separate product — it's a **temporary fork** for urgent internal needs, and all improvements will be contributed back to pi-mono."
-
-We actively track the upstream `pi-mom` and plan to:
-
-- ✅ Submit PRs for platform adapters (Telegram, Discord)
-- ✅ Contribute cross-platform abstractions
-- ✅ Keep dependencies synchronized with pi-mono releases
-- ✅ Document what we learn from production use
-
----
+Forked from [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono)'s `mom` package (MIT, by Mario Zechner) at v0.57.1. This fork adds Telegram and Discord adapters and exists to ship internally while we prepare changes to upstream.
 
 ## Features
 
-- **Multi-platform** — Slack, Telegram, and Discord adapters out of the box
-- **Persistent sessions** — session behavior is adapted per platform instead of forcing one thread model everywhere
-- **Concurrent conversations** — Slack threads, Discord replies/threads, and Telegram reply chains can run independently
-- **Sandbox execution** — run agent commands on host, in a shared container, in a managed per-user container, or experimentally in a Firecracker VM
-- **Credential vaults** — `/login` stores credentials under `--state-dir` and injects env only into container/image/Firecracker runs
-- **Web session viewer** — users can open a read-only web view of the current session via `session` / `/session`
-- **Persistent memory** — workspace-level and channel-level `MEMORY.md` files
-- **Skills** — drop custom CLI tools into `skills/` directories
-- **Event system** — schedule one-shot or recurring tasks via JSON files
-- **Multi-provider** — configure any provider/model supported by `pi-ai`
+- **Multi-platform** — Slack, Telegram, Discord adapters
+- **Concurrent conversations** — Slack threads, Discord replies/threads, and Telegram reply chains run as independent sessions
+- **Sandbox execution** — host, shared container, per-user managed container, Firecracker (alpha), or Cloudflare bridge (experimental)
+- **Credential vaults** — `/login` stores credentials under `--state-dir` and injects env into sandbox runs
+- **Web session viewer** — read-only web view of the current session via `session` / `/session`
+- **Persistent memory** — workspace-level and channel-level `MEMORY.md`
+- **Skills** — drop CLI tools into `skills/`
+- **Events** — schedule one-shot or recurring tasks via JSON files
+- **Multi-provider** — any provider/model supported by `pi-ai`
 
 ## Platform Session Model
 
-| Platform | User Interaction Structure                        | `sessionKey` Rule                                                                 | Default Session Model                                                                       | Special Handling Needed | Notes                                                                                            |
-| -------- | ------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
-| Slack    | channel top-level + thread replies                | top-level / DM: `conversationId`; thread: `conversationId:threadTs`               | top-level channel and DM sessions persist; each Slack thread forks into its own session     | High                    | thread inherits parent context at fork time only; branch changes do not merge back automatically |
-| Discord  | server mentions, replies, thread channels, DMs    | DM: `channelId`; shared top-level: `channelId:messageId`; reply/thread: rooted id | DMs are one persistent session; shared spaces are scoped per top-level mention or thread    | Medium                  | replies in shared channels continue the root message session; DM replies do not fork             |
-| Telegram | private chats, group mentions, group reply chains | private: `chatId`; shared top-level: `chatId:messageId`; reply chain: root reply  | private chats are one persistent session; shared groups are scoped per mentioned reply root | Medium                  | Telegram has no native thread model; shared sessions are inferred from reply chains              |
+| Platform | `sessionKey` Rule                                                                 | Notes                                                                                |
+| -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Slack    | top-level / DM: `conversationId`; thread: `conversationId:threadTs`               | thread inherits parent context at fork time only; branch changes do not merge back   |
+| Discord  | DM: `channelId`; shared top-level: `channelId:messageId`; reply/thread: rooted id | replies in shared channels continue the root message session; DM replies do not fork |
+| Telegram | private: `chatId`; shared top-level: `chatId:messageId`; reply chain: root reply  | no native thread model; shared sessions are inferred from reply chains               |
 
 ## Requirements
 
 - Node.js >= 20
-- One of the platform integrations below
 
 ## Installation
 
@@ -74,469 +37,240 @@ We actively track the upstream `pi-mom` and plan to:
 npm install -g @geminixiang/mama
 ```
 
-Or run directly after cloning:
+Or from source:
 
 ```bash
-npm install
-npm run build
+npm install && npm run build
 ```
 
----
-
 ## Quick Start
 
-### Slack
+All platforms share the same CLI:
 
-1. Create a Slack app with **Socket Mode** enabled ([setup guide](docs/slack-bot-minimal-guide.md)).
-2. Add the following **OAuth Bot Token Scopes**:
-   - `app_mentions:read`, `channels:history`, `channels:read`, `chat:write`
-   - `files:read`, `files:write`, `groups:history`, `groups:read`
-   - `im:history`, `im:read`, `im:write`, `users:read`
-   - `assistant:write` — required for native "Thinking" status indicator
-3. Enable the **Home Tab** and **Agent mode**:
-   - **App Home → Show Tabs** — toggle **Home Tab** on
-   - **App Home → Agents & AI Apps** — toggle **Agent or Assistant** on
-4. Subscribe to **Bot Events**:
-   - `app_home_opened`, `app_mention`
-   - `assistant_thread_context_changed`, `assistant_thread_started`
-   - `message.channels`, `message.groups`, `message.im`
-5. Enable **Interactivity** (Settings → Interactivity & Shortcuts → toggle on).
-6. (Optional) Add **Slash Commands** such as `/pi-login` and `/pi-new` in the Slack app settings if you want dedicated commands with less naming conflict. `/pi-new` is intended for DM use only.
-7. Copy the **App-Level Token** (`xapp-…`) and **Bot Token** (`xoxb-…`).
-
-Or import this **App Manifest** directly (Settings → App Manifest → paste JSON):
-
-<details>
-<summary>Example App Manifest</summary>
-
-```json
-{
-  "display_information": {
-    "name": "mama"
-  },
-  "features": {
-    "app_home": {
-      "home_tab_enabled": true,
-      "messages_tab_enabled": false,
-      "messages_tab_read_only_enabled": false
-    },
-    "bot_user": {
-      "display_name": "mama",
-      "always_online": false
-    }
-  },
-  "oauth_config": {
-    "scopes": {
-      "bot": [
-        "app_mentions:read",
-        "assistant:write",
-        "channels:history",
-        "channels:read",
-        "chat:write",
-        "files:read",
-        "files:write",
-        "groups:history",
-        "groups:read",
-        "im:history",
-        "im:read",
-        "im:write",
-        "users:read"
-      ]
-    }
-  },
-  "settings": {
-    "event_subscriptions": {
-      "bot_events": [
-        "app_home_opened",
-        "app_mention",
-        "assistant_thread_context_changed",
-        "assistant_thread_started",
-        "message.channels",
-        "message.groups",
-        "message.im"
-      ]
-    },
-    "interactivity": {
-      "is_enabled": true
-    },
-    "org_deploy_enabled": false,
-    "socket_mode_enabled": true,
-    "token_rotation_enabled": false
-  }
-}
+```bash
+mama [--state-dir=~/.mama] [--sandbox=<mode>] <working-directory>
 ```
 
-</details>
+Set the platform tokens you need (you can run multiple platforms at once):
 
 ```bash
-export MOM_SLACK_APP_TOKEN=xapp-...
-export MOM_SLACK_BOT_TOKEN=xoxb-...
-
-mama [--state-dir=~/.mama] [--sandbox=host|container:<container>|image:<image>|firecracker:<vm-id>:<path>] <working-directory>
+export MAMA_SLACK_APP_TOKEN=xapp-...
+export MAMA_SLACK_BOT_TOKEN=xoxb-...
+export MAMA_TELEGRAM_BOT_TOKEN=123456:ABC-...
+export MAMA_DISCORD_BOT_TOKEN=MTI...
 ```
 
-The bot responds when `@mentioned` in any channel or via DM.
-
-- **Top-level channel messages** — share one persistent channel session.
-- **Thread replies** — fork from the channel session into an isolated thread session.
-- **DM top-level messages** — share one persistent DM session.
-- **DM thread replies** — fork from the DM session into an isolated thread session.
-- **Thread memory** — inherited at fork time only; thread changes do not merge back into the parent session automatically.
+### Slack
 
----
+Create a Socket Mode app with the scopes and event subscriptions listed in [docs/slack-bot-minimal-guide.md](docs/slack-bot-minimal-guide.md). The bot responds when `@mentioned` in channels and to all DMs.
 
 ### Telegram
 
-1. Message [@BotFather](https://t.me/BotFather) → `/newbot` to create a bot and get the **Bot Token**.
-2. Optionally disable privacy mode (`/setprivacy → Disable`) so the bot can read group messages without being `@mentioned`.
-
-```bash
-export MOM_TELEGRAM_BOT_TOKEN=123456:ABC-...
-
-mama [--state-dir=~/.mama] [--sandbox=host|container:<container>|image:<image>|firecracker:<vm-id>:<path>] <working-directory>
-```
-
-- **Private chats** — every message is forwarded to the bot automatically.
-- **Group chats** — the bot only responds when `@mentioned` by username.
-- **Private chat session** — one persistent session per DM.
-- **Group top-level mentions** — each mentioned message starts its own scoped session.
-- **Reply chains** — replying to a previous message continues that reply-root session.
-- Say `stop` or `/stop` to cancel a running task.
-
----
+Create a bot via [@BotFather](https://t.me/BotFather) and copy the token. The bot responds to all private messages, and to `@mention` or reply chains in groups. Use `/login`, `/session`, `/new`, and `/stop` for controls.
 
 ### Discord
 
-1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) → **New Application**.
-2. Under **Bot**, enable **Message Content Intent** (required to read message text).
-3. Under **OAuth2 → URL Generator**, select scopes `bot` + permissions `Send Messages`, `Read Message History`, `Attach Files`. Invite the bot to your server with the generated URL.
-4. Copy the **Bot Token**.
+Create an application in the [Discord Developer Portal](https://discord.com/developers/applications), enable **Message Content Intent**, and invite the bot with `Send Messages`, `Read Message History`, `Attach Files`. The bot responds to `@mentions` in servers and to all DMs.
 
-```bash
-export MOM_DISCORD_BOT_TOKEN=MTI...
+## Sandbox Modes
 
-mama [--state-dir=~/.mama] [--sandbox=host|container:<container>|image:<image>|firecracker:<vm-id>:<path>] <working-directory>
-```
-
-- **Server channels** — the bot responds when `@mentioned`.
-- **DMs** — every message is forwarded automatically.
-- **DM session** — one persistent session per DM channel.
-- **Top-level mentions in shared channels** — each mentioned message starts its own scoped session.
-- **Threads and reply chains** — messages inside the same thread or reply root share a session.
-- Say `stop` or `/stop` to cancel a running task.
-
----
+| Mode                         | Description                                                            |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `host` (default)             | Run on host; no vault env injection                                    |
+| `container:<name>`           | Run in an existing shared container; uses vault key `container-<name>` |
+| `image:<image>`              | Auto-provision one Docker container per resolved vault/user            |
+| `firecracker:<vm-id>:<path>` | Firecracker microVM (alpha; not recommended)                           |
+| `cloudflare:<sandbox-id>`    | Cloudflare Worker bridge (experimental; no auto workspace sync)        |
 
-## Options
+Vault routing: `image`, `firecracker`, and `cloudflare` look up `bindings.json` first, then fall back to the userId vault. See [docs/sandbox.md](docs/sandbox.md) for the full matrix.
 
-| Option                                 | Default   | Description                                                        |
-| -------------------------------------- | --------- | ------------------------------------------------------------------ |
-| `--state-dir=<dir>`                    | `~/.mama` | Store settings, credential vaults, and bindings outside workspace  |
-| `--sandbox=host`                       | ✓         | Run commands directly on host; vault env is not injected           |
-| `--sandbox=container:<name>`           |           | Run commands in an existing shared container                       |
-| `--sandbox=image:<image>`              |           | Auto-provision one Docker container per platform user              |
-| `--sandbox=firecracker:<vm-id>:<path>` |           | Experimental Firecracker microVM mode (alpha; not recommended yet) |
-| `--download <channel-id>`              |           | Download channel history to stdout and exit (Slack only)           |
-
-### Sandbox and Vault Semantics
-
-- `host`: no vault env injection.
-- `container:<name>`: one container maps to one shared vault key: `container-<name>`.
-- `image:<image>`: mama creates one container per resolved vault/user and injects that vault's env and file mounts.
-- `firecracker:*`: per-user vault routing via `bindings.json` first, then direct userId vault. This mode is still alpha and not recommended for normal deployments yet.
-- `docker:*` is not supported; use `container:*` or `image:*`.
-
-See [docs/sandbox.md](docs/sandbox.md) for the full sandbox/vault behavior matrix.
-
-### Download channel history (Slack)
+### Managed per-user containers (`image:*`)
 
 ```bash
-mama --download C0123456789
+docker pull ghcr.io/geminixiang/mama-sandbox:tools
+mama --sandbox=image:ghcr.io/geminixiang/mama-sandbox:tools /path/to/workspace
 ```
 
-## `/login` Credential Onboarding
-
-For normal deployments, set `MOM_LINK_URL` to the externally reachable base URL of the web credential onboarding flow:
+Or build locally:
 
 ```bash
-export MOM_LINK_URL="https://mama.example.com"
-# optional; defaults to 8181 when MOM_LINK_URL is set
-export MOM_LINK_PORT=8181
+docker build -f docker/mama-sandbox.Dockerfile -t mama-sandbox:tools .
 ```
 
-For local-only testing, you can set `MOM_LINK_PORT` without `MOM_LINK_URL`; mama will use `http://localhost:<port>` for the onboarding link.
-
-Users can then run `/login` in a private conversation with the bot. mama returns a 15-minute link for storing API keys or using built-in OAuth providers. `/login` is rejected in shared channels to avoid leaking onboarding links.
-
-On Slack, you can also register native slash commands such as `/pi-login` and `/pi-new`.
-
-- `/pi-login` in a shared channel opens a DM and continues the credential flow there.
-- `/pi-new` only works in a Slack DM and resets that DM session context.
+mama creates one container per vault, attaches each to its own bridge network, mounts the workspace at `/workspace`, injects vault env, mounts declared credential files, and stops idle containers.
 
-## Web Session Viewer
+### Firecracker / Cloudflare
 
-The same web portal used for `/login` can also render a read-only view of the current session.
+See [docs/firecracker-setup.md](docs/firecracker-setup.md) and [examples/cloudflare-sandbox-bridge/README.md](examples/cloudflare-sandbox-bridge/README.md).
 
-- Users can send `session`, `/session`, or `/pi-session` in a private conversation / DM.
-- mama returns an expiring read-only link to `/session?token=...`.
-- The page shows the current branch timeline, including user messages, assistant replies, tool results, and compaction / branch summary events.
-- For now, session links are only issued from private conversations to avoid leaking shared-channel history.
+## `/login` and Web Session Viewer
 
-This feature uses the same `MOM_LINK_URL` / `MOM_LINK_PORT` configuration as `/login`.
+```bash
+export MAMA_LINK_URL="https://mama.example.com"   # public base URL
+export MAMA_LINK_PORT=8181                         # optional, defaults to 8181
+```
 
-Built-in OAuth guides:
+For local testing you can set just `MAMA_LINK_PORT`; mama will use `http://localhost:<port>`.
 
-- [GitHub OAuth](docs/oauth/github.md)
-- [Google Workspace CLI OAuth](docs/oauth/google-workspace.md)
+- `/login` (DM only) returns a 15-minute link to store API keys or run built-in OAuth flows ([GitHub](docs/oauth/github.md), [Google Workspace](docs/oauth/google-workspace.md)).
+- `session` / `/session` (DM only) returns a read-only link showing the current session timeline.
+- `new` / `/new` (DM only) resets the current session and starts fresh.
+- `model` / `/model` / `/pi-model provider/model[:thinking]` switches the LLM for the current conversation, e.g. `/pi-model anthropic/claude-sonnet-4-5:off`.
+- `stop` / `/stop` stops the current run. On Slack, use text commands so thread-local stop routing remains accurate.
+- On Slack you can also register native commands like `/pi-login`, `/pi-session`, `/pi-model`, and `/pi-new`.
 
-Credentials are stored under `<state-dir>/vaults` (default `~/.mama/vaults`). Runtime env injection only happens in `container`, `image`, and `firecracker` modes.
+Credentials are stored under `<state-dir>/vaults` (default `~/.mama/vaults`). Vault env is only injected in `container`, `image`, `firecracker`, and `cloudflare` modes.
 
 ## Configuration
 
-mama loads settings from `<state-dir>/settings.json` first, then falls back to `<working-directory>/settings.json` if the state-dir file is absent. For shared bot deployments, prefer the state-dir copy:
+mama reads global settings from `<state-dir>/settings.json` (default `~/.mama/settings.json`, override via `--state-dir` or `MAMA_STATE_DIR`). This file is required and is created explicitly with `mama --onboard`. Per-conversation settings live at `<workingDir>/<conversationId>/settings.json` and override global settings for that conversation.
 
 ```json
 {
-  "provider": "anthropic",
-  "model": "claude-sonnet-4-5",
-  "thinkingLevel": "off",
-  "sessionScope": "thread",
-  "logFormat": "console",
-  "logLevel": "info",
-  "sentryDsn": "https://examplePublicKey@o0.ingest.sentry.io/0"
+  "llm": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-5",
+    "thinkingLevel": "off"
+  },
+  "log": {
+    "format": "console",
+    "level": "info"
+  },
+  "sentry": {
+    "dsn": "https://examplePublicKey@o0.ingest.sentry.io/0"
+  },
+  "sandbox": {
+    "cpus": "0.5",
+    "memory": "512m"
+  }
 }
 ```
 
-| Field           | Default             | Description                                                                                              |
-| --------------- | ------------------- | -------------------------------------------------------------------------------------------------------- |
-| `provider`      | `anthropic`         | AI provider (env: `MOM_AI_PROVIDER`)                                                                     |
-| `model`         | `claude-sonnet-4-5` | Model name (env: `MOM_AI_MODEL`)                                                                         |
-| `thinkingLevel` | `off`               | `off` / `low` / `medium` / `high`                                                                        |
-| `sessionScope`  | `thread`            | Legacy compatibility setting. Current session boundaries are platform-defined by adapter/session policy. |
-| `logFormat`     | `console`           | `console` (colored stdout) or `json` (GCP Cloud Logging)                                                 |
-| `logLevel`      | `info`              | `trace` / `debug` / `info` / `warn` / `error`                                                            |
-| `sentryDsn`     | unset               | Sentry DSN (preferred over env `SENTRY_DSN`)                                                             |
-
-When `sentryDsn` is set, mama sends Sentry events with sensitive prompt/tool content redacted before upload.
-
-### GCP Cloud Logging (Compute Engine)
-
-Set `logFormat: "json"` to send structured logs directly to Cloud Logging via API — no Ops Agent or log file configuration needed.
-
-**Requirements:**
-
-1. VM service account has `roles/logging.logWriter`
-2. `GOOGLE_CLOUD_PROJECT` env var is set
-
-```bash
-GOOGLE_CLOUD_PROJECT=<your-project-id> mama <working-directory>
-```
+| Field               | Default             | Description                                              |
+| ------------------- | ------------------- | -------------------------------------------------------- |
+| `llm.provider`      | `anthropic`         | AI provider                                              |
+| `llm.model`         | `claude-sonnet-4-5` | Model name                                               |
+| `llm.thinkingLevel` | `off`               | `off` / `low` / `medium` / `high`                        |
+| `log.format`        | `console`           | `console` (colored stdout) or `json` (GCP Cloud Logging) |
+| `log.level`         | `info`              | `trace` / `debug` / `info` / `warn` / `error`            |
+| `sentry.dsn`        | unset               | Sentry DSN; sensitive prompt/tool content is redacted    |
+| `sandbox.cpus`      | unset               | CPU limit for managed containers                         |
+| `sandbox.memory`    | unset               | Memory limit for managed containers                      |
 
-In `<state-dir>/settings.json` (or `<working-directory>/settings.json` as a fallback):
+Conversation-local settings written by `/pi-model` use the same shape and usually only include the override:
 
 ```json
 {
-  "logFormat": "json",
-  "logLevel": "info"
+  "llm": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-5",
+    "thinkingLevel": "off"
+  }
 }
 ```
 
-Logs appear in Cloud Logging under **Log name: `mama`**. Console output (stdout) is unaffected and continues to work alongside Cloud Logging.
+For GCP Cloud Logging, set `log.format: "json"`, give the VM service account `roles/logging.logWriter`, and export `GOOGLE_CLOUD_PROJECT`. Logs land under log name `mama`.
 
-## State Directory Layout
+## Layout
 
 ```
 <state-dir>/
-├── settings.json          # Preferred provider/model/logging/Sentry config
+├── settings.json
 └── vaults/
-    ├── bindings.json      # Platform user -> vault mapping
-    ├── vault.json         # Vault metadata
+    ├── bindings.json          # platform user -> vault mapping
+    ├── vault.json
     └── <vault-id>/
-        ├── env            # Injected env vars
-        └── ...            # Credential files (e.g. gws.json, .ssh/)
-```
-
-## Working Directory Layout
+        ├── env
+        └── ...                # credential files
 
-```
 <working-directory>/
-├── settings.json          # Optional fallback config if <state-dir>/settings.json is absent
-├── MEMORY.md              # Global memory (all channels)
-├── SYSTEM.md              # Installed packages / env changes log
-├── skills/                # Global skills (CLI tools)
-├── events/                # Scheduled event files
+├── MEMORY.md                  # global memory
+├── SYSTEM.md                  # installed packages / env log
+├── skills/                    # global skills
+├── events/                    # scheduled events
 └── <conversation-id>/
-    ├── MEMORY.md          # Conversation-specific memory
-    ├── log.jsonl          # Full message history
-    ├── attachments/       # Downloaded user files
-    ├── scratch/           # Agent working directory
-    ├── skills/            # Conversation-specific skills
+    ├── MEMORY.md
+    ├── log.jsonl
+    ├── attachments/
+    ├── scratch/
+    ├── skills/
     └── sessions/
-        ├── current                      # Pointer for the persistent top-level / direct session
-        ├── 2026-04-05T18-04-31-010Z_1d92b3ad.jsonl
-        └── <session-suffix>.jsonl       # Fixed-path scoped session (thread / reply root)
 ```
 
-## Container Sandbox
-
-```bash
-# Create a container (mount your working directory to /workspace)
-docker run -d --name mama-tools \
-  -v /path/to/workspace:/workspace \
-  alpine:latest sleep infinity
-
-# Start mama with container sandbox
-mama --sandbox=container:mama-tools /path/to/workspace
-```
+## Events
 
-`container:mama-tools` uses vault key `container-mama-tools`. If multiple users share the same container, they share that container vault.
+Drop JSON files into `<working-directory>/events/`:
 
-## Managed Per-User Container Sandbox
+```json
+// Immediate
+{"type": "immediate", "platform": "slack", "conversationId": "C0123456789", "conversationKind": "shared", "text": "Deploy finished"}
 
-```bash
-# Pull the prebuilt image from GHCR
-# Release builds publish :tools, :<version>, and :latest / :beta
-# Pushes to main also publish :edge
-docker pull ghcr.io/geminixiang/mama-sandbox:tools
+// One-shot
+{"type": "one-shot", "platform": "telegram", "conversationId": "574247312", "conversationKind": "direct", "text": "Standup", "at": "2025-12-15T09:00:00+08:00"}
 
-# Start mama with managed image sandboxes
-mama --sandbox=image:ghcr.io/geminixiang/mama-sandbox:tools /path/to/workspace
+// Periodic (cron)
+{"type": "periodic", "platform": "discord", "conversationId": "1498975469343739948", "conversationKind": "shared", "text": "Check inbox", "schedule": "0 9 * * 1-5", "timezone": "Asia/Taipei"}
 ```
 
-Or build the bundled image locally:
+## Skills
 
-```bash
-docker build -f docker/mama-sandbox.Dockerfile -t mama-sandbox:tools .
-mama --sandbox=image:mama-sandbox:tools /path/to/workspace
+```
+skills/my-tool/
+├── SKILL.md      # name + description frontmatter, usage docs
+└── run.sh
 ```
 
-In this mode mama creates one Docker container per resolved vault/user, attaches each container to its own Docker bridge network for per-user network isolation, mounts the workspace at `/workspace`, injects vault env on execution, mounts any credential files declared in the vault, and stops idle containers automatically.
-
-## Firecracker Sandbox
-
-Warning: Firecracker support is still in very early alpha. It is useful for experimentation, but it is not yet the recommended sandbox mode for normal development or production use. Prefer `image:<image>` unless you are actively validating Firecracker behavior.
-
-Firecracker provides lightweight VM isolation with the security benefits of a hypervisor. Unlike Docker containers, Firecracker runs a full Linux kernel, providing stronger isolation.
-
-### Requirements
-
-- SSH access to the Firecracker VM
-- SSH key-based authentication configured
-- Host workspace must be mounted at `/workspace` inside the VM
-
-### Format
+```yaml
+---
+name: my-tool
+description: Does something useful
+---
 
-```
---sandbox=firecracker:<vm-id>:<host-path>[:<ssh-user>[:<ssh-port>]]
+Usage: {baseDir}/run.sh <args>
 ```
 
-| Parameter   | Default | Description                    |
-| ----------- | ------- | ------------------------------ |
-| `vm-id`     | -       | VM identifier (hostname or IP) |
-| `host-path` | -       | Working directory on the host  |
-| `ssh-user`  | `root`  | SSH username                   |
-| `ssh-port`  | `22`    | SSH port                       |
-
-### Examples
+## Slack: Download channel history
 
 ```bash
-# Basic usage (VM at 192.168.1.100, default ssh user root:22)
-mama --sandbox=firecracker:192.168.1.100:/home/user/workspace /home/user/workspace
-
-# Custom SSH user
-mama --sandbox=firecracker:192.168.1.100:/home/user/workspace:ubuntu /home/user/workspace
-
-# Custom SSH port
-mama --sandbox=firecracker:192.168.1.100:/home/user/workspace:root:2222 /home/user/workspace
+mama --download C0123456789
 ```
 
-### Setup
-
-1. **Start a Firecracker VM** with your preferred method (fc-agent, firecracker-ctl, or manual)
-
-2. **Configure SSH access** inside the VM:
-
-   ```bash
-   # Inside the VM - allow password-less SSH for mama
-   sudo systemctl enable ssh
-   sudo sed -i 's/^#*PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
-   sudo sed -i 's/^#*PubkeyAuthentication.*/PubkeyAuthentication yes/' /etc/ssh/sshd_config
-   sudo systemctl restart ssh
-   ```
-
-3. **Mount your workspace** at `/workspace` inside the VM:
-
-   ```bash
-   # Option A: 9pfs (recommended, from host)
-   sudo mount -t 9p -o trans=virtio,version=9p2000.L host0 /workspace
+## Production deployment (PM2)
 
-   # Option B: NFS
-   sudo mount -t nfs <host-ip>:/path/to/workspace /workspace
-   ```
+For long-running deployments, use [PM2](https://pm2.keymetrics.io/) as a process supervisor. It daemonizes mama, restarts on crash, and survives reboots.
 
-4. **Test SSH connectivity** from host:
-   ```bash
-   ssh root@192.168.1.100 "echo works"
-   ```
-
-The host path is mounted as `/workspace` inside the Firecracker VM. All bash commands will execute inside the VM.
-
-## Events
-
-Drop JSON files into `<working-directory>/events/` to trigger the agent:
-
-```json
-// Immediate — triggers as soon as mama sees the file
-{"type": "immediate", "platform": "slack", "conversationId": "C0123456789", "conversationKind": "shared", "text": "New deployment finished"}
+```bash
+# 1. Install mama and pm2
+npm i -g @geminixiang/mama pm2
 
-// One-shot — triggers once at a specific time
-{"type": "one-shot", "platform": "telegram", "conversationId": "574247312", "conversationKind": "direct", "text": "Daily standup reminder", "at": "2025-12-15T09:00:00+08:00"}
+# 2. Start the sandbox container (long-lived; mama execs into it)
+docker pull ghcr.io/geminixiang/mama-sandbox:latest
 
-// Periodic — triggers on a cron schedule
-{"type": "periodic", "platform": "discord", "conversationId": "1498975469343739948", "conversationKind": "shared", "text": "Check inbox", "schedule": "0 9 * * 1-5", "timezone": "Asia/Taipei"}
+# 3. Grab the ecosystem file, edit args + env tokens, then start
+curl -O https://raw.githubusercontent.com/geminixiang/mama/main/deploy/pm2/ecosystem.config.cjs
+pm2 start ecosystem.config.cjs
+pm2 save
+pm2 startup        # run the printed command to enable boot autostart
 ```
 
-## Skills
-
-Create reusable CLI tools by adding a directory with a `SKILL.md`:
+Upgrade flow:
 
-```
-skills/
-└── my-tool/
-    ├── SKILL.md    # name + description frontmatter, usage docs
-    └── run.sh      # the actual script
+```bash
+npm i -g @geminixiang/mama && pm2 reload mama
 ```
 
-`SKILL.md` frontmatter:
-
-```yaml
----
-name: my-tool
-description: Does something useful
----
+`pm2 reload` sends SIGTERM and waits up to `kill_timeout` (60s in the shipped config) before SIGKILL. mama's internal graceful shutdown drains in-flight LLM turns within that window, so reloads do not interrupt active conversations.
 
-Usage: {baseDir}/run.sh <args>
-```
+See [`deploy/pm2/ecosystem.config.cjs`](deploy/pm2/ecosystem.config.cjs) for all tunables.
 
 ## Development
 
 ```bash
 npm run dev     # watch mode
-npm test        # run tests
-npm run build   # production build
+npm test
+npm run build
 ```
 
-## 📦 Dependencies & Versions
-
-| Package                         | mama Version | pi-mom Synced Version            |
-| ------------------------------- | ------------ | -------------------------------- |
-| `@mariozechner/pi-agent-core`   | `^0.69.0`    | ✅ Synchronized                  |
-| `@mariozechner/pi-ai`           | `^0.69.0`    | ✅ Synchronized                  |
-| `@mariozechner/pi-coding-agent` | `^0.69.0`    | ✅ Synchronized                  |
-| `@anthropic-ai/sandbox-runtime` | `^0.0.49`    | ⚠️ Newer than original fork base |
-
 ## License
 
-MIT — see [LICENSE](LICENSE).
-
-**Note**: This project inherits the MIT license from pi-mom and aims to keep its contributions compatible with the upstream ecosystem.
+MIT — see [LICENSE](LICENSE). Inherits from pi-mom.