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
7.6 KB
Raw Blame
/**
 * Write-session store (Agent Write Contract Suite, t_bc36a8a2).
 *
 * One JSON file per session under `Brain/.sessions/write/`, snake_case
 * on disk, lazy TTL on read, sweep for terminal/expired files.
 */

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

import {
  allocateWriteSessionId,
  createWriteSession,
  deleteWriteSession,
  isWriteSessionId,
  listWriteSessions,
  readWriteSession,
  saveWriteSession,
  sweepWriteSessions,
  writeSessionDir,
  writeSessionPath,
} from "../../../../src/core/brain/write-session/store.ts";
import type { WriteSessionRecord } from "../../../../src/core/brain/write-session/types.ts";

let tmp: string;
let vault: string;

const NOW = "2026-06-04T10:00:00Z";
const LATER = "2026-06-05T11:00:00Z";

function record(id: string, over: Partial<WriteSessionRecord> = {}): WriteSessionRecord {
  return {
    id,
    kind: "artifact",
    status: "needs-llm-step",
    step: "artifact",
    agent: "fixture-agent",
    createdAt: NOW,
    updatedAt: NOW,
    expiresAt: "2026-06-05T10:00:00Z",
    attempts: 0,
    retryCap: 3,
    targetPath: "Brain/notes/fixture.md",
    intent: "create",
    requireReview: false,
    prompt: "Write the fixture note.",
    schemaType: null,
    topic: null,
    personas: [],
    responses: {},
    pendingArtifact: null,
    lastErrors: [],
    failReason: null,
    ...over,
  };
}

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-ws-store-"));
  vault = join(tmp, "vault");
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

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

test("writeSessionDir nests under Brain/.sessions/write", () => {
  expect(writeSessionDir(vault)).toBe(join(vault, "Brain", ".sessions", "write"));
});

test("session id grammar accepts allocated ids and rejects traversal shapes", () => {
  const id = allocateWriteSessionId(vault, NOW);
  expect(isWriteSessionId(id)).toBe(true);
  expect(id.startsWith("ws-")).toBe(true);
  expect(isWriteSessionId("../../etc/passwd")).toBe(false);
  expect(isWriteSessionId("ws-UPPER")).toBe(false);
  expect(isWriteSessionId("")).toBe(false);
  expect(() => writeSessionPath(vault, "../escape")).toThrow(/session id/);
});

test("createWriteSession claims ids exclusively - same-second creates never collide", () => {
  const a = createWriteSession(vault, NOW, (id) => record(id));
  const b = createWriteSession(vault, NOW, (id) => record(id));
  expect(a.id).not.toBe(b.id);
  expect(readWriteSession(vault, a.id, NOW).session).not.toBeNull();
  expect(readWriteSession(vault, b.id, NOW).session).not.toBeNull();
});

test("a structurally incomplete record reads as an error probe (fail closed)", () => {
  const id = allocateWriteSessionId(vault, NOW);
  mkdirSync(writeSessionDir(vault), { recursive: true });
  writeFileSync(
    writeSessionPath(vault, id),
    JSON.stringify({ id, kind: "artifact", status: "needs-llm-step" }),
  );
  const probe = readWriteSession(vault, id, NOW);
  expect(probe.session).toBeNull();
  expect(probe.error).toMatch(/malformed/);
});

test("sweep removes *.json files whose names violate the id grammar", () => {
  mkdirSync(writeSessionDir(vault), { recursive: true });
  writeFileSync(join(writeSessionDir(vault), "GARBAGE.json"), "{}");
  const swept = sweepWriteSessions(vault, NOW);
  expect(swept.removed).toBe(1);
  expect(existsSync(join(writeSessionDir(vault), "GARBAGE.json"))).toBe(false);
});

test("allocateWriteSessionId never collides with an existing session file", () => {
  const first = allocateWriteSessionId(vault, NOW);
  saveWriteSession(vault, record(first));
  const second = allocateWriteSessionId(vault, NOW);
  expect(second).not.toBe(first);
  expect(isWriteSessionId(second)).toBe(true);
});

