min-agent 0.1.0

package/src/serve.ts

@@ -0,0 +1,400 @@
+/**
+ * HTTP API server: exposes chat / models / health for programmatic use.
+ * Run: min-agent serve [--host 127.0.0.1] [--port 8787]
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from "http"
+import { readFileSync, existsSync } from "fs"
+import path from "path"
+import type { LanguageModelUsage, ModelMessage } from "ai"
+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, type RunOnceCallbacks } from "./agent.js"
+import { loadSession, saveSession } from "./sessions.js"
+
+const MAX_BODY_BYTES = 2 * 1024 * 1024
+const MAX_TOOL_RESULT_SSE_CHARS = 48_000
+
+export interface ServeOptions {
+  host?: string
+  port?: number
+}
+
+function packageVersion(): string {
+  try {
+    const pkgPath = path.join(process.cwd(), "package.json")
+    if (existsSync(pkgPath)) {
+      const j = JSON.parse(readFileSync(pkgPath, "utf-8")) as { version?: string }
+      return j.version ?? "0.0.0"
+    }
+  } catch {}
+  return "0.0.0"
+}
+
+function corsHeaders(): Record<string, string> {
+  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: IncomingMessage): boolean {
+  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: ServerResponse, status: number, body: unknown) {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json; charset=utf-8",
+    ...corsHeaders(),
+  }
+  res.writeHead(status, headers)
+  res.end(JSON.stringify(body))
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let total = 0
+    req.on("data", (c: Buffer) => {
+      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: ServerResponse, obj: Record<string, unknown>) {
+  try {
+    if (res.writableEnded) return
+    res.write(`data: ${JSON.stringify(obj)}\n\n`)
+  } catch {
+    /* client gone */
+  }
+}
+
+function truncateForJson(v: unknown, max: number): unknown {
+  if (typeof v === "string" && v.length > max) return v.slice(0, max) + `\n… [truncated ${v.length - max} chars]`
+  return v
+}
+
+interface ChatBody {
+  message?: string
+  messages?: ModelMessage[]
+  model?: string
+  stream?: boolean
+  session_id?: string
+  images?: string[]
+}
+
+function normalizeMessages(body: ChatBody): { ok: true; messages: ModelMessage[] } | { ok: false; error: string } {
+  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: ServeOptions = {}): Promise<void> {
+  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: string
+        try {
+          raw = await readBody(req)
+        } catch (e: any) {
+          if (e?.message === "body_too_large") {
+            sendJson(res, 413, { error: "payload_too_large", max_bytes: MAX_BODY_BYTES })
+            return
+          }
+          throw e
+        }
+
+        let body: ChatBody
+        try {
+          body = JSON.parse(raw) as ChatBody
+        } 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: ModelMessage[]
+
+        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: { name: string; input: unknown }[] = []
+          const toolResults: { name: string; output: unknown }[] = []
+
+          const callbacks: RunOnceCallbacks = {
+            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: string | undefined
+              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: any) {
+            if (!res.writableEnded) {
+              sseWrite(res, { type: "fatal", message: err?.message ?? String(err) })
+              res.end()
+            }
+          }
+          return
+        }
+
+        const toolCalls: { name: string; input: unknown }[] = []
+        const toolResults: { name: string; output: unknown }[] = []
+        type FinishInfo = {
+          stepCount: number
+          usage: LanguageModelUsage | undefined
+          hasError: boolean
+          aborted: boolean
+        }
+        const finishBox: { info: FinishInfo | null } = { 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: string | undefined
+        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: any) {
+      sendJson(res, 500, { error: "internal_error", message: err?.message ?? String(err) })
+    }
+  })
+
+  await new Promise<void>((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/src/sessions.ts

@@ -0,0 +1,94 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "fs"
+import path from "path"
+import type { ModelMessage } from "ai"
+import { getConfigDir } from "./config.js"
+
+export interface SessionMeta {
+  id: string
+  title: string
+  created: string
+  updated: string
+  messageCount: number
+}
+
+interface SessionData {
+  meta: SessionMeta
+  messages: ModelMessage[]
+}
+
+function getSessionsDir(): string {
+  return path.join(getConfigDir(), "sessions")
+}
+
+function sessionPath(id: string): string {
+  return path.join(getSessionsDir(), `${id}.json`)
+}
+
+function generateId(): string {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+}
+
+function deriveTitle(messages: ModelMessage[]): string {
+  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: ModelMessage[], existingId?: string): string {
+  const dir = getSessionsDir()
+  mkdirSync(dir, { recursive: true })
+
+  const id = existingId ?? generateId()
+  const now = new Date().toISOString()
+
+  const data: SessionData = {
+    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: string): SessionData | null {
+  const file = sessionPath(id)
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"))
+  } catch {
+    return null
+  }
+}
+
+export function listSessions(): SessionMeta[] {
+  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")) as SessionData
+        return data.meta
+      } catch {
+        return null
+      }
+    })
+    .filter((m): m is SessionMeta => m !== null)
+    .sort((a, b) => b.updated.localeCompare(a.updated))
+}
+
+export function deleteSession(id: string): boolean {
+  const file = sessionPath(id)
+  if (!existsSync(file)) return false
+  const { unlinkSync } = require("fs")
+  unlinkSync(file)
+  return true
+}

package/src/skills.ts

@@ -0,0 +1,146 @@
+import { tool, jsonSchema, type Tool } from "ai"
+import { readFileSync, existsSync, readdirSync, statSync } from "fs"
+import os from "os"
+import path from "path"
+import { globSync } from "glob"
+
+export interface SkillInfo {
+  name: string
+  description: string
+  location: string
+  content: string
+}
+
+/**
+ * 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: Record<string, SkillInfo> = {}
+
+export function discoverSkills(): void {
+  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: string): SkillInfo | null {
+  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(): SkillInfo[] {
+  return Object.values(loadedSkills)
+}
+
+export function getSkill(name: string): SkillInfo | undefined {
+  return loadedSkills[name]
+}
+
+export function getSkillsTool(): Tool {
+  return tool({
+    description: buildSkillDescription(),
+    inputSchema: jsonSchema<{ name: string }>({
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The name of the skill to load" },
+      },
+      required: ["name"],
+    }),
+    execute: async ({ name }: { name: string }) => {
+      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: string[] = []
+      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")
+    },
+  }) as Tool
+}
+
+export function getSkillsSystemPrompt(): string {
+  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(): string {
+  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")
+}