selftune 0.1.4 → 0.2.1

package/cli/selftune/utils/frontmatter.ts

@@ -0,0 +1,217 @@
+/**
+ * frontmatter.ts
+ *
+ * Line-based YAML frontmatter parser for SKILL.md files.
+ * Extracts name, description, and version without a YAML library.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SkillFrontmatter {
+  name: string;
+  description: string;
+  version: string;
+  body: string;
+}
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse YAML frontmatter from a SKILL.md file.
+ *
+ * Handles two description formats:
+ *   - Single-line:  `description: When the user wants to...`
+ *   - Folded scalar: `description: >\n  Multi-line text...`
+ *
+ * Handles two version locations:
+ *   - Top-level: `version: 1.0.0`
+ *   - Nested:    `metadata:\n  version: 1.0.0`
+ *
+ * Returns the full content as description if no frontmatter is found.
+ */
+export function parseFrontmatter(content: string): SkillFrontmatter {
+  const lines = content.split("\n");
+
+  // Check for opening delimiter
+  if (lines[0]?.trim() !== "---") {
+    return { name: "", description: content, version: "", body: content };
+  }
+
+  // Find closing delimiter
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      endIdx = i;
+      break;
+    }
+  }
+
+  if (endIdx < 0) {
+    return { name: "", description: content, version: "", body: content };
+  }
+
+  const yamlLines = lines.slice(1, endIdx);
+  const body = lines
+    .slice(endIdx + 1)
+    .join("\n")
+    .replace(/^\n+/, "");
+
+  let name = "";
+  let description = "";
+  let version = "";
+  let inMetadata = false;
+
+  for (let i = 0; i < yamlLines.length; i++) {
+    const line = yamlLines[i];
+    const trimmed = line.trimEnd();
+
+    // Top-level `name:`
+    if (trimmed.startsWith("name:")) {
+      name = trimmed.slice("name:".length).trim();
+      inMetadata = false;
+      continue;
+    }
+
+    // Top-level `version:`
+    if (trimmed.startsWith("version:") && !trimmed.startsWith("  ")) {
+      version = trimmed.slice("version:".length).trim();
+      inMetadata = false;
+      continue;
+    }
+
+    // `metadata:` block start
+    if (trimmed === "metadata:" || trimmed.startsWith("metadata:")) {
+      inMetadata = true;
+      continue;
+    }
+
+    // Nested `version:` inside metadata
+    if (inMetadata && /^\s+version:/.test(trimmed)) {
+      version = trimmed.replace(/^\s+version:\s*/, "");
+      continue;
+    }
+
+    // Top-level `description:` — single-line or folded scalar
+    if (trimmed.startsWith("description:")) {
+      inMetadata = false;
+      const afterKey = trimmed.slice("description:".length).trim();
+
+      if (afterKey === ">" || afterKey === "|") {
+        // Folded/literal scalar: collect indented continuation lines
+        const descParts: string[] = [];
+        let j = i + 1;
+        while (j < yamlLines.length) {
+          const next = yamlLines[j];
+          // Continuation line must be indented (starts with whitespace)
+          if (next.length > 0 && /^\s/.test(next)) {
+            descParts.push(next.replace(/^\s+/, ""));
+          } else {
+            break;
+          }
+          j++;
+        }
+        description = descParts.join(" ").trim();
+        i = j - 1; // advance past consumed lines
+      } else {
+        // Single-line value
+        description = afterKey;
+      }
+      continue;
+    }
+
+    // Any other top-level key resets inMetadata
+    if (/^\S/.test(trimmed) && trimmed.includes(":")) {
+      inMetadata = false;
+    }
+  }
+
+  return { name, description, version, body };
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter description replacement
+// ---------------------------------------------------------------------------
+
+/**
+ * Replace the `description:` field in YAML frontmatter, preserving all other
+ * content. If the new description contains special YAML characters, it is
+ * written as a folded scalar (`description: >`).
+ *
+ * Returns the original content unchanged if no frontmatter is found.
+ */
+export function replaceFrontmatterDescription(content: string, newDescription: string): string {
+  const lines = content.split("\n");
+
+  if (lines[0]?.trim() !== "---") return content;
+
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      endIdx = i;
+      break;
+    }
+  }
+  if (endIdx < 0) return content;
+
+  // Find and replace the description within frontmatter lines
+  const yamlLines = lines.slice(1, endIdx);
+  const newYamlLines: string[] = [];
+  let i = 0;
+  let replaced = false;
+
+  while (i < yamlLines.length) {
+    const trimmed = yamlLines[i].trimEnd();
+
+    if (trimmed.startsWith("description:")) {
+      replaced = true;
+      const afterKey = trimmed.slice("description:".length).trim();
+
+      // Skip continuation lines of folded/literal scalars
+      if (afterKey === ">" || afterKey === "|") {
+        i++;
+        while (i < yamlLines.length && yamlLines[i].length > 0 && /^\s/.test(yamlLines[i])) {
+          i++;
+        }
+      } else {
+        i++;
+      }
+
+      // Write new description — use folded scalar if it's long or has special chars
+      const needsFolded = newDescription.length > 120 || /[:#"'[\]{}|>]/.test(newDescription);
+      if (needsFolded) {
+        newYamlLines.push("description: >");
+        // Wrap at ~78 chars with 2-space indent
+        const words = newDescription.split(/\s+/);
+        let line = "  ";
+        for (const word of words) {
+          if (line.length + word.length + 1 > 80 && line.trim().length > 0) {
+            newYamlLines.push(line);
+            line = `  ${word}`;
+          } else {
+            line = line.trim().length === 0 ? `  ${word}` : `${line} ${word}`;
+          }
+        }
+        if (line.trim().length > 0) newYamlLines.push(line);
+      } else {
+        newYamlLines.push(`description: ${newDescription}`);
+      }
+      continue;
+    }
+
+    newYamlLines.push(yamlLines[i]);
+    i++;
+  }
+
+  // If description wasn't found in frontmatter, add it
+  if (!replaced) {
+    newYamlLines.push(`description: ${newDescription}`);
+  }
+
+  const before = lines[0]; // "---"
+  const after = lines.slice(endIdx); // "---" + body
+  return [before, ...newYamlLines, ...after].join("\n");
+}

