Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
18.1 KB
Raw Blame
/**
 * Code-intelligence operation cluster — pure move from operations.ts
 * (v0.46.x tranche 3): the v0.34 Cathedral III MCP wrappers (code_callers /
 * code_callees / code_def / code_refs), the W3 recursive code_blast +
 * code_flow, and the W3b code_traversal_cache_clear admin op. Op consts stay
 * module-private; `codeIntelOperations` 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 { opError, type OperationError } from './contract.ts';
import { routeCodeIntelScope, readPolicyOpts } from './context.ts';
import { hostOnlyError } from './op-fix.ts';
import { isValidSourceId } from '../source-id.ts';
import type { WalkResult } from '../code-intel/recursive-walk.ts';
import {
  CODE_CALLERS_DESCRIPTION,
  CODE_CALLEES_DESCRIPTION,
  CODE_DEF_DESCRIPTION,
  CODE_REFS_DESCRIPTION,
} from '../operations-descriptions.ts';

// ──────────────────────────────────────────────────────────────────────────────
// v0.34 Cathedral III — code-intelligence ops (MCP-exposed).
//
// Pre-v0.34 code-callers / code-callees / code-def / code-refs lived only in
// the CLI_ONLY set at cli.ts:30 — agents calling gbrain via MCP couldn't reach
// them and fell through to text search. These wrappers expose the existing
// engine + library functions to the MCP surface with resolver-grade
// descriptions (operations-descriptions.ts) so agents route to them
// automatically during plan-mode.
//
// All four are scope:'read'. Source-scoped via ctx.sourceId when set.
// Both `source_id` and `all_sources` are params so per-call overrides work.
// ──────────────────────────────────────────────────────────────────────────────

const code_callers: Operation = {
  name: 'code_callers',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: CODE_CALLERS_DESCRIPTION,
  params: {
    symbol: { type: 'string', required: true, description: 'Symbol to find callers of (bare or qualified name).' },
    limit: { type: 'number', description: 'Max edges returned. Default 100.' },
    source_id: { type: 'string', description: "Scope to a single source. Defaults to ctx.sourceId; '__all__' spans every source for trusted local callers, your granted sources for remote callers." },
    all_sources: { type: 'boolean', description: 'Span sources (equivalent to source_id=__all__): every source locally, your grant remotely.' },
  },
  scope: 'read',
  handler: async (ctx, p) => {
    const symbol = p.symbol as string;
    const limit = (p.limit as number) ?? 100;
    const sourceIdParam = typeof p.source_id === 'string' ? p.source_id : undefined;
    // Single trust+grant resolver + federated code-source re-route (see
    // routeCodeIntelScope): remote callers can't span sources outside their
    // grant, and `__all__` collapses to their grant (not the whole brain).
    const { allSources, sourceId } = await routeCodeIntelScope(ctx, sourceIdParam, p.all_sources === true, 'code_callers');
    const edges = await ctx.engine.getCallersOf(symbol, {
      limit,
      allSources,
      sourceId,
    });
    const { resolveCodeReadiness } = await import('../code-graph-readiness.ts');
    // #4352: thread trust — the out_of_scope brain-wide rerun is local-only.
    const readiness = await resolveCodeReadiness(ctx.engine, {
      kind: 'edge', count: edges.length, sourceId, allSources, remote: ctx.remote,
    });
    return {
      symbol, count: edges.length, status: readiness.status, ready: readiness.ready,
      // #3707: out_of_scope names the empty scope so a federated client can see
      // "grant problem", not "graph never built".
      ...(readiness.scoped_source_id ? { scoped_source_id: readiness.scoped_source_id } : {}),
      callers: edges,
    };
  },
  cliHints: { name: 'code_callers', hidden: true },
};

const code_callees: Operation = {
  name: 'code_callees',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: CODE_CALLEES_DESCRIPTION,
  params: {
    symbol: { type: 'string', required: true, description: 'Symbol to find callees of (bare or qualified name).' },
    limit: { type: 'number', description: 'Max edges returned. Default 100.' },
    source_id: { type: 'string', description: "Scope to a single source. Defaults to ctx.sourceId; '__all__' spans every source for trusted local callers, your granted sources for remote callers." },
    all_sources: { type: 'boolean', description: 'Span sources: every source locally, your grant remotely.' },
  },
  scope: 'read',
  handler: async (ctx, p) => {
    const symbol = p.symbol as string;
    const limit = (p.limit as number) ?? 100;
    const sourceIdParam = typeof p.source_id === 'string' ? p.source_id : undefined;
    // Single trust+grant resolver + federated re-route (see code_callers).
    const { allSources, sourceId } = await routeCodeIntelScope(ctx, sourceIdParam, p.all_sources === true, 'code_callees');
    const edges = await ctx.engine.getCalleesOf(symbol, {
      limit,
      allSources,
      sourceId,
      bareFallback: true, // #4670: honor the documented "bare or qualified" contract
    });
    const { resolveCodeReadiness } = await import('../code-graph-readiness.ts');
    // #4352: thread trust — see code_callers.
    const readiness = await resolveCodeReadiness(ctx.engine, {
      kind: 'edge', count: edges.length, sourceId, allSources, remote: ctx.remote,
    });
    return {
      symbol, count: edges.length, status: readiness.status, ready: readiness.ready,
      // #3707: see code_callers.
      ...(readiness.scoped_source_id ? { scoped_source_id: readiness.scoped_source_id } : {}),
      callees: edges,
    };
  },
  cliHints: { name: 'code_callees', hidden: true },
};

const code_def: Operation = {
  name: 'code_def',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: CODE_DEF_DESCRIPTION,
  params: {
    symbol: { type: 'string', required: true, description: 'Symbol name (bare token; e.g., parseMarkdown, BrainEngine).' },
    limit: { type: 'number', description: 'Max definition sites returned. Default 20.' },
    lang: { type: 'string', description: "Filter by content_chunks.language (e.g. 'typescript', 'python')." },
  },
  scope: 'read',
  handler: async (ctx, p) => {
    const { findCodeDef } = await import('../../commands/code-def.ts');
    const policy = await readPolicyOpts(ctx, ctx.remote === false ? {} : undefined);
    const defs = await findCodeDef(ctx.engine, p.symbol as string, {
      ...policy,
      limit: (p.limit as number) ?? 20,
      language: (p.lang as string) || undefined,
    });
    const { resolveCodeReadiness, readinessHint } = await import('../code-graph-readiness.ts');
    const readiness = await resolveCodeReadiness(ctx.engine, { ...policy, remote: ctx.remote, kind: 'symbol', count: defs.length });
    return { symbol: p.symbol as string, count: defs.length, status: readiness.status, ready: readiness.ready, hint: readinessHint(readiness), defs };
  },
  cliHints: { name: 'code_def', hidden: true },
};

const code_refs: Operation = {
  name: 'code_refs',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: CODE_REFS_DESCRIPTION,
  params: {
    symbol: { type: 'string', required: true, description: 'Symbol to find references to.' },
    limit: { type: 'number', description: 'Max references returned. Default 50.' },
    lang: { type: 'string', description: "Filter by content_chunks.language." },
  },
  scope: 'read',
  handler: async (ctx, p) => {
    const { findCodeRefs } = await import('../../commands/code-refs.ts');
    const policy = await readPolicyOpts(ctx, ctx.remote === false ? {} : undefined);
    const refs = await findCodeRefs(ctx.engine, p.symbol as string, {
      ...policy,
      limit: (p.limit as number) ?? 50,
      language: (p.lang as string) || undefined,
    });
    const { resolveCodeReadiness, readinessHint } = await import('../code-graph-readiness.ts');
    const readiness = await resolveCodeReadiness(ctx.engine, { ...policy, remote: ctx.remote, kind: 'symbol', count: refs.length });
    return { symbol: p.symbol as string, count: refs.length, status: readiness.status, ready: readiness.ready, hint: readinessHint(readiness), refs };
  },
  cliHints: { name: 'code_refs', hidden: true },
};

// --- v0.34 W3: recursive code_blast + code_flow ---

/**
 * Stamp the same typed readiness contract code_callers/callees/def/refs carry
 * onto a recursive walk result. Without it a bare `{result:"not_found"}` (or an
 * `ok` walk with zero nodes) conflates a genuine miss with an unbuilt or
 * still-indexing graph, and agents read absence of evidence as "no blast
 * radius". Runs AFTER the traversal cache so readiness is never cached.
 * `unsupported_language` is left untouched — it says nothing about the graph.
 * `ambiguous` (2+ candidates) short-circuits to ready without a query.
 */
