@vietor/easy-agent 0.1.1 → 0.3.1

package/README.md

@@ -42,7 +42,7 @@ Create `~/.easy-agent.json` in your home directory:
 
 ### Optional: MCP servers
 
-Add an `mcpServers` map to expose external tools through the Model Context Protocol. Each entry spawns a local process (stdio transport):
+Add an `mcpServers` map to expose external tools through the Model Context Protocol. Each entry is either a local process (stdio) or a remote endpoint (SSE / Streamable HTTP):
 
 ```json
 {
@@ -50,23 +50,24 @@ Add an `mcpServers` map to expose external tools through the Model Context Proto
   "mcpServers": {
     "chrome-devtools": {
       "command": "npx",
-      "args": [
-        "chrome-devtools-mcp@latest",
-        "--auto-connect",
-        "--accept-insecure-certs"
-      ]
+      "args": ["chrome-devtools-mcp@latest", "--auto-connect", "--accept-insecure-certs"]
+    },
+    "remote-server": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp",
+      "headers": { "Authorization": "Bearer your-token" }
     }
   }
 }
 ```
 
-Only `command` is required; `args` and `env` are optional. MCP tools become available to the agent as `MCP__<server>__<tool>`. If a server fails to connect within 30s, it is disabled and the error is shown in the TUI — the rest keep running.
+A stdio server omits `type` (or sets `"stdio"`); only `command` is required, `args` and `env` are optional. A remote server sets `type` to `"sse"` or `"http"` with a required `url`; `headers` is optional and sent with every request (use it for static auth tokens). Either entry accepts an optional `enabled` (defaults to `true`); set `false` to keep a server configured but skip starting it. MCP tools become available to the agent as `MCP__<server>__<tool>`. If a server fails to connect within 30s, it is disabled and the error is shown in the TUI — for stdio servers the captured stderr tail is included to help diagnose startup failures — and the rest keep running.
 
 ### Optional: Agent instructions
 
 Easy Agent reads instructions files and appends them to the system prompt, so you can set persistent rules, conventions, or preferences. It looks in two places:
 
-1. **Global** — your home directory, applied to every session. Checks `~/.agents/AGENTS.md` first, then `~/.claude/CLAUDE.md`; uses the first one found.
+1. **Global** — your home directory, applied to every conversation. Checks `~/.agents/AGENTS.md` first, then `~/.claude/CLAUDE.md`; uses the first one found.
 2. **Project** — your current working directory, applied per-project. Checks `./AGENTS.md` first, then `./CLAUDE.md`; uses the first one found.
 
 Both global and project files are loaded and concatenated into the system prompt if they exist.
