min-agent 0.1.4 → 0.1.6

package/dist/tools/task.js

@@ -0,0 +1,98 @@
+import { tool, jsonSchema, streamText, stepCountIs } from "ai";
+import { resolveModel } from "../provider.js";
+import { createTools } from "./index.js";
+import { getMcpTools } from "../mcp.js";
+import { getSkillsTool, getSkills } from "../skills.js";
+import { loadPluginTools } from "../plugins.js";
+import { DoomLoopDetector } from "../doom-loop.js";
+import { stripThinkingFromAssistantText } from "../assistant-stream.js";
+import { truncateToolOutput } from "../tool-output.js";
+const SUB_AGENT_MAX_STEPS = 15;
+const SUB_AGENT_SYSTEM = `You are a focused sub-agent executing a specific task. Complete the task thoroughly and return a clear result.
+
+Rules:
+- Focus only on the assigned task
+- Be thorough but concise
+- Use tools as needed to complete the task
+- Return a clear summary of what you did and the result
+
+Working directory: ${process.cwd()}
+Platform: ${process.platform}
+Date: ${new Date().toDateString()}`;
+export function createTaskTool(modelId) {
+    return tool({
+        description: `Launch a sub-agent to execute a task independently. The sub-agent has its own context and tools. Use this for:
+- Parallel execution: call multiple tasks at once for independent work
+- Context isolation: keep the main conversation clean while the sub-agent explores
+- Delegation: hand off well-defined subtasks (search, analysis, file operations)
+
+The sub-agent can read/write files, run commands, search, and use all available tools.
+Call multiple tasks in parallel when the work is independent.`,
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                description: { type: "string", description: "Short description of the task (shown to user)" },
+                prompt: { type: "string", description: "Detailed instructions for the sub-agent" },
+            },
+            required: ["description", "prompt"],
+        }),
+        execute: async ({ description, prompt }) => {
+            console.log(`\x1b[90m  ┌─ Sub-agent: ${description}\x1b[0m`);
+            try {
+                const result = await runSubAgent(prompt, modelId);
+                console.log(`\x1b[90m  └─ ✓ Done\x1b[0m`);
+                return truncateToolOutput(result, { direction: "head" }).content;
+            }
+            catch (err) {
+                console.log(`\x1b[90m  └─ ✗ Failed: ${err.message}\x1b[0m`);
+                return `Sub-agent error: ${err.message}`;
+            }
+        },
+    });
+}
+async function runSubAgent(prompt, modelId) {
+    const model = resolveModel(modelId);
+    // Build tools for sub-agent (no task tool to prevent recursion)
+    const builtinTools = createTools();
+    const mcpTools = getMcpTools();
+    const pluginTools = await loadPluginTools();
+    const skills = getSkills();
+    const allTools = { ...builtinTools, ...pluginTools };
+    for (const [id, t] of Object.entries(mcpTools))
+        allTools[id] = t;
+    if (skills.length > 0)
+        allTools["skill"] = getSkillsTool();
+    // Remove task tool from sub-agent to prevent infinite recursion
+    delete allTools["task"];
+    const messages = [{ role: "user", content: prompt }];
+    const doomLoop = new DoomLoopDetector();
+    const result = streamText({
+        model,
+        system: SUB_AGENT_SYSTEM,
+        messages,
+        tools: allTools,
+        stopWhen: stepCountIs(SUB_AGENT_MAX_STEPS),
+        maxRetries: 2,
+        onError() { },
+    });
+    let assistantText = "";
+    for await (const event of result.fullStream) {
+        switch (event.type) {
+            case "text-delta":
+                assistantText += event.text;
+                break;
+            case "tool-call":
+                if (doomLoop.record(event.toolName, event.input)) {
+                    return assistantText + "\n\n[Sub-agent stopped: doom loop detected]";
+                }
+                console.log(`\x1b[90m  │ ⚡ ${event.toolName}\x1b[0m`);
+                break;
+            case "tool-result":
+                break;
+            case "error":
+                return assistantText + `\n\n[Sub-agent error: ${event.error}]`;
+        }
+    }
+    const cleaned = stripThinkingFromAssistantText(assistantText);
+    return cleaned || "(sub-agent produced no output)";
+}

