Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.4 KB
Raw Blame
/**
 * v0.36.1.0 (D21) — BaseCyclePhase abstract class for the Hindsight calibration
 * wave. Three new phases (`propose_takes`, `grade_takes`, `calibration_profile`)
 * share enough structure that the duplication-vs-abstraction trade tips toward
 * a shared base. Without this scaffold, each phase reimplements the same five
 * concerns and source-isolation discipline drifts the way it drifted in v0.34.1.
 *
 * What this enforces:
 *   1. Phase signature is uniform: `run(ctx, opts) → PhaseResult`.
 *   2. ctx.sourceId / ctx.auth.allowedSources MUST be threaded — the base class
 *      surfaces a `scope()` helper that wraps `sourceScopeOpts(ctx)` and
 *      forbids the subclass from reading `ctx.engine` directly. Forgetting to
 *      thread source scope becomes a TypeScript compile error, not a runtime
 *      leak. Closes the v0.34.1 source-isolation bug class structurally.
 *   3. Budget meter wraps run() automatically. Subclass declares budgetUsdKey
 *      + budgetUsdDefault; base reads the resolved cap from config and creates
 *      the BudgetMeter. Subclass calls `this.meter.check(...)` before each LLM
 *      submit; budget-exhausted phase still returns `status: 'ok'` (clean
 *      abort) with `details.budget_exhausted: true` so the report shows
 *      partial completion, not failure.
 *   4. Error envelope is uniform. Thrown errors get caught and converted to
 *      `status: 'fail'` with phase-specific `error.code`.
 *   5. Progress reporter integration. Base accepts the reporter via opts;
 *      subclasses call `this.tick(...)` instead of touching the reporter
 *      directly.
 *
 * Synthesize.ts / patterns.ts (existing pre-v0.36 phases) deliberately do NOT
 * retrofit to this base in v0.36.1.0 — too much churn for a refactor that
 * doesn't pay off until v0.37+ when more phases land. Future phases use this
 * by default.
 */

import { BudgetMeter, loadAllowUnpriced, loadPricingOverrides, parseBudgetUsd, type SubmitEstimate, type BudgetCheckResult } from './budget-meter.ts';
import { sourceScopeOpts, type OperationContext } from '../operations.ts';
import type { BrainEngine } from '../engine.ts';
import type { CyclePhase, PhaseResult, PhaseStatus, PhaseError } from '../cycle.ts';
import type { ProgressReporter } from '../progress.ts';

/**
 * Source-scoped read options threaded through every engine call inside a
 * BaseCyclePhase. The base class produces these via `this.scope()`; subclasses
 * receive them as the only sanctioned way to read source-scoped data.
 */
export interface ScopedReadOpts {
  sourceId?: string;
  sourceIds?: string[];
}

export interface BasePhaseOpts {
  /** Optional progress reporter. Phases call tick() / start() through the base. */
  reporter?: ProgressReporter;
  /**
   * Dry-run mode propagated from cycle opts. Honored in run(): the phase is
   * skipped (`status: 'skipped'`, `reason: 'no_dry_run_support'`) before
   * process() is called — every subclass bills LLM calls and INSERTs rows and
   * has no dry-run path of its own (#4823). `ctx.dryRun` is honored too.
   */
  dryRun?: boolean;
  /** Optional explicit budget override in USD. Otherwise base reads config. */
  budgetUsd?: number;
  /** Optional injected BudgetMeter (tests). When set, replaces the default constructed one. */
  meter?: BudgetMeter;
  /**
   * Absolute wall-clock deadline (epoch ms) inherited from the owning job's
   * claim-time `timeout_at` (gbrain#4168). Phases with their own relative
   * deadline (e.g. propose_takes' 30-min cap) clamp it via
   * `effectivePhaseDeadlineMs()` so the clean partial-exit path fires BEFORE
   * the worker's kill switch — without this, a phase default equal to (or,
   * since phases start mid-cycle, always trailing) the job timeout makes the
   * clean exit unreachable and the job dead-letters instead of banking
   * partial work. Null/undefined = no job deadline (interactive CLI runs).
   */
  deadlineAtMs?: number | null;
}

/**
 * Stop-margin reserved under the job deadline when deriving a phase's
 * effective relative deadline. Guarantees the phase's clean exit + result
 * write unwind before the worker's abort fires: wait poll interval (5s) +
 * worker force-evict grace (30s) + lock and DB cleanup headroom. Lives here
 * (not patterns.ts) because every deadline-aware phase consumes it;
 * patterns.ts re-exports for back-compat.
 */
export const CYCLE_DEADLINE_RESERVE_MS = 60 * 1000;

/**
 * Effective relative deadline for a phase: the phase's own default, clamped
 * to the time remaining under the job's absolute deadline minus the reserve.
 * Returns 0 when the job budget is already inside the reserve — callers
 * treat that as "exit cleanly now with deadline_hit", never as unlimited.
 */
export function effectivePhaseDeadlineMs(
  phaseDefaultMs: number,
  deadlineAtMs: number | null | undefined,
  nowMs: number,
): number {
  if (deadlineAtMs == null) return phaseDefaultMs;
  const remaining = deadlineAtMs - CYCLE_DEADLINE_RESERVE_MS - nowMs;
  return Math.max(0, Math.min(phaseDefaultMs, remaining));
}

export abstract class BaseCyclePhase {
  /** Phase name; matches a CyclePhase enum entry in cycle.ts. */
  abstract readonly name: CyclePhase;

