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
/**
* `second_brain_wiring` - what this install is wired into.
*
* Two readers already answered this and neither was reachable from the
* MCP surface. `linkedProjectsStatus` reports every registered project
* link with its pointer state, and had one consumer: the CLI verb
* `o2b brain project status`. That is the whole gap this view closes -
* no new health model, no second registry walk.
*
* The path policy is the part worth testing hard. The registry is keyed
* on ABSOLUTE host paths, and an MCP response lands in model context, so
* every reference here goes through the same `expose_host_paths`
* contract `vault_path` already obeys. A payload that leaked a project
* directory would be the same defect the vault-path census exists to
* prevent, one field over.
*
* The hosts view leaks differently: `verify()` composes its `details`
* and `fix_hint` sentences from `InstallEnv.home`, so the path arrives
* inside prose no store reference can render. `foldHostHome` folds the
* home prefix there, and the no-host-path assertion below is over the
* SERIALISED payload of both views - the census in
* `tests/core/architecture/vault-path-census.test.ts` is keyed on the
* field name `vault_path` and cannot see either of these fields.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { Writable } from "node:stream";
import { join, sep } from "node:path";
import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
import { buildToolTable } from "../../src/mcp/tools.ts";
import {
WIRING_MAX_PROJECTS,
WIRING_TOOL_NAME,
WIRING_VIEWS,
hostWiringEntry,
} from "../../src/mcp/wiring-tools.ts";
import { INVALID_PARAMS } from "../../src/mcp/protocol.ts";
import { foldHostHome } from "../../src/mcp/vault-path-field.ts";
import {
projectsRegistryPath,
registerLinkedProject,
writeVaultPointer,
VAULT_POINTER_FILE,
} from "../../src/core/brain/portability/pointer.ts";
import { INSTALLATION_SECRET_ENV_KEY, VAULT_STORE_REF_PREFIX } from "../../src/core/config.ts";
import { VAULT_NOT_CONFIGURED_REASON, buildInstallEnv } from "../../src/core/install/env.ts";
import { defaultRegistry } from "../../src/core/install/registry.ts";
import "../../src/core/install/adapters/all.ts";
import {
HOST_PROBE_RESULT,
resetHostProbeRunner,
setHostProbeRunner,
} from "../../src/core/install/host-probe.ts";
import { VERIFY_STATUSES, type InstallEnv } from "../../src/core/install/types.ts";
import {
codexAdapter,
resetCodexRunner,
setCodexRunner,
} from "../../src/core/install/adapters/codex.ts";
import { buildPayload } from "../../src/core/install/payload.ts";
import { fakeCredential } from "../helpers/fake-credentials.ts";
/** Deterministic 32-hex key so `vault://<hex>` is stable across runs. */
const SECRET = fakeCredential("0123456789abcdef", "0123456789abcdef");
/** The escape hatch that restores raw host paths. */
const EXPOSE_ENV = "OPEN_SECOND_BRAIN_EXPOSE_HOST_PATHS";
/** The override `defaultConfigPath` consults before the host home. */
const CONFIG_PATH_ENV = "OPEN_SECOND_BRAIN_CONFIG";
/**
* Every environment variable this file writes.
*
* Bun runs the whole suite in ONE process and `tests/setup.ts` makes it
* hermetic by pointing `OPEN_SECOND_BRAIN_CONFIG` at a throwaway config
* for every file that does not set its own. A `delete` here therefore
* does not restore a prior state - it destroys that default for every
* file bun schedules after this one, which is why the restore below is
* a snapshot of the value rather than a removal of the key.
*/
const MUTATED_ENV: ReadonlyArray<string> = Object.freeze([
INSTALLATION_SECRET_ENV_KEY,
EXPOSE_ENV,
CONFIG_PATH_ENV,
]);
interface Sandbox {
readonly root: string;
readonly configPath: string;
readonly vault: string;
readonly project: string;
}
let sandbox: Sandbox;
let savedEnv: Map<string, string | undefined>;
function makeSandbox(): Sandbox {
const root = mkdtempSync(join(tmpdir(), "o2b-wiring-"));
const configPath = join(root, "config", "config.yaml");
mkdirSync(join(root, "config"), { recursive: true });
writeFileSync(configPath, "vault: \n", "utf8");
const vault = join(root, "vault");
const project = join(root, "project");
mkdirSync(vault, { recursive: true });
mkdirSync(project, { recursive: true });
return { root, configPath, vault, project };
}
beforeEach(() => {
savedEnv = new Map(MUTATED_ENV.map((key) => [key, process.env[key]]));
process.env[INSTALLATION_SECRET_ENV_KEY] = SECRET;
delete process.env[EXPOSE_ENV];
sandbox = makeSandbox();
});
afterEach(() => {
for (const [key, value] of savedEnv) {
if (value === undefined) delete process.env[key];
else process.env[key] = value;
}
rmSync(sandbox.root, { recursive: true, force: true });
});
/** `server` overrides the default context, for the tests about that context. */
async function callWiring(
args: Record<string, unknown>,
server: MCPServer = new MCPServer({ vault: sandbox.vault, configPath: sandbox.configPath }),
): Promise<{
payload?: Record<string, unknown>;
error?: { code: number; message: string };
}> {
await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 1,
method: "initialize",
params: {
protocolVersion: PROTOCOL_VERSION,
capabilities: {},
clientInfo: { name: "wiring-test", version: "0" },
},
});
const response = (await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 2,
method: "tools/call",
params: { name: WIRING_TOOL_NAME, arguments: args },
})) as {
result?: { content: ReadonlyArray<{ type: string; text: string }> };
error?: { code: number; message: string };
};
if (response.error) return { error: response.error };
return { payload: JSON.parse(response.result!.content[0]!.text) };
}
describe("second_brain_wiring registration", () => {
test("is in the full tool table and in neither reduced scope", () => {
expect(buildToolTable("full").find((t) => t.name === WIRING_TOOL_NAME)).toBeDefined();
expect(buildToolTable("writer").find((t) => t.name === WIRING_TOOL_NAME)).toBeUndefined();
const catalog = buildToolTable("catalog").find((t) => t.name === WIRING_TOOL_NAME);
expect(catalog?.hidden).toBe(true);
});
test("view is required, and an absent one names the accepted members", async () => {
const { error } = await callWiring({});
expect(error?.code).toBe(INVALID_PARAMS);
for (const view of WIRING_VIEWS) expect(error?.message).toContain(view);
});
test("an unknown view is refused by name rather than defaulted", async () => {
const { error } = await callWiring({ view: "everything" });
expect(error?.code).toBe(INVALID_PARAMS);
expect(error?.message).toContain("everything");
});
});
describe("view=projects", () => {
test("reports one entry per registered link with its pointer state", async () => {
registerLinkedProject(sandbox.configPath, sandbox.project, sandbox.vault);
writeVaultPointer(sandbox.project, sandbox.vault);
const { payload } = await callWiring({ view: "projects" });
expect(payload!["view"]).toBe("projects");
const projects = payload!["projects"] as Array<Record<string, unknown>>;
expect(projects).toHaveLength(1);
expect(projects[0]).toMatchObject({ pointer: "ok", vault_exists: true });
});
test("an empty registry is an empty list, not an error", async () => {
const { payload } = await callWiring({ view: "projects" });
expect(payload!["projects"]).toEqual([]);
expect(payload!["total"]).toBe(0);
expect(payload!["returned"]).toBe(0);
expect(payload!["truncated"]).toBe(false);
});
test("an uncapped registry is capped, and the payload says so", async () => {
// Nothing caps `projects.json` - every `o2b brain project link`
// appends to it - and this response lands in model context, so the
// bound has to be in the payload rather than in the expectation
// that operators link few projects.
const over = WIRING_MAX_PROJECTS + 3;
for (let i = 0; i < over; i++) {
const project = join(sandbox.root, `linked-${i}`);
mkdirSync(project, { recursive: true });
registerLinkedProject(sandbox.configPath, project, sandbox.vault);
}
const { payload } = await callWiring({ view: "projects" });
expect((payload!["projects"] as unknown[]).length).toBe(WIRING_MAX_PROJECTS);
expect(payload!["total"]).toBe(over);
expect(payload!["returned"]).toBe(WIRING_MAX_PROJECTS);
expect(payload!["truncated"]).toBe(true);
});
test("a registry under the cap is not reported as truncated", async () => {
registerLinkedProject(sandbox.configPath, sandbox.project, sandbox.vault);
const { payload } = await callWiring({ view: "projects" });
expect(payload!["total"]).toBe(1);
expect(payload!["returned"]).toBe(1);
expect(payload!["truncated"]).toBe(false);
});
test("each of the four pointer states is reported as itself", async () => {
registerLinkedProject(sandbox.configPath, sandbox.project, sandbox.vault);
const missing = await callWiring({ view: "projects" });
expect((missing.payload!["projects"] as Array<Record<string, unknown>>)[0]!["pointer"]).toBe(
"missing",
);
writeFileSync(join(sandbox.project, VAULT_POINTER_FILE), "{ not json", "utf8");
const malformed = await callWiring({ view: "projects" });
expect((malformed.payload!["projects"] as Array<Record<string, unknown>>)[0]!["pointer"]).toBe(
"malformed",
);
const other = join(sandbox.root, "other-vault");
mkdirSync(other, { recursive: true });
writeVaultPointer(sandbox.project, other);
const mismatch = await callWiring({ view: "projects" });
expect((mismatch.payload!["projects"] as Array<Record<string, unknown>>)[0]!["pointer"]).toBe(
"mismatch",
);
});
test("a vault that no longer exists is reported, not hidden", async () => {
const gone = join(sandbox.root, "removed-vault");
mkdirSync(gone, { recursive: true });
registerLinkedProject(sandbox.configPath, sandbox.project, gone);
rmSync(gone, { recursive: true, force: true });
const { payload } = await callWiring({ view: "projects" });
expect((payload!["projects"] as Array<Record<string, unknown>>)[0]).toMatchObject({
vault_exists: false,
});
});
});
describe("view=projects path policy", () => {
test("no absolute host path appears anywhere in the serialised payload", async () => {
registerLinkedProject(sandbox.configPath, sandbox.project, sandbox.vault);
writeVaultPointer(sandbox.project, sandbox.vault);
const { payload } = await callWiring({ view: "projects" });
const serialised = JSON.stringify(payload);
expect(serialised).not.toContain(sandbox.project);
expect(serialised).not.toContain(sandbox.vault);
expect(serialised).toContain(VAULT_STORE_REF_PREFIX);
});
test("with expose_host_paths on, the raw paths are what the operator asked for", async () => {
process.env[EXPOSE_ENV] = "true";
registerLinkedProject(sandbox.configPath, sandbox.project, sandbox.vault);
const { payload } = await callWiring({ view: "projects" });
const projects = payload!["projects"] as Array<Record<string, unknown>>;
expect(projects[0]!["project_ref"]).toBe(sandbox.project);
expect(projects[0]!["vault_ref"]).toBe(sandbox.vault);
});
test("a config that cannot be read renders the reason, never the raw path", async () => {
registerLinkedProject(sandbox.configPath, sandbox.project, sandbox.vault);
// The secret keys the reference and lives in the config; an
// unreadable config leaves the reference unresolvable, and the
// contract forbids degrading to the path the reference hides.
delete process.env[INSTALLATION_SECRET_ENV_KEY];
// A directory where the config file belongs: `discoverConfig`
// refuses a path that is not a regular file, which is the one
// ConfigReadError branch a test can stage without depending on the
// running user being unable to read a chmod-ed file.
rmSync(sandbox.configPath, { force: true });
mkdirSync(sandbox.configPath, { recursive: true });
const { payload } = await callWiring({ view: "projects" });
const serialised = JSON.stringify(payload);
expect(serialised).not.toContain(sandbox.project);
// Both sides of the link, not just the one: the two fields are
// rendered by the same call and an assertion over one of them would
// pass for a payload that leaked the other.
expect(serialised).not.toContain(sandbox.vault);
const projects = payload!["projects"] as Array<Record<string, unknown>>;
expect(projects[0]!["project_ref"]).toHaveProperty("error");
expect(projects[0]!["vault_ref"]).toHaveProperty("error");
});
test("a registry damaged by hand reads as no links, exactly as the CLI verb does", async () => {
registerLinkedProject(sandbox.configPath, sandbox.project, sandbox.vault);
writeFileSync(projectsRegistryPath(sandbox.configPath), "{ broken", "utf8");
const { payload } = await callWiring({ view: "projects" });
// `listLinkedProjects` passes `tolerateParseError`, so this view
// answers what `o2b brain project status` answers. It is core's
// tolerance, not this view's: a tool that refused where the verb
// tolerates would be the second answer this file exists to avoid.
expect(payload!["projects"]).toEqual([]);
});
test("a server given no config path reads the machine default, not an empty list", async () => {
// The view used to answer `[]` here, which reports "nothing is
// linked" for a box whose registry is full - and disagreed with
// `view=hosts` in the same tool, which has always defaulted. The
// default is redirected through the env override `defaultConfigPath`
// consults first, since `os.homedir()` cannot be moved in-process.
registerLinkedProject(sandbox.configPath, sandbox.project, sandbox.vault);
writeVaultPointer(sandbox.project, sandbox.vault);
process.env[CONFIG_PATH_ENV] = sandbox.configPath;
// No local restore: `afterEach` puts every key in `MUTATED_ENV` back
// to the value it snapshotted, which for this one is the hermetic
// default `tests/setup.ts` installs for the whole process.
const server = new MCPServer({ vault: sandbox.vault });
const { payload } = await callWiring({ view: "projects" }, server);
expect((payload!["projects"] as unknown[]).length).toBe(1);
});
});
/** How a folded sentence names the host home; see `foldHostHome`. */
const FOLDED_HOME = "~";
/** The identity a staged registration is written under. */
const STAGE_AGENT = "wiring-test";
/** The timezone a staged registration is written under. */
const STAGE_TIMEZONE = "UTC";
/**
* A codex registration this build wrote, under `home`.
*
* An unstaged target verifies to "no install manifest entry" - a
* sentence carrying no path at all - so a path assertion over it would
* pass for the wrong reason. An absent binary sends `apply` down the
* file-writing path, so the registration exists as a real artifact.
*
* LEAVES both runners stubbed, because `verify()` consults them too -
* an unstubbed host probe would spawn whatever `codex` binary the test
* machine happens to have. Every caller resets them in its own
* `finally`; a caller that wants a different probe answer overrides it.
*/
function stageCodexInstall(home: string, vault: string): InstallEnv {
const installEnv: InstallEnv = {
vault,
home,
cwd: home,
env: { VAULT_AGENT_NAME: STAGE_AGENT, VAULT_TIMEZONE: STAGE_TIMEZONE },
now: new Date(),
};
const payload = buildPayload({ vault, agent_name: STAGE_AGENT, timezone: STAGE_TIMEZONE });
setCodexRunner({
available: () => false,
run: () => {
throw new Error("the adapter must not spawn codex when it reported the binary absent");
},
});
setHostProbeRunner({
available: () => false,
run: () => {
throw new Error("the probe must not spawn when it reported the binary absent");
},
});
const sink = new Writable({ write: (_c, _e, cb) => cb() }) as unknown as NodeJS.WriteStream;
codexAdapter.apply(codexAdapter.plan(payload, installEnv), payload, installEnv, {
dryRun: false,
force: false,
stdout: sink,
stderr: sink,
});
return installEnv;
}
describe("view=hosts", () => {
test("reports one entry per registered adapter", async () => {
const { payload } = await callWiring({ view: "hosts" });
expect(payload!["view"]).toBe("hosts");
const hosts = payload!["hosts"] as Array<Record<string, unknown>>;
expect(hosts.map((h) => h["target"])).toEqual([...defaultRegistry.targets()]);
for (const host of hosts) {
expect([...VERIFY_STATUSES] as string[]).toContain(host["status"] as string);
expect(Array.isArray(host["details"])).toBe(true);
expect(host).toHaveProperty("fix_hint");
}
});
test("it is the same verify() answer, over the same registry and env", async () => {
// Not "an equivalent aggregate": the same call over the same
// registry with the same env, so one implementation of connector
// health cannot become two that disagree. The env is built through
// `buildInstallEnv` - the constructor `o2b install` now shares - so
// splitting that constructor again fails here.
const env = buildInstallEnv({ vault: sandbox.vault, configPath: sandbox.configPath });
const policy = { configPath: sandbox.configPath };
const direct = defaultRegistry.list().map((adapter) => adapter.verify(env));
const { payload } = await callWiring({ view: "hosts" });
const hosts = payload!["hosts"] as Array<Record<string, unknown>>;
expect(hosts).toEqual(direct.map((r) => hostWiringEntry(r, env.home, policy)));
});
test("the serialised payload of neither view carries this process's home", async () => {
// The cheap end-to-end guard. It is not the one with teeth - an
// install-free home verifies to "no install manifest entry", a
// sentence with no path in it - so the folding assertions below
// stage a registration first.
const answers = await Promise.all(WIRING_VIEWS.map((view) => callWiring({ view })));
for (const { payload } of answers) {
expect(JSON.stringify(payload)).not.toContain(homedir());
}
});
test("adapter prose folds the host home instead of naming it", () => {
const home = mkdtempSync(join(sandbox.root, "fold-home-"));
const installEnv = stageCodexInstall(home, sandbox.vault);
try {
const entry = hostWiringEntry(codexAdapter.verify(installEnv), home, {
configPath: sandbox.configPath,
});
const details = (entry["details"] as string[]).join("; ");
// Staged, so the sentence names a file: the assertion below is
// about WHICH form that name takes, not about its absence.
// The folded name keeps the host separator (`~\\.codex\\` on Windows):
// only the home prefix is rewritten.
expect(details).toContain(`${FOLDED_HOME}${sep}.codex${sep}`);
expect(details).not.toContain(home);
} finally {
resetHostProbeRunner();
resetCodexRunner();
}
});
test("a sibling home that extends this one is left alone", () => {
// A plain prefix replacement run under a home named `dev` clips a
// sibling named `developer` into `~eloper` - a path that names no
// file, which is worse than either the raw one or the folded one.
const home = join(sandbox.root, "dev");
const sibling = `${home}eloper/.codex/config.toml`;
const folded = foldHostHome(`${home}/.codex/config.toml and ${sibling}`, home, {
configPath: sandbox.configPath,
});
expect(folded).toBe(`${FOLDED_HOME}/.codex/config.toml and ${sibling}`);
});
test("the home folds at the end of a sentence and before punctuation too", () => {
const home = join(sandbox.root, "dev");
const folded = foldHostHome(`checked ${home}, then ${home}`, home, {
configPath: sandbox.configPath,
});
expect(folded).toBe(`checked ${FOLDED_HOME}, then ${FOLDED_HOME}`);
});
test("`expose_host_paths` restores the raw path in that same sentence", () => {
// The escape hatch is ONE flag for both mechanisms: the config that
// un-hashes `vault_path` un-folds the adapter prose with it.
const home = mkdtempSync(join(sandbox.root, "expose-home-"));
const installEnv = stageCodexInstall(home, sandbox.vault);
process.env[EXPOSE_ENV] = "1";
try {
const entry = hostWiringEntry(codexAdapter.verify(installEnv), home, {
configPath: sandbox.configPath,
});
expect((entry["details"] as string[]).join("; ")).toContain(`${home}${sep}.codex${sep}`);
} finally {
// `afterEach` restores EXPOSE_ENV from the snapshot; the runners
// are process-global and have no snapshot, so they reset here.
resetHostProbeRunner();
resetCodexRunner();
}
});
test("an unresolved vault is refused by name, not reported as ten clean targets", async () => {
const server = new MCPServer({ vault: "", configPath: sandbox.configPath });
await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 1,
method: "initialize",
params: {
protocolVersion: PROTOCOL_VERSION,
capabilities: {},
clientInfo: { name: "wiring-test", version: "0" },
},
});
const response = (await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 2,
method: "tools/call",
params: { name: WIRING_TOOL_NAME, arguments: { view: "hosts" } },
})) as {
result?: { content: ReadonlyArray<{ text: string }> };
error?: { code: number; message: string };
};
expect(response.error?.message).toContain(VAULT_NOT_CONFIGURED_REASON);
// The code docs/mcp.md gives for this refusal, alongside the one it
// gives for a bad `view`.
expect(response.error?.code).toBe(INVALID_PARAMS);
expect(response.result).toBeUndefined();
});
test("a probe that cannot run reaches the payload as its named reason, not an ok", () => {
// The branch needs an INSTALLED target verified against a specific
// host home, and `os.homedir()` here does not follow a later
// `process.env.HOME`, so the home the view resolves cannot be
// redirected in-process. The env is therefore built by hand, as the
// adapter suites do, and the assertion is over the view's own
// mapping of the real `verify()` answer - the deep-equality test
// above is what ties that mapping to the env the view builds.
const home = mkdtempSync(join(sandbox.root, "probe-home-"));
const installEnv = stageCodexInstall(home, sandbox.vault);
try {
// The host binary answers, and refuses.
setHostProbeRunner({
available: () => true,
run: () => ({ exitCode: 4, stdout: "", stderr: "failed to load configuration\n" }),
});
const entry = hostWiringEntry(codexAdapter.verify(installEnv), home, {
configPath: sandbox.configPath,
});
const details = (entry["details"] as string[]).join("; ");
expect(details).toContain("exited 4");
expect(details).toContain("failed to load configuration");
// The skip is NAMED, so nothing here reads as a host-confirmed
// registration.
expect(details).not.toContain(HOST_PROBE_RESULT.answered);
expect(entry["target"]).toBe(codexAdapter.target);
} finally {
resetHostProbeRunner();
resetCodexRunner();
}
});
});