Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
35.0 KB
Raw Blame
/**
 * `gbrain decide`: System One operator surface (local CLI only; thin clients
 * refuse). Every slot is `off` or `on`; `--shadow` is advanced diagnostics.
 *
 *   status [--json] [--egress]        provider, consent, budget, per-slot readiness
 *   probe [--query <q>] [--yes]       key-only live probe; --query previews S1+S3
 *   enable <slot> [--provider <id>] [--shadow] [--yes] | enable --recommended
 *   disable <slot> | --all
 *   calibrate / qualify / calibrations / dataset   (src/commands/decide/calibrate.ts)
 *   receipts [--slot <slot>] [--since <h>] [--what-if-threshold <t>]  (decide/receipts.ts)
 *
 * Slot lanes add subcommands (proposals, sweep; judge-agreement from decide/eval-lane.ts) through
 * `registerDecideSubcommand`.
 */
import type { BrainEngine } from '../core/engine.ts';
import { loadConfigSnapshot } from '../core/config-snapshot.ts';
import { configureGateway, configureGatewayIfUninitialized, requireConfig } from '../core/ai/gateway.ts';
import { buildGatewayConfig } from '../core/ai/build-gateway-config.ts';
import { typesafeApiKey } from '../core/ai/recipes/typesafe.ts';
import {
  DEFAULT_TYPESAFE_PROVIDER, isTypesafeAlias, isValidProvider, providerKind, readDecideConfig, type DecideConfig,
} from '../core/ai/decide/config.ts';
import { runDecide } from '../core/ai/decide/index.ts';
import { estimateContextTokens, packShape, planBatches } from '../core/ai/decide/pack.ts';
import { KEY_DEFAULT_LABEL, keyDefaultOptOut, readiness, resolveSlotPolicy, type PolicyInputs, type SlotPolicy } from '../core/ai/decide/policy.ts';
import { newerReference, recommendedSlots } from '../core/ai/decide/reference-calibrations.ts';
import { REFUSAL_CATALOG, SLOT_PLAIN_NAMES, refusalLine } from '../core/ai/decide/outcomes.ts';
import { toWireQuestion } from '../core/ai/decide/providers/typesafe.ts';
import { SLOT_SPECS } from '../core/ai/decide/slots.ts';
import {
  conflictNoEntityShare, dailySpend, deleteDecideState, flushDecideWrites, getDecideState, listCalibrations, recentResolvedModels, setDecideState,
  slotUsage, type CalibrationRow,
} from '../core/ai/decide/store.ts';
import { DECIDE_SLOTS, DecideError, EVIDENCE_CLASSES, type DecideQuestion, type DecideSlot } from '../core/ai/decide/types.ts';
import { usageCostUsd } from '../core/budget/reservation-cost.ts';
import { evidenceCoPackedSlots, resetDecideSearchCache } from '../core/search/decide-stage.ts';
import { currentExitCode } from '../core/cli-force-exit.ts';
import { consentGate, engineConsentEnv } from '../core/consent-cli.ts';

export const DECIDE_HELP = `Usage: gbrain decide <subcommand> [options]

System One decision support (TypeSafe Jev or an llm: provider). Each slot is off
or on. Without a TypeSafe key every slot is off; with one, the slots with a measured
win (the enable --recommended set) are on by default until you set them yourself.
Runs on the brain host (local CLI only).

Subcommands:
  status [--json] [--egress]                 Provider, consent, budget and per-slot readiness
  probe [--query <q>] [--yes] [--json]       Live probe with only a key; --query previews rerank
                                             and the evidence gate on your brain (changes nothing)
  enable <slot> [--provider <id>] [--yes] [--json]
                                             Turn a slot on (writes provider, consent and mode)
  enable --recommended [--yes]               Turn on the slots with a recorded win
  enable <slot> --shadow                     Advanced diagnostics: receipts only, no behavior change
  disable <slot> | --all                     Turn a slot (or every slot) off
  calibrate --slot <slot> --dataset <jsonl> [--target precision|recall|f1] [--min <x>]
            [--call-site <site>] [--dry-run] [--json]
  qualify --slot <slot> --dataset <jsonl> [--call-site <site>] [--items-out <path>] [--json]
  calibrations list [--slot <slot>] [--json] | adopt <id> | retire <id> | restore <id>
  dataset --slot <slot> --from <source> <path> [--out <file>]
  receipts [--slot <slot>] [--since <hours>] [--what-if-threshold <t>] [--json]

Slots: ${DECIDE_SLOTS.map((s) => `${s} (${SLOT_PLAIN_NAMES[s]})`).join(', ')}
Docs: docs/guides/system-one.md, docs/architecture/decide.md
`;

export type DecideSubcommand = (engine: BrainEngine, args: string[]) => Promise<number>;
const extraSubcommands = new Map<string, { run: DecideSubcommand; help: string }>();