package/dist/tools/todo.js

@@ -0,0 +1,88 @@
+import { tool, jsonSchema } from "ai";
+let todos = [];
+let nextId = 1;
+export function getTodos() {
+    return todos;
+}
+export function resetTodos() {
+    todos = [];
+    nextId = 1;
+}
+function formatTodos() {
+    if (todos.length === 0)
+        return "No tasks.";
+    const icons = {
+        pending: "○",
+        in_progress: "◐",
+        done: "●",
+        cancelled: "✕",
+    };
+    return todos
+        .map((t) => `  ${icons[t.status]} #${t.id} ${t.text}`)
+        .join("\n");
+}
+function printTodos() {
+    if (todos.length === 0)
+        return;
+    console.log(`\x1b[90m  ┌─ Tasks${"─".repeat(36)}\x1b[0m`);
+    for (const t of todos) {
+        const icon = t.status === "done" ? "\x1b[32m●\x1b[0m"
+            : t.status === "in_progress" ? "\x1b[33m◐\x1b[0m"
+                : t.status === "cancelled" ? "\x1b[90m✕\x1b[0m"
+                    : "\x1b[90m○\x1b[0m";
+        const dim = t.status === "done" || t.status === "cancelled" ? "\x1b[90m" : "";
+        const reset = dim ? "\x1b[0m" : "";
+        console.log(`\x1b[90m  │\x1b[0m ${icon} ${dim}#${t.id} ${t.text}${reset}`);
+    }
+    console.log(`\x1b[90m  └${"─".repeat(44)}\x1b[0m`);
+}
+export const todoTool = tool({
+    description: `Create or update tasks to track progress. Use this FREQUENTLY to:
+- Plan multi-step work by creating tasks upfront
+- Mark tasks as in_progress when starting them
+- Mark tasks as done when completed
+- Give the user visibility into your progress
+
+To create new tasks: provide items with "text" and optionally "status" (defaults to "pending").
+To update existing tasks: provide items with "id" and "status".
+You can mix creates and updates in one call.`,
+    inputSchema: jsonSchema({
+        type: "object",
+        properties: {
+            todos: {
+                type: "array",
+                description: "List of tasks to create or update",
+                items: {
+                    type: "object",
+                    properties: {
+                        text: { type: "string", description: "Task description (for new tasks)" },
+                        status: { type: "string", description: "Status: pending, in_progress, done, cancelled" },
+                        id: { type: "number", description: "Task ID (for updating existing tasks)" },
+                    },
+                },
+            },
+        },
+        required: ["todos"],
+    }),
+    execute: async ({ todos: items }) => {
+        for (const item of items) {
+            if (item.id) {
+                // Update existing
+                const existing = todos.find((t) => t.id === item.id);
+                if (existing && item.status) {
+                    existing.status = item.status;
+                }
+            }
+            else if (item.text) {
+                // Create new
+                todos.push({
+                    id: nextId++,
+                    text: item.text,
+                    status: item.status ?? "pending",
+                });
+            }
+        }
+        printTodos();
+        return formatTodos();
+    },
+});

package/docs/API.md

@@ -1,216 +1,312 @@
 # min-agent HTTP API
 
-通过 `min-agent serve` 启动本地 HTTP 服务，以编程方式调用与 CLI `chat` 相同的代理能力（同一套 MCP、技能、规则、工具与模型配置）。
+`min-agent serve` 启动本地 HTTP 服务，以编程方式调用代理能力。
 
 ## 启动
 
 ```bash
 min-agent serve
-min-agent serve --host 127.0.0.1 --port 8787
-min-agent serve -p 3030
+min-agent serve --host 0.0.0.0 --port 3000
 ```
 
