@tjamescouch/gro 1.3.6 → 1.3.8

package/dist/mcp/client.js

@@ -0,0 +1,130 @@
+/**
+ * MCP client — connects to MCP servers, discovers tools, routes tool calls.
+ * Compatible with Claude Code's ~/.claude/settings.json mcpServers config.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { Logger } from "../logger.js";
+import { groError, asError, errorLogFields } from "../errors.js";
+export class McpManager {
+    constructor() {
+        this.servers = new Map();
+    }
+    /**
+     * Connect to all configured MCP servers and discover their tools.
+     */
+    async connectAll(configs) {
+        const entries = Object.entries(configs);
+        if (entries.length === 0)
+            return;
+        Logger.debug(`Connecting to ${entries.length} MCP server(s)...`);
+        await Promise.all(entries.map(([name, cfg]) => this.connectOne(name, cfg).catch((e) => {
+            const ge = groError("mcp_error", `MCP server "${name}" failed to connect: ${asError(e).message}`, {
+                retryable: true,
+                cause: e,
+            });
+            Logger.warn(ge.message, errorLogFields(ge));
+        })));
+    }
+    async connectOne(name, cfg) {
+        const transport = new StdioClientTransport({
+            command: cfg.command,
+            args: cfg.args ?? [],
+            env: { ...process.env, ...cfg.env },
+            cwd: cfg.cwd,
+            stderr: "pipe",
+        });
+        const client = new Client({ name: "gro", version: "0.2.0" }, { capabilities: {} });
+        await client.connect(transport);
+        // Discover tools
+        const toolsResult = await client.listTools();
+        const tools = (toolsResult.tools ?? []).map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            serverName: name,
+        }));
+        this.servers.set(name, { name, client, transport, tools });
+        Logger.debug(`MCP "${name}": ${tools.length} tool(s) available`);
+    }
+    /**
+     * Get all discovered tools in OpenAI function-calling format.
+     */
+    getToolDefinitions() {
+        const defs = [];
+        for (const server of this.servers.values()) {
+            for (const tool of server.tools) {
+                defs.push({
+                    type: "function",
+                    function: {
+                        name: tool.name,
+                        description: tool.description ?? "",
+                        parameters: tool.inputSchema ?? { type: "object", properties: {} },
+                    },
+                });
+            }
+        }
+        return defs;
+    }
+    /**
+     * Execute a tool call by routing it to the correct MCP server.
+     */
+    async callTool(name, args) {
+        // Find which server provides this tool
+        for (const server of this.servers.values()) {
+            const tool = server.tools.find(t => t.name === name);
+            if (tool) {
+                try {
+                    const result = await server.client.callTool({ name, arguments: args }, undefined, { timeout: 5 * 60 * 1000 });
+                    // Extract text content from result
+                    if (Array.isArray(result.content)) {
+                        return result.content
+                            .map((c) => {
+                            if (c.type === "text")
+                                return c.text;
+                            return JSON.stringify(c);
+                        })
+                            .join("\n");
+                    }
+                    return JSON.stringify(result);
+                }
+                catch (e) {
+                    const err = asError(e);
+                    const ge = groError("mcp_error", `MCP tool "${name}" (server: ${server.name}) failed: ${err.message}`, {
+                        retryable: true,
+                        cause: e,
+                    });
+                    Logger.error(`MCP tool call failed [${server.name}/${name}]:`, errorLogFields(ge));
+                    throw ge;
+                }
+            }
+        }
+        const ge = groError("mcp_error", `No MCP server provides tool "${name}"`, { retryable: false });
+        Logger.error(ge.message, errorLogFields(ge));
+        throw ge;
+    }
+    /**
+     * Check if a tool name is provided by any connected MCP server.
+     */
+    hasTool(name) {
+        for (const server of this.servers.values()) {
+            if (server.tools.some(t => t.name === name))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Disconnect all MCP servers.
+     */
+    async disconnectAll() {
+        for (const server of this.servers.values()) {
+            try {
+                await server.client.close();
+            }
+            catch (e) {
+                Logger.debug(`MCP server "${server.name}" close error: ${asError(e).message}`);
+            }
+        }
+        this.servers.clear();
+    }
+}

package/dist/mcp/index.js

@@ -0,0 +1 @@
+export { McpManager } from "./client.js";

package/dist/memory/advanced-memory.js

@@ -0,0 +1,210 @@
+import { AgentMemory } from "./agent-memory.js";
+import { saveSession, loadSession, ensureGroDir } from "../session.js";
+/**
+ * AdvancedMemory — swim-lane summarization with token budgeting.
+ *
+ * Maintains three lanes (assistant / system / user) and summarizes independently.
+ * Uses character-based token estimation with high/low watermark hysteresis.
+ * Background summarization never blocks the caller.
+ */
+export class AdvancedMemory extends AgentMemory {
+    constructor(args) {
+        super(args.systemPrompt);
+        this.driver = args.driver;
+        this.model = args.model;
+        this.summarizerDriver = args.summarizerDriver ?? args.driver;
+        this.summarizerModel = args.summarizerModel ?? args.model;
+        this.contextTokens = Math.max(2048, Math.floor(args.contextTokens ?? 8192));
+        this.reserveHeaderTokens = Math.max(0, Math.floor(args.reserveHeaderTokens ?? 1200));
+        this.reserveResponseTokens = Math.max(0, Math.floor(args.reserveResponseTokens ?? 800));
+        this.highRatio = Math.min(0.95, Math.max(0.55, args.highRatio ?? 0.70));
+        this.lowRatio = Math.min(this.highRatio - 0.05, Math.max(0.35, args.lowRatio ?? 0.50));
+        this.summaryRatio = Math.min(0.50, Math.max(0.15, args.summaryRatio ?? 0.35));
+        this.avgCharsPerToken = Math.max(1.5, Number(args.avgCharsPerToken ?? 4));
+        this.keepRecentPerLane = Math.max(1, Math.floor(args.keepRecentPerLane ?? 4));
+        this.keepRecentTools = Math.max(0, Math.floor(args.keepRecentTools ?? 3));
+    }
+    async load(id) {
+        const session = loadSession(id);
+        if (session) {
+            this.messagesBuffer = session.messages;
+        }
+    }
+    async save(id) {
+        ensureGroDir();
+        saveSession(id, this.messagesBuffer, {
+            id,
+            provider: "unknown",
+            model: this.model,
+            createdAt: new Date().toISOString(),
+        });
+    }
+    async onAfterAdd() {
+        const budget = this.budgetTokens();
+        const estTok = this.estimateTokens(this.messagesBuffer);
+        if (estTok <= Math.floor(this.highRatio * budget))
+            return;
+        await this.runOnce(async () => {
+            const budget2 = this.budgetTokens();
+            const estTok2 = this.estimateTokens(this.messagesBuffer);
+            if (estTok2 <= Math.floor(this.highRatio * budget2))
+                return;
+            const { firstSystemIndex, assistant, user, system, tool, other } = this.partition();
+            const tailN = this.keepRecentPerLane;
+            const olderAssistant = assistant.slice(0, Math.max(0, assistant.length - tailN));
+            const keepAssistant = assistant.slice(Math.max(0, assistant.length - tailN));
+            const sysHead = firstSystemIndex === 0 ? [this.messagesBuffer[0]] : [];
+            const remainingSystem = firstSystemIndex === 0 ? system.slice(1) : system.slice(0);
+            const olderSystem = remainingSystem.slice(0, Math.max(0, remainingSystem.length - tailN));
+            const keepSystem = remainingSystem.slice(Math.max(0, remainingSystem.length - tailN));
+            const olderUser = user.slice(0, Math.max(0, user.length - tailN));
+            const keepUser = user.slice(Math.max(0, user.length - tailN));
+            const keepTools = tool.slice(Math.max(0, tool.length - this.keepRecentTools));
+            const preserved = [
+                ...sysHead, ...keepAssistant, ...keepSystem, ...keepUser, ...keepTools, ...other,
+            ];
+            const preservedTok = this.estimateTokens(preserved);
+            const lowTarget = Math.floor(this.lowRatio * budget2);
+            const maxSummaryTok = Math.floor(this.summaryRatio * budget2);
+            if (preservedTok <= lowTarget) {
+                const rebuilt = this.ordered([], sysHead, keepAssistant, keepSystem, keepUser, keepTools, other);
+                this.messagesBuffer.splice(0, this.messagesBuffer.length, ...rebuilt);
+                return;
+            }
+            const removedCharA = this.totalChars(olderAssistant);
+            const removedCharS = this.totalChars(olderSystem);
+            const removedCharU = this.totalChars(olderUser);
+            const removedTotal = Math.max(1, removedCharA + removedCharS + removedCharU);
+            const totalSummaryBudget = Math.max(64, Math.min(maxSummaryTok, lowTarget - preservedTok));
+            const budgetA = Math.max(48, Math.floor(totalSummaryBudget * (removedCharA / removedTotal)));
+            const budgetS = Math.max(48, Math.floor(totalSummaryBudget * (removedCharS / removedTotal)));
+            const budgetU = Math.max(48, Math.floor(totalSummaryBudget * (removedCharU / removedTotal)));
+            const [sumA, sumS, sumU] = await Promise.all([
+                olderAssistant.length ? this.summarizeLane("assistant", olderAssistant, budgetA) : "",
+                olderSystem.length ? this.summarizeLane("system", olderSystem, budgetS) : "",
+                olderUser.length ? this.summarizeLane("user", olderUser, budgetU) : "",
+            ]);
+            const summaries = [];
+            if (sumA)
+                summaries.push({ from: "Me", role: "assistant", content: `ASSISTANT SUMMARY:\n${sumA}` });
+            if (sumS)
+                summaries.push({ from: "System", role: "system", content: `SYSTEM SUMMARY:\n${sumS}` });
+            if (sumU)
+                summaries.push({ from: "Memory", role: "user", content: `USER SUMMARY:\n${sumU}` });
+            const rebuilt = this.ordered(summaries, sysHead, keepAssistant, keepSystem, keepUser, keepTools, other);
+            this.messagesBuffer.splice(0, this.messagesBuffer.length, ...rebuilt);
+            // Final clamp
+            let finalTok = this.estimateTokens(this.messagesBuffer);
+            if (finalTok > lowTarget) {
+                const pruned = [];
+                for (const m of this.messagesBuffer) {
+                    pruned.push(m);
+                    finalTok = this.estimateTokens(pruned);
+                    if (finalTok > lowTarget && m.role !== "system") {
+                        pruned.pop();
+                    }
+                }
+                this.messagesBuffer.splice(0, this.messagesBuffer.length, ...pruned);
+            }
+        });
+    }
+    budgetTokens() {
+        return Math.max(512, this.contextTokens - this.reserveHeaderTokens - this.reserveResponseTokens);
+    }
+    estimateTokens(msgs) {
+        return Math.ceil(this.totalChars(msgs) / this.avgCharsPerToken);
+    }
+    totalChars(msgs) {
+        let c = 0;
+        for (const m of msgs) {
+            const s = String(m.content ?? "");
+            if (m.role === "tool" && s.length > 24_000)
+                c += 24_000;
+            else
+                c += s.length;
+            c += 32;
+        }
+        return c;
+    }
+    partition() {
+        const assistant = [];
+        const user = [];
+        const system = [];
+        const tool = [];
+        const other = [];
+        for (const m of this.messagesBuffer) {
+            switch (m.role) {
+                case "assistant":
+                    assistant.push(m);
+                    break;
+                case "user":
+                    user.push(m);
+                    break;
+                case "system":
+                    system.push(m);
+                    break;
+                case "tool":
+                    tool.push(m);
+                    break;
+                default:
+                    other.push(m);
+                    break;
+            }
+        }
+        const firstSystemIndex = this.messagesBuffer.findIndex(x => x.role === "system");
+        return { firstSystemIndex, assistant, user, system, tool, other };
+    }
+    ordered(summaries, sysHead, keepA, keepS, keepU, keepT, other) {
+        const keepSet = new Set([...sysHead, ...keepA, ...keepS, ...keepU, ...keepT, ...other]);
+        const rest = [];
+        for (const m of this.messagesBuffer) {
+            if (keepSet.has(m))
+                rest.push(m);
+        }
+        const orderedSummaries = [
+            ...summaries.filter(s => s.role === "assistant"),
+            ...summaries.filter(s => s.role === "system"),
+            ...summaries.filter(s => s.role === "user"),
+        ];
+        return [...orderedSummaries, ...rest];
+    }
+    async summarizeLane(laneName, messages, tokenBudget) {
+        if (messages.length === 0 || tokenBudget <= 0)
+            return "";
+        const approxChars = Math.max(120, Math.floor(tokenBudget * this.avgCharsPerToken));
+        const header = (() => {
+            switch (laneName) {
+                case "assistant": return "Summarize prior ASSISTANT replies (decisions, plans, code edits, shell commands and outcomes).";
+                case "system": return "Summarize SYSTEM instructions (rules, goals, constraints) without changing their intent.";
+                case "user": return "Summarize USER requests, feedback, constraints, and acceptance criteria.";
+            }
+        })();
+        let acc = "";
+        for (const m of messages) {
+            let c = String(m.content ?? "");
+            if (c.length > 4000)
+                c = c.slice(0, 4000) + "\n…(truncated)…";
+            const next = `- ${laneName.toUpperCase()}: ${c}\n\n`;
+            if (acc.length + next.length > approxChars * 3)
+                break;
+            acc += next;
+        }
+        const sys = {
+            role: "system",
+            from: "System",
+            content: [
+                "You are a precise summarizer.",
+                "Output concise bullet points; preserve facts, tasks, file paths, commands, constraints.",
+                `Hard limit: ~${approxChars} characters total.`,
+                "Avoid fluff; keep actionable details.",
+            ].join(" "),
+        };
+        const usr = {
+            role: "user",
+            from: "User",
+            content: `${header}\n\nTranscript:\n${acc}`,
+        };
+        const out = await this.summarizerDriver.chat([sys, usr], { model: this.summarizerModel });
+        return String(out?.text ?? "").trim();
+    }
+}

package/dist/memory/agent-memory.js

@@ -0,0 +1,52 @@
+/**
+ * Base class for agent memory with background summarization support.
+ * Subclasses call `runOnce` to serialize/queue summarization so callers never block.
+ */
+export class AgentMemory {
+    constructor(systemPrompt) {
+        this.messagesBuffer = [];
+        this.summarizing = false;
+        this.pending = false;
+        if (systemPrompt && systemPrompt.trim().length > 0) {
+            this.messagesBuffer.push({ role: "system", content: systemPrompt, from: "System" });
+        }
+    }
+    async add(msg) {
+        this.messagesBuffer.push(msg);
+        await this.onAfterAdd();
+    }
+    async addIfNotExists(msg) {
+        const exists = this.messagesBuffer.some(m => m.content === msg.content && m.role === msg.role);
+        if (!exists) {
+            this.messagesBuffer.push(msg);
+            await this.onAfterAdd();
+        }
+    }
+    messages() {
+        return [...this.messagesBuffer];
+    }
+    nonSystemCount() {
+        if (this.messagesBuffer.length === 0)
+            return 0;
+        return this.messagesBuffer[0].role === "system"
+            ? this.messagesBuffer.length - 1
+            : this.messagesBuffer.length;
+    }
+    async runOnce(task) {
+        if (this.summarizing) {
+            this.pending = true;
+            return;
+        }
+        this.summarizing = true;
+        try {
+            await task();
+        }
+        finally {
+            this.summarizing = false;
+            if (this.pending) {
+                this.pending = false;
+                void this.runOnce(task);
+            }
+        }
+    }
+}

package/dist/memory/agenthnsw.js

@@ -0,0 +1,86 @@
+/**
+ * agenthnsw adapter — optional dynamic import.
+ *
+ * The "agenthnsw" package is an optional dependency.  We load it at
+ * runtime via a dynamic `import()` so that TypeScript compilation and
+ * Docker builds succeed even when the package is not installed.
+ *
+ * If agenthnsw is missing at runtime the factory function
+ * `createAgentHnswIndex()` will throw a clear error.
+ */
+/**
+ * Dynamically import "agenthnsw".
+ *
+ * We use `eval("(m) => import(m)")` to prevent the TypeScript compiler
+ * and bundlers from resolving the specifier at compile time.
+ */
+async function importAgentHnsw() {
+    try {
+        const dynImport = eval("(m) => import(m)");
+        return await dynImport("agenthnsw");
+    }
+    catch (err) {
+        throw new Error(`Optional dependency "agenthnsw" is not installed. ` +
+            `Install it with:  npm install agenthnsw\n` +
+            `Original error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ── AgentHnswIndex class ────────────────────────────────────────────────────
+export class AgentHnswIndex {
+    constructor(opts) {
+        this.idx = null;
+        this.metric = opts?.metric;
+    }
+    /** Lazily initialise the underlying index on first use. */
+    async ensureIndex() {
+        if (!this.idx) {
+            const mod = await importAgentHnsw();
+            this.idx = new mod.InMemoryLinearIndex({ metric: this.metric });
+        }
+        return this.idx;
+    }
+    async upsert(record) {
+        const idx = await this.ensureIndex();
+        await idx.upsert({ id: record.id, vector: record.vector, metadata: record.metadata });
+    }
+    async upsertMany(records) {
+        const idx = await this.ensureIndex();
+        await idx.upsertMany(records.map((r) => ({ id: r.id, vector: r.vector, metadata: r.metadata })));
+    }
+    async search(query, k) {
+        const idx = await this.ensureIndex();
+        const res = await idx.search(query, k);
+        return res.map((r) => ({
+            id: r.id,
+            score: r.score,
+            metadata: r.metadata,
+        }));
+    }
+    async delete(id) {
+        const idx = await this.ensureIndex();
+        await idx.delete(id);
+    }
+    async save(dir) {
+        const idx = await this.ensureIndex();
+        await idx.save(dir);
+    }
+    async load(dir) {
+        const idx = await this.ensureIndex();
+        await idx.load(dir);
+    }
+    async stats() {
+        const idx = await this.ensureIndex();
+        return await idx.stats();
+    }
+}
+// ── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create an AgentHnswIndex.
+ *
+ * The underlying "agenthnsw" package is loaded lazily — this function
+ * itself never throws even when the package is absent.  The first call
+ * to any index method will attempt the dynamic import.
+ */
+export function createAgentHnswIndex(opts) {
+    return new AgentHnswIndex(opts);
+}

package/{src/memory/index.ts → dist/memory/index.js}

@@ -1,6 +1,5 @@
 export * from "./vector-index.js";
 export * from "./agenthnsw.js";
-
 export { AgentMemory } from "./agent-memory.js";
 export { AdvancedMemory } from "./advanced-memory.js";
 export { SimpleMemory } from "./simple-memory.js";

package/dist/memory/simple-memory.js

@@ -0,0 +1,34 @@
+import { AgentMemory } from "./agent-memory.js";
+import { saveSession, loadSession, ensureGroDir } from "../session.js";
+/**
+ * SimpleMemory — unbounded message buffer.
+ * No summarization, no token budgeting. Useful for short conversations
+ * or when the caller manages context externally.
+ */
+export class SimpleMemory extends AgentMemory {
+    constructor(systemPrompt) {
+        super(systemPrompt);
+        this.provider = "";
+        this.model = "";
+    }
+    setMeta(provider, model) {
+        this.provider = provider;
+        this.model = model;
+    }
+    async load(id) {
+        const session = loadSession(id);
+        if (session) {
+            this.messagesBuffer = session.messages;
+        }
+    }
+    async save(id) {
+        ensureGroDir();
+        saveSession(id, this.messagesBuffer, {
+            id,
+            provider: this.provider,
+            model: this.model,
+            createdAt: new Date().toISOString(),
+        });
+    }
+    async onAfterAdd() { }
+}

package/dist/memory/vector-index.js

@@ -0,0 +1,7 @@
+/**
+ * Pluggable vector index interface for retrieval-backed memory.
+ *
+ * This is intentionally small so backends can live in separate packages
+ * (e.g. agenthnsw) and be imported by gro.
+ */
+export {};

package/dist/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@tjamescouch/gro",
+  "version": "1.3.2",
+  "description": "Provider-agnostic LLM runtime with context management",
+  "type": "module",
+  "scripts": {
+    "start": "npx tsx src/main.ts",
+    "build": "npx tsc && cp package.json dist/",
+    "build:bun": "bun build src/main.ts --outdir dist --target bun",
+    "test": "npx tsx --test tests/*.test.ts",
+    "test:bun": "bun test"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "isexe": "^4.0.0"
+  }
+}