@tjamescouch/gro 1.3.3 → 1.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Couch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tjamescouch/gro",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "Provider-agnostic LLM runtime with context management",
   "type": "module",
   "scripts": {

package/src/drivers/anthropic.ts

@@ -7,7 +7,7 @@ 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";
-import type { ChatDriver, ChatMessage, ChatOutput, ChatToolCall } from "./types.js";
+import type { ChatDriver, ChatMessage, ChatOutput, ChatToolCall, TokenUsage } from "./types.js";
 
 export interface AnthropicDriverConfig {
   apiKey: string;
@@ -107,6 +107,40 @@ function convertMessages(messages: ChatMessage[]): { system: string | undefined;
   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: any, onToken?: (t: string) => void): ChatOutput {
+  let text = "";
+  const toolCalls: ChatToolCall[] = [];
+
+  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: TokenUsage | undefined = data.usage ? {
+    inputTokens: data.usage.input_tokens ?? 0,
+    outputTokens: data.usage.output_tokens ?? 0,
+  } : undefined;
+
+  return { text, toolCalls, usage };
+}
+
 export function makeAnthropicDriver(cfg: AnthropicDriverConfig): ChatDriver {
   const base = (cfg.baseUrl ?? "https://api.anthropic.com").replace(/\/+$/, "");
   const endpoint = `${base}/v1/messages`;
@@ -179,32 +213,59 @@ export function makeAnthropicDriver(cfg: AnthropicDriverConfig): ChatDriver {
       }
 
       const data = await res.json() as any;
+      return parseResponseContent(data, onToken);
+    } catch (e: unknown) {
+      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,
+            });
 
-      let text = "";
-      const toolCalls: ChatToolCall[] = [];
+            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),
+              });
+            }
 
-      for (const block of data.content ?? []) {
-        if (block.type === "text") {
-          text += block.text;
-          if (onToken) {
-            try { onToken(block.text); } catch {}
+            // Success on retry — parse and return
+            const data = await retryRes.json() as any;
+            Logger.info(`Recovered from transient error after ${attempt + 1} retries`);
+            return parseResponseContent(data, onToken);
+          } catch (retryErr: unknown) {
+            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;
+            }
           }
-        } else if (block.type === "tool_use") {
-          toolCalls.push({
-            id: block.id,
-            type: "custom",
-            function: {
-              name: block.name,
-              arguments: JSON.stringify(block.input),
-            },
-          });
         }
       }
 
