Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.5 KB
Raw Blame
/**
 * Large pages (Wave A): the per-connection egress budget. Every MCP tool
 * result is measured as the complete JSON-RPC response frame it becomes
 * (content blocks, notices and `_meta` included, every string escaped), not as
 * the body's character count, and a result over the connection's cap is
 * replaced by a structured `result_too_large` error instead of a frame the
 * client cannot read (the TypeScript SDK's stdio reader refuses messages over
 * 10 MiB; Claude Code cuts tool results at about 25k tokens).
 *
 * Defaults: 4 MiB on stdio (under the SDK's 10 MiB stdio buffer with margin),
 * 1 MiB on HTTP. `mcp.max_result_bytes_stdio` / `mcp.max_result_bytes_http`
 * (DB plane, then the config file's `mcp` block) move a cap within
 * [EGRESS_CAP_MIN, EGRESS_CAP_MAX]. Trusted local CLI calls have no cap: they
 * never cross a transport.
 */
import type { BrainEngine } from './engine.ts';
import type { GBrainConfig } from './config.ts';
import { opError, type OperationError } from './ops/contract.ts';

export type EgressTransport = 'stdio' | 'http';

export const EGRESS_CAP_DEFAULTS: Readonly<Record<EgressTransport, number>> = { stdio: 4 * 1024 * 1024, http: 1024 * 1024 };
export const EGRESS_CAP_CONFIG_KEYS: Readonly<Record<EgressTransport, string>> = {
  stdio: 'mcp.max_result_bytes_stdio',
  http: 'mcp.max_result_bytes_http',
};
/** A configured cap is clamped to this range: big enough for any windowed read, small enough for the SDK's 10 MiB stdio reader. */
export const EGRESS_CAP_MIN = 256 * 1024;
export const EGRESS_CAP_MAX = 9 * 1024 * 1024;
/** Bytes a frame spends outside the measured result: the request id and the transport's own framing (SSE `data:` lines). */
export const FRAME_RESERVE_BYTES = 1024;

export interface EgressCaller {
  remote: boolean;
  transport?: EgressTransport;
  engine?: Pick<BrainEngine, 'getConfig'>;
  config?: GBrainConfig | null;
}

/** The transport a caller's results travel over; null for the trusted local CLI. */
export function egressTransport(caller: Pick<EgressCaller, 'remote' | 'transport'>): EgressTransport | null {
  if (caller.remote === false) return null;
  return caller.transport === 'stdio' ? 'stdio' : 'http';
}

function parseCap(raw: unknown): number | null {
  const n = typeof raw === 'number' ? raw : typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : NaN;
  if (!Number.isFinite(n) || n <= 0) return null;
  return Math.min(EGRESS_CAP_MAX, Math.max(EGRESS_CAP_MIN, Math.floor(n)));
}

/**
 * The connection's result cap in bytes of the final encoded frame: Infinity
 * for the trusted local CLI, else the DB plane, the file plane, the default.
 * A config read that fails falls through; resolving a cap never fails a call.
 */
export async function resultByteCap(caller: EgressCaller): Promise<number> {
  const transport = egressTransport(caller);
  if (transport === null) return Number.POSITIVE_INFINITY;
  const key = EGRESS_CAP_CONFIG_KEYS[transport];
  try {
    const db = parseCap(await caller.engine?.getConfig(key));
    if (db !== null) return db;
  } catch {
    // Engine without a config table / transient error: the file plane decides.
  }
  const mcp = caller.config?.mcp as Record<string, unknown> | undefined;
  return parseCap(mcp?.[`max_result_bytes_${transport}`]) ?? EGRESS_CAP_DEFAULTS[transport];
}

/** Bytes of the complete JSON-RPC response frame carrying `result`, plus the framing reserve. */
export function encodedFrameBytes(result: unknown): number {
  return Buffer.byteLength(JSON.stringify({ jsonrpc: '2.0', id: 0, result }), 'utf8') + FRAME_RESERVE_BYTES;
}

/** The measured frame and the cap it broke, or null when `result` fits this connection. */
export async function frameOverCap(result: unknown, caller: EgressCaller): Promise<{ bytes: number; cap: number; transport: EgressTransport } | null> {
  const transport = egressTransport(caller);
  if (transport === null) return null;
  const cap = await resultByteCap(caller);
  const bytes = encodedFrameBytes(result);
  return bytes > cap ? { bytes, cap, transport } : null;
}

/**
 * The dispatcher's backstop refusal: a read whose final frame is over the
 * connection's cap. Nothing is cut; the caller asks again for less. Reads
 * only: a write's result is its receipt and is never replaced.
 */
export function resultTooLargeError(op: string, params: Record<string, unknown>, over: { bytes: number; cap: number; transport: EgressTransport }): OperationError {
  const slug = typeof params.slug === 'string' ? params.slug : undefined;
  const sourceId = typeof params.source_id === 'string' ? params.source_id : undefined;
  return opError('result_too_large',
    `${op} produced a ${over.bytes}-byte response; this connection carries at most ${over.cap} bytes per result (${EGRESS_CAP_CONFIG_KEYS[over.transport]}).`,
    "Ask for less in one call: a window (get_page body: 'window'), a page of rows (limit / cursor), or metadata only. Nothing was returned or cut.",
    {
      legacy_error: 'invalid_params',
      detail: JSON.stringify({ op, result_bytes: over.bytes, max_result_bytes: over.cap, transport: over.transport, config_key: EGRESS_CAP_CONFIG_KEYS[over.transport] }),
      ...(slug ? { fix: { argv: ['gbrain', 'get', ...(sourceId ? ['--source', sourceId] : []), '--', slug],
        mcp: { tool: 'get_page', arguments: { slug, ...(sourceId ? { source_id: sourceId } : {}), body: 'outline' } },
        consent: [], actor: 'agent' as const, why: "Returns the page's size and outline, which name the windows to read.", requires_exclusive: false } } : {}),
    });
}