Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
13.9 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";

import { emitRecallTelemetry, RECALL_CHANNEL } from "../../src/core/brain/recall-telemetry.ts";
import { assessRecallAdequacy } from "../../src/core/brain/recall-adequacy.ts";
import {
  normalizeQueryTerms,
  recordRecallAdequacyDemand,
} from "../../src/core/brain/query-demand.ts";
import {
  listGapTasks,
  promoteGapsToTasks,
  GAP_SOURCE_ADEQUACY,
  GAP_SOURCE_TELEMETRY,
  GAP_TASK_CLOSED_RETENTION_MS,
  GAP_TASK_KIND,
  GAP_TASK_STATUS_CLOSED,
  GAP_TASK_STATUS_OPEN,
  GAP_TASKS_MAX_NOTES,
} from "../../src/core/brain/gaps/gap-loop.ts";
import { brainGapTasksDir } from "../../src/core/brain/paths.ts";
import { RETRIEVAL_DEGRADATION } from "../../src/core/search/retrieval-trail.ts";
import { writeFrontmatterAtomic } from "../../src/core/vault.ts";
import { homeEnv } from "../helpers/platform.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

const HOOKS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "hooks");

let vault: string;
let configHome: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-hook-gap-vault-"));
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
  configHome = mkdtempSync(join(tmpdir(), "o2b-hook-gap-cfg-"));
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
  rmSync(configHome, { recursive: true, force: true });
});

interface RunResult {
  readonly stdout: string;
  readonly exit: number;
}

async function runHook(
  name: string,
  payload: unknown,
  env: Record<string, string> = {},
): Promise<RunResult> {
  const inherited: Record<string, string> = {
    PATH: process.env["PATH"] ?? "",
    ...homeEnv(configHome),
  };
  const proc = Bun.spawn(["bun", "run", join(HOOKS_DIR, `${name}.ts`)], {
    stdin: "pipe",
    stdout: "pipe",
    stderr: "pipe",
    env: { ...inherited, ...env },
  });
  proc.stdin.write(JSON.stringify(payload));
  await proc.stdin.end();
  const stdout = await new Response(proc.stdout).text();
  const exit = await proc.exited;
  return { stdout, exit };
}

function seedGap(topic: string, times: number): void {
  for (let i = 0; i < times; i++) {
    emitRecallTelemetry(vault, {
      host: "test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "empty",
      durationMs: 0,
      resultCount: 0,
      gaps: [topic],
      createdAt: `2026-05-2${i}T09:00:00.000Z`,
    });
  }
}

/** The bucket key `normalizeQueryTerms` derives for {@link ADEQUACY_QUERY}. */
const ADEQUACY_QUERY = "widget calibration procedure";
const ADEQUACY_BUCKET = normalizeQueryTerms(ADEQUACY_QUERY).join(" ");

/** Seed a recurring weak-recall bucket (signals-that-survive, unit 6). */
function seedUnmetRecall(times: number): void {
  const verdict = assessRecallAdequacy({ matchQuality: 0.4, scores: [0.9] });
  for (let i = 0; i < times; i++) {
    recordRecallAdequacyDemand(vault, {
      query: ADEQUACY_QUERY,
      verdict,
      at: `2026-05-1${i}T09:00:00.000Z`,
    });
  }
}

describe("gap-promote hook (SessionEnd)", () => {
  test("flag off is a no-op: no gap-task notes written", async () => {
    seedGap("alpha topic", 3);
    const r = await runHook("gap-promote", { hook_event_name: "SessionEnd" }, { VAULT_DIR: vault });
    expect(r.exit).toBe(0);
    expect(existsSync(join(vault, "Brain", "gap-tasks"))).toBe(false);
  });

  test("flag off is a no-op for the adequacy source too", async () => {
    seedUnmetRecall(4);
    const r = await runHook("gap-promote", { hook_event_name: "SessionEnd" }, { VAULT_DIR: vault });
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
    expect(existsSync(join(vault, "Brain", "gap-tasks"))).toBe(false);
    expect(listGapTasks(vault)).toHaveLength(0);
  });

  test("flag on promotes a recurring weak-recall bucket to a gap task", async () => {
    seedUnmetRecall(4);
    const run = await runHook(
      "gap-promote",
      { hook_event_name: "SessionEnd" },
      {
        VAULT_DIR: vault,
        OPEN_SECOND_BRAIN_GAP_LOOP_ENABLED: "true",
        OPEN_SECOND_BRAIN_GAP_LOOP_THRESHOLD: "3",
      },
    );
    expect(run.exit).toBe(0);
    const open = listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN });
    expect(open.map((t) => t.topic)).toContain(ADEQUACY_BUCKET);
    expect(open.map((t) => t.source)).toContain(GAP_SOURCE_ADEQUACY);
  });

  test("flag on promotes a recurring gap to an open gap-task note", async () => {
    seedGap("alpha topic", 3);
    const run = await runHook(
      "gap-promote",
      { hook_event_name: "SessionEnd" },
      {
        VAULT_DIR: vault,
        OPEN_SECOND_BRAIN_GAP_LOOP_ENABLED: "true",
        OPEN_SECOND_BRAIN_GAP_LOOP_THRESHOLD: "2",
      },
    );
    expect(run.exit).toBe(0);
    const open = listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN });
    expect(open.map((t) => t.topic)).toContain("alpha topic");
  });
});

