Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.4 KB
Raw Blame
// Life Chronicle (#5876): the one reason table for automatic event extraction, and the
// `chronicle_backstop` write-receipt field built from it. Docs (docs/guides/life-chronicle.md)
// and tests render from CHRONICLE_REASONS; nothing else spells these codes out.
import { pricingSetCommand } from '../budget/no-pricing.ts';
import type { Action, Actor } from '../agent-output.ts';

/**
 * Where a code is decided: `decision` when
 * the page is written (receipt), `discovery` when the phase finds the page, `execution` when it judges
 * the page, `phase` for a whole run.
 */
export type ChronicleStage = 'decision' | 'discovery' | 'execution' | 'phase';

export interface ChronicleReasonContext {
  /** Omitted on brain-wide surfaces (doctor, advisor): the pointer then covers every source. */
  sourceId?: string;
  /** The day to scope a backfill pointer to (YYYY-MM-DD, compared with the page's updated date). */
  since: string;
  /** Configured chat model, for the pricing registration command. */
  model?: string;
  dailyLimit?: number;
  recentDays?: number;
}

interface ChronicleReason {
  stage: ChronicleStage;
  meaning: (ctx: ChronicleReasonContext) => string;
  fix?: (ctx: ChronicleReasonContext) => Action;
}

/**
 * The backfill pointer every surface emits. The paid form carries `--yes` (chronicle-backfill's
 * consent flag): it is the command to run after the user agrees, never before.
 */
export function chronicleBackfillArgv(opts: { sourceId?: string; since: string; limit?: number; dryRun: boolean }): string[] {
  return ['gbrain', 'chronicle-backfill', ...(opts.sourceId ? ['--source', opts.sourceId] : []),
    '--since', opts.since, '--limit', String(opts.limit ?? 50), opts.dryRun ? '--dry-run' : '--yes'];
}

/** The run-now pointer: the chronicle phase in the foreground (paid). */
export const CHRONICLE_RUN_NOW_ARGV = ['gbrain', 'dream', '--phase', 'chronicle'] as const;

const backfill = (actor: Actor, why: string) => (ctx: ChronicleReasonContext): Action => ({
  argv: chronicleBackfillArgv({ sourceId: ctx.sourceId, since: ctx.since, dryRun: false }),
  preview_argv: chronicleBackfillArgv({ sourceId: ctx.sourceId, since: ctx.since, dryRun: true }),
  consent: ['paid'], actor, why, requires_exclusive: false,
});

const FIX_BY_BACKFILL = 'Preview with the dry run, then backfill these pages if the user agrees to one paid chat call per page.';
const FIX_ON_HOST = 'Only the brain host operator can extract these pages: preview and backfill on the brain host if the user agrees to the cost.';

