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
23.2 KB
Raw Blame
/**
 * `o2b brain dream [run] [--dry-run] [--step S] [--gate N=V] | stage |
 * validate <run-id> | apply <run-id> | retriage <run-id> | discard
 * <run-id> | list` - the learning pass plus the staged lifecycle
 * (t_ae8a8ec0). `run` (the default, kept positional-free for back-compat)
 * promotes inline; `stage` persists a reviewable proposal bundle;
 * `validate` proves the vault has not drifted; `apply` re-validates and
 * runs the same engine live; `retriage` re-runs the salience gate against
 * the current threshold and reports what would move; `discard` drops the
 * bundle.
 *
 * `--step` and `--gate` (no-dead-ends, Unit E - operator surface) are
 * the shell reach for the two capabilities that previously existed only
 * as TypeScript arguments: `runDreamStep` and `DreamOptions.gates`.
 * Both belong to the default `run` action and both refuse by name -
 * `--step` through `DreamStepNotRunnableError`, which carries the
 * specific reason and the runnable set, and `--gate` through
 * `DreamGateOverrideError`. Neither writes anything back to
 * `Brain/_brain.yaml`; with both absent the verb is byte-identical.
 *
 * Exit codes: 0 on success, 1 on operational failure (including a
 * failed validation - scripts gate on it), 2 on usage errors, which is
 * where a refused step or gate lands: the request was understood and
 * declined, not attempted and broken.
 */

import { resolveAgentName } from "../../../core/config.ts";
import { dream, type DreamGateOverrides } from "../../../core/brain/dream.ts";
import { CountGuardError, assertExpectedCount } from "../../../core/brain/count-guard.ts";
import {
  DREAM_GATE_NAMES,
  DreamGateOverrideError,
  parseDreamGateOverrides,
} from "../../../core/brain/dream-gates.ts";
import {
  DREAM_STEP_RUNNABLE,
  DreamStepNotRunnableError,
  runDreamStep,
  type DreamStepResult,
} from "../../../core/brain/dream-step.ts";
import {
  applyDreamBundle,
  discardDreamBundle,
  DreamRetriageError,
  listDreamBundles,
  retriageDreamBundle,
  stageDream,
  validateDreamBundle,
  type DreamRetriageEntry,
} from "../../../core/brain/dream-stage.ts";
import {
  createSafeguard,
  OPERATION,
  resolveSafeguardTimeoutMs,
  SafeguardTimeoutError,
} from "../../../core/brain/safeguard.ts";
import {
  prepareTopicVerdicts,
  type PrepareTopicVerdictsOptions,
} from "../../../core/topics/decide-auto.ts";
import { nextCommandField } from "../../../core/brain/next-step.ts";
import { emitNextStep } from "../../advisory-rail.ts";
import { attachProgress, reportProgressRefusal } from "../../progress-rail.ts";
import {
  brainVerbContext,
  describeErrorChain,
  fail,
  ok,
  okJson,
  parse,
  parseOptionalIsoDate,
  requireBrainVaultFor,
} from "../helpers.ts";

// The runnable set is read from the step registry, never retyped: a
// usage line that advertises a step the pass refuses is its own dead end.
const USAGE =
  `usage: o2b brain dream [run] [--dry-run] [--step <${DREAM_STEP_RUNNABLE.join("|")}>] ` +
  `[--gate <${DREAM_GATE_NAMES.join("|")}>=<true|false>] | ` +
  "stage | validate <run-id> | apply <run-id> | retriage <run-id> | discard <run-id> | list  " +
  "[--now ISO] [--agent A] [--vault <path>] [--json]";

const ACTIONS = new Set(["run", "stage", "validate", "apply", "retriage", "discard", "list"]);

/** Staged actions that name one bundle. */
const RUN_ID_ACTIONS = new Set(["validate", "apply", "retriage", "discard"]);

/**
 * Refuse a request this verb understood and declined. Exit 2, with the
 * reason on stderr for a human and as a payload for a machine - never a
 * stray line on a stream a caller parses.
 */
