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
8.4 KB
Raw Blame
/**
 * A3 (t_e540b093): opt-in write-approval pending queue.
 *
 * With write_approval enabled, extracted signals are STAGED into
 * Brain/pending/ with byte-identical frontmatter (default off preserves the
 * direct-to-inbox path byte-for-byte). apply moves a staged file into
 * Brain/inbox/ unchanged (anchors + dedup hash preserved); reject moves it to
 * Brain/retired/ with retire-shaped frontmatter. Applying or rejecting a
 * missing / already-processed id is a typed error, never a silent no-op.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { brainDirs } from "../../../src/core/brain/paths.ts";
import { parseFrontmatter } from "../../../src/core/vault.ts";
import { routeExtractedFacts, type ExtractedFact } from "../../../src/core/brain/fact-extract.ts";
import {
  applyPending,
  listPending,
  PendingSignalNotFoundError,
  rejectPending,
  stagePendingSignal,
} from "../../../src/core/brain/pending.ts";
import type { DedupIndexEntry } from "../../../src/core/brain/dedup-hash.ts";

let vault: string;
let configHome: string;

const NOW = new Date("2026-07-18T12:00:00Z");

function makeVault(): string {
  const v = mkdtempSync(join(tmpdir(), "o2b-pending-vault-"));
  const cfg = mkdtempSync(join(tmpdir(), "o2b-pending-cfg-"));
  const configPath = join(cfg, "config.yaml");
  atomicWriteFileSync(configPath, `vault: ${v}\n`);
  bootstrapBrain(v, { configPath });
  toCleanup.push(v, cfg);
  return v;
}

const toCleanup: string[] = [];

beforeEach(() => {
  vault = makeVault();
  configHome = "";
});

afterEach(() => {
  for (const p of toCleanup.splice(0)) rmSync(p, { recursive: true, force: true });
  void configHome;
});

function names(dir: string): string[] {
  if (!existsSync(dir)) return [];
  return readdirSync(dir)
    .filter((f) => f.startsWith("sig-") && f.endsWith(".md"))
    .toSorted();
}

const URL_FACT: ExtractedFact = { family: "url", text: "https://techmeat.dev", line: 1 };

describe("routeExtractedFacts staging decision", () => {
  test("write_approval disabled writes to inbox (no pending dir touched)", () => {
    const res = routeExtractedFacts(vault, {
      facts: [URL_FACT],
      agent: "claude-dev-agent",
      now: NOW,
      sessionRef: "s#1",
      dedup: new Map<string, DedupIndexEntry>(),
      writeApprovalEnabled: false,
    });
    expect(res.created).toBe(1);
    expect(names(brainDirs(vault).inbox).length).toBe(1);
    expect(names(brainDirs(vault).pending).length).toBe(0);
  });

  test("write_approval enabled stages to pending, inbox stays empty", () => {
    const res = routeExtractedFacts(vault, {
      facts: [URL_FACT],
      agent: "claude-dev-agent",
      now: NOW,
      sessionRef: "s#1",
      dedup: new Map<string, DedupIndexEntry>(),
      writeApprovalEnabled: true,
    });
    expect(res.created).toBe(1);
    expect(names(brainDirs(vault).pending).length).toBe(1);
    expect(names(brainDirs(vault).inbox).length).toBe(0);
  });

  test("staged pending doc is byte-for-byte identical to the inbox doc", () => {
    // Same input routed to two fresh vaults: one to inbox (disabled), one to
    // pending (enabled). The documents must be identical byte-for-byte.
    const inboxVault = makeVault();
    routeExtractedFacts(inboxVault, {
      facts: [URL_FACT],
      agent: "claude-dev-agent",
      now: NOW,
      sessionRef: "s#1",
      dedup: new Map(),
      writeApprovalEnabled: false,
    });
    routeExtractedFacts(vault, {
      facts: [URL_FACT],
      agent: "claude-dev-agent",
      now: NOW,
      sessionRef: "s#1",
      dedup: new Map(),
      writeApprovalEnabled: true,
    });
    const inboxName = names(brainDirs(inboxVault).inbox)[0]!;
    const pendingName = names(brainDirs(vault).pending)[0]!;
    expect(pendingName).toBe(inboxName);
    const inboxDoc = readFileSync(join(brainDirs(inboxVault).inbox, inboxName), "utf8");
    const pendingDoc = readFileSync(join(brainDirs(vault).pending, pendingName), "utf8");
    expect(pendingDoc).toBe(inboxDoc);
  });
});

describe("stagePendingSignal", () => {
  test("writes the identical frontmatter document into Brain/pending/", () => {
    const res = stagePendingSignal(vault, {
      topic: "fact-url",
      signal: "positive",
      agent: "claude-dev-agent",
      principle: "https://techmeat.dev",
      created_at: "2026-07-18T12:00:00Z",
      date: "2026-07-18",
      slug: "fact-url",
      source_type: "extracted",
      dedup_hash: "abc123",
    });
    expect(res.id).toBe("sig-2026-07-18-fact-url");
    expect(existsSync(res.path)).toBe(true);
    expect(res.path.startsWith(brainDirs(vault).pending)).toBe(true);
  });
});

describe("listPending", () => {
  test("returns the staged signals with their coordinates", () => {
    stagePendingSignal(vault, {
      topic: "fact-url",
      signal: "positive",
      agent: "claude-dev-agent",
      principle: "https://techmeat.dev",
      created_at: "2026-07-18T12:00:00Z",
      date: "2026-07-18",
      slug: "fact-url",
      source_type: "extracted",
      dedup_hash: "abc123",
    });
    const items = listPending(vault);
    expect(items.length).toBe(1);
    expect(items[0]!.id).toBe("sig-2026-07-18-fact-url");
    expect(items[0]!.signal.principle).toBe("https://techmeat.dev");
  });

  test("empty (or absent) pending dir lists nothing", () => {
    expect(listPending(vault)).toEqual([]);
  });
});

describe("applyPending", () => {
  test("moves a staged signal into inbox unchanged (anchors + dedup hash)", () => {
    // Stage a signal carrying an entity anchor body + dedup hash.
    const staged = stagePendingSignal(vault, {
      topic: "fact-url",
      signal: "positive",
      agent: "claude-dev-agent",
      principle: "https://techmeat.dev",
      created_at: "2026-07-18T12:00:00Z",
      date: "2026-07-18",
      slug: "fact-url",
      source_type: "extracted",
      dedup_hash: "hash-xyz",
      raw: "entities: ent-projects-techmeat",
    });
    const before = readFileSync(staged.path, "utf8");

    const applied = applyPending(vault, staged.id);
    expect(applied.id).toBe(staged.id);
    expect(applied.path.startsWith(brainDirs(vault).inbox)).toBe(true);

    // Pending file gone, inbox file present, bytes preserved verbatim.
    expect(existsSync(staged.path)).toBe(false);
    const after = readFileSync(applied.path, "utf8");
    expect(after).toBe(before);
    expect(after).toContain("dedup_hash: hash-xyz");
    expect(after).toContain("entities: ent-projects-techmeat");
  });

  test("applying a missing id is a typed error, not a no-op", () => {
    expect(() => applyPending(vault, "sig-2026-07-18-nope")).toThrow(PendingSignalNotFoundError);
  });

  test("applying twice is a typed error the second time", () => {
    const staged = stagePendingSignal(vault, {
      topic: "fact-url",
      signal: "positive",
      agent: "claude-dev-agent",
      principle: "https://techmeat.dev",
      created_at: "2026-07-18T12:00:00Z",
      date: "2026-07-18",
      slug: "fact-url",
    });
    applyPending(vault, staged.id);
    expect(() => applyPending(vault, staged.id)).toThrow(PendingSignalNotFoundError);
  });
});

describe("rejectPending", () => {
  test("moves a staged signal to retired with retire-shaped frontmatter", () => {
    const staged = stagePendingSignal(vault, {
      topic: "fact-url",
      signal: "positive",
      agent: "claude-dev-agent",
      principle: "https://techmeat.dev",
      created_at: "2026-07-18T12:00:00Z",
      date: "2026-07-18",
      slug: "fact-url",
    });
    const rejected = rejectPending(vault, staged.id, "not useful", { now: NOW });
    expect(existsSync(staged.path)).toBe(false);
    expect(rejected.path.startsWith(brainDirs(vault).retired)).toBe(true);

    const [meta] = parseFrontmatter(rejected.path);
    expect(meta["_status"]).toBe("retired");
    expect(meta["retired_at"]).toBe(NOW.toISOString());
    expect(meta["retired_reason"]).toBe("not useful");
    // The original signal content is preserved for the audit trail.
    expect(meta["principle"]).toBe("https://techmeat.dev");
  });

  test("rejecting a missing id is a typed error", () => {
    expect(() => rejectPending(vault, "sig-2026-07-18-nope", "x")).toThrow(
      PendingSignalNotFoundError,
    );
  });
});