package/cli/selftune/utils/hooks.ts

@@ -0,0 +1,41 @@
+import { CLAUDE_CODE_HOOK_KEYS } from "../constants.js";
+
+export interface ClaudeCodeHookCommand {
+  command?: string;
+}
+
+export interface ClaudeCodeHookEntry {
+  command?: string;
+  hooks?: ClaudeCodeHookCommand[];
+}
+
+function isHookEntry(value: unknown): value is ClaudeCodeHookEntry {
+  return typeof value === "object" && value !== null;
+}
+
+export function entryReferencesSelftune(entry: ClaudeCodeHookEntry): boolean {
+  if (typeof entry.command === "string" && entry.command.includes("selftune")) {
+    return true;
+  }
+
+  if (Array.isArray(entry.hooks)) {
+    return entry.hooks.some(
+      (hook) => typeof hook.command === "string" && hook.command.includes("selftune"),
+    );
+  }
+
+  return false;
+}
+
+export function hookKeyHasSelftuneEntry(hooks: Record<string, unknown>, key: string): boolean {
+  const entries = hooks[key];
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return false;
+  }
+
+  return entries.some((entry) => isHookEntry(entry) && entryReferencesSelftune(entry));
+}
+
+export function missingClaudeCodeHookKeys(hooks: Record<string, unknown>): string[] {
+  return CLAUDE_CODE_HOOK_KEYS.filter((key) => !hookKeyHasSelftuneEntry(hooks, key));
+}

package/cli/selftune/utils/html.ts

