Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
21.9 KB
Raw Blame
/**
 * Life Chronicle + ontology operation cluster — pure move from operations.ts
 * (v0.46.x tranche 3): the v0.42.x (#2390) timeline reads, the ontology
 * read/write ops, volunteer_chronicle, and the chronicle_backfill sweep. Op
 * consts stay module-private; `chronicleOperations` below lists them in
 * EXACTLY the order they appear in the canonical `operations` array in
 * ../operations.ts. Never import from '../operations.ts' here (cycle).
 */

import type { Operation, OperationContext } from './contract.ts';
import type { ChronicleTimelineRow, OntologyValue } from '../types.ts';
import { readPolicyOpts, requireWritablePage, sourceScopeOpts } from './context.ts';
import { withFolderRestricted, worldOnlyFacts } from '../search/private-visibility.ts';
import { invalidParam } from './op-fix.ts';
import { quoteTimelineRows } from './timeline-quote.ts';
import { quoteFacts, quotePageText, quotesStored, unquoteAnyTranscriptText, unquoteFactText } from '../search/transcript-quote.ts';

// ── Remote diary redaction (fail-closed) ─────────────────────────────────
// The exact mechanism the ontology siblings use (`ctx.remote !== false` →
// life/diary provenance is redacted; only strictly-local `remote: false`
// sees it). A timeline row is diary-sourced when its depth page OR its
// event page lives under life/diary/, or its `source` provenance
// references a life/diary page.
const DIARY_PREFIX = 'life/diary/';
function redactDiaryTimeline<
  T extends { page_slug?: string | null; event_slug?: string | null; source?: string | null },
>(ctx: OperationContext, rows: T[]): T[] {
  if (ctx.remote === false) return rows;
  return rows.filter((r) =>
    !(r.page_slug ?? '').startsWith(DIARY_PREFIX) &&
    !(r.event_slug ?? '').startsWith(DIARY_PREFIX) &&
    !(r.source ?? '').includes(DIARY_PREFIX));
}
/**
 * The rows a remote reader gets: diary rows redacted, then each entry below the owner's tier quoted as its own page's (GST-687),
 * and an event projection's `kind` (its event page's frontmatter) quoted by that event page's type and tier (#8384).
 */
async function remoteTimeline(ctx: OperationContext, rows: ChronicleTimelineRow[]) {
  const quoted = await quoteTimelineRows(ctx, r => r.page_slug, redactDiaryTimeline(ctx, rows));
  const events = quoted.flatMap(r => (r.kind ? [Number(r.event_page_id)] : []));
  if (ctx.remote === false || events.length === 0) return quoted;
  const pages = new Map((await ctx.engine.executeRaw<{ id: number | string; type: string | null; trust_tier: string | null }>(
    'SELECT id, type, trust_tier FROM pages WHERE id = ANY($1::bigint[])', [[...new Set(events)]])).map(p => [Number(p.id), p]));
  return quoted.map(r => {
    const page = pages.get(Number(r.event_page_id));
    return r.kind && quotesStored(page?.type, page?.trust_tier)
      ? { ...r, kind: quotePageText(r.kind, r.event_slug ?? r.page_slug, page?.type), quoted: 'transcript' as const } : r;
  });
}
/** #8384: ontology values a remote reader gets, each quoted by its fact's stored tier as recall quotes the fact (quoteFacts). */
async function remoteOntology<V extends Pick<OntologyValue, 'value' | 'source' | 'fact_id'>>(ctx: OperationContext, values: V[]): Promise<Array<V & { quoted?: 'transcript' }>> {
  if (ctx.remote === false || values.length === 0) return values;
  const facts = await quoteFacts(ctx.engine, values.map(v => ({ id: v.fact_id, fact: v.value, source: v.source })), true);
  return values.map((v, i) => facts[i]!.quoted ? { ...v, value: facts[i]!.fact, quoted: 'transcript' as const } : v);
}

