min-agent 0.1.0 → 0.1.1

package/dist/serve.js

@@ -0,0 +1,351 @@
+/**
+ * HTTP API server: exposes chat / models / health for programmatic use.
+ * Run: min-agent serve [--host 127.0.0.1] [--port 8787]
+ */
+import { createServer } from "http";
+import { readFileSync, existsSync } from "fs";
+import path from "path";
+import { initMcp, shutdownMcp } from "./mcp.js";
+import { discoverSkills } from "./skills.js";
+import { loadInstructions } from "./instructions.js";
+import { loadConfig, fetchModels, isConfigured } from "./config.js";
+import { setAutoApprove } from "./confirm.js";
+import { runOnce, buildUserContent } from "./agent.js";
+import { loadSession, saveSession } from "./sessions.js";
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+const MAX_TOOL_RESULT_SSE_CHARS = 48_000;
+function packageVersion() {
+    try {
+        const pkgPath = path.join(process.cwd(), "package.json");
+        if (existsSync(pkgPath)) {
+            const j = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            return j.version ?? "0.0.0";
+        }
+    }
+    catch { }
+    return "0.0.0";
+}
+function corsHeaders() {
+    if (process.env.MIN_AGENT_SERVE_CORS === "1" || process.env.MIN_AGENT_SERVE_CORS === "true") {
+        return {
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+            "Access-Control-Allow-Headers": "Content-Type, Authorization",
+        };
+    }
+    return {};
+}
+function authOk(req) {
+    const token = process.env.MIN_AGENT_SERVE_TOKEN?.trim();
+    if (!token)
+        return true;
+    const h = req.headers.authorization?.trim();
+    if (!h?.startsWith("Bearer "))
+        return false;
+    return h.slice(7) === token;
+}
+function sendJson(res, status, body) {
+    const headers = {
+        "Content-Type": "application/json; charset=utf-8",
+        ...corsHeaders(),
+    };
+    res.writeHead(status, headers);
+    res.end(JSON.stringify(body));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on("data", (c) => {
+            total += c.length;
+            if (total > MAX_BODY_BYTES) {
+                reject(new Error("body_too_large"));
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.on("error", reject);
+    });
+}
+function sseWrite(res, obj) {
+    try {
+        if (res.writableEnded)
+            return;
+        res.write(`data: ${JSON.stringify(obj)}\n\n`);
+    }
+    catch {
+        /* client gone */
+    }
+}
+function truncateForJson(v, max) {
+    if (typeof v === "string" && v.length > max)
+        return v.slice(0, max) + `\n… [truncated ${v.length - max} chars]`;
+    return v;
+}
+function normalizeMessages(body) {
+    if (body.messages && Array.isArray(body.messages)) {
+        if (body.messages.length === 0)
+            return { ok: false, error: "messages must be non-empty" };
+        return { ok: true, messages: [...body.messages] };
+    }
+    if (typeof body.message === "string" && body.message.length > 0) {
+        return { ok: true, messages: [{ role: "user", content: body.message }] };
+    }
+    return { ok: false, error: "Provide `message` (string) or non-empty `messages` array" };
+}
+export async function runServe(opts = {}) {
+    if (!isConfigured()) {
+        console.error("Not configured. Run: min-agent setup");
+        process.exit(1);
+    }
+    const host = opts.host ?? process.env.MIN_AGENT_SERVE_HOST ?? "127.0.0.1";
+    const port = opts.port ?? parseInt(process.env.MIN_AGENT_SERVE_PORT ?? "8787", 10);
+    console.error("\x1b[33m⚠ min-agent serve: confirmations are auto-approved for this process (same as -y). Dangerous shell commands will run without prompts.\x1b[0m");
+    setAutoApprove(true);
+    console.error("\x1b[90m⟳ Initializing MCP, skills, instructions…\x1b[0m");
+    await initMcp();
+    discoverSkills();
+    let instructions = await loadInstructions();
+    const version = packageVersion();
+    const server = createServer(async (req, res) => {
+        const c = corsHeaders();
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, c);
+            res.end();
+            return;
+        }
+        if (!authOk(req)) {
+            sendJson(res, 401, { error: "unauthorized", detail: "Set Authorization: Bearer <MIN_AGENT_SERVE_TOKEN> when MIN_AGENT_SERVE_TOKEN is set" });
+            return;
+        }
+        const url = new URL(req.url ?? "/", `http://${host}`);
+        const pathname = url.pathname.replace(/\/$/, "") || "/";
+        try {
+            if (req.method === "GET" && pathname === "/health") {
+                sendJson(res, 200, { ok: true, service: "min-agent", version });
+                return;
+            }
+            if (req.method === "GET" && pathname === "/v1/meta") {
+                sendJson(res, 200, {
+                    version,
+                    cwd: process.cwd(),
+                    instructions_chars: instructions.join("\n").length,
+                });
+                return;
+            }
+            if (req.method === "GET" && pathname === "/v1/models") {
+                const config = loadConfig();
+                const base = config.provider?.baseURL;
+                const key = config.provider?.apiKey;
+                if (!base || !key) {
+                    sendJson(res, 500, { error: "provider_not_configured" });
+                    return;
+                }
+                const models = await fetchModels(base, key);
+                sendJson(res, 200, {
+                    default_model: config.provider?.defaultModel ?? null,
+                    models,
+                });
+                return;
+            }
+            if (req.method === "POST" && pathname === "/v1/chat/reload-instructions") {
+                instructions = await loadInstructions();
+                sendJson(res, 200, { ok: true, instructions_chars: instructions.join("\n").length });
+                return;
+            }
+            if (req.method === "POST" && pathname === "/v1/chat") {
+                if (req.headers["content-type"]?.split(";")[0]?.trim() !== "application/json") {
+                    sendJson(res, 415, { error: "unsupported_media_type", detail: "Use Content-Type: application/json" });
+                    return;
+                }
+                let raw;
+                try {
+                    raw = await readBody(req);
+                }
+                catch (e) {
+                    if (e?.message === "body_too_large") {
+                        sendJson(res, 413, { error: "payload_too_large", max_bytes: MAX_BODY_BYTES });
+                        return;
+                    }
+                    throw e;
+                }
+                let body;
+                try {
+                    body = JSON.parse(raw);
+                }
+                catch {
+                    sendJson(res, 400, { error: "invalid_json" });
+                    return;
+                }
+                const modelId = typeof body.model === "string" ? body.model : undefined;
+                const stream = body.stream === true;
+                const sessionId = typeof body.session_id === "string" ? body.session_id : undefined;
+                let messages;
+                if (sessionId) {
+                    const session = loadSession(sessionId);
+                    if (!session) {
+                        sendJson(res, 404, { error: "session_not_found", session_id: sessionId });
+                        return;
+                    }
+                    if (typeof body.message !== "string" || !body.message.trim()) {
+                        sendJson(res, 400, {
+                            error: "session_requires_message",
+                            detail: "With `session_id`, send a non-empty `message` for the new user turn",
+                        });
+                        return;
+                    }
+                    messages = [...session.messages];
+                    const content = body.images && body.images.length > 0 ? await buildUserContent(body.message, body.images) : body.message;
+                    messages.push({ role: "user", content });
+                }
+                else {
+                    const norm = normalizeMessages(body);
+                    if (!norm.ok) {
+                        sendJson(res, 400, { error: "invalid_body", detail: norm.error });
+                        return;
+                    }
+                    messages = norm.messages;
+                    if (body.images && body.images.length > 0) {
+                        const last = messages[messages.length - 1];
+                        if (!last || last.role !== "user" || typeof body.message !== "string") {
+                            sendJson(res, 400, {
+                                error: "images_require_message",
+                                detail: "With `images`, send a top-level `message` string for the user turn",
+                            });
+                            return;
+                        }
+                        messages[messages.length - 1] = {
+                            role: "user",
+                            content: await buildUserContent(body.message, body.images),
+                        };
+                    }
+                }
+                const abort = new AbortController();
+                req.on("close", () => abort.abort());
+                if (stream) {
+                    res.writeHead(200, {
+                        "Content-Type": "text/event-stream; charset=utf-8",
+                        "Cache-Control": "no-cache, no-transform",
+                        Connection: "keep-alive",
+                        "X-Accel-Buffering": "no",
+                        ...c,
+                    });
+                    res.flushHeaders?.();
+                    const toolCalls = [];
+                    const toolResults = [];
+                    const callbacks = {
+                        onAssistantDisplayDelta(delta) {
+                            sseWrite(res, { type: "assistant", text: delta });
+                        },
+                        onThinkingDelta(delta) {
+                            sseWrite(res, { type: "thinking", text: delta });
+                        },
+                        onToolCall(name, input) {
+                            toolCalls.push({ name, input });
+                            sseWrite(res, { type: "tool_call", name, input });
+                        },
+                        onToolResult(name, output) {
+                            const out = truncateForJson(output, MAX_TOOL_RESULT_SSE_CHARS);
+                            toolResults.push({ name, output: out });
+                            sseWrite(res, { type: "tool_result", name, output: out });
+                        },
+                        onCompaction(line) {
+                            sseWrite(res, { type: "compaction", line });
+                        },
+                        onStreamError(message) {
+                            sseWrite(res, { type: "error", message });
+                        },
+                        onRunFinish(info) {
+                            let saved;
+                            if (sessionId && messages.length > 0) {
+                                try {
+                                    saved = saveSession(messages, sessionId);
+                                }
+                                catch {
+                                    saved = undefined;
+                                }
+                            }
+                            sseWrite(res, {
+                                type: "done",
+                                step_count: info.stepCount,
+                                usage: info.usage,
+                                has_error: info.hasError,
+                                aborted: info.aborted,
+                                session_id: saved,
+                                messages,
+                            });
+                            if (!res.writableEnded)
+                                res.end();
+                        },
+                    };
+                    try {
+                        await runOnce(messages, instructions, modelId, abort.signal, callbacks);
+                    }
+                    catch (err) {
+                        if (!res.writableEnded) {
+                            sseWrite(res, { type: "fatal", message: err?.message ?? String(err) });
+                            res.end();
+                        }
+                    }
+                    return;
+                }
+                const toolCalls = [];
+                const toolResults = [];
+                const finishBox = { info: null };
+                await runOnce(messages, instructions, modelId, abort.signal, {
+                    onToolCall(name, input) {
+                        toolCalls.push({ name, input });
+                    },
+                    onToolResult(name, output) {
+                        toolResults.push({ name, output: truncateForJson(output, MAX_TOOL_RESULT_SSE_CHARS) });
+                    },
+                    onRunFinish(info) {
+                        finishBox.info = info;
+                    },
+                });
+                const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant");
+                let savedSession;
+                if (sessionId && messages.length > 0) {
+                    try {
+                        savedSession = saveSession(messages, sessionId);
+                    }
+                    catch {
+                        savedSession = undefined;
+                    }
+                }
+                const fi = finishBox.info;
+                sendJson(res, 200, {
+                    messages,
+                    assistant: lastAssistant ?? null,
+                    tool_calls: toolCalls,
+                    tool_results: toolResults,
+                    session_id: savedSession,
+                    step_count: fi?.stepCount ?? 0,
+                    usage: fi?.usage ?? null,
+                    has_error: fi?.hasError ?? false,
+                    aborted: fi?.aborted ?? false,
+                });
+                return;
+            }
+            sendJson(res, 404, { error: "not_found", path: pathname });
+        }
+        catch (err) {
+            sendJson(res, 500, { error: "internal_error", message: err?.message ?? String(err) });
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            console.error(`\x1b[32m✓ min-agent serve\x1b[0m http://${host}:${port}  (API: docs/API.md)`);
+            resolve();
+        });
+    });
+    const shutdown = async () => {
+        await shutdownMcp();
+        server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}