export const CHRONICLE_REASONS = {
  auto_chronicle_off: { stage: 'decision',
    meaning: () => 'Automatic event extraction is off on this brain by choice (`gbrain config set auto_chronicle false`).' },
  auto_chronicle_invalid: { stage: 'decision',
    meaning: () => 'auto_chronicle holds a value that is neither true nor false, so it reads as off.',
    fix: () => ({ argv: ['gbrain', 'config', 'set', 'auto_chronicle', 'true'], consent: ['paid'], actor: 'agent',
      why: 'Ask the user whether automatic extraction should be on (one paid chat call per eligible page) or off (`gbrain config set auto_chronicle false`).',
      requires_exclusive: false }) },
  slug_bound_client: { stage: 'decision',
    meaning: () => 'The writer is confined (slug-bound, delegated or namespace-restricted), so its writes never trigger extraction into life/events/.',
    fix: backfill('host_admin', FIX_ON_HOST) },
  operation_bound_client: { stage: 'decision',
    meaning: () => 'The writer\'s grant lists operations without extract_facts, the permission that covers derived extraction.',
    fix: backfill('host_admin', FIX_ON_HOST) },
  no_extract: { stage: 'decision',
    meaning: () => 'The sync ran with extraction turned off (--no-extract, or a remote sync, which never extracts).',
    fix: backfill('agent', FIX_BY_BACKFILL) },
  history: { stage: 'decision',
    meaning: (ctx) => `The page's own date is more than ${ctx.recentDays ?? 30} days old (chronicle.auto_recent_days); history is extracted only on request.`,
    fix: backfill('agent', FIX_BY_BACKFILL) },
  not_yet_happened: { stage: 'decision',
    meaning: () => 'The calendar event has not ended yet; it is picked up automatically after its end time, with no edit needed.' },
  too_short: { stage: 'decision',
    meaning: () => 'The page body is under 80 characters, too short to hold events.' },
  dream_generated: { stage: 'decision',
    meaning: () => 'Dream-generated pages are never mined for events.' },
  page_body_segmented: { stage: 'decision',
    meaning: () => 'An earlier release skipped this page: its body is over the 24 MiB single-string ceiling and is stored in segments. This release reads segmented pages, so the next revision or a backfill extracts it.' },
  no_write_decision: { stage: 'discovery',
    meaning: () => 'This revision has no recorded write decision (written by an older binary or before this release activated), so only a trusted backfill extracts it.',
    fix: backfill('agent', FIX_BY_BACKFILL) },
  not_chronicle_shaped: { stage: 'decision',
    meaning: () => 'The page is no longer a meeting, conversation or calendar page, so the events extracted from it were retired.' },
  already_extracted: { stage: 'decision',
    meaning: () => 'This exact content was already extracted; its events are current, so no new call is made.' },
  judge_input_unchanged: { stage: 'execution',
    meaning: () => 'Nothing the extraction reads changed since the page was last extracted (for example only text past a long page\'s first 12,000 characters changed), so the earlier events are current and no new call is made.' },
  judge_input_failed: { stage: 'execution',
    meaning: () => 'Earlier revisions of the page already spent every extraction attempt on exactly this text without publishing events (the judge\'s answer was cut off, unreadable, malformed or over the per-page spend cap), so it is not paid for again until the text extraction reads changes.',
    fix: backfill('agent', 'After fixing the cause the earlier failure named (doctor auto_chronicle), preview and backfill the page if the user agrees to one more paid chat call.') },
  superseded: { stage: 'execution',
    meaning: () => 'A newer revision replaced this content before extraction ran; the newer revision carries its own decision.' },
  daily_limit: { stage: 'execution',
    meaning: (ctx) => `The automatic daily limit (chronicle.auto_daily_limit = ${ctx.dailyLimit ?? 200} calls per rolling 24 hours) is used up; pending pages wait for a free slot.`,
    fix: (ctx) => ({ argv: ['gbrain', 'config', 'set', 'chronicle.auto_daily_limit', String((ctx.dailyLimit ?? 200) * 2)],
      consent: ['paid'], actor: 'agent', requires_exclusive: false,
      why: 'Pending pages run on their own as slots free up. Raise the limit only if the user agrees to more paid calls per day.' }) },
  judge_llm_unavailable: { stage: 'execution',
    meaning: () => 'No chat provider is configured on the brain host, so extraction cannot run.',
    fix: () => ({ consent: ['credentials'], actor: 'user', requires_exclusive: false,
      why: 'Ask the user to configure a chat provider key on the brain host (see docs/ai-providers/); pending pages run on the next cycle.' }) },
  no_pricing: { stage: 'execution',
    meaning: (ctx) => `chronicle.job_budget_usd was set explicitly, and gbrain has no price for ${ctx.model ?? 'the chat model'}, so the cap cannot be enforced.`,
    fix: (ctx) => ({ argv: ['gbrain', 'pricing', 'set', ctx.model ?? '<model>', ...pricingSetCommand('model', 'chat').split(' ').slice(4)],
      consent: [], actor: 'agent', requires_exclusive: false,
    why: 'Look up the model\'s current price and register it on the brain host; extraction retries on the next cycle.',
    inputs: [{ name: 'usd-per-1M-input-tokens', how: 'the provider pricing page' },
      { name: 'usd-per-1M-output-tokens', how: 'the provider pricing page' },
      { name: 'pricing-page-url', how: 'the URL you read the price from' }] }) },
  budget_exhausted: { stage: 'execution',
    meaning: () => 'The extraction call cost more than chronicle.job_budget_usd allows for one page.',
    fix: () => ({ argv: ['gbrain', 'config', 'set', 'chronicle.job_budget_usd', '0.50'], consent: ['paid'], actor: 'agent',
      requires_exclusive: false, why: 'Raising the per-page cap lets long pages finish; ask the user before raising spend.' }) },
  campaign_exhausted: { stage: 'execution',
    meaning: () => 'The page used every attempt its capped backfill (chronicle-backfill --max-usd) authorized without finishing, so it stops before spending more.',
    fix: (ctx) => ({ argv: chronicleBackfillArgv({ sourceId: ctx.sourceId, since: ctx.since, dryRun: true }), consent: [], actor: 'agent',
      requires_exclusive: false,
      why: 'Preview what a new backfill would queue (read-only); queuing it again is paid, so ask the user for a new --max-usd first.' }) },
  judge_chat_error: { stage: 'execution',
    meaning: () => 'The chat provider returned an error; the page retries with backoff.',
    fix: () => ({ consent: [], actor: 'provider', requires_exclusive: false,
      why: 'Wait for the retry; if it keeps failing, check the provider status and key.' }) },
  judge_truncated: { stage: 'execution',
    meaning: () => 'The extraction output hit chronicle.judge_max_tokens and was cut off, so nothing was written.',
    fix: () => ({ argv: ['gbrain', 'config', 'set', 'chronicle.judge_max_tokens', '8000'], consent: ['paid'], actor: 'agent',
      requires_exclusive: false, why: 'A higher output cap lets event-dense pages finish; ask the user before raising spend.' }) },
  judge_parse_failed: { stage: 'execution',
    meaning: () => 'The extraction output had no parseable JSON array, so nothing was written; the page retries on a later run.' },
  malformed_proposal: { stage: 'execution',
    meaning: () => 'A proposed event failed validation, so the whole batch was rejected and nothing was written; the page retries on a later run.' },
  publish_error: { stage: 'execution',
    meaning: () => 'Publishing the events failed; nothing from this attempt replaced the previous events, and the page retries on a later run.' },
  judge_refused: { stage: 'execution',
    meaning: () => 'The chat model refused or filtered the page; no events were written.' },
  page_missing: { stage: 'execution',
    meaning: () => 'The page was deleted before extraction ran.' },
  no_events: { stage: 'execution',
    meaning: () => 'Extraction read the page and found no events.' },
  future_dated: { stage: 'execution',
    meaning: () => 'Every event the extraction proposed was dated after the page\'s own day (a plan, follow-up or scheduled item), so none was written; only what happened by the end of the page\'s day becomes an event.' },
  date_imprecise: { stage: 'execution',
    meaning: () => 'Every event the extraction proposed had only a year or a month ("back in 2024"), so none was written; the timeline stores days and never invents one.' },
  no_chat_provider: { stage: 'phase',
    meaning: () => 'No chat provider is configured on the brain host, so the chronicle phase made no calls.',
    fix: () => ({ consent: ['credentials'], actor: 'user', requires_exclusive: false,
      why: 'Ask the user to configure a chat provider key on the brain host (see docs/ai-providers/); pending pages run on the next cycle.' }) },
} as const satisfies Record<string, ChronicleReason>;