/** Slot lanes register subcommands (proposals, sweep, judge-agreement) here. */
export function registerDecideSubcommand(name: string, run: DecideSubcommand, help: string): void {
  extraSubcommands.set(name, { run, help });
}

/** Slot lanes register subcommands, what-if reducers and dataset adapters when their module loads. */
export async function loadDecideLanes(): Promise<void> {
  await import('./decide/writepath.ts');
  await import('./decide/eval-lane.ts');
}

export function decideHelpText(): string {
  const extra = [...extraSubcommands.entries()].map(([, v]) => `  ${v.help}`).join('\n');
  return extra ? `${DECIDE_HELP}\nMore subcommands:\n${extra}\n` : DECIDE_HELP;
}

export function flagValue(args: string[], flag: string): string | undefined {
  const i = args.indexOf(flag);
  return i >= 0 && i + 1 < args.length && !args[i + 1]!.startsWith('--') ? args[i + 1] : undefined;
}

const has = (args: string[], flag: string) => args.includes(flag);

// ---------------------------------------------------------------------------
// Shared state
// ---------------------------------------------------------------------------

export interface DecideState {
  cfg: DecideConfig;
  snapshot: Record<string, string>;
  calibrations: CalibrationRow[];
  lastResolved: Record<string, string>;
  key: { present: boolean; from: string | null };
  rerankerModel: string;
  rerankerEnabled: boolean;
  searchMode: string;
}

export async function loadDecideState(engine: BrainEngine): Promise<DecideState> {
  const snapshot = (await loadConfigSnapshot(engine)) ?? {};
  const [calibrations, recent] = await Promise.all([listCalibrations(engine, { includeRetired: true }), recentResolvedModels(engine, 24 * 7)]);
  const lastResolved: Record<string, string> = {};
  for (const r of recent) lastResolved[r.provider] ??= r.model_resolved;
  let env: Record<string, string | undefined> = process.env;
  try { env = requireConfig().env; } catch { /* unconfigured gateway: process env */ }
  const key = typesafeApiKey(env);
  const cfg = readDecideConfig(snapshot, { typesafeKey: key !== null });
  const { loadSearchModeConfig, resolveSearchMode } = await import('../core/search/mode.ts');
  const modeInput = await loadSearchModeConfig(engine);
  const knobs = resolveSearchMode({ mode: modeInput.mode, overrides: modeInput.overrides });
  return {
    cfg, snapshot, calibrations: calibrations.filter((c) => !c.retired_at), lastResolved,
    key: { present: key !== null, from: key?.from ?? null },
    rerankerModel: knobs.reranker_model, rerankerEnabled: knobs.reranker_enabled, searchMode: knobs.resolved_mode,
  };
}

export function slotPackShape(slot: DecideSlot, cfg: DecideConfig): string {
  if (slot === 'injection') return packShape('evidence', [...evidenceCoPackedSlots(cfg), 'injection']);
  return slot === 'evidence' ? packShape('evidence', evidenceCoPackedSlots(cfg)) : packShape(slot, [], { unpacked: ['answerable', 'triage', 'grounding'].includes(slot) });
}

export function policyInputs(state: DecideState, slot: DecideSlot, cfg = state.cfg, callSite?: string): PolicyInputs {
  return {
    cfg, slot, callSite, packShape: slotPackShape(slot, cfg), calibrations: state.calibrations, lastResolved: state.lastResolved,
    hasTypesafeKey: state.key.present, rerankerModel: state.rerankerEnabled ? state.rerankerModel : undefined,
  };
}

export function policyFor(state: DecideState, slot: DecideSlot, cfg = state.cfg): SlotPolicy {
  return resolveSlotPolicy(policyInputs(state, slot, cfg));
}

/** `requested: <mode> / effective: <mode> / cause: <reason> (<values>) / fix: <command> / docs: <anchor>` */
export function effectiveModeLine(p: SlotPolicy): string | null {
  if (p.requested === p.effective && !p.inactive) return null;
  const entry = REFUSAL_CATALOG[p.inactive ?? ''];
  const cause = entry ? `${p.inactive} (${entry.cause})` : p.inactive ?? 'unknown';
  const fix = entry ? entry.fix.replaceAll('<slot>', p.slot) : 'gbrain decide status';
  return `${p.slot}: requested: ${p.requested} / effective: ${p.effective} / cause: ${cause} / fix: ${fix} / docs: docs/guides/system-one.md${entry?.anchor ?? ''}`;
}

/** Post-set hook for `gbrain config set decide.slots.<slot>.*`. */
export async function printEffectiveModeLines(engine: BrainEngine, slot?: string): Promise<void> {
  if (!slot || !(DECIDE_SLOTS as readonly string[]).includes(slot)) return;
  const state = await loadDecideState(engine);
  const line = effectiveModeLine(policyFor(state, slot as DecideSlot));
  if (line) console.log(line);
}

