Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
28.3 KB
Raw Blame
/**
 * One turn: `resolveSkills(input)` reads the catalog index(es), ranks the
 * message, applies the session's no-repeat and budget rules and renders the
 * block. It never rebuilds, never touches the network, a model or a brain,
 * and its output outside `meta` is byte-identical for the same index,
 * input and session state. Committing the session state is the caller's
 * second step (`result.commit()`), taken only after the block was
 * delivered.
 *
 * Session rules (one state per session across every merged catalog):
 *  - k shrinks as the budget drains: top_k, then at most 3 once half is
 *    spent, then 1 once 80% is spent;
 *  - once half is spent, only a turn whose top result matched on name,
 *    triggers or routing (or names a skill explicitly) spends any of it;
 *  - a skill suggested once is not suggested again, except once more when
 *    it ranks first with a name, trigger or routing match at least 10 turns
 *    later, or whenever the turn names it explicitly;
 *  - when nothing new is in the top k the block is empty; when no new line
 *    fits what is left of the budget, budget_exhausted is true, but a skill
 *    the turn names explicitly still gets its line (its tokens still count).
 *
 * min_match_strength drops weaker matches before the cut to k, so a floor
 * never shrinks the block below what the stronger matches fill: it filters
 * candidates and does not gate the block. top_gate (TOP_GATE_DEFAULT unless
 * set; 0 turns it off) does: when the best skill the block would show (after exclude,
 * min_match_strength, session dedupe and pacing) scores below it over its
 * catalog's maxIdf, the block is empty (block_reason weak_top_match), unless
 * the turn names a skill. A message that matches no catalog word falls back to
 * previous_user_message.
 */
import { existsSync, readFileSync, statSync } from 'node:fs';
import { createHash } from 'node:crypto';
import { join } from 'node:path';
import { VERSION } from '../../../version.ts';
import { BLOCK_TOKEN_CAP, BLOCK_TOKENIZER, HARNESSES, renderBlock, type BlockLine } from './block.ts';
import type { BuildReceipt } from './build.ts';
import { dirFingerprintSlice, listCatalogs, readReceipt } from './catalog-files.ts';
import { readResolverSettings, type ResolverSettings, validateSessionTokenBudget } from './config.ts';
import { ResolverError } from './errors.ts';
import { appendDailyLogSync, RESOLVER_LOG } from './daily-log.ts';
import { ensureDir, writeFileAtomic } from './fsutil.ts';
import { EXCLUDE_MAX, MATCH_STRENGTHS, type MatchStrength, STRENGTH_FIELDS, TOP_GATE_DEFAULT, TOP_GATE_MAX, TOP_K_DEFAULT, TOP_K_MAX } from './limits.ts';
import { IndexReader, RANKER_ID, RANKER_VERSION } from './index-format.ts';
import { assertCatalogName, catalogFile, logsDir, resolverHome } from './paths.ts';
import { isAcknowledgement, maxIdf, mentionsSkill, rankIndex, reasonText, type RankResult } from './rank.ts';
import { commitSession, freshState, loadSession, sessionKey, type SessionState, type TurnDelta } from './session.ts';

export const SCHEMA_VERSION = 1;
export const MESSAGE_CAP_BYTES = 8192;
export { EXCLUDE_MAX, MATCH_STRENGTHS, TOP_K_DEFAULT, TOP_K_MAX, type MatchStrength };
export const RESUGGEST_AFTER_TURNS = 10;
export const STAT_CHECK_INTERVAL_MS = 60_000;
/** Stat calls one turn may spend on the freshness sweep; a larger catalog is swept over several turns. */
export const STAT_CHECK_SLICE = 1024;

export interface TurnInput {
  message: string;
  previous_user_message?: string;
  session_id?: string;
  harness?: string;
  top_k?: number;
  exclude?: string[];
  shadow?: boolean;
  expected_catalog_hash?: string;
  reset_session?: boolean;
  min_match_strength?: MatchStrength;
  top_gate?: number;
}

