@modelprofile.com/flexharness 10.16.0 → 10.17.1

package/ts/classes.toolcatalog.ts

@@ -907,10 +907,13 @@ class FlexToolCatalogCore {
     if (cached) return cached;
     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: [] });
+      // A host's declaration names its parameters' types in its parameter list and its result's after
+      // it; text that is no plain function declaration declares every type it names with it.
+      const parts = signatureParts(entry.declaration, entry.name);
+      const input = this.scanTypes(parts?.params ?? entry.declaration);
+      const output = parts ? this.scanTypes(parts.result) : [];
+      rendered = { text: entry.declaration.trim(), types: [...new Set([...input, ...output])].sort(compareCodePoints) };
+      this.methodTypeSets.set(entry.path, { input, output });
     } else {
       const inputWriter = new SchemaDeclarationWriter(this.scopeContext(entry.inputScope));
       const members = inputWriter.objectMembers(entry.input.json);
@@ -944,9 +947,10 @@ class FlexToolCatalogCore {
     return rendered;
   }
 
+  /** The catalog types a declaration's code names; its comments and string literals name none. */
   private scanTypes(text: string, self?: string): string[] {
     const found = new Set<string>();
-    for (const match of text.matchAll(identifierScanPattern)) {
+    for (const match of codeOf(text).matchAll(identifierScanPattern)) {
       if (match[0] !== self && this.types.has(match[0])) found.add(match[0]);
     }
     return [...found].sort(compareCodePoints);
@@ -1045,6 +1049,16 @@ export class FlexToolCatalog<TScope = unknown> {
     private readonly describeTopMatch: boolean,
   ) {}
 
+  /**
+   * The identifier a name from elsewhere, such as a file or an API's method, is declared under as a
+   * path segment or a type: every other character `_`, `_` before a leading digit and after a
+   * reserved word (`export-jobs` becomes `export_jobs`, `delete` becomes `delete_`). The catalog
+   * maps type names that are no identifiers the same way.
+   */
+  public static identifierOf(name: string): string {
+    return typeIdentifierOf(name);
+  }
+
   /**
    * 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.
@@ -1290,7 +1304,7 @@ export class FlexToolCatalog<TScope = unknown> {
     const unknownTypes = requestedTypes.filter((name) => identifierOf(name) === undefined).sort(compareCodePoints);
     const notes = [
       ...unknownMethods.map((path) => {
-        const suggestions = closeMatches(path, this.methods);
+        const suggestions = closeMatches(path, this.listedMethods());
         return `Unknown method ${path}.${suggestions.length ? ` Did you mean ${suggestions.join(', ')}?` : ' Find methods with search_tools.'}`;
       }),
       ...unknownTypes.map((name) => {
@@ -1336,7 +1350,7 @@ export class FlexToolCatalog<TScope = unknown> {
         error: {
           error: 'unknown_method',
           method: path,
-          didYouMean: isNamespace ? [] : closeMatches(path, this.methods),
+          didYouMean: isNamespace ? [] : closeMatches(path, this.listedMethods()),
           hint: isNamespace
             ? `${path} is a namespace; list it with search_tools({"namespace":"${path}"}).`
             : 'Find methods with search_tools.',
@@ -1393,6 +1407,11 @@ export class FlexToolCatalog<TScope = unknown> {
     return { method: input.method, params: input.params === undefined ? {} : input.params };
   }
 
+  /** The method paths search and suggestions may name: built-ins such as `results.get` stay out. */
+  private listedMethods(): string[] {
+    return this.methods.filter((path) => !this.core.unlisted.has(path));
+  }
+
   private isAdmitted(path: string): boolean {
     return this.admitted === undefined || this.admitted.has(path);
   }
@@ -1780,6 +1799,70 @@ export const catalogToolInputSchema = <TInput>(definition: IFlexCatalogToolDefin
   });
 };
 
+/** Declaration text with its comments and the contents of its string literals blanked. */
+const codeOf = (text: string): string => {
+  let code = '';
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index];
+    if (char === '/' && text[index + 1] === '/') {
+      const end = text.indexOf('\n', index);
+      index = (end === -1 ? text.length : end) - 1;
+      code += ' ';
+    } else if (char === '/' && text[index + 1] === '*') {
+      const end = text.indexOf('*/', index + 2);
+      index = end === -1 ? text.length : end + 1;
+      code += ' ';
+    } else if (char === '"' || char === "'" || char === '`') {
+      let end = index + 1;
+      while (end < text.length && text[end] !== char) end += text[end] === '\\' ? 2 : 1;
+      code += `${char}${char}`;
+      index = end;
+    } else {
+      code += char;
+    }
+  }
+  return code;
+};
+
+/** The index of the bracket that closes the one at `open`, or -1. */
+const closingBracket = (code: string, open: number): number => {
+  const pairs: Record<string, string> = { '(': ')', '<': '>', '{': '}', '[': ']' };
+  const stack: string[] = [];
+  for (let index = open; index < code.length; index++) {
+    const char = code[index];
+    if (char === '=' && code[index + 1] === '>') {
+      index++;
+    } else if (pairs[char] !== undefined && (char !== '<' || stack.length === 0 || stack[stack.length - 1] === '>')) {
+      stack.push(pairs[char]);
+    } else if (char === stack[stack.length - 1]) {
+      stack.pop();
+      if (stack.length === 0) return index;
+    }
+  }
+  return -1;
+};
+
+/**
+ * A host method declaration's parameter list and the result after it, as code without comments, or
+ * undefined where the text is no plain `function name(…): …` declaration.
+ */
+const signatureParts = (declaration: string, name: string): { params: string; result: string } | undefined => {
+  const code = codeOf(declaration);
+  const start = new RegExp(`\\bfunction\\s+${name}\\s*`).exec(code);
+  if (!start) return undefined;
+  let open = start.index + start[0].length;
+  if (code[open] === '<') {
+    const typeParameters = closingBracket(code, open);
+    if (typeParameters === -1) return undefined;
+    open = typeParameters + 1;
+    while (/\s/.test(code[open] ?? '')) open++;
+  }
+  if (code[open] !== '(') return undefined;
+  const close = closingBracket(code, open);
+  if (close === -1) return undefined;
+  return { params: code.slice(open + 1, close), result: code.slice(close + 1) };
+};
+
 /** 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');

package/ts/interfaces.ts

@@ -688,6 +688,8 @@ export const FLEX_RESULT_METHOD = 'results.get';
 export const FLEX_RESULT_LIMITS = Object.freeze({
   /** The most of one output a result stores; beyond it the stored value is truncated. */
   maxStoredBytes: 8 * 1024 * 1024,
