@typeship-ax/mcp 0.21.0 → 0.23.0

package/src/core/pagination.ts

@@ -1,5 +1,5 @@
 /**
- * Auto-pagination. Generated by typeship — https://typeship.dev
+ * Auto-pagination. Generated by Typeship — https://typeship.dev
  *
  * List operations return a PagePromise: `await` it for one page, or
  * `for await` it to stream every item across every page.
@@ -7,13 +7,15 @@
 
 import {
   HttpCore,
+  SdkError,
   type CoreRequest,
   type ResponseMeta,
 } from "./http.js";
 
 export interface PageConfig {
-  style: "cursor" | "cursorFromLastId" | "page" | "offset";
-  /** Response field holding the item array ("data", "items", …). */
+  style: "cursor" | "cursorFromLastId" | "page" | "offset" | "nextUrl" | "link";
+  /** Response field holding the item array ("data", "items", …); "" when
+   * the body is the array itself. */
   itemsField: string;
   cursorParam?: string;
   /** Dot-path into the response body ("next_cursor", "meta.next_cursor"). */
@@ -24,16 +26,41 @@ export interface PageConfig {
   pageParam?: string;
   offsetParam?: string;
   limitParam?: string;
+  /** nextUrl: dot-path of the next page's URL ("next_page_uri", "next"). */
+  nextUrlField?: string;
+  /** page: the first page number when it is not 1. */
+  firstPage?: number;
+  /** Dot-path of the total item count: iteration stops once it is reached. */
+  totalField?: string;
+  /** Dot-path of the total page count: page iteration stops at the last page. */
+  totalPagesField?: string;
+  /** Each item is this field of the listed element (a Relay edge's `node`). */
+  itemPath?: string;
+  /** Page size sent when the caller gives none (GraphQL `first`). */
+  defaultLimit?: number;
+  /** Relay backward paging, used when the caller passes `backward.limitParam` (`last`). */
+  backward?: { limitParam: string; cursorParam: string; cursorField: string; hasMoreField: string };
+}
+
+/** A list response the pagination rules cannot read. */
+export class PaginationError extends SdkError {
+  constructor(message: string, response?: ResponseMeta) {
+    super(message, "pagination_error", response?.status ?? null, response?.rawBody, response?.requestId);
+  }
 }
 
 type FetchPage<Item, E> = (
   query: Record<string, unknown>,
+  url?: string,
+  before?: number,
 ) => Promise<Page<Item, E>>;
 
 export class Page<Item, E = unknown> {
   private readonly fetchPage: FetchPage<Item, E>;
   private readonly config: PageConfig;
   private readonly params: Record<string, unknown>;
+  /** Items on the pages before this one, for the total-count stop. */
+  private readonly before: number;
   readonly body: unknown;
   readonly response: ResponseMeta;
 
@@ -43,48 +70,74 @@ export class Page<Item, E = unknown> {
     params: Record<string, unknown>,
     body: unknown,
     response: ResponseMeta,
+    before = 0,
   ) {
     this.fetchPage = fetchPage;
     this.config = config;
     this.params = params;
     this.body = body;
     this.response = response;
+    this.before = before;
   }
 
   get items(): Item[] {
-    const value = getPath(this.body, this.config.itemsField);
-    return Array.isArray(value) ? (value as Item[]) : [];
+    const value = this.config.itemsField === "" ? this.body : getPath(this.body, this.config.itemsField);
+    if (!Array.isArray(value)) return [];
+    const path = this.config.itemPath;
+    return path === undefined ? (value as Item[]) : value.map((entry) => (entry as Record<string, unknown> | null)?.[path] as Item);
+  }
+
+  /** True when the caller asked for backward Relay pages (`last`). */
+  private get backward(): PageConfig["backward"] | undefined {
+    const backward = this.config.backward;
+    return backward && this.params[backward.limitParam] !== undefined ? backward : undefined;
   }
 
   hasNextPage(): boolean {
     return this.nextPageParams() !== null;
   }
 
+  /** The next page's URL, for styles that follow one (a response field or
+   * the Link header); null on the last page and for the other styles. */
+  nextPageUrl(): string | null {
+    if (this.finished()) return null;
+    switch (this.config.style) {
+    }
+    return null;
+  }
+
   nextPageParams(): Record<string, unknown> | null {
     const { config, params } = this;
     const items = this.items;
-
-    if (config.hasMoreField !== undefined) {
-      const hasMore = getPath(this.body, config.hasMoreField);
-      if (hasMore === false) return null;
-    }
+    if (this.finished()) return null;
+    const backward = this.backward;
 
     switch (config.style) {
       case "cursor": {
-        const next = getPath(this.body, config.nextCursorField!);
+        const cursorParam = backward ? backward.cursorParam : config.cursorParam!;
+        const next = getPath(this.body, backward ? backward.cursorField : config.nextCursorField!);
         if (next === undefined || next === null || next === "") return null;
-        if (next === params[config.cursorParam!]) return null;
-        return { ...params, [config.cursorParam!]: next };
+        if (next === params[cursorParam]) return null;
+        return { ...params, [cursorParam]: next };
       }
     }
-    return null;
+    // URL styles: the next request is the URL itself. Pass page_url as the
+    // pageUrl request option to fetch that page.
+    const url = this.nextPageUrl();
+    if (url === null) return null;
+    // The URL is the whole request: its query can hold parameters the
+    // operation does not declare (GitHub's after), so it is passed as is.
+    return { page_url: url };
   }
 
   /** Fetch the next page, or null when this is the last one. Throws the typed error on failure. */
   async getNextPage(): Promise<Page<Item, E> | null> {
+    const url = this.nextPageUrl();
+    if (url !== null) return this.fetchPage({}, url, this.before + this.items.length);
+    if (this.config.style === "nextUrl" || this.config.style === "link") return null;
     const next = this.nextPageParams();
     if (next === null) return null;
-    return this.fetchPage(next);
+    return this.fetchPage(next, undefined, this.before + this.items.length);
   }
 
   /** Iterate every item on this page and all following pages. */
@@ -96,6 +149,36 @@ export class Page<Item, E = unknown> {
     }
   }
 
