Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
21.5 KB
Raw Blame
/**
 * Registry guard (token-diet, t_352fd7f6 + t_c967abaf; completeness
 * audit added by evidence-at-the-boundary, task C3).
 *
 * One walk over the assembled tool table backs three contract tests:
 *
 *   1. Description caps - tool descriptions and per-property schema
 *      descriptions have hard character ceilings so the serialized
 *      registry (paid by every MCP client on every request in
 *      non-deferred hosts) cannot silently regrow. Long-form guidance
 *      belongs in server instructions or docs/mcp.md, not in schemas.
 *   2. Preview-budget default - every tool either carries a
 *      `previewBudget` or appears in the explicit exempt list below
 *      with a reason. Unbounded tool output is a deliberate, reviewed
 *      property, never an accident of omission.
 *   3. Schema completeness - the catalog documents itself. Fifty-nine
 *      advertised parameters carried no description at all when this
 *      audit was written; five further dimensions (object root, a
 *      properties map, a closed root, a declared type on every node, a
 *      `required` list naming only declared properties) were already
 *      clean at 108 of 108 tools and equally unguarded, so they ratchet
 *      here rather than wait for the first regression.
 *
 * Why one traversal rather than two. The original walker descended
 * `properties` and `items` and lost the difference between them, which
 * is precisely the difference a completeness rule needs: the array
 * property already carries the description, and demanding one on a
 * `{type:"string"}` items node produces 53 noise entries. So the walk is
 * now a node stream carrying node KIND, and both audits read it. Two
 * walks that disagreed about which nodes exist is the drift this
 * removes.
 *
 * Why {@link SCHEMA_COMPLETENESS_RULE.unsupportedComposition} exists with
 * no offender in the table: the walk follows `properties`, `items` and a
 * schema-valued `additionalProperties`, and nothing else. A `oneOf`, an
 * `allOf` or a `$ref` would be skipped in silence, and every rule below
 * it would pass by never running. Reporting the keyword turns a future
 * composed schema into a failing test instead of an unguarded one.
 *
 * There is deliberately NO exemption table for descriptions. An
 * exemption keyed on a property path would be a rule that documents
 * nothing; the fix for a missing description is the description.
 *
 * Test-time module: nothing here runs on the MCP request path. The
 * request-path counterpart is `./argument-guard.ts`, which reads the
 * `additionalProperties: false` this audit guarantees.
 */

import type { ToolDefinition } from "./tool-contract.ts";

export const TOOL_DESCRIPTION_MAX = 300;
// The retry_tasks description enumerates the known lane tasks, so a fifth
// task's registration (note-change truth maintenance) grew the measured
// length; the cap moved with the population rather than shortening the text
// that names what an operator may retry. The maintenance parity census
// imports this constant and measures against it, so the cap and the census
// cannot drift.
export const PROPERTY_DESCRIPTION_MAX = 168;

/**
 * Shortest reason that can justify a preview-budget exemption. Sits with
 * the caps because it is the same kind of number: a floor under prose
 * that a reviewer has to read, not a style preference.
 */
export const EXEMPTION_REASON_MIN = 10;

/**
 * What kind of schema node the walk is standing on. The kind is the
 * whole point of the stream: `missing-description` applies to `property`
 * nodes and nothing else.
 */
export const SCHEMA_NODE_KIND = Object.freeze({
  /** The tool's input schema itself. */
  root: "root",
  /** Reached through a `properties` entry, so it has a name of its own. */
  property: "property",
  /** Reached through an `items` edge; the array property names it. */
  items: "items",
  /** Reached through a schema-valued `additionalProperties` (a free map). */
  values: "values",
} as const);

/** Closed union over {@link SCHEMA_NODE_KIND}. */
export type SchemaNodeKind = (typeof SCHEMA_NODE_KIND)[keyof typeof SCHEMA_NODE_KIND];

/** Membership list, in traversal-discovery order. */
export const SCHEMA_NODE_KINDS: ReadonlyArray<SchemaNodeKind> = Object.freeze([
  SCHEMA_NODE_KIND.root,
  SCHEMA_NODE_KIND.property,
  SCHEMA_NODE_KIND.items,
  SCHEMA_NODE_KIND.values,
]);

/** Narrow a string back to a member of the kind vocabulary. */
export function isSchemaNodeKind(value: unknown): value is SchemaNodeKind {
  return typeof value === "string" && (SCHEMA_NODE_KINDS as ReadonlyArray<string>).includes(value);
}