-      return { text, toolCalls };
-    } catch (e: unknown) {
-      if (isGroError(e)) throw e; // already wrapped above
-      const ge = groError("provider_error", `Anthropic driver error: ${asError(e).message}`, {
+      // Non-transient error — throw immediately
+      const ge = groError("provider_error", `Anthropic driver error: ${errMsg}`, {
         provider: "anthropic",
         model: resolvedModel,
         request_id: requestId,

package/src/drivers/index.ts

@@ -1,4 +1,4 @@
-export type { ChatDriver, ChatMessage, ChatOutput, ChatToolCall } from "./types.js";
+export type { ChatDriver, ChatMessage, ChatOutput, ChatToolCall, TokenUsage } from "./types.js";
 export { makeStreamingOpenAiDriver } from "./streaming-openai.js";
 export type { OpenAiDriverConfig } from "./streaming-openai.js";
 export { makeAnthropicDriver } from "./anthropic.js";

package/src/drivers/streaming-openai.ts

@@ -7,7 +7,7 @@ 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";
-import type { ChatDriver, ChatMessage, ChatOutput, ChatToolCall } from "./types.js";
+import type { ChatDriver, ChatMessage, ChatOutput, ChatToolCall, TokenUsage } from "./types.js";
 
 export interface OpenAiDriverConfig {
   baseUrl: string;
@@ -108,7 +108,11 @@ export function makeStreamingOpenAiDriver(cfg: OpenAiDriverConfig): ChatDriver {
         const content = typeof msg?.content === "string" ? msg.content : "";
         const toolCalls: ChatToolCall[] = Array.isArray(msg?.tool_calls) ? msg.tool_calls : [];
         if (content && onToken) onToken(content);
-        return { text: content, reasoning: msg?.reasoning || undefined, toolCalls };
+        const usage: TokenUsage | undefined = 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
@@ -117,6 +121,7 @@ export function makeStreamingOpenAiDriver(cfg: OpenAiDriverConfig): ChatDriver {
       let buf = "";
       let fullText = "";
       let fullReasoning = "";
+      let streamUsage: TokenUsage | undefined;
       const toolByIndex = new Map<number, ChatToolCall>();
 
       const pumpEvent = async (rawEvent: string) => {
@@ -133,6 +138,14 @@ export function makeStreamingOpenAiDriver(cfg: OpenAiDriverConfig): ChatDriver {
         let payload: any;
         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;
 
@@ -230,7 +243,7 @@ export function makeStreamingOpenAiDriver(cfg: OpenAiDriverConfig): ChatDriver {
         .sort((a, b) => a[0] - b[0])
         .map(([, v]) => v);
 
-      return { text: fullText, reasoning: fullReasoning || undefined, toolCalls };
+      return { text: fullText, reasoning: fullReasoning || undefined, toolCalls, usage: streamUsage };
     } catch (e: unknown) {
       const wrapped = asError(e);
       if (wrapped.name === "AbortError") Logger.debug("timeout(stream)", { ms: defaultTimeout });

package/src/drivers/types.ts

@@ -16,10 +16,16 @@ export interface ChatToolCall {
   raw?: string;
 }
 
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
 export interface ChatOutput {
   text: string;
   toolCalls: ChatToolCall[];
   reasoning?: string;
+  usage?: TokenUsage;
 }
 
 export interface ChatDriver {

package/src/main.ts

@@ -21,7 +21,7 @@ import { McpManager } from "./mcp/index.js";
 import { newSessionId, findLatestSession, loadSession, ensureGroDir } from "./session.js";
 import { groError, asError, isGroError, errorLogFields } from "./errors.js";
 import type { McpServerConfig } from "./mcp/index.js";
-import type { ChatDriver, ChatMessage, ChatOutput } from "./drivers/types.js";
+import type { ChatDriver, ChatMessage, ChatOutput, TokenUsage } from "./drivers/types.js";
 import type { AgentMemory } from "./memory/agent-memory.js";
 import { bashToolDefinition, executeBash } from "./tools/bash.js";
 import { agentpatchToolDefinition, executeAgentpatch } from "./tools/agentpatch.js";
@@ -55,6 +55,7 @@ interface GroConfig {
   wakeNotes: string;
   wakeNotesEnabled: boolean;
   contextTokens: number;
+  maxTokens: number;
   interactive: boolean;
   print: boolean;
   maxToolRounds: number;
@@ -168,6 +169,7 @@ function loadConfig(): GroConfig {
     else if (arg === "--wake-notes") { flags.wakeNotes = args[++i]; }
     else if (arg === "--no-wake-notes") { flags.noWakeNotes = "true"; }
     else if (arg === "--context-tokens") { flags.contextTokens = args[++i]; }
+    else if (arg === "--max-tokens") { flags.maxTokens = args[++i]; }
     else if (arg === "--max-tool-rounds" || arg === "--max-turns") { flags.maxToolRounds = args[++i]; }
     else if (arg === "--bash") { flags.bash = "true"; }
     else if (arg === "--persistent" || arg === "--keep-alive") { flags.persistent = "true"; }
@@ -287,6 +289,7 @@ ${systemPrompt}` : wake;
     wakeNotes: flags.wakeNotes || WAKE_NOTES_DEFAULT_PATH,
     wakeNotesEnabled: flags.noWakeNotes !== "true",
     contextTokens: parseInt(flags.contextTokens || "8192"),
+    maxTokens: parseInt(flags.maxTokens || "16384"),
     interactive: interactiveMode,
     print: printMode,
     maxToolRounds: parseInt(flags.maxToolRounds || "10"),
@@ -361,6 +364,7 @@ options:
   --wake-notes           path to wake notes file (default: ~/.claude/WAKE.md)
   --no-wake-notes        disable auto-prepending wake notes
   --context-tokens       context window budget (default: 8192)
+  --max-tokens           max response tokens per turn (default: 16384)
   --max-turns            max agentic rounds per turn (default: 10)
   --max-tool-rounds      alias for --max-turns
   --bash                 enable built-in bash tool for shell command execution
@@ -391,6 +395,7 @@ function createDriverForModel(
   model: string,
   apiKey: string,
   baseUrl: string,
+  maxTokens?: number,
 ): ChatDriver {
   switch (provider) {
     case "anthropic":
@@ -398,7 +403,7 @@ function createDriverForModel(
         Logger.error("gro: ANTHROPIC_API_KEY not set (set ANTHROPIC_BASE_URL for proxy mode)");
         process.exit(1);
       }
-      return makeAnthropicDriver({ apiKey: apiKey || "proxy-managed", model, baseUrl });
+      return makeAnthropicDriver({ apiKey: apiKey || "proxy-managed", model, baseUrl, maxTokens });
 
     case "openai":
       if (!apiKey && baseUrl === "https://api.openai.com") {
@@ -418,7 +423,7 @@ function createDriverForModel(
 }
 
 function createDriver(cfg: GroConfig): ChatDriver {
-  return createDriverForModel(cfg.provider, cfg.model, cfg.apiKey, cfg.baseUrl);
+  return createDriverForModel(cfg.provider, cfg.model, cfg.apiKey, cfg.baseUrl, cfg.maxTokens);
 }
 
 // ---------------------------------------------------------------------------
@@ -493,6 +498,8 @@ async function executeTurn(
   tools.push(agentpatchToolDefinition());
   if (cfg.bash) tools.push(bashToolDefinition());
   let finalText = "";
+  let turnTokensIn = 0;
+  let turnTokensOut = 0;
 
   const onToken = cfg.outputFormat === "stream-json"
     ? (t: string) => process.stdout.write(JSON.stringify({ type: "token", token: t }) + "\n")
@@ -507,6 +514,14 @@ async function executeTurn(
       onToken,
     });
 
+    // Track token usage for niki budget enforcement
+    if (output.usage) {
+      turnTokensIn += output.usage.inputTokens;
+      turnTokensOut += output.usage.outputTokens;
+      // Log cumulative usage to stderr — niki parses these patterns for budget enforcement
+      process.stderr.write(`"input_tokens": ${turnTokensIn}, "output_tokens": ${turnTokensOut}\n`);
+    }
+
     // Accumulate text
     if (output.text) finalText += output.text;
 
@@ -551,7 +566,8 @@ async function executeTurn(
       let fnArgs: Record<string, any>;
       try {
         fnArgs = JSON.parse(tc.function.arguments);
-      } catch {
+      } catch (e: unknown) {
+        Logger.debug(`Failed to parse args for ${fnName}: ${asError(e).message}, using empty args`);
         fnArgs = {};
       }
 
@@ -567,12 +583,14 @@ async function executeTurn(
           result = await mcp.callTool(fnName, fnArgs);
         }
       } catch (e: unknown) {
-        const ge = groError("tool_error", `Tool "${fnName}" failed: ${asError(e).message}`, {
+        const raw = asError(e);
+        const ge = groError("tool_error", `Tool "${fnName}" failed: ${raw.message}`, {
           retryable: false,
           cause: e,
         });
         Logger.error("Tool execution error:", errorLogFields(ge));
-        result = `Error: ${ge.message}`;
+        if (raw.stack) Logger.error(raw.stack);
+        result = `Error: ${ge.message}${raw.stack ? '\nStack: ' + raw.stack : ''}`;
       }
 
       // Feed tool result back into memory
@@ -604,6 +622,11 @@ async function executeTurn(
       model: cfg.model,
       onToken,
     });
+    if (finalOutput.usage) {
+      turnTokensIn += finalOutput.usage.inputTokens;
+      turnTokensOut += finalOutput.usage.outputTokens;
+      process.stderr.write(`"input_tokens": ${turnTokensIn}, "output_tokens": ${turnTokensOut}\n`);
+    }
     if (finalOutput.text) finalText += finalOutput.text;
     await memory.add({ role: "assistant", from: "Assistant", content: finalOutput.text || "" });
   }
@@ -653,11 +676,13 @@ async function singleShot(
   await memory.add({ role: "user", from: "User", content: prompt });
 
   let text: string | undefined;
+  let fatalError = false;
   try {
     text = await executeTurn(driver, memory, mcp, cfg, sessionId);
   } catch (e: unknown) {
     const ge = isGroError(e) ? e : groError("provider_error", asError(e).message, { cause: e });
     Logger.error(C.red(`error: ${ge.message}`), errorLogFields(ge));
+    fatalError = true;
   }
 
   // Save session (even on error — preserve conversation state)
@@ -669,6 +694,12 @@ async function singleShot(
     }
   }
 
+  // Exit with non-zero code on fatal API errors so the supervisor
+  // can distinguish "finished cleanly" from "crashed on API call"
+  if (fatalError) {
+    process.exit(1);
+  }
+
   if (text) {
     if (cfg.outputFormat === "json") {
       process.stdout.write(formatOutput(text, "json") + "\n");
@@ -805,7 +836,7 @@ async function main() {
     "--provider", "-P", "--model", "-m", "--base-url",
     "--system-prompt", "--system-prompt-file",
     "--append-system-prompt", "--append-system-prompt-file",
-    "--context-tokens", "--max-tool-rounds", "--max-turns",
+    "--context-tokens", "--max-tokens", "--max-tool-rounds", "--max-turns",
     "--max-thinking-tokens", "--max-budget-usd",
     "--summarizer-model", "--output-format", "--mcp-config",
     "--resume", "-r",
@@ -857,10 +888,14 @@ for (const sig of ["SIGTERM", "SIGHUP"] as const) {
 
 // Catch unhandled promise rejections (e.g. background summarization)
 process.on("unhandledRejection", (reason: unknown) => {
-  Logger.error(C.red(`unhandled rejection: ${asError(reason).message}`));
+  const err = asError(reason);
+  Logger.error(C.red(`unhandled rejection: ${err.message}`));
+  if (err.stack) Logger.error(C.red(err.stack));
 });
 
 main().catch((e: unknown) => {
-  Logger.error("gro:", asError(e).message);
+  const err = asError(e);
+  Logger.error("gro:", err.message);
+  if (err.stack) Logger.error(err.stack);
   process.exit(1);
 });

package/src/mcp/client.ts

@@ -109,20 +109,32 @@ export class McpManager {
     for (const server of this.servers.values()) {
       const tool = server.tools.find(t => t.name === name);
       if (tool) {
-        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: any) => {
-              if (c.type === "text") return c.text;
-              return JSON.stringify(c);
-            })
-            .join("\n");
+        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: any) => {
+                if (c.type === "text") return c.text;
+                return JSON.stringify(c);
+              })
+              .join("\n");
+          }
+          return JSON.stringify(result);
+        } catch (e: unknown) {
+          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;
         }
-        return JSON.stringify(result);
       }
     }
-    throw new Error(`No MCP server provides tool "${name}"`);
+    const ge = groError("mcp_error", `No MCP server provides tool "${name}"`, { retryable: false });
+    Logger.error(ge.message, errorLogFields(ge));
+    throw ge;
   }
 
   /**
@@ -140,7 +152,11 @@ export class McpManager {
    */
   async disconnectAll(): Promise<void> {
     for (const server of this.servers.values()) {
-      try { await server.client.close(); } catch {}
+      try {
+        await server.client.close();
+      } catch (e: unknown) {
+        Logger.debug(`MCP server "${server.name}" close error: ${asError(e).message}`);
+      }
     }
     this.servers.clear();
   }