@modelprofile.com/flexharness 10.13.0 → 10.15.0

package/ts/classes.toolcatalog.ts

@@ -1,8 +1,13 @@
 import * as plugins from './plugins.js';
 import { FlexHarnessValidationError } from './errors.js';
 import {
+  FLEX_CODE_MODE_TOOL_NAME,
   FLEX_TOOL_CATALOG_LIMITS as limits,
   FLEX_TOOL_CATALOG_TOOL_NAMES as toolNames,
+  type IFlexCatalogProposal,
+  type IFlexCatalogProposalContext,
+  type IFlexCodeModeLimits,
+  type TFlexCatalogCallDecision,
   type IFlexCatalogDescribeInput,
   type IFlexCatalogDescribeResult,
   type IFlexCatalogMethod,
@@ -25,6 +30,7 @@ import {
   type IRenderedDeclaration,
   type TJsonSchemaNode,
 } from './utils.schemadeclarations.js';
+import { normalizeToolCatalogOptions } from './utils.harnessoptions.js';
 import { validateUtf8String } from './utils.validation.js';
 
 type TValidationResult = { success: true; value: unknown } | { success: false; error: Error };
@@ -51,6 +57,7 @@ interface IMethodEntry {
   readonly summary: string;
   readonly description?: string;
   readonly tags: readonly string[];
+  readonly aliases: readonly string[];
   readonly examples: readonly string[];
   readonly input: ICatalogSchema;
   readonly inputScope: ISchemaScope;
@@ -58,10 +65,14 @@ interface IMethodEntry {
   readonly outputScope?: ISchemaScope;
   readonly declaration?: string;
   readonly run: IFlexCatalogMethod['run'];
+  readonly onCall?: NonNullable<IFlexCatalogMethod['onCall']>;
 }
 
 interface ITypeEntry {
+  /** The identifier the type is declared under. */
   readonly name: string;
+  /** The catalog's name for the type, where it is no identifier; `$ref`s name the type by it. */
+  readonly schemaName?: string;
   readonly description?: string;
   readonly declaration?: string;
   /** A catalog type's schema. */
@@ -76,6 +87,8 @@ interface IPreparedCall {
   readonly success: true;
   readonly method: string;
   readonly params: unknown;
+  /** The method's `onCall` decision for the call; `run` without the hook. */
+  decide(context: IFlexCatalogRunContext<any>): Promise<TFlexCatalogCallDecision>;
   run(context: IFlexCatalogRunContext<any>): ReturnType<IFlexCatalogMethod['run']>;
 }
 
@@ -98,17 +111,28 @@ const reservedWords = new Set([
 const controlPattern = /[\u0000-\u001f\u007f]/;
 const definitionRefPattern = /^#\/(\$defs|definitions)\/([^/]+)$/;
 const declaredTypesHeader = '// Declares types: ';
+const declaredTypesLine = /^\/\/ Declares types: (.*)$/gm;
 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',
+  'method', 'summary', 'description', 'tags', 'aliases', 'examples', 'inputSchema', 'outputSchema', 'declaration', 'run', 'onCall',
 ]);
+const catalogKeys = new Set(['methods', 'types', 'vocabulary', 'onProposals']);
 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',
+  'a', 'an', 'and', 'are', 'all', 'as', 'be', 'by', 'for', 'from', '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;
+const fieldWeights = { name: 3, aliases: 3, namespace: 1.5, summary: 2, tags: 2, description: 1 } as const;
+/**
+ * A method whose name's, or one alias's, every word the query names ranks this much higher: it is
+ * what was asked for.
+ */
+const nameCoverageFactor = 1.5;
+/**
+ * A top match leads clearly when it is the only one, or when the query names it and it scores this
+ * many times the runner-up.
+ */
+const clearMatchMargin = 1.25;
 type TSearchField = keyof typeof fieldWeights;
 const bm25K1 = 1.2;
 const bm25B = 0.75;
@@ -207,6 +231,13 @@ const searchTerms = (text: string): string[] => text
   .filter(Boolean)
   .map(stem);
 
+/** The search terms of a name or an alias, which must have some to be matched at all. */
+const namedTermsOf = (text: string, label: string): string[] => {
+  const terms = searchTerms(text);
+  if (terms.length === 0) throw new FlexHarnessValidationError(`${label} must contain a letter or digit.`);
+  return terms;
+};
+
 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);
@@ -292,6 +323,25 @@ const textOf = (
   return value;
 };
 
+/** Optional text: absent, or a string that is empty or blank, counts as not given. */
+const optionalTextOf = (
+  value: unknown,
+  label: string,
+  options: { maxCharacters?: number; maxBytes?: number; singleLine?: boolean },
+): string | undefined => value === undefined || (typeof value === 'string' && !value.trim())
+  ? undefined
+  : textOf(value, label, options);
+
+/**
+ * The identifier a catalog type is declared under: its name where that is one, else the name with
+ * each character an identifier cannot hold replaced by `_`, a leading digit or a reserved word
+ * escaped with `_`.
+ */
+const typeIdentifierOf = (name: string): string => {
+  const identifier = name.replace(/[^A-Za-z0-9_]/g, '_').replace(/^(?=\d)/, '_');
+  return reservedWords.has(identifier) ? `${identifier}_` : identifier;
+};
+
 const textListOf = (
   value: unknown,
   label: string,
@@ -305,6 +355,30 @@ const textListOf = (
   return value.map((entry, index) => textOf(entry, `${label}[${index}]`, options));
 };
 
+/** A vocabulary alias and the catalog words a query that says it searches for as well. */
+interface IVocabularyEntry {
+  readonly alias: readonly string[];
+  readonly words: readonly string[];
+}
+
+const vocabularyOf = (value: unknown): IVocabularyEntry[] => {
+  if (value === undefined) return [];
+  if (!isPlainObject(value)) {
+    throw new FlexHarnessValidationError('A tool catalog vocabulary must be a plain object of words and their aliases.');
+  }
+  const words = Object.entries(value);
+  if (words.length > limits.maxVocabularyWords) {
+    throw new FlexHarnessValidationError(`A tool catalog vocabulary must have at most ${limits.maxVocabularyWords} words.`);
+  }
+  const textOptions = { maxCharacters: limits.maxAliasCharacters, singleLine: true };
+  return words.flatMap(([word, aliases]) => {
+    const label = `Tool catalog vocabulary word "${word}"`;
+    const terms = namedTermsOf(textOf(word, label, textOptions), label);
+    return textListOf(aliases, `${label} aliases`, limits.maxAliases, textOptions)
+      .map((alias, index) => ({ alias: namedTermsOf(alias, `${label} aliases[${index}]`), words: terms }));
+  });
+};
+
 async function resolveCatalogSchema(schema: unknown, label: string): Promise<ICatalogSchema> {
   let json: unknown;
   let validate: TValidate | undefined;
@@ -346,10 +420,14 @@ async function resolveCatalogSchema(schema: unknown, label: string): Promise<ICa
 class CatalogSearchIndex {
   private readonly postings = new Map<string, Array<{ index: number; weight: number }>>();
   private readonly idf = new Map<string, number>();
+  /** The terms of each method's name and of each of its aliases. */
+  private readonly nameTerms: ReadonlyArray<ReadonlyArray<readonly string[]>>;
 
-  constructor(private readonly entries: readonly IMethodEntry[]) {
+  constructor(private readonly entries: readonly IMethodEntry[], private readonly vocabulary: readonly IVocabularyEntry[]) {
+    this.nameTerms = entries.map((entry) => [entry.name, ...entry.aliases].map((name) => [...new Set(searchTerms(name))]));
     const fieldTexts = (entry: IMethodEntry): Record<TSearchField, string[]> => ({
       name: searchTerms(entry.name),
+      aliases: entry.aliases.flatMap(searchTerms),
       namespace: searchTerms(entry.namespace),
       summary: searchTerms(entry.summary),
       tags: entry.tags.flatMap(searchTerms),
@@ -384,11 +462,21 @@ class CatalogSearchIndex {
     }
   }
 
-  /** 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))];
+  /**
+   * Methods ranked by BM25 over name, aliases, namespace, summary, tags and description, best first.
+   * The query searches for the catalog words of every vocabulary alias it says as well.
+   */
+  public search(
+    query: string,
+    accept: (entry: IMethodEntry) => boolean,
+  ): Array<{ entry: IMethodEntry; score: number; named: boolean }> {
+    const said = new Set(searchTerms(query));
+    const allTerms = [...said];
+    for (const { alias, words } of this.vocabulary) {
+      if (alias.every((term) => said.has(term))) allTerms.push(...words);
+    }
     const meaningful = allTerms.filter((term) => !stopWords.has(term));
-    const terms = meaningful.length > 0 ? meaningful : allTerms;
+    const terms = [...new Set(meaningful.length > 0 ? meaningful : allTerms)];
     const scores = new Map<number, number>();
     for (const term of terms) {
       const idf = this.idf.get(term);
@@ -398,20 +486,23 @@ class CatalogSearchIndex {
       }
     }
     const exact = query.trim().toLowerCase();
+    const queryTerms = new Set(allTerms);
     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 };
+        const bonus = [entry.path, entry.name, ...entry.aliases].some((name) => name.toLowerCase() === exact) ? 1000 : 0;
+        const named = this.nameTerms[index].some((name) => name.every((term) => queryTerms.has(term)));
+        return { entry, score: (named ? score * nameCoverageFactor : score) + bonus, named };
       })
       .filter(({ entry }) => accept(entry))
-      .sort((left, right) => right.score - left.score || compareCodePoints(left.entry.path, right.entry.path))
-      .map(({ entry }) => entry);
+      .sort((left, right) => right.score - left.score || compareCodePoints(left.entry.path, right.entry.path));
   }
 }
 
 class FlexToolCatalogCore {
   public readonly renderedMethods = new Map<string, IRenderedDeclaration>();
+  /** The named types each rendered method's parameters and result use. */
+  public readonly methodTypeSets = new Map<string, { input: string[]; output: string[] }>();
   public readonly renderedTypes = new Map<string, IRenderedDeclaration>();
   public readonly validators = new Map<string, plugins.JsonSchemaValidator>();
   public readonly selfContainedInputs = new Map<string, TJsonSchemaNode>();
@@ -421,27 +512,63 @@ class FlexToolCatalogCore {
     public readonly mode: TDeclarationMode,
     public readonly methods: ReadonlyMap<string, IMethodEntry>,
     public readonly types: ReadonlyMap<string, ITypeEntry>,
+    /** The identifier of each catalog type, by the name its `$ref`s use. */
+    public readonly typeIdentifiers: ReadonlyMap<string, string>,
+    vocabulary: readonly IVocabularyEntry[],
+    public readonly onProposals: IFlexToolCatalog['onProposals'] | undefined,
   ) {
-    this.index = new CatalogSearchIndex([...methods.values()]);
+    this.index = new CatalogSearchIndex([...methods.values()], vocabulary);
   }
 
   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');
+    const unsupported = Object.keys(catalog).find((key) => !catalogKeys.has(key));
     if (unsupported) throw new FlexHarnessValidationError(`A tool catalog does not support "${unsupported}".`);
+    const onProposals = catalog.onProposals;
+    if (onProposals !== undefined && typeof onProposals !== 'function') {
+      throw new FlexHarnessValidationError('A tool catalog onProposals must be a function.');
+    }
+    const vocabulary = vocabularyOf(catalog.vocabulary);
     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>();
+    const namedTypes = 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)) {
+      if (namedTypes.has(entry.name)) {
         throw new FlexHarnessValidationError(`Tool catalog type "${entry.name}" is defined twice.`);
       }
-      catalogTypes.set(entry.name, entry);
+      namedTypes.set(entry.name, entry);
+    }
+    // A name that is an identifier keeps it; the others are mapped in code-point order, so a
+    // catalog always declares the same identifiers.
+    const typeIdentifiers = new Map<string, string>();
+    const taken = new Set<string>();
+    const names = [...namedTypes.keys()].sort(compareCodePoints);
+    for (const name of names) {
+      if (typeIdentifierOf(name) !== name) continue;
+      typeIdentifiers.set(name, name);
+      taken.add(name);
+    }
+    for (const name of names) {
+      if (typeIdentifiers.has(name)) continue;
+      const base = typeIdentifierOf(name);
+      let identifier = base;
+      for (let suffix = 2; taken.has(identifier); suffix++) identifier = `${base}_${suffix}`;
+      typeIdentifiers.set(name, identifier);
+      taken.add(identifier);
+    }
+    /** Catalog types by the name their `$ref`s use. */
+    const catalogTypes = new Map<string, ITypeEntry>();
+    for (const [name, entry] of namedTypes) {
+      const identifier = typeIdentifiers.get(name)!;
+      if (entry.declaration !== undefined && !new RegExp(`\\b(?:interface|type|enum|class)\\s+${identifier}\\b`).test(entry.declaration)) {
+        throw new FlexHarnessValidationError(`Tool catalog type "${name}" declaration must declare "${identifier}".`);
+      }
+      catalogTypes.set(name, { ...entry, name: identifier, ...(identifier === name ? {} : { schemaName: name }) });
     }
     const methodInputs: Array<Omit<IMethodEntry, 'inputScope' | 'outputScope'>> = [];
     for (const [index, method] of (catalog.methods as unknown[]).entries()) {
@@ -462,7 +589,7 @@ class FlexToolCatalogCore {
       }
     }
 
-    const registry = new Map<string, ITypeEntry>(catalogTypes);
+    const registry = new Map<string, ITypeEntry>([...catalogTypes.values()].map((type) => [type.name, type]));
     const canonicalDefinitions = new Map<string, string>();
     const scopeOf = (root: TJsonSchemaNode, label: string, requireSchemas: boolean): ISchemaScope => {
       const scope: ISchemaScope = { root, localNames: new Map() };
@@ -493,7 +620,10 @@ class FlexToolCatalogCore {
     };
     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) });
+      registry.set(type.name, {
+        ...type,
+        scope: scopeOf(type.schema.json, `Tool catalog type "${type.schemaName ?? type.name}"`, true),
+      });
     }
     const methods = new Map<string, IMethodEntry>();
     for (const method of methodInputs) {
@@ -506,7 +636,16 @@ class FlexToolCatalogCore {
       });
     }
     const types = new Map([...registry.entries()].sort(([left], [right]) => compareCodePoints(left, right)));