@@ -104,22 +105,23 @@ Launch the TUI:
 easy-agent
 ```
 
-Type a prompt and press Enter. The agent streams its reply and calls tools as needed, showing each tool call and a one-line preview of its result. It iterates until the task is done (capped at 25 tool rounds per turn).
+Type a prompt and press Enter. The agent streams its reply and calls tools as needed, showing each tool call and a one-line preview of its result. It iterates until the task is done (capped at 50 tool rounds per turn).
 
 Built-in tools:
 
 - **Shell** — run shell commands using this platform's native syntax.
-- **FileRead** — read a file's full contents.
+- **FileRead** — read a file with line numbers; supports `offset`/`limit` for paging large files.
 - **FileWrite** — create or fully overwrite a file.
-- **FileEdit** — replace one exact, unique match within a file.
+- **FileEdit** — replace exact matches in a file; `replace_all` for every occurrence.
 - **Glob** — list files, optionally filtered by a glob pattern.
-- **Grep** — search file contents by regex.
+- **Grep** — search file contents by regex with `glob`/`type` filters, context lines, case-insensitive, and `files_with_matches`/`count` output modes.
 - **WebFetch** — fetch a URL as markdown or text.
+- **AskUser** — ask the user a question and wait for their answer.
 
 Slash commands:
 
 - `/mcp` — list linked MCP servers, their status, and exposed tools.
 - `/clear` — reset the conversation.
 - `/compact` — compress the conversation into a summary to free context.
-- `/export` — save the current session to `session-{timestamp}.jsonl`.
+- `/export` — save the current conversation to `conversation-{timestamp}.jsonl`.
 - `/quit` or `/exit` — leave the app.

package/dist/cmds/builtin.js

@@ -1,7 +1,7 @@
 import { writeFileSync } from "node:fs";
 export const exitCommand = {
     name: "exit",
-    description: "Exit the session",
+    description: "Exit the conversation",
     async execute(_ctx, host) {
         host.exit();
     },
@@ -9,9 +9,8 @@ export const exitCommand = {
 export const clearCommand = {
     name: "clear",
     description: "Clear the conversation and log",
-    async execute(ctx, host) {
-        ctx.agent.clear();
-        host.clearLog();
+    async execute(ctx) {
+        ctx.session.clear();
     },
 };
 export const mcpCommand = {
@@ -22,7 +21,7 @@ export const mcpCommand = {
         const text = servers.length
             ? [
                 "MCP servers:",
-                ...servers.map((s) => `❯ ${s.name} ⋅ ${s.status} ∶ ${s.tools.join(", ") || "(no tools)"}`),
+                ...servers.map((s) => `❯ ${s.name} ⋅ ${s.type} ⋅ ${s.status} ∶ ${s.tools.join(", ") || "(no tools)"}`),
             ].join("\n")
             : "No MCP servers linked.";
         host.info(text);
@@ -34,8 +33,9 @@ export const compactCommand = {
     async execute(ctx, host) {
         host.thinking(true);
         try {
-            await ctx.agent.compact();
-            host.info("context compacted");
+            const ok = await ctx.session.compact();
+            if (ok)
+                host.info("context compacted");
         }
         catch (e) {
             host.error(e.message);
@@ -47,14 +47,14 @@ export const compactCommand = {
 };
 export const exportCommand = {
     name: "export",
-    description: "Export the session to a JSONL file",
+    description: "Export the conversation to a JSONL file",
     async execute(ctx, host) {
         try {
             const d = new Date();
             const pad = (n) => String(n).padStart(2, "0");
             const ts = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
-            const file = `session-${ts}.jsonl`;
-            const lines = ctx.agent
+            const file = `conversation-${ts}.jsonl`;
+            const lines = ctx.session
                 .export()
                 .map((m) => JSON.stringify(m))
                 .join("\n");

package/dist/cmds/registry.js

@@ -10,6 +10,9 @@ export class CommandRegistry {
             description: t.description,
         }));
     }
+    exists(name) {
+        return this.commands.has(name);
+    }
     async execute(command, ctx, host) {
         const cmd = this.commands.get(command);
         if (!cmd) {

package/dist/config.js

@@ -8,19 +8,41 @@ const LLMConfig = z.object({
     apiKey: z.string(),
     model: z.string(),
 });
-const MCPServerConfig = z.object({
+const StdioServerConfig = z.object({
+    type: z.literal("stdio").optional(),
     command: z.string(),
     args: z.array(z.string()).optional(),
     env: z.record(z.string(), z.string()).optional(),
+    enabled: z.boolean().optional(),
 });
+const RemoteServerConfig = z.object({
+    type: z.enum(["sse", "http"]),
+    url: z.string().url(),
+    headers: z.record(z.string(), z.string()).optional(),
+    enabled: z.boolean().optional(),
+});
+const MCPServerConfig = z.union([StdioServerConfig, RemoteServerConfig]);
 const Config = z.object({
     llm: LLMConfig,
     mcpServers: z.record(z.string(), MCPServerConfig).optional(),
 });
 export function loadConfig() {
     const path = join(homedir(), CONFIG_FILE);
-    const raw = JSON.parse(readFileSync(path, "utf-8"));
-    const result = Config.safeParse(raw);
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch {
+        throw new Error(`Config not found: create ~/${CONFIG_FILE} (see README for format).`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in ~/${CONFIG_FILE}.`);
+    }
+    const result = Config.safeParse(parsed);
     if (!result.success) {
         const issues = result.error.issues
             .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)

package/dist/core/agent.js

@@ -1,63 +1,70 @@
 import { withAbort } from "../util/async.js";
 const STALL_THRESHOLD = 3;
