min-agent 0.3.0 → 0.4.0

package/skills/self-config/reference.md

@@ -0,0 +1,149 @@
+# self-config field catalog
+
+Read this when you need exact keys. Files are strict JSON.
+
+## Global `~/.min-agent/config.json`
+
+```json
+{
+  "providers": [
+    {
+      "name": "default",
+      "type": "openai-compatible",
+      "baseURL": "https://api.openai.com/v1",
+      "apiKey": "sk-...",
+      "defaultModel": "gpt-5.5",
+      "contextWindow": 1000000
+    }
+  ],
+  "activeProvider": "default",
+  "webSearchURL": "https://searxng.example.com",
+  "webSearchFallbackEngines": "google,bing",
+  "serperApiKey": "your-serper-key",
+  "webFetchURL": "https://firecrawl.example.com",
+  "instructions": ["./docs/rules.md"],
+  "disabledSkills": [],
+  "permission": "ask",
+  "sandbox": {
+    "mode": "off",
+    "network": "allow",
+    "extraWriteRoots": [],
+    "extraReadRoots": []
+  },
+  "pricing": { "gpt-5.5": { "inputPerMillion": 1.25, "outputPerMillion": 10 } },
+  "sampling": { "temperature": 0.7, "maxTokens": 4096, "topP": 1 },
+  "budget": { "maxCostUSD": 5 },
+  "compaction": { "model": "gemini-2.0-flash", "autoContinue": true },
+  "tools": { "bashTimeoutMs": 600000 },
+  "agent": {
+    "maxSteps": 40,
+    "maxContinues": 40,
+    "autoContinue": true,
+    "maxEmptyAttempts": 4,
+    "emptyRetryDelayMs": 1000,
+    "requestTimeoutMs": 180000,
+    "streamIdleTimeoutMs": 90000,
+    "turnTimeLimitMs": 1200000,
+    "softStepLimit": 120,
+    "subAgentMaxSteps": 15,
+    "exploreMaxSteps": 20,
+    "researchSteerAfter": 3,
+    "researchStopAfter": 5,
+    "researchTotalCap": 24
+  }
+}
+```
+
+- `contextWindow`: tokens; omit to query the API, then 512k fallback.
+- `agent.autoContinue` omitted → uses `compaction.autoContinue` (default true).
+- `agent.maxSteps` omitted → no tool-step ceiling.
+- `agent.maxEmptyAttempts` / `agent.emptyRetryDelayMs`: retries when the provider returns an empty stream (HTTP 200, no content). First retry is immediate, later ones back off exponentially, capped at 8s.
+- `agent.requestTimeoutMs` / `agent.streamIdleTimeoutMs`: abort a request that never starts responding, or a stream that goes quiet mid-response; the run then retries it like an empty reply. 0 disables. Env overrides: `MIN_AGENT_REQUEST_TIMEOUT_MS`, `MIN_AGENT_STREAM_IDLE_TIMEOUT_MS`.
+- `agent.turnTimeLimitMs` / `agent.softStepLimit`: budget for one turn. On expiry the model is asked to wrap up once, then the turn stops. 0 disables either half.
+- `agent.subAgentMaxSteps` / `agent.exploreMaxSteps`: step ceilings for the `task` and `explore` sub-agents. Sub-agents share the parent's research budget and cost budget.
+- `agent.researchSteerAfter` / `researchStopAfter`: research *rounds that returned no new source* before steering / dropping `search_web` and `web_fetch`; `researchTotalCap` is the hard number of research calls per turn. Productive research (new URLs or domains each round) is not penalised.
+- `tools.bashTimeoutMs`: default kill timeout for `bash` (10 minutes; the model can override per call, 0 disables).
+- `MIN_AGENT_TRACE=1` logs a request/response summary for every model call (model, message and tool counts, status, time to first byte).
+- Web search/fetch that has not yet produced the requested output still continues even when `autoContinue` is false; further search/fetch calls return a stop-and-write notice instead of new results.
+- Old single-provider configs migrate on first run; write the `providers` array for new files.
+
+## Project `.min-agent/config.json`
+
+Allowed keys (no `providers`, no API keys, no search secrets):
+
+`disabledSkills`, `enabledSkills`, `activeProvider`, `defaultModel`, `sampling`, `budget`, `permission`, `sandbox`, `compaction`, `agent`.
+
+Present keys overlay the global file. Nested objects `sampling` / `budget` / `sandbox` / `compaction` / `agent` merge per field. `defaultModel` overrides the active provider's model without copying keys.
+
+## `mcp.json`
+
+```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
+    }
+  }
+}
+```
+
+- `command` may be a string plus `args[]` (Claude/opencode shape).
+- `timeout` is the legacy shared value; `connectTimeout` / `callTimeout` override it.
+- `oauth`: object (optional `clientId` / `clientSecret` / `scope`) or `false`.
+- Tokens for OAuth land in `~/.min-agent/mcp-oauth/`.
+
+## Skills frontmatter
+
+Required: `name`, `description`. Optional: `version`, `allowed-tools` (flow `[read, grep]` or a YAML list), `always-load` (`true` injects the body into the system prompt), `metadata.requires.bins`.
+
+Disable lists are string arrays. A project `enabledSkills` name unblocks a globally disabled skill in this repo only.
+
+## Plugins
+
+`.min-agent/tools/*.ts` (or `~/.min-agent/tools/*.ts`). Each exported object:
+
+```typescript
+export const myTool = {
+  description: "...",
+  parameters: { arg: { type: "string", description: "..." } },
+  execute: async ({ arg }) => "result",
+}
+```
+
+Default: confirm before run. `readOnly: true` or `dangerous: false` skips confirm. Plan mode keeps only `readOnly` custom tools. Export name `default` → tool id is the file basename; other exports → `basename_exportName`.
+
+## Memory `memory.json`
+
+Array of `{ "content": string, "tags": string[], "created": string }`. Prefer memory tools.
+
+## Environment overrides
+
+| Variable | Role |
+|----------|------|
+| `MIN_AGENT_CONFIG_DIR` | Replaces `~/.min-agent` |
+| `MIN_AGENT_SKILLS_DIRS` | Replaces user skill roots (path-delimiter separated) |
+| `MIN_AGENT_NO_BUILTIN_SKILLS` | `1` / `true` skips packaged skills |
+| `MIN_AGENT_SANDBOX` / `MIN_AGENT_SANDBOX_NETWORK` | Isolation |
+| `MIN_AGENT_SERPER_API_KEY` | Overrides `serperApiKey` |
+| `MIN_AGENT_SEARXNG_URL` | Overrides `webSearchURL` (SearXNG instead of Serper) |
+| `MIN_AGENT_SEARXNG_FALLBACK_ENGINES` | Default `google,bing`; empty string disables retry |
+| `MIN_AGENT_FIRECRAWL_URL` | Overrides `webFetchURL` |
+| `EXA_API_KEY` | Enables Exa code search |
+| `MIN_AGENT_SERVE_TOKEN` / `MIN_AGENT_SERVE_CORS` | HTTP server |
+
+## HTTP (only if the user is running `min-agent serve`)
+
+Skills: `GET /v1/skills`, `GET /v1/skills/:name`, `POST /v1/skills/reload`, `POST /v1/skills/:name/enable|disable` with `{ "scope": "project"|"global" }`. MCP enable/disable similarly. Full list is `docs/API.md` in the min-agent package; do not treat that file as this skill's replacement.