harnery 0.32.0 → 0.34.0

package/src/core/hooks/effects/image-capture.ts

@@ -1,23 +1,13 @@
 /**
- * Image-feed capture: a non-coordination side effect fired from the normalized
- * `agent-hook` tool handlers (see effects/index.ts for the family rationale).
+ * Privacy-safe image artifact capture for normalized tool hooks.
  *
- * When an agent VIEWS an image (Read tool on a `.png`/`.jpg`/…) or PRODUCES one
- * (a Bash command writes an image file via `harn browse`, `harn image`, `--diff`, …),
- * we content-address the bytes into `.harnery/images/<sha256>.<ext>` (dedup:
- * identical bytes collapse to one blob) and emit an `image.captured` event into
- * the canonical stream. The web image feed (`/images`) groups those events by
- * hash and streams them live over the existing SSE infra.
- *
- * Why this lives at the hook layer: it's the single adapter-agnostic chokepoint
- * that sees every tool call across Claude Code / Cursor / Codex with the full
- * `tool_input` (file paths) and `tool_response`. No per-command code needed.
- *
- * Everything here is best-effort and MUST NOT throw; callers wrap it in
- * try/catch + logError, matching every other effect.
+ * Image bytes are content-addressed under `.harnery/images/`. The canonical V3
+ * ledger receives an `artifact.observed` record after the source tool event is
+ * durable, so the web feed can recover provenance without retaining command,
+ * output, intent, or absolute paths.
  */
 
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import {
   existsSync,
   mkdirSync,
@@ -28,185 +18,139 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { buildEventV3 } from "../../events/v3/builder.ts";
+import type { EventV3 } from "../../events/v3/contract.ts";
+import { writeEventV3 } from "../../events/v3/writer.ts";
 import type { ParsedPayload } from "../adapter/parse.ts";
-import { emit } from "../events/emit.ts";
-import type { Adapter } from "../events/schema.ts";
 
-/** Raster + vector image extensions the feed accepts. PDF is intentionally
- * excluded: book renders aren't an "image feed" and don't thumbnail inline. */
 const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "svg"]);
-
-/** Skip hashing files larger than this; screenshots are tens of KB; a huge
- * file mentioned in passing isn't worth the read. */
+const MEDIA_TYPES: Record<string, string> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  bmp: "image/bmp",
+  svg: "image/svg+xml",
+};
 const MAX_CAPTURE_BYTES = 25 * 1024 * 1024;
-
-/** A produced image must have been written within this window of the command
- * finishing, otherwise a path merely *mentioned* in output (an old baseline,
- * a doc reference) would be captured. Viewed images skip this gate. */
 const PRODUCED_MTIME_WINDOW_MS = 120_000;
+const IMAGE_PATH_RE = /[\w./~@:+-]+\.(?:png|jpe?g|gif|webp|bmp|svg)\b/gi;
 
