min-agent 0.2.1 → 0.4.0

package/README.md

@@ -6,15 +6,17 @@ Minimal AI coding agent for the terminal. Works with any OpenAI-compatible API.
 
 ```bash
 npm install -g min-agent
+min-agent update              # Upgrade to the latest npm release
 ```
 
 ## Quick Start
 
 ```bash
 min-agent setup              # Configure provider
-min-agent chat "hello"       # Single message
-min-agent chat               # Interactive session
-min-agent code               # Project-aware coding mode
+min-agent                    # Interactive session
+min-agent "hello"            # Interactive session, send immediately
+min-agent exec "hello"       # One-shot, then exit
+min-agent exec --resume <id> "continue"  # Continue a saved one-shot session
 ```
 
 ---
@@ -22,38 +24,78 @@ min-agent code               # Project-aware coding mode
 ## Commands
 
 ```bash
-min-agent chat [message]          # Chat (interactive if no message)
-min-agent chat -m <model> "msg"   # Override model
-min-agent chat -i img.png "msg"   # Attach image
-min-agent chat --resume <id>      # Resume session
-min-agent code                    # AI coding mode (project scan)
+min-agent                         # Interactive session
+min-agent "msg"                   # Interactive session, send immediately
+min-agent exec "msg"              # One-shot, then exit
+min-agent exec --resume <id> "msg" # Continue a saved one-shot session
+min-agent -m <model> "msg"        # Override model
+min-agent --provider <name> "msg" # Use a specific provider
+min-agent -i img.png "msg"        # Attach image
+min-agent --resume <id>           # Resume session
+min-agent chat | code             # Same as interactive session (compat)
 min-agent setup                   # Configure API provider
 min-agent models                  # List available models
 min-agent history                 # List saved sessions
+min-agent history delete <id>     # Delete a session
+min-agent history rename <id> <t> # Rename a session
+min-agent history export <id> [-o file]  # Export a session as JSON
+min-agent update                  # Upgrade to the latest npm release
 min-agent rules                   # Show loaded rules
 min-agent rules edit              # Edit global rules
-min-agent memory                  # List memories
-min-agent memory add "text"       # Save memory
+min-agent memory                  # List project + global memories
+min-agent memory add "text"       # Save memory (project if .min-agent exists)
+min-agent memory add "text" --project
+min-agent memory add "text" --global
 min-agent mcp -h                  # MCP server management
 min-agent skills -h               # Skills management
+min-agent sandbox                 # Show isolation
+min-agent sandbox off             # Write isolation to config and exit
+min-agent --sandbox workspace "msg"  # This session only; does not write config
+min-agent sandbox network deny --project
+min-agent permission              # Show confirmation mode
+min-agent --permission ask        # Write confirmation mode to config and exit
+min-agent --permission accept-edits --project
+min-agent --permission allow-all "msg"  # This session only
 min-agent serve                   # Start HTTP API server
 ```
 
 ## Interactive Commands
 
+Type `/` in the interactive session to pop up a command menu (type to filter, Tab/Enter select, Esc close). **↑↓** in the input box recall previously sent messages, skipping slash commands. All commands also work by typing them directly:
+
 | Command | Description |
 |---------|-------------|
-| `/clear` | Clear history |
+| `/new` | Start a new session (keeps the current one) |
 | `/compact` | Force compaction |
-| `/model [name]` | Show/change model |
-| `/memory [text]` | List/save memory |
-| `/tokens` | Context usage |
+| `/model [name]` | Interactive model picker (↑↓ navigate, Enter confirm) |
+| `/provider [name]` | List/switch provider |
+| `/plan` | Toggle read-only plan mode |
+| `/memory [text]` | List/save memory (`--project` writes to this repo) |
+| `/tokens` | Context occupancy, session totals & cost |
+| `/budget [n]` | Show/set cost budget (USD; `--project` writes to this repo) |
+| `/permission` | Show/set confirmation (`ask` / `accept-edits` / `allow-all`; `--project` writes to this repo) |
+| `/sandbox` | Show/set isolation (`off` / `workspace` / `strict`; `--project` writes to this repo) |
+| `/undo` | Undo last turn |
+| `/redo` | Resend last message |
+| `/diff` | Show working tree diff |
+| `/sessions [id]` | List or switch saved sessions |
+| `/resume [id]` | Same as `/sessions` |
+| `/reload` | Reload rules |
+| `/rename <title>` | Rename current session |
+| `/attach <path>` | Attach a local image |
 | `/paste [text]` | Clipboard image |