export interface Suggestion { id: string; name: string; score: number; summary: string; reason: string; match_strength: MatchStrength; path?: string; catalog: string }
export interface TurnError { code: string; message: string; fix: { suggestion: string; command?: string } }
/** Why a block is empty; null when it has a suggestion. */
export type BlockReason = 'ack' | 'no_match' | 'filtered' | 'weak_top_match' | 'deduped' | 'paced' | 'budget_exhausted' | 'shadow' | 'error';
export interface TurnOutput {
  schema_version: 1;
  gbrain_version: string;
  catalog: string | null;
  catalog_hash: string | null;
  index_hash: string | null;
  ranker: { id: string; version: number; variant: string | null; k: number };
  no_skill: boolean;
  no_skill_reason: 'ack' | 'no_match' | null;
  budget_exhausted: boolean;
  block_reason: BlockReason | null;
  suggestions: Suggestion[];
  block: string;
  block_tokens: number;
  tokenizer: string;
  deduped: string[];
  shadow: boolean;
  error?: TurnError;
  meta: { timing_ms: number; index_age_s: number | null; index_stale: boolean };
}

export interface ResolveOptions {
  home?: string;
  catalogs?: string[];
  failOpen?: boolean;
  deadlineMs?: number;
  sessionTokenBudget?: number;
  loadHint?: string;
  namesOnly?: boolean;
  explainTarget?: string;
  env?: NodeJS.ProcessEnv;
  now?: () => number;
}

export interface Explain {
  target: string;
  indexed: boolean;
  catalog: string | null;
  rank: number | null;
  score: number | null;
  fields: Record<string, string[]>;
  excluded: boolean;
  deduped: boolean;
  in_block: boolean;
  skip_reason: string | null;
  session: { turn: number; spent: number; budget: number; remaining: number } | null;
}

export interface ResolveResult {
  output: TurnOutput;
  /** Shadow mode: the output the on arm would have produced (block included); `output` injects nothing. */
  shadowOutput?: TurnOutput;
  explain?: Explain;
  /** Set when a runtime error was turned into an empty result (failOpen). */
  failOpen?: boolean;
  /** Commit this turn's session state; call only after the block was delivered. */
  commit(): Promise<boolean>;
  /** What commit() would apply, for a caller that commits on another thread (the hook lane): null when there is no session to commit. */
  pending?: { key: string; delta: TurnDelta } | null;
}

const sha = (s: string) => createHash('sha256').update(s).digest('hex');
const round4 = (x: number) => Math.round(x * 1e4) / 1e4;

function invalid(message: string, suggestion: string): ResolverError {
  return new ResolverError('skill_resolve_invalid_input', message, { suggestion });
}

function capUtf8(s: string, max: number): string {
  const b = Buffer.from(s, 'utf8');
  return b.length <= max ? s : b.subarray(0, max).toString('utf8').replace(/\uFFFD+$/, '');
}