const TYPICAL_CANDIDATE = 'x'.repeat(1200);
const CLASS_TEXT: Record<string, string> = { query: 'query text', candidates: 'candidate text', facts: 'fact text', conversation: 'conversation text' };
const COST_UNITS: Partial<Record<DecideSlot, { unit: string; questions: number; unpacked?: boolean }>> = {
  rerank: { unit: 'queries', questions: 30 },
  evidence: { unit: 'queries', questions: 20 },
  recall_needed: { unit: 'turns', questions: 1 },
  triage: { unit: 'transcripts', questions: 20, unpacked: true },
  grounding: { unit: 'dream pages', questions: 10, unpacked: true },
  conflict: { unit: 'swept facts', questions: 5 },
};

/** Estimated USD per 1,000 units: from the last 24 h of receipts, else the planner estimate for a typical input. */
function costPer1k(slot: DecideSlot, provider: string, usage?: { decisions: number; input_tokens: number }): { usd: number | null; basis: 'receipts' | 'estimate' | 'n/a' } {
  if (providerKind(provider) !== 'typesafe') return { usd: null, basis: 'n/a' };
  if (usage && usage.decisions > 0) return { usd: (usageCostUsd(provider, usage.input_tokens / usage.decisions, 0, 'decide') ?? 0) * 1000, basis: 'receipts' };
  const typical = COST_UNITS[slot];
  if (!typical) return { usd: null, basis: 'n/a' };
  const q: DecideQuestion = { id: 'q', kind: 'noul', instructions: 'Typical question about `candidate`.', inputs: { candidate: { text: TYPICAL_CANDIDATE, class: 'candidates' } } };
  const tokens = typical.unpacked
    ? typical.questions * planBatches(estimateContextTokens({}), [estimateContextTokens(toWireQuestion(q))])[0]!.estimatedInputTokens
    : planBatches(estimateContextTokens({ query: 'a typical question' }), Array.from({ length: typical.questions }, () => estimateContextTokens(toWireQuestion(q))))
      .reduce((n, b) => n + b.estimatedInputTokens, 0);
  return { usd: (usageCostUsd(provider, tokens, 0, 'decide') ?? 0) * 1000, basis: 'estimate' };
}

// ---------------------------------------------------------------------------
// status
// ---------------------------------------------------------------------------

export async function buildStatus(engine: BrainEngine, state: DecideState) {
  const [spend, usage, noEntity, reviewRates] = await Promise.all([
    dailySpend(engine).catch(() => ({ total: 0, remote: 0 })), slotUsage(engine, 24).catch(() => []),
    conflictNoEntityShare(engine).catch(() => ({ skipped: 0, receipts: 0, share: 0 })),
    import('../core/ai/decide/review-lane.ts').then(m => m.proposalReviewRates(engine)).catch(() => []),
  ]);
  const slots = DECIDE_SLOTS.map((slot) => {
    const p = policyFor(state, slot);
    const u = usage.find((x) => x.slot === slot);
    const inputs = policyInputs(state, slot);
    return {
      slot, plain: SLOT_PLAIN_NAMES[slot], wired: SLOT_SPECS[slot].wired, mode: p.requested, effective: p.effective,
      readiness: readiness(p, inputs), inactive: p.inactive ?? null, provider: p.provider, model: p.model,
      threshold: p.threshold ?? null, threshold_source: p.thresholdSource, calibration: p.calibration?.ref ?? null,
      min_keep: SLOT_SPECS[slot].thresholded ? p.minKeep : null, force_on: p.forceOn,
      newer_reference: newerReference(p),
      receipts_24h: u?.rows ?? 0, decisions_24h: u?.decisions ?? 0, errors_24h: u?.errors ?? 0,
      error_rate_24h: u && u.rows > 0 ? Number((u.errors / u.rows).toFixed(4)) : 0, egress_refusals_24h: u?.egress ?? 0,
      status: !u || u.rows === 0 ? 'pending' : u.skipped === u.rows ? (p.inactive ? 'demoted' : 'blocked') : 'active',
      cost_per_1k: { ...costPer1k(slot, p.provider, u), unit: COST_UNITS[slot]?.unit ?? 'units' },
      effective_line: effectiveModeLine(p),
      ...(state.cfg.slots[slot].keyDefault ? { key_default: true, opt_out: keyDefaultOptOut(slot) } : {}),
      ...(slot === 'conflict' ? { no_entity_7d: noEntity, proposal_review: reviewRates } : {}),
    };
  });
  return {
    provider: state.cfg.provider, provider_pinned: state.cfg.provider !== 'none' && !isTypesafeAlias(state.cfg.provider),
    key: state.key,
    egress: {
      private: state.cfg.egressPrivate, fallback: state.cfg.egressFallback, deny_sources: state.cfg.denySources,
      consent: Object.fromEntries(EVIDENCE_CLASSES.map((c) => [c, state.cfg.consent[c] ? 'allow' : 'deny'])),
    },
    budget: {
      daily_usd: state.cfg.dailyUsd, spent_today_usd: Number(spend.total.toFixed(6)), remote_today_usd: Number(spend.remote.toFixed(6)),
      remote_share: state.cfg.remoteShare,
      excluded: ['S1 on: reranker spend controls (BudgetKind rerank)', 'llm: providers: chat spend controls (BudgetKind chat)'],
    },
    reranker: {
      model: state.rerankerModel, enabled: state.rerankerEnabled, search_mode: state.searchMode,
      jev_called: state.rerankerEnabled && state.rerankerModel.startsWith('typesafe:') ? 'yes (reranker)' : state.cfg.slots.rerank.mode === 'shadow' ? 'shadow' : 'no',
      credential: state.key.from,
    },
    slots,
  };
}

