Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.9 KB
Raw Blame
import { applyRedaction, planRedaction, type RedactionPlan } from '../secret-scan.ts';
import { DEGRADED_REASONS, DEGRADED_STAGES } from '../types.ts';
import type { Operation } from '../ops/contract.ts';

export const OUTPUT_REDACTION_MAX_FIELD_CHARS = 64 * 1024;
export const OUTPUT_REDACTION_MAX_TOTAL_CHARS = 1024 * 1024;
export const OUTPUT_REDACTION_LIMIT = '<REDACTED:output_limit>';

const IDENTITY_FIELDS = new Set([
  'id', 'slug', 'source_id', 'page_id', 'chunk_id', 'message_id', 'thread_id',
  'graph_session_prefix', 'relational_seed', 'relational_path', 'superseded_by',
  'fact_id', 'entity_slug', 'from_slug', 'to_slug', 'origin_slug', 'from_source_id', 'to_source_id', 'origin_source_id',
]);
const MAX_DEPTH = 24;
const MAX_TEXT_FIELDS = 8192;
const DEGRADED_STAGE_CODES = new Set<string>(DEGRADED_STAGES);
const DEGRADED_REASON_CODES = new Set<string>(DEGRADED_REASONS);
const GUEST_STAMP = Symbol('gbrain.guest_stamp');

/**
 * Registers a guest mark built by the guest stamp (guests/stamp.ts), so its `writer`, a principal id read from
 * guest_marks, passes redaction while the mark's other fields are scanned like stored text. Only a registered object
 * qualifies, by a symbol key that stored data cannot carry: a stored look-alike `guest.writer`, and a `writer` anywhere
 * else, is still redacted.
 */
export function exemptGuestWriter<T extends object>(guest: T): T {
  (guest as Record<symbol, unknown>)[GUEST_STAMP] = true;
  return guest;
}

export interface RetrievalRedactionOpts {
  /**
   * Scan every text field whole: no per-field, response or field-count
   * replacement with `<REDACTED:output_limit>`. One echo dictionary still
   * spans the response and every field is planned before any write.
   */
  uncapped?: boolean;
  /** Keys of each top-level result object copied verbatim, unscanned. */
  verbatim?: readonly string[];
}

export function redactRetrievalOutput<T, M>(results: T[], meta: M, opts: RetrievalRedactionOpts = {}): { results: T[]; meta: M } {
  const echoValues = new Map<string, string>();
  const plans = new Map<string, RedactionPlan>();
  const writes: Array<() => void> = [];
  const verbatim = new Set(opts.verbatim ?? []);
  let remaining = OUTPUT_REDACTION_MAX_TOTAL_CHARS;
  let fields = 0;

  function copy(value: unknown, depth: number, path: Array<string | number>): unknown {
    if (typeof value !== 'object' || value === null) return value;
    if (value instanceof Date) return new Date(value.getTime());
    if (depth > MAX_DEPTH) return OUTPUT_REDACTION_LIMIT;
    const entries = Array.isArray(value) ? value.entries() : Object.entries(value);
    const out: Record<string, unknown> | unknown[] = Array.isArray(value) ? [] : {};
    for (const [key, item] of entries) {
      let next: unknown;
      if (path.length === 2 && path[0] === 'results' && verbatim.has(String(key))) {
        next = item;
      } else if (key === 'writer' && typeof item === 'string' && (value as Record<symbol, unknown>)[GUEST_STAMP] === true) {
        next = item;
      } else if (IDENTITY_FIELDS.has(String(key)) && (typeof item !== 'object' || item === null ||
        (Array.isArray(item) && item.every(part => typeof part === 'string')))) {
        next = Array.isArray(item) ? [...item] : item;
      } else if (typeof item === 'string' && path[0] === 'meta' && (
        path.length === 3 && path[1] === 'degraded' && typeof path[2] === 'number' &&
          (key === 'stage' && DEGRADED_STAGE_CODES.has(item) || key === 'reason' && DEGRADED_REASON_CODES.has(item)) ||
        path.length === 2 && path[1] === 'projection_readiness' && key === 'status' &&
          ['ready', 'projection_pending', 'unknown'].includes(item)
      )) {
        next = item;
      } else if (typeof item === 'string') {
        let plan = plans.get(item);
        if (!opts.uncapped && (item.length > OUTPUT_REDACTION_MAX_FIELD_CHARS || item.length > remaining || ++fields > MAX_TEXT_FIELDS)) {
          next = OUTPUT_REDACTION_LIMIT;
        } else {
          remaining -= item.length;
          if (!plan) {
            plan = planRedaction(item, { echoValues, highEntropy: true });
            plans.set(item, plan);
          }
          const planned = plan;
          writes.push(() => {
            Object.defineProperty(out, key, { value: applyRedaction(planned), enumerable: true, writable: true, configurable: true });
          });
        }
      } else {
        next = copy(item, depth + 1, [...path, key]);
      }
      Object.defineProperty(out, key, { value: next, enumerable: true, writable: true, configurable: true });
    }
    return out;
  }

  const output = copy({ results, meta }, 0, []) as { results: T[]; meta: M };
  for (const write of writes) write();
  return output;
}

/**
 * The registration-time wrapper behind `Operation.outputRedaction`: a
 * retrieval op's whole response (early returns included) passes through the
 * uncapped redactor; `localVerbatim` keys stay raw for the trusted local CLI.
 * Every other policy returns the handler unchanged.
 */
export function withOutputRedaction(op: Pick<Operation, 'handler' | 'outputRedaction'>): Operation['handler'] {
  const { handler, outputRedaction: policy } = op;
  if (policy !== 'retrieval' && !(typeof policy === 'object' && 'retrieval' in policy)) return handler;
  const localVerbatim = policy === 'retrieval' ? [] : policy.retrieval.localVerbatim;
  return async (ctx, params) => {
    const result = await handler(ctx, params);
    const redacted = redactRetrievalOutput([result], {}, { uncapped: true, verbatim: ctx.remote === false ? localVerbatim : [] }).results[0];
    // In-process side channels (symbol keys, e.g. a think answer's room evidence) survive the redaction copy; no response carries them.
    if (result && typeof result === 'object' && redacted && typeof redacted === 'object') {
      for (const key of Object.getOwnPropertySymbols(result)) (redacted as Record<symbol, unknown>)[key] = (result as Record<symbol, unknown>)[key];
    }
    return redacted;
  };
}