export function normalizeTurnInput(raw: unknown): Required<Pick<TurnInput, 'message' | 'top_k' | 'exclude' | 'shadow' | 'reset_session'>> & TurnInput {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid('The turn input must be a JSON object.', 'Send {"message": "..."} (see docs/schemas/skill-resolver.v1.turn-input.json).');
  const o = raw as Record<string, unknown>;
  const known = new Set(['message', 'previous_user_message', 'session_id', 'harness', 'top_k', 'exclude', 'shadow', 'expected_catalog_hash', 'reset_session', 'min_match_strength', 'top_gate']);
  const extra = Object.keys(o).find(k => !known.has(k));
  if (extra) throw invalid(`Unknown turn input field "${extra}".`, 'Use only the fields in docs/schemas/skill-resolver.v1.turn-input.json.');
  if (typeof o.message !== 'string') throw invalid('message is required and must be a string.', 'Send the user message as "message".');
  if (o.previous_user_message !== undefined && typeof o.previous_user_message !== 'string') throw invalid('previous_user_message must be a string.', 'Send a string or omit it.');
  if (o.session_id !== undefined && (typeof o.session_id !== 'string' || !/^[\x21-\x7e]{1,256}$/.test(o.session_id))) throw invalid('session_id must be 1-256 visible ASCII characters.', "Pass the harness's session id.");
  if (o.harness !== undefined && !(HARNESSES as readonly unknown[]).includes(o.harness)) throw invalid(`harness must be one of ${HARNESSES.join(', ')}.`, 'Pass a supported harness, or omit it and use --load-hint.');
  if (o.top_k !== undefined && (!Number.isInteger(o.top_k) || (o.top_k as number) < 1 || (o.top_k as number) > TOP_K_MAX)) throw invalid(`top_k must be an integer from 1 to ${TOP_K_MAX}.`, 'Omit it for the default of 5.');
  if (o.exclude !== undefined && (!Array.isArray(o.exclude) || o.exclude.length > EXCLUDE_MAX || o.exclude.some(x => typeof x !== 'string' || x.length > 256))) throw invalid(`exclude must be at most ${EXCLUDE_MAX} skill ids.`, 'Pass the ids already loaded this turn.');
  if (o.shadow !== undefined && typeof o.shadow !== 'boolean') throw invalid('shadow must be a boolean.', 'Pass true or false.');
  if (o.reset_session !== undefined && typeof o.reset_session !== 'boolean') throw invalid('reset_session must be a boolean.', 'Pass true on the first turn after a compaction.');
  if (o.min_match_strength !== undefined && !(MATCH_STRENGTHS as readonly unknown[]).includes(o.min_match_strength)) throw invalid(`min_match_strength must be one of ${MATCH_STRENGTHS.join(', ')}.`, 'Omit it to keep every match, or pass description to drop body-only matches.');
  if (o.top_gate !== undefined && (typeof o.top_gate !== 'number' || !Number.isFinite(o.top_gate) || o.top_gate < 0 || o.top_gate > TOP_GATE_MAX)) throw invalid(`top_gate must be a number from 0 to ${TOP_GATE_MAX}.`, 'Omit it for the default gate, or pass 0 to turn the gate off.');
  if (o.expected_catalog_hash !== undefined && (typeof o.expected_catalog_hash !== 'string' || !/^[0-9a-f]{64}$/.test(o.expected_catalog_hash))) throw invalid('expected_catalog_hash must be a sha256 hex string.', 'Pass the catalog_hash from the build receipt.');
  return {
    message: capUtf8(o.message, MESSAGE_CAP_BYTES),
    ...(typeof o.previous_user_message === 'string' ? { previous_user_message: capUtf8(o.previous_user_message, MESSAGE_CAP_BYTES) } : {}),
    ...(o.session_id !== undefined ? { session_id: o.session_id as string } : {}),
    ...(o.harness !== undefined ? { harness: o.harness as string } : {}),
    top_k: (o.top_k as number | undefined) ?? TOP_K_DEFAULT,
    exclude: (o.exclude as string[] | undefined) ?? [],
    shadow: o.shadow === true,
    reset_session: o.reset_session === true,
    ...(o.expected_catalog_hash !== undefined ? { expected_catalog_hash: o.expected_catalog_hash as string } : {}),
    ...(o.min_match_strength !== undefined ? { min_match_strength: o.min_match_strength as MatchStrength } : {}),
    ...(o.top_gate === undefined ? { top_gate: TOP_GATE_DEFAULT } : o.top_gate ? { top_gate: o.top_gate as number } : {}),
  };
}

/** A catalog's receipt and open index: what a turn reads once per catalog, and what a warm handle keeps between turns. */
export interface OpenedCatalog { name: string; receipt: BuildReceipt; ix: IndexReader; publishing: boolean }
interface Loaded extends OpenedCatalog { stale: string | null }

