Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.6 KB
Raw Blame
/**
 * #2411 / #4102 — drain surface for the `take_proposals` queue.
 *
 * The propose_takes cycle phase (src/core/cycle/propose-takes.ts) WRITES
 * proposals; the D17 auto-resolve posture says the ONLY path from queue to
 * canonical fence is explicit operator accept. This module is that path:
 *
 *   - listPendingProposals — source-scoped pending queue (newest first).
 *   - acceptProposal       — promote via a coordinated `takes_add` mutation
 *                            (submitPageMutation, the same path `gbrain
 *                            takes add` uses), then stamp status='accepted' +
 *                            promoted_row_num + acted_at/acted_by.
 *   - rejectProposal       — stamp status='rejected' + acted_at/acted_by.
 *
 * All reads/writes are parameterized and scoped to the caller's source when
 * one is provided (the CLI always resolves one via resolveSourceId).
 *
 * The promote write goes through submitPageMutation (the SAME coordinated
 * pipeline `takes add`/`takes update`/`takes supersede`/`takes resolve` use),
 * not the uncoordinated addTakeToPage — a managed brain (persistence_brain
 * enabled: Postgres/Supabase with a coordinator-owned worktree) refuses any
 * direct file write outside that pipeline with 'writer_coordinator_required'
 * ("This file belongs to a managed canonical worktree."). Calling
 * addTakeToPage directly here made every `takes propose --accept` fail on a
 * managed brain — including the Slack report-lane's accept-before-correct
 * step, so a corrective reply on a pending proposal could never land.
 */

import { createHash } from 'node:crypto';
import type { BrainEngine, TakeKind } from './engine.ts';
import type { GBrainConfig } from './config.ts';
import type { OperationContext } from './ops/contract.ts';
import { submitPageMutation } from './persistence/page-mutations.ts';
import { waitForWrite } from './persistence/service.ts';
import type { WriteRequest } from './persistence/model.ts';

export interface TakeProposalRow {
  id: number;
  source_id: string;
  page_slug: string;
  claim_text: string;
  kind: string;
  holder: string;
  weight: number;
  domain: string | null;
  status: string;
  proposed_at: string | Date;
  model_id: string;
  promoted_row_num: number | null;
}

/** Normalize Postgres driver values to the public numeric row contract. */
function normalizeTakeProposalRow(row: TakeProposalRow): TakeProposalRow {
  return {
    ...row,
    id: Number(row.id),
    weight: Number(row.weight),
    promoted_row_num: row.promoted_row_num == null ? null : Number(row.promoted_row_num),
  };
}

export type TakeProposalErrorCode = 'not_found' | 'not_pending';

export class TakeProposalError extends Error {
  constructor(
    public readonly code: TakeProposalErrorCode,
    message: string,
  ) {
    super(message);
    this.name = 'TakeProposalError';
  }
}

/**
 * The producer (parseExtractorOutput) only ever writes the four canonical
 * kinds, but the column is free TEXT — coerce defensively so a legacy or
 * hand-inserted row can't crash the promote path. 'prediction' (the raw
 * extractor-prompt enum) maps to 'bet'; anything else unknown maps to 'take'.
 */
export function coerceProposalKind(raw: string): TakeKind {
  if (raw === 'fact' || raw === 'take' || raw === 'bet' || raw === 'hunch') return raw;
  if (raw === 'prediction') return 'bet';
  return 'take';
}

const PROPOSAL_COLUMNS =
  'id, source_id, page_slug, claim_text, kind, holder, weight, domain, status, proposed_at, model_id, promoted_row_num';

export interface ListPendingOpts {
  /** Scope to one source (the CLI always provides one). Omit = all sources (trusted local only). */
  sourceId?: string;
  limit?: number;
}