// ── v0.42.x — Life Chronicle (#2390) timeline read ops ───────────────────
// CLI names avoid the existing `timeline` (get_timeline, a page's own timeline):
// `gbrain day <date>` / `gbrain since <date>` / `gbrain last-seen <entity>`.
// All route through sourceScopeOpts(ctx) so reads honor source isolation.
const chronicle_day: Operation = {
  name: 'chronicle_day',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description:
    'Life Chronicle: events + timeline entries on a given day (or its ISO week when week=true), ' +
    "ordered chronologically; each row backlinks to its depth page. Distinct from `get_timeline`/" +
    "`gbrain timeline <slug>`, which shows ONE page's timeline. CLI: `gbrain day <date>`.",
  scope: 'read',
  params: {
    date: { type: 'string', required: true, description: 'Day as YYYY-MM-DD.' },
    week: { type: 'boolean', description: 'Expand to the ISO week (Mon–Sun) containing the date.' },
    limit: { type: 'number', description: 'Max rows (default 200).' },
    narrative: { type: 'boolean', description: 'Also return a prose day-by-day narrative.' },
  },
  handler: async (ctx, p) => {
    const rows = await remoteTimeline(ctx, await ctx.engine.getTimelineForDate(String(p.date), {
      week: p.week === true,
      limit: typeof p.limit === 'number' ? p.limit : undefined,
      ...await readPolicyOpts(ctx),
    }));
    if (p.narrative === true) {
      const { renderTimelineNarrative } = await import('../chronicle/narrative.ts');
      return { date: String(p.date), narrative: renderTimelineNarrative(rows), events: rows };
    }
    return rows;
  },
  cliHints: { name: 'day', positional: ['date'] },
};

const chronicle_on_this_day: Operation = {
  name: 'chronicle_on_this_day',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description:
    'Life Chronicle: events from the same calendar day in PRIOR years ("on this day"). ' +
    'CLI: `gbrain on-this-day [--date YYYY-MM-DD]`.',
  scope: 'read',
  params: {
    date: { type: 'string', description: 'Anchor day YYYY-MM-DD (default today); matches its month-day in prior years.' },
    limit: { type: 'number', description: 'Max rows (default 50).' },
  },
  handler: async (ctx, p) => remoteTimeline(ctx, await ctx.engine.getOnThisDay({
    date: typeof p.date === 'string' ? p.date : undefined,
    limit: typeof p.limit === 'number' ? p.limit : undefined,
    ...await readPolicyOpts(ctx),
  })),
  cliHints: { name: 'on-this-day' },
};

const chronicle_since: Operation = {
  name: 'chronicle_since',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description:
    'Life Chronicle: events + timeline entries on or after a date, optionally filtered by event kind. ' +
    'CLI: `gbrain since <date> [--kind commitment]`.',
  scope: 'read',
  params: {
    date: { type: 'string', required: true, description: 'Lower-bound day as YYYY-MM-DD (inclusive).' },
    kind: { type: 'string', description: "Filter event projections by event.kind (e.g. 'commitment')." },
    limit: { type: 'number', description: 'Max rows (default 200).' },
  },
  handler: async (ctx, p) => {
    return remoteTimeline(ctx, await ctx.engine.getSince(String(p.date), {
      kind: typeof p.kind !== 'string' ? undefined : ctx.remote === false ? p.kind : unquoteAnyTranscriptText(p.kind),
      limit: typeof p.limit === 'number' ? p.limit : undefined,
      ...await readPolicyOpts(ctx),
    }));
  },
  cliHints: { name: 'since', positional: ['date'] },
};

const chronicle_last_seen: Operation = {
  name: 'chronicle_last_seen',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description:
    "Life Chronicle: when an entity was last seen — its own timeline rows OR an event's `who`. " +
    'Returns last_date, the event slug, and days_ago. CLI: `gbrain last-seen <entity-slug>`.',
  scope: 'read',
  params: {
    entity: { type: 'string', required: true, description: 'Entity page slug (e.g. people/sarah-chen).' },
    asof: { type: 'string', description: 'Reference day YYYY-MM-DD for days_ago (default today).' },
  },
  handler: async (ctx, p) => {
    const res = await ctx.engine.getLastSeen(String(p.entity), {
      asof: typeof p.asof === 'string' ? p.asof : undefined,
      ...await readPolicyOpts(ctx),
    });
    // Fail-closed diary redaction: when the evidence is a life/diary event
    // (or a life/diary page is queried AS the entity), remote callers get
    // the never-seen shape rather than a diary-derived sighting.
    if (ctx.remote !== false &&
        ((res.last_event_slug ?? '').startsWith(DIARY_PREFIX) || String(p.entity).startsWith(DIARY_PREFIX))) {
      return { ...res, last_date: null, last_event_slug: null, days_ago: null };
    }
    return res;
  },
  cliHints: { name: 'last-seen', positional: ['entity'] },
};

