@zuora/agent-toolkit 0.0.1-alpha.0

package/dist/openai/index.d.ts

@@ -0,0 +1,165 @@
+import { Z as ZuoraOpenAIAgentToolkit } from '../toolkit-CafRZuAV.js';
+export { c as createZuoraOpenAIAgentToolkit } from '../toolkit-CafRZuAV.js';
+import { ChatCompletion, ChatCompletionToolMessageParam } from 'openai/resources/chat/completions';
+import { b as ZuoraToolExecutionResult, Z as ZuoraToolDefinition, c as ZuoraAsyncJobResult } from '../async-jobs-Dd8Jafv0.js';
+import '../shared/toolkit-core.js';
+
+type ZuoraOpenAIToolExecutionContext = {
+    toolName: string;
+    input: Record<string, unknown>;
+};
+/**
+ * Return value from `shouldExecute` when the hook wants to decline a tool call.
+ * Returning `void` (or `undefined`) from `shouldExecute` means proceed.
+ */
+type ZuoraToolDecision = {
+    /**
+     * Set to `true` to decline the tool call. `handleToolCalls` will inject a
+     * "declined" tool message into the conversation and skip execution.
+     * `onToolExecuted` and `onToolComplete` will not fire for declined calls.
+     */
+    decline: true;
+    /**
+     * Optional message sent to the model explaining why the call was declined.
+     * Defaults to "The operation was not approved." when omitted.
+     * Keep it instructional — e.g. "User declined. Do not retry."
+     */
+    message?: string;
+};
+type ZuoraOpenAIAgentToolkitHooks = {
+    onToolStart?: (context: ZuoraOpenAIToolExecutionContext) => void | Promise<void>;
+    /**
+     * Fires after the raw MCP result is received from `callTool`, before any
+     * async-job handling. Useful for logging or side-effects that must observe
+     * the exact, unmodified tool output.
+     *
+     * For async tools, `result.data` will be a pending `ZuoraAsyncJobResult`
+     * here even when `shouldAutoWait` returns `true` — `onToolExecuted` always
+     * sees the immediate return value. `onToolComplete` receives the final
+     * resolved result after any auto-waiting.
+     *
+     * `onToolExecuted` is not called when `callTool` throws.
+     *
+     * @param context.toolName - The name of the tool that was executed.
+     * @param context.input - The input arguments passed to the tool.
+     * @param context.result - The raw execution result from `callTool`.
+     */
+    onToolExecuted?: (context: ZuoraOpenAIToolExecutionContext & {
+        result: ZuoraToolExecutionResult;
+    }) => void | Promise<void>;
+    /**
+     * Fires after all async-job handling is complete and the final result is
+     * ready to be sent back to the model.
+     *
+     * - For **synchronous tools**: `result` is the direct return value of
+     *   `callTool` — identical to what `onToolExecuted` receives.
+     * - For **async tools with `shouldAutoWait: true`**: `result` is the final
+     *   resolved value after `waitForJob()` finishes polling — it differs from
+     *   the pending `result` that `onToolExecuted` received.
+     * - For **async tools with `shouldAutoWait: false`** (or unset): `result`
+     *   is the pending async job result, same as `onToolExecuted`. The caller
+     *   is expected to poll via `requireToolOnNextStep` / `loadFollowUpTools`.
+     *
+     * `onToolComplete` is not called when `callTool` throws — use error
+     * handling in the agent loop for that case.
+     *
+     * @param context.toolName - The name of the tool that completed.
+     * @param context.input - The input arguments passed to the tool.
+     * @param context.result - The final execution result (post async-wait).
+     */
+    onToolComplete?: (context: ZuoraOpenAIToolExecutionContext & {
+        result: ZuoraToolExecutionResult;
+    }) => void | Promise<void>;
+    /**
+     * Controls whether `handleToolCalls` automatically polls an async job to
+     * completion before returning the result to the caller.
+     *
+     * When this hook returns `true` for a given async job, `handleToolCalls`
+     * will call `toolkit.waitForJob()` and return the final result instead of
+     * the pending async job result.
+     *
+     * When this hook returns `false` (or is not provided), the pending async
+     * job result is returned as-is and `requireToolOnNextStep` is set to `true`
+     * so the caller knows to continue the agent loop with a polling call.
+     *
+     * @param context.toolName - The name of the tool that started the async job.
+     * @param context.asyncResult - The pending async job result.
+     */
+    /**
+     * Called before each tool is executed. Return `{ decline: true }` to skip
+     * execution and inject a "declined" message into the conversation so the
+     * model can respond gracefully. Return `void` (or nothing) to proceed.
+     *
+     * Use this hook for interactive human-in-the-loop decisions — e.g. prompting
+     * the user at the CLI before a write operation runs. For automated policy
+     * enforcement that applies across all adapters, use `approvalPolicy` on the
+     * toolkit config instead.
+     *
+     * `context.tool` carries the full tool definition — `meta.access`,
+     * `meta.riskLevel`, `meta.bundle` — so the handler can make a
+     * context-aware decision without resolving the tool separately.
+     *
+     * `onToolExecuted` and `onToolComplete` do not fire for declined calls.
+     * `abortTurn` is NOT set — the agent loop continues after a decline.
+     *
+     * @example
+     * ```ts
+     * shouldExecute: async ({ toolName, input, tool }) => {
+     *   if (tool.meta.access === "read") return; // reads proceed silently
+     *   const ok = await askUser(`Allow ${toolName}?`);
+     *   if (!ok) return { decline: true, message: "User declined. Do not retry." };
+     * }
+     * ```
+     */
+    shouldExecute?: (context: ZuoraOpenAIToolExecutionContext & {
+        tool: ZuoraToolDefinition;
+    }) => void | ZuoraToolDecision | Promise<void | ZuoraToolDecision>;
+    /**
+     * Controls whether `handleToolCalls` automatically polls an async job to
+     * completion before returning the result to the caller.
+     *
+     * When this hook returns `true` for a given async job, `handleToolCalls`
+     * will call `toolkit.waitForJob()` and return the final result instead of
+     * the pending async job result.
+     *
+     * When this hook returns `false` (or is not provided), the pending async
+     * job result is returned as-is and `requireToolOnNextStep` is set to `true`
+     * so the caller knows to continue the agent loop with a polling call.
+     *
+     * @param context.toolName - The name of the tool that started the async job.
+     * @param context.asyncResult - The pending async job result.
+     */
+    shouldAutoWait?: (context: ZuoraOpenAIToolExecutionContext & {
+        asyncResult: ZuoraAsyncJobResult;
+    }) => boolean | Promise<boolean>;
+};
+
+type HandleToolCallsInput = {
+    toolkit: ZuoraOpenAIAgentToolkit;
+    response: ChatCompletion;
+    hooks?: ZuoraOpenAIAgentToolkitHooks;
+};
+type HandleToolCallsResult = {
+    /** Tool message params to append to the conversation. */
+    messages: ChatCompletionToolMessageParam[];
+    /**
+     * True when a non-recoverable tool error occurred. The caller should break
+     * the agent loop rather than sending the messages back to the model.
+     */
+    abortTurn: boolean;
+    /**
+     * True when at least one async job is pending (status: "pending" was returned
+     * by a tool). The caller should set `tool_choice: "required"` on the next
+     * model call so the model continues polling rather than generating prose.
+     */
+    requireToolOnNextStep: boolean;
+    /**
+     * Names of tools the server recommends calling next (e.g. the polling tool
+     * for an async job that was just started). The caller may use these to
+     * narrow the `tools` list on the next model call.
+     */
+    followUpToolNames: string[];
+};
+declare const handleToolCalls: (input: HandleToolCallsInput) => Promise<HandleToolCallsResult>;
+
+export { type HandleToolCallsInput, type HandleToolCallsResult, ZuoraOpenAIAgentToolkit, type ZuoraOpenAIAgentToolkitHooks, type ZuoraOpenAIToolExecutionContext, handleToolCalls };