@ai-sdk/workflow 2.0.15 → 2.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/workflow",
-  "version": "2.0.15",
+  "version": "2.0.17",
   "type": "module",
   "description": "WorkflowAgent for building AI agents with AI SDK",
   "license": "Apache-2.0",
@@ -33,7 +33,7 @@
   "dependencies": {
     "@ai-sdk/provider": "4.0.9",
     "@ai-sdk/provider-utils": "5.0.34",
-    "ai": "7.0.85",
+    "ai": "7.0.87",
     "ajv": "^8.20.0"
   },
   "devDependencies": {

package/src/do-stream-step.ts

@@ -25,6 +25,12 @@ import {
 
 export type ModelCallStreamPart<TTools extends ToolSet = ToolSet> =
   | Experimental_LanguageModelStreamPart<TTools>
+  | {
+      type: 'tool-approval-request';
+      approvalId: string;
+      toolCallId: string;
+      signature?: string;
+    }
   | { type: 'reset-step' };
 
 export type ModelStopCondition = StopCondition<NoInfer<ToolSet>, any>;
@@ -326,7 +332,16 @@ export async function doStreamStep(
 
       // Write to writable in real-time
       if (writer) {
-        await writer.write(part);
+        if (part.type === 'tool-approval-request') {
+          await writer.write({
+            type: 'tool-approval-request',
+            approvalId: part.approvalId,
+            toolCallId: part.toolCall.toolCallId,
+            ...(part.signature != null ? { signature: part.signature } : {}),
+          });
+        } else {
+          await writer.write(part);
+        }
       }
 
       if (part.type === 'error' && !hasTerminalError) {

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   type WorkflowAgentOptions,
   type WorkflowAgentStreamOptions,
   type WorkflowAgentStreamResult,
+  type WorkflowToolApprovalSecret,
   type GenerationSettings,
   type InferWorkflowAgentTools,
   type InferWorkflowAgentUIMessage,

package/src/test/agent-e2e-workflows.ts

@@ -28,6 +28,13 @@ async function throwingStep(): Promise<string> {
   throw new FatalError('Tool execution failed fatally');
 }
 
+async function executeApprovedAction(input: {
+  action: string;
+}): Promise<string> {
+  'use step';
+  return `executed:${input.action}`;
+}
+
 // ============================================================================
 // Core agent tests
 // ============================================================================
@@ -514,6 +521,96 @@ export async function agentToolApprovalE2e() {
   };
 }
 
+const signedToolApprovalSecret = {
+  environmentVariable: 'WORKFLOW_TOOL_APPROVAL_SECRET',
+};
+
+export async function agentSignedToolApprovalIssueE2e() {
+  'use workflow';
+  const agent = new WorkflowAgent({
+    model: mockSequenceModel([
+      {
+        type: 'tool-call',
+        toolName: 'riskyTool',
+        input: JSON.stringify({ action: 'delete' }),
+      },
+    ]),
+    tools: {
+      riskyTool: tool({
+        description: 'A dangerous tool that needs approval',
+        inputSchema: z.object({ action: z.string() }),
+        execute: executeApprovedAction,
+        needsApproval: true,
+      }),
+    },
+    experimental_toolApprovalSecret: signedToolApprovalSecret,
+  });
+
+  const result = await agent.stream({
+    messages: [{ role: 'user', content: 'do something risky' }],
+    writable: getWritable(),
+  });
+
+  return { toolCallsCount: result.toolCalls.length };
+}
+
+export async function agentSignedToolApprovalResumeE2e(signature: string) {
+  'use workflow';
+  const agent = new WorkflowAgent({
+    model: mockSequenceModel([{ type: 'text', text: 'approved action done' }]),
+    tools: {
+      riskyTool: tool({
+        description: 'A dangerous tool that needs approval',
+        inputSchema: z.object({ action: z.string() }),
+        execute: executeApprovedAction,
+        needsApproval: true,
+      }),
+    },
+    experimental_toolApprovalSecret: signedToolApprovalSecret,
+  });
+
+  const result = await agent.stream({
+    messages: [
+      { role: 'user', content: 'do something risky' },
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: 'tool-call',
+            toolCallId: 'call-1',
+            toolName: 'riskyTool',
+            input: { action: 'delete' },
+          },
+          {
+            type: 'tool-approval-request',
+            approvalId: 'approval-call-1',
+            toolCallId: 'call-1',
+            signature,
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        content: [
+          {
+            type: 'tool-approval-response',
+            approvalId: 'approval-call-1',
+            approved: true,
+          },
+        ],
+      },
+    ],
+    writable: getWritable(),
+  });
+
+  return {
+    lastStepText: result.steps.at(-1)?.text,
+    containsApprovedToolResult: JSON.stringify(result.messages).includes(
+      'executed:delete',
+    ),
+  };
+}
+
 // ============================================================================
 // Tool with input schema (tests serialization across step boundary)
 // ============================================================================

package/src/to-ui-message-chunk.ts

@@ -185,20 +185,22 @@ export function toUIMessageChunk(
     case 'raw':
       return undefined;
 
+    case 'tool-approval-request':
+      return {
+        type: 'tool-approval-request',
+        approvalId: part.approvalId,
+        toolCallId:
+          'toolCallId' in part ? part.toolCallId : part.toolCall.toolCallId,
+        ...(part.signature != null ? { signature: part.signature } : {}),
+      };
+
     default: {
-      // Pass through tool-approval-request, step boundaries, and other
-      // chunks as-is. Step boundaries (finish-step/start-step) are not
-      // standard ModelCallStreamPart types but are written by the
-      // WorkflowAgent between tool execution and the next model step
-      // to ensure proper message splitting in convertToModelMessages.
+      // Pass through step boundaries and other chunks as-is. Step boundaries
+      // (finish-step/start-step) are not standard ModelCallStreamPart types
+      // but are written by the WorkflowAgent between tool execution and the
+      // next model step to ensure proper message splitting in
+      // convertToModelMessages.
       const passthroughPart = part as any;
-      if (passthroughPart.type === 'tool-approval-request') {
-        return {
-          type: 'tool-approval-request',
-          approvalId: passthroughPart.approvalId,
-          toolCallId: passthroughPart.toolCallId,
-        } as UIMessageChunk;
-      }
       if (
         passthroughPart.type === 'finish-step' ||
         passthroughPart.type === 'start-step' ||

package/src/workflow-agent.ts

@@ -34,14 +34,17 @@ import {
   type TelemetryOptions as CoreTelemetryOptions,
   type Instructions,
   type Experimental_SandboxSession as SandboxSession,
+  InvalidToolApprovalSignatureError,
 } from 'ai';
 import {
   createRestrictedTelemetryDispatcher,
   collectToolApprovals,
   convertToLanguageModelPrompt,
   mergeCallbacks,
+  signToolApproval,
   standardizePrompt,
   validateApprovedToolApprovals,
+  verifyToolApprovalSignature,
 } from 'ai/internal';
 import { createLanguageModelToolResultOutput } from './create-language-model-tool-result-output.js';
 import type { ModelCallStreamPart } from './do-stream-step.js';
@@ -116,6 +119,17 @@ export interface OutputSpecification<OUTPUT, PARTIAL> {
  */
 export type ProviderOptions = SharedV4ProviderOptions;
 
+/**
+ * Workflow-safe reference to the environment variable that contains the
+ * secret used to sign and verify tool approvals.
+ */
+export type WorkflowToolApprovalSecret = {
+  /**
+   * Name of an environment variable containing a high-entropy secret.
+   */
+  environmentVariable: string;
+};
+
 type WorkflowAgentToolsContextParameter<TTools extends ToolSet> =
   HasRequiredKey<InferToolSetContext<TTools>> extends true
     ? { toolsContext: InferToolSetContext<TTools> }
@@ -543,6 +557,18 @@ export type WorkflowAgentOptions<
      */
     experimental_sandbox?: SandboxSession;
 
+    /**
+     * Workflow-safe reference to the environment variable containing the
+     * secret for HMAC-signing tool approval requests. When set, the agent signs
+     * each approval request and verifies the signature before executing an
+     * approved tool replayed from client-supplied message history.
+     *
+     * Only the environment variable name crosses workflow boundaries. The
+     * secret value is read inside signing and verification steps and is never
+     * serialized. Per-stream values override this default.
+     */
+    experimental_toolApprovalSecret?: WorkflowToolApprovalSecret;
+
     /**
      * Default callback function called before each step in the agent loop.
      * Use this to modify settings, manage context, or inject messages dynamically
@@ -1002,6 +1028,18 @@ export type WorkflowAgentStreamOptions<
      */
     experimental_sandbox?: SandboxSession;
 
+    /**
+     * Workflow-safe reference to the environment variable containing the
+     * secret for HMAC-signing tool approval requests. When set, the agent signs
+     * each approval request and verifies the signature before executing an
+     * approved tool replayed from client-supplied message history.
+     *
+     * Only the environment variable name crosses workflow boundaries. The
+     * secret value is read inside signing and verification steps and is never
+     * serialized. Overrides the constructor-level value if provided.
+     */
+    experimental_toolApprovalSecret?: WorkflowToolApprovalSecret;
+
     /**
      * Callback function to be called after each step completes.
      */
@@ -1266,6 +1304,7 @@ export class WorkflowAgent<
   private repairToolCall?: ToolCallRepairFunction<TBaseTools>;
   private experimentalDownload?: DownloadFunction;
   private experimentalSandbox?: SandboxSession;
+  private experimentalToolApprovalSecret?: WorkflowToolApprovalSecret;
   private prepareStep?: PrepareStepCallback<TBaseTools, TRuntimeContext>;
   private allowSystemInMessages: boolean;
   private constructorOnStepEnd?: WorkflowAgentOnStepEndCallback<
@@ -1305,6 +1344,8 @@ export class WorkflowAgent<
       options.repairToolCall ?? options.experimental_repairToolCall;
     this.experimentalDownload = options.experimental_download;
     this.experimentalSandbox = options.experimental_sandbox;
+    this.experimentalToolApprovalSecret =
+      options.experimental_toolApprovalSecret;
     this.prepareStep = options.prepareStep;
     this.constructorOnStepEnd = options.onStepEnd ?? options.onStepFinish;
     const { onFinish, onEnd = onFinish } = options;
@@ -1374,6 +1415,9 @@ export class WorkflowAgent<
       options.activeTools ?? this.activeTools;
     let effectiveDownloadFromPrepare =
       options.experimental_download ?? this.experimentalDownload;
+    const effectiveToolApprovalSecret =
+      options.experimental_toolApprovalSecret ??
+      this.experimentalToolApprovalSecret;
     let effectiveTelemetryFromPrepare = options.telemetry ?? this.telemetry;
 
     // Resolve messages for prepareCall: use messages directly, or convert prompt
@@ -1562,11 +1606,20 @@ export class WorkflowAgent<
           }
 
           // Re-validate through the shared core implementation: input schema,
-          // HMAC signature (when configured), and approval policy. Convert
-          // invalid input, denial, or signature errors to a tool error result
-          // so the agent loop can continue gracefully.
+          // approval signature (when configured), and approval policy.
+          // Convert invalid input, denial, or signature errors to a tool error
+          // result so the agent loop can continue gracefully.
           let revalidationReason: string | undefined;
           try {
+            await validateWorkflowToolApprovalSignature({
+              secret: effectiveToolApprovalSecret,
+              approvalId: approval.collected.approvalRequest.approvalId,
+              toolCallId: approval.toolCallId,
+              toolName: approval.toolName,
+              input: approval.input,
+              signature: approval.collected.approvalRequest.signature,
+            });
+
             const { deniedToolApprovals: policyDenied, invalidToolApprovals } =
               await validateApprovedToolApprovals({
                 approvedToolApprovals: [approval.collected],
@@ -2394,13 +2447,31 @@ export class WorkflowAgent<
                 return approvalNeeded[tcIndex];
               });
               if (approvalToolCalls.length > 0) {
-                await writeApprovalRequests(
-                  options.writable,
-                  approvalToolCalls.map(tc => ({
-                    toolCallId: tc.toolCallId,
-                    toolName: tc.toolName,
-                  })),
+                // The signing step receives only a non-secret environment
+                // variable reference. It resolves the secret inside the step,
+                // and only the resulting signature is persisted in the stream.
+                const approvalRequests = await Promise.all(
+                  approvalToolCalls.map(async tc => {
+                    const approvalId = `approval-${tc.toolCallId}`;
+                    const signature =
+                      effectiveToolApprovalSecret == null
+                        ? undefined
+                        : await signWorkflowToolApproval({
+                            secret: effectiveToolApprovalSecret,
+                            approvalId,
+                            toolCallId: tc.toolCallId,
+                            toolName: tc.toolName,
+                            input: tc.input,
+                          });
+
+                    return {
+                      approvalId,
+                      toolCallId: tc.toolCallId,
+                      ...(signature != null ? { signature } : {}),
+                    };
+                  }),
                 );
+                await writeApprovalRequests(options.writable, approvalRequests);
               }
             }
 
@@ -2727,16 +2798,21 @@ async function closeStream(
  */
 async function writeApprovalRequests(
   writable: WritableStream<any>,
-  toolCalls: Array<{ toolCallId: string; toolName: string }>,
+  approvalRequests: Array<{
+    approvalId: string;
+    toolCallId: string;
+    signature?: string;
+  }>,
 ) {
   'use step';
   const writer = writable.getWriter();
   try {
-    for (const tc of toolCalls) {
+    for (const request of approvalRequests) {
       await writer.write({
         type: 'tool-approval-request',
-        approvalId: `approval-${tc.toolCallId}`,
-        toolCallId: tc.toolCallId,
+        approvalId: request.approvalId,
+        toolCallId: request.toolCallId,
+        ...(request.signature != null ? { signature: request.signature } : {}),
       });
     }
   } finally {
@@ -2744,6 +2820,116 @@ async function writeApprovalRequests(
   }
 }
 
+async function signWorkflowToolApproval({
+  secret,
+  approvalId,
+  toolCallId,
+  toolName,
+  input,
+}: {
+  secret: WorkflowToolApprovalSecret;
+  approvalId: string;
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+}): Promise<string> {
+  'use step';
+
+  return signToolApproval({
+    secret: getWorkflowToolApprovalSecret(secret),
+    approvalId,
+    toolCallId,
+    toolName,
+    input,
+  });
+}
+
+async function verifyWorkflowToolApprovalSignature({
+  secret,
+  signature,
+  approvalId,
+  toolCallId,
+  toolName,
+  input,
+}: {
+  secret: WorkflowToolApprovalSecret;
+  signature: string;
+  approvalId: string;
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+}): Promise<boolean> {
+  'use step';
+
+  return verifyToolApprovalSignature({
+    secret: getWorkflowToolApprovalSecret(secret),
+    signature,
+    approvalId,
+    toolCallId,
+    toolName,
+    input,
+  });
+}
+
+async function validateWorkflowToolApprovalSignature({
+  secret,
+  signature,
+  approvalId,
+  toolCallId,
+  toolName,
+  input,
+}: {
+  secret: WorkflowToolApprovalSecret | undefined;
+  signature: string | undefined;
+  approvalId: string;
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+}): Promise<void> {
+  if (secret == null) {
+    return;
+  }
+
+  if (signature == null) {
+    throw new InvalidToolApprovalSignatureError({
+      approvalId,
+      toolCallId,
+      reason: 'missing signature',
+    });
+  }
+
+  const valid = await verifyWorkflowToolApprovalSignature({
+    secret,
+    signature,
+    approvalId,
+    toolCallId,
+    toolName,
+    input,
+  });
+
+  if (!valid) {
+    throw new InvalidToolApprovalSignatureError({
+      approvalId,
+      toolCallId,
+      reason: 'invalid signature',
+    });
+  }
+}
+
+function getWorkflowToolApprovalSecret({
+  environmentVariable,
+}: WorkflowToolApprovalSecret): string {
+  const secret = process.env[environmentVariable];
+
+  if (secret == null) {
+    throw new Error(
+      `Tool approval secret environment variable "${environmentVariable}" is not set`,
+    );
+  }
+
+  return secret;
+}
+
 async function writeToolResults(
   writable: WritableStream<any>,
   results: Array<{