+  /** Signals every style shares: has_more false, or the total reached. */
+  private finished(): boolean {
+    // Backward Relay pages end on hasPreviousPage, forward ones on hasNextPage.
+    const hasMoreField = this.backward?.hasMoreField ?? this.config.hasMoreField;
+    if (hasMoreField !== undefined && getPath(this.body, hasMoreField) === false) return true;
+    if (this.config.totalField !== undefined) {
+      const total = getPath(this.body, this.config.totalField);
+      if (typeof total === "number" && this.itemsThrough() >= total) return true;
+    }
+    return false;
+  }
+
+  /** Items up to the end of this page: counted along a walk, or implied by
+   * the page's position when it was fetched on its own (an MCP nextPage). */
+  private itemsThrough(): number {
+    let before = this.before;
+    const { config, params } = this;
+    if (before === 0 && config.style === "offset" && config.offsetParam !== undefined) {
+      const offset = Number(params[config.offsetParam]);
+      if (Number.isFinite(offset) && offset > 0) before = offset;
+    }
+    if (before === 0 && config.style === "page" && config.pageParam !== undefined && config.limitParam !== undefined) {
+      const current = Number(params[config.pageParam]);
+      const limit = Number(params[config.limitParam]);
+      const first = config.firstPage ?? 1;
+      if (Number.isFinite(current) && Number.isFinite(limit) && limit > 0 && current > first) before = (current - first) * limit;
+    }
+    return before + this.items.length;
+  }
+
   private looksLikeMore(items: Item[]): boolean {
     if (items.length === 0) return false;
     if (this.config.limitParam !== undefined) {
@@ -137,20 +220,48 @@ export function paginate<Item, E>(
 ): PagePromise<Item, E> {
   const isGraphql = false
   ;
-  const fetchPage: FetchPage<Item, E> = async (params) => {
+  const fetchPage: FetchPage<Item, E> = async (params, url, before = 0) => {
     let nextReq: CoreRequest = { ...req, query: params };
+    if (url !== undefined) {
+      // A next-page URL is followed verbatim, but only on the API's own
+      // origin: the request carries the client's credentials.
+      const base = new URL(core.config.baseUrl);
+      const target = new URL(url, base);
+      if (target.origin !== base.origin) {
+        throw new PaginationError("The next page is on another origin (" + target.origin + "); refusing to send credentials there. Fetch it yourself if you trust it.");
+      }
+      nextReq = { ...req, query: undefined, url: target.toString() };
+    }
     const result = await core.request<unknown, E>(nextReq);
     if (!result.ok) throw result.error instanceof Error ? result.error : new Error(String(result.error));
-    return new Page<Item, E>(fetchPage, config, params, result.data, result.response);
+    // A page without its item array is a contract break, not an empty page:
+    // iterating it would silently end the walk. A null array is empty.
+    const items = config.itemsField === "" ? result.data : getPath(result.data, config.itemsField);
+    if (!Array.isArray(items) && !(items === null && config.itemsField !== "")) {
+      throw new PaginationError(
+        (config.itemsField === "" ? "The list response is not an array" : "The list response has no " + JSON.stringify(config.itemsField) + " array")
+          + ". Check the API response against the spec, or configure this operation's pagination.",
+        result.response,
+      );
+    }
+    return new Page<Item, E>(fetchPage, config, params, result.data, result.response, before);
   };
   const initial: Record<string, unknown> = {};
   let seed = req.query ?? {};
   for (const [k, v] of Object.entries(seed)) {
     if (v !== undefined) initial[k] = v;
   }
-  return new PagePromise<Item, E>(fetchPage(initial));
+  // Relay servers reject a connection query with neither `first` nor `last`.
+  const backwardLimit = config.backward?.limitParam;
+  if (config.defaultLimit !== undefined && config.limitParam !== undefined && initial[config.limitParam] === undefined
+    && (backwardLimit === undefined || initial[backwardLimit] === undefined)) {
+    initial[config.limitParam] = config.defaultLimit;
+  }
+  const pageUrl = req.options?.pageUrl;
+  return new PagePromise<Item, E>(pageUrl !== undefined ? fetchPage({}, pageUrl) : fetchPage(initial));
 }
 
+
 function getPath(body: unknown, path: string): unknown {
   let node: unknown = body;
   for (const key of path.split(".")) {

package/src/credential-storage.ts

@@ -30,12 +30,22 @@ function parseKey(value: string): Buffer {
   return key;
 }
 
+/** The OS item's service name: the command that owns it, then a digest of
+ * the session file, so each profile has its own key. Limited to a fixed
+ * alphabet because the macOS write passes it through security's command
+ * stream. */
+export function credentialKeyService(owner: string, path: string): string {
+  const name = owner.replace(/[^A-Za-z0-9._-]/g, "-") || "cli";
+  return name + ".credentials." + createHash("sha256").update(resolve(path)).digest("hex");
+}
+
 /** A small wrapping key avoids OS item-size limits; session files are encrypted
- * separately so refresh rotation can retain the atomic file/lock transaction. */
-export function nativeCredentialKeyStore(path: string, platform: NodeJS.Platform = process.platform, run: NativeCommand = nativeCommand, environmentName = "CREDENTIAL_STORE"): CredentialKeyStore {
+ * separately so refresh rotation can retain the atomic file/lock transaction.
+ * `owner` is the command name; the CLI and its local MCP server pass the same
+ * one so they share the key. */
+export function nativeCredentialKeyStore(path: string, owner: string, platform: NodeJS.Platform = process.platform, run: NativeCommand = nativeCommand, environmentName = "CREDENTIAL_STORE"): CredentialKeyStore {
   const failed = (name: string): never => unavailable(name, environmentName);
-  const identity = createHash("sha256").update(resolve(path)).digest("hex");
-  const service = "typeship.credentials." + identity;
+  const service = credentialKeyService(owner, path);
   const account = "session-key";
   if (platform === "darwin") {
     const name = "macOS Keychain";
@@ -175,9 +185,9 @@ export function encryptedCredentialCodec(path: string, keyStore: CredentialKeySt
 /** OS protection is the default. Plaintext storage is an explicit, separate
  * store for environments where the owner accepts that tradeoff. Never migrate
  * or fall back silently when an OS service is unavailable. */
-export function createCredentialStore(directory: string, mode: string = "os", environmentName = "CREDENTIAL_STORE"): FileCredentialStore {
+export function createCredentialStore(directory: string, owner: string, mode: string = "os", environmentName = "CREDENTIAL_STORE"): FileCredentialStore {
   if (mode === "file") return new FileCredentialStore(join(directory, "credentials.json"));
   if (mode !== "os") throw new CredentialStorageError(environmentName + " must be os or file.");
   const path = join(directory, "credentials.enc");
-  return new FileCredentialStore(path, 40_000, encryptedCredentialCodec(path, nativeCredentialKeyStore(path, process.platform, nativeCommand, environmentName)));
+  return new FileCredentialStore(path, 40_000, encryptedCredentialCodec(path, nativeCredentialKeyStore(path, owner, process.platform, nativeCommand, environmentName)));
 }

package/src/dates.ts

@@ -1,5 +1,5 @@
 /**
- * Relative dates for date / date-time arguments. Generated by typeship — https://typeship.dev
+ * Relative dates for date / date-time arguments. Generated by Typeship — https://typeship.dev
  *
  * Agents rarely know "now" and often do know "a week ago", so date-shaped
  * arguments of the CLI and the MCP server accept, besides an absolute

package/src/errors.ts

@@ -1,138 +1,69 @@
-// typeship — typed error classes.
-// Generated by typeship — https://typeship.dev
+// Typeship — typed error classes.
+// Generated by Typeship — https://typeship.dev
 
-import { ApiError, type ResponseMeta } from "./core/http.js";
+import { ApiError, RateLimitError, ServerError, type ResponseMeta } from "./core/http.js";
 import type { ErrorModel, ErrorModelRead } from "./types.js";
 
-export { ApiError, SdkError, ResponseParseError, TransportError, UnexpectedApiError, ValidationError, type Violation } from "./core/http.js";
+export {
+  ApiError,
+  SdkError,
+  PayloadError,
+  ResponseParseError,
+  TransportError,
+  UnexpectedApiError,
+  ValidationError,
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  NotFoundError,
+  NotModifiedError,
+  RateLimitError,
+  ServerError,
+  UnauthorizedError,
+  UnprocessableEntityError,
+  type RateLimitInfo,
+  type Violation,
+} from "./core/http.js";
 
-/**
- * The request body, Spec source, target selection, or package name is invalid.
- * Raised for HTTP 400 responses.
- */
-export class BadRequestError extends ApiError<400, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The request body, Spec source, target selection, or package name is invalid.", 400, body, response);
-  }
-}
-
-/**
- * Missing, invalid, expired, or revoked credentials.
- * Raised for HTTP 401 responses.
- */
-export class UnauthorizedError extends ApiError<401, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("Missing, invalid, expired, or revoked credentials.", 401, body, response);
-  }
-}
-
-/**
- * The credentials are valid but cannot act on the requested organization.
- * Raised for HTTP 403 responses.
- */
-export class ForbiddenError extends ApiError<403, ErrorModelRead> {
+/** Raised for HTTP 402 responses. */
+export class PaymentRequiredError extends ApiError<402, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The credentials are valid but cannot act on the requested organization.", 403, body, response);
+    super("HTTP 402", 402, body, response);
   }
 }
 
-/**
- * The key identifies changed intent.
- * Raised for HTTP 409 responses.
- */
-export class ConflictError extends ApiError<409, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The key identifies changed intent.", 409, body, response);
-  }
-}
+/** @deprecated Use RateLimitError, raised for every 429 response. */
+export const RateLimitedError = RateLimitError;
+/** @deprecated Use RateLimitError, raised for every 429 response. */
+export type RateLimitedError = RateLimitError<ErrorModelRead>;
 
-/**
- * Spec exceeds the 10MB limit.
- * Raised for HTTP 413 responses.
- */
-export class PayloadTooLargeError extends ApiError<413, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("Spec exceeds the 10MB limit.", 413, body, response);
-  }
-}
+/** @deprecated Use ServerError, raised for every 5xx response. */
+export const InternalServerError = ServerError;
+/** @deprecated Use ServerError, raised for every 5xx response. */
+export type InternalServerError = ServerError<ErrorModelRead>;
 
-/**
- * The Spec could not be resolved or understood.
- * Raised for HTTP 422 responses.
- */
-export class UnprocessableEntityError extends ApiError<422, ErrorModelRead> {
+/** Raised for HTTP 412 responses. */
+export class PreconditionFailedError extends ApiError<412, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The Spec could not be resolved or understood.", 422, body, response);
+    super("HTTP 412", 412, body, response);
   }
 }
 
