@vietor/easy-agent 0.1.1

package/dist/mcp/server.js

@@ -0,0 +1,85 @@
+import { MCPClient } from "./client.js";
+import { withTimeout } from "../util/async.js";
+const CONNECT_TIMEOUT = 30_000;
+function fixError(text) {
+    return text.startsWith("Error: ") ? text : `Error: ${text}`;
+}
+export class MCPServers {
+    servers = new Map();
+    pending = new Set();
+    disposed = false;
+    errorBuffer = [];
+    onError;
+    report(msg) {
+        if (this.onError)
+            this.onError(msg);
+        else
+            this.errorBuffer.push(msg);
+    }
+    flushErrors() {
+        const buf = this.errorBuffer;
+        this.errorBuffer = [];
+        return buf;
+    }
+    async connect(mcpServers = {}) {
+        const tools = [];
+        await Promise.all(Object.entries(mcpServers).map(async ([name, cfg]) => {
+            if (this.disposed)
+                return;
+            const client = new MCPClient(name, cfg);
+            this.pending.add(client);
+            try {
+                await withTimeout(client.connect(), CONNECT_TIMEOUT);
+                if (this.disposed) {
+                    client.kill();
+                    return;
+                }
+                const mcpTools = await withTimeout(client.listTools(), CONNECT_TIMEOUT);
+                if (this.disposed) {
+                    client.kill();
+                    return;
+                }
+                this.servers.set(name, { status: "connected", client, tools: mcpTools.map((t) => t.name) });
+                for (const t of mcpTools)
+                    tools.push(this.adapt(name, client, t));
+            }
+            catch (e) {
+                client.kill();
+                if (!this.disposed) {
+                    this.servers.set(name, { status: "disabled", tools: [] });
+                    this.report(`MCP server "${name}" failed: ${e.message}`);
+                }
+            }
+            finally {
+                this.pending.delete(client);
+            }
+        }));
+        return tools;
+    }
+    adapt(server, client, tool) {
+        return {
+            name: `MCP__${server}__${tool.name}`,
+            description: tool.description ?? `${server} ${tool.name}`,
+            parameters: tool.inputSchema,
+            async execute(args) {
+                const result = await client.callTool(tool.name, args);
+                const text = result.content.map((c) => (c.type === "text" ? c.text : "")).join("\n");
+                return result.isError
+                    ? { content: fixError(text), isError: true }
+                    : { content: text || "(no output)" };
+            },
+        };
+    }
+    list() {
+        return [...this.servers.entries()].map(([name, s]) => ({ name, status: s.status, tools: s.tools }));
+    }
+    kill() {
+        this.disposed = true;
+        for (const { client } of this.servers.values())
+            client?.kill();
+        for (const client of this.pending)
+            client.kill();
+        this.servers.clear();
+        this.pending.clear();
+    }
+}

package/dist/skills/loader.js

@@ -0,0 +1,43 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tryReadFileText } from "../util/fs.js";
+function parseSkillFile(skillName, skillFile) {
+    const content = tryReadFileText(skillFile);
+    if (!content)
+        return undefined;
+    const frontMatterRegex = /^---\r?\n([\s\S]*?)\r?\n---/;
+    const match = content.match(frontMatterRegex);
+    let name = null;
+    let description = "";
+    let prompt = content;
+    if (match) {
+        const yamlBody = match[1];
+        prompt = content.replace(match[0], "").trim();
+        const nameMatch = yamlBody.match(/^name:\s*(.+)$/m);
+        if (nameMatch)
+            name = nameMatch[1].trim();
+        const descMatch = yamlBody.match(/^description:\s*(.+)$/m);
+        if (descMatch)
+            description = descMatch[1].trim();
+    }
+    if (!name) {
+        name = skillName;
+    }
+    return { name, description, prompt };
+}
+export function tryLoadSkills(path) {
+    if (!existsSync(path))
+        return undefined;
+    const skills = [];
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const skillFile = join(path, entry.name, "SKILL.md");
+        if (!existsSync(skillFile))
+            continue;
+        const skill = parseSkillFile(entry.name, skillFile);
+        if (skill && skill.prompt)
+            skills.push(skill);
+    }
+    return skills.length > 0 ? skills : undefined;
+}