const ontology_get: Operation = {
  name: 'ontology_get',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description:
    "Life Chronicle: the current resolved per-entity ontology (dimension → value) at `asof` " +
    "(default now), with provenance + confidence + validity. CLI: `gbrain ontology <entity> [--asof YYYY-MM-DD]`.",
  scope: 'read',
  params: {
    entity: { type: 'string', required: true, description: 'Entity page slug (e.g. people/sarah-chen).' },
    asof: { type: 'string', description: 'Valid-time as-of day YYYY-MM-DD (time-travel; default now).' },
    min_confidence: { type: 'number', description: 'Only return observations at/above this confidence (0..1).' },
    include_quarantined: { type: 'boolean', description: 'Include quarantined novel dimensions (default false).' },
  },
  handler: async (ctx, p) => {
    const rows = await ctx.engine.getOntology(String(p.entity), {
      asof: typeof p.asof === 'string' ? p.asof : undefined,
      minConfidence: typeof p.min_confidence === 'number' ? p.min_confidence : undefined,
      includeQuarantined: p.include_quarantined === true,
      visibility: worldOnlyFacts(ctx.remote) ? ['world'] : undefined,
      excludeDiary: ctx.remote !== false,
      ...await readPolicyOpts(ctx),
    });
    // Remote redaction: the visibility recall reads (worldOnlyFacts), resolved before
    // DISTINCT ON; never surface diary-sourced ontology to untrusted callers.
    return ctx.remote !== false ? remoteOntology(ctx, rows.filter((r) => !(r.source ?? '').startsWith('life/diary/'))) : rows;
  },
  cliHints: { name: 'ontology', positional: ['entity'] },
};

const ontology_propose: Operation = {
  name: 'ontology_propose',
  idempotent: false,
  outputRedaction: 'retrieval',
  description:
    'Life Chronicle: record one ontology observation (entity has dimension=value), sourced + ' +
    'confidence-weighted + bi-temporal. Idempotent on (entity,dimension,value,source). A new value ' +
    'supersedes the prior; a backdated conflict is flagged not rewritten. CLI: `gbrain ontology-add <entity> <dimension> <value>`.',
  scope: 'write',
  mutating: true,
  params: {
    entity: { type: 'string', required: true, description: 'Entity page slug.' },
    dimension: { type: 'string', required: true, description: 'Dimension (e.g. role, risk_tolerance). Normalized at write.' },
    value: { type: 'string', required: true, description: 'The resolved value (e.g. advisor).' },
    confidence: { type: 'number', description: '0..1; default 0.7.' },
    source: { type: 'string', description: 'Provenance (page slug / uri); default "manual".' },
    valid_from: { type: 'string', description: 'ISO date the value became true (default: now).' },
    valid_to: { type: 'string', description: 'ISO date the value stopped being true (default: open).' },
    visibility: { type: 'string', enum: ['private', 'world'], description: 'Default private.' },
  },
  handler: async (ctx, p) => {
    // [ENG-8] Same unset-vs-explicit ladder as extract_facts: explicit
    // caller visibility wins; unset resolves facts.default_visibility.
    const { resolveVisibilityParam } = await import('../facts/visibility.ts');
    const { coordinatedDatabaseWrite } = await import('../persistence/database-write.ts');
    const entitySlug = String(p.entity);
    let visibility = await resolveVisibilityParam(ctx.engine, p.visibility);
    // GBRA-431: a remote caller writes an observation only onto an entity page it can read (a hidden page answers as
    // put_page's create on it does), and the observation is never wider than that page, as remember and extract_facts.
    if (ctx.remote !== false) {
      await requireWritablePage(ctx, entitySlug, 'ontology_propose', 'page', true);
      const page = await ctx.engine.getPage(entitySlug, { sourceId: ctx.sourceId ?? 'default' });
      if (page) {
        const { tightenToPage } = await import('../facts/visibility.ts');
        visibility = tightenToPage(visibility, await withFolderRestricted(ctx.engine, page));
      }
    }
    const merge = (engine: typeof ctx.engine, sourceId: string | undefined) => engine.mergeOntologyFact({
      entitySlug,
      dimension: String(p.dimension),
      // #8384: a value copied out of a quoted ontology read is stored without the fence.
      value: ctx.remote === false ? String(p.value) : unquoteFactText(String(p.value)),
      confidence: typeof p.confidence === 'number' ? p.confidence : undefined,
      source: typeof p.source === 'string' && p.source ? p.source : 'manual',
      validFrom: typeof p.valid_from === 'string' ? p.valid_from : undefined,
      validTo: typeof p.valid_to === 'string' ? p.valid_to : undefined,
      visibility,
      sourceId,
    });
    // A managed brain commits the observation as a coordinated database-only
    // write serialized on the entity's page key; unmanaged brains write directly.
    // #5575: an agent observation never closes a more trusted stint; it is stored contested for the owner (A5).
    const { ontologyWriteTrust, contestOntologySupersession } = await import('../trust/supersede-handlers.ts');
    const trust = ontologyWriteTrust(ctx);
    const guarded = async (engine: typeof ctx.engine, sourceId: string | undefined) => {
      const result = await merge(engine, sourceId);
      return { ...result, ...await contestOntologySupersession(engine, sourceId ?? 'default', entitySlug, String(p.dimension), result) };
    };
    // W1 #6783 §5.1: the observation's rows live in its provenance's stream and in the closed stint's, so those keys are held too.
    const { ontologyStreamSlugs, beliefTransaction } = await import('../belief/writers.ts');
    const { withWriteAttribution } = await import('../persistence/context.ts');
    const { maintenanceAttribution } = await import('../persistence/attribution.ts');
    const sourceId = ctx.sourceId ?? 'default';
    const slugs = await ontologyStreamSlugs(ctx.engine, sourceId, entitySlug, String(p.dimension), typeof p.source === 'string' && p.source ? p.source : 'manual');
    const managed = await coordinatedDatabaseWrite(ctx, 'ontology_propose', entitySlug, slugs, guarded, trust);
    if (managed) return managed.value;
    const attribution = { ...await maintenanceAttribution(ctx.engine), trust };
    return beliefTransaction(ctx.engine, { sourceId, slugs, publicationId: crypto.randomUUID(), op: 'ontology_propose', remote: ctx.remote !== false },
      tx => guarded(tx, ctx.sourceId), (tx, run) => withWriteAttribution(tx, attribution, run));
  },
  cliHints: { name: 'ontology-add', positional: ['entity', 'dimension', 'value'] },
};