async function cmdStatus(engine: BrainEngine, args: string[]): Promise<number> {
  const state = await loadDecideState(engine);
  const status = await buildStatus(engine, state);
  if (has(args, '--json')) {
    console.log(JSON.stringify(status, null, 2));
    return 0;
  }
  console.log(`System One (decide): provider ${status.provider}${status.provider !== 'none' && !status.provider_pinned ? ' (alias: pin with gbrain decide enable <slot>)' : ''}; key: ${state.key.from ?? 'not set'}`);
  const keyDefaults = status.slots.filter((s) => s.key_default).map((s) => `${s.slot} (${SLOT_SPECS[s.slot].egressClasses.join(', ')})`);
  console.log(`egress: private=${status.egress.private}; consent ${EVIDENCE_CLASSES.map((c) => `${c}=${status.egress.consent[c]}`).join(' ')}; deny_sources: ${status.egress.deny_sources.join(',') || 'none'}; fallback: ${status.egress.fallback}${keyDefaults.length ? `; key default allows: ${keyDefaults.join(', ')}` : ''}`);
  console.log(`budget: $${status.budget.spent_today_usd.toFixed(4)} of $${status.budget.daily_usd.toFixed(2)} today (remote $${status.budget.remote_today_usd.toFixed(4)}, cap ${Math.round(status.budget.remote_share * 100)}%); not covered: ${status.budget.excluded.join('; ')}`);
  console.log(`reranker: ${status.reranker.model} (${status.reranker.enabled ? 'enabled' : 'disabled'}, mode ${status.reranker.search_mode}); Jev called: ${status.reranker.jev_called}`);
  console.log('');
  for (const s of status.slots) {
    const threshold = s.threshold === null ? '' : ` threshold ${s.threshold.toFixed(3)} (${s.threshold_source}${s.calibration ? ` ${s.calibration}` : ''})`;
    const cost = s.cost_per_1k.usd === null ? '' : ` ~$${s.cost_per_1k.usd.toFixed(4)}/1k ${s.cost_per_1k.unit} (${s.cost_per_1k.basis})`;
    const activity = s.receipts_24h > 0 ? ` 24h: ${s.decisions_24h} decisions, ${(s.error_rate_24h * 100).toFixed(1)}% errors` : '';
    console.log(`  ${s.slot.padEnd(14)} ${s.readiness}${threshold}${cost}${activity}${s.wired ? '' : ' (not available in this build)'}`);
    if (s.force_on) console.log(`    WARN: decide.slots.${s.slot}.force_on bypasses the action-precision gate`);
    if (s.newer_reference) console.log(`    newer reference available: ${s.newer_reference} (gbrain decide calibrations adopt ${s.newer_reference})`);
    if (s.no_entity_7d && s.no_entity_7d.skipped > 0) {
      console.log(`    ${(s.no_entity_7d.share * 100).toFixed(1)}% of conflict receipts in 7 days (${s.no_entity_7d.skipped} of ${s.no_entity_7d.receipts}) skipped a fact with no entity (no_entity); link them: gbrain facts relink --dry-run`);
    }
    for (const r of s.proposal_review ?? []) {
      if (!r.enabled && r.pending === 0) continue;
      console.log(`    ${r.kind} proposals: ${r.pending} pending${r.oldest_pending_days !== null ? ` (oldest ${r.oldest_pending_days} days)` : ''}; last 30 days: ${r.accepted_30d} accepted, ${r.rejected_30d} rejected${r.pending > 0 ? ' (review: gbrain decide proposals list)' : ''}`);
    }
    if (s.opt_out) console.log(`    on by default because a TypeSafe key is present (sends ${SLOT_SPECS[s.slot].egressClasses.map((c) => CLASS_TEXT[c]).join(', ')} to TypeSafe); opt out: ${s.opt_out}`);
  }
  const lines = status.slots.map((s) => s.effective_line).filter(Boolean);
  if (lines.length) { console.log(''); for (const l of lines) console.log(l); }
  if (has(args, '--egress')) {
    console.log('\nprovider x data class (the key that decides each cell):');
    for (const c of EVIDENCE_CLASSES) {
      const typesafe = status.egress.consent[c] === 'allow' ? `allow (decide.egress.typesafe.${c})` : `deny (decide.egress.typesafe.${c})`;
      const priv = c === 'query' ? '' : `; private content: ${status.egress.private} (decide.egress.private)`;
      console.log(`  ${c.padEnd(13)} typesafe: ${typesafe}${priv}; llm: chat egress rules; reranker (S1 on): ${c === 'query' || c === 'candidates' ? 'search.reranker.model' : 'n/a'}`);
    }
  }
  return 0;
}

