@towles/tool 0.0.20 → 0.0.41

package/src/commands/observe/setup.ts

@@ -0,0 +1,180 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { homedir } from "node:os";
+import pc from "picocolors";
+import consola from "consola";
+import { BaseCommand } from "../base.js";
+
+const CLAUDE_DIR = path.join(homedir(), ".claude");
+const CLAUDE_SETTINGS_PATH = path.join(CLAUDE_DIR, "settings.json");
+const REPORTS_DIR = path.join(CLAUDE_DIR, "reports");
+
+interface ClaudeSettings {
+  cleanupPeriodDays?: number;
+  alwaysThinkingEnabled?: boolean;
+  env?: Record<string, string>;
+  hooks?: {
+    SubagentStop?: Array<{
+      matcher?: Record<string, unknown>;
+      hooks?: Array<{
+        type: string;
+        command: string;
+      }>;
+    }>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+const OTEL_ENV_VARS: Record<string, string> = {
+  CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+  OTEL_METRICS_EXPORTER: "otlp",
+  OTEL_LOGS_EXPORTER: "otlp",
+  OTEL_EXPORTER_OTLP_ENDPOINT: "http://localhost:4317",
+};
+
+/**
+ * Configure observability settings for Claude Code
+ */
+export default class ObserveSetup extends BaseCommand {
+  static override description = "Configure Claude Code observability settings";
+
+  static override examples = [
+    "<%= config.bin %> observe setup",
+    "<%= config.bin %> observe setup  # Adds SubagentStop hook for lineage tracking",
+  ];
+
+  async run(): Promise<void> {
+    await this.parse(ObserveSetup);
+
+    this.log(pc.bold("\n📊 Claude Code Observability Setup\n"));
+
+    // Load or create Claude settings
+    let claudeSettings: ClaudeSettings = {};
+    if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+      try {
+        const content = fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf-8");
+        claudeSettings = JSON.parse(content);
+        this.log(pc.dim(`Found existing Claude settings at ${CLAUDE_SETTINGS_PATH}`));
+      } catch {
+        this.log(
+          pc.yellow(`Warning: Could not parse ${CLAUDE_SETTINGS_PATH}, will create fresh settings`),
+        );
+      }
+    } else {
+      this.log(pc.dim(`No Claude settings file found, will create one`));
+    }
+
+    let modified = false;
+
+    // 1. Ensure cleanupPeriodDays is set to prevent log deletion
+    if (claudeSettings.cleanupPeriodDays !== 99999) {
+      claudeSettings.cleanupPeriodDays = 99999;
+      modified = true;
+      this.log(pc.green("✓ Set cleanupPeriodDays: 99999 (prevent log deletion)"));
+    } else {
+      this.log(pc.dim("✓ cleanupPeriodDays already set to 99999"));
+    }
+
+    // 2. Configure SubagentStop hook for lineage tracking
+    const subagentLogPath = path.join(REPORTS_DIR, "subagent-log.jsonl");
+    const subagentHookCommand = `jq -c '. + {parent: env.SESSION_ID, timestamp: now}' >> ${subagentLogPath}`;
+
+    if (!claudeSettings.hooks) {
+      claudeSettings.hooks = {};
+    }
+
+    const existingSubagentHook = claudeSettings.hooks.SubagentStop;
+    const hasSubagentHook =
+      existingSubagentHook &&
+      Array.isArray(existingSubagentHook) &&
+      existingSubagentHook.length > 0;
+
+    if (!hasSubagentHook) {
+      claudeSettings.hooks.SubagentStop = [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: subagentHookCommand,
+            },
+          ],
+        },
+      ];
+      modified = true;
+      this.log(pc.green("✓ Added SubagentStop hook for subagent lineage tracking"));
+    } else {
+      this.log(pc.dim("✓ SubagentStop hook already configured"));
+    }
+
+    // 3. Add OTEL environment variables to settings
+    if (!claudeSettings.env) {
+      claudeSettings.env = {};
+    }
+
+    const addedVars: string[] = [];
+    const skippedVars: string[] = [];
+    for (const [key, value] of Object.entries(OTEL_ENV_VARS)) {
+      if (claudeSettings.env[key] === undefined) {
+        claudeSettings.env[key] = value;
+        addedVars.push(key);
+        modified = true;
+      } else {
+        skippedVars.push(key);
+      }
+    }
+
+    if (addedVars.length > 0) {
+      this.log(pc.green(`✓ Added env vars: ${addedVars.join(", ")}`));
+    }
+    if (skippedVars.length > 0) {
+      this.log(pc.dim(`✓ Env vars already set: ${skippedVars.join(", ")}`));
+    }
+
+    // Save settings if modified
+    if (modified) {
+      this.saveClaudeSettings(claudeSettings);
+      this.log(pc.green(`\n✓ Saved settings to ${CLAUDE_SETTINGS_PATH}`));
+    }
+
+    // 4. Create reports directory
+    if (!fs.existsSync(REPORTS_DIR)) {
+      fs.mkdirSync(REPORTS_DIR, { recursive: true });
+      this.log(pc.green(`✓ Created reports directory at ${REPORTS_DIR}`));
+    } else {
+      this.log(pc.dim(`✓ Reports directory exists at ${REPORTS_DIR}`));
+    }
+
+    // 5. Show OTEL environment variables setup
+    this.log(pc.bold("\n🔧 OTEL Environment Variables\n"));
+    this.log(pc.cyan("Add these to your shell profile (~/.bashrc, ~/.zshrc, etc.):\n"));
+
+    consola.box(`export CLAUDE_CODE_ENABLE_TELEMETRY=1
+export OTEL_METRICS_EXPORTER=otlp
+export OTEL_LOGS_EXPORTER=otlp
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317`);
+
+    this.log("");
+    this.log(pc.dim("For a full monitoring stack, see:"));
+    this.log(pc.dim("  https://github.com/anthropics/claude-code-monitoring-guide"));
+    this.log("");
+
+    // Quick usage tips
+    this.log(pc.bold("📈 Quick Analysis Commands\n"));
+    this.log(pc.dim("  tt observe status     # Check current config"));
+    this.log(pc.dim("  tt observe report     # Token/cost breakdown"));
+    this.log(pc.dim("  tt observe session    # List sessions"));
+    this.log(pc.dim("  tt observe graph     # Visualize token usage"));
+    this.log("");
+
+    this.log(pc.bold(pc.green("✅ Observability setup complete!\n")));
+  }
+
+  private saveClaudeSettings(settings: ClaudeSettings): void {
+    const dir = path.dirname(CLAUDE_SETTINGS_PATH);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2));
+  }
+}