/** Where a turn gets its settings and catalogs: the cold path reads them every turn, a warm handle (handle.ts) keeps them. */
export interface TurnSource {
  settings(home: string, env?: NodeJS.ProcessEnv): ResolverSettings;
  open(home: string, name: string): OpenedCatalog;
  /** Called once per turn with every catalog it opened. */
  done(opened: OpenedCatalog[]): void;
}

const COLD: TurnSource = { settings: readResolverSettings, open: openCatalogIndex, done: opened => { for (const c of opened) c.ix.close(); } };
const STAT_TIER_KINDS: readonly string[] = ['dir', 'claude_plugins'];

function defaultCatalogs(home: string): string[] {
  const all = listCatalogs(home);
  if (all.length === 1) return all;
  if (all.length === 0) throw new ResolverError('skill_index_missing', 'No skill catalog has been built yet.', { suggestion: 'Build one: gbrain skills index build --catalog <name> --dir <skills dir> (or --bundled, or --from-json <file>).', argv: ['gbrain', 'skills', 'index', 'build', '--help'] });
  throw new ResolverError('skill_catalog_unknown', `Several catalogs exist (${all.join(', ')}); pick one with --catalog.`, { suggestion: `Pass --catalog with one of: ${all.join(', ')}.` }, { catalogs: all.join(',') });
}

/** Read a catalog's receipt and open its index; throws the turn's refusal when either is missing or incompatible. */
export function openCatalogIndex(home: string, name: string): OpenedCatalog {
  let receipt = readReceipt(home, name);
  if (!receipt) {
    if (existsSync(catalogFile(home, name, 'index.bin'))) throw new ResolverError('skill_index_incompatible', `The catalog "${name}" has an index but no readable receipt.`, { suggestion: 'Rebuild it with gbrain skills index build.' }, { catalog: name });
    throw new ResolverError('skill_index_missing', `The catalog "${name}" has not been built.`, { suggestion: `Build it: gbrain skills index build --catalog ${name} --dir <skills dir> (or --bundled, or --from-json <file>).` }, { catalog: name });
  }
  const fix = receipt.build?.rebuild_argv ?? undefined;
  if (receipt.schema_version !== 1 || receipt.ranker?.id !== RANKER_ID || receipt.ranker?.version !== RANKER_VERSION) {
    throw new ResolverError('skill_index_incompatible', `The catalog "${name}" was built by an incompatible gbrain (receipt schema ${receipt.schema_version}, ranker ${receipt.ranker?.id} v${receipt.ranker?.version}).`,
      fix ? { suggestion: 'Rebuild it with the command it was built with.', argv: fix } : { suggestion: 'The adapter that owns this catalog rebuilds it by passing a new snapshot to gbrain skills index build --from-json -.' }, { catalog: name });
  }
  const ix = IndexReader.open(catalogFile(home, name, 'index.bin'), fix);
  let publishing = false;
  try {
    const size = statSync(catalogFile(home, name, 'index.bin')).size;
    if (size !== receipt.index.size) {
      const again = readReceipt(home, name);
      if (again && again.index.size === size) receipt = again; else publishing = true;
    }
  } catch (e) { ix.close(); throw e; }
  return { name, receipt, ix, publishing };
}

/**
 * The turn's staleness verdict for an opened catalog: publishing, a gbrain
 * version skew, or (directory catalogs) one slice of the stat sweep. A stale
 * catalog gbrain can rebuild gets stale.stamp once (no fsync; an existing
 * stamp is left alone); an adapter-owned stdin catalog never does.
 */
