@tjamescouch/gro 1.3.5 → 1.3.7

package/dist/drivers/anthropic.js

@@ -0,0 +1,256 @@
+/**
+ * Anthropic Messages API driver.
+ * Direct HTTP — no SDK dependency.
+ */
+import { Logger } from "../logger.js";
+import { rateLimiter } from "../utils/rate-limiter.js";
+import { timedFetch } from "../utils/timed-fetch.js";
+import { MAX_RETRIES, isRetryable, retryDelay, sleep } from "../utils/retry.js";
+import { groError, asError, isGroError, errorLogFields } from "../errors.js";
+/**
+ * Convert tool definitions from OpenAI format to Anthropic format.
+ * OpenAI: { type: "function", function: { name, description, parameters } }
+ * Anthropic: { name, description, input_schema }
+ */
+function convertToolDefs(tools) {
+    return tools.map(t => {
+        if (t.type === "function" && t.function) {
+            return {
+                type: "custom",
+                name: t.function.name,
+                description: t.function.description || "",
+                input_schema: t.function.parameters || { type: "object", properties: {} },
+            };
+        }
+        // Already in Anthropic format — ensure type is set
+        if (!t.type)
+            return { type: "custom", ...t };
+        return t;
+    });
+}
+/**
+ * Convert internal messages (OpenAI-style) to Anthropic Messages API format.
+ *
+ * Key differences:
+ * - Assistant tool calls become content blocks with type "tool_use"
+ * - Tool result messages become user messages with type "tool_result" content blocks
+ * - Anthropic requires strictly alternating user/assistant roles
+ */
+function convertMessages(messages) {
+    let systemPrompt;
+    const apiMessages = [];
+    for (const m of messages) {
+        if (m.role === "system") {
+            systemPrompt = systemPrompt ? systemPrompt + "\n" + m.content : m.content;
+            continue;
+        }
+        if (m.role === "assistant") {
+            const content = [];
+            if (m.content)
+                content.push({ type: "text", text: m.content });
+            // Convert OpenAI-style tool_calls to Anthropic tool_use blocks
+            const toolCalls = m.tool_calls;
+            if (Array.isArray(toolCalls)) {
+                for (const tc of toolCalls) {
+                    let input;
+                    try {
+                        input = JSON.parse(tc.function.arguments || "{}");
+                    }
+                    catch {
+                        input = {};
+                    }
+                    content.push({
+                        type: "tool_use",
+                        id: tc.id,
+                        name: tc.function.name,
+                        input,
+                    });
+                }
+            }
+            if (content.length > 0) {
+                apiMessages.push({ role: "assistant", content });
+            }
+            continue;
+        }
+        if (m.role === "tool") {
+            // Tool results must be in a user message with tool_result content blocks
+            const block = {
+                type: "tool_result",
+                tool_use_id: m.tool_call_id,
+                content: m.content,
+            };
+            // Group consecutive tool results into a single user message
+            const last = apiMessages[apiMessages.length - 1];
+            if (last && last.role === "user" && Array.isArray(last.content) &&
+                last.content.length > 0 && last.content[0].type === "tool_result") {
+                last.content.push(block);
+            }
+            else {
+                apiMessages.push({ role: "user", content: [block] });
+            }
+            continue;
+        }
+        // Regular user messages
+        apiMessages.push({ role: "user", content: m.content });
+    }
+    return { system: systemPrompt, apiMessages };
+}
+/** Pattern matching transient network errors that should be retried */
+const TRANSIENT_ERROR_RE = /fetch timeout|fetch failed|ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENETUNREACH|EAI_AGAIN|socket hang up/i;
+/** Parse response content blocks into text + tool calls + token usage */
+function parseResponseContent(data, onToken) {
+    let text = "";
+    const toolCalls = [];
+    for (const block of data.content ?? []) {
+        if (block.type === "text") {
+            text += block.text;
+            if (onToken) {
+                try {
+                    onToken(block.text);
+                }
+                catch { }
+            }
+        }
+        else if (block.type === "tool_use") {
+            toolCalls.push({
+                id: block.id,
+                type: "custom",
+                function: {
+                    name: block.name,
+                    arguments: JSON.stringify(block.input),
+                },
+            });
+        }
+    }
+    const usage = data.usage ? {
+        inputTokens: data.usage.input_tokens ?? 0,
+        outputTokens: data.usage.output_tokens ?? 0,
+    } : undefined;
+    return { text, toolCalls, usage };
+}
+export function makeAnthropicDriver(cfg) {
+    const base = (cfg.baseUrl ?? "https://api.anthropic.com").replace(/\/+$/, "");
+    const endpoint = `${base}/v1/messages`;
+    const model = cfg.model ?? "claude-sonnet-4-20250514";
+    const maxTokens = cfg.maxTokens ?? 4096;
+    const timeoutMs = cfg.timeoutMs ?? 2 * 60 * 60 * 1000;
+    async function chat(messages, opts) {
+        await rateLimiter.limit("llm-ask", 1);
+        const onToken = opts?.onToken;
+        const resolvedModel = opts?.model ?? model;
+        const { system: systemPrompt, apiMessages } = convertMessages(messages);
+        const body = {
+            model: resolvedModel,
+            thinking: {
+                type: "adaptive"
+            },
+            max_tokens: maxTokens,
+            messages: apiMessages,
+        };
+        if (systemPrompt)
+            body.system = systemPrompt;
+        // Tools support — convert from OpenAI format to Anthropic format
+        if (Array.isArray(opts?.tools) && opts.tools.length) {
+            body.tools = convertToolDefs(opts.tools);
+        }
+        const headers = {
+            "Content-Type": "application/json",
+            "x-api-key": cfg.apiKey,
+            "anthropic-version": "2023-06-01",
+        };
+        const RETRYABLE_STATUS = new Set([429, 503, 529]);
+        let requestId;
+        try {
+            let res;
+            for (let attempt = 0;; attempt++) {
+                res = await timedFetch(endpoint, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(body),
+                    where: "driver:anthropic",
+                    timeoutMs,
+                });
+                if (res.ok)
+                    break;
+                if (isRetryable(res.status) && attempt < MAX_RETRIES) {
+                    const delay = retryDelay(attempt);
+                    Logger.warn(`Anthropic ${res.status}, retry ${attempt + 1}/${MAX_RETRIES} in ${Math.round(delay)}ms`);
+                    await sleep(delay);
+                    continue;
+                }
+                const text = await res.text().catch(() => "");
+                const ge = groError("provider_error", `Anthropic API failed (${res.status}): ${text}`, {
+                    provider: "anthropic",
+                    model: resolvedModel,
+                    request_id: requestId,
+                    retryable: RETRYABLE_STATUS.has(res.status),
+                    cause: new Error(text),
+                });
+                Logger.error("Anthropic driver error:", errorLogFields(ge));
+                throw ge;
+            }
+            const data = await res.json();
+            return parseResponseContent(data, onToken);
+        }
+        catch (e) {
+            if (isGroError(e))
+                throw e; // already wrapped above
+            // Classify the error: fetch timeouts and network errors are transient
+            const errMsg = asError(e).message;
+            const isTransient = TRANSIENT_ERROR_RE.test(errMsg);
+            if (isTransient) {
+                // Retry transient network errors (e.g. auth proxy down during container restart)
+                for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+                    const delay = retryDelay(attempt);
+                    Logger.warn(`Transient error: ${errMsg.substring(0, 120)}, retry ${attempt + 1}/${MAX_RETRIES} in ${Math.round(delay)}ms`);
+                    await sleep(delay);
+                    try {
+                        const retryRes = await timedFetch(endpoint, {
+                            method: "POST",
+                            headers,
+                            body: JSON.stringify(body),
+                            where: "driver:anthropic",
+                            timeoutMs,
+                        });
+                        if (!retryRes.ok) {
+                            const text = await retryRes.text().catch(() => "");
+                            if (isRetryable(retryRes.status) && attempt < MAX_RETRIES - 1)
+                                continue;
+                            throw groError("provider_error", `Anthropic API failed (${retryRes.status}): ${text}`, {
+                                provider: "anthropic", model: resolvedModel, retryable: false, cause: new Error(text),
+                            });
+                        }
+                        // Success on retry — parse and return
+                        const data = await retryRes.json();
+                        Logger.info(`Recovered from transient error after ${attempt + 1} retries`);
+                        return parseResponseContent(data, onToken);
+                    }
+                    catch (retryErr) {
+                        if (isGroError(retryErr))
+                            throw retryErr;
+                        if (attempt === MAX_RETRIES - 1) {
+                            // Exhausted retries — throw with context
+                            const ge = groError("provider_error", `Anthropic driver error (after ${MAX_RETRIES} retries): ${errMsg}`, {
+                                provider: "anthropic", model: resolvedModel, request_id: requestId,
+                                retryable: false, cause: e,
+                            });
+                            Logger.error("Anthropic driver error (retries exhausted):", errorLogFields(ge));
+                            throw ge;
+                        }
+                    }
+                }
+            }
+            // Non-transient error — throw immediately
+            const ge = groError("provider_error", `Anthropic driver error: ${errMsg}`, {
+                provider: "anthropic",
+                model: resolvedModel,
+                request_id: requestId,
+                retryable: false,
+                cause: e,
+            });
+            Logger.error("Anthropic driver error:", errorLogFields(ge));
+            throw ge;
+        }
+    }
+    return { chat };
+}