+| `/mcp` | MCP server status |
+| `/skills` | List skills; `/skills info <name>` to view; `/skills enable\|disable <name>` to toggle |
+| `/models` | List available models |
 | `/path` | Working directory |
 | `/help` | All commands |
 | `/exit` | Exit |
 
-**Ctrl+C** interrupts current generation.
+**Ctrl+C** clears the input box and saves it to history (↑ / ↓ to recall). Press **Ctrl+C twice** on an empty input to exit; the current session is saved. While generating, it interrupts the current run. **Ctrl+B** enters message selection mode (arrow keys expand the selection, Enter copies, Esc exits). **↑ / ↓** in the input box recall previously typed or sent messages. **Home / End** move to the start or end of the line.
+
+授权确认时 **[y] / [N]** 始终留在窗口底部；详情过长时用 **↑↓** 或 **PageUp / PageDown** 滚动，不必翻到消息区底部。提问输入行同样固定可见。
+
+**鼠标** 在消息区拖拽选择文本，松开自动复制；双击选词、三击选中该条可见内容。复制时不含 `>` 与工具前缀。状态栏会短暂提示"已复制"。
 
 ---
 
@@ -64,52 +106,199 @@ All config in `~/.min-agent/`:
 ```json
 // ~/.min-agent/config.json
 {
-  "provider": {
-    "type": "openai-compatible",
-    "baseURL": "https://api.openai.com/v1",
-    "apiKey": "sk-...",
-    "defaultModel": "gpt-5.5",
-    "contextWindow": 128000
-  },
+  "providers": [
+    {
+      "name": "default",
+      "type": "openai-compatible",
+      "baseURL": "https://api.openai.com/v1",
+      "apiKey": "sk-...",
+      "defaultModel": "gpt-5.5",
+      "contextWindow": 1000000
+    }
+  ],
+  "activeProvider": "default",
+  "webSearchURL": "https://your-searxng.example.com",
+  "serperApiKey": "your-serper-key",
   "instructions": ["./docs/rules.md"],
-  "disabledSkills": []
+  "disabledSkills": [],
+  "pricing": { "gpt-5.5": { "inputPerMillion": 1.25, "outputPerMillion": 10 } },
+  "sampling": { "temperature": 0.7, "maxTokens": 4096 },
+  "budget": { "maxCostUSD": 5 }
+}
+```
+
+Project-level config lives in `.min-agent/config.json`. It can override skill state and selected global settings; API keys stay in `~/.min-agent/config.json` only:
+
+```json
+// .min-agent/config.json
+{
+  "disabledSkills": ["noisy-skill"],
+  "enabledSkills": ["skill-disabled-globally"],
+  "activeProvider": "default",
+  "defaultModel": "gpt-5.5",
+  "sampling": { "temperature": 0.4 },
+  "budget": { "maxCostUSD": 2 },
+  "permission": "ask",
+  "sandbox": { "mode": "workspace", "network": "allow" },
+  "compaction": { "autoContinue": false }
 }
 ```
 
