Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.7 KB
Raw Blame
/**
 * Notice dedupe, coaching budget and mute (agent operator contract v1, A6).
 *
 * - stdio / CLI: one process-wide ledger (dedupe per process).
 * - HTTP is stateless: the ledger lives in ServeHttpContext and is keyed by
 *   authenticated principal + transport-resolved session id (never a
 *   `_meta.session_id` taken from tool arguments); with no session id, by
 *   principal. Bounded: 10k keys, 24 h TTL.
 * - `degraded` and `safety` notices are never deduped on HTTP (attached to
 *   every affected call). At most 2 `coaching` notices per session.
 * - A notice's unrendered `dedupe_key` replaces its code as the dedupe
 *   identity, and turns a per-call code into a once-per-session one:
 *   `degraded_recall` rides every affected call, except a notice made only of
 *   configuration-persistent stages (a keyless brain's `embed_unavailable`),
 *   which shows once per session per distinct key.
 * - Mute applies to `coaching` and `info` only: globally for the local owner
 *   (`gbrain notices mute <code>`), per client on remote transports
 *   (`mute_notice`). Persisted under GBRAIN_HOME.
 * - A notice carrying `escalation` (#7165 coverage notices: held_files and a
 *   projection-only degraded_recall) shows once per session per key for
 *   COVERAGE_NOTICE_WINDOW_MS, per-call code or not, and again at once when its
 *   level rises materially (`coverageWorsened`). HTTP applies it only with a
 *   transport-resolved session id. One-shot CLI calls share the window through
 *   `admitAcrossCliCalls` (GBRAIN_HOME/notices/coverage.json).
 */
import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
import { dirname } from 'node:path';
import { gbrainPath } from './config.ts';
import type { Notice, Transport } from './agent-output.ts';

const MAX_KEYS = 10_000;
const TTL_MS = 24 * 60 * 60 * 1000;
export const COACHING_BUDGET_PER_SESSION = 2;
/** The one muteable `ask`: an unanswered first-run bundle must stay dismissible. Every other ask always shows. */
export const MUTEABLE_ASK_CODES: ReadonlySet<string> = new Set(['first_run_decisions']);
/** Notices that describe THIS call's result (never deduped unless the notice carries a `dedupe_key`): the diagnosis must ride every affected call. */
export const PER_CALL_NOTICE_CODES: ReadonlySet<string> = new Set(['degraded_recall', 'hidden_tool_content', 'empty_retrieval', 'unknown_param', 'listing_truncated', 'former_relationships_hidden', 'source_binding_narrowed', 'local_transcripts', 'held_files', 'relational_chain', 'graph_walk_truncated', 'mention_index', 'delta_incomplete', 'identity_siblings_capped', 'references_unavailable', 'record_types_undeclared', 'alias_fanout', 'facts_unembedded', 'loops_no_google_in_scope', 'privacy_label_ignored', 'loops_source_read_failed', 'room_above_level', 'room_hints_unavailable', 'room_conflict']);

/** How long a shown coverage state (a notice's `escalation`) stays shown. */
export const COVERAGE_NOTICE_WINDOW_MS = 30 * 60 * 1000;

/** Material worsening over `floor`, the lowest level seen since the notice last showed: up by 10% and at least 1. */
export function coverageWorsened(floor: number, level: number): boolean {
  return level >= floor + Math.max(1, Math.ceil(floor * 0.1));
}

interface EscalationMark { floor: number; at: number }

/** Show or suppress one escalating notice given its last mark; the returned mark replaces it. */
function escalate(prev: EscalationMark | undefined, level: number, now: number): { show: boolean; mark: EscalationMark } {
  if (prev && now - prev.at < COVERAGE_NOTICE_WINDOW_MS && !coverageWorsened(prev.floor, level)) {
    return { show: false, mark: { floor: Math.min(prev.floor, level), at: prev.at } };
  }
  return { show: true, mark: { floor: level, at: now } };
}

/** Notices whose producer already deduped them with `claim` on its own key; admit applies mute only. */
export const SELF_DEDUPED_NOTICE_CODES: ReadonlySet<string> = new Set(['grant_blocked_operations']);

