@geminixiang/mikan 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,324 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+once it leaves the 0.x line. While on `0.2.0-beta.*`, breaking changes may land in
+any release.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-23
+
+### Changed
+
+- Renamed the project, CLI, npm package, GitHub repository, documentation, release skill, and sandbox image references to mikan.
+- Changed platform credentials to unprefixed env vars (`SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN`, `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN`) while keeping `MIKAN_*` aliases as fallbacks.
+- Changed runtime env vars such as `LINK_URL`, `LINK_PORT`, `STATE_DIR`, OAuth scope overrides, and Cloudflare sandbox settings to prefer unprefixed names with `MIKAN_*` fallbacks.
+- Raised the minimum supported Node.js version to `>=22.19.0`.
+- Updated internal variable, function, type, Docker label, sandbox image, and generated resource names to use mikan naming.
+- Added manual dispatch support to the CI workflow.
+
+## [0.2.0-beta.25] - 2026-05-23
+
+### Changed
+
+- Grouped session modules under a single directory.
+- Centralized command parsing across adapters.
+- Removed explicit `any` usage across the type surface.
+- Cleaned unused dependencies.
+
+### Tests
+
+- CI now enforces coverage thresholds.
+
+## [0.2.0-beta.24]
+
+### Fixed
+
+- Session history writes now emit valid assistant messages.
+
+## [0.2.0-beta.23]
+
+### Fixed
+
+- Refresh stale channel history before forking a thread.
+- Separate history seeds from live sessions to prevent cross-contamination.
+- Materialize channel history when the first thread is created.
+
+### Added
+
+- Scripts to migrate session history and repair orphan thread sessions.
+
+## [0.2.0-beta.22]
+
+### Fixed
+
+- Slack: fork bot response threads from the channel session so replies inherit context.
+- Vault: preserve failures when the default shared vault cannot be applied.
+
+## [0.2.0-beta.21]
+
+### Added
+
+- Vault: seed new sandboxes from a shared profile (`sandbox.defaultSharedVault`).
+
+## [0.2.0-beta.20]
+
+### Added
+
+- Sentry: report user-facing failures.
+- Auto-reply: surface configured rules in the status command.
+
+### Fixed
+
+- Slack: anchor event-fork sessions correctly (#61).
+- Slack: keep session ephemerals scoped to threads.
+- Agent: require history search before answering unknown replies.
+- Agent: keep quiet tool errors out of chat.
+
+### Changed
+
+- Removed cloud-logging config — log to stdout/stderr and route via your process manager.
+
+## [0.2.0-beta.19]
+
+### Fixed
+
+- Sandbox: bootstrap `gh` git credentials inside managed containers.
+
+## [0.2.0-beta.18]
+
+### Fixed
+
+- Sandbox: update memory swap when applying CPU/memory limits.
+- Slack: preserve long replies posted in threads.
+
+## [0.2.0-beta.17]
+
+### Added
+
+- Sentry: store env values and write a `sentry-cli` config for richer error reports.
+
+### Changed
+
+- Bumped `@earendil-works/pi-*` packages.
+
+## [0.2.0-beta.16]
+
+### Performance
+
+- Slack: unblock startup while backfill is running.
+
+## [0.2.0-beta.15]
+
+### Added
+
+- Config: validate JSON files with TypeBox schemas.
+- Agent: attribute the trigger (mention/direct/auto-reply/…) in responses.
+
+## [0.2.0-beta.14]
+
+### Fixed
+
+- Login: refresh the sandbox after copying a shared profile.
+
+### Changed
+
+- Simplified command dispatch, token stores, and re-exports (#60).
+
+## [0.2.0-beta.13]
+
+### Added
+
+- Login: gcloud OAuth support.
+
+## [0.2.0-beta.12]
+
+### Fixed
+
+- Auto-reply: persist the resolved session key.
+
+## [0.2.0-beta.11]
+
+### Fixed
+
+- Login: make Slack login ephemeral and refresh vault mounts after credentials change.
+
+### Changed
+
+- Sandbox: update base image and tags.
+
+## [0.2.0-beta.10]
+
+### Added
+
+- Auto-reply: channel trigger rules and a configurable judge model (`llm.autoReply`).
+- Slack: native E2E smoke workflow under `e2e/`.
+
+### Fixed
+
+- Auto-reply: use mom-compatible marker files; judge policy never throws and always logs.
+- Events: validate one-shot times before scheduling; simplify fresh follow-up sessions.
+
+### Changed
+
+- Onboard: default model is `claude-sonnet-4-6`.
+- Separated runtime and control-plane paths.
+
+## [0.2.0-beta.9]
+
+### Added
+
+- Session view: floating composer and per-message copy button.
+- Docker sandbox: add `rg` and `fd` to the image.
+
+### Fixed
+
+- Session view: ignore Enter during IME composition; preserve code-block contrast.
+
+## [0.2.0-beta.8]
+
+### Added
+
+- Login: shared vault profiles.
+- Session view: improved interactive chat console.
+- Slack: harden socket connection and label the platform in the connect log.
+- Agent: `ThinkingLevel` type on session parameters.
+
+### Changed
+
+- Sandbox: store the image workspace mount in settings.
+- Dropped `vault.json` metadata — directories are the only source of truth.
+- Refactored agent runner orchestration into smaller modules.
+
+### Removed
+
+- `UserBindingStore` and `bindings.json` plumbing.
+- Log-to-session backfill.
+
+## [0.2.0-beta.7]
+
+### Added
+
+- Sandbox: temporary `boost` command for one-off CPU/memory bumps.
+- Slack: mute command summaries.
+
+### Changed
+
+- Migrated `pi-*` packages to the `@earendil-works/` namespace.
+
+### Fixed
+
+- Slack: log messages from external apps; hide bash tool diagnostics.
+- Session: ignore history written before a reset.
+- Agent: clarify runtime workspace paths in the system prompt.
+
+## [0.2.0-beta.6]
+
+### Added
+
+- Commands: conversation model switch (`/pi-model …`) with `:thinking` shorthand.
+- Config: onboarding flow for global settings (`mikan --onboard`).
+- Docs: PM2 ecosystem config and production deploy guide.
+
+### Changed
+
+- Config: nest settings schema; align chat platform commands.
+
+### Fixed
+
+- Slack: strip only the bot's own mention from message text.
+
+## [0.2.0-beta.5]
+
+### Added
+
+- Sandbox: Cloudflare sandbox bridge (experimental).
+- Tests: unit coverage for `CommandRegistry` and command handlers.
+
+### Changed
+
+- Env: renamed `MOM_*` env vars to `MIKAN_*` (breaking).
+- Vault: conversation vault directories are now the source of truth; dropped platform prefix from the conversation vault key.
+- Config: `--state-dir` is the single source for settings.
+- Tightened command/runtime types and added a `postPrivate` capability.
+
+## [0.2.0-beta.4]
+
+### Changed
+
+- Hardened core writes; unified adapter retry and log helpers.
+- Eliminated duplication across adapters, vault, and Slack command factories (#53).
+- Session forks now anchor to raw split points.
+- Adapter-specific stop logic stays in adapters.
+
+### Fixed
+
+- Slack: tighten thread reply triggers.
+
+## [0.2.0-beta.3]
+
+### Added
+
+- Session view: Slack-aware session viewer with branching (#51).
+- Login: built-in credential presets and a redesigned credential portal.
+- Sandbox: image-mode container CPU/memory limits (#50), bridge network isolation, `ffmpeg` in the tools image.
+
+### Fixed
+
+- Discord: normalize thread sessions; queue follow-up messages; persistent channel sessions; hide usage summary by default.
+- Events: restore Slack synthetic notifications (#52).
+- Attachments: wait for downloads before the agent accesses them.
+
+## [0.2.0-beta.2]
+
+### Added
+
+- Per-user vault system for actor-scoped credential isolation (#24).
+- Managed image sandbox (`--sandbox=image:<image>`) (#47).
+- Login flow wired into the runtime; credential onboarding server (#32, #34).
+- Slack: `/pi-new` and `/pi-login` DM commands.
+- Events: actor-aware scheduling tool (#36, #39).
+
+### Changed
+
+- Internal contracts unified around "conversation" naming across adapter, store, config, log, and UI layers (#38, #41, #42, #43, #44, #46).
+
+### Fixed
+
+- Telegram: handle bare `stop` in shared chats; escape unsupported HTML entities.
+- Slack: queue follow-up messages per session.
+
+## [0.2.0-beta.1]
+
+### Added
+
+- File-backed credential vault (#31) and per-user vault routing (#33).
+- OAuth: GitHub redirect flow, scope parity with `gh` CLI, gcloud OAuth.
+- Sandbox: separate `stateDir` from `workspaceDir` to keep secrets out of sandboxes.
+
+### Security
+
+- Hardened vault writes, file permissions, and login flow.
+- Stopped leaking secrets in `docker exec` args.
+- Enforced vault sandbox isolation policy.
+
+### Changed
+
+- Renamed `docker` sandbox mode to `container` (breaking).
+- Replaced `DockerProvisioner` with `DockerContainerManager` + idle stop.
+
+## [0.2.0-beta.0]
+
+### Added
+
+- Sentry integration for error monitoring, tracing, and metrics (#21).
+- Persistent session management with in-thread replies (#18).
+- Telegram: native slash commands; private-chat session fix (#15).
+- `pi-coding-agent` extension loading (#12).
+
+## Earlier releases
+
+For releases prior to `0.2.0-beta.0` (i.e. the `0.1.x` line), see the [git tag history](https://github.com/geminixiang/mikan/tags).

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Original work Copyright (c) 2024 Mario Zechner
+Modified work Copyright (c) 2025 geminixiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,297 @@
+# mikan
+
+[![npm version](https://img.shields.io/npm/v/@geminixiang/mikan.svg)](https://www.npmjs.com/package/@geminixiang/mikan)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A multi-platform AI coding agent for Slack, Telegram, and Discord.
+
+## Features
+
+- **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 | `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 >= 22.19.0
+
+## Installation
+
+```bash
+npm install -g @geminixiang/mikan
+```
+
+Or from source:
+
+```bash
+npm install && npm run build
+```
+
+## Quick Start
+
+All platforms share the same CLI:
+
+```bash
+mikan [--state-dir=~/.mikan] [--sandbox=<mode>] <working-directory>
+```
+
+Set the platform tokens you need (you can run multiple platforms at once):
+
+```bash
+export SLACK_APP_TOKEN=xapp-...
+export SLACK_BOT_TOKEN=xoxb-...
+export TELEGRAM_BOT_TOKEN=123456:ABC-...
+export DISCORD_BOT_TOKEN=MTI...
+```
+
+### 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
+
+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
+
+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.
+
+## Sandbox Modes
+
+| 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)        |
+
+Vault routing: `image`, `firecracker`, and `cloudflare` resolve a vault per platform userId. See [docs/sandbox.md](docs/sandbox.md) for the full matrix.
+
+### Managed per-user containers (`image:*`)
+
+```bash
+docker pull ghcr.io/geminixiang/mikan-sandbox:latest
+mikan --sandbox=image:ghcr.io/geminixiang/mikan-sandbox:latest /path/to/workspace
+```
+
+Or build locally:
+
+```bash
+docker build -f docker/mikan-sandbox.Dockerfile -t mikan-sandbox:tools .
+```
+
+mikan 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.
+
+### Firecracker / Cloudflare
+
+See [docs/firecracker-setup.md](docs/firecracker-setup.md) and [examples/cloudflare-sandbox-bridge/README.md](examples/cloudflare-sandbox-bridge/README.md).
+
+## `/login` and Web Session Viewer
+
+```bash
+export LINK_URL="https://mikan.example.com"   # public base URL
+export LINK_PORT=8181                         # optional, defaults to 8181
+```
+
+For local testing you can set just `LINK_PORT`; mikan will use `http://localhost:<port>`.
+
+Every environment variable also supports a `MIKAN_` prefix for deployment-specific namespacing. For example, `MIKAN_SLACK_APP_TOKEN` and `MIKAN_LINK_URL` are accepted fallbacks. Unprefixed variables take precedence.
+
+- `/login` / `/pi-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), [Google Cloud SDK / gcloud](docs/oauth/google-cloud-sdk.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-6:off`.
+- `auto-reply` / `/pi-auto-reply on|off|status` controls group/channel auto-reply for the current conversation. Rules live in the conversation's `auto-reply` marker file.
+- `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`, `/pi-auto-reply`, and `/pi-new`.
+
+Credentials are stored under `<state-dir>/vaults` (default `~/.mikan/vaults`). Vault env is only injected in `container`, `image`, `firecracker`, and `cloudflare` modes.
+
+Shared login profiles live under `<state-dir>/vaults/shared/<name>`. `/pi-login copy <name>` merge-copies that shared profile into the current conversation vault: shared env keys overwrite matching conversation env keys, conversation-only env keys are kept, and files from the shared profile overwrite files at the same relative path. To seed every new managed sandbox vault from a shared profile, fill in `sandbox.defaultSharedVault` in `<state-dir>/settings.json` (onboard creates it as an empty string), for example `{ "sandbox": { "defaultSharedVault": "claw" } }`. Empty string disables the default. The default profile is copied only when the target vault does not exist yet.
+
+## Configuration
+
+mikan reads global settings from `<state-dir>/settings.json` (default `~/.mikan/settings.json`, override via `--state-dir` or `STATE_DIR`). This file is required and is created explicitly with `mikan --onboard`. Per-conversation settings live at `<workingDir>/<conversationId>/settings.json` and override global settings for that conversation.
+
+```json
+{
+  "llm": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "off"
+  },
+  "sentry": {
+    "dsn": "https://examplePublicKey@o0.ingest.sentry.io/0"
+  },
+  "sandbox": {
+    "cpus": "0.5",
+    "memory": "512m",
+    "boost": {
+      "cpus": "2",
+      "memory": "4g"
+    }
+  }
+}
+```
+
+| Field                  | Default             | Description                                           |
+| ---------------------- | ------------------- | ----------------------------------------------------- |
+| `llm.provider`         | `anthropic`         | AI provider                                           |
+| `llm.model`            | `claude-sonnet-4-6` | Model name                                            |
+| `llm.thinkingLevel`    | `off`               | `off` / `low` / `medium` / `high`                     |
+| `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                   |
+| `sandbox.boost.cpus`   | unset               | Temporary CPU limit used by `/pi-sandbox boost`       |
+| `sandbox.boost.memory` | unset               | Temporary memory limit used by `/pi-sandbox boost`    |
+
+`/pi-sandbox` shows the current managed-container CPU/memory limits. `/pi-sandbox boost` temporarily applies `sandbox.boost` to the current conversation; the boost ends when that sandbox container is stopped.
+
+Conversation-local settings written by `/pi-model` use the same shape and usually only include the override:
+
+```json
+{
+  "llm": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "thinkingLevel": "off"
+  }
+}
+```
+
+mikan writes logs to stdout/stderr. Use your process manager or host platform (for example PM2, systemd, Docker, or a cloud logging agent) to route logs to your preferred backend.
+
+## Layout
+
+```
+<state-dir>/
+├── settings.json
+└── vaults/
+    └── <vault-id>/
+        ├── env
+        └── ...                # credential files
+
+<working-directory>/
+├── MEMORY.md                  # global memory
+├── SYSTEM.md                  # installed packages / env log
+├── skills/                    # global skills
+├── events/                    # scheduled events
+└── <conversation-id>/
+    ├── MEMORY.md
+    ├── auto-reply[.disabled]    # optional channel auto-reply rules
+    ├── log.jsonl
+    ├── attachments/
+    ├── scratch/
+    ├── skills/
+    └── sessions/
+```
+
+## Events
+
+Drop JSON files into `<working-directory>/events/`:
+
+```json
+// Immediate
+{"type": "immediate", "platform": "slack", "conversationId": "C0123456789", "conversationKind": "shared", "text": "Deploy finished"}
+
+// One-shot
+{"type": "one-shot", "platform": "telegram", "conversationId": "574247312", "conversationKind": "direct", "text": "Standup", "at": "2025-12-15T09:00:00+08:00"}
+
+// Periodic (cron)
+{"type": "periodic", "platform": "discord", "conversationId": "1498975469343739948", "conversationKind": "shared", "text": "Check inbox", "schedule": "0 9 * * 1-5", "timezone": "Asia/Taipei"}
+```
+
+## Skills
+
+```
+skills/my-tool/
+├── SKILL.md      # name + description frontmatter, usage docs
+└── run.sh
+```
+
+```yaml
+---
+name: my-tool
+description: Does something useful
+---
+
+Usage: {baseDir}/run.sh <args>
+```
+
+## Slack: Download channel history
+
+```bash
+mikan --download C0123456789
+```
+
+## Production deployment (PM2)
+
+For long-running deployments, use [PM2](https://pm2.keymetrics.io/) as a process supervisor. It daemonizes mikan, restarts on crash, and survives reboots.
+
+```bash
+# 1. Install mikan and pm2
+npm i -g @geminixiang/mikan pm2
+
+# 2. Start the sandbox container (long-lived; mikan execs into it)
+docker pull ghcr.io/geminixiang/mikan-sandbox:latest
+
+# 3. Grab the ecosystem file, edit args + env tokens, then start
+curl -O https://raw.githubusercontent.com/geminixiang/mikan/main/deploy/pm2/ecosystem.config.cjs
+pm2 start ecosystem.config.cjs
+pm2 save
+pm2 startup        # run the printed command to enable boot autostart
+```
+
+Upgrade flow:
+
+```bash
+npm i -g @geminixiang/mikan && pm2 reload mikan
+```
+
+`pm2 reload` sends SIGTERM and waits up to `kill_timeout` (60s in the shipped config) before SIGKILL. mikan's internal graceful shutdown drains in-flight LLM turns within that window, so reloads do not interrupt active conversations.
+
+See [`deploy/pm2/ecosystem.config.cjs`](deploy/pm2/ecosystem.config.cjs) for all tunables.
+
+## Development
+
+```bash
+npm run dev         # build in watch mode
+npm test            # unit tests (vitest)
+npm run lint        # oxlint
+npm run fmt:check   # oxfmt (use `npm run fmt` to auto-fix)
+npm run build       # type check + emit dist/
+```
+
+### End-to-end tests
+
+E2E suites under `e2e/` exercise real platform APIs and are kept off the default `npm test` run.
+
+```bash
+npm run test:e2e          # all platforms
+npm run test:e2e:slack    # Slack only
+```
+
+Slack E2E requires `SLACK_QA_USER_TOKEN`, `SLACK_QA_CHANNEL_ID`, and `SLACK_QA_BOT_USER_ID` against a dedicated test workspace. See [`docs/slack-qa-test-plan.md`](docs/slack-qa-test-plan.md) for setup.
+
+## Contributing
+
+PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, commit style, and the testing checklist. Bug reports and feature requests go through the GitHub issue templates.
+
+## License
+
+MIT — see [LICENSE](LICENSE).