@axlsdk/axl 0.21.0 → 0.21.1

package/dist/index.js

@@ -171,6 +171,221 @@ var ValidationError = class extends AxlError {
 
 // src/tool.ts
 var DEFAULT_MAX_STRING_LENGTH = 1e4;
+var MAX_MODEL_ARGUMENT_ISSUES = 8;
+var MAX_MODEL_ARGUMENT_MESSAGE_LENGTH = 2e3;
+var MAX_MODEL_ARGUMENT_LINE_LENGTH = 220;
+var MAX_MODEL_ARGUMENT_PATH_LENGTH = 160;
+var MAX_UNION_DEPTH = 3;
+var MAX_UNION_BRANCHES = 4;
+var MAX_LITERAL_ALTERNATIVES = 10;
+var SAFE_SCHEMA_TYPES = /* @__PURE__ */ new Set([
+  "string",
+  "number",
+  "boolean",
+  "null",
+  "array",
+  "object",
+  "integer"
+]);
+var SAFE_STRING_FORMATS = /* @__PURE__ */ new Set([
+  "email",
+  "url",
+  "emoji",
+  "uuid",
+  "guid",
+  "nanoid",
+  "cuid",
+  "cuid2",
+  "ulid",
+  "xid",
+  "ksuid",
+  "datetime",
+  "date",
+  "time",
+  "duration",
+  "ipv4",
+  "ipv6",
+  "cidrv4",
+  "cidrv6",
+  "base64",
+  "base64url",
+  "json_string",
+  "e164",
+  "lowercase",
+  "uppercase",
+  "jwt"
+]);
+function truncateModelFeedback(value, maximum) {
+  return value.length <= maximum ? value : `${value.slice(0, Math.max(0, maximum - 1))}\u2026`;
+}
+var DISPLAY_CONTROL_CHARACTERS = /[\u061C\u200B-\u200F\u202A-\u202E\u2066-\u2069\u2028\u2029]/g;
+function isJsonSchema(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function escapeDisplayControls(value) {
+  return value.replace(
+    DISPLAY_CONTROL_CHARACTERS,
+    (character) => `\\u${character.codePointAt(0).toString(16).padStart(4, "0")}`
+  );
+}
+function quoteModelText(value) {
+  return escapeDisplayControls(JSON.stringify(value));
+}
+function schemaNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? String(value) : void 0;
+}
+function schemaLiteral(value) {
+  if (typeof value === "string") {
+    const rendered = quoteModelText(value);
+    return rendered.length <= 120 ? rendered : '"<literal omitted>"';
+  }
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : void 0;
+  if (typeof value === "boolean") return String(value);
+  if (value === null) return "null";
+  return void 0;
+}
+function schemaType(schema) {
+  const type = schema.type;
+  return typeof type === "string" && SAFE_SCHEMA_TYPES.has(type) ? type : void 0;
+}
+function compositionBranches(schema) {
+  const branches = [];
+  for (const key of ["anyOf", "oneOf", "allOf"]) {
+    const value = schema[key];
+    if (!Array.isArray(value)) continue;
+    for (const branch of value.slice(0, MAX_UNION_BRANCHES)) {
+      if (isJsonSchema(branch)) branches.push(branch);
+    }
+  }
+  return branches;
+}
+function unionBranches(schema) {
+  const branches = [];
+  for (const key of ["anyOf", "oneOf"]) {
+    const value = schema[key];
+    if (!Array.isArray(value)) continue;
+    for (const branch of value.slice(0, MAX_UNION_BRANCHES)) {
+      if (isJsonSchema(branch)) branches.push(branch);
+    }
+  }
+  return branches;
+}
+function resolvePathSegment(schema, segment, depth = 0) {
+  if (depth >= MAX_UNION_DEPTH) return void 0;
+  if (typeof segment === "string") {
+    const properties = schema.properties;
+    if (isJsonSchema(properties) && Object.hasOwn(properties, segment)) {
+      const child = properties[segment];
+      if (isJsonSchema(child)) return { node: child, renderedSegment: segment };
+    }
+    if (isJsonSchema(schema.additionalProperties)) {
+      return { node: schema.additionalProperties, renderedSegment: "<key>" };
+    }
+  } else if (typeof segment === "number" && Number.isSafeInteger(segment) && segment >= 0) {
+    const prefixItems = schema.prefixItems;
+    if (Array.isArray(prefixItems) && isJsonSchema(prefixItems[segment])) {
+      return { node: prefixItems[segment], renderedSegment: String(segment) };
+    }
+    if (isJsonSchema(schema.items)) {
+      return { node: schema.items, renderedSegment: "<index>" };
+    }
+  }
+  for (const branch of compositionBranches(schema)) {
+    const resolved = resolvePathSegment(branch, segment, depth + 1);
+    if (resolved !== void 0) return resolved;
+  }
+  return void 0;
+}
+function resolveSchemaPath(providerVisibleSchema, issuePath) {
+  if (!isJsonSchema(providerVisibleSchema)) return void 0;
+  let node = providerVisibleSchema;
+  const segments = [];
+  for (const segment of issuePath) {
+    const resolved = resolvePathSegment(node, segment);
+    if (resolved === void 0) {
+      segments.push("<path omitted>");
+      return { node, segments };
+    }
+    node = resolved.node;
+    segments.push(resolved.renderedSegment);
+  }
+  return { node, segments };
+}
+function jsonPointerPath(segments) {
+  if (segments.length === 0) return "<root>";
+  const pointer = `/${segments.map((segment) => segment.replaceAll("~", "~0").replaceAll("/", "~1")).join("/")}`;
+  const rendered = quoteModelText(pointer);
+  return rendered.length <= MAX_MODEL_ARGUMENT_PATH_LENGTH ? rendered : '"<path omitted>"';
+}
+function schemaAlternatives(schema, depth = 0) {
+  if (depth >= MAX_UNION_DEPTH) return [];
+  const constant = "const" in schema ? schemaLiteral(schema.const) : void 0;
+  if (constant !== void 0) return [constant];
+  if (Array.isArray(schema.enum)) {
+    const values = schema.enum.slice(0, MAX_LITERAL_ALTERNATIVES).map(schemaLiteral);
+    if (values.every((value) => value !== void 0)) return values;
+  }
+  const type = schemaType(schema);
+  if (type !== void 0) return [type];
+  const alternatives = unionBranches(schema).flatMap(
+    (branch) => schemaAlternatives(branch, depth + 1)
+  );
+  return alternatives.slice(0, MAX_LITERAL_ALTERNATIVES);
+}
+function schemaEnumExpectation(schema) {
+  if ("const" in schema) {
+    const constant = schemaLiteral(schema.const);
+    return constant === void 0 ? void 0 : `expected ${constant}`;
+  }
+  if (!Array.isArray(schema.enum)) return void 0;
+  const values = schema.enum.slice(0, MAX_LITERAL_ALTERNATIVES).map(schemaLiteral);
+  if (values.some((value) => value === void 0)) return void 0;
+  const rendered = values;
+  if (rendered.length === 0) return void 0;
+  const omission = schema.enum.length > rendered.length ? ", \u2026" : "";
+  return `expected ${rendered.length === 1 ? rendered[0] : `one of ${rendered.join(", ")}`}${omission}`;
+}
+function schemaTypeExpectation(schema) {
+  const type = schemaType(schema);
+  if (type !== void 0) return `expected ${type}`;
+  const alternatives = schemaAlternatives(schema);
+  return alternatives.length === 0 ? void 0 : `expected one of: ${alternatives.join(", ")}`;
+}
+function schemaSizeExpectation(schema, direction) {
+  const type = schemaType(schema);
+  const keyword = direction === "small" ? type === "string" ? "minLength" : type === "array" ? "minItems" : "minimum" : type === "string" ? "maxLength" : type === "array" ? "maxItems" : "maximum";
+  const value = schemaNumber(schema[keyword]);
+  if (value === void 0) return void 0;
+  const label = type === "string" ? "string length" : type === "array" ? "array length" : type;
+  if (label === void 0) return void 0;
+  return `expected ${label} ${direction === "small" ? "at least" : "at most"} ${value}`;
+}
+function schemaExpectation(schema, issueCode) {
+  switch (issueCode) {
+    case "invalid_type":
+      return schemaTypeExpectation(schema) ?? "failed structural validation";
+    case "invalid_value":
+      return schemaEnumExpectation(schema) ?? schemaTypeExpectation(schema) ?? "failed structural validation";
+    case "too_small":
+      return schemaSizeExpectation(schema, "small") ?? schemaTypeExpectation(schema) ?? "failed structural validation";
+    case "too_big":
+      return schemaSizeExpectation(schema, "big") ?? schemaTypeExpectation(schema) ?? "failed structural validation";
+    case "not_multiple_of": {
+      const multipleOf = schemaNumber(schema.multipleOf);
+      return multipleOf === void 0 ? schemaTypeExpectation(schema) ?? "failed structural validation" : `expected a multiple of ${multipleOf}`;
+    }
+    case "invalid_format": {
+      const format = schema.format;
+      return typeof format === "string" && SAFE_STRING_FORMATS.has(format) ? `expected valid ${format} format` : schemaTypeExpectation(schema) ?? "failed structural validation";
+    }
+    case "invalid_union":
+      return schemaTypeExpectation(schema) ?? "failed structural validation";
+    default: {
+      const typeExpectation = schemaTypeExpectation(schema);
+      return typeExpectation === void 0 ? "failed structural validation" : `failed structural validation; ${typeExpectation}`;
+    }
+  }
+}
 var ToolStringLengthError = class extends Error {
   constructor(path, actual, maximum) {
     const renderedPath = path.reduce(
@@ -186,6 +401,42 @@ var ToolStringLengthError = class extends Error {
     this.name = "ToolStringLengthError";
   }
 };
+function toolArgumentModelMessage(error, providerVisibleSchema) {
+  try {
+    let lines;
+    let omitted = false;
+    if (error instanceof ZodError) {
+      if (error.issues.length === 0) return void 0;
+      lines = [];
+      for (const issue of error.issues.slice(0, MAX_MODEL_ARGUMENT_ISSUES)) {
+        const resolved = resolveSchemaPath(providerVisibleSchema, issue.path);
+        if (resolved === void 0) return void 0;
+        const path = jsonPointerPath(resolved.segments);
+        const expectation = schemaExpectation(resolved.node, issue.code);
+        lines.push(
+          truncateModelFeedback(`- ${path}: ${expectation}`, MAX_MODEL_ARGUMENT_LINE_LENGTH)
+        );
+      }
+      omitted = error.issues.length > lines.length;
+    } else if (error instanceof ToolStringLengthError) {
+      const resolved = resolveSchemaPath(providerVisibleSchema, error.path);
+      const maximum = schemaNumber(error.maximum);
+      if (resolved === void 0 || maximum === void 0) return void 0;
+      const path = jsonPointerPath(resolved.segments);
+      lines = [`- ${path}: maximum string length is ${maximum}`];
+    } else {
+      return void 0;
+    }
+    const header = "Error: Invalid tool arguments:";
+    const footer = "Correct the arguments and try again.";
+    const omission = omitted ? "Additional validation issues were omitted." : void 0;
+    const parts = [header, ...lines, ...omission ? [omission] : [], footer];
+    const message = parts.join("\n");
+    return message.length <= MAX_MODEL_ARGUMENT_MESSAGE_LENGTH ? message : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function validateStringLengths(value, maxLen, path = []) {
   if (typeof value === "string") {
     if (value.length > maxLen) {
@@ -6330,7 +6581,15 @@ function cloneToolArguments(value) {
   }
 }
 function parseToolInvocation(options) {
-  const { toolCall, configuredTool, override, mcpCall, mcpTraceName, availableTools } = options;
+  const {
+    toolCall,
+    configuredTool,
+    override,
+    mcpCall,
+    mcpTraceName,
+    availableTools,
+    providerVisibleSchema
+  } = options;
   const requestedTool = toolCall.function.name;
   if (!override && !configuredTool && !mcpCall) {
     return {
@@ -6390,7 +6649,7 @@ function parseToolInvocation(options) {
           args: parsedArguments,
           issues: toolArgumentIssues(error)
         },
-        modelMessage: INVALID_ARGUMENTS_MODEL_MESSAGE
+        modelMessage: toolArgumentModelMessage(error, providerVisibleSchema) ?? INVALID_ARGUMENTS_MODEL_MESSAGE
       };
     }
   }
@@ -7293,7 +7552,7 @@ var WorkflowContext = class _WorkflowContext {
   /** Resolve, execute, and observe one non-handoff tool request. Rejections
    * never start. Every accepted request emits one terminal event before a
    * continuation message or abort escapes this coordinator. */
-  async observeToolInvocation(agent2, toolCall, currentMessages, availableTools) {
+  async observeToolInvocation(agent2, toolCall, currentMessages, toolDefs) {
     const signal = this.currentSignal;
     signal?.throwIfAborted();
     const requestedTool = toolCall.function.name;
@@ -7303,6 +7562,7 @@ var WorkflowContext = class _WorkflowContext {
     const override = this.toolOverrides?.get(requestedTool);
     const mcpManager = this.mcpManager;
     const mcpMatch = !configuredTool ? mcpManager?.getToolsForAgent(agent2._config.mcp, agent2._config.mcpTools).find(({ tool: tool2 }) => tool2.name === requestedTool) : void 0;
+    const providerVisibleSchema = toolDefs.find((tool2) => tool2.function.name === requestedTool)?.function.parameters;
     const parsed = parseToolInvocation({
       toolCall,
       configuredTool,
@@ -7311,7 +7571,8 @@ var WorkflowContext = class _WorkflowContext {
         mcpCall: (args) => mcpManager.callTool(requestedTool, args, mcpMatch.server),
         mcpTraceName: `${mcpMatch.server}:${requestedTool}`
       } : {},
-      availableTools
+      availableTools: toolDefs.map((tool2) => tool2.function.name),
+      ...configuredTool ? { providerVisibleSchema } : {}
     });
     signal?.throwIfAborted();
     if ("kind" in parsed) {
@@ -8122,12 +8383,7 @@ ${appendedSchemaText}`;
               return await handoffFn();
             }
           }
-          await this.observeToolInvocation(
-            agent2,
-            toolCall,
-            currentMessages,
-            toolDefs.map((tool2) => tool2.function.name)
-          );
+          await this.observeToolInvocation(agent2, toolCall, currentMessages, toolDefs);
         }
         continue;
       }