@ai-sdk/harness 1.0.39 → 1.0.40

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ai-sdk/harness
 
+## 1.0.40
+
+### Patch Changes
+
+- 59a2306: fix(harness): execute host tools through telemetry context wrappers
+- 5f65e61: feat(harness): add support for `stopWhen` control to `HarnessAgent` (e.g. `isStepCount(1)`)
+- Updated dependencies [7f6650b]
+- Updated dependencies [106ea59]
+  - ai@7.0.35
+
 ## 1.0.39
 
 ### Patch Changes

package/dist/agent/index.d.ts

@@ -1,6 +1,6 @@
 import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
-import { Experimental_SandboxSession, UserModelMessage, ToolSet, FlexibleSchema, Tool, ToolApprovalResponse, ModelMessage, Context } from '@ai-sdk/provider-utils';
-import { ToolApprovalStatus, TelemetryOptions, ActiveTools, StreamTextResult, Agent, AgentCallParameters, GenerateTextResult, AgentStreamParameters, Telemetry } from 'ai';
+import { Experimental_SandboxSession, UserModelMessage, ToolSet, FlexibleSchema, Tool, Context, Arrayable, ToolApprovalResponse, ModelMessage } from '@ai-sdk/provider-utils';
+import { StopCondition, ToolApprovalStatus, TelemetryOptions, ActiveTools, StreamTextResult, Agent, AgentCallParameters, GenerateTextResult, AgentStreamParameters, Telemetry } from 'ai';
 import { z } from 'zod/v4';
 import { JSONValue, LanguageModelV4ToolCall, LanguageModelV4ToolApprovalRequest, LanguageModelV4ToolResult, LanguageModelV4FinishReason, LanguageModelV4Usage, JSONSchema7, AISDKError } from '@ai-sdk/provider';
 
@@ -1143,7 +1143,7 @@ type HarnessAgentToolFilteringSettings<TOOLS extends ToolSet> = {
      */
     readonly inactiveTools?: HarnessTools<TOOLS>;
 };
