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

package/dist/langchain/index.js

@@ -1 +1,4964 @@
+// src/langchain/toolkit.ts
+import { tool } from "@langchain/core/tools";
+
+// src/shared/errors.ts
+var ZuoraAgentToolkitError = class extends Error {
+  code;
+  category;
+  retryable;
+  recoverable;
+  requestId;
+  details;
+  constructor(params) {
+    super(params.message);
+    this.name = "ZuoraAgentToolkitError";
+    this.code = params.code;
+    this.category = params.category;
+    this.recoverable = params.recoverable ?? params.retryable ?? false;
+    this.retryable = params.retryable ?? false;
+    this.requestId = params.requestId;
+    this.details = params.details;
+  }
+};
+
+// src/shared/types.ts
+var SafetyMode = {
+  ReadOnly: "readOnly",
+  WriteEnabled: "writeEnabled"
+};
+var ApprovalPolicyPreset = {
+  Off: "off",
+  AllWrites: "all_writes",
+  HighRisk: "high_risk",
+  ProductionWrites: "production_writes",
+  ProductionHighRisk: "production_high_risk"
+};
+
+// src/shared/utils/zuora-url.ts
+var normalizeZuoraMcpUrl = (raw) => {
+  const trimmed = raw.replace(/\/+$/, "");
+  const parsed = new URL(trimmed);
+  let restBaseUrl;
+  if (trimmed.endsWith("/mcp")) {
+    if (!isZuoraHost(parsed.hostname)) {
+      return {
+        remoteUrl: trimmed,
+        restBaseUrl: trimmed.slice(0, -"/mcp".length)
+      };
+    }
+    const stagingHostMatch = parsed.hostname.match(/^staging(\d+)\.zuora\.com$/);
+    if (stagingHostMatch?.[1]) {
+      restBaseUrl = `${parsed.protocol}//rest-staging${stagingHostMatch[1]}.zuora.com`;
+    } else if (parsed.hostname.startsWith("rest.")) {
+      restBaseUrl = `${parsed.protocol}//${parsed.hostname}`;
+    } else if (parsed.hostname.startsWith("rest-")) {
+      restBaseUrl = `${parsed.protocol}//${parsed.hostname}`;
+    } else {
+      restBaseUrl = `${parsed.protocol}//rest.${parsed.hostname}`;
+    }
+  } else {
+    restBaseUrl = trimmed;
+  }
+  return {
+    remoteUrl: `${restBaseUrl}/mcp`,
+    restBaseUrl
+  };
+};
+var isZuoraHost = (hostname) => {
+  const lower = hostname.toLowerCase();
+  return lower === "zuora.com" || lower.endsWith(".zuora.com");
+};
+var isStagingZuoraBaseUrl = (baseUrl) => {
+  try {
+    const hostname = new URL(baseUrl).hostname.toLowerCase();
+    return hostname.includes("staging") || hostname.includes(".stg.") || hostname.includes("-stg");
+  } catch {
+    const lower = baseUrl.toLowerCase();
+    return lower.includes("staging") || lower.includes(".stg.") || lower.includes("-stg");
+  }
+};
+var inferZuoraEnvironment = (baseUrl) => {
+  let hostname;
+  try {
+    hostname = new URL(normalizeZuoraMcpUrl(baseUrl).restBaseUrl).hostname.toLowerCase();
+  } catch {
+    return void 0;
+  }
+  if (PRODUCTION_ZUORA_HOSTS.has(hostname)) {
+    return "production";
+  }
+  if (SANDBOX_ZUORA_HOSTS.has(hostname) || isStagingZuoraBaseUrl(baseUrl)) {
+    return "sandbox";
+  }
+  return void 0;
+};
+var SANDBOX_ZUORA_HOSTS = /* @__PURE__ */ new Set([
+  "rest.apisandbox.zuora.com",
+  "rest.sandbox.na.zuora.com",
+  "rest.sandbox.eu.zuora.com",
+  "rest.test.zuora.com",
+  "rest.test.eu.zuora.com",
+  "rest.test.ap.zuora.com"
+]);
+var PRODUCTION_ZUORA_HOSTS = /* @__PURE__ */ new Set([
+  "rest.zuora.com",
+  "rest.na.zuora.com",
+  "rest.eu.zuora.com",
+  "rest.ap.zuora.com"
+]);
+
+// src/shared/approval-policy.ts
+var normalizeApprovalPolicyResult = (result) => {
+  if (typeof result === "string") {
+    return result;
+  }
+  return result.decision;
+};
+var evaluatePreset = (preset, request) => {
+  const { tool: tool2, environment } = request;
+  const isWrite = tool2.meta.access === "write";
+  const isHighRisk = tool2.meta.riskLevel === "high";
+  const isProduction = environment === "production";
+  switch (preset) {
+    case ApprovalPolicyPreset.Off:
+      return "allow";
+    case ApprovalPolicyPreset.AllWrites:
+      return isWrite ? "deny" : "allow";
+    case ApprovalPolicyPreset.HighRisk:
+      return isHighRisk ? "deny" : "allow";
+    case ApprovalPolicyPreset.ProductionWrites:
+      return isProduction && isWrite ? "deny" : "allow";
+    case ApprovalPolicyPreset.ProductionHighRisk:
+      return isProduction && isHighRisk ? "deny" : "allow";
+  }
+};
+var throwApprovalRejected = (tool2) => {
+  throw new ZuoraAgentToolkitError({
+    code: "APPROVAL_REJECTED",
+    message: `Tool "${tool2.name}" was denied by approval policy.`,
+    category: "approval",
+    recoverable: false
+  });
+};
+var enforceApproval = async (tool2, input, config, emit, native) => {
+  const { approvalPolicy } = config;
+  if (!approvalPolicy) {
+    return;
+  }
+  const environment = inferZuoraEnvironment(config.baseUrl) ?? "sandbox";
+  const request = {
+    tool: tool2,
+    input,
+    environment,
+    ...native ? { native } : {}
+  };
+  emit?.({
+    name: "approval.requested",
+    toolName: tool2.name,
+    access: tool2.meta.access,
+    bundle: tool2.meta.bundle,
+    riskLevel: tool2.meta.riskLevel,
+    environment,
+    approvalStatus: "requested"
+  });
+  const decision = typeof approvalPolicy === "function" ? normalizeApprovalPolicyResult(await approvalPolicy(request)) : evaluatePreset(approvalPolicy, request);
+  const resolvedStatus = decision === "deny" ? "rejected" : "not_required";
+  emit?.({
+    name: "approval.resolved",
+    toolName: tool2.name,
+    access: tool2.meta.access,
+    bundle: tool2.meta.bundle,
+    riskLevel: tool2.meta.riskLevel,
+    environment,
+    approvalDecision: decision === "deny" ? "deny" : "allow",
+    approvalStatus: resolvedStatus
+  });
+  if (decision === "deny") {
+    throwApprovalRejected(tool2);
+  }
+};
+
+// src/shared/utils/adapter-name.ts
+var MAX_ADAPTER_TOOL_NAME_LENGTH = 64;
+var SAFE_ADAPTER_TOOL_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+var createOperationAdapterToolName = (sourceToolName, operationName) => {
+  const rawName = `${sourceToolName}__${operationName}`;
+  if (rawName.length <= MAX_ADAPTER_TOOL_NAME_LENGTH && SAFE_ADAPTER_TOOL_NAME_PATTERN.test(rawName)) {
+    return rawName;
+  }
+  return sanitizeAdapterToolName(rawName);
+};
+var stableNameHash = (value) => {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36).padStart(7, "0").slice(-7);
+};
+var sanitizeAdapterToolName = (name) => {
+  if (name.length <= MAX_ADAPTER_TOOL_NAME_LENGTH && SAFE_ADAPTER_TOOL_NAME_PATTERN.test(name)) {
+    return name;
+  }
+  const sanitized = name.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  const candidate = sanitized || "tool";
+  if (candidate.length <= MAX_ADAPTER_TOOL_NAME_LENGTH && SAFE_ADAPTER_TOOL_NAME_PATTERN.test(candidate)) {
+    return candidate;
+  }
+  const hash = stableNameHash(name);
+  const suffix = `_${hash}`;
+  const maxPrefixLength = MAX_ADAPTER_TOOL_NAME_LENGTH - suffix.length;
+  const prefix = candidate.slice(0, maxPrefixLength) || "tool";
+  return `${prefix}${suffix}`;
+};
+
+// src/shared/async-jobs.ts
+var DEFAULT_ASYNC_JOB_TERMINAL_STATUSES = {
+  success: ["Completed", "Success", "Succeeded", "Done"],
+  failure: ["Failed", "Error", "Errored", "Aborted"],
+  canceled: ["Canceled", "Cancelled"]
+};
+var normalizeMetadataPath = (path5) => {
+  const trimmed = path5.trim();
+  if (trimmed.startsWith("$.")) {
+    return trimmed.slice(2);
+  }
+  if (trimmed.startsWith("$")) {
+    return trimmed.slice(1);
+  }
+  return trimmed;
+};
+function resolveByPath(obj, path5) {
+  return path5.split(".").reduce(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- same reason as above
+    (current, segment) => current != null && typeof current === "object" ? current[segment] : void 0,
+    obj
+  );
+}
+function resolveAsyncJobPollingToolNameFromMeta(asyncMeta, context) {
+  const pollingOperation = asyncMeta.pollingOperation;
+  const pollingTool = asyncMeta.pollingTool;
+  if (!pollingOperation) {
+    return pollingTool ?? context.sourceToolName;
+  }
+  if (pollingTool) {
+    return createOperationAdapterToolName(pollingTool, pollingOperation);
+  }
+  if (context.operationSelector && context.sourceOperationNames?.includes(pollingOperation)) {
+    return createOperationAdapterToolName(
+      context.sourceToolName,
+      pollingOperation
+    );
+  }
+  return context.sourceToolName;
+}
+function buildAsyncJobResult(result, asyncMeta, context) {
+  const payload = result.data;
+  const jobId = resolveByPath(payload, asyncMeta.jobIdPath);
+  if (jobId == null) {
+    throw new ZuoraAgentToolkitError({
+      code: "TOOL_EXECUTION_ERROR",
+      message: `Async job ID not found at path "${asyncMeta.jobIdPath}" in tool result for "${result.toolName}".`,
+      category: "tool_execution"
+    });
+  }
+  const pollingToolName = resolveAsyncJobPollingToolNameFromMeta(
+    asyncMeta,
+    context
+  );
+  const pending = {
+    toolName: result.toolName,
+    status: "pending",
+    jobId: String(jobId),
+    pollingToolName,
+    ...asyncMeta.pollingOperation ? { pollingOperation: asyncMeta.pollingOperation } : {},
+    statusPath: asyncMeta.statusPath,
+    terminalStatuses: asyncMeta.terminalStatuses
+  };
+  const needsOperationInjection = !!asyncMeta.pollingOperation && !asyncMeta.pollingTool && !context.operationSelector;
+  if (needsOperationInjection) {
+    pending.pollingArgs = {
+      ...asyncMeta.pollingArgs,
+      operation: asyncMeta.pollingOperation
+    };
+  } else if (asyncMeta.pollingArgs !== void 0) {
+    pending.pollingArgs = asyncMeta.pollingArgs;
+  }
+  if (asyncMeta.recommendedPollIntervalMs !== void 0) {
+    pending.recommendedPollIntervalMs = asyncMeta.recommendedPollIntervalMs;
+  }
+  if (asyncMeta.maxPollAttempts !== void 0) {
+    pending.maxPollAttempts = asyncMeta.maxPollAttempts;
+  }
+  if (asyncMeta.defaultTimeoutMs !== void 0) {
+    pending.defaultTimeoutMs = asyncMeta.defaultTimeoutMs;
+  }
+  return pending;
+}
+function resolveAsyncJobTerminalState(status, statuses) {
+  const lower = status.toLowerCase();
+  if (statuses.success.some((s) => s.toLowerCase() === lower)) return "success";
+  if (statuses.failure.some((s) => s.toLowerCase() === lower)) return "failure";
+  if (statuses.canceled?.some((s) => s.toLowerCase() === lower)) return "canceled";
+  return void 0;
+}
+function resolveAsyncJobStatus(result, statusPath) {
+  const raw = resolveByPath(result.data, statusPath);
+  if (raw == null || typeof raw !== "string") return void 0;
+  return raw;
+}
+function resolveAsyncJobStatusDetails(result, statusPath, terminalStatuses) {
+  const status = resolveAsyncJobStatus(result, statusPath);
+  if (status == null || status === "") {
+    return { status: void 0, isTerminal: false, terminalState: void 0 };
+  }
+  const terminalState = resolveAsyncJobTerminalState(status, terminalStatuses);
+  const isTerminal = terminalState !== void 0;
+  return { status, isTerminal, terminalState };
+}
+
+// src/shared/bundles.ts
+import bundleCatalog from "../bundle-catalog-3V6EICKE.json";
+
+// src/shared/utils/values.ts
+var nonEmptyString = (value) => typeof value === "string" && value.trim() ? value.trim() : void 0;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var normalizeIdList = (value) => {
+  const values = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+  const normalized = values.flatMap((entry) => {
+    const normalizedEntry = nonEmptyString(entry);
+    return normalizedEntry ? [normalizedEntry] : [];
+  });
+  return normalized.length > 0 ? normalized : void 0;
+};
+
+// src/shared/bundles.ts
+var ZUORA_BUNDLE_NAMES = [
+  "accounts",
+  "catalog",
+  "subscriptions",
+  "orders",
+  "billing",
+  "payments",
+  "usage",
+  "revenue",
+  "finance",
+  "workflows",
+  "query",
+  "admin"
+];
+var readStringArrayField = (record, fieldName, bundleName) => {
+  const value = record[fieldName];
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw new Error(
+      `Invalid bundle catalog entry for ${bundleName}: ${fieldName} must be a non-empty string array.`
+    );
+  }
+  return value.map((item) => item.trim());
+};
+var readBundleCatalogEntry = (value, bundleName) => {
+  if (!isRecord(value)) {
+    throw new Error(`Missing bundle catalog entry for ${bundleName}.`);
+  }
+  const description = value.description;
+  if (typeof description !== "string" || description.trim() === "") {
+    throw new Error(
+      `Invalid bundle catalog entry for ${bundleName}: description is required.`
+    );
+  }
+  return {
+    description: description.trim(),
+    examples: readStringArrayField(value, "examples", bundleName),
+    commonObjects: readStringArrayField(value, "commonObjects", bundleName),
+    keywords: readStringArrayField(value, "keywords", bundleName)
+  };
+};
+var loadBundleCatalog = () => {
+  const raw = bundleCatalog;
+  if (!isRecord(raw)) {
+    throw new Error("Invalid bundle catalog: expected an object.");
+  }
+  const rawBundles = raw.bundles;
+  if (!isRecord(rawBundles)) {
+    throw new Error("Invalid bundle catalog: expected a bundles object.");
+  }
+  const version = raw.version;
+  if (typeof version !== "number" || !Number.isInteger(version)) {
+    throw new Error("Invalid bundle catalog: version must be an integer.");
+  }
+  const bundles = Object.fromEntries(
+    ZUORA_BUNDLE_NAMES.map((name) => [
+      name,
+      readBundleCatalogEntry(rawBundles[name], name)
+    ])
+  );
+  return {
+    version,
+    bundles
+  };
+};
+var BUNDLE_CATALOG = loadBundleCatalog();
+var ZUORA_BUNDLE_NAME_SET = new Set(ZUORA_BUNDLE_NAMES);
+var hasBundleDefinition = (name) => ZUORA_BUNDLE_NAME_SET.has(name);
+var getBundleDefinition = (name, tools = []) => {
+  const metadata = BUNDLE_CATALOG.bundles[name];
+  const bundleTools = tools.filter((tool2) => tool2.meta.bundle === name);
+  const description = metadata?.description ?? name;
+  const examples = metadata ? [...metadata.examples] : [];
+  const commonObjects = metadata ? [...metadata.commonObjects] : [];
+  const keywords = metadata ? [...metadata.keywords] : [];
+  return {
+    name,
+    description,
+    examples,
+    commonObjects,
+    keywords,
+    toolCount: bundleTools.length,
+    readToolCount: bundleTools.filter((tool2) => tool2.meta.access === "read").length,
+    writeToolCount: bundleTools.filter((tool2) => tool2.meta.access === "write").length,
+    tools: bundleTools
+  };
+};
+
+// src/shared/tools/operation-metadata.ts
+var inferOperationSelector = (inputSchema, operationPermissions) => {
+  const operationNames = Object.keys(operationPermissions ?? {});
+  if (operationNames.length <= 1) {
+    return void 0;
+  }
+  const properties = inputSchema?.properties;
+  if (!properties) {
+    return void 0;
+  }
+  const candidates = Object.entries(properties).flatMap(
+    ([propertyName, propertySchema]) => isOperationSelectorSchema(propertySchema, operationNames) ? [propertyName] : []
+  );
+  return candidates.length === 1 ? candidates[0] : void 0;
+};
+var omitSchemaProperty = (schema, propertyName) => {
+  if (!schema.properties?.[propertyName]) {
+    return schema;
+  }
+  const { [propertyName]: _removed, ...properties } = schema.properties;
+  const nextSchema = {
+    ...schema,
+    properties
+  };
+  if (schema.required) {
+    const required = schema.required.filter((name) => name !== propertyName);
+    if (required.length > 0) {
+      nextSchema.required = required;
+    } else {
+      delete nextSchema.required;
+    }
+  }
+  return nextSchema;
+};
+var enforceOperationSelector = (tool2, input) => {
+  const selector = tool2.meta.operationSelector;
+  if (!selector || !tool2.meta.operationName) {
+    return;
+  }
+  if (!Object.prototype.hasOwnProperty.call(input, selector)) {
+    return;
+  }
+  const providedOperation = input[selector];
+  const expectedOperation = tool2.meta.operationName;
+  if (providedOperation === expectedOperation) {
+    return;
+  }
+  throw new ZuoraAgentToolkitError({
+    code: "OPERATION_SELECTOR_MISMATCH",
+    message: `Tool ${tool2.name} is bound to ${selector}=${expectedOperation}.`,
+    category: "validation",
+    recoverable: true,
+    details: {
+      selector,
+      expected: expectedOperation,
+      received: providedOperation,
+      sourceName: tool2.meta.sourceName
+    }
+  });
+};
+var createMcpToolInput = (tool2, input) => {
+  const selector = tool2.meta.operationSelector;
+  if (!selector || !tool2.meta.operationName) {
+    return input;
+  }
+  return { ...input, [selector]: tool2.meta.operationName };
+};
+var isOperationSelectorSchema = (schema, operationNames) => {
+  const enumValues = stringEnumValues(schema);
+  if (!enumValues) {
+    return false;
+  }
+  return haveSameStringSet(enumValues, operationNames);
+};
+var stringEnumValues = (schema) => {
+  if (schema.type !== "string" || !Array.isArray(schema.enum)) {
+    return void 0;
+  }
+  return schema.enum.every((value) => typeof value === "string") ? schema.enum : void 0;
+};
+var haveSameStringSet = (left, right) => {
+  if (left.length !== right.length) {
+    return false;
+  }
+  const rightSet = new Set(right);
+  return left.every((value) => rightSet.has(value));
+};
+
+// src/shared/utils/event-sanitizer.ts
+var REDACTED_EVENT_VALUE = "[REDACTED]";
+var TRUNCATED_EVENT_VALUE = "[TRUNCATED]";
+var DEFAULT_EVENT_SANITIZER_LIMITS = {
+  maxDepth: 4,
+  maxArrayLength: 20,
+  maxObjectKeys: 50,
+  maxStringLength: 512
+};
+var sanitizeEventRecord = (value, limits = DEFAULT_EVENT_SANITIZER_LIMITS) => {
+  const sanitized = sanitizeEventValue(value, "", 0, limits);
+  return isRecord(sanitized) ? sanitized : { value: sanitized };
+};
+var sanitizeEventValue = (value, key, depth, limits) => {
+  if (isSensitiveEventKey(key)) {
+    return REDACTED_EVENT_VALUE;
+  }
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === "string") {
+    if (looksSensitiveString(value)) {
+      return REDACTED_EVENT_VALUE;
+    }
+    return value.length > limits.maxStringLength ? `${value.slice(0, limits.maxStringLength)}...` : value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value === void 0 || typeof value === "function" || typeof value === "symbol") {
+    return void 0;
+  }
+  if (depth >= limits.maxDepth) {
+    return TRUNCATED_EVENT_VALUE;
+  }
+  if (Array.isArray(value)) {
+    const entries = value.slice(0, limits.maxArrayLength).map((entry) => sanitizeEventValue(entry, "", depth + 1, limits));
+    return value.length > limits.maxArrayLength ? [...entries, TRUNCATED_EVENT_VALUE] : entries;
+  }
+  if (!isRecord(value)) {
+    return String(value);
+  }
+  return Object.fromEntries(
+    Object.entries(value).slice(0, limits.maxObjectKeys).flatMap(([entryKey, entryValue]) => {
+      const sanitizedEntry = sanitizeEventValue(
+        entryValue,
+        entryKey,
+        depth + 1,
+        limits
+      );
+      return sanitizedEntry === void 0 ? [] : [[entryKey, sanitizedEntry]];
+    })
+  );
+};
+var isSensitiveEventKey = (key) => /authorization|client[_-]?secret|access[_-]?token|refresh[_-]?token|api[_-]?key|private[_-]?key|password|secret|token|signed[_-]?url|card[_-]?number|cvv|cvc|iban|bank[_-]?account|routing[_-]?number/i.test(
+  key
+);
+var looksSensitiveString = (value) => /^(Bearer|Basic)\s+\S+/i.test(value) || looksSignedUrl(value) || /(?:access_token|refresh_token|client_secret|signature|x-amz-signature)=/i.test(
+  value
+) || /^sk-[A-Za-z0-9_-]{12,}/.test(value) || /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value);
+var looksSignedUrl = (value) => {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return false;
+  }
+  for (const key of parsed.searchParams.keys()) {
+    if (/^(sig|signature|token|access_token|security-token|x-amz-.+|x-goog-.+|expires|expires_in)$/i.test(
+      key
+    )) {
+      return true;
+    }
+  }
+  return false;
+};
+
+// src/shared/observability/events.ts
+var reportObservabilitySinkError = (logger, error) => {
+  try {
+    logger?.error?.("[zuora-agent-toolkit] observability sink failed", {
+      name: "observability.sink_failed",
+      type: "observability.sink_failed",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      error: {
+        code: "OBSERVABILITY_SINK_ERROR",
+        category: "configuration",
+        recoverable: true
+      },
+      metadata: sanitizeEventRecord({
+        message: error instanceof Error ? error.message : String(error)
+      })
+    });
+  } catch {
+  }
+};
+var normalizeToolkitEvent = (event, sanitizerLimits) => {
+  const { metadata, timestamp, type, ...rest } = event;
+  return {
+    ...rest,
+    type: type ?? toolkitEventTypeForName(event.name),
+    timestamp: timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+    ...metadata ? { metadata: sanitizeEventRecord(metadata, sanitizerLimits) } : {}
+  };
+};
+var compactToolkitError = (error) => ({
+  code: error.code,
+  category: error.category,
+  recoverable: error.recoverable,
+  retryable: error.retryable,
+  message: error.message,
+  ...error.requestId ? { requestId: error.requestId } : {}
+});
+var metadataLoadedEventMetadata = (tools) => {
+  const bundleCounts = tools.reduce(
+    (counts, tool2) => {
+      counts[tool2.meta.bundle] = (counts[tool2.meta.bundle] ?? 0) + 1;
+      return counts;
+    },
+    {}
+  );
+  return {
+    toolCount: tools.length,
+    bundleCounts
+  };
+};
+var toolkitEventTypeForName = (name) => name === "approval.resolved" ? "approval.decided" : name;
+
+// src/shared/observability/async-poll-events.ts
+var logAsyncPollChecked = (logger, details) => {
+  if (!logger?.debug) {
+    return;
+  }
+  const message = "[zuora-agent-toolkit] async.poll.checked";
+  const event = {
+    name: "async.poll.checked",
+    type: "async.poll.checked",
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    executionPhase: "async_poll",
+    toolName: details.pollingToolName,
+    metadata: sanitizeEventRecord({
+      jobId: details.jobId,
+      attempt: details.attempt,
+      maxAttempts: details.maxAttempts,
+      pollingToolName: details.pollingToolName,
+      statusPath: details.statusPath,
+      statusSource: details.statusSource,
+      resolvedValue: details.resolvedValue,
+      ...details.resolvedStatus ? { resolvedStatus: details.resolvedStatus } : {},
+      terminalStatuses: details.terminalStatuses,
+      matchedSuccess: details.matchedSuccess,
+      matchedFailure: details.matchedFailure,
+      matchedCanceled: details.matchedCanceled,
+      decision: details.decision
+    })
+  };
+  try {
+    logger.debug(message, event);
+  } catch {
+  }
+};
+
+// src/shared/observability/payloads.ts
+var compactToolInputForEvent = (input) => sanitizeEventRecord(input);
+var compactToolOutputForEvent = (result) => sanitizeEventRecord({
+  toolName: result.toolName,
+  ...result.requestId ? { requestId: result.requestId } : {},
+  ...result.request ? { request: result.request } : {},
+  riskLevel: result.riskLevel,
+  data: result.data,
+  ...result.warnings?.length ? { warnings: result.warnings } : {}
+});
+
+// src/shared/transport/request-metadata.ts
+var normalizeRequestMetadataFields = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  const record = value;
+  const requestId = nonEmptyString(record.requestId) ?? nonEmptyString(record.request_id);
+  const zuoraRequestId = nonEmptyString(record.zuoraRequestId) ?? nonEmptyString(record.zuora_request_id);
+  const tenantId = nonEmptyString(record.tenantId) ?? nonEmptyString(record.tenant_id);
+  const entityIds = normalizeIdList(record.entityIds) ?? normalizeIdList(record.entity_ids) ?? normalizeIdList(record.entityId) ?? normalizeIdList(record.entity_id);
+  const orgIds = normalizeIdList(record.orgIds) ?? normalizeIdList(record.org_ids) ?? normalizeIdList(record.orgId) ?? normalizeIdList(record.org_id);
+  const environment = normalizeRequestEnvironment(record.environment);
+  const metadata = {
+    ...requestId ? { requestId } : {},
+    ...zuoraRequestId ? { zuoraRequestId } : {},
+    ...environment ? { environment } : {},
+    ...tenantId ? { tenantId } : {},
+    ...entityIds ? { entityIds } : {},
+    ...orgIds ? { orgIds } : {}
+  };
+  return Object.keys(metadata).length > 0 ? metadata : void 0;
+};
+var normalizeExecutionRequestMetadata = normalizeRequestMetadataFields;
+var normalizeRequestEnvironment = (value) => {
+  const normalized = nonEmptyString(value)?.toLowerCase();
+  return normalized === "sandbox" || normalized === "production" ? normalized : void 0;
+};
+
+// src/shared/observability/request-metadata.ts
+var extractExecutionRequestMetadata = (result) => {
+  const explicitRequest = normalizeRequestMetadataFields(result.request) ?? {};
+  const nestedRequest = extractNestedRequestMetadata(result.data);
+  const fallbackRequestId = result.requestId ?? extractRequestId(result.data);
+  const requestId = explicitRequest.requestId ?? nestedRequest.requestId ?? fallbackRequestId ?? explicitRequest.zuoraRequestId ?? nestedRequest.zuoraRequestId;
+  const zuoraRequestId = explicitRequest.zuoraRequestId ?? nestedRequest.zuoraRequestId ?? extractZuoraRequestId(result.data) ?? requestId;
+  const metadata = {
+    ...requestId ? { requestId } : {},
+    ...zuoraRequestId ? { zuoraRequestId } : {},
+    ...explicitRequest.environment ?? nestedRequest.environment ? { environment: explicitRequest.environment ?? nestedRequest.environment } : {},
+    ...explicitRequest.tenantId ?? nestedRequest.tenantId ? { tenantId: explicitRequest.tenantId ?? nestedRequest.tenantId } : {},
+    ...explicitRequest.entityIds ?? nestedRequest.entityIds ? { entityIds: explicitRequest.entityIds ?? nestedRequest.entityIds } : {},
+    ...explicitRequest.orgIds ?? nestedRequest.orgIds ? { orgIds: explicitRequest.orgIds ?? nestedRequest.orgIds } : {}
+  };
+  return metadata;
+};
+var extractNestedRequestMetadata = (value) => {
+  if (!value || typeof value !== "object") {
+    return {};
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const request2 = extractNestedRequestMetadata(item);
+      if (Object.keys(request2).length > 0) {
+        return request2;
+      }
+    }
+    return {};
+  }
+  const record = value;
+  const request = normalizeRequestMetadataFields(record.request) ?? {};
+  if (Object.keys(request).length > 0) {
+    return request;
+  }
+  for (const entry of Object.values(record)) {
+    const nestedRequest = extractNestedRequestMetadata(entry);
+    if (Object.keys(nestedRequest).length > 0) {
+      return nestedRequest;
+    }
+  }
+  return {};
+};
+var extractFirstMatchingStringField = (value, keys) => {
+  if (!value || typeof value !== "object") {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = extractFirstMatchingStringField(item, keys);
+      if (found) {
+        return found;
+      }
+    }
+    return void 0;
+  }
+  const record = value;
+  for (const key of keys) {
+    if (key in record && typeof record[key] === "string") {
+      return record[key];
+    }
+  }
+  for (const entry of Object.values(record)) {
+    const found = extractFirstMatchingStringField(entry, keys);
+    if (found) {
+      return found;
+    }
+  }
+  return void 0;
+};
+var extractRequestId = (value) => extractFirstMatchingStringField(value, [
+  "zuoraRequestId",
+  "zuora_request_id",
+  "requestId",
+  "request_id"
+]);
+var extractZuoraRequestId = (value) => extractFirstMatchingStringField(value, [
+  "zuoraRequestId",
+  "zuora_request_id"
+]);
+
+// src/shared/tools/native/file-artifacts/config.ts
+import os from "os";
+import path from "path";
+
+// src/shared/tools/native/config.ts
+var resolveNativeToolMetadata = (input, defaults) => {
+  const description = nonEmptyString(input?.description);
+  return {
+    enabled: input?.enabled ?? defaults.enabled,
+    operationAccess: input?.operationAccess ?? defaults.operationAccess,
+    riskLevel: input?.riskLevel ?? defaults.riskLevel,
+    ...description ? { description } : {}
+  };
+};
+
+// src/shared/tools/native/file-artifacts/config.ts
+var DEFAULT_MAX_DOWNLOAD_BYTES = 10 * 1024 * 1024;
+var DEFAULT_MAX_READ_BYTES = 64 * 1024;
+var DEFAULT_MAX_READ_LINES = 200;
+var DEFAULT_DOWNLOAD_TIMEOUT_MS = 3e4;
+var resolveNativeFileToolsConfig = (input) => {
+  const enabled = input?.enabled ?? false;
+  const bundleName = input?.bundleName ?? "query";
+  const userHomeDir = nonEmptyString(input?.userHomeDir) ?? os.homedir();
+  const userHomeDirAbsolute = path.resolve(userHomeDir);
+  const rootDir = nonEmptyString(input?.rootDir) ?? "";
+  const rootDirAbsolute = rootDir ? path.resolve(rootDir) : "";
+  const requireRootUnderUserHome = input?.requireRootUnderUserHome ?? true;
+  const allowedProtocols = normalizeProtocols(input?.allowedProtocols);
+  const allowedHosts = normalizeStringList(input?.allowedHosts).map(
+    (host) => host.toLowerCase()
+  );
+  const allowedUrlPrefixes = normalizeStringList(input?.allowedUrlPrefixes);
+  const zuoraDownloadHosts = normalizeStringList(input?.zuoraDownloadHosts).map(
+    (host) => host.toLowerCase()
+  );
+  const config = {
+    enabled,
+    bundleName,
+    tools: {
+      downloadFile: resolveNativeToolMetadata(input?.tools?.downloadFile, {
+        enabled: false,
+        operationAccess: "read",
+        riskLevel: "medium"
+      }),
+      readDownloadedFile: resolveNativeToolMetadata(input?.tools?.readDownloadedFile, {
+        enabled: true,
+        operationAccess: "read",
+        riskLevel: "low"
+      }),
+      extractDownloadedArchive: resolveNativeToolMetadata(
+        input?.tools?.extractDownloadedArchive,
+        {
+          enabled: false,
+          operationAccess: "read",
+          riskLevel: "medium"
+        }
+      ),
+      readResource: resolveNativeToolMetadata(input?.tools?.readResource, {
+        enabled: true,
+        operationAccess: "read",
+        riskLevel: "low"
+      })
+    },
+    rootDir,
+    rootDirAbsolute,
+    userHomeDir,
+    userHomeDirAbsolute,
+    requireRootUnderUserHome,
+    allowOverwrite: input?.allowOverwrite ?? false,
+    maxDownloadBytes: positiveInteger(
+      input?.maxDownloadBytes,
+      DEFAULT_MAX_DOWNLOAD_BYTES,
+      "maxDownloadBytes"
+    ),
+    maxReadBytes: positiveInteger(
+      input?.maxReadBytes,
+      DEFAULT_MAX_READ_BYTES,
+      "maxReadBytes"
+    ),
+    maxReadLines: positiveInteger(
+      input?.maxReadLines,
+      DEFAULT_MAX_READ_LINES,
+      "maxReadLines"
+    ),
+    maxExtractedFiles: positiveInteger(
+      input?.maxExtractedFiles,
+      0,
+      "maxExtractedFiles",
+      true
+    ),
+    maxExtractedBytes: positiveInteger(
+      input?.maxExtractedBytes,
+      0,
+      "maxExtractedBytes",
+      true
+    ),
+    downloadTimeoutMs: positiveInteger(
+      input?.downloadTimeoutMs,
+      DEFAULT_DOWNLOAD_TIMEOUT_MS,
+      "downloadTimeoutMs"
+    ),
+    allowedProtocols,
+    allowedHosts,
+    allowedUrlPrefixes,
+    zuoraDownloadHosts,
+    allowZuoraAuthenticatedDownload: input?.allowZuoraAuthenticatedDownload ?? false,
+    allowS3PresignedDownload: input?.allowS3PresignedDownload ?? true,
+    allowArchiveExtraction: input?.allowArchiveExtraction ?? false
+  };
+  if (!enabled) {
+    return config;
+  }
+  validateEnabledConfig(config);
+  return config;
+};
+var validateEnabledConfig = (config) => {
+  if (config.bundleName !== "query") {
+    throw nativeFileConfigError(
+      `Unsupported native file bundle: ${config.bundleName}. Only "query" is supported.`
+    );
+  }
+  if (!config.rootDir) {
+    throw nativeFileConfigError(
+      "nativeFileTools.rootDir is required when native file tools are enabled."
+    );
+  }
+  if (config.allowedHosts.length === 0 && config.allowedUrlPrefixes.length === 0) {
+    throw nativeFileConfigError(
+      "nativeFileTools.allowedHosts or nativeFileTools.allowedUrlPrefixes is required when native file tools are enabled."
+    );
+  }
+  for (const protocol of config.allowedProtocols) {
+    if (protocol !== "http:" && protocol !== "https:") {
+      throw nativeFileConfigError(
+        `Unsupported native file download protocol: ${protocol}. This MVP supports HTTP(S) only.`
+      );
+    }
+  }
+  if (config.allowedProtocols.length === 0) {
+    throw nativeFileConfigError(
+      "nativeFileTools.allowedProtocols must include at least one protocol."
+    );
+  }
+  if (config.requireRootUnderUserHome && !isPathInside(config.rootDirAbsolute, config.userHomeDirAbsolute)) {
+    throw nativeFileConfigError(
+      "nativeFileTools.rootDir must be under nativeFileTools.userHomeDir when requireRootUnderUserHome is true."
+    );
+  }
+  if (config.tools.readDownloadedFile.operationAccess !== "read") {
+    throw nativeFileConfigError(
+      'read_downloaded_file must be configured with operationAccess "read".'
+    );
+  }
+  if (config.tools.downloadFile.operationAccess !== "read") {
+    throw nativeFileConfigError(
+      'download_file must be configured with operationAccess "read".'
+    );
+  }
+  if (config.tools.extractDownloadedArchive.operationAccess !== "read") {
+    throw nativeFileConfigError(
+      'extract_downloaded_archive must be configured with operationAccess "read".'
+    );
+  }
+  for (const prefix of config.allowedUrlPrefixes) {
+    validateConfiguredPrefix(prefix);
+  }
+  if (config.allowZuoraAuthenticatedDownload) {
+    throw nativeFileConfigError(
+      "Authenticated Zuora file downloads are not supported by the native file tools MVP. Use public or presigned HTTPS links."
+    );
+  }
+  if (config.allowArchiveExtraction) {
+    throw nativeFileConfigError(
+      "Archive extraction is not supported by the native file tools MVP."
+    );
+  }
+};
+var normalizeProtocols = (values) => {
+  const protocols = normalizeStringList(values ?? ["https:"]).map((value) => {
+    const normalized = value.toLowerCase();
+    return normalized.endsWith(":") ? normalized : `${normalized}:`;
+  });
+  return [...new Set(protocols)];
+};
+var normalizeStringList = (values) => [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))];
+var positiveInteger = (value, fallback, name, allowZero = false) => {
+  const candidate = value ?? fallback;
+  const minimum = allowZero ? 0 : 1;
+  if (!Number.isInteger(candidate) || candidate < minimum) {
+    throw nativeFileConfigError(
+      `nativeFileTools.${name} must be ${allowZero ? "zero or " : ""}a positive integer.`
+    );
+  }
+  return candidate;
+};
+var validateConfiguredPrefix = (prefix) => {
+  let parsed;
+  try {
+    parsed = new URL(prefix);
+  } catch {
+    throw nativeFileConfigError(
+      `Invalid native file allowedUrlPrefixes entry: ${prefix}`
+    );
+  }
+  if (parsed.username || parsed.password) {
+    throw nativeFileConfigError(
+      "nativeFileTools.allowedUrlPrefixes entries must not include URL userinfo."
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw nativeFileConfigError(
+      "nativeFileTools.allowedUrlPrefixes entries must use HTTP(S)."
+    );
+  }
+  if (!parsed.hostname) {
+    throw nativeFileConfigError(
+      "nativeFileTools.allowedUrlPrefixes entries must include a host."
+    );
+  }
+  if (parsed.search || parsed.hash) {
+    throw nativeFileConfigError(
+      "nativeFileTools.allowedUrlPrefixes entries must not include query strings or fragments."
+    );
+  }
+};
+var isPathInside = (candidate, root) => {
+  const relative = path.relative(root, candidate);
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+};
+var nativeFileConfigError = (message) => new ZuoraAgentToolkitError({
+  code: "NATIVE_FILE_CONFIG_INVALID",
+  message,
+  category: "configuration",
+  recoverable: true
+});
+
+// src/shared/tools/native/metadata.ts
+var nativeObjectSchema = (properties, required = []) => ({
+  type: "object",
+  properties,
+  required,
+  additionalProperties: false
+});
+
+// src/shared/tools/native/file-artifacts/definitions.ts
+var createDownloadFileToolDefinition = (config) => {
+  const toolConfig = config.tools.downloadFile;
+  return {
+    name: "download_file",
+    description: toolConfig.description ?? [
+      "Download a remote file into the configured local artifact folder.",
+      "Use this when the user asks to download, save, or fetch a file URL from prior tool output.",
+      "For presigned URLs, pass the exact raw URL including the full query string; do not use redacted, shortened, decoded, or assistant-summarized links.",
+      "If the URL appears in a field such as dataFile, resultUrl, downloadUrl, fileUrl, or href, use that field value exactly.",
+      "If the result requires confirmation, ask the user before retrying with overwrite:true."
+    ].join(" "),
+    inputSchema: nativeObjectSchema(
+      {
+        url: {
+          type: "string",
+          description: "Absolute HTTP(S) file URL. For presigned S3 or similar URLs, provide the exact original URL including every query parameter and signature token."
+        },
+        fileName: {
+          type: "string",
+          description: "Optional relative artifact file name under the configured artifact root."
+        },
+        overwrite: {
+          type: "boolean",
+          description: "Replace an existing local artifact at fileName. Set to true only after download_file returned requiresConfirmation:true and the user explicitly confirmed overwrite."
+        }
+      },
+      ["url"]
+    ),
+    outputSchema: nativeObjectSchema(
+      {
+        status: {
+          type: "string",
+          enum: [
+            "downloaded",
+            "existing",
+            "requires_confirmation",
+            "overwritten"
+          ]
+        },
+        message: { type: "string" },
+        requiresConfirmation: { type: "boolean" },
+        artifactId: { type: "string" },
+        path: { type: "string" },
+        bytes: { type: "number" },
+        existingBytes: { type: "number" },
+        remoteBytes: { type: "number" },
+        sha256: { type: "string" },
+        contentType: { type: "string" },
+        source: {
+          type: "object",
+          additionalProperties: true
+        }
+      },
+      ["status", "path", "source"]
+    ),
+    meta: {
+      bundle: config.bundleName,
+      access: toolConfig.operationAccess,
+      riskLevel: toolConfig.riskLevel,
+      requiredServicePermissions: [],
+      limitations: [],
+      sourceName: "download_file"
+    }
+  };
+};
+var createReadDownloadedFileToolDefinition = (config) => {
+  const toolConfig = config.tools.readDownloadedFile;
+  return {
+    name: "read_downloaded_file",
+    description: toolConfig.description ?? "Read bounded text content from a registered downloaded file artifact.",
+    inputSchema: nativeObjectSchema({
+      artifactId: {
+        type: "string",
+        description: "Artifact id returned by download_query_result or another native download tool."
+      },
+      path: {
+        type: "string",
+        description: "Relative artifact path from a prior download result. Used only when artifactId is omitted."
+      },
+      startLine: {
+        type: "number",
+        description: "One-based line number to start reading from."
+      },
+      maxLines: {
+        type: "number",
+        description: "Maximum number of text lines to return."
+      },
+      maxBytes: {
+        type: "number",
+        description: "Maximum number of bytes to inspect, capped by SDK config."
+      }
+    }),
+    outputSchema: nativeObjectSchema(
+      {
+        artifactId: { type: "string" },
+        path: { type: "string" },
+        content: { type: "string" },
+        startLine: { type: "number" },
+        endLine: { type: "number" },
+        linesReturned: { type: "number" },
+        bytesRead: { type: "number" },
+        truncated: { type: "boolean" }
+      },
+      [
+        "artifactId",
+        "path",
+        "content",
+        "startLine",
+        "linesReturned",
+        "bytesRead",
+        "truncated"
+      ]
+    ),
+    meta: {
+      bundle: config.bundleName,
+      access: toolConfig.operationAccess,
+      riskLevel: toolConfig.riskLevel,
+      requiredServicePermissions: [],
+      limitations: [
+        "Only files registered by this toolkit instance can be read.",
+        "Reads are bounded by configured byte and line limits.",
+        "Binary-looking files are rejected."
+      ],
+      sourceName: "read_downloaded_file"
+    }
+  };
+};
+var createReadResourceToolDefinition = (config, description) => {
+  return {
+    name: "read_resource",
+    description: description ?? "Read content from an MCP resource URI returned by Zuora tools. Use this to access files referenced via resourceUri (e.g., zuora://files/{fileId}) in tool results.",
+    inputSchema: nativeObjectSchema({
+      uri: {
+        type: "string",
+        description: "The MCP resource URI to read, typically in the format zuora://files/{fileId} or zuora://objects/{type}/{id}."
+      }
+    }),
+    outputSchema: nativeObjectSchema(
+      {
+        uri: { type: "string" },
+        mimeType: { type: "string" },
+        content: {
+          type: "string",
+          description: "Text content if the resource is text-based (JSON, XML, text)."
+        },
+        data: {
+          type: "string",
+          description: "Base64-encoded binary data if the resource is binary (PDF, images, etc.)."
+        }
+      },
+      ["uri", "mimeType"]
+    ),
+    meta: {
+      bundle: config.bundleName,
+      access: "read",
+      riskLevel: "low",
+      requiredServicePermissions: [],
+      limitations: [
+        "Resource URIs must be valid MCP resource URIs returned by Zuora tools.",
+        "Binary content is returned as base64-encoded data.",
+        "Resource availability depends on the underlying Zuora service."
+      ],
+      sourceName: "read_resource"
+    }
+  };
+};
+
+// src/shared/tools/native/file-artifacts/download-service.ts
+import { createHash, randomBytes } from "crypto";
+import fs2 from "fs/promises";
+import path3 from "path";
+
+// src/shared/tools/native/file-artifacts/errors.ts
+var nativeFileError = (params) => new ZuoraAgentToolkitError({
+  code: params.code,
+  message: params.message,
+  category: "native_file_tools",
+  ...params.retryable !== void 0 ? { retryable: params.retryable } : {},
+  recoverable: params.recoverable ?? true,
+  ...params.details !== void 0 ? { details: params.details } : {}
+});
+
+// src/shared/tools/native/file-artifacts/path-policy.ts
+import fs from "fs/promises";
+import path2 from "path";
+
+// src/shared/tools/native/file-artifacts/manifest.ts
+var FileArtifactManifest = class {
+  byId = /* @__PURE__ */ new Map();
+  byPath = /* @__PURE__ */ new Map();
+  register(record) {
+    this.byId.set(record.artifactId, record);
+    this.byPath.set(normalizeManifestPath(record.relativePath), record);
+    return record;
+  }
+  getById(artifactId) {
+    return this.byId.get(artifactId);
+  }
+  getByRelativePath(relativePath) {
+    return this.byPath.get(normalizeManifestPath(relativePath));
+  }
+};
+var normalizeManifestPath = (relativePath) => relativePath.replace(/\\/g, "/").replace(/^\/+/, "");
+
+// src/shared/tools/native/file-artifacts/path-policy.ts
+var resolveOutputRelativePath = (inputFileName, sourceUrl) => {
+  const requested = typeof inputFileName === "string" && inputFileName.trim() ? inputFileName.trim() : fallbackFileNameFromUrl(sourceUrl);
+  return normalizeSafeRelativePath(requested);
+};
+var resolveInputRelativePath = (inputPath) => {
+  if (typeof inputPath !== "string" || !inputPath.trim()) {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "A non-empty artifact path is required."
+    });
+  }
+  return normalizeSafeRelativePath(inputPath.trim());
+};
+var prepareOutputArtifactPath = async (config, relativePath, options = {}) => {
+  const rootRealPath = await prepareRoot(config);
+  const resolved = resolveUnderRoot(rootRealPath, relativePath);
+  await assertNoSymlinkComponents(rootRealPath, relativePath, {
+    includeLeaf: true,
+    missingLeafOk: true
+  });
+  try {
+    await fs.mkdir(path2.dirname(resolved.absolutePath), { recursive: true });
+  } catch (error) {
+    throw nativePathFilesystemError(
+      "Could not create the native file artifact output directory.",
+      error,
+      {
+        relativePath
+      }
+    );
+  }
+  await assertNoSymlinkComponents(rootRealPath, relativePath, {
+    includeLeaf: true,
+    missingLeafOk: true
+  });
+  if (!config.allowOverwrite && !options.allowExistingFile) {
+    try {
+      await fs.lstat(resolved.absolutePath);
+      throw nativeFileError({
+        code: "FILE_PATH_NOT_ALLOWED",
+        message: "download_file would overwrite an existing artifact and allowOverwrite is false.",
+        details: {
+          relativePath
+        }
+      });
+    } catch (error) {
+      if (isNodeErrorCode(error, "ENOENT")) {
+        return resolved;
+      }
+      if (error instanceof ZuoraAgentToolkitError) {
+        throw error;
+      }
+      throw nativePathFilesystemError(
+        "Could not inspect the native file artifact output path.",
+        error,
+        {
+          relativePath
+        }
+      );
+    }
+  }
+  return resolved;
+};
+var resolveRegisteredArtifactPath = async (config, relativePath) => {
+  const rootRealPath = await prepareRoot(config);
+  const resolved = resolveUnderRoot(rootRealPath, relativePath);
+  await assertNoSymlinkComponents(rootRealPath, relativePath, {
+    includeLeaf: true,
+    missingLeafOk: false
+  });
+  let realPath;
+  try {
+    realPath = await fs.realpath(resolved.absolutePath);
+  } catch (error) {
+    if (isNodeErrorCode(error, "ENOENT")) {
+      throw error;
+    }
+    throw nativePathFilesystemError(
+      "Could not resolve the registered native file artifact path.",
+      error,
+      {
+        relativePath
+      }
+    );
+  }
+  if (!isPathInside2(realPath, rootRealPath)) {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "Artifact path resolves outside the configured file artifact root.",
+      details: {
+        relativePath
+      }
+    });
+  }
+  return {
+    ...resolved,
+    absolutePath: realPath
+  };
+};
+var prepareRoot = async (config) => {
+  const userHomeRealPath = await resolveRealPathIfPossible(
+    config.userHomeDirAbsolute
+  );
+  const userHomeAbsolutePath = path2.resolve(config.userHomeDirAbsolute);
+  if (config.requireRootUnderUserHome && !isPathInside2(config.rootDirAbsolute, userHomeAbsolutePath)) {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "Configured native file artifact root resolves outside the configured user home directory.",
+      details: {
+        rootDir: config.rootDirAbsolute,
+        userHomeDir: config.userHomeDirAbsolute
+      }
+    });
+  }
+  if (config.requireRootUnderUserHome) {
+    await assertNoExistingSymlinkComponents(
+      userHomeAbsolutePath,
+      config.rootDirAbsolute
+    );
+  }
+  try {
+    await fs.mkdir(config.rootDirAbsolute, { recursive: true });
+  } catch (error) {
+    throw nativePathFilesystemError(
+      "Could not create the native file artifact root directory.",
+      error,
+      {
+        rootDir: config.rootDirAbsolute
+      }
+    );
+  }
+  let rootRealPath;
+  try {
+    rootRealPath = await fs.realpath(config.rootDirAbsolute);
+  } catch (error) {
+    throw nativePathFilesystemError(
+      "Could not resolve the native file artifact root directory.",
+      error,
+      {
+        rootDir: config.rootDirAbsolute
+      }
+    );
+  }
+  if (config.requireRootUnderUserHome && !isPathInside2(rootRealPath, userHomeRealPath)) {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "Configured native file artifact root resolves outside the configured user home directory.",
+      details: {
+        rootDir: config.rootDirAbsolute,
+        userHomeDir: config.userHomeDirAbsolute
+      }
+    });
+  }
+  return rootRealPath;
+};
+var resolveRealPathIfPossible = async (targetPath) => {
+  try {
+    return await fs.realpath(targetPath);
+  } catch {
+    return path2.resolve(targetPath);
+  }
+};
+var resolveUnderRoot = (rootRealPath, relativePath) => {
+  const normalizedRelativePath = normalizeSafeRelativePath(relativePath);
+  const absolutePath = path2.resolve(rootRealPath, normalizedRelativePath);
+  if (!isPathInside2(absolutePath, rootRealPath)) {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "Artifact path must stay under the configured file artifact root.",
+      details: {
+        relativePath: normalizedRelativePath
+      }
+    });
+  }
+  return {
+    rootRealPath,
+    absolutePath,
+    relativePath: normalizedRelativePath
+  };
+};
+var assertNoSymlinkComponents = async (rootRealPath, relativePath, options) => {
+  const components = normalizeManifestPath(relativePath).split("/").filter(Boolean);
+  const componentsToCheck = options.includeLeaf ? components : components.slice(0, -1);
+  let current = rootRealPath;
+  for (let index = 0; index < componentsToCheck.length; index += 1) {
+    current = path2.join(current, componentsToCheck[index]);
+    try {
+      const stat = await fs.lstat(current);
+      if (stat.isSymbolicLink()) {
+        throw nativeFileError({
+          code: "FILE_PATH_NOT_ALLOWED",
+          message: "File artifact paths must not traverse symlinks.",
+          details: {
+            relativePath
+          }
+        });
+      }
+    } catch (error) {
+      if (isNodeErrorCode(error, "ENOENT") && (options.missingLeafOk || index < componentsToCheck.length - 1)) {
+        return;
+      }
+      if (error instanceof ZuoraAgentToolkitError) {
+        throw error;
+      }
+      throw nativePathFilesystemError(
+        "Could not inspect native file artifact path components.",
+        error,
+        {
+          relativePath
+        }
+      );
+    }
+  }
+};
+var assertNoExistingSymlinkComponents = async (rootRealPath, candidatePath) => {
+  const relative = path2.relative(rootRealPath, candidatePath);
+  if (relative === "") {
+    return;
+  }
+  if (relative.startsWith("..") || path2.isAbsolute(relative)) {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "Configured native file artifact root must stay under user home.",
+      details: {
+        rootDir: candidatePath,
+        userHomeDir: rootRealPath
+      }
+    });
+  }
+  await assertNoSymlinkComponents(rootRealPath, relative, {
+    includeLeaf: true,
+    missingLeafOk: true
+  });
+};
+var normalizeSafeRelativePath = (rawPath) => {
+  if (rawPath.includes("\0")) {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "Artifact paths must not contain null bytes."
+    });
+  }
+  const slashPath = rawPath.replace(/\\/g, "/");
+  if (path2.isAbsolute(slashPath) || slashPath.startsWith("/")) {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "Artifact paths must be relative.",
+      details: {
+        relativePath: rawPath
+      }
+    });
+  }
+  const normalized = normalizeManifestPath(path2.posix.normalize(slashPath));
+  if (!normalized || normalized === ".") {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "Artifact paths must not be empty."
+    });
+  }
+  if (normalized === ".." || normalized.startsWith("../") || normalized.split("/").includes("..")) {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "Artifact paths must not traverse outside the artifact root.",
+      details: {
+        relativePath: rawPath
+      }
+    });
+  }
+  return normalized;
+};
+var fallbackFileNameFromUrl = (url) => {
+  const rawBaseName = path2.posix.basename(url.pathname) || "downloaded-file";
+  const decodedBaseName = safeDecodeURIComponent(rawBaseName);
+  const sanitized = decodedBaseName.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");
+  return sanitized || "downloaded-file";
+};
+var safeDecodeURIComponent = (value) => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+var isPathInside2 = (candidate, root) => {
+  const relative = path2.relative(root, candidate);
+  return relative === "" || !relative.startsWith("..") && !path2.isAbsolute(relative);
+};
+var isNodeErrorCode = (error, code) => typeof error === "object" && error !== null && "code" in error && error.code === code;
+var nativePathFilesystemError = (message, error, details) => nativeFileError({
+  code: "FILE_PATH_NOT_ALLOWED",
+  message,
+  recoverable: true,
+  details: {
+    ...details,
+    cause: error instanceof Error ? error.message : String(error)
+  }
+});
+
+// src/shared/tools/native/file-artifacts/url-policy.ts
+var validateDownloadUrl = (rawUrl, config) => {
+  if (typeof rawUrl !== "string" || !rawUrl.trim()) {
+    throw nativeFileError({
+      code: "FILE_URL_INVALID",
+      message: "download_file requires a non-empty absolute URL.",
+      details: {
+        expected: "absolute HTTP(S) URL"
+      }
+    });
+  }
+  let url;
+  try {
+    url = new URL(rawUrl.trim());
+  } catch {
+    throw nativeFileError({
+      code: "FILE_URL_INVALID",
+      message: "download_file received an invalid URL.",
+      details: {
+        expected: "absolute HTTP(S) URL"
+      }
+    });
+  }
+  return validateParsedDownloadUrl(url, config);
+};
+var validateRedirectUrl = (rawUrl, baseUrl, config) => {
+  let url;
+  try {
+    url = new URL(rawUrl, baseUrl);
+  } catch {
+    throw nativeFileError({
+      code: "FILE_URL_INVALID",
+      message: "Download redirect returned an invalid URL.",
+      details: {
+        source: safeSourceFromUrl(baseUrl, config)
+      }
+    });
+  }
+  return validateParsedDownloadUrl(url, config);
+};
+var redactUrl = (url) => {
+  const redacted = new URL(url.toString());
+  redacted.username = "";
+  redacted.password = "";
+  redacted.search = "";
+  redacted.hash = "";
+  return redacted.toString();
+};
+var validateParsedDownloadUrl = (url, config) => {
+  if (!url.protocol || !url.hostname) {
+    throw nativeFileError({
+      code: "FILE_URL_INVALID",
+      message: "download_file requires an absolute URL with a host."
+    });
+  }
+  if (url.username || url.password) {
+    throw nativeFileError({
+      code: "FILE_URL_INVALID",
+      message: "download_file rejects URLs with embedded credentials.",
+      details: {
+        source: safeSourceFromUrl(url, config)
+      }
+    });
+  }
+  if (!config.allowedProtocols.includes(url.protocol)) {
+    throw nativeFileError({
+      code: "FILE_URL_NOT_ALLOWED",
+      message: `URL protocol ${url.protocol} is not allowed for native file downloads.`,
+      details: {
+        source: safeSourceFromUrl(url, config),
+        allowedProtocols: config.allowedProtocols
+      }
+    });
+  }
+  if (!hostAllowed(url, config) && !prefixMatches(url, config.allowedUrlPrefixes)) {
+    throw nativeFileError({
+      code: "FILE_URL_NOT_ALLOWED",
+      message: "URL host or prefix is not allowed for native file downloads.",
+      details: {
+        source: safeSourceFromUrl(url, config)
+      }
+    });
+  }
+  return {
+    url,
+    source: safeSourceFromUrl(url, config)
+  };
+};
+var safeSourceFromUrl = (url, config) => ({
+  protocol: url.protocol,
+  host: url.host.toLowerCase(),
+  path: url.pathname,
+  redactedUrl: redactUrl(url),
+  kind: classifySource(url, config)
+});
+var classifySource = (url, config) => {
+  const host = url.hostname.toLowerCase();
+  if (config.zuoraDownloadHosts.includes(host)) {
+    return "zuora-public";
+  }
+  if (config.allowS3PresignedDownload && (host.includes(".s3.") || host.endsWith(".s3.amazonaws.com") || host.endsWith(".amazonaws.com")) && hasPresignedUrlQuery(url)) {
+    return "s3-presigned";
+  }
+  return "http";
+};
+var hasPresignedUrlQuery = (url) => {
+  for (const key of url.searchParams.keys()) {
+    if (/^(x-amz-|x-goog-|signature|sig|expires|token)/i.test(key)) {
+      return true;
+    }
+  }
+  return false;
+};
+var hostAllowed = (url, config) => hostMatches(url.host, config.allowedHosts) || hostMatches(url.hostname, config.allowedHosts) || s3VirtualHostedEndpointMatches(url, config);
+var hostMatches = (host, allowedHosts) => {
+  const normalizedHost = host.toLowerCase();
+  return allowedHosts.some((allowedHost) => {
+    const normalizedAllowedHost = allowedHost.toLowerCase();
+    if (normalizedAllowedHost.startsWith("*.")) {
+      const suffix = normalizedAllowedHost.slice(1);
+      return normalizedHost.length > suffix.length && normalizedHost.endsWith(suffix);
+    }
+    return normalizedHost === normalizedAllowedHost;
+  });
+};
+var s3VirtualHostedEndpointMatches = (url, config) => {
+  if (!config.allowS3PresignedDownload || !hasPresignedUrlQuery(url)) {
+    return false;
+  }
+  const host = url.hostname.toLowerCase();
+  return config.allowedHosts.some((allowedHost) => {
+    const normalizedAllowedHost = allowedHost.toLowerCase();
+    return isS3RegionalEndpointHost(normalizedAllowedHost) && host.length > normalizedAllowedHost.length + 1 && host.endsWith(`.${normalizedAllowedHost}`);
+  });
+};
+var isS3RegionalEndpointHost = (host) => host === "s3.amazonaws.com" || /^s3[.-][a-z0-9-]+\.amazonaws\.com$/.test(host);
+var prefixMatches = (url, allowedPrefixes) => allowedPrefixes.some((prefix) => {
+  let allowedUrl;
+  try {
+    allowedUrl = new URL(prefix);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== allowedUrl.protocol) {
+    return false;
+  }
+  if (url.host.toLowerCase() !== allowedUrl.host.toLowerCase()) {
+    return false;
+  }
+  return pathPrefixMatches(url.pathname, allowedUrl.pathname);
+});
+var pathPrefixMatches = (pathName, allowedPathName) => {
+  if (!allowedPathName || allowedPathName === "/") {
+    return true;
+  }
+  const normalizedAllowedPath = allowedPathName.endsWith("/") ? allowedPathName : `${allowedPathName}/`;
+  return pathName === allowedPathName || pathName.startsWith(normalizedAllowedPath);
+};
+
+// src/shared/tools/native/file-artifacts/download-service.ts
+var MAX_REDIRECTS = 5;
+var MAX_GUIDED_DOWNLOAD_FAILURE_ATTEMPTS = 3;
+var PRESIGNED_URL_403_GUIDANCE = "For presigned S3 or similar URLs, provide the exact original URL including every query parameter and signature token. A 403 usually means the URL was stripped, edited, expired, or the signature no longer matches.";
+var NativeFileDownloadService = class {
+  constructor(serviceConfig) {
+    this.serviceConfig = serviceConfig;
+  }
+  serviceConfig;
+  /**
+   * Per-instance failure counter for guided download retries.
+   * Kept as an instance field (not a module-level singleton) so that
+   * different toolkit instances and multi-tenant server contexts do not
+   * share failure state with each other.
+   */
+  guidedDownloadFailureAttempts = /* @__PURE__ */ new Map();
+  async downloadFile(input) {
+    const { config } = this.serviceConfig;
+    const validatedUrl = validateDownloadUrl(input.url, config);
+    const overwrite = readOverwriteInput(input.overwrite);
+    const artifactId = createArtifactId();
+    const relativePath = resolveOutputRelativePath(
+      input.fileName ?? `${artifactId}-${fallbackFileNameForExecution(validatedUrl.url)}`,
+      validatedUrl.url
+    );
+    const outputPath = await prepareOutputArtifactPath(config, relativePath, {
+      allowExistingFile: true
+    });
+    const existingFile = await inspectExistingOutputFile(outputPath);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+      controller.abort();
+    }, config.downloadTimeoutMs);
+    try {
+      const { response, source } = await fetchAllowedResponse(
+        validatedUrl,
+        config,
+        controller.signal,
+        this.guidedDownloadFailureAttempts
+      );
+      const contentType = response.headers.get("content-type") ?? void 0;
+      const contentLengthBytes = readContentLengthBytes(response);
+      if (Number.isFinite(contentLengthBytes) && contentLengthBytes > config.maxDownloadBytes) {
+        throw createDownloadTooLargeError({
+          contentLengthBytes,
+          maxDownloadBytes: config.maxDownloadBytes
+        });
+      }
+      if (existingFile && !overwrite && Number.isFinite(contentLengthBytes) && existingFile.bytes === contentLengthBytes) {
+        await cancelResponseBody(response);
+        const artifact2 = await this.registerExistingArtifact({
+          artifactId,
+          outputPath,
+          bytes: existingFile.bytes,
+          contentType,
+          source
+        });
+        return {
+          toolName: "download_file",
+          riskLevel: config.tools.downloadFile.riskLevel,
+          data: downloadOutput(artifact2, {
+            status: "existing",
+            message: "Local file already exists with the same size. The download was skipped and the existing file was registered as an artifact."
+          })
+        };
+      }
+      if (existingFile && !overwrite && Number.isFinite(contentLengthBytes) && existingFile.bytes !== contentLengthBytes) {
+        await cancelResponseBody(response);
+        return {
+          toolName: "download_file",
+          riskLevel: config.tools.downloadFile.riskLevel,
+          data: existingFileRequiresConfirmationOutput({
+            outputPath,
+            source,
+            existingBytes: existingFile.bytes,
+            remoteBytes: contentLengthBytes
+          })
+        };
+      }
+      const body = await readBoundedResponseBody(response, config);
+      const sha256 = createHash("sha256").update(body).digest("hex");
+      if (existingFile && !overwrite) {
+        if (existingFile.bytes === body.byteLength) {
+          const artifact2 = await this.registerExistingArtifact({
+            artifactId,
+            outputPath,
+            bytes: existingFile.bytes,
+            contentType,
+            source
+          });
+          return {
+            toolName: "download_file",
+            riskLevel: config.tools.downloadFile.riskLevel,
+            data: downloadOutput(artifact2, {
+              status: "existing",
+              message: "Local file already exists with the same size. The download was skipped and the existing file was registered as an artifact."
+            })
+          };
+        }
+        return {
+          toolName: "download_file",
+          riskLevel: config.tools.downloadFile.riskLevel,
+          data: existingFileRequiresConfirmationOutput({
+            outputPath,
+            source,
+            existingBytes: existingFile.bytes,
+            remoteBytes: body.byteLength
+          })
+        };
+      }
+      try {
+        await fs2.writeFile(outputPath.absolutePath, body, {
+          flag: overwrite ? "w" : "wx"
+        });
+      } catch (error) {
+        if (isNodeErrorCode2(error, "EEXIST")) {
+          const racedExistingFile = await inspectExistingOutputFile(outputPath);
+          if (racedExistingFile?.bytes === body.byteLength) {
+            const artifact2 = await this.registerExistingArtifact({
+              artifactId,
+              outputPath,
+              bytes: racedExistingFile.bytes,
+              contentType,
+              source
+            });
+            return {
+              toolName: "download_file",
+              riskLevel: config.tools.downloadFile.riskLevel,
+              data: downloadOutput(artifact2, {
+                status: "existing",
+                message: "Local file already exists with the same size. The download was skipped and the existing file was registered as an artifact."
+              })
+            };
+          }
+          return {
+            toolName: "download_file",
+            riskLevel: config.tools.downloadFile.riskLevel,
+            data: existingFileRequiresConfirmationOutput({
+              outputPath,
+              source,
+              existingBytes: racedExistingFile?.bytes,
+              remoteBytes: body.byteLength
+            })
+          };
+        }
+        throw nativeFilesystemError(
+          "FILE_DOWNLOAD_FAILED",
+          "download_file could not write the local artifact.",
+          error,
+          {
+            relativePath: outputPath.relativePath
+          }
+        );
+      }
+      const artifact = this.serviceConfig.manifest.register({
+        artifactId,
+        relativePath: outputPath.relativePath,
+        bytes: body.byteLength,
+        sha256,
+        ...contentType ? { contentType } : {},
+        source,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return {
+        toolName: "download_file",
+        riskLevel: config.tools.downloadFile.riskLevel,
+        data: downloadOutput(artifact, {
+          status: existingFile && overwrite ? "overwritten" : "downloaded",
+          message: existingFile && overwrite ? "Existing local file was overwritten after overwrite:true." : "Remote file was downloaded into the local artifact root."
+        })
+      };
+    } catch (error) {
+      if (isAbortError(error)) {
+        throw nativeFileError({
+          code: "FILE_DOWNLOAD_TIMEOUT",
+          message: `download_file exceeded ${config.downloadTimeoutMs}ms.`,
+          retryable: true,
+          recoverable: true
+        });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  async persistBufferedDownload({
+    input,
+    toolName,
+    riskLevel,
+    body,
+    contentType,
+    source,
+    defaultFileName
+  }) {
+    const { config } = this.serviceConfig;
+    if (body.byteLength > config.maxDownloadBytes) {
+      throw createDownloadTooLargeError({
+        contentLengthBytes: body.byteLength,
+        maxDownloadBytes: config.maxDownloadBytes
+      });
+    }
+    const overwrite = readOverwriteInput(input.overwrite);
+    const artifactId = createArtifactId();
+    const relativePath = resolveOutputRelativePath(
+      input.fileName ?? defaultFileName,
+      new URL(`https://zuora.local/${encodeURIComponent(defaultFileName)}`)
+    );
+    const outputPath = await prepareOutputArtifactPath(config, relativePath, {
+      allowExistingFile: true
+    });
+    const existingFile = await inspectExistingOutputFile(outputPath);
+    const remoteBytes = body.byteLength;
+    if (existingFile && !overwrite && existingFile.bytes === remoteBytes) {
+      const artifact2 = await this.registerExistingArtifact({
+        artifactId,
+        outputPath,
+        bytes: existingFile.bytes,
+        contentType,
+        source
+      });
+      return {
+        toolName,
+        riskLevel,
+        data: downloadOutput(artifact2, {
+          status: "existing",
+          message: "Local file already exists with the same size. The download was skipped and the existing file was registered as an artifact."
+        })
+      };
+    }
+    if (existingFile && !overwrite && existingFile.bytes !== remoteBytes) {
+      return {
+        toolName,
+        riskLevel,
+        data: existingFileRequiresConfirmationOutput({
+          outputPath,
+          source,
+          existingBytes: existingFile.bytes,
+          remoteBytes
+        })
+      };
+    }
+    const sha256 = createHash("sha256").update(body).digest("hex");
+    try {
+      await fs2.writeFile(outputPath.absolutePath, body, {
+        flag: overwrite ? "w" : "wx"
+      });
+    } catch (error) {
+      if (isNodeErrorCode2(error, "EEXIST")) {
+        const racedExistingFile = await inspectExistingOutputFile(outputPath);
+        if (racedExistingFile?.bytes === body.byteLength) {
+          const artifact2 = await this.registerExistingArtifact({
+            artifactId,
+            outputPath,
+            bytes: racedExistingFile.bytes,
+            contentType,
+            source
+          });
+          return {
+            toolName,
+            riskLevel,
+            data: downloadOutput(artifact2, {
+              status: "existing",
+              message: "Local file already exists with the same size. The download was skipped and the existing file was registered as an artifact."
+            })
+          };
+        }
+        return {
+          toolName,
+          riskLevel,
+          data: existingFileRequiresConfirmationOutput({
+            outputPath,
+            source,
+            existingBytes: racedExistingFile?.bytes,
+            remoteBytes: body.byteLength
+          })
+        };
+      }
+      throw nativeFilesystemError(
+        "FILE_DOWNLOAD_FAILED",
+        `${toolName} could not write the local artifact.`,
+        error,
+        {
+          relativePath: outputPath.relativePath
+        }
+      );
+    }
+    const artifact = this.serviceConfig.manifest.register({
+      artifactId,
+      relativePath: outputPath.relativePath,
+      bytes: body.byteLength,
+      sha256,
+      ...contentType ? { contentType } : {},
+      source,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    return {
+      toolName,
+      riskLevel,
+      data: downloadOutput(artifact, {
+        status: existingFile && overwrite ? "overwritten" : "downloaded",
+        message: existingFile && overwrite ? "Existing local file was overwritten after overwrite:true." : "Remote file was downloaded into the local artifact root."
+      })
+    };
+  }
+  async registerExistingArtifact({
+    artifactId,
+    outputPath,
+    bytes,
+    contentType,
+    source
+  }) {
+    const sha256 = await sha256File(outputPath.absolutePath);
+    return this.serviceConfig.manifest.register({
+      artifactId,
+      relativePath: outputPath.relativePath,
+      bytes,
+      sha256,
+      ...contentType ? { contentType } : {},
+      source,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+};
+var fetchAllowedResponse = async (initialUrl, config, signal, failureAttempts) => {
+  let currentUrl = initialUrl;
+  for (let redirectCount = 0; redirectCount <= MAX_REDIRECTS; redirectCount += 1) {
+    let response;
+    try {
+      response = await fetch(currentUrl.url, {
+        redirect: "manual",
+        signal
+      });
+    } catch (error) {
+      if (isAbortError(error)) {
+        throw error;
+      }
+      throw nativeFileError({
+        code: "FILE_DOWNLOAD_FAILED",
+        message: "download_file could not open the remote URL.",
+        retryable: true,
+        recoverable: true,
+        details: {
+          source: currentUrl.source,
+          cause: error instanceof Error ? error.message : String(error)
+        }
+      });
+    }
+    if (isRedirectResponse(response.status)) {
+      const location = response.headers.get("location");
+      if (!location) {
+        throw nativeFileError({
+          code: "FILE_DOWNLOAD_FAILED",
+          message: "Download redirect response did not include a location.",
+          retryable: true,
+          recoverable: true,
+          details: {
+            source: currentUrl.source,
+            status: response.status
+          }
+        });
+      }
+      currentUrl = validateRedirectUrl(location, currentUrl.url, config);
+      continue;
+    }
+    if (!response.ok) {
+      const failure = recordGuidedDownloadFailure(currentUrl.source, response.status, failureAttempts);
+      const guidance = downloadFailureGuidance(response.status, failure.attempt);
+      throw nativeFileError({
+        code: "FILE_DOWNLOAD_FAILED",
+        message: guidance ? `Download failed with HTTP status ${response.status}. ${guidance}` : `Download failed with HTTP status ${response.status}.`,
+        retryable: response.status >= 500,
+        recoverable: guidance ? failure.shouldRetry : true,
+        details: {
+          source: currentUrl.source,
+          status: response.status,
+          downloadAttempt: failure.attempt,
+          maxSuggestedAttempts: MAX_GUIDED_DOWNLOAD_FAILURE_ATTEMPTS,
+          ...guidance ? { guidance } : {}
+        }
+      });
+    }
+    clearGuidedDownloadFailure(currentUrl.source, failureAttempts);
+    return {
+      response,
+      source: currentUrl.source
+    };
+  }
+  throw nativeFileError({
+    code: "FILE_DOWNLOAD_FAILED",
+    message: `Download exceeded ${MAX_REDIRECTS} redirects.`,
+    recoverable: true,
+    details: {
+      source: initialUrl.source
+    }
+  });
+};
+var recordGuidedDownloadFailure = (source, status, failureAttempts) => {
+  const key = guidedDownloadFailureKey(source, status);
+  const attempt = (failureAttempts.get(key) ?? 0) + 1;
+  failureAttempts.set(key, attempt);
+  return {
+    attempt,
+    shouldRetry: attempt < MAX_GUIDED_DOWNLOAD_FAILURE_ATTEMPTS
+  };
+};
+var clearGuidedDownloadFailure = (source, failureAttempts) => {
+  failureAttempts.delete(guidedDownloadFailureKey(source, 403));
+};
+var guidedDownloadFailureKey = (source, status) => `${status}:${source.redactedUrl}`;
+var downloadFailureGuidance = (status, attempt) => {
+  if (status !== 403) {
+    return void 0;
+  }
+  if (attempt >= MAX_GUIDED_DOWNLOAD_FAILURE_ATTEMPTS) {
+    return `${PRESIGNED_URL_403_GUIDANCE} This is the third failed attempt for this download, so stop retrying this URL and ask the user for a fresh exact dataFile URL or to rerun the query.`;
+  }
+  return `${PRESIGNED_URL_403_GUIDANCE} Retry only with the exact dataFile/download URL from the tool result. Stop retrying after ${MAX_GUIDED_DOWNLOAD_FAILURE_ATTEMPTS} failed attempts.`;
+};
+var readBoundedResponseBody = async (response, config) => {
+  const contentLengthBytes = readContentLengthBytes(response);
+  if (Number.isFinite(contentLengthBytes) && contentLengthBytes > config.maxDownloadBytes) {
+    throw createDownloadTooLargeError({
+      contentLengthBytes,
+      maxDownloadBytes: config.maxDownloadBytes
+    });
+  }
+  if (!response.body) {
+    return Buffer.alloc(0);
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let totalBytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    totalBytes += value.byteLength;
+    if (totalBytes > config.maxDownloadBytes) {
+      throw nativeFileError({
+        code: "FILE_DOWNLOAD_TOO_LARGE",
+        message: `Remote file exceeded the configured ${config.maxDownloadBytes} byte download limit.`,
+        recoverable: true,
+        details: {
+          maxDownloadBytes: config.maxDownloadBytes
+        }
+      });
+    }
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks, totalBytes);
+};
+var readContentLengthBytes = (response) => {
+  const contentLength = response.headers.get("content-length");
+  if (!contentLength) {
+    return Number.NaN;
+  }
+  const parsed = Number.parseInt(contentLength, 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : Number.NaN;
+};
+var createDownloadTooLargeError = ({
+  contentLengthBytes,
+  maxDownloadBytes
+}) => nativeFileError({
+  code: "FILE_DOWNLOAD_TOO_LARGE",
+  message: `Remote file is larger than the configured ${maxDownloadBytes} byte download limit.`,
+  recoverable: true,
+  details: {
+    contentLengthBytes,
+    maxDownloadBytes
+  }
+});
+var cancelResponseBody = async (response) => {
+  try {
+    await response.body?.cancel();
+  } catch {
+  }
+};
+var readOverwriteInput = (value) => {
+  if (value === void 0) {
+    return false;
+  }
+  if (typeof value !== "boolean") {
+    throw nativeFileError({
+      code: "FILE_PATH_NOT_ALLOWED",
+      message: "download_file overwrite must be a boolean.",
+      recoverable: true
+    });
+  }
+  return value;
+};
+var inspectExistingOutputFile = async (outputPath) => {
+  try {
+    const stat = await fs2.stat(outputPath.absolutePath);
+    if (!stat.isFile()) {
+      throw nativeFileError({
+        code: "FILE_PATH_NOT_ALLOWED",
+        message: "download_file output path already exists and is not a file.",
+        recoverable: true,
+        details: {
+          relativePath: outputPath.relativePath
+        }
+      });
+    }
+    return {
+      bytes: stat.size
+    };
+  } catch (error) {
+    if (isNodeErrorCode2(error, "ENOENT")) {
+      return void 0;
+    }
+    if (error instanceof ZuoraAgentToolkitError) {
+      throw error;
+    }
+    throw nativeFilesystemError(
+      "FILE_PATH_NOT_ALLOWED",
+      "Could not inspect the native file artifact output path.",
+      error,
+      {
+        relativePath: outputPath.relativePath
+      }
+    );
+  }
+};
+var sha256File = async (absolutePath) => {
+  const body = await fs2.readFile(absolutePath);
+  return createHash("sha256").update(body).digest("hex");
+};
+var downloadOutput = (artifact, metadata) => ({
+  status: metadata.status,
+  message: metadata.message,
+  requiresConfirmation: false,
+  artifactId: artifact.artifactId,
+  path: artifact.relativePath,
+  bytes: artifact.bytes,
+  sha256: artifact.sha256,
+  ...artifact.contentType ? { contentType: artifact.contentType } : {},
+  source: artifact.source
+});
+var existingFileRequiresConfirmationOutput = ({
+  outputPath,
+  source,
+  existingBytes,
+  remoteBytes
+}) => ({
+  status: "requires_confirmation",
+  message: "Local file already exists with a different size. Ask the user whether to overwrite it, then retry download_file with the same url, same fileName, and overwrite:true only if the user confirms.",
+  requiresConfirmation: true,
+  path: outputPath.relativePath,
+  ...typeof existingBytes === "number" ? { existingBytes } : {},
+  remoteBytes,
+  source
+});
+var createArtifactId = () => `artifact_${Date.now().toString(36)}_${randomBytes(6).toString("hex")}`;
+var fallbackFileNameForExecution = (url) => {
+  const rawBaseName = path3.posix.basename(url.pathname) || "downloaded-file";
+  try {
+    return decodeURIComponent(rawBaseName);
+  } catch {
+    return rawBaseName;
+  }
+};
+var isRedirectResponse = (status) => status >= 300 && status < 400;
+var isAbortError = (error) => error instanceof Error && error.name === "AbortError";
+var isNodeErrorCode2 = (error, code) => typeof error === "object" && error !== null && "code" in error && error.code === code;
+var nativeFilesystemError = (code, message, error, details) => nativeFileError({
+  code,
+  message,
+  recoverable: true,
+  details: {
+    ...details,
+    cause: error instanceof Error ? error.message : String(error)
+  }
+});
+
+// src/shared/tools/native/file-artifacts/helpers.ts
+import fs3 from "fs/promises";
+var readFilePrefix = async (absolutePath, maxBytes) => {
+  const handle = await fs3.open(absolutePath, "r");
+  try {
+    const buffer = Buffer.alloc(maxBytes + 1);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    const boundedBytes = Math.min(bytesRead, maxBytes);
+    return {
+      buffer: buffer.subarray(0, boundedBytes),
+      bytesRead: boundedBytes,
+      truncatedByBytes: bytesRead > maxBytes
+    };
+  } finally {
+    await handle.close();
+  }
+};
+var capPositiveInteger = (value, fallback, maximum, name) => {
+  if (value === void 0) {
+    return fallback;
+  }
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw nativeFileError({
+      code: "FILE_READ_TOO_LARGE",
+      message: `read_downloaded_file ${name} must be a positive integer.`,
+      recoverable: true
+    });
+  }
+  return Math.min(value, maximum);
+};
+var looksBinary = (buffer) => buffer.includes(0);
+var isNodeErrorCode3 = (error, code) => typeof error === "object" && error !== null && "code" in error && error.code === code;
+var nativeFilesystemError2 = (code, message, error, details) => nativeFileError({
+  code,
+  message,
+  recoverable: true,
+  details: {
+    ...details,
+    cause: error instanceof Error ? error.message : String(error)
+  }
+});
+
+// src/shared/tools/native/registry-source.ts
+var createNativeRuntimeTool = ({
+  definition,
+  execute,
+  approvalMetadata = () => void 0
+}) => ({
+  definition,
+  execute,
+  approvalMetadata
+});
+
+// src/shared/tools/native/file-artifacts/index.ts
+var NativeFileArtifactTools = class {
+  config;
+  manifest = new FileArtifactManifest();
+  downloadService;
+  mcpClient;
+  constructor(config, options = {}) {
+    this.config = resolveNativeFileToolsConfig(config);
+    this.mcpClient = options.mcpClient;
+    this.downloadService = new NativeFileDownloadService({
+      config: this.config,
+      manifest: this.manifest
+    });
+  }
+  listTools() {
+    if (!this.config.enabled) {
+      return [];
+    }
+    return [
+      ...this.config.tools.downloadFile.enabled ? [this.createDownloadFileTool()] : [],
+      ...this.config.tools.readDownloadedFile.enabled ? [this.createReadDownloadedFileTool()] : [],
+      ...this.config.tools.readResource.enabled ? [this.createReadResourceTool()] : []
+    ];
+  }
+  isEnabled() {
+    return this.config.enabled;
+  }
+  createDownloadFileTool() {
+    return createNativeRuntimeTool({
+      definition: createDownloadFileToolDefinition(this.config),
+      execute: (input) => this.downloadFile(input),
+      approvalMetadata: (input) => this.createDownloadApprovalMetadata(input)
+    });
+  }
+  createReadDownloadedFileTool() {
+    return createNativeRuntimeTool({
+      definition: createReadDownloadedFileToolDefinition(this.config),
+      execute: (input) => this.readDownloadedFile(input),
+      approvalMetadata: (input) => this.createReadApprovalMetadata(input)
+    });
+  }
+  createReadResourceTool() {
+    return createNativeRuntimeTool({
+      definition: createReadResourceToolDefinition(this.config),
+      execute: (input) => this.readResource(input)
+    });
+  }
+  async downloadFile(input) {
+    return this.downloadService.downloadFile(input);
+  }
+  async persistBufferedDownload(options) {
+    return this.downloadService.persistBufferedDownload(options);
+  }
+  async readDownloadedFile(input) {
+    const artifact = this.resolveArtifact(input);
+    const maxBytes = capPositiveInteger(
+      input.maxBytes,
+      this.config.maxReadBytes,
+      this.config.maxReadBytes,
+      "maxBytes"
+    );
+    const maxLines = capPositiveInteger(
+      input.maxLines,
+      this.config.maxReadLines,
+      this.config.maxReadLines,
+      "maxLines"
+    );
+    const startLine = capPositiveInteger(
+      input.startLine,
+      1,
+      Number.MAX_SAFE_INTEGER,
+      "startLine"
+    );
+    let artifactPath;
+    try {
+      artifactPath = await resolveRegisteredArtifactPath(
+        this.config,
+        artifact.relativePath
+      );
+    } catch (error) {
+      if (isNodeErrorCode3(error, "ENOENT")) {
+        throw nativeFileError({
+          code: "FILE_ARTIFACT_NOT_FOUND",
+          message: "The registered artifact file no longer exists.",
+          details: {
+            artifactId: artifact.artifactId,
+            path: artifact.relativePath
+          }
+        });
+      }
+      throw error;
+    }
+    let filePrefix;
+    try {
+      filePrefix = await readFilePrefix(artifactPath.absolutePath, maxBytes);
+    } catch (error) {
+      if (isNodeErrorCode3(error, "ENOENT")) {
+        throw nativeFileError({
+          code: "FILE_ARTIFACT_NOT_FOUND",
+          message: "The registered artifact file no longer exists.",
+          details: {
+            artifactId: artifact.artifactId,
+            path: artifact.relativePath
+          }
+        });
+      }
+      throw nativeFilesystemError2(
+        "FILE_PATH_NOT_ALLOWED",
+        "read_downloaded_file could not read the local artifact.",
+        error,
+        {
+          artifactId: artifact.artifactId,
+          path: artifact.relativePath
+        }
+      );
+    }
+    const { buffer, bytesRead, truncatedByBytes } = filePrefix;
+    if (looksBinary(buffer)) {
+      throw nativeFileError({
+        code: "FILE_PATH_NOT_ALLOWED",
+        message: "read_downloaded_file only supports text-like artifacts.",
+        recoverable: true,
+        details: {
+          artifactId: artifact.artifactId,
+          path: artifact.relativePath
+        }
+      });
+    }
+    const text = buffer.toString("utf8");
+    const lines = text.split(/\r?\n/);
+    const startIndex = startLine - 1;
+    const selectedLines = lines.slice(startIndex, startIndex + maxLines);
+    const truncatedByLines = lines.length > startIndex + selectedLines.length;
+    return {
+      toolName: "read_downloaded_file",
+      riskLevel: this.config.tools.readDownloadedFile.riskLevel,
+      data: {
+        artifactId: artifact.artifactId,
+        path: artifact.relativePath,
+        content: selectedLines.join("\n"),
+        startLine,
+        ...selectedLines.length > 0 ? { endLine: startLine + selectedLines.length - 1 } : {},
+        linesReturned: selectedLines.length,
+        bytesRead,
+        truncated: truncatedByBytes || truncatedByLines
+      }
+    };
+  }
+  async readResource(input) {
+    const uri = typeof input.uri === "string" && input.uri.trim() ? input.uri.trim() : void 0;
+    if (!uri) {
+      throw nativeFileError({
+        code: "FILE_DOWNLOAD_FAILED",
+        message: "read_resource requires a non-empty uri.",
+        recoverable: true
+      });
+    }
+    if (!this.mcpClient?.readResource) {
+      throw nativeFileError({
+        code: "NATIVE_FILE_TOOLS_DISABLED",
+        message: "read_resource requires an MCP client that supports resource reading. Configure the toolkit with an MCP client to use this tool.",
+        recoverable: false
+      });
+    }
+    const result = await this.mcpClient.readResource(uri);
+    const primaryContent = result.contents[0];
+    return {
+      toolName: "read_resource",
+      riskLevel: this.config.tools.readResource.riskLevel,
+      data: {
+        uri,
+        mimeType: primaryContent?.mimeType ?? "application/octet-stream",
+        ...primaryContent?.text !== void 0 ? { content: primaryContent.text } : {},
+        ...primaryContent?.blob !== void 0 ? { data: primaryContent.blob } : {}
+      }
+    };
+  }
+  resolveArtifact(input) {
+    const artifactId = typeof input.artifactId === "string" && input.artifactId.trim() ? input.artifactId.trim() : void 0;
+    if (artifactId) {
+      const artifact = this.manifest.getById(artifactId);
+      if (artifact) {
+        return artifact;
+      }
+    }
+    const inputPath = typeof input.path === "string" && input.path.trim() ? resolveInputRelativePath(input.path) : void 0;
+    if (inputPath) {
+      const artifact = this.manifest.getByRelativePath(inputPath);
+      if (artifact) {
+        return artifact;
+      }
+    }
+    throw nativeFileError({
+      code: "FILE_ARTIFACT_NOT_FOUND",
+      message: "read_downloaded_file requires an artifactId or path returned by download_file in this toolkit session.",
+      recoverable: true,
+      details: {
+        artifactId,
+        path: inputPath
+      }
+    });
+  }
+  createDownloadApprovalMetadata(input) {
+    try {
+      const validatedUrl = validateDownloadUrl(input.url, this.config);
+      const outputRelativePath = typeof input.fileName === "string" && input.fileName.trim() ? resolveOutputRelativePath(input.fileName, validatedUrl.url) : void 0;
+      return {
+        source: "native",
+        nativeToolType: "fileArtifacts",
+        filesystemRoot: this.config.rootDirAbsolute,
+        sideEffects: ["networkRead", "localFileWrite"],
+        urlHost: validatedUrl.source.host,
+        urlProtocol: validatedUrl.source.protocol,
+        urlPath: validatedUrl.source.path,
+        urlKind: validatedUrl.source.kind,
+        ...outputRelativePath ? { outputRelativePath } : {}
+      };
+    } catch {
+      return void 0;
+    }
+  }
+  createReadApprovalMetadata(input) {
+    const artifactId = typeof input.artifactId === "string" && input.artifactId.trim() ? input.artifactId.trim() : void 0;
+    const relativePath = typeof input.path === "string" && input.path.trim() ? input.path.trim() : void 0;
+    return {
+      source: "native",
+      nativeToolType: "fileArtifacts",
+      filesystemRoot: this.config.rootDirAbsolute,
+      sideEffects: ["localFileRead"],
+      ...artifactId ? { artifactId } : {},
+      ...relativePath ? { relativePath } : {}
+    };
+  }
+};
+
+// src/shared/tools/native/resolve-native-file-tools-input.ts
+import os2 from "os";
+import path4 from "path";
+var DEFAULT_NATIVE_ARTIFACT_ROOT = path4.join(
+  os2.homedir(),
+  ".zuora-agent-artifacts"
+);
+var DEFAULT_NATIVE_ALLOWED_HOSTS = [
+  "*.amazonaws.com",
+  "*.s3.amazonaws.com",
+  "s3.amazonaws.com",
+  "s3.us-west-2.amazonaws.com",
+  "*.s3.us-west-2.amazonaws.com"
+];
+var AGENT_NATIVE_TOOL_DEFAULTS = {
+  downloadFile: { enabled: false, operationAccess: "read" },
+  extractDownloadedArchive: { enabled: false, operationAccess: "read" },
+  downloadQueryResult: { enabled: true, operationAccess: "read" },
+  readDownloadedFile: { enabled: true, operationAccess: "read" },
+  downloadZuoraFile: { enabled: true, operationAccess: "read" },
+  readResource: { enabled: true, operationAccess: "read" }
+};
+var readEnvAllowedHosts = () => {
+  const raw = process.env["ZUORA_NATIVE_ALLOWED_HOSTS"]?.trim();
+  if (!raw) {
+    return void 0;
+  }
+  const hosts = raw.split(",").map((host) => host.trim()).filter(Boolean);
+  return hosts.length > 0 ? hosts : void 0;
+};
+var resolveNativeFileToolsInput = (config) => {
+  const explicit = config.nativeFileTools;
+  if (explicit?.enabled === false) {
+    return { enabled: false };
+  }
+  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 {
+    enabled: true,
+    bundleName: explicit?.bundleName ?? "query",
+    rootDir,
+    allowedHosts,
+    allowS3PresignedDownload: explicit?.allowS3PresignedDownload ?? true,
+    requireRootUnderUserHome: explicit?.requireRootUnderUserHome ?? true,
+    tools: mergeNativeToolOverrides(explicit?.tools, AGENT_NATIVE_TOOL_DEFAULTS),
+    ...explicit?.userHomeDir ? { userHomeDir: explicit.userHomeDir } : {},
+    ...explicit?.allowOverwrite !== void 0 ? { allowOverwrite: explicit.allowOverwrite } : {},
+    ...explicit?.maxDownloadBytes !== void 0 ? { maxDownloadBytes: explicit.maxDownloadBytes } : {},
+    ...explicit?.maxReadBytes !== void 0 ? { maxReadBytes: explicit.maxReadBytes } : {},
+    ...explicit?.maxReadLines !== void 0 ? { maxReadLines: explicit.maxReadLines } : {},
+    ...explicit?.downloadTimeoutMs !== void 0 ? { downloadTimeoutMs: explicit.downloadTimeoutMs } : {},
+    ...explicit?.allowedProtocols ? { allowedProtocols: explicit.allowedProtocols } : {},
+    ...explicit?.allowedUrlPrefixes ? { allowedUrlPrefixes: explicit.allowedUrlPrefixes } : {}
+  };
+};
+var mergeNativeToolOverrides = (overrides, defaults) => ({
+  downloadFile: mergeNativeToolMetadata(
+    defaults.downloadFile,
+    overrides?.downloadFile
+  ),
+  extractDownloadedArchive: mergeNativeToolMetadata(
+    defaults.extractDownloadedArchive,
+    overrides?.extractDownloadedArchive
+  ),
+  downloadQueryResult: mergeNativeToolMetadata(
+    defaults.downloadQueryResult,
+    overrides?.downloadQueryResult
+  ),
+  readDownloadedFile: mergeNativeToolMetadata(
+    defaults.readDownloadedFile,
+    overrides?.readDownloadedFile
+  ),
+  downloadZuoraFile: mergeNativeToolMetadata(
+    defaults.downloadZuoraFile,
+    overrides?.downloadZuoraFile
+  ),
+  readResource: mergeNativeToolMetadata(
+    defaults.readResource,
+    overrides?.readResource
+  )
+});
+var mergeNativeToolMetadata = (defaults, override) => {
+  const enabled = override?.enabled ?? defaults?.enabled ?? false;
+  const operationAccess = override?.operationAccess ?? defaults?.operationAccess ?? "read";
+  const riskLevel = override?.riskLevel ?? defaults?.riskLevel ?? "low";
+  const description = override?.description ?? defaults?.description;
+  return {
+    enabled,
+    operationAccess,
+    riskLevel,
+    ...description ? { description } : {}
+  };
+};
+
+// src/shared/tools/native/query-result-download/config.ts
+var resolveNativeQueryResultDownloadConfig = (input, options) => {
+  const tool2 = resolveNativeToolMetadata(input?.tools?.downloadQueryResult, {
+    enabled: true,
+    operationAccess: "read",
+    riskLevel: "medium"
+  });
+  if (tool2.operationAccess !== "read") {
+    throw new ZuoraAgentToolkitError({
+      code: "NATIVE_FILE_CONFIG_INVALID",
+      message: 'download_query_result must be configured with operationAccess "read".',
+      category: "configuration",
+      recoverable: true
+    });
+  }
+  const config = {
+    enabled: options.fileArtifactsEnabled && tool2.enabled,
+    tool: tool2
+  };
+  return config;
+};
+
+// src/shared/tools/native/query-result-download/helpers/status-resolver.ts
+var resolveQueryResultStatusCall = (tools, jobId) => {
+  const candidates = tools.map((tool2) => ({
+    tool: tool2,
+    score: scoreQueryResultStatusTool(tool2)
+  })).filter(({ score, tool: tool2 }) => score > 0 && !isSubmitStyleStatusTool(tool2)).sort((first, second) => second.score - first.score);
+  const candidate = candidates[0];
+  if (!candidate) {
+    return void 0;
+  }
+  return {
+    toolName: candidate.tool.name,
+    input: createQueryResultStatusInput(candidate.tool, jobId)
+  };
+};
+var scoreQueryResultStatusTool = (tool2) => {
+  const haystack = `${tool2.name} ${tool2.description}`.toLowerCase();
+  const operationName = tool2.meta.operationName ?? "";
+  if (tool2.meta.bundle !== "query") {
+    return 0;
+  }
+  let score = 0;
+  if (tool2.name === "manage_dataquery") {
+    score += 200;
+  }
+  if (operationName === "get_query_job" || tool2.name.endsWith("__get_query_job")) {
+    score += 220;
+  }
+  if (/(dataquery|data query|data_query|manage_data_queries)/i.test(haystack)) {
+    score += 80;
+  }
+  if (/(query).*(job|status|result)|(job|status|result).*(query)/i.test(haystack)) {
+    score += 40;
+  }
+  if (operationName && /(get|retrieve|fetch|read|status|poll|download)/i.test(operationName)) {
+    score += 50;
+  }
+  return score;
+};
+var isSubmitStyleStatusTool = (tool2) => {
+  const operationName = tool2.meta.operationName ?? tool2.name;
+  if (/^(submit|run|create)_/i.test(operationName)) {
+    return true;
+  }
+  return /__(submit|run|create)_/i.test(tool2.name);
+};
+var createQueryResultStatusInput = (tool2, jobId) => {
+  const input = {};
+  if (tool2.meta.operationSelector) {
+    const operationName = tool2.meta.operationName ?? resolveStatusOperationName(tool2);
+    if (operationName) {
+      input[tool2.meta.operationSelector] = operationName;
+    }
+  }
+  input[resolveQueryJobIdInputName(tool2.inputSchema)] = jobId;
+  return input;
+};
+var resolveStatusOperationName = (tool2) => {
+  const asyncOperations = tool2.meta.asyncOperations;
+  if (!asyncOperations) {
+    return void 0;
+  }
+  for (const meta of Object.values(asyncOperations)) {
+    if (meta.pollingOperation) {
+      return meta.pollingOperation;
+    }
+  }
+  return Object.keys(asyncOperations).find(
+    (name) => /(get|status|poll|retrieve|fetch)/i.test(name)
+  );
+};
+var resolveQueryJobIdInputName = (schema) => {
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const propertyNames = Object.keys(properties);
+  const exactPreferred = ["jobId", "queryJobId", "dataQueryJobId", "id"].find(
+    (name) => propertyNames.includes(name)
+  );
+  if (exactPreferred) {
+    return exactPreferred;
+  }
+  return propertyNames.find((name) => /job.*id|id.*job/i.test(name)) ?? propertyNames.find((name) => /id$/i.test(name)) ?? "jobId";
+};
+
+// src/shared/tools/native/query-result-download/definitions.ts
+var createDownloadQueryResultToolDefinition = (toolConfig) => ({
+  name: "download_query_result",
+  description: toolConfig.description ?? [
+    "Download a completed Zuora Data Query result by jobId.",
+    "Use this instead of copying a dataFile URL when the user asks to download a query result and a jobId is available.",
+    "The SDK fetches the latest query job result, extracts the exact dataFile URL internally, and downloads it to the local artifact folder."
+  ].join(" "),
+  inputSchema: nativeObjectSchema(
+    {
+      jobId: {
+        type: "string",
+        description: "Zuora Data Query job id."
+      },
+      fileName: {
+        type: "string",
+        description: "Optional relative artifact file name under the configured artifact root."
+      },
+      overwrite: {
+        type: "boolean",
+        description: "Replace an existing local artifact at fileName. Set to true only after the user explicitly confirmed overwrite."
+      }
+    },
+    ["jobId"]
+  ),
+  outputSchema: nativeObjectSchema(
+    {
+      jobId: { type: "string" },
+      queryStatus: { type: "string" },
+      download: {
+        type: "object",
+        additionalProperties: true
+      }
+    },
+    ["jobId", "download"]
+  ),
+  meta: {
+    bundle: "query",
+    access: toolConfig.operationAccess,
+    riskLevel: toolConfig.riskLevel,
+    requiredServicePermissions: [],
+    limitations: [],
+    sourceName: "download_query_result"
+  }
+});
+
+// src/shared/tools/native/query-result-download/helpers/index.ts
+var readJobId = (value) => {
+  if (typeof value === "string" && value.trim()) {
+    return value.trim();
+  }
+  throw new ZuoraAgentToolkitError({
+    code: "QUERY_RESULT_JOB_ID_INVALID",
+    message: "download_query_result requires a non-empty jobId.",
+    category: "validation",
+    recoverable: true
+  });
+};
+var findDownloadUrl = (value) => findStringByKey(value, (key, candidate) => {
+  if (!DOWNLOAD_URL_KEY_PATTERN.test(key)) {
+    return false;
+  }
+  return isHttpUrl(candidate);
+});
+var findQueryStatus = (value) => findStringByKey(value, (key) => /^(queryStatus|status)$/i.test(key));
+var findStringByKey = (value, predicate, depth = 0) => {
+  if (depth > 8 || typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = findStringByKey(item, predicate, depth + 1);
+      if (found) {
+        return found;
+      }
+    }
+    return void 0;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item === "string" && predicate(key, item)) {
+      return item;
+    }
+    const found = findStringByKey(item, predicate, depth + 1);
+    if (found) {
+      return found;
+    }
+  }
+  return void 0;
+};
+var isHttpUrl = (value) => {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+};
+var DOWNLOAD_URL_KEY_PATTERN = /^(dataFile|resultFile|downloadFile|fileUrl|downloadUrl|resultUrl|href)$/i;
+
+// src/shared/tools/native/query-result-download/index.ts
+var NativeQueryResultDownloadTools = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  listTools() {
+    if (!this.config.enabled) {
+      return [];
+    }
+    return [this.createDownloadQueryResultTool()];
+  }
+  createDownloadQueryResultTool() {
+    return createNativeRuntimeTool({
+      definition: createDownloadQueryResultToolDefinition(this.config.tool),
+      execute: (input) => this.downloadQueryResult(input)
+    });
+  }
+  async downloadQueryResult(input) {
+    const jobId = readJobId(input.jobId);
+    const queryResult = await this.config.fetchQueryResult(jobId);
+    const dataFile = findDownloadUrl(queryResult.data);
+    if (!dataFile) {
+      throw new ZuoraAgentToolkitError({
+        code: "QUERY_RESULT_DATA_FILE_NOT_FOUND",
+        message: "Query result did not include a dataFile URL. Confirm the job is completed before downloading the result.",
+        category: "native_file_tools",
+        recoverable: true,
+        details: {
+          jobId,
+          queryStatus: findQueryStatus(queryResult.data)
+        }
+      });
+    }
+    const download = await this.config.downloadFile({
+      url: dataFile,
+      ...typeof input.fileName === "string" && input.fileName.trim() ? { fileName: input.fileName.trim() } : {},
+      ...typeof input.overwrite === "boolean" ? { overwrite: input.overwrite } : {}
+    });
+    return {
+      toolName: "download_query_result",
+      riskLevel: this.config.tool.riskLevel,
+      data: {
+        jobId,
+        ...findQueryStatus(queryResult.data) ? { queryStatus: findQueryStatus(queryResult.data) } : {},
+        download: download.data
+      },
+      warnings: [
+        ...queryResult.warnings ?? [],
+        ...download.warnings ?? []
+      ]
+    };
+  }
+};
+
+// src/shared/tools/native/zuora-file-download/config.ts
+var resolveNativeZuoraFileDownloadConfig = (input, options) => {
+  const tool2 = resolveNativeToolMetadata(input?.tools?.downloadZuoraFile, {
+    enabled: true,
+    operationAccess: "read",
+    riskLevel: "medium"
+  });
+  const config = {
+    enabled: options.fileArtifactsEnabled && tool2.enabled,
+    tool: tool2
+  };
+  return config;
+};
+
+// src/shared/tools/native/zuora-file-download/definitions.ts
+var createDownloadZuoraFileToolDefinition = (toolConfig) => ({
+  name: "download_zuora_file",
+  description: toolConfig.description ?? [
+    "Download a Zuora tenant file by fileId using the Zuora REST Files API.",
+    "Use this when a prior tool result includes resourceUri zuora://files/{fileId} or an explicit fileId for a generated artifact such as an invoice PDF.",
+    "The SDK downloads the file with the configured Zuora credentials and saves it to the local artifact folder."
+  ].join(" "),
+  inputSchema: nativeObjectSchema(
+    {
+      fileId: {
+        type: "string",
+        description: "Zuora file id from a prior tool result."
+      },
+      resourceUri: {
+        type: "string",
+        description: "Optional zuora://files/{fileId} resource URI from a prior tool result."
+      },
+      fileName: {
+        type: "string",
+        description: "Optional relative artifact file name under the configured artifact root."
+      },
+      overwrite: {
+        type: "boolean",
+        description: "Replace an existing local artifact at fileName. Set to true only after the user explicitly confirmed overwrite."
+      }
+    },
+    []
+  ),
+  outputSchema: nativeObjectSchema(
+    {
+      fileId: { type: "string" },
+      download: {
+        type: "object",
+        additionalProperties: true
+      }
+    },
+    ["fileId", "download"]
+  ),
+  meta: {
+    bundle: "query",
+    access: toolConfig.operationAccess,
+    riskLevel: toolConfig.riskLevel,
+    requiredServicePermissions: [],
+    limitations: [],
+    sourceName: "download_zuora_file"
+  }
+});
+
+// src/shared/tools/native/zuora-file-download/helpers/index.ts
+var ZUORA_FILE_RESOURCE_URI_PATTERN = /^zuora:\/\/files\/([A-Za-z0-9]+)$/i;
+var readZuoraFileId = (input) => {
+  const fileId = typeof input.fileId === "string" ? input.fileId.trim() : "";
+  const resourceUri = typeof input.resourceUri === "string" ? input.resourceUri.trim() : "";
+  if (fileId) {
+    return fileId;
+  }
+  const parsedFileId = parseZuoraFileResourceUri(resourceUri);
+  if (parsedFileId) {
+    return parsedFileId;
+  }
+  throw new ZuoraAgentToolkitError({
+    code: "INVALID_INPUT",
+    message: "download_zuora_file requires fileId or resourceUri zuora://files/{fileId}.",
+    category: "validation",
+    recoverable: true
+  });
+};
+var parseZuoraFileResourceUri = (resourceUri) => {
+  const match = resourceUri.match(ZUORA_FILE_RESOURCE_URI_PATTERN);
+  return match?.[1];
+};
+var resolveZuoraFileResource = (value, keyPath = [], depth = 0) => {
+  if (depth > 6) {
+    return void 0;
+  }
+  if (typeof value === "string") {
+    const fileId = parseZuoraFileResourceUri(value);
+    if (fileId && keyPath.at(-1) === "resourceUri") {
+      return { fileId, resourceUri: value };
+    }
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) {
+      const resolved = resolveZuoraFileResource(item, [
+        ...keyPath,
+        String(index)
+      ], depth + 1);
+      if (resolved) {
+        return resolved;
+      }
+    }
+    return void 0;
+  }
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  const record = value;
+  const resourceUri = record.resourceUri;
+  if (typeof resourceUri === "string") {
+    const fileId = parseZuoraFileResourceUri(resourceUri);
+    if (fileId) {
+      return { fileId, resourceUri };
+    }
+  }
+  const explicitFileId = typeof record.fileId === "string" ? record.fileId.trim() : "";
+  if (explicitFileId && typeof resourceUri === "string") {
+    const parsed = parseZuoraFileResourceUri(resourceUri);
+    if (parsed === explicitFileId) {
+      return { fileId: explicitFileId, resourceUri };
+    }
+  }
+  for (const [key, item] of Object.entries(record)) {
+    const resolved = resolveZuoraFileResource(item, [...keyPath, key], depth + 1);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  return void 0;
+};
+var defaultZuoraFileName = (fileId, contentType) => {
+  if (contentType?.includes("pdf")) {
+    return `${fileId}.pdf`;
+  }
+  if (contentType?.includes("json")) {
+    return `${fileId}.json`;
+  }
+  return `${fileId}.bin`;
+};
+
+// src/shared/tools/native/zuora-file-download/index.ts
+var NativeZuoraFileDownloadTools = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  listTools() {
+    if (!this.config.enabled) {
+      return [];
+    }
+    return [this.createDownloadZuoraFileTool()];
+  }
+  createDownloadZuoraFileTool() {
+    return createNativeRuntimeTool({
+      definition: createDownloadZuoraFileToolDefinition(this.config.tool),
+      execute: (input) => this.downloadZuoraFile(input)
+    });
+  }
+  async downloadZuoraFile(input) {
+    const fileId = readZuoraFileId(input);
+    const fetched = await this.config.fetchZuoraFile(fileId);
+    const source = {
+      protocol: "zuora:",
+      host: "files",
+      path: `/${fileId}`,
+      redactedUrl: `zuora://files/${fileId}`,
+      kind: "zuora-public"
+    };
+    const download = await this.config.persistDownload({
+      input,
+      toolName: "download_zuora_file",
+      riskLevel: this.config.tool.riskLevel,
+      body: Buffer.from(fetched.bytes),
+      ...fetched.contentType ? { contentType: fetched.contentType } : {},
+      source,
+      defaultFileName: defaultZuoraFileName(fileId, fetched.contentType)
+    });
+    return {
+      toolName: "download_zuora_file",
+      riskLevel: this.config.tool.riskLevel,
+      data: {
+        fileId,
+        download: download.data
+      },
+      ...download.warnings ? { warnings: download.warnings } : {}
+    };
+  }
+};
+
+// src/shared/tools/mcp-tool-definition.ts
+var DEFAULT_ACCESS = "write";
+var DEFAULT_RISK_LEVEL = "high";
+var DEFAULT_BUNDLE = "admin";
+var RISK_RANK = {
+  low: 0,
+  medium: 1,
+  high: 2
+};
+var normalizeMcpTools = (tools, splitOperations) => tools.flatMap((tool2) => normalizeSingleTool(tool2, splitOperations));
+var normalizeSingleTool = (tool2, splitOperations) => {
+  const extracted = extractToolMetadata(tool2);
+  const operationPermissions = extracted.operationPermissions;
+  const operationNames = operationPermissions ? Object.keys(operationPermissions) : [];
+  if (operationNames.length <= 1) {
+    const access2 = aggregateOperation(operationPermissions) ?? DEFAULT_ACCESS;
+    return [
+      buildZuoraToolDefinition(tool2, extracted, {
+        name: tool2.name,
+        access: access2,
+        operationName: operationNames[0],
+        isSplit: false
+      })
+    ];
+  }
+  if (splitOperations) {
+    return operationNames.map(
+      (operationName) => buildZuoraToolDefinition(tool2, extracted, {
+        name: createOperationAdapterToolName(tool2.name, operationName),
+        access: operationPermissions[operationName],
+        operationName,
+        isSplit: true
+      })
+    );
+  }
+  const access = aggregateOperation(operationPermissions);
+  return [
+    buildZuoraToolDefinition(tool2, extracted, {
+      name: tool2.name,
+      access,
+      isSplit: false,
+      isMultiOpMerged: true
+    })
+  ];
+};
+var extractToolMetadata = (tool2) => {
+  const meta = isRecord(tool2._meta) ? tool2._meta : void 0;
+  const zuoraMeta = isRecord(meta?.zuora) ? meta.zuora : void 0;
+  const operationPermissions = normalizeOperationPermissions(
+    meta?.["operationPermissions"],
+    tool2.name
+  );
+  const operationRiskLevels = normalizeRiskLevels(
+    meta?.["riskLevels"] ?? meta?.["operationRiskLevels"],
+    tool2.name
+  );
+  const bundleValue = nonEmptyString(meta?.["bundle"]);
+  const bundle = bundleValue !== void 0 ? bundleValue.toLowerCase() : DEFAULT_BUNDLE;
+  const requiredServicePermissions = parseServicePermissions(
+    meta?.["requiredServicePermissions"]
+  );
+  const asyncOperations = parseAsyncOperations(meta?.["asyncOperations"]);
+  const limitations = normalizeLimitations(
+    meta?.["knownLimitations"] ?? zuoraMeta?.["limitations"]
+  ) ?? [];
+  return {
+    bundle,
+    operationPermissions,
+    operationRiskLevels,
+    asyncOperations,
+    requiredServicePermissions,
+    limitations
+  };
+};
+var buildZuoraToolDefinition = (tool2, extracted, params) => {
+  const asyncOperation = resolveAsyncOperation(extracted, params);
+  const baseInputSchema = tool2.inputSchema ?? {
+    type: "object",
+    additionalProperties: true
+  };
+  const needsOperationSelector = (params.isSplit || params.isMultiOpMerged) && extracted.operationPermissions !== void 0;
+  const operationSelector = needsOperationSelector ? inferOperationSelector(baseInputSchema, extracted.operationPermissions) : void 0;
+  const inputSchema = params.isSplit && operationSelector ? omitSchemaProperty(baseInputSchema, operationSelector) : baseInputSchema;
+  return {
+    name: params.name,
+    description: tool2.description ?? params.name,
+    inputSchema,
+    ...tool2.outputSchema ? { outputSchema: tool2.outputSchema } : {},
+    meta: {
+      bundle: extracted.bundle,
+      access: params.access,
+      riskLevel: resolveRiskLevel(extracted, params),
+      ...asyncOperation ? { asyncOperation } : {},
+      // Multi-op merged tool: store per-operation maps so callTool can look up
+      // the correct access, risk, and async meta from the runtime input.
+      ...params.isMultiOpMerged && extracted.asyncOperations ? { asyncOperations: extracted.asyncOperations } : {},
+      ...params.isMultiOpMerged && extracted.operationPermissions ? { operationAccess: extracted.operationPermissions } : {},
+      ...params.isMultiOpMerged && extracted.operationRiskLevels ? { operationRiskLevel: extracted.operationRiskLevels } : {},
+      requiredServicePermissions: extracted.requiredServicePermissions,
+      limitations: extracted.limitations,
+      sourceName: tool2.name,
+      ...operationSelector ? { operationSelector } : {},
+      ...params.isSplit && params.operationName ? { operationName: params.operationName } : {}
+    }
+  };
+};
+var resolveRiskLevel = (extracted, params) => {
+  const { operationRiskLevels } = extracted;
+  if (operationRiskLevels) {
+    if (params.isSplit && params.operationName) {
+      return operationRiskLevels[params.operationName] ?? DEFAULT_RISK_LEVEL;
+    }
+    const highest = highestRiskLevel(Object.values(operationRiskLevels));
+    if (highest) {
+      return highest;
+    }
+  }
+  return DEFAULT_RISK_LEVEL;
+};
+var resolveAsyncOperation = (extracted, params) => {
+  const { asyncOperations } = extracted;
+  if (!asyncOperations) {
+    return void 0;
+  }
+  if (params.isSplit && params.operationName) {
+    return asyncOperations[params.operationName];
+  }
+  if (params.isMultiOpMerged) {
+    return void 0;
+  }
+  return Object.values(asyncOperations)[0];
+};
+var parseServicePermissions = (value) => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.flatMap((item) => {
+    if (!isRecord(item)) {
+      return [];
+    }
+    const scope = nonEmptyString(item["scope"]);
+    const name = nonEmptyString(item["name"]);
+    if (!scope || !name) {
+      return [];
+    }
+    return [{ scope, name }];
+  });
+};
+var parseAsyncOperations = (value) => {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const result = {};
+  for (const [opName, opValue] of Object.entries(value)) {
+    const parsed = parseAsyncOperationMeta(opValue);
+    if (parsed) {
+      result[opName] = parsed;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : void 0;
+};
+var parseAsyncOperationMeta = (value) => {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const pollingOperation = nonEmptyString(value["pollingOperation"]);
+  const pollingTool = nonEmptyString(value["pollingTool"]);
+  const jobIdPath = nonEmptyString(value["jobIdPath"]);
+  const statusPath = nonEmptyString(value["statusPath"]);
+  if (!pollingOperation && !pollingTool || !jobIdPath || !statusPath) {
+    return void 0;
+  }
+  const terminalStatuses = parseTerminalStatuses(value["terminalStatuses"]);
+  if (!terminalStatuses) {
+    return void 0;
+  }
+  const pollingArgs = parsePollingArgs(value["pollingArgs"]);
+  return {
+    ...pollingOperation ? { pollingOperation } : {},
+    ...pollingTool ? { pollingTool } : {},
+    jobIdPath: normalizeMetadataPath(jobIdPath),
+    statusPath: normalizeMetadataPath(statusPath),
+    terminalStatuses,
+    ...pollingArgs ? { pollingArgs } : {},
+    ...typeof value["recommendedPollIntervalMs"] === "number" ? { recommendedPollIntervalMs: value["recommendedPollIntervalMs"] } : {},
+    ...typeof value["defaultTimeoutMs"] === "number" ? { defaultTimeoutMs: value["defaultTimeoutMs"] } : {},
+    ...typeof value["maxPollAttempts"] === "number" ? { maxPollAttempts: value["maxPollAttempts"] } : {}
+  };
+};
+var parsePollingArgs = (value) => {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const entries = Object.entries(value).flatMap(
+    ([key, entryValue]) => typeof entryValue === "string" ? [[key, entryValue]] : []
+  );
+  return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+};
+var parseTerminalStatuses = (value) => {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const success = parseStringArray(value["success"]);
+  const failure = parseStringArray(value["failure"]);
+  if (!success || !failure) {
+    return void 0;
+  }
+  return {
+    success,
+    failure,
+    ...Array.isArray(value["canceled"]) ? { canceled: parseStringArray(value["canceled"]) ?? [] } : {}
+  };
+};
+var parseStringArray = (value) => {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const strings = value.filter((entry) => typeof entry === "string");
+  return strings.length > 0 ? strings : void 0;
+};
+var normalizeOperationPermissions = (value, toolName) => {
+  const direct = normalizeOperation(value);
+  if (direct) {
+    return { [toolName]: direct };
+  }
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const entries = Object.entries(value).flatMap(([operationName, rawValue]) => {
+    const operation = normalizeOperation(rawValue);
+    return operation ? [[operationName, operation]] : [];
+  });
+  return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+};
+var aggregateOperation = (operationPermissions) => {
+  if (!operationPermissions) {
+    return void 0;
+  }
+  return Object.values(operationPermissions).includes("write") ? "write" : "read";
+};
+var normalizeRiskLevels = (value, toolName) => {
+  const direct = normalizeRiskLevel(value);
+  if (direct) {
+    return { [toolName]: direct };
+  }
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const entries = Object.entries(value).flatMap(([operationName, rawValue]) => {
+    const riskLevel = normalizeRiskLevel(rawValue);
+    return riskLevel ? [[operationName, riskLevel]] : [];
+  });
+  return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+};
+var normalizeRiskLevel = (value) => {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "low" || normalized === "medium" || normalized === "high") {
+    return normalized;
+  }
+  return void 0;
+};
+var highestRiskLevel = (riskLevels) => {
+  let highest;
+  for (const riskLevel of riskLevels) {
+    if (!highest || RISK_RANK[riskLevel] > RISK_RANK[highest]) {
+      highest = riskLevel;
+    }
+  }
+  return highest;
+};
+var normalizeOperation = (value) => {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "read" || normalized === "readonly" || normalized === "read_only") {
+    return "read";
+  }
+  if (normalized === "write" || normalized === "mutation") {
+    return "write";
+  }
+  return void 0;
+};
+var normalizeStringList2 = (value) => uniqueStrings(collectStrings(value));
+var normalizeLimitations = (value) => {
+  const limitations = normalizeStringList2(value);
+  return limitations.length > 0 ? limitations : void 0;
+};
+var collectStrings = (value) => {
+  const direct = nonEmptyString(value);
+  if (direct) {
+    return [direct];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap(collectStrings);
+  }
+  if (isRecord(value)) {
+    return Object.values(value).flatMap(collectStrings);
+  }
+  return [];
+};
+var uniqueStrings = (values) => [...new Set(values)];
+
+// src/shared/utils/redaction.ts
+var redactSensitiveString = (value, sensitiveValues) => sensitiveValues.reduce(
+  (redacted, sensitiveValue) => sensitiveValue ? redacted.split(sensitiveValue).join("[REDACTED]") : redacted,
+  value
+);
+var redactSensitiveDetails = (value, sensitiveValues) => {
+  if (typeof value === "string") {
+    return redactSensitiveString(value, sensitiveValues);
+  }
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: redactSensitiveString(value.message, sensitiveValues)
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSensitiveDetails(item, sensitiveValues));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        redactSensitiveDetails(entry, sensitiveValues)
+      ])
+    );
+  }
+  return value;
+};
+
+// src/shared/transport/oauth-token-provider.ts
+var TOKEN_REFRESH_SKEW_MAX_MS = 6e4;
+var DEFAULT_TOKEN_EXPIRES_IN_SECONDS = 3600;
+var OAuthTokenProvider = class {
+  constructor(config, restBaseUrl) {
+    this.config = config;
+    this.restBaseUrl = restBaseUrl;
+  }
+  config;
+  restBaseUrl;
+  accessToken;
+  tokenIssuedAt = 0;
+  tokenExpiresAt = 0;
+  tenantId;
+  preferredTokenEndpoint;
+  async ensureAccessToken() {
+    if (!this.config.auth) {
+      throw new ZuoraAgentToolkitError({
+        code: "MISSING_AUTH",
+        message: "Zuora auth configuration is required unless tenant auth is enabled.",
+        category: "auth"
+      });
+    }
+    const now = Date.now();
+    if (this.accessToken && this.isAccessTokenFresh(now)) {
+      return this.accessToken;
+    }
+    const token = await this.fetchOAuthToken();
+    this.accessToken = token.access_token;
+    this.tokenIssuedAt = now;
+    this.tokenExpiresAt = now + (token.expires_in ?? DEFAULT_TOKEN_EXPIRES_IN_SECONDS) * 1e3;
+    this.tenantId = extractTenantId(token.scope);
+    return this.accessToken;
+  }
+  getTenantId() {
+    return this.tenantId;
+  }
+  invalidateAccessToken() {
+    this.accessToken = void 0;
+    this.tokenIssuedAt = 0;
+    this.tokenExpiresAt = 0;
+  }
+  sensitiveValues() {
+    const values = [this.accessToken];
+    const auth = this.config.auth;
+    if (auth?.clientSecret) {
+      values.push(auth.clientSecret);
+    }
+    return values.filter(
+      (value) => typeof value === "string" && value.length > 0
+    );
+  }
+  isAccessTokenFresh(now) {
+    const tokenLifetimeMs = Math.max(0, this.tokenExpiresAt - this.tokenIssuedAt);
+    const refreshSkewMs = Math.min(
+      TOKEN_REFRESH_SKEW_MAX_MS,
+      Math.floor(tokenLifetimeMs / 10)
+    );
+    return now < this.tokenExpiresAt - refreshSkewMs;
+  }
+  async fetchOAuthToken() {
+    const endpoints = await this.resolveTokenEndpoints();
+    let lastFailure;
+    const attempts = [];
+    for (const endpoint of endpoints) {
+      try {
+        const token = await this.requestOAuthToken(endpoint);
+        this.preferredTokenEndpoint = endpoint;
+        return token;
+      } catch (error) {
+        if (error instanceof ZuoraAgentToolkitError) {
+          lastFailure = error;
+          attempts.push({
+            tokenEndpoint: endpoint,
+            code: error.code,
+            message: error.message,
+            retryable: error.retryable,
+            details: error.details
+          });
+        } else {
+          lastFailure = new ZuoraAgentToolkitError({
+            code: "OAUTH_TOKEN_ERROR",
+            message: this.redactString(
+              error instanceof Error ? error.message : String(error)
+            ),
+            category: "auth",
+            retryable: true,
+            recoverable: true,
+            details: this.redactDetails(error)
+          });
+          attempts.push({
+            tokenEndpoint: endpoint,
+            code: lastFailure.code,
+            message: lastFailure.message,
+            retryable: lastFailure.retryable,
+            details: lastFailure.details
+          });
+        }
+      }
+    }
+    throw new ZuoraAgentToolkitError({
+      code: "OAUTH_TOKEN_ERROR",
+      message: lastFailure?.message ?? "OAuth token request failed against all configured endpoints.",
+      category: "auth",
+      retryable: attempts.some((attempt) => attempt.retryable),
+      recoverable: true,
+      details: this.redactDetails({ attempts })
+    });
+  }
+  async resolveTokenEndpoints() {
+    const restEndpoint = `${this.restBaseUrl}/oauth/token`;
+    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) {
+      return uniqueEndpoints;
+    }
+    return [
+      this.preferredTokenEndpoint,
+      ...uniqueEndpoints.filter(
+        (endpoint) => endpoint !== this.preferredTokenEndpoint
+      )
+    ];
+  }
+  async requestOAuthToken(tokenEndpoint) {
+    if (!this.config.auth) {
+      throw new ZuoraAgentToolkitError({
+        code: "UNSUPPORTED_AUTH",
+        message: "Unsupported auth configuration for Zuora HTTP MCP client.",
+        category: "auth"
+      });
+    }
+    const body = new URLSearchParams({ grant_type: "client_credentials" });
+    const headers = {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json"
+    };
+    const auth = this.config.auth;
+    body.set("client_id", auth.clientId);
+    body.set("client_secret", auth.clientSecret);
+    const response = await fetch(tokenEndpoint, {
+      method: "POST",
+      headers,
+      body
+    });
+    const token = await response.json().catch(() => ({}));
+    if (!response.ok || !token.access_token) {
+      const oauthError = typeof token.error === "string" && token.error.trim() ? token.error.trim() : void 0;
+      const oauthDescription = typeof token.error_description === "string" && token.error_description.trim() ? token.error_description.trim() : void 0;
+      const summary = oauthDescription ? oauthError && oauthError !== oauthDescription ? `${oauthError}: ${oauthDescription}` : oauthDescription : oauthError ?? `OAuth token request failed with HTTP ${response.status}.`;
+      throw new ZuoraAgentToolkitError({
+        code: "OAUTH_TOKEN_ERROR",
+        message: this.redactString(`${summary} (HTTP ${response.status})`),
+        category: "auth",
+        retryable: response.status >= 500,
+        recoverable: true,
+        details: this.redactDetails({
+          tokenEndpoint,
+          status: response.status,
+          ...oauthError ? { error: oauthError } : {},
+          ...oauthDescription ? { errorDescription: oauthDescription } : {}
+        })
+      });
+    }
+    return {
+      access_token: token.access_token,
+      ...typeof token.expires_in === "number" ? { expires_in: token.expires_in } : {},
+      ...token.scope ? { scope: token.scope } : {}
+    };
+  }
+  redactString(value) {
+    return redactSensitiveString(value, this.sensitiveValues());
+  }
+  redactDetails(value) {
+    return redactSensitiveDetails(value, this.sensitiveValues());
+  }
+};
+var extractTenantId = (scope) => {
+  const tenantMatch = scope?.match(/tenant\.(\d+)/);
+  return tenantMatch?.[1];
+};
+
+// src/shared/transport/request-headers.ts
+var RESERVED_HEADER_NAMES = /* @__PURE__ */ new Set([
+  "accept",
+  "authorization",
+  "content-type",
+  "mcp-session-id",
+  "user-agent",
+  "zuora-entity-ids",
+  "zuora-org-ids",
+  "zuora-tenant-id",
+  "zuora-token-id",
+  "zuora-user-id"
+]);
+var buildZuoraRequestHeaders = (config, options) => {
+  const tenantAuth = enabledTenantAuth(config);
+  return {
+    ...options.accessToken ? { authorization: `Bearer ${options.accessToken}` } : {},
+    ...options.contentType ? { "content-type": options.contentType } : {},
+    accept: options.accept,
+    "user-agent": options.userAgent,
+    ...sanitizeConfiguredHeaders(config),
+    ...config.zuoraVersion ? { "zuora-version": config.zuoraVersion } : {},
+    ...tenantAuth ? tenantAuthHeaders(config, tenantAuth) : scopeHeaders(config)
+  };
+};
+var enabledTenantAuth = (config) => {
+  const tenantAuth = config.tenantAuth;
+  return tenantAuth?.enabled === true ? tenantAuth : void 0;
+};
+var sanitizeConfiguredHeaders = (config) => Object.fromEntries(
+  Object.entries(config.headers ?? {}).filter(
+    (entry) => Boolean(entry[1]) && !RESERVED_HEADER_NAMES.has(entry[0].toLowerCase())
+  )
+);
+var tenantAuthHeaders = (config, tenantAuth) => {
+  const entityIds = headerListValue(config.entityIds);
+  const orgIds = headerListValue(config.orgIds);
+  return {
+    ...entityIds ? { "Zuora-Entity-Ids": entityIds } : {},
+    ...orgIds ? { "Zuora-Org-Ids": orgIds } : {},
+    "Zuora-Tenant-Id": tenantAuth.tenantId,
+    "Zuora-Token-Id": tenantAuth.tokenId,
+    "Zuora-User-Id": tenantAuth.userId
+  };
+};
+var scopeHeaders = (config) => {
+  const entityIds = headerListValue(config.entityIds);
+  const orgIds = headerListValue(config.orgIds);
+  return {
+    ...entityIds ? { "zuora-entity-ids": entityIds } : {},
+    ...orgIds ? { "zuora-org-ids": orgIds } : {}
+  };
+};
+var headerListValue = (value) => {
+  if (!value) {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    const normalized2 = value.map((item) => item.trim()).filter(Boolean);
+    return normalized2.length > 0 ? normalized2.join(",") : void 0;
+  }
+  const normalized = value.trim();
+  return normalized || void 0;
+};
+
+// src/shared/transport/resolve-connection-config.ts
+var resolveZuoraConnectionConfig = (config, mcpUrl) => ({
+  clientName: config.clientName ?? "zuora-agent-toolkit",
+  clientVersion: config.clientVersion ?? "0.1.0",
+  protocolVersion: config.protocolVersion ?? "2025-03-26",
+  url: mcpUrl,
+  ...config.auth ? { auth: config.auth } : {},
+  ...config.headers ? { headers: config.headers } : {},
+  ...config.tenantAuth ? { tenantAuth: config.tenantAuth } : {},
+  ...config.entityIds ? { entityIds: config.entityIds } : {},
+  ...config.orgIds ? { orgIds: config.orgIds } : {},
+  ...config.zuoraVersion ? { zuoraVersion: config.zuoraVersion } : {}
+});
+
+// src/shared/transport/zuora-client.ts
+var ZuoraClient = class {
+  constructor(shared) {
+    this.shared = shared;
+  }
+  shared;
+  static createSharedState(config) {
+    const { remoteUrl, restBaseUrl } = normalizeZuoraMcpUrl(config.url);
+    const connection = resolveZuoraConnectionConfig(config, remoteUrl);
+    const normalizedRestBaseUrl = restBaseUrl.replace(/\/+$/, "");
+    return {
+      connection,
+      tokenProvider: new OAuthTokenProvider(
+        connection,
+        normalizedRestBaseUrl
+      ),
+      restBaseUrl: normalizedRestBaseUrl,
+      ...typeof config.maxDownloadBytes === "number" ? { maxDownloadBytes: config.maxDownloadBytes } : {}
+    };
+  }
+  get connection() {
+    return this.shared.connection;
+  }
+  get tokenProvider() {
+    return this.shared.tokenProvider;
+  }
+  get restBaseUrl() {
+    return this.shared.restBaseUrl;
+  }
+  get maxDownloadBytes() {
+    return this.shared.maxDownloadBytes;
+  }
+  getTenantId() {
+    return this.enabledTenantAuth()?.tenantId ?? this.tokenProvider.getTenantId();
+  }
+  async restGet(path5, options = {}) {
+    const normalizedPath = path5.startsWith("/") ? path5 : `/${path5}`;
+    const url = `${this.restBaseUrl}${normalizedPath}`;
+    const retryAttempts = this.enabledTenantAuth() ? [false] : [false, true];
+    for (const retry of retryAttempts) {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: await this.buildHeaders({
+          accept: "*/*"
+        }),
+        ...options.signal ? { signal: options.signal } : {}
+      });
+      if (!retry && (response.status === 401 || response.status === 403) && !this.enabledTenantAuth()) {
+        this.tokenProvider.invalidateAccessToken();
+        continue;
+      }
+      return response;
+    }
+    throw new ZuoraAgentToolkitError({
+      code: "ZUORA_REST_AUTH_RETRY_FAILED",
+      message: "Zuora REST request failed after auth retry.",
+      category: "auth"
+    });
+  }
+  async buildHeaders(options) {
+    const tenantAuth = this.enabledTenantAuth();
+    const accessToken = tenantAuth ? void 0 : await this.tokenProvider.ensureAccessToken();
+    return buildZuoraRequestHeaders(this.connection, {
+      ...accessToken ? { accessToken } : {},
+      userAgent: `${this.connection.clientName}/${this.connection.clientVersion}`,
+      accept: options.accept,
+      ...options.contentType ? { contentType: options.contentType } : {}
+    });
+  }
+  enabledTenantAuth() {
+    return enabledTenantAuth(this.connection);
+  }
+};
+
+// src/shared/transport/zuora-rest-client.ts
+var ZuoraRestClient = class extends ZuoraClient {
+  constructor(shared) {
+    super(shared);
+  }
+  async downloadFile(fileId, options = {}) {
+    const normalizedFileId = fileId.trim();
+    if (!normalizedFileId) {
+      throw new ZuoraAgentToolkitError({
+        code: "INVALID_INPUT",
+        message: "fileId is required for Zuora REST file download.",
+        category: "validation",
+        recoverable: true
+      });
+    }
+    const response = await this.restGet(
+      `/v1/files/${encodeURIComponent(normalizedFileId)}`,
+      options
+    );
+    if (!response.ok) {
+      throw new ZuoraAgentToolkitError({
+        code: "ZUORA_REST_FILE_DOWNLOAD_FAILED",
+        message: `Zuora REST file download failed with HTTP ${response.status}.`,
+        category: response.status === 404 ? "validation" : "mcp",
+        retryable: response.status >= 500,
+        recoverable: response.status === 404,
+        details: {
+          fileId: normalizedFileId,
+          status: response.status
+        }
+      });
+    }
+    const bytes = await readResponseBytes(response, this.maxDownloadBytes);
+    const contentType = response.headers.get("content-type");
+    const contentDisposition = response.headers.get("content-disposition");
+    return {
+      bytes,
+      ...contentType ? { contentType } : {},
+      ...contentDisposition ? { contentDisposition } : {}
+    };
+  }
+};
+var readResponseBytes = async (response, maxDownloadBytes) => {
+  if (!response.body) {
+    const buffer = new Uint8Array(await response.arrayBuffer());
+    if (typeof maxDownloadBytes === "number" && buffer.byteLength > maxDownloadBytes) {
+      throw new ZuoraAgentToolkitError({
+        code: "ZUORA_REST_FILE_TOO_LARGE",
+        message: `Zuora REST file download exceeded ${maxDownloadBytes} bytes.`,
+        category: "validation",
+        recoverable: true
+      });
+    }
+    return buffer;
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let totalBytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    if (!value) {
+      continue;
+    }
+    totalBytes += value.byteLength;
+    if (typeof maxDownloadBytes === "number" && totalBytes > maxDownloadBytes) {
+      throw new ZuoraAgentToolkitError({
+        code: "ZUORA_REST_FILE_TOO_LARGE",
+        message: `Zuora REST file download exceeded ${maxDownloadBytes} bytes.`,
+        category: "validation",
+        recoverable: true
+      });
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+};
+
+// src/shared/tool-selection.ts
+var resolveToolSelectionPolicy = (configuration, selection) => ({
+  mode: resolveToolMode(configuration, selection),
+  bundles: resolveBundles(configuration, selection),
+  include: /* @__PURE__ */ new Set([
+    ...resolveIncludedToolNames(configuration),
+    ...selection?.include ?? []
+  ]),
+  exclude: /* @__PURE__ */ new Set([
+    ...resolveExcludedToolNames(configuration),
+    ...selection?.exclude ?? []
+  ])
+});
+var resolveToolMode = (configuration, selection) => selection?.mode ?? configuration?.mode ?? SafetyMode.ReadOnly;
+var resolveExcludedToolNames = (configuration) => /* @__PURE__ */ new Set([
+  ...resolveConfiguredExcludedToolNames(configuration),
+  ...resolveBundleExcludedToolNames(configuration)
+]);
+var resolveBundles = (configuration, selection) => {
+  if (selection?.bundles) {
+    return new Set(selection.bundles);
+  }
+  const configured = configuration?.bundles;
+  if (!configured) {
+    return /* @__PURE__ */ new Set();
+  }
+  return new Set(
+    Object.entries(configured).filter(([, value]) => Boolean(value)).map(([name]) => name)
+  );
+};
+var resolveIncludedToolNames = (configuration) => {
+  const tools = configuration?.tools ?? {};
+  return Object.entries(tools).filter(([, enabled]) => enabled).map(([name]) => name);
+};
+var resolveConfiguredExcludedToolNames = (configuration) => {
+  const tools = configuration?.tools ?? {};
+  return Object.entries(tools).filter(([, enabled]) => !enabled).map(([name]) => name);
+};
+var resolveBundleExcludedToolNames = (configuration) => {
+  const bundles = configuration?.bundles ?? {};
+  return Object.values(bundles).flatMap((value) => {
+    if (typeof value === "object" && value) {
+      const config = value;
+      return config.exclude ?? [];
+    }
+    return [];
+  });
+};
+
+// src/shared/transport/mcp-tool-error.ts
+var extractMcpToolErrorMessage = (result) => {
+  if (Array.isArray(result.content)) {
+    for (const item of result.content) {
+      if (item != null && typeof item === "object" && "text" in item && typeof item.text === "string") {
+        const text = item.text.trim();
+        if (text) {
+          return text;
+        }
+      }
+    }
+  }
+  if (result.structuredContent != null) {
+    if (typeof result.structuredContent === "object" && result.structuredContent !== null && "message" in result.structuredContent && typeof result.structuredContent.message === "string") {
+      return result.structuredContent.message;
+    }
+    return "MCP tool call returned a structured error response.";
+  }
+  return void 0;
+};
+
+// src/shared/transport/json-rpc.ts
+var parseJsonRpcResponse = async ({
+  response,
+  sensitiveValues
+}) => {
+  const text = await response.text();
+  if (!response.ok) {
+    throw new ZuoraAgentToolkitError({
+      code: "MCP_HTTP_ERROR",
+      message: `Zuora MCP request failed with HTTP ${response.status}.`,
+      category: response.status === 401 || response.status === 403 ? "auth" : "mcp",
+      retryable: response.status >= 500,
+      details: redactSensitiveString(text, sensitiveValues)
+    });
+  }
+  if (!text.trim()) {
+    return {};
+  }
+  const json = parseResponseBody(text, response.headers.get("content-type"));
+  if (json.error) {
+    throw new ZuoraAgentToolkitError({
+      code: "MCP_JSON_RPC_ERROR",
+      message: redactSensitiveString(json.error.message, sensitiveValues),
+      category: "mcp",
+      details: redactSensitiveDetails(json.error, sensitiveValues)
+    });
+  }
+  return json.result ?? {};
+};
+var parseResponseBody = (text, contentType) => {
+  if (contentType?.includes("text/event-stream")) {
+    const dataLines = text.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice("data:".length).trim()).filter((line) => line && line !== "[DONE]");
+    const payload = dataLines.find((line) => line.startsWith("{"));
+    if (!payload) {
+      return {};
+    }
+    return JSON.parse(payload);
+  }
+  return JSON.parse(text);
+};
+
+// src/shared/transport/mcp-client.ts
+var ZuoraHttpMcpClient = class _ZuoraHttpMcpClient extends ZuoraClient {
+  mcpRequestId = 0;
+  mcpInitialized = false;
+  mcpSessionId;
+  constructor(config) {
+    super(ZuoraClient.createSharedState(config));
+  }
+  /** @internal Used by ZuoraRestClient via shared state injection. */
+  static fromSharedState(shared) {
+    const instance = Object.create(_ZuoraHttpMcpClient.prototype);
+    instance.shared = shared;
+    instance.mcpRequestId = 0;
+    instance.mcpInitialized = false;
+    instance.mcpSessionId = void 0;
+    return instance;
+  }
+  async initialize() {
+    if (!this.enabledTenantAuth()) {
+      await this.tokenProvider.ensureAccessToken();
+    }
+    if (this.mcpInitialized) {
+      return;
+    }
+    await this.postMcpJsonRpc("initialize", {
+      protocolVersion: this.connection.protocolVersion,
+      capabilities: {},
+      clientInfo: {
+        name: this.connection.clientName,
+        version: this.connection.clientVersion
+      }
+    });
+    await this.postMcpNotification("notifications/initialized");
+    this.mcpInitialized = true;
+  }
+  async listTools() {
+    await this.initialize();
+    const result = await this.postMcpJsonRpc(
+      "tools/list",
+      {}
+    );
+    return result.tools ?? [];
+  }
+  async callTool(name, input) {
+    await this.initialize();
+    const result = await this.postMcpJsonRpc("tools/call", {
+      name,
+      arguments: input
+    });
+    if (result.isError) {
+      const mcpMessage = extractMcpToolErrorMessage(result);
+      throw new ZuoraAgentToolkitError({
+        code: "TOOL_EXECUTION_ERROR",
+        message: mcpMessage ?? `Zuora MCP tool "${name}" returned an error.`,
+        category: "tool_execution"
+      });
+    }
+    const request = normalizeExecutionRequestMetadata(result.request);
+    const requestId = request?.requestId ?? request?.zuoraRequestId;
+    return {
+      toolName: name,
+      data: result.structuredContent ?? result.content ?? result,
+      ...requestId ? { requestId } : {},
+      ...request ? { request } : {}
+    };
+  }
+  async readResource(uri) {
+    await this.initialize();
+    return this.postMcpJsonRpc("resources/read", {
+      uri
+    });
+  }
+  getSensitiveValues() {
+    return this.tokenProvider.sensitiveValues();
+  }
+  async close() {
+    this.mcpInitialized = false;
+    this.mcpSessionId = void 0;
+  }
+  async postMcpJsonRpc(method, params) {
+    const id = ++this.mcpRequestId;
+    const retryAttempts = this.enabledTenantAuth() ? [false] : [false, true];
+    for (const retry of retryAttempts) {
+      const response = await fetch(this.connection.url, {
+        method: "POST",
+        headers: await this.buildMcpHeaders(),
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id,
+          method,
+          params
+        })
+      });
+      const sessionId = response.headers.get("mcp-session-id");
+      if (sessionId) {
+        this.mcpSessionId = sessionId;
+      }
+      try {
+        return await parseJsonRpcResponse({
+          response,
+          sensitiveValues: this.tokenProvider.sensitiveValues()
+        });
+      } catch (error) {
+        if (retry || !(error instanceof ZuoraAgentToolkitError) || error.category !== "auth") {
+          throw error;
+        }
+        this.tokenProvider.invalidateAccessToken();
+      }
+    }
+    throw new ZuoraAgentToolkitError({
+      code: "MCP_AUTH_RETRY_FAILED",
+      message: `MCP request ${method} failed after auth retry.`,
+      category: "auth"
+    });
+  }
+  async postMcpNotification(method) {
+    const retryAttempts = this.enabledTenantAuth() ? [false] : [false, true];
+    for (const retry of retryAttempts) {
+      const response = await fetch(this.connection.url, {
+        method: "POST",
+        headers: await this.buildMcpHeaders(),
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          method
+        })
+      });
+      const sessionId = response.headers.get("mcp-session-id");
+      if (sessionId) {
+        this.mcpSessionId = sessionId;
+      }
+      if (response.ok) {
+        return;
+      }
+      const error = new ZuoraAgentToolkitError({
+        code: "MCP_NOTIFICATION_FAILED",
+        message: `MCP notification ${method} failed with HTTP ${response.status}.`,
+        category: response.status === 401 || response.status === 403 ? "auth" : "mcp",
+        retryable: response.status >= 500
+      });
+      if (retry || error.category !== "auth") {
+        throw error;
+      }
+      this.tokenProvider.invalidateAccessToken();
+    }
+    throw new ZuoraAgentToolkitError({
+      code: "MCP_AUTH_RETRY_FAILED",
+      message: `MCP notification ${method} failed after auth retry.`,
+      category: "auth"
+    });
+  }
+  async buildMcpHeaders() {
+    const baseHeaders = await this.buildHeaders({
+      accept: "application/json, text/event-stream",
+      contentType: "application/json"
+    });
+    return {
+      ...baseHeaders,
+      ...this.mcpSessionId ? { "mcp-session-id": this.mcpSessionId } : {}
+    };
+  }
+};
+
+// src/shared/toolkit-core.ts
+var createHttpMcpClientConfig = (config) => {
+  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 } : {},
+      ...connection,
+      ...contextOverrides
+    };
+  }
+  if (!config.auth) {
+    throw new ZuoraAgentToolkitError({
+      code: "MISSING_AUTH",
+      message: "Zuora auth configuration is required unless tenant auth is enabled.",
+      category: "auth"
+    });
+  }
+  return {
+    url: config.baseUrl,
+    auth: config.auth,
+    ...connection ?? {},
+    ...contextOverrides
+  };
+};
+var isTenantAuthConnection = (connection) => connection?.tenantAuth?.enabled === true;
+var filterCatalogTools = (tools, policy) => tools.filter((tool2) => {
+  if (policy.mode === SafetyMode.ReadOnly && tool2.meta.access === "write") {
+    return false;
+  }
+  if (policy.bundles.size > 0 && !policy.bundles.has(tool2.meta.bundle)) {
+    return false;
+  }
+  if (policy.include.size > 0 && !policy.include.has(tool2.name)) {
+    return false;
+  }
+  if (policy.exclude.has(tool2.name)) {
+    return false;
+  }
+  return true;
+});
+var ToolkitCore = class {
+  config;
+  mcpClient;
+  catalogTools;
+  _initialized = false;
+  // Resolved once at construction so we never read process.env at runtime.
+  sanitizerLimits;
+  // SDK-native tool sets (e.g. file-artifacts). Indexed by tool name for O(1) dispatch.
+  nativeFileArtifactTools;
+  nativeQueryResultDownloadTools;
+  nativeZuoraFileDownloadTools;
+  // REST client for Zuora file downloads (used by zuora-file-download sub-module).
+  restClient;
+  nativeToolRegistry;
+  constructor(config) {
+    this.config = config;
+    const nativeFileTools = resolveNativeFileToolsInput(config);
+    this.sanitizerLimits = config.observability?.sanitizerLimits;
+    this.mcpClient = new ZuoraHttpMcpClient(createHttpMcpClientConfig(config));
+    const sharedState = ZuoraClient.createSharedState({
+      ...createHttpMcpClientConfig(config),
+      ...typeof nativeFileTools?.maxDownloadBytes === "number" ? { maxDownloadBytes: nativeFileTools.maxDownloadBytes } : {}
+    });
+    this.restClient = new ZuoraRestClient(sharedState);
+    this.nativeFileArtifactTools = new NativeFileArtifactTools(
+      nativeFileTools,
+      { mcpClient: this.mcpClient }
+    );
+    const queryResultDownloadConfig = resolveNativeQueryResultDownloadConfig(
+      nativeFileTools,
+      { fileArtifactsEnabled: this.nativeFileArtifactTools.isEnabled() }
+    );
+    this.nativeQueryResultDownloadTools = new NativeQueryResultDownloadTools({
+      enabled: queryResultDownloadConfig.enabled,
+      tool: queryResultDownloadConfig.tool,
+      fetchQueryResult: (jobId) => this.fetchQueryResultForDownload(jobId),
+      downloadFile: (input) => this.nativeFileArtifactTools.downloadFile(input)
+    });
+    const zuoraFileDownloadConfig = resolveNativeZuoraFileDownloadConfig(
+      nativeFileTools,
+      { fileArtifactsEnabled: this.nativeFileArtifactTools.isEnabled() }
+    );
+    this.nativeZuoraFileDownloadTools = new NativeZuoraFileDownloadTools({
+      enabled: zuoraFileDownloadConfig.enabled,
+      tool: zuoraFileDownloadConfig.tool,
+      fetchZuoraFile: (fileId) => this.restClient.downloadFile(fileId),
+      persistDownload: (options) => this.nativeFileArtifactTools.persistBufferedDownload(options)
+    });
+  }
+  async initialize() {
+    if (this._initialized) {
+      return;
+    }
+    const startedAt = Date.now();
+    await this.mcpClient.initialize?.();
+    const rawTools = await this.mcpClient.listTools();
+    const mcpCatalogTools = normalizeMcpTools(
+      rawTools,
+      this.resolveSplitOperations()
+    );
+    const nativeRuntimeTools = [
+      ...this.nativeFileArtifactTools.listTools(),
+      ...this.nativeQueryResultDownloadTools.listTools(),
+      ...this.nativeZuoraFileDownloadTools.listTools()
+    ];
+    this.nativeToolRegistry = new Map(
+      nativeRuntimeTools.map((runtimeTool) => [
+        runtimeTool.definition.name,
+        runtimeTool
+      ])
+    );
+    const nativeToolDefinitions = nativeRuntimeTools.map(
+      (runtimeTool) => runtimeTool.definition
+    );
+    this.catalogTools = [...mcpCatalogTools, ...nativeToolDefinitions];
+    this._initialized = true;
+    this.emit({
+      name: "metadata.loaded",
+      latencyMs: Date.now() - startedAt,
+      ...this.createEventContext(),
+      metadata: metadataLoadedEventMetadata(this.catalogTools)
+    });
+  }
+  async close() {
+    await this.mcpClient.close?.();
+    this._initialized = false;
+    this.catalogTools = void 0;
+    this.nativeToolRegistry = void 0;
+  }
+  async listTools(selection) {
+    this.warnIfNotInitialized();
+    return filterCatalogTools(
+      this.getNormalizedTools(),
+      resolveToolSelectionPolicy(this.config.configuration, selection)
+    );
+  }
+  /**
+   * Returns framework-native tool objects for the given selection.
+   *
+   * @param selection - Optional filter (bundles, mode) to narrow the catalog.
+   * @param maxTools - When provided and greater than zero, limits the result to
+   *   the first `maxTools` entries after filtering. Values ≤ 0 are treated as
+   *   no-limit. Does not affect `loadFollowUpTools()`, which always searches
+   *   the full catalog.
+   */
+  async getTools(selection, maxTools) {
+    this.warnIfNotInitialized();
+    let filtered = filterCatalogTools(
+      this.getNormalizedTools(),
+      resolveToolSelectionPolicy(this.config.configuration, selection)
+    );
+    if (typeof maxTools === "number" && maxTools > 0) {
+      filtered = filtered.slice(0, maxTools);
+    }
+    return this.convertTools(filtered);
+  }
+  async listBundles() {
+    this.warnIfNotInitialized();
+    const tools = this.getNormalizedTools();
+    return ZUORA_BUNDLE_NAMES.map((name) => getBundleDefinition(name, tools));
+  }
+  async describeBundle(name) {
+    this.warnIfNotInitialized();
+    if (!hasBundleDefinition(name)) {
+      throw new ZuoraAgentToolkitError({
+        code: "BUNDLE_NOT_FOUND",
+        message: `Unknown Zuora bundle: ${name}`,
+        category: "configuration"
+      });
+    }
+    return getBundleDefinition(name, this.getNormalizedTools());
+  }
+  async describeTool(name) {
+    this.warnIfNotInitialized();
+    return this.getNormalizedTools().find((tool2) => tool2.name === name);
+  }
+  async callTool(operationName, input) {
+    this.warnIfNotInitialized();
+    const tool2 = this.getNormalizedTools().find(
+      (candidate) => candidate.name === operationName
+    );
+    if (!tool2) {
+      throw new ZuoraAgentToolkitError({
+        code: "TOOL_NOT_FOUND",
+        message: `Unknown Zuora tool: ${operationName}`,
+        category: "configuration"
+      });
+    }
+    const mode = this.config.configuration?.mode ?? SafetyMode.ReadOnly;
+    if (mode === SafetyMode.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 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;
+    const effectiveTool = effectiveAccess === tool2.meta.access && effectiveRiskLevel === tool2.meta.riskLevel ? tool2 : { ...tool2, meta: { ...tool2.meta, access: effectiveAccess, riskLevel: effectiveRiskLevel } };
+    await enforceApproval(
+      effectiveTool,
+      input,
+      this.config,
+      (event) => this.emit(event),
+      nativeApprovalMetadata
+    );
+    const startedAt = Date.now();
+    const includePayloads = this.config.observability?.includePayloads === true;
+    const toolEventBase = {
+      toolName: tool2.name,
+      access: effectiveAccess,
+      bundle: tool2.meta.bundle,
+      riskLevel: effectiveRiskLevel,
+      ...this.createEventContext()
+    };
+    this.emit({
+      name: "tool.called",
+      ...toolEventBase,
+      ...includePayloads ? { input: compactToolInputForEvent(input) } : {}
+    });
+    let rawMcpResult;
+    try {
+      let result;
+      if (nativeRuntimeTool) {
+        result = await nativeRuntimeTool.execute(input);
+      } else {
+        enforceOperationSelector(tool2, input);
+        const mcpInput = createMcpToolInput(tool2, input);
+        const rawResult = await this.mcpClient.callTool(
+          tool2.meta.sourceName,
+          mcpInput
+        );
+        rawMcpResult = { ...rawResult, riskLevel: tool2.meta.riskLevel };
+        const resolvedAsyncOperation = tool2.meta.asyncOperation ?? (tool2.meta.asyncOperations && tool2.meta.operationSelector ? tool2.meta.asyncOperations[String(input[tool2.meta.operationSelector] ?? "")] : void 0);
+        const isApiFailure = isRecord(rawResult.data) && rawResult.data["success"] === false;
+        if (resolvedAsyncOperation && !isApiFailure) {
+          const asyncJobResult = buildAsyncJobResult(
+            rawResult,
+            resolvedAsyncOperation,
+            {
+              sourceToolName: tool2.meta.sourceName,
+              ...tool2.meta.operationSelector ? { operationSelector: tool2.meta.operationSelector } : {},
+              sourceOperationNames: this.getNormalizedTools().filter(
+                (candidate) => candidate.meta.sourceName === tool2.meta.sourceName
+              ).map(
+                (candidate) => candidate.meta.operationName ?? candidate.name
+              )
+            }
+          );
+          if (resolvedAsyncOperation.pollingOperation === void 0 && resolvedAsyncOperation.pollingTool === void 0) {
+            this.config.observability?.logger?.warn?.(
+              `[zuora-agent-toolkit] async operation metadata for tool "${tool2.name}" has neither pollingOperation nor pollingTool. Polling will fall back to the source tool "${tool2.meta.sourceName}" which may be incorrect. Check server metadata.`
+            );
+          }
+          const resolvedPollingTool = this.getNormalizedTools().find(
+            (t) => t.name === asyncJobResult.pollingToolName
+          );
+          if (!resolvedPollingTool && resolvedAsyncOperation.pollingTool && resolvedAsyncOperation.pollingOperation) {
+            const mergedPollingTool = this.getNormalizedTools().find(
+              (t) => t.meta.sourceName === resolvedAsyncOperation.pollingTool && t.meta.operationSelector
+            );
+            if (mergedPollingTool) {
+              asyncJobResult.pollingToolName = mergedPollingTool.name;
+              asyncJobResult.pollingArgs = {
+                ...asyncJobResult.pollingArgs,
+                [mergedPollingTool.meta.operationSelector]: resolvedAsyncOperation.pollingOperation
+              };
+            }
+          }
+          result = {
+            toolName: tool2.meta.sourceName,
+            data: asyncJobResult,
+            riskLevel: tool2.meta.riskLevel
+          };
+        } else {
+          result = { ...rawResult, riskLevel: tool2.meta.riskLevel };
+        }
+      }
+      const requestMetadata = extractExecutionRequestMetadata(result);
+      this.emit({
+        name: "tool.completed",
+        ...toolEventBase,
+        ...requestMetadata,
+        latencyMs: Date.now() - startedAt,
+        ...includePayloads ? { output: compactToolOutputForEvent(result) } : {}
+      });
+      return result;
+    } catch (error) {
+      if (error instanceof ZuoraAgentToolkitError) {
+        const eventError2 = compactToolkitError(error);
+        const requestMetadata = error.requestId ? { requestId: error.requestId } : {};
+        const rawOutputForEvent2 = includePayloads && rawMcpResult ? { output: compactToolOutputForEvent(rawMcpResult) } : {};
+        this.emit({
+          name: "tool.failed",
+          ...toolEventBase,
+          ...requestMetadata,
+          ...rawOutputForEvent2,
+          error: eventError2,
+          metadata: { error: eventError2 }
+        });
+        throw error;
+      }
+      const wrappedError = new ZuoraAgentToolkitError({
+        code: "TOOL_EXECUTION_ERROR",
+        message: `Tool "${operationName}" execution failed: ${error instanceof Error ? error.message : String(error)}`,
+        category: "tool_execution",
+        recoverable: true
+      });
+      const eventError = compactToolkitError(wrappedError);
+      const rawOutputForEvent = includePayloads && rawMcpResult ? { output: compactToolOutputForEvent(rawMcpResult) } : {};
+      this.emit({
+        name: "tool.failed",
+        ...toolEventBase,
+        ...rawOutputForEvent,
+        error: eventError,
+        metadata: { error: eventError }
+      });
+      throw wrappedError;
+    }
+  }
+  /**
+   * Polls an async job to completion using the polling operation specified in
+   * the async job result. Returns the final polling tool execution result when
+   * the job reaches a terminal state.
+   *
+   * Polling stops when:
+   * - A terminal status is matched (success, failure, or canceled)
+   * - The maximum number of poll attempts is exhausted
+   * - The absolute timeout is exceeded
+   *
+   * @param toolName - The name of the tool that started the async job. Used for
+   *   observability context only.
+   * @param asyncResult - The pending async job result from an initial tool call.
+   * @param options - Optional overrides for polling behavior.
+   * @throws ZuoraAgentToolkitError with ASYNC_JOB_TIMEOUT if the job does not
+   *   reach a terminal state within the configured limits.
+   */
+  async waitForJob(toolName, asyncResult, options) {
+    this.warnIfNotInitialized();
+    const terminalStatuses = options?.terminalStatuses ?? asyncResult.terminalStatuses ?? DEFAULT_ASYNC_JOB_TERMINAL_STATUSES;
+    const statusPath = asyncResult.statusPath ?? "status";
+    const maxPollAttempts = options?.maxPollAttempts ?? asyncResult.maxPollAttempts ?? 50;
+    const pollIntervalMs = options?.pollIntervalMs ?? asyncResult.recommendedPollIntervalMs ?? 2e3;
+    const timeoutMs = options?.timeoutMs ?? asyncResult.defaultTimeoutMs ?? 3e5;
+    const logger = this.config.observability?.logger;
+    const startedAt = Date.now();
+    for (let attempt = 1; attempt <= maxPollAttempts; attempt++) {
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new ZuoraAgentToolkitError({
+          code: "ASYNC_JOB_TIMEOUT",
+          message: `Async job "${toolName}" (id: ${asyncResult.jobId}) timed out after ${timeoutMs}ms.`,
+          category: "tool_execution",
+          recoverable: false,
+          details: {
+            jobId: asyncResult.jobId,
+            toolName,
+            pollingOperation: asyncResult.pollingOperation,
+            attempt,
+            timeoutMs
+          }
+        });
+      }
+      const pollingInput = resolvePollingInput(asyncResult);
+      const pollResult = await this.callTool(
+        asyncResult.pollingToolName,
+        pollingInput
+      );
+      const statusDetails = resolveAsyncJobStatusDetails(
+        pollResult,
+        statusPath,
+        terminalStatuses
+      );
+      let decision;
+      if (statusDetails.status == null) {
+        decision = "no_status";
+      } else if (statusDetails.terminalState === "success") {
+        decision = "success";
+      } else if (statusDetails.terminalState === "failure") {
+        decision = "failure";
+      } else if (statusDetails.terminalState === "canceled") {
+        decision = "canceled";
+      } else {
+        decision = "continue";
+      }
+      logAsyncPollChecked(logger, {
+        jobId: asyncResult.jobId,
+        attempt,
+        maxAttempts: maxPollAttempts,
+        // pollingToolName is always set on ZuoraAsyncJobResult
+        pollingToolName: asyncResult.pollingToolName,
+        statusPath,
+        statusSource: statusDetails.status != null ? "statusPath" : "none",
+        resolvedValue: statusDetails.status,
+        ...statusDetails.status != null ? { resolvedStatus: statusDetails.status } : {},
+        terminalStatuses,
+        matchedSuccess: statusDetails.terminalState === "success",
+        matchedFailure: statusDetails.terminalState === "failure",
+        matchedCanceled: statusDetails.terminalState === "canceled",
+        decision
+      });
+      if (statusDetails.isTerminal) {
+        return pollResult;
+      }
+      if (attempt < maxPollAttempts) {
+        await sleep(pollIntervalMs);
+      }
+    }
+    throw new ZuoraAgentToolkitError({
+      code: "ASYNC_JOB_TIMEOUT",
+      message: `Async job "${toolName}" (id: ${asyncResult.jobId}) did not reach a terminal state after ${maxPollAttempts} poll attempts.`,
+      category: "tool_execution",
+      recoverable: false,
+      details: {
+        jobId: asyncResult.jobId,
+        toolName,
+        pollingOperation: asyncResult.pollingOperation,
+        maxPollAttempts
+      }
+    });
+  }
+  /**
+   * Returns the full normalized tool catalog after initialization.
+   *
+   * @internal For use by adapter subclasses only (e.g. to implement
+   * follow-up tool resolution against the full catalog). Do not call
+   * from outside the class hierarchy.
+   */
+  getNormalizedTools() {
+    return this.catalogTools ?? [];
+  }
+  resolveSplitOperations() {
+    return this.config.configuration?.splitOperations ?? false;
+  }
+  warnIfNotInitialized() {
+    if (!this._initialized) {
+      console.warn(
+        "Zuora Agent Toolkit accessed before initialize(). Call await toolkit.initialize() first."
+      );
+    }
+  }
+  emit(event) {
+    const normalizedEvent = normalizeToolkitEvent(event, this.sanitizerLimits);
+    const logger = this.config.observability?.logger;
+    try {
+      this.config.observability?.onEvent?.(normalizedEvent);
+    } catch (error) {
+      reportObservabilitySinkError(logger, error);
+    }
+    try {
+      const emitResult = this.config.observability?.emit?.(normalizedEvent);
+      if (emitResult) {
+        void Promise.resolve(emitResult).catch((error) => {
+          reportObservabilitySinkError(logger, error);
+        });
+      }
+    } catch (error) {
+      reportObservabilitySinkError(logger, error);
+    }
+    const message = `[zuora-agent-toolkit] ${normalizedEvent.name}`;
+    try {
+      if (normalizedEvent.name === "tool.failed") {
+        logger?.error?.(message, normalizedEvent);
+        return;
+      }
+      if (normalizedEvent.name === "approval.requested") {
+        logger?.warn?.(message, normalizedEvent);
+        return;
+      }
+      if (normalizedEvent.executionPhase === "async_poll" && (normalizedEvent.name === "tool.called" || normalizedEvent.name === "tool.completed" || normalizedEvent.name === "async.poll.checked")) {
+        logger?.debug?.(message, normalizedEvent);
+        return;
+      }
+      logger?.info?.(message, normalizedEvent);
+    } catch {
+    }
+  }
+  /**
+   * Fetches a Data Query job result to extract the dataFile download URL.
+   * Called by NativeQueryResultDownloadTools to resolve the presigned S3 URL
+   * for a completed query job before handing off to downloadFile.
+   */
+  async fetchQueryResultForDownload(jobId) {
+    const tools = this.getNormalizedTools();
+    const statusCall = resolveQueryResultStatusCall(tools, jobId);
+    if (!statusCall) {
+      throw new ZuoraAgentToolkitError({
+        code: "QUERY_RESULT_STATUS_TOOL_NOT_FOUND",
+        message: "Could not find a Data Query job status tool to resolve the query result dataFile URL.",
+        category: "native_file_tools",
+        recoverable: true,
+        details: {
+          jobId,
+          expectedTool: "manage_data_queries__get_query_job"
+        }
+      });
+    }
+    return this.callTool(statusCall.toolName, statusCall.input);
+  }
+  createEventContext() {
+    const configurationContext = this.config.configuration?.context ?? {};
+    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,
+      ...entityIds ? { entityIds } : {},
+      ...orgIds ? { orgIds } : {}
+    };
+  }
+};
+var JOB_ID_PLACEHOLDERS = /* @__PURE__ */ new Set(["{{jobId}}", "${jobId}"]);
+var resolvePollingInput = (asyncResult) => {
+  const base = { jobId: asyncResult.jobId };
+  if (!asyncResult.pollingArgs) {
+    return base;
+  }
+  const resolved = {};
+  for (const [key, value] of Object.entries(asyncResult.pollingArgs)) {
+    if (JOB_ID_PLACEHOLDERS.has(value)) {
+      resolved[key] = asyncResult.jobId;
+    } else {
+      resolved[key] = value;
+    }
+  }
+  return { ...resolved, ...base };
+};
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// src/shared/configuration.ts
+var ZUORA_TOOLKIT_ENDPOINT_ENV = "ZUORA_BASE_URL or ZUORA_MCP_URL";
+var isEnvSourcedConfig = (config) => "env" in config;
+var mergeConfiguration = (base, overrides) => {
+  if (!base && !overrides) {
+    return void 0;
+  }
+  return {
+    ...base ?? {},
+    ...overrides ?? {},
+    ...overrides?.context || base?.context ? {
+      context: {
+        ...base?.context,
+        ...overrides?.context
+      }
+    } : {}
+  };
+};
+var mergeZuoraAgentToolkitConfig = (base, overrides) => {
+  const { configuration: overrideConfiguration, ...restOverrides } = overrides;
+  const configuration = mergeConfiguration(
+    base.configuration,
+    overrideConfiguration
+  );
+  return {
+    ...base,
+    ...restOverrides,
+    ...configuration ? { configuration } : {}
+  };
+};
+var resolveZuoraAgentToolkitConfig = (config) => {
+  if (!isEnvSourcedConfig(config)) {
+    return config;
+  }
+  const { env: envSource, ...overrides } = config;
+  const env = envSource === true ? process.env : envSource.env ?? process.env;
+  return mergeZuoraAgentToolkitConfig(
+    zuoraAgentToolkitConfigFromEnv(env),
+    overrides
+  );
+};
+var readTrimmedEnv = (env, name) => {
+  const value = env[name]?.trim();
+  return value ? value : void 0;
+};
+var requiredEnv = (env, name) => {
+  const value = readTrimmedEnv(env, name);
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+};
+var readBooleanEnvValue = (name, rawValue) => {
+  const value = rawValue?.trim().toLowerCase();
+  if (!value) {
+    return false;
+  }
+  if (["true", "1", "yes"].includes(value)) {
+    return true;
+  }
+  if (["false", "0", "no"].includes(value)) {
+    return false;
+  }
+  throw new Error(`Invalid ${name}: expected true or false.`);
+};
+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() ?? SafetyMode.ReadOnly;
+  if (mode === SafetyMode.ReadOnly || mode === SafetyMode.WriteEnabled) {
+    return mode;
+  }
+  throw new Error(
+    `Invalid ZUORA_TOOLKIT_MODE: ${mode}. Expected ${SafetyMode.ReadOnly} or ${SafetyMode.WriteEnabled}.`
+  );
+};
+var readConnectionOptions = (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 } : {},
+    ...zuoraVersion ? { zuoraVersion } : {}
+  };
+};
+var zuoraAgentToolkitConfigFromEnv = (env = process.env) => {
+  const baseUrl = readZuoraEndpoint(env);
+  if (!baseUrl) {
+    throw new Error(`Set ${ZUORA_TOOLKIT_ENDPOINT_ENV}.`);
+  }
+  const mode = readToolkitMode(env);
+  const connection = readConnectionOptions(env);
+  if (readBooleanEnv(env, "ZUORA_TENANT_AUTH")) {
+    const tenantId = requiredEnv(env, "ZUORA_TENANT_ID");
+    return {
+      baseUrl,
+      connection: {
+        ...connection,
+        tenantAuth: {
+          enabled: true,
+          tenantId,
+          tokenId: requiredEnv(env, "ZUORA_TOKEN_ID"),
+          userId: requiredEnv(env, "ZUORA_USER_ID")
+        }
+      },
+      configuration: {
+        mode
+      }
+    };
+  }
+  return {
+    baseUrl,
+    auth: {
+      clientId: requiredEnv(env, "ZUORA_CLIENT_ID"),
+      clientSecret: requiredEnv(env, "ZUORA_CLIENT_SECRET")
+    },
+    ...Object.keys(connection).length > 0 ? { connection } : {},
+    configuration: {
+      mode
+    }
+  };
+};
+
+// src/shared/agent-tool-follow-ups.ts
+var QUERY_RESULT_DOWNLOAD_TOOL = "download_query_result";
+var ZUORA_FILE_DOWNLOAD_TOOL = "download_zuora_file";
+var READ_DOWNLOADED_FILE_TOOL = "read_downloaded_file";
+var resolveAgentToolFollowUps = (result, context = {}) => {
+  const followUpToolNames = [];
+  const data = result.data;
+  const jobId = context.asyncJobId ?? findQueryJobId(data);
+  const zuoraFile = resolveZuoraFileResource(data);
+  const hasDownloadUrl = findDownloadUrl(data) !== void 0;
+  const artifactId = findDownloadArtifactId(data);
+  let recommendedNextTool;
+  let recommendedNextArgs;
+  if (zuoraFile) {
+    followUpToolNames.push(ZUORA_FILE_DOWNLOAD_TOOL);
+    recommendedNextTool = ZUORA_FILE_DOWNLOAD_TOOL;
+    recommendedNextArgs = { fileId: zuoraFile.fileId };
+  } else if (hasDownloadUrl && jobId) {
+    followUpToolNames.push(QUERY_RESULT_DOWNLOAD_TOOL, READ_DOWNLOADED_FILE_TOOL);
+    recommendedNextTool = QUERY_RESULT_DOWNLOAD_TOOL;
+    recommendedNextArgs = { jobId };
+  } else if (artifactId && (result.toolName === QUERY_RESULT_DOWNLOAD_TOOL || result.toolName === "download_file" || result.toolName === ZUORA_FILE_DOWNLOAD_TOOL)) {
+    followUpToolNames.push(READ_DOWNLOADED_FILE_TOOL);
+    recommendedNextTool = READ_DOWNLOADED_FILE_TOOL;
+    recommendedNextArgs = { artifactId };
+  }
+  const uniqueFollowUps = [...new Set(followUpToolNames)];
+  return {
+    followUpToolNames: uniqueFollowUps,
+    requireToolOnNextStep: uniqueFollowUps.length > 0,
+    ...recommendedNextTool ? { recommendedNextTool } : {},
+    ...recommendedNextArgs ? { recommendedNextArgs } : {},
+    hasDownloadableOutput: hasDownloadUrl || zuoraFile !== void 0
+  };
+};
+var buildToolMessagePayload = (result, followUp) => {
+  const baseData = typeof result.data === "object" && result.data !== null ? result.data : { value: result.data };
+  if (!followUp.recommendedNextTool) {
+    return baseData;
+  }
+  return {
+    ...baseData,
+    hasDownloadableOutput: followUp.hasDownloadableOutput,
+    recommendedNextTool: followUp.recommendedNextTool,
+    ...followUp.recommendedNextArgs ? { recommendedNextArgs: followUp.recommendedNextArgs } : {}
+  };
+};
+var findQueryJobId = (value) => {
+  const direct = readNonEmptyString(value);
+  if (direct) {
+    return direct;
+  }
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const found = findQueryJobId(item);
+      if (found) {
+        return found;
+      }
+    }
+    return void 0;
+  }
+  const record = value;
+  for (const key of ["jobId", "queryJobId"]) {
+    const candidate = readNonEmptyString(record[key]);
+    if (candidate) {
+      return candidate;
+    }
+  }
+  for (const item of Object.values(record)) {
+    const found = findQueryJobId(item);
+    if (found) {
+      return found;
+    }
+  }
+  const idCandidate = readNonEmptyString(record["id"]);
+  if (idCandidate) {
+    return idCandidate;
+  }
+  return void 0;
+};
+var findDownloadArtifactId = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  const record = value;
+  const direct = readNonEmptyString(record["artifactId"]);
+  if (direct) {
+    return direct;
+  }
+  const download = record["download"];
+  if (typeof download === "object" && download !== null) {
+    const nested = readNonEmptyString(
+      download["artifactId"]
+    );
+    if (nested) {
+      return nested;
+    }
+  }
+  for (const item of Object.values(record)) {
+    if (item === record["download"]) {
+      continue;
+    }
+    const found = findDownloadArtifactId(item);
+    if (found) {
+      return found;
+    }
+  }
+  return void 0;
+};
+var readNonEmptyString = (value) => {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+};
+
+// src/langchain/toolkit.ts
+var ZuoraLangChainToolkit = class extends ToolkitCore {
+  convertTools(tools) {
+    return tools.map((def) => {
+      const sanitizedName = sanitizeAdapterToolName(def.name);
+      const schema = def.inputSchema;
+      return tool(
+        async (input) => {
+          const args = input;
+          const result = await this.callTool(def.name, args);
+          const followUp = resolveAgentToolFollowUps(result);
+          const payload = buildToolMessagePayload(result, followUp);
+          return JSON.stringify(payload);
+        },
+        {
+          name: sanitizedName,
+          description: def.description,
+          schema
+        }
+      );
+    });
+  }
+  async close() {
+    await super.close();
+  }
+};
+var createZuoraLangChainToolkit = async (config) => {
+  const toolkit = new ZuoraLangChainToolkit(
+    resolveZuoraAgentToolkitConfig(config)
+  );
+  await toolkit.initialize();
+  return toolkit;
+};
+export {
+  ZuoraLangChainToolkit,
+  createZuoraLangChainToolkit
+};
 //# sourceMappingURL=index.js.map