selftune 0.2.6 → 0.2.9

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

@@ -2,9 +2,10 @@
 /**
  * Claude Code PostToolUse hook: skill-eval.ts
  *
- * Fires whenever Claude reads a file. If that file is a SKILL.md, this hook:
+ * Fires whenever Claude reads a file or invokes a skill. If the file is a
+ * SKILL.md or the tool is a Skill invocation, this hook:
  *   1. Finds the triggering user query from the transcript JSONL
- *   2. Appends a usage record to ~/.claude/skill_usage_log.jsonl
+ *   2. Writes a usage record to SQLite via writeSkillUsageToDb()
  *
  * This builds a real-usage eval dataset over time, seeding the
  * `should_trigger: true` half of trigger evals.
@@ -23,7 +24,7 @@ import {
   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";
 
@@ -94,17 +95,26 @@ export function countSkillToolInvocations(transcriptPath: string, skillName: str
  * 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
+ * Handles two PostToolUse event types:
+ *   - Read: when a SKILL.md file is read (original path)
+ *   - Skill: when a skill is explicitly invoked via the Skill tool
+ *
+ * For Read events, 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(
+export async function processToolUse(
   payload: PostToolUsePayload,
   logPath: string = SKILL_LOG,
   canonicalLogPath: string = CANONICAL_LOG,
   promptStatePath?: string,
-): SkillUsageRecord | null {
-  // Only care about Read tool
+): Promise<SkillUsageRecord | null> {
+  // Handle Skill tool invocations (e.g., Skill(selftune))
+  if (payload.tool_name === "Skill") {
+    return await processSkillToolUse(payload, logPath, canonicalLogPath, promptStatePath);
+  }
+
+  // Only care about Read tool for SKILL.md detection
   if (payload.tool_name !== "Read") return null;
 
   const rawPath = payload.tool_input?.file_path;
@@ -132,11 +142,10 @@ export function processToolUse(
     ...skillPathMetadata,
     query,
     triggered: wasInvoked,
+    invocation_type: "contextual",
     source: "claude_code",
   };
 
-  appendJsonl(logPath, record);
-
   const baseInput: CanonicalBaseInput = {
     platform: "claude_code",
     capture_mode: "hook",
@@ -155,6 +164,7 @@ export function processToolUse(
   const { invocation_mode, confidence } = deriveInvocationMode({
     has_skill_tool_call: wasInvoked,
     has_skill_md_read: !wasInvoked,
+    hook_invocation_type: "contextual",
   });
   const canonical = buildCanonicalSkillInvocation({
     ...baseInput,
@@ -172,6 +182,175 @@ export function processToolUse(
     confidence,
     tool_name: payload.tool_name,
   });
+
+  // Write unified record to skill_invocations (replaces separate writeSkillUsageToDb call)
+  try {
+    const { writeSkillCheckToDb } = await import("../localdb/direct-write.js");
+    writeSkillCheckToDb({
+      ...canonical,
+      query: record.query,
+      skill_path: record.skill_path,
+      skill_scope: record.skill_scope,
+      source: record.source,
+    });
+  } catch {
+    /* hooks must never block */
+  }
+
+  appendCanonicalRecord(canonical, canonicalLogPath);
+
+  return record;
+}
+
+/**
+ * Classify how a Skill tool invocation was triggered:
+ *
+ *   explicit  — User typed /skillName (slash command) or skill was already loaded
+ *   implicit  — User mentioned the skill by name in their prompt; Claude invoked it
+ *   inferred  — User never mentioned the skill; Claude chose it autonomously
+ *
+ * Examples:
+ *   "/selftune"                    → explicit (slash command)
+ *   "setup selftune"               → implicit (user named the skill)
+ *   "show me the dashboard" → Browser → inferred (user never said "browser")
+ */
+function classifyInvocationType(
+  query: string,
+  skillName: string,
+): "explicit" | "implicit" | "inferred" {
+  const trimmed = query.trim();
+  const skillLower = skillName.toLowerCase();
+
+  // /selftune or /selftune args
+  if (trimmed.toLowerCase().startsWith(`/${skillLower}`)) return "explicit";
+
+  // <command-name>/selftune</command-name> pattern (skill already loaded)
+  if (trimmed.includes(`<command-name>/${skillLower}</command-name>`)) return "explicit";
+  if (trimmed.includes(`<command-name>${skillLower}</command-name>`)) return "explicit";
+
+  // User mentioned the skill name in their prompt (case-insensitive word boundary)
+  const mentionPattern = new RegExp(
+    `\\b${skillLower.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`,
+    "i",
+  );
+  if (mentionPattern.test(trimmed)) return "implicit";
+
+  // Claude chose this skill entirely on its own
+  return "inferred";
+}
+
+/**
+ * Handle Skill tool invocations (e.g., Skill(selftune), Skill(Browser)).
+ * The tool_input contains { skill: "skillName", args?: "..." }.
+ * Classifies as explicit, implicit, or inferred based on user prompt.
+ */
+/**
+ * Detect if the current transcript belongs to a subagent.
+ * Returns the agent type (e.g., "Explore", "Engineer") or "main".
+ */
+function detectAgentType(transcriptPath: string): string {
+  if (!transcriptPath) return "main";
+  try {
+    // Subagent transcripts live under .../subagents/agent-<id>.jsonl
+    if (!/[/\\]subagents[/\\]/.test(transcriptPath)) return "main";
+    const metaPath = transcriptPath.replace(/\.jsonl$/, ".meta.json");
+    if (existsSync(metaPath)) {
+      const meta: unknown = JSON.parse(readFileSync(metaPath, "utf-8"));
+      const agentType =
+        typeof meta === "object" && meta !== null
+          ? (meta as Record<string, unknown>).agentType
+          : undefined;
+      return typeof agentType === "string" ? agentType : "subagent";
+    }
+    return "subagent";
+  } catch {
+    return "main";
+  }
+}
+
+async function processSkillToolUse(
+  payload: PostToolUsePayload,
+  _logPath: string,
+  canonicalLogPath: string,
+  promptStatePath?: string,
+): Promise<SkillUsageRecord | null> {
+  const rawSkill = payload.tool_input?.skill;
+  const skillName = typeof rawSkill === "string" ? rawSkill : null;
+  if (!skillName) return null;
+
+  const transcriptPath = payload.transcript_path ?? "";
+  const sessionId = payload.session_id ?? "unknown";
+
+  const query = getLastUserMessage(transcriptPath);
+  if (!query) return null;
+
+  const invocationType = classifyInvocationType(query, skillName);
+  const invocationIndex = countSkillToolInvocations(transcriptPath, skillName) - 1;
+
+  const record: SkillUsageRecord = {
+    timestamp: new Date().toISOString(),
+    session_id: sessionId,
+    skill_name: skillName,
+    skill_path: "",
+    query,
+    triggered: true,
+    invocation_type: invocationType,
+    source: "claude_code",
+  };
+
+  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({
+    hook_invocation_type: invocationType,
+  });
+  // Detect if this invocation is from a subagent
+  const agentType = detectAgentType(transcriptPath);
+
+  const canonical = buildCanonicalSkillInvocation({
+    ...baseInput,
+    skill_invocation_id: deriveSkillInvocationId(
+      sessionId,
+      skillName,
+      Math.max(invocationIndex, 0),
+    ),
+    occurred_at: record.timestamp,
+    matched_prompt_id: promptId,
+    skill_name: skillName,
+    skill_path: "",
+    invocation_mode,
+    triggered: true,
+    confidence,
+    tool_name: payload.tool_name,
+    agent_type: agentType,
+  });
+
+  // Write unified record to skill_invocations (replaces separate writeSkillUsageToDb call)
+  try {
+    const { writeSkillCheckToDb } = await import("../localdb/direct-write.js");
+    writeSkillCheckToDb({
+      ...canonical,
+      query: record.query,
+      skill_path: record.skill_path,
+      skill_scope: record.skill_scope,
+      source: record.source,
+    });
+  } catch {
+    /* hooks must never block */
+  }
+
   appendCanonicalRecord(canonical, canonicalLogPath);
 
   return record;
@@ -181,7 +360,7 @@ export function processToolUse(
 if (import.meta.main) {
   try {
     const payload: PostToolUsePayload = JSON.parse(await Bun.stdin.text());
-    processToolUse(payload);
+    await processToolUse(payload);
   } catch {
     // silent — hooks must never block Claude
   }

package/cli/selftune/index.ts

@@ -21,8 +21,10 @@
  *   selftune workflows          — Discover and manage multi-skill workflows
  *   selftune quickstart         — Guided onboarding: init, ingest, status, and suggestions
  *   selftune repair-skill-usage — Rebuild trustworthy skill usage from transcripts
+ *   selftune export             — Export SQLite data to JSONL files
  *   selftune export-canonical   — Export canonical telemetry for downstream ingestion
  *   selftune telemetry          — Manage anonymous usage analytics (status, enable, disable)
+ *   selftune alpha <subcommand> — Alpha program management (upload)
  *   selftune hook <name>        — Run a hook by name (prompt-log, session-stop, etc.)
  */
 
@@ -53,7 +55,9 @@ Commands:
   workflows          Discover and manage multi-skill workflows
   quickstart         Guided onboarding: init, ingest, status, and suggestions
   repair-skill-usage Rebuild trustworthy skill usage from transcripts
+  export             Export SQLite data to JSONL files
   export-canonical   Export canonical telemetry for downstream ingestion
+  alpha <subcommand> Alpha program management (upload)
   telemetry          Manage anonymous usage analytics (status, enable, disable)
   hook <name>        Run a hook by name (prompt-log, session-stop, etc.)
 
@@ -68,6 +72,12 @@ if (command && command !== "--help" && command !== "-h") {
     .catch(() => {});
 }
 
+// Auto-update check (skip for hooks — they must be fast — and --help)
+if (command && command !== "hook" && command !== "--help" && command !== "-h") {
+  const { autoUpdate } = await import("./auto-update.js");
+  await autoUpdate();
+}
+
 if (!command) {
   // Show status by default — same as `selftune status`
   const { cliMain: statusMain } = await import("./status.js");
@@ -263,7 +273,6 @@ Run 'selftune eval <action> --help' for action-specific options.`);
           process.exit(0);
         }
         const { parseArgs } = await import("node:util");
-        const { readJsonl } = await import("./utils/jsonl.js");
         const { TELEMETRY_LOG } = await import("./constants.js");
         const { analyzeComposability } = await import("./eval/composability.js");
         let values: ReturnType<typeof parseArgs>["values"];
@@ -287,7 +296,22 @@ Run 'selftune eval <action> --help' for action-specific options.`);
           process.exit(1);
         }
         const logPath = values["telemetry-log"] ?? TELEMETRY_LOG;
-        const telemetry = readJsonl(logPath);
+        let telemetry: unknown[];
+        if (logPath === TELEMETRY_LOG) {
+          try {
+            const { getDb } = await import("./localdb/db.js");
+            const { querySessionTelemetry } = await import("./localdb/queries.js");
+            const db = getDb();
+            telemetry = querySessionTelemetry(db);
+          } catch {
+            // DB unavailable — fall back to JSONL
+            const { readJsonl } = await import("./utils/jsonl.js");
+            telemetry = readJsonl(logPath);
+          }
+        } else {
+          const { readJsonl } = await import("./utils/jsonl.js");
+          telemetry = readJsonl(logPath);
+        }
         const rawWindow = values.window as string | undefined;
         if (rawWindow !== undefined && !/^[1-9]\d*$/.test(rawWindow)) {
           console.error("Invalid --window value. Use a positive integer number of days.");
@@ -458,6 +482,67 @@ Run 'selftune cron <subcommand> --help' for subcommand-specific options.`);
     cliMain();
     break;
   }
+  case "export": {
+    const { parseArgs } = await import("node:util");
+    let values: ReturnType<typeof parseArgs>["values"];
+    let positionals: string[];
+    try {
+      ({ values, positionals } = parseArgs({
+        options: {
+          output: { type: "string", short: "o" },
+          since: { type: "string" },
+          help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: true,
+        strict: true,
+      }));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Invalid arguments: ${message}`);
+      console.error("Run 'selftune export --help' for usage.");
+      process.exit(1);
+    }
+    if (values.help) {
+      console.log(`selftune export — Export SQLite data to JSONL files
+
+Usage:
+  selftune export [tables...] [options]
+
+Tables (default: all):
+  telemetry    Session telemetry records
+  skills       Skill usage records
+  queries      Query log entries
+  audit        Evolution audit trail
+  evidence     Evolution evidence trail
+  signals      Improvement signals
+  orchestrate  Orchestrate run log
+
+Options:
+  -o, --output <dir>   Output directory (default: current directory)
+  --since <date>       Only export records after this date (ISO 8601)
+  -h, --help           Show this help`);
+      process.exit(0);
+    }
+    const { exportToJsonl } = await import("./export.js");
+    const outputDir = (values.output as string | undefined) ?? process.cwd();
+    const since = values.since as string | undefined;
+    const tables = positionals.length > 0 ? positionals : undefined;
+    try {
+      const result = exportToJsonl({ outputDir, since, tables });
+      console.log(
+        `Exported ${result.records} records to ${result.files.length} files in ${outputDir}`,
+      );
+      for (const file of result.files) {
+        console.log(`  ${file}`);
+      }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`Export failed: ${message}`);
+      console.error("Ensure the SQLite database exists. Run 'selftune sync' first if needed.");
+      process.exit(1);
+    }
+    break;
+  }
   case "export-canonical": {
     const { cliMain } = await import("./canonical-export.js");
     cliMain();
@@ -468,6 +553,193 @@ Run 'selftune cron <subcommand> --help' for subcommand-specific options.`);
     await cliMain();
     break;
   }
+  case "alpha": {
+    const sub = process.argv[2];
+    if (!sub || sub === "--help" || sub === "-h") {
+      console.log(`selftune alpha — Alpha program management
+
+Usage:
+  selftune alpha <subcommand> [options]
+
+Subcommands:
+  upload        Run a manual alpha data upload cycle
+  relink        Re-authenticate with the cloud (revokes old key, issues new one)
+
+Run 'selftune alpha <subcommand> --help' for subcommand-specific options.`);
+      process.exit(0);
+    }
+    process.argv = [process.argv[0], process.argv[1], ...process.argv.slice(3)];
+    switch (sub) {
+      case "upload": {
+        const { parseArgs } = await import("node:util");
+        let values: ReturnType<typeof parseArgs>["values"];
+        try {
+          ({ values } = parseArgs({
+            options: {
+              "dry-run": { type: "boolean", default: false },
+              help: { type: "boolean", short: "h", default: false },
+            },
+            strict: true,
+          }));
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          console.error(`Invalid arguments: ${message}`);
+          process.exit(1);
+        }
+        if (values.help) {
+          console.log(`selftune alpha upload — Run a manual alpha data upload cycle
+
+Usage:
+  selftune alpha upload [--dry-run]
+
+Options:
+  --dry-run   Log what would be uploaded without sending
+  -h, --help  Show this help message
+
+Output:
+  JSON summary: { enrolled, prepared, sent, failed, skipped, guidance? }`);
+          process.exit(0);
+        }
+
+        const { SELFTUNE_CONFIG_PATH } = await import("./constants.js");
+        const { getAlphaGuidance } = await import("./agent-guidance.js");
+        const { readAlphaIdentity } = await import("./alpha-identity.js");
+        const { getDb } = await import("./localdb/db.js");
+        const { runUploadCycle } = await import("./alpha-upload/index.js");
+        const { getSelftuneVersion, readConfiguredAgentType } = await import(
+          "./utils/selftune-meta.js"
+        );
+
+        const identity = readAlphaIdentity(SELFTUNE_CONFIG_PATH);
+        if (!identity?.enrolled) {
+          const guidance = getAlphaGuidance(identity);
+          console.log(
+            JSON.stringify(
+              {
+                enrolled: false,
+                prepared: 0,
+                sent: 0,
+                failed: 0,
+                skipped: 0,
+                guidance,
+              },
+              null,
+              2,
+            ),
+          );
+          console.error(`[alpha upload] ${guidance.message}`);
+          console.error(`[alpha upload] Next: ${guidance.next_command}`);
+          process.exit(1);
+        }
+
+        if (!identity.user_id?.trim() || !identity.api_key?.trim()) {
+          const guidance = getAlphaGuidance(identity);
+          console.log(
+            JSON.stringify(
+              {
+                enrolled: true,
+                prepared: 0,
+                sent: 0,
+                failed: 0,
+                skipped: 0,
+                guidance,
+              },
+              null,
+              2,
+            ),
+          );
+          console.error(`[alpha upload] ${guidance.message}`);
+          console.error(`[alpha upload] Next: ${guidance.next_command}`);
+          process.exit(1);
+        }
+
+        const db = getDb();
+
+        const result = await runUploadCycle(db, {
+          enrolled: true,
+          userId: identity.user_id,
+          agentType: readConfiguredAgentType(SELFTUNE_CONFIG_PATH, "unknown"),
+          selftuneVersion: getSelftuneVersion(),
+          dryRun: values["dry-run"] ?? false,
+          apiKey: identity.api_key,
+        });
+
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(result.failed > 0 ? 1 : 0);
+        break;
+      }
+      case "relink": {
+        const { SELFTUNE_CONFIG_PATH } = await import("./constants.js");
+        const { readAlphaIdentity, writeAlphaIdentity, generateUserId } = await import(
+          "./alpha-identity.js"
+        );
+        const { requestDeviceCode, pollDeviceCode } = await import("./auth/device-code.js");
+        const { chmodSync } = await import("node:fs");
+
+        const existingIdentity = readAlphaIdentity(SELFTUNE_CONFIG_PATH);
+        process.stderr.write("[alpha relink] Starting device-code authentication flow...\n");
+
+        const grant = await requestDeviceCode();
+
+        console.log(
+          JSON.stringify({
+            level: "info",
+            code: "device_code_issued",
+            verification_url: grant.verification_url,
+            user_code: grant.user_code,
+            expires_in: grant.expires_in,
+            message: `Open ${grant.verification_url} and enter code: ${grant.user_code}`,
+          }),
+        );
+
+        // Try to open browser
+        try {
+          const url = `${grant.verification_url}?code=${grant.user_code}`;
+          Bun.spawn(["open", url], { stdout: "ignore", stderr: "ignore" });
+          process.stderr.write("[alpha relink] Browser opened. Waiting for approval...\n");
+        } catch {
+          process.stderr.write(
+            "[alpha relink] Could not open browser. Visit the URL above manually.\n",
+          );
+        }
+
+        process.stderr.write("[alpha relink] Polling");
+        const result = await pollDeviceCode(grant.device_code, grant.interval, grant.expires_in);
+        process.stderr.write("\n[alpha relink] Approved!\n");
+
+        const updatedIdentity = {
+          enrolled: true,
+          user_id: existingIdentity?.user_id ?? generateUserId(),
+          cloud_user_id: result.cloud_user_id,
+          cloud_org_id: result.org_id,
+          email: existingIdentity?.email,
+          display_name: existingIdentity?.display_name,
+          consent_timestamp: new Date().toISOString(),
+          api_key: result.api_key,
+        };
+
+        writeAlphaIdentity(SELFTUNE_CONFIG_PATH, updatedIdentity);
+        chmodSync(SELFTUNE_CONFIG_PATH, 0o600);
+
+        console.log(
+          JSON.stringify({
+            level: "info",
+            code: "alpha_relinked",
+            replaced_existing_key: Boolean(existingIdentity?.api_key),
+            cloud_user_id: result.cloud_user_id,
+            message: "Successfully relinked. Old key revoked by cloud during approval.",
+          }),
+        );
+        break;
+      }
+      default:
+        console.error(
+          `Unknown alpha subcommand: ${sub}\nRun 'selftune alpha --help' for available subcommands.`,
+        );
+        process.exit(1);
+    }
+    break;
+  }
   case "telemetry": {
     const { cliMain } = await import("./analytics.js");
     await cliMain();