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
2.9 KB
Raw Blame
/**
 * Shared external-command JSON bridge (continuity-hygiene-freshness
 * suite).
 *
 * The Brain core stays deterministic: no LLM (or any other external
 * judgment) ever runs inside the harness. When a feature wants an
 * external opinion - the bench judge, the hygiene conflict resolver -
 * it goes through this one boundary: a configured shell command
 * receives the question as JSON on stdin and answers with JSON on
 * stdout. The bridge is advisory and fail-open by contract: an absent
 * command skips, and every failure mode (non-zero exit, signal kill,
 * timeout, malformed JSON) reports `error` instead of throwing, so a
 * broken bridge can never take down the deterministic path around it.
 */

import { spawnSync } from "node:child_process";

export interface JsonCommandBridgeOptions {
  /** Kill the command after this many milliseconds (default 60s). */
  readonly timeoutMs?: number;
  /** Noun used in error details, e.g. "judge command" (default "command"). */
  readonly label?: string;
}

export type JsonCommandBridgeResult =
  | { readonly status: "skipped" }
  | { readonly status: "ran"; readonly output: unknown }
  | { readonly status: "error"; readonly detail: string };

const DEFAULT_TIMEOUT_MS = 60_000;

/**
 * The shell an operator-configured command line runs under: `sh -c` on
 * POSIX, `cmd.exe /d /s /c` on native Windows (the same invocation Node
 * uses for `shell: true`; `/d` skips AutoRun, whose output would corrupt
 * the JSON on stdout). Exported because the maintenance lane's custom
 * tasks run an operator-configured command line too, and one invocation
 * form for both keeps the Windows quoting in one place.
 */
export function shellArgv(cmd: string): [string, string[]] {
  if (process.platform === "win32") {
    return [process.env["ComSpec"] || "cmd.exe", ["/d", "/s", "/c", `"${cmd}"`]];
  }
  return ["sh", ["-c", cmd]];
}

/**
 * Run `cmd` through the platform shell with `input` serialized as JSON on
 * stdin and parse its stdout as JSON. Never throws.
 */
export function runJsonCommandBridge(
  cmd: string | undefined,
  input: unknown,
  opts: JsonCommandBridgeOptions = {},
): JsonCommandBridgeResult {
  if (cmd === undefined || cmd.trim() === "") return Object.freeze({ status: "skipped" });
  const label = opts.label ?? "command";
  try {
    const [shell, argv] = shellArgv(cmd);
    const proc = spawnSync(shell, argv, {
      input: JSON.stringify(input),
      windowsVerbatimArguments: process.platform === "win32",
      encoding: "utf8",
      timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
    });
    if (proc.status !== 0) {
      return Object.freeze({
        status: "error",
        detail: `${label} exited ${proc.status ?? "by signal"}`,
      });
    }
    return Object.freeze({ status: "ran", output: JSON.parse(proc.stdout) as unknown });
  } catch (error) {
    return Object.freeze({
      status: "error",
      detail: error instanceof Error ? error.message : `${label} failed`,
    });
  }
}