async function attachWalkReadiness(ctx: OperationContext, walk: WalkResult, sourceId: string | undefined) {
  if (walk.result === 'unsupported_language') return walk;
  const count = walk.result === 'ok'
    ? walk.depth_groups.reduce((total, group) => total + group.nodes.length, 0)
    : walk.result === 'ambiguous' ? walk.candidates.length : 0;
  const { resolveCodeReadiness } = await import('../code-graph-readiness.ts');
  // not_found = the seed symbol never resolved → symbol grain; anything else
  // is about edge resolution → edge grain. Trust threaded like the siblings.
  const readiness = await resolveCodeReadiness(ctx.engine, {
    kind: walk.result === 'not_found' ? 'symbol' : 'edge', count, sourceId, remote: ctx.remote,
  });
  return {
    ...walk,
    status: readiness.status,
    ready: readiness.ready,
    ...(readiness.scoped_source_id ? { scoped_source_id: readiness.scoped_source_id } : {}),
  };
}

const code_blast: Operation = {
  name: 'code_blast',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: 'BEFORE editing any function, run code_blast with the symbol name to surface every transitive caller grouped by depth (direct → 2-hop → 3-hop). Use this during plan-mode to size the change. Returns up to 200 nodes. Trust an empty/not_found result only when ready=true; ready=false means impact is unknown and requires a safe fallback. Returns: {result, status, ready, depth_groups?, truncation?, cycles_detected?, did_you_mean?, candidates?}. Example ok: {result:"ok", status:"ready", ready:true, depth_groups:[{depth:1, nodes:[{symbol,chunk_id}], confidence:0.77}], truncation:"none"}.',
  params: {
    symbol: { type: 'string', required: true, description: 'Bare or qualified symbol name (e.g. "performSync" or "src/foo::performSync")' },
    depth: { type: 'number', description: 'Hop cap (default 5, max 8)' },
    max_nodes: { type: 'number', description: 'Result-set cap (default 200)' },
    exact: { type: 'boolean', description: 'Skip bare-name disambiguation; treat symbol as exact qualified name' },
    source_id: { type: 'string', description: 'Source to traverse. Defaults to ctx.sourceId; federated clients with multiple granted sources must specify one.' },
  },
  scope: 'read',
  handler: async (ctx, p) => {
    const { runRecursiveWalk } = await import('../code-intel/recursive-walk.ts');
    const symbol = p.symbol as string;
    const depth = Math.min((p.depth as number) ?? 5, 8);
    const max_nodes = Math.min((p.max_nodes as number) ?? 200, 200);
    const exact = (p.exact as boolean) ?? false;
    // Single trust+grant resolver: a remote federated client can't traverse a
    // source outside its grant (pre-fix this scoped by bare ctx.sourceId only).
    // Falls back to ctx.sourceId (a required string) for the trusted-local case,
    // exactly preserving pre-fix local behavior.
    const { sourceId: scopedSourceId } = await routeCodeIntelScope(ctx, typeof p.source_id === 'string' ? p.source_id : undefined, false, 'code_blast');
    const sourceId = scopedSourceId ?? ctx.sourceId;
    const walk = await runRecursiveWalk(ctx.engine, symbol, {
        direction: 'callers',
        depth,
        maxNodes: max_nodes,
        sourceId,
        exact,
      });
    return attachWalkReadiness(ctx, walk, sourceId);
  },
  cliHints: { name: 'code_blast', hidden: true },
};

