@arvorco/relentless 0.3.0 → 0.4.2

package/src/agents/amp.ts

@@ -1,11 +1,31 @@
 /**
  * Amp Agent Adapter
  *
- * Adapter for Sourcegraph's Amp CLI
+ * Adapter for Sourcegraph's Amp CLI with model/mode selection support.
  * https://ampcode.com
+ *
+ * ## Supported Modes
+ * - `free` - Free tier mode ($10/day grant, may have rate limits)
+ * - `smart` - Smart mode (uses Amp's intelligent model selection)
+ *
+ * ## Model Selection Method
+ * Amp uses the `-m`/`--mode` CLI flag for mode selection.
+ * Amp uses `-x`/`--execute` to run a single prompt non-interactively.
+ *
+ * ## Usage Example
+ * ```typescript
+ * const result = await ampAdapter.invoke("Fix the bug", {
+ *   model: "free",  // Uses -m free
+ *   workingDirectory: "/path/to/project"
+ * });
+ * ```
+ *
+ * @module agents/amp
  */
 
 import type { AgentAdapter, AgentResult, InvokeOptions, RateLimitInfo } from "./types";
+import { getModelById } from "../routing/registry";
+import { runCommand } from "./exec";
 
 export const ampAdapter: AgentAdapter = {
   name: "amp",
@@ -37,31 +57,41 @@ export const ampAdapter: AgentAdapter = {
   },
 
   async invoke(prompt: string, options?: InvokeOptions): Promise<AgentResult> {
-    const startTime = Date.now();
     const args: string[] = [];
 
     if (options?.dangerouslyAllowAll) {
       args.push("--dangerously-allow-all");
     }
 
-    const proc = Bun.spawn(["amp", ...args], {
+    // Add mode flag if model is provided
+    if (options?.model) {
+      const modelProfile = getModelById(options.model);
+      const modeValue =
+        modelProfile?.harness === "amp" ? modelProfile.cliValue : options.model;
+      const modeFlag =
+        modelProfile?.harness === "amp" ? modelProfile.cliFlag : "-m";
+      args.push(modeFlag, modeValue);
+    }
+
+    // Execute single prompt in non-interactive mode
+    args.push("-x");
+
+    const result = await runCommand(["amp", ...args], {
       cwd: options?.workingDirectory,
       stdin: new Blob([prompt]),
-      stdout: "pipe",
-      stderr: "pipe",
+      timeoutMs: options?.timeout,
     });
 
-    // Collect output
-    const stdout = await new Response(proc.stdout).text();
-    const stderr = await new Response(proc.stderr).text();
-    const exitCode = await proc.exited;
-
-    const output = stdout + (stderr ? `\n${stderr}` : "");
-    const duration = Date.now() - startTime;
+    const timeoutNote =
+      result.timedOut && options?.timeout
+        ? `\n[Relentless] Idle timeout after ${options.timeout}ms.`
+        : "";
+    const output = result.stdout + (result.stderr ? `\n${result.stderr}` : "") + timeoutNote;
+    const duration = result.duration;
 
     return {
       output,
-      exitCode,
+      exitCode: result.exitCode,
       isComplete: this.detectCompletion(output),
       duration,
     };
@@ -72,12 +102,22 @@ export const ampAdapter: AgentAdapter = {
   },
 
   detectRateLimit(output: string): RateLimitInfo {
+    if (output.includes("[Relentless] Idle timeout")) {
+      return {
+        limited: true,
+        message: "Amp idle timeout",
+      };
+    }
+
     // Amp rate limit patterns
     const patterns = [
       /quota exceeded/i,
       /limit reached/i,
       /rate limit/i,
       /too many requests/i,
+      /execute mode is not permitted/i,
+      /unexpected error inside amp cli/i,
+      /amp threads share --support/i,
     ];
 
     for (const pattern of patterns) {

package/src/agents/claude.ts

@@ -1,11 +1,38 @@
 /**
  * Claude Code Agent Adapter
  *
- * Adapter for Anthropic's Claude Code CLI
+ * Adapter for Anthropic's Claude Code CLI.
  * https://docs.anthropic.com/claude-code
+ *
+ * ## Model Selection
+ *
+ * Claude Code supports model selection via the `--model` flag.
+ * Pass the model name in the `options.model` parameter.
+ *
+ * **Supported models:**
+ * - `opus-4.5` (claude-opus-4-5-20251101) - SOTA, best for code review and architecture
+ * - `sonnet-4.5` (claude-sonnet-4-5-20251020) - Balanced, good for daily coding
+ * - `haiku-4.5` (claude-haiku-4-5-20251001) - Fast and cheap, good for simple tasks
+ *
+ * These IDs map to the full Claude model identifiers in the CLI.
+ *
+ * **CLI command format:**
+ * ```
+ * claude --model <model> -p <prompt>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const result = await claudeAdapter.invoke("Fix the bug", {
+ *   model: "opus-4.5",
+ *   workingDirectory: "/path/to/project"
+ * });
+ * ```
  */
 
 import type { AgentAdapter, AgentResult, InvokeOptions, RateLimitInfo } from "./types.js";
+import { getModelById } from "../routing/registry";
+import { runCommand } from "./exec";
 
 export const claudeAdapter: AgentAdapter = {
   name: "claude",
@@ -37,7 +64,6 @@ export const claudeAdapter: AgentAdapter = {
   },
 
   async invoke(prompt: string, options?: InvokeOptions): Promise<AgentResult> {
-    const startTime = Date.now();
     const args = ["-p"];
 
     if (options?.dangerouslyAllowAll) {
@@ -45,27 +71,30 @@ export const claudeAdapter: AgentAdapter = {
     }
 
     if (options?.model) {
-      args.push("--model", options.model);
+      const modelProfile = getModelById(options.model);
+      if (modelProfile?.harness === "claude") {
+        args.push("--model", modelProfile.cliValue);
+      } else {
+        args.push("--model", options.model);
+      }
     }
 
-    const proc = Bun.spawn(["claude", ...args], {
+    const result = await runCommand(["claude", ...args], {
       cwd: options?.workingDirectory,
       stdin: new Blob([prompt]),
-      stdout: "pipe",
-      stderr: "pipe",
+      timeoutMs: options?.timeout,
     });
 
-    // Collect output
-    const stdout = await new Response(proc.stdout).text();
-    const stderr = await new Response(proc.stderr).text();
-    const exitCode = await proc.exited;
-
-    const output = stdout + (stderr ? `\n${stderr}` : "");
-    const duration = Date.now() - startTime;
+    const timeoutNote =
+      result.timedOut && options?.timeout
+        ? `\n[Relentless] Idle timeout after ${options.timeout}ms.`
+        : "";
+    const output = result.stdout + (result.stderr ? `\n${result.stderr}` : "") + timeoutNote;
+    const duration = result.duration;
 
     return {
       output,
-      exitCode,
+      exitCode: result.exitCode,
       isComplete: this.detectCompletion(output),
       duration,
     };
@@ -83,7 +112,12 @@ export const claudeAdapter: AgentAdapter = {
     }
 
     if (options?.model) {
-      args.push("--model", options.model);
+      const modelProfile = getModelById(options.model);
+      if (modelProfile?.harness === "claude") {
+        args.push("--model", modelProfile.cliValue);
+      } else {
+        args.push("--model", options.model);
+      }
     }
 
     const proc = Bun.spawn(["claude", ...args], {
@@ -130,6 +164,27 @@ export const claudeAdapter: AgentAdapter = {
   },
 
   detectRateLimit(output: string): RateLimitInfo {
+    if (output.includes("[Relentless] Idle timeout")) {
+      return {
+        limited: true,
+        message: "Claude idle timeout",
+      };
+    }
+
+    if (/(?:operation not permitted|permission denied|\beperm\b).*(?:\/\.claude|\.claude)/i.test(output)) {
+      return {
+        limited: true,
+        message: "Claude unavailable due to permission error",
+      };
+    }
+
+    if (/not_found_error/i.test(output) && /model/i.test(output)) {
+      return {
+        limited: true,
+        message: "Claude model not found",
+      };
+    }
+
     // Pattern: "You've hit your limit · resets 12am (America/Sao_Paulo)"
     if (output.includes("You've hit your limit") || output.includes("you've hit your limit")) {
       const resetMatch = output.match(/resets\s+(\d{1,2})(am|pm)/i);

package/src/agents/codex.ts

@@ -1,11 +1,39 @@
 /**
  * Codex Agent Adapter
  *
- * Adapter for OpenAI's Codex CLI
+ * Adapter for OpenAI's Codex CLI.
  * https://developers.openai.com/codex/cli/
+ *
+ * ## Model Selection
+ *
+ * Codex supports model selection via the `--model` flag.
+ * Pass the model name in the `options.model` parameter.
+ *
+ * **Supported models (GPT-5.2 reasoning tiers):**
+ * - `gpt-5.2-xhigh` - reasoning-effort xhigh (~$1.75/$14 per MTok)
+ * - `gpt-5.2-high` - reasoning-effort high (~$1.75/$14 per MTok)
+ * - `gpt-5.2-medium` - reasoning-effort medium (~$1.25/$10 per MTok)
+ * - `gpt-5.2-low` - reasoning-effort low (~$0.75/$6 per MTok)
+ *
+ * These IDs map to `--model gpt-5.2 -c reasoning_effort="<tier>"` in the CLI.
+ *
+ * **CLI command format:**
+ * ```
+ * codex exec --model gpt-5.2 -c reasoning_effort="<low|medium|high|xhigh>" -
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const result = await codexAdapter.invoke("Fix the bug", {
+ *   model: "gpt-5.2-high",
+ *   workingDirectory: "/path/to/project"
+ * });
+ * ```
  */
 
 import type { AgentAdapter, AgentResult, InvokeOptions, RateLimitInfo } from "./types";
+import { getModelById } from "../routing/registry";
+import { runCommand } from "./exec";
 
 export const codexAdapter: AgentAdapter = {
   name: "codex",
@@ -37,27 +65,40 @@ export const codexAdapter: AgentAdapter = {
   },
 
   async invoke(prompt: string, options?: InvokeOptions): Promise<AgentResult> {
-    const startTime = Date.now();
+    const args = ["exec"];
+
+    // Add model selection if specified
+    if (options?.model) {
+      const modelProfile = getModelById(options.model);
+      if (modelProfile?.harness === "codex") {
+        args.push(modelProfile.cliFlag, modelProfile.cliValue);
+        if (modelProfile.cliArgs) {
+          args.push(...modelProfile.cliArgs);
+        }
+      } else {
+        args.push("--model", options.model);
+      }
+    }
+
+    // Codex uses `-` to read from stdin
+    args.push("-");
 
-    // Codex uses `codex exec -` to read from stdin
-    const proc = Bun.spawn(["codex", "exec", "-"], {
+    const result = await runCommand(["codex", ...args], {
       cwd: options?.workingDirectory,
       stdin: new Blob([prompt]),
-      stdout: "pipe",
-      stderr: "pipe",
+      timeoutMs: options?.timeout,
     });
 
-    // Collect output
-    const stdout = await new Response(proc.stdout).text();
-    const stderr = await new Response(proc.stderr).text();
-    const exitCode = await proc.exited;
-
-    const output = stdout + (stderr ? `\n${stderr}` : "");
-    const duration = Date.now() - startTime;
+    const timeoutNote =
+      result.timedOut && options?.timeout
+        ? `\n[Relentless] Idle timeout after ${options.timeout}ms.`
+        : "";
+    const output = result.stdout + (result.stderr ? `\n${result.stderr}` : "") + timeoutNote;
+    const duration = result.duration;
 
     return {
       output,
-      exitCode,
+      exitCode: result.exitCode,
       isComplete: this.detectCompletion(output),
       duration,
     };
@@ -68,6 +109,24 @@ export const codexAdapter: AgentAdapter = {
   },
 
   detectRateLimit(output: string): RateLimitInfo {
+    if (output.includes("[Relentless] Idle timeout")) {
+      return {
+        limited: true,
+        message: "Codex idle timeout",
+      };
+    }
+
+    if (
+      /cannot access session files/i.test(output) ||
+      /failed to create session/i.test(output) ||
+      /(permission denied|operation not permitted).*\/\.codex\/sessions/i.test(output)
+    ) {
+      return {
+        limited: true,
+        message: "Codex unavailable due to session permissions",
+      };
+    }
+
     // Codex/OpenAI rate limit patterns
     const patterns = [
       /rate limit exceeded/i,

package/src/agents/droid.ts

@@ -1,11 +1,41 @@
 /**
  * Droid Agent Adapter
  *
- * Adapter for Factory's Droid CLI
+ * Adapter for Factory's Droid CLI.
  * https://factory.ai
+ *
+ * ## Model Selection
+ *
+ * Droid supports model selection via the `-m` flag (short form).
+ * Pass the model name in the `options.model` parameter.
+ *
+ * **Supported models:**
+ * - `claude-opus-4-5-20251101` - Claude Opus 4.5
+ * - `claude-sonnet-4-5-20250929` - Claude Sonnet 4.5
+ * - `claude-haiku-4-5-20251001` - Claude Haiku 4.5
+ * - `gpt-5.2` - GPT-5.2
+ * - `gpt-5.1` - GPT-5.1
+ * - `gpt-5.1-codex` - GPT-5.1 Codex
+ * - `gpt-5.1-codex-max` - GPT-5.1 Codex Max
+ * - `gemini-3-pro-preview` - Gemini 3 Pro Preview
+ *
+ * **CLI command format:**
+ * ```
+ * droid exec -m <model> --reasoning-effort <level> --auto high
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const result = await droidAdapter.invoke("Fix the bug", {
+ *   model: "gpt-5.2",
+ *   workingDirectory: "/path/to/project"
+ * });
+ * ```
  */
 
 import type { AgentAdapter, AgentResult, InvokeOptions, RateLimitInfo } from "./types";
+import { getModelById } from "../routing/registry";
+import { runCommand } from "./exec";
 
 export const droidAdapter: AgentAdapter = {
   name: "droid",
@@ -37,28 +67,38 @@ export const droidAdapter: AgentAdapter = {
   },
 
   async invoke(prompt: string, options?: InvokeOptions): Promise<AgentResult> {
-    const startTime = Date.now();
+    // Build command args: droid exec [-m <model>] --auto high
+    const args = ["exec"];
+
+    if (options?.model) {
+      const modelProfile = getModelById(options.model);
+      const modelValue =
+        modelProfile?.harness === "droid" ? modelProfile.cliValue : options.model;
+      args.push("-m", modelValue);
+      if (modelProfile?.harness === "droid" && modelProfile.cliArgs) {
+        args.push(...modelProfile.cliArgs);
+      }
+    }
 
-    // Droid reads from stdin when piped or redirected.
     // Use --auto high for high risk tolerance by default
-    const proc = Bun.spawn(["droid", "exec", "--auto", "high"], {
+    args.push("--auto", "high");
+
+    const result = await runCommand(["droid", ...args], {
       cwd: options?.workingDirectory,
       stdin: new Blob([prompt]),
-      stdout: "pipe",
-      stderr: "pipe",
+      timeoutMs: options?.timeout,
     });
 
-    // Collect output
-    const stdout = await new Response(proc.stdout).text();
-    const stderr = await new Response(proc.stderr).text();
-    const exitCode = await proc.exited;
-
-    const output = stdout + (stderr ? `\n${stderr}` : "");
-    const duration = Date.now() - startTime;
+    const timeoutNote =
+      result.timedOut && options?.timeout
+        ? `\n[Relentless] Idle timeout after ${options.timeout}ms.`
+        : "";
+    const output = result.stdout + (result.stderr ? `\n${result.stderr}` : "") + timeoutNote;
+    const duration = result.duration;
 
     return {
       output,
-      exitCode,
+      exitCode: result.exitCode,
       isComplete: this.detectCompletion(output),
       duration,
     };
@@ -69,6 +109,20 @@ export const droidAdapter: AgentAdapter = {
   },
 
   detectRateLimit(output: string): RateLimitInfo {
+    if (output.includes("[Relentless] Idle timeout")) {
+      return {
+        limited: true,
+        message: "Droid idle timeout",
+      };
+    }
+
+    if (/mcp start failed/i.test(output) || /error reloading mcp servers/i.test(output)) {
+      return {
+        limited: true,
+        message: "Droid unavailable due to MCP initialization failure",
+      };
+    }
+
     // Droid rate limit patterns
     const patterns = [
       /rate limit/i,

package/src/agents/exec.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared command runner with idle timeout support for agent adapters.
+ */
+
+export interface RunCommandOptions {
+  cwd?: string;
+  stdin?: Blob;
+  timeoutMs?: number;
+}
+
+export interface RunCommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  duration: number;
+  timedOut: boolean;
+}
+
+async function readStream(
+  stream: ReadableStream<Uint8Array>,
+  onChunk: () => void
+): Promise<string> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let output = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        const chunk = decoder.decode(value, { stream: true });
+        if (chunk) {
+          output += chunk;
+          onChunk();
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  return output;
+}
+
+export async function runCommand(
+  command: string[],
+  options: RunCommandOptions = {}
+): Promise<RunCommandResult> {
+  const startTime = Date.now();
+  const proc = Bun.spawn(command, {
+    cwd: options.cwd,
+    stdin: options.stdin,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  let lastOutput = Date.now();
+  let timedOut = false;
+  let idleTimer: ReturnType<typeof setInterval> | undefined;
+
+  const onChunk = () => {
+    lastOutput = Date.now();
+  };
+
+  if (options.timeoutMs && options.timeoutMs > 0) {
+    idleTimer = setInterval(() => {
+      if (Date.now() - lastOutput > options.timeoutMs!) {
+        timedOut = true;
+        try {
+          proc.kill();
+        } catch {
+          // Best-effort kill on timeout.
+        }
+      }
+    }, 500);
+  }
+
+  const [stdout, stderr] = await Promise.all([
+    readStream(proc.stdout, onChunk),
+    readStream(proc.stderr, onChunk),
+  ]);
+  const exitCode = await proc.exited;
+
+  if (idleTimer) {
+    clearInterval(idleTimer);
+  }
+
+  return {
+    stdout,
+    stderr,
+    exitCode,
+    duration: Date.now() - startTime,
+    timedOut,
+  };
+}

package/src/agents/gemini.ts

@@ -1,11 +1,33 @@
 /**
  * Gemini Agent Adapter
  *
- * Adapter for Google's Gemini CLI
+ * Adapter for Google's Gemini CLI with model selection support.
  * https://github.com/google-gemini/gemini-cli
+ *
+ * ## Supported Models
+ * - `gemini-3-pro` - Gemini 3 Pro (best for complex reasoning and coding tasks)
+ * - `gemini-3-flash` - Gemini 3 Flash (faster, more cost-effective for simpler tasks)
+ *
+ * ## CLI Command Format
+ * With model: `gemini --model <model> --prompt "<prompt>"`
+ * Without model: `gemini --prompt "<prompt>"`
+ * With dangerous mode: `gemini --yolo --model <model> --prompt "<prompt>"`
+ *
+ * ## Usage Example
+ * ```typescript
+ * const result = await geminiAdapter.invoke("Fix the bug", {
+ *   model: "gemini-3-pro",
+ *   dangerouslyAllowAll: true,  // Sets --yolo flag
+ *   workingDirectory: "/path/to/project"
+ * });
+ * ```
+ *
+ * @module agents/gemini
  */
 
 import type { AgentAdapter, AgentResult, InvokeOptions, RateLimitInfo } from "./types";
+import { getModelById } from "../routing/registry";
+import { runCommand } from "./exec";
 
 export const geminiAdapter: AgentAdapter = {
   name: "gemini",
@@ -37,7 +59,6 @@ export const geminiAdapter: AgentAdapter = {
   },
 
   async invoke(prompt: string, options?: InvokeOptions): Promise<AgentResult> {
-    const startTime = Date.now();
     const args: string[] = [];
 
     if (options?.dangerouslyAllowAll) {
@@ -45,29 +66,35 @@ export const geminiAdapter: AgentAdapter = {
     }
 
     if (options?.model) {
-      args.push("--model", options.model);
+      const modelProfile = getModelById(options.model);
+      if (modelProfile?.harness === "gemini") {
+        args.push("--model", modelProfile.cliValue);
+        if (modelProfile.cliArgs) {
+          args.push(...modelProfile.cliArgs);
+        }
+      } else {
+        args.push("--model", options.model);
+      }
     }
 
-    // Gemini CLI accepts prompt as positional argument
-    args.push(prompt);
+    // Gemini CLI uses -p/--prompt for non-interactive prompts
+    args.push("--prompt", prompt);
 
-    const proc = Bun.spawn(["gemini", ...args], {
+    const result = await runCommand(["gemini", ...args], {
       cwd: options?.workingDirectory,
-      stdout: "pipe",
-      stderr: "pipe",
+      timeoutMs: options?.timeout,
     });
 
-    // Collect output
-    const stdout = await new Response(proc.stdout).text();
-    const stderr = await new Response(proc.stderr).text();
-    const exitCode = await proc.exited;
-
-    const output = stdout + (stderr ? `\n${stderr}` : "");
-    const duration = Date.now() - startTime;
+    const timeoutNote =
+      result.timedOut && options?.timeout
+        ? `\n[Relentless] Idle timeout after ${options.timeout}ms.`
+        : "";
+    const output = result.stdout + (result.stderr ? `\n${result.stderr}` : "") + timeoutNote;
+    const duration = result.duration;
 
     return {
       output,
-      exitCode,
+      exitCode: result.exitCode,
       isComplete: this.detectCompletion(output),
       duration,
     };
@@ -78,6 +105,13 @@ export const geminiAdapter: AgentAdapter = {
   },
 
   detectRateLimit(output: string): RateLimitInfo {
+    if (output.includes("[Relentless] Idle timeout")) {
+      return {
+        limited: true,
+        message: "Gemini idle timeout",
+      };
+    }
+
     // Gemini rate limit patterns
     const patterns = [
       /quota exceeded/i,
@@ -85,6 +119,15 @@ export const geminiAdapter: AgentAdapter = {
       /rate limit/i,
       /\b429\b/,
       /too many requests/i,
+      /operation not permitted/i,
+      /\beperm\b/i,
+      /error initializing chat recording service/i,
+      /err_module_not_found/i,
+      /cannot find package/i,
+      /data collection is disabled/i,
+      /gemini_api_key/i,
+      /google_genai_use_vertexai/i,
+      /google_genai_use_gca/i,
     ];
 
     for (const pattern of patterns) {