dsh-engram 0.2.0

package/lib/api.js

@@ -0,0 +1,418 @@
+/**
+ * dsh-engram: read-mostly web API for the GUI (host half).
+ *
+ * A small same-origin JSON route family under `/api/dsh-engram`. Every route
+ * wears the loopback-only trust fence (copied from the SSH family): these
+ * routes expose the on-disk memory store, so a LAN-exposed dsh web must not
+ * serve them. All reads go straight at the opened storage-domain handle
+ * (synchronous after the first open); the two mutations (archive / delete)
+ * go through the same store methods the agent tools use.
+ */
+
+import { uuid, shortId } from "./util.js";
+
+/** Route family prefix (kept in sync with the client half). */
+export const API_PREFIX = "/api/dsh-engram";
+
+/** Cap on JSON request bodies (archives/deletes are tiny). */
+const MAX_JSON_BODY_BYTES = 32 * 1024;
+
+/** Loopback literal check plus browser same-origin markers. */
+function isLoopbackRequest(request, trustedHosts = []) {
+  const address = request.socket?.remoteAddress;
+  if (address !== "127.0.0.1" && address !== "::1" && address !== "::ffff:127.0.0.1") return false;
+  const host = request.headers.host;
+  if (typeof host !== "string") return false;
+  let hostUrl;
+  try {
+    hostUrl = new URL(`http://${host}`);
+  } catch {
+    return false;
+  }
+  const hostname = hostUrl.hostname;
+  if (hostname === "127.0.0.1" || hostname === "localhost" || hostname === "[::1]") {
+    if (request.headers["sec-fetch-site"] === "cross-site") return false;
+    const origin = request.headers.origin;
+    if (origin === undefined) return true;
+    try {
+      return new URL(origin).host === hostUrl.host;
+    } catch {
+      return false;
+    }
+  }
+  // Not loopback: only an explicitly configured trusted hostname (e.g. a
+  // cloudflare tunnel the operator authorized) may read the store. This is
+  // the opt-in that makes the GUI usable when it is reached through a
+  // tunnel; the default stays loopback-only.
+  if (trustedHosts.some((h) => typeof h === "string" && h.length > 0 && h.toLowerCase() === hostname.toLowerCase())) {
+    if (request.headers["sec-fetch-site"] === "cross-site") return false;
+    return true;
+  }
+  return false;
+}
+
+function writeJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8", "referrer-policy": "no-referrer" });
+  res.end(payload);
+}
+
+function writeError(res, status, message) {
+  writeJson(res, status, { error: message });
+}
+
+function readQuery(req) {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  return url.searchParams;
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_JSON_BODY_BYTES) {
+        resolve({ error: "body too large" });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (size === 0) {
+        resolve({ value: {} });
+        return;
+      }
+      try {
+        resolve({ value: JSON.parse(Buffer.concat(chunks).toString("utf8")) });
+      } catch {
+        resolve({ error: "invalid JSON body" });
+      }
+    });
+    req.on("error", () => resolve({ error: "request error" }));
+  });
+}
+
+/** Coarse token estimate for a [ENGRAM] index block (ASCII ≈ 4 chars/token). */
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.max(1, Math.ceil([...text].length / 4));
+}
+
+/**
+ * Build the route list for one plugin instance.
+ * @param service - the engram service ({ config, getDomain, openedDomain, ensureDomain }).
+ * @returns the routes to pass to `ctx.webServer.register(route)`.
+ */
+export function makeEngramRoutes(service) {
+  const trustedHosts = Array.isArray(service?.config?.trustedHosts) ? service.config.trustedHosts : [];
+  const withDomain = async (res) => {
+    const opened = service.openedDomain?.();
+    if (opened !== void 0) return opened;
+    try {
+      return await service.getDomain();
+    } catch (error) {
+      writeError(res, 503, `engram storage unavailable: ${String(error?.message ?? error)}`);
+      return void 0;
+    }
+  };
+
+  const readConfig = (_req, res) => {
+    const c = service.config ?? {};
+    const payload = {
+      autoCapture: c.autoCapture,
+      sessionSearch: c.sessionSearch,
+      autoCapturePerSession: c.autoCapturePerSession,
+      indexMaxLines: c.indexMaxLines,
+      indexMaxChars: c.indexMaxChars,
+      minIndexSignal: c.minIndexSignal,
+      promoteHits: c.promoteHits,
+      expireDays: c.expireDays,
+      maxMemoriesPerWorkspace: c.maxMemoriesPerWorkspace,
+    };
+    writeJson(res, 200, payload);
+  };
+
+  const overview = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const summary = domain.summarize();
+    // [ENGRAM] index estimate: recompute the exact block cost per workspace.
+    const indexes = {};
+    for (const ws of Object.keys(summary.workspaces)) {
+      const block = service.renderIndexBlock?.(ws) ?? "";
+      indexes[ws] = { chars: [...block].length, tokens: estimateTokens(block), lines: block.split("\n").length - 1 };
+    }
+    writeJson(res, 200, {
+      ...summary,
+      indexes,
+      captures: service.captureStats ?? { total: 0, git: 0, file: 0, error: 0 },
+      gc: service.gcStats ?? { lastRun: 0, archivedMemories: 0, archivedTasks: 0, removedLinks: 0 },
+      config: service.config ?? {},
+      anonymous: {
+        version: 2,
+        note: "counts exclude archived/expired entries; tasks exclude stable.",
+      },
+    });
+    void req;
+  };
+
+  const memories = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const params = readQuery(req);
+    const items = domain.searchMemories({
+      workspace: params.get("workspace") || void 0,
+      q: params.get("q") || void 0,
+      kind: params.get("kind") || void 0,
+      status: params.get("status") || void 0,
+      limit: Number(params.get("limit") ?? 100),
+    });
+    writeJson(res, 200, { items });
+  };
+
+  const tasks = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const params = readQuery(req);
+    const workspace = params.get("workspace");
+    if (!workspace) {
+      writeError(res, 400, "workspace query parameter is required");
+      return;
+    }
+    const includeStable = params.get("includeStable") === "1";
+    writeJson(res, 200, { items: domain.listTasks(workspace, { includeStable }) });
+  };
+
+  const links = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const params = readQuery(req);
+    const workspace = params.get("workspace");
+    if (!workspace) {
+      writeError(res, 400, "workspace query parameter is required");
+      return;
+    }
+    writeJson(res, 200, { items: domain.allLinks(workspace) });
+  };
+
+  const entities = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const params = readQuery(req);
+    const workspace = params.get("workspace");
+    if (!workspace) {
+      writeError(res, 400, "workspace query parameter is required");
+      return;
+    }
+    writeJson(res, 200, { items: domain.listEntities(workspace) });
+  };
+
+  const archive = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const body = await readJsonBody(req);
+    if (body.error) return writeError(res, 400, body.error);
+    const { id, workspace } = body.value ?? {};
+    if (typeof id !== "string" || typeof workspace !== "string") {
+      return writeError(res, 400, "id and workspace are required");
+    }
+    try {
+      const ok = await domain.archiveMemory(workspace, id);
+      if (!ok) return writeError(res, 404, "memory not found or already archived");
+      writeJson(res, 200, { ok: true });
+    } catch (error) {
+      writeError(res, 500, String(error?.message ?? error));
+    }
+  };
+
+  const remove = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const body = await readJsonBody(req);
+    if (body.error) return writeError(res, 400, body.error);
+    const { id, workspace } = body.value ?? {};
+    if (typeof id !== "string" || typeof workspace !== "string") {
+      return writeError(res, 400, "id and workspace are required");
+    }
+    try {
+      const ok = await domain.deleteMemory(workspace, id);
+      if (!ok) return writeError(res, 404, "memory not found");
+      writeJson(res, 200, { ok: true });
+    } catch (error) {
+      writeError(res, 500, String(error?.message ?? error));
+    }
+  };
+
+  const gcRun = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const body = await readJsonBody(req);
+    if (body.error) return writeError(res, 400, body.error);
+    const { workspace, dryRun } = body.value ?? {};
+    // Workspace optional -> sweep every workspace (same semantics as the tool).
+    if (workspace !== void 0 && typeof workspace !== "string") {
+      return writeError(res, 400, "workspace must be a string when provided");
+    }
+    try {
+      const report = await domain.gc(
+        workspace === void 0 || workspace.length === 0 ? void 0 : workspace,
+        service.config ?? {},
+        { dryRun: dryRun === true },
+      );
+      if (dryRun !== true) {
+        service.gcStats ??= { lastRun: 0, archivedMemories: 0, archivedTasks: 0, removedLinks: 0 };
+        service.gcStats.lastRun = Date.now();
+        service.gcStats.archivedMemories += report.archivedMemories.length;
+        service.gcStats.archivedTasks += report.archivedTasks.length;
+        service.gcStats.removedLinks += report.removedLinks.length;
+      }
+      writeJson(res, 200, { report });
+    } catch (error) {
+      writeError(res, 500, String(error?.message ?? error));
+    }
+  };
+
+  const guard = (req, res, method, handler) => {
+    if ((req.method ?? "GET").toUpperCase() !== method) {
+      writeError(res, 405, "method not allowed");
+      return;
+    }
+    if (!isLoopbackRequest(req, trustedHosts)) {
+      writeError(res, 403, "loopback-only");
+      return;
+    }
+    return handler(req, res);
+  };
+
+  /** GUI task creation — mirrors esr_task (id + state defaults), no session. */
+  const createTask = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const body = await readJsonBody(req);
+    if (body.error) return writeError(res, 400, body.error);
+    const { workspace, name, description } = body.value ?? {};
+    if (typeof workspace !== "string" || workspace.length === 0) return writeError(res, 400, "workspace is required");
+    if (typeof name !== "string" || name.trim().length === 0) return writeError(res, 400, "name is required");
+    const max = service.config?.maxTasksPerWorkspace ?? 10;
+    if (domain.activeTaskCount(workspace) >= max) {
+      return writeError(res, 409, `workspace already holds ${max} active tasks; close some first`);
+    }
+    const now = Date.now();
+    const task = {
+      id: `tsk_${shortId(uuid())}`,
+      workspace,
+      name: name.trim().slice(0, 200),
+      description: typeof description === "string" ? description.trim().slice(0, 2000) : "",
+      state: "active",
+      artifact: null,
+      evaluation: null,
+      memoryRefs: [],
+      sessionId: "gui",
+      createdAt: now,
+      updatedAt: now,
+      stateChangedAt: 0,
+    };
+    await domain.putTask(task);
+    writeJson(res, 200, { task });
+  };
+
+  /** GUI task close — mirrors esr_close's evidence gates without a session. */
+  const closeTask = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const body = await readJsonBody(req);
+    if (body.error) return writeError(res, 400, body.error);
+    const { workspace, id, artifact, evaluation, memory_refs } = body.value ?? {};
+    if (typeof workspace !== "string" || workspace.length === 0 || typeof id !== "string" || id.length === 0) {
+      return writeError(res, 400, "workspace and id are required");
+    }
+    const task = domain.getTask(workspace, id);
+    if (task === void 0) return writeError(res, 404, "task not found");
+    const str = (v) => (typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined);
+    const refs = Array.isArray(memory_refs)
+      ? memory_refs.filter((x) => typeof x === "string" && x.trim().length > 0).map((x) => x.trim())
+      : undefined;
+    const next = {
+      ...task,
+      artifact: str(artifact) ?? task.artifact ?? null,
+      evaluation: str(evaluation) ?? task.evaluation ?? null,
+      memoryRefs: refs ?? task.memoryRefs ?? [],
+      updatedAt: Date.now(),
+    };
+    const gaps = [];
+    if (next.artifact === null || next.artifact === "") gaps.push("artifact");
+    if (next.evaluation === null || next.evaluation === "") gaps.push("evaluation");
+    if (!Array.isArray(next.memoryRefs) || next.memoryRefs.length === 0) gaps.push("memory_ref");
+    if (gaps.length > 0) {
+      await domain.putTask(next);
+      writeJson(res, 200, { ok: true, state: "active", gaps });
+      return;
+    }
+    const closed = { ...next, state: "stable", stateChangedAt: Date.now() };
+    await domain.putTask(closed);
+    writeJson(res, 200, { ok: true, state: "stable", task: closed });
+  };
+
+  /** Real agent-behaviour observability: per-(workspace, day) usage rollup + ratios. */
+  const stats = async (req, res) => {
+    const domain = await withDomain(res);
+    if (domain === void 0) return;
+    const params = readQuery(req);
+    const workspace = params.get("workspace") ?? void 0;
+    const rows = domain.usageRows(workspace);
+    const totals = { counts: {}, failures: 0, recall: {} };
+    for (const r of rows) {
+      for (const [k, v] of Object.entries(r.counts ?? {})) totals.counts[k] = (totals.counts[k] ?? 0) + v;
+      totals.failures += r.failures ?? 0;
+      for (const [k, v] of Object.entries(r.recall ?? {})) totals.recall[k] = (totals.recall[k] ?? 0) + v;
+    }
+    const ENGRAM = ["engram_store", "engram_recall", "engram_detail", "loom_store", "loom_recall", "loom_detail"];
+    const ESR = ["esr_task", "esr_node", "esr_close", "esr_link", "esr_gc"];
+    const sum = (keys) => keys.reduce((acc, k) => acc + (totals.counts[k] ?? 0), 0);
+    const memCalls = sum(ENGRAM);
+    const esrCalls = sum(ESR);
+    const calls = memCalls + esrCalls;
+    const queries = totals.recall.queries ?? 0;
+    const withHits = totals.recall.withHits ?? 0;
+    const hitsTotal = totals.recall.hitsTotal ?? 0;
+    const detailFollows = totals.recall.detailFollows ?? 0;
+    writeJson(res, 200, {
+      workspace: workspace ?? null,
+      byDay: rows.slice(-14).reverse(),
+      totals,
+      ratios: {
+        calls,
+        esrCalls,
+        memCalls,
+        esrRatio: calls > 0 ? +(esrCalls / calls).toFixed(4) : null,
+        recallHitRate: queries > 0 ? +(withHits / queries).toFixed(4) : null,
+        recallHitsPerQuery: queries > 0 ? +(hitsTotal / queries).toFixed(3) : null,
+        detailFollowRate: queries > 0 ? +(detailFollows / queries).toFixed(4) : null,
+      },
+    });
+  };
+
+  const make = (method, path, handler) => ({
+    kind: "exact",
+    path: `${API_PREFIX}${path}`,
+    method,
+    handler: (req, res) => guard(req, res, method, handler),
+  });
+
+  return [
+    make("GET", "/overview", overview),
+    make("GET", "/memories", memories),
+    make("GET", "/tasks", tasks),
+    make("GET", "/links", links),
+    make("GET", "/nodes", entities),
+    make("GET", "/stats", stats),
+    make("GET", "/config", readConfig),
+    make("POST", "/memories/archive", archive),
+    make("POST", "/memories/delete", remove),
+    make("POST", "/tasks", createTask),
+    make("POST", "/tasks/close", closeTask),
+    make("POST", "/gc", gcRun),
+  ];
+}