/** Pending proposals, newest first. Tombstones never surface (status='rejected'). */
export async function listPendingProposals(
  engine: BrainEngine,
  opts: ListPendingOpts = {},
): Promise<TakeProposalRow[]> {
  const limit = Math.max(1, Math.min(500, opts.limit ?? 20));
  const where = [`status = 'pending'`];
  const params: unknown[] = [];
  if (opts.sourceId) {
    params.push(opts.sourceId);
    where.push(`source_id = $${params.length}`);
  }
  params.push(limit);
  const rows = await engine.executeRaw<TakeProposalRow>(
    `SELECT ${PROPOSAL_COLUMNS}
       FROM take_proposals
      WHERE ${where.join(' AND ')}
      ORDER BY proposed_at DESC, id DESC
      LIMIT $${params.length}`,
    params,
  );
  return rows.map(normalizeTakeProposalRow);
}

async function loadProposal(
  engine: BrainEngine,
  id: number,
  sourceId?: string,
  opts: { allowStranded?: boolean } = {},
): Promise<TakeProposalRow> {
  const params: unknown[] = [id];
  let scope = '';
  if (sourceId) {
    params.push(sourceId);
    scope = ` AND source_id = $${params.length}`;
  }
  const rows = await engine.executeRaw<TakeProposalRow>(
    `SELECT ${PROPOSAL_COLUMNS} FROM take_proposals WHERE id = $1${scope}`,
    params,
  );
  if (rows.length === 0) {
    throw new TakeProposalError('not_found', `No take proposal #${id}${sourceId ? ` in source '${sourceId}'` : ''}.`);
  }
  const row = normalizeTakeProposalRow(rows[0]);
  if (row.status !== 'pending') {
    // wave-g (#4480 follow-up): a crash between the accept CAS and the fence
    // write (or a failed rollback) strands the row as status='accepted' with
    // no promoted take — invisible in the pending list, so surface the
    // repairable shape exactly where a human retry lands.
    if (row.status === 'accepted' && row.promoted_row_num == null) {
      if (opts.allowStranded) return row;
      throw new TakeProposalError(
        'not_pending',
        `Proposal #${id} is claimed 'accepted' but its take is not recorded yet (its write is pending, or a crash stopped it). ` +
        `Re-run \`gbrain takes propose --accept ${id}\` to finish it; it resumes the same write and never adds a second take.`,
      );
    }
    throw new TakeProposalError(
      'not_pending',
      `Proposal #${id} is already '${row.status}' (acted on) — only pending proposals can be accepted or rejected.`,
    );
  }
  return row;
}

export interface ProposalActionTarget {
  engine: BrainEngine;
  /** Not read: the takes_add mutation accept submits resolves its write root from the proposal's source (#7271). */
  brainDir?: string;
  /** Source scope: a proposal outside this source reads as not_found. */
  sourceId?: string;
  /** Recorded in acted_by. Defaults to 'cli'. */
  actedBy?: string;
  /** Threaded into the coordinated takes_add mutation accept performs. */
  config: GBrainConfig;
  /** An explicit `--dir`: validated against the source's canonical root, as `takes add --dir` is. */
  localDir?: string;
}

/** #5214: reviewer edits applied over the proposal at accept; the queue row keeps the original text. */
export interface ProposalEdits { claim?: string; weight?: number; holder?: string; kind?: string }

/**
 * One write request per claim: derived from the proposal id and the claim's
 * acted_at, so resuming a claimed-but-unrecorded accept replays the same
 * durable request (a pending or committed takes_add is never admitted twice),
 * while a fresh claim after a released failure gets a new request.
 */
const SETTLED_WITHOUT_COMMIT = new Set(['failed', 'cancelled', 'conflict']);

async function claimRequestStates(engine: BrainEngine, requestId: string): Promise<WriteRequest[]> {
  return engine.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE request_id = $1::uuid', [requestId]);
}

/** A claim younger than this may belong to an accept that is still submitting its write. */
const RESUME_GRACE_MS = 2 * 60_000;

function claimRequestId(id: number, actedAt: string): string {
  const h = createHash('sha256').update(`take-proposal-accept:${id}:${actedAt}`).digest('hex');
  return `${h.slice(0, 8)}-${h.slice(8, 12)}-8${h.slice(13, 16)}-${((parseInt(h[16]!, 16) & 0x3) | 0x8).toString(16)}${h.slice(17, 20)}-${h.slice(20, 32)}`;
}

