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
/**
* The generated grok hook entries read their timeout from the committed
* vault tier instead of a literal.
*
* Two obligations pull against each other here and both are pinned below.
*
* A vault that declares no `install:` block must still generate the file
* it generated before this knob existed - install verification works by
* RE-CONSTRUCTION, never a stored hash, so a single changed byte reads as
* drift on every machine that already applied. The baseline is DERIVED
* rather than restated: `hooks/hooks.json` is the shipped plugin hook set
* and carries the same timeout on every entry, which is the number the
* generator used to hardcode. The parity suite next door already reads
* that file for the event -> hook-name map; this reads it for the one
* scalar the generator now resolves.
*
* A vault that DOES declare one must have it reach every entry, and an
* unreadable `_brain.yaml` must stop the write rather than quietly
* regenerate the default - the file is a writer's input, and a writer
* cannot infer intent from bytes it could not parse.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, sep } from "node:path";
import { Writable } from "node:stream";
import { grokAdapter } from "../../../src/core/install/adapters/grok.ts";
import { grokHooksJson } from "../../../src/core/install/grok-asset.ts";
import { buildPayload } from "../../../src/core/install/payload.ts";
import { resolveInstallHookTimeoutSeconds } from "../../../src/core/install/settings.ts";
import { INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT } from "../../../src/core/brain/policy/blocks/install.ts";
import { brainConfigPath } from "../../../src/core/brain/paths.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { CONFIG_ORIGIN } from "../../../src/core/validate.ts";
import type { InstallEnv } from "../../../src/core/install/types.ts";
const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
interface HookEntry {
readonly type: string;
readonly command: string;
readonly env: Record<string, string>;
readonly timeout: number;
}
/**
* The one timeout the shipped plugin hook set uses, read off
* `hooks/hooks.json`. Derived, not restated: this is the literal the grok
* generator carried before the `install:` block existed, so a vault with
* no block must still produce it.
*/
function shippedHookTimeoutSeconds(): number {
const raw = readFileSync(join(REPO_ROOT, "hooks", "hooks.json"), "utf8");
const timeouts = new Set([...raw.matchAll(/"timeout"\s*:\s*(\d+)/g)].map((m) => Number(m[1])));
expect(timeouts.size).toBe(1);
return [...timeouts][0]!;
}
/** The committed rendering, with the two per-machine paths left as tokens. */
function golden(): string {
return readFileSync(
join(REPO_ROOT, "tests", "fixtures", "install", "grok-hooks.golden.json"),
"utf8",
);
}
/** A path as it appears inside a JSON string literal. */
function jsonEscaped(path: string): string {
return JSON.stringify(path).slice(1, -1);
}
/**
* A generated hooks file reduced to the form the golden is stored in.
*
* Only the bun binary and the repository root are tokenised, because only
* those two are machine-specific by design (grok's restricted
* session-spawn PATH forces absolute commands). Tokenising anything else
* would be the golden agreeing not to look at it.
*/
function normalize(json: string): string {
// The paths appear JSON-escaped in the rendered file, which only differs
// from the raw path where it holds backslashes (Windows). Hook paths are
// then joined with the platform separator, so fold that back to `/` too.
const replaced = json
.split(jsonEscaped(process.execPath))
.join("<BUN>")
.split(jsonEscaped(REPO_ROOT))
.join("<REPO>");
if (sep === "/") return replaced;
return replaced.replace(
/<REPO>((?:\\\\[\w.-]+)+)/g,
(_, rest: string) => `<REPO>${rest.split("\\\\").join("/")}`,
);
}
function hookEntries(json: string): ReadonlyArray<HookEntry> {
const parsed = JSON.parse(json) as {
hooks: Record<string, Array<{ hooks: HookEntry[] }>>;
};
return Object.values(parsed.hooks)
.flat()
.flatMap((group) => group.hooks);
}
let vault: string;
let home: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "osb-grok-timeout-v-"));
home = mkdtempSync(join(tmpdir(), "osb-grok-timeout-h-"));
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => {
for (const dir of [vault, home]) rmSync(dir, { recursive: true, force: true });
});
function installEnv(): InstallEnv {
return {
vault,
home,
cwd: home,
env: { VAULT_AGENT_NAME: "claude-dev-agent", VAULT_TIMEZONE: "UTC" },
now: new Date("2026-06-12T12:00:00.000Z"),
};
}
function payload() {
return buildPayload({ vault, agent_name: "claude-dev-agent", timezone: "UTC" });
}
function apply(): void {
const sink = new Writable({
write(_chunk, _encoding, done) {
done();
},
});
const opts = {
dryRun: false,
force: false,
stdout: sink as unknown as NodeJS.WriteStream,
stderr: sink as unknown as NodeJS.WriteStream,
};
const env = installEnv();
grokAdapter.apply(grokAdapter.plan(payload(), env), payload(), env, opts);
}
function hooksPath(): string {
return join(home, ".grok", "hooks", "open-second-brain.json");
}
describe("a vault with no install: block regenerates the committed output", () => {
test("the compiled default is the timeout the shipped hook set carries", () => {
expect(INSTALL_HOOK_TIMEOUT_SECONDS_DEFAULT).toBe(shippedHookTimeoutSeconds());
});
test("resolution reports the default layer and the shipped value", () => {
expect(
resolveInstallHookTimeoutSeconds({
vault,
configPath: join(home, "absent-config.yaml"),
}),
).toEqual({ value: shippedHookTimeoutSeconds(), origin: CONFIG_ORIGIN.default });
});
test("the generation matches the committed golden rendering, byte for byte", () => {
// The anchor. Every other "byte-identical" assertion here and in the
// adapter suite compared the generator against ITSELF - the same call
// with the argument the default supplied - so it could only fail if
// the generator were non-deterministic, and a change to the hook
// command paths, the `env` map, the entry ordering or the JSON
// indentation left every one of them green. This compares against
// bytes committed to the tree.
//
// Two substitutions, and only two: the bun binary and the repository
// root are absolute paths that differ per machine, and the whole
// reason `grok-asset.ts` emits them is that grok's session-spawn PATH
// will not resolve a bare command. Everything else - including the
// derived agent name and the timeout on every entry - is compared
// literally.
expect(normalize(grokHooksJson(payload(), shippedHookTimeoutSeconds()))).toBe(golden());
});
test("the applied file is the same golden rendering", () => {
apply();
expect(normalize(readFileSync(hooksPath(), "utf8"))).toBe(golden());
});
test("every generated entry carries the shipped timeout", () => {
const entries = hookEntries(grokHooksJson(payload(), shippedHookTimeoutSeconds()));
expect(entries.length).toBeGreaterThan(0);
for (const entry of entries) expect(entry.timeout).toBe(shippedHookTimeoutSeconds());
});
});
describe("a configured hook_timeout_seconds reaches every entry", () => {
const CONFIGURED = 45;
beforeEach(() => {
atomicWriteFileSync(
brainConfigPath(vault),
`schema_version: 1\ninstall:\n hook_timeout_seconds: ${CONFIGURED}\n`,
);
});
test("the resolver reports the vault-config layer", () => {
expect(
resolveInstallHookTimeoutSeconds({
vault,
configPath: join(home, "absent-config.yaml"),
}),
).toEqual({ value: CONFIGURED, origin: CONFIG_ORIGIN.vaultConfig });
});
test("the applied hooks file carries it on every entry", () => {
apply();
const entries = hookEntries(readFileSync(hooksPath(), "utf8"));
expect(entries.length).toBeGreaterThan(0);
for (const entry of entries) expect(entry.timeout).toBe(CONFIGURED);
});
test("the applied file equals the generation for that timeout", () => {
apply();
expect(readFileSync(hooksPath(), "utf8")).toBe(grokHooksJson(payload(), CONFIGURED));
});
test("it is the golden rendering with only the timeout changed", () => {
// Pins the SCOPE of the setting as well as its arrival: a knob that
// also moved a command path or reordered the entries would pass the
// assertion above and fail this one.
apply();
expect(normalize(readFileSync(hooksPath(), "utf8"))).toBe(
golden().replaceAll(`"timeout": ${shippedHookTimeoutSeconds()}`, `"timeout": ${CONFIGURED}`),
);
});
test("a freshly applied install reports no drift", () => {
apply();
expect(grokAdapter.verify(installEnv()).status).toBe("ok");
});
});
describe("an unreadable _brain.yaml refuses the generation", () => {
beforeEach(() => {
atomicWriteFileSync(
brainConfigPath(vault),
"schema_version: 1\ninstall:\n hook_timeout_seconds: [broken\n",
);
});
test("apply refuses and names the file", () => {
let message = "";
try {
apply();
} catch (err) {
message = (err as Error).message;
}
expect(message).toContain(brainConfigPath(vault));
});
test("nothing is written", () => {
try {
apply();
} catch {
// The refusal is the assertion below: no hooks file exists.
}
expect(() => readFileSync(hooksPath(), "utf8")).toThrow();
});
/**
* The READ paths refuse too, and they are the ones with a blast radius:
* `o2b install` with no `--target` walks every adapter's `detect`, and
* `--check` walks every `verify`, so one unparsable file used to take
* down the status of nine targets that never read it. The refusal is
* still correct - `syncState` compares against a generation it cannot
* produce - and `src/cli/main.ts` now renders it as one line rather than
* a stack trace.
*/
test("verify refuses and names the file", () => {
let message = "";
try {
grokAdapter.verify(installEnv());
} catch (err) {
message = (err as Error).message;
}
expect(message).toContain(brainConfigPath(vault));
});
test("detect refuses and names the file", () => {
let message = "";
try {
grokAdapter.detect(installEnv());
} catch (err) {
message = (err as Error).message;
}
expect(message).toContain(brainConfigPath(vault));
});
});