function turnStaleness(home: string, c: OpenedCatalog, now: number, autoRebuild: boolean): string | null {
  const { name, receipt } = c;
  let stale: string | null = c.publishing ? 'publishing' : null;
  if (!stale && receipt.gbrain_version !== VERSION) stale = 'gbrain_version_changed';
  if (!stale && STAT_TIER_KINDS.includes(receipt.catalog.source.kind)) {
    const stamp = catalogFile(home, name, 'stat-check');
    let last: { verdict: 'fresh' | 'stale'; cursor: number } | null = null;
    let age = Infinity;
    try { age = now - statSync(stamp).mtimeMs; last = JSON.parse(readFileSync(stamp, 'utf8')); } catch { /* none or unreadable: sweep from the start */ }
    if (last?.verdict === 'stale') stale = 'source_changed';
    else if (!(last?.verdict === 'fresh' && last.cursor === 0 && age < STAT_CHECK_INTERVAL_MS)) {
      const slice = dirFingerprintSlice(home, name, last?.verdict === 'fresh' ? last.cursor : 0, STAT_CHECK_SLICE);
      stale = slice.changed ? 'source_changed' : null;
      try { writeFileAtomic(stamp, JSON.stringify({ verdict: slice.changed ? 'stale' : 'fresh', cursor: slice.changed ? 0 : slice.next })); } catch { /* read-only home: check again next turn */ }
    }
  }
  if (stale && autoRebuild && receipt.build?.rebuild_argv) {
    const stamp = catalogFile(home, name, 'stale.stamp');
    if (!existsSync(stamp)) { try { writeFileAtomic(stamp, `${JSON.stringify({ reason: stale })}\n`); } catch { /* best effort */ } }
  }
  return stale;
}

function emptyOutput(input: { shadow?: boolean }, extra: Partial<TurnOutput>): TurnOutput {
  return {
    schema_version: 1, gbrain_version: VERSION, catalog: null, catalog_hash: null, index_hash: null,
    ranker: { id: RANKER_ID, version: RANKER_VERSION, variant: null, k: 0 },
    no_skill: false, no_skill_reason: null, budget_exhausted: false, block_reason: extra.error ? 'error' : null, suggestions: [], block: '', block_tokens: 0, tokenizer: BLOCK_TOKENIZER,
    deduped: [], shadow: Boolean(input.shadow), meta: { timing_ms: 0, index_age_s: null, index_stale: false }, ...extra,
  };
}

/** The turn output for a runtime error: no suggestions, block "", `error` set. */
export function errorTurnOutput(err: ResolverError, opts: { shadow?: boolean; catalog?: string | null } = {}): TurnOutput {
  const hash = err.code === 'skill_catalog_mismatch' && typeof err.context.catalog_hash === 'string' ? err.context.catalog_hash : null;
  return emptyOutput({ shadow: opts.shadow }, { error: err.toJSON(), catalog: opts.catalog ?? null, catalog_hash: hash });
}

function logUnexpected(home: string, e: unknown): void {
  try {
    const dir = logsDir(home);
    ensureDir(dir);
    const err = e as Error;
    appendDailyLogSync(dir, RESOLVER_LOG, `${JSON.stringify({ at: new Date().toISOString(), version: VERSION, name: err?.name ?? typeof e, stack: String(err?.stack ?? '').split('\n').slice(1, 6).map(l => l.trim()) })}\n`);
  } catch { /* logging never fails a turn */ }
}

/** Resolve one turn. Throws ResolverError on a usage error always, and on a runtime error unless failOpen. */
export async function resolveSkills(rawInput: TurnInput | unknown, opts: ResolveOptions = {}): Promise<ResolveResult> {
  return runTurn(rawInput, opts, COLD);
}

/** One turn over a TurnSource: resolveSkills with the cold source, a warm handle with its own. */
export async function runTurn(rawInput: TurnInput | unknown, opts: ResolveOptions, source: TurnSource): Promise<ResolveResult> {
  const t0 = performance.now();
  const input = normalizeTurnInput(rawInput);
  let home: string;
  try { home = opts.home ?? resolverHome(opts.env); } catch (e) { throw new ResolverError('skill_resolver_config_invalid', (e as Error).message, { suggestion: 'Set GBRAIN_HOME to an absolute path without .. segments, or unset it.' }); }
  try {
    return await resolveInner(input, opts, home, t0, source);
  } catch (e) {
    const err = e instanceof ResolverError ? e : new ResolverError('skill_resolver_internal', 'The skill resolver failed unexpectedly; a scrubbed trace was written under skill-index/logs/.', { suggestion: 'Run gbrain skills index status and report the trace if it repeats.', argv: ['gbrain', 'skills', 'index', 'status', '--json'] });
    if (!(e instanceof ResolverError)) logUnexpected(home, e);
    if (!opts.failOpen || err.usage) throw err;
    const output = errorTurnOutput(err, { shadow: input.shadow, catalog: opts.catalogs?.length === 1 ? opts.catalogs[0]! : null });
    output.meta.timing_ms = round4(performance.now() - t0);
    return { output, failOpen: true, commit: async () => false };
  }
}

