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
/**
* Open Second Brain plugin for opencode (https://opencode.ai).
*
* Installed by `o2b install --target opencode --apply` into
* `~/.config/opencode/plugins/open-second-brain.ts`. The file is
* deliberately self-contained (no imports beyond node builtins and the
* Bun globals opencode already provides) so the copy works standalone
* inside opencode's plugin sandbox.
*
* Supports OpenCode V1 (server) and V2 (setup). Five behaviors mirror
* the Claude Code / Codex hook layer:
*
* 1. Active-context inject: V1 `experimental.chat.system.transform` /
* V2 `session.hook("context")`
* spawns the bundled `o2b-hook active-inject` PATH shim (override:
* `OSB_HOOK_BIN`) with a synthetic SessionStart payload and appends
* `hookSpecificOutput.additionalContext` to the system prompt.
* Vault resolution, budgeting, and quiet-failure semantics are
* inherited from the shim rather than reimplemented here.
*
* 2. Session capture: V1 snapshots the full message list on idle,
* compaction, or deletion; V2 snapshots active context on idle and
* before/after compaction, merging with earlier snapshots to retain
* history. The deterministic JSONL spool lives under
* `${XDG_DATA_HOME:-~/.local/share}/open-second-brain/opencode/`
* (`%LOCALAPPDATA%\\open-second-brain\\opencode\\` on native Windows)
* (override: `OSB_OPENCODE_SPOOL_DIR`). The spool format is owned
* by Open Second Brain (`format: 1`); `o2b brain import-session`
* pointed at the spool dir ingests it via the `opencode` session
* adapter. Snapshot-rewrite, not append: idempotent and
* self-healing after crashes.
*
* 3. Post-write reminder: V1 `tool.execute.after` /
* V2 `tool.hook("execute.after")` appends the standard
* logging nudge to the output of file-mutating tools so the model
* sees it, matching the Claude Code post-write-reminder contract.
*
* 4. Tool gating: V1 `tool.execute.before` /
* V2 `tool.hook("execute.before")` relays the opt-in PreToolUse
* shims (`pretool-orient`, `pretool-host-backup`) with synthetic
* PreToolUse payloads carrying the opencode session id. Only an
* explicit structured `permissionDecision: "deny"` throws (with the
* shim's `permissionDecisionReason` as the error text) - the one
* blocking channel opencode offers. Every other outcome (flag off,
* missing binary, spawn failure, timeout, malformed stdout) passes
* the tool call untouched, because a plugin bug must never break
* operator tool calls on a lane without the Claude Code wrapper's
* forced exit-0 safety net. The Claude Code "nudge on allow"
* downgrade has no channel on a tool call here and is declared as a
* divergence in the opencode hook parity census.
*
* 5. Prompt-time injection: V1 `chat.message` /
* V2 `session.hook("prompt")` observes the user prompt and relays
* the opt-in UserPromptSubmit shims (`recall-inject`, `nav-inject`,
* `counterparty-brief`, `reground-deliver`) with synthetic payloads
* carrying the opencode session id, so the vault hook-state ledger
* dedupes exactly as on the Claude Code lane. The shims'
* `hookSpecificOutput.additionalContext` enters a single-slot
* per-turn queue that the context delivery points drain on the first
* model request of the turn - the prompt hook itself runs before
* durable prompt admission and is not a delivery channel.
*
* Every hook body is fail-soft: a missing vault, missing binary, or
* session API error must never break the operator's opencode session.
*/
import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { setTimeout as sleep } from "node:timers/promises";
const SPOOL_FORMAT = 1;
const SPOOL_ORIGINATOR = "open-second-brain-opencode-plugin";
const CAPTURE_EVENTS = new Set(["session.idle", "session.compacted", "session.deleted"]);
const V2_CAPTURE_EVENTS = new Set([
// v2 tree naming: the turn ends with an idle event.
"session.idle",
// v2 >= 2.0.24 naming: the turn ends with an execution event, and a
// failed or interrupted run still leaves messages worth capturing.
"session.execution.succeeded",
"session.execution.failed",
"session.execution.interrupted",
"session.compaction.started",
"session.compaction.ended",
"session.compaction.failed",
"session.revert.committed",
"session.deleted",
]);
const MUTATING_TOOLS = new Set(["write", "edit", "multiedit", "patch", "apply_patch"]);
/**
* The host marker the synthetic hook payloads carry, and `hooks/lib/
* detect.ts` answers with the `opencode` runtime - the honest answer to
* "which harness is calling", where a fabricated Claude Code
* `tool_use_id` would mislabel every audit row this lane writes. The
* two literals are one contract stated in both files (this file is
* copied alone into opencode's plugin directory and cannot import it).
*/
const PAYLOAD_HOST_MARKER = "opencode";
/**
* opencode's tool names, translated onto the Claude Code spellings the
* shim decision cores parse. The relay's design is a synthetic
* Claude-Code-shaped payload, so the translation lives here rather than
* in the shims: opencode names its file tools in lowercase, and the
* cores' tool sets are exact-match. Any name outside the table passes
* verbatim.
*/
const PRETOOL_TOOL_NAMES: Readonly<Record<string, string>> = Object.freeze({
read: "Read",
edit: "Edit",
write: "Write",
multiedit: "MultiEdit",
patch: "apply_patch",
apply_patch: "apply_patch",
});
/**
* The MCP server names this project registers under (`OSB_KEY_FULL` and
* its underscore spelling), which is how opencode prefixes its MCP tool
* names: `<server>_<tool>` with a single underscore. The decision
* cores' brain-tool matchers are built for the `mcp__` double-underscore
* spellings and never fire on those names, so the relay strips a KNOWN
* server prefix from a Brain tool name - never a prefix-shaped suffix of
* some other server's tool - and an orientation refresh plus every
* brain-tool branch of the cores see the bare name.
*/
const BRAIN_SERVER_PREFIXES: ReadonlyArray<string> = Object.freeze([
"open-second-brain_",
"open_second_brain_",
]);
function translateToolName(tool: string): string {
const mapped = PRETOOL_TOOL_NAMES[tool.toLowerCase()] ?? tool;
const lower = mapped.toLowerCase();
for (const prefix of BRAIN_SERVER_PREFIXES) {
if (lower.startsWith(prefix) && lower.slice(prefix.length).startsWith("brain_")) {
return mapped.slice(prefix.length);
}
}
return mapped;
}
const ACTIVE_CONTEXT_TTL_MS = 5 * 60 * 1000;
/** A failed render retries sooner than a successful one expires. */
const ACTIVE_CONTEXT_NEGATIVE_TTL_MS = 30 * 1000;
const HOOK_TIMEOUT_MS = 10_000;
/**
* The PreToolUse relay: the shims the execute.before gate spawns and the
* default-OFF flag each one answers to. The env/config key pairs restate
* the canonical resolvers in src/core/config.ts exactly as the hook
* wrappers' stdlib twins do, so a flag the shim would honor is one this
* gate spawns for (and flags off mean zero spawns). `mutatingOnly`
* mirrors the Claude Code host-backup row matcher
* (Write|Edit|MultiEdit|apply_patch).
*/
const PRETOOL_SHIMS: ReadonlyArray<{
readonly name: string;
readonly envKey: string;
readonly configKey: string;
readonly mutatingOnly?: boolean;
}> = [
{
name: "pretool-orient",
envKey: "OPEN_SECOND_BRAIN_HOOK_STRICT_ENABLED",
configKey: "hook_strict_enabled",
},
{
name: "pretool-host-backup",
envKey: "OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP",
configKey: "host_settings_backup",
mutatingOnly: true,
},
];
/**
* The UserPromptSubmit relay: the prompt-time shims and the flag each
* answers to, restated from src/core/config.ts exactly as the PreToolUse
* pairs above. Every flag is default-OFF except the ones marked
* `defaultOn` (neighbour updates run on every host unless turned off). The opencode prompt hook observes the prompt
* before durable admission and is not a delivery channel, so the shims'
* additionalContext rides the per-turn queue below instead.
*/
const PROMPT_SHIMS: ReadonlyArray<{
readonly name: string;
readonly envKey: string;
readonly configKey: string;
readonly defaultOn?: boolean;
}> = [
{
name: "recall-inject",
envKey: "OPEN_SECOND_BRAIN_RECALL_INJECT_ENABLED",
configKey: "recall_inject_enabled",
},
{
name: "nav-inject",
envKey: "OPEN_SECOND_BRAIN_NAV_TIER_ENABLED",
configKey: "nav_tier_enabled",
},
{
name: "neighbour-updates",
envKey: "OPEN_SECOND_BRAIN_NEIGHBOUR_UPDATES_ENABLED",
configKey: "neighbour_updates_enabled",
defaultOn: true,
},
{
name: "counterparty-brief",
envKey: "OPEN_SECOND_BRAIN_COUNTERPARTY_BRIEF_ENABLED",
configKey: "counterparty_brief_enabled",
},
{
name: "reground-deliver",
envKey: "OPEN_SECOND_BRAIN_REGROUND_PARTS_ENABLED",
configKey: "reground_parts_enabled",
},
];
/** Disambiguates concurrent spool writes within one process. */
let spoolWriteSeq = 0;
const POST_WRITE_NUDGE =
"Open Second Brain: artifact written. If a taste signal or scoped " +
"preference applies, call brain_feedback / brain_apply_evidence / " +
"brain_note (full contract earlier in this session).";
interface SpoolTurn {
readonly type: "turn";
readonly turnId: string;
readonly timestamp: string;
readonly role: "user" | "assistant" | "system";
readonly text?: string;
readonly toolCalls?: ReadonlyArray<{
readonly name: string;
readonly id?: string;
readonly input: Record<string, unknown>;
}>;
}
function spoolDir(): string {
const override = process.env["OSB_OPENCODE_SPOOL_DIR"];
if (override && override.length > 0) return override;
const xdg = process.env["XDG_DATA_HOME"];
// Mirrors `dataBaseDir` in src/core/platform-dirs.ts (this file is copied
// into opencode's plugin directory and cannot import it): XDG wins, then
// %LOCALAPPDATA% on native Windows, then ~/.local/share.
const local = process.env["LOCALAPPDATA"];
let base: string;
if (xdg && xdg.length > 0) base = xdg;
else if (process.platform !== "win32") base = join(homedir(), ".local", "share");
else base = local && local.length > 0 ? local : join(homedir(), "AppData", "Local");
return join(base, "open-second-brain", "opencode");
}
function sanitizeSessionId(id: string): string | null {
const name = id.replace(/[^A-Za-z0-9._-]/g, "_");
if (name.length === 0 || /^\.{1,2}$/.test(name)) return null;
return name;
}
function asRecord(value: unknown): Record<string, unknown> | null {
if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
return value as Record<string, unknown>;
}
function extractSessionId(properties: unknown): string | null {
const props = asRecord(properties);
if (!props) return null;
if (typeof props["sessionID"] === "string") return props["sessionID"];
const info = asRecord(props["info"]);
if (info && typeof info["id"] === "string") return info["id"];
const session = asRecord(props["session"]);
if (session && typeof session["id"] === "string") return session["id"];
return null;
}
/**
* Normalizes a V1 SDK message (`{info, parts}`) or a V2 session message
* (`{id, type, text|content}`) into a spool turn.
* Unknown roles and empty messages return null and are skipped: the
* spool only carries what the session adapter understands.
*/
function normalizeMessage(message: unknown): SpoolTurn | null {
const m = asRecord(message);
if (!m) return null;
const info = asRecord(m["info"]) ?? m;
if (!info || typeof info["id"] !== "string") return null;
const role = info["role"] ?? info["type"];
if (role !== "user" && role !== "assistant" && role !== "system") return null;
const time = asRecord(info["time"]);
const created = time && typeof time["created"] === "number" ? time["created"] : null;
const timestamp = created !== null ? new Date(created).toISOString() : new Date(0).toISOString();
const texts: string[] = [];
const toolCalls: Array<{ name: string; id?: string; input: Record<string, unknown> }> = [];
if (typeof m["text"] === "string" && m["text"].length > 0) texts.push(m["text"]);
const parts = Array.isArray(m["parts"])
? m["parts"]
: Array.isArray(m["content"])
? m["content"]
: [];
for (const rawPart of parts) {
const part = asRecord(rawPart);
if (!part) continue;
if (part["type"] === "text" && typeof part["text"] === "string" && part["text"].length > 0) {
texts.push(part["text"]);
} else if (part["type"] === "tool") {
const tool = typeof part["tool"] === "string" ? part["tool"] : part["name"];
if (typeof tool !== "string") continue;
const state = asRecord(part["state"]);
const input = state ? (asRecord(state["input"]) ?? {}) : {};
toolCalls.push({
name: tool,
...(typeof part["callID"] === "string"
? { id: part["callID"] }
: typeof part["id"] === "string"
? { id: part["id"] }
: {}),
input,
});
}
}
if (texts.length === 0 && toolCalls.length === 0) return null;
return {
type: "turn",
turnId: info["id"],
timestamp,
role,
...(texts.length > 0 ? { text: texts.join("\n") } : {}),
...(toolCalls.length > 0 ? { toolCalls } : {}),
};
}
/**
* Deterministic snapshot write: same messages produce a byte-identical
* file (no wall-clock fields), so repeated `session.idle` events are
* no-ops for downstream content-hash dedup. Atomic via tmp + rename.
*/
function writeSpool(
sessionId: string,
directory: string,
messages: unknown[],
preserveExisting = false,
revertTo?: string,
): void {
const name = sanitizeSessionId(sessionId);
if (name === null) return;
const meta = {
type: "session_meta",
originator: SPOOL_ORIGINATOR,
format: SPOOL_FORMAT,
session_id: sessionId,
directory,
};
const dir = spoolDir();
mkdirSync(dir, { recursive: true });
const target = join(dir, `${name}.jsonl`);
const turns = new Map<string, SpoolTurn | null>();
if (preserveExisting) {
try {
const lines = readFileSync(target, "utf8").trimEnd().split("\n");
const previous = asRecord(JSON.parse(lines[0]!));
if (previous?.["session_id"] === sessionId && previous["format"] === SPOOL_FORMAT) {
// Include control-message IDs so a revert can target a non-transcript boundary.
if (Array.isArray(previous["message_ids"])) {
for (const id of previous["message_ids"]) {
if (typeof id === "string") turns.set(id, null);
}
}
for (const line of lines.slice(1)) {
const turn = asRecord(JSON.parse(line));
if (turn?.["type"] === "turn" && typeof turn["turnId"] === "string") {
turns.set(turn["turnId"], turn as unknown as SpoolTurn);
}
}
}
} catch {
// A missing or incomplete previous snapshot must not block a fresh one.
}
}
if (revertTo !== undefined) {
const ids = Array.from(turns.keys());
const boundary = ids.indexOf(revertTo);
if (boundary === -1) {
// An older or missed snapshot cannot locate the boundary safely.
// Rebuild from authoritative context rather than reintroducing removed turns.
console.warn(
"Open Second Brain: revert boundary was not captured; rebuilding from active context",
);
turns.clear();
} else {
for (const id of ids.slice(boundary)) turns.delete(id);
}
}
for (const message of messages) {
const record = asRecord(message);
const info = asRecord(record?.["info"]) ?? record;
if (typeof info?.["id"] === "string") turns.set(info["id"], normalizeMessage(message));
}
const lines = [
JSON.stringify({
...meta,
...(preserveExisting ? { message_ids: Array.from(turns.keys()) } : {}),
}),
...Array.from(turns.values())
.filter((turn) => turn !== null)
.map((turn) => JSON.stringify(turn)),
];
spoolWriteSeq += 1;
const tmp = join(dir, `.${name}.jsonl.tmp-${process.pid}-${spoolWriteSeq}`);
writeFileSync(tmp, lines.join("\n") + "\n", "utf8");
renameSync(tmp, target);
}
/** Pulls the message list out of the SDK response defensively. */
function messageList(response: unknown): unknown[] | null {
if (Array.isArray(response)) return response;
const r = asRecord(response);
if (r && Array.isArray(r["data"])) return r["data"];
return null;
}
/**
* The machine config path, matching the core default: the XDG layout on
* POSIX, `%LOCALAPPDATA%\open-second-brain\config.yaml` on native
* Windows (the same resolution `src/core/platform-dirs.ts` and the
* spool-dir resolver below make, so a flag the shims honor is one this
* relay reads); the env override wins. A missing file means every flag
* is off.
*/
function osbConfigPath(): string {
const override = process.env["OPEN_SECOND_BRAIN_CONFIG"]?.trim();
if (override) return override;
const xdg = process.env["XDG_CONFIG_HOME"]?.trim();
let base: string;
if (xdg && xdg.length > 0) {
base = xdg;
} else if (process.platform === "win32") {
base = process.env["LOCALAPPDATA"]?.trim() || join(homedir(), "AppData", "Local");
} else {
base = join(homedir(), ".config");
}
return join(base, "open-second-brain", "config.yaml");
}
/**
* Cut an unquoted trailing `#...` comment: one scan tracking quote
* state, so a `#` INSIDE a quoted value (a vault path like
* `/data/brain#main`) stays whole. The stdlib twin of the canonical
* resolver's quote-aware YAML parsing, as shipped in the hook wrappers.
*/
function stripUnquotedComment(value: string): string {
let quote: string | null = null;
for (let i = 0; i < value.length; i++) {
const ch = value[i]!;
if (quote !== null) {
if (ch === quote) quote = null;
} else if (ch === '"' || ch === "'") {
quote = ch;
} else if (ch === "#") {
return value.slice(0, i);
}
}
return value;
}
/**
* Default-OFF flag read: env (trimmed) wins, then a top-level `key:` in
* the machine config; only literal `true`/`1` is truthy. The stdlib twin
* of `resolveConfigFlag` in src/core/config.ts (this file is copied
* alone into opencode's plugin directory and cannot import it), agreeing
* with the hook wrappers so a flag the shims honor is one the relay
* spawns for; anything else reads off, which keeps the default path at
* zero spawns.
*/
function configFlagOn(envKey: string, configKey: string): boolean {
const raw = configFlagRaw(envKey, configKey);
return raw === "true" || raw === "1";
}
/**
* Default-ON flag read, the twin of `resolveNeighbourUpdatesEnabled`:
* only literal `false`/`0` turns it off; unset or anything else is on.
*/
function configFlagNotOff(envKey: string, configKey: string): boolean {
const raw = configFlagRaw(envKey, configKey);
return raw !== "false" && raw !== "0";
}
/** The flag's value: env (trimmed) first, then the top-level config key; null when unset. */
function configFlagRaw(envKey: string, configKey: string): string | null {
const env = process.env[envKey]?.trim();
if (env) return env;
let text: string;
try {
text = readFileSync(osbConfigPath(), "utf8");
} catch {
return null;
}
// Anchored at column 0: a top-level YAML key has no indentation, and
// an indented match would arm the gate off a key nested under some
// other mapping - the canonical resolver reads top-level keys only.
const match = new RegExp(`^${configKey}\\s*:\\s*(.+?)\\s*$`, "m").exec(text);
if (match === null) return null;
return stripUnquotedComment(match[1]!)
.trim()
.replace(/^["']|["']$/g, "");
}
/**
* One shim spawn, through `hookCommand` - the only `Bun.spawnSync` site
* in this file, so every relay ride keeps the Windows current-directory
* planting guard. Never throws and never decides: every failure mode
* (binary missing, spawn error, timeout, non-zero exit) collapses to
* `ok: false` so callers fail soft.
*/
function spawnHookShim(
shim: string,
payload: Record<string, unknown>,
): { ok: boolean; stdout: string } {
try {
const bin = process.env["OSB_HOOK_BIN"] ?? "o2b-hook";
const command = hookCommand(bin, shim);
if (command === null) return { ok: false, stdout: "" };
const proc = Bun.spawnSync(command.argv, {
stdin: Buffer.from(JSON.stringify(payload)),
stdout: "pipe",
stderr: "ignore",
timeout: HOOK_TIMEOUT_MS,
windowsHide: true,
windowsVerbatimArguments: command.verbatim,
env: command.env,
});
if (!proc.success) return { ok: false, stdout: "" };
return { ok: true, stdout: proc.stdout.toString("utf8").trim() };
} catch {
return { ok: false, stdout: "" };
}
}
/**
* The relay's verdict: exactly the three fields it reads from shim
* stdout. Malformed or empty output parses as a pass with no context,
* so a shim that answers garbage can never block a tool call and never
* injects.
*/
function readHookVerdict(stdout: string): {
deny: boolean;
reason: string | null;
context: string | null;
} {
const pass = { deny: false, reason: null, context: null };
let parsed: Record<string, unknown> | null;
try {
parsed = asRecord(JSON.parse(stdout));
} catch {
return pass;
}
const hookOutput = parsed !== null ? asRecord(parsed["hookSpecificOutput"]) : null;
if (hookOutput === null) return pass;
const reason = hookOutput["permissionDecisionReason"];
const context = hookOutput["additionalContext"];
return {
deny: hookOutput["permissionDecision"] === "deny",
reason: typeof reason === "string" && reason.length > 0 ? reason : null,
context: typeof context === "string" && context.length > 0 ? context : null,
};
}
/** Spawn one shim and read its verdict; a failed spawn passes. */
function spawnHookVerdict(
shim: string,
payload: Record<string, unknown>,
): { deny: boolean; reason: string | null; context: string | null } {
const spawned = spawnHookShim(shim, payload);
if (!spawned.ok) return { deny: false, reason: null, context: null };
return readHookVerdict(spawned.stdout);
}
/**
* Renders the active-context block by spawning the same
* `o2b-hook active-inject` shim the Claude Code and Codex hook layers
* use. Returns null on every failure mode (binary missing, timeout,
* empty or malformed output) — the caller treats null as "no inject".
*/
function renderActiveContext(cwd: string): string | null {
const spawned = spawnHookShim("active-inject", { hook_event_name: "SessionStart", cwd });
if (!spawned.ok) return null;
return readHookVerdict(spawned.stdout).context;
}
/**
* opencode's tool input onto the snake_case keys the shim decision
* cores read: the camelCase `filePath` the host passes is copied to
* `file_path`, everything else rides verbatim. A non-object input
* becomes the empty payload the shims answer allow to.
*/
function translateToolInput(toolInput: unknown): Record<string, unknown> {
if (toolInput === null || typeof toolInput !== "object" || Array.isArray(toolInput)) return {};
const source = toolInput as Record<string, unknown>;
const translated: Record<string, unknown> = { ...source };
if (typeof source["filePath"] === "string" && translated["file_path"] === undefined) {
translated["file_path"] = source["filePath"];
}
// opencode's patch tool carries the diff body under its own key; the
// Codex apply_patch shape the backup shim parses reads `input`.
if (typeof source["patchText"] === "string" && translated["input"] === undefined) {
translated["input"] = source["patchText"];
}
return translated;
}
/**
* The execute.before gate: relay each opt-in PreToolUse shim with a
* synthetic Claude-Code-shaped payload - the host's tool name and
* argument keys translated onto the spellings the shim decision cores
* parse (`pretool-orient` reads `Read` and `file_path`; the backup shim
* reads the Write/Edit family), and an explicit `hook_host` marker so
* runtime detection answers `opencode` instead of guessing. The pure
* decision cores and the vault hook-state ledger see the same view the
* Claude Code lane sees, and the audit trail records the translated
* spellings - the census declares that divergence.
*
* Fail-soft by construction: only an explicit structured
* `permissionDecision: "deny"` throws, carrying the shim's
* `permissionDecisionReason` - the one blocking channel opencode
* offers. A flag that is off (which also means zero spawns), a missing
* binary, a spawn failure, a timeout, malformed stdout, and an
* untranslatable payload all pass the tool call untouched.
*/
function runPretoolGate(call: {
tool: string;
sessionId: string | null;
toolInput: unknown;
cwd: string;
}): void {
let payload: Record<string, unknown>;
try {
payload = {
hook_event_name: "PreToolUse",
...(call.sessionId !== null ? { session_id: call.sessionId } : {}),
hook_host: PAYLOAD_HOST_MARKER,
tool_name: translateToolName(call.tool),
tool_input: translateToolInput(call.toolInput),
cwd: call.cwd,
};
} catch {
return; // a payload this host shape breaks is not a deny: pass
}
const mutating = MUTATING_TOOLS.has(call.tool.toLowerCase());
for (const shim of PRETOOL_SHIMS) {
if (!configFlagOn(shim.envKey, shim.configKey)) continue;
if (shim.mutatingOnly === true && !mutating) continue;
const verdict = spawnHookVerdict(shim.name, payload);
if (verdict.deny) {
throw new Error(
verdict.reason ?? `Open Second Brain: the ${shim.name} gate denied this tool call.`,
);
}
}
}
/**
* The per-turn queue for prompt-time context, keyed by SESSION. The
* plugin instance is server-wide: every session on the opencode host
* shares one queue object, so a single slot would deliver one session's
* recalled vault context into another session's model request and let
* any background request consume the turn's injection. Each session
* owns a single slot: its prompt starts a new turn (replacing any
* payload a previous prompt left undelivered), every answering shim
* appends into that session's slot, and the first model request
* belonging to the session drains it exactly once - the context hooks
* fire per model request, so a turn with several requests would
* otherwise inject the shim payload repeatedly. Events that name no
* session share one session-less bucket, which is the pre-keying
* behavior for hosts that never identify the session. The take-once
* cursor of the reground carrier is the pattern; the active inject's
* TTL cache is deliberately untouched.
*/
function promptContextQueue(): {
beginTurn(sessionId: string | null): void;
offer(sessionId: string | null, text: string): void;
take(sessionId: string | null): string | null;
} {
const slots = new Map<string, string | null>();
return {
beginTurn(sessionId) {
slots.set(sessionId ?? "", null);
},
offer(sessionId, text) {
const key = sessionId ?? "";
const current = slots.get(key);
slots.set(key, current === null || current === undefined ? text : `${current}\n\n${text}`);
},
take(sessionId) {
// Deleted, not nulled: the plugin instance is server-wide and the
// map would otherwise grow one entry per session forever. A
// delivery input that names no session drains only the session-
// less bucket (the empty key) - the one its own prompt events
// wrote to - so no request can ever consume another session's
// queued context.
const key = sessionId ?? "";
const value = slots.get(key) ?? null;
slots.delete(key);
return value;
},
};
}
/** The session id a context-delivery input names, when it names one. */
function contextSessionId(input: unknown): string | null {
const record = asRecord(input);
if (record === null) return null;
const direct = record["sessionID"] ?? record["sessionId"];
if (typeof direct === "string" && direct.length > 0) return direct;
const message = asRecord(record["message"]);
const nested = message?.["sessionID"] ?? message?.["sessionId"];
return typeof nested === "string" && nested.length > 0 ? nested : null;
}
/**
* The user text of one prompt event, across the shapes upstream releases
* have shipped: the text rides the event record, its `message`, or the
* output's `message`/text `parts` (the documented V1 `chat.message`
* shape, whose input carries only session/agent/model ids).
*/
function observePromptText(record: Record<string, unknown>, output: unknown): string | null {
for (const candidate of [record, asRecord(record["message"])]) {
if (candidate === null) continue;
const value = candidate["prompt"] ?? candidate["text"];
if (typeof value === "string" && value.length > 0) return value;
}
const outRecord = asRecord(output);
if (outRecord !== null) {
const message = asRecord(outRecord["message"]);
const messageText = message?.["text"] ?? message?.["content"];
if (typeof messageText === "string" && messageText.length > 0) return messageText;
// Text parts ride the output directly on one shape and inside its
// message on the other; both spellings are joined in part order.
for (const parts of [outRecord["parts"], message?.["parts"]]) {
if (!Array.isArray(parts)) continue;
const text = parts
.map((part) => (asRecord(part)?.["type"] === "text" ? asRecord(part)?.["text"] : null))
.filter((value): value is string => typeof value === "string")
.join("");
if (text.length > 0) return text;
}
}
return null;
}
/**
* Best-effort read of a V1 `chat.message` / V2 `prompt` event: the
* prompt text plus the opencode session id (the ledger inside the vault
* hook-state dedupes on it). The id is taken only where a SESSION id can
* appear - the record or its message's `sessionID`, or the `session`
* record's own id - never a top-level or message `id`, which on the
* documented V1 shape is a MESSAGE id and would key the per-session
* ledger per message.
*/
function observePrompt(
event: unknown,
output?: unknown,
): { prompt: string | null; sessionId: string | null } {
const record = asRecord(event);
if (record === null) return { prompt: null, sessionId: null };
const prompt = observePromptText(record, output);
let sessionId: string | null = null;
for (const candidate of [record, asRecord(record["message"]), asRecord(record["session"])]) {
if (candidate === null) continue;
const value =
candidate === record || candidate === asRecord(record["message"])
? candidate["sessionID"]
: (candidate["id"] ?? candidate["sessionID"]);
if (typeof value === "string" && value.length > 0) {
sessionId = value;
break;
}
}
return { prompt, sessionId };
}
/**
* The prompt lane: relay each opt-in UserPromptSubmit shim with a
* synthetic Claude-Code-shaped payload carrying the opencode session id,
* so the vault hook-state ledger (recall once per session, brief on the
* first qualifying turn, reground's take-once cursor) dedupes exactly as
* on the Claude Code lane. Returned additionalContext enters the
* per-turn queue; nothing here throws - a broken shim or a flag that is
* off (zero spawns) just means no context this turn.
*/
function runPromptShims(call: {
prompt: string;
sessionId: string | null;
cwd: string;
queue: ReturnType<typeof promptContextQueue>;
}): void {
call.queue.beginTurn(call.sessionId);
const payload: Record<string, unknown> = {
hook_event_name: "UserPromptSubmit",
...(call.sessionId !== null ? { session_id: call.sessionId } : {}),
prompt: call.prompt,
cwd: call.cwd,
};
for (const shim of PROMPT_SHIMS) {
const on =
shim.defaultOn === true
? configFlagNotOff(shim.envKey, shim.configKey)
: configFlagOn(shim.envKey, shim.configKey);
if (!on) continue;
const verdict = spawnHookVerdict(shim.name, payload);
if (verdict.context !== null) call.queue.offer(call.sessionId, verdict.context);
}
}
/** Each loaded plugin instance has its own short-lived active-context cache. */
function activeContextFor(cwd: string): () => string | null {
let cache: { value: string | null; at: number } | null = null;
return () => {
const now = Date.now();
const ttl = cache?.value === null ? ACTIVE_CONTEXT_NEGATIVE_TTL_MS : ACTIVE_CONTEXT_TTL_MS;
if (cache === null || now - cache.at > ttl) {
cache = { value: renderActiveContext(cwd), at: now };
}
return cache.value;
};
}
/**
* How to start the `o2b-hook` shim `bin` (a bare name or a path) with the
* subcommand `shim` (the hook entry point, e.g. `active-inject`), or null
* when it cannot be found. The single argv builder for every spawn in
* this file - no second builder may appear, or the Windows guard below
* stops covering the new site.
*
* POSIX: `bin` itself - `execvp` searches PATH only.
*
* Native Windows: the shim is `o2b-hook.cmd`, which Bun.spawn cannot start
* from a bare name (it resolves `.exe` only), so it runs through cmd.exe.
* But cmd.exe looks for a bare name in the current directory before PATH,
* and opencode runs in the project it opened: `cmd /c o2b-hook` would run
* an `o2b-hook.cmd` that repository ships. So the name is resolved to an
* absolute path here first, with `Bun.which` (PATH only, never the
* current directory), and cmd gets that path - quoted as a whole with
* `/s`, the form Node uses for `shell: true`, so spaces and parentheses in
* it survive. `NoDefaultCurrentDirectoryInExePath` covers the launcher's
* own `bun` lookup as well. `OSB_HOOK_BIN` is operator-controlled; the
* resolved path is the only non-literal in the command line.
*/
function hookCommand(
bin: string,
shim: string,
): {
readonly argv: string[];
readonly verbatim: boolean;
readonly env: Record<string, string | undefined> | undefined;
} | null {
if (process.platform !== "win32") return { argv: [bin, shim], verbatim: false, env: undefined };
const resolved = Bun.which(bin, { PATH: process.env["PATH"] ?? "" });
if (resolved === null) return null;
const comspec = process.env["ComSpec"];
const systemRoot = process.env["SystemRoot"] || "C:\\Windows";
return {
argv: [
comspec && comspec.length > 0 ? comspec : join(systemRoot, "System32", "cmd.exe"),
"/d",
"/s",
"/c",
`""${resolved}" ${shim}"`,
],
verbatim: true,
env: { ...process.env, NoDefaultCurrentDirectoryInExePath: "1" },
};
}
/**
* V1 entry point, called through the default export's server() method.
*/
const openSecondBrainV1 = async (pluginInput: {
client: unknown;
project?: unknown;
directory?: string;
worktree?: string;
}) => {
const directory = typeof pluginInput.directory === "string" ? pluginInput.directory : "";
const worktree = typeof pluginInput.worktree === "string" ? pluginInput.worktree : "";
// Anchor active-inject to the real project scope, not an arbitrary dir.
const injectCwd = worktree || directory || process.cwd();
const client = asRecord(pluginInput.client);
const getActiveContext = activeContextFor(injectCwd);
const promptQueue = promptContextQueue();
async function captureSession(sessionId: string): Promise<void> {
const session = client ? asRecord(client["session"]) : null;
const messages = session ? session["messages"] : null;
if (typeof messages !== "function") return;
// Invoke as a method bound to `session`: the opencode SDK client
// dereferences `this._client` internally, so a detached call
// (`messages(...)`) throws "undefined is not an object". Reflect.apply
// carries the receiver without re-narrowing the SDK's untyped shape.
const response: unknown = await Reflect.apply(messages, session, [{ path: { id: sessionId } }]);
const list = messageList(response);
if (list === null) return;
writeSpool(sessionId, directory, list);
}
return {
event: async ({ event }: { event: { type?: string; properties?: unknown } }) => {
try {
if (typeof event?.type !== "string" || !CAPTURE_EVENTS.has(event.type)) return;
const sessionId = extractSessionId(event.properties);
if (sessionId === null) return;
await captureSession(sessionId);
} catch {
// Capture is best-effort; never break the operator's session.
}
},
"experimental.chat.system.transform": async (input: unknown, output: { system: string[] }) => {
try {
if (!Array.isArray(output?.system)) return;
const context = getActiveContext();
if (context !== null) {
output.system.push(context);
}
// Drain the prompt lane's per-turn queue beside the cached active
// inject: the first model request BELONGING TO THE PROMPTING
// SESSION delivers it, the take() clearing makes later requests in
// the turn no-ops, and another session's request drains nothing.
const queued = promptQueue.take(contextSessionId(input));
if (queued !== null) {
output.system.push(queued);
}
} catch {
// Inject is a nicety; the session works without it.
}
},
"chat.message": async (input: unknown, output: unknown) => {
try {
const observed = observePrompt(input, output);
if (observed.prompt === null) return;
runPromptShims({
prompt: observed.prompt,
sessionId: observed.sessionId,
cwd: injectCwd,
queue: promptQueue,
});
} catch {
// Prompt-time injection is best-effort; the turn proceeds without it.
}
},
"tool.execute.after": async (input: { tool?: string }, output: { output?: unknown }) => {
try {
const tool = typeof input?.tool === "string" ? input.tool.toLowerCase() : "";
if (!MUTATING_TOOLS.has(tool)) return;
if (output && typeof output.output === "string") {
output.output = `${output.output}\n\n${POST_WRITE_NUDGE}`;
}
} catch {
// Reminder is a nicety; tool output stays untouched on failure.
}
},
"tool.execute.before": (
input: { tool?: string; sessionID?: string },
output: { args?: unknown },
) => {
runPretoolGate({
tool: typeof input?.tool === "string" ? input.tool : "",
sessionId: typeof input?.sessionID === "string" ? input.sessionID : null,
toolInput: output?.args,
cwd: injectCwd,
});
},
};
};
interface V2Context {
location: { directory: string };
session: {
hook(
name: "context",
callback: (event: {
system: Array<{ type: "text"; text: string }>;
/** The session the model request belongs to, when the host names it. */
sessionID?: string;
}) => void,
): Promise<unknown>;
hook(name: "prompt", callback: (event: unknown) => void): Promise<unknown>;
get(input: { sessionID: string }): Promise<unknown>;
context(input: { sessionID: string }): Promise<unknown>;
};
tool: {
hook(
name: "execute.after",
callback: (event: {
tool: string;
status: string;
result?: { content: unknown[]; [key: string]: unknown };
}) => void,
): Promise<unknown>;
hook(
name: "execute.before",
callback: (input: { tool?: string; sessionID?: string }, output: { args?: unknown }) => void,
): Promise<unknown>;
};
event: {
subscribe(input: { signal: AbortSignal }): AsyncIterable<{
type?: string;
data?: unknown;
properties?: unknown;
location?: { directory?: string };
}>;
};
}
/**
* One best-effort registration: a V2 host that rejects a hook name
* (the newer names are feature-detected upstream, so an older build
* may refuse them) must degrade that one hook to a no-op instead of
* killing setup - capture and every later hook would otherwise never
* start.
*/
async function registerV2Hook(register: () => Promise<unknown>): Promise<void> {
try {
await register();
} catch {
// The hook stays unregistered; everything else keeps working.
}
}
/** V2 reads this default definition; V1 calls server() on the same object. */
export default {
id: "open-second-brain",
server: openSecondBrainV1,
async setup(ctx: V2Context) {
// V1's experimental V2 loader also calls setup(), but without these
// capabilities; its separate V1 loader still runs server().
if (
typeof ctx?.location?.directory !== "string" ||
typeof ctx.session?.hook !== "function" ||
typeof ctx.session?.get !== "function" ||
typeof ctx.session?.context !== "function" ||
typeof ctx.tool?.hook !== "function" ||
typeof ctx.event?.subscribe !== "function"
)
return;
const directory = ctx.location.directory;
const getActiveContext = activeContextFor(directory);
const promptQueue = promptContextQueue();
await registerV2Hook(() =>
ctx.session.hook("context", (event) => {
try {
const context = getActiveContext();
if (context !== null) event.system.push({ type: "text", text: context });
// Drain the prompt lane's per-turn queue beside the cached
// active inject; the take() clearing delivers the queued
// context exactly once per turn even when this hook fires for
// several model requests, and only for the session the prompt
// came from.
const queued = promptQueue.take(contextSessionId(event));
if (queued !== null) event.system.push({ type: "text", text: queued });
} catch {
// Context injection is best-effort.
}
}),
);
await registerV2Hook(() =>
ctx.session.hook("prompt", (event: unknown) => {
try {
const observed = observePrompt(event);
if (observed.prompt === null) return;
runPromptShims({
prompt: observed.prompt,
sessionId: observed.sessionId,
cwd: directory,
queue: promptQueue,
});
} catch {
// Prompt-time injection is best-effort; the turn proceeds without it.
}
}),
);
await registerV2Hook(() =>
ctx.tool.hook("execute.after", (event) => {
try {
if (event.status !== "completed" || !MUTATING_TOOLS.has(event.tool.toLowerCase())) return;
if (!event.result || !Array.isArray(event.result.content)) return;
event.result = {
...event.result,
content: [...event.result.content, { type: "text", text: POST_WRITE_NUDGE }],
};
} catch {
// Reminder is best-effort; tool results remain untouched on failure.
}
}),
);
await registerV2Hook(() =>
ctx.tool.hook("execute.before", (input, output) => {
runPretoolGate({
tool: typeof input?.tool === "string" ? input.tool : "",
sessionId: typeof input?.sessionID === "string" ? input.sessionID : null,
toolInput: output?.args,
cwd: directory,
});
}),
);
const controller = new AbortController();
void (async () => {
let retryDelay = 1_000;
while (!controller.signal.aborted) {
try {
for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
retryDelay = 1_000;
try {
if (!event || !V2_CAPTURE_EVENTS.has(event.type ?? "")) continue;
const sessionID = extractSessionId(event.data ?? event.properties);
if (sessionID === null) continue;
// The event stream is server-wide, not scoped to this plugin's location.
const eventDirectory = event.location?.directory;
if (eventDirectory && eventDirectory !== directory) continue;
if (!eventDirectory) {
const session = asRecord(await ctx.session.get({ sessionID }));
const location = asRecord(session?.["location"]);
if (location?.["directory"] !== directory) continue;
}
const revertTo =
event.type === "session.revert.committed"
? asRecord(event.data ?? event.properties)?.["to"]
: undefined;
if (event.type === "session.revert.committed" && typeof revertTo !== "string")
continue;
const messages = messageList(await ctx.session.context({ sessionID }));
if (messages !== null)
writeSpool(sessionID, directory, messages, true, revertTo as string | undefined);
} catch {
// A failed snapshot must not stop later session captures.
}
}
} catch {
// Subscriptions are live-only and do not reconnect automatically.
}
if (controller.signal.aborted) break;
console.warn(`Open Second Brain: capture stream ended; retrying in ${retryDelay}ms`);
try {
await sleep(retryDelay, undefined, { signal: controller.signal, ref: false });
} catch {
break; // Cleanup aborts a pending retry immediately.
}
retryDelay = Math.min(retryDelay * 2, 30_000);
}
})();
return () => controller.abort();
},
};