  /** Config key for the budget-USD override, e.g. `cycle.propose_takes.budget_usd`. */
  protected abstract readonly budgetUsdKey: string;

  /** Default budget cap in USD if no config override is present. */
  protected abstract readonly budgetUsdDefault: number;

  /**
   * The phase's actual work. Subclass implements this; base wraps it with
   * source-scope enforcement, budget metering, error catching, and progress
   * accounting. `scope` is the only sanctioned way to read source-scoped data.
   */
  protected abstract process(
    engine: BrainEngine,
    scope: ScopedReadOpts,
    ctx: OperationContext,
    opts: BasePhaseOpts,
  ): Promise<{
    summary: string;
    details: Record<string, unknown>;
    status?: PhaseStatus;
  }>;

  /**
   * Optional error-code mapper for thrown errors. Subclass can specialize:
   * a network error from the gateway maps to `LLM_TIMEOUT`, a postgres unique
   * violation maps to `PROPOSAL_CONFLICT`, etc. Default: 'UNKNOWN'.
   */
  protected mapErrorCode(_err: unknown): string {
    return 'UNKNOWN';
  }

  /**
   * Optional error-class mapper. Default 'InternalError' is fine for most;
   * subclass can flag 'LLMError', 'DatabaseConnection' etc.
   */
  protected mapErrorClass(_err: unknown): string {
    return 'InternalError';
  }

  /**
   * Tick the progress reporter for this phase. Subclass calls this instead of
   * reaching for opts.reporter directly so the phase name is always correct.
   */
  protected tick(opts: BasePhaseOpts, message?: string, delta = 1): void {
    if (!opts.reporter) return;
    opts.reporter.tick(delta, message);
  }

  /**
   * Check the budget for a planned LLM submit. Subclass calls this before
   * every gateway.chat() / gateway.embed() / etc. submission. When the result
   * has allowed=false the subclass MUST abort the planned submit and continue
   * with what it's already accumulated (clean partial-completion path).
   */
  protected checkBudget(estimate: SubmitEstimate): BudgetCheckResult {
    if (!this.meter) {
      // Tests that don't inject a meter get an unbounded fall-through. The
      // real path always constructs one in run().
      return {
        allowed: true,
        estimatedCostUsd: 0,
        cumulativeCostUsd: 0,
        budgetUsd: 0,
      };
    }
    return this.meter.check(estimate);
  }

  /**
   * BudgetMeter instance for this run. Set by run() (or injected via opts.meter
   * for tests). Subclass accesses it via checkBudget() rather than directly.
   */
  protected meter?: BudgetMeter;

  /**
   * Resolve the budget cap from config (or default). Override is the explicit
   * value passed via opts.budgetUsd. Otherwise: config[budgetUsdKey] → default.
   */
  private resolveBudgetUsd(ctx: OperationContext, opts: BasePhaseOpts): number {
    if (typeof opts.budgetUsd === 'number') return opts.budgetUsd;
    const raw = (ctx.config as unknown as Record<string, unknown>)[this.budgetUsdKey];
    return parseBudgetUsd(typeof raw === 'number' || typeof raw === 'string' ? raw : undefined, this.budgetUsdDefault);
  }

  /**
   * Public entry point. Wraps the subclass's process() with all the cross-cutting
   * concerns. Returns a PhaseResult ready to slot into CycleReport.phases.
   */
  async run(ctx: OperationContext, opts: BasePhaseOpts = {}): Promise<PhaseResult> {
    const t0 = Date.now();

    // Source-scope discipline — required by every base-phase subclass. Forgetting
    // to thread this would have been the v0.34.1 leak class. Now structural.
    const scope = sourceScopeOpts(ctx);

    // `--dry-run` promises "preview without writing". No subclass has a
    // dry-run path (LLM calls + INSERT take_proposals / take_grade_cache /
    // calibration_profiles), so skip here — one guard for all three, the same
    // shape extract / resolve_symbol_edges use (#4823). Read both channels so
    // a caller that forgets to thread opts.dryRun still can't bill.
    if (opts.dryRun || ctx.dryRun === true) {
      return {
        phase: this.name,
        status: 'skipped',
        duration_ms: Date.now() - t0,
        summary: `dry-run: ${this.name} skipped (LLM calls + DB writes)`,
        details: { dryRun: true, reason: 'no_dry_run_support' },
      };
    }

    // Budget meter construction. The default path reads config; tests inject.
    if (!opts.meter) {
      const budgetUsd = this.resolveBudgetUsd(ctx, opts);
      this.meter = new BudgetMeter({
        budgetUsd,
        phase: this.name,
        allowUnpriced: await loadAllowUnpriced(ctx.engine),
        pricingOverrides: await loadPricingOverrides(ctx.engine),
      });
    } else {
      this.meter = opts.meter;
    }

    try {
      const out = await this.process(ctx.engine, scope, ctx, opts);
      return {
        phase: this.name,
        status: out.status ?? 'ok',
        duration_ms: Date.now() - t0,
        summary: out.summary,
        details: out.details,
      };
    } catch (err) {
      const code = this.mapErrorCode(err);
      const errClass = this.mapErrorClass(err);
      const message = err instanceof Error ? err.message : String(err);
      const phaseError: PhaseError = {
        class: errClass,
        code,
        message,
      };
      return {
        phase: this.name,
        status: 'fail',
        duration_ms: Date.now() - t0,
        summary: `${this.name} failed: ${message}`,
        details: { error_code: code },
        error: phaseError,
      };
    }
  }
}