-环境变量（可选）：
-
-| 变量 | 说明 |
-|------|------|
-| `MIN_AGENT_SERVE_HOST` | 默认监听地址，默认 `127.0.0.1` |
-| `MIN_AGENT_SERVE_PORT` | 默认端口，默认 `8787` |
-| `MIN_AGENT_SERVE_TOKEN` | 若设置，则所有除 `OPTIONS` 外的请求须带 `Authorization: Bearer <token>` |
-| `MIN_AGENT_SERVE_CORS` | 设为 `1` 或 `true` 时添加 `Access-Control-Allow-Origin: *`（仅开发跨域时使用） |
-
-启动后进程内 **`--yes` 等效**：危险 shell 等确认会自动通过，请勿把未鉴权服务暴露到公网。
+| 环境变量 | 说明 |
+|----------|------|
+| `MIN_AGENT_SERVE_HOST` | 监听地址（默认 `127.0.0.1`） |
+| `MIN_AGENT_SERVE_PORT` | 端口（默认 `8787`） |
+| `MIN_AGENT_SERVE_TOKEN` | Bearer token 鉴权 |
+| `MIN_AGENT_SERVE_CORS` | 设为 `1` 启用 CORS |
 
 ---
 
-## 通用约定
+## 端点一览
 
-- **Base URL**：`http://<host>:<port>`
-- **请求体**：JSON，`Content-Type: application/json`
-- **响应体**：JSON，除非注明为 SSE
-- **工作目录**：与启动 `serve` 时的 `process.cwd()` 一致（影响 `read`/`bash` 等工具路径）
-- **单例初始化**：进程启动时连接 MCP、扫描技能并加载规则；之后请求复用该状态。修改规则文件后可调用下方「重载规则」接口或重启进程
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/health` | 存活检查 |
+| GET | `/v1/meta` | 运行环境 |
+| GET | `/v1/models` | 模型列表 |
+| GET | `/v1/context` | 上下文窗口信息 |
+| GET | `/v1/project` | 项目扫描 |
+| POST | `/v1/chat` | 对话 |
+| POST | `/v1/code` | Code 模式对话 |
+| POST | `/v1/paste` | 图片+文本对话 |
+| POST | `/v1/chat/compact` | 手动压缩会话 |
+| POST | `/v1/chat/reload-instructions` | 重载规则 |
+| GET | `/v1/sessions` | 列出会话 |
+| DELETE | `/v1/sessions/:id` | 删除会话 |
+| GET | `/v1/memory` | 列出记忆 |
+| POST | `/v1/memory` | 添加记忆 |
+| GET | `/v1/memory/search?q=xxx` | 搜索记忆 |
+| DELETE | `/v1/memory/:index` | 删除记忆 |
+| GET | `/v1/mcp` | MCP 状态 |
+| POST | `/v1/mcp` | 添加 MCP 服务器 |
+| DELETE | `/v1/mcp/:name` | 删除 MCP 服务器 |
+| GET | `/v1/skills` | 技能列表 |
+| GET | `/v1/rules` | 已加载规则 |
 
 ---
 
 ## `GET /health`
 
-存活检查。
+```json
+{ "ok": true, "service": "min-agent", "version": "0.1.0" }
+```
 
-**响应 200**
+## `GET /v1/meta`
 
 ```json
