Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
18.1 KB
Raw Blame
/**
 * Insight-read operation cluster — pure move from operations.ts (v0.46.x
 * tranche 3): the v0.43 push-based-context op (volunteer_context) plus the
 * find_* insight reads (find_experts, find_contradictions, find_trajectory).
 * Unlike the other tranche-3 clusters these four occupy NON-adjacent slots of
 * the canonical `operations` array in ../operations.ts, so the ops are
 * exported individually and spliced as bare entries at their original
 * positions (order is contractual — docs/TOOL_CATALOG.md is generated from
 * it). Never import from '../operations.ts' here (cycle).
 */

import { MIN_TRUST_PARAM, resolveReadEligibility } from '../eligibility/policy.ts';
import { resolveScopedFindings } from '../eval-contradictions/scoped-read.ts';
import type { ProbeReport } from '../eval-contradictions/types.ts';
import { proactiveEligibility } from '../eligibility/registry.ts';
import { activationSuppressionNotice, suppressionSummary } from '../eligibility/activation.ts';
import type { Operation } from './contract.ts';
import { opError } from './contract.ts';
import { invalidParam, paramUse } from './op-fix.ts';
import { federatedSearchScope, sourceScopeOpts, readPolicyOpts } from './context.ts';
import { parseSourceIdsParam, requestSourceScope, SOURCE_IDS_PARAM } from './search-source-scope.ts';
import { currentReadMode } from '../access/scope-read.ts';
import {
  FIND_EXPERTS_DESCRIPTION,
  FIND_CONTRADICTIONS_DESCRIPTION,
  FIND_TRAJECTORY_DESCRIPTION,
} from '../operations-descriptions.ts';

// --- v0.43 (#2095): push-based context — the brain volunteers pages ---