-    return new FlexToolCatalogCore(mode, methods, types);
+    return new FlexToolCatalogCore(
+      mode,
+      methods,
+      types,
+      typeIdentifiers,
+      vocabulary,
+      onProposals === undefined
+        ? undefined
+        : (proposals, context) => (onProposals as NonNullable<IFlexToolCatalog['onProposals']>).call(catalog, proposals, context),
+    );
   }
 
   private static async normalizeType(value: unknown, label: string): Promise<ITypeEntry> {
@@ -514,21 +653,16 @@ class FlexToolCatalogCore {
     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 (/\s/.test(name)) throw new FlexHarnessValidationError(`${label} name must not contain whitespace.`);
     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 description = optionalTextOf(value.description, `Tool catalog type "${name}" description`, {
+      maxBytes: limits.maxDescriptionBytes,
+    })?.trim();
     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`);
@@ -573,12 +707,16 @@ class FlexToolCatalogCore {
     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 description = optionalTextOf(value.description, `${methodLabel} description`, {
+      maxBytes: limits.maxDescriptionBytes,
+    })?.trim();
     const tags = textListOf(value.tags, `${methodLabel} tags`, limits.maxTags, {
       maxCharacters: limits.maxTagCharacters, singleLine: true,
     });
+    const aliases = textListOf(value.aliases, `${methodLabel} aliases`, limits.maxAliases, {
+      maxCharacters: limits.maxAliasCharacters, singleLine: true,
+    });
+    aliases.forEach((alias, index) => namedTermsOf(alias, `${methodLabel} aliases[${index}]`));
     const examples = textListOf(value.examples, `${methodLabel} examples`, limits.maxExamples, {
       maxBytes: limits.maxExampleBytes,
     });
@@ -590,6 +728,9 @@ class FlexToolCatalogCore {
       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.onCall !== undefined && typeof value.onCall !== 'function') {
+      throw new FlexHarnessValidationError(`${methodLabel} onCall 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;
@@ -604,6 +745,7 @@ class FlexToolCatalogCore {
       ? undefined
       : await resolveCatalogSchema(value.outputSchema, `${methodLabel} outputSchema`);
     const run = value.run as IFlexCatalogMethod['run'];
+    const onCall = value.onCall as IFlexCatalogMethod['onCall'];
     return {
       path,
       namespace: segments.slice(0, -1).join('.'),
@@ -611,11 +753,15 @@ class FlexToolCatalogCore {
       summary,
       ...(description ? { description } : {}),
       tags: Object.freeze(tags),
+      aliases: Object.freeze(aliases),
       examples: Object.freeze(examples),
       input,
       ...(output ? { output } : {}),
       ...(declaration === undefined ? {} : { declaration }),
       run: (params, context) => run.call(value, params, context),
+      ...(onCall === undefined ? {} : {
+        onCall: (params: unknown, context: IFlexCatalogRunContext) => onCall.call(value, params, context),
+      }),
     };
   }
 
@@ -660,7 +806,7 @@ class FlexToolCatalogCore {
         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;
+        return this.typeIdentifiers.get(key);
       },
       resolve: (ref: string): TJsonSchemaNode | undefined => {
         const target = resolvePointer(scope.root, ref);
@@ -674,12 +820,17 @@ class FlexToolCatalogCore {
     if (cached) return cached;
     const type = this.types.get(name)!;
     let rendered: IRenderedDeclaration;
+    const schemaNote = type.schemaName === undefined ? undefined : `Named "${type.schemaName}" in the schema.`;
     if (type.declaration !== undefined) {
-      rendered = { text: type.declaration.trim(), types: this.scanTypes(type.declaration, name) };
+      rendered = {
+        text: `${schemaNote === undefined ? '' : docBlock(schemaNote, '')}${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);
+      const description = [type.description, schemaNote].filter((part) => part !== undefined).join('\n\n');
+      const text = writer.namedDeclaration(name, schema, description || undefined);
       rendered = { text, types: writer.usedTypes.filter((used) => used !== name) };
     }
     this.renderedTypes.set(name, rendered);
@@ -692,6 +843,9 @@ class FlexToolCatalogCore {
     let rendered: IRenderedDeclaration;
     if (entry.declaration !== undefined) {
       rendered = { text: entry.declaration.trim(), types: this.scanTypes(entry.declaration) };
+      // A host's declaration text does not tell parameters from the result: every type it names is
+      // declared with it.
+      this.methodTypeSets.set(entry.path, { input: rendered.types, output: [] });
     } else {
       const inputWriter = new SchemaDeclarationWriter(this.scopeContext(entry.inputScope));
       const members = inputWriter.objectMembers(entry.input.json);
@@ -716,6 +870,10 @@ class FlexToolCatalogCore {
         text: `${docBlock(lines.join('\n'), '')}${signature}`,
         types: [...new Set([...inputWriter.usedTypes, ...(outputWriter?.usedTypes ?? [])])].sort(compareCodePoints),
       };
+      this.methodTypeSets.set(entry.path, {
+        input: [...new Set(inputWriter.usedTypes)].sort(compareCodePoints),
+        output: [...new Set(outputWriter?.usedTypes ?? [])].sort(compareCodePoints),
+      });
     }
     this.renderedMethods.set(entry.path, rendered);
     return rendered;
@@ -729,6 +887,28 @@ class FlexToolCatalogCore {
     return [...found].sort(compareCodePoints);
   }
 
+  /** The named types a method's parameters and result use. */
+  public methodTypes(entry: IMethodEntry): { input: string[]; output: string[] } {
+    this.renderMethod(entry);
+    return this.methodTypeSets.get(entry.path)!;
+  }
+
+  /** `names` and the types they use up to `depth` levels, `names` being the first, sorted. */
+  public typeLevels(names: Iterable<string>, depth: number, stop: ReadonlySet<string> = new Set()): string[] {
+    const result = new Set<string>();
+    let level = [...names];
+    for (let current = 0; current < depth && level.length > 0; current++) {
+      const next: string[] = [];
+      for (const name of level) {
+        if (result.has(name) || stop.has(name) || !this.types.has(name)) continue;
+        result.add(name);
+        next.push(...this.renderType(name).types);
+      }
+      level = next;
+    }
+    return [...result].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>();
@@ -755,7 +935,8 @@ class FlexToolCatalogCore {
         const ref = queue.pop()!;
         const match = definitionRefPattern.exec(ref);
         if (!match || resolvePointer(root, ref) !== undefined) continue;
-        const type = this.types.get(decodePointerToken(match[2]));
+        const identifier = this.typeIdentifiers.get(decodePointerToken(match[2]));
+        const type = identifier === undefined ? undefined : this.types.get(identifier);
         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);
@@ -791,6 +972,12 @@ export class FlexToolCatalog<TScope = unknown> {
   private constructor(
     private readonly core: FlexToolCatalogCore,
     private readonly admitted: ReadonlySet<string> | undefined,
+    /** The limits of `run_code`; absent while code mode is off. */
+    public readonly codeMode: Readonly<IFlexCodeModeLimits> | undefined,
+    /** Levels of a result's named types a TypeScript declaration declares. */
+    private readonly outputTypeDepth: number,
+    /** `search` follows a clear top match with its declaration. */
+    private readonly describeTopMatch: boolean,
   ) {}
 
   /**
@@ -801,10 +988,8 @@ export class FlexToolCatalog<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".');
-    }
+    const normalized = normalizeToolCatalogOptions(options);
+    const mode = normalized.declarations;
     if (typeof catalog !== 'object' || catalog === null) {
       throw new FlexHarnessValidationError('A tool catalog must be a plain object.');
     }
@@ -818,7 +1003,13 @@ export class FlexToolCatalog<TScope = unknown> {
       core = FlexToolCatalogCore.build(catalog, mode);
       byMode.set(mode, core);
     }
-    return new FlexToolCatalog<TScope>(await core, undefined);
+    return new FlexToolCatalog<TScope>(
+      await core,
+      undefined,
+      normalized.codeMode,
+      normalized.outputTypeDepth,
+      normalized.describeTopMatch,
+    );
   }
 
   /** Every method path this catalog offers, sorted. */
@@ -837,6 +1028,9 @@ export class FlexToolCatalog<TScope = unknown> {
     return new FlexToolCatalog<TScope>(
       this.core,
       new Set([...this.core.methods.keys()].filter((path) => allowed.has(path) && this.isAdmitted(path))),
+      this.codeMode,
+      this.outputTypeDepth,
+      this.describeTopMatch,
     );
   }
 
@@ -844,7 +1038,10 @@ export class FlexToolCatalog<TScope = unknown> {
     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. */
+  /**
+   * The built-in tools as the model sees them: the three catalog tools, and `run_code` in code
+   * mode. Their text depends only on the catalog and its options.
+   */
   public toolDefinitions(): Record<string, IFlexCatalogToolDefinition> {
     const typescript = this.core.mode === 'typescript';
     const methodPath = { type: 'string', maxLength: limits.maxMethodPathCharacters } as const;
@@ -855,6 +1052,7 @@ export class FlexToolCatalog<TScope = unknown> {
           '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.describeTopMatch ? ['When one match clearly leads, its declaration follows the results.'] : []),
           this.topLevelLine(),
         ].join(' '),
         inputSchema: {
@@ -899,11 +1097,50 @@ export class FlexToolCatalog<TScope = unknown> {
           additionalProperties: false,
         },
       },
+      ...(this.codeMode ? { [FLEX_CODE_MODE_TOOL_NAME]: this.codeToolDefinition(this.codeMode) } : {}),
     };
   }
 
-  /** Search results or a namespace listing as text. */
-  public search(input: IFlexCatalogSearchInput = {}): string {
+  private codeToolDefinition(codeMode: Readonly<IFlexCodeModeLimits>): IFlexCatalogToolDefinition {
+    return {
+      description: [
+        'Run a short TypeScript or JavaScript program against the catalog, for work that takes several calls:',
+        'loops, filters, joins. Call a method as `await api.<dotted path>(params)`, for example',
+        '`await api.banking.listMovements({ accountId })`, with the declarations describe_tools returns; a refused',
+        'call throws an `ApiError` whose `details` say why. `return` a JSON value: it and the `console.log` output',
+        'come back, nothing else does. No network, files, timers or imports;',
+        `at most ${codeMode.maxCalls} calls and ${Math.round(codeMode.wallMs / 1000)} seconds.`,
+      ].join(' '),
+      inputSchema: {
+        type: 'object',
+        properties: { code: { type: 'string', minLength: 1, maxLength: codeMode.maxSourceBytes } },
+        required: ['code'],
+        additionalProperties: false,
+      },
+    };
+  }
+
+  /** Hands proposed calls to the catalog's `onProposals` and returns what the model sees for them. */
+  public async propose(
+    proposals: readonly IFlexCatalogProposal[],
+    context: IFlexCatalogProposalContext<TScope>,
+  ): Promise<unknown> {
+    if (!this.core.onProposals) {
+      throw new FlexHarnessValidationError(
+        `Tool catalog method "${proposals[0]?.method}" proposed a call, but the catalog has no onProposals.`,
+      );
+    }
+    return await this.core.onProposals(proposals, context as IFlexCatalogProposalContext);
+  }
+
+  /**
+   * Search results or a namespace listing as text. A clear top match of a query's first page is
+   * followed by its declaration, as `describe` gives it with `options`.
+   */
+  public search(
+    input: IFlexCatalogSearchInput = {},
+    options: { declaredTypes?: Iterable<string>; maxBytes?: number } = {},
+  ): string {
     const limit = input.limit ?? limits.defaultSearchResults;
     const offset = input.offset ?? 0;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > limits.maxSearchResults) {
@@ -929,7 +1166,16 @@ export class FlexToolCatalog<TScope = unknown> {
       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 results = this.page(matches.map(({ entry }) => `${entry.path} - ${entry.summary}`), offset, limit, 'matches');
+      const [top, next] = matches;
+      const clear = offset === 0 && (!next || (top.named && top.score >= clearMatchMargin * next.score));
+      if (!this.describeTopMatch || !clear) return results;
+      // The declaration follows only while the whole answer fits what describe_tools may answer;
+      // an answer over the output limit would lose the results too.
+      const maxBytes = Math.min(options.maxBytes ?? limits.maxDescribeBytes, limits.maxDescribeBytes);
+      const declaration = this.describe({ methods: [top.entry.path] }, { ...options, maxBytes }).output;
+      const answer = `${results}\n\n${typeof declaration === 'string' ? declaration : JSON.stringify(declaration)}`;
+      return Buffer.byteLength(JSON.stringify(answer), 'utf8') <= maxBytes ? answer : results;
     }
     const node = tree.get(namespace)!;
     const lines = [...node.children.entries()].map(([child, count]) => `${child}.* (${count} method${count === 1 ? '' : 's'})`);
@@ -957,8 +1203,11 @@ export class FlexToolCatalog<TScope = unknown> {
     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);
+    // A type is asked for by its identifier or by the name its schema gives it.
+    const identifierOf = (name: string): string | undefined =>
+      this.core.types.has(name) ? name : this.core.typeIdentifiers.get(name);
+    const knownTypes = [...new Set(requestedTypes.flatMap((name) => identifierOf(name) ?? []))].sort(compareCodePoints);
+    const unknownTypes = requestedTypes.filter((name) => identifierOf(name) === undefined).sort(compareCodePoints);
     const notes = [
       ...unknownMethods.map((path) => {
         const suggestions = closeMatches(path, this.methods);
@@ -977,18 +1226,18 @@ export class FlexToolCatalog<TScope = unknown> {
       : this.describeTypescript(entries, knownTypes, notes, new Set(options.declaredTypes ?? []), maxBytes);
   }
 
-  /** The named types `describe_tools` results in `messages` declared. */
+  /** The named types the `describe_tools` and `search_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;
+        if (part.type !== 'tool-result' || (part.toolName !== toolNames.describe && part.toolName !== toolNames.search)) 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);
+        if (output.type !== 'text' || typeof output.value !== 'string') continue;
+        for (const [, header] of output.value.matchAll(declaredTypesLine)) {
+          for (const name of header.split(', ')) if (this.core.types.has(name)) declared.add(name);
+        }
       }
     }
     return declared;
@@ -1041,6 +1290,19 @@ export class FlexToolCatalog<TScope = unknown> {
       success: true,
       method: path,
       params: validated,
+      decide: async (context) => {
+        const decision = entry.onCall ? await entry.onCall(validated, context) : 'run';
+        if (decision === 'run' || decision === 'propose') return decision;
+        if (
+          isSchemaRecord(decision)
+          && Object.keys(decision).length === 1
+          && typeof decision.deny === 'string'
+          && decision.deny.trim()
+        ) {
+          return { deny: decision.deny.slice(0, 2000) };
+        }
+        throw new FlexHarnessValidationError(`Tool catalog method "${path}" onCall returned an invalid decision.`);
+      },
       run: (context) => entry.run(validated, context),
     };
   }
@@ -1118,10 +1380,24 @@ export class FlexToolCatalog<TScope = unknown> {
     const included: IMethodEntry[] = [];
     const omitted: string[] = [];
     const alreadyDeclared = new Set([...declared].filter((name) => !requestedTypes.includes(name)));
-    let types = this.core.typeClosure(requestedTypes, alreadyDeclared);
+    // Parameters' types are declared in full; a result's only `outputTypeDepth` levels deep.
+    const typesFor = (methods: IMethodEntry[]): string[] => {
+      const inputs = [...requestedTypes, ...methods.flatMap((entry) => this.core.methodTypes(entry).input)];
+      const outputs = methods.flatMap((entry) => this.core.methodTypes(entry).output);
+      return [...new Set([
+        ...this.core.typeClosure(inputs, alreadyDeclared),
+        ...this.core.typeLevels(outputs, this.outputTypeDepth, alreadyDeclared),
+      ])].sort(compareCodePoints);
+    };
+    let types = typesFor([]);
     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 shown = new Set(typeNames);
+      const named = new Set([
+        ...methods.flatMap((entry) => this.core.renderMethod(entry).types),
+        ...typeNames.flatMap((name) => this.core.renderType(name).types),
+      ]);
+      const earlier = [...named].filter((name) => declared.has(name) && !shown.has(name)).sort(compareCodePoints);
+      const undeclared = [...named].filter((name) => !declared.has(name) && !shown.has(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);
@@ -1134,6 +1410,7 @@ export class FlexToolCatalog<TScope = unknown> {
       }
       const trailing = [
         ...(earlier.length ? [`Declared earlier: ${earlier.join(', ')}; describe_tools({"types":[...]}) declares them again.`] : []),
+        ...(undeclared.length ? [`Not declared yet: ${undeclared.join(', ')}; describe_tools({"types":[...]}) declares them.`] : []),
         ...notes,
         ...(skipped.length ? [`Not included to stay within the size limit: ${skipped.join(', ')}; describe them in another call.`] : []),
       ];
@@ -1142,10 +1419,7 @@ export class FlexToolCatalog<TScope = unknown> {
     };
     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 candidateTypes = typesFor(candidate);
       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));
@@ -1170,7 +1444,7 @@ export class FlexToolCatalog<TScope = unknown> {
       const type = this.core.types.get(name)!;
       const schema = type.definition ?? type.schema?.json;
       return [{
-        name,
+        name: type.schemaName ?? name,
         ...(type.description ? { description: type.description } : {}),
         ...(schema === undefined ? { declaration: type.declaration! } : { schema: withoutDraft(schema) }),
       }];
@@ -1213,7 +1487,8 @@ export class FlexToolCatalog<TScope = unknown> {
       namedType: (ref) => {
         const match = definitionRefPattern.exec(ref);
         const key = match ? decodePointerToken(match[2]) : undefined;
-        return key && typeNamePattern.test(key) ? key : undefined;
+        if (key === undefined) return undefined;
+        return this.core.typeIdentifiers.get(key) ?? (typeNamePattern.test(key) ? key : undefined);
       },
       resolve: (ref) => {
         const target = resolvePointer(root, ref);
@@ -1383,14 +1658,17 @@ const constraintText = (subset: Record<string, unknown>): string => {
 };
 
 /**
- * While a run has a catalog, its three tool names are reserved, and a method path must differ from
- * every tool name.
+ * While a run has a catalog, its tool names are reserved (`run_code` in code mode too), 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));
+  const catalogToolNames = new Set<string>([
+    ...Object.values(toolNames),
+    ...(catalog.codeMode ? [FLEX_CODE_MODE_TOOL_NAME] : []),
+  ]);
   for (const name of catalogToolNames) {
     if (Object.prototype.hasOwnProperty.call(tools, name)) {
       throw new FlexHarnessValidationError(`Tool provider cannot define enabled built-in tool "${name}".`);