package/dist/drivers/index.js

@@ -0,0 +1,2 @@
+export { makeStreamingOpenAiDriver } from "./streaming-openai.js";
+export { makeAnthropicDriver } from "./anthropic.js";

package/dist/drivers/streaming-openai.js

@@ -0,0 +1,262 @@
+/**
+ * Streaming OpenAI-compatible chat driver.
+ * Works with OpenAI, Anthropic (via proxy), LM Studio, Ollama, etc.
+ */
+import { Logger } from "../logger.js";
+import { asError } from "../errors.js";
+import { rateLimiter } from "../utils/rate-limiter.js";
+import { timedFetch } from "../utils/timed-fetch.js";
+import { MAX_RETRIES, isRetryable, retryDelay, sleep } from "../utils/retry.js";
+function yieldToLoop() {
+    return new Promise((resolve) => typeof globalThis.setImmediate === "function"
+        ? globalThis.setImmediate(resolve)
+        : setTimeout(resolve, 0));
+}
+class YieldBudget {
+    constructor(byteBudget = 1024, msBudget = 8) {
+        this.byteBudget = byteBudget;
+        this.msBudget = msBudget;
+        this.bytesSince = 0;
+        this.last = Date.now();
+    }
+    async maybe(extraBytes = 0) {
+        this.bytesSince += extraBytes;
+        const now = Date.now();
+        if (this.bytesSince >= this.byteBudget || (now - this.last) >= this.msBudget) {
+            this.bytesSince = 0;
+            this.last = now;
+            await yieldToLoop();
+        }
+    }
+}
+export function makeStreamingOpenAiDriver(cfg) {
+    const base = cfg.baseUrl.replace(/\/+$/, "");
+    const endpoint = `${base}/v1/chat/completions`;
+    const defaultTimeout = cfg.timeoutMs ?? 2 * 60 * 60 * 1000;
+    async function chat(messages, opts) {
+        await rateLimiter.limit("llm-ask", 1);
+        Logger.debug("streaming messages out", messages);
+        const controller = new AbortController();
+        const userSignal = opts?.signal;
+        const linkAbort = () => controller.abort();
+        if (userSignal) {
+            if (userSignal.aborted)
+                controller.abort();
+            else
+                userSignal.addEventListener("abort", linkAbort, { once: true });
+        }
+        const timer = setTimeout(() => controller.abort(), defaultTimeout);
+        const model = opts?.model ?? cfg.model;
+        const tools = Array.isArray(opts?.tools) && opts.tools.length ? opts.tools : undefined;
+        const onToken = opts?.onToken;
+        const onReasoningToken = opts?.onReasoningToken;
+        const onToolCallDelta = opts?.onToolCallDelta;
+        const headers = { "Content-Type": "application/json" };
+        if (cfg.apiKey)
+            headers["Authorization"] = `Bearer ${cfg.apiKey}`;
+        const payload = { model, messages, stream: true };
+        if (tools) {
+            payload.tools = tools;
+            payload.tool_choice = "auto";
+        }
+        try {
+            let res;
+            for (let attempt = 0;; attempt++) {
+                res = await timedFetch(endpoint, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(payload),
+                    signal: controller.signal,
+                    where: "driver:openai:stream",
+                    timeoutMs: defaultTimeout,
+                });
+                if (res.ok)
+                    break;
+                if (isRetryable(res.status) && attempt < MAX_RETRIES) {
+                    const delay = retryDelay(attempt);
+                    Logger.warn(`OpenAI ${res.status}, retry ${attempt + 1}/${MAX_RETRIES} in ${Math.round(delay)}ms`);
+                    await sleep(delay);
+                    continue;
+                }
+                const text = await res.text().catch(() => "");
+                throw new Error(`OpenAI chat (stream) failed (${res.status}): ${text}`);
+            }
+            const ct = (res.headers.get("content-type") || "").toLowerCase();
+            if (!ct.includes("text/event-stream")) {
+                const data = await res.json().catch(() => ({}));
+                const choice = data?.choices?.[0];
+                const msg = choice?.message || {};
+                const content = typeof msg?.content === "string" ? msg.content : "";
+                const toolCalls = Array.isArray(msg?.tool_calls) ? msg.tool_calls : [];
+                if (content && onToken)
+                    onToken(content);
+                const usage = data?.usage ? {
+                    inputTokens: data.usage.prompt_tokens ?? 0,
+                    outputTokens: data.usage.completion_tokens ?? 0,
+                } : undefined;
+                return { text: content, reasoning: msg?.reasoning || undefined, toolCalls, usage };
+            }
+            // SSE streaming
+            const decoder = new TextDecoder("utf-8");
+            const yb = new YieldBudget(1024, 8);
+            let buf = "";
+            let fullText = "";
+            let fullReasoning = "";
+            let streamUsage;
+            const toolByIndex = new Map();
+            const pumpEvent = async (rawEvent) => {
+                const dataLines = rawEvent
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter((l) => l.startsWith("data:"))
+                    .map((l) => l.replace(/^data:\s?/, ""));
+                if (!dataLines.length)
+                    return;
+                const joined = dataLines.join("\n").trim();
+                if (!joined || joined === "[DONE]")
+                    return;
+                let payload;
+                try {
+                    payload = JSON.parse(joined);
+                }
+                catch {
+                    return;
+                }
+                // Capture usage from final streaming chunk (if stream_options.include_usage was set)
+                if (payload?.usage) {
+                    streamUsage = {
+                        inputTokens: payload.usage.prompt_tokens ?? 0,
+                        outputTokens: payload.usage.completion_tokens ?? 0,
+                    };
+                }
+                const delta = payload?.choices?.[0]?.delta;
+                if (!delta)
+                    return;
+                if (typeof delta.content === "string" && delta.content.length) {
+                    fullText += delta.content;
+                    if (onToken) {
+                        let s = delta.content;
+                        while (s.length) {
+                            const piece = s.slice(0, 512);
+                            s = s.slice(512);
+                            try {
+                                onToken(piece);
+                            }
+                            catch { }
+                            await yb.maybe(piece.length);
+                        }
+                    }
+                    else {
+                        await yb.maybe(delta.content.length);
+                    }
+                }
+                if (typeof delta.reasoning === "string" && delta.reasoning.length) {
+                    fullReasoning += delta.reasoning;
+                    if (onReasoningToken) {
+                        let s = delta.reasoning;
+                        while (s.length) {
+                            const piece = s.slice(0, 512);
+                            s = s.slice(512);
+                            try {
+                                onReasoningToken(piece);
+                            }
+                            catch { }
+                            await yb.maybe(piece.length);
+                        }
+                    }
+                    else {
+                        await yb.maybe(delta.reasoning.length);
+                    }
+                }
+                if (Array.isArray(delta.tool_calls)) {
+                    for (const item of delta.tool_calls) {
+                        const idx = typeof item?.index === "number" ? item.index : 0;
+                        const prev = toolByIndex.get(idx) ?? {
+                            id: "", type: "function", function: { name: "", arguments: "" }
+                        };
+                        if (typeof item.id === "string" && item.id)
+                            prev.id = item.id;
+                        if (typeof item.type === "string" && item.type)
+                            prev.type = item.type;
+                        const f = item?.function ?? {};
+                        if (typeof f.name === "string" && f.name)
+                            prev.function.name += f.name;
+                        if (typeof f.arguments === "string" && f.arguments)
+                            prev.function.arguments += f.arguments;
+                        toolByIndex.set(idx, prev);
+                        if (onToolCallDelta) {
+                            try {
+                                onToolCallDelta(prev);
+                            }
+                            catch { }
+                        }
+                        await yb.maybe(64);
+                    }
+                }
+            };
+            const body = res.body;
+            if (body && typeof body.getReader === "function") {
+                const reader = body.getReader();
+                try {
+                    while (true) {
+                        const { value, done } = await reader.read();
+                        if (done)
+                            break;
+                        buf += decoder.decode(value, { stream: true });
+                        await yb.maybe(value?.byteLength ?? 0);
+                        let sepIdx;
+                        while ((sepIdx = buf.indexOf("\n\n")) !== -1) {
+                            const rawEvent = buf.slice(0, sepIdx).trim();
+                            buf = buf.slice(sepIdx + 2);
+                            if (rawEvent)
+                                await pumpEvent(rawEvent);
+                        }
+                    }
+                    if (buf.trim())
+                        await pumpEvent(buf.trim());
+                }
+                finally {
+                    reader.cancel().catch(() => { });
+                }
+            }
+            else if (body && typeof body[Symbol.asyncIterator] === "function") {
+                for await (const chunk of body) {
+                    buf += decoder.decode(chunk, { stream: true });
+                    await yb.maybe(chunk.byteLength);
+                    let sepIdx;
+                    while ((sepIdx = buf.indexOf("\n\n")) !== -1) {
+                        const rawEvent = buf.slice(0, sepIdx).trim();
+                        buf = buf.slice(sepIdx + 2);
+                        if (rawEvent)
+                            await pumpEvent(rawEvent);
+                    }
+                }
+                if (buf.trim())
+                    await pumpEvent(buf.trim());
+            }
+            else {
+                const txt = await res.text();
+                for (const part of txt.split("\n\n").map((s) => s.trim())) {
+                    if (part)
+                        await pumpEvent(part);
+                }
+            }
+            const toolCalls = Array.from(toolByIndex.entries())
+                .sort((a, b) => a[0] - b[0])
+                .map(([, v]) => v);
+            return { text: fullText, reasoning: fullReasoning || undefined, toolCalls, usage: streamUsage };
+        }
+        catch (e) {
+            const wrapped = asError(e);
+            if (wrapped.name === "AbortError")
+                Logger.debug("timeout(stream)", { ms: defaultTimeout });
+            throw wrapped;
+        }
+        finally {
+            clearTimeout(timer);
+            if (userSignal)
+                userSignal.removeEventListener("abort", linkAbort);
+        }
+    }
+    return { chat };
+}

