Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.7 KB
Raw Blame
/**
 * mcp-usage.ts — the ONE shared reader over `mcp_request_log` (amendment 30).
 *
 * Consumed by three surfaces that must never disagree on what counts as an
 * "operation call" (each reads it through readClientOpUsageWithCoverage, so a
 * window that reaches back past pruned history says so):
 *   - `gbrain auth clients --usage` (E4, src/commands/auth.ts)
 *   - the advisor starter-fit collector (E3, src/core/advisor/collect-mcp-client-fit.ts)
 *   - `scripts/derive-starter-ops.ts` (amendment 23 / D12)
 *
 * Row hygiene (amendments 23 + 30) — encoded HERE, nowhere else:
 *   - JSON-RPC method rows are NOT op calls: 'tools/list', 'initialize',
 *     'notifications/initialized', 'ping' are dropped.
 *   - The legacy bearer transport (src/mcp/http-transport.ts) logs calls as
 *     'tools/call:<name>' — the prefix is stripped and the row counts as <name>.
 *   - 'surface_change' audit rows (ENG-8, src/core/surface-audit.ts) are
 *     bookkeeping, not usage — dropped.
 *   - Only successful calls count ('success' / 'success_with_warnings' /
 *     'accepted_pending', an admitted write still in flight, #5249).
 *     Denied and errored rows are not usage: a client repeatedly bouncing off
 *     a gated op must not "use" its way into starter-set derivation or an
 *     advisor fit finding (that would let denial traffic curate the catalog).
 *
 * Windowed on `created_at` so the query rides `idx_mcp_log_time_agent`
 * (created_at, token_name). Plain SQL through `engine.executeRaw` — works on
 * BOTH engines; never writes, so no jsonb pathway is involved.
 *
 * Scope caveat (amendment 30): usage-derived features see HTTP clients ONLY.
 * The stdio transport (local pipe, including every bootstrap/hook-lane serve)
 * does not write `mcp_request_log`, so stdio usage is structurally invisible
 * here — treat absence of a client as "not an HTTP client", never "unused".
 *
 * D12 automation classification: bootstrap/hook-lane identities register no
 * distinguishing client name (the hook lane is stdio and never logs; thin
 * clients carry operator-chosen names), so automation is detected
 * BEHAVIORALLY — a client whose calls are >90% ambient-recall boundary ops
 * (`context_pack` / `delta`) is flagged `likely_automation` and excluded from
 * starter-set derivation + advisor fit findings. The threshold and op set are
 * exported so consumers cite one definition.
 *
 * Retention (src/core/mcp-request-log-retention.ts): an opt-in prune removes
 * rows past cycle.purge.mcp_request_log_retention_days (never fewer than 30
 * days, so the built-in 30-day windows stay complete) and never the
 * AUDIT_LOG_OPERATIONS rows. Coverage reads the newest pruned row
 * (mcp_request_log_rollup.pruned_through); a brain that never pruned reports
 * every window complete.
 */

import type { BrainEngine } from './engine.ts';

/** Default trailing window for every usage-derived surface. */
export const MCP_USAGE_DEFAULT_WINDOW_DAYS = 30;

/**
 * Operator audit rows that ride the request log and are never pruned: ENG-8
 * surface changes (src/core/surface-audit.ts), GBRA-219 memory setting
 * changes (src/core/facts/writeback-settings.ts) and GST-1094 owner access
 * administration (src/commands/serve-http-access.ts).
 */
export const AUDIT_LOG_OPERATIONS: ReadonlySet<string> = new Set(['surface_change', 'memory_setting_change', 'access_admin']);

/** JSON-RPC method / server-plane rows that are not operation calls. */
export const NON_OP_LOG_ROWS: ReadonlySet<string> = new Set([
  'tools/list',
  'initialize',
  'notifications/initialized',
  'ping',
  ...AUDIT_LOG_OPERATIONS,
]);

/** Legacy bearer transport row prefix — 'tools/call:query' means op 'query'. */
export const LEGACY_CALL_PREFIX = 'tools/call:';

/**
 * D12: ambient-recall boundary verbs — the ops a hook-lane / turn-context
 * automation client calls almost exclusively.
 */
export const AUTOMATION_BOUNDARY_OPS: ReadonlySet<string> = new Set(['context_pack', 'delta']);

/** Fraction of a client's calls that must be boundary ops to classify as automation. */
export const AUTOMATION_FRACTION_THRESHOLD = 0.9;

/**
 * Normalize one logged `operation` value to an op name, or null when the row
 * is not an operation call. The single source for the hygiene rules above.
 */
export function normalizeLoggedOperation(operation: string): string | null {
  if (operation.startsWith(LEGACY_CALL_PREFIX)) {
    const name = operation.slice(LEGACY_CALL_PREFIX.length);
    if (name.length === 0) return null;
    // The stripped name re-runs the hygiene check: 'tools/call:tools/list'
    // or a prefixed 'surface_change' audit row is still not an op call.
    return NON_OP_LOG_ROWS.has(name) ? null : name;
  }
  if (NON_OP_LOG_ROWS.has(operation)) return null;
  return operation;
}

export interface ClientOpUsage {
  /** `mcp_request_log.token_name`: OAuth client_id, or a legacy bearer token name. */
  token_name: string;
  /** Op name → call count inside the window (post-hygiene). */
  ops: Record<string, number>;
  total_calls: number;
  /** Sorted distinct op names inside the window. */
  distinct_ops: string[];
  /** ISO timestamp of the client's most recent op call in the window. */
  last_seen: string;
  /** Fraction of calls that are AUTOMATION_BOUNDARY_OPS (0 when no calls). */
  automation_fraction: number;
  /** D12 behavioral classification: automation_fraction > threshold. */
  likely_automation: boolean;
}