async function resolveInner(input: ReturnType<typeof normalizeTurnInput>, opts: ResolveOptions, home: string, t0: number, source: TurnSource): Promise<ResolveResult> {
  const now = (opts.now ?? Date.now)();
  const check = opts.deadlineMs === undefined ? () => {} : () => {
    if (performance.now() - t0 > opts.deadlineMs!) throw new ResolverError('skill_resolve_timeout', `The resolver ran past its ${opts.deadlineMs} ms deadline; nothing was committed.`, { suggestion: 'The turn proceeds without a block; check the index size with gbrain skills index status.' });
  };
  const settings = source.settings(home, opts.env);
  const budget = opts.sessionTokenBudget === undefined ? settings.sessionTokenBudget : validateSessionTokenBudget(opts.sessionTokenBudget, 'sessionTokenBudget');
  const names = opts.catalogs?.length ? [...new Set(opts.catalogs.map(assertCatalogName))] : defaultCatalogs(home);
  const loaded: Loaded[] = [];
  try {
    for (const n of names) { const l: Loaded = { ...source.open(home, n), stale: null }; loaded.push(l); l.stale = turnStaleness(home, l, now, settings.autoRebuild); check(); }
    const single = loaded.length === 1 ? loaded[0]! : null;
    const catalog = loaded.map(l => l.name).join('+');
    const catalogHash = single ? single.receipt.catalog.catalog_hash : sha(JSON.stringify(loaded.map(l => [l.name, l.receipt.catalog.catalog_hash])));
    const indexHash = single ? single.receipt.index.index_hash : sha(JSON.stringify(loaded.map(l => [l.name, l.receipt.index.index_hash])));
    const variant = loaded.map(l => l.receipt.ranker.variant).join('+');
    if (input.expected_catalog_hash !== undefined && input.expected_catalog_hash !== catalogHash) {
      throw new ResolverError('skill_catalog_mismatch', `The catalog "${catalog}" was built from a different skill list than the caller expects (expected ${input.expected_catalog_hash.slice(0, 12)}, index has ${catalogHash.slice(0, 12)}).`,
        { suggestion: 'Rebuild the catalog from the current skill list (an adapter passes its new snapshot to gbrain skills index build --from-json -), then retry.' }, { catalog, catalog_hash: catalogHash });
    }
    const oldest = Math.min(...loaded.map(l => Date.parse(l.receipt.build.built_at)));
    const meta = { timing_ms: 0, index_age_s: Number.isFinite(oldest) ? Math.max(0, Math.floor((now - oldest) / 1000)) : null, index_stale: loaded.some(l => l.stale !== null) };
    const scope = input.shadow ? 'shadow' : 'on';
    const key = input.session_id ? sessionKey(scope, input.harness, input.session_id) : null;
    const state: SessionState = key && !input.reset_session ? loadSession(home, key) : freshState();
    const turnNo = state.turn + 1;
    const spentFrac = budget === 0 ? 1 : state.spent / budget;
    const kEff = spentFrac < 0.5 ? input.top_k : spentFrac < 0.8 ? Math.min(input.top_k, 3) : 1;
    const base: TurnOutput = {
      ...emptyOutput(input, {}), catalog, catalog_hash: catalogHash, index_hash: indexHash,
      ranker: { id: RANKER_ID, version: RANKER_VERSION, variant, k: kEff }, meta, budget_exhausted: budget === 0 || state.spent >= budget,
    };
    const finish = (out: TurnOutput, delta: { tokens: number; suggested: string[]; resuggested: string[] }, explain?: Explain): ResolveResult => {
      out.meta.timing_ms = round4(performance.now() - t0);
      const pending = key ? { key, delta: { ...delta, reset: input.reset_session } } : null;
      const commit = async () => (pending ? commitSession(home, pending.key, pending.delta) : false);
      if (!input.shadow) return { output: out, ...(explain ? { explain } : {}), commit, pending };
      const quiet: TurnOutput = { ...out, block_reason: 'shadow', suggestions: [], block: '', block_tokens: 0, deduped: [], shadow: true };
      return { output: quiet, shadowOutput: { ...out, shadow: true }, ...(explain ? { explain } : {}), commit, pending };
    };

    if (isAcknowledgement(input.message)) return finish({ ...base, no_skill: true, no_skill_reason: 'ack', block_reason: 'ack' }, { tokens: 0, suggested: [], resuggested: [] });

    const rankText = (text: string): RankResult[] => loaded.map(l => { const r = rankIndex(l.ix, text, check); check(); return r; });
    let ranks = rankText(input.message);
    if (ranks.every(r => r.idfSum === 0) && input.previous_user_message?.trim()) ranks = rankText(input.previous_user_message);
    if (ranks.every(r => r.idfSum === 0)) return finish({ ...base, no_skill: true, no_skill_reason: 'no_match', block_reason: 'no_match' }, { tokens: 0, suggested: [], resuggested: [] });

    interface Cand { c: number; doc: number; score: number; id: string; explicit: boolean }
    const metaOf = (c: number, doc: number) => loaded[c]!.ix.meta(doc);
    const strengthOf = (x: Cand): MatchStrength => {
      if (x.explicit) return 'named';
      const fields = ranks[x.c]!.matchedFields(x.doc).fields;
      return STRENGTH_FIELDS.find(f => fields[f]?.length) ?? 'body';
    };
    const excluded = new Set(input.exclude);
    const floor = MATCH_STRENGTHS.indexOf(input.min_match_strength ?? 'body');
    const window: Cand[] = [];
    const seen = new Set<string>();
    const admit = (x: Cand) => {
      seen.add(x.id);
      if (window.length < kEff && !excluded.has(x.id) && MATCH_STRENGTHS.indexOf(strengthOf(x)) <= floor) window.push(x);
    };
    loaded.forEach((_, c) => {
      for (const r of ranks[c]!.ranked) {
        if (!ranks[c]!.nameHits.has(r.doc)) continue;
        const m = metaOf(c, r.doc);
        if (!seen.has(m.id) && mentionsSkill(input.message, m.id, m.name)) admit({ c, doc: r.doc, score: r.score, id: m.id, explicit: true });
      }
    });
    const longest = Math.max(...ranks.map(r => r.ranked.length));
    for (let i = 0; i < longest && window.length < kEff; i++) {
      loaded.forEach((_, c) => {
        const r = ranks[c]!.ranked[i];
        if (!r) return;
        const m = metaOf(c, r.doc);
        if (!seen.has(m.id)) admit({ c, doc: r.doc, score: r.score, id: m.id, explicit: false });
      });
      check();
    }
    const strong = (x: Cand) => x.explicit || ranks[x.c]!.matchedFields(x.doc).strong;
    const picked: Cand[] = [];
    const resuggested: string[] = [];
    const deduped: string[] = [];
    let paced = false;
    if (budget > 0 && window.length && spentFrac >= 0.5 && !strong(window[0]!)) paced = true;
    if (!paced) {
      window.forEach((x, i) => {
        const last = state.last[x.id];
        if (last !== undefined) {
          const again = x.explicit || (i === 0 && strong(x) && turnNo - last >= RESUGGEST_AFTER_TURNS && !state.again[x.id]);
          if (!again) { deduped.push(x.id); return; }
          if (!x.explicit) resuggested.push(x.id);
        }
        picked.push(x);
      });
    }
    const gated = input.top_gate !== undefined && picked.length > 0 && !picked.some(x => x.explicit)
      && Math.max(...picked.map(x => x.score / maxIdf(loaded[x.c]!.ix.n))) < input.top_gate;
    if (gated) picked.length = 0;
    const remaining = Math.max(0, budget - state.spent);
    const lines: BlockLine[] = picked.map(x => {
      const m = metaOf(x.c, x.doc);
      return { id: m.id, name: m.name, summary: m.summary, ...(m.path ? { path: m.path } : {}), namesOnly: Boolean(opts.namesOnly) || loaded[x.c]!.receipt.catalog.hints === 'names_only' };
    });
    let r = renderBlock(lines, { harness: input.harness, loadHint: opts.loadHint, cap: Math.min(BLOCK_TOKEN_CAP, remaining) });
    const exhausted = budget === 0 || remaining === 0 || (picked.length > 0 && r.kept === 0 && remaining < BLOCK_TOKEN_CAP);
    const named = picked.filter(x => x.explicit).length;
    if (budget > 0 && r.kept === 0 && named > 0) r = renderBlock(lines.slice(0, named), { harness: input.harness, loadHint: opts.loadHint, cap: BLOCK_TOKEN_CAP });
    const kept = picked.slice(0, r.kept);
    const suggestions: Suggestion[] = kept.map(x => {
      const m = metaOf(x.c, x.doc);
      const namesOnly = lines.find(l => l.id === m.id)!.namesOnly;
      const fields = ranks[x.c]!.matchedFields(x.doc).fields;
      const match_strength = strengthOf(x);
      return { id: m.id, name: m.name, score: round4(x.score), summary: namesOnly ? '' : m.summary, reason: x.explicit ? `named in the turn; ${reasonText(fields)}` : reasonText(fields), match_strength, ...(m.path ? { path: m.path } : {}), catalog: loaded[x.c]!.name };
    });
    const blockReason: BlockReason | null = suggestions.length ? null : exhausted ? 'budget_exhausted' : gated ? 'weak_top_match' : paced ? 'paced' : window.length ? 'deduped' : 'filtered';
    const out: TurnOutput = { ...base, budget_exhausted: exhausted, block_reason: blockReason, suggestions, block: r.block, block_tokens: r.tokens, deduped };
    let explain: Explain | undefined;
    if (opts.explainTarget !== undefined) {
      const target = opts.explainTarget;
      let found: { c: number; doc: number } | null = null;
      loaded.forEach((l, c) => { if (found) return; for (let d = 0; d < l.ix.n; d++) if (l.ix.meta(d).id === target) { found = { c, doc: d }; break; } });
      const f = found as { c: number; doc: number } | null;
      const pos = f ? ranks[f.c]!.ranked.findIndex(x => x.doc === f.doc) : -1;
      const skip = loaded.map(l => l.receipt.catalog.skipped.find(s => s.id === target)).find(Boolean);
      explain = {
        target, indexed: Boolean(f), catalog: f ? loaded[f.c]!.name : null, rank: pos >= 0 ? pos + 1 : null, score: pos >= 0 ? round4(ranks[f!.c]!.ranked[pos]!.score) : null,
        fields: f ? ranks[f.c]!.matchedFields(f.doc).fields : {}, excluded: excluded.has(target), deduped: deduped.includes(target), in_block: suggestions.some(s => s.id === target),
        skip_reason: skip?.reason ?? null, session: key ? { turn: state.turn, spent: state.spent, budget, remaining } : null,
      };
    }
    return finish(out, { tokens: r.tokens, suggested: kept.map(x => x.id), resuggested: resuggested.filter(id => kept.some(x => x.id === id)) }, explain);
  } finally {
    source.done(loaded);
  }
}