export interface NoticeAudience {
  transport: Transport;
  /** Authenticated principal (HTTP client id); undefined for the local owner. */
  principal?: string;
  /** Transport-resolved session id. */
  sessionId?: string;
}

export class NoticeLedger {
  private seen = new Map<string, number>();
  private coaching = new Map<string, { count: number; at: number }>();
  private tallies = new Map<string, { n: number; at: number }>();
  private claimed = new Map<string, number>();
  private memo = new Map<string, { value: unknown; at: number }>();
  private escalations = new Map<string, EscalationMark>();

  constructor(private readonly now: () => number = Date.now) {}

  private session(a: NoticeAudience): string {
    return `${a.principal ?? 'local'}|${a.sessionId ?? ''}`;
  }

  private prune<V>(map: Map<string, V>, at: (v: V) => number): void {
    const cutoff = this.now() - TTL_MS;
    for (const [k, v] of map) {
      if (at(v) >= cutoff && map.size <= MAX_KEYS) break;
      map.delete(k);
    }
  }

  /** Count one more `key` event in this audience's session (e.g. a reranker-degraded call) and return the session total. */
  tally(audience: NoticeAudience, key: string): number {
    const k = `${this.session(audience)}|${key}`;
    const n = (this.tallies.get(k)?.n ?? 0) + 1;
    this.tallies.delete(k);
    this.tallies.set(k, { n, at: this.now() });
    this.prune(this.tallies, v => v.at);
    return n;
  }

  /** First call for `key` returns true and records it; later calls (within the TTL) return false. */
  claim(key: string): boolean {
    if (this.claimed.has(key)) return false;
    this.claimed.set(key, this.now());
    this.prune(this.claimed, at => at);
    return true;
  }

  /** `compute` once per `key` (within the TTL); later calls get the stored value. */
  async memoize<T>(key: string, compute: () => Promise<T>): Promise<T> {
    const hit = this.memo.get(key);
    if (hit) return hit.value as T;
    const value = await compute();
    this.memo.set(key, { value, at: this.now() });
    this.prune(this.memo, v => v.at);
    return value;
  }

  /** Filter one call's notices: mute, dedupe and the coaching budget. Never throws. */
  admit(notices: readonly Notice[], audience: NoticeAudience, muted: ReadonlySet<string> = new Set()): Notice[] {
    const out: Notice[] = [];
    const session = this.session(audience);
    for (const n of notices) {
      if ((n.kind === 'coaching' || n.kind === 'info' || MUTEABLE_ASK_CODES.has(n.code)) && muted.has(n.code)) continue;
      if (n.escalation && (audience.transport !== 'http' || audience.sessionId)) {
        const key = `${session}|${n.code}|${n.escalation.key}`;
        const { show, mark } = escalate(this.escalations.get(key), n.escalation.level, this.now());
        this.escalations.delete(key);
        this.escalations.set(key, mark);
        if (!show) continue;
      }
      const always = (PER_CALL_NOTICE_CODES.has(n.code) && n.dedupe_key === undefined) || SELF_DEDUPED_NOTICE_CODES.has(n.code)
        || (audience.transport === 'http' && (n.kind === 'degraded' || n.kind === 'safety'));
      const key = n.dedupe_key === undefined ? `${session}|${n.code}` : `${session}|${n.code}|${n.dedupe_key}`;
      if (!always && this.seen.has(key)) continue;
      if (n.kind === 'coaching') {
        const used = this.coaching.get(session)?.count ?? 0;
        if (used >= COACHING_BUDGET_PER_SESSION) continue;
        this.coaching.delete(session);
        this.coaching.set(session, { count: used + 1, at: this.now() });
      }
      if (!always) {
        this.seen.delete(key);
        this.seen.set(key, this.now());
      }
      out.push(n);
    }
    this.prune(this.seen, at => at);
    this.prune(this.coaching, v => v.at);
    this.prune(this.escalations, v => v.at);
    return out;
  }
}

let processLedger: NoticeLedger | null = null;
/** The stdio / CLI ledger: one per process. */
export function processNoticeLedger(): NoticeLedger {
  processLedger ??= new NoticeLedger();
  return processLedger;
}
export function __resetProcessNoticeLedgerForTests(): void { processLedger = null; }