export type ChronicleReasonCode = keyof typeof CHRONICLE_REASONS;

/** Eligibility reasons for pages that are not chronicle-shaped: the receipt omits the field for them. */
const NOT_CHRONICLE_SHAPED = /^(kind:|diary_excluded$|event_self$|subagent_scratch$)/;

/**
 * The write-time decision (ledger.ts `decideChronicle`): `pending` with no reason is
 * queued for the next cycle; `pending` with a reason (`not_yet_happened`) waits and reports that
 * reason like a skip; `skipped` carries its reason.
 */
export type ChronicleDecision = { state: 'pending' | 'skipped'; reason?: string | null };

export type ChronicleBackstopReceipt =
  | { pending: 'next_cycle'; daily_remaining?: number }
  | { skipped: string; stage: ChronicleStage; why: string; fix?: Action };

/**
 * The `chronicle_backstop` receipt field (sibling of `facts_backstop`). Omitted (undefined) for pages
 * that are not chronicle-shaped, so ordinary notes carry no `kind:<type>` noise. An unknown reason
 * still reports itself with a doctor pointer rather than disappearing.
 */
export function chronicleBackstopReceipt(decision: ChronicleDecision, ctx: ChronicleReasonContext & { dailyRemaining?: number }): ChronicleBackstopReceipt | undefined {
  if (!decision.reason) {
    return decision.state === 'pending'
      ? { pending: 'next_cycle', ...(ctx.dailyRemaining === undefined ? {} : { daily_remaining: ctx.dailyRemaining }) }
      : chronicleBackstopReceipt({ state: 'skipped', reason: 'unknown' }, ctx);
  }
  const reason = decision.reason;
  if (NOT_CHRONICLE_SHAPED.test(reason)) return undefined;
  const entry: ChronicleReason | undefined = (CHRONICLE_REASONS as Record<string, ChronicleReason>)[reason];
  if (!entry) {
    return { skipped: reason, stage: 'decision', why: `Extraction was skipped (${reason}).`,
      fix: { argv: ['gbrain', 'doctor', '--json'], consent: [], actor: 'agent', requires_exclusive: false,
        why: 'Read the auto_chronicle check for details.' } };
  }
  const fix = entry.fix?.(ctx);
  return { skipped: reason, stage: entry.stage, why: entry.meaning(ctx), ...(fix ? { fix } : {}) };
}

function shellWord(word: string): string {
  return /^[\w.:/@+=<>-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`;
}

/** Markdown reason table for docs/guides/life-chronicle.md (rendered with placeholder values). */
export function renderChronicleReasonTable(): string {
  const ctx: ChronicleReasonContext = { sourceId: '<source>', since: '<YYYY-MM-DD>', model: '<provider:model>', dailyLimit: 200, recentDays: 30 };
  const rows = Object.entries(CHRONICLE_REASONS).map(([code, reason]) => {
    const entry: ChronicleReason = reason;
    const fix = entry.fix?.(ctx);
    const command = fix?.argv ? `\`${fix.argv.map(shellWord).join(' ')}\`` : '—';
    const preview = fix?.preview_argv ? ` (preview: \`${fix.preview_argv.map(shellWord).join(' ')}\`)` : '';
    const consent = fix && fix.consent.length > 0 ? fix.consent.join(', ') : '—';
    return `| \`${code}\` | ${entry.stage} | ${entry.meaning(ctx)} | ${fix ? `${command}${preview}` : '—'} | ${fix?.actor ?? '—'} | ${consent} |`;
  });
  return ['| Code | Stage | Meaning | Fix | Who acts | Consent |', '|---|---|---|---|---|---|', ...rows].join('\n');
}