@ai-sdk/harness 1.0.39 → 1.0.40

package/src/agent/harness-agent-settings.ts

@@ -9,10 +9,17 @@ import type {
   HarnessAgentSkill,
 } from './harness-agent-types';
 import type {
+  Arrayable,
+  Context,
   Experimental_SandboxSession as SandboxSession,
   ToolSet,
 } from '@ai-sdk/provider-utils';
-import type { ActiveTools, TelemetryOptions, ToolApprovalStatus } from 'ai';
+import type {
+  ActiveTools,
+  StopCondition,
+  TelemetryOptions,
+  ToolApprovalStatus,
+} from 'ai';
 import type { HarnessAllTools } from './harness-agent-tool-types';
 
 export type HarnessAgentToolApprovalConfiguration = Readonly<
@@ -91,6 +98,7 @@ type HarnessAgentToolFilteringSettings<TOOLS extends ToolSet> =
 export type HarnessAgentSettings<
   THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter,
   TUserTools extends ToolSet = {},
+  RUNTIME_CONTEXT extends Context = Context,
 > = {
   /**
    * The harness adapter driving the underlying agent runtime. Its
@@ -130,6 +138,22 @@ export type HarnessAgentSettings<
    */
   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.

package/src/agent/harness-agent.ts

@@ -6,6 +6,7 @@ import type {
   HarnessV1SandboxProvider,
 } from '../v1';
 import {
+  asArray,
   asSchema,
   generateId,
   type Context,
@@ -19,6 +20,7 @@ import type {
   GenerateTextResult,
   ReasoningFileOutput,
   ReasoningOutput,
+  StopCondition,
   StreamTextResult,
 } from 'ai';
 import type {
@@ -133,7 +135,14 @@ export class HarnessAgent<
    */
   readonly tools: HarnessAllTools<THarness, TUserTools>;
 
-  private readonly settings: HarnessAgentSettings<THarness, TUserTools>;
+  private readonly settings: HarnessAgentSettings<
+    THarness,
+    TUserTools,
+    RUNTIME_CONTEXT
+  >;
+  private readonly stopConditions: Array<
+    StopCondition<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT>
+  >;
   private readonly sandboxConfig: HarnessAgentSandboxConfig;
   private readonly activeUserTools: TUserTools;
   private readonly builtinToolFiltering:
@@ -141,10 +150,14 @@ export class HarnessAgent<
     | undefined;
   private readonly permissionMode: HarnessAgentPermissionMode;
 
-  constructor(settings: HarnessAgentSettings<THarness, TUserTools>) {
+  constructor(
+    settings: HarnessAgentSettings<THarness, TUserTools, RUNTIME_CONTEXT>,
+  ) {
     const sandboxConfig = resolveSandboxConfig(settings);
     validateSandboxBootstrapSettings(sandboxConfig);
     this.settings = settings;
+    this.stopConditions =
+      settings.stopWhen == null ? [] : asArray(settings.stopWhen);
     this.sandboxConfig = sandboxConfig;
     this.id = settings.id;
     const userTools = settings.tools ?? ({} as TUserTools);
@@ -528,6 +541,7 @@ export class HarnessAgent<
         runtimeContext: input.runtimeContext,
         abortSignal: input.abortSignal,
         telemetry: this.settings.telemetry,
+        stopConditions: this.stopConditions,
         toolApprovalContinuations: input.turnInput.toolApprovalContinuations,
         toolResultContinuations: input.turnInput.toolResultContinuations,
       });
@@ -546,6 +560,7 @@ export class HarnessAgent<
       runtimeContext: input.runtimeContext,
       abortSignal: input.abortSignal,
       telemetry: this.settings.telemetry,
+      stopConditions: this.stopConditions,
     });
   }
 

package/src/agent/internal/run-prompt.ts

@@ -32,6 +32,7 @@ import type {
   ContentPart,
   ProviderMetadata,
   StepResult,
+  StopCondition,
   TelemetryOptions,
   TextStreamPart,
 } from 'ai';
@@ -41,9 +42,14 @@ import type { HarnessAgentToolApprovalConfiguration } from '../harness-agent-set
 import { HarnessStreamTextResult } from './harness-stream-text-result';
 import { translateStreamPart } from './translate-stream-part';
 import { stripWorkDir } from './strip-work-dir';
-import { createTurnTelemetry, type TurnContentPart } from './turn-telemetry';
+import {
+  createTurnTelemetry,
+  type TurnContentPart,
+  type TurnTelemetry,
+} from './turn-telemetry';
 import { resolveCustomToolApproval } from './permission-mode';
 import { logBridgeError } from '../../utils/bridge-diagnostics';