+const MAX_TURNS = 50;
 const COMPACT_PROMPT = "Summarize this conversation into a concise context summary. Preserve the user's goal, decisions made, files touched, and current progress. Write the summary in the same language the user used in the conversation. Begin your reply with \"Summary of conversation so far:\".";
 export class Agent {
     llm;
-    session;
+    conversation;
     tools;
-    constructor(llm, session, tools) {
+    ask;
+    constructor(llm, conversation, tools, ask) {
         this.llm = llm;
-        this.session = session;
+        this.conversation = conversation;
         this.tools = tools;
+        this.ask = ask;
     }
     get contextTokens() {
-        return this.session.getEstimatedTokens();
+        return this.conversation.getEstimatedTokens();
     }
     clear() {
-        this.session.clear();
+        this.conversation.clear();
     }
     export() {
-        return this.session.export();
+        return this.conversation.export();
     }
-    async compact() {
-        const history = this.session.toLLM().slice(1);
+    async compact(signal) {
+        const history = this.conversation.toLLM().slice(1);
         if (history.length === 0)
             return;
         const request = [
             ...history,
             { role: "user", content: COMPACT_PROMPT },
         ];
-        const msg = await this.llm.chat(request, []);
-        this.session.compact(msg.content || "");
+        const msg = await this.llm.chat({ messages: request, tools: [], signal });
+        this.conversation.compact(msg.content || "");
     }
     async run(userInput, onEvent, signal) {
-        this.session.createCheckpoint();
-        try {
-            this.session.add({ role: "user", content: userInput });
-            await this.loop(onEvent, signal);
-        }
-        finally {
-            this.session.removeCheckpoint();
-        }
+        await this.runTurn({ role: "user", content: userInput }, onEvent, signal);
     }
     async runSkill(skill, onEvent, signal) {
-        this.session.createCheckpoint();
+        await this.runTurn({ role: "skill", name: skill.name, content: skill.prompt }, onEvent, signal);
+    }
+    async runTurn(msg, onEvent, signal) {
+        this.conversation.add(msg);
+        this.conversation.createSnapshot();
         try {
-            this.session.add({ role: "skill", name: skill.name, content: skill.prompt });
             await this.loop(onEvent, signal);
         }
         finally {
-            this.session.removeCheckpoint();
+            this.conversation.clearSnapshot();
         }
     }
     async loop(onEvent, signal) {
         await withAbort(async (aborted) => {
             let lastSig = "";
             let stall = 0;
+            let turns = 0;
             while (true) {
                 let msg;
                 try {
-                    msg = await this.llm.chat(this.session.toLLM(), this.tools.schemas(), (text) => onEvent?.({ type: "delta", text }), (attempt, max) => onEvent?.({ type: "retry", attempt, max }), (promptTokens, completionTokens) => onEvent?.({ type: "usage", promptTokens, completionTokens }), signal);
+                    msg = await this.llm.chat({
+                        messages: this.conversation.toLLM(),
+                        tools: this.tools.schemas(),
+                        onDelta: (text) => onEvent?.({ type: "delta", text }),
+                        onRetry: (attempt, max) => onEvent?.({ type: "retry", attempt, max }),
+                        onUsage: (promptTokens, completionTokens) => onEvent?.({ type: "usage", promptTokens, completionTokens }),
+                        signal,
+                    });
                 }
                 catch (e) {
                     if (aborted())
@@ -65,7 +72,7 @@ export class Agent {
                     onEvent?.({ type: "error", text: e.message });
                     return;
                 }
-                this.session.add(msg);
+                this.conversation.add(msg);
                 if (!msg.tool_calls?.length)
                     return;
                 if (aborted())
@@ -79,7 +86,11 @@ export class Agent {
                     onEvent?.({ type: "error", text: "agent stalled: repeated identical tool calls" });
                     return;
                 }
-                await Promise.all(msg.tool_calls.map(async (call) => {
+                if (++turns >= MAX_TURNS) {
+                    onEvent?.({ type: "error", text: `agent exceeded max turns (${MAX_TURNS})` });
+                    return;
+                }
+                const results = await Promise.all(msg.tool_calls.map(async (call) => {
                     let args = {};
                     let argsError = "";
                     if (call.function.arguments) {
@@ -93,22 +104,29 @@ export class Agent {
                     const summary = this.tools.summarize(call.function.name, args);
                     onEvent?.({ type: "tool_start", id: call.id, name: call.function.name, summary });
                     if (aborted())
-                        return;
+                        return null;
+                    const ctx = { signal, ask: this.ask };
                     const result = argsError
                         ? { content: argsError, isError: true }
-                        : await this.tools.execute(call.function.name, args);
+                        : await this.tools.execute(call.function.name, args, ctx);
                     if (aborted())
-                        return;
-                    onEvent?.({ type: "tool_end", id: call.id, name: call.function.name, result: result.content, isError: result.isError });
-                    this.session.add({ role: "tool", tool_call_id: call.id, content: result.content });
+                        return null;
+                    onEvent?.({ type: "tool_end", id: call.id, result: result.content, isError: result.isError });
+                    return { id: call.id, content: result.content };
                 }));
                 if (aborted())
                     return;
+                for (const r of results) {
+                    if (r)
+                        this.conversation.add({ role: "tool", tool_call_id: r.id, content: r.content });
+                }
+                if (aborted())
+                    return;
             }
         }, {
             signal,
             onAbort: () => {
-                this.session.restoreCheckpoint();
+                this.conversation.restoreFromSnapshot();
                 onEvent?.({ type: "interrupted" });
             },
         });

package/dist/core/conversation.js

@@ -0,0 +1,82 @@
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    const cjk = (text.match(/[一-龥぀-ヿ가-힯]/g) || []).length;
+    const wordChars = (text.match(/[a-zA-Z0-9']/g) || []).length;
+    const words = (text.match(/[a-zA-Z0-9']+/g) || []).length;
+    const rest = text.length - cjk - wordChars;
+    return Math.ceil(cjk * 1.6 + words * 1.3 + rest * 0.3);
+}
+function messageText(msg) {
+    const parts = [];
+    if (typeof msg.content === "string")
+        parts.push(msg.content);
+    else if (Array.isArray(msg.content)) {
+        for (const p of msg.content) {
+            if (p.type === "text")
+                parts.push(p.text);
+        }
+    }
+    if ("tool_calls" in msg && msg.tool_calls) {
+        for (const tc of msg.tool_calls) {
+            if (tc.function?.name)
+                parts.push(tc.function.name);
+            if (tc.function?.arguments)
+                parts.push(tc.function.arguments);
+        }
+    }
+    return parts.join(" ");
+}
+export class Conversation {
+    system;
+    systemEstimateTokens;
+    messages = [];
+    estimatedTokens = 0;
+    messagesSnapshot;
+    estimatedTokensSnapshot = 0;
+    constructor(system) {
+        this.system = system;
+        this.systemEstimateTokens = estimateTokens(system);
+        this.messages.push({ role: "system", content: system });
+        this.estimatedTokens = this.systemEstimateTokens;
+    }
+    getEstimatedTokens() {
+        return this.estimatedTokens;
+    }
+    add(msg) {
+        this.messages.push(msg);
+        this.estimatedTokens += estimateTokens(messageText(msg));
+    }
+    toLLM() {
+        return this.messages.map((m) => (m.role === "skill" ? { role: "user", name: m.name, content: m.content } : m));
+    }
+    export() {
+        return this.messages.slice(1);
+    }
+    clear() {
+        this.messages = [{ role: "system", content: this.system }];
+        this.estimatedTokens = this.systemEstimateTokens;
+    }
+    compact(summary) {
+        this.messages = [
+            { role: "system", content: this.system },
+            { role: "assistant", content: summary },
+        ];
+        this.estimatedTokens = this.systemEstimateTokens + estimateTokens(summary);
+    }
+    createSnapshot() {
+        this.messagesSnapshot = this.messages.slice();
+        this.estimatedTokensSnapshot = this.estimatedTokens;
+    }
+    restoreFromSnapshot() {
+        const snap = this.messagesSnapshot;
+        if (snap) {
+            this.messages = snap.slice();
+            this.estimatedTokens = this.estimatedTokensSnapshot;
+        }
+    }
+    clearSnapshot() {
+        this.messagesSnapshot = undefined;
+        this.estimatedTokensSnapshot = 0;
+    }
+}

package/dist/core/logstore.js

@@ -0,0 +1,49 @@
+export class LogStore {
+    entries = [];
+    version = 0;
+    listeners = new Set();
+    getSnapshot = () => this.version;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    get all() {
+        return this.entries;
+    }
+    append(entry) {
+        this.entries.push(entry);
+        this.version++;
+        this.emit();
+    }
+    setResult(id, result, isError) {
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            const entry = this.entries[i];
+            if (entry.kind === "tool" && entry.id === id && entry.result === null) {
+                this.entries[i] = { ...entry, result, isError };
+                this.version++;
+                this.emit();
+                return;
+            }
+        }
+    }
+    setAnswer(id, answer) {
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            const entry = this.entries[i];
+            if (entry.kind === "question" && entry.id === id && entry.answer === null) {
+                this.entries[i] = { ...entry, answer };
+                this.version++;
+                this.emit();
+                return;
+            }
+        }
+    }
+    clear() {
+        this.entries = [];
+        this.version++;
+        this.emit();
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}