+Project values overlay the global file when present (`sampling` / `budget` / `sandbox` / `compaction` / `agent` merge field-by-field). `/budget 5 --project` writes the project budget. `/sandbox workspace --project` writes project isolation. `/permission accept-edits --project` writes project confirmation mode.
+
+Isolation is **off by default**. `--permission` / `--yes` only skip confirmations; they do not change isolation.
+
+`--permission ask|accept-edits|allow-all` without a message writes config and exits (same as `min-agent permission …`). With a message, `--resume`, `--model`, or `--provider`, it only overrides that session. `--yes` / `-y` is this session only (same as `--permission allow-all`) and does not write config.
+
+```bash
+min-agent permission                         # show current confirmation mode
+min-agent --permission ask                   # write global config, then exit
+min-agent --permission accept-edits --project
+min-agent --permission allow-all "msg"       # this session only; does not write config
+```
+
+`ask` (default) prompts before dangerous operations. `accept-edits` auto-approves file writes and still prompts for dangerous commands. `allow-all` auto-approves everything.
+
+Without a message, `--sandbox` / `--network` write config and exit (same as `min-agent sandbox …`). With a message, `--resume`, `--model`, or `--provider`, they only override that session:
+
+```bash
+min-agent sandbox                      # show current isolation
+min-agent --sandbox off                # write global config, then exit
+min-agent --sandbox workspace --project
+min-agent --sandbox workspace "msg"    # this session only; does not write config
+min-agent sandbox network deny
+```
+
+```json
+"sandbox": {
+  "mode": "workspace",
+  "network": "allow",
+  "extraWriteRoots": ["/path/allowed-to-write"],
+  "extraReadRoots": []
+}
+```
+
+`mode`: `off` (default) | `workspace` (write only in the working directory, plus temp/cache) | `strict` (read and write only there). `extraWriteRoots` / `extraReadRoots` add extra directories when isolation is on. Env: `MIN_AGENT_SANDBOX`, `MIN_AGENT_SANDBOX_NETWORK`.
+
+Project memories live in `.min-agent/memory.json`; global memories in `~/.min-agent/memory.json`. The agent reads project first, then global. Saving without `--project` / `--global` uses the project file when `.min-agent/` exists.
+
+`pricing` 覆盖模型价格（USD / 1M tokens），用于成本估算；未配置时自动从 models.dev 获取。
+
+Multiple providers are supported: add entries to `providers` and set `activeProvider` (or use `min-agent setup`). Old single-provider configs are migrated automatically on first run.
+
+`contextWindow` 填写该模型的上下文长度（token）。自定义接口请按实际容量填写，例如 100 万填 `1000000`。未填写时会向接口查询；查不到时按 512k 处理。旧的工具输出会自动省略，避免占满上下文。
+
+`sampling` sets defaults for temperature/maxTokens/topP (overridable per request). `budget.maxCostUSD` aborts the current run as soon as cumulative cost exceeds the limit (checked after each model step).
+
+A run continues in one model pass until the model finishes, the context fills (~75% of the window), the reply comes back empty, or a tool-only turn has no final answer. Context overflow and empty turns auto-continue up to `agent.maxContinues` times (default 40). Set `agent.autoContinue` to `false` to stop and wait for the next message (web research that has not yet produced the requested file or answer still continues, and further search/fetch calls return a notice to write from what is already known). If `agent.autoContinue` is omitted, `compaction.autoContinue` is used (default true). Optional `agent.maxSteps` is a hard tool-step ceiling for one pass (unset means no ceiling). When the provider answers with an empty stream (HTTP 200 and no content at all — usually an upstream timeout), the same request is re-sent up to `agent.maxEmptyAttempts` times (default 4; first retry immediate, then exponential backoff from `agent.emptyRetryDelayMs`, default 1000 ms) regardless of `autoContinue`, and the run then reports that the provider returned nothing instead of a vague "incomplete". Task lists and the original request are stored with the session and survive compaction. Repeated identical tool calls are stopped. Long stretches of web search/fetch without producing the requested output are redirected to finish the work; further search/fetch calls then return that same notice instead of new results.
+
+A turn also has a time / step budget (`agent.turnTimeLimitMs`, default 20 min; `agent.softStepLimit`, default 120 tool steps). When it runs out the model is asked once to wrap up and summarise, then the turn stops — a finished answer is never overridden by the budget. Model requests are guarded by a first-byte timeout (`agent.requestTimeoutMs`, default 180 s) and a stream idle timeout (`agent.streamIdleTimeoutMs`, default 90 s); a stalled request is aborted and retried like an empty reply. Old tool payloads are only trimmed once the context is filling up (60% of the window), biggest first, and each stub keeps the path of the full output on disk so the model can read it again. Sessions are written incrementally during a run, so a crash keeps the work done so far. `bash` commands are killed after `tools.bashTimeoutMs` (default 10 min) unless the call sets its own timeout. Sub-agents (`task`, `explore`) share the parent's research and cost budget; their step ceilings are `agent.subAgentMaxSteps` / `agent.exploreMaxSteps`.
+
+Research is judged by what it returns: rounds that bring new URLs or domains are free (up to `agent.researchTotalCap`, default 24 calls per turn), while `agent.researchSteerAfter` (default 3) rounds without a new source steer the model to write, and `agent.researchStopAfter` (default 5) removes `search_web` / `web_fetch` for the rest of the turn.
+
 Provider types: `openai-compatible` | `openai` | `ollama`
 
