Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.3 KB
Raw Blame
/**
 * Per-initialize inputs for the generated MCP instructions (agent operator
 * contract v1, F1): the caller's callable tool names (the tools/list
 * predicate) and the readiness tail (config plane + the probed tier within
 * its 250 ms best-effort bound; HTTP gets the redacted view). Every failure
 * degrades to "no tail" — the handshake never waits on or fails over it.
 */
import type { BrainEngine } from '../core/engine.ts';
import type { GBrainConfig } from '../core/config.ts';
import type { AuthInfo, OperationMeta } from '../core/ops/contract.ts';
import { opAllowedForBoundClient } from '../core/ops/context.ts';
import { isCallable, publishGatesFromDisabled } from '../core/ops/callable.ts';
import { configReadiness, probedReadiness, readinessHttpView, readinessTail, type ReadinessCache, type ReadinessEntry } from '../core/readiness.ts';
import { isEngineDegraded } from '../core/degraded-marker.ts';
import { disabledOpsForPublishGates } from './publish-gates.ts';
import type { InstructionTools } from './instructions.ts';
import { advertisedOps, clientAdvertisedSurface } from './surface.ts';

/** Readiness entries the instructions tail may name, most limiting first. */
const TAIL_PRIORITY = ['embeddings', 'chat_llm', 'migrations', 'worker', 'facts_drain', 'local_transcripts'] as const;

/** Config plane + probed tier (≤ 250 ms), ordered by TAIL_PRIORITY; [] on any failure. */
export async function instructionReadiness(
  engine: BrainEngine, config: GBrainConfig | null | undefined, transport: 'stdio' | 'http', cache?: ReadinessCache,
): Promise<ReadinessEntry[]> {
  if (!config) return [];
  try {
    const entries = [...configReadiness(config, { transport }).entries];
    if (!isEngineDegraded(engine)) entries.push(...(await readinessTail(engine, cache ? { cache } : {}) ?? []));
    const ranked = TAIL_PRIORITY.flatMap(cap => entries.filter(e => e.capability === cap));
    return transport === 'http' ? readinessHttpView(ranked) : ranked;
  } catch {
    return [];
  }
}

/** HTTP (OAuth and legacy bearer): the same filters tools/list applies, publish gates read on initialize. */
export async function httpInstructionTools(
  engine: BrainEngine, config: GBrainConfig | null | undefined,
  opts: { ops: readonly OperationMeta[]; surface: 'verbs' | 'starter' | 'full'; auth: AuthInfo; allowedOps?: ReadonlySet<string>; cache?: ReadinessCache; advertise?: 'verbs' | 'starter' | 'full' | null },
): Promise<InstructionTools> {
  const gateDisabled = await disabledOpsForPublishGates(engine, config ?? undefined).catch(() => new Set(opts.ops.map(o => o.name)));
  const publishGates = publishGatesFromDisabled(opts.ops, gateDisabled);
  const names = new Set(opts.ops.filter(op =>
    isCallable(op, { transport: 'http', surface: opts.surface, scopes: opts.auth.scopes, publishGates, allowedOps: opts.allowedOps })
    && opAllowedForBoundClient(opts.auth, op)).map(op => op.name));
  const callable = opts.ops.filter(op => names.has(op.name));
  const listed = advertisedOps(callable, opts.surface, await clientAdvertisedSurface(opts.auth, engine, config, opts.advertise ?? null));
  const listedNames = new Set(listed.map(op => op.name));
  return { callable: n => listedNames.has(n), readiness: await instructionReadiness(engine, config, 'http', opts.cache), hiddenCallable: callable.length - listed.length };
}

/**
 * F2: `gbrain://capabilities` on stdio — every readiness entry (config plane +
 * probed tier, 60 s cache) and the real worker status from the worker probe
 * (it replaces the old constant `unknown`).
 */
export async function stdioCapabilityReadiness(engine: BrainEngine, config: GBrainConfig | null | undefined): Promise<{
  readiness: ReadinessEntry[]; worker: { status: string; reason?: string; why?: string };
}> {
  if (!config) return { readiness: [], worker: { status: 'unknown', reason: 'not_configured' } };
  const readiness = [...configReadiness(config, { transport: 'stdio' }).entries];
  try {
    if (!isEngineDegraded(engine)) readiness.push(...await probedReadiness(engine));
  } catch { /* the probed tier is best-effort */ }
  const w = readiness.find(e => e.capability === 'worker');
  return { readiness, worker: w ? { status: w.state, reason: w.reason, why: w.why } : { status: 'unknown', reason: isEngineDegraded(engine) ? 'engine_unreachable' : 'probe_failed' } };
}