@tjamescouch/gro 1.3.2

package/owl/constraints.md

@@ -0,0 +1,32 @@
+# constraints
+
+## technology
+
+- TypeScript, targeting ES2021
+- Bun as primary runtime, Node.js 18+ as fallback
+- NodeNext module resolution with explicit `.js` import extensions
+- No frontend, no terminal UI, no raw/cooked mode — stdout/stderr only
+
+## dependencies
+
+- `@modelcontextprotocol/sdk` for MCP client transport (stdio)
+- `@types/node` for type definitions
+- `typescript` for compilation
+- No other runtime dependencies — HTTP calls use native fetch
+
+## architecture
+
+- Single-agent only. Multi-agent coordination happens via agentchat sockets, not inside gro
+- Drivers are pure functions: `(messages, opts) => ChatOutput`. No state, no side effects beyond the HTTP call
+- Memory is a class hierarchy: `AgentMemory` (abstract) -> `SimpleMemory` | `AdvancedMemory`
+- Session state lives in `.gro/context/<uuid>/` with `messages.json` and `meta.json`
+- MCP servers are discovered from Claude Code's `settings.json` or explicit `--mcp-config` paths
+- Config is resolved from CLI flags only (no config file yet). Environment variables for API keys
+
+## style
+
+- Prefer `async/await` over raw promises
+- Prefer explicit types over inference for function signatures
+- No classes where a plain function suffices (drivers are factory functions, not classes)
+- Error messages go to stderr via Logger. Completions go to stdout
+- Graceful degradation: unknown flags warn, never crash

package/owl/product.md

@@ -0,0 +1,28 @@
+# gro
+
+Provider-agnostic LLM runtime with context management. Single-agent, headless CLI that supersets the `claude` command-line interface.
+
+## purpose
+
+- Execute LLM completions against any provider (Anthropic, OpenAI, local) through a unified CLI
+- Manage conversation context with swim-lane summarization so long sessions don't overflow the context window
+- Connect to MCP servers for tool use, maintaining full compatibility with Claude Code's MCP ecosystem
+- Persist sessions to disk so conversations can be resumed across process restarts
+- Accept all `claude` CLI flags as a drop-in replacement, with graceful degradation for unimplemented features
+
+## components
+
+- **drivers**: Provider-specific chat completion backends (Anthropic native, OpenAI streaming, local via OpenAI-compat)
+- **memory**: Conversation state management with optional swim-lane summarization and token budgeting
+- **mcp**: MCP client manager that discovers servers, enumerates tools, and routes tool calls
+- **session**: Persistence layer for saving/loading conversation state to `.gro/context/<id>/`
+- **cli**: Flag parsing, config resolution, mode dispatch (interactive, print, pipe)
+
+## success criteria
+
+- `gro -p "hello"` produces a completion on stdout and exits
+- `gro -i` enters interactive mode with context management and session auto-save
+- `gro -c` resumes the most recent session with full message history
+- `gro --allowedTools Bash "hello"` warns about unsupported flag and still works
+- Summarization keeps token usage within budget during long interactive sessions
+- MCP tools discovered from `~/.claude/settings.json` are callable during agentic turns

package/owl/proposals/cooperative-scheduler.md

