selftune 0.2.22 → 0.2.24

package/cli/selftune/adapters/pi/hook.ts

@@ -0,0 +1,273 @@
+#!/usr/bin/env bun
+/**
+ * Pi hook adapter for selftune.
+ *
+ * Reads Pi hook payloads from stdin and delegates to shared selftune hook logic.
+ * Pi extensions emit events for tool calls, tool results, and session lifecycle.
+ *
+ * Usage: echo '$HOOK_PAYLOAD' | selftune pi hook
+ *
+ * Event routing:
+ *   tool_call        -> skill-change-guard + evolution-guard (PreToolUse)
+ *   tool_result      -> skill-eval (processToolUse) + commit-track (processCommitTrack)
+ *   message (user)   -> prompt-log (processPrompt) + auto-activate
+ *   session_shutdown -> session-stop (processSessionStop)
+ *
+ * Fail-open: any unhandled error -> exit 0, never crash the host agent.
+ */
+
+import type {
+  PostToolUsePayload,
+  PreToolUsePayload,
+  PromptSubmitPayload,
+  StopPayload,
+} from "../../types.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Pi hook payload — superset of all event fields. */
+export interface PiHookPayload {
+  event_type?: string;
+  session_id?: string;
+  cwd?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_use_id?: string;
+  tool_output?: Record<string, unknown>;
+  prompt?: string;
+  user_prompt?: string;
+  model?: string;
+  provider?: string;
+  last_assistant_message?: string;
+  [key: string]: unknown;
+}
+
+/** Response written to stdout. Empty object = no-op. */
+type HookResponse = Record<string, unknown>;
+
+const EMPTY_RESPONSE: HookResponse = {};
+
+// ---------------------------------------------------------------------------
+// Event handlers (dynamic imports for fast startup)
+// ---------------------------------------------------------------------------
+
+async function handlePromptSubmit(payload: PiHookPayload): Promise<HookResponse> {
+  // 1. Prompt logging
+  try {
+    const { processPrompt } = await import("../../hooks/prompt-log.js");
+    const promptPayload: PromptSubmitPayload = {
+      session_id: payload.session_id,
+      cwd: payload.cwd,
+      prompt: payload.prompt ?? payload.user_prompt,
+      user_prompt: payload.user_prompt ?? payload.prompt,
+      hook_event_name: "UserPromptSubmit",
+    };
+    await processPrompt(promptPayload);
+  } catch {
+    // fail-open
+  }
+
+  // 2. Auto-activate suggestions
+  let response: HookResponse = EMPTY_RESPONSE;
+  try {
+    const { processAutoActivate } = await import("../../hooks/auto-activate.js");
+    const sessionId = payload.session_id ?? "unknown";
+    const suggestions = await processAutoActivate(sessionId);
+    if (suggestions.length > 0) {
+      const context = suggestions.map((s) => `[selftune] Suggestion: ${s}`).join("\n");
+      response = { additionalContext: context };
+    }
+  } catch {
+    // fail-open
+  }
+
+  return response;
+}
+
+async function handlePreToolUse(
+  payload: PiHookPayload,
+): Promise<{ response: HookResponse; exitCode: number }> {
+  const prePayload: PreToolUsePayload = {
+    tool_name: payload.tool_name ?? "",
+    tool_input: payload.tool_input ?? {},
+    tool_use_id: payload.tool_use_id,
+    session_id: payload.session_id,
+    cwd: payload.cwd,
+    hook_event_name: "PreToolUse",
+  };
+
+  let constants:
+    | { EVOLUTION_AUDIT_LOG: string; SELFTUNE_CONFIG_DIR: string; SESSION_STATE_DIR: string }
+    | undefined;
+  try {
+    constants = await import("../../constants.js");
+  } catch {
+    // fail-open
+  }
+
+  // 1. Evolution guard (can block with exit 2)
+  try {
+    if (constants) {
+      const { processEvolutionGuard } = await import("../../hooks/evolution-guard.js");
+      const guardResult = await processEvolutionGuard(prePayload, {
+        auditLogPath: constants.EVOLUTION_AUDIT_LOG,
+        selftuneDir: constants.SELFTUNE_CONFIG_DIR,
+      });
+      if (guardResult) {
+        process.stderr.write(`${guardResult.message}\n`);
+        return { response: EMPTY_RESPONSE, exitCode: guardResult.exitCode };
+      }
+    }
+  } catch {
+    // fail-open
+  }
+
+  // 2. Skill change guard (advisory only, never blocks)
+  try {
+    if (constants) {
+      const { processPreToolUse } = await import("../../hooks/skill-change-guard.js");
+      const sessionId = payload.session_id ?? "unknown";
+      const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+      const statePath = `${constants.SESSION_STATE_DIR}/guard-state-${safe}.json`;
+      const suggestion = processPreToolUse(prePayload, statePath);
+      if (suggestion) {
+        process.stderr.write(`[selftune] Suggestion: ${suggestion}\n`);
+      }
+    }
+  } catch {
+    // fail-open
+  }
+
+  return { response: EMPTY_RESPONSE, exitCode: 0 };
+}
+
+async function handlePostToolUse(payload: PiHookPayload): Promise<HookResponse> {
+  const postPayload: PostToolUsePayload = {
+    tool_name: payload.tool_name ?? "",
+    tool_input: payload.tool_input ?? {},
+    tool_use_id: payload.tool_use_id,
+    tool_response: payload.tool_output,
+    session_id: payload.session_id,
+    cwd: payload.cwd,
+    hook_event_name: "PostToolUse",
+  };
+
+  // 1. Skill eval (Read/Skill tool usage tracking)
+  try {
+    const { processToolUse } = await import("../../hooks/skill-eval.js");
+    await processToolUse(postPayload);
+  } catch {
+    // fail-open
+  }
+
+  // 2. Commit tracking (git commit detection in Bash output)
+  try {
+    const { processCommitTrack } = await import("../../hooks/commit-track.js");
+    await processCommitTrack(postPayload);
+  } catch {
+    // fail-open
+  }
+
+  return EMPTY_RESPONSE;
+}
+
+async function handleSessionEnd(payload: PiHookPayload): Promise<HookResponse> {
+  try {
+    const { processSessionStop } = await import("../../hooks/session-stop.js");
+    const stopPayload: StopPayload = {
+      session_id: payload.session_id,
+      cwd: payload.cwd,
+      last_assistant_message:
+        typeof payload.last_assistant_message === "string"
+          ? payload.last_assistant_message
+          : undefined,
+      hook_event_name: "Stop",
+    };
+    await processSessionStop(stopPayload);
+  } catch {
+    // fail-open
+  }
+  return EMPTY_RESPONSE;
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+function writeResponseAndExit(response: HookResponse, code: number): void {
+  const data = JSON.stringify(response);
+  process.stdout.write(data, () => {
+    process.exit(code);
+  });
+}
+
+/**
+ * CLI entry point. Reads stdin, routes to the correct handler, writes response.
+ */
+export async function cliMain(): Promise<void> {
+  let exitCode = 0;
+
+  try {
+    const raw = await Bun.stdin.text();
+
+    // Fast-path: empty stdin -> no-op
+    if (!raw.trim()) {
+      writeResponseAndExit(EMPTY_RESPONSE, 0);
+      return;
+    }
+
+    let payload: PiHookPayload;
+    try {
+      payload = JSON.parse(raw) as PiHookPayload;
+    } catch {
+      writeResponseAndExit(EMPTY_RESPONSE, 0);
+      return;
+    }
+
+    const eventType = typeof payload.event_type === "string" ? payload.event_type : "";
+
+    if (!eventType) {
+      writeResponseAndExit(EMPTY_RESPONSE, 0);
+      return;
+    }
+
+    let response: HookResponse = EMPTY_RESPONSE;
+
+    switch (eventType) {
+      case "message": {
+        response = await handlePromptSubmit(payload);
+        break;
+      }
+      case "tool_call": {
+        const result = await handlePreToolUse(payload);
+        response = result.response;
+        exitCode = result.exitCode;
+        break;
+      }
+      case "tool_result": {
+        response = await handlePostToolUse(payload);
+        break;
+      }
+      case "session_shutdown": {
+        response = await handleSessionEnd(payload);
+        break;
+      }
+      default: {
+        // Unknown event — no-op
+        break;
+      }
+    }
+
+    writeResponseAndExit(response, exitCode);
+  } catch {
+    // Fail-open: never crash
+    writeResponseAndExit(EMPTY_RESPONSE, 0);
+  }
+}
+
+// --- stdin main (only when executed directly, not when imported) ---
+if (import.meta.main) {
+  await cliMain();
+}

package/cli/selftune/adapters/pi/install.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env bun
+/**
+ * Install selftune hooks into Pi coding agent environment.
+ *
+ * Pi supports extensions that hook into its lifecycle. This installer
+ * creates a selftune extension that pipes events to `selftune pi hook`.
+ *
+ * Extension location: ~/.pi/extensions/selftune/
+ *
+ * Events hooked:
+ *   - tool_call        (pre-tool — skill guards, inline)
+ *   - tool_result      (post-tool — skill eval + commit tracking, inline)
+ *   - message          (prompt submit — prompt logging + auto-activate, inline)
+ *   - session_shutdown (session end — session telemetry, background)
+ *
+ * Usage: selftune pi install [--dry-run] [--uninstall]
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PI_DIR = process.env.SELFTUNE_PI_DIR ?? join(homedir(), ".pi");
+const PI_EXTENSIONS_DIR = join(PI_DIR, "extensions", "selftune");
+const MARKER = "# selftune-managed";
+
+// ---------------------------------------------------------------------------
+// Hook script generators
+// ---------------------------------------------------------------------------
+
+/** Build a hook command that prefers SELFTUNE_CLI_PATH, then npx. */
+const HOOK_CMD =
+  'if [ -n "$SELFTUNE_CLI_PATH" ]; then "$SELFTUNE_CLI_PATH" pi hook; else npx selftune pi hook; fi';
+
+function hookScript(eventType: string, inline: boolean): string {
+  if (inline) {
+    // Inline — fast path; finish before Pi moves on.
+    // Capture output and exit code separately to avoid double JSON and preserve guard blocks (exit 2).
+    return `#!/usr/bin/env bash
+${MARKER}
+input=$(cat)
+result=$(echo "$input" | (${HOOK_CMD}) 2>/dev/null)
+rc=$?
+[ -z "$result" ] && result='{}'
+echo "$result"
+exit $rc
+`;
+  }
+
+  // Background — don't block Pi
+  return `#!/usr/bin/env bash
+${MARKER}
+input=$(cat)
+echo "$input" | (${HOOK_CMD}) &>/dev/null &
+echo '{}'
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Hook definitions
+// ---------------------------------------------------------------------------
+
+const HOOKS: Array<{ name: string; description: string; inline: boolean }> = [
+  { name: "tool_call", description: "Pre-tool guards (evolution, skill change)", inline: true },
+  { name: "tool_result", description: "Post-tool eval + commit tracking", inline: true },
+  { name: "message", description: "Prompt logging + auto-activate", inline: true },
+  { name: "session_shutdown", description: "Session telemetry recording", inline: false },
+];
+
+// ---------------------------------------------------------------------------
+// Install
+// ---------------------------------------------------------------------------
+
+function installHooks(dryRun: boolean): void {
+  console.log("Setting up selftune hooks for Pi...");
+  console.log(`Extensions directory: ${PI_EXTENSIONS_DIR}`);
+  console.log("");
+
+  if (!dryRun) {
+    mkdirSync(PI_EXTENSIONS_DIR, { recursive: true });
+  }
+
+  let installed = 0;
+  let skipped = 0;
+
+  for (const hook of HOOKS) {
+    const hookPath = join(PI_EXTENSIONS_DIR, hook.name);
+
+    if (existsSync(hookPath)) {
+      const existing = readFileSync(hookPath, "utf-8");
+      if (existing.includes(MARKER)) {
+        if (dryRun) {
+          console.log(`  Would update: ${hook.name}`);
+        } else {
+          writeFileSync(hookPath, hookScript(hook.name, hook.inline), { mode: 0o755 });
+          chmodSync(hookPath, 0o755);
+          console.log(`  Updated: ${hook.name}`);
+        }
+        installed++;
+      } else {
+        console.log(`  Skipped: ${hook.name} (existing hook not managed by selftune)`);
+        skipped++;
+      }
+    } else {
+      if (dryRun) {
+        console.log(`  Would create: ${hook.name}`);
+      } else {
+        writeFileSync(hookPath, hookScript(hook.name, hook.inline), { mode: 0o755 });
+        console.log(`  Created: ${hook.name}`);
+      }
+      installed++;
+    }
+  }
+
+  console.log("");
+  if (dryRun) {
+    console.log(`Dry run: ${installed} hook(s) would be installed.`);
+  } else if (installed > 0) {
+    console.log(`Installed ${installed} hook(s).`);
+  }
+  if (skipped > 0) {
+    console.log(`Skipped ${skipped} hook(s) with existing non-selftune content.`);
+  }
+  if (!dryRun && installed > 0) {
+    console.log("");
+    if (skipped === 0) {
+      console.log("Pi will now track commits and record session telemetry.");
+    } else {
+      console.log("Partial install: some hooks were skipped. Telemetry may be incomplete.");
+    }
+    console.log("Run `selftune status` to verify setup.");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Uninstall
+// ---------------------------------------------------------------------------
+
+function uninstallHooks(dryRun: boolean): void {
+  console.log("Removing selftune hooks from Pi...");
+  console.log("");
+
+  let removed = 0;
+  let skipped = 0;
+
+  for (const hook of HOOKS) {
+    const hookPath = join(PI_EXTENSIONS_DIR, hook.name);
+
+    if (!existsSync(hookPath)) {
+      console.log(`  Not found: ${hook.name}`);
+      continue;
+    }
+
+    const existing = readFileSync(hookPath, "utf-8");
+    if (!existing.includes(MARKER)) {
+      console.log(`  Skipped: ${hook.name} (not managed by selftune)`);
+      skipped++;
+      continue;
+    }
+
+    if (dryRun) {
+      console.log(`  Would remove: ${hook.name}`);
+    } else {
+      rmSync(hookPath);
+      console.log(`  Removed: ${hook.name}`);
+    }
+    removed++;
+  }
+
+  console.log("");
+  if (dryRun) {
+    console.log(`Dry run: ${removed} hook(s) would be removed.`);
+  } else if (removed > 0) {
+    console.log(`Removed ${removed} hook(s).`);
+  }
+  if (skipped > 0) {
+    console.log(`Skipped ${skipped} hook(s) not managed by selftune.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function cliMain(): Promise<void> {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const uninstall = args.includes("--uninstall");
+
+  if (uninstall) {
+    uninstallHooks(dryRun);
+  } else {
+    installHooks(dryRun);
+  }
+}
+
+// --- stdin main (only when executed directly, not when imported) ---
+if (import.meta.main) {
+  try {
+    await cliMain();
+  } catch (err) {
+    console.error(
+      `[selftune] Pi install failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+}

package/cli/selftune/alpha-upload/build-payloads.ts

@@ -11,7 +11,7 @@
 
 import type { Database } from "bun:sqlite";
 
-import type { CanonicalRecord } from "@selftune/telemetry-contract";
+import type { CanonicalRecord, PushPayloadV2 } from "@selftune/telemetry-contract/types";
 
 import { buildPushPayloadV2 } from "../canonical-export.js";
 import type { EvolutionEvidenceEntry } from "../types.js";
@@ -19,7 +19,7 @@ import type { EvolutionEvidenceEntry } from "../types.js";
 // -- Types --------------------------------------------------------------------
 
 export interface BuildV2Result {
-  payload: Record<string, unknown>;
+  payload: PushPayloadV2 & { content_hashes?: Record<string, string> };
   lastSeq: number;
 }
 
@@ -152,7 +152,7 @@ export function buildV2PushPayload(
     return null;
   }
 
-  const payload = buildPushPayloadV2(
+  const payload: BuildV2Result["payload"] = buildPushPayloadV2(
     canonicalRecords,
     evidenceEntries,
     orchestrateRuns,

package/cli/selftune/alpha-upload/stage-canonical.ts

@@ -68,6 +68,12 @@ export function generateSignalId(record: Record<string, unknown>): string {
   return `sig_${createHash("sha256").update(key).digest("hex").slice(0, 16)}`;
 }
 
+function addOptional(record: Record<string, unknown>, key: string, value: unknown): void {
+  if (value !== undefined && value !== null) {
+    record[key] = value;
+  }
+}
+
 /**
  * Enrich a raw parsed record: if it is an execution_fact missing
  * execution_fact_id, inject a deterministic one.
@@ -128,7 +134,7 @@ function extractRecordId(record: CanonicalRecord): string {
  * Extract session_id from a canonical record (if the record has one).
  */
 function extractSessionId(record: CanonicalRecord): string | null {
-  if ("session_id" in record) return record.session_id;
+  if ("session_id" in record && typeof record.session_id === "string") return record.session_id;
   return null;
 }
 
@@ -136,7 +142,7 @@ function extractSessionId(record: CanonicalRecord): string | null {
  * Extract prompt_id from a canonical record (if the record has one).
  */
 function extractPromptId(record: CanonicalRecord): string | null {
-  if ("prompt_id" in record) return record.prompt_id;
+  if ("prompt_id" in record && typeof record.prompt_id === "string") return record.prompt_id;
   return null;
 }
 
@@ -213,19 +219,19 @@ export function stageCanonicalRecords(db: Database, logPath: string = CANONICAL_
     for (const entry of evidence) {
       const evidenceRecord: Record<string, unknown> = {
         skill_name: entry.skill_name,
-        skill_path: entry.skill_path,
-        proposal_id: entry.proposal_id,
         target: entry.target,
         stage: entry.stage,
-        rationale: entry.rationale,
-        confidence: entry.confidence,
-        details: entry.details,
-        original_text: entry.original_text,
-        proposed_text: entry.proposed_text,
-        eval_set_json: entry.eval_set,
-        validation_json: entry.validation,
         timestamp: entry.timestamp,
       };
+      addOptional(evidenceRecord, "skill_path", entry.skill_path);
+      addOptional(evidenceRecord, "proposal_id", entry.proposal_id);
+      addOptional(evidenceRecord, "rationale", entry.rationale);
+      addOptional(evidenceRecord, "confidence", entry.confidence);
+      addOptional(evidenceRecord, "details", entry.details);
+      addOptional(evidenceRecord, "original_text", entry.original_text);
+      addOptional(evidenceRecord, "proposed_text", entry.proposed_text);
+      addOptional(evidenceRecord, "eval_set_json", entry.eval_set);
+      addOptional(evidenceRecord, "validation_json", entry.validation);
       // Generate deterministic evidence_id if not already present
       const evidenceId = generateEvidenceId(evidenceRecord);
       evidenceRecord.evidence_id = evidenceId;