+  /** The results a session keeps; a new one beyond them deletes the oldest. */
+  maxResultsPerSession: 32,
   /** The size of the summary the model gets in place of the output. */
   summaryBytes: 2 * 1024,
 });
@@ -720,7 +722,7 @@ export const FLEX_TOOL_CATALOG_LIMITS = Object.freeze({
   maxIdentifierCharacters: 128,
   maxSummaryCharacters: 120,
   maxDescriptionBytes: 16 * 1024,
-  maxDeclarationBytes: 16 * 1024,
+  maxDeclarationBytes: 64 * 1024,
   maxTags: 16,
   maxTagCharacters: 48,
   maxAliases: 16,
@@ -1432,11 +1434,17 @@ export interface IFlexToolJobStoreProvider {
 
 /**
  * Tool outputs over the output budget, stored whole for the session that produced them. A result
- * is written once under its handle and read by `results.get`.
+ * is written once under its handle and read by `results.get`; FlexHarness keeps a session's latest
+ * `FLEX_RESULT_LIMITS.maxResultsPerSession` results and deletes older ones. A FlexHarness writes a
+ * session's results one operation at a time, so a store need not order concurrent writes of one
+ * session.
  */
 export interface IFlexResultStore {
   save(storageKey: string, sessionId: string, handle: string, value: TJsonValue): Promise<void>;
   load(storageKey: string, sessionId: string, handle: string): Promise<TJsonValue | undefined>;
+  /** The handles of the session's results, oldest first. */
+  list(storageKey: string, sessionId: string): Promise<string[]>;
+  delete(storageKey: string, sessionId: string, handle: string): Promise<void>;
   deleteSession(storageKey: string, sessionId: string): Promise<void>;
 }
 

package/ts/utils.storerules.ts

@@ -175,3 +175,18 @@ export function assertSameArchiveEvents(
     throw new Error(`Archive "${next.archiveId}" already exists with different events.`);
   }
 }
+
+/** The index of a session's stored results: their handles, oldest first. */
+export interface IFlexResultIndex {
+  handles: string[];
+}
+
+export function validateResultIndex(value: unknown): IFlexResultIndex {
+  assertRecord(value, '$resultIndex');
+  assertExactKeys(value, ['handles'], '$resultIndex');
+  const handles = value.handles;
+  if (!Array.isArray(handles) || !handles.every((handle) => typeof handle === 'string')) {
+    throw new FlexHarnessStoreFormatError('$resultIndex.handles must list handles.');
+  }
+  return { handles: [...handles] };
+}

package/ts_stores_nosqldb/classes.nosqldbstores.ts

@@ -47,6 +47,7 @@ import {
   validateExpectedRevision,
   validateIdentifier,
   validateProjectManagementWriteContext,
+  validateResultIndex,
   validateSnapshotSave,
 } from '../ts/utils.storerules.js';
 import { FlexRecordStore, type IFlexRecordWrite } from './classes.recordstore.js';
@@ -431,6 +432,11 @@ export interface INoSqlFlexHarnessStoresOptions {
   operationTimeoutMs?: number;
 }
 
+/**
+ * One record per result and an index record of the session's handles, oldest first, changed with
+ * compare-and-swap. A result whose handle the index lost to a failed write stays until its session
+ * is deleted.
+ */
 class NoSqlResultStore implements IFlexResultStore {
   constructor(private readonly records: FlexRecordStore) {}
 
@@ -446,6 +452,7 @@ class NoSqlResultStore implements IFlexResultStore {
       },
       contention: conflict,
     });
+    await this.changeIndex(storageKey, sessionId, (handles) => [...handles, handle]);
   }
 
   public load(storageKey: string, sessionId: string, handle: string): Promise<TJsonValue | undefined> {
@@ -453,9 +460,31 @@ class NoSqlResultStore implements IFlexResultStore {
     return this.records.read({ domain: 'result', storageKey, sessionId, entryId: handle }, validateResult);
   }
 
+  public async list(storageKey: string, sessionId: string): Promise<string[]> {
+    const index = await this.records.read({ domain: 'result', storageKey, sessionId }, validateResultIndex);
+    return index?.handles ?? [];
+  }
+
+  public async delete(storageKey: string, sessionId: string, handle: string): Promise<void> {
+    validateIdentifier(handle, 'handle');
+    await this.changeIndex(storageKey, sessionId, (handles) => handles.filter((entry) => entry !== handle));
+    await this.records.delete({ domain: 'result', storageKey, sessionId, entryId: handle });
+  }
+
   public deleteSession(storageKey: string, sessionId: string): Promise<void> {
     return this.records.deleteOwner(storageKey, sessionId, ['result']);
   }
+
+  /** The session's index record: the result records' handles, without an entry of its own. */
+  private changeIndex(storageKey: string, sessionId: string, change: (handles: string[]) => string[]): Promise<void> {
+    const contention = () => new Error(`The result index of session "${sessionId}" is contended by concurrent writers.`);
+    return this.records.mutate({ domain: 'result', storageKey, sessionId }, {
+      validate: validateResultIndex,
+      // The write token fences concurrent writers; the index keeps no revision of its own.
+      decide: (current) => ({ revision: 1, value: { handles: change(current?.handles ?? []) } }),
+      contention,
+    });
+  }
 }
 
 function validateResult(value: unknown): TJsonValue {

package/ts_stores_nosqldb/classes.recordstore.ts

@@ -297,6 +297,13 @@ export class FlexRecordStore {
     throw mutation.contention(actualRevision);
   }
 
+  /** Deletes one record and its chunks. */
+  public async delete(address: IFlexRecordAddress): Promise<void> {
+    await this.prepare();
+    const resolved = this.resolve(address);
+    await this.deleteInTransaction(resolved.path, { recordId: resolved.recordId, domain: resolved.domain });
+  }
+
   /** Deletes every record and chunk one session owns in the given domains. */
   public async deleteOwner(
     storageKey: string,
@@ -324,6 +331,7 @@ export class FlexRecordStore {
   private async deleteInTransaction(
     path: string,
     selector:
+      | { recordId: string; domain: TFlexRecordDomain }
       | { ownerKey: string; domain: { $in: TFlexRecordDomain[] } }
       | { namespaceKey: string; domain: TFlexRecordDomain },
   ): Promise<void> {

package/ts_typedrequest/catalog.ts

@@ -0,0 +1,91 @@
+import * as plugins from './plugins.js';
+import type { IFlexCatalogMethod, IFlexCatalogRunContext, IFlexToolCatalog } from '@modelprofile.com/flexharness';
+import type {
+  IFlexTypedRequestCatalogOptions,
+  IFlexTypedRequestMethod,
+  IFlexTypedRequestSurface,
+} from './interfaces.js';
+
+/**
+ * A typed request the router refused: the `text` and `data` of its error, as a client of the API
+ * would receive them. A host's `externalErrorProjector` decides what of it the model sees.
+ */
+export class FlexTypedRequestError extends Error {
+  constructor(
+    /** The typed method: `getVoucher`. */
+    public readonly method: string,
+    /** The error's text, such as a `TypedResponseError`'s message. */
+    public readonly text: string,
+    /** The error's data. */
+    public readonly data?: unknown,
+  ) {
+    super(`${method} was refused: ${text}`);
+    this.name = 'FlexTypedRequestError';
+  }
+}
+
+/**
+ * The tool catalog of a typedrequest surface: every included method becomes a catalog method of
+ * its path, declared as its contract writes it and validated against its schema, and runs through
+ * `router.routeAndAddResponse()` in process, its request the model's parameters with the omitted
+ * properties `request` fills. A refusal rejects with `FlexTypedRequestError`.
+ */
+export function catalogFromTypedRequests<TScope = unknown>(
+  surface: IFlexTypedRequestSurface,
+  options: IFlexTypedRequestCatalogOptions<TScope>,
+): IFlexToolCatalog<TScope> {
+  if (typeof options?.router?.routeAndAddResponse !== 'function') {
+    throw new plugins.FlexHarnessValidationError('catalogFromTypedRequests needs a router with routeAndAddResponse().');
+  }
+  const aliases = options.aliases ?? {};
+  const known = new Set(surface.methods.map((method) => method.method));
+  const unknown = Object.keys(aliases).filter((method) => !known.has(method));
+  if (unknown.length > 0) {
+    throw new plugins.FlexHarnessValidationError(`The surface has no method ${unknown.join(', ')} to give aliases.`);
+  }
+  if (surface.omit.length > 0 && !options.request) {
+    throw new plugins.FlexHarnessValidationError(
+      `The surface leaves ${surface.omit.join(', ')} out of every request; the options' request() must fill them.`,
+    );
+  }
+  const include = options.include ?? ((method: IFlexTypedRequestMethod) => !method.deprecated);
+  const { router } = options;
+  const call = async (
+    method: IFlexTypedRequestMethod,
+    params: Record<string, unknown>,
+    context: IFlexCatalogRunContext<TScope>,
+  ): Promise<unknown> => {
+    const filled = options.request ? await options.request(method, context) : {};
+    const localData = options.localData ? await options.localData(method, context) : undefined;
+    const answer = await router.routeAndAddResponse(
+      {
+        method: method.method,
+        request: { ...params, ...filled },
+        response: {},
+        correlation: { id: plugins.crypto.randomUUID(), phase: 'request' },
+      },
+      { ...(localData ? { trustedLocalData: localData } : {}), trustedAbortSignal: context.abortSignal },
+    );
+    if (!answer) throw new FlexTypedRequestError(method.method, 'The router answered nothing.');
+    if (answer.error) throw new FlexTypedRequestError(method.method, answer.error.text, answer.error.data);
+    return answer.response;
+  };
+  return {
+    methods: surface.methods.filter((method) => include(method)).map((method): IFlexCatalogMethod<TScope> => ({
+      method: method.path,
+      summary: method.summary,
+      ...(method.description ? { description: method.description } : {}),
+      ...(aliases[method.method] ? { aliases: aliases[method.method] } : {}),
+      inputSchema: method.inputSchema,
+      outputSchema: method.outputSchema,
+      declaration: method.declaration,
+      run: (params: Record<string, unknown>, context) => call(method, params, context),
+      ...(options.onCall
+        ? { onCall: (params: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>) => options.onCall!(method, params, context) }
+        : {}),
+    })),
+    types: surface.types,
+    ...(options.vocabulary ? { vocabulary: options.vocabulary } : {}),
+    ...(options.onProposals ? { onProposals: options.onProposals } : {}),
+  };
+}

package/ts_typedrequest/describe.ts

@@ -0,0 +1,211 @@
+import * as plugins from './plugins.js';
+import type {
+  IFlexTypedRequestMethod,
+  IFlexTypedRequestSurface,
+  IFlexTypedRequestSurfaceOptions,
+  TFlexTypedRequestSchema,
+} from './interfaces.js';
+
+const componentsPrefix = '#/components/schemas/';
+const definitionsPrefix = '#/$defs/';
+const maxSummaryCharacters = 120;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** A schema whose references name `#/$defs/<type>` instead of the OpenAPI components. */
+const withDefinitionRefs = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(withDefinitionRefs);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+    key,
+    key === '$ref' && typeof child === 'string' && child.startsWith(componentsPrefix)
+      ? `${definitionsPrefix}${child.slice(componentsPrefix.length)}`
+      : withDefinitionRefs(child),
+  ]));
+};
+
+/** The type a `#/$defs/<type>` reference names. */
+const referencedType = (schema: TFlexTypedRequestSchema): string | undefined =>
+  typeof schema.$ref === 'string' && schema.$ref.startsWith(definitionsPrefix)
+    ? schema.$ref.slice(definitionsPrefix.length)
+    : undefined;
+
+/**
+ * A request schema without the omitted properties: an object loses them, and a reference to a
+ * named type that holds one becomes the type's own schema without them.
+ */
+const withoutOmitted = (
+  schema: TFlexTypedRequestSchema,
+  omit: ReadonlySet<string>,
+  types: Readonly<Record<string, TFlexTypedRequestSchema>>,
+): TFlexTypedRequestSchema => {
+  const target = referencedType(schema);
+  if (target !== undefined) {
+    const named = types[target];
+    return named !== undefined && holdsOmitted(named, omit, types, new Set([target]))
+      ? withoutOmitted(named, omit, types)
+      : schema;
+  }
+  const stripped: TFlexTypedRequestSchema = { ...schema };
+  if (isRecord(stripped.properties)) {
+    stripped.properties = Object.fromEntries(Object.entries(stripped.properties).filter(([key]) => !omit.has(key)));
+  }
+  if (Array.isArray(stripped.required)) {
+    stripped.required = stripped.required.filter((key) => typeof key !== 'string' || !omit.has(key));
+  }
+  for (const key of ['allOf', 'anyOf', 'oneOf'] as const) {
+    const members = stripped[key];
+    if (Array.isArray(members)) {
+      stripped[key] = members.map((member) => isRecord(member) ? withoutOmitted(member, omit, types) : member);
+    }
+  }
+  return stripped;
+};
+
+/** Whether a schema has an omitted property, itself or through the schemas it composes or refers to. */
+const holdsOmitted = (
+  schema: TFlexTypedRequestSchema,
+  omit: ReadonlySet<string>,
+  types: Readonly<Record<string, TFlexTypedRequestSchema>>,
+  seen: Set<string>,
+): boolean => {
+  if (isRecord(schema.properties) && Object.keys(schema.properties).some((key) => omit.has(key))) return true;
+  const target = referencedType(schema);
+  if (target !== undefined) {
+    if (seen.has(target) || types[target] === undefined) return false;
+    seen.add(target);
+    return holdsOmitted(types[target], omit, types, seen);
+  }
+  return (['allOf', 'anyOf', 'oneOf'] as const).some((key) => Array.isArray(schema[key])
+    && (schema[key] as unknown[]).some((member) => isRecord(member) && holdsOmitted(member, omit, types, seen)));
+};
+
+/** Whether a call may leave out every parameter: its schema requires none. */
+const requiresNothing = (
+  schema: TFlexTypedRequestSchema,
+  types: Readonly<Record<string, TFlexTypedRequestSchema>>,
+): boolean => {
+  const target = referencedType(schema);
+  if (target !== undefined) return types[target] === undefined || requiresNothing(types[target], types);
+  if (Array.isArray(schema.required) && schema.required.length > 0) return false;
+  return !Array.isArray(schema.allOf)
+    || schema.allOf.every((member) => !isRecord(member) || requiresNothing(member, types));
+};
+
+/** The named types a schema refers to. */
+const referencesIn = (value: unknown, found: Set<string>): Set<string> => {
+  if (Array.isArray(value)) {
+    for (const entry of value) referencesIn(entry, found);
+  } else if (isRecord(value)) {
+    const target = referencedType(value);
+    if (target !== undefined) found.add(target);
+    for (const child of Object.values(value)) referencesIn(child, found);
+  }
+  return found;
+};
+
+/** The first sentence of a contract's JSDoc, its tags left out, within the summary's length. */
+const summaryOf = (documentation: string | undefined, method: string): string => {
+  const prose = (documentation ?? '').split(/\n(?=@)/)[0].replace(/\s+/g, ' ').trim();
+  const sentence = prose.split(/(?<=[.!?])\s/)[0] ?? '';
+  if (!sentence) return method;
+  return [...sentence].length <= maxSummaryCharacters
+    ? sentence
+    : `${[...sentence].slice(0, maxSummaryCharacters - 1).join('')}…`;
+};
+
+/** A JSDoc block of the given lines; `*\/` in them cannot end it early. */
+const docBlock = (lines: string[]): string => {
+  const text = lines.join('\n').replace(/\*\//g, '*\\/');
+  return `/**\n${text.split('\n').map((line) => (line ? ` * ${line}` : ' *')).join('\n')}\n */\n`;
+};
+
+/** The area of a contract when the options name none: its file's base name, an `index` file's folder. */
+const defaultArea = (file: string): string => {
+  const parsed = plugins.path.posix.parse(file);
+  return parsed.name === 'index' ? plugins.path.posix.basename(parsed.dir) || parsed.name : parsed.name;
+};
+
+/**
+ * Reads a typedrequest API's contracts from their TypeScript sources: each typed method's path
+ * (`<area>.<method>`), its summary and JSDoc, its request and response as JSON Schema for
+ * validation, and its TypeScript declaration as the contract writes it, for the model to read; and
+ * the named types they reach, each with its schema, its declaration, or both. Needs the optional
+ * peer `@api.global/typedopenapi`. Run it at build time and keep the JSON, or at startup where the
+ * sources are at hand.
+ */
+export async function describeTypedRequests(options: IFlexTypedRequestSurfaceOptions): Promise<IFlexTypedRequestSurface> {
+  let typedopenapi: Awaited<ReturnType<typeof plugins.importTypedOpenApi>>;
+  try {
+    typedopenapi = await plugins.importTypedOpenApi();
+  } catch (error) {
+    throw new plugins.FlexHarnessValidationError(
+      'describeTypedRequests needs the optional peer @api.global/typedopenapi (0.8.0 or later).',
+      { cause: error },
+    );
+  }
+  const omit = [...new Set(options.omit ?? [])].sort();
+  const source = {
+    tsconfig: options.tsconfig,
+    contracts: options.contracts,
+    ...(options.contractNamePattern ? { contractNamePattern: options.contractNamePattern } : {}),
+  };
+  const schemaSet = typedopenapi.generateContractSchemas(source);
+  const declarationSet = typedopenapi.generateContractDeclarations({ ...source, omit });
+  const schemas = withDefinitionRefs(schemaSet.schemas) as Record<string, TFlexTypedRequestSchema>;
+  const declarations = new Map(declarationSet.contracts.map((contract) => [contract.name, contract]));
+  const omitted = new Set(omit);
+
+  const paths = new Set<string>();
+  const methods: IFlexTypedRequestMethod[] = schemaSet.contracts.map((contract) => {
+    const declared = declarations.get(contract.name);
+    if (!declared) {
+      throw new plugins.FlexHarnessValidationError(`@api.global/typedopenapi declared no contract ${contract.name}, whose schemas it generated.`);
+    }
+    const area = options.area ? options.area({ name: contract.name, method: contract.method, file: declared.file }) : defaultArea(declared.file);
+    const name = plugins.FlexToolCatalog.identifierOf(contract.method);
+    const base = `${plugins.FlexToolCatalog.identifierOf(area)}.${name}`;
+    let path = base;
+    for (let suffix = 2; paths.has(path); suffix++) path = `${base}_${suffix}`;
+    paths.add(path);
+    const inputSchema = withoutOmitted(withDefinitionRefs(contract.request) as TFlexTypedRequestSchema, omitted, schemas);
+    const docLines = [
+      ...(declared.documentation ? [declared.documentation] : []),
+      ...(declared.request.documentation ? [`@param params ${declared.request.documentation}`] : []),
+      ...(declared.response.documentation ? [`@returns ${declared.response.documentation}`] : []),
+    ];
+    const functionName = path.slice(path.lastIndexOf('.') + 1);
+    const optional = requiresNothing(inputSchema, schemas) ? '?' : '';
+    return {
+      method: contract.method,
+      path,
+      summary: summaryOf(declared.documentation, contract.method),
+      ...(declared.documentation ? { description: declared.documentation } : {}),
+      ...(contract.deprecated ? { deprecated: true } : {}),
+      inputSchema,
+      outputSchema: withDefinitionRefs(contract.response) as TFlexTypedRequestSchema,
+      declaration: `${docLines.length ? docBlock(docLines) : ''}function ${functionName}(params${optional}: ${declared.request.type}): Promise<${declared.response.type}>;`,
+    };
+  }).sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+
+  // Only the schemas the methods still reach: an omitted property's types are gone with it.
+  const reached = new Set<string>();
+  const pending = [...referencesIn(methods.map((method) => [method.inputSchema, method.outputSchema]), new Set())];
+  while (pending.length) {
+    const name = pending.pop()!;
+    if (reached.has(name) || schemas[name] === undefined) continue;
+    reached.add(name);
+    pending.push(...referencesIn(schemas[name], new Set()));
+  }
+  const names = [...new Set([...reached, ...Object.keys(declarationSet.types)])].sort();
+  return {
+    methods,
+    types: names.map((name) => ({
+      name,
+      ...(reached.has(name) ? { schema: schemas[name] } : {}),
+      ...(declarationSet.types[name] !== undefined ? { declaration: declarationSet.types[name] } : {}),
+    })),
+    omit,
+  };
+}

package/ts_typedrequest/index.ts

@@ -0,0 +1,3 @@
+export * from './interfaces.js';
+export { describeTypedRequests } from './describe.js';
+export { FlexTypedRequestError, catalogFromTypedRequests } from './catalog.js';