@animalabs/agent-framework 0.22.2 → 0.23.0

package/src/silent-heartbeat.ts

@@ -1,40 +1,70 @@
 /**
- * Stored-row handling for silent heartbeat ticks.
+ * Request-only rows: user turns a request carries before a stored response
+ * that the store never holds, rendered again by every later compile.
  *
- * A silent tick stores no prompt row (#216): its reply is written straight
- * after whatever the window held before it — often the previous assistant
- * message, since a suppressed tick leaves no delivery receipt behind. The
- * wire formatter merges consecutive same-role messages, so without a turn
- * between them the tick would read as an unprompted continuation of the
- * earlier response and one assistant message would carry signed thinking
- * from two separate responses (a provider 400 when it is the latest
- * assistant message; see `Agent.addAssistantResponse`).
+ * Two kinds exist, and both are anchored to the response they prompted:
  *
- * Every row a tick writes is therefore stamped with `metadata.silentHeartbeat`
- * and, at request-build time only, a terse user turn is rendered immediately
- * before the first of the tick's rows that survives compilation. The
- * separator is never stored and its position is a function of the stamped
- * rows alone, so every compile renders it in the same place (the tick's own
- * request ends on the same turn), which keeps the prompt-cache prefix
- * stable — unlike a per-compile injection that re-anchors to the newest user
- * message.
+ * - A silent heartbeat tick stores no prompt row (#216): its reply is written
+ *   straight after whatever the window held before it — often the previous
+ *   assistant message, since a suppressed tick leaves no delivery receipt
+ *   behind. Every row a tick writes is stamped with `metadata.silentHeartbeat`,
+ *   and a separator carrying the tick's instruction is rendered before the
+ *   first of the tick's rows that survives compilation.
+ * - A compile that ends on the agent's own message gets a trailing
+ *   `[Continue]` turn (some models reject a trailing assistant message). The
+ *   reply it prompts is stored straight after that message, so the reply's
+ *   rows are stamped `metadata.promptedBy` (`RequestOnlyPrompt`), and the turn
+ *   is rendered before the first of them that survives. A reply follows the
+ *   prompt when what it was sent ends on that `[Continue]`, or on the tool
+ *   results of a reply that followed it (`toolLoopPrompt`): a stream start
+ *   and each round of a stream alike. A reply sent anything else after the
+ *   results (a message that arrived meanwhile) follows that, and carries no
+ *   prompt.
+ *
+ * Without the row, the wire formatter merges consecutive same-role messages:
+ * the reply would read as an unprompted continuation of the earlier response,
+ * and one assistant message would carry signed thinking from two separate
+ * responses (a provider 400 when it is the latest assistant message; see
+ * `Agent.addAssistantResponse`). And the request that minted the reply held
+ * the row: a provider that binds signed thinking to the prefix it was minted
+ * under (context-manager #155) refuses that thinking once a later request
+ * drops it. Each row's text is read from the stamp (what the request that
+ * minted the reply rendered, so a later change to the constant changes no
+ * stored reply's prefix) and its position is a function of the stamped rows
+ * alone, so every compile renders it in the same place (the request that
+ * minted the reply ends on that same turn), which keeps the prompt-cache
+ * prefix and the binding stable — unlike a per-compile injection that
+ * re-anchors to the newest user message, or a system prompt that changes for
+ * one turn.
  *
  * Known limit: compiled messages carry no store provenance, so a stored row
  * is recognised only by structural identity the provider made unique
- * (tool_use ids, thinking signatures). A tick reply with neither — unsigned
- * and tool-free — gets no separator and still merges as before. Without
- * signed thinking that merge carries no provider-rejection risk; it is only
- * a misreading. Reply text is deliberately never used as identity: identical
- * replies ("all quiet") would collide, and an ordinary reply with the same
- * text could take a tick's separator and rewrite cached history. Exact
- * matching for every row would need the compile result to expose each
- * message's source rows.
+ * (tool_use ids, thinking signatures). A reply with neither — unsigned and
+ * tool-free — gets no row and still merges as before. Without signed thinking
+ * that merge carries no provider-rejection risk; it is only a misreading.
+ * Reply text is deliberately never used as identity: identical replies ("all
+ * quiet") would collide, and an ordinary reply with the same text could take
+ * another reply's row and rewrite cached history. Exact matching for every
+ * row would need the compile result to expose each message's source rows.
  */
 import type { ContentBlock, NormalizedMessage } from '@animalabs/membrane';
 
