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
16.6 KB
Raw Blame
/**
 * Orchestrator tests for `o2b brain import-session`.
 *
 * Validates the cross-cutting behaviours: marker + tool_use replay
 * extraction, dedup by hash, dedup on re-run, directory walk,
 * autodetect failure, and the dry-run mode.
 */

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

import { brainDirs } from "../../src/core/brain/paths.ts";
import { DEFAULT_BRAIN_CONFIG_YAML } from "../../src/core/brain/config-template.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { importSession, importSessionPath } from "../../src/core/brain/sessions/import.ts";
import { SessionImportError } from "../../src/core/brain/sessions/types.ts";
import { describeSessionRecall } from "../../src/core/brain/session-recall.ts";

const CLAUDE = resolve("tests/fixtures/sessions/claude-minimal.jsonl");
const CODEX = resolve("tests/fixtures/sessions/codex-minimal.jsonl");
const HERMES = resolve("tests/fixtures/sessions/hermes-minimal.jsonl");
const OPENCODE = resolve("tests/fixtures/sessions/opencode-minimal.jsonl");

let tmp: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-import-"));
  const dirs = brainDirs(tmp);
  for (const d of [
    dirs.brain,
    dirs.inbox,
    dirs.processed,
    dirs.preferences,
    dirs.retired,
    dirs.log,
    dirs.snapshots,
  ]) {
    mkdirSync(d, { recursive: true });
  }
  atomicWriteFileSync(join(dirs.brain, "_brain.yaml"), DEFAULT_BRAIN_CONFIG_YAML);
});

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

