@zuora/agent-toolkit 0.0.1-alpha.0 → 0.1.0-alpha.1

package/dist/openai-agents/index.d.ts

@@ -1,7 +1,7 @@
 import { tool } from '@openai/agents';
 import { ToolkitCore } from '../shared/toolkit-core.js';
-import { Z as ZuoraToolDefinition, a as ZuoraAgentToolkitConfigInput, T as ToolSelection } from '../async-jobs-Dd8Jafv0.js';
-import { Z as ZuoraOpenAIAgentToolkit } from '../toolkit-CafRZuAV.js';
+import { b as ZuoraToolExecutionResult, Z as ZuoraToolDefinition, a as ZuoraAgentToolkitConfigInput, T as ToolSelection } from '../async-jobs-DJ_GygII.js';
+import { Z as ZuoraOpenAIAgentToolkit } from '../toolkit-Bjw46goJ.js';
 import 'openai/resources/chat/completions';
 
 /** Native tool type returned by `tool()` from `@openai/agents`. */
@@ -22,6 +22,35 @@ type AgentsFunctionTool = ReturnType<typeof tool>;
  * automatically inside `convertTools()` — callers do not need to know about it.
  */
 declare class ZuoraOpenAIAgentsToolkit extends ToolkitCore<AgentsFunctionTool> {
+    /** Maps sanitized adapter tool names back to their original ZuoraToolDefinition. */
+    private sanitizedToolMap;
+    /**
+     * Look up a ZuoraToolDefinition by its sanitized adapter tool name.
+     *
+     * The OpenAI Agents SDK registers tools with sanitized names (see convertTools),
+     * but external code may reference tools by their original MCP names. This method
+     * provides resolution in both directions.
+     */
+    private resolveToolName;
+    /**
+     * Resolve a tool name that may be either sanitized or original MCP format.
+     *
+     * This provides additional name normalization to handle cases where:
+     * - A tool name contains unsanitized characters (like dots)
+     * - A tool name was learned from descriptions or logs
+     *
+     * We attempt to find a match with relaxed sanitization rules before giving up.
+     */
+    private normalizeToolName;
+    /**
+     * Override callTool to provide flexible name resolution.
+     *
+     * The OpenAI Agents SDK may receive tool calls with names that were learned
+     * from descriptions or other sources (not directly from tool registration).
+     * This override allows us to handle both sanitized and original tool names
+     * by falling back to name normalization when the direct lookup fails.
+     */
+    callTool(operationName: string, input: Record<string, unknown>): Promise<ZuoraToolExecutionResult>;
     /**
      * Serialises the agent tool response, emits an `agent.tool.response`
      * observability event (with the response in `metadata` when
@@ -42,7 +71,7 @@ declare class ZuoraOpenAIAgentsToolkit extends ToolkitCore<AgentsFunctionTool> {
  * import { createZuoraOpenAIAgentsToolkit } from "@zuora/agent-toolkit/openai-agents";
  *
  * const toolkit = await createZuoraOpenAIAgentsToolkit({ env: true });
- * const tools  = await toolkit.getTools({ bundles: ["query"], mode: "readOnly" });
+ * const tools  = await toolkit.getTools({ bundles: ["query"], mode: SafetyMode.ReadOnly });
  * const agent  = new Agent({ name: "Cli Agent", tools });
  * const result = await run(agent, "How many active accounts?");
  * ```

package/dist/openai-agents/index.js

@@ -22,6 +22,10 @@ var ZuoraAgentToolkitError = class extends Error {
 };
 
 // src/shared/types.ts
+var SafetyMode = {
+  ReadOnly: "readOnly",
+  WriteEnabled: "writeEnabled"
+};
 var ApprovalPolicyPreset = {
   Off: "off",
   AllWrites: "all_writes",
@@ -117,15 +121,15 @@ var evaluatePreset = (preset, request) => {
   const isProduction = environment === "production";
   switch (preset) {
     case ApprovalPolicyPreset.Off:
-      return "not_required";
+      return "allow";
     case ApprovalPolicyPreset.AllWrites:
-      return isWrite ? "deny" : "not_required";
+      return isWrite ? "deny" : "allow";
     case ApprovalPolicyPreset.HighRisk:
-      return isHighRisk ? "deny" : "not_required";
+      return isHighRisk ? "deny" : "allow";
     case ApprovalPolicyPreset.ProductionWrites:
-      return isProduction && isWrite ? "deny" : "not_required";
+      return isProduction && isWrite ? "deny" : "allow";
     case ApprovalPolicyPreset.ProductionHighRisk:
-      return isProduction && isHighRisk ? "deny" : "not_required";
+      return isProduction && isHighRisk ? "deny" : "allow";
   }
 };
 var throwApprovalRejected = (tool2) => {
@@ -2600,26 +2604,11 @@ var readEnvAllowedHosts = () => {
   const hosts = raw.split(",").map((host) => host.trim()).filter(Boolean);
   return hosts.length > 0 ? hosts : void 0;
 };
-var isQueryBundleConfigured = (configuration) => {
-  const bundles = configuration?.bundles;
-  if (!bundles) {
-    return false;
-  }
-  const query = bundles.query;
-  if (query === true) {
-    return true;
-  }
-  return typeof query === "object" && query !== null;
-};
 var resolveNativeFileToolsInput = (config) => {
   const explicit = config.nativeFileTools;
   if (explicit?.enabled === false) {
     return { enabled: false };
   }
-  const autoEnable = isQueryBundleConfigured(config.configuration);
-  if (!autoEnable && explicit?.enabled !== true) {
-    return explicit;
-  }
   const rootDir = nonEmptyString(explicit?.rootDir) ?? nonEmptyString(process.env["ZUORA_NATIVE_FILE_ROOT"]) ?? DEFAULT_NATIVE_ARTIFACT_ROOT;
   const allowedHosts = explicit?.allowedHosts ?? readEnvAllowedHosts() ?? DEFAULT_NATIVE_ALLOWED_HOSTS;
   return {
@@ -3490,21 +3479,10 @@ var OAuthTokenProvider = class {
         category: "auth"
       });
     }
-    if (this.config.auth.type === "accessToken" && this.config.auth.accessToken) {
-      this.accessToken = this.config.auth.accessToken;
-      return this.config.auth.accessToken;
-    }
     const now = Date.now();
     if (this.accessToken && this.isAccessTokenFresh(now)) {
       return this.accessToken;
     }
-    if (this.config.auth.type !== "oauthClientCredentials") {
-      throw new ZuoraAgentToolkitError({
-        code: "UNSUPPORTED_AUTH",
-        message: "Unsupported auth configuration for Zuora HTTP MCP client.",
-        category: "auth"
-      });
-    }
     const token = await this.fetchOAuthToken();
     this.accessToken = token.access_token;
     this.tokenIssuedAt = now;
@@ -3523,10 +3501,8 @@ var OAuthTokenProvider = class {
   sensitiveValues() {
     const values = [this.accessToken];
     const auth = this.config.auth;
-    if (auth?.type === "oauthClientCredentials") {
+    if (auth?.clientSecret) {
       values.push(auth.clientSecret);
-    } else if (auth?.type === "accessToken") {
-      values.push(auth.accessToken);
     }
     return values.filter(
       (value) => typeof value === "string" && value.length > 0
@@ -3590,11 +3566,8 @@ var OAuthTokenProvider = class {
     });
   }
   async resolveTokenEndpoints() {
-    if (this.config.tokenEndpoint) {
-      return [this.config.tokenEndpoint];
-    }
     const restEndpoint = `${this.restBaseUrl}/oauth/token`;
-    const oneIdEndpoint = await this.resolveOneIdTokenEndpoint();
+    const oneIdEndpoint = isStagingZuoraBaseUrl(this.restBaseUrl) ? "https://one.stg.na.zuora.com/oauth2/token" : "https://one.zuora.com/oauth2/token";
     const endpoints = [restEndpoint, oneIdEndpoint];
     const uniqueEndpoints = [...new Set(endpoints)];
     if (!this.preferredTokenEndpoint) {
@@ -3607,29 +3580,8 @@ var OAuthTokenProvider = class {
       )
     ];
   }
-  async resolveOneIdTokenEndpoint() {
-    const fallback = isStagingZuoraBaseUrl(this.restBaseUrl) ? "https://one.stg.na.zuora.com/oauth2/token" : "https://one.zuora.com/oauth2/token";
-    try {
-      return await this.discoverTokenEndpoint() ?? fallback;
-    } catch {
-      return fallback;
-    }
-  }
-  async discoverTokenEndpoint() {
-    const metadataUrl = new URL(this.restBaseUrl);
-    metadataUrl.pathname = "/.well-known/oauth-authorization-server";
-    metadataUrl.search = "";
-    const response = await fetch(metadataUrl, {
-      headers: { accept: "application/json" }
-    });
-    if (!response.ok) {
-      return void 0;
-    }
-    const metadata = await response.json().catch(() => ({}));
-    return metadata.token_endpoint;
-  }
   async requestOAuthToken(tokenEndpoint) {
-    if (!this.config.auth || this.config.auth.type !== "oauthClientCredentials") {
+    if (!this.config.auth) {
       throw new ZuoraAgentToolkitError({
         code: "UNSUPPORTED_AUTH",
         message: "Unsupported auth configuration for Zuora HTTP MCP client.",
@@ -3642,17 +3594,8 @@ var OAuthTokenProvider = class {
       accept: "application/json"
     };
     const auth = this.config.auth;
-    if (this.config.tokenAuthMethod === "client_secret_basic") {
-      headers.authorization = `Basic ${base64Encode(
-        `${auth.clientId}:${auth.clientSecret}`
-      )}`;
-    } else {
-      body.set("client_id", auth.clientId);
-      body.set("client_secret", auth.clientSecret);
-    }
-    if (auth.scope) {
-      body.set("scope", auth.scope);
-    }
+    body.set("client_id", auth.clientId);
+    body.set("client_secret", auth.clientSecret);
     const response = await fetch(tokenEndpoint, {
       method: "POST",
       headers,
@@ -3694,7 +3637,6 @@ var extractTenantId = (scope) => {
   const tenantMatch = scope?.match(/tenant\.(\d+)/);
   return tenantMatch?.[1];
 };
-var base64Encode = (value) => Buffer.from(value).toString("base64");
 
 // src/shared/transport/request-headers.ts
 var RESERVED_HEADER_NAMES = /* @__PURE__ */ new Set([
@@ -3766,10 +3708,8 @@ var resolveZuoraConnectionConfig = (config, mcpUrl) => ({
   clientName: config.clientName ?? "zuora-agent-toolkit",
   clientVersion: config.clientVersion ?? "0.1.0",
   protocolVersion: config.protocolVersion ?? "2025-03-26",
-  tokenAuthMethod: config.tokenAuthMethod ?? "client_secret_post",
   url: mcpUrl,
   ...config.auth ? { auth: config.auth } : {},
-  ...config.tokenEndpoint ? { tokenEndpoint: config.tokenEndpoint } : {},
   ...config.headers ? { headers: config.headers } : {},
   ...config.tenantAuth ? { tenantAuth: config.tenantAuth } : {},
   ...config.entityIds ? { entityIds: config.entityIds } : {},
@@ -3950,7 +3890,7 @@ var resolveToolSelectionPolicy = (configuration, selection) => ({
     ...selection?.exclude ?? []
   ])
 });
-var resolveToolMode = (configuration, selection) => selection?.mode ?? configuration?.mode ?? "readOnly";
+var resolveToolMode = (configuration, selection) => selection?.mode ?? configuration?.mode ?? SafetyMode.ReadOnly;
 var resolveExcludedToolNames = (configuration) => /* @__PURE__ */ new Set([
   ...resolveConfiguredExcludedToolNames(configuration),
   ...resolveBundleExcludedToolNames(configuration)
@@ -4212,11 +4152,19 @@ var ZuoraHttpMcpClient = class _ZuoraHttpMcpClient extends ZuoraClient {
 
 // src/shared/toolkit-core.ts
 var createHttpMcpClientConfig = (config) => {
-  if (isTenantAuthConnection(config.connection)) {
+  const contextEntityIds = config.configuration?.context?.entityIds;
+  const contextOrgIds = config.configuration?.context?.orgIds;
+  const contextOverrides = {
+    ...contextEntityIds ? { entityIds: contextEntityIds } : {},
+    ...contextOrgIds ? { orgIds: contextOrgIds } : {}
+  };
+  const connection = "connection" in config ? config.connection : void 0;
+  if (isTenantAuthConnection(connection)) {
     return {
       url: config.baseUrl,
       ...config.auth ? { auth: config.auth } : {},
-      ...config.connection
+      ...connection,
+      ...contextOverrides
     };
   }
   if (!config.auth) {
@@ -4229,13 +4177,23 @@ var createHttpMcpClientConfig = (config) => {
   return {
     url: config.baseUrl,
     auth: config.auth,
-    ...config.connection
+    ...connection ?? {},
+    ...contextOverrides
   };
 };
 var isTenantAuthConnection = (connection) => connection?.tenantAuth?.enabled === true;
 var filterCatalogTools = (tools, policy) => tools.filter((tool2) => {
-  if (policy.mode === "readOnly" && tool2.meta.access === "write") {
-    return false;
+  if (policy.mode === SafetyMode.ReadOnly) {
+    if (tool2.meta.operationAccess) {
+      const hasReadOperation = Object.values(tool2.meta.operationAccess).some(
+        (access) => access === "read"
+      );
+      if (!hasReadOperation) {
+        return false;
+      }
+    } else if (tool2.meta.access === "write") {
+      return false;
+    }
   }
   if (policy.bundles.size > 0 && !policy.bundles.has(tool2.meta.bundle)) {
     return false;
@@ -4396,19 +4354,19 @@ var ToolkitCore = class {
         category: "configuration"
       });
     }
-    const mode = this.config.configuration?.mode ?? "readOnly";
-    if (mode === "readOnly" && tool2.meta.access === "write") {
-      throw new ZuoraAgentToolkitError({
-        code: "TOOL_EXECUTION_ERROR",
-        message: `Write tool "${operationName}" is disabled in readOnly mode.`,
-        category: "tool_execution"
-      });
-    }
+    const mode = this.config.configuration?.mode ?? SafetyMode.ReadOnly;
     const nativeRuntimeTool = this.nativeToolRegistry?.get(operationName);
     const nativeApprovalMetadata = nativeRuntimeTool?.approvalMetadata(input);
     const invokedOperation = tool2.meta.operationSelector ? String(input[tool2.meta.operationSelector] ?? "") : void 0;
     const effectiveAccess = (invokedOperation ? tool2.meta.operationAccess?.[invokedOperation] : void 0) ?? tool2.meta.access;
     const effectiveRiskLevel = (invokedOperation ? tool2.meta.operationRiskLevel?.[invokedOperation] : void 0) ?? tool2.meta.riskLevel;
+    if (mode === SafetyMode.ReadOnly && effectiveAccess === "write") {
+      throw new ZuoraAgentToolkitError({
+        code: "TOOL_EXECUTION_ERROR",
+        message: `Write operation "${invokedOperation ?? operationName}" is disabled in readOnly mode.`,
+        category: "tool_execution"
+      });
+    }
     const effectiveTool = effectiveAccess === tool2.meta.access && effectiveRiskLevel === tool2.meta.riskLevel ? tool2 : { ...tool2, meta: { ...tool2.meta, access: effectiveAccess, riskLevel: effectiveRiskLevel } };
     await enforceApproval(
       effectiveTool,
@@ -4642,7 +4600,7 @@ var ToolkitCore = class {
     return this.catalogTools ?? [];
   }
   resolveSplitOperations() {
-    return this.config.configuration?.splitOperations ?? true;
+    return this.config.configuration?.splitOperations ?? false;
   }
   warnIfNotInitialized() {
     if (!this._initialized) {
@@ -4711,13 +4669,11 @@ var ToolkitCore = class {
   }
   createEventContext() {
     const configurationContext = this.config.configuration?.context ?? {};
-    const tenantId = nonEmptyString(configurationContext.tenantId) ?? nonEmptyString(configurationContext.tenant_id);
     const entityIds = normalizeIdList(configurationContext.entityIds) ?? normalizeIdList(configurationContext.entityId);
     const orgIds = normalizeIdList(configurationContext.orgIds) ?? normalizeIdList(configurationContext.orgId);
     const environment = inferZuoraEnvironment(this.config.baseUrl) ?? "sandbox";
     return {
       environment,
-      ...tenantId ? { tenantId } : {},
       ...entityIds ? { entityIds } : {},
       ...orgIds ? { orgIds } : {}
     };
@@ -4809,51 +4765,21 @@ var readBooleanEnvValue = (name, rawValue) => {
 var readBooleanEnv = (env, name) => readBooleanEnvValue(name, env[name]);
 var readZuoraEndpoint = (env) => readTrimmedEnv(env, "ZUORA_BASE_URL") ?? readTrimmedEnv(env, "ZUORA_MCP_URL");
 var readToolkitMode = (env) => {
-  const mode = env.ZUORA_TOOLKIT_MODE?.trim() ?? "readOnly";
-  if (mode === "readOnly" || mode === "writeEnabled") {
+  const mode = env.ZUORA_TOOLKIT_MODE?.trim() ?? SafetyMode.ReadOnly;
+  if (mode === SafetyMode.ReadOnly || mode === SafetyMode.WriteEnabled) {
     return mode;
   }
   throw new Error(
-    `Invalid ZUORA_TOOLKIT_MODE: ${mode}. Expected readOnly or writeEnabled.`
-  );
-};
-var readOptionalUrlEnv = (env, name) => {
-  const value = readTrimmedEnv(env, name);
-  if (!value) {
-    return void 0;
-  }
-  try {
-    const url = new URL(value);
-    if (url.protocol === "http:" || url.protocol === "https:") {
-      return url.toString();
-    }
-  } catch {
-  }
-  throw new Error(`${name} must be an absolute HTTP(S) URL.`);
-};
-var readTokenAuthMethodEnv = (env) => {
-  const value = readTrimmedEnv(env, "ZUORA_TOKEN_AUTH_METHOD");
-  if (!value) {
-    return void 0;
-  }
-  if (value === "client_secret_post" || value === "client_secret_basic") {
-    return value;
-  }
-  throw new Error(
-    "Invalid ZUORA_TOKEN_AUTH_METHOD: expected client_secret_post or client_secret_basic."
+    `Invalid ZUORA_TOOLKIT_MODE: ${mode}. Expected ${SafetyMode.ReadOnly} or ${SafetyMode.WriteEnabled}.`
   );
 };
 var readConnectionOptions = (env) => {
-  const tokenEndpoint = readOptionalUrlEnv(env, "ZUORA_TOKEN_ENDPOINT");
-  const tokenAuthMethod = readTokenAuthMethodEnv(env);
   const entityIds = readTrimmedEnv(env, "ZUORA_ENTITY_IDS");
   const orgIds = readTrimmedEnv(env, "ZUORA_ORG_IDS");
   const zuoraVersion = readTrimmedEnv(env, "ZUORA_VERSION");
   return {
     ...entityIds ? { entityIds } : {},
     ...orgIds ? { orgIds } : {},
-    ...tokenEndpoint ? { tokenEndpoint } : {},
-    ...tokenAuthMethod ? { tokenAuthMethod } : {},
     ...zuoraVersion ? { zuoraVersion } : {}
   };
 };
@@ -4878,28 +4804,19 @@ var zuoraAgentToolkitConfigFromEnv = (env = process.env) => {
         }
       },
       configuration: {
-        mode,
-        context: {
-          tenantId
-        }
+        mode
       }
     };
   }
   return {
     baseUrl,
     auth: {
-      type: "oauthClientCredentials",
       clientId: requiredEnv(env, "ZUORA_CLIENT_ID"),
       clientSecret: requiredEnv(env, "ZUORA_CLIENT_SECRET")
     },
     ...Object.keys(connection).length > 0 ? { connection } : {},
     configuration: {
-      mode,
-      ...readTrimmedEnv(env, "ZUORA_TENANT_ID") ? {
-        context: {
-          tenantId: readTrimmedEnv(env, "ZUORA_TENANT_ID")
-        }
-      } : {}
+      mode
     }
   };
 };
@@ -5067,6 +4984,79 @@ var strictifySchema = (schema) => {
 
 // src/openai-agents/toolkit.ts
 var ZuoraOpenAIAgentsToolkit = class extends ToolkitCore {
+  /** Maps sanitized adapter tool names back to their original ZuoraToolDefinition. */
+  sanitizedToolMap = /* @__PURE__ */ new Map();
+  /**
+   * Look up a ZuoraToolDefinition by its sanitized adapter tool name.
+   *
+   * The OpenAI Agents SDK registers tools with sanitized names (see convertTools),
+   * but external code may reference tools by their original MCP names. This method
+   * provides resolution in both directions.
+   */
+  resolveToolName(name) {
+    if (this.sanitizedToolMap.has(name)) {
+      return name;
+    }
+    for (const [sanitized, def] of this.sanitizedToolMap) {
+      if (def.name === name) {
+        return sanitized;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Resolve a tool name that may be either sanitized or original MCP format.
+   *
+   * This provides additional name normalization to handle cases where:
+   * - A tool name contains unsanitized characters (like dots)
+   * - A tool name was learned from descriptions or logs
+   *
+   * We attempt to find a match with relaxed sanitization rules before giving up.
+   */
+  normalizeToolName(name) {
+    const directMatch = this.resolveToolName(name);
+    if (directMatch) {
+      return directMatch;
+    }
+    const normalized = name.replace(/\./g, "_");
+    const normalizedMatch = this.resolveToolName(normalized);
+    if (normalizedMatch) {
+      return normalizedMatch;
+    }
+    for (const [sanitized, def] of this.sanitizedToolMap) {
+      if (def.name === normalized) {
+        return sanitized;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Override callTool to provide flexible name resolution.
+   *
+   * The OpenAI Agents SDK may receive tool calls with names that were learned
+   * from descriptions or other sources (not directly from tool registration).
+   * This override allows us to handle both sanitized and original tool names
+   * by falling back to name normalization when the direct lookup fails.
+   */
+  async callTool(operationName, input) {
+    try {
+      return await super.callTool(operationName, input);
+    } catch (error) {
+      if (error instanceof Error && (error.message.includes("Unknown Zuora tool") || error.message.includes("TOOL_NOT_FOUND"))) {
+        const sanitized = this.normalizeToolName(operationName);
+        if (sanitized) {
+          const def = this.sanitizedToolMap.get(sanitized);
+          if (def) {
+            console.warn(
+              `[zuora-agent-toolkit] Tool name normalized: "${operationName}" -> "${def.name}" (sanitized: "${sanitized}")`
+            );
+            return await super.callTool(def.name, input);
+          }
+        }
+      }
+      throw error;
+    }
+  }
   /**
    * Serialises the agent tool response, emits an `agent.tool.response`
    * observability event (with the response in `metadata` when
@@ -5090,6 +5080,7 @@ var ZuoraOpenAIAgentsToolkit = class extends ToolkitCore {
   convertTools(tools) {
     return tools.map((def) => {
       const sanitizedName = sanitizeAdapterToolName(def.name);
+      this.sanitizedToolMap.set(sanitizedName, def);
       return tool({
         name: sanitizedName,
         description: def.description,