@ai-sdk/harness 1.0.38 → 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/harness-stream-text-result.ts

@@ -460,6 +460,25 @@ export class HarnessStreamTextResult<
     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: { error: unknown; reason?: string }): void {
+    if (this.settled) return;
+    this.settled = true;
+    this.fullStreamController.enqueue({
+      type: 'abort',
+      ...(input.reason !== undefined ? { reason: input.reason } : {}),
+    } as TextStreamPart<TOOLS>);
+    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.
@@ -472,6 +491,10 @@ export class HarnessStreamTextResult<
       error,
     } as TextStreamPart<TOOLS>);
     this.fullStreamController.close();
+    this.rejectDelayedPromises(error);
+  }
+
+  private rejectDelayedPromises(error: unknown): void {
     for (const dp of [
       this._content,
       this._text,
@@ -605,6 +628,7 @@ export class HarnessStreamTextResult<
   toUIMessageStream<UI_MESSAGE extends UIMessage>({
     originalMessages,
     generateMessageId,
+    onEnd,
     onFinish,
     messageMetadata,
     sendReasoning,
@@ -621,6 +645,7 @@ export class HarnessStreamTextResult<
         tools: this.tools,
         originalMessages,
         generateMessageId,
+        onEnd,
         onFinish,
         messageMetadata,
         sendReasoning,
@@ -643,6 +668,7 @@ export class HarnessStreamTextResult<
   toUIMessageStreamResponse<UI_MESSAGE extends UIMessage>({
     originalMessages,
     generateMessageId,
+    onEnd,
     onFinish,
     messageMetadata,
     sendReasoning,
@@ -660,6 +686,7 @@ export class HarnessStreamTextResult<
       stream: this.toUIMessageStream<UI_MESSAGE>({
         originalMessages,
         generateMessageId,
+        onEnd,
         onFinish,
         messageMetadata,
         sendReasoning,

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

@@ -21,16 +21,18 @@ import {
   type Experimental_SandboxSession as SandboxSession,
   type ToolSet,
 } from '@ai-sdk/provider-utils';
-import type {
-  LanguageModelV4FinishReason,
-  LanguageModelV4ToolCall,
-  LanguageModelV4Usage,
+import {
+  getErrorMessage,
+  type LanguageModelV4FinishReason,
+  type LanguageModelV4ToolCall,
+  type LanguageModelV4Usage,
 } from '@ai-sdk/provider';
 import { parseToolCall } from 'ai/internal';
 import type {
   ContentPart,
   ProviderMetadata,
   StepResult,
+  StopCondition,
   TelemetryOptions,
   TextStreamPart,
 } from 'ai';
@@ -40,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:
@@ -80,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[];
@@ -95,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>;
@@ -124,6 +133,29 @@ export function runPrompt<
     runtimeContext: input.runtimeContext,
   });
 
+  /*
+   * Settle a failed turn. When the caller's own `abortSignal` has fired, the
+   * failure is a user-initiated stop, not an error: surface it as an `abort`
+   * stream part — matching `streamText`'s abort contract — so
+   * `toUIMessageStream` consumers observe an `abort` chunk and
+   * `isAborted: true` instead of a spurious `onError`. Every other failure
+   * stays a real `error` part. Both outcomes notify `onTurnFailed` so the
+   * session's turn tracking returns to idle and the session stays usable.
+   */
+  const settleFailure = (err: unknown) => {
+    input.onTurnFailed?.();
+    if (input.abortSignal?.aborted) {
+      result.abort({
+        error: err,
+        ...(input.abortSignal.reason !== undefined
+          ? { reason: getErrorMessage(input.abortSignal.reason) }
+          : {}),
+      });
+      return;
+    }
+    result.fail(err);
+  };
+
   const done = (async () => {
     let bridge: Awaited<ReturnType<typeof toHarnessStream>>;
     try {
@@ -159,8 +191,7 @@ export function runPrompt<
         context: 'failed to start harness turn',
         error: err,
       });
-      input.onTurnFailed?.();
-      result.fail(err);
+      settleFailure(err);
       return;
     }
 
@@ -197,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.
@@ -247,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;
@@ -390,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,
@@ -455,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') {
@@ -531,6 +609,28 @@ export function runPrompt<
           }
         }
 
+        /*
+         * Settle failures before the translate-and-forward step below: the
+         * translated `error` part must not reach the consumer stream, or the
+         * turn surfaces BOTH a forwarded `error` part and the settle-owned
+         * terminal part (an `abort` part for user stops via `settleFailure`,
+         * or a second `error` part from `fail`).
+         */
+        if (value.type === 'error' && displayValue.type === 'error') {
+          // Telemetry and stderr diagnostics keep the raw error (absolute
+          // paths help debugging); the consumer-facing settle uses the
+          // workDir-stripped one, like every other forwarded part.
+          telemetry.error(value.error);
+          logBridgeError({
+            harnessId: input.harness.harnessId,
+            sessionId: input.session.sessionId,
+            context: 'harness stream error',
+            error: value.error,
+          });
+          settleFailure(displayValue.error);
+          return;
+        }
+
         // Forward to consumer as soon as possible.
         for (const part of translateStreamPart<TOOLS>(displayValue)) {
           result.enqueue(part);
@@ -564,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,
@@ -641,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') {
@@ -758,6 +865,7 @@ export function runPrompt<
           const execution = await maybeExecuteHostTool({
             event: toolCall,
             tools: activeTools,
+            wrappedExecuteTool: telemetry.executeTool,
             sandboxSession: input.sandboxSession,
             abortSignal: input.abortSignal,
             control,
@@ -799,19 +907,6 @@ export function runPrompt<
           }
           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,
-          });
-          input.onTurnFailed?.();
-          result.fail(value.error);
-          return;
-        }
       }
       if (finalFinish != null) {
         input.onTurnFinished?.();
@@ -835,9 +930,9 @@ export function runPrompt<
         context: 'harness turn failed',
         error: err,
       });
-      input.onTurnFailed?.();
-      result.fail(err);
+      settleFailure(err);
     } finally {
+      releasePendingStopBoundary();
       reader.releaseLock();
     }
   })();
@@ -890,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;
@@ -918,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;
       }
     });