const volunteer_context: Operation = {
  name: 'volunteer_context',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description:
    'Push-based context: volunteer brain pages relevant to a rolling conversation window ' +
    'WITHOUT being asked. Zero-LLM, confidence-gated (alias 0.9 / exact-title 0.8 / ' +
    'slug-suffix 0.6, +0.05 for multi-turn or newest-turn mentions; default gate 0.7), ' +
    'capped at 3 pages (max 5). Returns pointers with one-line rationales + synopses — ' +
    'open the page (get_page) before relying on details. Pass stats: true for the ' +
    'approximate volunteered-vs-used precision summary (the feedback loop).',
  scope: 'read',
  params: {
    window: {
      type: 'string',
      description:
        "Recent conversation turns, oldest → newest, as 'user:' / 'assistant:' prefixed " +
        'lines (unprefixed text = one user turn). Required unless stats: true. ' +
        'CLI: piped stdin fills this.',
    },
    prior_context: {
      type: 'string',
      description:
        'Already-surfaced context (pointer blocks / opened page bodies). Pages whose slug ' +
        'appears here are not re-volunteered.',
    },
    max_pages: { type: 'number', description: 'Max pages to volunteer (default 3, hard cap 5).' },
    min_trust: MIN_TRUST_PARAM,
    min_confidence: {
      type: 'number',
      description:
        'Confidence gate 0..1 (default 0.7 — slug-suffix matches need an explicit lower gate).',
    },
    session_id: { type: 'string', description: 'Optional caller session id, logged for attribution.' },
    turn: { type: 'number', description: 'Optional caller turn number, logged for attribution.' },
    stats: {
      type: 'boolean',
      description:
        'Return the volunteered-vs-used precision summary instead of volunteering. ' +
        'APPROXIMATE: "used" = pages.last_retrieved_at > volunteered_at.',
    },
    days: { type: 'number', description: 'Stats window in days (default 30; stats mode only).' },
    source_ids: SOURCE_IDS_PARAM,
  },
  handler: async (ctx, p) => {
    const { parseWindow, volunteerContext, volunteerUsageStats } = await import('../context/volunteer.ts');
    // GST-1158 E1: under the scope record the stats summary (volunteering across whole sources) is refused.
    const asScope = currentReadMode() === 'scope';
    if (p.stats === true && asScope) {
      throw invalidParam(ctx, 'volunteer_context', 'stats', '`stats` summarizes volunteering across whole sources, so a call that names sources as their audience cannot ask for it.', { example: false });
    }
    const named = parseSourceIdsParam(ctx, 'volunteer_context', p.source_ids);
    const scope = named === undefined ? sourceScopeOpts(ctx) : await requestSourceScope(ctx, undefined, named);
    const sourceIds = scope.sourceIds ?? (scope.sourceId ? [scope.sourceId] : ['default']);

    if (p.stats === true) {
      return volunteerUsageStats(ctx.engine, sourceIds, typeof p.days === 'number' ? p.days : undefined);
    }

    if (typeof p.window !== 'string' || !p.window.trim()) {
      throw opError(
        'invalid_params',
        `window is required unless ${paramUse(ctx, 'stats')}`,
        `${ctx.remote === false ? 'Pipe the recent turns on stdin' : 'Pass `window` with the recent turns as a string'}, or pass ${paramUse(ctx, 'stats')} for the volunteered-vs-used summary.`,
      );
    }
    const turns = parseWindow(p.window);
    const { loadConfig: loadCfgForArms } = await import('../config.ts');
    const { lexicalArmsEnabled } = await import('../context/reflex.ts');
    const { resolveExcludePrivatePages } = await import('../search/private-visibility.ts');
    const withheldKeys = new Set<string>();
    const pages = await volunteerContext(ctx.engine, turns, {
      sourceIds,
      priorContext: typeof p.prior_context === 'string' ? p.prior_context : undefined,
      maxPages: typeof p.max_pages === 'number' ? p.max_pages : undefined,
      minConfidence: typeof p.min_confidence === 'number' ? p.min_confidence : undefined,
      // v0.46.15+ kill switch for the lexical recall arms (weak-alias +
      // surname) — file-plane gate, threaded per ResolvePointersOpts.
      lexicalArms: lexicalArmsEnabled(loadCfgForArms()),
      // N8-1: the same private-page gate remote search applies.
      excludePrivate: asScope || await resolveExcludePrivatePages(ctx.engine, ctx.remote),
      // #5575: token floor + min_trust + activation control (CEO-20, DX-10).
      eligibility: await proactiveEligibility(ctx, 'volunteer', { minTrust: p.min_trust }),
      onWithheld: keys => { for (const k of keys) withheldKeys.add(k); },
    });
    const withheld = withheldKeys.size;
    const notice = activationSuppressionNotice(withheld, 'volunteered context');
    if (notice) ctx.emitNotice?.(notice);

    // Feedback-loop logging: fire-and-forget batched INSERT through the
    // volunteer-events sink (drained at exit). Never fails the op.
    if (pages.length) {
      try {
        const { logVolunteerEventsFireAndForget, volunteerEventRowsFrom, SESSION_ID_MAX_LEN } = await import('../context/volunteer-events.ts');
        // Trust-boundary clamps (remote MCP callers): cap session_id length so
        // a read-scoped token can't bank unbounded TEXT per request, and only
        // log integer turns — a non-integer would throw inside the single
        // multi-row INSERT and silently drop the whole batch.
        const sessionId = typeof p.session_id === 'string' ? p.session_id.slice(0, SESSION_ID_MAX_LEN) : null;
        const turn =
          typeof p.turn === 'number' && Number.isInteger(p.turn) && Math.abs(p.turn) <= 2_147_483_647
            ? p.turn
            : null;
        logVolunteerEventsFireAndForget(
          ctx.engine,
          volunteerEventRowsFrom(pages, { channel: 'op', session_id: sessionId, turn }),
        );
      } catch {
        /* telemetry only */
      }
    }
    const suppressed = suppressionSummary(withheld);
    return { pages, count: pages.length, window_turns: turns.length, ...(suppressed ? { suppressed } : {}) };
  },
  cliHints: { name: 'volunteer-context', stdin: 'window' },
};