-/** Matches image-ish paths in a command string or its output. Deliberately
- * permissive on the path body (`~`, `@`, `.`, `-`, `/`); existence + ext + the
- * mtime gate do the real filtering. */
-const IMAGE_PATH_RE = /[\w./~@+-]+\.(?:png|jpe?g|gif|webp|bmp|svg)\b/gi;
-
-export interface CaptureContext {
-  eventType: "tool.pre_use" | "tool.post_use";
-  /** The built event data (tool_name, tool_input string, intent, tool_use_id). */
-  data: Record<string, unknown>;
-  /** The full parsed payload, used for the un-clamped command + tool_response. */
-  payload: ParsedPayload | null;
-  instanceId: string;
-  sessionId: string;
-  adapter: Adapter;
+export interface CapturedImageArtifact {
+  hash: string;
+  ext: string;
+  bytes: number;
+  role: "viewed" | "produced";
+  workspace_path?: string;
 }
 
 interface Candidate {
-  path: string; // resolved absolute path
-  role: "viewed" | "produced";
-  intent?: string;
-  commandHead?: string;
+  path: string;
+  role: CapturedImageArtifact["role"];
   requireRecentMtime: boolean;
 }
 
-/**
- * Inspect one tool event for image references and capture any that resolve to
- * a real image on disk. Emits zero or more `image.captured` events.
- */
-export function captureImages(coordRoot: string, ctx: CaptureContext): void {
-  const imagesDir = join(coordRoot, ".harnery", "images");
-  const cwd = resolveCwd(ctx.payload);
-  const toolName = String(ctx.data.tool_name ?? "");
-
-  const candidates =
-    ctx.eventType === "tool.pre_use"
-      ? collectViewed(toolName, ctx.data, cwd)
-      : collectProduced(toolName, ctx.payload, cwd);
-
-  if (candidates.length === 0) return;
-
-  for (const cand of candidates) {
-    // Never re-capture our own blob store (would loop on Reads of the gallery).
-    if (cand.path.startsWith(`${imagesDir}/`)) continue;
-    const captured = captureOne(imagesDir, cand);
-    if (!captured) continue;
-    emit(coordRoot, {
-      event_type: "image.captured",
-      instance_id: ctx.instanceId,
-      session_id: ctx.sessionId,
-      adapter: ctx.adapter,
-      data: {
-        hash: captured.hash,
-        ext: captured.ext,
-        bytes: captured.bytes,
-        role: cand.role,
-        source_path: canonicalize(coordRoot, cand.path),
-        tool_name: toolName,
-        tool_use_id: ctx.data.tool_use_id as string | undefined,
-        ...(cand.intent ? { intent: cand.intent } : {}),
-        ...(cand.commandHead ? { command_head: cand.commandHead } : {}),
-      },
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    } as Parameters<typeof emit>[1]);
-  }
-}
-
-/** Read tool → the file_path it's about to show (the "agent saw this" signal). */
-function collectViewed(toolName: string, data: Record<string, unknown>, cwd: string): Candidate[] {
-  if (toolName !== "Read") return [];
-  const input = parseToolInput(data.tool_input);
-  const filePath = input?.file_path;
-  if (typeof filePath !== "string" || !filePath) return [];
-  if (!hasImageExt(filePath)) return [];
-  return [
-    {
-      path: toAbsolute(filePath, cwd),
-      role: "viewed",
-      intent: typeof data.intent === "string" ? data.intent : undefined,
-      requireRecentMtime: false,
-    },
-  ];
-}
-
-/** Bash tool → scan the command + its output for freshly-written image files. */
-function collectProduced(
-  toolName: string,
+/** Copy every qualifying image referenced by one tool hook into the blob store. */
+export function captureImages(
+  coordRoot: string,
+  eventType: "tool.requested" | "tool.completed",
   payload: ParsedPayload | null,
-  cwd: string,
-): Candidate[] {
-  if (toolName !== "Bash") return [];
-  const command = bashCommand(payload);
-  const responseText = stringifyResponse(payload?.tool_response);
-  const commandHead = command ? command.slice(0, 120) : undefined;
-
+): CapturedImageArtifact[] {
+  const images = join(coordRoot, ".harnery", "images");
+  const cwd = payload?.cwd ? resolve(payload.cwd) : process.cwd();
+  const toolName = payload?.tool_name ?? "";
+  const candidates =
+    eventType === "tool.requested"
+      ? collectViewed(toolName, payload?.tool_input, cwd)
+      : collectProduced(toolName, payload, cwd);
+  const captured: CapturedImageArtifact[] = [];
   const seen = new Set<string>();
-  const out: Candidate[] = [];
-  for (const text of [command, responseText]) {
-    if (!text) continue;
-    for (const m of text.matchAll(IMAGE_PATH_RE)) {
-      const raw = m[0];
-      const abs = toAbsolute(raw, cwd);
-      if (seen.has(abs)) continue;
-      seen.add(abs);
-      out.push({ path: abs, role: "produced", commandHead, requireRecentMtime: true });
-    }
-  }
-  return out;
-}
 
-interface CapturedBlob {
-  hash: string;
-  ext: string;
-  bytes: number;
+  for (const candidate of candidates) {
+    if (candidate.path.startsWith(`${images}${sep}`)) continue;
+    const blob = captureOne(images, candidate);
+    if (!blob) continue;
+    const dedupeKey = `${blob.hash}:${candidate.role}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    const workspacePath = safeWorkspacePath(coordRoot, candidate.path);
+    captured.push({
+      ...blob,
+      role: candidate.role,
+      ...(workspacePath ? { workspace_path: workspacePath } : {}),
+    });
+  }
+  return captured;
 }
 
 /**
- * Validate the candidate on disk, hash it, and copy into the content-addressed
- * store (skipping the copy when the blob already exists). Returns null when the
- * candidate doesn't qualify.
+ * Emit content-addressed image references as canonical V3 artifact events.
+ * Each observation uses a one-event producer boot, which preserves independent
+ * producer sequence continuity while the ledger writer serializes appends.
  */
-function captureOne(imagesDir: string, cand: Candidate): CapturedBlob | null {
-  let st: ReturnType<typeof statSync>;
-  try {
-    st = statSync(cand.path);
-  } catch {
-    return null; // path doesn't exist (common for "produced" false-positives)
-  }
-  if (!st.isFile() || st.size === 0 || st.size > MAX_CAPTURE_BYTES) return null;
-  if (cand.requireRecentMtime && Date.now() - st.mtimeMs > PRODUCED_MTIME_WINDOW_MS) {
-    return null; // mentioned but not freshly produced by this command
+export function recordImageArtifactsV3(
+  coordRoot: string,
+  sourceEvent: EventV3,
+  artifacts: readonly CapturedImageArtifact[],
+): void {
+  if (!("generation_id" in sourceEvent.scope) || !sourceEvent.attestation_id) return;
+  for (const artifact of artifacts) {
+    writeEventV3(coordRoot, buildImageArtifactEventV3(sourceEvent, artifact));
   }
-  const ext = extOf(cand.path);
-  if (!ext || !IMAGE_EXTS.has(ext)) return null;
+}
 
-  let bytes: Buffer;
-  try {
-    bytes = readFileSync(cand.path);
-  } catch {
-    return null;
-  }
-  const hash = createHash("sha256").update(bytes).digest("hex");
-  const dest = join(imagesDir, `${hash}.${ext}`);
-  if (!existsSync(dest)) {
-    try {
-      mkdirSync(imagesDir, { recursive: true });
-      const tmp = `${dest}.tmp.${process.pid}`;
-      writeFileSync(tmp, bytes);
-      renameSync(tmp, dest);
-    } catch {
-      return null; // couldn't store, don't emit a dangling event
-    }
+export function buildImageArtifactEventV3(
+  sourceEvent: EventV3,
+  artifact: CapturedImageArtifact,
+): EventV3 {
+  if (!("generation_id" in sourceEvent.scope) || !sourceEvent.attestation_id) {
+    throw new Error("image artifacts require a generation-scoped source event");
   }
-  return { hash, ext, bytes: st.size };
+  return buildEventV3("artifact.observed", {
+    producer: {
+      producer_id: "prd_agent-hook-image-capture",
+      boot_id: `boot_${randomUUID()}`,
+      sequence: 1,
+      component: "agent-hook",
+      build_id: sourceEvent.producer.build_id,
+      platform: sourceEvent.producer.platform,
+      ...(sourceEvent.producer.bridge ? { bridge: sourceEvent.producer.bridge } : {}),
+    },
+    scope: {
+      root_id: sourceEvent.scope.root_id,
+      instance_id: sourceEvent.scope.instance_id,
+      session_id: sourceEvent.scope.session_id,
+      generation_id: sourceEvent.scope.generation_id,
+      ...(sourceEvent.scope.run_id ? { run_id: sourceEvent.scope.run_id } : {}),
+      ...(sourceEvent.scope.workflow_id ? { workflow_id: sourceEvent.scope.workflow_id } : {}),
+      ...(sourceEvent.scope.workflow_agent_id
+        ? { workflow_agent_id: sourceEvent.scope.workflow_agent_id }
+        : {}),
+    },
+    attestation_id: sourceEvent.attestation_id as `att_${string}`,
+    links: { caused_by: [sourceEvent.event_id] },
+    provenance: {
+      ...sourceEvent.provenance,
+      attestation: "derived",
+      confidence: "high",
+    },
+    payload: {
+      artifact: {
+        artifact_id: `art_${artifact.hash}`,
+        kind: "image",
+        media_type: MEDIA_TYPES[artifact.ext] ?? "image/png",
+        bytes: artifact.bytes,
+        retention_class: "bounded_local",
+        ...(artifact.workspace_path ? { workspace_path: artifact.workspace_path } : {}),
+      },
+      operation: artifact.role === "viewed" ? "viewed" : "created",
+    },
+  });
 }
 
-/**
- * Prune `.harnery/images/` past a size cap (default 2 GB) and an age cap
- * (default 30 days), oldest-mtime-first. Fired on session.start next to
- * journalJanitor. Pure-fs, fail-soft. Orphaned `image.captured` events whose
- * blob was pruned render as an "expired" placeholder in the gallery.
- */
+/** Prune the bounded blob store by age and total size, oldest first. */
 export function imageJanitor(coordRoot: string): void {
   try {
     const dir = join(coordRoot, ".harnery", "images");
@@ -214,117 +158,163 @@ export function imageJanitor(coordRoot: string): void {
     const maxBytes = envInt("HARNERY_IMAGES_MAX_BYTES", 2 * 1024 * 1024 * 1024);
     const maxAgeMs = envInt("HARNERY_IMAGES_MAX_AGE_DAYS", 30) * 24 * 60 * 60 * 1000;
     const now = Date.now();
+    const entries: Array<{ path: string; size: number; mtimeMs: number }> = [];
 
-    type Entry = { path: string; size: number; mtimeMs: number };
-    const entries: Entry[] = [];
     for (const name of readdirSync(dir)) {
       if (name.endsWith(".tmp") || name.includes(".tmp.")) {
-        // Orphaned temp from a crashed copy; sweep it.
         rmSync(join(dir, name), { force: true });
         continue;
       }
       const full = join(dir, name);
-      let st: ReturnType<typeof statSync>;
       try {
-        st = statSync(full);
+        const stat = statSync(full);
+        if (stat.isFile()) entries.push({ path: full, size: stat.size, mtimeMs: stat.mtimeMs });
       } catch {
-        continue;
+        // A concurrent cleanup or write can make one entry disappear.
       }
-      if (!st.isFile()) continue;
-      entries.push({ path: full, size: st.size, mtimeMs: st.mtimeMs });
     }
 
-    // Age cap.
     let total = 0;
-    const survivors: Entry[] = [];
-    for (const e of entries) {
-      if (now - e.mtimeMs > maxAgeMs) {
-        rmSync(e.path, { force: true });
-        continue;
+    const survivors: typeof entries = [];
+    for (const entry of entries) {
+      if (now - entry.mtimeMs > maxAgeMs) {
+        rmSync(entry.path, { force: true });
+      } else {
+        total += entry.size;
+        survivors.push(entry);
       }
-      total += e.size;
-      survivors.push(e);
     }
-
-    // Size cap: drop oldest first until under.
-    if (total > maxBytes) {
-      survivors.sort((a, b) => a.mtimeMs - b.mtimeMs);
-      for (const e of survivors) {
-        if (total <= maxBytes) break;
-        rmSync(e.path, { force: true });
-        total -= e.size;
-      }
+    survivors.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    for (const entry of survivors) {
+      if (total <= maxBytes) break;
+      rmSync(entry.path, { force: true });
+      total -= entry.size;
     }
   } catch {
-    // best-effort
+    // Hook effects are always best-effort.
   }
 }
 
-/* ── helpers ─────────────────────────────────────────────────────────────── */
+function collectViewed(toolName: string, toolInput: unknown, cwd: string): Candidate[] {
+  const name = normalizedToolName(toolName);
+  if (name !== "read" && name !== "view_image" && name !== "image") return [];
+  const input = objectInput(toolInput);
+  const filePath = input?.file_path ?? input?.path ?? input?.image_path;
+  if (typeof filePath !== "string" || !hasImageExt(filePath)) return [];
+  return [{ path: toAbsolute(filePath, cwd), role: "viewed", requireRecentMtime: false }];
+}
 
-function envInt(name: string, fallback: number): number {
-  const v = process.env[name];
-  if (!v) return fallback;
-  const n = Number(v);
-  return Number.isFinite(n) && n > 0 ? n : fallback;
+function collectProduced(
+  toolName: string,
+  payload: ParsedPayload | null,
+  cwd: string,
+): Candidate[] {
+  const name = normalizedToolName(toolName);
+  const producerTools = new Set([
+    "bash",
+    "shell",
+    "exec_command",
+    "imagegen",
+    "image_gen",
+    "browse",
+    "browse_ai",
+    "screenshot",
+  ]);
+  if (!producerTools.has(name)) return [];
+  const input = objectInput(payload?.tool_input);
+  const command = [input?.command, input?.cmd].find((value) => typeof value === "string") ?? "";
+  const response = stringify(payload?.tool_response).slice(0, 2_000_000);
+  const seen = new Set<string>();
+  const out: Candidate[] = [];
+  for (const text of [String(command), response]) {
+    for (const match of text.matchAll(IMAGE_PATH_RE)) {
+      const absolute = toAbsolute(match[0], cwd);
+      if (seen.has(absolute)) continue;
+      seen.add(absolute);
+      out.push({ path: absolute, role: "produced", requireRecentMtime: true });
+    }
+  }
+  return out;
 }
 
-function parseToolInput(raw: unknown): Record<string, unknown> | null {
-  if (typeof raw !== "string") return null;
+function captureOne(
+  imagesDir: string,
+  candidate: Candidate,
+): Omit<CapturedImageArtifact, "role" | "workspace_path"> | null {
   try {
-    const parsed = JSON.parse(raw) as Record<string, unknown>;
-    return parsed && typeof parsed === "object" ? parsed : null;
+    const stat = statSync(candidate.path);
+    if (!stat.isFile() || stat.size === 0 || stat.size > MAX_CAPTURE_BYTES) return null;
+    if (candidate.requireRecentMtime && Date.now() - stat.mtimeMs > PRODUCED_MTIME_WINDOW_MS) {
+      return null;
+    }
+    const ext = extOf(candidate.path);
+    if (!IMAGE_EXTS.has(ext)) return null;
+    const bytes = readFileSync(candidate.path);
+    const hash = createHash("sha256").update(bytes).digest("hex");
+    const destination = join(imagesDir, `${hash}.${ext}`);
+    if (!existsSync(destination)) {
+      mkdirSync(imagesDir, { recursive: true });
+      const temporary = `${destination}.tmp.${process.pid}.${randomUUID().slice(0, 8)}`;
+      writeFileSync(temporary, bytes, { mode: 0o600 });
+      renameSync(temporary, destination);
+    }
+    return { hash, ext, bytes: stat.size };
   } catch {
     return null;
   }
 }
 
-/** The un-clamped Bash command from the raw payload (falls back to clamped). */
-function bashCommand(payload: ParsedPayload | null): string {
-  const ti = payload?.raw?.tool_input as Record<string, unknown> | undefined;
-  const cmd = ti?.command;
-  return typeof cmd === "string" ? cmd : "";
+function normalizedToolName(value: string): string {
+  return (value.split(/[.:/]/).pop() ?? value).toLowerCase().replaceAll("-", "_");
 }
 
-function stringifyResponse(value: unknown): string {
-  if (value == null) return "";
+function objectInput(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value !== "string") return null;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function stringify(value: unknown): string {
   if (typeof value === "string") return value;
   try {
-    return JSON.stringify(value);
+    return JSON.stringify(value ?? "");
   } catch {
     return "";
   }
 }
 
-function resolveCwd(payload: ParsedPayload | null): string {
-  const raw = payload?.raw as Record<string, unknown> | undefined;
-  const cwd = raw?.cwd;
-  return typeof cwd === "string" && cwd ? cwd : process.cwd();
+function toAbsolute(value: string, cwd: string): string {
+  if (value.startsWith("~/") && process.env.HOME) return resolve(process.env.HOME, value.slice(2));
+  return isAbsolute(value) ? resolve(value) : resolve(cwd, value);
 }
 
-function hasImageExt(p: string): boolean {
-  const ext = extOf(p);
-  return !!ext && IMAGE_EXTS.has(ext);
+function safeWorkspacePath(coordRoot: string, value: string): string | undefined {
+  const rel = relative(resolve(coordRoot), resolve(value));
+  if (!rel || isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`)) return undefined;
+  const normalized = rel.split(sep).join("/");
+  return normalized.length <= 240 && !normalized.startsWith("/") ? normalized : undefined;
 }
 
-function extOf(p: string): string {
-  const clean = p.split(/[?#]/)[0] ?? p; // drop any query/fragment
-  const dot = clean.lastIndexOf(".");
-  if (dot < 0) return "";
-  return clean.slice(dot + 1).toLowerCase();
+function hasImageExt(value: string): boolean {
+  return IMAGE_EXTS.has(extOf(value));
 }
 
-function toAbsolute(p: string, cwd: string): string {
-  let path = p;
-  if (path.startsWith("~/")) {
-    const home = process.env.HOME;
-    if (home) path = join(home, path.slice(2));
-  }
-  return isAbsolute(path) ? path : resolve(cwd, path);
+function extOf(value: string): string {
+  const clean = value.split(/[?#]/)[0] ?? value;
+  const dot = clean.lastIndexOf(".");
+  return dot < 0 ? "" : clean.slice(dot + 1).toLowerCase();
 }
 
-/** Strip the coordRoot prefix so the feed shows repo-relative paths. */
-function canonicalize(coordRoot: string, p: string): string {
-  if (p.startsWith(`${coordRoot}/`)) return p.slice(coordRoot.length + 1);
-  return p;
+function envInt(name: string, fallback: number): number {
+  const parsed = Number(process.env[name]);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }

package/src/core/hooks/effects/index.ts

@@ -19,8 +19,7 @@ import { join } from "node:path";
 import { applyDetection } from "../../../lib/presence.ts";
 import { coordBinPath } from "../../agents/coord-bin.ts";
 
-export type { CaptureContext } from "./image-capture.ts";
-export { captureImages, imageJanitor } from "./image-capture.ts";
+export { captureImages, imageJanitor, recordImageArtifactsV3 } from "./image-capture.ts";
 
 /**
  * Play a notification sound via the cross-platform utility
@@ -151,40 +150,6 @@ export function runSessionSyncExtension(repoRoot: string, force: boolean): void
   }
 }
 
-/**
- * Fire the turn-summary extension (Haiku auto-summary of the turn → heartbeat
- * `turn_summary`). Detached + unref'd; it makes an Anthropic API call and must
- * never block the Stop hook. Claude-Code-only. The
- * script self-guards on ANTHROPIC_API_KEY / curl / jq / matching session.
- */
-export function runTurnSummary(
-  repoRoot: string,
-  owner: string,
-  sessionId: string,
-  transcriptPath: string | undefined,
-): void {
-  try {
-    if (!transcriptPath || !existsSync(transcriptPath)) return;
-    const script = join(
-      repoRoot,
-      "scripts",
-      "hooks",
-      "harness",
-      "claude-code",
-      "extensions",
-      "turn-summary.sh",
-    );
-    if (!existsSync(script)) return;
-    const child = spawn("bash", [script, owner, sessionId, transcriptPath], {
-      detached: true,
-      stdio: "ignore",
-    });
-    child.unref();
-  } catch {
-    // best-effort
-  }
-}
-
 /** Reset per-turn sound rate-limit counters at the start of a new turn. */
 export function resetSoundCounters(sessionId: string): void {
   try {

package/src/core/hooks/events/input-hash.ts

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+
+/** Canonical JSON for hashing adapter input before any event-payload clamp. */
+export function canonicalToolInput(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+/** Exact-input digest used by the report-only run-quality evaluator. */
+export function toolInputHash(toolName: string, input: unknown): string {
+  return createHash("sha256")
+    .update(toolName)
+    .update("\n")
+    .update(canonicalToolInput(input))
+    .digest("hex");
+}
+
+/** Hash a semantic target without persisting its path, URL, or query. */
+export function toolTargetHash(toolName: string, input: unknown): string | undefined {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+  const record = input as Record<string, unknown>;
+  const target =
+    record.file_path ??
+    record.path ??
+    record.target ??
+    record.url ??
+    record.notebook_path ??
+    record.pattern;
+  if (target === undefined) return undefined;
+  return createHash("sha256")
+    .update(toolName)
+    .update("\n")
+    .update(canonicalToolInput(target))
+    .digest("hex");
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return Object.fromEntries(
+      Object.keys(record)
+        .sort()
+        .map((key) => [key, canonicalize(record[key])]),
+    );
+  }
+  return value;
+}