package/dist/drivers/types.js

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

package/dist/errors.js

@@ -0,0 +1,79 @@
+/**
+ * Structured error types for gro.
+ *
+ * All error boundaries should wrap errors using GroError instead of
+ * stringifying with e.message. This preserves stack traces, enables
+ * retry logic, and provides consistent logging fields.
+ */
+/**
+ * Create a GroError with structured fields.
+ */
+export function groError(kind, message, opts = {}) {
+    const err = new Error(message);
+    err.kind = kind;
+    err.retryable = opts.retryable ?? false;
+    if (opts.provider)
+        err.provider = opts.provider;
+    if (opts.model)
+        err.model = opts.model;
+    if (opts.request_id)
+        err.request_id = opts.request_id;
+    if (opts.latency_ms !== undefined)
+        err.latency_ms = opts.latency_ms;
+    if (opts.cause !== undefined)
+        err.cause = opts.cause;
+    return err;
+}
+/**
+ * Normalize an unknown thrown value into an Error.
+ * Handles strings, objects, nulls — the full JS throw spectrum.
+ */
+export function asError(e) {
+    if (e instanceof Error)
+        return e;
+    if (typeof e === "string")
+        return new Error(e.slice(0, 1024));
+    if (e === null || e === undefined)
+        return new Error("Unknown error");
+    try {
+        const s = String(e);
+        return new Error(s.length > 1024 ? s.slice(0, 1024) + "..." : s);
+    }
+    catch {
+        return new Error("Unknown error (unstringifiable)");
+    }
+}
+/**
+ * Check if an error is a GroError with structured fields.
+ */
+export function isGroError(e) {
+    return e instanceof Error && "kind" in e && "retryable" in e;
+}
+/**
+ * Format a GroError for structured logging.
+ * Returns a plain object suitable for JSON.stringify or structured loggers.
+ */
+export function errorLogFields(e) {
+    const fields = {
+        kind: e.kind,
+        message: e.message,
+        retryable: e.retryable,
+    };
+    if (e.provider)
+        fields.provider = e.provider;
+    if (e.model)
+        fields.model = e.model;
+    if (e.request_id)
+        fields.request_id = e.request_id;
+    if (e.latency_ms !== undefined)
+        fields.latency_ms = e.latency_ms;
+    if (e.cause) {
+        const cause = asError(e.cause);
+        fields.cause_message = cause.message;
+        if (cause.stack)
+            fields.cause_stack = cause.stack;
+    }
+    if (e.stack)
+        fields.stack = e.stack;
+    return fields;
+}

package/dist/logger.js

@@ -0,0 +1,30 @@
+export const C = {
+    reset: "\x1b[0m",
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    red: (s) => `\x1b[31m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    blue: (s) => `\x1b[34m${s}\x1b[0m`,
+    magenta: (s) => `\x1b[35m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    gray: (s) => `\x1b[90m${s}\x1b[0m`,
+};
+function writeRaw(s) {
+    const g = globalThis;
+    if (g?.Bun?.stdout?.write) {
+        g.Bun.stdout.write(s);
+        return;
+    }
+    g?.process?.stdout?.write?.(s);
+}
+export class Logger {
+    static info(...a) { console.log(...a); }
+    static warn(...a) { console.warn(...a); }
+    static error(...a) { console.error(...a); }
+    static debug(...a) {
+        if ((process.env.GRO_LOG_LEVEL ?? "").toUpperCase() === "DEBUG")
+            console.log(...a);
+    }
+    static streamInfo(s) { writeRaw(s); }
+    static endStreamLine(suffix = "") { writeRaw(suffix + "\n"); }
+}