-{
-  "ok": true,
-  "service": "min-agent",
-  "version": "0.1.0"
-}
+{ "version": "0.1.0", "cwd": "/path/to/project", "instructions_chars": 1234 }
 ```
 
----
+## `GET /v1/models`
 
-## `GET /v1/meta`
+```json
+{ "default_model": "gpt-4o", "models": ["gpt-4o", "gpt-4o-mini"] }
+```
 
-运行环境摘要。
+## `GET /v1/context`
 
-**响应 200**
+```json
+{ "context_window": 128000, "model": "gpt-4o" }
+```
+
+## `GET /v1/project`
 
 ```json
 {
-  "version": "0.1.0",
-  "cwd": "/path/to/project",
-  "instructions_chars": 1234
+  "project": {
+    "directory": "/path",
+    "isGitRepo": true,
+    "branch": "main",
+    "languages": ["TypeScript"],
+    "framework": "Next.js",
+    "packageManager": "bun",
+    "entryFiles": ["src/index.ts"],
+    "configFiles": ["package.json", "tsconfig.json"],
+    "summary": "..."
+  }
 }
 ```
 
 ---
 
-## `GET /v1/models`
+## `POST /v1/chat`
 
-从当前配置的 OpenAI 兼容提供商拉取模型列表（与 CLI `min-agent models` 同源）。
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `message` | string | 用户消息（与 `messages` 二选一） |
+| `messages` | array | 完整 ModelMessage[] |
+| `model` | string | 覆盖模型 |
+| `stream` | boolean | SSE 流式 |
+| `session_id` | string | 恢复会话 |
+| `images` | string[] | 本地图片路径 |
 
-**响应 200**
+### 非流式响应
 
 ```json
 {
-  "default_model": "gpt-4.1",
-  "models": ["gpt-4.1", "gpt-4o-mini", "..."]
+  "messages": [...],
+  "assistant": { "role": "assistant", "content": "..." },
+  "tool_calls": [{ "name": "bash", "input": {...} }],
+  "tool_results": [{ "name": "bash", "output": "..." }],
+  "session_id": "abc123",
+  "step_count": 2,
+  "usage": { "inputTokens": 1200, "outputTokens": 300 },
+  "has_error": false,
+  "aborted": false
 }
 ```
 
----
+### 流式 SSE 事件
 
-## `POST /v1/chat/reload-instructions`
+| type | 字段 | 说明 |
+|------|------|------|
+| `assistant` | text | 正文增量 |
+| `thinking` | text | 思考片段 |
+| `tool_call` | name, input | 工具调用 |
+| `tool_result` | name, output | 工具返回 |
+| `compaction` | line | 压缩进度 |
+| `error` | message | 错误 |
+| `done` | step_count, usage, messages, session_id | 结束 |
+| `fatal` | message | 致命错误 |
 
-重新从磁盘加载 `AGENTS.md`、规则与 `config.json` 中的 instructions 片段（不重启 MCP）。
+---
 
-**响应 200**
+## `POST /v1/code`
 
+Code 模式对话（项目感知 prompt + explore 工具）。请求体与 `/v1/chat` 相同。
+
+响应额外包含：
 ```json
-{
-  "ok": true,
-  "instructions_chars": 1234
-}
+{ "mode": "code", "project": { "languages": [...], ... }, ... }
 ```
 
 ---
 
-## `POST /v1/chat`
-
-执行一轮或多轮对话（与 CLI 使用相同的 `streamText` + 工具集）。
+## `POST /v1/paste`
 
-### 请求体字段
+图片 + 文本多模态对话。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `message` | `string` | 单轮：用户消息文本。与 `messages` 二选一（会话续写见下） |
-| `messages` | `array` | 多轮：完整 `ModelMessage[]`（与 AI SDK 一致：`role` + `content`）。最后一轮通常为用户消息 |
-| `model` | `string` | 可选，覆盖默认模型 |
-| `stream` | `boolean` | 为 `true` 时使用 **SSE** 流式返回 |
-| `session_id` | `string` | 可选，从 `~/.min-agent/sessions/<id>.json` 恢复历史，并追加本条 `message` 为新用户轮 |
-| `images` | `string[]` | 可选，本地图片路径（相对 cwd 或绝对路径），须与顶层 `message` 一起使用，用于构造多模态用户消息 |
+| `image_base64` | string | **必填** Base64 图片数据 |
+| `mime_type` | string | MIME 类型（默认 `image/png`） |
+| `message` | string | 文本 prompt |
+| `model` | string | 覆盖模型 |
+| `session_id` | string | 追加到会话 |
+| `stream` | boolean | SSE 流式 |
 
-### 会话续写 `session_id`
+---
 
-- 请求体必须包含 **`message`**（新用户发言）
-- 服务端加载该会话已有 `messages`，追加新用户消息后调用模型，并在本轮结束后 **写回同一 `session_id`**
+## `POST /v1/chat/compact`
 
-### 非流式 `stream: false`（默认）
+```json
+// 请求
+{ "session_id": "abc123" }
+// 响应
+{ "ok": true, "compacted": true, "message_count": 5 }
+```
 
-**响应 200**
+## `POST /v1/chat/reload-instructions`
 
 ```json