@@ -0,0 +1,106 @@
+# Proposal: Cooperative scheduler for persistent tool loops
+
+## problem
+
+In `--persistent` mode, gro nudges the model when it returns a text-only response (no tool calls) by injecting:
+
+> "[SYSTEM] You stopped calling tools... Call agentchat_listen now ..."
+
+This is a reasonable *guardrail*, but it has an unintended second-order effect in agentchat-style workflows:
+
+- Models interpret the nudge as a hard requirement to **only** call `agentchat_listen` repeatedly.
+- That starves actual work (`bash`, repo edits, commits), because the model prioritizes satisfying the persistence nudge.
+- Humans then (correctly) complain: agents are "present" but not shipping.
+
+We need a runtime-level way to preserve responsiveness (check chat periodically) **without** forcing the model into a single-tool monoculture.
+
+## goals
+
+- Keep agents responsive to chat/interrupts.
+- Allow real work (bash/tooling) to progress.
+- Avoid instruction conflicts: "listen forever" vs "ship code".
+- Avoid daemons/multi-process requirements.
+- Preserve provider/tool compatibility (OpenAI/Anthropic + MCP).
+
+## non-goals
+
+- Multi-agent orchestration inside gro.
+- A full job scheduler with priorities, retries, persistence, etc. (keep it small).
+
+## proposal (runtime behavior)
+
+### 1) Add an explicit *work-first* persistent policy
+
+Add a `--persistent-policy` flag:
+
+- `listen-only` (current emergent behavior; not recommended)
+- `work-first` (default for persistent)
+
+`work-first` changes the injected nudge message and adds a runtime contract:
+
+- The model should alternate between (a) short checks for new messages and (b) work slices.
+- The runtime should help by making it easy to do the right thing.
+
+### 2) Replace the current persistence nudge with a cooperative contract
+
+Current nudge text hardcodes `agentchat_listen`. Instead, use:
+
+- **If tools exist**: request a tool call (any tool) OR a short `agentchat_listen`, but do not prescribe one tool.
+- Explicitly allow a work slice.
+
+Suggested nudge:
+
+```
+[SYSTEM] Persistent mode: you must keep making forward progress.
+Loop:
+1) Check messages quickly (agentchat_listen with short timeout)
+2) Do one work slice (bash/tool)
+3) Repeat.
+Do not get stuck calling listen repeatedly.
+```
+
+### 3) Runtime supports a short-timeout listen hint
+
+In agentchat MCP tool definition (or in docs), support `agentchat_listen({..., max_wait_ms})`.
+
+If tool does not support it, gro can still encourage a short cadence by setting expectations in the system nudge.
+
+### 4) Add a first-class “yield” tool (optional)
+
+Provide an internal tool `yield({ms})` (or `sleep`) that:
+
+- blocks for `ms`
+- returns a small structured result
+
+This gives the model a safe way to wait without spamming chat tools, and keeps the tool loop alive.
+
+### 5) Heartbeat + fairness guardrail
+
+Add a runtime counter:
+
+- If the model calls the same tool N times consecutively (e.g. `agentchat_listen`), inject a corrective system message:
+
+```
+[SYSTEM] You have called agentchat_listen N times without doing any work.
+Do one work slice (bash/tool) now before listening again.
+```
+
+This is crude, but it fixes the failure mode without needing deep semantic understanding.
+
+## minimal implementation plan
+
+1. Implement `--persistent-policy work-first` (default when `--persistent` is set).
+2. Change the nudge message in `src/main.ts` to the cooperative contract.
+3. Implement consecutive-tool guardrail (same-tool repetition).
+4. (Optional) add `yield` tool.
+
+## acceptance criteria
+
+- In a chat-driven prompt, the agent alternates: listen → bash work → listen.
+- Agent no longer gets stuck in an infinite `agentchat_listen` loop after a restart.
+- Existing non-chat uses of `--persistent` still behave correctly.
+
+## notes
+
+- This proposal intentionally does not require changes to the agentchat server.
+- If we later add structured “work queue” tools, this policy becomes the default scheduling model.

package/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"
+  }
+}

