min-agent 0.1.0 → 0.1.2

package/dist/assistant-stream.js

@@ -0,0 +1,114 @@
+/**
+ * Split "thinking" fragments (inline XML-style blocks some models leak into text)
+ * from displayable assistant text. Thinking is emitted to stderr; display goes to Markdown.
+ */
+const BT = String.fromCharCode(96); // backtick — some models wrap thinking in `think` / `redacted_thinking`
+const THINKING_BLOCKS = [
+    { open: "<think>", close: "</think>" },
+    { open: "<thinking>", close: "</thinking>" },
+    { open: `<${BT}think${BT}>`, close: `<${BT}/think${BT}>` },
+    { open: `<${BT}redacted_thinking${BT}>`, close: `<${BT}/redacted_thinking${BT}>` },
+];
+/** Max tail to keep when looking for a partial opening tag. */
+const PARTIAL_TAG_HOLD = 72;
+function lower(s) {
+    return s.toLowerCase();
+}
+function findFirstOpen(buf) {
+    const l = lower(buf);
+    let best = null;
+    for (const tag of THINKING_BLOCKS) {
+        const i = l.indexOf(tag.open);
+        if (i >= 0 && (!best || i < best.index))
+            best = { index: i, tag };
+    }
+    return best;
+}
+/**
+ * Incremental filter: feed raw model text deltas; get display text (for stdout / history)
+ * and thinking text (for stderr). Handles tags split across chunks.
+ */
+export class ThinkingBodySplitter {
+    buf = "";
+    feed(chunk) {
+        this.buf += chunk;
+        return this.drain(false);
+    }
+    /** End of stream: flush remainder; incomplete thinking block → stderr only. */
+    flush() {
+        return this.drain(true);
+    }
+    drain(isFinal) {
+        let display = "";
+        let thinking = "";
+        while (this.buf.length > 0) {
+            const open = findFirstOpen(this.buf);
+            if (!open) {
+                if (isFinal) {
+                    display += this.buf;
+                    this.buf = "";
+                }
+                else {
+                    const holdFrom = lastPotentialPartialOpen(this.buf);
+                    if (holdFrom >= 0) {
+                        display += this.buf.slice(0, holdFrom);
+                        this.buf = this.buf.slice(holdFrom);
+                    }
+                    else {
+                        display += this.buf;
+                        this.buf = "";
+                    }
+                }
+                break;
+            }
+            if (open.index > 0) {
+                display += this.buf.slice(0, open.index);
+                this.buf = this.buf.slice(open.index);
+            }
+            const low = lower(this.buf);
+            if (!low.startsWith(open.tag.open)) {
+                this.buf = this.buf.slice(1);
+                continue;
+            }
+            const afterOpen = open.tag.open.length;
+            const closeRel = low.indexOf(open.tag.close, afterOpen);
+            if (closeRel < 0) {
+                if (isFinal) {
+                    thinking += this.buf.slice(afterOpen);
+                    this.buf = "";
+                }
+                break;
+            }
+            const inner = this.buf.slice(afterOpen, closeRel);
+            thinking += inner;
+            this.buf = this.buf.slice(closeRel + open.tag.close.length);
+        }
+        return { display, thinking };
+    }
+}
+/** If `buf` ends with `<...` that could still become a thinking open tag, return index of `<` to hold from; else -1. */
+function lastPotentialPartialOpen(buf) {
+    const start = Math.max(0, buf.length - PARTIAL_TAG_HOLD);
+    const tail = buf.slice(start);
+    const lt = tail.lastIndexOf("<");
+    if (lt < 0)
+        return -1;
+    const globalLt = start + lt;
+    const cand = buf.slice(globalLt).toLowerCase();
+    if (cand.length > 64)
+        return -1;
+    for (const tag of THINKING_BLOCKS) {
+        if (tag.open.startsWith(cand))
+            return globalLt;
+    }
+    return -1;
+}
+/** Final strip for assistant message (complete tags only). */
+export function stripThinkingFromAssistantText(text) {
+    let s = text;
+    for (const { open, close } of THINKING_BLOCKS) {
+        const re = new RegExp(open.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "[\\s\\S]*?" + close.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi");
+        s = s.replace(re, "");
+    }
+    return s;
+}

package/dist/cli.js

@@ -0,0 +1,471 @@
+import { runAgent, runChat } from "./agent.js";
+import { loadMcpConfig, saveMcpConfig, checkMcpServer, checkAllMcpServers, formatMcpServerBinding, } from "./mcp.js";
+import { discoverSkills, getSkills } from "./skills.js";
+import { loadMemories, addMemory, deleteMemory, searchMemories } from "./memory.js";
+import { runSetup, isConfigured, loadConfig, fetchModels, getConfigDir, getRulesFile } from "./config.js";
+import { setAutoApprove } from "./confirm.js";
+import { existsSync, writeFileSync, mkdirSync } from "fs";
+import path from "path";
+const rawArgs = process.argv.slice(2);
+// Extract leading global flags only, so subcommands can still use "-y"
+const args = [...rawArgs];
+let hasYes = false;
+while (args[0] === "--yes" || args[0] === "-y") {
+    hasYes = true;
+    args.shift();
+}
+if (hasYes)
+    setAutoApprove(true);
+function printUsage() {
+    console.log(`
+min-agent - Minimal AI coding agent
+
+Usage:
+  min-agent chat <message>          Send a message to the agent
+  min-agent chat                    Start interactive multi-turn chat
+  min-agent chat --resume <id>      Resume a previous session
+  min-agent setup                   Configure API provider (interactive)
+  min-agent models                  List available models
+  min-agent history                 List saved sessions
+  min-agent rules                   Show loaded instruction rules
+  min-agent rules edit              Edit global rules file
+  min-agent memory                  List all memories
+  min-agent memory add <text>       Add a memory manually
+  min-agent memory search <query>   Search memories
+  min-agent memory delete <index>   Delete a memory by number
+  min-agent mcp add <name> <cmd>    Add a local MCP server (stdio)
+  min-agent mcp add <name> --url <url> [--sse] [--token <t>]  Add remote MCP (HTTP)
+  min-agent mcp remove <name>       Remove an MCP server
+  min-agent mcp list                List configured MCP servers
+  min-agent mcp check               Check MCP server availability
+  min-agent skills list             List available skills
+  min-agent serve [--host H] [--port P]   HTTP API (see docs/API.md)
+
+Options:
+  --model, -m <model>    Override model for this request
+  --image, -i <path>     Attach an image (can be used multiple times)
+  --yes, -y              Auto-approve all confirmations (dangerous commands, file overwrites)
+
+Rules (loaded as system instructions):
+  Global:  ~/.min-agent/rules.md
+  Project: ./AGENTS.md or ./RULES.md or ./.min-agent/AGENTS.md
+  Config:  "instructions" array in ~/.min-agent/config.json
+
+Examples:
+  min-agent setup
+  min-agent chat "hello"
+  min-agent chat
+  min-agent serve --port 8787
+  min-agent rules edit
+  min-agent mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /tmp
+  min-agent mcp add remote --url https://example.com/mcp --token "$TOKEN"
+`);
+}
+function parseMcpAddArgs(argv) {
+    let skipCheck = false;
+    let url;
+    let token;
+    let sse = false;
+    const cmd = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--skip-check") {
+            skipCheck = true;
+            continue;
+        }
+        if (a === "--sse") {
+            sse = true;
+            continue;
+        }
+        if (a === "--url" && argv[i + 1]) {
+            url = argv[++i];
+            continue;
+        }
+        if (a === "--token" && argv[i + 1]) {
+            token = argv[++i];
+            continue;
+        }
+        cmd.push(a);
+    }
+    return { skipCheck, url, token, sse, cmd };
+}
+function ensureProjectDefaults() {
+    const projectConfigDir = path.join(process.cwd(), ".min-agent");
+    const projectSkillsDir = path.join(projectConfigDir, "skills");
+    const projectMcpFile = path.join(projectConfigDir, "mcp.json");
+    if (!existsSync(projectSkillsDir)) {
+        mkdirSync(projectSkillsDir, { recursive: true });
+    }
+    if (!existsSync(projectMcpFile)) {
+        mkdirSync(projectConfigDir, { recursive: true });
+        writeFileSync(projectMcpFile, JSON.stringify({ mcpServers: {} }, null, 2), "utf-8");
+    }
+}
+async function main() {
+    ensureProjectDefaults();
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printUsage();
+        process.exit(0);
+    }
+    const command = args[0];
+    switch (command) {
+        case "setup": {
+            await runSetup();
+            break;
+        }
+        case "models": {
+            const config = loadConfig();
+            if (!config.provider?.baseURL || !config.provider?.apiKey) {
+                console.error("Not configured. Run: min-agent setup");
+                process.exit(1);
+            }
+            console.log("Fetching models...");
+            const models = await fetchModels(config.provider.baseURL, config.provider.apiKey);
+            if (models.length === 0) {
+                console.log("No models found or unable to fetch model list.");
+            }
+            else {
+                console.log(`\nAvailable models (${models.length}):`);
+                for (const m of models) {
+                    const marker = m === config.provider.defaultModel ? " ← default" : "";
+                    console.log(`  ${m}${marker}`);
+                }
+            }
+            break;
+        }
+        case "chat": {
+            if (!isConfigured()) {
+                console.error("Not configured. Run: min-agent setup");
+                process.exit(1);
+            }
+            // Parse --model / -m, --resume, and --image / -i flags
+            let modelOverride;
+            let resumeId;
+            const images = [];
+            const chatArgs = [];
+            for (let i = 1; i < args.length; i++) {
+                if ((args[i] === "--model" || args[i] === "-m") && args[i + 1]) {
+                    modelOverride = args[++i];
+                }
+                else if (args[i] === "--resume" && args[i + 1]) {
+                    resumeId = args[++i];
+                }
+                else if ((args[i] === "--image" || args[i] === "-i") && args[i + 1]) {
+                    images.push(args[++i]);
+                }
+                else {
+                    chatArgs.push(args[i]);
+                }
+            }
+            const message = chatArgs.join(" ");
+            if (!message) {
+                // No message provided — enter interactive multi-turn mode
+                await runChat(modelOverride, resumeId);
+            }
+            else {
+                await runAgent(message, modelOverride, images.length > 0 ? images : undefined);
+            }
+            break;
+        }
+        case "serve": {
+            if (!isConfigured()) {
+                console.error("Not configured. Run: min-agent setup");
+                process.exit(1);
+            }
+            let servePort;
+            let serveHost;
+            for (let i = 1; i < args.length; i++) {
+                if ((args[i] === "--port" || args[i] === "-p") && args[i + 1]) {
+                    servePort = parseInt(args[++i], 10);
+                }
+                else if (args[i] === "--host" && args[i + 1]) {
+                    serveHost = args[++i];
+                }
+            }
+            const { runServe } = await import("./serve.js");
+            await runServe({ port: servePort, host: serveHost });
+            break;
+        }
+        case "mcp": {
+            const subcommand = args[1];
+            switch (subcommand) {
+                case "add": {
+                    const name = args[2];
+                    if (!name) {
+                        console.error("Usage: min-agent mcp add <name> [--skip-check] <command...>");
+                        console.error("   or: min-agent mcp add <name> --url <https://host/mcp> [--sse] [--token <bearer>] [--skip-check]");
+                        process.exit(1);
+                    }
+                    const { skipCheck, url, token, sse, cmd } = parseMcpAddArgs(args.slice(3));
+                    let entry;
+                    if (url?.trim()) {
+                        entry = {
+                            url: url.trim(),
+                            enabled: true,
+                            remoteTransport: sse ? "sse" : "auto",
+                        };
+                        if (token?.trim())
+                            entry.token = token.trim();
+                    }
+                    else if (cmd.length > 0) {
+                        entry = { command: cmd, enabled: true };
+                    }
+                    else {
+                        console.error("Usage: min-agent mcp add <name> [--skip-check] <command...>");
+                        console.error("   or: min-agent mcp add <name> --url <https://host/mcp> [--sse] [--token <bearer>] [--skip-check]");
+                        process.exit(1);
+                    }
+                    let detectedTools = 0;
+                    if (!skipCheck) {
+                        console.log(`Validating MCP server "${name}"...`);
+                        const checkResult = await checkMcpServer(name, entry);
+                        if (!checkResult.ok) {
+                            console.error(`MCP server "${name}" validation failed: ${checkResult.error ?? "unknown error"}`);
+                            process.exit(1);
+                        }
+                        detectedTools = checkResult.toolCount;
+                    }
+                    else {
+                        console.log(`Skipping MCP validation for "${name}" (--skip-check).`);
+                    }
+                    const config = loadMcpConfig();
+                    config.mcpServers[name] = entry;
+                    saveMcpConfig(config);
+                    const toolsSuffix = skipCheck ? "" : ` (${detectedTools} tools detected)`;
+                    console.log(`✓ MCP server "${name}" added: ${formatMcpServerBinding(entry)}${toolsSuffix}`);
+                    break;
+                }
+                case "remove": {
+                    const name = args[2];
+                    if (!name) {
+                        console.error("Usage: min-agent mcp remove <name>");
+                        process.exit(1);
+                    }
+                    const config = loadMcpConfig();
+                    if (!config.mcpServers[name]) {
+                        console.error(`MCP server "${name}" not found`);
+                        process.exit(1);
+                    }
+                    delete config.mcpServers[name];
+                    saveMcpConfig(config);
+                    console.log(`✓ MCP server "${name}" removed`);
+                    break;
+                }
+                case "list": {
+                    const config = loadMcpConfig();
+                    const servers = Object.entries(config.mcpServers);
+                    if (servers.length === 0) {
+                        console.log("No MCP servers configured.");
+                        console.log("Add one with: min-agent mcp add <name> <command...>  or  --url <https://...>");
+                    }
+                    else {
+                        console.log("MCP Servers:");
+                        for (const [name, cfg] of servers) {
+                            const status = cfg.enabled === false ? " (disabled)" : "";
+                            console.log(`  ${name}: ${formatMcpServerBinding(cfg)}${status}`);
+                        }
+                    }
+                    break;
+                }
+                case "check": {
+                    const results = await checkAllMcpServers();
+                    if (results.length === 0) {
+                        console.log("No MCP servers configured.");
+                        console.log("Add one with: min-agent mcp add <name> <command...>  or  --url <https://...>");
+                        break;
+                    }
+                    let failed = 0;
+                    console.log("MCP Check Results:");
+                    for (const result of results) {
+                        if (!result.enabled) {
+                            console.log(`  ${result.name}: skipped (disabled)`);
+                            continue;
+                        }
+                        if (result.ok) {
+                            console.log(`  ${result.name}: ok (${result.toolCount} tools)`);
+                        }
+                        else {
+                            failed++;
+                            console.log(`  ${result.name}: failed${result.error ? ` - ${result.error}` : ""}`);
+                        }
+                    }
+                    if (failed > 0) {
+                        console.error(`\n${failed} MCP server(s) failed.`);
+                        process.exit(1);
+                    }
+                    else {
+                        console.log("\nAll enabled MCP servers are available.");
+                    }
+                    break;
+                }
+                default:
+                    console.error("Usage: min-agent mcp [add|remove|list|check]");
+                    process.exit(1);
+            }
+            break;
+        }
+        case "history": {
+            const { listSessions } = await import("./sessions.js");
+            const sessions = listSessions();
+            if (sessions.length === 0) {
+                console.log("No saved sessions.");
+                console.log("Sessions are auto-saved when you exit interactive chat.");
+            }
+            else {
+                console.log(`Sessions (${sessions.length}):`);
+                for (const s of sessions.slice(0, 20)) {
+                    const date = s.updated.split("T")[0];
+                    console.log(`  ${s.id}  ${date}  ${s.title} (${s.messageCount} msgs)`);
+                }
+                console.log("\nResume with: min-agent chat --resume <id>");
+            }
+            break;
+        }
+        case "memory": {
+            const subcommand = args[1];
+            switch (subcommand) {
+                case "add": {
+                    const text = args.slice(2).join(" ");
+                    if (!text) {
+                        console.error("Usage: min-agent memory add <text>");
+                        process.exit(1);
+                    }
+                    addMemory(text);
+                    console.log(`✓ Memory saved: "${text}"`);
+                    break;
+                }
+                case "search": {
+                    const query = args.slice(2).join(" ");
+                    if (!query) {
+                        console.error("Usage: min-agent memory search <query>");
+                        process.exit(1);
+                    }
+                    const results = searchMemories(query);
+                    if (results.length === 0) {
+                        console.log(`No memories matching "${query}"`);
+                    }
+                    else {
+                        console.log(`Found ${results.length} memory(s):`);
+                        for (const m of results) {
+                            const tags = m.tags.length > 0 ? ` [${m.tags.join(", ")}]` : "";
+                            console.log(`  #${m.index + 1}: ${m.content}${tags}`);
+                        }
+                    }
+                    break;
+                }
+                case "delete": {
+                    const idx = parseInt(args[2]);
+                    if (isNaN(idx)) {
+                        console.error("Usage: min-agent memory delete <number>");
+                        process.exit(1);
+                    }
+                    if (deleteMemory(idx - 1)) {
+                        console.log(`✓ Memory #${idx} deleted`);
+                    }
+                    else {
+                        console.error(`Memory #${idx} not found`);
+                    }
+                    break;
+                }
+                default: {
+                    // List all memories
+                    const memories = loadMemories();
+                    if (memories.length === 0) {
+                        console.log("No memories stored.");
+                        console.log("The agent will automatically save memories during conversations.");
+                        console.log("Or add manually: min-agent memory add \"prefer TypeScript over JavaScript\"");
+                    }
+                    else {
+                        console.log(`Memories (${memories.length}):`);
+                        for (let i = 0; i < memories.length; i++) {
+                            const m = memories[i];
+                            const tags = m.tags.length > 0 ? ` [${m.tags.join(", ")}]` : "";
+                            const date = m.created.split("T")[0];
+                            console.log(`  #${i + 1}: ${m.content}${tags} (${date})`);
+                        }
+                    }
+                    break;
+                }
+            }
+            break;
+        }
+        case "skills": {
+            const subcommand = args[1];
+            switch (subcommand) {
+                case "list": {
+                    discoverSkills();
+                    const skills = getSkills();
+                    if (skills.length === 0) {
+                        console.log("No skills found.");
+                        console.log("Add skills by creating SKILL.md files in:");
+                        console.log("  ~/.agents/skills/<name>/SKILL.md   (global, all projects)");
+                        console.log("  .min-agent/skills/<name>/SKILL.md");
+                        console.log("  .opencode/skills/<name>/SKILL.md");
+                        console.log("");
+                        console.log("SKILL.md format:");
+                        console.log("  ---");
+                        console.log("  name: my-skill");
+                        console.log("  description: What this skill does");
+                        console.log("  ---");
+                        console.log("  # Instructions content...");
+                    }
+                    else {
+                        console.log("Available Skills:");
+                        for (const skill of skills) {
+                            console.log(`  ${skill.name}: ${skill.description}`);
+                            console.log(`    ${skill.location}`);
+                        }
+                    }
+                    break;
+                }
+                default:
+                    console.error("Usage: min-agent skills [list]");
+                    process.exit(1);
+            }
+            break;
+        }
+        case "rules": {
+            const subcommand = args[1];
+            if (subcommand === "edit") {
+                const rulesFile = getRulesFile();
+                if (!existsSync(rulesFile)) {
+                    mkdirSync(getConfigDir(), { recursive: true });
+                    writeFileSync(rulesFile, `# Global Agent Rules\n\n<!-- Add your custom instructions here. They will be included in every conversation. -->\n`, "utf-8");
+                }
+                const editor = process.env.EDITOR || "vi";
+                const { execSync } = await import("child_process");
+                execSync(`${editor} "${rulesFile}"`, { stdio: "inherit" });
+            }
+            else {
+                const { loadInstructions } = await import("./instructions.js");
+                const instructions = await loadInstructions();
+                if (instructions.length === 0) {
+                    console.log("No instruction rules loaded.");
+                    console.log("");
+                    console.log("Add rules by creating:");
+                    console.log(`  Global:  ${getRulesFile()}`);
+                    console.log("  Project: ./AGENTS.md or ./RULES.md");
+                    console.log("");
+                    console.log("Or add paths/URLs in ~/.min-agent/config.json:");
+                    console.log('  { "instructions": ["./docs/rules.md", "https://..."] }');
+                }
+                else {
+                    console.log(`Loaded ${instructions.length} instruction source(s):\n`);
+                    for (const inst of instructions) {
+                        const firstLine = inst.split("\n")[0];
+                        console.log(`  ${firstLine}`);
+                    }
+                }
+            }
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            printUsage();
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(`\x1b[31mFatal error: ${err.message}\x1b[0m`);
+    process.exit(1);
+});