+import { pinSandboxChannelEventCheckpoint } from '../../utils/sandbox-channel';
 
 /**
  * Drive one prompt turn end-to-end:
@@ -81,6 +87,7 @@ export function runPrompt<
   runtimeContext: RUNTIME_CONTEXT;
   abortSignal: AbortSignal | undefined;
   telemetry?: TelemetryOptions | undefined;
+  stopConditions?: ReadonlyArray<StopCondition<TOOLS, RUNTIME_CONTEXT>>;
   toolApproval?: HarnessAgentToolApprovalConfiguration | undefined;
   pendingToolApprovals?: readonly HarnessV1PendingToolApproval[];
   pendingToolResults?: readonly HarnessV1PendingToolResult[];
@@ -96,6 +103,7 @@ export function runPrompt<
   onToolResultSettled?: (toolCallId: string) => void;
   onTurnFinished?: () => void;
   onTurnFailed?: () => void;
+  onStopConditionMet?: () => Promise<void>;
 }): {
   result: HarnessStreamTextResult<TOOLS, RUNTIME_CONTEXT>;
   done: Promise<void>;
@@ -220,9 +228,21 @@ export function runPrompt<
     );
     const settledHostToolCallIds = new Set<string>();
     let closingResumedStep = false;
+    let pendingStopBoundary:
+      | {
+          finishReason: LanguageModelV4FinishReason;
+          usage: LanguageModelV4Usage;
+          releaseCheckpoint: (() => void) | undefined;
+        }
+      | undefined;
     let finalFinish:
       | Extract<HarnessV1StreamPart, { type: 'finish' }>
       | undefined;
+    const completedSteps: Array<StepResult<TOOLS, RUNTIME_CONTEXT>> = [];
+    const releasePendingStopBoundary = (): void => {
+      pendingStopBoundary?.releaseCheckpoint?.();
+      pendingStopBoundary = undefined;
+    };
 
     // Accumulate the model's output content per step so telemetry can record
     // `gen_ai.output.messages` and reporters can log what was actually said.
@@ -270,12 +290,14 @@ export function runPrompt<
         content: buildStepContent(),
       });
       resetStepContent();
-      return result.finishStep({
+      const step = result.finishStep({
         finishReason: input.finishReason,
         usage: input.usage,
         providerMetadata: input.providerMetadata,
         warnings: [],
       });
+      completedSteps.push(step);
+      return step;
     };
     const finishForHostInputPause = async (options: {
       completeCurrentStep: boolean;
@@ -413,9 +435,16 @@ export function runPrompt<
           input: approval.input,
         } satisfies Extract<HarnessV1StreamPart, { type: 'tool-call' }>);
 
+      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,
@@ -478,9 +507,35 @@ export function runPrompt<
 
       while (true) {
         const { value, done } = await reader.read();
-        if (done) break;
+        if (done) {
+          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 input.onStopConditionMet?.();
+            const { finishReason, usage } = pendingStopBoundary;
+            releasePendingStopBoundary();
+            telemetry.end({ finishReason, usage });
+            await result.finish();
+            return;
+          } else {
+            releasePendingStopBoundary();
+          }
+        }
+
         // Begin the operation span on stream-start, using the runtime-resolved
         // model the adapter reports (falling back to the session's model).
         if (value.type === 'stream-start') {
@@ -609,7 +664,7 @@ export function runPrompt<
             toolName: value.toolName,
             input: value.input,
           });
-          telemetry.toolStart({
+          await telemetry.toolStart({
             toolCallId: value.toolCallId,
             toolName: value.toolName,
             input: value.input,
@@ -686,6 +741,13 @@ export function runPrompt<
             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') {
@@ -803,6 +865,7 @@ export function runPrompt<
           const execution = await maybeExecuteHostTool({
             event: toolCall,
             tools: activeTools,
+            wrappedExecuteTool: telemetry.executeTool,
             sandboxSession: input.sandboxSession,
             abortSignal: input.abortSignal,
             control,
@@ -869,6 +932,7 @@ export function runPrompt<
       });
       settleFailure(err);
     } finally {
+      releasePendingStopBoundary();
       reader.releaseLock();
     }
   })();
@@ -921,6 +985,7 @@ function hasTool(input: { tools: ToolSet; toolName: string }): boolean {
 async function maybeExecuteHostTool<TOOLS extends ToolSet>(input: {
   event: { toolCallId: string; toolName: string; input: string };
   tools: TOOLS;
+  wrappedExecuteTool: TurnTelemetry['executeTool'];
   sandboxSession: SandboxSession;
   abortSignal: AbortSignal | undefined;
   control: HarnessV1PromptControl;
@@ -949,25 +1014,31 @@ async function maybeExecuteHostTool<TOOLS extends ToolSet>(input: {
      * back to the model — preliminary values are surfaced to the consumer
      * stream alone, matching how the AI SDK treats `onPreliminaryToolResult`.
      */
