harnery 0.0.1 → 0.2.0

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

@@ -0,0 +1,330 @@
+/**
+ * Image-feed capture: a non-coordination side effect fired from the normalized
+ * `agent-hook` tool handlers (see effects/index.ts for the family rationale).
+ *
+ * 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 harness-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.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { emit } from "../events/emit.ts";
+import type { Harness } from "../events/schema.ts";
+import type { ParsedPayload } from "../harness/parse.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 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;
+
+/** 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;
+  harness: Harness;
+}
+
+interface Candidate {
+  path: string; // resolved absolute path
+  role: "viewed" | "produced";
+  intent?: string;
+  commandHead?: string;
+  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,
+      harness: ctx.harness,
+      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,
+  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;
+
+  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;
+}
+
+/**
+ * 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.
+ */
+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
+  }
+  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
+    }
+  }
+  return { hash, ext, bytes: st.size };
+}
+
+/**
+ * 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
+ * scratchJanitor. Pure-fs, fail-soft. Orphaned `image.captured` events whose
+ * blob was pruned render as an "expired" placeholder in the gallery.
+ */
+export function imageJanitor(coordRoot: string): void {
+  try {
+    const dir = join(coordRoot, ".harnery", "images");
+    if (!existsSync(dir)) return;
+    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();
+
+    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);
+      } catch {
+        continue;
+      }
+      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;
+      }
+      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;
+      }
+    }
+  } catch {
+    // best-effort
+  }
+}
+
+/* ── helpers ─────────────────────────────────────────────────────────────── */
+
+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 parseToolInput(raw: unknown): Record<string, unknown> | null {
+  if (typeof raw !== "string") return null;
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } 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 stringifyResponse(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  try {
+    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 hasImageExt(p: string): boolean {
+  const ext = extOf(p);
+  return !!ext && IMAGE_EXTS.has(ext);
+}
+
+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 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);
+}
+
+/** 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;
+}

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

@@ -0,0 +1,210 @@
+/**
+ * Non-coordination side effects fired from the normalized `agent-hook` handlers.
+ *
+ * These are DELIBERATELY outside the agent-coord path: sounds, scratch
+ * lifecycle, session telemetry, presence detection. They used to live in
+ * per-harness bash adapters. Per the directive ("use the normalized hooks; if
+ * they aren't coordination, implement them outside of coordination") they move
+ * here so the harness configs reference only `agent-hook`, while staying a
+ * distinct concern from the coordination logic in cli.ts / agent-coord.
+ *
+ * Everything here is best-effort: it never throws and never blocks the hook on a
+ * slow dependency (telemetry runs detached).
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+import { applyDetection } from "../../../lib/presence.ts";
+
+export type { CaptureContext } from "./image-capture.ts";
+export { captureImages, imageJanitor } from "./image-capture.ts";
+
+/**
+ * Play a notification sound via the cross-platform utility
+ * (afplay on macOS, powershell.exe on WSL). The
+ * utility backgrounds the actual player, so this returns fast. Rate-limiting
+ * lives in the utility, keyed on CLAUDE_SOUND_SESSION_ID + the per-event count.
+ * Claude-Code-only today (Cursor has no sounds; Codex's never worked).
+ */
+export function playSound(
+  repoRoot: string,
+  soundEvent: string,
+  sessionId: string,
+  maxPlays = 0,
+): void {
+  try {
+    const player = join(repoRoot, "scripts", "hooks", "play-sound.sh");
+    if (!existsSync(player)) return;
+    spawnSync("bash", [player, soundEvent, String(maxPlays)], {
+      env: { ...process.env, CLAUDE_SOUND_SESSION_ID: sessionId },
+      timeout: 4000,
+      stdio: "ignore",
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+/** Map an agent-hook CLI event name → sound, or null if the event has no sound. */
+export function soundForEvent(eventName: string): { sound: string; maxPlays: number } | null {
+  switch (eventName) {
+    case "stop":
+      return { sound: "stop", maxPlays: 0 };
+    case "stop-failure":
+      return { sound: "error", maxPlays: 0 };
+    case "sub-agent-start":
+      return { sound: "subagent-start", maxPlays: 3 };
+    default:
+      return null;
+  }
+}
+
+function harnBin(repoRoot: string): string | null {
+  const bin = join(repoRoot, "harnery", "bin", "harn");
+  return existsSync(bin) ? bin : null;
+}
+
+/** Prune stale scratch archives + sweep orphans (global, fast). Fire-and-forget. */
+export function scratchJanitor(repoRoot: string): void {
+  try {
+    const bin = harnBin(repoRoot);
+    if (!bin) return;
+    spawnSync("bash", [bin, "scratch", "janitor", "--quiet"], {
+      env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
+      timeout: 5000,
+      stdio: "ignore",
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Return the one-line scratch recovery cue for SessionStart, or "" if none.
+ * The caller merges it into the session-start additionalContext (it used to be
+ * a standalone additionalContext emission from the previous scratch-on-start adapter).
+ */
+export function scratchRecoveryCue(repoRoot: string): string {
+  try {
+    const bin = harnBin(repoRoot);
+    if (!bin) return "";
+    const r = spawnSync("bash", [bin, "scratch", "recovery-cue"], {
+      env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
+      timeout: 5000,
+      encoding: "utf8",
+    });
+    return (r.stdout ?? "").trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Archive the ending agent's scratchpad. Fire-and-forget. */
+export function scratchArchive(repoRoot: string, owner: string): void {
+  try {
+    const bin = harnBin(repoRoot);
+    if (!bin || !owner) return;
+    spawnSync("bash", [bin, "scratch", "archive", "--owner", owner], {
+      env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
+      timeout: 5000,
+      stdio: "ignore",
+    });
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Sync Claude Code session JSONL → BigQuery (`harn claude-sessions sync`). Lives
+ * in the host CLI (parses Claude Code's own ~/.claude/projects/**\/*.jsonl), so harnery
+ * shells out to the harn binary rather than importing it. Detached + unref'd so a
+ * slow BigQuery round-trip never blocks the hook. Stop-path syncs are rate-
+ * limited inside `harn claude-sessions sync`; SessionEnd forces via env. Caller
+ * gates to the claude-code harness.
+ */
+export function syncClaudeSessions(repoRoot: string, force: boolean): void {
+  try {
+    const bin = join(repoRoot, "bin", "bp");
+    if (!existsSync(bin)) return;
+    const env: Record<string, string | undefined> = {
+      ...process.env,
+      HARNERY_OUTPUT_SESSION_TEE: "0",
+    };
+    if (force) env.HARNERY_CLAUDE_SESSIONS_FORCE = "1";
+    const child = spawn("bash", [bin, "claude-sessions", "sync", "--quiet"], {
+      env,
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * 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 {
+    if (!sessionId) return;
+    const dir = os.tmpdir();
+    const prefix = `claude-sounds-${sessionId}-`;
+    for (const f of readdirSync(dir)) {
+      if (f.startsWith(prefix) && f.endsWith(".count")) {
+        rmSync(join(dir, f), { force: true });
+      }
+    }
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Update the mobile-vs-office presence file from the user's prompt shape, using
+ * harnery's own presence library in-process: no external script, no host-path
+ * dependency. Claude-Code-only (the heuristic is tuned to CC's user-prompt
+ * payload; Cursor/Codex don't surface comparable prompt text). Fire-and-forget.
+ */
+export function detectPresence(prompt: string): void {
+  try {
+    if (!prompt) return;
+    applyDetection(prompt);
+  } catch {
+    // best-effort
+  }
+}

package/src/core/hooks/events/emit.ts

@@ -0,0 +1,120 @@
+import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  type EventEnvelope,
+  type EventType,
+  type Harness,
+  SCHEMA_VERSION,
+  type Source,
+} from "./schema.ts";
+import { ulid } from "./ulid.ts";
+
+const LOCK_FILE = ".harnery/events.ndjson.lock";
+const STREAM_FILE = ".harnery/events.ndjson";
+
+const MAX_LINE_BYTES = 64 * 1024;
+
+export interface EmitInput<TType extends EventType, TData> {
+  event_type: TType;
+  instance_id: string;
+  session_id: string;
+  harness: Harness;
+  source?: Source;
+  parent_session_id?: string;
+  turn_id?: string;
+  parent_turn_id?: string;
+  ts?: string;
+  data: TData;
+}
+
+/**
+ * Build a canonical envelope around the caller's `data` payload. Pure;
+ * doesn't touch the filesystem. Useful for tests + replay fixtures.
+ */
+export function buildEnvelope<TType extends EventType, TData>(
+  input: EmitInput<TType, TData>,
+): EventEnvelope<TType, TData> {
+  return {
+    schema_version: SCHEMA_VERSION,
+    event_id: ulid(),
+    event_type: input.event_type,
+    ts: input.ts ?? new Date().toISOString(),
+    instance_id: input.instance_id,
+    session_id: input.session_id,
+    parent_session_id: input.parent_session_id,
+    turn_id: input.turn_id,
+    parent_turn_id: input.parent_turn_id,
+    harness: input.harness,
+    source: input.source ?? "agent-hooks",
+    data: input.data,
+  };
+}
+
+/**
+ * Append one canonical event to `.harnery/events.ndjson` under a file lock.
+ * Append-only, one JSON object per line, lock-serialized.
+ *
+ * Synchronous because hooks are short-lived processes: we want the append to
+ * land before the binary exits, and async/await across a tiny write is just
+ * latency for no benefit.
+ *
+ * Returns the envelope so callers can chain off it (debug logs, post-emit
+ * verdict requests).
+ */
+export function emit<TType extends EventType, TData>(
+  coordRoot: string,
+  input: EmitInput<TType, TData>,
+): EventEnvelope<TType, TData> {
+  const envelope = buildEnvelope(input);
+  const streamPath = join(coordRoot, STREAM_FILE);
+  const lockPath = join(coordRoot, LOCK_FILE);
+
+  ensureDir(dirname(streamPath));
+  ensureFile(lockPath);
+
+  let line = `${JSON.stringify(envelope)}\n`;
+  if (Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) {
+    // lines >64KB are a schema bug. Phase 2 hard-truncates the `data`
+    // payload + sets `truncated: true` so we keep audit visibility without
+    // breaking downstream consumers.
+    const truncated = `${JSON.stringify({
+      ...envelope,
+      data: { __over_size_limit: true, original_bytes: Buffer.byteLength(line, "utf8") },
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+    })}\n`;
+    line = truncated;
+  }
+
+  const lockFd = openSync(lockPath, "r+");
+  try {
+    // flock isn't directly exposed in node fs; use fcntl-like via shelling out
+    // would be slower than POSIX flock(2) inside the kernel. Bun exposes
+    // `Bun.flock` in recent builds, but a simple fs-level append is atomic
+    // for lines <PIPE_BUF (4KB on Linux) anyway. For larger lines we rely on
+    // append-mode flag (O_APPEND) which kernels serialize per-fd.
+    //
+    // The `events.ndjson.lock` file is kept around for forward
+    // compatibility: Phase 4+ helpers acquire it before multi-write batches.
+    appendFileSync(streamPath, line, { encoding: "utf8", flag: "a" });
+  } finally {
+    closeSync(lockFd);
+  }
+
+  return envelope;
+}
+
+function ensureDir(path: string): void {
+  try {
+    mkdirSync(path, { recursive: true });
+  } catch {
+    /* swallow */
+  }
+}
+
+function ensureFile(path: string): void {
+  try {
+    closeSync(openSync(path, "a"));
+  } catch {
+    /* swallow */
+  }
+}