@ai-sdk/harness 1.0.38 → 1.0.40

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @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
+
+- 86a84c9: fix(harness): settle a turn aborted by the caller's abortSignal with an `abort` stream part instead of an AbortError `error` part, matching `streamText`'s abort contract
+  - ai@7.0.34
+
 ## 1.0.38
 
 ### 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,8 +182,11 @@ import {
   executeTool,
   generateId as generateId4,
   isExecutableTool,
-  safeParseJSON
+  safeParseJSON as safeParseJSON2
 } from "@ai-sdk/provider-utils";
+import {
+  getErrorMessage
+} from "@ai-sdk/provider";
 import { parseToolCall } from "ai/internal";
 
 // src/agent/internal/harness-stream-text-result.ts
@@ -457,6 +461,24 @@ var HarnessStreamTextResult = class {
     });
     this.fullStreamController.close();
   }
+  /**
+   * Settle the turn as user-aborted: emit a final `abort` part — matching
+   * `streamText`'s abort contract — and close the stream, instead of
+   * surfacing an `error` part. `toUIMessageStream` consumers then observe
+   * an `abort` chunk (and `isAborted: true`) rather than a spurious
+   * `onError`. The delayed promise accessors still reject with the
+   * underlying abort error so awaiting consumers do not hang. Idempotent.
+   */
+  abort(input) {
+    if (this.settled) return;
+    this.settled = true;
+    this.fullStreamController.enqueue({
+      type: "abort",
+      ...input.reason !== void 0 ? { reason: input.reason } : {}
+    });
+    this.fullStreamController.close();
+    this.rejectDelayedPromises(input.error);
+  }
   /**
    * Surface a fatal error as a stream `error` part + reject every delayed
    * promise so awaiting consumers stop hanging. Idempotent.
@@ -469,6 +491,9 @@ var HarnessStreamTextResult = class {
       error
     });
     this.fullStreamController.close();
+    this.rejectDelayedPromises(error);
+  }
+  rejectDelayedPromises(error) {
     for (const dp of [
       this._content,
       this._text,
@@ -596,6 +621,7 @@ var HarnessStreamTextResult = class {
   toUIMessageStream({
     originalMessages,
     generateMessageId,
+    onEnd,
     onFinish,
     messageMetadata,
     sendReasoning,
@@ -610,6 +636,7 @@ var HarnessStreamTextResult = class {
         tools: this.tools,
         originalMessages,
         generateMessageId,
+        onEnd,
         onFinish,
         messageMetadata,
         sendReasoning,
@@ -629,6 +656,7 @@ var HarnessStreamTextResult = class {
   toUIMessageStreamResponse({
     originalMessages,
     generateMessageId,
+    onEnd,
     onFinish,
     messageMetadata,
     sendReasoning,
@@ -642,6 +670,7 @@ var HarnessStreamTextResult = class {
       stream: this.toUIMessageStream({
         originalMessages,
         generateMessageId,
+        onEnd,
         onFinish,
         messageMetadata,
         sendReasoning,
@@ -896,7 +925,10 @@ var NOOP = {
   },
   stepFinish() {
   },
-  toolStart() {
+  async toolStart() {
+  },
+  async executeTool({ execute }) {
+    return await execute();
   },
   toolEnd() {
   },
@@ -1055,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,
@@ -1073,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;
@@ -1235,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;
@@ -1265,8 +1316,20 @@ function runPrompt(input) {
     promptText: input.prompt != null ? promptToText(input.prompt) : "",
     runtimeContext: input.runtimeContext
   });
+  const settleFailure = (err) => {
+    var _a4, _b4;
+    (_a4 = input.onTurnFailed) == null ? void 0 : _a4.call(input);
+    if ((_b4 = input.abortSignal) == null ? void 0 : _b4.aborted) {
+      result.abort({
+        error: err,
+        ...input.abortSignal.reason !== void 0 ? { reason: getErrorMessage(input.abortSignal.reason) } : {}
+      });
+      return;
+    }
+    result.fail(err);
+  };
   const done = (async () => {
-    var _a4, _b4, _c2, _d2, _e2, _f2, _g2, _h, _i, _j, _k, _l, _m;
+    var _a4, _b4, _c2, _d2, _e2, _f2, _g2, _h, _i, _j, _k;
     let bridge;
     try {
       bridge = await toHarnessStream({
@@ -1297,8 +1360,7 @@ function runPrompt(input) {
         context: "failed to start harness turn",
         error: err
       });
-      (_a4 = input.onTurnFailed) == null ? void 0 : _a4.call(input);
-      result.fail(err);
+      settleFailure(err);
       return;
     }
     const { stream, control } = bridge;
@@ -1312,7 +1374,7 @@ function runPrompt(input) {
       pendingToolApprovals.map((approval) => [approval.toolCallId, approval])
     );
     const continuationsByApprovalId = new Map(
-      ((_b4 = input.toolApprovalContinuations) != null ? _b4 : []).map((continuation) => [
+      ((_a4 = input.toolApprovalContinuations) != null ? _a4 : []).map((continuation) => [
         continuation.approvalResponse.approvalId,
         continuation
       ])
@@ -1324,14 +1386,21 @@ function runPrompt(input) {
       ])
     );
     const continuationsByToolCallId = new Map(
-      ((_c2 = input.toolResultContinuations) != null ? _c2 : []).map((continuation) => [
+      ((_b4 = input.toolResultContinuations) != null ? _b4 : []).map((continuation) => [
         continuation.toolCallId,
         continuation
       ])
     );
     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 = [];
@@ -1372,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) {
@@ -1478,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,
@@ -1538,8 +1616,29 @@ 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((_d2 = value.modelId) != null ? _d2 : input.session.modelId);
         }
@@ -1587,6 +1686,17 @@ function runPrompt(input) {
             continue;
           }
         }
+        if (value.type === "error" && displayValue.type === "error") {
+          telemetry.error(value.error);
+          logBridgeError({
+            harnessId: input.harness.harnessId,
+            sessionId: input.session.sessionId,
+            context: "harness stream error",
+            error: value.error
+          });
+          settleFailure(displayValue.error);
+          return;
+        }
         for (const part of translateStreamPart(displayValue)) {
           result.enqueue(part);
         }
@@ -1612,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
@@ -1675,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;
@@ -1783,6 +1900,7 @@ function runPrompt(input) {
           const execution = await maybeExecuteHostTool({
             event: toolCall,
             tools: activeTools,
+            wrappedExecuteTool: telemetry.executeTool,
             sandboxSession: input.sandboxSession,
             abortSignal: input.abortSignal,
             control,
@@ -1813,23 +1931,11 @@ function runPrompt(input) {
           }
           telemetry.toolEnd(toolCall.toolCallId, execution.outcome);
         }
-        if (value.type === "error") {
-          telemetry.error(value.error);
-          logBridgeError({
-            harnessId: input.harness.harnessId,
-            sessionId: input.session.sessionId,
-            context: "harness stream error",
-            error: value.error
-          });
-          (_j = input.onTurnFailed) == null ? void 0 : _j.call(input);
-          result.fail(value.error);
-          return;
-        }
       }
       if (finalFinish != null) {
-        (_k = input.onTurnFinished) == null ? void 0 : _k.call(input);
+        (_j = input.onTurnFinished) == null ? void 0 : _j.call(input);
       } else {
-        (_l = input.onTurnFailed) == null ? void 0 : _l.call(input);
+        (_k = input.onTurnFailed) == null ? void 0 : _k.call(input);
       }
       await result.finish(
         finalFinish ? {
@@ -1846,9 +1952,9 @@ function runPrompt(input) {
         context: "harness turn failed",
         error: err
       });
-      (_m = input.onTurnFailed) == null ? void 0 : _m.call(input);
-      result.fail(err);
+      settleFailure(err);
     } finally {
+      releasePendingStopBoundary();
       reader.releaseLock();
     }
   })();
@@ -1870,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
@@ -2009,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(),
@@ -2031,7 +2144,8 @@ var HarnessAgentSession = class {
         },
         onTurnFailed: () => {
           this.finishTrackedTurn({ turnId });
-        }
+        },
+        onStopConditionMet: () => this.captureStopConditionBoundary({ session, turnId })
       });
       return turn;
     } catch (error) {
@@ -2059,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(),
@@ -2083,7 +2198,8 @@ var HarnessAgentSession = class {
         },
         onTurnFailed: () => {
           this.finishTrackedTurn({ turnId });
-        }
+        },
+        onStopConditionMet: () => this.captureStopConditionBoundary({ session, turnId })
       });
       return turn;
     } catch (error) {
@@ -2249,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;
@@ -2305,6 +2432,7 @@ var HarnessAgentSession = class {
   startTrackedTurn() {
     const turnId = ++this.turnSequence;
     this.activeTurnSequence = turnId;
+    this.suspendedTurnState = void 0;
     this.turnState = "running";
     return turnId;
   }
@@ -2313,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) {
@@ -2833,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 : {};
@@ -3080,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
       });
@@ -3093,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) {