Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.1 KB
Raw Blame
/**
 * Trust decisions (#5575: ENG-4, A5/I3, CEO-12): the typed `trust_proposals`
 * record and its checked handlers. A proposal links the row a decision would
 * change (`target`) to the row that caused it (`related`): the lower-tier fact
 * that would supersede a higher-tier one, the higher-tier fact a remote caller
 * asked to forget, the page an agent edit lowered. `before_state` holds the
 * exact state the accept path re-checks under lock (tiers, ids, revisions).
 *
 * Storage goes through `engine.executeRaw` (the proposals-store.ts pattern).
 * decide_proposals gets no rows from here; CLI refs are `tp<id>`. Proposals
 * are inserted inside the publication transaction that created them, so the
 * proposer is read from that transaction's attribution settings.
 *
 * Accept/reject/undo dispatch to one handler per action, registered by the
 * module that owns the write path (trust/supersede-handlers.ts for facts,
 * takes and forget; the owner-ops module for lower_page). Every handler runs
 * only after the caller established the owner's confirmation (CEO-9,
 * trust/confirm.ts); handlers re-check `before_state` under lock and refuse
 * stale proposals instead of applying them.
 */
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import type { Principal } from '../persistence/model.ts';
import type { OwnerConfirmation } from './confirm.ts';
import type { TrustTable } from './schema.ts';
import { TRUST_PROPOSAL_ACTIONS, TRUST_PROPOSAL_STATUSES } from './schema.ts';
import { noteBelief } from '../belief/ledger.ts';

export type TrustProposalAction = typeof TRUST_PROPOSAL_ACTIONS[number];
export type TrustProposalStatus = typeof TRUST_PROPOSAL_STATUSES[number];
export type TrustDecision = 'accept' | 'reject' | 'undo';

export interface TrustProposalRow {
  id: number;
  action: TrustProposalAction;
  source_id: string;
  target_table: TrustTable;
  target_id: number;
  related_table: TrustTable | null;
  related_id: number | null;
  before_state: Record<string, unknown>;
  after_state: Record<string, unknown>;
  proposer: string;
  proposer_principal_kind: string | null;
  proposer_principal_id: string | null;
  write_request_id: string | null;
  status: TrustProposalStatus;
  decided_at: string | null;
  decided_principal_kind: string | null;
  decided_principal_id: string | null;
  created_at: string;
  updated_at: string;
}

/** The typed CLI ref of a trust proposal. */
export const trustProposalRef = (id: number | string): string => `tp${id}`;

/** GST-2897 B: the guard of a member's share about another member, held private on a confirm proposal for the brain owner. */
export const SHARE_HELD_GUARD = 'remember.share_held';
/** `tp<id>` (or a bare id) to the proposal id; null when the ref names something else. */
export function parseTrustProposalRef(ref: string): number | null {
  const m = /^(?:tp)?(\d{1,18})$/.exec(ref.trim());
  return m ? Number(m[1]) : null;
}

const json = (value: unknown): Record<string, unknown> => {
  if (value && typeof value === 'object') return value as Record<string, unknown>;
  if (typeof value === 'string') { try { return JSON.parse(value) as Record<string, unknown>; } catch { return {}; } }
  return {};
};
const iso = (value: unknown): string | null => value === null || value === undefined ? null : new Date(value as string).toISOString();
function normalize(r: Record<string, unknown>): TrustProposalRow {
  return {
    id: Number(r.id), action: r.action as TrustProposalAction, source_id: String(r.source_id),
    target_table: r.target_table as TrustTable, target_id: Number(r.target_id),
    related_table: (r.related_table as TrustTable | null) ?? null, related_id: r.related_id === null || r.related_id === undefined ? null : Number(r.related_id),
    before_state: json(r.before_state), after_state: json(r.after_state), proposer: String(r.proposer),
    proposer_principal_kind: (r.proposer_principal_kind as string | null) ?? null, proposer_principal_id: (r.proposer_principal_id as string | null) ?? null,
    write_request_id: (r.write_request_id as string | null) ?? null, status: r.status as TrustProposalStatus,
    decided_at: iso(r.decided_at), decided_principal_kind: (r.decided_principal_kind as string | null) ?? null,
    decided_principal_id: (r.decided_principal_id as string | null) ?? null,
    created_at: iso(r.created_at)!, updated_at: iso(r.updated_at)!,
  };
}

export interface NewTrustProposal {
  action: TrustProposalAction;
  sourceId: string;
  target: { table: TrustTable; id: number };
  related?: { table: TrustTable; id: number } | null;
  before: Record<string, unknown>;
  after?: Record<string, unknown>;
  /** Short name of the guard that raised it, e.g. `remember.replaces`, `fence_projection`, `remote_forget`, `agent_page_edit`. */
  proposer: string;
}