const code_flow: Operation = {
  name: 'code_flow',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: 'When tracing how a request flows through the codebase from entry point to side effect (DB write, HTTP call, file I/O), run code_flow from the entry point. Returns ordered execution chain with terminal-node tags. Returns: same envelope as code_blast plus terminal_nodes: [{symbol, sink_kind}] where sink_kind ∈ "db_call"|"http_call"|"file_io"|"process_exec"|"unknown".',
  params: {
    entry_point: { type: 'string', required: true, description: 'Entry-point symbol name (bare or qualified)' },
    depth: { type: 'number', description: 'Hop cap (default 8, max 12)' },
    max_nodes: { type: 'number', description: 'Result-set cap (default 200)' },
    exact: { type: 'boolean', description: 'Skip bare-name disambiguation' },
    source_id: { type: 'string', description: 'Source to traverse. Defaults to ctx.sourceId; federated clients with multiple granted sources must specify one.' },
  },
  scope: 'read',
  handler: async (ctx, p) => {
    const { runRecursiveWalk } = await import('../code-intel/recursive-walk.ts');
    const symbol = p.entry_point as string;
    const depth = Math.min((p.depth as number) ?? 8, 12);
    const max_nodes = Math.min((p.max_nodes as number) ?? 200, 200);
    const exact = (p.exact as boolean) ?? false;
    // Single trust+grant resolver (see code_blast).
    const { sourceId: scopedSourceId } = await routeCodeIntelScope(ctx, typeof p.source_id === 'string' ? p.source_id : undefined, false, 'code_flow');
    const sourceId = scopedSourceId ?? ctx.sourceId;
    const walk = await runRecursiveWalk(ctx.engine, symbol, {
        direction: 'callees',
        depth,
        maxNodes: max_nodes,
        sourceId,
        exact,
      });
    return attachWalkReadiness(ctx, walk, sourceId);
  },
  cliHints: { name: 'code_flow', hidden: true },
};

