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
6.8 KB
Raw Blame
/**
 * The advisory emission rail (no-dead-ends, task 2).
 *
 * Every forward-pointer line the CLI prints - "here is the command that
 * moves this forward" - passes through this module, and through nothing
 * else. It exists because that line is two decisions, and both were
 * previously taken per verb, differently:
 *
 *   1. WHAT to say. The rail takes a diagnostic CODE and resolves it
 *      through `resolveNextStep`, so the command is the registry's
 *      structural CLI string. There is deliberately no parameter through
 *      which a caller can supply a command or a sentence: prose cannot
 *      enter this surface, and an unregistered code produces an explicit
 *      absent result rather than an invented hint.
 *   2. WHETHER it is legal to say it here. Twelve top-level commands
 *      render their own JSON, and their stdout is a payload a caller
 *      parses; one stray advisory line breaks it. Everything else is
 *      wrapped by `withJsonFallback`, whose envelope buffers stdout, so a
 *      line there is harmless. The rail asks `ownsInternalJson` rather
 *      than leaving each verb to remember which family it is in.
 *
 * The caller supplies `jsonRequested` from its own PARSED flags, never
 * from a raw-argv scan: a positional whose text happens to contain the
 * flag would otherwise silence a legitimate human-path advisory.
 *
 * Suppression is not a drop. A suppressed emission still returns the
 * resolved `NextStep`, so a JSON verb carries it as a field in its own
 * payload - which is where it belongs on that stream.
 */

import { resolveNextStep, type NextStep } from "../core/brain/next-step.ts";

import { ownsInternalJson } from "./json-helpers.ts";
import { info } from "./output.ts";

/** Structural label prefixed to every advisory line. */
const NEXT_STEP_LABEL = "next:";

/** The output stream an emission is being considered for. */
export interface AdvisoryStream {
  /** Top-level `o2b` command, e.g. `brain`. */
  readonly command: string;
  /** Argv tail after the top-level command, as `main` dispatched it. */
  readonly argv: ReadonlyArray<string>;
  /**
   * Whether the caller asked for JSON, read from the verb's PARSED flags.
   * Never a raw-argv scan - see the module docblock.
   */
  readonly jsonRequested: boolean;
}

/** Why an emission did or did not reach stdout. Every case is named. */
export const ADVISORY_OUTCOME = Object.freeze({
  /** The line was written to stdout. */
  emitted: "emitted",
  /** Stdout is a machine-parsed payload; the line stayed off it. */
  suppressedMachineStream: "suppressed-machine-stream",
  /** No signal is registered for the code, so there is no command to name. */
  unregisteredCode: "unregistered-code",
} as const);

export type AdvisoryOutcome = (typeof ADVISORY_OUTCOME)[keyof typeof ADVISORY_OUTCOME];

/** What one rail call did, in full. */
export interface AdvisoryEmission {
  /**
   * The code this call was made for, echoed back. Load-bearing for the
   * unregistered outcome: without it a caller learns that one of its
   * codes has no exit but not WHICH, and the batch form's contract of
   * reporting such codes "by name" would be unmeetable.
   */
  readonly code: string;
  readonly outcome: AdvisoryOutcome;
  /** The resolved step, or `null` iff the code is unregistered. */
  readonly nextStep: NextStep | null;
  /** The exact line written, or `null` when nothing was written. */
  readonly line: string | null;
}

/**
 * True when an advisory line may be written to stdout for `stream`. False
 * only when the caller asked for JSON from a command that renders its own:
 * the envelope-wrapped family buffers stdout, so a line there is safe.
 */
export function advisoryIsLegal(stream: AdvisoryStream): boolean {
  if (!stream.jsonRequested) return true;
  return !ownsInternalJson(stream.command, stream.argv);
}

/** Render `step` as the one-line form the human surfaces print. */
export function renderNextStepLine(step: NextStep): string {
  return `${NEXT_STEP_LABEL} ${step.nextCommand}`;
}

/**
 * Resolve `code` and, if the stream allows it, print its next-step line.
 *
 * Never throws: an unregistered code is a caller that has not registered
 * its diagnostic yet, not a crash, and the doctor surfaces must be able to
 * report such an issue without inventing a command for it. The outcome
 * distinguishes that case from a suppressed one, so neither is silent.
 *
 * `nextCommand`, when given, replaces the registered command for a code
 * that IS registered - the registered one with the caller's own
 * arguments appended, such as a scope the run was limited to, so the
 * advice repeats the run instead of widening it. An unregistered code
 * stays unregistered: the override never invents an exit.
 */
export function emitNextStep(
  code: string,
  stream: AdvisoryStream,
  nextCommand?: string,
): AdvisoryEmission {
  const resolved = resolveNextStep(code);
  const nextStep =
    resolved !== null && nextCommand !== undefined
      ? Object.freeze({ ...resolved, nextCommand })
      : resolved;
  if (nextStep === null) {
    return Object.freeze({
      code,
      outcome: ADVISORY_OUTCOME.unregisteredCode,
      nextStep: null,
      line: null,
    });
  }
  if (!advisoryIsLegal(stream)) {
    return Object.freeze({
      code,
      outcome: ADVISORY_OUTCOME.suppressedMachineStream,
      nextStep,
      line: null,
    });
  }
  const line = renderNextStepLine(nextStep);
  info(line);
  return Object.freeze({ code, outcome: ADVISORY_OUTCOME.emitted, nextStep, line });
}

/**
 * Batch form: emit the DISTINCT next steps for `codes`, in the order
 * their commands first appear.
 *
 * A diagnosis surface reports issues, not exits, and the two are not one
 * to one: two hundred broken wikilinks share a single repair command,
 * and two different codes can share one too. Emitting per issue would
 * bury the answer in repetition, so the de-duplication rule lives here
 * rather than in each verb that reports a batch - the rail already owns
 * what reaches stdout, and one rule cannot drift from itself.
 *
 * De-duplication is keyed on the resolved COMMAND, not on the code,
 * because the caller acts on commands. Unregistered codes are returned
 * once each so the caller can still see, by name, which of its issues
 * has no registered exit; they never print.
 */
export function emitNextSteps(
  codes: Iterable<string>,
  stream: AdvisoryStream,
): ReadonlyArray<AdvisoryEmission> {
  const seenCommands = new Set<string>();
  const seenUnregistered = new Set<string>();
  const emissions: AdvisoryEmission[] = [];
  for (const code of codes) {
    const resolved = resolveNextStep(code);
    if (resolved === null) {
      if (seenUnregistered.has(code)) continue;
      seenUnregistered.add(code);
    } else {
      if (seenCommands.has(resolved.nextCommand)) continue;
      seenCommands.add(resolved.nextCommand);
    }
    emissions.push(emitNextStep(code, stream));
  }
  return Object.freeze(emissions);
}