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
7.8 KB
Raw Blame
import {
  PermissionsDocumentError,
  type PermissionAction,
  type PermissionsDocument,
} from "../../../core/brain/permissions/document.ts";
import { loadPermissionsDocumentFor } from "../../../core/brain/permissions/document-source.ts";
import {
  queryDecisionLedger,
  type DecisionLedgerFilter,
  type DecisionLedgerRow,
} from "../../../core/brain/permissions/ledger.ts";
import { resolvePermission } from "../../../core/brain/permissions/resolve.ts";
import {
  brainVerbContext,
  fail,
  normalizeFlagString,
  ok,
  okJson,
  parse,
  usageError,
  type BrainVerbFlags,
} from "../helpers.ts";

/**
 * `o2b brain permissions` - the operator surface over the vault's trust
 * policy (write-side-trust, Task 4).
 *
 * Subcommands:
 *   show    render the effective document plus a dry-run decision table
 *           over the agents it declares
 *   ledger  list the decision ledger rows the gates appended
 *
 * `show` exists because `default_action: deny` is a foot-gun: a one-agent
 * document denies everything else by construction, and the table makes
 * that visible before the first refusal does. Both subcommands are pure
 * reads; neither mutates the vault.
 *
 * A document that cannot be read is never smoothed over: `show` fails
 * naming the field the loader refused, and `o2b brain doctor` reports the
 * same fault under `permissions-unreadable` - whose exit is this verb.
 */
export async function cmdBrainPermissions(argv: string[]): Promise<number> {
  const sub = argv[0];
  const rest = argv.slice(1);
  const { flags } = parse(rest, {
    vault: { type: "string" },
    json: { type: "boolean" },
    actor: { type: "string" },
    action: { type: "string" },
    verdict: { type: "string" },
    since: { type: "string" },
    until: { type: "string" },
    limit: { type: "string" },
  });
  const json = flags["json"] === true;

  if (sub === "show") return show(flags, json);
  if (sub === "ledger") return ledger(flags, json);
  return usageError("brain permissions requires a subcommand: show | ledger");
}

// ----- show -----------------------------------------------------------------

/** The actions one dry-run row resolves, in the document's vocabulary order. */
const RESOLVED_ACTIONS: ReadonlyArray<PermissionAction> = ["write", "ingest", "owner_write"];

/** One resolved row of the dry-run decision table. */
interface DecisionTableRow {
  agent: string;
  role: string;
  action: PermissionAction;
  /** Empty for the blanket row; a declared target for the scoped rows. */
  target: string;
  verdict: string;
  source: string;
}

function show(flags: BrainVerbFlags, json: boolean): number {
  const { vault } = brainVerbContext(flags);
  try {
    const { document, path } = loadPermissionsDocumentFor(vault);
    if (document === null) {
      if (json) {
        okJson({ document: null, path });
      } else {
        ok(`no permissions document at ${path} - every write is ungated`);
      }
      return 0;
    }
    const decisions = decisionTable(document);
    if (json) {
      okJson({ document: { ...document }, decisions });
    } else {
      for (const line of renderShow(path, document, decisions)) ok(line);
    }
    return 0;
  } catch (exc) {
    if (exc instanceof PermissionsDocumentError) return fail(exc.message);
    return fail(`failed to read the permissions document: ${(exc as Error).message}`);
  }
}

/**
 * Resolve every declared agent against every action - once as a blanket
 * query, and once per target the document's entries name for that agent,
 * because a target-scoped entry is exactly the rule a blanket row hides.
 * Rows are sorted by construction: agents sorted, actions in vocabulary
 * order, targets sorted within their action.
 */
function decisionTable(document: PermissionsDocument): DecisionTableRow[] {
  const rows: DecisionTableRow[] = [];
  for (const agent of Object.keys(document.agents).toSorted()) {
    const role = document.agents[agent]?.role ?? "";
    for (const action of RESOLVED_ACTIONS) {
      const blanket = resolvePermission(document, { agent, via: "operator" }, action);
      rows.push({
        agent,
        role,
        action,
        target: "",
        verdict: blanket.verdict,
        source: blanket.source,
      });
      for (const target of declaredTargets(document, agent, action)) {
        const scoped = resolvePermission(document, { agent, via: "operator" }, action, target);
        rows.push({
          agent,
          role,
          action,
          target,
          verdict: scoped.verdict,
          source: scoped.source,
        });
      }
    }
  }
  return rows;
}

/** The distinct targets the document's entries declare for one agent and action. */
function declaredTargets(
  document: PermissionsDocument,
  agent: string,
  action: PermissionAction,
): string[] {
  const targets = new Set<string>();
  for (const entry of document.entries) {
    if (entry.agent === agent && entry.action === action && entry.target !== undefined) {
      targets.add(entry.target);
    }
  }
  return [...targets].toSorted();
}

function renderShow(
  path: string,
  document: PermissionsDocument,
  decisions: DecisionTableRow[],
): string[] {
  const lines: string[] = [
    `permissions document: ${path} (version ${document.version})`,
    `default_action: ${document.default_action}`,
  ];
  const roleNames = Object.keys(document.roles).toSorted();
  if (roleNames.length > 0) {
    lines.push("roles:");
    for (const name of roleNames) {
      const actions = Object.entries(document.roles[name] ?? {})
        .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
        .map(([action, verdict]) => `${action}=${verdict}`)
        .join(", ");
      const members = Object.keys(document.agents)
        .filter((agent) => document.agents[agent]?.role === name)
        .toSorted();
      lines.push(
        `  ${name}: ${actions === "" ? "(no action mapped)" : actions} ` +
          `(members: ${members.length > 0 ? members.join(", ") : "none"})`,
      );
    }
  }
  if (decisions.length === 0) {
    lines.push("no agents declared - the default_action decides every subject");
    return lines;
  }
  lines.push(`decision table (dry run, via=operator, ${decisions.length} rows):`);
  for (const row of decisions) {
    const target = row.target === "" ? "-" : row.target;
    lines.push(
      `  ${row.agent}  ${row.role === "" ? "-  " : `${row.role}  `}${row.action}  ` +
        `${target}  ${row.verdict}  ${row.source}`,
    );
  }
  return lines;
}

// ----- ledger ---------------------------------------------------------------

function ledger(flags: BrainVerbFlags, json: boolean): number {
  const { vault } = brainVerbContext(flags);
  const filter: DecisionLedgerFilter = {};
  for (const key of ["actor", "action", "verdict", "since", "until"] as const) {
    const value = normalizeFlagString(flags[key]);
    if (value !== null) filter[key] = value;
  }
  const limitRaw = normalizeFlagString(flags["limit"]);
  if (limitRaw !== null) {
    const limit = Number.parseInt(limitRaw, 10);
    if (!Number.isInteger(limit) || limit <= 0) {
      return usageError("brain permissions ledger --limit must be a positive integer");
    }
    filter.limit = limit;
  }

  try {
    const rows = queryDecisionLedger(vault, filter);
    if (json) {
      okJson({ rows });
      return 0;
    }
    if (rows.length === 0) {
      ok("no decision ledger rows");
      return 0;
    }
    for (const row of rows) ok(renderLedgerRow(row));
    return 0;
  } catch (exc) {
    return fail(`failed to read the decision ledger: ${(exc as Error).message}`);
  }
}

/** One row, fixed column order so a scan down the output stays aligned. */
function renderLedgerRow(row: DecisionLedgerRow): string {
  return [
    row.ts,
    row.actor,
    `via=${row.via}`,
    row.action,
    row.target,
    row.verdict,
    `source=${row.source}`,
    row.reason,
  ].join("  ");
}