-/**
- * Too many requests, or an identical write is still in progress. Wait for Retry-After before
- * retrying.
- * Raised for HTTP 429 responses.
- */
-export class RateLimitedError extends ApiError<429, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("Too many requests, or an identical write is still in progress. Wait for Retry-After before retrying.", 429, body, response);
-  }
-}
+/** @deprecated Use ServerError, raised for every 5xx response. */
+export const BadGatewayError = ServerError;
+/** @deprecated Use ServerError, raised for every 5xx response. */
+export type BadGatewayError = ServerError<ErrorModelRead>;
 
-/**
- * An unexpected error prevented the request from completing.
- * Raised for HTTP 500 responses.
- */
-export class InternalServerError extends ApiError<500, ErrorModelRead> {
+/** Raised for HTTP 413 responses. */
+export class PayloadTooLargeError extends ApiError<413, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("An unexpected error prevented the request from completing.", 500, body, response);
+    super("HTTP 413", 413, body, response);
   }
 }
 
-/**
- * Unexpected error.
- * Raised for "default" responses.
- */
+/** Raised for "default" responses. */
 export class ApiResponseError extends ApiError<number, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("Unexpected error.", response.status, body, response);
-  }
-}
-
-/**
- * No such resource in this organization.
- * Raised for HTTP 404 responses.
- */
-export class NotFoundError extends ApiError<404, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("No such resource in this organization.", 404, body, response);
-  }
-}
-
-/**
- * The plan does not include another project or the requested target configuration.
- * Raised for HTTP 402 responses.
- */
-export class PaymentRequiredError extends ApiError<402, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The plan does not include another project or the requested target configuration.", 402, body, response);
-  }
-}
-
-/**
- * The resource changed since the ETag supplied in If-Match. No write was applied.
- * Raised for HTTP 412 responses.
- */
-export class PreconditionFailedError extends ApiError<412, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The resource changed since the ETag supplied in If-Match. No write was applied.", 412, body, response);
-  }
-}
-
-/**
- * Dependent work failed while completing the request.
- * Raised for HTTP 502 responses.
- */
-export class BadGatewayError extends ApiError<502, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("Dependent work failed while completing the request.", 502, body, response);
+    super("HTTP " + response.status, response.status, body, response);
   }
 }