describe("importSession", () => {
  test("creates signals from @osb markers in claude user messages", async () => {
    const res = await importSession(tmp, CLAUDE, { agent: "test" });
    expect(res.format).toBe("claude");
    expect(res.signals_created).toBeGreaterThan(0);
  });

  test("creates signals from tool_use brain_feedback replays", async () => {
    const res = await importSession(tmp, CLAUDE, { agent: "test" });
    // The fixture has 1 marker AND 1 tool_use with the same NORMALISED
    // payload-but-different `principle` text. They are distinct
    // dedup_hashes, so we expect 2 signals.
    expect(res.signals_created).toBe(2);
    expect(res.tool_replays).toBe(1);
  });

  test("dedups when marker and tool_use have identical payloads", async () => {
    // Build a fixture where both have the same principle string.
    const fixturePath = join(tmp, "matched.jsonl");
    writeFileSync(
      fixturePath,
      [
        '{"type":"queue-operation","timestamp":"2026-05-16T10:00:00.000Z","sessionId":"x"}',
        '{"parentUuid":null,"sessionId":"x","entrypoint":"sdk-cli","type":"user","message":{"role":"user","content":"@osb feedback negative topic=match principle=\\"same-principle\\""},"uuid":"u1","timestamp":"2026-05-16T10:00:01.000Z"}',
        '{"parentUuid":"u1","sessionId":"x","entrypoint":"sdk-cli","type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"tu-1","name":"brain_feedback","input":{"topic":"match","signal":"negative","principle":"same-principle"}}]},"uuid":"a1","timestamp":"2026-05-16T10:00:02.000Z"}',
        "",
      ].join("\n"),
    );
    const res = await importSession(tmp, fixturePath, { agent: "test" });
    expect(res.signals_created).toBe(1);
    expect(res.signals_deduped).toBe(1);
  });

  test("imports only feedback markers, ignoring loop and set kinds", async () => {
    const fixturePath = join(tmp, "kinds.jsonl");
    const userText =
      "@osb feedback negative topic=kept principle=p\\n" +
      "@osb loop follow up on vendor id=vendor\\n" +
      "@osb set note=Roadmap field=completion value=65";
    writeFileSync(
      fixturePath,
      [
        '{"parentUuid":null,"sessionId":"k","entrypoint":"sdk-cli","type":"user","message":{"role":"user","content":"' +
          userText +
          '"},"uuid":"u1","timestamp":"2026-05-16T10:00:01.000Z"}',
        "",
      ].join("\n"),
    );
    const res = await importSession(tmp, fixturePath, { agent: "test" });
    // Only the feedback marker becomes a signal.
    expect(res.signals_created).toBe(1);
    const inbox = readdirSync(brainDirs(tmp).inbox).filter((n) => n.startsWith("sig-"));
    expect(inbox.length).toBe(1);
    expect(readFileSync(join(brainDirs(tmp).inbox, inbox[0]!), "utf8")).toMatch(/topic: kept/);
  });

  test("is idempotent on re-run (zero new signals)", async () => {
    const first = await importSession(tmp, CLAUDE, { agent: "test" });
    expect(first.signals_created).toBeGreaterThan(0);
    const second = await importSession(tmp, CLAUDE, { agent: "test" });
    expect(second.signals_created).toBe(0);
    expect(second.signals_deduped).toBe(first.signals_created);
  });

  test("persists a portable session_ref, not the absolute session-file path", async () => {
    // The session fixture lives OUTSIDE the vault at an absolute path.
    // A synced signal must not carry that machine-local path in its
    // provenance (Syncthing peers on Mac/Android cannot resolve it):
    // the ref keys the session by basename, matching the recall DAG id.
    const res = await importSession(tmp, CLAUDE, { agent: "test" });
    expect(res.signals_created).toBeGreaterThan(0);

    const inbox = brainDirs(tmp).inbox;
    const files = readdirSync(inbox).filter((n) => n.startsWith("sig-"));
    expect(files.length).toBeGreaterThan(0);

    const absDir = dirname(CLAUDE);
    for (const name of files) {
      const text = readFileSync(join(inbox, name), "utf8");
      // No absolute host directory of the session file leaked in.
      expect(text).not.toContain(absDir);
      expect(text).not.toContain(CLAUDE);
      // The portable identity (basename#turn) is present instead, in both
      // the `source` wikilink and the `session_ref` field.
      expect(text).toContain(`[[${basename(CLAUDE)}#`);
      expect(text).toContain(`session_ref: "${basename(CLAUDE)}#`);
    }
  });

  test("dry-run does not write signals", async () => {
    const res = await importSession(tmp, CLAUDE, {
      agent: "test",
      dryRun: true,
    });
    expect(res.signals_created).toBe(0);
    const inbox = readdirSync(brainDirs(tmp).inbox).filter((n) => n.startsWith("sig-"));
    expect(inbox.length).toBe(0);
  });

  test("can also store imported turns in the session recall DAG", async () => {
    const res = await importSession(tmp, CLAUDE, {
      agent: "test",
      recall: true,
      recallSessionId: "session-import-test",
      recallSummaryGroupSize: 2,
    });

    expect(res.recall_turns_imported).toBeGreaterThan(0);
    expect(res.recall_summary_nodes).toBeGreaterThan(0);
    expect(describeSessionRecall(tmp, { sessionId: "session-import-test" }).raw_turns).toBe(
      res.recall_turns_imported,
    );
  });

  test("recall import stamps explicit lineage and stitches with the parent segment", async () => {
    const res = await importSession(tmp, CLAUDE, {
      agent: "test",
      recall: true,
      recallSessionId: "import-child",
      recallLineage: {
        rootId: "import-root",
        parentId: "import-root",
        depth: 1,
        source: "payload",
      },
    });
    expect(res.recall_turns_imported).toBeGreaterThan(0);
    // Recall over the ROOT id reaches the child-segment turns.
    const described = describeSessionRecall(tmp, { sessionId: "import-root" });
    expect(described.raw_turns).toBe(res.recall_turns_imported);
    expect(described.lineage_root).toBe("import-root");
  });

  test("recall import resolves persisted ledger lineage when no explicit lineage is given", async () => {
    const { recordLineageObservation } = await import("../../src/core/brain/lineage/ledger.ts");
    recordLineageObservation(tmp, {
      sessionId: "ledger-child",
      at: "2026-06-10T09:00:00Z",
      event: "SessionStart",
      lineage: { rootId: "ledger-root", parentId: "ledger-root", depth: 1, source: "crutch" },
    });
    const res = await importSession(tmp, CLAUDE, {
      agent: "test",
      recall: true,
      recallSessionId: "ledger-child",
    });
    expect(res.recall_turns_imported).toBeGreaterThan(0);
    const described = describeSessionRecall(tmp, { sessionId: "ledger-root" });
    expect(described.raw_turns).toBe(res.recall_turns_imported);
  });

  test("supports filtered write mode by role", async () => {
    const res = await importSession(tmp, CLAUDE, {
      agent: "test",
      filterRoles: ["user"],
    });

    expect(res.signals_created).toBe(1);
    expect(res.tool_replays).toBe(0);
    expect(res.filtered_turns).toBeGreaterThan(0);
  });

  test("supports filtered write mode by text substring", async () => {
    const res = await importSession(tmp, CLAUDE, {
      agent: "test",
      filterTextIncludes: "no-match-substring",
    });

    expect(res.signals_created).toBe(0);
    expect(res.filtered_turns).toBe(res.turns_scanned);
  });

  test("handles the codex fixture", async () => {
    const res = await importSession(tmp, CODEX, { agent: "test" });
    expect(res.format).toBe("codex");
    expect(res.signals_created).toBeGreaterThan(0);
  });

  test("handles the hermes fixture and stamps agent from session profile", async () => {
    const res = await importSession(tmp, HERMES, { agent: "test" });
    expect(res.format).toBe("hermes");
    expect(res.signals_created).toBeGreaterThan(0);
  });

  test("handles the opencode spool fixture", async () => {
    const res = await importSession(tmp, OPENCODE, { agent: "test" });
    expect(res.format).toBe("opencode");
    expect(res.signals_created).toBeGreaterThan(0);
  });

  test("throws SessionImportError(DETECT_FAIL) on unknown format", async () => {
    const junk = join(tmp, "junk.jsonl");
    writeFileSync(junk, '{"foo":"bar"}\n');
    let caught: unknown;
    try {
      await importSession(tmp, junk, { agent: "test" });
    } catch (e) {
      caught = e;
    }
    expect(caught).toBeInstanceOf(SessionImportError);
    expect((caught as SessionImportError).code).toBe("DETECT_FAIL");
  });

  test("counts malformed @osb marker attempts in session text", async () => {
    const fixturePath = join(tmp, "malformed-marker.jsonl");
    writeFileSync(
      fixturePath,
      [
        '{"parentUuid":null,"sessionId":"x","entrypoint":"sdk-cli","type":"user","message":{"role":"user","content":"@osb feedback negative topic=missing-principle"},"uuid":"u1","timestamp":"2026-05-16T10:00:01.000Z"}',
        "",
      ].join("\n"),
    );
    const res = await importSession(tmp, fixturePath, { agent: "test" });
    expect(res.signals_created).toBe(0);
    expect(res.malformed).toBe(1);
  });

  test("--format override bypasses autodetect", async () => {
    const junk = join(tmp, "junk.jsonl");
    writeFileSync(junk, '{"foo":"bar"}\n');
    // Should not throw — adapter chosen explicitly, iteration just
    // yields nothing.
    const res = await importSession(tmp, junk, {
      agent: "test",
      format: "claude",
    });
    expect(res.format).toBe("claude");
    expect(res.signals_created).toBe(0);
  });
});