package/dist/skills/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/file_edit.js

@@ -0,0 +1,39 @@
+import { readFile, writeFile } from "node:fs/promises";
+const DESCRIPTION = [
+    "Replace the single occurrence of old_string with new_string in a file.",
+    "old_string must match exactly (including whitespace and indentation) and appear exactly once; read the file first and include enough surrounding context to be unique.",
+    "For full rewrites prefer FileWrite.",
+].join(" ");
+export const fileEditTool = {
+    name: "FileEdit",
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: {
+            path: { type: "string" },
+            old_string: { type: "string" },
+            new_string: { type: "string" },
+        },
+        required: ["path", "old_string", "new_string"],
+    },
+    async execute(args) {
+        const path = args.path;
+        const oldStr = args.old_string;
+        const newStr = args.new_string;
+        if (!path)
+            throw new Error("path is required");
+        if (!oldStr)
+            throw new Error("old_string is required");
+        if (newStr === undefined)
+            throw new Error("new_string is required");
+        const content = await readFile(path, "utf-8");
+        const count = content.split(oldStr).length - 1;
+        if (count === 0)
+            throw new Error(`old_string not found in ${path}`);
+        if (count > 1)
+            throw new Error(`old_string appears ${count} times in ${path}, must be unique`);
+        await writeFile(path, content.replace(oldStr, newStr), "utf-8");
+        return `Edited ${path}`;
+    },
+    summaryArg: "path",
+};

package/dist/tools/file_read.js

@@ -0,0 +1,18 @@
+import { readFile } from "node:fs/promises";
+const DESCRIPTION = [
+    "Read a file's full contents as UTF-8 text.",
+    "path may be relative (to the working directory) or absolute.",
+].join(" ");
+export const fileReadTool = {
+    name: "FileRead",
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+    },
+    async execute(args) {
+        return readFile(args.path, "utf-8");
+    },
+    summaryArg: "path",
+};

package/dist/tools/file_write.js

@@ -0,0 +1,22 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+const DESCRIPTION = [
+    "Write content to a file, overwriting it entirely if it exists and creating parent directories as needed.",
+    "Use for new files or full rewrites; for targeted changes prefer FileEdit.",
+].join(" ");
+export const fileWriteTool = {
+    name: "FileWrite",
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: { path: { type: "string" }, content: { type: "string" } },
+        required: ["path", "content"],
+    },
+    async execute(args) {
+        const path = args.path;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, args.content, "utf-8");
+        return `Wrote ${path}`;
+    },
+    summaryArg: "path",
+};

package/dist/tools/glob.js

@@ -0,0 +1,29 @@
+import { resolveCwd, runRgLines } from "../util/ripgrep.js";
+const DESCRIPTION = [
+    "List files under a directory, optionally filtered by a glob pattern (e.g. **/*.ts); omit pattern to list every file.",
+    "Skips node_modules and .git.",
+    "Returns paths relative to the root, one per line.",
+].join(" ");
+export const globTool = {
+    name: "Glob",
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: {
+            pattern: { type: "string", description: "glob pattern; omit to list all files" },
+            path: { type: "string", description: "root directory, defaults to cwd" },
+        },
+        required: [],
+    },
+    async execute(args) {
+        const cwd = resolveCwd(args.path);
+        const rgArgs = ["--files"];
+        const pattern = args.pattern;
+        if (pattern)
+            rgArgs.push("-g", pattern);
+        rgArgs.push(".");
+        const files = await runRgLines(rgArgs, cwd);
+        return files.length ? files.join("\n") : "(no matches)";
+    },
+    summaryArg: ["pattern", "path"],
+};

