@axlsdk/axl 0.20.1 → 0.21.1

package/README.md

@@ -71,6 +71,13 @@ Presets: `openrouter`, `azure`, `xai`, `deepseek`, `mistral`, `groq`, `bedrock`,
 
 Each provider also accepts an opt-in `rateLimit` (`{ maxConcurrent?, minIntervalMs?, acquireTimeoutMs? }`) for proactive client-side pacing on top of the automatic 429/503/529 backoff — useful when a large fan-out (e.g. an eval) shares one API key. It caps in-flight request concurrency (not token throughput) for that provider's chat calls. See [Providers → Rate limiting](../../docs/providers.md#rate-limiting-opt-in).
 
+Built-in providers require HTTPS for remote endpoints and never follow redirects.
+Literal loopback HTTP remains automatic for local inference; Docker service names,
+private-network URLs, and other remote HTTP endpoints require the provider-local
+`dangerouslyAllowInsecureHttp: true` acknowledgement. Keep Axl and proprietary
+system prompts on your trusted backend—see
+[Prompt confidentiality](../../docs/security.md#prompt-confidentiality-and-the-trusted-backend).
+
 State store options: `'memory'` (default), `'sqlite'` (requires `better-sqlite3`), or a `RedisStore` instance for multi-process deployments. See [State Stores](#state-stores).
 
 ### Tools, Agents, and Workflows

package/dist/index.cjs

@@ -380,6 +380,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(
@@ -395,6 +610,42 @@ var ToolStringLengthError = class extends Error {
     this.name = "ToolStringLengthError";
   }
 };
+function toolArgumentModelMessage(error, providerVisibleSchema) {
+  try {
+    let lines;
+    let omitted = false;
+    if (error instanceof import_zod.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) {
@@ -705,7 +956,7 @@ async function fetchWithRetry(input, init, opts) {
     for (let attempt = 0; ; attempt++) {
       let res;
       try {
-        res = await fetch(input, init);
+        res = await fetch(input, { ...init, redirect: "manual" });
       } catch (err) {
         if (isAbortError2(err, init?.signal ?? void 0)) throw err;
         if (attempt >= maxRetries) {
@@ -911,6 +1162,38 @@ function isBuiltinTablePricingEligible(profile, context) {
   return typeof effectiveTier === "string" && policy.supportedServiceTiers.includes(effectiveTier);
 }
 
+// src/http-transport.ts
+function assertSafeProviderBaseUrl(baseUrl, surface, dangerouslyAllowInsecureHttp = false) {
+  assertSafeHttpEndpoint(baseUrl, surface, dangerouslyAllowInsecureHttp, "prompts and credentials");
+}
+function assertSafeHttpEndpoint(endpoint, surface, dangerouslyAllowInsecureHttp = false, exposedData = "sensitive data") {
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    throw unsafeTransportError(surface, "a valid absolute HTTP(S) URL", exposedData);
+  }
+  if (url.protocol === "https:") return;
+  if (url.protocol !== "http:") {
+    throw unsafeTransportError(surface, "an HTTPS URL", exposedData);
+  }
+  if (dangerouslyAllowInsecureHttp || isLiteralLoopbackHost(url.hostname)) return;
+  throw unsafeTransportError(
+    surface,
+    "an HTTPS URL, or set dangerouslyAllowInsecureHttp: true only for a deliberately insecure endpoint",
+    exposedData
+  );
+}
+function isLiteralLoopbackHost(hostname) {
+  return hostname === "localhost" || hostname === "localhost." || /^127(?:\.\d{1,3}){3}$/.test(hostname) || hostname === "[::1]";
+}
+function unsafeTransportError(surface, remediation, exposedData) {
+  return new AxlError(
+    "UNSAFE_TRANSPORT",
+    `${surface} requires ${remediation}. Remote HTTP can expose ${exposedData} in transit.`
+  );
+}
+
 // src/providers/openai-compatible.ts
 function resolvePerModel(value, model, fallback) {
   if (value === void 0) return fallback;
@@ -1054,6 +1337,11 @@ var OpenAICompatibleProvider = class {
     const envBase = p.envBaseUrl ? process.env[p.envBaseUrl] : void 0;
     const explicitBase = options.baseUrl ?? envBase;
     this.baseUrl = (explicitBase ?? p.defaultBaseUrl).replace(/\/$/, "");
+    assertSafeProviderBaseUrl(
+      this.baseUrl,
+      `${p.label ?? p.name} provider`,
+      options.dangerouslyAllowInsecureHttp
+    );
     this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
     const label = p.label ?? p.name;
     if (p.requireExplicitBaseUrl && explicitBase === void 0) {
@@ -1954,6 +2242,11 @@ var OpenAIResponsesProvider = class {
   constructor(options = {}) {
     this.apiKeySource = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
     this.baseUrl = (options.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    assertSafeProviderBaseUrl(
+      this.baseUrl,
+      "OpenAI Responses provider",
+      options.dangerouslyAllowInsecureHttp
+    );
     this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
     if (typeof this.apiKeySource === "string" && !this.apiKeySource) {
       throw new Error("OpenAI API key is required. Set OPENAI_API_KEY or pass apiKey in options.");
@@ -2709,6 +3002,11 @@ var AnthropicProvider = class {
   constructor(options = {}) {
     this.apiKeySource = options.apiKey ?? process.env.ANTHROPIC_API_KEY ?? "";
     this.baseUrl = (options.baseUrl ?? "https://api.anthropic.com/v1").replace(/\/$/, "");
+    assertSafeProviderBaseUrl(
+      this.baseUrl,
+      "Anthropic provider",
+      options.dangerouslyAllowInsecureHttp
+    );
     this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
     if (typeof this.apiKeySource === "string" && !this.apiKeySource) {
       throw new Error(
@@ -3399,6 +3697,11 @@ var GeminiProvider = class {
       /\/$/,
       ""
     );
+    assertSafeProviderBaseUrl(
+      this.baseUrl,
+      "Google provider",
+      options.dangerouslyAllowInsecureHttp
+    );
     this.governor = options.rateLimit ? new RateLimiter(options.rateLimit) : void 0;
     if (typeof this.apiKeySource === "string" && !this.apiKeySource) {
       throw new Error("Google API key is required. Set GOOGLE_API_KEY or pass apiKey in options.");
@@ -4286,6 +4589,7 @@ var builtinFactories = {
     return new OpenAIProvider({
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       rateLimit: opts.rateLimit
     });
   },
@@ -4298,6 +4602,7 @@ var builtinFactories = {
     return new OpenAIResponsesProvider({
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       rateLimit: opts.rateLimit
     });
   },
@@ -4306,6 +4611,7 @@ var builtinFactories = {
     return new AnthropicProvider({
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       rateLimit: opts.rateLimit
     });
   },
@@ -4314,6 +4620,7 @@ var builtinFactories = {
     return new GeminiProvider({
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       rateLimit: opts.rateLimit
     });
   }
@@ -4325,6 +4632,7 @@ function presetFactory(profile) {
       profile,
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       authHeader: opts.authHeader,
       rateLimit: opts.rateLimit
     });
@@ -6482,7 +6790,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 {
@@ -6542,7 +6858,7 @@ function parseToolInvocation(options) {
           args: parsedArguments,
           issues: toolArgumentIssues(error)
         },
-        modelMessage: INVALID_ARGUMENTS_MODEL_MESSAGE
+        modelMessage: toolArgumentModelMessage(error, providerVisibleSchema) ?? INVALID_ARGUMENTS_MODEL_MESSAGE
       };
     }
   }
@@ -7445,7 +7761,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;
@@ -7455,6 +7771,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,
@@ -7463,7 +7780,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) {
@@ -8274,12 +8592,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;
       }
@@ -11335,6 +11648,14 @@ var HttpMcpClient = class {
     this.config = config;
     this.name = config.name;
     this.baseUrl = (config.uri ?? "").replace(/\/$/, "");
+    if (this.baseUrl) {
+      assertSafeHttpEndpoint(
+        this.baseUrl,
+        `MCP server "${this.name}"`,
+        config.dangerouslyAllowInsecureHttp,
+        "tool arguments and results"
+      );
+    }
   }
   name;
   tools = [];
@@ -11364,7 +11685,9 @@ var HttpMcpClient = class {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(request),
-      signal: AbortSignal.timeout(timeoutMs)
+      signal: AbortSignal.timeout(timeoutMs),
+      // Tool calls can be non-idempotent: never forward or retry their body.
+      redirect: "manual"
     });
     if (!res.ok) {
       throw new Error(`MCP HTTP error (${res.status}): ${await res.text()}`);
@@ -14156,6 +14479,11 @@ var OpenAIEmbedder = class {
     }
     this.model = options.model ?? "text-embedding-3-small";
     this.baseUrl = options.baseUrl ?? "https://api.openai.com";
+    assertSafeProviderBaseUrl(
+      this.baseUrl,
+      "OpenAI embedder",
+      options.dangerouslyAllowInsecureHttp
+    );
     this.dimensions = options.dimensions ?? 1536;
   }
   async embed(texts, signal) {