Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.0 KB
Raw Blame
/**
 * Agent-instruction writeback override (gbrain.io memory settings, GBRA-219).
 *
 * `memory.agent_writeback = inherit | off | salient | all` changes ONLY what
 * agents are told to save: the ambient-writeback section and the short
 * writeback line in the MCP initialize instructions, and what
 * `get_memory_settings` renders. It is DB-only (no file mirror), so it works
 * the same on a repo-less brain, and it never feeds the host capture lanes:
 * the Stop hook, the compaction harvest and SessionEnd transcripts keep
 * reading the operator's `memory.auto_writeback` through
 * captureGateDecision (writeback-config.ts). That separation is the point: a
 * remote `off` must never retire the operator's banked session text.
 *
 * Kept out of writeback-config.ts on purpose: the engine-free hook children
 * import that module, and this one reads the audience classifier and the
 * request log.
 *
 * Fail direction: an unreadable or unrecognized override resolves to `off`
 * (never back to inherit, which would widen an `off` override on a brain
 * whose operator mode is on), with status `degraded`. A read failure serves
 * the engine's last-known-good override first, matching the operator
 * resolver's mid-session posture.
 */

import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { executeRawJsonb } from '../sql-query.ts';
import { resolveWritebackConfig, type WritebackConfig, type WritebackMode } from './writeback-config.ts';

export const AGENT_WRITEBACK_KEY = 'memory.agent_writeback';
export const AGENT_WRITEBACK_VALUES = Object.freeze(['inherit', 'off', 'salient', 'all'] as const);
export type AgentWritebackValue = (typeof AGENT_WRITEBACK_VALUES)[number];

/** The request-log operation name of a settings change (a NON_OP_LOG_ROWS member). */
export const MEMORY_SETTING_AUDIT_OP = 'memory_setting_change';

export interface AgentWritebackResolution {
  /** The operator bundle with mode/enabled replaced by the effective instruction mode. */
  bundle: WritebackConfig;
  /** The operator's own `memory.auto_writeback` resolution (also what the capture lanes follow). */
  operator: WritebackConfig;
  /** The stored override, normalized; null when unset. */
  override: AgentWritebackValue | null;
  /** Where the effective instruction mode came from. */
  source: 'agent_override' | 'operator' | 'fail_closed';
  status: 'ok' | 'degraded';
  /** Machine-readable reasons for a degraded status. */
  reasons: string[];
}

export function parseAgentWriteback(raw: unknown): AgentWritebackValue | null | undefined {
  if (raw == null) return null;
  const s = String(raw).trim().toLowerCase();
  if (!s) return null;
  return (AGENT_WRITEBACK_VALUES as readonly string[]).includes(s) ? s as AgentWritebackValue : undefined;
}

const overrideLkg = new WeakMap<BrainEngine, AgentWritebackValue | null>();

/** Never throws. `fileCfg` is passed through to the operator resolver as drift/LKG input only. */
export async function resolveAgentWriteback(engine: BrainEngine, fileCfg?: GBrainConfig | null): Promise<AgentWritebackResolution> {
  const operator = await resolveWritebackConfig(engine, fileCfg);
  const reasons: string[] = [];
  if (operator.read_error) reasons.push('operator_mode_unreadable');
  if (!operator.mode_valid) reasons.push('operator_mode_invalid');
  if (operator.plane_drift) reasons.push('operator_plane_drift');
  let override: AgentWritebackValue | null | undefined;
  try {
    override = parseAgentWriteback(await engine.getConfig(AGENT_WRITEBACK_KEY));
    if (override !== undefined) overrideLkg.set(engine, override);
  } catch {
    override = overrideLkg.has(engine) ? overrideLkg.get(engine)! : undefined;
    reasons.push(overrideLkg.has(engine) ? 'agent_override_last_known_good' : 'agent_override_unreadable');
  }
  let mode: WritebackMode;
  let source: AgentWritebackResolution['source'];
  if (operator.read_error) {
    // The operator read failed with no last-known-good, so the visibility and
    // TTL posture are defaults, not this brain's: never emit an enabled rule on them.
    mode = 'off';
    source = 'fail_closed';
  } else if (override === undefined) {
    if (!reasons.includes('agent_override_unreadable')) reasons.push('agent_override_invalid');
    mode = 'off';
    source = 'fail_closed';
  } else if (override === null || override === 'inherit') {
    mode = operator.mode;
    source = 'operator';
  } else {
    mode = override;
    source = 'agent_override';
  }
  return {
    bundle: { ...operator, mode, enabled: mode !== 'off' },
    operator,
    override: override ?? null,
    source,
    status: reasons.length ? 'degraded' : 'ok',
    reasons,
  };
}

export interface AgentWritebackChange {
  actor: string;
  client_id: string | null;
  transport: 'cli' | 'stdio' | 'http';
}

/**
 * Write the override and its audit row in ONE transaction: either both land
 * or neither does. Returns the previous stored value. A throw means the
 * outcome is unknown to the caller (a lost acknowledgement looks the same as
 * a rollback), so callers re-read before any retry.
 */
export async function writeAgentWriteback(
  engine: BrainEngine,
  value: AgentWritebackValue,
  change: AgentWritebackChange,
): Promise<{ previous: AgentWritebackValue | null }> {
  const result = await engine.transaction(async (tx) => {
    // Serialize concurrent changes so each audit row's `old` is the value it replaced.
    await tx.executeRaw('SELECT pg_advisory_xact_lock(hashtext($1))', [AGENT_WRITEBACK_KEY]);
    const previous = parseAgentWriteback(await tx.getConfig(AGENT_WRITEBACK_KEY)) ?? null;
    await tx.setConfig(AGENT_WRITEBACK_KEY, value);
    await executeRawJsonb(
      tx,
      `INSERT INTO mcp_request_log (token_name, agent_name, operation, latency_ms, status, params)
       VALUES ($1, $2, $3, $4, $5, $6::jsonb)`,
      [change.actor, change.actor, MEMORY_SETTING_AUDIT_OP, 0, 'success'],
      [{ key: AGENT_WRITEBACK_KEY, actor: change.actor, client_id: change.client_id, transport: change.transport, old: previous, new: value }],
    );
    return { previous };
  });
  overrideLkg.set(engine, value);
  return result;
}