selftune 0.1.4 → 0.2.1

package/cli/selftune/hooks/session-stop.ts

@@ -7,11 +7,88 @@
  * Appends one record per session to ~/.claude/session_telemetry_log.jsonl.
  */
 
-import { TELEMETRY_LOG } from "../constants.js";
-import type { SessionTelemetryRecord, StopPayload } from "../types.js";
-import { appendJsonl } from "../utils/jsonl.js";
+import { closeSync, openSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { CANONICAL_LOG, ORCHESTRATE_LOCK, SIGNAL_LOG, TELEMETRY_LOG } from "../constants.js";
+import {
+  appendCanonicalRecords,
+  buildCanonicalExecutionFact,
+  buildCanonicalSession,
+  type CanonicalBaseInput,
+  getLatestPromptIdentity,
+} from "../normalization.js";
+import type { ImprovementSignalRecord, SessionTelemetryRecord, StopPayload } from "../types.js";
+import { appendJsonl, readJsonl } from "../utils/jsonl.js";
 import { parseTranscript } from "../utils/transcript.js";
 
+const LOCK_STALE_MS = 30 * 60 * 1000;
+
+/**
+ * Check for pending improvement signals and spawn a focused orchestrate run
+ * in the background if warranted. Fire-and-forget — the hook exits immediately.
+ *
+ * Returns true if a process was spawned, false otherwise.
+ */
+export function maybeSpawnReactiveOrchestrate(
+  signalLogPath: string = SIGNAL_LOG,
+  lockPath: string = ORCHESTRATE_LOCK,
+): boolean {
+  try {
+    // Read pending signals
+    const signals = readJsonl<ImprovementSignalRecord>(signalLogPath);
+    const pending = signals.filter((s) => !s.consumed);
+    if (pending.length === 0) return false;
+
+    // Atomically claim the lock — openSync with "wx" fails if file exists
+    let fd: number;
+    try {
+      fd = openSync(lockPath, "wx");
+      writeFileSync(fd, JSON.stringify({ timestamp: new Date().toISOString(), pid: process.pid }));
+      closeSync(fd);
+    } catch (lockErr: unknown) {
+      // Lock exists — check if stale
+      if ((lockErr as NodeJS.ErrnoException).code === "EEXIST") {
+        try {
+          const lockContent = readFileSync(lockPath, "utf8");
+          const lock = JSON.parse(lockContent);
+          const lockAge = Date.now() - new Date(lock.timestamp).getTime();
+          if (lockAge < LOCK_STALE_MS) return false; // Active lock, skip
+          // Stale lock — override
+          writeFileSync(
+            lockPath,
+            JSON.stringify({ timestamp: new Date().toISOString(), pid: process.pid }),
+          );
+        } catch {
+          return false; // Can't read lock, skip
+        }
+      } else {
+        return false;
+      }
+    }
+
+    // Spawn orchestrate in background (fire-and-forget)
+    try {
+      const proc = Bun.spawn(["selftune", "orchestrate", "--max-skills", "2"], {
+        stdout: "ignore",
+        stderr: "ignore",
+        stdin: "ignore",
+      });
+      proc.unref();
+    } catch {
+      // Spawn failed — release our lock
+      try {
+        unlinkSync(lockPath);
+      } catch {
+        /* ignore */
+      }
+      return false;
+    }
+
+    return true;
+  } catch {
+    return false; // Silent — hooks must never block Claude
+  }
+}
+
 /**
  * Core processing logic, exported for testability.
  * Returns the record that was appended.
@@ -19,6 +96,8 @@ import { parseTranscript } from "../utils/transcript.js";
 export function processSessionStop(
   payload: StopPayload,
   logPath: string = TELEMETRY_LOG,
+  canonicalLogPath: string = CANONICAL_LOG,
+  promptStatePath?: string,
 ): SessionTelemetryRecord {
   const sessionId = typeof payload.session_id === "string" ? payload.session_id : "unknown";
   const transcriptPath = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
@@ -36,6 +115,47 @@ export function processSessionStop(
   };
 
   appendJsonl(logPath, record);
+
+  // Emit canonical session + execution fact records (additive)
+  const baseInput: CanonicalBaseInput = {
+    platform: "claude_code",
+    capture_mode: "hook",
+    source_session_kind: "interactive",
+    session_id: sessionId,
+    raw_source_ref: {
+      path: transcriptPath || undefined,
+      event_type: "Stop",
+    },
+  };
+  const latestPrompt = getLatestPromptIdentity(sessionId, promptStatePath, canonicalLogPath);
+
+  const canonicalSession = buildCanonicalSession({
+    ...baseInput,
+    workspace_path: cwd || undefined,
+  });
+
+  const canonicalFact = buildCanonicalExecutionFact({
+    ...baseInput,
+    occurred_at: record.timestamp,
+    prompt_id: latestPrompt.last_actionable_prompt_id ?? latestPrompt.last_prompt_id,
+    tool_calls_json: metrics.tool_calls,
+    total_tool_calls: metrics.total_tool_calls,
+    bash_commands_redacted: metrics.bash_commands,
+    assistant_turns: metrics.assistant_turns,
+    errors_encountered: metrics.errors_encountered,
+    input_tokens: metrics.input_tokens,
+    output_tokens: metrics.output_tokens,
+    duration_ms: metrics.duration_ms,
+  });
+  appendCanonicalRecords([canonicalSession, canonicalFact], canonicalLogPath);
+
+  // Reactive: spawn focused orchestrate if pending improvement signals exist
+  try {
+    maybeSpawnReactiveOrchestrate();
+  } catch {
+    // silent — hooks must never block
+  }
+
   return record;
 }
 

package/cli/selftune/hooks/skill-change-guard.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env bun
+/**
+ * Claude Code PreToolUse hook: skill-change-guard.ts
+ *
+ * Fires before Write/Edit tool calls. If the target is a SKILL.md file,
+ * outputs a suggestion to run `selftune watch --skill <name>` to monitor
+ * the impact of the change.
+ *
+ * This is advisory only — exit code is always 0, never blocking.
+ * Uses session state to avoid repeating suggestions for the same skill.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { SESSION_STATE_DIR } from "../constants.js";
+import type { PreToolUsePayload } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Detection helpers
+// ---------------------------------------------------------------------------
+
+/** Check if a tool call is a Write or Edit targeting a SKILL.md file. */
+export function isSkillMdWrite(toolName: string, filePath: string): boolean {
+  if (toolName !== "Write" && toolName !== "Edit") return false;
+  return basename(filePath).toUpperCase() === "SKILL.MD";
+}
+
+/** Extract the skill folder name from a path ending in SKILL.md. */
+export function extractSkillNameFromPath(filePath: string): string {
+  return basename(dirname(filePath)) || "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// Session state (minimal — just tracks which skills we've already warned about)
+// ---------------------------------------------------------------------------
+
+interface GuardState {
+  session_id: string;
+  warned_skills: string[];
+}
+
+function loadGuardState(path: string, sessionId: string): GuardState {
+  if (!existsSync(path)) {
+    return { session_id: sessionId, warned_skills: [] };
+  }
+  try {
+    const data = JSON.parse(readFileSync(path, "utf-8")) as GuardState;
+    if (data.session_id === sessionId && Array.isArray(data.warned_skills)) {
+      return data;
+    }
+  } catch {
+    // corrupt — start fresh
+  }
+  return { session_id: sessionId, warned_skills: [] };
+}
+
+function saveGuardState(path: string, state: GuardState): void {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(state, null, 2), "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Core processing logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Process a PreToolUse payload and return a suggestion string if the tool
+ * call is writing to a SKILL.md file that hasn't been warned about yet.
+ */
+export function processPreToolUse(payload: PreToolUsePayload, statePath: string): string | null {
+  const filePath =
+    typeof payload.tool_input?.file_path === "string" ? payload.tool_input.file_path : "";
+
+  if (!isSkillMdWrite(payload.tool_name, filePath)) return null;
+
+  const skillName = extractSkillNameFromPath(filePath);
+  const sessionId = payload.session_id ?? "unknown";
+
+  // Check if we've already warned about this skill in this session
+  const state = loadGuardState(statePath, sessionId);
+  if (state.warned_skills.includes(skillName)) return null;
+
+  // Record that we warned about this skill
+  state.warned_skills.push(skillName);
+  saveGuardState(statePath, state);
+
+  return `Run \`selftune watch --skill ${skillName}\` to monitor the impact of this SKILL.md change.`;
+}
+
+// ---------------------------------------------------------------------------
+// stdin main (only when executed directly, not when imported)
+// ---------------------------------------------------------------------------
+
+if (import.meta.main) {
+  try {
+    const payload: PreToolUsePayload = JSON.parse(await Bun.stdin.text());
+    const sessionId = payload.session_id ?? "unknown";
+    const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const statePath = `${SESSION_STATE_DIR}/guard-state-${safe}.json`;
+
+    const suggestion = processPreToolUse(payload, statePath);
+    if (suggestion) {
+      process.stderr.write(`[selftune] 💡 Suggestion: ${suggestion}\n`);
+    }
+  } catch {
+    // silent — hooks must never block Claude
+  }
+  process.exit(0);
+}

package/cli/selftune/hooks/skill-eval.ts

@@ -10,10 +10,21 @@
  * `should_trigger: true` half of trigger evals.
  */
 
+import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
-import { SKILL_LOG } from "../constants.js";
+import { CANONICAL_LOG, SKILL_LOG } from "../constants.js";
+import {
+  appendCanonicalRecord,
+  buildCanonicalSkillInvocation,
+  type CanonicalBaseInput,
+  deriveInvocationMode,
+  derivePromptId,
+  deriveSkillInvocationId,
+  getLatestPromptIdentity,
+} from "../normalization.js";
 import type { PostToolUsePayload, SkillUsageRecord } from "../types.js";
 import { appendJsonl } from "../utils/jsonl.js";
+import { classifySkillPath } from "../utils/skill-discovery.js";
 import { getLastUserMessage } from "../utils/transcript.js";
 
 /**
@@ -25,13 +36,73 @@ export function extractSkillName(filePath: string): string | null {
   return basename(dirname(filePath)) || "unknown";
 }
 
+/**
+ * Check whether the transcript contains a Skill tool invocation for the given
+ * skill name, indicating an actual skill use rather than casual browsing.
+ * Scans the transcript backwards for efficiency.
+ */
+export function hasSkillToolInvocation(transcriptPath: string, skillName: string): boolean {
+  return countSkillToolInvocations(transcriptPath, skillName) > 0;
+}
+
+export function countSkillToolInvocations(transcriptPath: string, skillName: string): number {
+  if (!transcriptPath || !existsSync(transcriptPath)) return 0;
+
+  try {
+    const content = readFileSync(transcriptPath, "utf-8");
+    const lines = content.trim().split("\n");
+    let matches = 0;
+
+    for (let i = lines.length - 1; i >= 0; i--) {
+      let entry: Record<string, unknown>;
+      try {
+        entry = JSON.parse(lines[i]);
+      } catch {
+        continue;
+      }
+
+      const msg = (entry.message as Record<string, unknown>) ?? entry;
+      const role = (msg.role as string) ?? (entry.role as string) ?? "";
+      if (role !== "assistant") continue;
+
+      const entryContent = msg.content ?? entry.content ?? "";
+      if (!Array.isArray(entryContent)) continue;
+
+      for (const block of entryContent) {
+        if (typeof block !== "object" || block === null) continue;
+        const b = block as Record<string, unknown>;
+        if (b.type !== "tool_use") continue;
+
+        const toolName = (b.name as string) ?? "";
+        if (toolName === "Skill") {
+          const inp = (b.input as Record<string, unknown>) ?? {};
+          const skillArg = (inp.skill as string) ?? (inp.name as string) ?? "";
+          if (skillArg === skillName) matches += 1;
+        }
+      }
+    }
+
+    return matches;
+  } catch {
+    // silent — hooks must never block Claude
+  }
+
+  return 0;
+}
+
 /**
  * Core processing logic, exported for testability.
  * Returns the record that was appended, or null if skipped.
+ *
+ * To reduce false triggers, checks whether the Read of SKILL.md was
+ * preceded by an actual Skill tool invocation in the same transcript.
+ * If not, the record is still logged but marked as triggered: false.
  */
 export function processToolUse(
   payload: PostToolUsePayload,
   logPath: string = SKILL_LOG,
+  canonicalLogPath: string = CANONICAL_LOG,
+  promptStatePath?: string,
 ): SkillUsageRecord | null {
   // Only care about Read tool
   if (payload.tool_name !== "Read") return null;
@@ -45,19 +116,64 @@ export function processToolUse(
   const transcriptPath = payload.transcript_path ?? "";
   const sessionId = payload.session_id ?? "unknown";
 
-  const query = getLastUserMessage(transcriptPath) ?? "(query not found)";
+  const query = getLastUserMessage(transcriptPath);
+  if (!query) return null;
+
+  // Distinguish actual invocation from browsing by checking for a Skill tool call
+  const invocationCount = countSkillToolInvocations(transcriptPath, skillName);
+  const wasInvoked = invocationCount > 0;
+  const skillPathMetadata = classifySkillPath(filePath);
 
   const record: SkillUsageRecord = {
     timestamp: new Date().toISOString(),
     session_id: sessionId,
     skill_name: skillName,
     skill_path: filePath,
+    ...skillPathMetadata,
     query,
-    triggered: true,
+    triggered: wasInvoked,
     source: "claude_code",
   };
 
   appendJsonl(logPath, record);
+
+  const baseInput: CanonicalBaseInput = {
+    platform: "claude_code",
+    capture_mode: "hook",
+    source_session_kind: "interactive",
+    session_id: sessionId,
+    raw_source_ref: {
+      path: transcriptPath || undefined,
+      event_type: "PostToolUse",
+    },
+  };
+  const latestPrompt = getLatestPromptIdentity(sessionId, promptStatePath, canonicalLogPath);
+  const promptId =
+    latestPrompt.last_actionable_prompt_id ??
+    latestPrompt.last_prompt_id ??
+    derivePromptId(sessionId, 0);
+  const { invocation_mode, confidence } = deriveInvocationMode({
+    has_skill_tool_call: wasInvoked,
+    has_skill_md_read: !wasInvoked,
+  });
+  const canonical = buildCanonicalSkillInvocation({
+    ...baseInput,
+    skill_invocation_id: deriveSkillInvocationId(
+      sessionId,
+      skillName,
+      Math.max(invocationCount - 1, 0),
+    ),
+    occurred_at: record.timestamp,
+    matched_prompt_id: promptId,
+    skill_name: skillName,
+    skill_path: filePath,
+    invocation_mode,
+    triggered: wasInvoked,
+    confidence,
+    tool_name: payload.tool_name,
+  });
+  appendCanonicalRecord(canonical, canonicalLogPath);
+
   return record;
 }