/**
 * Promotes an accepted proposal into the page's fence via the SAME
 * coordinated `takes_add` mutation `gbrain takes add` uses — never the
 * uncoordinated addTakeToPage — so a managed brain's writer-coordinator
 * guard (assertManagedFilesystemWrite) sees this write the same way it sees
 * every other takes mutation, instead of refusing it as an uncoordinated
 * legacy writer.
 *
 * The mutation resolves its own write root from the proposal's source
 * (source.local_path / sync.repo_path), as `gbrain takes add <slug>` does; an
 * explicit `--dir` rides along as `local_dir`, which the coordinator refuses
 * unless it is that canonical root.
 */
async function promoteProposalViaTakesAdd(
  target: ProposalActionTarget,
  proposal: TakeProposalRow,
  requestId: string,
  edits: ProposalEdits,
): Promise<number> {
  const ctx: OperationContext = {
    engine: target.engine,
    config: target.config,
    remote: false,
    sourceId: proposal.source_id,
    dryRun: false,
    logger: { info: message => console.error(message), warn: message => console.error(message), error: message => console.error(message) },
  };
  const edited = Object.values(edits).some(value => value !== undefined);
  const params: Record<string, unknown> = {
    slug: proposal.page_slug,
    claim: edits.claim ?? proposal.claim_text,
    kind: edits.kind ?? coerceProposalKind(proposal.kind),
    holder: edits.holder ?? proposal.holder,
    weight: edits.weight ?? (typeof proposal.weight === 'number' ? proposal.weight : Number(proposal.weight)),
    source: `take_proposals#${proposal.id}${edited ? ' (edited)' : ''}`,
    source_id: proposal.source_id,
    request_id: requestId,
    ...(target.localDir !== undefined ? { local_dir: target.localDir } : {}),
  };
  const result = await submitPageMutation(ctx, { operation: 'takes_add', params });
  return Number(result.row_num);
}

/**
 * Promote a pending proposal into the page's takes fence.
 *
 * #4480 (TOCTOU): the row is CLAIMED FIRST via a CAS
 * (`status='pending' → 'accepted'` with the rowcount CHECKED), and only the
 * claim winner performs the fence write. The old order (fence write first,
 * status flip after, rowcount ignored) let two concurrent accepts both pass
 * the pending check and both append the take to the .md — the loser's no-op
 * UPDATE reported success anyway. If the fence write fails after a
 * successful claim, the claim is rolled back (best-effort compensation) so
 * a retry can act on the row.
 */