describe("gap-promote hook audit line and auto-close", () => {
  /** Every `gap_loop_run` details object the hook appended, oldest first. */
  function auditDetails(): ReadonlyArray<Record<string, unknown>> {
    const dir = join(vault, ".open-second-brain", "hook-audit");
    if (!existsSync(dir)) return [];
    return readdirSync(dir)
      .toSorted()
      .flatMap((name) => readFileSync(join(dir, name), "utf8").split("\n"))
      .filter((line) => line.trim().length > 0)
      .map((line) => JSON.parse(line) as { action?: string; details?: Record<string, unknown> })
      .filter((record) => record.action === "gap_loop_run")
      .map((record) => record.details ?? {});
  }

  /** Write one gap-task note directly, bypassing the hook's mint budget. */
  function writeTask(
    key: string,
    status: string,
    opts: { closedAt?: string; topic?: string } = {},
  ): void {
    const topic = opts.topic ?? key;
    writeFrontmatterAtomic(
      join(brainGapTasksDir(vault), `${key}.md`),
      {
        kind: GAP_TASK_KIND,
        gap_key: key,
        gap_topic: topic,
        gap_source: GAP_SOURCE_TELEMETRY,
        status,
        occurrences: "3",
        created_at: "2026-01-01T00:00:00.000Z",
        ...(opts.closedAt !== undefined
          ? { closed_at: opts.closedAt, closed_reason: "recalled" }
          : {}),
      },
      // The body repeats the topic, exactly as a minted note does: that is
      // why the auto-close gate excludes gap-task notes by path.
      `Recurring recall gap for ${topic}.`,
      { vaultForRelativePath: vault, overwrite: true },
    );
  }

  /** A plain vault note that genuinely covers `topic`, outside the gap area. */
  function writeCoveringNote(topic: string): void {
    writeFrontmatterAtomic(
      join(vault, "notes", "coverage.md"),
      { title: topic },
      `This note documents ${topic} end to end. The ${topic} steps are recorded here.`,
      { vaultForRelativePath: vault, overwrite: true },
    );
  }

  const FLAG_ON = {
    OPEN_SECOND_BRAIN_GAP_LOOP_ENABLED: "true",
    OPEN_SECOND_BRAIN_GAP_LOOP_THRESHOLD: "2",
  } as const;

  test("carries every count the promotion returns, not just the promotions", async () => {
    seedGap("alpha topic", 3);
    const run = await runHook(
      "gap-promote",
      { hook_event_name: "SessionEnd" },
      { VAULT_DIR: vault, ...FLAG_ON },
    );
    expect(run.exit).toBe(0);
    const [details] = auditDetails();
    expect(details).toBeDefined();
    expect(Object.keys(details ?? {}).toSorted()).toEqual([
      "capped",
      "closed",
      "kept",
      "promoted",
      "pruned",
      "skipped",
    ]);
    expect(details?.["promoted"]).toBe(1);
    expect(details?.["pruned"]).toBe(0);
    expect(details?.["capped"]).toBe(0);
  });

  test("reports a closed task removed under the retention window as pruned", async () => {
    const stale = new Date(Date.now() - GAP_TASK_CLOSED_RETENTION_MS - 60_000).toISOString();
    writeTask("gap-stale", GAP_TASK_STATUS_CLOSED, { closedAt: stale });
    const run = await runHook(
      "gap-promote",
      { hook_event_name: "SessionEnd" },
      { VAULT_DIR: vault, ...FLAG_ON },
    );
    expect(run.exit).toBe(0);
    const [details] = auditDetails();
    expect(details?.["pruned"]).toBe(1);
    expect(existsSync(join(brainGapTasksDir(vault), "gap-stale.md"))).toBe(false);
  });

  test("reports a refusal at the cap instead of an unremarkable run", async () => {
    // Closed-but-recent fillers fill the directory without giving the
    // auto-close pass anything to recall.
    const recent = new Date().toISOString();
    for (let i = 0; i < GAP_TASKS_MAX_NOTES; i++) {
      writeTask(`gap-filler-${i}`, GAP_TASK_STATUS_CLOSED, { closedAt: recent });
    }
    seedGap("alpha topic", 3);
    const run = await runHook(
      "gap-promote",
      { hook_event_name: "SessionEnd" },
      { VAULT_DIR: vault, ...FLAG_ON },
    );
    expect(run.exit).toBe(0);
    const [details] = auditDetails();
    expect(details?.["capped"]).toBe(1);
    expect(details?.["promoted"]).toBe(0);
    expect(listGapTasks(vault)).toHaveLength(GAP_TASKS_MAX_NOTES);
  });

  // The two tests below drive the WHOLE hook, not `autoCloseRecalledGaps`
  // in isolation, because the fault they exist to catch lives in the
  // wiring rather than in either piece. The gate takes a retriever of
  // `(topic, admits)`; a plain one-argument `RecallRetriever` is
  // structurally assignable to that type, so passing one type-checks
  // cleanly, ignores the membership rule, returns the gap-task note
  // itself and makes the gate throw - into the hook's outer catch, which
  // left every run doing nothing. Only an end-to-end run can tell the
  // difference: a core-level test supplies its own retriever and so can
  // never observe which one the hook actually passes.
  const COVERED_TOPIC = "widget calibration procedure";

  test("closes a gap task the vault now covers outside the gap area", async () => {
    writeTask("gap-covered", GAP_TASK_STATUS_OPEN, { topic: COVERED_TOPIC });
    writeCoveringNote(COVERED_TOPIC);
    const run = await runHook(
      "gap-promote",
      { hook_event_name: "SessionEnd" },
      { VAULT_DIR: vault, ...FLAG_ON },
    );
    expect(run.exit).toBe(0);
    const [details] = auditDetails();
    expect(details).toBeDefined();
    expect(details?.["closed"]).toBe(1);
    expect(details?.["kept"]).toBe(0);
    expect(listGapTasks(vault, { status: GAP_TASK_STATUS_CLOSED }).map((t) => t.key)).toEqual([
      "gap-covered",
    ]);
  });

  test("names the recall's degradation codes on the audit line, local only", async () => {
    // Semantic search on with no embedding provider configured: the gap
    // recall's semantic lane cannot run, and the trail says so. The codes
    // must reach the operator through the audit line, not vanish in the
    // hook.
    const configPath = join(configHome, "gap-config.yaml");
    writeFileSync(configPath, `vault: ${vault}\nsearch_semantic_enabled: true\n`);
    writeTask("gap-uncovered", GAP_TASK_STATUS_OPEN, { topic: COVERED_TOPIC });
    const run = await runHook(
      "gap-promote",
      { hook_event_name: "SessionEnd" },
      { VAULT_DIR: vault, OPEN_SECOND_BRAIN_CONFIG: configPath, ...FLAG_ON },
    );
    expect(run.exit).toBe(0);
    const [details] = auditDetails();
    const raw = details?.["retrieval_degraded"];
    expect(Array.isArray(raw)).toBe(true);
    const codes = raw as ReadonlyArray<string>;
    expect(codes.length).toBeGreaterThan(0);
    const known: ReadonlyArray<string> = Object.values(RETRIEVAL_DEGRADATION);
    for (const code of codes) expect(known).toContain(code);
    expect(new Set(codes).size).toBe(codes.length);
    // Reported, not judged: the task stays open exactly as it would have.
    expect(details?.["kept"]).toBe(1);
  });

  test("keeps a gap task whose only match is its own note", async () => {
    writeTask("gap-uncovered", GAP_TASK_STATUS_OPEN, { topic: COVERED_TOPIC });
    const run = await runHook(
      "gap-promote",
      { hook_event_name: "SessionEnd" },
      { VAULT_DIR: vault, ...FLAG_ON },
    );
    expect(run.exit).toBe(0);
    const [details] = auditDetails();
    expect(details?.["closed"]).toBe(0);
    expect(details?.["kept"]).toBe(1);
    expect(listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN }).map((t) => t.key)).toEqual([
      "gap-uncovered",
    ]);
  });
});