/** One node of one tool's input schema, as the walk found it. */
export interface SchemaNode {
  readonly tool: string;
  /** "" at the root, else a dotted path with `[]` and `{}` edge markers. */
  readonly path: string;
  readonly kind: SchemaNodeKind;
  /** The node object itself, for the audits to read. */
  readonly schema: Readonly<Record<string, unknown>>;
}

/**
 * Composition keywords the walk cannot follow. Not a style ban: each one
 * hides a subschema from every rule below it, so the honest answer is to
 * report it rather than descend into a branch this walker does not model.
 */
const UNSUPPORTED_COMPOSITION_KEYWORDS: ReadonlyArray<string> = Object.freeze([
  "oneOf",
  "anyOf",
  "allOf",
  "$ref",
]);

/** Depth-first node stream over one tool's input schema. */
export function* schemaNodes(tool: string, schema: unknown, path = ""): Generator<SchemaNode> {
  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) return;
  const node = schema as Record<string, unknown>;
  yield {
    tool,
    path,
    kind: path === "" ? SCHEMA_NODE_KIND.root : nodeKindFromPath(path),
    schema: node,
  };
  const properties = node["properties"];
  if (properties !== null && typeof properties === "object") {
    for (const key of Object.keys(properties)) {
      yield* schemaNodes(tool, (properties as Record<string, unknown>)[key], `${path}.${key}`);
    }
  }
  if (node["items"] !== undefined) yield* schemaNodes(tool, node["items"], `${path}[]`);
  const additional = node["additionalProperties"];
  if (additional !== null && typeof additional === "object" && !Array.isArray(additional)) {
    yield* schemaNodes(tool, additional, `${path}{}`);
  }
}

/** The edge marker the path ends with names the kind that reached it. */
function nodeKindFromPath(path: string): SchemaNodeKind {
  if (path.endsWith("[]")) return SCHEMA_NODE_KIND.items;
  if (path.endsWith("{}")) return SCHEMA_NODE_KIND.values;
  return SCHEMA_NODE_KIND.property;
}

export interface DescriptionViolation {
  readonly tool: string;
  /** "" for the tool description itself, else the property path. */
  readonly path: string;
  readonly length: number;
  readonly limit: number;
}

/** Every description over its cap, tool-level and property-level. */
export function auditToolDescriptions(
  tools: ReadonlyArray<ToolDefinition>,
): DescriptionViolation[] {
  const out: DescriptionViolation[] = [];
  for (const tool of tools) {
    if (tool.description.length > TOOL_DESCRIPTION_MAX) {
      out.push({
        tool: tool.name,
        path: "",
        length: tool.description.length,
        limit: TOOL_DESCRIPTION_MAX,
      });
    }
    for (const node of schemaNodes(tool.name, tool.inputSchema)) {
      if (node.kind === SCHEMA_NODE_KIND.root) continue;
      const description = node.schema["description"];
      if (typeof description === "string" && description.length > PROPERTY_DESCRIPTION_MAX) {
        out.push({
          tool: tool.name,
          path: node.path,
          length: description.length,
          limit: PROPERTY_DESCRIPTION_MAX,
        });
      }
    }
  }
  return out;
}

/**
 * The closed vocabulary of completeness defects. Every entry names what
 * is missing, never a severity: a schema either says the thing or it
 * does not.
 */
export const SCHEMA_COMPLETENESS_RULE = Object.freeze({
  /** A named property advertises itself with no description. */
  missingDescription: "missing-description",
  /** A node declares neither a `type` nor an `enum`. */
  missingType: "missing-type",
  /** The root does not declare `additionalProperties: false`. */
  openRoot: "open-root",
  /** The root is not `type: "object"`. */
  nonObjectRoot: "non-object-root",
  /** The root carries no `properties` map, so it advertises no arguments. */
  missingProperties: "missing-properties",
  /** A `required` entry names a property the same node never declared. */
  undeclaredRequired: "undeclared-required",
  /** A composition keyword hides a subschema the walk cannot follow. */
  unsupportedComposition: "unsupported-composition",
} as const);

/** Closed union over {@link SCHEMA_COMPLETENESS_RULE}. */
export type SchemaCompletenessRule =
  (typeof SCHEMA_COMPLETENESS_RULE)[keyof typeof SCHEMA_COMPLETENESS_RULE];