export async function acceptProposal(
  target: ProposalActionTarget,
  id: number,
  edits: ProposalEdits = {},
): Promise<{ proposal: TakeProposalRow; rowNum: number }> {
  const { engine } = target;
  const proposal = await loadProposal(engine, id, target.sourceId, { allowStranded: true });
  // Claim-first CAS: exactly one caller wins the pending row. A claim that is
  // already held without a recorded take resumes under its own request id.
  const claimed = proposal.status === 'accepted'
    ? await engine.executeRaw<{ id: number; acted_at: unknown }>(
      `SELECT id, acted_at FROM take_proposals WHERE id = $1 AND status = 'accepted' AND promoted_row_num IS NULL`, [id])
    : await engine.executeRaw<{ id: number; acted_at: unknown }>(
      `UPDATE take_proposals
          SET status = 'accepted', acted_at = now(), acted_by = $2
        WHERE id = $1 AND status = 'pending'
        RETURNING id, acted_at`,
      [id, target.actedBy ?? 'cli'],
    );
  if (claimed.length === 0) {
    throw new TakeProposalError(
      'not_pending',
      `Proposal #${id} was acted on concurrently — only one accept/reject can win a pending row.`,
    );
  }
  const claimedAt = claimed[0]!.acted_at == null ? null : new Date(claimed[0]!.acted_at as string | Date).toISOString();
  const actedAt = claimedAt ?? 'unclaimed';
  const requestId = claimRequestId(id, actedAt);
  // The claim's durable request may already exist, under this or another
  // local writer (the journal keys requests per principal). Settle from it
  // instead of submitting a second takes_add.
  let prior = await claimRequestStates(engine, requestId);
  const inFlight = prior.find(r => r.state !== 'committed' && !SETTLED_WITHOUT_COMMIT.has(r.state));
  if (inFlight) {
    // Drive the existing request through this host's persistence owner (a
    // standalone CLI has none running) instead of submitting another.
    await waitForWrite(engine, inFlight, target.config).catch(() => undefined);
    prior = await claimRequestStates(engine, requestId);
  } else if (prior.length === 0 && proposal.status === 'accepted' && claimedAt && Date.now() - Date.parse(claimedAt) < RESUME_GRACE_MS) {
    throw new TakeProposalError('not_pending', `Proposal #${id} was just claimed by another accept that may still be submitting its take. Re-run \`gbrain takes propose --accept ${id}\` in a few minutes.`);
  }
  const committed = prior.find(r => r.state === 'committed');
  let rowNum: number;
  if (committed) {
    rowNum = Number((committed.outcome as { row_num?: unknown } | null)?.row_num);
    if (!Number.isSafeInteger(rowNum) || rowNum < 1) {
      throw new TakeProposalError('not_pending', `Proposal #${id}'s take was written (request ${requestId}) but its receipt no longer names the row; check the page's takes and record it by hand.`);
    }
  } else if (prior.some(r => !SETTLED_WITHOUT_COMMIT.has(r.state))) {
    throw new TakeProposalError('not_pending', `Proposal #${id}'s take is still being written (request ${requestId}). Re-run \`gbrain takes propose --accept ${id}\` once it settles.`);
  } else {
    try {
      // The row's OWN source, never the caller's, is what promoteProposalViaTakesAdd
      // scopes the mutation to — the scoped load above already proved they agree
      // when a caller scope was provided.
      rowNum = await promoteProposalViaTakesAdd(target, proposal, requestId, edits);
    } catch (e) {
      // Release the claim only when its write provably cannot commit: no
      // durable request was admitted, or every one settled without committing.
      // A pending, replay-conflicting or committed request keeps the claim, so
      // neither a reject nor a second accept can race it; re-running accept
      // settles from it. Compensation is bound to this exact, unpromoted claim.
      const after = await claimRequestStates(engine, requestId);
      if (after.every(r => SETTLED_WITHOUT_COMMIT.has(r.state))) {
        try {
          await engine.executeRaw(
            `UPDATE take_proposals
                SET status = 'pending', acted_at = NULL, acted_by = NULL, promoted_row_num = NULL
              WHERE id = $1 AND status = 'accepted' AND promoted_row_num IS NULL
                AND date_trunc('milliseconds', acted_at) IS NOT DISTINCT FROM $2::timestamptz`,
            [id, claimedAt],
          );
        } catch { /* compensation is best-effort */ }
      }
      throw e;
    }
  }
  await engine.executeRaw(
    `UPDATE take_proposals SET promoted_row_num = $2 WHERE id = $1`,
    [id, rowNum],
  );
  return { proposal, rowNum };
}

/** Mark a pending proposal rejected. No markdown write. #4480: rowcount is
 * CHECKED — a reject that loses a race (row already accepted/rejected) now
 * reports the truth instead of claiming a rejection it never performed. */
export async function rejectProposal(
  target: Pick<ProposalActionTarget, 'engine' | 'sourceId' | 'actedBy'>,
  id: number,
): Promise<TakeProposalRow> {
  const { engine } = target;
  const proposal = await loadProposal(engine, id, target.sourceId);
  const rejected = await engine.executeRaw<{ id: number }>(
    `UPDATE take_proposals
        SET status = 'rejected', acted_at = now(), acted_by = $2
      WHERE id = $1 AND status = 'pending'
      RETURNING id`,
    [id, target.actedBy ?? 'cli'],
  );
  if (rejected.length === 0) {
    throw new TakeProposalError(
      'not_pending',
      `Proposal #${id} was acted on concurrently — only one accept/reject can win a pending row.`,
    );
  }
  return proposal;
}