// ---------------------------------------------------------------------------
// probe
// ---------------------------------------------------------------------------

const PROBE_QUESTIONS: DecideQuestion[] = [
  { id: 'probe_p', kind: 'noul', instructions: 'Does `note` state a decision?', inputs: { note: { text: 'We decided to ship the beta on Friday.', class: 'query' } } },
  { id: 'probe_c', kind: 'choice', instructions: 'What kind of statement is `note`?', options: { decision: 'a decision', question: 'a question', other: 'anything else' }, inputs: { note: { text: 'We decided to ship the beta on Friday.', class: 'query' } } },
];

export function ensureGatewayForProbe(): void {
  configureGatewayIfUninitialized();
  try { requireConfig(); } catch { configureGateway(buildGatewayConfig({ engine: 'pglite' } as Parameters<typeof buildGatewayConfig>[0])); }
}

export async function cmdProbe(engine: BrainEngine | null, args: string[]): Promise<number> {
  ensureGatewayForProbe();
  const json = has(args, '--json');
  const key = typesafeApiKey(requireConfig().env);
  if (!key) { console.error(refusalLine('no_key')); return 1; }
  const cfg = engine ? readDecideConfig((await loadConfigSnapshot(engine)) ?? {}) : readDecideConfig(null);
  const provider = cfg.provider.startsWith('typesafe:') ? cfg.provider : DEFAULT_TYPESAFE_PROVIDER;
  const query = flagValue(args, '--query');
  if (query) {
    if (!engine) { console.error('probe --query needs a brain: run it on the brain host.'); return 1; }
    const { runProbeQuery } = await import('./decide/probe-query.ts');
    return runProbeQuery(engine, cfg, provider, query, args);
  }
  const consentCfg = { ...cfg, consent: { ...cfg.consent, query: true } };
  try {
    const r = await runDecide({ slot: 'evidence', callSite: 'probe', state: {}, questions: PROBE_QUESTIONS, provider, deadlineMs: 10_000, lane: 'background' }, { engine: null, config: consentCfg });
    const out = {
      requested: provider, model_resolved: r.model_resolved, latency_ms: r.latency_ms, input_tokens: r.usage.input_tokens,
      cost_usd: Number(r.cost_usd.toFixed(8)), key_from: key.from, brain_content_sent: false,
      answers: r.answers, next: 'gbrain decide probe --query "<a question your brain can answer>"',
    };
    if (json) console.log(JSON.stringify(out, null, 2));
    else {
      console.log(`TypeSafe Jev probe: resolved ${r.model_resolved} (requested ${provider}) in ${r.latency_ms} ms, ${r.usage.input_tokens} input tokens, $${r.cost_usd.toFixed(6)}.`);
      console.log(`Key: ${key.from}. No brain content was sent.`);
      console.log(`Next: ${out.next}`);
    }
    return 0;
  } catch (err) {
    const reason = err instanceof DecideError ? err.reason : 'provider_error';
    console.error(`probe failed: ${refusalLine(reason)}`);
    return 1;
  }
}

// ---------------------------------------------------------------------------
// enable / disable
// ---------------------------------------------------------------------------

const RERANK_OWNERSHIP_KEY = 'rerank.ownership';
/** Refusals that keep `enable` from writing anything (effective could not be on). */
const ENABLE_REFUSALS = new Set(['slot_unavailable', 'no_provider', 'no_key', 'no_calibration', 'no_qualification', 'action_precision_low', 'policy_changed', 'pack_shape_mismatch', 'llm_capability']);
const PRIVATE_SLOTS: readonly DecideSlot[] = ['recall_needed', 'triage', 'grounding', 'conflict'];

async function resolvePinned(provider: string): Promise<string> {
  if (!isTypesafeAlias(provider)) return provider;
  const r = await runDecide({ slot: 'evidence', callSite: 'probe', state: {}, questions: [PROBE_QUESTIONS[0]!], provider, deadlineMs: 10_000, lane: 'background' },
    { engine: null, config: { ...readDecideConfig(null), consent: { query: true, candidates: false, facts: false, conversation: false } } });
  return `typesafe:${r.model_resolved}`;
}

/**
 * A4 consent for turning a slot on: text leaves the machine (`egress`) and the
 * provider bills per call (`paid`, bounded by decide.budget.daily_usd). `--yes`
 * authorizes; `--json` never does. Resolves false after printing the refusal
 * (exit verdict 3) or a declined prompt.
 */