// v0.33: expertise + relationship-proximity routing. CLI: gbrain whoknows.
const find_experts: Operation = {
  name: 'find_experts',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: FIND_EXPERTS_DESCRIPTION,
  scope: 'read',
  params: {
    topic: {
      type: 'string',
      description: 'The topic to route. Free-form natural language.',
    },
    limit: {
      type: 'number',
      description: 'Max results (default 5).',
    },
    explain: {
      type: 'boolean',
      description: 'Include factor breakdown per result (expertise, recency, salience).',
    },
    source_ids: SOURCE_IDS_PARAM,
  },
  handler: async (ctx, p) => {
    const { findExperts } = await import('../../commands/whoknows.ts');
    const topic = typeof p.topic === 'string' ? p.topic : '';
    if (!topic.trim()) {
      throw invalidParam(ctx, 'find_experts', 'topic', '`topic` is required and must be a non-empty string.',
        { def: find_experts.params.topic, example: 'vector search' });
    }
    // v0.34.1 (#861, D3 — 5th leak surface): find_experts (whoknows) was
    // authored against v0.33 after PR #861 was drafted, so the source-scope
    // thread was missing entirely. The op calls findExperts → hybridSearch
    // internally; without the thread an auth'd src-A whoknows query would
    // surface src-B people in the rankings.
    // v0.40.6.0 T1.5 wiring (D4): consult the active pack for expert
    // types; pack-load failure → empty filter (NOT hardcoded defaults
    // per the silent-violation bug class Finding 1.3 closed).
    const { loadActivePackBestEffort, expertTypesFromPack } = await import('../schema-pack/index.ts');
    const pack = await loadActivePackBestEffort(ctx);
    const types = pack ? expertTypesFromPack(pack.manifest) : [];
    const sourceIds = parseSourceIdsParam(ctx, 'find_experts', p.source_ids);
    const scope = await readPolicyOpts(ctx, sourceIds === undefined ? undefined : await requestSourceScope(ctx, undefined, sourceIds));
    let degraded: unknown[] = [];
    const experts = await findExperts(ctx.engine, {
      topic,
      limit: typeof p.limit === 'number' ? p.limit : undefined,
      explain: p.explain === true,
      types: types as never,
      ...scope,
      onMeta: m => { degraded = m.degraded ?? []; },
    });
    // GBRA-200: a keyword-only or cut ranking is stamped like search, never read as "nobody knows".
    if (degraded.length) ctx.emitResponseMeta?.('retrieval', { degraded });
    return experts;
  },
  // hidden: 'whoknows' is in CLI_ONLY (src/cli.ts) — runWhoknows owns the CLI
  // surface (ranked table + per-factor explain + thin-client routing) and was
  // unreachable while this non-hidden hint dispatched the generic op formatter
  // (the #2035 calibration bug class, resolved the #3502 way: wire the richer
  // handler, hide the hint).
  cliHints: { name: 'whoknows', positional: ['topic'], hidden: true },
};

// v0.32.6: contradiction probe MCP surface (M3)
const find_contradictions: Operation = {
  name: 'find_contradictions',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: FIND_CONTRADICTIONS_DESCRIPTION,
  scope: 'read',
  // Reads eval_contradictions_runs.report_json for the latest run, then
  // filters in-memory by slug and severity. No new probe is triggered;
  // the agent surfaces what's already on disk. Scoped readers (remote,
  // source-scoped or floored) get each side re-read live (D9, scoped-read.ts).
  params: {
    slug: {
      type: 'string',
      description: 'Optional slug filter; matches either side of a pair (substring match on slug).',
    },
    severity: {
      type: 'string',
      enum: ['low', 'medium', 'high'],
      description: 'Optional severity filter.',
    },
    limit: {
      type: 'number',
      description: 'Max findings to return. Default 20.',
    },
    min_trust: MIN_TRUST_PARAM,
  },
  handler: async (ctx, p) => {
    const scope = sourceScopeOpts(ctx);
    // N2-2: the local CLI always carries a sourceId; one the operator did not
    // select is not a filter, so the bare command reads the latest run.
    const sourceFiltered = scope.sourceIds !== undefined
      || (scope.sourceId !== undefined && ctx.localSourceImplicit !== true);
    const { floor } = await resolveReadEligibility(ctx, { minTrust: p.min_trust });
    const scoped = ctx.remote !== false || sourceFiltered || floor !== undefined;
    const readScope = ctx.remote === false && !sourceFiltered ? {} : federatedSearchScope(ctx);
    if (scoped && ctx.remote !== false && readScope.sourceId === undefined && readScope.sourceIds === undefined) {
      return { contradictions: [], note: 'This connection names no readable source, so no stored contradiction findings are returned.' };
    }

    const limit = typeof p.limit === 'number' && p.limit > 0 ? Math.min(p.limit, 100) : 20;
    const slugFilter = typeof p.slug === 'string' ? p.slug.toLowerCase() : null;
    const sevFilter = (p.severity === 'low' || p.severity === 'medium' || p.severity === 'high')
      ? p.severity
      : null;
    const rows = await ctx.engine.loadContradictionsTrend(30);
    if (rows.length === 0) {
      return { contradictions: [], note: 'No probe runs in the last 30 days; run `gbrain eval suspected-contradictions` first.' };
    }
    const latest = rows[0];
    const report = latest.report_json as Partial<ProbeReport> | null;
    const allFindings = (report?.per_query ?? []).flatMap((q) => q.contradictions ?? []);
    const matches = (f: { severity: string; a: { slug: string }; b: { slug: string } }) => {
      if (sevFilter && f.severity !== sevFilter) return false;
      if (slugFilter) {
        const sA = f.a.slug.toLowerCase();
        const sB = f.b.slug.toLowerCase();
        if (!sA.includes(slugFilter) && !sB.includes(slugFilter)) return false;
      }
      return true;
    };
    if (scoped) {
      // D9: every side is re-read live under the caller's policy; stored text,
      // totals and commands never leave for a scoped reader.
      const visible = (await resolveScopedFindings(ctx.engine, allFindings, await readPolicyOpts(ctx, readScope), floor)).filter(matches);
      return {
        run_id: latest.run_id,
        ran_at: latest.ran_at,
        contradictions: visible.slice(0, limit),
        total_visible: visible.length,
      };
    }
    // This branch is trusted, unscoped and unfloored. Apply the requested
    // display filters before the limit.
    const kept = allFindings.filter(matches).slice(0, limit);
    return {
      run_id: latest.run_id,
      ran_at: latest.ran_at,
      contradictions: kept,
      // Trusted unscoped callers retain the complete local run count.
      total_in_run: allFindings.length,
    };
  },
  cliHints: { name: 'find-contradictions' },
};