-type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter, TUserTools extends ToolSet = {}> = {
+type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter, TUserTools extends ToolSet = {}, RUNTIME_CONTEXT extends Context = Context> = {
     /**
      * The harness adapter driving the underlying agent runtime. Its
      * `builtinTools` are merged with the user-defined `tools` and exposed to
@@ -1177,6 +1177,16 @@ type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAge
      * later turns or when resuming a previously ended session.
      */
     readonly instructions?: string;
+    /**
+     * Conditions that stop the current result after a completed harness tool
+     * step that can continue into another model step. The underlying turn remains
+     * unfinished and can be suspended and continued.
+     *
+     * A terminal text-only step finishes naturally and is not stopped early.
+     *
+     * When omitted, the harness runs until the turn naturally finishes or pauses.
+     */
+    readonly stopWhen?: Arrayable<StopCondition<NoInfer<HarnessAllTools<THarness, TUserTools>>, RUNTIME_CONTEXT>>;
     /**
      * Built-in tool permission mode. Defaults to `'allow-all'`, preserving the
      * existing bypass-permissions behavior unless users opt in.
@@ -1303,6 +1313,7 @@ declare class HarnessAgentSession {
     private turnState;
     private turnSequence;
     private activeTurnSequence;
+    private suspendedTurnState;
     /**
      * Whether this session was created from `resumeFrom` or `continueFrom`.
      * Captured at construction so it survives lifecycle cleanup.
@@ -1332,6 +1343,7 @@ declare class HarnessAgentSession {
         runtimeContext: RUNTIME_CONTEXT;
         abortSignal: AbortSignal | undefined;
         telemetry: TelemetryOptions | undefined;
+        stopConditions: ReadonlyArray<StopCondition<TOOLS, RUNTIME_CONTEXT>>;
     }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT>;
     continueTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context>(options: {
         instructions: string | undefined;
@@ -1342,6 +1354,7 @@ declare class HarnessAgentSession {
         runtimeContext: RUNTIME_CONTEXT;
         abortSignal: AbortSignal | undefined;
         telemetry: TelemetryOptions | undefined;
+        stopConditions: ReadonlyArray<StopCondition<TOOLS, RUNTIME_CONTEXT>>;
         toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[] | undefined;
         toolResultContinuations?: readonly HarnessAgentToolResultContinuation[] | undefined;
     }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT>;
@@ -1392,6 +1405,7 @@ declare class HarnessAgentSession {
     private getPendingToolResults;
     private addPendingToolState;
     private suspendCurrentTurn;
+    private captureStopConditionBoundary;
     private toResumeStateWithContinuation;
     private requirePromptableTurn;
     private requireContinuableTurn;
@@ -1461,11 +1475,12 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
      */
     readonly tools: HarnessAllTools<THarness, TUserTools>;
     private readonly settings;
+    private readonly stopConditions;
     private readonly sandboxConfig;
     private readonly activeUserTools;
     private readonly builtinToolFiltering;
     private readonly permissionMode;
-    constructor(settings: HarnessAgentSettings<THarness, TUserTools>);
+    constructor(settings: HarnessAgentSettings<THarness, TUserTools, RUNTIME_CONTEXT>);
     /** Identifier of the harness backing this agent. */
     get harnessId(): string;
     /**

package/dist/agent/index.js

@@ -40,6 +40,7 @@ var HarnessCapabilityUnsupportedError = class extends (_b2 = HarnessError, _a2 =
 
 // src/agent/harness-agent.ts
 import {
+  asArray as asArray2,
   asSchema,
   generateId as generateId5
 } from "@ai-sdk/provider-utils";
@@ -181,7 +182,7 @@ import {
   executeTool,
   generateId as generateId4,
   isExecutableTool,
-  safeParseJSON
+  safeParseJSON as safeParseJSON2
 } from "@ai-sdk/provider-utils";
 import {
   getErrorMessage
@@ -924,7 +925,10 @@ var NOOP = {
   },
   stepFinish() {
   },
-  toolStart() {
+  async toolStart() {
+  },
+  async executeTool({ execute }) {
+    return await execute();
   },
   toolEnd() {
   },
@@ -1083,11 +1087,12 @@ function createTurnTelemetry(opts) {
       stepOpen = false;
       stepNumber += 1;
     },
-    toolStart(call) {
+    async toolStart(call) {
       var _a4;
       ensureStepOpen();
+      if (openTools.has(call.toolCallId)) return;
       openTools.set(call.toolCallId, call);
-      (_a4 = dispatcher.onToolExecutionStart) == null ? void 0 : _a4.call(
+      await ((_a4 = dispatcher.onToolExecutionStart) == null ? void 0 : _a4.call(
         dispatcher,
         cast({
           callId,
@@ -1101,7 +1106,11 @@ function createTurnTelemetry(opts) {
           },
           toolContext: void 0
         })
-      );
+      ));
+    },
+    async executeTool({ toolCallId, execute }) {
+      if (dispatcher.executeTool == null) return await execute();
+      return await dispatcher.executeTool({ callId, toolCallId, execute });
     },
     toolEnd(toolCallId, output) {
       var _a4;
@@ -1263,6 +1272,20 @@ function logBridgeError({
   }
 }
 
+// src/utils/sandbox-channel.ts
+import {
+  safeParseJSON,
+  safeValidateTypes as safeValidateTypes2
+} from "@ai-sdk/provider-utils";
+var sandboxChannelEventCheckpointSymbol = /* @__PURE__ */ Symbol.for(
+  "vercel.ai.harness.sandboxChannelEventCheckpoint"
+);
+function pinSandboxChannelEventCheckpoint(event) {
+  var _a3;
+  if (event == null || typeof event !== "object") return void 0;
+  return (_a3 = event[sandboxChannelEventCheckpointSymbol]) == null ? void 0 : _a3.pin();
+}
+
 // src/agent/internal/run-prompt.ts
 function runPrompt(input) {
   var _a3, _b3, _c, _d, _e, _f, _g;
@@ -1306,7 +1329,7 @@ function runPrompt(input) {
     result.fail(err);
   };
   const done = (async () => {
-    var _a4, _b4, _c2, _d2, _e2, _f2, _g2, _h, _i, _j;
+    var _a4, _b4, _c2, _d2, _e2, _f2, _g2, _h, _i, _j, _k;
     let bridge;
     try {
       bridge = await toHarnessStream({
@@ -1370,7 +1393,14 @@ function runPrompt(input) {
     );
     const settledHostToolCallIds = /* @__PURE__ */ new Set();
     let closingResumedStep = false;
+    let pendingStopBoundary;
     let finalFinish;
+    const completedSteps = [];
+    const releasePendingStopBoundary = () => {
+      var _a5;
+      (_a5 = pendingStopBoundary == null ? void 0 : pendingStopBoundary.releaseCheckpoint) == null ? void 0 : _a5.call(pendingStopBoundary);
+      pendingStopBoundary = void 0;
+    };
     let stepText = "";
     let stepReasoning = "";
     let stepToolCalls = [];
@@ -1411,12 +1441,14 @@ function runPrompt(input) {
         content: buildStepContent()
       });
       resetStepContent();
-      return result.finishStep({
+      const step = result.finishStep({
         finishReason: input2.finishReason,
         usage: input2.usage,
         providerMetadata: input2.providerMetadata,
         warnings: []
       });
+      completedSteps.push(step);
+      return step;
     };
     const finishForHostInputPause = async (options) => {
       if (options.completeCurrentStep) {
@@ -1517,9 +1549,16 @@ function runPrompt(input) {
         toolName: approval.toolName,
         input: approval.input
       };
+      telemetry.start(input.session.modelId);
+      await telemetry.toolStart({
+        toolCallId: rawToolCall.toolCallId,
+        toolName: rawToolCall.toolName,
+        input: rawToolCall.input
+      });
       const execution = await maybeExecuteHostTool({
         event: rawToolCall,
         tools: activeTools,
+        wrappedExecuteTool: telemetry.executeTool,
         sandboxSession: input.sandboxSession,
         abortSignal: input.abortSignal,
         control,
@@ -1577,10 +1616,31 @@ function runPrompt(input) {
       }
       while (true) {
         const { value, done: done2 } = await reader.read();
-        if (done2) break;
+        if (done2) {
+          releasePendingStopBoundary();
+          break;
+        }
         if (value == null) continue;
+        if (pendingStopBoundary != null) {
+          if (value.type === "finish") {
+            releasePendingStopBoundary();
+          } else if ((await Promise.all(
+            input.stopConditions.map(
+              (condition) => condition({ steps: completedSteps })
+            )
+          )).some(Boolean)) {
+            await ((_c2 = input.onStopConditionMet) == null ? void 0 : _c2.call(input));
+            const { finishReason, usage } = pendingStopBoundary;
+            releasePendingStopBoundary();
+            telemetry.end({ finishReason, usage });
+            await result.finish();
+            return;
+          } else {
+            releasePendingStopBoundary();
+          }
+        }
         if (value.type === "stream-start") {
-          telemetry.start((_c2 = value.modelId) != null ? _c2 : input.session.modelId);
+          telemetry.start((_d2 = value.modelId) != null ? _d2 : input.session.modelId);
         }
         if (value.type !== "stream-start" && value.type !== "finish-step" && value.type !== "finish" && value.type !== "error") {
           telemetry.ensureStepOpen();
@@ -1606,7 +1666,7 @@ function runPrompt(input) {
           const rawToolCall = rawToolCallsByToolCallId.get(
             displayValue.toolCallId
           );
-          const toolName = (_d2 = rawToolCall == null ? void 0 : rawToolCall.toolName) != null ? _d2 : toolCall.toolName;
+          const toolName = (_e2 = rawToolCall == null ? void 0 : rawToolCall.toolName) != null ? _e2 : toolCall.toolName;
           if (!isHarnessV1BuiltinToolIncluded({
             toolName,
             toolFiltering: input.builtinToolFiltering
@@ -1662,7 +1722,7 @@ function runPrompt(input) {
             toolName: value.toolName,
             input: value.input
           });
-          telemetry.toolStart({
+          await telemetry.toolStart({
             toolCallId: value.toolCallId,
             toolName: value.toolName,
             input: value.input
@@ -1682,13 +1742,13 @@ function runPrompt(input) {
             );
           }
           const rawToolCall = rawToolCallsByToolCallId.get(value.toolCallId);
-          const pendingApproval = (_g2 = pendingApprovalsByApprovalId.get(value.approvalId)) != null ? _g2 : {
+          const pendingApproval = (_h = pendingApprovalsByApprovalId.get(value.approvalId)) != null ? _h : {
             approvalId: value.approvalId,
             toolCallId: value.toolCallId,
             toolName: toolCall.toolName,
-            input: (_e2 = rawToolCall == null ? void 0 : rawToolCall.input) != null ? _e2 : JSON.stringify(toolCall.input),
+            input: (_f2 = rawToolCall == null ? void 0 : rawToolCall.input) != null ? _f2 : JSON.stringify(toolCall.input),
             kind: "builtin",
-            providerExecuted: (_f2 = rawToolCall == null ? void 0 : rawToolCall.providerExecuted) != null ? _f2 : true,
+            providerExecuted: (_g2 = rawToolCall == null ? void 0 : rawToolCall.providerExecuted) != null ? _g2 : true,
             ...(rawToolCall == null ? void 0 : rawToolCall.nativeName) !== void 0 ? { nativeName: rawToolCall.nativeName } : {}
           };
           pendingApprovalsByApprovalId.set(
@@ -1725,6 +1785,13 @@ function runPrompt(input) {
             usage: value.usage,
             providerMetadata: value.harnessMetadata
           });
+          if (input.stopConditions != null && input.stopConditions.length > 0) {
+            pendingStopBoundary = {
+              finishReason: value.finishReason,
+              usage: value.usage,
+              releaseCheckpoint: pinSandboxChannelEventCheckpoint(value)
+            };
+          }
         }
         if (value.type === "finish") {
           finalFinish = value;
@@ -1784,7 +1851,7 @@ function runPrompt(input) {
             telemetry.toolEnd(toolCall.toolCallId, { ok: true, output });
             continue;
           }
-          const pendingApproval = (_h = pendingApprovalsByToolCallId.get(toolCall.toolCallId)) != null ? _h : customToolApprovalDecision.type === "request" ? {
+          const pendingApproval = (_i = pendingApprovalsByToolCallId.get(toolCall.toolCallId)) != null ? _i : customToolApprovalDecision.type === "request" ? {
             approvalId: generateId4(),
             toolCallId: toolCall.toolCallId,
             toolName: toolCall.toolName,
@@ -1833,6 +1900,7 @@ function runPrompt(input) {
           const execution = await maybeExecuteHostTool({
             event: toolCall,
             tools: activeTools,
+            wrappedExecuteTool: telemetry.executeTool,
             sandboxSession: input.sandboxSession,
             abortSignal: input.abortSignal,
             control,
@@ -1865,9 +1933,9 @@ function runPrompt(input) {
         }
       }
       if (finalFinish != null) {
-        (_i = input.onTurnFinished) == null ? void 0 : _i.call(input);
+        (_j = input.onTurnFinished) == null ? void 0 : _j.call(input);
       } else {
-        (_j = input.onTurnFailed) == null ? void 0 : _j.call(input);
+        (_k = input.onTurnFailed) == null ? void 0 : _k.call(input);
       }
       await result.finish(
         finalFinish ? {
@@ -1886,6 +1954,7 @@ function runPrompt(input) {
       });
       settleFailure(err);
     } finally {
+      releasePendingStopBoundary();
       reader.releaseLock();
     }
   })();
@@ -1907,28 +1976,34 @@ function hasTool(input) {
 async function maybeExecuteHostTool(input) {
   const tool = input.tools[input.event.toolName];
   if (!isExecutableTool(tool)) return { executed: false };
-  const parsed = await safeParseJSON({ text: input.event.input });
+  const parsed = await safeParseJSON2({ text: input.event.input });
   const args = parsed.success ? parsed.value : input.event.input;
   try {
-    let output;
-    const stream = executeTool({
-      tool,
-      input: args,
-      options: {
-        toolCallId: input.event.toolCallId,
-        messages: [],
-        abortSignal: input.abortSignal,
-        context: void 0,
-        experimental_sandbox: input.sandboxSession
+    const output = await input.wrappedExecuteTool({
+      toolCallId: input.event.toolCallId,
+      execute: async () => {
+        let output2;
+        const stream = executeTool({
+          tool,
+          input: args,
+          options: {
+            toolCallId: input.event.toolCallId,
+            messages: [],
+            abortSignal: input.abortSignal,
+            context: void 0,
+            experimental_sandbox: input.sandboxSession
+          }
+        });
+        for await (const part of stream) {
+          if (part.type === "preliminary") {
+            input.onPreliminaryResult(part.output);
+          } else {
+            output2 = part.output;
+          }
+        }
+        return output2;
       }
     });
-    for await (const part of stream) {
-      if (part.type === "preliminary") {
-        input.onPreliminaryResult(part.output);
-      } else {
-        output = part.output;
-      }
-    }
     await input.control.submitToolResult({
       toolCallId: input.event.toolCallId,
       output
@@ -2046,6 +2121,7 @@ var HarnessAgentSession = class {
         runtimeContext: options.runtimeContext,
         abortSignal: options.abortSignal,
         telemetry: options.telemetry,
+        stopConditions: options.stopConditions,
         toolApproval: this.toolApproval,
         pendingToolApprovals: this.getPendingToolApprovals(),
         pendingToolResults: this.getPendingToolResults(),
@@ -2068,7 +2144,8 @@ var HarnessAgentSession = class {
         },
         onTurnFailed: () => {
           this.finishTrackedTurn({ turnId });
-        }
+        },
+        onStopConditionMet: () => this.captureStopConditionBoundary({ session, turnId })
       });
       return turn;
     } catch (error) {
@@ -2096,6 +2173,7 @@ var HarnessAgentSession = class {
         runtimeContext: options.runtimeContext,
         abortSignal: options.abortSignal,
         telemetry: options.telemetry,
+        stopConditions: options.stopConditions,
         toolApproval: this.toolApproval,
         pendingToolApprovals: this.getPendingToolApprovals(),
         pendingToolResults: this.getPendingToolResults(),
@@ -2120,7 +2198,8 @@ var HarnessAgentSession = class {
         },
         onTurnFailed: () => {
           this.finishTrackedTurn({ turnId });
-        }
+        },
+        onStopConditionMet: () => this.captureStopConditionBoundary({ session, turnId })
       });
       return turn;
     } catch (error) {
@@ -2286,14 +2365,25 @@ var HarnessAgentSession = class {
     };
   }
   async suspendCurrentTurn(options) {
-    const raw = await options.session.doSuspendTurn();
-    const validated = await validateLifecycleStateData({
-      harness: this.harness,
-      state: raw,
-      expectedType: "continue-turn"
-    });
+    var _a3;
+    (_a3 = this.suspendedTurnState) != null ? _a3 : this.suspendedTurnState = (async () => {
+      const raw = await options.session.doSuspendTurn();
+      const validated = await validateLifecycleStateData({
+        harness: this.harness,
+        state: raw,
+        expectedType: "continue-turn"
+      });
+      return this.addPendingToolState(validated);
+    })();
+    const state = await this.suspendedTurnState;
     this.turnState = "suspended";
-    return this.addPendingToolState(validated);
+    return state;
+  }
+  async captureStopConditionBoundary(options) {
+    if (this.sessionState !== "active" || this.activeTurnSequence !== options.turnId) {
+      return;
+    }
+    await this.suspendCurrentTurn({ session: options.session });
   }
   toResumeStateWithContinuation(options) {
     const { continueFrom } = options;
@@ -2342,6 +2432,7 @@ var HarnessAgentSession = class {
   startTrackedTurn() {
     const turnId = ++this.turnSequence;
     this.activeTurnSequence = turnId;
+    this.suspendedTurnState = void 0;
     this.turnState = "running";
     return turnId;
   }
@@ -2350,6 +2441,7 @@ var HarnessAgentSession = class {
     if (this.activeTurnSequence !== options.turnId) return;
     this.pendingToolApprovals.clear();
     this.pendingToolResults.clear();
+    this.suspendedTurnState = void 0;
     this.turnState = "idle";
   }
   endLocalHandle(options) {
@@ -2870,6 +2962,7 @@ var HarnessAgent = class {
     const sandboxConfig = resolveSandboxConfig(settings);
     validateSandboxBootstrapSettings(sandboxConfig);
     this.settings = settings;
+    this.stopConditions = settings.stopWhen == null ? [] : asArray2(settings.stopWhen);
     this.sandboxConfig = sandboxConfig;
     this.id = settings.id;
     const userTools = (_a3 = settings.tools) != null ? _a3 : {};
@@ -3117,6 +3210,7 @@ var HarnessAgent = class {
         runtimeContext: input.runtimeContext,
         abortSignal: input.abortSignal,
         telemetry: this.settings.telemetry,
+        stopConditions: this.stopConditions,
         toolApprovalContinuations: input.turnInput.toolApprovalContinuations,
         toolResultContinuations: input.turnInput.toolResultContinuations
       });
@@ -3130,7 +3224,8 @@ var HarnessAgent = class {
       builtinToolFiltering: this.builtinToolFiltering,
       runtimeContext: input.runtimeContext,
       abortSignal: input.abortSignal,
-      telemetry: this.settings.telemetry
+      telemetry: this.settings.telemetry,
+      stopConditions: this.stopConditions
     });
   }
   async _acquireSandbox(input) {