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
5.7 KB
Raw Blame
/**
 * `o2b brain design-note <topic>` (t_c87644b4): the one-shot sibling of
 * `o2b brain panel`.
 *
 * Without a payload the verb is read-only: it grounds the topic in the
 * vault's tensions, decisions and truth projections and prints the single
 * needs-llm-step envelope the calling agent answers. With `--payload` /
 * `--payload-file` it validates that answer - shape, then the
 * exactly-one-recommended rule - and commits the note under
 * `Brain/decisions/`. No model is ever called.
 *
 * Exit codes: 0 on success, 1 on an operational failure or a refused
 * payload, 2 on usage errors.
 */

import { readFileSync } from "node:fs";
import { relative } from "node:path";

import { canonicalNotePath } from "../../../core/path-safety.ts";

import {
  commitDesignNote,
  DesignNoteError,
  planDesignNote,
} from "../../../core/brain/design-note.ts";
import { gatedOwnerScopeView } from "../../../core/brain/owner-scope-view.ts";
import {
  parsePayloadJson,
  PayloadJsonError,
  payloadStripNote,
  type PayloadStrip,
} from "../../../core/brain/payload-json.ts";
import { ResponseCheckError } from "../../../core/brain/response-checks.ts";
import { ResponseShapeError } from "../../../core/brain/response-shape.ts";
import {
  brainVerbContext,
  fail,
  ok,
  okJson,
  parse,
  resolveBrainAgent,
  usageError,
} from "../helpers.ts";

const USAGE =
  "usage: o2b brain design-note <topic> [--payload <json> | --payload-file <path>] " +
  "[--agent <name>] [--vault <path>] [--json]";

/** Refusals the caller caused, reported without a stack. */
const NAMED_REFUSALS = [DesignNoteError, ResponseShapeError, ResponseCheckError] as const;

function isNamedRefusal(err: unknown): err is Error {
  return NAMED_REFUSALS.some((type) => err instanceof type);
}

export async function cmdBrainDesignNote(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    agent: { type: "string" },
    payload: { type: "string" },
    "payload-file": { type: "string" },
    json: { type: "boolean" },
  });
  const topic = positional.join(" ").trim();
  if (topic === "") return usageError(USAGE);
  const asJson = flags["json"] === true;

  try {
    const { config, vault } = brainVerbContext(flags);
    const rawPayload =
      typeof flags["payload"] === "string"
        ? (flags["payload"] as string)
        : typeof flags["payload-file"] === "string"
          ? readFileSync(flags["payload-file"] as string, "utf8")
          : null;

    if (rawPayload === null) {
      const report = planDesignNote(vault, topic, {
        now: new Date(),
        ownerScope: gatedOwnerScopeView(vault, resolveBrainAgent(flags, config)).scope,
      });
      const g = report.grounding;
      if (asJson) {
        okJson({
          ok: true,
          topic: report.topic,
          slug: report.slug,
          generated_at: report.generatedAt,
          target_path: report.targetPath,
          grounding: {
            tensions: g.tensions,
            decisions: g.decisions,
            truth_slots: g.truthSlots,
            conflicts: g.conflicts,
            counts: g.counts,
            empty_stores: g.emptyStores,
          },
          llm_step: report.llmStep,
        });
        return 0;
      }
      ok(`design note: ${report.topic}`);
      ok(
        `grounding: ${g.counts.tensions} tension(s), ${g.counts.decisions} decision(s), ` +
          `${g.counts.truthSlots} claim(s), ${g.counts.conflicts} conflict(s)`,
      );
      // Named rather than implied: an empty store and a store that matched
      // nothing are different facts about this vault.
      if (g.emptyStores.length > 0) ok(`empty stores: ${g.emptyStores.join(", ")}`);
      ok(`needs-llm-step: ${report.llmStep.step} -> ${report.llmStep.target_path}`);
      return 0;
    }

    let payload: unknown;
    let strip: PayloadStrip | undefined;
    try {
      const parsed = parsePayloadJson(rawPayload);
      payload = parsed.payload;
      strip = parsed.strip;
    } catch (error) {
      // Reported here rather than by the ingress: at this point the mistake
      // is the JSON the operator typed, and a path inside a payload the CLI
      // never parsed would not tell them what to fix. A refusal after a
      // strip attempt names the attempt (t_dac8bf7e).
      if (error instanceof PayloadJsonError) {
        if (!asJson) return fail(error.message);
        okJson({ ok: false, message: error.message });
        return 1;
      }
      throw error;
    }
    const res = commitDesignNote(vault, topic, payload, {
      agent: resolveBrainAgent(flags, config),
      now: new Date(),
    });
    if (asJson) {
      okJson({
        ok: true,
        topic: res.topic,
        slug: res.slug,
        // Vault-relative, like the distill surface and the MCP twin: the
        // absolute host path is the operator-supplied vault prefix composed
        // with a machine-derived subtree, and this output lands in model
        // context.
        path: canonicalNotePath(relative(vault, res.path)),
        recommended: res.recommended,
        alternative_count: res.alternativeCount,
        // Present only when a leading <think> block was stripped (t_dac8bf7e).
        ...(strip !== undefined ? { note: payloadStripNote(strip) } : {}),
      });
      return 0;
    }
    ok(`wrote ${canonicalNotePath(relative(vault, res.path))}`);
    ok(`recommended: ${res.recommended} (of ${res.alternativeCount} alternative(s))`);
    if (strip !== undefined) ok(payloadStripNote(strip));
    return 0;
  } catch (err) {
    const message = isNamedRefusal(err)
      ? err.message
      : `design-note failed: ${(err as Error).message ?? String(err)}`;
    if (asJson) {
      okJson({ ok: false, message });
      return 1;
    }
    return fail(message);
  }
}