/**
 * Inserts a pending proposal inside the caller's transaction, or returns the
 * pending one already recorded for the same (action, target, related): a
 * retried write or a second agent edit of one page reuses one queue item
 * (ENG-22). The proposer principal and request come from the transaction's
 * attribution settings.
 */
export async function insertTrustProposal(tx: BrainEngine, input: NewTrustProposal): Promise<{ id: number; created: boolean }> {
  const params = [input.action, input.sourceId, input.target.table, input.target.id, input.related?.table ?? null, input.related?.id ?? null,
    JSON.stringify(input.before), JSON.stringify(input.after ?? {}), input.proposer];
  const [inserted] = await tx.executeRaw<{ id: number }>(
    `INSERT INTO trust_proposals (action, source_id, target_table, target_id, related_table, related_id, before_state, after_state, proposer,
        proposer_principal_kind, proposer_principal_id, write_request_id)
      VALUES ($1, $2, $3, $4, $5, $6, $7::text::jsonb, $8::text::jsonb, $9,
        NULLIF(current_setting('gbrain.write_principal_kind', true), ''), NULLIF(current_setting('gbrain.write_principal_id', true), ''),
        NULLIF(current_setting('gbrain.write_request', true), '')::uuid)
      ON CONFLICT DO NOTHING RETURNING id`, params);
  if (inserted) {
    noteBelief({ kind: 'contested', table: input.target.table, rowId: input.target.id, proposalId: Number(inserted.id), guard: input.proposer });
    return { id: Number(inserted.id), created: true };
  }
  const [existing] = await tx.executeRaw<{ id: number }>(
    `SELECT id FROM trust_proposals WHERE status = 'pending' AND action = $1 AND target_table = $2 AND target_id = $3
       AND related_table IS NOT DISTINCT FROM $4 AND related_id IS NOT DISTINCT FROM $5 ORDER BY id LIMIT 1`,
    [input.action, input.target.table, input.target.id, input.related?.table ?? null, input.related?.id ?? null]);
  if (!existing) throw new Error('trust proposal insert conflicted but no pending row was found');
  noteBelief({ kind: 'contested', table: input.target.table, rowId: input.target.id, proposalId: Number(existing.id), guard: input.proposer });
  return { id: Number(existing.id), created: false };
}

export async function getTrustProposal(engine: BrainEngine, id: number, lock = false): Promise<TrustProposalRow | null> {
  const [row] = await engine.executeRaw<Record<string, unknown>>(`SELECT * FROM trust_proposals WHERE id = $1${lock ? ' FOR UPDATE' : ''}`, [id]);
  return row ? normalize(row) : null;
}

export interface TrustProposalFilter {
  status?: TrustProposalStatus | 'all';
  sourceId?: string;
  action?: TrustProposalAction;
  since?: Date;
  limit?: number;
}

export async function listTrustProposals(engine: BrainEngine, filter: TrustProposalFilter = {}): Promise<TrustProposalRow[]> {
  const status = filter.status ?? 'pending';
  const rows = await engine.executeRaw<Record<string, unknown>>(
    `SELECT * FROM trust_proposals
      WHERE ($1::text = 'all' OR status = $1) AND ($2::text IS NULL OR source_id = $2) AND ($3::text IS NULL OR action = $3)
        AND ($4::timestamptz IS NULL OR created_at >= $4)
      ORDER BY created_at, id LIMIT $5`,
    [status, filter.sourceId ?? null, filter.action ?? null, filter.since?.toISOString() ?? null, Math.min(Math.max(filter.limit ?? 500, 1), 5000)]);
  return rows.map(normalize);
}

/** Pending proposals naming a row as target or related (guards and explain read this). */
export async function pendingTrustProposalsFor(engine: BrainEngine, table: TrustTable, id: number): Promise<TrustProposalRow[]> {
  const rows = await engine.executeRaw<Record<string, unknown>>(
    `SELECT * FROM trust_proposals WHERE status = 'pending'
       AND ((target_table = $1 AND target_id = $2) OR (related_table = $1 AND related_id = $2)) ORDER BY id`, [table, id]);
  return rows.map(normalize);
}

/** Refreshes a pending proposal's after state (a later write folded into the same queue item). */
export async function updatePendingTrustProposalAfter(tx: BrainEngine, id: number, after: Record<string, unknown>): Promise<void> {
  await tx.executeRaw(`UPDATE trust_proposals SET after_state = $2::text::jsonb, updated_at = now() WHERE id = $1 AND status = 'pending'`, [id, JSON.stringify(after)]);
}