const ontology_dimensions: Operation = {
  name: 'ontology_dimensions',
  mutating: false,
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description:
    'Life Chronicle meta-ontology: which dimensions the brain tracks across entities, with ' +
    'entity + observation counts. CLI: `gbrain ontology-dimensions`.',
  scope: 'read',
  params: {},
  handler: async (ctx) => ctx.engine.discoverOntologyDimensions(sourceScopeOpts(ctx)),
  cliHints: { name: 'ontology-dimensions' },
};

const ontology_conflicts: Operation = {
  name: 'ontology_conflicts',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description:
    'Life Chronicle: dimensions with ≥2 distinct current values from ≥2 provenances (genuine ' +
    'disagreement, not temporal supersession). CLI: `gbrain ontology-contradictions`.',
  scope: 'read',
  params: {
    min_confidence: { type: 'number', description: 'Only consider observations at/above this confidence (0..1).' },
  },
  handler: async (ctx, p) => {
    const conflicts = await ctx.engine.findOntologyConflicts({
      minConfidence: typeof p.min_confidence === 'number' ? p.min_confidence : undefined,
      visibility: worldOnlyFacts(ctx.remote) ? ['world'] : undefined,
      excludeDiary: ctx.remote !== false,
      ...await readPolicyOpts(ctx),
    });
    if (ctx.remote === false) return conflicts;
    // Remote: redact diary-sourced values; drop conflicts that no longer have
    // ≥2 distinct values once diary provenance is removed (no leak via conflicts).
    const kept = conflicts
      .map((c) => ({ ...c, values: c.values.filter((v) => !(v.source ?? '').startsWith('life/diary/')) }))
      .filter((c) => new Set(c.values.map((v) => v.value)).size >= 2);
    const quoted = await remoteOntology(ctx, kept.flatMap((c) => c.values));
    let at = 0;
    return kept.map((c) => ({ ...c, values: c.values.map(() => quoted[at++]!) }));
  },
  cliHints: { name: 'ontology-contradictions' },
};