package/dist/tools/grep.js

@@ -0,0 +1,36 @@
+import { resolveCwd, runRgLines } from "../util/ripgrep.js";
+const MAX_MATCHES = 200;
+const DESCRIPTION = [
+    "Search file contents under a directory recursively for a regex pattern (RE2 syntax).",
+    "Skips node_modules and .git.",
+    "Returns matching lines as path:line: content, capped at 200 matches.",
+].join(" ");
+export const grepTool = {
+    name: "Grep",
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: {
+            pattern: { type: "string" },
+            path: { type: "string", description: "root directory, defaults to cwd" },
+        },
+        required: ["pattern"],
+    },
+    async execute(args) {
+        const cwd = resolveCwd(args.path);
+        const rgArgs = [
+            "--line-number",
+            "--with-filename",
+            "--no-heading",
+            args.pattern,
+            ".",
+        ];
+        const lines = await runRgLines(rgArgs, cwd);
+        if (!lines.length)
+            return "(no matches)";
+        if (lines.length > MAX_MATCHES)
+            return lines.slice(0, MAX_MATCHES).join("\n") + "\n(truncated)";
+        return lines.join("\n");
+    },
+    summaryArg: ["pattern", "path"],
+};

package/dist/tools/registry.js

@@ -0,0 +1,51 @@
+import { shellTool } from "./shell.js";
+import { fileReadTool } from "./file_read.js";
+import { fileWriteTool } from "./file_write.js";
+import { fileEditTool } from "./file_edit.js";
+import { globTool } from "./glob.js";
+import { grepTool } from "./grep.js";
+import { webFetchTool } from "./web_fetch.js";
+export class ToolRegistry {
+    tools = new Map();
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    schemas() {
+        return [...this.tools.values()].map((t) => ({
+            type: "function",
+            function: {
+                name: t.name,
+                description: t.description,
+                parameters: t.parameters,
+            },
+        }));
+    }
+    async execute(name, args) {
+        const tool = this.tools.get(name);
+        if (!tool)
+            return { content: `Error: unknown tool ${name}`, isError: true };
+        try {
+            const r = await tool.execute(args);
+            return typeof r === "string" ? { content: r } : r;
+        }
+        catch (e) {
+            return { content: `Error: ${e.message}`, isError: true };
+        }
+    }
+    summarize(name, args) {
+        const tool = this.tools.get(name);
+        if (!tool?.summaryArg)
+            return "";
+        const keys = Array.isArray(tool.summaryArg) ? tool.summaryArg : [tool.summaryArg];
+        for (const k of keys) {
+            const v = args[k];
+            if (typeof v === "string" && v)
+                return v;
+        }
+        return "";
+    }
+}
+export function registerBuiltinTools(tools) {
+    for (const t of [shellTool, fileReadTool, fileWriteTool, fileEditTool, globTool, grepTool, webFetchTool])
+        tools.register(t);
+}

package/dist/tools/shell.js

@@ -0,0 +1,34 @@
+import { runProcess } from "../util/process.js";
+const isWindows = process.platform === "win32";
+const shell = isWindows ? "powershell.exe" : "/bin/sh";
+const shellArgs = isWindows ? ["-NoProfile", "-NonInteractive", "-Command"] : ["-c"];
+const commandPrefix = isWindows
+    ? "[Console]::OutputEncoding=[Text.Encoding]::UTF8; $OutputEncoding=[Text.Encoding]::UTF8; "
+    : "";
+const DESCRIPTION = [
+    "Execute a shell command and return combined stdout and stderr.",
+    isWindows
+        ? "Runs on Windows PowerShell 5.1 (powershell.exe), NOT pwsh (PowerShell 7+). Chain commands with semicolons; conditional command chaining, null-coalescing, and ternary operators are pwsh-only and unsupported here."
+        : `Runs on ${shell} (POSIX sh).`,
+    "Runs synchronously with no stdin, so interactive prompts cannot be answered.",
+    "Output is capped at ~10MB; for large files prefer Grep or FileRead.",
+    "For URL content prefer WebFetch; use Shell for web requests only when WebFetch cannot (non-GET, custom headers, auth, raw bytes, or status codes).",
+].join(" ");
+export const shellTool = {
+    name: "Shell",
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: { command: { type: "string" } },
+        required: ["command"],
+    },
+    async execute(args) {
+        const command = args.command;
+        const r = await runProcess(shell, [...shellArgs, commandPrefix + command]);
+        if (r.status === 0 && !r.error) {
+            return r.stdout || "(no output)";
+        }
+        return (r.stdout || "") + (r.stderr || "") + (r.error?.message || "");
+    },
+    summaryArg: "command",
+};

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/web_fetch.js