function refuse(message: string, asJson: boolean, payload: Record<string, unknown> = {}): number {
  if (asJson) {
    okJson({ ok: false, ...payload, message });
    return 2;
  }
  process.stderr.write(`error: ${message}\n`);
  return 2;
}

/** `--json` row for one fact the gate would move. */
function retriageRow(entry: DreamRetriageEntry): Record<string, unknown> {
  return {
    pref_id: entry.pref_id,
    path: entry.path,
    score: entry.score,
    staged_score: entry.staged_score,
  };
}

/** An absent threshold reads as a word, never as a number the operator did not set. */
function describeThreshold(threshold: number | null): string {
  return threshold === null ? "absent" : String(threshold);
}

/** Print one side of a retriage delta, naming every fact in it. */
function printRetriageDelta(label: string, entries: ReadonlyArray<DreamRetriageEntry>): void {
  ok(`${label}: ${entries.length}`);
  for (const entry of entries) {
    const staged = entry.staged_score === null ? "not scored" : String(entry.staged_score);
    ok(`  ${entry.pref_id}  ${entry.score} (staged ${staged})`);
  }
}

/** Render one partial step result as the verb's human line format. */
function printStepResult(result: DreamStepResult): void {
  ok(`step: ${result.step}`);
  if (result.step === "scan") {
    ok(`active_signals: ${result.active_signals}`);
    ok(`processed_signals: ${result.processed_signals}`);
    ok(`preferences: ${result.preferences}`);
    ok(`retired: ${result.retired}`);
    if (result.corrupted.length > 0) ok(`corrupted: ${result.corrupted.join(", ")}`);
    return;
  }
  ok(`scanned: ${result.scanned}`);
  ok(`enriched: ${result.enriched}`);
  if (result.pages.length > 0) ok(`pages: ${result.pages.join(", ")}`);
}