describe("gap-agenda hook (SessionStart)", () => {
  test("flag off is a silent no-op: no stdout", async () => {
    seedGap("alpha topic", 3);
    promoteGapsToTasks(vault, { threshold: 2, now: new Date("2026-06-01T12:00:00.000Z") });
    const r = await runHook(
      "gap-agenda",
      { hook_event_name: "SessionStart" },
      { VAULT_DIR: vault },
    );
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
  });

  test("flag on injects an open-gap agenda as additionalContext", async () => {
    seedGap("alpha topic", 3);
    promoteGapsToTasks(vault, { threshold: 2, now: new Date("2026-06-01T12:00:00.000Z") });
    const r = await runHook(
      "gap-agenda",
      { hook_event_name: "SessionStart" },
      { VAULT_DIR: vault, OPEN_SECOND_BRAIN_GAP_LOOP_ENABLED: "true" },
    );
    expect(r.exit).toBe(0);
    const out = JSON.parse(r.stdout);
    expect(out.hookSpecificOutput.hookEventName).toBe("SessionStart");
    expect(out.hookSpecificOutput.additionalContext).toContain("alpha topic");
    expect(out.hookSpecificOutput.additionalContext).toContain("[open]");
  });

  test("flag on stays silent when there are no open gap tasks", async () => {
    const r = await runHook(
      "gap-agenda",
      { hook_event_name: "SessionStart" },
      { VAULT_DIR: vault, OPEN_SECOND_BRAIN_GAP_LOOP_ENABLED: "true" },
    );
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
  });
});