Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.4 KB
Raw Blame
/**
 * #7234: bounded diagnostics for a `malformed_proposal` refusal.
 *
 * The parse barrier (`isValidProposal`) rejects a judge response whose events
 * fail validation, and the refusal alone does not say which check failed.
 * `diagnoseMalformedProposals` names it with a fixed reason code, the required
 * field it concerns (from the proposal schema, never a key read from the
 * input) and the JSON type found there, plus counts. It never copies a value,
 * a key the judge invented, the prompt or the raw response, so the result is
 * safe to log and to return.
 *
 * Inspection is bounded and flat: at most MAX_INSPECTED_PROPOSALS proposals,
 * MAX_INSPECTED_WHO_ITEMS `who` entries each, and strings are read only up to
 * MAX_INSPECTED_CHARS; nested values are typed, never walked. A check past a
 * bound is skipped rather than guessed, so every reported defect is one the
 * barrier also rejects; a proposal whose defect lies past every bound is left
 * out of `invalid`, and when no defect is found at all the code is
 * `beyond_bounds`.
 */

export const MAX_INSPECTED_PROPOSALS = 50;
export const MAX_INSPECTED_WHO_ITEMS = 50;
export const MAX_INSPECTED_CHARS = 256;

export type MalformedProposalCode =
  | 'not_object'
  | 'missing_field'
  | 'wrong_type'
  | 'when_too_short'
  | 'when_unparseable'
  | 'what_blank'
  | 'who_item_not_string'
  | 'beyond_bounds';

export type ProposalField = 'when' | 'what' | 'who' | 'kind';
export type ValueShape = 'string' | 'number' | 'boolean' | 'null' | 'array' | 'object' | 'other';

interface Defect { code: Exclude<MalformedProposalCode, 'beyond_bounds'>; field?: ProposalField; shape?: ValueShape }

export interface MalformedProposalDiagnostics {
  /** The first defect found, or `beyond_bounds` when none was found within the bounds. */
  code: MalformedProposalCode;
  field?: ProposalField;
  /** The JSON type found at `field` (for `not_object`, the proposal's; for `who_item_not_string`, the entry's). */
  shape?: ValueShape;
  /** Zero-based position of the first defective proposal; absent with `beyond_bounds`. */
  index?: number;
  /** Proposals in the response. */
  events: number;
  /** Proposals inspected (at most MAX_INSPECTED_PROPOSALS). */
  inspected: number;
  /** Inspected proposals with a defect found. */
  invalid: number;
  /** Defects found, by code. */
  codes: Partial<Record<MalformedProposalCode, number>>;
}

function shapeOf(v: unknown): ValueShape {
  if (v === null) return 'null';
  if (Array.isArray(v)) return 'array';
  const t = typeof v;
  return t === 'string' || t === 'number' || t === 'boolean' || t === 'object' ? t : 'other';
}

function stringField(o: Record<string, unknown>, field: ProposalField): Defect | string {
  const v = o[field];
  if (v === undefined) return { code: 'missing_field', field };
  if (typeof v !== 'string') return { code: 'wrong_type', field, shape: shapeOf(v) };
  return v;
}

/** The first failing check of `isValidProposal`, in its order, within the bounds; null when none was found. */
function proposalDefect(e: unknown): Defect | null {
  if (!e || typeof e !== 'object' || Array.isArray(e)) return { code: 'not_object', shape: shapeOf(e) };
  const o = e as Record<string, unknown>;
  const when = stringField(o, 'when');
  if (typeof when !== 'string') return when;
  if (when.length < 4) return { code: 'when_too_short', field: 'when' };
  if (when.length <= MAX_INSPECTED_CHARS && Number.isNaN(new Date(when).getTime())) return { code: 'when_unparseable', field: 'when' };
  const what = stringField(o, 'what');
  if (typeof what !== 'string') return what;
  if (what.length <= MAX_INSPECTED_CHARS && what.trim().length === 0) return { code: 'what_blank', field: 'what' };
  const who = o.who;
  if (who === undefined) return { code: 'missing_field', field: 'who' };
  if (!Array.isArray(who)) return { code: 'wrong_type', field: 'who', shape: shapeOf(who) };
  const items = Math.min(who.length, MAX_INSPECTED_WHO_ITEMS);
  for (let i = 0; i < items; i++) {
    if (typeof who[i] !== 'string') return { code: 'who_item_not_string', field: 'who', shape: shapeOf(who[i]) };
  }
  const kind = stringField(o, 'kind');
  return typeof kind === 'string' ? null : kind;
}

export function diagnoseMalformedProposals(events: readonly unknown[]): MalformedProposalDiagnostics {
  const inspected = Math.min(events.length, MAX_INSPECTED_PROPOSALS);
  const codes: MalformedProposalDiagnostics['codes'] = {};
  let first: (Defect & { index: number }) | null = null;
  let invalid = 0;
  for (let i = 0; i < inspected; i++) {
    const defect = proposalDefect(events[i]);
    if (!defect) continue;
    invalid++;
    codes[defect.code] = (codes[defect.code] ?? 0) + 1;
    first ??= { ...defect, index: i };
  }
  if (!first) return { code: 'beyond_bounds', events: events.length, inspected, invalid, codes };
  return {
    code: first.code,
    ...(first.field ? { field: first.field } : {}),
    ...(first.shape ? { shape: first.shape } : {}),
    index: first.index, events: events.length, inspected, invalid, codes,
  };
}

/** One log clause built only from the fixed vocabulary and counts above. */
export function describeMalformedProposals(d: MalformedProposalDiagnostics): string {
  const where = d.index === undefined ? 'no defect within the inspection bounds' : `proposal ${d.index + 1} of ${d.events}`;
  const field = d.field ? ` field=${d.field}` : '';
  const shape = d.shape ? ` shape=${d.shape}` : '';
  return `code=${d.code}${field}${shape}; ${where}; ${d.invalid} of ${d.inspected} inspected invalid`;
}