Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.8 KB
Raw Blame
/**
 * Brain-audience classification for the ambient-writeback consent nudge
 * (WP8): personal brains get a one-time relayed ASK to enable
 * `memory.auto_writeback`; company/team/shared brains get silence.
 *
 * DECLARATION BEATS HEURISTICS. The declared axis is the `brain.audience`
 * config key ('personal' | 'shared'), set by the operator, by
 * company-brainify's Phase-5 handoff (shared), or from the bootstrap
 * interview's SURFACE_MULTIUSER answer. The heuristic exists only for
 * undeclared brains and is deliberately conservative: client count measures
 * surface breadth, not human count (Claude Code + Codex + a phone client is
 * three clients and one human), so only ≥3 DISTINCT non-automation MCP
 * clients active in the last 30 days reads as shared evidence — and
 * `reasons[]` always names what decided, so doctor can surface a
 * misclassification and the one-line fix (`gbrain config set brain.audience
 * personal|shared`).
 *
 * Fail direction: a config read failure → 'unknown' (nudge surfaces stay
 * SILENT — fail-quiet); a usage-heuristic failure with a reachable DB →
 * 'personal' (a plain personal PGLite brain has none of the multi-client
 * infra; missing tables are not evidence of sharing).
 *
 * Suppression (mounts, thin clients, ctx.remote) is the CALLER's job — those
 * are "don't ask here" conditions, not audience classifications.
 *
 * This module never enables anything: classification feeds ask-vs-silence
 * decisions only.
 */

import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { readClientOpUsage } from '../mcp-usage.ts';
import { resolveBrainId } from '../brain-resolver.ts';
import { HOST_BRAIN_ID } from '../brain-registry.ts';

export const BRAIN_AUDIENCE_KEY = 'brain.audience';
/** Distinct non-automation clients active in 30d that count as shared evidence. */
export const SHARED_CLIENT_THRESHOLD = 3;

export type BrainAudience = 'personal' | 'shared' | 'unknown';
export interface BrainAudienceResult {
  audience: BrainAudience;
  /** Human-readable evidence, surfaced verbatim by doctor + the config caution. */
  reasons: string[];
  /** Set when 'personal' is a fallback because the client-usage read failed, not evidence: callers that widen access read it as not personal. */
  unproven?: true;
}

export async function classifyBrainAudience(
  engine: BrainEngine,
  fileCfg?: GBrainConfig | null,
): Promise<BrainAudienceResult> {
  let declared: string | null;
  try {
    // DB plane authoritative; the file mirror (dual-written by `config set
    // brain.audience`) fills a gap — e.g. a fresh DB that lost its config
    // rows while the machine-local declaration survived. The mirror is
    // MACHINE-GLOBAL while DB rows are per-brain, so it only speaks for the
    // HOST brain: a mounted/selected team brain must never inherit the host
    // operator's declaration (adversarial review, this wave) — its own DB
    // row or its own heuristic decides.
    let fileDeclared: string | null = null;
    try {
      if (resolveBrainId(undefined) === HOST_BRAIN_ID) {
        fileDeclared = fileCfg?.brain?.audience ?? null;
      }
    } catch { /* mount resolution failed — the mirror is not this brain's voice */ }
    declared = (await engine.getConfig(BRAIN_AUDIENCE_KEY)) ?? fileDeclared;
  } catch {
    return { audience: 'unknown', reasons: ['brain.audience unreadable (config read failed)'] };
  }
  const d = declared == null ? '' : declared.trim().toLowerCase();
  if (d === 'shared') return { audience: 'shared', reasons: ['declared: brain.audience=shared'] };
  if (d === 'personal') return { audience: 'personal', reasons: ['declared: brain.audience=personal'] };
  const reasons: string[] = [];
  if (d) reasons.push(`brain.audience='${d}' unrecognized (expected personal|shared) — falling back to the heuristic`);

  try {
    const usage = await readClientOpUsage(engine, { days: 30 });
    const humans = usage.filter((u) => !u.likely_automation);
    if (humans.length >= SHARED_CLIENT_THRESHOLD) {
      return {
        audience: 'shared',
        reasons: [
          ...reasons,
          `heuristic: ${humans.length} distinct non-automation MCP clients active in 30d (threshold ${SHARED_CLIENT_THRESHOLD}) — declare the truth with: gbrain config set brain.audience personal|shared`,
        ],
      };
    }
    return {
      audience: 'personal',
      reasons: [...reasons, `no shared declaration; ${humans.length} non-automation client(s) active in 30d`],
    };
  } catch {
    // The declaration read above already proved the DB reachable — a failed
    // usage read here means the multi-client infra isn't there (fresh or
    // pre-OAuth brain), which is itself personal-shaped evidence.
    return { audience: 'personal', unproven: true, reasons: [...reasons, 'no shared declaration; client-usage heuristic unavailable'] };
  }
}