-{
-  "messages": [ ... ],
-  "assistant": { "role": "assistant", "content": "..." },
-  "tool_calls": [{ "name": "bash", "input": { "command": "ls" } }],
-  "tool_results": [{ "name": "bash", "output": "..." }],
-  "session_id": "abc123",
-  "step_count": 2,
-  "usage": { "inputTokens": 1200, "outputTokens": 300, "totalTokens": 1500 },
-  "has_error": false,
-  "aborted": false
-}
+{ "ok": true, "instructions_chars": 1234 }
 ```
 
-- `messages`：已包含本轮助手回复（就地追加，与 CLI 行为一致）
-- `tool_results` 中单条输出过长时会被截断并附带说明后缀
-- 未使用 `session_id` 时 `session_id` 字段为 `undefined`/省略
+---
 
-### 流式 `stream: true`
+## `GET /v1/sessions`
 
-- **Headers**：`Content-Type: text/event-stream`
-- **Body**：SSE，每条事件为一行 `data: <json>\n\n`
+```json
+{ "sessions": [{ "id": "abc", "title": "Fix bug", "updated": "...", "messageCount": 12 }] }
+```
 
-事件 `type` 取值：
+## `DELETE /v1/sessions/:id`
 
-| `type` | 字段 | 说明 |
-|--------|------|------|
-| `assistant` | `text` | 助手正文增量（已剥离思考块，与入库内容一致） |
-| `thinking` | `text` | 模型泄漏的思考片段（若存在） |
-| `tool_call` | `name`, `input` | 工具调用开始 |
-| `tool_result` | `name`, `output` | 工具返回（可能截断） |
-| `compaction` | `line` | 上下文压缩进度说明 |
-| `error` | `message` | 流内模型/鉴权类错误事件 |
-| `done` | `step_count`, `usage`, `has_error`, `aborted`, `messages`, `session_id?` | 本轮结束；之后连接关闭 |
-| `fatal` | `message` | 服务异常，随后关闭 |
+```json
+{ "ok": true, "deleted": "abc123" }
+```
 
-客户端断开连接时会 **Abort** 正在进行的生成；若已有部分正文，仍可能写入 `messages` 中的 assistant（与 CLI Ctrl+C 行为对齐）。
+---
 
-### 错误 HTTP 状态
+## `GET /v1/memory`
 
-| 状态 | 说明 |
-|------|------|
-| `400` | JSON 无效或缺少 `message`/`messages` |
-| `401` | 配置了 `MIN_AGENT_SERVE_TOKEN` 但未携带合法 Bearer |
-| `404` | `session_id` 不存在 |
-| `413` | 请求体超过约 2MB |
-| `415` | 非 `application/json` |
-| `500` | 未配置提供商等内部错误 |
+```json
+{ "memories": [{ "content": "...", "tags": [...], "created": "..." }] }
+```
 
----
+## `POST /v1/memory`
+
+```json
+// 请求
+{ "content": "prefer TypeScript", "tags": ["preference"] }
+// 响应
+{ "ok": true, "memory": {...} }
+```
+
+## `GET /v1/memory/search?q=typescript`
 
-## `OPTIONS *`
+```json
+{ "results": [{ "content": "...", "tags": [...], "index": 0 }] }
+```
 
-当启用 `MIN_AGENT_SERVE_CORS` 时，用于浏览器预检；返回 `204`。
+## `DELETE /v1/memory/:index`
+
+```json
+{ "ok": true, "deleted": 1 }
+```
 
 ---
 
-## 示例
+## `GET /v1/mcp`
 
-### curl：单轮非流式
+```json
+{ "servers": { "filesystem": { "connected": true, "tools": ["read_file", "write_file"] } } }
+```
 
-```bash
-curl -sS http://127.0.0.1:8787/v1/chat \
-  -H "Content-Type: application/json" \
-  -d '{"message":"List files in current directory","model":"gpt-4o-mini"}'
+## `POST /v1/mcp`
+
+```json
+// 本地 stdio
+{ "name": "fs", "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
+// 远程
+{ "name": "remote", "url": "https://mcp.example.com", "token": "xxx" }
 ```
 