/** Membership list, root-shape rules first. */
export const SCHEMA_COMPLETENESS_RULES: ReadonlyArray<SchemaCompletenessRule> = Object.freeze([
  SCHEMA_COMPLETENESS_RULE.nonObjectRoot,
  SCHEMA_COMPLETENESS_RULE.missingProperties,
  SCHEMA_COMPLETENESS_RULE.openRoot,
  SCHEMA_COMPLETENESS_RULE.missingDescription,
  SCHEMA_COMPLETENESS_RULE.missingType,
  SCHEMA_COMPLETENESS_RULE.undeclaredRequired,
  SCHEMA_COMPLETENESS_RULE.unsupportedComposition,
]);

/** Narrow a string back to a member of the rule vocabulary. */
export function isSchemaCompletenessRule(value: unknown): value is SchemaCompletenessRule {
  return (
    typeof value === "string" &&
    (SCHEMA_COMPLETENESS_RULES as ReadonlyArray<string>).includes(value)
  );
}

export interface CompletenessViolation {
  readonly tool: string;
  /** "" at the root, else the path of the offending node. */
  readonly path: string;
  readonly kind: SchemaNodeKind;
  readonly rule: SchemaCompletenessRule;
  /** What exactly is missing, when the rule alone does not say. */
  readonly detail: string;
}

/**
 * Every completeness defect across the advertised INPUT schemas.
 *
 * Output schemas are deliberately out of scope. Their vocabulary
 * declares union-typed fields with no `type` at all on purpose (the
 * lightweight response validator has no union, so `next_cursor` is
 * declared `{}` rather than declared wrongly), and not one of their 202
 * property nodes carries a description - `retrieval_trail` included.
 * Auditing them here would demand a type that would be a lie and turn a
 * 59-entry backfill into a 261-entry one. The output side already has
 * its own guard: every response is validated against its schema at
 * request time.
 */
export function auditSchemaCompleteness(
  tools: ReadonlyArray<ToolDefinition>,
): ReadonlyArray<CompletenessViolation> {
  const out: CompletenessViolation[] = [];
  for (const tool of tools) {
    for (const node of schemaNodes(tool.name, tool.inputSchema)) {
      auditNode(node, out);
    }
  }
  return Object.freeze(out);
}

function auditNode(node: SchemaNode, out: CompletenessViolation[]): void {
  const record = (rule: SchemaCompletenessRule, detail: string): void => {
    out.push({ tool: node.tool, path: node.path, kind: node.kind, rule, detail });
  };
  const schema = node.schema;

  for (const keyword of UNSUPPORTED_COMPOSITION_KEYWORDS) {
    if (schema[keyword] !== undefined) {
      record(SCHEMA_COMPLETENESS_RULE.unsupportedComposition, keyword);
    }
  }
  // Tuple-form `items` is the same problem wearing a supported keyword:
  // the walk descends a single schema and would skip an array of them.
  if (Array.isArray(schema["items"])) {
    record(SCHEMA_COMPLETENESS_RULE.unsupportedComposition, "items[]");
  }

  const properties = schema["properties"];
  const hasProperties = properties !== null && typeof properties === "object";

  if (node.kind === SCHEMA_NODE_KIND.root) {
    if (schema["type"] !== "object") {
      record(SCHEMA_COMPLETENESS_RULE.nonObjectRoot, `type=${String(schema["type"])}`);
    }
    if (!hasProperties) record(SCHEMA_COMPLETENESS_RULE.missingProperties, "properties");
    if (schema["additionalProperties"] !== false) {
      record(SCHEMA_COMPLETENESS_RULE.openRoot, "additionalProperties");
    }
  }

  if (node.kind === SCHEMA_NODE_KIND.property) {
    const description = schema["description"];
    if (typeof description !== "string" || description.trim() === "") {
      record(SCHEMA_COMPLETENESS_RULE.missingDescription, "description");
    }
  }

  if (schema["type"] === undefined && schema["enum"] === undefined) {
    record(SCHEMA_COMPLETENESS_RULE.missingType, "type");
  }

  const required = schema["required"];
  if (Array.isArray(required)) {
    const declared = hasProperties ? new Set(Object.keys(properties)) : new Set<string>();
    for (const entry of required) {
      if (typeof entry !== "string" || !declared.has(entry)) {
        record(SCHEMA_COMPLETENESS_RULE.undeclaredRequired, String(entry));
      }
    }
  }
}