package/lib/capture.js

@@ -0,0 +1,208 @@
+/**
+ * dsh-engram: zero-LLM auto-capture from tool results.
+ *
+ * Watches `tools/result` (the DSH-native equivalent of symbolic-index's PostToolUse
+ * hook) and extracts meaningful events by pure pattern matching on tool name +
+ * arguments. No model call, no embeddings — just deterministic extractors,
+ * in-memory rate limiting, and exact-duplicate dedup at the store layer.
+ *
+ * Extractors (default on):
+ *   - git milestones via bash (commit with an -m subject / merge / rebase /
+ *     branch / tag / cherry-pick). Pure plumbing (`push`, `stash`, `status`)
+ *     is deliberately NOT captured: those are operational echoes, not lasting
+ *     decisions, and would only drown the memory pool and the [ENGRAM] index.
+ *   - writes/edits to significant config & doc paths
+ *   - repeated tool errors (error signal, deduped by message)
+ * symbolic-index's own insight: one file edit is noise; accumulated edits and rare
+ * git milestones are signal. Low-signal entries stay out of the [ENGRAM] index
+ * until they accumulate recall hits.
+ */
+
+import { workspaceKey as workspaceKeyOf } from "./util.js";
+
+const GIT_MILESTONE_SIGNAL = 0.5;
+const GIT_COMMIT_SIGNAL = 0.55;
+
+/** Git operations that carry lasting meaning (milestones). */
+const GIT_OPS = [
+  // commit: only with an explicit -m subject — that's the semantic content.
+  { kind: "commit", pattern: /\bgit\s+commit\b/, text: (_cmd) => gitSubject(_cmd) },
+  { kind: "milestone", pattern: /\bgit\s+merge\b/, text: (cmd) => `git merge: ${headLine(cmd)}` },
+  { kind: "milestone", pattern: /\bgit\s+rebase\b/, text: (cmd) => `git rebase: ${headLine(cmd)}` },
+  { kind: "milestone", pattern: /\bgit\s+cherry-pick\b/, text: (cmd) => `git cherry-pick: ${headLine(cmd)}` },
+  { kind: "milestone", pattern: /\bgit\s+tag\b/, text: (cmd) => `git tag: ${headLine(cmd)}` },
+  { kind: "milestone", pattern: /\bgit\s+checkout\s+-b\s+(\S+)/, text: (_cmd, m) => `git branch created: ${m[1]}` },
+];
+
+/**
+ * Extract the `-m "subject"` (or -m 'subject') from a commit command.
+ * Returns null when there is no written commit message — a `git commit` run
+ * via an editor, `--amend`, or an un-messaged commit is an operational echo,
+ * not a memory. (The --amend/-a case for an already-reworded subject still
+ * carries its own -m, so it keeps working; silent commits are dropped.)
+ */
+function gitSubject(cmd) {
+  const m = cmd.match(/-m\s+["']([^"']{0,64})["']/i);
+  if (m) return `git commit: ${m[1]}`;
+  return null;
+}
+
+function headLine(cmd) {
+  return String(cmd).replace(/\s*\n+\s*/g, " ").trim().slice(0, 64);
+}
+
+/** Paths where a write is significant enough to remember (mirrors symbolic-index). */
+const SIGNIFICANT_PATH = [
+  /(^|\/)(AGENTS|CLAUDE|README|CHANGELOG|CONTRIBUTING)\.md$/i,
+  /(^|\/)package\.json$/i,
+  /(^|\/)tsconfig.*\.json$/i,
+  /(^|\/)biome\.json$/i,
+  /(^|\/)Dockerfile$/i,
+  /(^|\/)\.esr/i,
+  /(^|\/)\.engram/i,
+  /(^|\/)\.symbolic-index/i,
+  /docs\/.*\.(md|rst)$/i,
+];
+
+const EDIT_TOOLS = new Set(["write", "str_replace_editor", "edit"]);
+const READ_TOOLS = new Set(["read"]);
+/** Never capture our own noise or the explicit memory tools. */
+const OWN_TOOLS = new Set(["engram_store", "engram_recall", "engram_detail", "esr_task", "esr_close", "esr_link"]);
+
+/**
+ * Build the tools/result listener. `store` is the opened engram domain handle;
+ * `config.autoCapture*` control rate. Returns a handler (exec, result) => void
+ * (fire-and-forget — never blocks the tool pipeline, never throws).
+ * `stats` (optional) is a mutable {total, git, file, error} counter the GUI
+ * overview reads for capture observability.
+ */
+export function makeCaptureHandler(store, config, log, stats) {
+  const recent = new Set();
+  const perSession = new Map(); // sessionId -> count, to bound captures
+  let captures = 0;
+
+  return (exec, result) => {
+    try {
+      const name = String(exec?.name ?? "").toLowerCase();
+      if (name.length === 0 || OWN_TOOLS.has(name)) return;
+      const agent = exec?.agent;
+      if (agent === void 0) return;
+      const cwd = agent.session?.header?.cwd;
+      const sessionId = agent.session?.id;
+      if (cwd === void 0 || cwd.length === 0 || sessionId === void 0) return;
+
+      // per-session rate limit
+      const used = perSession.get(sessionId) ?? 0;
+      if (used >= config.autoCapturePerSession) return;
+      perSession.set(sessionId, used + 1);
+
+      if (captures >= (config.autoCaptureGlobalCap ?? 500)) return;
+      captures += 1;
+
+      const args = (exec.arguments ?? {});
+      const git = extractGit(name, args.command);
+      let entry = null;
+
+      if (git !== null) {
+        entry = { kind: "decision", text: git.text, signal: git.signal, tags: git.tags };
+      } else if (EDIT_TOOLS.has(name)) {
+        const path = String(args.path ?? args.file_path ?? args.filePath ?? "");
+        if (path.length > 0 && SIGNIFICANT_PATH.some((re) => re.test(path))) {
+          entry = { kind: "fact", text: `Edited ${path}`, signal: 0.3, tags: ["file", "edit", "auto-captured", `dir:${dirOf(path)}`] };
+        }
+      } else if (READ_TOOLS.has(name)) {
+        const path = String(args.path ?? args.file_path ?? args.filePath ?? "");
+        if (path.length > 0 && /(^|\/)(AGENTS|CLAUDE)\.md$/i.test(path)) {
+          entry = { kind: "fact", text: `Read ${path}`, signal: 0.3, tags: ["file", "read", "config", "auto-captured"] };
+        }
+      } else if (result?.isError === true) {
+        const msg = errorHead(result);
+        if (msg !== null) {
+          entry = { kind: "error", text: `${name} failed: ${msg}`, signal: 0.25, tags: ["error", "auto-captured"] };
+        }
+      }
+
+      if (entry === null) return;
+      if (stats) {
+        stats.total += 1;
+        if (entry.kind === "decision") stats.git += 1;
+        else if (entry.kind === "error") stats.error += 1;
+        else stats.file += 1;
+      }
+
+      // exact-duplicate guard across the recent window (store re-dedups by hash anyway)
+      const key = `${entry.kind}|${entry.text}`;
+      if (recent.has(key)) return;
+      recent.add(key);
+      if (recent.size > 500) {
+        const first = recent.values().next().value;
+        recent.delete(first);
+      }
+
+      void store
+        .storeMemory(
+          {
+            workspace: workspaceKeyOf(cwd),
+            kind: entry.kind,
+            text: entry.text,
+            tags: entry.tags,
+            signal: entry.signal,
+            sessionId,
+            seq: agent.session.events?.length ?? 0,
+          },
+          config,
+        )
+        .then(() => {})
+        .catch((error) => log?.warn?.(`engram auto-capture failed: ${String(error)}`));
+    } catch (error) {
+      // fully contained — a capture bug must never disturb the tool pipeline
+      log?.warn?.(`engram auto-capture threw: ${String(error)}`);
+    }
+  };
+}
+
+function extractGit(name, command) {
+  if (name !== "bash") return null;
+  if (typeof command !== "string" || command.length === 0) return null;
+  for (const op of GIT_OPS) {
+    const m = command.match(op.pattern);
+    if (m) {
+      try {
+        const text = op.text(command, m);
+        if (text === null) return null; // git commit without an -m subject: drop
+        return {
+          text,
+          signal: op.kind === "commit" ? GIT_COMMIT_SIGNAL : GIT_MILESTONE_SIGNAL,
+          tags: ["git", "auto-captured", op.kind],
+        };
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}
+
+function errorHead(result) {
+  // canonical value or rendered content
+  const value = result?.value;
+  if (typeof value === "string" && value.length > 0) return value.slice(0, 80);
+  if (value !== null && typeof value === "object") {
+    const first = value.error ?? value.stderr ?? value.message ?? value.stdout;
+    if (typeof first === "string" && first.length > 0) return first.slice(0, 80);
+  }
+  const content = result?.content;
+  if (Array.isArray(content) && content.length > 0) {
+    for (const block of content) {
+      if (block?.type === "text" && typeof block.text === "string" && block.text.length > 0) {
+        return block.text.slice(0, 80);
+      }
+    }
+  }
+  return null;
+}
+
+function dirOf(path) {
+  const i = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return i > 0 ? path.slice(0, i) : ".";
+}