+Logs: `~/.min-agent/logs/min-agent.YYYY-MM-DD.log` (rotated daily, kept 7 days). Lines inside a run carry `[run=<id> pass=<n>]`. Set `MIN_AGENT_TRACE=1` to also log a summary of every model request and response (model, message/tool counts, status, time to first byte).
+
+Input history: `~/.min-agent/input-history.json` (up to 1000 entries)
+
 ---
 
 ## MCP
 
 ```bash
 min-agent mcp add <name> <cmd...>              # Local stdio
+min-agent mcp add <name> <cmd...> --env K=V    # Local stdio with env vars
 min-agent mcp add <name> --url <url> --token T # Remote HTTP
-min-agent mcp list                             # List (name + status)
+min-agent mcp add <name> --url <url> --sse     # Legacy SSE transport
+min-agent mcp add <name> --url <url> --streamable-http  # Force streamable HTTP
+min-agent mcp add <name> ... --project         # Save to .min-agent/mcp.json (this repo only)
+min-agent mcp add <name> ... --timeout 10000   # Connection/call timeout in ms
+min-agent mcp list                             # List (name + status + scope)
 min-agent mcp info <name>                      # Details
-min-agent mcp enable/disable <name...>         # Toggle
-min-agent mcp remove <name>                    # Remove
+min-agent mcp enable/disable <name...> [--project]  # Toggle
+min-agent mcp remove <name> [--project]        # Remove
 min-agent mcp check                            # Test connectivity
 ```
 
+配置合并规则：`~/.min-agent/mcp.json`（全局）与 `.min-agent/mcp.json`（项目）按名称合并，项目条目覆盖同名全局条目；`mcp list` 会标注 `[project]`。
+
+Connected servers expose resources and prompts to the agent via `mcp_list_resources` / `mcp_read_resource` / `mcp_list_prompts` / `mcp_get_prompt`. `/mcp` shows counts when a server advertises them.
+
+远程服务器如需 OAuth 登录（部分云端 MCP），在 mcp.json 里加 `"oauth": {}`（或用 `"clientId"`/`"clientSecret"`/`"scope"` 显式指定），连接时自动打开浏览器完成授权，令牌缓存在 `~/.min-agent/mcp-oauth/`。`"oauth": false` 关闭。
+
+mcp.json 完整字段（`min-agent mcp add` 只生成子集，其余手写）：
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+      "environment": { "KEY": "VALUE" },
+      "enabled": true,
+      "connectTimeout": 10000,
+      "callTimeout": 30000
+    },
+    "remote": {
+      "url": "https://mcp.example.com/mcp",
+      "remoteTransport": "auto",
+      "token": "bearer-token",
+      "headers": { "X-API-Key": "..." },
+      "oauth": {},
+      "connectTimeout": 15000,
+      "callTimeout": 30000
+    }
+  }
+}
+```
+
+- `remoteTransport`：`auto`（默认，先 streamable-http 再 sse）、`streamable-http`、`sse`
+- `timeout`：连接与调用共用的旧字段；`connectTimeout` / `callTimeout` 可分别覆盖
+- 连接失败时错误信息会带上服务器 stderr 的最后几行，便于排查
+
 ## Skills
 
 ```bash
-min-agent skills list                          # List (name + status)
-min-agent skills info <name>                   # Details
-min-agent skills enable/disable <name...>      # Toggle
+min-agent skills list                          # List (status + scope + description + path)
+min-agent skills list --json                   # Machine-readable output
+min-agent skills info <name>                   # Details + content
+min-agent skills info <name> --json            # Details as JSON
+min-agent skills new <name>                    # Create a skill scaffold (.min-agent/skills/<name>/)
+min-agent skills new <name> --global           # Create in ~/.agents/skills/<name>/
+min-agent skills disable <name...>             # Disable everywhere (global)
+min-agent skills disable <name...> --project   # Disable in this repo only
+min-agent skills enable <name...> --project    # Re-enable here even if disabled globally
 ```
 
-Create: `.min-agent/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md`
+Scope: project state lives in `.min-agent/config.json`, global state in `~/.min-agent/config.json`.
+Project wins over global, so disabling a repo-local skill never affects other repos.
+
+In the interactive session: `/skills`, `/skills info <name>`, `/skills disable <name> [--project]`, `/skills enable <name> [--project]`.
+Type `/skills ` and press Tab to complete subcommands and skill names.
+
+Create: `min-agent skills new <name>` scaffolds a `SKILL.md` template into `.min-agent/skills/<name>/` (add `--global` for `~/.agents/skills/`), or write it by hand:
 
 ```markdown
 ---
 name: my-skill
 description: What it does