package/src/commands/observe/status.ts

@@ -0,0 +1,146 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { homedir } from "node:os";
+import pc from "picocolors";
+import { BaseCommand } from "../base.js";
+
+const CLAUDE_DIR = path.join(homedir(), ".claude");
+const CLAUDE_SETTINGS_PATH = path.join(CLAUDE_DIR, "settings.json");
+const REPORTS_DIR = path.join(CLAUDE_DIR, "reports");
+
+interface ClaudeSettings {
+  cleanupPeriodDays?: number;
+  alwaysThinkingEnabled?: boolean;
+  hooks?: {
+    SubagentStop?: unknown[];
+    PreToolUse?: unknown[];
+    PostToolUse?: unknown[];
+    Stop?: unknown[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+/**
+ * Display current observability configuration status
+ */
+export default class ObserveStatus extends BaseCommand {
+  static override description = "Display current observability configuration status";
+
+  static override examples = [
+    "<%= config.bin %> observe status",
+    "<%= config.bin %> observe status  # Check if observability is properly configured",
+  ];
+
+  async run(): Promise<void> {
+    await this.parse(ObserveStatus);
+
+    this.log(pc.bold("\n📊 Observability Status\n"));
+
+    // Load Claude settings
+    let settings: ClaudeSettings = {};
+    if (fs.existsSync(CLAUDE_SETTINGS_PATH)) {
+      try {
+        const content = fs.readFileSync(CLAUDE_SETTINGS_PATH, "utf-8");
+        settings = JSON.parse(content);
+      } catch {
+        this.log(pc.red(`✗ Could not parse ${CLAUDE_SETTINGS_PATH}`));
+      }
+    } else {
+      this.log(pc.yellow(`⚠ No settings file at ${CLAUDE_SETTINGS_PATH}`));
+      this.log(pc.dim("  Run: tt observe setup"));
+      this.log("");
+    }
+
+    // 1. Claude Settings
+    this.log(pc.bold("Claude Settings"));
+    this.log(pc.dim(`  Path: ${CLAUDE_SETTINGS_PATH}\n`));
+
+    // cleanupPeriodDays
+    const cleanup = settings.cleanupPeriodDays;
+    if (cleanup === 99999) {
+      this.log(pc.green("  ✓ cleanupPeriodDays: 99999 (logs preserved)"));
+    } else if (cleanup !== undefined) {
+      this.log(pc.yellow(`  ⚠ cleanupPeriodDays: ${cleanup} (logs may be deleted)`));
+    } else {
+      this.log(pc.red("  ✗ cleanupPeriodDays: not set (default cleanup applies)"));
+    }
+
+    // alwaysThinkingEnabled
+    if (settings.alwaysThinkingEnabled) {
+      this.log(pc.green("  ✓ alwaysThinkingEnabled: true"));
+    } else {
+      this.log(pc.dim("  ○ alwaysThinkingEnabled: false"));
+    }
+
+    this.log("");
+
+    // 2. Hooks
+    this.log(pc.bold("Hooks Configured"));
+    const hooks = settings.hooks || {};
+    const hookNames = ["SubagentStop", "PreToolUse", "PostToolUse", "Stop"];
+    let hasAnyHook = false;
+
+    for (const name of hookNames) {
+      const hook = hooks[name];
+      if (hook && Array.isArray(hook) && hook.length > 0) {
+        this.log(pc.green(`  ✓ ${name}: ${hook.length} handler(s)`));
+        hasAnyHook = true;
+      }
+    }
+
+    // Check for other hooks
+    const otherHooks = Object.keys(hooks).filter((k) => !hookNames.includes(k));
+    for (const name of otherHooks) {
+      const hook = hooks[name];
+      if (hook && Array.isArray(hook) && hook.length > 0) {
+        this.log(pc.green(`  ✓ ${name}: ${(hook as unknown[]).length} handler(s)`));
+        hasAnyHook = true;
+      }
+    }
+
+    if (!hasAnyHook) {
+      this.log(pc.dim("  ○ No hooks configured"));
+    }
+
+    this.log("");
+
+    // 3. Reports Directory
+    this.log(pc.bold("Reports Directory"));
+    if (fs.existsSync(REPORTS_DIR)) {
+      const files = fs.readdirSync(REPORTS_DIR);
+      this.log(pc.green(`  ✓ ${REPORTS_DIR}`));
+      this.log(pc.dim(`    ${files.length} file(s)`));
+    } else {
+      this.log(pc.yellow(`  ⚠ ${REPORTS_DIR} does not exist`));
+      this.log(pc.dim("    Run: tt observe setup"));
+    }
+
+    this.log("");
+
+    // 4. OTEL Environment Variables
+    this.log(pc.bold("OTEL Environment Variables"));
+
+    const otelVars = [
+      { name: "CLAUDE_CODE_ENABLE_TELEMETRY", expected: "1" },
+      { name: "OTEL_METRICS_EXPORTER", expected: "otlp" },
+      { name: "OTEL_LOGS_EXPORTER", expected: "otlp" },
+      { name: "OTEL_EXPORTER_OTLP_ENDPOINT", expected: undefined },
+    ];
+
+    for (const { name, expected } of otelVars) {
+      const value = process.env[name];
+      if (value) {
+        if (expected && value !== expected) {
+          this.log(pc.yellow(`  ⚠ ${name}=${value} (expected: ${expected})`));
+        } else {
+          this.log(pc.green(`  ✓ ${name}=${value}`));
+        }
+      } else {
+        this.log(pc.dim(`  ○ ${name}: not set`));
+      }
+    }
+
+    this.log("");
+  }
+}

package/src/commands/ralph/lib/execution.ts

@@ -0,0 +1,302 @@
+import type { WriteStream } from "node:fs";
+import { spawn } from "node:child_process";
+import pc from "picocolors";
+import { x } from "tinyexec";
+import { CLAUDE_DEFAULT_ARGS } from "./state.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface StreamEvent {
+  type: string;
+  event?: {
+    type: string;
+    delta?: { text?: string };
+  };
+  // New format: assistant message
+  message?: {
+    content?: Array<{ type: string; text?: string }>;
+    usage?: {
+      input_tokens?: number;
+      output_tokens?: number;
+      cache_read_input_tokens?: number;
+      cache_creation_input_tokens?: number;
+    };
+  };
+  result?: string;
+  total_cost_usd?: number;
+  num_turns?: number;
+  session_id?: string;
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
+}
+
+// Claude model context windows (tokens)
+const MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  "claude-sonnet-4-20250514": 200000,
+  "claude-opus-4-20250514": 200000,
+  "claude-3-5-sonnet-20241022": 200000,
+  "claude-3-opus-20240229": 200000,
+  default: 200000,
+};
+
+export interface IterationResult {
+  output: string;
+  exitCode: number;
+  contextUsedPercent?: number;
+  sessionId?: string;
+}
+
+interface ParsedLine {
+  text: string | null;
+  tool?: { name: string; summary: string };
+  usage?: StreamEvent["usage"];
+  sessionId?: string;
+}
+
+// ============================================================================
+// Claude CLI Check
+// ============================================================================
+
+export async function checkClaudeCli(): Promise<boolean> {
+  try {
+    const result = await x("which", ["claude"]);
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// Stream Parsing
+// ============================================================================
+
+// Track accumulated text from assistant messages to compute deltas
+let lastAssistantText = "";
+
+/**
+ * Reset stream parsing state between iterations.
+ */
+export function resetStreamState(): void {
+  lastAssistantText = "";
+}
+
+function summarizeTool(name: string, input: Record<string, unknown>): string {
+  switch (name) {
+    case "Read":
+      return (
+        String(input.file_path || input.path || "")
+          .split("/")
+          .pop() || "file"
+      );
+    case "Write":
+    case "Edit":
+      return (
+        String(input.file_path || input.path || "")
+          .split("/")
+          .pop() || "file"
+      );
+    case "Glob":
+      return String(input.pattern || "");
+    case "Grep":
+      return String(input.pattern || "");
+    case "Bash":
+      return String(input.command || "").substring(0, 40);
+    case "TodoWrite":
+      return "updating todos";
+    default:
+      return Object.values(input)[0]?.toString().substring(0, 30) || "";
+  }
+}
+
+function parseStreamLine(line: string): ParsedLine {
+  if (!line.trim()) return { text: null };
+  try {
+    const data = JSON.parse(line) as StreamEvent & {
+      tool_use?: { name: string; input: Record<string, unknown> };
+      content_block?: { type: string; name?: string; input?: Record<string, unknown> };
+    };
+
+    // Handle tool_use events
+    if (data.type === "tool_use" && data.tool_use) {
+      const name = data.tool_use.name;
+      const summary = summarizeTool(name, data.tool_use.input || {});
+      return { text: null, tool: { name, summary } };
+    }
+
+    // Handle content_block with tool_use (streaming format)
+    if (data.type === "content_block" && data.content_block?.type === "tool_use") {
+      const name = data.content_block.name || "Tool";
+      const summary = summarizeTool(name, data.content_block.input || {});
+      return { text: null, tool: { name, summary } };
+    }
+
+    // Extract text from streaming deltas (legacy format)
+    if (data.type === "stream_event" && data.event?.type === "content_block_delta") {
+      return { text: data.event.delta?.text || null };
+    }
+    // Add newline after content block ends (legacy format)
+    if (data.type === "stream_event" && data.event?.type === "content_block_stop") {
+      return { text: "\n" };
+    }
+    // NEW FORMAT: Handle assistant messages with content array
+    if (data.type === "assistant" && data.message) {
+      // Check for tool_use in content blocks
+      const toolBlocks = data.message.content?.filter((c) => c.type === "tool_use") || [];
+      if (toolBlocks.length > 0) {
+        const tb = toolBlocks[toolBlocks.length - 1] as {
+          name?: string;
+          input?: Record<string, unknown>;
+        };
+        const name = tb.name || "Tool";
+        const summary = summarizeTool(name, tb.input || {});
+        return {
+          text: null,
+          tool: { name, summary },
+          usage: data.message.usage || data.usage,
+          sessionId: data.session_id,
+        };
+      }
+
+      // Extract full text from content blocks
+      const fullText =
+        data.message.content
+          ?.filter((c) => c.type === "text" && c.text)
+          .map((c) => c.text)
+          .join("") || "";
+
+      // Compute delta (only new portion) to avoid duplicate output
+      let delta: string | null = null;
+      if (fullText.startsWith(lastAssistantText)) {
+        delta = fullText.slice(lastAssistantText.length) || null;
+      } else {
+        // Text doesn't match prefix - new context
+        delta = fullText || null;
+      }
+      lastAssistantText = fullText;
+
+      return { text: delta, usage: data.message.usage || data.usage, sessionId: data.session_id };
+    }
+    // Capture final result with usage and session_id
+    if (data.type === "result") {
+      const resultText = data.result
+        ? `\n[Result: ${data.result.substring(0, 100)}${data.result.length > 100 ? "..." : ""}]\n`
+        : null;
+      return { text: resultText, usage: data.usage, sessionId: data.session_id };
+    }
+  } catch {
+    // Not JSON, return raw
+    return { text: line };
+  }
+  return { text: null };
+}
+
+// ============================================================================
+// Run Iteration
+// ============================================================================
+
+export async function runIteration(
+  prompt: string,
+  claudeArgs: string[],
+  logStream?: WriteStream,
+): Promise<IterationResult> {
+  // Reset accumulated text state from previous iteration
+  resetStreamState();
+
+  // Pass task context as system prompt via --append-system-prompt
+  // 'continue' is the user prompt - required by claude CLI when using --print
+  const allArgs = [
+    ...CLAUDE_DEFAULT_ARGS,
+    ...claudeArgs,
+    "--append-system-prompt",
+    prompt,
+    "continue",
+  ];
+
+  let output = "";
+  let lineBuffer = "";
+  let finalUsage: StreamEvent["usage"] | undefined;
+  let sessionId: string | undefined;
+  let lastCharWasNewline = true;
+
+  const processLine = (line: string) => {
+    const { text: parsed, tool, usage, sessionId: sid } = parseStreamLine(line);
+    if (usage) finalUsage = usage;
+    if (sid) sessionId = sid;
+    if (tool) {
+      const prefix = lastCharWasNewline ? "" : "\n";
+      const toolLine = `${prefix}${pc.yellow("⚡")} ${pc.cyan(tool.name)}: ${tool.summary}\n`;
+      process.stdout.write(toolLine);
+      logStream?.write(`${prefix}⚡ ${tool.name}: ${tool.summary}\n`);
+      lastCharWasNewline = true;
+    }
+    if (parsed) {
+      process.stdout.write(parsed);
+      logStream?.write(parsed);
+      output += parsed;
+      lastCharWasNewline = parsed.endsWith("\n");
+    }
+  };
+
+  return new Promise((resolve) => {
+    const proc = spawn("claude", allArgs, {
+      stdio: ["inherit", "pipe", "pipe"],
+    });
+
+    proc.stdout.on("data", (chunk: Buffer) => {
+      const text = chunk.toString();
+      lineBuffer += text;
+
+      const lines = lineBuffer.split("\n");
+      lineBuffer = lines.pop() || "";
+
+      for (const line of lines) {
+        processLine(line);
+      }
+    });
+
+    proc.stderr.on("data", (chunk: Buffer) => {
+      const text = chunk.toString();
+      process.stderr.write(text);
+      logStream?.write(text);
+      output += text;
+    });
+
+    proc.on("close", (code: number | null) => {
+      if (lineBuffer) {
+        processLine(lineBuffer);
+      }
+
+      if (output && !output.endsWith("\n")) {
+        process.stdout.write("\n");
+        logStream?.write("\n");
+        output += "\n";
+      }
+
+      // Calculate context usage percent
+      let contextUsedPercent: number | undefined;
+      if (finalUsage) {
+        const totalTokens =
+          (finalUsage.input_tokens || 0) +
+          (finalUsage.output_tokens || 0) +
+          (finalUsage.cache_read_input_tokens || 0) +
+          (finalUsage.cache_creation_input_tokens || 0);
+        const maxContext = MODEL_CONTEXT_WINDOWS.default;
+        contextUsedPercent = Math.round((totalTokens / maxContext) * 100);
+      }
+
+      resolve({ output, exitCode: code ?? 0, contextUsedPercent, sessionId });
+    });
+
+    proc.on("error", (err: Error) => {
+      console.error(pc.red(`Error running claude: ${err}`));
+      logStream?.write(`Error running claude: ${err}\n`);
+      resolve({ output, exitCode: 1 });
+    });
+  });
+}