// --- v0.34 W3b: code_traversal_cache admin op ---

const code_traversal_cache_clear: Operation = {
  name: 'code_traversal_cache_clear',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'Clear cached code_blast / code_flow traversal results. Source-scoped by default; pass all_sources=true to wipe everything (destructive: it is guarded).',
  params: {
    source_id: { type: 'string', description: 'Source to clear. Required unless all_sources=true.' },
    all_sources: { type: 'boolean', description: 'Wipe cache across every source. Explicit opt-out of source-scoping.' },
  },
  mutating: true,
  scope: 'admin',
  localOnly: true,
  handler: async (ctx, p) => {
    // INTENTIONAL exemption from resolveRequestedScope: this is a localOnly
    // admin/destructive op with its own D8 all_sources guard. The read-side
    // trust+grant resolver does not apply here (no remote caller reaches it).
    const { clearTraversalCache } = await import('../code-intel/traversal-cache.ts');
    const sourceId = (p.source_id as string | undefined) ?? ctx.sourceId;
    const allSources = (p.all_sources as boolean) ?? false;
    if (ctx.dryRun) {
      return { dry_run: true, action: 'code_traversal_cache_clear', source_id: sourceId, all_sources: allSources };
    }
    const deleted = await clearTraversalCache(ctx.engine, {
      sourceId: allSources ? undefined : sourceId,
      allSources,
    });
    return { deleted, source_id: allSources ? null : sourceId, all_sources: allSources };
  },
  cliHints: { name: 'code_traversal_cache_clear', hidden: true },
};

const SYMBOL_ARG = /^[A-Za-z_$][\w$.:/-]{0,199}$/;

/**
 * B6: remote code reads are suspended; the same read runs through the
 * trusted local `gbrain call` lane on the brain host. The symbol and source
 * are interpolated only when they match strict id shapes.
 */
const CODE_READ_FOLLOW_UP = 'garrytan/gbrain#5052';

function codeReadRefusal(ctx: OperationContext, op: Operation, params: Record<string, unknown>): OperationError {
  const message = `${op.name} is temporarily unavailable to agent callers: remote code reads stay suspended until they support the remote read policy (follow-up: ${CODE_READ_FOLLOW_UP}). `
    + 'Code search (search, query) still works here.';
  const key = 'entry_point' in op.params ? 'entry_point' : 'symbol';
  const symbol = params[key];
  if (typeof symbol !== 'string' || !SYMBOL_ARG.test(symbol)) {
    return opError('permission_denied', message,
      `Use search or query for code text now, or ask the user to run ${op.name} with the trusted local CLI on the brain host (gbrain call ${op.name} '<params_json>').`);
  }
  const source = typeof params.source_id === 'string' && isValidSourceId(params.source_id) ? ['--source', params.source_id] : [];
  return hostOnlyError(ctx, 'permission_denied', message,
    ['gbrain', 'call', ...source, op.name, JSON.stringify({ [key]: symbol })],
    `Symbol definitions, references, callers, callees, blast radius and flow run only through the trusted local CLI on the brain host until remote code reads return (${CODE_READ_FOLLOW_UP}).`);
}

const codeReadOperations: Operation[] = [
  code_callers, code_callees, code_def, code_refs,
  code_blast, code_flow,
];

// Raw code fragments and cached traversals do not yet support the complete
// remote read policy. Suspend this optional surface before touching storage.
export const codeIntelOperations: Operation[] = [
  ...codeReadOperations.map((op): Operation => ({
    ...op,
    description: `${op.description} Temporarily available only to trusted local CLI callers; agent-facing code reads are suspended.`,
    handler: async (ctx, params) => {
      if (ctx.remote !== false) throw codeReadRefusal(ctx, op, params);
      return op.handler(ctx, params);
    },
  })),
  code_traversal_cache_clear,
];