@@ -0,0 +1,27 @@
+/**
+ * Escape JSON for safe embedding inside an HTML <script> tag.
+ *
+ * Escaping only </script> is not sufficient because arbitrary log payloads can
+ * contain HTML-like substrings that confuse the parser in raw-text script
+ * blocks. We escape all `<`, `>`, and `&` characters, plus the Unicode line
+ * separators that can break JavaScript parsing in some engines.
+ */
+export function escapeJsonForHtmlScript(data: unknown): string {
+  const json = JSON.stringify(data);
+  return (json ?? "null").replace(/[<>&\u2028\u2029]/g, (char) => {
+    switch (char) {
+      case "<":
+        return "\\u003c";
+      case ">":
+        return "\\u003e";
+      case "&":
+        return "\\u0026";
+      case "\u2028":
+        return "\\u2028";
+      case "\u2029":
+        return "\\u2029";
+      default:
+        return char;
+    }
+  });
+}

package/cli/selftune/utils/llm-call.ts

@@ -11,6 +11,27 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { AGENT_CANDIDATES } from "../constants.js";
+import { createLogger } from "./logging.js";
+
+const logger = createLogger("llm-call");
+
+// ---------------------------------------------------------------------------
+// Model alias resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * The claude CLI --model flag only accepts "sonnet" and "opus" as aliases.
+ * "haiku" is NOT a valid --model alias (only valid in --agents subagent config).
+ * Map short names to full model IDs so callers can use friendly names.
+ */
+const CLAUDE_MODEL_ALIASES: Record<string, string> = {
+  haiku: "claude-haiku-4-5-20251001",
+};
+
+/** Resolve a model alias to its full ID for the claude CLI --model flag. */
+function resolveModelFlag(flag: string): string {
+  return CLAUDE_MODEL_ALIASES[flag] ?? flag;
+}
 
 // ---------------------------------------------------------------------------
 // Agent detection
@@ -68,6 +89,35 @@ export function stripMarkdownFences(raw: string): string {
   return text;
 }
 
+// ---------------------------------------------------------------------------
+// Retry configuration
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_INITIAL_BACKOFF_MS = 2_000;
+
+/** Options to control retry behavior. All fields optional with sensible defaults. */
+export interface RetryOptions {
+  /** Maximum number of retries (default: 2). Set to 0 to disable retries. */
+  maxRetries?: number;
+  /** Initial backoff in ms before first retry (default: 2000). Doubles each retry. */
+  initialBackoffMs?: number;
+}
+
+/** Returns true for errors that are transient and worth retrying. */
+function isTransientError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message;
+  // Transient: non-zero exit codes from agent subprocess (crash, OOM, timeout kill)
+  if (/exited with code/i.test(msg)) return true;
+  return false;
+}
+
+/** Sleep for the given number of milliseconds. */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // ---------------------------------------------------------------------------
 // Call LLM via agent subprocess
 // ---------------------------------------------------------------------------
