Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.4 KB
Raw Blame
/**
 * Slot policy: requested versus effective mode, threshold resolution, margin,
 * floors and the policy fingerprint, computed from local state only.
 *
 * Owner decision (2026-09-30): the user-facing states are `off` and `on`;
 * `shadow` is advanced diagnostics. Anything that used to "demote to shadow"
 * now runs the call with off behavior, writes a receipt with the reason, and
 * surfaces as `on (inactive: <reason>)` plus the one command that fixes it.
 *
 * Threshold precedence: decide.slots.<slot>.threshold (operator override,
 * never drift-demoted, never bypasses the action-precision gate) > the adopted
 * calibration (decide.slots.<slot>.calibration) > the newest local row for
 * (slot, call site, provider, model) > a shipped reference row. With an alias
 * configured, the model is the one most recently resolved in receipts.
 */
import { createHash } from 'node:crypto';
import { DEFAULT_TYPESAFE_PROVIDER, providerKind, isTypesafeAlias, type DecideConfig } from './config.ts';
import { llmCapability, llmChatModel } from './providers/llm-structured.ts';
import { PROTECTION_VERSION } from './protection.ts';
import { REFERENCE_CALIBRATIONS, type ReferenceCalibration } from './reference-calibrations.ts';
import { SLOT_SPECS } from './slots.ts';
import type { CalibrationRow } from './store.ts';
import type { DecideMode, DecideSlot } from './types.ts';

export interface PolicyCalibration {
  ref: string;
  model_resolved: string;
  threshold: number;
  min_keep: number | null;
  retest_sd: number;
  repack_sd: number;
  action_precision_lb: number | null;
  policy_fingerprint: string | null;
  pack_shape: string;
  split_hash: string | null;
  calibrate_only: boolean;
  /** S9: proposal floor calibrated on supersede labels (local row notes or the reference row). */
  proposal_floor?: number;
}

/** A calibrated S9 proposal floor stored in a local row's notes JSON, if any. */
export function notesProposalFloor(notes: string | null | undefined): number | undefined {
  if (!notes) return undefined;
  try {
    const v = (JSON.parse(notes) as { proposal_floor?: unknown }).proposal_floor;
    return typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1 ? v : undefined;
  } catch { return undefined; }
}

export interface SlotPolicy {
  slot: DecideSlot;
  callSite: string;
  requested: DecideMode;
  /** What the call does: `off` = today's path (possibly with an inactive-cause receipt). */
  effective: DecideMode;
  /** Catalogued reason when effective is lower than requested. */
  inactive?: string;
  provider: string;
  /** The model id calibrations are looked up under (resolved alias when known). */
  model: string | null;
  threshold?: number;
  thresholdSource: 'override' | 'calibration' | 'reference' | 'none';
  calibration?: PolicyCalibration;
  minKeep: number;
  margin: number;
  fingerprint: string;
  forceOn: boolean;
  shadowSample: number;
  shadowWait: boolean;
  packShape: string;
  /** S6: the suppression boundary (part of the fingerprint). */
  suppressBelow?: number;
}

export interface PolicyInputs {
  cfg: DecideConfig;
  slot: DecideSlot;
  callSite?: string;
  packShape: string;
  calibrations: readonly CalibrationRow[];
  /** provider -> most recently resolved model id (from receipts). */
  lastResolved?: Readonly<Record<string, string>>;
  /** A TypeSafe key is configured (TYPESAFE_API_KEY or JEV_TYPESAFE_API_KEY). */
  hasTypesafeKey: boolean;
  /** search.reranker.model, for S1. */
  rerankerModel?: string;
  references?: readonly ReferenceCalibration[];
}

export function marginFor(marginFloor: number, calibration?: Pick<PolicyCalibration, 'retest_sd' | 'repack_sd'>): number {
  const sd = calibration ? Math.max(calibration.retest_sd, calibration.repack_sd) : 0;
  return Math.max(marginFloor, 2 * sd);
}

/** Immutable fingerprint of the action policy a qualification is bound to. */
export function policyFingerprint(p: { slot: DecideSlot; callSite: string; threshold?: number; marginFloor: number; minKeep: number; packShape: string; suppressBelow?: number }): string {
  const body = JSON.stringify({
    slot: p.slot, callSite: p.callSite, threshold: p.threshold === undefined ? null : Number(p.threshold.toFixed(4)),
    margin: 'max(floor,2*max(retest_sd,repack_sd))', marginFloor: p.marginFloor, minKeep: p.minKeep,
    protections: PROTECTION_VERSION, question: SLOT_SPECS[p.slot].questionVersion, packShape: p.packShape,
    suppressBelow: p.suppressBelow,
  });
  return createHash('sha256').update(body).digest('hex').slice(0, 16);
}