describe("importSessionPath (directory walk)", () => {
  test("processes every jsonl in a directory", async () => {
    const dir = join(tmp, "sessions");
    mkdirSync(dir, { recursive: true });
    // Hand-link the fixtures so each file matches a different adapter.
    writeFileSync(
      join(dir, "a.jsonl"),
      [
        '{"parentUuid":null,"sessionId":"x","entrypoint":"sdk-cli","type":"user","message":{"role":"user","content":"@osb feedback negative topic=dir-a principle=p"},"uuid":"u","timestamp":"2026-05-16T10:00:00Z"}',
        "",
      ].join("\n"),
    );
    writeFileSync(
      join(dir, "b.jsonl"),
      [
        '{"role":"session_meta","tools":[]}',
        '{"role":"user","content":"@osb feedback negative topic=dir-b principle=p","timestamp":"2026-05-16T10:00:00"}',
        "",
      ].join("\n"),
    );
    const result = await importSessionPath(tmp, dir, { agent: "test" });
    expect(result.files.length).toBe(2);
    const created = result.files.reduce((s, r) => s + r.signals_created, 0);
    expect(created).toBe(2);
  });

  test("skips unknown-format files with a warning entry", async () => {
    const dir = join(tmp, "mixed");
    mkdirSync(dir, { recursive: true });
    writeFileSync(join(dir, "junk.jsonl"), '{"foo":"bar"}\n');
    writeFileSync(
      join(dir, "valid.jsonl"),
      [
        '{"parentUuid":null,"sessionId":"x","entrypoint":"sdk-cli","type":"user","message":{"role":"user","content":"@osb feedback negative topic=mixed principle=p"},"uuid":"u","timestamp":"2026-05-16T10:00:00Z"}',
        "",
      ].join("\n"),
    );
    const result = await importSessionPath(tmp, dir, { agent: "test" });
    expect(result.files.length).toBe(1);
    expect(result.warnings.length).toBe(1);
  });
});

