hilos-agent 0.1.15 → 0.4.0

package/src/hook.mjs

@@ -0,0 +1,427 @@
+// Claude Code hook → hilos live progress (0448). This is the "watch your
+// agent's hands move" path for a RAW CLI session (no daemon): install the
+// hilos hooks in a repo (`hilos-agent hooks install`) and every tool call your
+// Claude Code session makes streams a step into the agent's live status card
+// in its hilos channel, via the `post_progress` MCP tool's channelId mode.
+//
+// Design rules:
+//   - NEVER block or break the user's CLI. Every entry point swallows every
+//     error and exits 0; the network send is capped by a hard timeout.
+//   - Cheap by default: a state file per Claude session carries the message id,
+//     step ring and last-send time, so most invocations are one small read +
+//     at most one bounded fetch. Sends are throttled (default 2s) with pending
+//     steps carried over — a burst of tool calls becomes one coalesced update.
+//   - Privacy is the install default: `hooks install` writes to the PROJECT's
+//     .claude/settings.json, so only repos you opt in ever stream. HILOS_HOOKS=off
+//     is the global kill switch.
+//   - Pure helpers (event parsing, step labels, throttling decisions) are
+//     exported for offline unit tests; I/O lives only in runHook/main.
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, unlinkSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, delimiter } from "node:path";
+import { sanitizeText } from "./agent-events.mjs";
+import { resolveConfig } from "./config.mjs";
+
+export const HOOK_STATE_DIR = join(homedir(), ".hilos", "hook-state");
+/** Coalesce window between sends; Stop/SessionEnd always flush. */
+const MIN_SEND_MS = 2000;
+/** A hook must never hang the CLI on a slow network. */
+const FETCH_TIMEOUT_MS = 3000;
+/** Step/file bounds — mirror the server's caps (lib/agent-progress.ts). */
+const MAX_STEPS = 8;
+const MAX_FILES = 20;
+/** Session state older than this is dead — GC'd opportunistically. */
+const STATE_TTL_MS = 48 * 60 * 60 * 1000;
+
+/**
+ * Parse a Claude Code hook event from stdin text. Returns a normalized
+ * { event, sessionId, toolName, toolInput, cwd } or null when unusable.
+ * PURE — never throws.
+ */
+export function parseHookEvent(raw) {
+  try {
+    const o = JSON.parse(String(raw));
+    if (!o || typeof o !== "object") return null;
+    const event = typeof o.hook_event_name === "string" ? o.hook_event_name : "";
+    const sessionId = typeof o.session_id === "string" ? o.session_id : "";
+    if (!event || !sessionId) return null;
+    return {
+      event,
+      sessionId,
+      toolName: typeof o.tool_name === "string" ? o.tool_name : "",
+      toolInput: o.tool_input && typeof o.tool_input === "object" ? o.tool_input : {},
+      cwd: typeof o.cwd === "string" ? o.cwd : "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Strip the session cwd prefix so step labels read as repo-relative paths. */
+function relPath(p, cwd) {
+  const s = String(p || "");
+  if (cwd && s.startsWith(cwd + "/")) return s.slice(cwd.length + 1);
+  return s;
+}
+
+/** First line of a shell command, trimmed to a readable label. */
+function cmdLabel(cmd) {
+  const first = String(cmd || "").split("\n")[0].trim();
+  return first.length > 60 ? first.slice(0, 59) + "…" : first;
+}
+
+/**
+ * Map a PostToolUse event to a human step label (and the file it touched, if
+ * any), or null for tools too noisy to narrate (TodoWrite etc). PURE.
+ * Mirrors the daemon's vocabulary (agent-events stepLabel) so a hook-streamed
+ * card and a daemon-streamed card read the same.
+ */
+export function hookStep(toolName, toolInput, cwd = "") {
+  const name = String(toolName || "");
+  const input = toolInput && typeof toolInput === "object" ? toolInput : {};
+  const file = typeof input.file_path === "string" ? relPath(input.file_path, cwd) : "";
+  // MCP tools arrive as `mcp__<server>__<tool>`. Skip hilos's own tools — a
+  // session posting to hilos narrating "posting to hilos" is self-referential
+  // noise — and label other servers by their short tool name.
+  const mcp = name.match(/^mcp__([^_]+(?:_[^_]+)*)__(.+)$/);
+  if (mcp) {
+    if (/hilos/i.test(mcp[1])) return null;
+    return { label: `Using ${mcp[2].replace(/_/g, " ")} (${mcp[1]})` };
+  }
+  switch (name) {
+    case "Edit":
+    case "Write":
+    case "MultiEdit":
+    case "NotebookEdit":
+      return file ? { label: `Editing ${file}`, file } : { label: "Editing files" };
+    case "Read":
+      return file ? { label: `Reading ${file}`, file } : { label: "Reading files" };
+    case "Bash": {
+      const c = cmdLabel(input.command);
+      return { label: c ? `Running ${c}` : "Running a command" };
+    }
+    case "Grep":
+    case "Glob": {
+      const q = typeof input.pattern === "string" ? input.pattern : "";
+      return { label: q ? `Searching for ${q.slice(0, 60)}` : "Searching the repo" };
+    }
+    case "Task": {
+      const d = typeof input.description === "string" ? input.description : "";
+      return { label: d ? `Delegating: ${d.slice(0, 60)}` : "Delegating a task" };
+    }
+    case "WebFetch": {
+      let host = "";
+      try {
+        host = new URL(String(input.url || "")).host;
+      } catch {
+        /* not a url */
+      }
+      return { label: host ? `Fetching ${host}` : "Fetching a page" };
+    }
+    case "WebSearch": {
+      const q = typeof input.query === "string" ? input.query : "";
+      return { label: q ? `Searching the web: ${q.slice(0, 60)}` : "Searching the web" };
+    }
+    case "TodoWrite":
+      return null; // planning chatter — too noisy to narrate
+    default:
+      return { label: `Using ${name || "a tool"}` };
+  }
+}
+
+/**
+ * Fold a step into the session state: dedupe an immediate repeat (a run of
+ * edits to one file stays one step), ring-bound steps, set-bound files. PURE —
+ * mutates and returns `state`.
+ */
+export function foldStep(state, step) {
+  if (!step) return state;
+  const label = sanitizeText(step.label);
+  if (!label) return state;
+  const steps = Array.isArray(state.steps) ? state.steps : [];
+  if (steps[steps.length - 1] !== label) steps.push(label);
+  while (steps.length > MAX_STEPS) steps.shift();
+  state.steps = steps;
+  if (step.file) {
+    const file = sanitizeText(step.file);
+    const files = Array.isArray(state.files) ? state.files : [];
+    if (file && !files.includes(file)) {
+      files.push(file);
+      while (files.length > MAX_FILES) files.shift();
+    }
+    state.files = files;
+  }
+  return state;
+}
+
+/** Throttle decision: send now, or fold and wait for a later event? PURE. */
+export function shouldSendNow(state, now, minSendMs = MIN_SEND_MS) {
+  const last = typeof state.lastSentAt === "number" ? state.lastSentAt : 0;
+  return now - last >= minSendMs;
+}
+
+/** Filename-safe session key (a session_id is a uuid, but never trust input). */
+function sessionKey(sessionId) {
+  return String(sessionId).replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+}
+
+export function statePath(sessionId, dir = HOOK_STATE_DIR) {
+  return join(dir, sessionKey(sessionId) + ".json");
+}
+
+export function readState(sessionId, dir = HOOK_STATE_DIR) {
+  try {
+    return JSON.parse(readFileSync(statePath(sessionId, dir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function writeState(sessionId, state, dir = HOOK_STATE_DIR) {
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(statePath(sessionId, dir), JSON.stringify(state));
+  } catch {
+    /* best-effort */
+  }
+}
+
+export function deleteState(sessionId, dir = HOOK_STATE_DIR) {
+  try {
+    unlinkSync(statePath(sessionId, dir));
+  } catch {
+    /* already gone */
+  }
+}
+
+/** Drop state files from long-dead sessions. Best-effort, bounded, silent. */
+export function gcStateDir(dir = HOOK_STATE_DIR, now = Date.now()) {
+  try {
+    for (const f of readdirSync(dir).slice(0, 200)) {
+      const p = join(dir, f);
+      try {
+        if (now - statSync(p).mtimeMs > STATE_TTL_MS) unlinkSync(p);
+      } catch {
+        /* skip */
+      }
+    }
+  } catch {
+    /* no dir yet */
+  }
+}
+
+/** One bounded post_progress call. Returns the server's messageId, or null. */
+async function sendProgress({ url, token, messageId, channelId, progress }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const args = messageId ? { messageId, progress } : { channelId, progress };
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "post_progress", arguments: args },
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    const text = json?.result?.content?.[0]?.text;
+    const parsed = typeof text === "string" ? JSON.parse(text) : null;
+    return parsed && typeof parsed.messageId === "string" ? parsed.messageId : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Handle one hook invocation end to end. Reads nothing from process.* so the
+ * caller (bin) owns stdin/env; returns quietly on every failure path.
+ */
+export async function runHook({ raw, cfg, now = Date.now, stateDir = HOOK_STATE_DIR }) {
+  const ev = parseHookEvent(raw);
+  if (!ev) return;
+  const { url, token, channelId } = cfg;
+  if (!url || !token || !channelId) return; // not connected to hilos — no-op
+
+  if (ev.event === "Stop" || ev.event === "SessionEnd") {
+    // End of a turn (or the session): settle the card honestly — "not doing
+    // anything right now". The next tool call revives the SAME card to working
+    // via its stored messageId, so a session stays one card, not one per turn.
+    const state = readState(ev.sessionId, stateDir);
+    if (!state || !state.messageId) return;
+    await sendProgress({
+      url,
+      token,
+      messageId: state.messageId,
+      progress: {
+        state: "done",
+        elapsedMs: Math.max(0, now() - (state.startedAt || now())),
+      },
+    });
+    if (ev.event === "SessionEnd") deleteState(ev.sessionId, stateDir);
+    else {
+      state.lastSentAt = now();
+      writeState(ev.sessionId, state, stateDir);
+    }
+    return;
+  }
+
+  if (ev.event !== "PostToolUse") return;
+
+  const step = hookStep(ev.toolName, ev.toolInput, ev.cwd);
+  if (!step) return;
+
+  let state = readState(ev.sessionId, stateDir);
+  if (!state) {
+    gcStateDir(stateDir, now()); // new session — a cheap moment to sweep old ones
+    state = { startedAt: now(), lastSentAt: 0, steps: [], files: [], messageId: null };
+  }
+  foldStep(state, step);
+
+  if (!shouldSendNow(state, now())) {
+    // Inside the coalesce window: fold only. The next event (or Stop) flushes.
+    writeState(ev.sessionId, state, stateDir);
+    return;
+  }
+
+  const progress = {
+    state: "working",
+    step: state.steps[state.steps.length - 1],
+    steps: state.steps,
+    filesTouched: state.files,
+    elapsedMs: Math.max(0, now() - (state.startedAt || now())),
+  };
+  const messageId = await sendProgress({
+    url,
+    token,
+    messageId: state.messageId || undefined,
+    channelId,
+    progress,
+  });
+  if (messageId) state.messageId = messageId;
+  state.lastSentAt = now();
+  writeState(ev.sessionId, state, stateDir);
+}
+
+/** Read all of stdin (the hook event JSON Claude Code pipes in). */
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    const timer = setTimeout(() => resolve(data), 2000); // stdin must never hang the hook
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+  });
+}
+
+/** `hilos-agent hook` — the command Claude Code invokes. Always exits 0. */
+export async function hookMain() {
+  try {
+    if (/^(off|0|false)$/i.test(process.env.HILOS_HOOKS || "")) return;
+    const raw = await readStdin();
+    const cfg = resolveConfig({});
+    await runHook({ raw, cfg });
+  } catch {
+    /* a hook must never fail the user's CLI */
+  }
+}
+
+// --- `hilos-agent hooks print|install [--global]` ---------------------------
+
+const HOOK_COMMAND = "hilos-agent hook";
+
+/** The hooks block hilos needs inside a Claude Code settings.json. */
+export function hilosHooksBlock() {
+  const entry = { hooks: [{ type: "command", command: HOOK_COMMAND }] };
+  return {
+    PostToolUse: [{ matcher: "*", ...entry }],
+    Stop: [entry],
+    SessionEnd: [entry],
+  };
+}
+
+/**
+ * Idempotently merge the hilos hooks into a settings object (parsed
+ * settings.json). Existing user hooks are preserved; a second install is a
+ * no-op. PURE — returns { settings, changed }.
+ */
+export function mergeHooksIntoSettings(settings) {
+  const out = settings && typeof settings === "object" ? settings : {};
+  const hooks = (out.hooks = out.hooks && typeof out.hooks === "object" ? out.hooks : {});
+  let changed = false;
+  for (const [event, entries] of Object.entries(hilosHooksBlock())) {
+    const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const already = existing.some((e) =>
+      (e?.hooks || []).some((h) => h?.command === HOOK_COMMAND),
+    );
+    if (!already) {
+      hooks[event] = [...existing, ...entries];
+      changed = true;
+    }
+  }
+  return { settings: out, changed };
+}
+
+/** `hilos-agent hooks install [--global]` / `hilos-agent hooks print`. */
+export function hooksMain(sub, { global: isGlobal = false } = {}) {
+  if (sub === "print") {
+    console.log(JSON.stringify({ hooks: hilosHooksBlock() }, null, 2));
+    console.log("\nMerge this into .claude/settings.json in the repo you want to stream.");
+    return;
+  }
+  if (sub !== "install") {
+    console.log("Usage: hilos-agent hooks <install|print> [--global]");
+    return;
+  }
+  const target = isGlobal
+    ? join(homedir(), ".claude", "settings.json")
+    : join(process.cwd(), ".claude", "settings.json");
+  let current = {};
+  if (existsSync(target)) {
+    try {
+      current = JSON.parse(readFileSync(target, "utf8"));
+    } catch {
+      console.error(`${target} exists but isn't valid JSON — fix it first (nothing written).`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const { settings, changed } = mergeHooksIntoSettings(current);
+  if (!changed) {
+    console.log(`hilos hooks already installed in ${target}.`);
+    return;
+  }
+  if (existsSync(target)) writeFileSync(target + ".bak", readFileSync(target));
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, JSON.stringify(settings, null, 2) + "\n");
+  console.log(`Installed hilos hooks into ${target}${existsSync(target + ".bak") ? ` (backup: ${target}.bak)` : ""}.`);
+  console.log(
+    isGlobal
+      ? "Every Claude Code session on this machine will now stream its steps to your hilos channel."
+      : "Claude Code sessions in THIS repo will now stream their steps to your hilos channel.",
+  );
+  console.log("Kill switch: HILOS_HOOKS=off.");
+  // The installed entry runs `hilos-agent hook` directly (npx per tool call
+  // would add cold-start latency) — warn now if that won't resolve.
+  const onPath = (process.env.PATH || "")
+    .split(delimiter)
+    .some((dir) => dir && existsSync(join(dir, "hilos-agent")));
+  if (!onPath) {
+    console.log(
+      "NOTE: hilos-agent isn't on your PATH — the hooks won't fire until you run: npm i -g hilos-agent",
+    );
+  }
+}

package/src/memory.mjs

@@ -0,0 +1,95 @@
+// Pure helper for building the team memory block injected into coding-agent
+// prompts before a task. Mirrors the shape of lib/memory.ts (server-side TS)
+// but as plain JS so the daemon package has no TypeScript/Next.js dependencies.
+// No I/O — pure function, exportable and unit-testable without a running server.
+
+const HEADER = "Team memory (accumulated learnings):";
+const REMEMBER_NOTE =
+  "To record durable new learnings from this task, use the `remember` MCP tool " +
+  "(call it if your MCP config includes the hilos server).";
+
+// Budgets are deliberately TIGHTER than lib/memory.ts formatMemoryBlock
+// (25/6000/400): the daemon injects this into a coding-agent prompt that already
+// carries the repo + task context, so it keeps a smaller footprint (25/4000/300)
+// to leave headroom for the code.
+const DEFAULT_MAX_ENTRIES = 25;
+const DEFAULT_MAX_CHARS = 4000;
+const DEFAULT_BODY_CHARS = 300;
+// Reserve up to this many entry slots for workspace-wide learnings when both
+// scopes have entries, so channel-first ordering can't starve team-wide
+// conventions out of the cap. Mirrors lib/memory.ts. Channel entries still lead.
+const RESERVED_WS_SLOTS = 5;
+
+/** Truncate `text` to `max` chars, appending "…" when clipped. */
+function clip(text, max) {
+  const t = String(text || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return t.length > max ? `${t.slice(0, max).trimEnd()}…` : t;
+}
+
+/**
+ * Build a compact "Team memory" block from recall() entries for injection into
+ * a coding-agent prompt. Channel-scoped entries come first (they are the most
+ * project-specific); newest first within each scope group. Each entry is one
+ * line: `- [kind] title: body`. Bodies are truncated to ~300 chars. The whole
+ * block is capped at ~4000 chars (entries that would overflow are dropped, but
+ * at least one entry is always kept). Ends with a note reminding the agent to
+ * record new learnings via the `remember` MCP tool. Saved memory is active
+ * immediately; people can correct or hide it later in hilos.
+ *
+ * Returns "" when entries is empty or null so callers can concatenate
+ * unconditionally (`block ? block + "\n\n" : ""`).
+ *
+ * @param {Array<{kind?: string, title: string, body: string, scope: string, updated_at?: string}>} entries
+ * @param {{ maxEntries?: number, maxChars?: number, bodyChars?: number }} [opts]
+ * @returns {string}
+ */
+export function buildMemoryBlock(entries, opts = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) return "";
+  const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+  const bodyChars = opts.bodyChars ?? DEFAULT_BODY_CHARS;
+
+  // Channel-scoped first (most relevant to the current project), then
+  // workspace-wide. Newest first within each scope group.
+  const scopeRank = (s) => (s === "channel" ? 0 : 1);
+  const ordered = [...entries].sort((a, b) => {
+    const byScope = scopeRank(a.scope) - scopeRank(b.scope);
+    if (byScope !== 0) return byScope;
+    return (b.updated_at || "").localeCompare(a.updated_at || "");
+  });
+
+  // Entry-count selection with a reserved workspace quota (see RESERVED_WS_SLOTS):
+  // hold back a few slots for workspace-wide entries when both scopes are present
+  // so channel entries can't claim every slot. Channel entries still lead.
+  const channelEntries = ordered.filter((e) => e.scope === "channel");
+  const workspaceEntries = ordered.filter((e) => e.scope !== "channel");
+  let picked;
+  if (channelEntries.length > 0 && workspaceEntries.length > 0) {
+    const wsReserve = Math.min(RESERVED_WS_SLOTS, workspaceEntries.length);
+    const chosenChannel = channelEntries.slice(0, Math.max(0, maxEntries - wsReserve));
+    const chosenWs = workspaceEntries.slice(0, maxEntries - chosenChannel.length);
+    picked = [...chosenChannel, ...chosenWs];
+  } else {
+    picked = ordered.slice(0, maxEntries);
+  }
+
+  const lines = [];
+  // Reserve chars for: header line + newline + 2 newlines before footer + footer.
+  let total = HEADER.length + 1 + 2 + REMEMBER_NOTE.length;
+  for (const e of picked) {
+    const kind = (e.kind || "note").trim();
+    const title = (e.title || "").replace(/\s+/g, " ").trim();
+    const body = clip(e.body || "", bodyChars);
+    const line = `- [${kind}] ${title}${body ? `: ${body}` : ""}`;
+    // Always keep the first entry even if it's large; drop later ones that
+    // would push the block past the budget.
+    if (lines.length > 0 && total + line.length + 1 > maxChars) break;
+    lines.push(line);
+    total += line.length + 1;
+  }
+
+  if (lines.length === 0) return "";
+  return `${HEADER}\n${lines.join("\n")}\n\n${REMEMBER_NOTE}`;
+}