function fromLocal(row: CalibrationRow): PolicyCalibration {
  return {
    ref: `local:${row.id}`, model_resolved: row.model_resolved, threshold: row.threshold, min_keep: row.min_keep,
    retest_sd: row.retest_sd ?? 0, repack_sd: row.repack_sd ?? 0, action_precision_lb: row.action_precision_lb,
    policy_fingerprint: row.policy_fingerprint, pack_shape: row.pack_shape, split_hash: row.split_hash, calibrate_only: row.calibrate_only,
    ...(notesProposalFloor(row.notes) !== undefined ? { proposal_floor: notesProposalFloor(row.notes) } : {}),
  };
}

function fromReference(row: ReferenceCalibration): PolicyCalibration {
  return {
    ref: `ref:${row.id}`, model_resolved: row.model_resolved, threshold: row.threshold, min_keep: row.min_keep,
    retest_sd: row.retest_sd, repack_sd: row.repack_sd, action_precision_lb: row.action_precision_lb,
    policy_fingerprint: row.policy_fingerprint, pack_shape: row.pack_shape, split_hash: row.split_hash, calibrate_only: true,
    ...(row.proposal_floor !== undefined ? { proposal_floor: row.proposal_floor } : {}),
  };
}

/** The model id calibrations are keyed under for `provider`, or null when an alias has never resolved. */
export function lookupModel(provider: string, lastResolved?: Readonly<Record<string, string>>): string | null {
  const kind = providerKind(provider);
  if (kind === 'typesafe') return isTypesafeAlias(provider) ? lastResolved?.[provider] ?? null : provider.replace(/^typesafe:/, '');
  if (kind === 'llm') return lastResolved?.[provider] ?? llmChatModel(provider);
  return null;
}

export function selectCalibration(inputs: Pick<PolicyInputs, 'slot' | 'calibrations' | 'references'> & { callSite: string; provider: string; model: string | null; adopted?: string }): PolicyCalibration | undefined {
  const { slot, callSite, provider, model, adopted } = inputs;
  if (!model) return undefined;
  const matches = (r: { slot: string; call_site: string; provider: string; model_resolved: string }) =>
    r.slot === slot && r.call_site === callSite && r.provider === provider && r.model_resolved === model;
  const refs = inputs.references ?? REFERENCE_CALIBRATIONS;
  if (adopted?.startsWith('local:')) {
    const row = inputs.calibrations.find((r) => `local:${r.id}` === adopted && !r.retired_at && matches(r));
    if (row) return fromLocal(row);
  }
  if (adopted?.startsWith('ref:')) {
    const row = refs.find((r) => `ref:${r.id}` === adopted && matches(r));
    if (row) return fromReference(row);
  }
  const local = inputs.calibrations
    .filter((r) => !r.retired_at && matches(r))
    .sort((a, b) => (a.created_at < b.created_at ? 1 : a.created_at > b.created_at ? -1 : b.id - a.id))[0];
  if (local) return fromLocal(local);
  const ref = refs.find(matches);
  return ref ? fromReference(ref) : undefined;
}