async function enableConsent(engine: BrainEngine, args: string[], req: { slots: DecideSlot[]; summary: string[]; dailyUsd: number; argv: string[] }): Promise<boolean> {
  const json = has(args, '--json');
  for (const line of req.summary) (json ? console.error : console.log)(line);
  const what = req.slots.length === 1 ? `Turn on the decide slot ${req.slots[0]}` : `Turn on the decide slots ${req.slots.join(', ')}`;
  const auth = await consentGate({
    command: 'decide enable',
    effects: ['egress', 'paid'],
    actor: 'agent',
    what,
    why: 'System One answers these routing and ranking questions with a hosted model instead of local heuristics; each slot is a measured win on the eval sets.',
    risk: `From now on, brain text named in the summary leaves this machine on every affected call, and the provider bills per call up to decide.budget.daily_usd ($${req.dailyUsd.toFixed(2)}/day). `
      + 'Undo any time: gbrain decide disable --all.',
    user_message: `${what}? Some of your brain's text (${req.summary.find(l => l.startsWith('Data that leaves')) ?? 'see the summary'}) will be sent to the provider on each call, capped at $${req.dailyUsd.toFixed(2)} a day; gbrain decide disable --all turns it off.`,
    argv: req.argv,
    preview_argv: ['gbrain', 'decide', 'status', '--json'],
    est_usd: null,
    args,
  }, { json, env: engineConsentEnv(engine, { configuredCapUsd: req.dailyUsd }) });
  return auth !== null;
}

async function writeConfig(engine: BrainEngine, writes: Array<[string, string]>): Promise<void> {
  for (const [k, v] of writes) await engine.setConfig(k, v);
  resetDecideSearchCache();
}

async function enableRerank(engine: BrainEngine, state: DecideState, provider: string, args: string[]): Promise<Array<[string, string]>> {
  const pinned = provider.startsWith('typesafe:') ? provider : DEFAULT_TYPESAFE_PROVIDER;
  const owned = await getDecideState(engine, RERANK_OWNERSHIP_KEY);
  if (!owned) {
    const previous = { model: state.snapshot['search.reranker.model'] ?? null, enabled: state.snapshot['search.reranker.enabled'] ?? null };
    await setDecideState(engine, RERANK_OWNERSHIP_KEY, JSON.stringify({ previous, wrote: { model: pinned, enabled: 'true' } }));
  }
  if (state.searchMode === 'conservative' && !state.snapshot['search.reranker.enabled']) {
    console.log('WARN: search mode is conservative, which disables reranking; decide enable rerank sets search.reranker.enabled true.');
  }
  void args;
  return [['search.reranker.model', pinned], ['search.reranker.enabled', 'true']];
}

async function conflictShareLine(engine: BrainEngine, fate: string): Promise<string> {
  const share = await (await import('../core/ai/decide/proposals-store.ts')).privateFactShare(engine);
  return `Facts: ${share.private} of ${share.total} active facts are private and ${fate}; an llm: route (decide.slots.conflict.provider llm:<provider:model>) keeps them with your chat provider.`;
}