/** One line per violation, so a failing assertion names every offender. */
export function renderCompletenessViolations(
  violations: ReadonlyArray<CompletenessViolation>,
): string {
  return violations.map((v) => `${v.tool}${v.path} [${v.kind}] ${v.rule}: ${v.detail}`).join("\n");
}

/**
 * Tools deliberately running without a preview budget, each with the
 * reason the omission is safe. Grouped by the property that bounds
 * their output instead.
 */
export const PREVIEW_BUDGET_EXEMPT: Readonly<Record<string, string>> = Object.freeze({
  // Writers and small acks - the result is a fixed-shape receipt.
  brain_feedback: "write; returns a small fixed-shape ack",
  brain_apply_evidence: "write; returns a small fixed-shape ack",
  brain_note: "write; returns a small fixed-shape ack",
  brain_settings:
    "small fixed-shape answers: one setting, or the list of shared settings that are set, " +
    "bounded by the closed key classification",
  brain_observed_use: "write; returns a small fixed-shape ack (records/aggregates count)",
  // The four note writers. Their receipts are no longer fixed-shape:
  // each carries an additive `lint` key over the pages it committed
  // (evidence-at-the-boundary, task A4). That key is what bounds them
  // now, and it bounds itself - the finding list is capped and reports
  // `total`, `returned` and `truncated`, so a preview envelope would
  // truncate a list that already declares its own truncation.
  brain_create_note:
    "write; returns the created note path, a created flag, the outcome discriminant, and a page-lint finding list capped and self-declaring its truncation",
  brain_update_note:
    "write; returns the updated note path, the kernel's updated flag, and a page-lint finding list capped and self-declaring its truncation",
  brain_append_note:
    "write; returns the appended note path, the kernel's appended flag, and a page-lint finding list capped and self-declaring its truncation",
  brain_write_batch:
    "write; returns a bounded per-operation result list, an applied count, and one page-lint finding list capped and self-declaring its truncation",
  brain_pinned_context: "pinned context is operator-curated and small by practice",
  brain_recall_feedback: "write; returns one event receipt plus bounded weights",
  brain_switch_vault: "write; returns a small profile ack",
  brain_write_session: "lifecycle ops return one fixed-shape envelope; prompts are kernel-bounded",
  brain_intake_entities: "write; returns created/updated id lists and a relation count",
  brain_ingest_source:
    "write; returns the summary path, bounded id lists and derived-section counts. Below local reach a summary page the caller cannot read is left untouched and the call answers as a first ingest would, so a repeated call answers created each time where a vault without that page answers created once; closing that needs a caller-lane summary path",
  brain_distill_source:
    "write; returns the distillation path, a claim count, source hash, capture scope, and a quotes report whose finding list is capped and self-declaring its truncation",
  brain_research_report:
    "write; returns the report path, a finding count, and one capture scope per caller-supplied source",
  brain_derive_fact: "write; returns one derived preference id, its level and premises",
  brain_memory_bridge:
    "write; returns a small fixed-shape receipt (recorded flag, kind, count, ids)",

  // Bounded by the operator-curated schema block, not by a receipt. Under
  // `dry_run: true` this tool is not a write at all and returns no receipt:
  // it returns the entire resulting pack plus a leaf-level diff.
  schema_apply_mutations:
    "returns the whole resulting schema pack - plus a leaf diff under dry_run, which writes nothing; bounded by the size of the schema pack, which the operator curates",

  // Bounded-by-construction reads.
  second_brain_capabilities: "fixed-size capability report",
  second_brain_wiring:
    "view=hosts is bounded by construction (one small fixed-shape entry per adapter in a registry this build closes); view=projects reads a registry nothing caps, so its list is capped in the handler at WIRING_MAX_PROJECTS and carries total/returned/truncated beside it, self-declaring its truncation",
  second_brain_status:
    "diagnostic contract; callers need full brain/search/config blocks, not a preview envelope",
  brain_context:
    "session bootstrap; deliberately returns the full preference set - it is the full-view target the budgeted SessionStart injection points at",
  brain_pre_compress_pack: "self-budgeting; enforces its own char budget internally",
  brain_artifact_get: "the preview-budget escape hatch; truncating it would defeat itself",
  brain_health: "fixed-shape counters",
  brain_doctor: "issue list bounded by vault invariants; CLI surface renders full detail",
  brain_status: "bounded operator snapshot: fixed counts plus a short problem list with hints",
  brain_recall_gate: "single verdict object",
  vault_health: "fixed list of manifest checks",
  brain_watchdog: "bounded probe report",
  brain_dream: "returns pass counters, not content",
  brain_intent_review: "bounded review window summary",
  brain_retention: "bounded retention counters",
  brain_review_candidates: "dry-run counters and short id lists",
  brain_sources: "per-(agent, source_type) counts only",
  brain_stale_scan: "bounded staleness list with caps in the handler",
  brain_moc_audit: "bounded audit summary",
  brain_mcp_landscape: "fixed-shape landscape summary",
  brain_session_describe: "single-session metadata only",
  brain_context_receipts: "bounded receipt list per session",
  brain_event_trace: "bounded event→trace join summary; full records via per-kind readers",
  brain_attestations:
    "bounded store evidence: fixed-shape metadata rows over the attestation ledger plus one " +
    "per-shard verdict summary; carries no note content at any reach",
  brain_write_destinations:
    "bounded destination table: the handler caps the page at limit and total_matched reports " +
    "the pre-truncation count; the fold is recomputed per call, so a cursor pages one walk, " +
    "and the per-kind readers remain the full-record surface",
  brain_changes:
    "record ids only, bounded by limit; a cut page says truncated: true and carries the watermark to pass next, which a head preview would cut off",
  brain_context_presets: "small preset list",
  brain_pre_compact_extract: "bounded extract; host injects it whole by design",
  brain_skill_proposals: "bounded proposal list",
  brain_skill_rewrite_status:
    "bounded status: one benchmark receipt plus at most ten grade verdict rows for one skill; " +
    "ids and rates only, never task or transcript text",
  brain_procedural_memory: "bounded hint list",
  brain_procedural_graph: "bounded graph summary",
  brain_recurrence: "bounded recurrence records; learn/forget are writes",
  brain_agent_diff: "bounded two-agent comparison",
  get_skill: "explicit full-content fetch; truncating the skill the agent asked for defeats it",
  tool_hydrate: "the two-pass schema escape hatch; truncating hydration would defeat itself",
  // The deprecated-alias exemptions were dropped with the aliases
  // themselves in the 1.0.0 sweep (tombstones in REMOVED_TOOLS).
});

