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

package/README.md

@@ -1,10 +1,21 @@
 # @zuora/agent-toolkit
 
-> **Alpha release** — APIs may change before the 1.0 stable release.
+> **Beta release — not intended for production use yet.** Customers are welcome to try the kit in sandbox or other non-production environments for evaluation and feedback. APIs may change before the 1.0 stable release.
 
-Zuora billing operations as callable tools for AI agent frameworks.
+## Introduction
 
-Built on the [Zuora MCP server](https://developer.zuora.com). Tool inventory is discovered at runtime from your tenant's MCP endpoint — it is not hardcoded in this package.
+Zuora Agent Kit is an SDK that turns Zuora billing operations into tools an AI agent can call. This package, `@zuora/agent-toolkit`, provides the TypeScript SDK; the Python package, `zuora-agent-toolkit`, is planned.
+
+Instead of wiring each Zuora REST API by hand for an LLM, the kit:
+
+1. Connects to your tenant's [Zuora MCP server](https://developer.zuora.com) using OAuth.
+2. Discovers available operations at runtime — the tool inventory is not hardcoded.
+3. Normalizes them into a shared tool shape, `ZuoraToolDefinition`.
+4. Exposes them in the format your agent framework expects: OpenAI Chat Completions, OpenAI Agents SDK, LangChain, or Vercel AI SDK.
+
+Your agent can then do things like "list accounts" or "run a query" through tool calls, while the kit handles authentication, filtering (read-only vs. writes and tool bundles), approval rules, and observability.
+
+To discover the bundles and tools available for your tenant, see [Discovery and execution](#discovery-and-execution) below.
 
 ## Quick start
 
@@ -34,12 +45,30 @@ Set `ZUORA_BASE_URL`, `ZUORA_CLIENT_ID`, and `ZUORA_CLIENT_SECRET` in your envir
 | `@zuora/agent-toolkit/vercel-ai` | `createZuoraVercelAIToolkit` | ✅ Implemented |
 | `@zuora/agent-toolkit/mcp` | — | 🚧 Coming soon |
 
+## Changelog
+
+### [0.1.0-beta.1]
+
+- First beta release — customers are welcome to evaluate it in sandbox or other non-production environments; it is **not intended for production use yet**.
+- Added an introduction explaining runtime tool discovery, the shared tool definition, framework adapters, and built-in safety and observability controls.
+
+### [0.1.0-alpha.1]
+
+- Fixed HITL approval policy handling with correct `request.environment` usage
+- Improved tool name resolution
+- Removed deprecated `CLI_AGENT_SPLIT_OPERATIONS` references
+- Test and documentation updates
+
+### [0.1.0-alpha.0]
+
+Initial alpha release.
+
 ## Installation
 
 Requires **Node.js 18** or later.
 
 ```bash
-npm install @zuora/agent-toolkit
+npm install @zuora/agent-toolkit@beta
 ```
 
 Framework packages are peer dependencies — install only what you use:
@@ -348,7 +377,11 @@ configuration: {
 
 ### Approval policy
 
-Gate write / high-risk operations before they reach Zuora. `approvalPolicy` is a **top-level** config field (not inside `configuration`):
+Approval policies are checked before a tool executes. An `"allow"` decision lets execution proceed; `"deny"` blocks it with an `APPROVAL_REJECTED` error. If no policy is configured, no additional approval check is performed.
+
+Approval policies are an additional guardrail, not a way to enable writes: write operations must also be enabled through `configuration.mode: SafetyMode.WriteEnabled`. The read-only execution guard runs before the approval policy.
+
+`approvalPolicy` is a **top-level** config field (not inside `configuration`):
 
 ```ts
 import { ApprovalPolicyPreset, SafetyMode } from "@zuora/agent-toolkit";
@@ -365,9 +398,29 @@ const toolkit = await createZuoraOpenAIAgentToolkit({
 });
 ```
 
-Presets: `Off`, `AllWrites`, `HighRisk`, `ProductionWrites`, `ProductionHighRisk`.
+Built-in presets automatically allow or deny operations; they do **not** display an approval prompt. Operations that do not match a preset's denial condition are allowed by that policy.
+
+| Preset | Behavior |
+|---|---|
+| `Off` | No additional approval restriction |
+| `AllWrites` | Denies all write operations |
+| `HighRisk` | Denies all high-risk operations, including reads |
+| `ProductionWrites` | Denies writes when the detected environment is production |
+| `ProductionHighRisk` | Denies high-risk operations when the detected environment is production |
+
+Custom handlers can be synchronous or async and receive:
+
+| Field | Contents |
+|---|---|
+| `request.tool` | Tool definition, including access and risk metadata for the invoked operation |
+| `request.input` | Arguments supplied to the tool |
+| `request.environment` | `"production"` or `"sandbox"`, inferred from `baseUrl` |
+
+**Environment detection:** unrecognized URLs currently default to `"sandbox"`. Production-only presets therefore do not block operations on unrecognized URLs; use a custom policy if your endpoint is not recognized as production.
+
+Custom handler return values: `"allow"` (proceed) · `"deny"` (block) · `{ decision: "allow" | "deny", reason?: string }`. Only `decision` is used; `reason` is not currently included in the rejection error.
 
-Custom handler return values: `"allow"` (proceed) · `"deny"` (block) · `{ decision: "allow" | "deny", reason?: string }` (with an explanation added to the rejection error).
+A custom async `approvalPolicy` can integrate your own approval workflow. For an example combining interactive approval through the OpenAI `shouldExecute` hook with an automated toolkit policy, see [`examples/openai/hitl.ts`](examples/openai/hitl.ts). In that example, the hook prompts before writes and returns a declined result to the model if the user refuses. The toolkit policy separately denies high-risk operations in production, even if the user approved them.
 
 ### Context
 
@@ -495,6 +548,7 @@ Working examples are available in the source repository:
 | `examples/openai/advanced.ts` | Observability, hooks, async jobs, discovery |
 | `examples/openai/hitl.ts` | Human-in-the-loop (HITL) approval |
 | `examples/openai-agents/index.ts` | OpenAI Agents SDK agent |
-| `examples/openai-agents-cli/` | Interactive CLI agent + planner |
+| `examples/openai-agents-cli/` | Interactive CLI agent + planner + dual-layer approval (HITL + toolkit) |
+| `examples/langchain-agents-cli/` | Interactive LangChain CLI agent + planner + dual-layer approval (HITL + toolkit) |
 | `examples/langchain/index.ts` | LangChain ReactAgent with Zuora tools |
 | `examples/vercel-ai/index.ts` | Vercel AI SDK `streamText` agent |

package/dist/langchain/index.js

@@ -4175,8 +4175,17 @@ var createHttpMcpClientConfig = (config) => {
 };
 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.mode === SafetyMode.ReadOnly) {
+    if (tool2.meta.operationAccess) {
+      const hasReadOperation = Object.values(tool2.meta.operationAccess).some(
+        (access) => access === "read"
+      );
+      if (!hasReadOperation) {
+        return false;
+      }
+    } else if (tool2.meta.access === "write") {
+      return false;
+    }
   }
   if (policy.bundles.size > 0 && !policy.bundles.has(tool2.meta.bundle)) {
     return false;
@@ -4338,18 +4347,18 @@ var ToolkitCore = class {
       });
     }
     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;
+    if (mode === SafetyMode.ReadOnly && effectiveAccess === "write") {
+      throw new ZuoraAgentToolkitError({
+        code: "TOOL_EXECUTION_ERROR",
+        message: `Write operation "${invokedOperation ?? operationName}" is disabled in readOnly mode.`,
+        category: "tool_execution"
+      });
+    }
     const effectiveTool = effectiveAccess === tool2.meta.access && effectiveRiskLevel === tool2.meta.riskLevel ? tool2 : { ...tool2, meta: { ...tool2.meta, access: effectiveAccess, riskLevel: effectiveRiskLevel } };
     await enforceApproval(
       effectiveTool,