-/** Request-only separator text. Constant on purpose: it carries no time or
- * id, so it is byte-identical on every compile. */
-export const SILENT_HEARTBEAT_SEPARATOR = '[heartbeat tick]';
+/** Request-only separator a silent tick's request ends on. It carries the
+ * tick's instruction, so the tick's own request reads it as its prompt, and
+ * every later compile renders it again before the tick's first surviving row.
+ * Constant on purpose: it carries no time or id. Each tick's rows record the
+ * text their request rendered (`SilentHeartbeatStamp.separator`), so changing
+ * this constant changes only ticks that open afterwards. */
+export const SILENT_HEARTBEAT_SEPARATOR =
+  '[silent heartbeat] Scheduled private self-check. Review pending matters privately. ' +
+  'Do not narrate or publish plain prose; use an explicit send tool only if you deliberately choose to contact someone.';
+
+/** The separator ticks rendered before their rows recorded its text: rows
+ * stamped without `separator` still render it, byte for byte. */
+const LEGACY_SILENT_HEARTBEAT_SEPARATOR = '[heartbeat tick]';
+
+/** Request-only turn a compile that ends on the agent's own message gets. */
+export const CONTINUE_ROW = '[Continue]';
 
 /** Identity of one authenticated silent heartbeat tick. */
 export interface SilentHeartbeatTick {
@@ -50,20 +80,63 @@ export interface SilentHeartbeatTick {
  * (tool_result rows are stored as `user`). */
 export interface SilentHeartbeatStamp extends SilentHeartbeatTick {
   agentName: string;
+  /** The separator text the tick's request rendered, which later compiles
+   * render again. Absent on rows stamped before it was recorded; they render
+   * the bare marker those requests carried. */
+  separator?: string;
+}
+
+/** One tick's key in an index or a rendered window: the server and its event
+ * id together, since two servers' events can share an id. */
+export function tickKey(tick: SilentHeartbeatTick): string {
+  return JSON.stringify([tick.serverId, tick.eventId]);
 }
 
 /** The tick stamp on a stored row's metadata, if any. */
 export function silentHeartbeatOf(metadata: unknown): SilentHeartbeatStamp | undefined {
   const stamp = (metadata as { silentHeartbeat?: unknown } | undefined)?.silentHeartbeat;
   if (!stamp || typeof stamp !== 'object') return undefined;
-  const { eventId, serverId, agentName } = stamp as Record<string, unknown>;
+  const { eventId, serverId, agentName, separator } = stamp as Record<string, unknown>;
   return typeof eventId === 'string' && typeof serverId === 'string' && typeof agentName === 'string'
-    ? { eventId, serverId, agentName }
+    ? { eventId, serverId, agentName, ...(typeof separator === 'string' ? { separator } : {}) }
     : undefined;
 }
 
+/** A request-only turn a request ended on before the agent's reply, as
+ * `metadata.promptedBy` on the rows of each reply that follows it: `turn`
+ * names the one prompt, and `text` is what the request rendered. */
+export interface RequestOnlyPrompt {
+  turn: string;
+  text: string;
+}
+
+/** The stamps on a row a turn stores after a request-only turn
+ * (`silentHeartbeatOf`, `promptedByOf` read them back). A type alias, so a
+ * value fits `MessageMetadata`'s index signature without a cast, and a
+ * misspelled key fails to compile. */
+export type RequestOnlyStamps = {
+  silentHeartbeat?: SilentHeartbeatStamp;
+  promptedBy?: RequestOnlyPrompt;
+};
+
+/** The request-only prompt a stored row replies to, if any. */
+export function promptedByOf(metadata: unknown): RequestOnlyPrompt | undefined {
+  const prompt = (metadata as { promptedBy?: unknown } | undefined)?.promptedBy;
+  if (!prompt || typeof prompt !== 'object') return undefined;
+  const { turn, text } = prompt as Record<string, unknown>;
+  return typeof turn === 'string' && typeof text === 'string' ? { turn, text } : undefined;
+}
+
 export function silentHeartbeatSeparatorTurn(): NormalizedMessage {
-  return { participant: 'user', content: [{ type: 'text', text: SILENT_HEARTBEAT_SEPARATOR }] };
+  return requestOnlyTurn(SILENT_HEARTBEAT_SEPARATOR);
+}
+
+export function continueTurn(): NormalizedMessage {
+  return requestOnlyTurn(CONTINUE_ROW);
+}
+
+function requestOnlyTurn(text: string): NormalizedMessage {
+  return { participant: 'user', content: [{ type: 'text', text }] };
 }
 
 /**
@@ -76,7 +149,7 @@ export function silentHeartbeatSeparatorTurn(): NormalizedMessage {
 function identityKeys(content: ContentBlock[]): string[] {
   const keys: string[] = [];
   for (const block of content) {
-    if (block.type === 'tool_use' && typeof block.id === 'string' && block.id) keys.push(`tool_use:${block.id}`);
+    if (block.type === 'tool_use' && typeof block.id === 'string' && block.id) keys.push(toolUseKey(block.id));
     else if (block.type === 'thinking' && typeof block.signature === 'string' && block.signature) {
       keys.push(`thinking:${block.signature}`);
     } else if (block.type === 'redacted_thinking' && typeof block.data === 'string' && block.data) {
@@ -86,56 +159,108 @@ function identityKeys(content: ContentBlock[]): string[] {
   return keys;
 }
 
+function toolUseKey(id: string): string {
+  return `tool_use:${id}`;
+}
+
 export interface StoredRowLike {
   participant: string;
   content: ContentBlock[];
   metadata?: unknown;
 }
 
-export interface SilentTickIndex {
-  /** Identity key of every assistant row this agent stored during a tick → tick event id. */
-  rows: Map<string, string>;
-  /** Ticks this agent has already stored rows for (its own, not another resident's). */
-  started: Set<string>;
+export interface RequestOnlyRowIndex {
+  /** Identity key of every assistant row this agent stored during a silent
+   *  tick → the tick (`tickKey`), and the separator text to render before
+   *  its first surviving row. */
+  ticks: Map<string, { tick: string; text: string }>;
+  /** Identity key of every assistant row this agent stored in reply to a
+   *  request-only prompt → that prompt. */
+  prompts: Map<string, RequestOnlyPrompt>;
 }
 
-/** Index the rows this agent stored during silent ticks. */
-export function indexSilentTickRows(stored: readonly StoredRowLike[], agentName: string): SilentTickIndex {
-  const rows = new Map<string, string>();
-  const started = new Set<string>();
+/** Index the agent's own rows that follow request-only turns: the rows of its
+ * silent ticks, and the rows of each reply to a `[Continue]`. The two are
+ * independent, so a row can be both. Only stamped rows are keyed, so an
+ * agent's history walk costs a metadata read per row. */
+export function indexRequestOnlyRows(stored: readonly StoredRowLike[], agentName: string): RequestOnlyRowIndex {
+  const ticks = new Map<string, { tick: string; text: string }>();
+  const prompts = new Map<string, RequestOnlyPrompt>();
   for (const row of stored) {
-    const stamp = silentHeartbeatOf(row.metadata);
-    if (!stamp || stamp.agentName !== agentName) continue;
-    started.add(stamp.eventId);
     if (row.participant !== agentName) continue;
-    for (const key of identityKeys(row.content)) rows.set(key, stamp.eventId);
+    const stamp = silentHeartbeatOf(row.metadata);
+    const ownTick = stamp !== undefined && stamp.agentName === agentName;
+    const prompt = promptedByOf(row.metadata);
+    if (!ownTick && !prompt) continue;
+    const keys = identityKeys(row.content);
+    if (ownTick) {
+      const tick = { tick: tickKey(stamp), text: stamp.separator ?? LEGACY_SILENT_HEARTBEAT_SEPARATOR };
+      for (const key of keys) ticks.set(key, tick);
+    }
+    if (prompt) for (const key of keys) prompts.set(key, prompt);
   }
-  return { rows, started };
+  return { ticks, prompts };
 }
 
 /**
- * Insert the separator turn immediately before the first surviving row of
- * each tick in a compiled window — the tick's first row when it is rendered,
- * otherwise whichever later row a strategy kept. Rows folded into summaries
+ * The prompt a reply continues when what it is sent ends on `last`: if
+ * `last` holds tool results, the prompt of the reply that called those tools
+ * (this reply continues that reply's tool loop); otherwise none. Read from
+ * the stored stamps, so it doesn't depend on anything held in memory. A
+ * request that ends on its own `[Continue]` mints a new prompt instead.
+ */
+export function toolLoopPrompt(
+  last: NormalizedMessage | undefined,
+  index: RequestOnlyRowIndex,
+): RequestOnlyPrompt | undefined {
+  if (!last) return undefined;
+  for (const block of last.content) {
+    if (block.type !== 'tool_result') continue;
+    const prompt = index.prompts.get(toolUseKey(block.toolUseId));
+    if (prompt) return prompt;
+  }
+  return undefined;
+}
+
+export interface RenderedRequestOnlyRows {
+  messages: NormalizedMessage[];
+  /** The ticks (`tickKey`) whose separator this window renders. A tick none
+   *  of whose rows survive compilation renders none. */
+  separatedTicks: Set<string>;
+}
+
+/**
+ * Insert the request-only turns into a compiled window, each immediately
+ * before the first of its rows that survives compilation (the first row when
+ * it is rendered, otherwise whichever later row a strategy kept): a tick's
+ * separator, and the prompt each reply to `[Continue]` followed, after any
+ * separator, as the reply's request had them. Rows folded into summaries
  * simply do not match; ordinary messages pass through untouched.
  */
-export function separateSilentHeartbeatTicks(
+export function renderRequestOnlyRows(
   messages: NormalizedMessage[],
-  rows: ReadonlyMap<string, string>,
+  index: RequestOnlyRowIndex,
   agentName: string,
-): NormalizedMessage[] {
-  if (rows.size === 0) return messages;
-  const separated = new Set<string>();
+): RenderedRequestOnlyRows {
+  const separatedTicks = new Set<string>();
+  const promptedTurns = new Set<string>();
+  if (index.ticks.size === 0 && index.prompts.size === 0) return { messages, separatedTicks };
   const out: NormalizedMessage[] = [];
   for (const message of messages) {
     if (message.participant === agentName) {
-      const eventId = identityKeys(message.content).map((key) => rows.get(key)).find((id) => id !== undefined);
-      if (eventId !== undefined && !separated.has(eventId)) {
-        separated.add(eventId);
-        out.push(silentHeartbeatSeparatorTurn());
+      const keys = identityKeys(message.content);
+      const tick = keys.map((key) => index.ticks.get(key)).find((t) => t !== undefined);
+      if (tick !== undefined && !separatedTicks.has(tick.tick)) {
+        separatedTicks.add(tick.tick);
+        out.push(requestOnlyTurn(tick.text));
+      }
+      const prompt = keys.map((key) => index.prompts.get(key)).find((p) => p !== undefined);
+      if (prompt !== undefined && !promptedTurns.has(prompt.turn)) {
+        promptedTurns.add(prompt.turn);
+        out.push(requestOnlyTurn(prompt.text));
       }
     }
     out.push(message);
   }
-  return out;
+  return { messages: out, separatedTicks };
 }

package/src/tool-args.ts

@@ -0,0 +1,213 @@
+import type { ToolDefinition } from './types/index.js';
+
+/** A run of 16 or more digits, which membrane's XML parser passes as text for
+ *  a number or integer parameter: some such runs would lose precision as a
+ *  JavaScript number, so membrane keeps every one as text, and so does this
+ *  check. */
+const LARGE_INTEGER_TEXT = /^\d{16,}$/;
+
+/** The JSON kind of a value, as a schema's `type` names it. */
+function kindOf(value: unknown): string {
+  if (Array.isArray(value)) return 'array';
+  if (value === null) return 'null';
+  return typeof value;
+}
+
+/** A kind with its article, for a sentence. */
+function withArticle(kind: string): string {
+  if (kind === 'null') return 'null';
+  return /^[aeiou]/.test(kind) ? `an ${kind}` : `a ${kind}`;
+}
+
+/** The types JSON Schema names. A `type` naming anything else, such as
+ *  `any`, is one the check can't read. */
+const JSON_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array', 'null']);
+
+/** The kinds a declaration's type admits, each once, or none when it declares
+ *  none it can read. A type list naming anything JSON Schema doesn't have is
+ *  one it can't read as a whole, as membrane reads it, rather than the names
+ *  in it that it knows. OpenAPI's `nullable: true`, the form Gemini's dialect
+ *  uses, admits `null` beside its type, as a type list naming `null` does. */
+function admittedKinds(param: { type?: unknown; nullable?: unknown } | undefined): string[] {
+  const type = param?.type;
+  const types = Array.isArray(type) ? type : type === undefined ? [] : [type];
+  if (!types.every((t) => typeof t === 'string' && JSON_TYPES.has(t))) return [];
+  const kinds = new Set((types as string[]).map((t) => (t === 'integer' ? 'number' : t)));
+  if (kinds.size > 0 && param?.nullable === true) kinds.add('null');
+  return [...kinds];
+}
+
+/** Whether `null` is a value for a key so declared: where the declaration
+ *  admits it (a type list naming it, or `nullable: true`), or declares no
+ *  type at all. A type the check can't read says nothing about `null`, so
+ *  there `null` is no value unless the declaration names it. */
+function takesNull(param: { type?: unknown; nullable?: unknown } | undefined): boolean {
+  const type = param?.type;
+  if (type === undefined || param?.nullable === true) return true;
+  return Array.isArray(type) ? type.includes('null') : type === 'null';
+}
+
+/** A value as the call gave it, briefly: the first 80 characters of its JSON
+ *  text, then an ellipsis when there are more, cut between characters rather
+ *  than inside one. The whole value is serialized before the cut. */
+function shown(value: unknown): string {
+  let text: string;
+  try {
+    text = JSON.stringify(value) ?? String(value);
+  } catch {
+    text = '(a value that could not be shown)';
+  }
+  let head = '';
+  let count = 0;
+  for (const char of text) {
+    if (count === 80) return `${head}…`;
+    head += char;
+    count++;
+  }
+  return head;
+}
+
+/** A list in prose: `a`, `a or b`, `a, b or c`. */
+function oneOf(items: string[]): string {
+  return items.length <= 1 ? items.join('') : `${items.slice(0, -1).join(', ')} or ${items[items.length - 1]}`;
+}
+
+/** A list in prose: `a`, `a and b`, `a, b and c`. */
+function allOf(items: string[]): string {
+  return items.length <= 1 ? items.join('') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
+
+/** At most this many keys a call gave that its schema doesn't declare are named. */
+const UNDECLARED_SHOWN = 5;
+
+/** An own property, so a key such as `constructor` isn't found on the prototype. */
+function own(obj: Record<string, unknown>, key: string): unknown {
+  return Object.hasOwn(obj, key) ? obj[key] : undefined;
+}
+
+/** An object that isn't a list: a map of keys, as `properties` should be. */
+function isMap(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Every root keyword in JSON Schema's drafts 4 to 2020-12, besides
+ *  `properties` and `required`, that can accept, require or name an object's
+ *  keys, except the two read by declaresKeysPlainly (`additionalProperties`
+ *  and `unevaluatedProperties`, which count when `true` or a schema object). The
+ *  reading is cautious: a root with any of them names no key, whatever its
+ *  subschemas hold, since naming a key the schema takes would mislead the
+ *  agent more than a hint left out. So `not` is here too, since a negation
+ *  can require a key (`not: {properties: {y: {type: 'string'}}}` refuses an
+ *  object without a non-string `y`), and so is `if` with or without `then`
+ *  and `else`. `then` and `else` act only beside `if`, and a keyword JSON
+ *  Schema doesn't have declares nothing. */
+const OTHER_KEY_DECLARERS = [
+  'allOf', 'anyOf', 'oneOf', 'not', 'if', '$ref', '$dynamicRef', '$recursiveRef',
+  'dependentSchemas', 'dependencies', 'dependentRequired', 'patternProperties',
+  'propertyNames', 'enum', 'const',
+];
+
+/** Whether a schema's root declares its keys only in `properties` and
+ *  `required`, so that a key in neither isn't one of its parameters. A root
+ *  with any keyword in OTHER_KEY_DECLARERS can declare keys another way. A
+ *  schema object for `additionalProperties` or `unevaluatedProperties`, `{}`
+ *  included, or `true`, which means the same there, says the root takes keys
+ *  `properties` doesn't list, as a map's input does, so a key in neither list
+ *  may be meant. `false` there says it takes none, so it names. Left out,
+ *  the keyword is JSON Schema's default, which says nothing of what the
+ *  author meant, and most schemas leave it out without welcoming other keys,
+ *  so a root without it names them too. */
+function declaresKeysPlainly(schema: Record<string, unknown>): boolean {
+  return !OTHER_KEY_DECLARERS.some((key) => Object.hasOwn(schema, key))
+    && !takesOtherKeys(schema.additionalProperties)
+    && !takesOtherKeys(schema.unevaluatedProperties);
+}
+
+function takesOtherKeys(value: unknown): boolean {
+  return value === true || isMap(value);
+}
+
+/**
+ * What's wrong with a call's input against its tool's declared inputSchema,
+ * checked shallowly: the input is an object, and each root `required` key has
+ * a value. With `values`, also each declared key's value: a type and an enum
+ * value its declaration admits. It isn't a JSON-Schema engine: nested shapes,
+ * unions and references are the handler's to check, as they always were.
+ * Every problem is reported at once, each naming the key, what the schema
+ * wants and what the call gave. An empty list means the call can go to its
+ * handler.
+ *
+ * - An absent input (`undefined` or `null`) gives no arguments: it's refused
+ *   only for the keys the schema requires.
+ * - A required key given as `null` has no value, the same as one left out,
+ *   unless its declaration admits `null` (a type list naming it, or
+ *   `nullable: true`), or has no `type` at all: a key with no `type` takes
+ *   `null` as a value, as it takes any other. One whose `type` the check
+ *   can't read, such as Gemini's `STRING`, or a list naming one, takes
+ *   `null` only where the declaration names it, and its values aren't
+ *   checked against the type. An empty string is a value.
+ * - A schema whose `required` isn't a list requires nothing here, and a key
+ *   it lists twice is reported once.
+ * - Where a required key is missing and the call gave keys the schema
+ *   declares neither in its `properties` nor in its `required` list, those
+ *   are named too, since a key sent under another name is one reason a
+ *   required key goes missing. They're never refused for themselves. A schema
+ *   whose root can declare keys another way names none
+ *   (declaresKeysPlainly).
+ *
+ * A module tool's call is checked without `values`: a handler may take more
+ * than its schema can say on every provider, such as one name where a list
+ * is declared, and refusing that would refuse calls that work. The `utils`
+ * tool checks a utility's values too, as it always has. `field` names what
+ * the input is to the caller ("input" unless given).
+ */
+export function toolArgsProblems(
+  input: unknown,
+  schema: ToolDefinition['inputSchema'] | undefined,
+  options: { values?: boolean; field?: string } = {},
+): string[] {
+  if (!schema) return [];
+  const absent = input === undefined || input === null;
+  if (!absent && (typeof input !== 'object' || Array.isArray(input))) {
+    return [`its ${options.field ?? 'input'} must be an object, and this call gave ${withArticle(kindOf(input))}`];
+  }
+  const obj = (absent ? {} : input) as Record<string, unknown>;
+  const properties = (isMap(schema.properties) ? schema.properties : {}) as Record<string, { type?: unknown; nullable?: unknown; enum?: unknown } | undefined>;
+  const declared = (key: string) => (Object.hasOwn(properties, key) ? properties[key] : undefined);
+  const problems: string[] = [];
+  const missing = new Set<string>();
+  const required: unknown[] = Array.isArray(schema.required) ? schema.required : [];
+  for (const key of required) {
+    if (typeof key !== 'string' || missing.has(key)) continue;
+    const value = own(obj, key);
+    const kinds = admittedKinds(declared(key));
+    if (value !== undefined && (value !== null || takesNull(declared(key)))) continue;
+    missing.add(key);
+    const wanted = kinds.length > 0 ? `"${key}" (${oneOf(kinds.map(withArticle))})` : `"${key}"`;
+    problems.push(`needs ${wanted}, and this call gave ${value === null ? 'null' : 'none'}`);
+  }
+  if (missing.size > 0 && declaresKeysPlainly(schema as Record<string, unknown>)) {
+    const undeclared = Object.keys(obj).filter((key) => !Object.hasOwn(properties, key) && !required.includes(key));
+    if (undeclared.length > 0) {
+      const named = undeclared.slice(0, UNDECLARED_SHOWN).map(shown);
+      if (undeclared.length > UNDECLARED_SHOWN) named.push(`${undeclared.length - UNDECLARED_SHOWN} more`);
+      problems.push(undeclared.length === 1 ? `${named[0]} isn't one of its parameters` : `${allOf(named)} aren't among its parameters`);
+    }
+  }
+  if (!options.values) return problems;
+  for (const [key, value] of Object.entries(obj)) {
+    const param = declared(key);
+    if (!param || value === undefined || missing.has(key)) continue;
+    const kinds = admittedKinds(param);
+    const kind = kindOf(value);
+    const largeInteger = kind === 'string' && kinds.includes('number') && LARGE_INTEGER_TEXT.test(value as string);
+    if (kinds.length > 0 && !kinds.includes(kind) && !largeInteger) {
+      problems.push(`"${key}" must be ${oneOf(kinds.map(withArticle))}, and this call gave ${withArticle(kind)}`);
+      continue;
+    }
+    if (Array.isArray(param.enum) && !param.enum.includes(value)) {
+      problems.push(`"${key}" must be one of ${oneOf(param.enum.map(shown))}, and this call gave ${shown(value)}`);
+    }
+  }
+  return problems;
+}