@modelprofile.com/flexharness 10.12.0 → 10.13.0

package/ts/classes.toolcatalog.ts

@@ -0,0 +1,1431 @@
+import * as plugins from './plugins.js';
+import { FlexHarnessValidationError } from './errors.js';
+import {
+  FLEX_TOOL_CATALOG_LIMITS as limits,
+  FLEX_TOOL_CATALOG_TOOL_NAMES as toolNames,
+  type IFlexCatalogDescribeInput,
+  type IFlexCatalogDescribeResult,
+  type IFlexCatalogMethod,
+  type IFlexCatalogParamIssue,
+  type IFlexCatalogRunContext,
+  type IFlexCatalogSearchInput,
+  type IFlexCatalogToolDefinition,
+  type IFlexToolCatalog,
+  type IFlexToolCatalogOptions,
+  type TFlexCatalogCallError,
+  type TJsonValue,
+} from './interfaces.js';
+import {
+  SchemaDeclarationWriter,
+  countOf,
+  docBlock,
+  indentLines,
+  isIdentifier,
+  isSchemaRecord,
+  type IRenderedDeclaration,
+  type TJsonSchemaNode,
+} from './utils.schemadeclarations.js';
+import { validateUtf8String } from './utils.validation.js';
+
+type TValidationResult = { success: true; value: unknown } | { success: false; error: Error };
+type TValidate = (value: unknown) => TValidationResult | PromiseLike<TValidationResult>;
+type TDeclarationMode = NonNullable<IFlexToolCatalogOptions['declarations']>;
+type TSchemaDraft = '4' | '7' | '2019-09' | '2020-12';
+
+interface ICatalogSchema {
+  readonly json: TJsonSchemaNode;
+  /** The schema's own validator, such as zod's, run after JSON Schema validation. */
+  readonly validate?: TValidate;
+}
+
+interface ISchemaScope {
+  readonly root: TJsonSchemaNode;
+  /** The named type of each identifier-keyed local definition, by `<container>/<key>`. */
+  readonly localNames: Map<string, string>;
+}
+
+interface IMethodEntry {
+  readonly path: string;
+  readonly namespace: string;
+  readonly name: string;
+  readonly summary: string;
+  readonly description?: string;
+  readonly tags: readonly string[];
+  readonly examples: readonly string[];
+  readonly input: ICatalogSchema;
+  readonly inputScope: ISchemaScope;
+  readonly output?: ICatalogSchema;
+  readonly outputScope?: ISchemaScope;
+  readonly declaration?: string;
+  readonly run: IFlexCatalogMethod['run'];
+}
+
+interface ITypeEntry {
+  readonly name: string;
+  readonly description?: string;
+  readonly declaration?: string;
+  /** A catalog type's schema. */
+  readonly schema?: ICatalogSchema;
+  /** The scope the type's schema or local definition renders in. */
+  readonly scope?: ISchemaScope;
+  /** A local definition's schema, registered under `name`. */
+  readonly definition?: TJsonSchemaNode;
+}
+
+interface IPreparedCall {
+  readonly success: true;
+  readonly method: string;
+  readonly params: unknown;
+  run(context: IFlexCatalogRunContext<any>): ReturnType<IFlexCatalogMethod['run']>;
+}
+
+interface IFailedCall {
+  readonly success: false;
+  readonly error: TFlexCatalogCallError;
+}
+
+const aiSchemaSymbol = Symbol.for('vercel.ai.schema');
+const methodPathPattern = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const typeNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Words a declaration cannot use as a function, namespace or type name. */
+const reservedWords = new Set([
+  'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do',
+  'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'implements', 'import',
+  'in', 'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private', 'protected', 'public',
+  'return', 'static', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while',
+  'with', 'yield',
+]);
+const controlPattern = /[\u0000-\u001f\u007f]/;
+const definitionRefPattern = /^#\/(\$defs|definitions)\/([^/]+)$/;
+const declaredTypesHeader = '// Declares types: ';
+const identifierScanPattern = /[A-Za-z_$][A-Za-z0-9_$]*/g;
+const describeFormats = new Set(['typescript', 'json-schema']);
+const methodKeys = new Set([
+  'method', 'summary', 'description', 'tags', 'examples', 'inputSchema', 'outputSchema', 'declaration', 'run',
+]);
+const typeKeys = new Set(['name', 'description', 'schema', 'declaration']);
+const stopWords = new Set([
+  'a', 'an', 'and', 'are', 'all', 'as', 'be', 'by', 'for', 'from', 'get', 'i', 'in', 'is', 'it', 'me', 'my',
+  'of', 'on', 'or', 'that', 'the', 'this', 'to', 'with',
+]);
+const fieldWeights = { name: 3, namespace: 1.5, summary: 2, tags: 2, description: 1 } as const;
+type TSearchField = keyof typeof fieldWeights;
+const bm25K1 = 1.2;
+const bm25B = 0.75;
+const coreCache = new WeakMap<object, Map<TDeclarationMode, Promise<FlexToolCatalogCore>>>();
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object'
+  && value !== null
+  && !Array.isArray(value)
+  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+
+const compareCodePoints = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;
+
+const stableStringify = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (isSchemaRecord(value)) {
+    return `{${Object.keys(value).sort(compareCodePoints)
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+};
+
+const deepFreeze = <T>(value: T): T => {
+  if (typeof value === 'object' && value !== null && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+};
+
+const decodePointerToken = (token: string): string => {
+  let decoded = token;
+  try {
+    decoded = decodeURI(token);
+  } catch {
+    decoded = token;
+  }
+  return decoded.replace(/~1/g, '/').replace(/~0/g, '~');
+};
+
+const pointerTokens = (pointer: string): string[] =>
+  pointer.replace(/^#/, '').split('/').slice(1).map(decodePointerToken);
+
+/** Resolves a local JSON pointer against `root`, following `$ref` tokens of keyword locations. */
+const resolvePointer = (root: TJsonSchemaNode, pointer: string): unknown => {
+  let node: unknown = root;
+  for (const token of pointerTokens(pointer)) {
+    if (token === '$ref' && isSchemaRecord(node) && typeof node.$ref === 'string') {
+      node = node.$ref.startsWith('#') ? resolvePointer(root, node.$ref) : undefined;
+      continue;
+    }
+    if (Array.isArray(node)) node = node[Number(token)];
+    else if (isSchemaRecord(node)) node = Object.prototype.hasOwnProperty.call(node, token) ? node[token] : undefined;
+    else return undefined;
+  }
+  return node;
+};
+
+const collectRefs = (node: unknown, refs: Set<string>): void => {
+  if (Array.isArray(node)) {
+    for (const child of node) collectRefs(child, refs);
+    return;
+  }
+  if (!isSchemaRecord(node)) return;
+  for (const [key, child] of Object.entries(node)) {
+    if (key === '$ref' && typeof child === 'string') refs.add(child);
+    else if (key !== 'const' && key !== 'enum' && key !== 'default' && key !== 'examples') collectRefs(child, refs);
+  }
+};
+
+const schemaDraft = (root: TJsonSchemaNode): TSchemaDraft => {
+  const declared = isSchemaRecord(root) && typeof root.$schema === 'string' ? root.$schema : '';
+  if (declared.includes('draft-04')) return '4';
+  if (declared.includes('draft-06') || declared.includes('draft-07')) return '7';
+  if (declared.includes('2019-09')) return '2019-09';
+  return '2020-12';
+};
+
+const withoutDraft = (schema: TJsonSchemaNode): TJsonSchemaNode => {
+  if (!isSchemaRecord(schema) || schema.$schema === undefined) return schema;
+  const { $schema: _draft, ...rest } = schema;
+  return rest;
+};
+
+const stem = (word: string): string => {
+  if (word.length > 4 && word.endsWith('ies')) return `${word.slice(0, -3)}y`;
+  if (word.length > 3 && word.endsWith('s') && !word.endsWith('ss')) return word.slice(0, -1);
+  return word;
+};
+
+const searchTerms = (text: string): string[] => text
+  .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+  .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+  .toLowerCase()
+  .split(/[^\p{L}\p{N}]+/u)
+  .filter(Boolean)
+  .map(stem);
+
+const editDistance = (left: string, right: string, limit: number): number => {
+  if (Math.abs(left.length - right.length) > limit) return limit + 1;
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let row = 1; row <= left.length; row++) {
+    const current = [row];
+    let best = row;
+    for (let column = 1; column <= right.length; column++) {
+      const cost = left[row - 1] === right[column - 1] ? 0 : 1;
+      current[column] = Math.min(previous[column] + 1, current[column - 1] + 1, previous[column - 1] + cost);
+      best = Math.min(best, current[column]);
+    }
+    if (best > limit) return limit + 1;
+    previous = current;
+  }
+  return previous[right.length];
+};
+
+const closeMatches = (wanted: string, candidates: Iterable<string>, count = 3): string[] => {
+  const normalized = wanted.toLowerCase();
+  const limit = Math.max(2, Math.floor(normalized.length / 3));
+  const scored: Array<{ name: string; distance: number }> = [];
+  for (const candidate of candidates) {
+    const lower = candidate.toLowerCase();
+    const lastSegment = lower.slice(lower.lastIndexOf('.') + 1);
+    const distance = Math.min(
+      editDistance(normalized, lower, limit),
+      lower.includes(normalized) || normalized.includes(lastSegment) ? 1 : limit + 1,
+    );
+    if (distance <= limit) scored.push({ name: candidate, distance });
+  }
+  return scored
+    .sort((left, right) => left.distance - right.distance || compareCodePoints(left.name, right.name))
+    .slice(0, count)
+    .map((entry) => entry.name);
+};
+
+const preview = (value: unknown): string => {
+  if (value === undefined) return 'missing';
+  let text: string;
+  try {
+    text = JSON.stringify(value) ?? String(value);
+  } catch {
+    text = String(value);
+  }
+  return text.length > 80 ? `${text.slice(0, 77)}...` : text;
+};
+
+const paramsPath = (tokens: readonly (string | number)[]): string => tokens.reduce<string>((path, token) => {
+  if (typeof token === 'number' || /^\d+$/.test(token)) return `${path}[${token}]`;
+  return isIdentifier(token) ? `${path}.${token}` : `${path}[${JSON.stringify(token)}]`;
+}, 'params');
+
+const valueAt = (value: unknown, tokens: readonly (string | number)[]): unknown => {
+  let node = value;
+  for (const token of tokens) {
+    if (Array.isArray(node)) node = node[Number(token)];
+    else if (isSchemaRecord(node)) node = Object.prototype.hasOwnProperty.call(node, token) ? node[String(token)] : undefined;
+    else return undefined;
+  }
+  return node;
+};
+
+const compactType = (text: string): string => {
+  const compact = text.replace(/\/\*\*[\s\S]*?\*\//g, '').replace(/\s+/g, ' ').trim();
+  return compact.length > 200 ? `${compact.slice(0, 197)}...` : compact;
+};
+
+const textOf = (
+  value: unknown,
+  label: string,
+  options: { maxCharacters?: number; maxBytes?: number; singleLine?: boolean },
+): string => {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new FlexHarnessValidationError(`${label} must be a non-empty string.`);
+  }
+  if (options.maxBytes !== undefined) validateUtf8String(value, label, options.maxBytes, true);
+  if (options.maxCharacters !== undefined && [...value].length > options.maxCharacters) {
+    throw new FlexHarnessValidationError(`${label} must be at most ${options.maxCharacters} characters.`);
+  }
+  if (options.singleLine && controlPattern.test(value)) {
+    throw new FlexHarnessValidationError(`${label} must be one line without control characters.`);
+  }
+  return value;
+};
+
+const textListOf = (
+  value: unknown,
+  label: string,
+  maxItems: number,
+  options: { maxCharacters?: number; maxBytes?: number; singleLine?: boolean },
+): string[] => {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > maxItems) {
+    throw new FlexHarnessValidationError(`${label} must be an array with at most ${maxItems} entries.`);
+  }
+  return value.map((entry, index) => textOf(entry, `${label}[${index}]`, options));
+};
+
+async function resolveCatalogSchema(schema: unknown, label: string): Promise<ICatalogSchema> {
+  let json: unknown;
+  let validate: TValidate | undefined;
+  if (
+    typeof schema === 'function'
+    || (isSchemaRecord(schema) && (aiSchemaSymbol in schema || '~standard' in schema))
+  ) {
+    let resolved: plugins.Schema<unknown>;
+    try {
+      resolved = plugins.asSchema(schema as plugins.FlexibleSchema<unknown>);
+      json = await resolved.jsonSchema;
+    } catch (error) {
+      throw new FlexHarnessValidationError(`${label} cannot be converted to JSON Schema.`, { cause: error });
+    }
+    if (resolved.validate) {
+      const validator = resolved.validate;
+      validate = (value) => validator(value);
+    }
+  } else if (isPlainObject(schema) || typeof schema === 'boolean') {
+    json = schema;
+  } else {
+    throw new FlexHarnessValidationError(
+      `${label} must be a JSON Schema object, or a zod, Standard Schema or AI SDK schema.`,
+    );
+  }
+  let copy: unknown;
+  try {
+    copy = structuredClone(json);
+  } catch (error) {
+    throw new FlexHarnessValidationError(`${label} must be plain JSON.`, { cause: error });
+  }
+  if (!isSchemaRecord(copy) && typeof copy !== 'boolean') {
+    throw new FlexHarnessValidationError(`${label} must be a JSON Schema object.`);
+  }
+  validateUtf8String(JSON.stringify(copy), label, limits.maxSchemaBytes, true);
+  return { json: deepFreeze(copy), ...(validate ? { validate } : {}) };
+}
+
+class CatalogSearchIndex {
+  private readonly postings = new Map<string, Array<{ index: number; weight: number }>>();
+  private readonly idf = new Map<string, number>();
+
+  constructor(private readonly entries: readonly IMethodEntry[]) {
+    const fieldTexts = (entry: IMethodEntry): Record<TSearchField, string[]> => ({
+      name: searchTerms(entry.name),
+      namespace: searchTerms(entry.namespace),
+      summary: searchTerms(entry.summary),
+      tags: entry.tags.flatMap(searchTerms),
+      description: searchTerms(entry.description ?? ''),
+    });
+    const documents = entries.map(fieldTexts);
+    const fields = Object.keys(fieldWeights) as TSearchField[];
+    const averageLength = Object.fromEntries(fields.map((field) => [
+      field,
+      Math.max(1, documents.reduce((sum, document) => sum + document[field].length, 0) / Math.max(1, documents.length)),
+    ])) as Record<TSearchField, number>;
+    const documentFrequency = new Map<string, number>();
+    documents.forEach((document, index) => {
+      const weights = new Map<string, number>();
+      for (const field of fields) {
+        const frequencies = new Map<string, number>();
+        for (const term of document[field]) frequencies.set(term, (frequencies.get(term) ?? 0) + 1);
+        const norm = 1 - bm25B + bm25B * (document[field].length / averageLength[field]);
+        for (const [term, frequency] of frequencies) {
+          weights.set(term, (weights.get(term) ?? 0) + fieldWeights[field] * frequency / norm);
+        }
+      }
+      for (const [term, weight] of weights) {
+        documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
+        const postings = this.postings.get(term) ?? [];
+        postings.push({ index, weight });
+        this.postings.set(term, postings);
+      }
+    });
+    for (const [term, frequency] of documentFrequency) {
+      this.idf.set(term, Math.log(1 + (entries.length - frequency + 0.5) / (frequency + 0.5)));
+    }
+  }
+
+  /** Methods ranked by BM25 over name, namespace, summary, tags and description. */
+  public search(query: string, accept: (entry: IMethodEntry) => boolean): IMethodEntry[] {
+    const allTerms = [...new Set(searchTerms(query))];
+    const meaningful = allTerms.filter((term) => !stopWords.has(term));
+    const terms = meaningful.length > 0 ? meaningful : allTerms;
+    const scores = new Map<number, number>();
+    for (const term of terms) {
+      const idf = this.idf.get(term);
+      if (idf === undefined) continue;
+      for (const { index, weight } of this.postings.get(term)!) {
+        scores.set(index, (scores.get(index) ?? 0) + idf * weight * (bm25K1 + 1) / (weight + bm25K1));
+      }
+    }
+    const exact = query.trim().toLowerCase();
+    return [...scores.entries()]
+      .map(([index, score]) => {
+        const entry = this.entries[index];
+        const bonus = entry.path.toLowerCase() === exact || entry.name.toLowerCase() === exact ? 1000 : 0;
+        return { entry, score: score + bonus };
+      })
+      .filter(({ entry }) => accept(entry))
+      .sort((left, right) => right.score - left.score || compareCodePoints(left.entry.path, right.entry.path))
+      .map(({ entry }) => entry);
+  }
+}
+
+class FlexToolCatalogCore {
+  public readonly renderedMethods = new Map<string, IRenderedDeclaration>();
+  public readonly renderedTypes = new Map<string, IRenderedDeclaration>();
+  public readonly validators = new Map<string, plugins.JsonSchemaValidator>();
+  public readonly selfContainedInputs = new Map<string, TJsonSchemaNode>();
+  public readonly index: CatalogSearchIndex;
+
+  constructor(
+    public readonly mode: TDeclarationMode,
+    public readonly methods: ReadonlyMap<string, IMethodEntry>,
+    public readonly types: ReadonlyMap<string, ITypeEntry>,
+  ) {
+    this.index = new CatalogSearchIndex([...methods.values()]);
+  }
+
+  public static async build(catalog: unknown, mode: TDeclarationMode): Promise<FlexToolCatalogCore> {
+    if (!isPlainObject(catalog)) throw new FlexHarnessValidationError('A tool catalog must be a plain object.');
+    const unsupported = Object.keys(catalog).find((key) => key !== 'methods' && key !== 'types');
+    if (unsupported) throw new FlexHarnessValidationError(`A tool catalog does not support "${unsupported}".`);
+    if (!Array.isArray(catalog.methods) || catalog.methods.length > limits.maxMethods) {
+      throw new FlexHarnessValidationError(`Tool catalog methods must be an array with at most ${limits.maxMethods} entries.`);
+    }
+    if (catalog.types !== undefined && (!Array.isArray(catalog.types) || catalog.types.length > limits.maxTypes)) {
+      throw new FlexHarnessValidationError(`Tool catalog types must be an array with at most ${limits.maxTypes} entries.`);
+    }
+    const catalogTypes = new Map<string, ITypeEntry>();
+    for (const [index, type] of ((catalog.types ?? []) as unknown[]).entries()) {
+      const entry = await FlexToolCatalogCore.normalizeType(type, `Tool catalog type ${index}`);
+      if (catalogTypes.has(entry.name)) {
+        throw new FlexHarnessValidationError(`Tool catalog type "${entry.name}" is defined twice.`);
+      }
+      catalogTypes.set(entry.name, entry);
+    }
+    const methodInputs: Array<Omit<IMethodEntry, 'inputScope' | 'outputScope'>> = [];
+    for (const [index, method] of (catalog.methods as unknown[]).entries()) {
+      methodInputs.push(await FlexToolCatalogCore.normalizeMethod(method, `Tool catalog method ${index}`));
+    }
+    methodInputs.sort((left, right) => compareCodePoints(left.path, right.path));
+    const paths = new Set<string>();
+    for (const method of methodInputs) {
+      if (paths.has(method.path)) throw new FlexHarnessValidationError(`Tool catalog method "${method.path}" is defined twice.`);
+      paths.add(method.path);
+    }
+    for (const method of methodInputs) {
+      for (let end = method.path.indexOf('.'); end !== -1; end = method.path.indexOf('.', end + 1)) {
+        const namespace = method.path.slice(0, end);
+        if (paths.has(namespace)) {
+          throw new FlexHarnessValidationError(`Tool catalog path "${namespace}" is both a method and a namespace.`);
+        }
+      }
+    }
+
+    const registry = new Map<string, ITypeEntry>(catalogTypes);
+    const canonicalDefinitions = new Map<string, string>();
+    const scopeOf = (root: TJsonSchemaNode, label: string, requireSchemas: boolean): ISchemaScope => {
+      const scope: ISchemaScope = { root, localNames: new Map() };
+      FlexToolCatalogCore.checkRefs(root, label, catalogTypes, requireSchemas);
+      if (!isSchemaRecord(root)) return scope;
+      for (const container of ['$defs', 'definitions']) {
+        const definitions = root[container];
+        if (!isSchemaRecord(definitions)) continue;
+        for (const key of Object.keys(definitions).sort(compareCodePoints)) {
+          if (!typeNamePattern.test(key) || reservedWords.has(key) || key.length > limits.maxIdentifierCharacters) continue;
+          const definition = definitions[key] as TJsonSchemaNode;
+          const canonical = stableStringify(definition);
+          let name = key;
+          for (let suffix = 2; ; suffix++) {
+            const existing = registry.get(name);
+            if (!existing) {
+              registry.set(name, { name, definition, scope });
+              canonicalDefinitions.set(name, canonical);
+              break;
+            }
+            if (existing.definition === undefined || canonicalDefinitions.get(name) === canonical) break;
+            name = `${key}_${suffix}`;
+          }
+          scope.localNames.set(`${container}/${key}`, name);
+        }
+      }
+      return scope;
+    };
+    for (const type of catalogTypes.values()) {
+      if (!type.schema) continue;
+      registry.set(type.name, { ...type, scope: scopeOf(type.schema.json, `Tool catalog type "${type.name}"`, true) });
+    }
+    const methods = new Map<string, IMethodEntry>();
+    for (const method of methodInputs) {
+      methods.set(method.path, {
+        ...method,
+        inputScope: scopeOf(method.input.json, `Tool catalog method "${method.path}" inputSchema`, true),
+        ...(method.output
+          ? { outputScope: scopeOf(method.output.json, `Tool catalog method "${method.path}" outputSchema`, false) }
+          : {}),
+      });
+    }
+    const types = new Map([...registry.entries()].sort(([left], [right]) => compareCodePoints(left, right)));
+    return new FlexToolCatalogCore(mode, methods, types);
+  }
+
+  private static async normalizeType(value: unknown, label: string): Promise<ITypeEntry> {
+    if (!isPlainObject(value)) throw new FlexHarnessValidationError(`${label} must be a plain object.`);
+    const unsupported = Object.keys(value).find((key) => !typeKeys.has(key));
+    if (unsupported) throw new FlexHarnessValidationError(`${label} does not support "${unsupported}".`);
+    const name = textOf(value.name, `${label} name`, { maxCharacters: limits.maxIdentifierCharacters, singleLine: true });
+    if (!typeNamePattern.test(name) || reservedWords.has(name)) {
+      throw new FlexHarnessValidationError(`${label} name must be an identifier that is not a reserved word.`);
+    }
+    if (value.schema === undefined && value.declaration === undefined) {
+      throw new FlexHarnessValidationError(`Tool catalog type "${name}" needs a schema or a declaration.`);
+    }
+    const description = value.description === undefined
+      ? undefined
+      : textOf(value.description, `Tool catalog type "${name}" description`, { maxBytes: limits.maxDescriptionBytes });
+    const declaration = value.declaration === undefined
+      ? undefined
+      : textOf(value.declaration, `Tool catalog type "${name}" declaration`, { maxBytes: limits.maxDeclarationBytes });
+    if (declaration !== undefined && !new RegExp(`\\b(?:interface|type|enum|class)\\s+${name}\\b`).test(declaration)) {
+      throw new FlexHarnessValidationError(`Tool catalog type "${name}" declaration must declare "${name}".`);
+    }
+    const schema = value.schema === undefined
+      ? undefined
+      : await resolveCatalogSchema(value.schema, `Tool catalog type "${name}" schema`);
+    if (schema && isSchemaRecord(schema.json) && (schema.json.$defs !== undefined || schema.json.definitions !== undefined)) {
+      throw new FlexHarnessValidationError(
+        `Tool catalog type "${name}" schema must refer to other catalog types instead of defining $defs.`,
+      );
+    }
+    return {
+      name,
+      ...(description === undefined ? {} : { description }),
+      ...(declaration === undefined ? {} : { declaration }),
+      ...(schema === undefined ? {} : { schema }),
+    };
+  }
+
+  private static async normalizeMethod(
+    value: unknown,
+    label: string,
+  ): Promise<Omit<IMethodEntry, 'inputScope' | 'outputScope'>> {
+    if (!isPlainObject(value)) throw new FlexHarnessValidationError(`${label} must be a plain object.`);
+    const unsupported = Object.keys(value).find((key) => !methodKeys.has(key));
+    if (unsupported) throw new FlexHarnessValidationError(`${label} does not support "${unsupported}".`);
+    const path = textOf(value.method, `${label} method`, { maxCharacters: limits.maxMethodPathCharacters, singleLine: true });
+    const segments = path.split('.');
+    if (
+      !methodPathPattern.test(path)
+      || segments.length > limits.maxMethodPathSegments
+      || segments.some((segment) => segment.length > limits.maxIdentifierCharacters)
+    ) {
+      throw new FlexHarnessValidationError(
+        `${label} method "${path}" must be a dotted path of at most ${limits.maxMethodPathSegments} identifiers.`,
+      );
+    }
+    const reserved = segments.find((segment) => reservedWords.has(segment));
+    if (reserved) {
+      throw new FlexHarnessValidationError(
+        `${label} method "${path}" uses the reserved word "${reserved}", which a declaration cannot name.`,
+      );
+    }
+    const methodLabel = `Tool catalog method "${path}"`;
+    const summary = textOf(value.summary, `${methodLabel} summary`, {
+      maxCharacters: limits.maxSummaryCharacters, singleLine: true,
+    }).trim();
+    const description = value.description === undefined
+      ? undefined
+      : textOf(value.description, `${methodLabel} description`, { maxBytes: limits.maxDescriptionBytes }).trim();
+    const tags = textListOf(value.tags, `${methodLabel} tags`, limits.maxTags, {
+      maxCharacters: limits.maxTagCharacters, singleLine: true,
+    });
+    const examples = textListOf(value.examples, `${methodLabel} examples`, limits.maxExamples, {
+      maxBytes: limits.maxExampleBytes,
+    });
+    const name = segments[segments.length - 1];
+    const declaration = value.declaration === undefined
+      ? undefined
+      : textOf(value.declaration, `${methodLabel} declaration`, { maxBytes: limits.maxDeclarationBytes });
+    if (declaration !== undefined && !new RegExp(`\\bfunction\\s+${name}\\s*[<(]`).test(declaration)) {
+      throw new FlexHarnessValidationError(`${methodLabel} declaration must declare "function ${name}(".`);
+    }
+    if (typeof value.run !== 'function') throw new FlexHarnessValidationError(`${methodLabel} run must be a function.`);
+    if (value.inputSchema === undefined) throw new FlexHarnessValidationError(`${methodLabel} needs an inputSchema.`);
+    const input = await resolveCatalogSchema(value.inputSchema, `${methodLabel} inputSchema`);
+    const inputJson = input.json;
+    const describesObject = isSchemaRecord(inputJson) && (
+      inputJson.type === 'object'
+      || (Array.isArray(inputJson.type) && inputJson.type.includes('object'))
+      || (inputJson.type === undefined && (inputJson.properties !== undefined || inputJson.$ref !== undefined
+        || inputJson.anyOf !== undefined || inputJson.oneOf !== undefined || inputJson.allOf !== undefined))
+    );
+    if (!describesObject) throw new FlexHarnessValidationError(`${methodLabel} inputSchema must describe an object.`);
+    const output = value.outputSchema === undefined
+      ? undefined
+      : await resolveCatalogSchema(value.outputSchema, `${methodLabel} outputSchema`);
+    const run = value.run as IFlexCatalogMethod['run'];
+    return {
+      path,
+      namespace: segments.slice(0, -1).join('.'),
+      name,
+      summary,
+      ...(description ? { description } : {}),
+      tags: Object.freeze(tags),
+      examples: Object.freeze(examples),
+      input,
+      ...(output ? { output } : {}),
+      ...(declaration === undefined ? {} : { declaration }),
+      run: (params, context) => run.call(value, params, context),
+    };
+  }
+
+  /** Every `$ref` must be local and resolve here or, as a definition reference, to a catalog type. */
+  private static checkRefs(
+    root: TJsonSchemaNode,
+    label: string,
+    catalogTypes: ReadonlyMap<string, ITypeEntry>,
+    requireSchemas: boolean,
+  ): void {
+    const refs = new Set<string>();
+    collectRefs(root, refs);
+    const pending = [...refs];
+    const visited = new Set<string>();
+    while (pending.length > 0) {
+      const ref = pending.pop()!;
+      if (visited.has(ref)) continue;
+      visited.add(ref);
+      if (!ref.startsWith('#')) throw new FlexHarnessValidationError(`${label} has the non-local $ref "${ref}".`);
+      if (resolvePointer(root, ref) !== undefined) continue;
+      const match = definitionRefPattern.exec(ref);
+      const type = match ? catalogTypes.get(decodePointerToken(match[2])) : undefined;
+      if (!type) throw new FlexHarnessValidationError(`${label} has the unresolved $ref "${ref}".`);
+      if (!requireSchemas) continue;
+      if (!type.schema) {
+        throw new FlexHarnessValidationError(
+          `${label} refers to type "${type.name}", which has no schema to validate with.`,
+        );
+      }
+      const nested = new Set<string>();
+      collectRefs(type.schema.json, nested);
+      pending.push(...nested);
+    }
+  }
+
+  public scopeContext(scope: ISchemaScope) {
+    return {
+      namedType: (ref: string): string | undefined => {
+        const match = definitionRefPattern.exec(ref);
+        if (!match) return undefined;
+        const key = decodePointerToken(match[2]);
+        const local = scope.localNames.get(`${match[1]}/${key}`);
+        if (local) return local;
+        if (resolvePointer(scope.root, ref) !== undefined) return undefined;
+        return this.types.has(key) ? key : undefined;
+      },
+      resolve: (ref: string): TJsonSchemaNode | undefined => {
+        const target = resolvePointer(scope.root, ref);
+        return isSchemaRecord(target) || typeof target === 'boolean' ? target : undefined;
+      },
+    };
+  }
+
+  public renderType(name: string): IRenderedDeclaration {
+    const cached = this.renderedTypes.get(name);
+    if (cached) return cached;
+    const type = this.types.get(name)!;
+    let rendered: IRenderedDeclaration;
+    if (type.declaration !== undefined) {
+      rendered = { text: type.declaration.trim(), types: this.scanTypes(type.declaration, name) };
+    } else {
+      const schema = type.definition ?? type.schema!.json;
+      const writer = new SchemaDeclarationWriter(this.scopeContext(type.scope!));
+      const text = writer.namedDeclaration(name, schema, type.description);
+      rendered = { text, types: writer.usedTypes.filter((used) => used !== name) };
+    }
+    this.renderedTypes.set(name, rendered);
+    return rendered;
+  }
+
+  public renderMethod(entry: IMethodEntry): IRenderedDeclaration {
+    const cached = this.renderedMethods.get(entry.path);
+    if (cached) return cached;
+    let rendered: IRenderedDeclaration;
+    if (entry.declaration !== undefined) {
+      rendered = { text: entry.declaration.trim(), types: this.scanTypes(entry.declaration) };
+    } else {
+      const inputWriter = new SchemaDeclarationWriter(this.scopeContext(entry.inputScope));
+      const members = inputWriter.objectMembers(entry.input.json);
+      const paramsType = inputWriter.type(entry.input.json, '', 0, members !== undefined);
+      const optional = inputWriter.hasNoRequiredProperties(entry.input.json) ? '?' : '';
+      const outputWriter = entry.output && entry.outputScope
+        ? new SchemaDeclarationWriter(this.scopeContext(entry.outputScope))
+        : undefined;
+      const resultType = outputWriter ? outputWriter.type(entry.output!.json) : 'unknown';
+      const lines = [entry.summary];
+      if (entry.description && entry.description !== entry.summary) lines.push('', ...entry.description.split('\n'));
+      for (const member of members ?? []) {
+        if (member.doc === undefined) continue;
+        const key = isIdentifier(member.name) ? `.${member.name}` : `[${JSON.stringify(member.name)}]`;
+        lines.push(`@param params${key} ${member.doc.replace(/\s*\n\s*/g, ' ')}`);
+      }
+      for (const example of entry.examples) {
+        lines.push(...(example.includes('\n') ? ['@example', ...example.split('\n')] : [`@example ${example}`]));
+      }
+      const signature = `function ${entry.name}(params${optional}: ${paramsType}): Promise<${resultType}>;`;
+      rendered = {
+        text: `${docBlock(lines.join('\n'), '')}${signature}`,
+        types: [...new Set([...inputWriter.usedTypes, ...(outputWriter?.usedTypes ?? [])])].sort(compareCodePoints),
+      };
+    }
+    this.renderedMethods.set(entry.path, rendered);
+    return rendered;
+  }
+
+  private scanTypes(text: string, self?: string): string[] {
+    const found = new Set<string>();
+    for (const match of text.matchAll(identifierScanPattern)) {
+      if (match[0] !== self && this.types.has(match[0])) found.add(match[0]);
+    }
+    return [...found].sort(compareCodePoints);
+  }
+
+  /** `names` and every type they use, transitively, sorted. */
+  public typeClosure(names: Iterable<string>, stop: ReadonlySet<string> = new Set()): string[] {
+    const result = new Set<string>();
+    const pending = [...names];
+    while (pending.length > 0) {
+      const name = pending.pop()!;
+      if (result.has(name) || stop.has(name) || !this.types.has(name)) continue;
+      result.add(name);
+      pending.push(...this.renderType(name).types);
+    }
+    return [...result].sort(compareCodePoints);
+  }
+
+  /** The method's input schema with the catalog types it refers to added as definitions. */
+  public selfContainedInput(entry: IMethodEntry): TJsonSchemaNode {
+    const cached = this.selfContainedInputs.get(entry.path);
+    if (cached !== undefined) return cached;
+    const root = structuredClone(entry.input.json) as TJsonSchemaNode;
+    if (isSchemaRecord(root)) {
+      const pending = new Set<string>();
+      collectRefs(root, pending);
+      const queue = [...pending];
+      while (queue.length > 0) {
+        const ref = queue.pop()!;
+        const match = definitionRefPattern.exec(ref);
+        if (!match || resolvePointer(root, ref) !== undefined) continue;
+        const type = this.types.get(decodePointerToken(match[2]));
+        if (!type?.schema) continue;
+        const container = (isSchemaRecord(root[match[1]]) ? root[match[1]] : (root[match[1]] = {})) as Record<string, unknown>;
+        container[decodePointerToken(match[2])] = withoutDraft(structuredClone(type.schema.json) as TJsonSchemaNode);
+        const nested = new Set<string>();
+        collectRefs(type.schema.json, nested);
+        queue.push(...nested);
+      }
+    }
+    deepFreeze(root);
+    this.selfContainedInputs.set(entry.path, root);
+    return root;
+  }
+
+  public validator(entry: IMethodEntry): plugins.JsonSchemaValidator {
+    let validator = this.validators.get(entry.path);
+    if (!validator) {
+      const root = structuredClone(this.selfContainedInput(entry));
+      validator = new plugins.JsonSchemaValidator(root as never, schemaDraft(root), false);
+      this.validators.set(entry.path, validator);
+    }
+    return validator;
+  }
+}
+
+/**
+ * A tool catalog prepared for the model: search, TypeScript declarations, parameter validation and
+ * dispatch. FlexHarness builds one for every catalog a tool provider returns; it is public so a
+ * host can check what its catalog shows the model, and measure it, without running a session.
+ */
+export class FlexToolCatalog<TScope = unknown> {
+  private namespaceTree?: Map<string, { methods: IMethodEntry[]; children: Map<string, number> }>;
+
+  private constructor(
+    private readonly core: FlexToolCatalogCore,
+    private readonly admitted: ReadonlySet<string> | undefined,
+  ) {}
+
+  /**
+   * Prepares `catalog`. Preparing the same object again returns the cached preparation, so a host
+   * that returns one catalog object for every run pays for it once.
+   */
+  public static async create<TScope = unknown>(
+    catalog: IFlexToolCatalog<TScope>,
+    options: IFlexToolCatalogOptions = {},
+  ): Promise<FlexToolCatalog<TScope>> {
+    const mode = options.declarations ?? 'typescript';
+    if (!describeFormats.has(mode)) {
+      throw new FlexHarnessValidationError('toolCatalog.declarations must be "typescript" or "json-schema".');
+    }
+    if (typeof catalog !== 'object' || catalog === null) {
+      throw new FlexHarnessValidationError('A tool catalog must be a plain object.');
+    }
+    let byMode = coreCache.get(catalog);
+    if (!byMode) {
+      byMode = new Map();
+      coreCache.set(catalog, byMode);
+    }
+    let core = byMode.get(mode);
+    if (!core) {
+      core = FlexToolCatalogCore.build(catalog, mode);
+      byMode.set(mode, core);
+    }
+    return new FlexToolCatalog<TScope>(await core, undefined);
+  }
+
+  /** Every method path this catalog offers, sorted. */
+  public get methods(): string[] {
+    return [...this.core.methods.keys()].filter((path) => this.isAdmitted(path));
+  }
+
+  /** Every named type, sorted. */
+  public get types(): string[] {
+    return [...this.core.types.keys()];
+  }
+
+  /** The same catalog offering only `paths`. */
+  public restrict(paths: Iterable<string>): FlexToolCatalog<TScope> {
+    const allowed = new Set(paths);
+    return new FlexToolCatalog<TScope>(
+      this.core,
+      new Set([...this.core.methods.keys()].filter((path) => allowed.has(path) && this.isAdmitted(path))),
+    );
+  }
+
+  public has(path: string): boolean {
+    return this.core.methods.has(path) && this.isAdmitted(path);
+  }
+
+  /** The three built-in tools as the model sees them. Their text depends only on the catalog. */
+  public toolDefinitions(): Record<string, IFlexCatalogToolDefinition> {
+    const typescript = this.core.mode === 'typescript';
+    const methodPath = { type: 'string', maxLength: limits.maxMethodPathCharacters } as const;
+    return {
+      [toolNames.search]: {
+        description: [
+          'Search the API catalog. Its methods are called with execute, not as tools. `query` ranks methods by',
+          'name, summary and description; `namespace` (a dotted path) narrows the search or, without `query`, lists',
+          `the namespace like ls. Read a method's ${typescript ? 'TypeScript declaration' : 'description and JSON Schema'}`,
+          'with describe_tools before calling it.',
+          this.topLevelLine(),
+        ].join(' '),
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', maxLength: limits.maxQueryCharacters },
+            namespace: methodPath,
+            limit: { type: 'integer', minimum: 1, maximum: limits.maxSearchResults },
+            offset: { type: 'integer', minimum: 0 },
+          },
+          additionalProperties: false,
+        },
+      },
+      [toolNames.describe]: {
+        description: typescript
+          ? 'Return the TypeScript declarations of catalog methods (`methods`: dotted paths) and named types (`types`). '
+            + 'A declaration comes with the named types it uses that this conversation has not declared yet.'
+          : 'Return the description and JSON Schema of catalog methods (`methods`: dotted paths) and named types (`types`).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            methods: { type: 'array', items: methodPath, maxItems: limits.maxDescribeMethods },
+            types: {
+              type: 'array',
+              items: { type: 'string', maxLength: limits.maxIdentifierCharacters },
+              maxItems: limits.maxDescribeTypes,
+            },
+          },
+          additionalProperties: false,
+        },
+      },
+      [toolNames.execute]: {
+        description: 'Call a catalog method: `method` is its dotted path, `params` the parameter object of its '
+          + 'declaration. Invalid params return an error naming each path, what was expected and what was given.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            method: { ...methodPath, minLength: 1 },
+            params: { type: 'object' },
+          },
+          required: ['method'],
+          additionalProperties: false,
+        },
+      },
+    };
+  }
+
+  /** Search results or a namespace listing as text. */
+  public search(input: IFlexCatalogSearchInput = {}): string {
+    const limit = input.limit ?? limits.defaultSearchResults;
+    const offset = input.offset ?? 0;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > limits.maxSearchResults) {
+      throw new FlexHarnessValidationError(`limit must be an integer from 1 through ${limits.maxSearchResults}.`);
+    }
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new FlexHarnessValidationError('offset must be a non-negative integer.');
+    const namespace = (input.namespace ?? '').trim().replace(/\.\*?$/, '');
+    const tree = this.tree();
+    if (namespace && !tree.has(namespace)) {
+      if (this.has(namespace)) {
+        return `${namespace} is a method, not a namespace; read it with describe_tools.`;
+      }
+      const suggestions = closeMatches(namespace, [...tree.keys()].filter(Boolean));
+      return [
+        `There is no namespace ${namespace}.${suggestions.length ? ` Did you mean ${suggestions.join(', ')}?` : ''}`,
+        this.topLevelLine(),
+      ].join('\n');
+    }
+    const query = (input.query ?? '').trim();
+    if (query) {
+      const prefix = namespace ? `${namespace}.` : '';
+      const matches = this.core.index.search(query, (entry) => this.isAdmitted(entry.path) && entry.path.startsWith(prefix));
+      if (matches.length === 0) {
+        return [`No methods match "${query}"${namespace ? ` in ${namespace}` : ''}.`, this.topLevelLine()].join('\n');
+      }
+      return this.page(matches.map((entry) => `${entry.path} - ${entry.summary}`), offset, limit, 'matches');
+    }
+    const node = tree.get(namespace)!;
+    const lines = [...node.children.entries()].map(([child, count]) => `${child}.* (${count} method${count === 1 ? '' : 's'})`);
+    const methodLines = node.methods.map((entry) => `${entry.path} - ${entry.summary}`);
+    if (methodLines.length === 0) return lines.join('\n') || 'The catalog has no methods.';
+    return [...lines, this.page(methodLines, offset, limit, 'methods')].filter(Boolean).join('\n');
+  }
+
+  /**
+   * The declarations of `input.methods` and `input.types`. Method declarations bring the named
+   * types they use, minus `declaredTypes`, which a session already has.
+   */
+  public describe(
+    input: IFlexCatalogDescribeInput,
+    options: { declaredTypes?: Iterable<string>; maxBytes?: number } = {},
+  ): IFlexCatalogDescribeResult {
+    const requestedMethods = [...new Set(input.methods ?? [])];
+    const requestedTypes = [...new Set(input.types ?? [])];
+    if (requestedMethods.length > limits.maxDescribeMethods || requestedTypes.length > limits.maxDescribeTypes) {
+      throw new FlexHarnessValidationError(
+        `describe_tools takes at most ${limits.maxDescribeMethods} methods and ${limits.maxDescribeTypes} types.`,
+      );
+    }
+    const maxBytes = Math.min(options.maxBytes ?? limits.maxDescribeBytes, limits.maxDescribeBytes);
+    const entries = requestedMethods.filter((path) => this.has(path)).sort(compareCodePoints)
+      .map((path) => this.core.methods.get(path)!);
+    const unknownMethods = requestedMethods.filter((path) => !this.has(path)).sort(compareCodePoints);
+    const knownTypes = requestedTypes.filter((name) => this.core.types.has(name)).sort(compareCodePoints);
+    const unknownTypes = requestedTypes.filter((name) => !this.core.types.has(name)).sort(compareCodePoints);
+    const notes = [
+      ...unknownMethods.map((path) => {
+        const suggestions = closeMatches(path, this.methods);
+        return `Unknown method ${path}.${suggestions.length ? ` Did you mean ${suggestions.join(', ')}?` : ' Find methods with search_tools.'}`;
+      }),
+      ...unknownTypes.map((name) => {
+        const suggestions = closeMatches(name, this.core.types.keys());
+        return `Unknown type ${name}.${suggestions.length ? ` Did you mean ${suggestions.join(', ')}?` : ''}`;
+      }),
+    ];
+    if (requestedMethods.length === 0 && requestedTypes.length === 0) {
+      notes.push('Pass methods (dotted paths) or types to describe.');
+    }
+    return this.core.mode === 'json-schema'
+      ? this.describeJson(entries, knownTypes, notes, maxBytes)
+      : this.describeTypescript(entries, knownTypes, notes, new Set(options.declaredTypes ?? []), maxBytes);
+  }
+
+  /** The named types `describe_tools` results in `messages` declared. */
+  public declaredTypesIn(messages: readonly plugins.ModelMessage[] | undefined): Set<string> {
+    const declared = new Set<string>();
+    for (const message of messages ?? []) {
+      if (message.role !== 'tool' || !Array.isArray(message.content)) continue;
+      for (const part of message.content) {
+        if (part.type !== 'tool-result' || part.toolName !== toolNames.describe) continue;
+        const output = part.output as { type?: string; value?: unknown };
+        if (output.type !== 'text' || typeof output.value !== 'string' || !output.value.startsWith(declaredTypesHeader)) continue;
+        const lineEnd = output.value.indexOf('\n');
+        const header = output.value.slice(declaredTypesHeader.length, lineEnd === -1 ? undefined : lineEnd);
+        for (const name of header.split(', ')) if (this.core.types.has(name)) declared.add(name);
+      }
+    }
+    return declared;
+  }
+
+  /**
+   * Resolves and validates a call. A failure is the error `execute` reports to the model; success
+   * returns the run with the validated parameters. A schema validator that throws rejects.
+   */
+  public async prepareCall(method: unknown, params: unknown): Promise<IPreparedCall | IFailedCall> {
+    const path = typeof method === 'string' ? method : '';
+    if (!this.has(path)) {
+      const isNamespace = path !== '' && this.tree().has(path);
+      return {
+        success: false,
+        error: {
+          error: 'unknown_method',
+          method: path,
+          didYouMean: isNamespace ? [] : closeMatches(path, this.methods),
+          hint: isNamespace
+            ? `${path} is a namespace; list it with search_tools({"namespace":"${path}"}).`
+            : 'Find methods with search_tools.',
+        },
+      };
+    }
+    const entry = this.core.methods.get(path)!;
+    const value = params === undefined ? {} : params;
+    const issues = this.validateStructure(entry, value);
+    let validated: unknown = value;
+    if (issues.length === 0 && entry.input.validate) {
+      // A validator that throws failed itself; only a failure it reports is the model's to repair.
+      const result = await entry.input.validate(value);
+      if (result.success) validated = result.value;
+      else issues.push(...this.foreignIssues(result.error, value));
+    }
+    if (issues.length > 0) {
+      const listed = issues.slice(0, limits.maxParamIssues);
+      return {
+        success: false,
+        error: {
+          error: 'invalid_params',
+          method: path,
+          issues: listed,
+          ...(issues.length > listed.length ? { more: issues.length - listed.length } : {}),
+          see: `describe_tools({"methods":["${path}"]})`,
+        },
+      };
+    }
+    return {
+      success: true,
+      method: path,
+      params: validated,
+      run: (context) => entry.run(validated, context),
+    };
+  }
+
+  /** The real method and params of an `execute` input, when it names a method of this catalog. */
+  public callTarget(input: unknown): { method: string; params: unknown } | undefined {
+    if (!isSchemaRecord(input) || typeof input.method !== 'string' || !this.has(input.method)) return undefined;
+    return { method: input.method, params: input.params === undefined ? {} : input.params };
+  }
+
+  private isAdmitted(path: string): boolean {
+    return this.admitted === undefined || this.admitted.has(path);
+  }
+
+  private tree(): Map<string, { methods: IMethodEntry[]; children: Map<string, number> }> {
+    if (this.namespaceTree) return this.namespaceTree;
+    const tree = new Map<string, { methods: IMethodEntry[]; children: Map<string, number> }>();
+    const node = (namespace: string) => {
+      let entry = tree.get(namespace);
+      if (!entry) {
+        entry = { methods: [], children: new Map() };
+        tree.set(namespace, entry);
+      }
+      return entry;
+    };
+    node('');
+    for (const entry of this.core.methods.values()) {
+      if (!this.isAdmitted(entry.path)) continue;
+      node(entry.namespace).methods.push(entry);
+      const segments = entry.path.split('.');
+      for (let depth = 1; depth < segments.length; depth++) {
+        const parent = segments.slice(0, depth - 1).join('.');
+        const child = segments.slice(0, depth).join('.');
+        const children = node(parent).children;
+        children.set(child, (children.get(child) ?? 0) + 1);
+        node(child);
+      }
+    }
+    for (const entry of tree.values()) {
+      entry.children = new Map([...entry.children.entries()].sort(([left], [right]) => compareCodePoints(left, right)));
+    }
+    this.namespaceTree = tree;
+    return tree;
+  }
+
+  private topLevelLine(): string {
+    const root = this.tree().get('')!;
+    const namespaces = [...root.children.entries()];
+    const shown = namespaces.slice(0, 40).map(([name, count]) => `${name}.* (${count})`);
+    if (namespaces.length > shown.length) shown.push(`${namespaces.length - shown.length} more namespaces`);
+    if (root.methods.length > 0) {
+      shown.push(namespaces.length > 0
+        ? `${root.methods.length} top-level method${root.methods.length === 1 ? '' : 's'}`
+        : `${root.methods.length} method${root.methods.length === 1 ? '' : 's'}`);
+    }
+    return `Top level: ${shown.join(', ') || 'no methods'}.`;
+  }
+
+  private page(lines: string[], offset: number, limit: number, noun: string): string {
+    const shown = lines.slice(offset, offset + limit);
+    if (shown.length === 0) return `No more ${noun}: there are ${lines.length}.`;
+    if (offset === 0 && shown.length === lines.length) return shown.join('\n');
+    const end = offset + shown.length;
+    const more = end < lines.length ? `; pass offset ${end} for more` : '';
+    return [...shown, `Showing ${offset + 1}-${end} of ${lines.length} ${noun}${more}.`].join('\n');
+  }
+
+  private describeTypescript(
+    entries: IMethodEntry[],
+    requestedTypes: string[],
+    notes: string[],
+    declared: ReadonlySet<string>,
+    maxBytes: number,
+  ): IFlexCatalogDescribeResult {
+    const included: IMethodEntry[] = [];
+    const omitted: string[] = [];
+    const alreadyDeclared = new Set([...declared].filter((name) => !requestedTypes.includes(name)));
+    let types = this.core.typeClosure(requestedTypes, alreadyDeclared);
+    const assemble = (methods: IMethodEntry[], typeNames: string[], skipped: string[]): string => {
+      const used = new Set(methods.flatMap((entry) => this.core.typeClosure(this.core.renderMethod(entry).types)));
+      const earlier = [...used].filter((name) => declared.has(name) && !typeNames.includes(name)).sort(compareCodePoints);
+      const blocks: string[] = [];
+      if (typeNames.length) blocks.push(`${declaredTypesHeader}${typeNames.join(', ')}`);
+      for (const name of typeNames) blocks.push(this.core.renderType(name).text);
+      const byNamespace = new Map<string, IMethodEntry[]>();
+      for (const entry of methods) byNamespace.set(entry.namespace, [...(byNamespace.get(entry.namespace) ?? []), entry]);
+      for (const [namespace, members] of byNamespace) {
+        const texts = members.map((entry) => this.core.renderMethod(entry).text);
+        if (namespace) blocks.push(`declare namespace ${namespace} {\n${indentLines(texts.join('\n'), '  ')}\n}`);
+        else blocks.push(...texts.map(withDeclare));
+      }
+      const trailing = [
+        ...(earlier.length ? [`Declared earlier: ${earlier.join(', ')}; describe_tools({"types":[...]}) declares them again.`] : []),
+        ...notes,
+        ...(skipped.length ? [`Not included to stay within the size limit: ${skipped.join(', ')}; describe them in another call.`] : []),
+      ];
+      if (trailing.length) blocks.push(trailing.map((note) => `// ${note}`).join('\n'));
+      return blocks.join('\n\n');
+    };
+    for (const entry of entries) {
+      const candidate = [...included, entry];
+      const candidateTypes = this.core.typeClosure(
+        [...requestedTypes, ...candidate.flatMap((method) => this.core.renderMethod(method).types)],
+        alreadyDeclared,
+      );
+      const text = assemble(candidate, candidateTypes, entries.slice(candidate.length).map((method) => method.path));
+      if (Buffer.byteLength(JSON.stringify(text), 'utf8') > maxBytes && included.length > 0) {
+        omitted.push(...entries.slice(included.length).map((method) => method.path));
+        break;
+      }
+      included.push(entry);
+      types = candidateTypes;
+    }
+    const text = assemble(included, types, omitted);
+    return { output: text, declaredTypes: types };
+  }
+
+  private describeJson(
+    entries: IMethodEntry[],
+    requestedTypes: string[],
+    notes: string[],
+    maxBytes: number,
+  ): IFlexCatalogDescribeResult {
+    const methods: TJsonValue[] = [];
+    const omitted: string[] = [];
+    const typeSchemas = requestedTypes.flatMap((name) => {
+      const type = this.core.types.get(name)!;
+      const schema = type.definition ?? type.schema?.json;
+      return [{
+        name,
+        ...(type.description ? { description: type.description } : {}),
+        ...(schema === undefined ? { declaration: type.declaration! } : { schema: withoutDraft(schema) }),
+      }];
+    });
+    let size = Buffer.byteLength(JSON.stringify({ types: typeSchemas, notes }), 'utf8');
+    for (const entry of entries) {
+      const method = {
+        method: entry.path,
+        summary: entry.summary,
+        ...(entry.description ? { description: entry.description } : {}),
+        inputSchema: withoutDraft(this.core.selfContainedInput(entry)),
+        ...(entry.output ? { outputSchema: withoutDraft(entry.output.json) } : {}),
+        ...(entry.examples.length ? { examples: [...entry.examples] } : {}),
+      } as TJsonValue;
+      const bytes = Buffer.byteLength(JSON.stringify(method), 'utf8') + 1;
+      if (methods.length > 0 && size + bytes > maxBytes) {
+        omitted.push(...entries.slice(methods.length).map((skipped) => skipped.path));
+        break;
+      }
+      size += bytes;
+      methods.push(method);
+    }
+    return {
+      output: JSON.parse(JSON.stringify({
+        methods,
+        ...(typeSchemas.length ? { types: typeSchemas } : {}),
+        ...(notes.length ? { notes } : {}),
+        ...(omitted.length ? { omitted } : {}),
+      })) as TJsonValue,
+      declaredTypes: [],
+    };
+  }
+
+  /** Issues the method's JSON Schema finds in `value`. */
+  private validateStructure(entry: IMethodEntry, value: unknown): IFlexCatalogParamIssue[] {
+    const result = this.core.validator(entry).validate(value);
+    if (result.valid) return [];
+    const root = this.core.selfContainedInput(entry);
+    const writer = new SchemaDeclarationWriter({
+      namedType: (ref) => {
+        const match = definitionRefPattern.exec(ref);
+        const key = match ? decodePointerToken(match[2]) : undefined;
+        return key && typeNamePattern.test(key) ? key : undefined;
+      },
+      resolve: (ref) => {
+        const target = resolvePointer(root, ref);
+        return isSchemaRecord(target) || typeof target === 'boolean' ? target : undefined;
+      },
+    });
+    const typeText = (schema: unknown): string =>
+      isSchemaRecord(schema) || typeof schema === 'boolean' ? compactType(writer.type(schema)) : 'a value';
+    const issues: IFlexCatalogParamIssue[] = [];
+    const covered: string[] = [];
+    let container: (typeof result.errors)[number] | undefined;
+    for (const unit of result.errors) {
+      if (covered.some((prefix) => unit.keywordLocation.startsWith(`${prefix}/`))) continue;
+      const tokens = pointerTokens(unit.instanceLocation);
+      const path = paramsPath(tokens);
+      const got = preview(valueAt(value, tokens));
+      const schemaHere = resolvePointer(root, unit.keywordLocation);
+      const parent = resolvePointer(root, unit.keywordLocation.slice(0, unit.keywordLocation.lastIndexOf('/')));
+      switch (unit.keyword) {
+        case 'additionalProperties':
+        case 'unevaluatedProperties':
+          container = unit;
+          continue;
+        case 'properties':
+        case 'patternProperties':
+        case 'items':
+        case 'prefixItems':
+        case 'additionalItems':
+        case 'unevaluatedItems':
+        case 'allOf':
+        case '$ref':
+        case '$recursiveRef':
+        case '$dynamicRef':
+        case 'dependentSchemas':
+        case 'if':
+        case 'then':
+        case 'else':
+          continue;
+        case 'false': {
+          const name = tokens[tokens.length - 1] ?? '';
+          const owner = container && unit.instanceLocation.startsWith(`${container.instanceLocation}/`)
+            ? resolvePointer(root, container.keywordLocation.slice(0, container.keywordLocation.lastIndexOf('/')))
+            : undefined;
+          if (isSchemaRecord(owner)) {
+            const declaredProperty = isSchemaRecord(owner.properties)
+              && Object.prototype.hasOwnProperty.call(owner.properties, name);
+            const matchesPattern = isSchemaRecord(owner.patternProperties)
+              && Object.keys(owner.patternProperties).some((pattern) => {
+                try {
+                  return new RegExp(pattern, 'u').test(name);
+                } catch {
+                  return false;
+                }
+              });
+            if (declaredProperty || matchesPattern) continue;
+            const known = isSchemaRecord(owner.properties) ? Object.keys(owner.properties) : [];
+            issues.push({
+              path,
+              expected: known.length
+                ? `no such property; known properties: ${known.slice(0, 20).join(', ')}`
+                : 'no such property',
+              got,
+            });
+          } else {
+            issues.push({ path, expected: 'no value', got });
+          }
+          continue;
+        }
+        case 'required': {
+          const required = Array.isArray(schemaHere) ? schemaHere.filter((key): key is string => typeof key === 'string') : [];
+          const instance = valueAt(value, tokens);
+          for (const key of required) {
+            if (isSchemaRecord(instance) && Object.prototype.hasOwnProperty.call(instance, key)) continue;
+            const property = isSchemaRecord(parent) && isSchemaRecord(parent.properties) ? parent.properties[key] : undefined;
+            issues.push({ path: paramsPath([...tokens, key]), expected: typeText(property), got: 'missing' });
+          }
+          continue;
+        }
+        case 'anyOf':
+        case 'oneOf':
+        case 'not':
+          covered.push(unit.keywordLocation);
+          issues.push({ path, expected: unit.keyword === 'not' ? `not ${typeText(schemaHere)}` : typeText(parent), got });
+          continue;
+        case 'type':
+          issues.push({
+            path,
+            expected: Array.isArray(schemaHere) ? schemaHere.join(' | ') : String(schemaHere),
+            got,
+          });
+          continue;
+        case 'enum':
+        case 'const':
+          issues.push({ path, expected: typeText(parent), got });
+          continue;
+        case 'minimum':
+        case 'exclusiveMinimum':
+        case 'maximum':
+        case 'exclusiveMaximum':
+        case 'multipleOf':
+        case 'minLength':
+        case 'maxLength':
+        case 'minItems':
+        case 'maxItems':
+        case 'uniqueItems':
+        case 'pattern':
+        case 'format': {
+          const constraint = new SchemaDeclarationWriter({ namedType: () => undefined, resolve: () => undefined });
+          const text = isSchemaRecord(parent) ? compactType(constraint.type(parent)) : 'a value';
+          const subset = isSchemaRecord(parent) ? { type: parent.type, [unit.keyword]: schemaHere } : {};
+          const doc = Object.keys(subset).length ? constraintText(subset) : unit.error;
+          issues.push({ path, expected: doc ? `${text} (${doc})` : text, got });
+          continue;
+        }
+        default:
+          issues.push({ path, expected: unit.error, got });
+      }
+    }
+    const seen = new Set<string>();
+    return issues.filter((issue) => {
+      const key = `${issue.path}\u0000${issue.expected}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+
+  /** Issues reported by a zod, Standard Schema or AI SDK validator. */
+  private foreignIssues(error: Error, value: unknown): IFlexCatalogParamIssue[] {
+    const source = error as Error & { issues?: unknown; cause?: unknown };
+    const list = Array.isArray(source.issues)
+      ? source.issues
+      : isSchemaRecord(source.cause) && Array.isArray((source.cause as { issues?: unknown }).issues)
+        ? (source.cause as { issues: unknown[] }).issues
+        : Array.isArray(source.cause) ? source.cause : undefined;
+    if (!list || list.length === 0) return [{ path: 'params', expected: error.message || 'valid params', got: preview(value) }];
+    return list.map((issue) => {
+      const record = isSchemaRecord(issue) ? issue : {};
+      const tokens = (Array.isArray(record.path) ? record.path : []).map((segment) => {
+        const key = isSchemaRecord(segment) ? segment.key : segment;
+        return typeof key === 'number' ? key : String(key);
+      });
+      const expected = typeof record.expected === 'string'
+        ? record.expected
+        : typeof record.message === 'string' ? record.message : 'a valid value';
+      return { path: paramsPath(tokens), expected, got: preview(valueAt(value, tokens)) };
+    });
+  }
+}
+
+const constraintText = (subset: Record<string, unknown>): string => {
+  const parts: string[] = [];
+  const value = (key: string) => subset[key];
+  if (typeof value('minimum') === 'number') parts.push(`>= ${value('minimum')}`);
+  if (typeof value('exclusiveMinimum') === 'number') parts.push(`> ${value('exclusiveMinimum')}`);
+  if (typeof value('maximum') === 'number') parts.push(`<= ${value('maximum')}`);
+  if (typeof value('exclusiveMaximum') === 'number') parts.push(`< ${value('exclusiveMaximum')}`);
+  if (typeof value('multipleOf') === 'number') parts.push(`multiple of ${value('multipleOf')}`);
+  if (typeof value('minLength') === 'number') parts.push(`at least ${countOf(value('minLength') as number, 'character')}`);
+  if (typeof value('maxLength') === 'number') parts.push(`at most ${countOf(value('maxLength') as number, 'character')}`);
+  if (typeof value('minItems') === 'number') parts.push(`at least ${countOf(value('minItems') as number, 'item')}`);
+  if (typeof value('maxItems') === 'number') parts.push(`at most ${countOf(value('maxItems') as number, 'item')}`);
+  if (value('uniqueItems') === true) parts.push('unique items');
+  if (typeof value('pattern') === 'string') parts.push(`matching /${value('pattern')}/`);
+  if (typeof value('format') === 'string') parts.push(`format ${value('format')}`);
+  return parts.join(', ');
+};
+
+/**
+ * While a run has a catalog, its three tool names are reserved, and a method path must differ from
+ * every tool name.
+ */
+export const assertNoCatalogCollisions = (
+  catalog: FlexToolCatalog<unknown>,
+  tools: Readonly<Record<string, unknown>>,
+): void => {
+  const catalogToolNames = new Set<string>(Object.values(toolNames));
+  for (const name of catalogToolNames) {
+    if (Object.prototype.hasOwnProperty.call(tools, name)) {
+      throw new FlexHarnessValidationError(`Tool provider cannot define enabled built-in tool "${name}".`);
+    }
+  }
+  for (const path of catalog.methods) {
+    if (Object.prototype.hasOwnProperty.call(tools, path) || catalogToolNames.has(path) || path === 'invalid') {
+      throw new FlexHarnessValidationError(`Tool catalog method "${path}" has the name of a tool.`);
+    }
+  }
+};
+
+/**
+ * The AI SDK schema of a built-in catalog tool: the definition's JSON Schema, validated with it, so a
+ * malformed call goes back to the model like any other invalid tool input.
+ */
+export const catalogToolInputSchema = <TInput>(definition: IFlexCatalogToolDefinition): plugins.Schema<TInput> => {
+  const validator = new plugins.JsonSchemaValidator(structuredClone(definition.inputSchema) as never, '2020-12', false);
+  return plugins.jsonSchema<TInput>(definition.inputSchema, {
+    validate: (value) => {
+      const result = validator.validate(value);
+      if (result.valid) return { success: true, value: value as TInput };
+      const message = result.errors
+        .filter((unit) => !['properties', 'items', 'additionalProperties'].includes(unit.keyword))
+        .map((unit) => `${unit.instanceLocation.replace(/^#/, '') || '/'}: ${unit.error}`)
+        .join(' ');
+      return { success: false, error: new Error(message || 'Invalid input.') };
+    },
+  });
+};
+
+/** A root-level method declaration gets `declare`, as a namespace member does not need it. */
+const withDeclare = (text: string): string => {
+  const lines = text.split('\n');
+  const index = lines.findIndex((line) => /^(?:async\s+)?function\s/.test(line));
+  if (index !== -1) lines[index] = `declare ${lines[index]}`;
+  return lines.join('\n');
+};