package/dist/sessions.d.ts

@@ -0,0 +1,17 @@
+import type { ModelMessage } from "ai";
+export interface SessionMeta {
+    id: string;
+    title: string;
+    created: string;
+    updated: string;
+    messageCount: number;
+}
+interface SessionData {
+    meta: SessionMeta;
+    messages: ModelMessage[];
+}
+export declare function saveSession(messages: ModelMessage[], existingId?: string): string;
+export declare function loadSession(id: string): SessionData | null;
+export declare function listSessions(): SessionMeta[];
+export declare function deleteSession(id: string): boolean;
+export {};

package/dist/sessions.js

@@ -0,0 +1,74 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "fs";
+import path from "path";
+import { getConfigDir } from "./config.js";
+function getSessionsDir() {
+    return path.join(getConfigDir(), "sessions");
+}
+function sessionPath(id) {
+    return path.join(getSessionsDir(), `${id}.json`);
+}
+function generateId() {
+    return Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+}
+function deriveTitle(messages) {
+    const first = messages.find((m) => m.role === "user");
+    if (!first)
+        return "Untitled";
+    const content = typeof first.content === "string" ? first.content : "";
+    return content.slice(0, 60) || "Untitled";
+}
+export function saveSession(messages, existingId) {
+    const dir = getSessionsDir();
+    mkdirSync(dir, { recursive: true });
+    const id = existingId ?? generateId();
+    const now = new Date().toISOString();
+    const data = {
+        meta: {
+            id,
+            title: deriveTitle(messages),
+            created: existingId ? loadSession(id)?.meta.created ?? now : now,
+            updated: now,
+            messageCount: messages.length,
+        },
+        messages,
+    };
+    writeFileSync(sessionPath(id), JSON.stringify(data, null, 2), "utf-8");
+    return id;
+}
+export function loadSession(id) {
+    const file = sessionPath(id);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function listSessions() {
+    const dir = getSessionsDir();
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => {
+        try {
+            const data = JSON.parse(readFileSync(path.join(dir, f), "utf-8"));
+            return data.meta;
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((m) => m !== null)
+        .sort((a, b) => b.updated.localeCompare(a.updated));
+}
+export function deleteSession(id) {
+    const file = sessionPath(id);
+    if (!existsSync(file))
+        return false;
+    const { unlinkSync } = require("fs");
+    unlinkSync(file);
+    return true;
+}

package/dist/skills.d.ts

@@ -0,0 +1,12 @@
+import { type Tool } from "ai";
+export interface SkillInfo {
+    name: string;
+    description: string;
+    location: string;
+    content: string;
+}
+export declare function discoverSkills(): void;
+export declare function getSkills(): SkillInfo[];
+export declare function getSkill(name: string): SkillInfo | undefined;
+export declare function getSkillsTool(): Tool;
+export declare function getSkillsSystemPrompt(): string;

package/dist/skills.js

@@ -0,0 +1,127 @@
+import { tool, jsonSchema } from "ai";
+import { readFileSync, existsSync, readdirSync, statSync } from "fs";
+import os from "os";
+import path from "path";
+import { globSync } from "glob";
+/**
+ * Skill scan order: later entries win on duplicate `name` in frontmatter.
+ * Global user skills first, then project-local dirs so repo skills override ~/.agents.
+ */
+const SKILL_DIRS = [
+    path.join(os.homedir(), ".agents", "skills"),
+    path.join(process.cwd(), ".min-agent", "skills"),
+    path.join(process.cwd(), ".agent-demo", "skills"),
+    path.join(process.cwd(), ".opencode", "skills"),
+    path.join(process.cwd(), ".claude", "skills"),
+];
+let loadedSkills = {};
+export function discoverSkills() {
+    loadedSkills = {};
+    for (const dir of SKILL_DIRS) {
+        if (!existsSync(dir))
+            continue;
+        const matches = globSync("**/SKILL.md", { cwd: dir, absolute: true });
+        for (const match of matches) {
+            const skill = parseSkillFile(match);
+            if (skill) {
+                loadedSkills[skill.name] = skill;
+            }
+        }
+    }
+    const count = Object.keys(loadedSkills).length;
+    if (count > 0) {
+        console.log(`\x1b[90m  Skills loaded: ${count} (${Object.keys(loadedSkills).join(", ")})\x1b[0m`);
+    }
+}
+function parseSkillFile(filePath) {
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        // Parse frontmatter (---\n...\n---)
+        const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+        if (!fmMatch)
+            return null;
+        const frontmatter = fmMatch[1];
+        const content = fmMatch[2];
+        const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+        const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+        if (!nameMatch || !descMatch)
+            return null;
+        return {
+            name: nameMatch[1].trim().replace(/^["']|["']$/g, ""),
+            description: descMatch[1].trim().replace(/^["']|["']$/g, ""),
+            location: filePath,
+            content: content.trim(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function getSkills() {
+    return Object.values(loadedSkills);
+}
+export function getSkill(name) {
+    return loadedSkills[name];
+}
+export function getSkillsTool() {
+    return tool({
+        description: buildSkillDescription(),
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                name: { type: "string", description: "The name of the skill to load" },
+            },
+            required: ["name"],
+        }),
+        execute: async ({ name }) => {
+            const skill = loadedSkills[name];
+            if (!skill) {
+                const available = Object.keys(loadedSkills);
+                return `Skill "${name}" not found. Available skills: ${available.length ? available.join(", ") : "none"}`;
+            }
+            const dir = path.dirname(skill.location);
+            let files = [];
+            try {
+                files = readdirSync(dir)
+                    .filter((f) => f !== "SKILL.md" && !statSync(path.join(dir, f)).isDirectory())
+                    .slice(0, 10);
+            }
+            catch { }
+            return [
+                `<skill_content name="${skill.name}">`,
+                `# Skill: ${skill.name}`,
+                "",
+                skill.content,
+                "",
+                `Base directory: ${dir}`,
+                "",
+                files.length ? `<skill_files>\n${files.map((f) => `  ${f}`).join("\n")}\n</skill_files>` : "",
+                `</skill_content>`,
+            ]
+                .filter(Boolean)
+                .join("\n");
+        },
+    });
+}
+export function getSkillsSystemPrompt() {
+    const skills = Object.values(loadedSkills);
+    if (skills.length === 0)
+        return "";
+    return [
+        "## Available Skills",
+        "Use the `skill` tool to load specialized instructions when a task matches a skill's description.",
+        "",
+        ...skills.map((s) => `- **${s.name}**: ${s.description}`),
+    ].join("\n");
+}
+function buildSkillDescription() {
+    const skills = Object.values(loadedSkills);
+    if (skills.length === 0)
+        return "Load a specialized skill. No skills are currently available.";
+    return [
+        "Load a specialized skill that provides domain-specific instructions and workflows.",
+        "",
+        "Available skills:",
+        ...skills.map((s) => `- ${s.name}: ${s.description}`),
+    ].join("\n");
+}

package/dist/tool-output.d.ts

@@ -0,0 +1,31 @@
+/** Default limits (aligned with common agent tooling practice). */
+export declare const TOOL_OUTPUT_MAX_LINES = 2000;
+export declare const TOOL_OUTPUT_MAX_BYTES: number;
+export type TruncateDirection = "head" | "tail";
+export interface TruncateToolOutputOptions {
+    maxLines?: number;
+    maxBytes?: number;
+    direction?: TruncateDirection;
+}
+export interface TruncateToolOutputResult {
+    content: string;
+    truncated: boolean;
+    outputPath?: string;
+}
+/** Write full text to ~/.min-agent/tool-output/ and return absolute path. */
+export declare function writeFullToolOutput(fullText: string): string;
+/** Keep end of text within line/byte limits (good for shell logs). */
+export declare function tailPreview(text: string, maxLines: number, maxBytes: number): {
+    text: string;
+    cut: boolean;
+};
+/** Keep start of text within line/byte limits (good for files / HTTP bodies). */
+export declare function headPreview(text: string, maxLines: number, maxBytes: number): {
+    text: string;
+    cut: boolean;
+};
+/**
+ * If text exceeds limits, write full text to disk and return a preview + path hint.
+ * Otherwise returns the original string.
+ */
+export declare function truncateToolOutput(text: string, options?: TruncateToolOutputOptions): TruncateToolOutputResult;