async function cmdEnable(engine: BrainEngine, args: string[]): Promise<number> {
  const json = has(args, '--json');
  const state = await loadDecideState(engine);
  if (has(args, '--recommended')) return enableRecommended(engine, state, args);
  const slot = args.find((a) => !a.startsWith('--') && a !== 'enable' && a !== flagValue(args, '--provider')) as DecideSlot | undefined;
  if (!slot || !(DECIDE_SLOTS as readonly string[]).includes(slot)) { console.error(`Usage: gbrain decide enable <slot>. Slots: ${DECIDE_SLOTS.join(', ')}`); return 1; }
  if (!SLOT_SPECS[slot].wired) { console.error(refusalLine('slot_unavailable', slot)); return 1; }
  const mode = has(args, '--shadow') ? 'shadow' : 'on';
  if (mode === 'on' && (flagValue(args, '--provider') ?? state.cfg.slots[slot].provider) === state.cfg.slots[slot].provider && state.cfg.slots[slot].keyDefault && !policyFor(state, slot).inactive) {
    if (json) console.log(JSON.stringify({ slot, requested: 'on', effective: 'on', inactive: null, key_default: true, writes: {} }, null, 2));
    else console.log(`${slot}: already on (${KEY_DEFAULT_LABEL}); nothing written. Opt out: ${keyDefaultOptOut(slot)}`);
    return 0;
  }
  const requestedProvider = flagValue(args, '--provider');
  if (requestedProvider && !isValidProvider(requestedProvider)) { console.error(`--provider must be typesafe:<model> or llm:<provider:model> (got ${requestedProvider})`); return 1; }
  const base = requestedProvider ?? state.cfg.slots[slot].provider;
  if (providerKind(base) === 'none' && slot !== 'rerank') { console.error(refusalLine('no_provider', slot)); return 1; }
  let provider = providerKind(base) === 'none' ? DEFAULT_TYPESAFE_PROVIDER : base;
  if (providerKind(provider) === 'typesafe' && !state.key.present) { console.error(refusalLine('no_key', slot)); return 1; }
  try { provider = await resolvePinned(provider); } catch (err) { console.error(`could not resolve ${provider}: ${err instanceof Error ? err.message : err}`); return 1; }

  const writes: Array<[string, string]> = [];
  if (state.cfg.provider === 'none' || (requestedProvider && state.cfg.provider === requestedProvider)) writes.push(['decide.provider', provider]);
  else if (requestedProvider) writes.push([`decide.slots.${slot}.provider`, provider]);
  const typesafe = providerKind(provider) === 'typesafe';
  const classes = SLOT_SPECS[slot].egressClasses;
  if (typesafe && slot !== 'rerank') for (const c of classes) writes.push([`decide.egress.typesafe.${c}`, 'allow']);
  if (typesafe && PRIVATE_SLOTS.includes(slot) && state.cfg.egressPrivate === 'deny' && state.cfg.egressFallback === 'none') {
    console.error(`${refusalLine('egress_private_denied', slot)}\nMissing keys: decide.egress.private=allow, or decide.slots.${slot}.provider llm:<provider:model>, or decide.egress_fallback llm:<provider:model>`);
    if (slot === 'conflict') console.error(await conflictShareLine(engine, 'would be refused'));
    return 1;
  }
  writes.push([`decide.slots.${slot}.mode`, mode]);
  const nextSnapshot = { ...state.snapshot, ...Object.fromEntries(writes) };
  if (slot === 'rerank') { nextSnapshot['search.reranker.model'] = provider; nextSnapshot['search.reranker.enabled'] = 'true'; }
  const nextCfg = readDecideConfig(nextSnapshot, { typesafeKey: state.key.present });
  const nextState: DecideState = { ...state, cfg: nextCfg, snapshot: nextSnapshot, ...(slot === 'rerank' ? { rerankerModel: provider, rerankerEnabled: true } : {}) };
  const policy = policyFor(nextState, slot);
  if (mode === 'on' && policy.inactive && ENABLE_REFUSALS.has(policy.inactive)) {
    console.error(refusalLine(policy.inactive, slot));
    return 1;
  }
  if (policy.calibration) writes.push([`decide.slots.${slot}.calibration`, policy.calibration.ref]);
  const cost = costPer1k(slot, provider);
  const summary = [
    `Enable ${slot} (${SLOT_PLAIN_NAMES[slot]}) ${mode === 'shadow' ? 'in shadow (advanced diagnostics)' : 'on'} with ${provider}.`,
    slot === 'rerank'
      ? 'Data that leaves this machine: query and candidate text go to TypeSafe as the search reranker, exactly as with any configured reranker (Voyage today).'
      : `Data that leaves this machine: ${classes.join(', ')} text to ${typesafe ? 'TypeSafe' : 'your configured chat provider'}; private pages stay local unless decide.egress.private=allow.`,
    ...(slot === 'conflict' && typesafe ? [await conflictShareLine(engine, state.cfg.egressPrivate === 'allow' ? 'are sent (decide.egress.private=allow)' : 'go to decide.egress_fallback')] : []),
    ...(cost.usd !== null ? [`Estimated cost: ~$${cost.usd.toFixed(4)} per 1,000 ${COST_UNITS[slot]?.unit ?? 'units'}; daily cap $${nextCfg.dailyUsd.toFixed(2)} (decide.budget.daily_usd${slot === 'rerank' ? '; S1 on uses reranker spend controls' : ''}).`] : []),
    `Writes: ${[...writes, ...(slot === 'rerank' ? [['search.reranker.model', provider], ['search.reranker.enabled', 'true']] : [])].map(([k, v]) => `${k}=${v}`).join(', ')}`,
  ];
  if (!(await enableConsent(engine, args, { slots: [slot], summary, dailyUsd: nextCfg.dailyUsd,
    argv: ['gbrain', 'decide', 'enable', slot, '--provider', provider, ...(mode === 'shadow' ? ['--shadow'] : []), ...(json ? ['--json'] : [])] }))) return currentExitCode() || 1;
  if (slot === 'rerank') writes.push(...await enableRerank(engine, state, provider, args));
  await writeConfig(engine, writes);
  const after = policyFor(nextState, slot);
  const line = effectiveModeLine(after);
  const result = { slot, requested: mode, effective: after.effective, inactive: after.inactive ?? null, provider, writes: Object.fromEntries(writes) };
  if (json) console.log(JSON.stringify(result, null, 2));
  else console.log(`${slot}: requested: ${mode} / effective: ${after.effective}${line ? `\n${line}` : ''}`);
  return after.effective === mode ? 0 : 1;
}