-### curl：SSE 流式
+```json
+{ "ok": true, "name": "fs" }
+```
 
-```bash
-curl -sS -N http://127.0.0.1:8787/v1/chat \
-  -H "Content-Type: application/json" \
-  -d '{"message":"Say hi in one sentence","stream":true}'
+## `DELETE /v1/mcp/:name`
+
+```json
+{ "ok": true, "deleted": "fs" }
 ```
 
-### 带鉴权
+---
 
-```bash
-export MIN_AGENT_SERVE_TOKEN=secret
-min-agent serve &
-curl -sS http://127.0.0.1:8787/health \
-  -H "Authorization: Bearer secret"
+## `GET /v1/skills`
+
+```json
+{ "skills": [{ "name": "git-workflow", "description": "...", "location": "..." }] }
+```
+
+## `GET /v1/rules`
+
+```json
+{ "count": 2, "rules": [{ "source": "~/.min-agent/rules.md", "chars": 456 }] }
 ```
 
 ---
 
-## 与 OpenCode / 其他客户端的对比说明
+## 错误码
 
-本 API **不是** OpenAI Chat Completions 的完全兼容实现；字段与事件名为 min-agent 专用。若需对接现有 OpenAI SDK，请在网关层做映射。
+| 状态 | 说明 |
+|------|------|
+| 400 | 请求参数错误 |
+| 401 | 未授权 |
+| 404 | 资源不存在 |
+| 413 | 请求体过大（>2MB） |
+| 415 | Content-Type 不是 JSON |
+| 500 | 内部错误 |
 
 ---
 
-## 版本
+## 示例
+
+```bash
+# 对话
+curl http://127.0.0.1:8787/v1/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message":"list files"}'
+
+# 流式
+curl -N http://127.0.0.1:8787/v1/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message":"say hi","stream":true}'
+
+# Code 模式
+curl http://127.0.0.1:8787/v1/code \
+  -H "Content-Type: application/json" \
+  -d '{"message":"add error handling to login"}'
+
+# 图片
+curl http://127.0.0.1:8787/v1/paste \
+  -H "Content-Type: application/json" \
+  -d '{"image_base64":"iVBOR...","message":"分析这张图"}'
 
-文档与实现随仓库版本迭代；`GET /health` 中的 `version` 来自项目根目录 `package.json`。
+# 添加 MCP
+curl -X POST http://127.0.0.1:8787/v1/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"name":"fs","command":["npx","-y","@modelcontextprotocol/server-filesystem","/tmp"]}'
+
+# 添加记忆
+curl -X POST http://127.0.0.1:8787/v1/memory \
+  -H "Content-Type: application/json" \
+  -d '{"content":"prefer TypeScript","tags":["preference"]}'
+
+# 压缩会话
+curl -X POST http://127.0.0.1:8787/v1/chat/compact \
+  -H "Content-Type: application/json" \
+  -d '{"session_id":"abc123"}'
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "min-agent",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "Minimal AI coding agent with tool use, MCP, and skills support",
   "license": "MIT",