@@ -0,0 +1,140 @@
+import { Parser } from "htmlparser2";
+import TurndownService from "turndown";
+const SKIP_TAGS = new Set(["script", "style", "noscript", "template", "head", "title", "meta", "link", "base"]);
+const BLOCK_TAGS = new Set([
+    "p",
+    "div",
+    "ul",
+    "ol",
+    "li",
+    "br",
+    "tr",
+    "table",
+    "blockquote",
+    "pre",
+    "section",
+    "article",
+    "header",
+    "footer",
+    "nav",
+    "aside",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "hr",
+]);
+function normalize(s) {
+    return s
+        .replace(/\r\n/g, "\n")
+        .replace(/\u00a0/g, " ")
+        .replace(/[ \t]+\n/g, "\n")
+        .split("\n")
+        .map((l) => l.replace(/[ \t]{2,}/g, " ").replace(/\s+$/, ""))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+function htmlToText(html) {
+    let out = "";
+    let skip = 0;
+    const parser = new Parser({
+        onopentag(name) {
+            if (SKIP_TAGS.has(name))
+                skip++;
+            else if (name === "li")
+                out += "\n- ";
+            else if (BLOCK_TAGS.has(name))
+                out += "\n";
+        },
+        onclosetag(name) {
+            if (SKIP_TAGS.has(name) && skip > 0)
+                skip--;
+        },
+        ontext(text) {
+            if (skip === 0)
+                out += text;
+        },
+    });
+    parser.write(html);
+    parser.end();
+    return normalize(out);
+}
+const turndown = new TurndownService({
+    headingStyle: "atx",
+    hr: "---",
+    bulletListMarker: "-",
+    codeBlockStyle: "fenced",
+    emDelimiter: "*",
+    strongDelimiter: "**",
+    linkStyle: "inlined",
+});
+turndown.remove(["script", "style", "title", "meta", "head", "noscript", "template", "link", "base"]);
+function htmlToMarkdown(html) {
+    return turndown.turndown(html);
+}
+function mimeFrom(contentType) {
+    return contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function isTextualMime(mime) {
+    return (!mime ||
+        mime.startsWith("text/") ||
+        mime === "application/json" ||
+        mime.endsWith("+json") ||
+        mime === "application/xml" ||
+        mime.endsWith("+xml") ||
+        mime === "application/javascript" ||
+        mime === "application/x-javascript");
+}
+const DESCRIPTION = [
+    "Fetch a URL via GET and return its content as markdown (default) or plain text.",
+    "Follows redirects.",
+    "HTML is converted; other textual types (JSON, XML, plain text) are returned raw; non-textual content (images, binaries) is rejected.",
+].join(" ");
+export const webFetchTool = {
+    name: "WebFetch",
+    description: DESCRIPTION,
+    parameters: {
+        type: "object",
+        properties: {
+            url: {
+                type: "string",
+                description: "full URL including scheme (http or https)",
+            },
+            format: {
+                type: "string",
+                description: "output format: 'markdown' (default) or 'text'",
+            },
+        },
+        required: ["url"],
+    },
+    async execute(args) {
+        const url = args.url;
+        const format = (args.format || "markdown").toLowerCase();
+        let res;
+        try {
+            res = await fetch(url, {
+                headers: {
+                    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
+                },
+                redirect: "follow",
+            });
+        }
+        catch (e) {
+            throw new Error(`failed to fetch ${url}: ${e.message}`);
+        }
+        if (!res.ok)
+            throw new Error(`${res.status} ${res.statusText} for ${url}`);
+        const body = await res.text();
+        const contentType = res.headers.get("content-type") || "";
+        const mime = mimeFrom(contentType);
+        if (!isTextualMime(mime))
+            throw new Error(`unsupported content type: ${mime} for ${url}`);
+        if (!contentType.includes("html"))
+            return body;
+        return format === "text" ? htmlToText(body) : htmlToMarkdown(body);
+    },
+    summaryArg: "url",
+};

package/dist/tui/App.js

@@ -0,0 +1,147 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Box, render, Text, useApp, useInput } from "ink";
+import { Markdown } from "./components/Markdown.js";
+import { LogView } from "./LogView.js";
+import { LogStore } from "./LogStore.js";
+import { AppHeader } from "./AppHeader.js";
+import { PromptOrCommandInput } from "./PromptOrCommandInput.js";
+import { Spinner } from "./Spinner.js";
+import { compactDisplay } from "../util/format.js";
+const STREAM_FRAME_MS = 240;
+export function App({ agent, commands, mcp }) {
+    const { exit } = useApp();
+    const [store] = useState(() => new LogStore());
+    const log = useSyncExternalStore(store.subscribe, store.getSnapshot);
+    const [status, setStatus] = useState("idle");
+    const [, setTick] = useState(0);
+    const streamingRef = useRef("");
+    const renderTimerRef = useRef(undefined);
+    const abortRef = useRef(null);
+    const startRef = useRef(0);
+    const timerRef = useRef(undefined);
+    const [elapsed, setElapsed] = useState(0);
+    const [usage, setUsage] = useState({ prompt: 0, completion: 0 });
+    const allCmds = useMemo(() => commands.schemas(), []);
+    useEffect(() => {
+        for (const msg of mcp.flushErrors())
+            store.append({ kind: "error", text: msg });
+        mcp.onError = (msg) => store.append({ kind: "error", text: msg });
+        return () => {
+            mcp.onError = undefined;
+        };
+    }, []);
+    const cancelStreamingRender = () => {
+        if (renderTimerRef.current) {
+            clearTimeout(renderTimerRef.current);
+            renderTimerRef.current = undefined;
+        }
+    };
+    const scheduleStreamingRender = () => {
+        if (renderTimerRef.current)
+            return;
+        renderTimerRef.current = setTimeout(() => {
+            renderTimerRef.current = undefined;
+            setStatus("streaming");
+            setTick((t) => t + 1);
+        }, STREAM_FRAME_MS);
+    };
+    const flushStreaming = () => {
+        cancelStreamingRender();
+        if (streamingRef.current) {
+            store.append({ kind: "assistant", text: streamingRef.current });
+            streamingRef.current = "";
+        }
+    };
+    const onEvent = (e) => {
+        if (e.type === "delta") {
+            streamingRef.current += e.text;
+            scheduleStreamingRender();
+        }
+        else if (e.type === "tool_start") {
+            flushStreaming();
+            setStatus("thinking");
+            store.append({ kind: "tool", id: e.id, name: e.name, summary: e.summary, result: null });
+        }
+        else if (e.type === "retry") {
+            cancelStreamingRender();
+            streamingRef.current = "";
+            setStatus("thinking");
+            store.append({ kind: "retry", attempt: e.attempt, max: e.max });
+        }
+        else if (e.type === "tool_end") {
+            setStatus("thinking");
+            store.setToolResult(e.id, e.result, e.isError);
+        }
+        else if (e.type === "error") {
+            flushStreaming();
+            store.append({ kind: "error", text: e.text });
+        }
+        else if (e.type === "interrupted") {
+            flushStreaming();
+            store.append({ kind: "interrupted" });
+        }
+        else if (e.type === "usage") {
+            setUsage({ prompt: e.promptTokens, completion: e.completionTokens });
+        }
+    };
+    useInput((_input, key) => {
+        if (key.escape) {
+            abortRef.current?.abort();
+        }
+        else if (key.ctrl && _input === "c") {
+            if (abortRef.current)
+                abortRef.current.abort();
+            else
+                exit();
+        }
+    });
+    async function handleCommand(name) {
+        return await commands.execute(name, { agent, mcp }, {
+            exit,
+            clearLog: () => store.clear(),
+            info: (t) => store.append({ kind: "system", text: t }),
+            error: (t) => store.append({ kind: "error", text: t }),
+            thinking: (on) => setStatus(on ? "thinking" : "idle"),
+            runSkill: (s) => handleSkill(s),
+        });
+    }
+    async function runAgent(entry, run) {
+        store.append(entry);
+        setStatus("thinking");
+        streamingRef.current = "";
+        startRef.current = Date.now();
+        setElapsed(0);
+        setUsage({ prompt: 0, completion: 0 });
+        timerRef.current = setInterval(() => {
+            setElapsed(Math.floor((Date.now() - startRef.current) / 1000));
+        }, 1000);
+        const controller = new AbortController();
+        abortRef.current = controller;
+        try {
+            await run(controller.signal);
+            flushStreaming();
+        }
+        catch (e) {
+            flushStreaming();
+            store.append({ kind: "error", text: e.message });
+        }
+        finally {
+            clearInterval(timerRef.current);
+            timerRef.current = undefined;
+            abortRef.current = null;
+            setStatus("idle");
+        }
+    }
+    async function handlePrompt(text) {
+        await runAgent({ kind: "user", text }, (signal) => agent.run(text, onEvent, signal));
+    }
+    async function handleSkill(skill) {
+        await runAgent({ kind: "skill", name: skill.name }, (signal) => agent.runSkill(skill, onEvent, signal));
+    }
+    return (_jsxs(Box, { flexDirection: "column", minWidth: 80, children: [_jsx(AppHeader, {}), _jsx(Box, { flexDirection: "column", paddingLeft: 1, paddingRight: 1, children: log.map((entry, i) => (_jsx(LogView, { entry: entry }, i))) }), status === "streaming" && streamingRef.current ? (_jsx(Box, { paddingLeft: 1, paddingRight: 1, children: _jsx(Markdown, { color: "green", children: streamingRef.current }) })) : null, status === "thinking" ? (_jsx(Box, { marginTop: 1, paddingLeft: 1, children: _jsx(Spinner, { label: "thinking", elapsed: elapsed, promptTokens: usage.prompt, completionTokens: usage.completion }) })) : null, status === "idle" ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { dimColor: true, children: ["[CTX ", compactDisplay(agent.contextTokens), "] \u00B7 ESC to stop \u00B7 \"/quit\" to leave"] }), _jsx(PromptOrCommandInput, { commands: allCmds, onCommand: handleCommand, onPrompt: handlePrompt })] })) : null] }));
+}
+export function startApp(agent, commands, mcp) {
+    process.stdout.write("\u001B[2J\u001B[H");
+    return render(_jsx(App, { agent: agent, commands: commands, mcp: mcp }), { exitOnCtrlC: false });
+}

package/dist/tui/AppHeader.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { getPackageInfo } from "../util/package.js";
+export function AppHeader() {
+    const pkginfo = getPackageInfo();
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: "red", bold: true, children: "Easy Agent" }), _jsxs(Text, { dimColor: true, children: [" v", pkginfo.version] })] }), _jsx(Text, { dimColor: true, children: process.cwd() })] }));
+}