min-agent 0.3.0 → 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,46 +24,63 @@ 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 --provider <name> "msg"   # Use a specific provider
-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                  # Check for updates and upgrade
+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 (↑↓ navigate, Enter select, Esc close). All commands also work by typing them directly:
+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]` | Interactive model picker (↑↓ navigate, Enter confirm) |
 | `/provider [name]` | List/switch provider |
 | `/plan` | Toggle read-only plan mode |
-| `/memory [text]` | List/save memory |
-| `/tokens` | Context usage & cost |
-| `/budget [n]` | Show/set cost budget (USD) |
+| `/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` | List saved sessions |
+| `/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 |
@@ -72,9 +91,11 @@ Type `/` in the interactive session to pop up a command menu (↑↓ navigate, E
 | `/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** 滚动，不必翻到消息区底部。提问输入行同样固定可见。
+
+**鼠标** 在消息区拖拽选择文本，松开自动复制；双击选词、三击选中该条可见内容。复制时不含 `>` 与工具前缀。状态栏会短暂提示"已复制"。
 
 ---
 
@@ -92,7 +113,7 @@ All config in `~/.min-agent/`:
       "baseURL": "https://api.openai.com/v1",
       "apiKey": "sk-...",
       "defaultModel": "gpt-5.5",
-      "contextWindow": 128000
+      "contextWindow": 1000000
     }
   ],
   "activeProvider": "default",
@@ -106,25 +127,80 @@ All config in `~/.min-agent/`:
 }
 ```
 
-Project-level config lives in `.min-agent/config.json` and currently holds skill state only:
+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"]
+  "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)
+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)
 
 ---
 
@@ -147,6 +223,8 @@ 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` 只生成子集，其余手写）：
@@ -216,8 +294,9 @@ metadata:
 
 - `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 path overrides the earlier one; within one path the top-level `SKILL.md` wins over a nested copy.
-- `MIN_AGENT_SKILLS_DIRS` (path-delimiter separated) replaces the discovery list entirely.
+- 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
@@ -232,6 +311,8 @@ metadata:
 
 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: "...",
@@ -243,6 +324,7 @@ 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")
@@ -270,11 +352,12 @@ Full reference: [docs/API.md](docs/API.md)
 | Variable | Description |
 |----------|-------------|
 | `EXA_API_KEY` | Enable Exa code search |
-| `MIN_AGENT_SERPER_API_KEY` | Serper key for `search_web` (default backend; takes precedence over `serperApiKey` in config) |
+| `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 default skill discovery list |
+| `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 (without a token, only localhost origins are allowed) |