-    let output: unknown;
-    const stream = executeTool({
-      tool,
-      input: args as never,
-      options: {
-        toolCallId: input.event.toolCallId,
-        messages: [],
-        abortSignal: input.abortSignal,
-        context: undefined as never,
-        experimental_sandbox: input.sandboxSession,
+    const output = await input.wrappedExecuteTool({
+      toolCallId: input.event.toolCallId,
+      execute: async () => {
+        let output: unknown;
+        const stream = executeTool({
+          tool,
+          input: args as never,
+          options: {
+            toolCallId: input.event.toolCallId,
+            messages: [],
+            abortSignal: input.abortSignal,
+            context: undefined as never,
+            experimental_sandbox: input.sandboxSession,
+          },
+        });
+        for await (const part of stream) {
+          if (part.type === 'preliminary') {
+            input.onPreliminaryResult(part.output);
+          } else {
+            output = part.output;
+          }
+        }
+        return output;
       },
     });
-    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,

package/src/agent/internal/turn-telemetry.ts

@@ -58,7 +58,12 @@ export interface TurnTelemetry {
     toolCallId: string;
     toolName: string;
     input: unknown;
-  }): void;
+  }): void | Promise<void>;
+  /** Execute a host tool through each telemetry integration's context wrapper. */
+  executeTool<T>(input: {
+    toolCallId: string;
+    execute: () => PromiseLike<T>;
+  }): Promise<T>;
   /**
    * A tool execution completed (on its `tool-result` or after host execution).
    * Idempotent per `toolCallId` — the first caller wins, so provider-executed
@@ -78,7 +83,10 @@ const NOOP: TurnTelemetry = {
   start() {},
   ensureStepOpen() {},
   stepFinish() {},
-  toolStart() {},
+  async toolStart() {},
+  async executeTool({ execute }) {
+    return await execute();
+  },
   toolEnd() {},
   end() {},
   error() {},
@@ -258,10 +266,11 @@ export function createTurnTelemetry(opts: {
       stepNumber += 1;
     },
 
-    toolStart(call) {
+    async toolStart(call) {
       ensureStepOpen();
+      if (openTools.has(call.toolCallId)) return;
       openTools.set(call.toolCallId, call);
-      dispatcher.onToolExecutionStart?.(
+      await dispatcher.onToolExecutionStart?.(
         cast<'onToolExecutionStart'>({
           callId,
           messages: [],
@@ -277,6 +286,11 @@ export function createTurnTelemetry(opts: {
       );
     },
 
+    async executeTool({ toolCallId, execute }) {
+      if (dispatcher.executeTool == null) return await execute();
+      return await dispatcher.executeTool({ callId, toolCallId, execute });
+    },
+
     toolEnd(toolCallId, output) {
       const call = openTools.get(toolCallId);
       if (call == null) return;

package/src/bridge/index.ts

@@ -234,6 +234,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
   let currentBoundPort = 0;
   let currentTurnState: BridgeState = 'init';
   let activeSocket: WebSocket | undefined;
+  let activeSocketReadyForLiveEvents = false;
   let isFirstTurn = true;
   let turnAbort: AbortController | undefined;
   let currentUserMessages: string[] | undefined;
@@ -389,7 +390,10 @@ export async function runBridge<TStart extends { type: 'start' }>(
     eventLog.push({ seq, line });
     diskBuffer += `${line}\n`;
     scheduleEventFlush();
-    if (activeSocket?.readyState === WS_OPEN) {
+    if (
+      activeSocketReadyForLiveEvents &&
+      activeSocket?.readyState === WS_OPEN
+    ) {
       try {
         activeSocket.send(line);
       } catch {
@@ -522,6 +526,8 @@ export async function runBridge<TStart extends { type: 'start' }>(
   ): Promise<void> => {
     switch (msg.type) {
       case 'start': {
+        if (activeSocket !== ws) return;
+        activeSocketReadyForLiveEvents = true;
         const firstTurn = isFirstTurn;
         isFirstTurn = false;
         eventLog = []; // clear previous turn; keep seqCounter monotonic
@@ -643,7 +649,9 @@ export async function runBridge<TStart extends { type: 'start' }>(
         }
         return;
       case 'resume':
+        if (activeSocket !== ws) return;
         replay(ws, msg.lastSeenEventId);
+        activeSocketReadyForLiveEvents = true;
         return;
       case 'shutdown':
         currentTurnState = 'done';
@@ -721,6 +729,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
     // (the host reconnecting after a drop). The previous socket's close is a
     // no-op below because it is no longer `activeSocket`.
     activeSocket = ws;
+    activeSocketReadyForLiveEvents = false;
 
     // Announce liveness the instant we accept. Some sandbox runtimes complete
     // the host-side WS handshake before the connection is forwarded here; the
@@ -754,6 +763,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
       // log for replay when the host reconnects.
       if (activeSocket === ws) {
         activeSocket = undefined;
+        activeSocketReadyForLiveEvents = false;
       }
     });
 

package/src/utils/sandbox-channel.ts

@@ -75,6 +75,30 @@ type Listener<TOut extends { type: string }, T extends EventTypeOf<TOut>> = (
   event: Extract<TOut, { type: T }>,
 ) => void;
 
+/*
+ * The agent and utilities entrypoints bundle this module separately. A global
+ * symbol lets the agent recognize metadata attached by the channel's bundle
+ * copy, while the non-enumerable property leaves protocol payloads unchanged.
+ */
+const sandboxChannelEventCheckpointSymbol = Symbol.for(
+  'vercel.ai.harness.sandboxChannelEventCheckpoint',
+);
+
+type SandboxChannelEventCheckpoint = {
+  pin: () => () => void;
+};
+
+export function pinSandboxChannelEventCheckpoint(
+  event: unknown,
+): (() => void) | undefined {
+  if (event == null || typeof event !== 'object') return undefined;
+  return (
+    event as {
+      [sandboxChannelEventCheckpointSymbol]?: SandboxChannelEventCheckpoint;
+    }
+  )[sandboxChannelEventCheckpointSymbol]?.pin();
+}
+
 const sleep = (ms: number): Promise<void> =>
   new Promise(resolve => {
     const t = setTimeout(resolve, ms);
@@ -136,6 +160,9 @@ export class SandboxChannel<
    * replayed to the next process on `resume`.
    */
   private suspended = false;
+  private pinnedSuspensionCursor:
+    | { eventId: number; token: object }
+    | undefined;
   /** Channel is fully torn down; `send` throws and `onClose` has fired. */
   private terminal = false;
   private _lastSeenEventId = 0;
@@ -251,6 +278,9 @@ export class SandboxChannel<
   }
 
   interrupt(options?: { timeoutMs?: number }): Promise<void> {
+    if (this.pinnedSuspensionCursor != null) {
+      return Promise.resolve();
+    }
     const timeoutMs = options?.timeoutMs ?? 5000;
     return new Promise<void>((resolve, reject) => {
       let settled = false;
@@ -313,19 +343,24 @@ export class SandboxChannel<
    * aborts it) and accumulates events past the cursor for the next process to
    * `resume`. Unlike {@link close}, the consumer's active turn is wound down
    * cleanly — adapters distinguish a suspend from an unexpected drop via the
-   * `'suspended'` close reason and resolve `done` successfully.
+   * `'suspended'` close reason and resolve `done` successfully. When an event
+   * checkpoint is pinned, the returned cursor points to that event so any
+   * already-dispatched tail is replayed by the next process.
    */
   suspend(): Promise<number> {
     return new Promise<number>(resolve => {
+      const pinnedSuspensionCursor = this.pinnedSuspensionCursor?.eventId;
       if (this.terminal) {
-        resolve(this._lastSeenEventId);
+        resolve(pinnedSuspensionCursor ?? this._lastSeenEventId);
         return;
       }
       // Stop counting/dispatching further inbound frames immediately, and
       // suppress reconnect so the socket close finalises.
       this.suspended = true;
       this.closing = true;
-      this.onClose(() => resolve(this._lastSeenEventId));
+      this.onClose(() =>
+        resolve(pinnedSuspensionCursor ?? this._lastSeenEventId),
+      );
       // Queue the close behind any already-dispatched frames so everything
       // delivered to the consumer is reflected in the final cursor.
       this.enqueue(() => {
@@ -465,6 +500,9 @@ export class SandboxChannel<
       schema: this.outboundSchema,
     });
     if (validated.success) {
+      if (seq !== undefined) {
+        this.attachEventCheckpoint({ event: validated.value, eventId: seq });
+      }
       this.dispatch(validated.value);
     } else {
       this.dispatch({
@@ -506,6 +544,26 @@ export class SandboxChannel<
     }
   }
 
+  private attachEventCheckpoint(options: {
+    event: TOut;
+    eventId: number;
+  }): void {
+    if (!Object.isExtensible(options.event)) return;
+    Object.defineProperty(options.event, sandboxChannelEventCheckpointSymbol, {
+      value: {
+        pin: () => {
+          const token = {};
+          this.pinnedSuspensionCursor = { eventId: options.eventId, token };
+          return () => {
+            if (this.pinnedSuspensionCursor?.token === token) {
+              this.pinnedSuspensionCursor = undefined;
+            }
+          };
+        },
+      } satisfies SandboxChannelEventCheckpoint,
+    });
+  }
+
   private finalizeClose(code: number, reason: string): void {
     if (this.terminal) return;
     this.terminal = true;