function toIso(v: unknown): string {
  if (v instanceof Date) return v.toISOString();
  const d = new Date(String(v));
  return Number.isNaN(d.getTime()) ? String(v) : d.toISOString();
}

/**
 * Per-client op usage over the trailing window (default 30d). Returns one
 * entry per token_name, sorted by total_calls descending. Never throws for
 * an empty log; a missing table (very old brain) DOES throw — callers that
 * must be resilient wrap in try/catch (the advisor collector does).
 */
export async function readClientOpUsage(
  engine: BrainEngine,
  opts: { days?: number } = {},
): Promise<ClientOpUsage[]> {
  const days = opts.days ?? MCP_USAGE_DEFAULT_WINDOW_DAYS;
  if (!Number.isInteger(days) || days < 1 || days > 3650) {
    throw new Error(`readClientOpUsage: days must be an integer in [1, 3650]; got ${String(opts.days)}`);
  }
  // Windowed on created_at (rides idx_mcp_log_time_agent). The day count is
  // bound as a parameter and multiplied into a unit interval — portable
  // across Postgres and PGLite, no string-splicing into the SQL.
  const rows = await engine.executeRaw<{
    token_name: string | null;
    operation: string;
    n: number | string;
    last_seen: unknown;
  }>(
    `SELECT token_name, operation, count(*)::int AS n, max(created_at) AS last_seen
       FROM mcp_request_log
      WHERE created_at > now() - ($1::int * interval '1 day')
        AND token_name IS NOT NULL
        AND status IN ('success', 'success_with_warnings', 'accepted_pending')
      GROUP BY token_name, operation`,
    [days],
  );

  const byClient = new Map<string, { ops: Map<string, number>; total: number; lastSeen: string }>();
  for (const row of rows) {
    if (!row.token_name) continue;
    const op = normalizeLoggedOperation(row.operation);
    if (op === null) continue;
    const n = typeof row.n === 'number' ? row.n : parseInt(String(row.n), 10) || 0;
    const lastSeen = toIso(row.last_seen);
    let entry = byClient.get(row.token_name);
    if (!entry) {
      entry = { ops: new Map(), total: 0, lastSeen };
      byClient.set(row.token_name, entry);
    }
    entry.ops.set(op, (entry.ops.get(op) ?? 0) + n);
    entry.total += n;
    if (lastSeen > entry.lastSeen) entry.lastSeen = lastSeen;
  }

  const out: ClientOpUsage[] = [];
  for (const [token, entry] of byClient) {
    let automationCalls = 0;
    for (const [op, n] of entry.ops) {
      if (AUTOMATION_BOUNDARY_OPS.has(op)) automationCalls += n;
    }
    const fraction = entry.total > 0 ? automationCalls / entry.total : 0;
    out.push({
      token_name: token,
      ops: Object.fromEntries([...entry.ops.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))),
      total_calls: entry.total,
      distinct_ops: [...entry.ops.keys()].sort(),
      last_seen: entry.lastSeen,
      automation_fraction: fraction,
      likely_automation: fraction > AUTOMATION_FRACTION_THRESHOLD,
    });
  }
  out.sort((a, b) => b.total_calls - a.total_calls || (a.token_name < b.token_name ? -1 : 1));
  return out;
}

/** How much of a requested usage window the request log still holds in detail. */
export interface McpUsageCoverage {
  requested_days: number;
  /** Whole days back from now the log holds in full (requested_days when not truncated). */
  covered_days: number;
  truncated: boolean;
  /** ISO time of the newest pruned row; null on a brain that never pruned. */
  pruned_before: string | null;
}

const DAY_MS = 86_400_000;

/** Coverage of a trailing window. A brain without the tally table (before its migration) never pruned. */
export async function readMcpUsageCoverage(engine: BrainEngine, days: number): Promise<McpUsageCoverage> {
  const [probe] = await engine.executeRaw<{ present: boolean; now: unknown }>(
    "SELECT to_regclass('mcp_request_log_rollup') IS NOT NULL AS present, now() AS now");
  const [row] = probe?.present
    ? await engine.executeRaw<{ pruned_before: unknown }>('SELECT max(pruned_through) AS pruned_before FROM mcp_request_log_rollup')
    : [];
  if (!row?.pruned_before) return { requested_days: days, covered_days: days, truncated: false, pruned_before: null };
  const prunedBefore = toIso(row.pruned_before);
  const keptDays = Math.floor((Date.parse(toIso(probe!.now)) - Date.parse(prunedBefore)) / DAY_MS);
  const truncated = keptDays < days;
  return { requested_days: days, covered_days: truncated ? Math.max(1, keptDays) : days, truncated, pruned_before: prunedBefore };
}

/** readClientOpUsage plus the window's coverage, for every surface that shows a window to a person. */
export async function readClientOpUsageWithCoverage(
  engine: BrainEngine,
  opts: { days?: number } = {},
): Promise<{ clients: ClientOpUsage[]; coverage: McpUsageCoverage }> {
  const clients = await readClientOpUsage(engine, opts);
  return { clients, coverage: await readMcpUsageCoverage(engine, opts.days ?? MCP_USAGE_DEFAULT_WINDOW_DAYS) };
}

/** The one truncation sentence: what was pruned, the exact window that is complete, and that raising retention restores nothing. */
export function truncatedWindowNote(coverage: McpUsageCoverage): string {
  return `window truncated: details before ${coverage.pruned_before} were pruned, so the ${coverage.requested_days}-day window holds only the last ${coverage.covered_days} day(s) in full. ` +
    `For an exact report use --days ${coverage.covered_days}. Raising cycle.purge.mcp_request_log_retention_days cannot restore pruned detail.`;
}