const volunteer_chronicle: Operation = {
  name: 'volunteer_chronicle',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description:
    'Life Chronicle agent-orientation: the recent timeline (last N days) + the current ' +
    'validity-resolved ontology for the named entities, in one zero-LLM payload, so an agent ' +
    'orients before acting. Diary-sourced ontology is redacted for remote callers. ' +
    'CLI: `gbrain orient [--days 7] [--entities people/a,people/b]`.',
  scope: 'read',
  params: {
    days: { type: 'number', description: 'Recent-timeline lookback in days (default 7).' },
    entities: { type: 'string', description: 'Comma-separated entity slugs to resolve ontology for.' },
    limit: { type: 'number', description: 'Max timeline rows (default 50).' },
  },
  handler: async (ctx, p) => {
    const { loadChronicleContext } = await import('../context/chronicle-context.ts');
    const entities = typeof p.entities === 'string'
      ? p.entities.split(',').map((s) => s.trim()).filter(Boolean)
      : undefined;
    const result = await loadChronicleContext(ctx.engine, {
      days: typeof p.days === 'number' ? p.days : undefined,
      entities,
      limit: typeof p.limit === 'number' ? p.limit : undefined,
      remote: ctx.remote !== false,
      ...await readPolicyOpts(ctx),
    });
    // Same fail-closed diary redaction as the timeline reads: the loader
    // redacts diary-sourced ONTOLOGY; the recent timeline is redacted here.
    const ontologies = Object.fromEntries(await Promise.all(Object.entries(result.ontologies).map(async ([slug, values]) => [slug, await remoteOntology(ctx, values)] as const)));
    return { ...result, recent_timeline: await remoteTimeline(ctx, result.recent_timeline), ontologies };
  },
  cliHints: { name: 'orient' },
};

const chronicle_backfill: Operation = {
  name: 'chronicle_backfill',
  idempotent: false,
  outputRedaction: 'no_stored_text',
  description:
    'Life Chronicle: queue existing meeting/conversation/calendar pages (by type or under meetings/, conversations/, ' +
    'cal/, calendar/) for timeline-event extraction. One paid chat call per page, so it needs --yes; --dry-run ' +
    'reports the candidates, an estimated cost and skip reasons. The chronicle_page_state ledger skips content ' +
    'already extracted or queued, so repeats never pay twice. Queued pages run in the `chronicle` cycle phase ' +
    '(`gbrain dream --phase chronicle`), exempt from the daily limit. --max-usd is a hard bound counting retries: ' +
    'pages queue only while their worst case fits, and an unpriced chat model then refuses with no_pricing. Local-only bulk op. ' +
    'CLI: `gbrain chronicle-backfill [--since YYYY-MM-DD] [--dated-since YYYY-MM-DD] [--recent] [--limit N] [--max-usd USD] [--dry-run | --yes]`.',
  scope: 'admin',
  mutating: true,
  localOnly: true,
  params: {
    since: { type: 'string', description: 'Only pages UPDATED on/after this date (YYYY-MM-DD). Use --dated-since for the page\'s own date.' },
    dated_since: { type: 'string', description: "Only pages whose own date (authored effective date, else frontmatter date/start) is on/after this date (YYYY-MM-DD)." },
    recent: { type: 'boolean', description: 'Only pages within chronicle.auto_recent_days (the automatic path\'s window).' },
    limit: { type: 'number', description: 'Max pages queued in this run, across all types and sources (default 1000).' },
    dry_run: { type: 'boolean', description: 'Count candidates, estimate cost and report skip reasons without queuing.' },
    yes: { type: 'boolean', description: 'Consent to queue paid extraction (one chat call per page). Ask the user first.' },
    max_usd: { type: 'number', description: 'Hard spend bound in USD for everything this run queues, retries included; pages beyond it are not queued (cap_reached).' },
  },
  handler: async (ctx, p) => {
    const { runChronicleBackfill } = await import('../chronicle/backfill.ts');
    const { getChatModel } = await import('../ai/gateway.ts');
    let model: string | undefined;
    try { model = getChatModel(); } catch { model = undefined; }
    const scope = sourceScopeOpts(ctx);
    if (p.max_usd !== undefined && !(typeof p.max_usd === 'number' && Number.isFinite(p.max_usd) && p.max_usd > 0)) {
      throw invalidParam(ctx, 'chronicle_backfill', 'max_usd', 'chronicle_backfill: max_usd must be a positive number of US dollars.', { example: 5 });
    }
    return runChronicleBackfill(ctx.engine, {
      since: typeof p.since === 'string' ? p.since : undefined,
      datedSince: typeof p.dated_since === 'string' ? p.dated_since : undefined,
      recent: p.recent === true,
      limit: typeof p.limit === 'number' ? p.limit : undefined,
      dryRun: p.dry_run === true,
      yes: p.yes === true,
      sourceId: scope.sourceId,
      sourceIds: scope.sourceIds,
      model,
      maxUsd: typeof p.max_usd === 'number' ? p.max_usd : undefined,
    });
  },
  cliHints: { name: 'chronicle-backfill' },
};

export const chronicleOperations: Operation[] = [
  chronicle_day, chronicle_on_this_day, chronicle_since, chronicle_last_seen,
  ontology_get, ontology_propose, ontology_dimensions, ontology_conflicts,
  volunteer_chronicle, chronicle_backfill,
];