package/src/fields.ts

@@ -0,0 +1,167 @@
+/**
+ * Result projection shared by the generated CLI (--fields) and MCP server
+ * (the fields argument). Generated by Typeship — https://typeship.dev
+ */
+
+/** Keep only `paths` of a value: arrays item by item, objects by dotted
+ * path, including paths through arrays (`items.id` keeps each item's id);
+ * scalars untouched. */
+export function projectFields(value: unknown, paths: string[][] | null): unknown {
+  if (paths === null) return value;
+  if (Array.isArray(value)) return value.map((v) => projectFields(v, paths));
+  if (value === null || typeof value !== "object") return value;
+  const groups = new Map<string, string[][]>();
+  for (const [key, ...rest] of paths) {
+    if (key === undefined) continue;
+    const group = groups.get(key);
+    if (group) group.push(rest); else groups.set(key, [rest]);
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, rests] of groups) {
+    const child = (value as Record<string, unknown>)[key];
+    if (child === undefined) continue;
+    if (rests.some((rest) => rest.length === 0)) out[key] = child;
+    else if (child !== null && typeof child === "object") out[key] = projectFields(child, rests);
+  }
+  return out;
+}
+
+/** A requested path that selected nothing, with the keys that exist where
+ * it stopped matching. */
+export interface UnmatchedField {
+  path: string;
+  /** Keys present at the level where the path failed, first 40. */
+  available: string[];
+  /** The path segment that is not a key there, or null when the path runs
+   * into a scalar or the result is not an object. */
+  missing: string | null;
+}
+
+/**
+ * The paths that match nothing in any item of `value`. A path matches when
+ * at least one item has it; reaching null or an empty array counts as a
+ * match, because the path may be right and the values merely empty. An
+ * empty result matches everything.
+ *
+ * `schema` is the JSON Schema of `value` (the operation's declared
+ * response, or its item schema for a list). A key the schema declares may
+ * be absent from every item, as optional fields are: the path matches, and
+ * projects to nothing. What the schema cannot vouch for (no schema, an
+ * object without properties, a key it does not list) still has to be in
+ * the data.
+ */
+export function unmatchedFields(value: unknown, paths: string[][], schema?: unknown): UnmatchedField[] {
+  const out: UnmatchedField[] = [];
+  for (const path of paths) {
+    const miss = { depth: -1, keys: new Set<string>(), segment: null as string | null };
+    if (!pathMatches(value, path, 0, miss, schema)) {
+      out.push({ path: path.join("."), available: [...miss.keys].slice(0, 40), missing: miss.segment });
+    }
+  }
+  return out;
+}
+
+type Miss = { depth: number; keys: Set<string>; segment: string | null };
+
+function pathMatches(value: unknown, path: string[], index: number, miss: Miss, schema: unknown): boolean {
+  if (value === null || value === undefined) return true;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return true;
+    const items = arrayItems(schema);
+    let any = false;
+    for (const item of value) if (pathMatches(item, path, index, miss, items)) any = true;
+    return any;
+  }
+  if (index === path.length) return true;
+  if (typeof value !== "object") {
+    if (miss.depth < index) { miss.depth = index; miss.keys = new Set(); miss.segment = null; }
+    return false;
+  }
+  const key = path[index]!;
+  const record = value as Record<string, unknown>;
+  if (!Object.hasOwn(record, key)) {
+    const declared = declaredProperty(schema, key);
+    if (declared !== undefined) return declaredPath(declared, path, index + 1, miss);
+    if (miss.depth < index) { miss.depth = index; miss.keys = new Set(); miss.segment = key; }
+    if (miss.depth === index) for (const k of Object.keys(record)) miss.keys.add(k);
+    return false;
+  }
+  return pathMatches(record[key], path, index + 1, miss, declaredProperty(schema, key));
+}
+
+/** The rest of a path below a declared key no item has: nothing in the data
+ * can contradict it, so it matches unless the schema lists that level's
+ * keys and the next segment is not one of them. */
+function declaredPath(schema: unknown, path: string[], index: number, miss: Miss): boolean {
+  if (index === path.length) return true;
+  const key = path[index]!;
+  const declared = declaredProperty(schema, key);
+  if (declared !== undefined) return declaredPath(declared, path, index + 1, miss);
+  const listed = listedProperties(schema);
+  if (listed === null) return true;
+  if (miss.depth < index) { miss.depth = index; miss.keys = new Set(); miss.segment = key; }
+  if (miss.depth === index) for (const k of listed) miss.keys.add(k);
+  return false;
+}
+
+/** A schema with its allOf, anyOf and oneOf branches flattened, arrays
+ * seen through to their items. */
+function variants(schema: unknown, out: Record<string, unknown>[] = []): Record<string, unknown>[] {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) return out;
+  const node = schema as Record<string, unknown>;
+  out.push(node);
+  for (const key of ["allOf", "anyOf", "oneOf"]) {
+    const branches = node[key];
+    if (Array.isArray(branches)) for (const branch of branches) variants(branch, out);
+  }
+  return out;
+}
+
+function arrayItems(schema: unknown): unknown {
+  const items = variants(schema).map((node) => node.items).filter((item) => item !== undefined && item !== null);
+  return items.length === 0 ? undefined : items.length === 1 ? items[0] : { anyOf: items };
+}
+
+/** The schema of `key` when some branch declares it, else undefined. */
+function declaredProperty(schema: unknown, key: string): unknown {
+  const found = variants(schema).flatMap((node) => {
+    const properties = node.properties as Record<string, unknown> | undefined;
+    return properties && typeof properties === "object" && Object.hasOwn(properties, key) ? [properties[key] ?? {}] : [];
+  });
+  return found.length === 0 ? undefined : found.length === 1 ? found[0] : { anyOf: found };
+}
+
+/** Every key the schema declares, or null when it cannot say which keys
+ * exist: no schema, an object without properties, or one that admits more. */
+function listedProperties(schema: unknown): string[] | null {
+  const nodes = variants(schema);
+  const keys: string[] = [];
+  let closed = false;
+  for (const node of nodes) {
+    const properties = node.properties as Record<string, unknown> | undefined;
+    if (properties && typeof properties === "object") {
+      closed = true;
+      keys.push(...Object.keys(properties));
+    }
+    if (node.additionalProperties !== undefined && node.additionalProperties !== false) return null;
+    if (node.patternProperties !== undefined) return null;
+    // Tool schemas keep the first eight variants of a union; more may exist.
+    if (Array.isArray(node.anyOf) && node.anyOf.length >= 8) return null;
+  }
+  // A branch that is an object without listed properties is open.
+  if (nodes.some((node) => node.properties === undefined && (node.type === "object" || (Array.isArray(node.type) && node.type.includes("object"))))) return null;
+  return closed ? [...new Set(keys)] : null;
+}
+
+/** The error message: the call went through, and for each unmatched path,
+ * what exists instead. */
+export function unmatchedFieldsMessage(unmatched: UnmatchedField[], perItem: boolean): string {
+  return "The API call succeeded, but " + unmatched.map((u, index) => {
+    const where = perItem ? " in any item" : " in the result";
+    const why = u.missing !== null
+      ? " (\"" + u.missing + "\" is not a key there)"
+      : " (it runs into a value that is not an object)";
+    const keys = u.available.length > 0 ? " Available keys: " + u.available.join(", ") + "." : "";
+    return (index === 0 ? "the" : "The") + " field path \"" + u.path + "\" matched nothing" + where + why + "." + keys;
+  }).join(" ");
+}