@@ -77,6 +127,8 @@ export async function callViaAgent(
   systemPrompt: string,
   userPrompt: string,
   agent: string,
+  modelFlag?: string,
+  retryOpts?: RetryOptions,
 ): Promise<string> {
   // Write prompt to temp file to avoid shell quoting issues
   const promptFile = join(tmpdir(), `selftune-llm-${Date.now()}.txt`);
@@ -88,6 +140,10 @@ export async function callViaAgent(
 
     if (agent === "claude") {
       cmd = ["claude", "-p", promptContent];
+      if (modelFlag) {
+        const resolved = resolveModelFlag(modelFlag);
+        cmd.push("--model", resolved);
+      }
     } else if (agent === "codex") {
       cmd = ["codex", "exec", "--skip-git-repo-check", promptContent];
     } else if (agent === "opencode") {
@@ -96,26 +152,53 @@ export async function callViaAgent(
       throw new Error(`Unknown agent: ${agent}`);
     }
 
-    const proc = Bun.spawn(cmd, {
-      stdout: "pipe",
-      stderr: "pipe",
-      env: { ...process.env, CLAUDECODE: "" },
-    });
-
-    // 120s timeout
-    const timeout = setTimeout(() => proc.kill(), 120_000);
-    const exitCode = await proc.exited;
-    clearTimeout(timeout);
-
-    if (exitCode !== 0) {
-      const stderr = await new Response(proc.stderr).text();
-      throw new Error(
-        `Agent '${agent}' exited with code ${exitCode}.\nstderr: ${stderr.slice(0, 500)}`,
-      );
+    // Retry loop with exponential backoff for transient failures
+    const maxRetries = retryOpts?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const initialBackoffMs = retryOpts?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;
+    let lastError: Error | undefined;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      if (attempt > 0) {
+        const backoffMs = initialBackoffMs * 2 ** (attempt - 1);
+        logger.warn(
+          `Retry ${attempt}/${maxRetries} for agent '${agent}' after ${backoffMs}ms backoff`,
+        );
+        await sleep(backoffMs);
+      }
+
+      try {
+        const proc = Bun.spawn(cmd, {
+          stdout: "pipe",
+          stderr: "pipe",
+          env: { ...process.env, CLAUDECODE: "" },
+        });
+
+        // Longer timeout for heavier models (sonnet/opus take longer than haiku)
+        const isLightModel = modelFlag === "haiku" || modelFlag?.includes("haiku");
+        const timeoutMs = isLightModel ? 120_000 : 300_000;
+        const timeout = setTimeout(() => proc.kill(), timeoutMs);
+        const exitCode = await proc.exited;
+        clearTimeout(timeout);
+
+        if (exitCode !== 0) {
+          const stderr = await new Response(proc.stderr).text();
+          throw new Error(
+            `Agent '${agent}' exited with code ${exitCode}.\nstderr: ${stderr.slice(0, 500)}`,
+          );
+        }
+
+        const raw = await new Response(proc.stdout).text();
+        return raw;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (!isTransientError(lastError) || attempt === maxRetries) {
+          throw lastError;
+        }
+        logger.warn(`Transient failure on attempt ${attempt + 1}: ${lastError.message}`);
+      }
     }
 
-    const raw = await new Response(proc.stdout).text();
-    return raw;
+    // Unreachable, but satisfies TypeScript
+    throw lastError ?? new Error("callViaAgent: unexpected retry loop exit");
   } finally {
     try {
       const { unlinkSync } = await import("node:fs");
@@ -135,9 +218,10 @@ export async function callLlm(
   systemPrompt: string,
   userPrompt: string,
   agent: string,
+  modelFlag?: string,
 ): Promise<string> {
   if (!agent) {
     throw new Error("Agent must be specified for callLlm");
   }
-  return callViaAgent(systemPrompt, userPrompt, agent);
+  return callViaAgent(systemPrompt, userPrompt, agent, modelFlag);
 }

package/cli/selftune/utils/math.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared math utilities.
+ */
+
+/**
+ * Clamp a number between min and max.
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}

package/cli/selftune/utils/query-filter.ts

@@ -0,0 +1,139 @@
+import { SKIP_PREFIXES } from "../constants.js";
+import type { QueryLogRecord, SkillUsageRecord } from "../types.js";
+
+const NON_USER_QUERY_PREFIXES = [
+  "<system_instruction>",
+  "<system-instruction>",
+  "<system-reminder>",
+  "<available-deferred-tools>",
+  "<fast_mode_info>",
+  "<local-command-caveat>",
+  "<local-command-stdout>",
+  "<local-command-stderr>",
+  "<command-name>",
+  "<task-notification>",
+  "<teammate-message",
+  "[Request interrupted by user for tool use]",
+  "[Request interrupted by user]",
+  "Base directory for this skill:",
+  "This session is being continued from a previous conversation that ran out of context.",
+  "USER'S CURRENT MESSAGE (summarize THIS):",
+  "CONTEXT:",
+  "Completing task",
+  "Tool loaded.",
+  "Continue from where you left off.",
+  "You are an evaluation assistant.",
+  "You are a skill description optimizer for an AI agent routing system.",
+  "The following skills are available",
+] as const;
+
+/**
+ * Regex patterns for wrapper/hook pipeline artifacts that are never real user prompts.
+ * These fire after prefix checks and cover structured hook callback lines.
+ */
+const NON_USER_QUERY_PATTERNS = [
+  // Hook callback output lines (e.g. "SessionStart:startup hook success: ...")
+  // "Stop" excluded from general alternation — too common as English word.
+  /^(SessionStart|UserPromptSubmit|PreToolUse|PostToolUse):/,
+  // Stop hook callbacks follow a structured shape: "Stop:" + lowercase/callback text
+  /^Stop:(session |cleanup |hook |Callback )/,
+  // Injected git context blocks
+  /^gitStatus:\s/,
+] as const;
+
+const LEADING_WRAPPED_QUERY_TAGS = [
+  "system_instruction",
+  "system-instruction",
+  "system-reminder",
+  "available-deferred-tools",
+  "fast_mode_info",
+  "task-notification",
+  "teammate-message",
+  "local-command-caveat",
+  "local-command-stdout",
+  "local-command-stderr",
+  "command-name",
+] as const;
+
+function stripLeadingWrappedQueryText(query: string): string {
+  let current = query.trim();
+
+  for (;;) {
+    let changed = false;
+
+    for (const tag of LEADING_WRAPPED_QUERY_TAGS) {
+      const pattern = new RegExp(`^<${tag}\\b[^>]*>[\\s\\S]*?<\\/${tag}>\\s*`, "i");
+      const next = current.replace(pattern, "").trim();
+      if (next !== current) {
+        current = next;
+        changed = true;
+        break;
+      }
+    }
+
+    if (!changed) return current;
+  }
+}
+
+export function extractActionableQueryText(query: string): string | null {
+  if (typeof query !== "string") return null;
+
+  const trimmed = query.trim();
+  if (!trimmed || trimmed === "-" || trimmed === "(query not found)") return null;
+
+  const candidate = stripLeadingWrappedQueryText(trimmed) || trimmed;
+  if (!candidate || candidate === "-" || candidate === "(query not found)") return null;
+
+  const isBlocked =
+    SKIP_PREFIXES.some((prefix) => candidate.startsWith(prefix)) ||
+    NON_USER_QUERY_PREFIXES.some((prefix) => candidate.startsWith(prefix)) ||
+    NON_USER_QUERY_PATTERNS.some((pattern) => pattern.test(candidate));
+
+  return isBlocked ? null : candidate;
+}
+
+export function isActionableQueryText(query: string): boolean {
+  return extractActionableQueryText(query) !== null;
+}
+
+export function filterActionableQueryRecords(queryRecords: QueryLogRecord[]): QueryLogRecord[] {
+  const actionable: QueryLogRecord[] = [];
+
+  for (const record of queryRecords) {
+    if (record == null) continue;
+    const normalizedQuery = extractActionableQueryText((record as QueryLogRecord).query);
+    if (!normalizedQuery) continue;
+    actionable.push(
+      normalizedQuery === record.query ? record : { ...record, query: normalizedQuery },
+    );
+  }
+
+  return actionable;
+}
+
+export function isActionableSkillUsageRecord(record: SkillUsageRecord | null | undefined): boolean {
+  if (record == null) return false;
+  if (typeof record.skill_name !== "string" || !record.skill_name.trim()) return false;
+  if (typeof record.query !== "string") return false;
+
+  const query = record.query.trim();
+  if (!query || query === "(query not found)") return false;
+
+  return extractActionableQueryText(query) !== null;
+}
+
+export function filterActionableSkillUsageRecords(
+  skillRecords: SkillUsageRecord[],
+): SkillUsageRecord[] {
+  const actionable: SkillUsageRecord[] = [];
+
+  for (const record of skillRecords) {
+    const normalizedQuery = extractActionableQueryText(record?.query);
+    if (!normalizedQuery) continue;
+    actionable.push(
+      normalizedQuery === record.query ? record : { ...record, query: normalizedQuery },
+    );
+  }
+
+  return actionable;
+}