/**
 * Own-key membership set for {@link PREVIEW_BUDGET_EXEMPT}, computed once at
 * module load. Replaces `name in PREVIEW_BUDGET_EXEMPT`, which walks the
 * prototype chain (so a tool named like an `Object.prototype` member -
 * `constructor`, `toString`, `hasOwnProperty` - would be falsely treated as
 * exempt) and recomputed `Object.keys` on every call. (t_6fbdba4b)
 */
const PREVIEW_BUDGET_EXEMPT_NAMES: ReadonlySet<string> = new Set(
  Object.keys(PREVIEW_BUDGET_EXEMPT),
);

export interface PreviewBudgetAudit {
  /** Tools with neither a budget nor an exempt entry - the guard fails on these. */
  readonly unbudgetedAndUnexempted: ReadonlyArray<string>;
  /** Exempt entries that now carry a budget - stale exemptions to clean up. */
  readonly exemptButBudgeted: ReadonlyArray<string>;
  /** Exempt entries naming tools that no longer exist. */
  readonly exemptButUnknown: ReadonlyArray<string>;
}

export function auditPreviewBudgets(tools: ReadonlyArray<ToolDefinition>): PreviewBudgetAudit {
  const names = new Set(tools.map((t) => t.name));
  const unbudgetedAndUnexempted: string[] = [];
  const exemptButBudgeted: string[] = [];
  for (const tool of tools) {
    const exempt = PREVIEW_BUDGET_EXEMPT_NAMES.has(tool.name);
    if (tool.previewBudget === undefined && !exempt) unbudgetedAndUnexempted.push(tool.name);
    if (tool.previewBudget !== undefined && exempt) exemptButBudgeted.push(tool.name);
  }
  const exemptButUnknown = [...PREVIEW_BUDGET_EXEMPT_NAMES].filter((n) => !names.has(n));
  return Object.freeze({
    unbudgetedAndUnexempted: Object.freeze(unbudgetedAndUnexempted),
    exemptButBudgeted: Object.freeze(exemptButBudgeted),
    exemptButUnknown: Object.freeze(exemptButUnknown),
  });
}