export async function cmdBrainDream(argv: string[]): Promise<number> {
  const { flags, positional } = parse(argv, {
    vault: { type: "string" },
    "dry-run": { type: "boolean" },
    now: { type: "string" },
    agent: { type: "string" },
    expect: { type: "string" },
    strict: { type: "boolean" },
    step: { type: "string" },
    gate: { type: "string-array" },
    progress: { type: "boolean" },
    json: { type: "boolean" },
  });
  const asJson = flags["json"] === true;
  const action = positional[0] ?? "run";
  if (!ACTIONS.has(action)) {
    process.stderr.write(`${USAGE}\n`);
    return 2;
  }
  const needsRunId = RUN_ID_ACTIONS.has(action);
  if (needsRunId ? positional.length !== 2 : positional.length > 1) {
    process.stderr.write(`${USAGE}\n`);
    return 2;
  }

  // --- Operator-surface argument checks (no-dead-ends, Unit E) --------
  // Both live on the default `run` action and each is refused by name
  // where it would otherwise be accepted and quietly ignored.
  const stepRequest = flags["step"];
  const gateEntries = (flags["gate"] as string[] | undefined) ?? [];
  const wantsStep = typeof stepRequest === "string";
  if ((wantsStep || gateEntries.length > 0) && action !== "run") {
    return refuse(
      `brain dream: --step and --gate steer the default 'run' action; ` +
        `'${action}' drives the staged lifecycle, which has neither a single step nor a gate to override`,
      asJson,
      { action },
    );
  }
  if (wantsStep) {
    // Every flag below configures work a single step does not do, so
    // accepting one alongside --step would silently drop it.
    const conflict =
      gateEntries.length > 0
        ? {
            flag: "--gate",
            reason:
              "a gate steers a full pass; the 'heal-enrich' step IS the opt-in and the 'scan' step reads no gate, so an override would have nothing to apply to",
          }
        : flags["dry-run"] === true
          ? {
              flag: "--dry-run",
              reason:
                "runDreamStep has no preview path - 'scan' already writes nothing and 'heal-enrich' has no plan-only mode, so a dry run would be either a no-op dressed as a preview or a write",
            }
          : flags["expect"] !== undefined
            ? {
                flag: "--expect",
                reason:
                  "the count guard asserts over the preferences a full pass creates, confirms, retires or moves, and a single step produces none of those counters",
              }
            : flags["strict"] === true
              ? {
                  flag: "--strict",
                  reason:
                    "it demands a count guard over the preferences a full pass changes, and a single step changes none of them",
                }
              : null;
    if (conflict !== null) {
      return refuse(
        `brain dream: --step cannot be combined with ${conflict.flag}: ${conflict.reason}`,
        asJson,
        { step: stepRequest, conflicting_flag: conflict.flag },
      );
    }
  }

  let gates: DreamGateOverrides | null = null;
  if (gateEntries.length > 0) {
    try {
      gates = parseDreamGateOverrides(gateEntries);
    } catch (exc) {
      if (exc instanceof DreamGateOverrideError) {
        return refuse(`brain dream: ${exc.message}`, asJson, {
          entry: exc.entry,
          known_gates: [...exc.known],
        });
      }
      throw exc;
    }
  }

  // With no vault configured (`null`) the inline pass runs over the
  // store's folds alone (design D14). A single step and the staged
  // lifecycle work on vault files (user notes, the staging lane), so they
  // still need a vault and say so.
  const verbContext = brainVerbContext(flags, { vault: "optional" });
  const { config, vault } = verbContext;
  const vaultFor = (what: string): string => requireBrainVaultFor(verbContext, what);

  const agentFlag = flags["agent"];
  let agent: string;
  if (typeof agentFlag === "string") {
    const trimmed = agentFlag.trim();
    if (trimmed.length === 0) {
      return fail("brain dream: --agent must be a non-empty string when provided");
    }
    agent = trimmed;
  } else {
    agent = resolveAgentName(config);
  }

  const { value: now, error: nowErr } = parseOptionalIsoDate(flags, "now");
  if (nowErr) return fail(nowErr);

  // No signal: `dreamRun` is synchronous end to end, so a signal handler
  // cannot run while it does (see `interrupt.ts`). The deadline is the
  // only cooperative stop a dream pass has; SIGINT is left with its
  // default meaning so the keystroke still kills the process, and every
  // artifact a pass writes goes through `atomicWriteFileSync`, so being
  // killed leaves no half-written note.
  const guard = () =>
    createSafeguard({
      operation: OPERATION.dream,
      timeoutMs: resolveSafeguardTimeoutMs(OPERATION.dream, config ?? undefined),
    });

  if (wantsStep) {
    // A step is a whole run on this surface, so it is guarded and
    // watched like one: `scan` walks the Brain tree and `heal-enrich`
    // reads and rewrites every user page, and neither had a deadline or
    // a sink before. The step itself owns the counter - the two units
    // report under their own stage names - so this attaches the rail and
    // forwards, exactly as the maintenance lane does over its tasks.
    const stepObservation =
      flags["progress"] === true
        ? // The rail is told what was actually dispatched, not a label
          // for it: `brain.ts` hands this verb the tail AFTER `dream`, and
          // `["dream", "step"]` named a positional this verb has never had
          // - `--step` is a flag. The two sibling call sites below pass
          // the real action for the same reason.
          attachProgress({ command: "brain", argv: ["dream", ...argv], jsonRequested: asJson })
        : null;
    reportProgressRefusal(stepObservation);
    let result: DreamStepResult;
    try {
      result = runDreamStep(vaultFor("dream --step"), stepRequest, {
        safeguard: guard(),
        ...(stepObservation?.sink !== undefined ? { onProgress: stepObservation.sink } : {}),
      });
    } catch (exc) {
      if (exc instanceof DreamStepNotRunnableError) {
        return refuse(exc.message, asJson, {
          step: exc.requested,
          runnable: [...exc.runnable],
          reason: exc.reason,
        });
      }
      const message = `dream step ${stepRequest} failed: ${(exc as Error).message ?? exc}`;
      if (asJson) {
        // The same marker the staged-action catch and the inline-pass
        // catch emit, for the same reason and on the same contract
        // (`docs/cli-reference.md`, "Long-running operations"): a machine
        // caller has to be able to tell a budget it can raise or retry
        // past from a defect it cannot. This branch is the one the step
        // deadline was added for, so it was the one place a timeout came
        // back indistinguishable from a crash.
        okJson({
          ok: false,
          step: stepRequest,
          ...(exc instanceof SafeguardTimeoutError ? { timed_out: true } : {}),
          message,
        });
        return 1;
      }
      return fail(message);
    }
    if (asJson) {
      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
      return 0;
    }
    printStepResult(result);
    return 0;
  }

  // The staged actions that RUN a pass watch the same five stages the
  // inline run does. `DreamStageOptions` has declared `onProgress` and
  // threaded it through all three of those entry points since U1; this is
  // the caller that asks. A stream that reached only one of the two entry
  // points would be the half-wired mechanism this release exists to
  // remove.
  //
  // `discard` and `list` are excluded because they run no pass and have
  // nothing to report, and `run` because it falls through this block to
  // the inline pass below, which attaches its own. Attaching here for
  // `run` too would build two observers for one pass and report a refusal
  // twice.
  const STAGED_PASSES = new Set(["stage", "validate", "apply"]);
  const stagedObservation =
    flags["progress"] === true && STAGED_PASSES.has(action)
      ? attachProgress({ command: "brain", argv: ["dream", action], jsonRequested: asJson })
      : null;
  reportProgressRefusal(stagedObservation);
  const stagedProgress =
    stagedObservation?.sink !== undefined ? { onProgress: stagedObservation.sink } : {};
  try {
    if (action === "stage") {
      const bundle = stageDream(vaultFor(`dream ${action}`), {
        now: now ?? new Date(),
        safeguard: guard(),
        ...stagedProgress,
        ...(agent ? { agentName: agent } : {}),
      });
      if (asJson) {
        okJson({
          run_id: bundle.runId,
          plan: bundle.plan,
          sources: bundle.sources.length,
          dir: `Brain/dream/staged/${bundle.runId}`,
        });
      } else {
        ok(`staged: ${bundle.runId} -> Brain/dream/staged/${bundle.runId}/`);
        ok(`planned changes: ${bundle.plan.changed ? "yes" : "none"}`);
      }
      return 0;
    }

    if (action === "validate" || action === "apply") {
      const runId = positional[1]!;
      const stageOpts = {
        now: now ?? new Date(),
        safeguard: guard(),
        ...stagedProgress,
        ...(agent ? { agentName: agent } : {}),
      };
      if (action === "validate") {
        const verdict = validateDreamBundle(vaultFor(`dream ${action}`), runId, stageOpts);
        if (asJson) okJson({ run_id: runId, valid: verdict.valid, drift: verdict.drift });
        else if (verdict.valid) ok(`validate ${runId}: clean`);
        else {
          ok(`validate ${runId}: DRIFT`);
          for (const line of verdict.drift) ok(`  ${line}`);
        }
        return verdict.valid ? 0 : 1;
      }
      const outcome = applyDreamBundle(vaultFor(`dream ${action}`), runId, stageOpts);
      if (asJson) {
        okJson({
          run_id: runId,
          applied: outcome.applied,
          drift: outcome.validation.drift,
          ...(outcome.summary !== undefined
            ? {
                changed: outcome.summary.changed,
                new_unconfirmed: outcome.summary.new_unconfirmed,
                confirmed: outcome.summary.confirmed,
              }
            : {}),
        });
      } else if (outcome.applied) {
        ok(`apply ${runId}: done (changed: ${outcome.summary!.changed})`);
      } else {
        ok(`apply ${runId}: ABORTED - bundle drifted, re-stage first`);
        for (const line of outcome.validation.drift) ok(`  ${line}`);
      }
      return outcome.applied ? 0 : 1;
    }

    if (action === "retriage") {
      const runId = positional[1]!;
      const outcome = retriageDreamBundle(vaultFor(`dream ${action}`), runId, {
        now: now ?? new Date(),
        safeguard: guard(),
        ...(agent ? { agentName: agent } : {}),
      });
      if (asJson) {
        okJson({
          run_id: outcome.runId,
          staged_threshold: outcome.stagedThreshold,
          current_threshold: outcome.currentThreshold,
          changed: outcome.changed,
          considered: outcome.considered,
          admitted: outcome.admitted,
          newly_admitted: outcome.newlyAdmitted.map(retriageRow),
          newly_excluded: outcome.newlyExcluded.map(retriageRow),
          notes: [...outcome.notes],
        });
        return 0;
      }
      ok(
        `retriage ${runId}: threshold staged=${describeThreshold(outcome.stagedThreshold)} ` +
          `current=${describeThreshold(outcome.currentThreshold)}`,
      );
      ok(`fold set: ${outcome.admitted} of ${outcome.considered} admitted now`);
      printRetriageDelta("newly admitted", outcome.newlyAdmitted);
      printRetriageDelta("newly excluded", outcome.newlyExcluded);
      for (const note of outcome.notes) ok(`note: ${note}`);
      if (outcome.changed) ok("re-stage the bundle to adopt this partition");
      return 0;
    }

    if (action === "discard") {
      const runId = positional[1]!;
      const removed = discardDreamBundle(vaultFor(`dream ${action}`), runId);
      if (asJson) okJson({ run_id: runId, removed });
      else ok(removed ? `discarded ${runId}` : `no staged bundle named ${runId}`);
      return 0;
    }

    if (action === "list") {
      const bundles = listDreamBundles(vaultFor(`dream ${action}`));
      if (asJson) {
        okJson({
          bundles: bundles.map((b) => ({
            run_id: b.runId,
            status: b.status,
            staged_at: b.stagedAt,
            proposals: b.proposals,
            sources: b.sources,
          })),
          ...(bundles.length === 0 ? nextCommandField("dream-bundles-absent") : {}),
        });
      } else if (bundles.length === 0) {
        ok("no dream bundles");
        // no-dead-ends, phase 3: this pointer was hand-written beside
        // the rail. One mechanism, one line format.
        emitNextStep("dream-bundles-absent", { command: "brain", argv, jsonRequested: asJson });
      } else {
        for (const b of bundles) {
          ok(`${b.runId}  ${b.status}  staged ${b.stagedAt}  ${b.proposals} proposal(s)`);
        }
      }
      return 0;
    }
  } catch (exc) {
    // A bundle this verb understood and declined is a refusal, not an
    // operational failure: exit 2, with the bare reason beside the
    // sentence so a machine caller can branch on it.
    if (exc instanceof DreamRetriageError) {
      return refuse(exc.message, asJson, { action, run_id: exc.runId, reason: exc.reason });
    }
    const timedOut = exc instanceof SafeguardTimeoutError;
    if (asJson) {
      okJson({
        ok: false,
        message: `dream ${action} failed: ${(exc as Error).message ?? exc}`,
        ...(timedOut ? { timed_out: true } : {}),
      });
      return 1;
    }
    return fail(`dream ${action} failed: ${(exc as Error).message ?? exc}`);
  }

  // action === "run": the legacy inline pass.
  const expectRaw = flags["expect"] as string | undefined;
  let expect: number | null = null;
  if (expectRaw !== undefined) {
    const n = Number(expectRaw);
    if (!Number.isInteger(n) || n < 0) return fail("--expect must be a non-negative integer");
    expect = n;
  }
  const strict = flags["strict"] === true;
  // Only pay for a preview pass when a guard is requested.
  if (expect !== null || strict) {
    try {
      const preview = dream(vault, {
        ...(now !== null ? { now } : {}),
        dryRun: true,
        ...(agent ? { agentName: agent } : {}),
        // The guard must preview the run it is guarding, overrides and
        // all, or it asserts a count for a pass that will not happen.
        ...(gates !== null ? { gates } : {}),
      });
      const matchList = [
        ...preview.new_unconfirmed,
        ...preview.confirmed,
        ...preview.retired.map((r) => r.id),
        ...preview.moved_to_processed,
      ];
      assertExpectedCount({
        matched: matchList.length,
        expect,
        strict,
        willMutate: !flags["dry-run"],
        matchList,
      });
    } catch (exc) {
      if (exc instanceof CountGuardError) return fail(exc.message);
      return fail(`dream preview failed: ${(exc as Error).message ?? exc}`);
    }
  }

  // Progress is opt-in: attaching a sink by default would change the
  // stderr of every existing invocation, and this CLI's one streaming
  // precedent (`o2b search index --verbose`) is opt-in for the same
  // reason. The rail decides whether the stream can carry it at all.
  const observation =
    flags["progress"] === true
      ? attachProgress({ command: "brain", argv: ["dream"], jsonRequested: asJson })
      : null;
  reportProgressRefusal(observation);
  // The model verdicts are decided before the pass (design D10, D20):
  // only a live pass decides; a dry run gets the deterministic result.
  const dryRun = Boolean(flags["dry-run"]);
  // The same config and run date the pass below plans with.
  const decideOptions: PrepareTopicVerdictsOptions = {
    ...(config !== undefined ? { configPath: config } : {}),
    ...(now !== null ? { runAt: now } : {}),
  };
  const topicVerdicts = dryRun ? undefined : await prepareTopicVerdicts(decideOptions);
  let summary;
  try {
    summary = dream(vault, {
      ...(now !== null ? { now } : {}),
      dryRun,
      ...(topicVerdicts !== undefined ? { topicVerdicts } : {}),
      ...(agent ? { agentName: agent } : {}),
      safeguard: guard(),
      ...(observation?.sink !== undefined ? { onProgress: observation.sink } : {}),
      ...(gates !== null ? { gates } : {}),
      ...(config !== undefined ? { configPath: config } : {}),
    });
  } catch (exc) {
    if (exc instanceof SafeguardTimeoutError && asJson) {
      okJson({ ok: false, timed_out: true, message: exc.message });
      return 1;
    }
    return fail(`dream failed: ${describeErrorChain(exc)}`);
  }
  for (const w of summary.warnings ?? []) {
    process.stderr.write(`warning: ${w.code}: ${w.message}\n`);
  }

  if (asJson) {
    process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
    return 0;
  }
  ok(`run_id: ${summary.run_id}`);
  ok(`changed: ${summary.changed}`);
  // Only when a threshold is configured: with the gate open every fact is
  // admitted, and a line saying so on every run would be noise. With it
  // closed the exclusions are otherwise invisible on this stream - the
  // ladder just folds fewer facts and says nothing about why.
  const gate = summary.salience_gate;
  if (gate.threshold !== null) {
    ok(
      `salience_gate: ${gate.admitted} of ${gate.considered} fact(s) admitted ` +
        `(threshold ${gate.threshold})`,
    );
  }
  if (summary.new_unconfirmed.length > 0)
    ok(`new_unconfirmed: ${summary.new_unconfirmed.join(", ")}`);
  if (summary.confirmed.length > 0) ok(`confirmed: ${summary.confirmed.join(", ")}`);
  if (summary.retired.length > 0)
    ok(`retired: ${summary.retired.map((r) => `${r.id} (${r.reason})`).join(", ")}`);
  if (summary.contradictions.length > 0) ok(`contradictions: ${summary.contradictions.join(", ")}`);
  if (summary.moved_to_processed.length > 0)
    ok(`moved_to_processed: ${summary.moved_to_processed.length}`);
  const archived = summary.archived_signals?.length ?? 0;
  if (archived > 0) ok(`archived_signals: ${archived}`);
  if (summary.view !== undefined) ok(`view: ${summary.view.summary}`);
  return 0;
}