package/providers/claude.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# gro adapter: claude
+# reads prompt from stdin, outputs completion to stdout
+# env: GRO_MODEL, GRO_SYSTEM_PROMPT
+
+prompt=$(cat)
+
+# try CLI first
+if command -v claude &>/dev/null; then
+  args=(-p)
+  [[ -n "${GRO_MODEL:-}" ]] && args+=(--model "$GRO_MODEL")
+  [[ -n "${GRO_SYSTEM_PROMPT:-}" ]] && args+=(--system-prompt "$GRO_SYSTEM_PROMPT")
+  echo "$prompt" | claude "${args[@]}"
+  exit
+fi
+
+# fallback to HTTP API
+api_key="${ANTHROPIC_API_KEY:-}"
+if [[ -z "$api_key" && -f "${GRO_CONFIG_FILE:-}" ]]; then
+  api_key=$(grep "^anthropic.api-key=" "$GRO_CONFIG_FILE" 2>/dev/null | cut -d= -f2- || true)
+fi
+
+if [[ -z "$api_key" ]]; then
+  echo "gro/claude: neither \`claude\` CLI nor ANTHROPIC_API_KEY available" >&2
+  exit 1
+fi
+
+model="${GRO_MODEL:-claude-sonnet-4-20250514}"
+
+if [[ -n "${GRO_SYSTEM_PROMPT:-}" ]]; then
+  body=$(jq -nc \
+    --arg model "$model" \
+    --arg prompt "$prompt" \
+    --arg sys "$GRO_SYSTEM_PROMPT" \
+    '{model: $model, max_tokens: 4096, system: $sys, messages: [{role: "user", content: $prompt}]}')
+else
+  body=$(jq -nc \
+    --arg model "$model" \
+    --arg prompt "$prompt" \
+    '{model: $model, max_tokens: 4096, messages: [{role: "user", content: $prompt}]}')
+fi
+
+curl -sS https://api.anthropic.com/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: ${api_key}" \
+  -H "anthropic-version: 2023-06-01" \
+  -d "$body" \
+| jq -r '.content[0].text // error(.error.message // "empty response")'

package/providers/gemini.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# gro adapter: gemini
+# reads prompt from stdin, outputs completion to stdout
+# env: GRO_MODEL, GRO_SYSTEM_PROMPT, GEMINI_API_KEY
+
+prompt=$(cat)
+
+api_key="${GEMINI_API_KEY:-}"
+if [[ -z "$api_key" && -f "${GRO_CONFIG_FILE:-}" ]]; then
+  api_key=$(grep "^gemini.api-key=" "$GRO_CONFIG_FILE" 2>/dev/null | cut -d= -f2- || true)
+fi
+
+if [[ -z "$api_key" ]]; then
+  echo "gro/gemini: GEMINI_API_KEY not set" >&2
+  exit 1
+fi
+
+model="${GRO_MODEL:-gemini-2.0-flash}"
+
+if [[ -n "${GRO_SYSTEM_PROMPT:-}" ]]; then
+  body=$(jq -nc \
+    --arg prompt "$prompt" \
+    --arg sys "$GRO_SYSTEM_PROMPT" \
+    '{systemInstruction: {parts: [{text: $sys}]}, contents: [{role: "user", parts: [{text: $prompt}]}]}')
+else
+  body=$(jq -nc \
+    --arg prompt "$prompt" \
+    '{contents: [{role: "user", parts: [{text: $prompt}]}]}')
+fi
+
+curl -sS "https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${api_key}" \
+  -H "Content-Type: application/json" \
+  -d "$body" \
+| jq -r '.candidates[0].content.parts[0].text // error(.error.message // "empty response")'