async function enableRecommended(engine: BrainEngine, state: DecideState, args: string[]): Promise<number> {
  const provider = state.cfg.provider !== 'none' ? state.cfg.provider : DEFAULT_TYPESAFE_PROVIDER;
  const model = provider.replace(/^typesafe:/, '');
  const recommended = recommendedSlots(provider, (slot) => state.cfg.slots[slot].minActionPrecision);
  const winners = DECIDE_SLOTS.filter((slot) => recommended.includes(slot));
  if (winners.length === 0) {
    console.error(`no slot has a recorded win for ${model}; see docs/eval/system-one/`);
    return 1;
  }
  // One ask covers every winner; the per-slot runs then carry the approval.
  if (!has(args, '--yes')) {
    const summary = [`Enable ${winners.join(', ')} with ${provider} (the slots with a recorded win; docs/eval/system-one/).`,
      `Data that leaves this machine: the query, candidate and fact text each slot scores, to ${provider.startsWith('typesafe:') ? 'TypeSafe' : 'your configured chat provider'}; private pages stay local unless decide.egress.private=allow.`];
    if (!(await enableConsent(engine, args, { slots: winners, summary, dailyUsd: state.cfg.dailyUsd,
      argv: ['gbrain', 'decide', 'enable', '--recommended', ...(flagValue(args, '--provider') ? ['--provider', flagValue(args, '--provider')!] : []), ...(has(args, '--json') ? ['--json'] : [])] }))) return currentExitCode() || 1;
  }
  let code = 0;
  const pin = state.cfg.provider === 'none' && !flagValue(args, '--provider') ? ['--provider', provider] : [];
  for (const slot of winners) code = Math.max(code, await cmdEnable(engine, ['enable', slot, ...pin, ...args.filter((a) => a !== '--recommended' && a !== '--yes'), '--yes']));
  return code;
}

async function cmdDisable(engine: BrainEngine, args: string[]): Promise<number> {
  const all = has(args, '--all');
  const slot = args.find((a) => !a.startsWith('--') && a !== 'disable') as DecideSlot | undefined;
  if (!all && (!slot || !(DECIDE_SLOTS as readonly string[]).includes(slot))) { console.error(`Usage: gbrain decide disable <slot>|--all. Slots: ${DECIDE_SLOTS.join(', ')}`); return 1; }
  const slots = all ? [...DECIDE_SLOTS] : [slot!];
  const writes: Array<[string, string]> = slots.map((s) => [`decide.slots.${s}.mode`, 'off']);
  const restored: string[] = [];
  if (slots.includes('rerank')) {
    const owned = await getDecideState(engine, RERANK_OWNERSHIP_KEY);
    if (owned) {
      const { previous, wrote } = JSON.parse(owned) as { previous: { model: string | null; enabled: string | null }; wrote: { model: string; enabled: string } };
      const current = { model: await engine.getConfig('search.reranker.model'), enabled: await engine.getConfig('search.reranker.enabled') };
      // Restore only configuration decide still owns (the operator may have changed it since).
      for (const [field, key] of [['model', 'search.reranker.model'], ['enabled', 'search.reranker.enabled']] as const) {
        if (current[field] !== wrote[field]) continue;
        if (previous[field] === null) await engine.unsetConfig(key);
        else writes.push([key, previous[field]!]);
        restored.push(key);
      }
      await deleteDecideState(engine, RERANK_OWNERSHIP_KEY);
    }
  }
  await writeConfig(engine, writes);
  console.log(`${all ? 'Every slot' : slot} is off.${restored.length ? ` Restored ${restored.join(', ')} to the values before decide enable rerank.` : ''}${all ? ' decide.provider none also stops every slot, S1 shadow and the S9 sweep.' : ''}`);
  return 0;
}

// ---------------------------------------------------------------------------
// dispatch
// ---------------------------------------------------------------------------

export async function runDecideCommand(engine: BrainEngine, args: string[]): Promise<number> {
  const sub = args[0];
  await loadDecideLanes();
  try {
    switch (sub) {
      case 'status': return await cmdStatus(engine, args.slice(1));
      case 'probe': return await cmdProbe(engine, args.slice(1));
      case 'enable': return await cmdEnable(engine, args);
      case 'disable': return await cmdDisable(engine, args);
      case 'calibrate': case 'qualify': case 'calibrations': case 'dataset': {
        const m = await import('./decide/calibrate.ts');
        return await m.runCalibrationSubcommand(engine, sub, args.slice(1));
      }
      case 'receipts': {
        const m = await import('./decide/receipts.ts');
        return await m.runReceiptsCommand(engine, args.slice(1));
      }
      default: {
        const extra = sub ? extraSubcommands.get(sub) : undefined;
        if (extra) return await extra.run(engine, args.slice(1));
        if (sub === 'proposals' || sub === 'sweep') {
          console.error(`gbrain decide ${sub} is not available in this build (its slot is not wired yet). See gbrain decide status.`);
          return 1;
        }
        console.error(decideHelpText());
        return sub ? 1 : 0;
      }
    }
  } finally {
    await flushDecideWrites().catch(() => {});
  }
}