@tjamescouch/gro 1.3.2

package/src/session.ts

@@ -0,0 +1,150 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { ChatMessage } from "./drivers/types.js";
+import { Logger } from "./logger.js";
+import { groError, asError, errorLogFields } from "./errors.js";
+
+/**
+ * Session persistence for gro.
+ *
+ * Layout:
+ *   .gro/
+ *     context/
+ *       <session-id>/
+ *         messages.json   — full message history
+ *         meta.json       — session metadata (model, provider, timestamps)
+ */
+
+export interface SessionMeta {
+  id: string;
+  provider: string;
+  model: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+const GRO_DIR = ".gro";
+const CONTEXT_DIR = "context";
+
+function groDir(): string {
+  return join(process.cwd(), GRO_DIR);
+}
+
+function contextDir(): string {
+  return join(groDir(), CONTEXT_DIR);
+}
+
+function sessionDir(id: string): string {
+  return join(contextDir(), id);
+}
+
+/**
+ * Ensure the .gro/context directory exists.
+ */
+export function ensureGroDir(): void {
+  const dir = contextDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Generate a new session ID (short UUID prefix for readability).
+ */
+export function newSessionId(): string {
+  return randomUUID().split("-")[0];
+}
+
+/**
+ * Save a session to disk.
+ */
+export function saveSession(
+  id: string,
+  messages: ChatMessage[],
+  meta: Omit<SessionMeta, "updatedAt">,
+): void {
+  const dir = sessionDir(id);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const fullMeta: SessionMeta = {
+    ...meta,
+    updatedAt: new Date().toISOString(),
+  };
+
+  writeFileSync(join(dir, "messages.json"), JSON.stringify(messages, null, 2));
+  writeFileSync(join(dir, "meta.json"), JSON.stringify(fullMeta, null, 2));
+}
+
+/**
+ * Load a session from disk. Returns null if not found.
+ */
+export function loadSession(id: string): { messages: ChatMessage[]; meta: SessionMeta } | null {
+  const dir = sessionDir(id);
+  const msgPath = join(dir, "messages.json");
+  const metaPath = join(dir, "meta.json");
+
+  if (!existsSync(msgPath) || !existsSync(metaPath)) {
+    return null;
+  }
+
+  try {
+    const messages = JSON.parse(readFileSync(msgPath, "utf-8"));
+    const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+    return { messages, meta };
+  } catch (e: unknown) {
+    const ge = groError("session_error", `Failed to load session ${id}: ${asError(e).message}`, { cause: e });
+    Logger.warn(ge.message, errorLogFields(ge));
+    return null;
+  }
+}
+
+/**
+ * Find the most recent session (for --continue).
+ */
+export function findLatestSession(): string | null {
+  const dir = contextDir();
+  if (!existsSync(dir)) return null;
+
+  let latest: { id: string; mtime: number } | null = null;
+
+  for (const entry of readdirSync(dir)) {
+    const metaPath = join(dir, entry, "meta.json");
+    if (existsSync(metaPath)) {
+      const stat = statSync(metaPath);
+      if (!latest || stat.mtimeMs > latest.mtime) {
+        latest = { id: entry, mtime: stat.mtimeMs };
+      }
+    }
+  }
+
+  return latest?.id ?? null;
+}
+
+/**
+ * List all sessions, sorted by most recent first.
+ */
+export function listSessions(): SessionMeta[] {
+  const dir = contextDir();
+  if (!existsSync(dir)) return [];
+
+  const sessions: (SessionMeta & { mtime: number })[] = [];
+
+  for (const entry of readdirSync(dir)) {
+    const metaPath = join(dir, entry, "meta.json");
+    if (existsSync(metaPath)) {
+      try {
+        const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+        const stat = statSync(metaPath);
+        sessions.push({ ...meta, mtime: stat.mtimeMs });
+      } catch {
+        // skip corrupt sessions
+      }
+    }
+  }
+
+  sessions.sort((a, b) => b.mtime - a.mtime);
+  return sessions.map(({ mtime: _, ...rest }) => rest);
+}

package/src/tools/agentpatch.ts

@@ -0,0 +1,89 @@
+/**
+ * agentpatch tool integration for gro.
+ *
+ * Exposes a first-class file editor: `apply_patch`.
+ *
+ * This wraps the agentpatch patch grammar and applies patches via the
+ * `agentpatch/bin/apply_patch` script.
+ */
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { Logger } from "../logger.js";
+
+const DEFAULT_TIMEOUT = 120_000;
+const MAX_OUTPUT = 30_000;
+
+export function agentpatchToolDefinition(): any {
+  return {
+    type: "function",
+    function: {
+      name: "apply_patch",
+      description: "Apply a unified agentpatch-style patch to the working tree (safe, idempotent).",
+      parameters: {
+        type: "object",
+        properties: {
+          patch: { type: "string", description: "The patch text (agentpatch grammar)." },
+          dry_run: { type: "boolean", description: "If true, validate/preview without writing." },
+          verbose: { type: "boolean", description: "If true, emit debug logs from applier." },
+          allow_delete: { type: "boolean", description: "Allow *** Delete File ops." },
+          allow_rename: { type: "boolean", description: "Allow *** Rename File ops." },
+          timeout: { type: "number", description: "Timeout in ms (default 120000)." },
+        },
+        required: ["patch"],
+      },
+    },
+  };
+}
+
+function truncate(s: string): string {
+  if (s.length <= MAX_OUTPUT) return s;
+  const half = Math.floor(MAX_OUTPUT / 2);
+  return s.slice(0, half) + `\n\n... (truncated ${s.length - MAX_OUTPUT} chars) ...\n\n` + s.slice(-half);
+}
+
+export function executeAgentpatch(args: Record<string, any>): string {
+  const patch = (args.patch as string) || "";
+  if (!patch.trim()) return "Error: empty patch";
+
+  const timeout = (args.timeout as number) || DEFAULT_TIMEOUT;
+  const dryRun = args.dry_run === true;
+  const verbose = args.verbose === true;
+  const allowDelete = args.allow_delete === true;
+  const allowRename = args.allow_rename === true;
+
+  // Expected layout in this monorepo-ish runner: /home/agent/agentpatch
+  // If not present, instruct user to clone it.
+  const agentpatchPath = process.env.AGENTPATCH_PATH || join(process.env.HOME || "", "agentpatch");
+  const bin = join(agentpatchPath, "bin", "apply_patch");
+  if (!existsSync(bin)) {
+    return `Error: agentpatch not found at ${bin}. Set AGENTPATCH_PATH or clone agentpatch to ~/agentpatch.`;
+  }
+
+  const cmd = [bin];
+  if (dryRun) cmd.push("--dry-run");
+  if (verbose) cmd.push("--verbose");
+  if (allowDelete) cmd.push("--allow-delete");
+  if (allowRename) cmd.push("--allow-rename");
+
+  Logger.debug(`apply_patch: ${cmd.join(" ")}`);
+
+  try {
+    const out = execSync(cmd.join(" "), {
+      shell: "/bin/bash",
+      input: patch,
+      encoding: "utf-8",
+      timeout,
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return truncate(out || "ok");
+  } catch (e: any) {
+    let result = "";
+    if (e.stdout) result += e.stdout;
+    if (e.stderr) result += (result ? "\n" : "") + e.stderr;
+    if (!result) result = e.message || "Command failed";
+    if (e.status != null) result += `\n[exit code: ${e.status}]`;
+    return truncate(result);
+  }
+}

package/src/tools/bash.ts

@@ -0,0 +1,61 @@
+/**
+ * Built-in bash tool for gro — executes shell commands and returns output.
+ * Gated behind --bash flag. Not enabled by default.
+ */
+import { execSync } from "node:child_process";
+import { Logger } from "../logger.js";
+
+const MAX_OUTPUT = 30_000;
+const DEFAULT_TIMEOUT = 120_000;
+
+export function bashToolDefinition(): any {
+  return {
+    type: "function",
+    function: {
+      name: "bash",
+      description: "Execute a bash command and return its output (stdout + stderr).",
+      parameters: {
+        type: "object",
+        properties: {
+          command: { type: "string", description: "The bash command to execute" },
+          timeout: { type: "number", description: "Timeout in milliseconds (default: 120000)" },
+        },
+        required: ["command"],
+      },
+    },
+  };
+}
+
+export function executeBash(args: Record<string, any>): string {
+  const command = args.command as string;
+  if (!command) return "Error: no command provided";
+
+  const timeout = (args.timeout as number) || DEFAULT_TIMEOUT;
+
+  Logger.debug(`bash: ${command}`);
+
+  try {
+    const output = execSync(command, {
+      shell: "/bin/bash",
+      encoding: "utf-8",
+      timeout,
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return truncate(output);
+  } catch (e: any) {
+    // execSync throws on non-zero exit — capture stdout + stderr
+    let result = "";
+    if (e.stdout) result += e.stdout;
+    if (e.stderr) result += (result ? "\n" : "") + e.stderr;
+    if (!result) result = e.message || "Command failed";
+    if (e.status != null) result += `\n[exit code: ${e.status}]`;
+    return truncate(result);
+  }
+}
+
+function truncate(s: string): string {
+  if (s.length <= MAX_OUTPUT) return s;
+  const half = Math.floor(MAX_OUTPUT / 2);
+  return s.slice(0, half) + `\n\n... (truncated ${s.length - MAX_OUTPUT} chars) ...\n\n` + s.slice(-half);
+}

package/src/utils/rate-limiter.ts

@@ -0,0 +1,60 @@
+type LimiterState = {
+  nextAvailableMs: number;
+  tail: Promise<void>;
+};
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
+class RateLimiter {
+  private states = new Map<string, LimiterState>();
+  private readonly now: () => number;
+
+  constructor(now?: () => number) {
+    this.now =
+      now ??
+      (() =>
+        typeof performance !== "undefined" && typeof performance.now === "function"
+          ? performance.now()
+          : Date.now());
+  }
+
+  async limit(name: string, throughputPerSecond: number): Promise<void> {
+    if (!Number.isFinite(throughputPerSecond) || throughputPerSecond <= 0) {
+      throw new RangeError(
+        `throughputPerSecond must be a positive finite number; got ${throughputPerSecond}`
+      );
+    }
+    const key = name || "default";
+    const state = this.getState(key);
+
+    const waitPromise = state.tail.then(async () => {
+      const intervalMs = 1000 / throughputPerSecond;
+      const now = this.now();
+      const scheduledAt = Math.max(now, state.nextAvailableMs);
+      state.nextAvailableMs = scheduledAt + intervalMs;
+      const delay = scheduledAt - now;
+      if (delay > 0) await sleep(delay);
+    });
+
+    state.tail = waitPromise.catch(() => {});
+    return waitPromise;
+  }
+
+  reset(name?: string): void {
+    if (name) this.states.delete(name);
+    else this.states.clear();
+  }
+
+  private getState(name: string): LimiterState {
+    let s = this.states.get(name);
+    if (!s) {
+      s = { nextAvailableMs: this.now(), tail: Promise.resolve() };
+      this.states.set(name, s);
+    }
+    return s;
+  }
+}
+
+export const rateLimiter = new RateLimiter();

package/src/utils/retry.ts

@@ -0,0 +1,32 @@
+/**
+ * Retry utilities for API drivers.
+ *
+ * Shared between Anthropic and OpenAI drivers to avoid duplication.
+ */
+
+export const MAX_RETRIES = 3;
+export const RETRY_BASE_MS = 1000;
+
+/**
+ * Check if an HTTP status code is retryable.
+ * 429 = rate limited, 502/503 = upstream error, 529 = overloaded.
+ */
+export function isRetryable(status: number): boolean {
+  return status === 429 || status === 502 || status === 503 || status === 529;
+}
+
+/**
+ * Calculate retry delay with exponential backoff + jitter.
+ * attempt 0 → base 1s + 0-0.5s jitter
+ * attempt 1 → base 2s + 0-1s jitter
+ * attempt 2 → base 4s + 0-2s jitter
+ */
+export function retryDelay(attempt: number): number {
+  const base = RETRY_BASE_MS * Math.pow(2, attempt);
+  const jitter = Math.random() * base * 0.5;
+  return base + jitter;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/utils/timed-fetch.ts

@@ -0,0 +1,29 @@
+import { asError } from "../errors.js";
+
+/** Wrap fetch with timeout and location context for debugging. */
+export async function timedFetch(
+  url: string,
+  init: RequestInit & { timeoutMs?: number; where?: string } = {}
+) {
+  const { timeoutMs, where, ...rest } = init;
+  let controller: AbortController | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  try {
+    if (timeoutMs && timeoutMs > 0) {
+      controller = new AbortController();
+      (rest as any).signal = controller.signal;
+      timer = setTimeout(() => controller!.abort(), timeoutMs);
+    }
+    return await fetch(url, rest);
+  } catch (e: unknown) {
+    const wrapped = asError(e);
+    const err = new Error(
+      `[fetch timeout] ${where ?? ""} ${url} -> ${wrapped.name}: ${wrapped.message}`
+    );
+    (err as any).cause = e;
+    throw err;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/tests/errors.test.ts

@@ -0,0 +1,246 @@
+/**
+ * Tests for structured error types (GroError).
+ *
+ * Covers: groError, asError, isGroError, errorLogFields
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import { groError, asError, isGroError, errorLogFields } from "../src/errors.js";
+import type { GroError } from "../src/errors.js";
+
+// ---------------------------------------------------------------------------
+// groError factory
+// ---------------------------------------------------------------------------
+
+describe("groError", () => {
+  test("creates an Error with kind and retryable fields", () => {
+    const e = groError("provider_error", "API failed");
+    assert.ok(e instanceof Error);
+    assert.strictEqual(e.kind, "provider_error");
+    assert.strictEqual(e.message, "API failed");
+    assert.strictEqual(e.retryable, false); // default
+    assert.ok(e.stack, "should have a stack trace");
+  });
+
+  test("retryable defaults to false", () => {
+    const e = groError("tool_error", "boom");
+    assert.strictEqual(e.retryable, false);
+  });
+
+  test("retryable can be set to true", () => {
+    const e = groError("provider_error", "429", { retryable: true });
+    assert.strictEqual(e.retryable, true);
+  });
+
+  test("optional fields are set when provided", () => {
+    const e = groError("provider_error", "fail", {
+      provider: "anthropic",
+      model: "claude-sonnet-4-20250514",
+      request_id: "req_123",
+      latency_ms: 450,
+      cause: new Error("underlying"),
+    });
+    assert.strictEqual(e.provider, "anthropic");
+    assert.strictEqual(e.model, "claude-sonnet-4-20250514");
+    assert.strictEqual(e.request_id, "req_123");
+    assert.strictEqual(e.latency_ms, 450);
+    assert.ok(e.cause instanceof Error);
+  });
+
+  test("optional fields are omitted when not provided", () => {
+    const e = groError("config_error", "bad config");
+    assert.strictEqual(e.provider, undefined);
+    assert.strictEqual(e.model, undefined);
+    assert.strictEqual(e.request_id, undefined);
+    assert.strictEqual(e.latency_ms, undefined);
+    assert.strictEqual(e.cause, undefined);
+  });
+
+  test("all GroErrorKind values are accepted", () => {
+    const kinds = [
+      "provider_error",
+      "tool_error",
+      "config_error",
+      "mcp_error",
+      "timeout_error",
+      "session_error",
+    ] as const;
+    for (const kind of kinds) {
+      const e = groError(kind, `test ${kind}`);
+      assert.strictEqual(e.kind, kind);
+    }
+  });
+
+  test("latency_ms of 0 is preserved (not treated as falsy)", () => {
+    const e = groError("provider_error", "fast fail", { latency_ms: 0 });
+    assert.strictEqual(e.latency_ms, 0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// asError
+// ---------------------------------------------------------------------------
+
+describe("asError", () => {
+  test("returns Error instances unchanged", () => {
+    const original = new Error("original");
+    const result = asError(original);
+    assert.strictEqual(result, original);
+  });
+
+  test("wraps strings into Error", () => {
+    const result = asError("something broke");
+    assert.ok(result instanceof Error);
+    assert.strictEqual(result.message, "something broke");
+  });
+
+  test("truncates long strings to 1024 chars", () => {
+    const long = "x".repeat(2000);
+    const result = asError(long);
+    assert.strictEqual(result.message.length, 1024);
+  });
+
+  test("handles null", () => {
+    const result = asError(null);
+    assert.ok(result instanceof Error);
+    assert.strictEqual(result.message, "Unknown error");
+  });
+
+  test("handles undefined", () => {
+    const result = asError(undefined);
+    assert.ok(result instanceof Error);
+    assert.strictEqual(result.message, "Unknown error");
+  });
+
+  test("handles objects via String()", () => {
+    const result = asError({ code: 42 });
+    assert.ok(result instanceof Error);
+    assert.ok(result.message.includes("[object Object]"));
+  });
+
+  test("handles numbers", () => {
+    const result = asError(42);
+    assert.ok(result instanceof Error);
+    assert.strictEqual(result.message, "42");
+  });
+
+  test("truncates long stringified values with ellipsis", () => {
+    // Use a value whose String() representation exceeds 1024 chars
+    const longStr = "z".repeat(2000);
+    const result = asError(longStr);
+    // String input goes through the string branch (slice to 1024, no ellipsis)
+    assert.strictEqual(result.message.length, 1024);
+
+    // For non-string values, String() > 1024 gets ellipsis
+    const longToString = { toString: () => "w".repeat(2000) };
+    const result2 = asError(longToString);
+    assert.ok(result2.message.endsWith("..."));
+    assert.strictEqual(result2.message.length, 1027); // 1024 + "..."
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isGroError
+// ---------------------------------------------------------------------------
+
+describe("isGroError", () => {
+  test("returns true for groError instances", () => {
+    const e = groError("provider_error", "test");
+    assert.strictEqual(isGroError(e), true);
+  });
+
+  test("returns false for plain Error", () => {
+    assert.strictEqual(isGroError(new Error("nope")), false);
+  });
+
+  test("returns false for non-Error objects", () => {
+    assert.strictEqual(isGroError({ kind: "provider_error", retryable: true }), false);
+  });
+
+  test("returns false for null", () => {
+    assert.strictEqual(isGroError(null), false);
+  });
+
+  test("returns false for undefined", () => {
+    assert.strictEqual(isGroError(undefined), false);
+  });
+
+  test("returns false for strings", () => {
+    assert.strictEqual(isGroError("error"), false);
+  });
+
+  test("returns true for Error manually augmented with kind and retryable", () => {
+    const e = new Error("manual") as any;
+    e.kind = "tool_error";
+    e.retryable = false;
+    assert.strictEqual(isGroError(e), true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// errorLogFields
+// ---------------------------------------------------------------------------
+
+describe("errorLogFields", () => {
+  test("returns basic fields for minimal GroError", () => {
+    const e = groError("config_error", "bad");
+    const fields = errorLogFields(e);
+    assert.strictEqual(fields.kind, "config_error");
+    assert.strictEqual(fields.message, "bad");
+    assert.strictEqual(fields.retryable, false);
+    assert.ok(fields.stack, "should include stack");
+  });
+
+  test("includes optional fields when present", () => {
+    const e = groError("provider_error", "fail", {
+      provider: "anthropic",
+      model: "claude-sonnet-4-20250514",
+      request_id: "req_abc",
+      latency_ms: 100,
+    });
+    const fields = errorLogFields(e);
+    assert.strictEqual(fields.provider, "anthropic");
+    assert.strictEqual(fields.model, "claude-sonnet-4-20250514");
+    assert.strictEqual(fields.request_id, "req_abc");
+    assert.strictEqual(fields.latency_ms, 100);
+  });
+
+  test("omits optional fields when not set", () => {
+    const e = groError("tool_error", "boom");
+    const fields = errorLogFields(e);
+    assert.strictEqual(fields.provider, undefined);
+    assert.strictEqual(fields.model, undefined);
+    assert.strictEqual(fields.request_id, undefined);
+    assert.strictEqual(fields.latency_ms, undefined);
+  });
+
+  test("resolves cause into cause_message and cause_stack", () => {
+    const cause = new Error("root cause");
+    const e = groError("mcp_error", "mcp failed", { cause });
+    const fields = errorLogFields(e);
+    assert.strictEqual(fields.cause_message, "root cause");
+    assert.ok(fields.cause_stack);
+  });
+
+  test("resolves non-Error cause via asError", () => {
+    const e = groError("provider_error", "fail", { cause: "string cause" });
+    const fields = errorLogFields(e);
+    assert.strictEqual(fields.cause_message, "string cause");
+  });
+
+  test("result is JSON-serializable", () => {
+    const e = groError("provider_error", "test", {
+      provider: "openai",
+      model: "gpt-4o",
+      request_id: "req_1",
+      latency_ms: 200,
+      cause: new Error("inner"),
+    });
+    const fields = errorLogFields(e);
+    const json = JSON.stringify(fields);
+    assert.ok(json.length > 0);
+    const parsed = JSON.parse(json);
+    assert.strictEqual(parsed.kind, "provider_error");
+  });
+});