@axlsdk/axl 0.20.1 → 0.21.0

package/dist/index.d.cts

@@ -2127,6 +2127,8 @@ type OpenAICompatibleOptions = {
     /** API key or a per-request resolver (expiring tokens). See {@link ApiKeySource}. */
     apiKey?: ApiKeySource;
     baseUrl?: string;
+    /** Permit a non-loopback HTTP endpoint for this provider instance. */
+    dangerouslyAllowInsecureHttp?: boolean;
     /** Override the profile's auth header shape (e.g. Azure Entra bearer tokens). */
     authHeader?: AuthHeader;
     rateLimit?: RateLimitConfig;
@@ -2223,6 +2225,49 @@ type OpenAIModelResponse = {
     usage?: OpenAIUsage;
 };
 
+/**
+ * MCP (Model Context Protocol) types for tool discovery and execution.
+ */
+/** A tool definition discovered from an MCP server. */
+type McpToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+};
+/** Configuration for connecting to an MCP server. */
+type McpServerConfig = {
+    name: string;
+    /** Command to spawn for stdio transport (e.g. "npx -y @modelcontextprotocol/server-fs") */
+    command?: string;
+    /** Arguments for the command */
+    args?: string[];
+    /** HTTP/SSE endpoint URI for HTTP transport */
+    uri?: string;
+    /** Allow this MCP server to use non-loopback HTTP. Prefer HTTPS. */
+    dangerouslyAllowInsecureHttp?: boolean;
+    /** Environment variables to pass to the spawned process */
+    env?: Record<string, string>;
+};
+/** Result from calling an MCP tool. */
+type McpToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    }>;
+    isError?: boolean;
+};
+/** A connected MCP server with its discovered tools. */
+type McpServer = {
+    name: string;
+    tools: McpToolDefinition[];
+    callTool(toolName: string, args: unknown): Promise<McpToolResult>;
+    close(): Promise<void>;
+};
+
 /** A pending human decision awaiting resolution. */
 type PendingDecision = {
     executionId: string;
@@ -2470,6 +2515,11 @@ type ProviderConfig = {
      *  the common case. See {@link ApiKeySource}. */
     apiKey?: ApiKeySource;
     baseUrl?: string;
+    /**
+     * Allow a non-loopback HTTP endpoint for this provider. HTTP can expose
+     * prompts and credentials in transit; prefer HTTPS whenever possible.
+     */
+    dangerouslyAllowInsecureHttp?: boolean;
     /** OpenAI-compatible presets only: override the profile auth header shape. */
     authHeader?: AuthHeader;
     /**
@@ -2482,13 +2532,6 @@ type ProviderConfig = {
      */
     rateLimit?: RateLimitConfig;
 };
-/** MCP server configuration */
-type McpServerConfig$1 = {
-    name: string;
-    command?: string;
-    uri?: string;
-    env?: Record<string, string>;
-};
 /** Trace configuration */
 type TraceConfig = {
     enabled?: boolean;
@@ -2600,7 +2643,7 @@ type AxlConfig = {
     defaultProvider?: string;
     defaultModel?: string;
     mcp?: {
-        servers?: McpServerConfig$1[];
+        servers?: McpServerConfig[];
     };
     state?: StateConfig;
     trace?: TraceConfig;
@@ -2693,47 +2736,6 @@ declare class ProviderRegistry {
     clearFactories(): void;
 }
 
-/**
- * MCP (Model Context Protocol) types for tool discovery and execution.
- */
-/** A tool definition discovered from an MCP server. */
-type McpToolDefinition = {
-    name: string;
-    description: string;
-    inputSchema: unknown;
-};
-/** Configuration for connecting to an MCP server. */
-type McpServerConfig = {
-    name: string;
-    /** Command to spawn for stdio transport (e.g. "npx -y @modelcontextprotocol/server-fs") */
-    command?: string;
-    /** Arguments for the command */
-    args?: string[];
-    /** HTTP/SSE endpoint URI for HTTP transport */
-    uri?: string;
-    /** Environment variables to pass to the spawned process */
-    env?: Record<string, string>;
-};
-/** Result from calling an MCP tool. */
-type McpToolResult = {
-    content: Array<{
-        type: 'text';
-        text: string;
-    } | {
-        type: 'image';
-        data: string;
-        mimeType: string;
-    }>;
-    isError?: boolean;
-};
-/** A connected MCP server with its discovered tools. */
-type McpServer = {
-    name: string;
-    tools: McpToolDefinition[];
-    callTool(toolName: string, args: unknown): Promise<McpToolResult>;
-    close(): Promise<void>;
-};
-
 /**
  * Manages connections to multiple MCP servers.
  * Discovers tools, filters by agent config, and routes tool calls.
@@ -4434,7 +4436,14 @@ declare function registerConditions(conditions: string[]): Promise<void>;
  *    attempt-N text never leaks into attempt-N+1).
  *  - `ask_end` clears the per-ask accumulator (memory hygiene).
  *
- * Example (browser, consuming Studio's WS firehose):
+ * SECURITY: "browser-safe" here means this module has no Node runtime
+ * dependency. It does not redact or authorize the raw `AxlEvent` source.
+ * Prompts, system messages, tool data, and traces should remain on the trusted
+ * backend; public applications should relay an output-only DTO produced from a
+ * server-side curated view. Use this helper only when the browser is authorized
+ * to receive the underlying event stream.
+ *
+ * Example (trusted operator browser, consuming an authorized Studio WS firehose):
  *
  * ```ts
  * import { stringStreamFromEvents } from '@axlsdk/axl';
@@ -4813,6 +4822,7 @@ declare class OpenAIProvider extends OpenAICompatibleProvider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     protected computeCost(model: string, usage: ProviderResponse['usage'], _reportedCost: number | undefined, context?: DirectOpenAIPricingContext): number | undefined;
@@ -4835,6 +4845,7 @@ declare class OpenAIResponsesProvider implements Provider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     /** Resolve the API key for one request (supports an expiring-token callback). */
@@ -4885,6 +4896,7 @@ declare class AnthropicProvider implements Provider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     /** Resolve the API key for one request (supports an expiring-token callback). */
@@ -4956,6 +4968,7 @@ declare class GeminiProvider implements Provider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     /** Resolve the API key for one request (supports an expiring-token callback). */
@@ -5509,6 +5522,7 @@ declare class OpenAIEmbedder implements Embedder {
         apiKey?: string;
         model?: string;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         dimensions?: number;
     });
     embed(texts: string[], signal?: AbortSignal): Promise<EmbedResult>;

package/dist/index.d.ts

@@ -2127,6 +2127,8 @@ type OpenAICompatibleOptions = {
     /** API key or a per-request resolver (expiring tokens). See {@link ApiKeySource}. */
     apiKey?: ApiKeySource;
     baseUrl?: string;
+    /** Permit a non-loopback HTTP endpoint for this provider instance. */
+    dangerouslyAllowInsecureHttp?: boolean;
     /** Override the profile's auth header shape (e.g. Azure Entra bearer tokens). */
     authHeader?: AuthHeader;
     rateLimit?: RateLimitConfig;
@@ -2223,6 +2225,49 @@ type OpenAIModelResponse = {
     usage?: OpenAIUsage;
 };
 
+/**
+ * MCP (Model Context Protocol) types for tool discovery and execution.
+ */
+/** A tool definition discovered from an MCP server. */
+type McpToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+};
+/** Configuration for connecting to an MCP server. */
+type McpServerConfig = {
+    name: string;
+    /** Command to spawn for stdio transport (e.g. "npx -y @modelcontextprotocol/server-fs") */
+    command?: string;
+    /** Arguments for the command */
+    args?: string[];
+    /** HTTP/SSE endpoint URI for HTTP transport */
+    uri?: string;
+    /** Allow this MCP server to use non-loopback HTTP. Prefer HTTPS. */
+    dangerouslyAllowInsecureHttp?: boolean;
+    /** Environment variables to pass to the spawned process */
+    env?: Record<string, string>;
+};
+/** Result from calling an MCP tool. */
+type McpToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+    }>;
+    isError?: boolean;
+};
+/** A connected MCP server with its discovered tools. */
+type McpServer = {
+    name: string;
+    tools: McpToolDefinition[];
+    callTool(toolName: string, args: unknown): Promise<McpToolResult>;
+    close(): Promise<void>;
+};
+
 /** A pending human decision awaiting resolution. */
 type PendingDecision = {
     executionId: string;
@@ -2470,6 +2515,11 @@ type ProviderConfig = {
      *  the common case. See {@link ApiKeySource}. */
     apiKey?: ApiKeySource;
     baseUrl?: string;
+    /**
+     * Allow a non-loopback HTTP endpoint for this provider. HTTP can expose
+     * prompts and credentials in transit; prefer HTTPS whenever possible.
+     */
+    dangerouslyAllowInsecureHttp?: boolean;
     /** OpenAI-compatible presets only: override the profile auth header shape. */
     authHeader?: AuthHeader;
     /**
@@ -2482,13 +2532,6 @@ type ProviderConfig = {
      */
     rateLimit?: RateLimitConfig;
 };
-/** MCP server configuration */
-type McpServerConfig$1 = {
-    name: string;
-    command?: string;
-    uri?: string;
-    env?: Record<string, string>;
-};
 /** Trace configuration */
 type TraceConfig = {
     enabled?: boolean;
@@ -2600,7 +2643,7 @@ type AxlConfig = {
     defaultProvider?: string;
     defaultModel?: string;
     mcp?: {
-        servers?: McpServerConfig$1[];
+        servers?: McpServerConfig[];
     };
     state?: StateConfig;
     trace?: TraceConfig;
@@ -2693,47 +2736,6 @@ declare class ProviderRegistry {
     clearFactories(): void;
 }
 
-/**
- * MCP (Model Context Protocol) types for tool discovery and execution.
- */
-/** A tool definition discovered from an MCP server. */
-type McpToolDefinition = {
-    name: string;
-    description: string;
-    inputSchema: unknown;
-};
-/** Configuration for connecting to an MCP server. */
-type McpServerConfig = {
-    name: string;
-    /** Command to spawn for stdio transport (e.g. "npx -y @modelcontextprotocol/server-fs") */
-    command?: string;
-    /** Arguments for the command */
-    args?: string[];
-    /** HTTP/SSE endpoint URI for HTTP transport */
-    uri?: string;
-    /** Environment variables to pass to the spawned process */
-    env?: Record<string, string>;
-};
-/** Result from calling an MCP tool. */
-type McpToolResult = {
-    content: Array<{
-        type: 'text';
-        text: string;
-    } | {
-        type: 'image';
-        data: string;
-        mimeType: string;
-    }>;
-    isError?: boolean;
-};
-/** A connected MCP server with its discovered tools. */
-type McpServer = {
-    name: string;
-    tools: McpToolDefinition[];
-    callTool(toolName: string, args: unknown): Promise<McpToolResult>;
-    close(): Promise<void>;
-};
-
 /**
  * Manages connections to multiple MCP servers.
  * Discovers tools, filters by agent config, and routes tool calls.
@@ -4434,7 +4436,14 @@ declare function registerConditions(conditions: string[]): Promise<void>;
  *    attempt-N text never leaks into attempt-N+1).
  *  - `ask_end` clears the per-ask accumulator (memory hygiene).
  *
- * Example (browser, consuming Studio's WS firehose):
+ * SECURITY: "browser-safe" here means this module has no Node runtime
+ * dependency. It does not redact or authorize the raw `AxlEvent` source.
+ * Prompts, system messages, tool data, and traces should remain on the trusted
+ * backend; public applications should relay an output-only DTO produced from a
+ * server-side curated view. Use this helper only when the browser is authorized
+ * to receive the underlying event stream.
+ *
+ * Example (trusted operator browser, consuming an authorized Studio WS firehose):
  *
  * ```ts
  * import { stringStreamFromEvents } from '@axlsdk/axl';
@@ -4813,6 +4822,7 @@ declare class OpenAIProvider extends OpenAICompatibleProvider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     protected computeCost(model: string, usage: ProviderResponse['usage'], _reportedCost: number | undefined, context?: DirectOpenAIPricingContext): number | undefined;
@@ -4835,6 +4845,7 @@ declare class OpenAIResponsesProvider implements Provider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     /** Resolve the API key for one request (supports an expiring-token callback). */
@@ -4885,6 +4896,7 @@ declare class AnthropicProvider implements Provider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     /** Resolve the API key for one request (supports an expiring-token callback). */
@@ -4956,6 +4968,7 @@ declare class GeminiProvider implements Provider {
     constructor(options?: {
         apiKey?: ApiKeySource;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         rateLimit?: RateLimitConfig;
     });
     /** Resolve the API key for one request (supports an expiring-token callback). */
@@ -5509,6 +5522,7 @@ declare class OpenAIEmbedder implements Embedder {
         apiKey?: string;
         model?: string;
         baseUrl?: string;
+        dangerouslyAllowInsecureHttp?: boolean;
         dimensions?: number;
     });
     embed(texts: string[], signal?: AbortSignal): Promise<EmbedResult>;

package/dist/index.js

@@ -496,7 +496,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) {
@@ -702,6 +702,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;
@@ -845,6 +877,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) {
@@ -1745,6 +1782,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.");
@@ -2500,6 +2542,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(
@@ -3190,6 +3237,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.");
@@ -4077,6 +4129,7 @@ var builtinFactories = {
     return new OpenAIProvider({
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       rateLimit: opts.rateLimit
     });
   },
@@ -4089,6 +4142,7 @@ var builtinFactories = {
     return new OpenAIResponsesProvider({
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       rateLimit: opts.rateLimit
     });
   },
@@ -4097,6 +4151,7 @@ var builtinFactories = {
     return new AnthropicProvider({
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       rateLimit: opts.rateLimit
     });
   },
@@ -4105,6 +4160,7 @@ var builtinFactories = {
     return new GeminiProvider({
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       rateLimit: opts.rateLimit
     });
   }
@@ -4116,6 +4172,7 @@ function presetFactory(profile) {
       profile,
       apiKey: opts.apiKey,
       baseUrl: opts.baseUrl,
+      dangerouslyAllowInsecureHttp: opts.dangerouslyAllowInsecureHttp,
       authHeader: opts.authHeader,
       rateLimit: opts.rateLimit
     });
@@ -11126,6 +11183,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 = [];
@@ -11155,7 +11220,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()}`);
@@ -13947,6 +14014,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) {