+# optional
+version: 1.0.0
+allowed-tools: [read, grep]
+metadata:
+  requires:
+    bins: ["some-cli"]
 ---
 # Instructions...
 ```
 
+- `description` may use a YAML block scalar (`|` / `>`) for multi-line text.
+- Discovery paths, in override order: `~/.agents/skills/` → `.min-agent/skills/` → `.agents/skills/` → `.opencode/skills/` → `.claude/skills/`. Symlinked skill directories are followed, so one shared skill library can be linked into several of these.
+- A same-named skill in a later user path overrides the earlier one; within one path the top-level `SKILL.md` wins over a nested copy.
+- Built-in skills shipped with min-agent (including `self-config`, which the agent loads automatically when changing its own settings) are always discovered and win on name over user copies.
+- `MIN_AGENT_SKILLS_DIRS` (path-delimiter separated) replaces the user discovery list; built-in skills still load unless `MIN_AGENT_NO_BUILTIN_SKILLS=1`.
+- Files next to `SKILL.md` (including subdirectories such as `scripts/`) are listed for the agent when the skill loads; `metadata.requires.bins` entries missing from `PATH` are reported.
+
 ## Rules
 
 | Source | Scope |
@@ -122,6 +311,8 @@ description: What it does
 
 Custom tools: `.min-agent/tools/*.ts` or `~/.min-agent/tools/*.ts`
 
+By default a custom tool asks before it runs. Set `readOnly: true` (or `dangerous: false`) to skip the prompt. Plan mode only keeps `readOnly` custom tools.
+
 ```typescript
 export const myTool = {
   description: "...",
@@ -130,6 +321,20 @@ export const myTool = {
 }
 ```
 
+```typescript
+export const dockerPs = {
+  description: "List running docker containers",
+  readOnly: true,
+  parameters: { limit: { type: "number", description: "Max containers to show" } },
+  execute: async ({ limit }) => {
+    const { execSync } = await import("child_process")
+    return execSync(`docker ps --format "table {{.Names}}\t{{.Status}}" --limit ${limit ?? 10}`, {
+      encoding: "utf-8",
+    })
+  }
+}
+```
+
 ---
 
 ## HTTP API
@@ -147,9 +352,15 @@ Full reference: [docs/API.md](docs/API.md)
 | Variable | Description |
 |----------|-------------|
 | `EXA_API_KEY` | Enable Exa code search |
+| `MIN_AGENT_SERPER_API_KEY` | Optional Serper key override for `search_web` (takes precedence over `serperApiKey` in config; a built-in default is used otherwise) |
+| `MIN_AGENT_SEARXNG_URL` | Use SearXNG instead of Serper for `search_web` (takes precedence over `webSearchURL` in config) |
+| `MIN_AGENT_SEARXNG_FALLBACK_ENGINES` | Engines retried when the SearXNG instance's default engines return nothing (default `google,bing`; empty string disables the retry) |
+| `MIN_AGENT_FIRECRAWL_URL` | Firecrawl instance for `web_fetch` (takes precedence over `webFetchURL` in config) |
+| `MIN_AGENT_SKILLS_DIRS` | `:`-separated dirs that replace the user skill discovery list (built-in skills still load) |
+| `MIN_AGENT_NO_BUILTIN_SKILLS` | `1` to skip skills shipped with min-agent |
 | `MIN_AGENT_SHOW_THINKING` | `0` to hide thinking |
 | `MIN_AGENT_SERVE_TOKEN` | API auth token |
-| `MIN_AGENT_SERVE_CORS` | `1` to enable CORS |
+| `MIN_AGENT_SERVE_CORS` | `1` to enable CORS (without a token, only localhost origins are allowed) |
 
 ## License