describe("per-skill invocation telemetry", () => {
  function writeSkillSession(path: string): void {
    writeFileSync(
      path,
      [
        '{"parentUuid":null,"sessionId":"sk","entrypoint":"sdk-cli","type":"user","message":{"role":"user","content":"do a release"},"uuid":"u1","timestamp":"2026-06-01T10:00:00.000Z"}',
        '{"parentUuid":"u1","sessionId":"sk","type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"c1","name":"get_skill","input":{"name":"release"}}]},"uuid":"a1","timestamp":"2026-06-01T10:00:01.000Z"}',
        '{"parentUuid":"a1","sessionId":"sk","type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"c2","name":"Skill","input":{"command":"release"}}]},"uuid":"a2","timestamp":"2026-06-01T10:00:02.000Z"}',
        '{"parentUuid":"a2","sessionId":"sk","type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"c3","name":"get_skill","input":{"name":"triage"}}]},"uuid":"a3","timestamp":"2026-06-01T10:00:03.000Z"}',
        "",
      ].join("\n"),
    );
  }

  test("counts get_skill / Skill invocations and derives per-skill usage", async () => {
    const { deriveSkillUsage } = await import("../../src/core/brain/skill-usage.ts");
    const fixture = join(tmp, "skills.jsonl");
    writeSkillSession(fixture);

    const res = await importSession(tmp, fixture, { agent: "test" });
    expect(res.skill_invocations).toBe(3);

    const usage = deriveSkillUsage(tmp);
    expect(usage.map((u) => [u.skill, u.invocationCount])).toEqual([
      ["release", 2],
      ["triage", 1],
    ]);
  });

  test("a dry run records no invocations and re-import is idempotent", async () => {
    const { deriveSkillUsage } = await import("../../src/core/brain/skill-usage.ts");
    const fixture = join(tmp, "skills.jsonl");
    writeSkillSession(fixture);

    const dry = await importSession(tmp, fixture, { agent: "test", dryRun: true });
    expect(dry.skill_invocations).toBe(0);
    expect(deriveSkillUsage(tmp)).toEqual([]);

    await importSession(tmp, fixture, { agent: "test" });
    // Re-importing the same session dedupes rather than double-counting.
    await importSession(tmp, fixture, { agent: "test" });
    const usage = deriveSkillUsage(tmp);
    expect(usage.find((u) => u.skill === "release")!.invocationCount).toBe(2);
  });
});

/**
 * The new model-mining lane (salience-lifecycle-enrichment, unit 2) added a
 * `source_type` member and a second way to turn a session into signals.
 * `import-session` is not that lane and must not have moved: it still
 * stamps `session`, and re-running it over the same log produces the same
 * bytes on disk, which is what "byte-identical" has to mean for a test that
 * cannot reach the previous release.
 */
describe("import-session is untouched by the model-mining lane", () => {
  function inboxBytes(): ReadonlyArray<readonly [string, string]> {
    const dir = brainDirs(tmp).inbox;
    return readdirSync(dir)
      .filter((name) => name.endsWith(".md"))
      .toSorted()
      .map((name) => [name, readFileSync(join(dir, name), "utf8")] as const);
  }

  test("every imported signal is stamped `session`, never `auto_extract`", async () => {
    await importSession(tmp, CLAUDE, { agent: "test" });
    const files = inboxBytes();
    expect(files.length).toBeGreaterThan(0);
    for (const [name, body] of files) {
      expect(`${name} stamps session: ${body.includes("source_type: session")}`).toBe(
        `${name} stamps session: true`,
      );
      expect(body).not.toContain("auto_extract");
    }
  });

  test("a second import over the same log leaves the inbox bytes unchanged", async () => {
    const now = new Date("2026-08-22T10:00:00Z");
    await importSession(tmp, CLAUDE, { agent: "test", now });
    const before = inboxBytes();
    await importSession(tmp, CLAUDE, { agent: "test", now });
    expect(inboxBytes()).toEqual(before);
  });
});