const find_trajectory: Operation = {
  name: 'find_trajectory',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: FIND_TRAJECTORY_DESCRIPTION,
  scope: 'read',
  // localOnly intentionally NOT set — federated OAuth clients should be
  // able to query trajectories for entities in their scope. Visibility
  // filtering (D-CDX-1) inside the engine restricts remote callers to
  // visibility='world' facts.
  params: {
    entity_slug: {
      type: 'string',
      description: 'Required. Entity slug to chart (e.g. "companies/acme-example", "people/alice-example").',
    },
    metric: {
      type: 'string',
      description: 'Optional. Filter to a single canonical metric (e.g. "mrr", "arr", "team_size"). When omitted, all metrics return.',
    },
    kind: {
      type: 'string',
      enum: ['metric', 'event', 'all'],
      description: 'Optional. Filter by row shape: "metric" (typed-claim rows only), "event" (event_type rows only), or "all" (default). v0.40.2.0+.',
    },
    since: {
      type: 'string',
      description: 'Optional lower bound on valid_from (YYYY-MM-DD or ISO).',
    },
    until: {
      type: 'string',
      description: 'Optional upper bound on valid_from (YYYY-MM-DD or ISO).',
    },
    limit: {
      type: 'number',
      description: 'Max points returned. Default 100, max 500.',
    },
  },
  handler: async (ctx, p) => {
    if (typeof p.entity_slug !== 'string' || !p.entity_slug.trim()) {
      throw invalidParam(ctx, 'find_trajectory', 'entity_slug', 'find_trajectory requires entity_slug (string)', { example: 'people/alice-example' });
    }
    const metric = typeof p.metric === 'string' ? p.metric : undefined;
    const kind = (p.kind === 'metric' || p.kind === 'event' || p.kind === 'all')
      ? (p.kind as 'metric' | 'event' | 'all')
      : undefined;
    const since  = typeof p.since  === 'string' ? p.since  : undefined;
    const until  = typeof p.until  === 'string' ? p.until  : undefined;
    const limit  = typeof p.limit  === 'number' ? p.limit  : undefined;
    const scope = sourceScopeOpts(ctx);
    const { resolveExcludePrivatePages, worldOnlyFacts } = await import('../search/private-visibility.ts');

    // D-CDX-1: the engine filters visibility in SQL. GST-2951: world-only for every remote caller but the brain owner,
    // as recall and think's trajectory (worldOnlyFacts); page rules still apply through excludePrivate.
    const points = await ctx.engine.findTrajectory({
      entitySlug: p.entity_slug,
      ...scope,
      remote: worldOnlyFacts(ctx.remote),
      excludePrivate: await resolveExcludePrivatePages(ctx.engine, ctx.remote),
      metric,
      kind,
      since,
      until,
      limit,
    });

    const { computeTrajectoryStats, TRAJECTORY_SCHEMA_VERSION } = await import('../trajectory.ts');
    const { regressions, drift_score } = computeTrajectoryStats(points);

    // Engine result includes raw embeddings (Float32Array); strip those
    // before sending over MCP — they're bulky binary noise that consumers
    // never need at this layer.
    // v0.40.2.0: event_type surfaces on the wire so remote callers (thin-
    // client think, founder-scorecard) see the event-shaped rows.
    const wirePoints = points.map(pt => ({
      fact_id: pt.fact_id,
      valid_from: pt.valid_from.toISOString().slice(0, 10),
      metric: pt.metric,
      value: pt.value,
      unit: pt.unit,
      period: pt.period,
      event_type: pt.event_type,
      text: pt.text,
      source_session: pt.source_session,
      source_markdown_slug: pt.source_markdown_slug,
    }));

    return {
      points: wirePoints,
      regressions,
      drift_score,
      schema_version: TRAJECTORY_SCHEMA_VERSION,
    };
  },
  cliHints: { name: 'find-trajectory' },
};

export { volunteer_context, find_experts, find_contradictions, find_trajectory };