@animalabs/agent-framework 0.27.0 → 0.29.0

package/src/mcpl/tool-signature.ts

@@ -1,15 +1,16 @@
 /**
  * How a dynamic tool reads to a model when it reaches the conversation
  * instead of the tool list (MCPL RFC-014 §8.3): a compact signature, its
- * first sentence the first time a definition is shown, the whole definition
- * on request. Also the host's own argument check against a tool's current
- * definition (RFC-014 §6.1: "the host checks arguments for that instance
- * against it").
+ * first sentence the first time a definition is shown, and on request its
+ * description, input schema and class. Also the host's own argument check
+ * against a tool's current definition (RFC-014 §6.1: "the host checks
+ * arguments for that instance against it").
  *
  * Ported from mcpl-cc-bridge's tool-render.ts and schema-check.ts, the
  * reference host of RFC-014. Dependency-free.
  */
 import { createHash } from 'node:crypto';
+import { nameToTypeBack, quotedValue, suppliedValue } from '../supplied-text.js';
 
 export type JsonSchema = Record<string, unknown>;
 
@@ -24,11 +25,25 @@ export interface HintedTool {
 
 const isObj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 
+/** How deep a server's value may nest and still be written out, the same on every runtime. */
+const DEEPEST = 64;
+
+function nestsWithin(value: unknown, depth = 0): boolean {
+  if (value === null || typeof value !== 'object') return true;
+  return depth <= DEEPEST && Object.values(value).every((v) => nestsWithin(v, depth + 1));
+}
+
+/** A schema's literal value (an enum's, a const or a default) as JSON, or … where it's nested too deeply to write. */
+function literal(value: unknown): string {
+  return nestsWithin(value) ? quotedValue(value) : '…';
+}
+
 function typeSig(schema: JsonSchema | undefined, depth = 0): string {
   if (!schema || typeof schema !== 'object') return 'any';
+  if (depth > 8) return '…';
   if (Array.isArray(schema.enum)) {
     // The enum is often the menu (a decision's options): all of it unless it is long.
-    const vals = (schema.enum as unknown[]).map((v) => JSON.stringify(v));
+    const vals = (schema.enum as unknown[]).map(literal);
     if (vals.length <= 8 || vals.join('|').length <= 400) return vals.join('|');
     let shown = 0;
     let len = 0;
@@ -38,10 +53,12 @@ function typeSig(schema: JsonSchema | undefined, depth = 0): string {
     }
     return `${vals.slice(0, Math.max(shown, 4)).join('|')}|…(${vals.length} in all)`;
   }
-  if (schema.const !== undefined) return JSON.stringify(schema.const);
+  if (schema.const !== undefined) return literal(schema.const);
   const alts = (schema.oneOf ?? schema.anyOf) as JsonSchema[] | undefined;
   if (Array.isArray(alts)) return alts.map((s) => typeSig(s, depth + 1)).join(' | ');
-  const t = Array.isArray(schema.type) ? (schema.type as string[]).join('|') : (schema.type as string | undefined);
+  // Only text names a type: entries that aren't text are left out, and a type with none reads as no type.
+  const types = (Array.isArray(schema.type) ? schema.type : [schema.type]).filter((x): x is string => typeof x === 'string');
+  const t = types.length ? types.join('|') : undefined;
   switch (t) {
     case 'integer':
     case 'number': {
@@ -64,12 +81,12 @@ function typeSig(schema: JsonSchema | undefined, depth = 0): string {
       if (!isObj(props) || Object.keys(props).length === 0) return 'object';
       if (depth >= 3) return '{…}';
       const req = new Set(Array.isArray(schema.required) ? (schema.required as string[]) : []);
-      return `{${Object.entries(props).map(([k, v]) => `${k}${req.has(k) ? '' : '?'}: ${typeSig(v, depth + 1)}`).join(', ')}}`;
+      return `{${Object.entries(props).map(([k, v]) => `${nameToTypeBack(k)}${req.has(k) ? '' : '?'}: ${typeSig(v, depth + 1)}`).join(', ')}}`;
     }
     case undefined:
       return 'any';
     default:
-      return t;
+      return suppliedValue(t);
   }
 }
 
@@ -81,10 +98,10 @@ export function signature(tool: HintedTool): string {
   const props = (isObj(s.properties) ? s.properties : {}) as Record<string, JsonSchema>;
   const req = new Set(Array.isArray(s.required) ? (s.required as string[]) : []);
   const params = Object.entries(props).map(([k, v]) => {
-    const def = isObj(v) && v.default !== undefined ? ` =${JSON.stringify(v.default)}` : '';
-    return `${k}${req.has(k) ? '' : '?'}: ${typeSig(v, 1)}${def}`;
+    const def = isObj(v) && v.default !== undefined ? ` =${literal(v.default)}` : '';
+    return `${nameToTypeBack(k)}${req.has(k) ? '' : '?'}: ${typeSig(v, 1)}${def}`;
   });
-  return `${tool.name}(${params.join(', ')})`;
+  return `${nameToTypeBack(String(tool.name))}(${params.join(', ')})`;
 }
 
 /** An options schema as `{size?: 9|13|19 =9, …}` (a toolset's options). */
@@ -94,22 +111,23 @@ export function objectSignature(schema: unknown): string {
 }
 
 /** First sentence of a description, bounded. */
-export function firstSentence(text: string | undefined, max = 140): string {
-  const t = (text ?? '').trim().replace(/\s+/g, ' ');
+export function firstSentence(text: unknown, max = 140): string {
+  const t = (typeof text === 'string' ? text : '').trim().replace(/\s+/g, ' ');
   // A sentence ends at . ! ? followed by a capital, a bracket, or the end, so "e.g. \"D4\"" does not end it.
   const m = t.match(/^(.+?[.!?])(?=\s+[A-Z([]|$)/);
-  const s = m ? m[1]! : t;
-  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+  const s = [...(m ? m[1]! : t)];
+  return s.length > max ? s.slice(0, max - 1).join('') + '…' : s.join('');
 }
 
-function canonicalJson(value: unknown): string {
+function canonicalJson(value: unknown, depth = 0): string {
   if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (depth > DEEPEST) return '"…"';
+  if (Array.isArray(value)) return `[${value.map((v) => canonicalJson(v, depth + 1)).join(',')}]`;
   const obj = value as Record<string, unknown>;
   return `{${Object.keys(obj)
     .sort()
     .filter((k) => obj[k] !== undefined)
-    .map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`)
+    .map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k], depth + 1)}`)
     .join(',')}}`;
 }
 
@@ -121,31 +139,45 @@ export function toolDigest(tool: HintedTool): string {
     .slice(0, 22);
 }
 
+/** The definitions a model has been shown, by digest: has and add are all rendering needs. */
+export type Shown = { has(digest: string): boolean; add(digest: string): void };
+
 /**
  * Tool lines as the model reads them. A definition the model has been shown
  * gets its signature only; a new or changed one also gets its first
  * sentence. `shown` is updated.
  */
-export function renderToolLines(tools: HintedTool[], shown: Set<string>, opts: { describeAll?: boolean; indent?: string } = {}): string[] {
+export function renderToolLines(tools: HintedTool[], shown: Shown, opts: { describeAll?: boolean; indent?: string } = {}): string[] {
   const indent = opts.indent ?? '  ';
   return tools.map((t) => {
     const d = toolDigest(t);
     const describe = opts.describeAll || !shown.has(d);
     shown.add(d);
     const sentence = describe ? firstSentence(t.description) : '';
-    return `${indent}${signature(t)}${sentence ? ` — ${sentence}` : ''}`;
+    return `${indent}${signature(t)}${sentence ? ` — ${suppliedValue(sentence)}` : ''}`;
   });
 }
 
-/** The whole definition, for `look` naming a tool. */
+/** A server's value as JSON, or a note where it's nested too deeply, or too long, to show. */
+export function jsonText(value: unknown, space?: number): string {
+  if (!nestsWithin(value)) return '(nested too deeply to show)';
+  try {
+    return JSON.stringify(value) === undefined ? '' : quotedValue(value, space);
+  } catch {
+    return '(too long to show)';
+  }
+}
+
+/** A tool's signature, description, class and input schema, for `look` naming a tool. */
 export function renderToolDefinition(tool: HintedTool): string {
   const cls = tool._meta?.['mcpl/class'];
+  const classes = Array.isArray(cls) ? cls.filter((c): c is string => typeof c === 'string') : [];
   return [
     signature(tool),
-    tool.description ?? '',
-    ...(Array.isArray(cls) ? [`class: ${cls.join(', ')}`] : []),
+    typeof tool.description === 'string' ? suppliedValue(tool.description) : '',
+    ...(classes.length ? [`class: ${classes.map(suppliedValue).join(', ')}`] : []),
     'inputSchema:',
-    JSON.stringify(tool.inputSchema ?? {}, null, 2),
+    jsonText(tool.inputSchema ?? {}, 2),
   ]
     .filter((l) => l !== '')
     .join('\n');
@@ -221,15 +253,15 @@ function check(schema: unknown, value: unknown, at: string, depth: number, budge
   const s = schema;
   if (s.type !== undefined) {
     const types = Array.isArray(s.type) ? (s.type as string[]) : [s.type as string];
-    if (!types.some((t) => typeOk(t, value))) return `${at}: must be ${types.join(' or ')}`;
+    if (!types.some((t) => typeOk(t, value))) return `${at}: must be ${types.map(suppliedValue).join(' or ')}`;
   }
   if (Array.isArray(s.enum) || s.const !== undefined) {
     const own = canonicalJson(value);
     if (Array.isArray(s.enum)) {
       spend(budget, s.enum.length);
-      if (!s.enum.some((e) => canonicalJson(e) === own)) return `${at}: must be one of ${s.enum.map((e) => JSON.stringify(e)).join('|')}`;
+      if (!s.enum.some((e) => canonicalJson(e) === own)) return `${at}: must be one of ${s.enum.map((e) => quotedValue(e)).join('|')}`;
     }
-    if (s.const !== undefined && canonicalJson(s.const) !== own) return `${at}: must be ${JSON.stringify(s.const)}`;
+    if (s.const !== undefined && canonicalJson(s.const) !== own) return `${at}: must be ${quotedValue(s.const)}`;
   }
   if (typeof value === 'string') {
     const n = [...value].length;
@@ -255,16 +287,16 @@ function check(schema: unknown, value: unknown, at: string, depth: number, budge
   if (isObj(value)) {
     const props = isObj(s.properties) ? s.properties : {};
     for (const r of Array.isArray(s.required) ? (s.required as unknown[]) : []) {
-      if (typeof r === 'string' && !Object.hasOwn(value, r)) return `${at}.${r}: required`;
+      if (typeof r === 'string' && !Object.hasOwn(value, r)) return `${at}.${nameToTypeBack(r)}: required`;
     }
     for (const [k, v] of Object.entries(value)) {
       if (Object.hasOwn(props, k)) {
-        const e = check(props[k], v, `${at}.${k}`, depth + 1, budget);
+        const e = check(props[k], v, `${at}.${nameToTypeBack(k)}`, depth + 1, budget);
         if (e) return e;
       } else if (s.additionalProperties === false) {
-        return `${at}.${k}: not an argument of this tool`;
+        return `${at}.${nameToTypeBack(k)}: not an argument of this tool`;
       } else if (isObj(s.additionalProperties)) {
-        const e = check(s.additionalProperties, v, `${at}.${k}`, depth + 1, budget);
+        const e = check(s.additionalProperties, v, `${at}.${nameToTypeBack(k)}`, depth + 1, budget);
         if (e) return e;
       }
     }