test("save + read round-trips a record with snake_case on disk", () => {
  const id = allocateWriteSessionId(vault, NOW);
  saveWriteSession(
    vault,
    record(id, {
      kind: "panel",
      step: "persona:technical",
      topic: "adopt bun",
      personas: [{ slug: "technical", lens: "technical feasibility", prompt: "Assess it." }],
      responses: { "persona:technical": "fine" },
      lastErrors: [{ code: "frontmatter-missing", path: "frontmatter", message: "absent" }],
    }),
  );
  const raw = JSON.parse(readFileSync(writeSessionPath(vault, id), "utf8"));
  expect(raw["created_at"]).toBe(NOW);
  expect(raw["retry_cap"]).toBe(3);
  expect(raw["target_path"]).toBe("Brain/notes/fixture.md");
  expect(raw["require_review"]).toBe(false);
  expect(raw["last_errors"][0]["code"]).toBe("frontmatter-missing");

  const probe = readWriteSession(vault, id, NOW);
  expect(probe.error).toBeNull();
  expect(probe.session!.kind).toBe("panel");
  expect(probe.session!.step).toBe("persona:technical");
  expect(probe.session!.personas[0]!.lens).toBe("technical feasibility");
  expect(probe.session!.responses["persona:technical"]).toBe("fine");
});

test("missing session reads as a null probe without error", () => {
  const probe = readWriteSession(vault, "ws-2026-06-04-missing", NOW);
  expect(probe.session).toBeNull();
  expect(probe.error).toBeNull();
});

test("corrupted session file reads as an error probe, never throws", () => {
  const id = allocateWriteSessionId(vault, NOW);
  mkdirSync(writeSessionDir(vault), { recursive: true });
  writeFileSync(writeSessionPath(vault, id), "{broken");
  const probe = readWriteSession(vault, id, NOW);
  expect(probe.session).toBeNull();
  expect(probe.error).toMatch(/not valid JSON/);
});

test("lazy TTL: an expired non-terminal session reads as failed/expired", () => {
  const id = allocateWriteSessionId(vault, NOW);
  saveWriteSession(vault, record(id, { status: "needs-correction" }));
  const fresh = readWriteSession(vault, id, NOW);
  expect(fresh.session!.status).toBe("needs-correction");
  const expired = readWriteSession(vault, id, LATER);
  expect(expired.session!.status).toBe("failed");
  expect(expired.session!.failReason).toBe("expired");
});

test("lazy TTL leaves terminal sessions untouched", () => {
  const id = allocateWriteSessionId(vault, NOW);
  saveWriteSession(vault, record(id, { status: "done" }));
  const probe = readWriteSession(vault, id, LATER);
  expect(probe.session!.status).toBe("done");
  expect(probe.session!.failReason).toBeNull();
});

test("listWriteSessions returns sessions sorted by created_at then id", () => {
  expect(listWriteSessions(vault, NOW)).toEqual([]);
  const a = allocateWriteSessionId(vault, NOW);
  saveWriteSession(vault, record(a, { createdAt: "2026-06-04T09:00:00Z" }));
  const b = allocateWriteSessionId(vault, NOW);
  saveWriteSession(vault, record(b, { createdAt: "2026-06-04T08:00:00Z" }));
  const sessions = listWriteSessions(vault, NOW);
  expect(sessions.map((s) => s.id)).toEqual([b, a]);
});

test("delete removes the file; sweep removes terminal and expired sessions", () => {
  const done = allocateWriteSessionId(vault, NOW);
  saveWriteSession(vault, record(done, { status: "done" }));
  const expired = allocateWriteSessionId(vault, NOW);
  saveWriteSession(vault, record(expired, { status: "needs-llm-step" }));
  const live = allocateWriteSessionId(vault, NOW);
  saveWriteSession(vault, record(live, { expiresAt: "2026-06-06T10:00:00Z" }));

  deleteWriteSession(vault, done);
  expect(existsSync(writeSessionPath(vault, done))).toBe(false);

  const swept = sweepWriteSessions(vault, LATER);
  expect(swept.removed).toBe(1);
  expect(swept.kept).toBe(1);
  expect(existsSync(writeSessionPath(vault, expired))).toBe(false);
  expect(existsSync(writeSessionPath(vault, live))).toBe(true);
});