/** Compare-and-set on status; records the decider and an after state. False when the proposal was not in `from`. */
export async function transitionTrustProposal(tx: BrainEngine, id: number, from: TrustProposalStatus, to: TrustProposalStatus,
  opts: { after?: Record<string, unknown>; decidedBy?: Principal | null } = {}): Promise<boolean> {
  const rows = await tx.executeRaw<{ id: number }>(
    `UPDATE trust_proposals SET status = $3, updated_at = now(),
        after_state = CASE WHEN $4::text IS NULL THEN after_state ELSE $4::text::jsonb END,
        decided_at = CASE WHEN $3 IN ('accepted', 'rejected', 'undone') THEN now() ELSE decided_at END,
        decided_principal_kind = COALESCE($5, decided_principal_kind), decided_principal_id = COALESCE($6, decided_principal_id)
      WHERE id = $1 AND status = $2 RETURNING id`,
    [id, from, to, opts.after ? JSON.stringify(opts.after) : null, opts.decidedBy?.kind ?? null, opts.decidedBy?.id ?? null]);
  return rows.length === 1;
}

// ---------------------------------------------------------------------------
// Checked handlers
// ---------------------------------------------------------------------------

export interface TrustDecisionResult {
  id: number;
  ref: string;
  action: TrustProposalAction;
  decision: TrustDecision;
  status: TrustProposalStatus | 'refused' | 'not_found' | 'stale';
  reason?: string;
  detail?: Record<string, unknown>;
}

export interface TrustDecisionContext {
  config?: GBrainConfig;
  /** How the owner confirmed (trust/confirm.ts requireOwnerConfirmation); required for accept and undo. */
  confirmation: OwnerConfirmation;
  /** The owner principal recorded as the decider. */
  decidedBy?: Principal | null;
}

export interface TrustProposalHandler {
  accept(engine: BrainEngine, proposal: TrustProposalRow, ctx: TrustDecisionContext): Promise<TrustDecisionResult>;
  reject?(engine: BrainEngine, proposal: TrustProposalRow, ctx: TrustDecisionContext): Promise<TrustDecisionResult>;
  undo?(engine: BrainEngine, proposal: TrustProposalRow, ctx: TrustDecisionContext): Promise<TrustDecisionResult>;
}

const handlers = new Map<TrustProposalAction, TrustProposalHandler>();
/** Registers the handler for an action; returns the call that puts the previous registration back (a test stub must restore it: the registry is process-global). */
export function registerTrustProposalHandler(action: TrustProposalAction, handler: TrustProposalHandler): () => void {
  const previous = handlers.get(action);
  handlers.set(action, handler);
  return () => { if (previous) handlers.set(action, previous); else handlers.delete(action); };
}

/**
 * Load every module that registers a proposal handler and return the actions
 * now registered. The registering modules import this one, so they cannot be
 * static imports here; loading them at the read point keeps a decision from
 * depending on which modules the calling command happened to load first.
 */
export async function ensureTrustProposalHandlers(): Promise<TrustProposalAction[]> {
  await Promise.all([import('./page-handlers.ts'), import('./supersede-handlers.ts')]);
  return [...handlers.keys()];
}

export function decisionResult(proposal: Pick<TrustProposalRow, 'id' | 'action'>, decision: TrustDecision,
  status: TrustDecisionResult['status'], extra: { reason?: string; detail?: Record<string, unknown> } = {}): TrustDecisionResult {
  return { id: proposal.id, ref: trustProposalRef(proposal.id), action: proposal.action, decision, status, ...extra };
}

/** The default reject: the proposal closes and nothing else changes. */
async function rejectOnly(engine: BrainEngine, proposal: TrustProposalRow, ctx: TrustDecisionContext): Promise<TrustDecisionResult> {
  return await transitionTrustProposal(engine, proposal.id, 'pending', 'rejected', { decidedBy: ctx.decidedBy })
    ? decisionResult(proposal, 'reject', 'rejected')
    : decisionResult(proposal, 'reject', 'refused', { reason: (await getTrustProposal(engine, proposal.id))?.status ?? 'not_found' });
}

/**
 * Applies one owner decision. The caller has already established the owner's
 * confirmation for this exact proposal (CEO-9); the handler re-checks the
 * recorded state under lock. Unknown ids and wrong states are reported, not thrown.
 */
export async function decideTrustProposal(engine: BrainEngine, id: number, decision: TrustDecision, ctx: TrustDecisionContext): Promise<TrustDecisionResult> {
  const proposal = await getTrustProposal(engine, id);
  if (!proposal) return { id, ref: trustProposalRef(id), action: 'confirm', decision, status: 'not_found' };
  const want = decision === 'undo' ? 'accepted' : 'pending';
  if (proposal.status !== want) return decisionResult(proposal, decision, 'refused', { reason: proposal.status });
  await ensureTrustProposalHandlers();
  const handler = handlers.get(proposal.action);
  if (decision === 'reject') return (handler?.reject ?? rejectOnly)(engine, proposal, ctx);
  if (!handler) return decisionResult(proposal, decision, 'refused', { reason: 'no_handler' });
  if (decision === 'undo') return handler.undo ? handler.undo(engine, proposal, ctx) : decisionResult(proposal, decision, 'refused', { reason: 'undo_unsupported' });
  return handler.accept(engine, proposal, ctx);
}