package/providers/openai.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""gro adapter: openai
+Reads prompt from stdin, outputs completion to stdout.
+Env: GRO_MODEL, GRO_SYSTEM_PROMPT, OPENAI_API_KEY, GRO_CONFIG_FILE
+"""
+
+import sys
+import os
+import json
+import urllib.request
+import urllib.error
+
+
+TIMEOUT = 60
+
+
+def load_config_value(key):
+    config_file = os.environ.get("GRO_CONFIG_FILE", "")
+    if not config_file or not os.path.exists(config_file):
+        return ""
+    with open(config_file) as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if line.startswith(f"{key}="):
+                return line.split("=", 1)[1]
+    return ""
+
+
+def main():
+    prompt = sys.stdin.read().strip()
+    if not prompt:
+        print("gro/openai: empty prompt", file=sys.stderr)
+        sys.exit(1)
+
+    api_key = os.environ.get("OPENAI_API_KEY") or load_config_value("openai.api-key")
+    if not api_key:
+        print("gro/openai: OPENAI_API_KEY not set", file=sys.stderr)
+        sys.exit(1)
+
+    model = os.environ.get("GRO_MODEL") or "gpt-4o"
+    system_prompt = os.environ.get("GRO_SYSTEM_PROMPT", "")
+
+    messages = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    messages.append({"role": "user", "content": prompt})
+
+    body = json.dumps({"model": model, "messages": messages}).encode()
+
+    req = urllib.request.Request(
+        "https://api.openai.com/v1/chat/completions",
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
+            data = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode()
+        try:
+            err = json.loads(error_body)
+            print(f"gro/openai: {err.get('error', {}).get('message', error_body)}", file=sys.stderr)
+        except json.JSONDecodeError:
+            print(f"gro/openai: HTTP {e.code}: {error_body[:200]}", file=sys.stderr)
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        print(f"gro/openai: network error: {e.reason}", file=sys.stderr)
+        sys.exit(1)
+
+    content = data.get("choices", [{}])[0].get("message", {}).get("content", "")
+    if not content:
+        print("gro/openai: empty response", file=sys.stderr)
+        sys.exit(1)
+
+    print(content.strip())
+
+
+if __name__ == "__main__":
+    main()

package/src/drivers/anthropic.ts

@@ -0,0 +1,215 @@
+/**
+ * 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";
+import type { ChatDriver, ChatMessage, ChatOutput, ChatToolCall } from "./types.js";
+
+export interface AnthropicDriverConfig {
+  apiKey: string;
+  baseUrl?: string;
+  model?: string;
+  maxTokens?: number;
+  timeoutMs?: number;
+}
+
+/**
+ * Convert tool definitions from OpenAI format to Anthropic format.
+ * OpenAI: { type: "function", function: { name, description, parameters } }
+ * Anthropic: { name, description, input_schema }
+ */
+function convertToolDefs(tools: any[]): any[] {
+  return tools.map(t => {
+    if (t.type === "function" && t.function) {
+      return {
+        name: t.function.name,
+        description: t.function.description || "",
+        input_schema: t.function.parameters || { type: "object", properties: {} },
+      };
+    }
+    // Already in Anthropic format — pass through
+    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: ChatMessage[]): { system: string | undefined; apiMessages: any[] } {
+  let systemPrompt: string | undefined;
+  const apiMessages: any[] = [];
+
+  for (const m of messages) {
+    if (m.role === "system") {
+      systemPrompt = systemPrompt ? systemPrompt + "\n" + m.content : m.content;
+      continue;
+    }
+
+    if (m.role === "assistant") {
+      const content: any[] = [];
+      if (m.content) content.push({ type: "text", text: m.content });
+
+      // Convert OpenAI-style tool_calls to Anthropic tool_use blocks
+      const toolCalls = (m as any).tool_calls;
+      if (Array.isArray(toolCalls)) {
+        for (const tc of toolCalls) {
+          let input: any;
+          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 };
+}
+
+export function makeAnthropicDriver(cfg: AnthropicDriverConfig): ChatDriver {
+  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: ChatMessage[], opts?: any): Promise<ChatOutput> {
+    await rateLimiter.limit("llm-ask", 1);
+
+    const onToken: ((t: string) => void) | undefined = opts?.onToken;
+    const resolvedModel = opts?.model ?? model;
+
+    const { system: systemPrompt, apiMessages } = convertMessages(messages);
+
+    const body: any = {
+      model: resolvedModel,
+      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: Record<string, string> = {
+      "Content-Type": "application/json",
+      "x-api-key": cfg.apiKey,
+      "anthropic-version": "2023-06-01",
+    };
+
+    const RETRYABLE_STATUS = new Set([429, 503, 529]);
+    let requestId: string | undefined;
+
+    try {
+      let res!: Response;
+      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() as any;
+
+      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),
+            },
+          });
+        }
+      }
+
+      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}`, {
+        provider: "anthropic",
+        model: resolvedModel,
+        request_id: requestId,
+        retryable: false,
+        cause: e,
+      });
+      Logger.error("Anthropic driver error:", errorLogFields(ge));
+      throw ge;
+    }
+  }
+
+  return { chat };
+}

package/src/drivers/index.ts

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