// ── coverage window for one-shot CLI calls ─────────────────────────────────

const CLI_COVERAGE_MARKS_MAX = 200;

export function coverageNoticePath(): string {
  return gbrainPath('notices', 'coverage.json');
}

/**
 * #7165: whether an escalating notice shows in this CLI call, given what earlier
 * calls under this GBRAIN_HOME showed within COVERAGE_NOTICE_WINDOW_MS. `key`
 * names the brain, the code and the escalation key. A store that cannot be
 * written shows it. Never throws.
 */
export function admitAcrossCliCalls(key: string, level: number, now: number = Date.now()): boolean {
  let marks: Record<string, EscalationMark> = {};
  try {
    const raw = JSON.parse(readFileSync(coverageNoticePath(), 'utf8')) as { marks?: Record<string, EscalationMark> };
    if (raw.marks && typeof raw.marks === 'object') marks = raw.marks;
  } catch { /* no marks yet */ }
  const { show, mark } = escalate(marks[key], level, now);
  const kept = Object.entries({ ...marks, [key]: mark })
    .filter(([, m]) => typeof m?.at === 'number' && typeof m.floor === 'number' && now - m.at < COVERAGE_NOTICE_WINDOW_MS)
    .sort((a, b) => b[1].at - a[1].at).slice(0, CLI_COVERAGE_MARKS_MAX);
  try {
    const path = coverageNoticePath();
    mkdirSync(dirname(path), { recursive: true });
    const tmp = `${path}.tmp-${process.pid}`;
    writeFileSync(tmp, `${JSON.stringify({ marks: Object.fromEntries(kept) })}\n`, { mode: 0o600 });
    renameSync(tmp, path);
  } catch {
    return true;
  }
  return show;
}

// ── mute store ──────────────────────────────────────────────────────────────

interface MuteFile { global: string[]; clients: Record<string, string[]> }

export function noticeMutePath(): string {
  return gbrainPath('notices', 'muted.json');
}

function readMuteFile(): MuteFile {
  try {
    const raw = JSON.parse(readFileSync(noticeMutePath(), 'utf8')) as Partial<MuteFile>;
    return { global: Array.isArray(raw.global) ? raw.global : [], clients: raw.clients && typeof raw.clients === 'object' ? raw.clients : {} };
  } catch {
    return { global: [], clients: {} };
  }
}

/** Muted codes for an audience: the owner's global list plus the client's own list on remote transports. */
export function mutedNoticeCodes(principal?: string): Set<string> {
  const f = readMuteFile();
  return new Set([...f.global, ...(principal ? f.clients[principal] ?? [] : [])]);
}

/** Persist a (un)mute. `principal` scopes it to one remote client; omitted = the local owner (global). */
export function setNoticeMuted(code: string, muted: boolean, principal?: string): string[] {
  const f = readMuteFile();
  const list = new Set(principal ? f.clients[principal] ?? [] : f.global);
  if (muted) list.add(code); else list.delete(code);
  const sorted = [...list].sort();
  if (principal) f.clients[principal] = sorted; else f.global = sorted;
  writeMuteFile(f);
  return sorted;
}

/**
 * The owner's unmute: clears the code from the global list and from the
 * stdio MCP pipe's list (`mute_notice` over stdio stores under `stdio`).
 * Returns the owner's remaining muted codes across both.
 */
export function unmuteNoticeForOwner(code: string): string[] {
  const f = readMuteFile();
  f.global = f.global.filter(c => c !== code);
  if (f.clients.stdio) f.clients.stdio = f.clients.stdio.filter(c => c !== code);
  writeMuteFile(f);
  return [...new Set([...f.global, ...(f.clients.stdio ?? [])])].sort();
}

function writeMuteFile(f: MuteFile): void {
  const path = noticeMutePath();
  mkdirSync(dirname(path), { recursive: true });
  const tmp = `${path}.tmp-${process.pid}`;
  writeFileSync(tmp, `${JSON.stringify(f, null, 2)}\n`, { mode: 0o600 });
  renameSync(tmp, path);
}