package/dist/compaction.js

@@ -0,0 +1,99 @@
+import { generateText } from "ai";
+/**
+ * Context compaction system.
+ *
+ * When conversation history exceeds a token threshold, older messages are
+ * summarized into a compact form to free up context window space.
+ *
+ * Strategy:
+ * 1. Estimate token count of messages (rough: 1 token ≈ 4 chars for English, 2 chars for CJK)
+ * 2. When over threshold, take older messages and summarize them via the LLM
+ * 3. Replace old messages with a single system summary message
+ * 4. Keep recent N turns verbatim for continuity
+ */
+const COMPACTION_PROMPT = `You are a conversation summarizer. Summarize the following conversation history into a concise but complete summary that preserves:
+- Key decisions made
+- Important context and facts discussed
+- Current state of any tasks in progress
+- User preferences mentioned
+- File paths, code snippets, or technical details that are still relevant
+
+Be concise but don't lose critical information. Output only the summary, no preamble.`;
+// Default: trigger compaction at ~80% of context window
+const DEFAULT_MAX_TOKENS = 128000;
+const COMPACTION_RATIO = 0.75;
+const KEEP_RECENT_TURNS = 4; // Keep last N user+assistant pairs verbatim
+/** Rough token estimation */
+export function estimateTokens(messages) {
+    let chars = 0;
+    for (const msg of messages) {
+        if (typeof msg.content === "string") {
+            chars += msg.content.length;
+        }
+        else if (Array.isArray(msg.content)) {
+            for (const part of msg.content) {
+                if ("text" in part && typeof part.text === "string") {
+                    chars += part.text.length;
+                }
+            }
+        }
+    }
+    // Rough estimate: mix of English (~4 chars/token) and CJK (~2 chars/token)
+    return Math.ceil(chars / 3);
+}
+/** Check if compaction is needed */
+export function needsCompaction(messages, config) {
+    const maxTokens = config?.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const threshold = maxTokens * COMPACTION_RATIO;
+    return estimateTokens(messages) > threshold;
+}
+/** Compact messages by summarizing older history */
+export async function compactMessages(messages, model, config) {
+    const keepTurns = config?.keepRecentTurns ?? KEEP_RECENT_TURNS;
+    if (messages.length <= keepTurns * 2) {
+        // Not enough messages to compact
+        return { messages, compacted: false };
+    }
+    // Split: older messages to summarize, recent messages to keep
+    const splitIdx = messages.length - keepTurns * 2;
+    const toSummarize = messages.slice(0, splitIdx);
+    const toKeep = messages.slice(splitIdx);
+    // Build conversation text for summarization
+    const conversationText = toSummarize
+        .map((msg) => {
+        const role = msg.role;
+        const content = typeof msg.content === "string"
+            ? msg.content
+            : Array.isArray(msg.content)
+                ? msg.content
+                    .filter((p) => "text" in p)
+                    .map((p) => p.text)
+                    .join("\n")
+                : "";
+        return `[${role}]: ${content.slice(0, 2000)}`;
+    })
+        .join("\n\n");
+    try {
+        const result = await generateText({
+            model,
+            messages: [
+                { role: "system", content: COMPACTION_PROMPT },
+                { role: "user", content: `Summarize this conversation:\n\n${conversationText}` },
+            ],
+        });
+        const summary = result.text;
+        // Build compacted message list
+        const compactedMessages = [
+            {
+                role: "system",
+                content: `[Context Summary - Previous conversation was compacted]\n\n${summary}`,
+            },
+            ...toKeep,
+        ];
+        return { messages: compactedMessages, compacted: true };
+    }
+    catch {
+        // If summarization fails, just truncate older messages
+        return { messages: toKeep, compacted: true };
+    }
+}