export function resolveSlotPolicy(inputs: PolicyInputs): SlotPolicy {
  const { cfg, slot } = inputs;
  const spec = SLOT_SPECS[slot];
  const sc = cfg.slots[slot];
  const callSite = inputs.callSite ?? spec.callSites[0]!;
  const provider = slot === 'rerank' && sc.mode !== 'off' && inputs.rerankerModel?.startsWith('typesafe:') ? inputs.rerankerModel : sc.provider;
  const model = lookupModel(provider, inputs.lastResolved);
  const calibration = spec.thresholded
    ? selectCalibration({ slot, callSite, provider, model, adopted: sc.calibration, calibrations: inputs.calibrations, references: inputs.references })
    : undefined;
  const threshold = sc.threshold ?? calibration?.threshold;
  const thresholdSource: SlotPolicy['thresholdSource'] = sc.threshold !== undefined ? 'override'
    : calibration ? (calibration.ref.startsWith('ref:') ? 'reference' : 'calibration') : 'none';
  const minKeep = sc.minKeep ?? calibration?.min_keep ?? spec.defaultMinKeep ?? 0;
  const margin = marginFor(cfg.marginFloor, sc.threshold !== undefined && !calibration ? undefined : calibration);
  const fingerprint = policyFingerprint({ slot, callSite, threshold, marginFloor: cfg.marginFloor, minKeep, packShape: inputs.packShape, suppressBelow: sc.suppressBelow });
  const base: SlotPolicy = {
    slot, callSite, requested: sc.mode, effective: sc.mode, provider, model, threshold, thresholdSource, calibration,
    minKeep, margin, fingerprint, forceOn: sc.forceOn, shadowSample: sc.shadowSample ?? spec.shadowSample,
    shadowWait: sc.shadowWait, packShape: inputs.packShape, ...(sc.suppressBelow !== undefined ? { suppressBelow: sc.suppressBelow } : {}),
  };
  const inactive = (reason: string): SlotPolicy => ({ ...base, effective: 'off', inactive: reason });
  if (sc.mode === 'off') return base;
  if (!spec.wired) return inactive('slot_unavailable');
  if (slot === 'rerank') {
    if (cfg.provider === 'none') return inactive('no_provider');
    if (sc.mode === 'on' && !inputs.rerankerModel?.startsWith('typesafe:')) return inactive('reranker_not_jev');
    if (!inputs.hasTypesafeKey) return inactive('no_key');
    // Shadow with the Jev reranker already selected behaves as on.
    if (sc.mode === 'shadow' && inputs.rerankerModel?.startsWith('typesafe:')) return { ...base, effective: 'on' };
    return base;
  }
  const kind = providerKind(provider);
  if (kind === 'none') return inactive('no_provider');
  if (kind === 'typesafe' && !inputs.hasTypesafeKey) return inactive('no_key');
  if (sc.mode === 'shadow') return base;
  if (kind === 'llm' && llmCapability(provider) !== 'structured') return inactive('llm_capability');
  if (threshold === undefined) return inactive('no_calibration');
  if (calibration && sc.threshold === undefined && calibration.pack_shape !== inputs.packShape) return inactive('pack_shape_mismatch');
  if (spec.harmful && !sc.forceOn) {
    if (!calibration || calibration.action_precision_lb === null) return inactive('no_qualification');
    if (calibration.action_precision_lb < sc.minActionPrecision) return inactive('action_precision_low');
    if (calibration.policy_fingerprint && calibration.policy_fingerprint !== fingerprint) return inactive('policy_changed');
  }
  return base;
}

export const KEY_DEFAULT_LABEL = 'default: Jev key present';

/** One-line opt-out for a slot on by the key-aware default. */
export function keyDefaultOptOut(slot: DecideSlot): string {
  return `gbrain decide disable ${slot}`;
}

/** Readiness line for status/doctor: off, ready for on, on, on (default: Jev key present), on (inactive: <reason>), needs calibration, shadow. */
export function readiness(policy: SlotPolicy, inputs: PolicyInputs): string {
  if (policy.requested === 'on' && inputs.cfg.slots[policy.slot].keyDefault) {
    return policy.inactive ? `on (${KEY_DEFAULT_LABEL}; inactive: ${policy.inactive})` : `on (${KEY_DEFAULT_LABEL})`;
  }
  if (policy.requested === 'on') return policy.inactive ? `on (inactive: ${policy.inactive})` : 'on';
  if (policy.requested === 'shadow') return policy.inactive ? `shadow (inactive: ${policy.inactive})` : 'shadow';
  const spec = SLOT_SPECS[policy.slot];
  if (!spec.wired) return 'off';
  // Probe what `decide enable <slot>` would produce (it writes the pinned default provider, and the reranker for S1).
  const sc = inputs.cfg.slots[policy.slot];
  const provider = sc.provider === 'none' ? DEFAULT_TYPESAFE_PROVIDER : sc.provider;
  const probe = resolveSlotPolicy({
    ...inputs,
    cfg: { ...inputs.cfg, provider: inputs.cfg.provider === 'none' ? provider : inputs.cfg.provider, slots: { ...inputs.cfg.slots, [policy.slot]: { ...sc, mode: 'on', provider } } },
    ...(policy.slot === 'rerank' ? { rerankerModel: inputs.rerankerModel?.startsWith('typesafe:') ? inputs.rerankerModel : DEFAULT_TYPESAFE_PROVIDER } : {}),
  });
  if (!probe.inactive) return 'ready for on';
  return ['no_calibration', 'no_qualification', 'pack_shape_mismatch'].includes(probe.inactive) ? 'needs calibration' : 'off';
}

/** After a response: a resolved model different from the calibration's demotes that call (override never demotes). */
export function driftReason(policy: SlotPolicy, resolved: string): string | undefined {
  if (policy.thresholdSource === 'override' || !policy.calibration) return undefined;
  return resolved === policy.calibration.model_resolved ? undefined : 'model_drift';
}