@ai-sdk/harness 1.0.100 → 1.0.102

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness",
-  "version": "1.0.100",
+  "version": "1.0.102",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -46,7 +46,7 @@
   "dependencies": {
     "@ai-sdk/provider": "4.0.10",
     "@ai-sdk/provider-utils": "5.0.36",
-    "ai": "7.0.91"
+    "ai": "7.0.93"
   },
   "peerDependencies": {
     "ws": "^8.21.0",
@@ -58,7 +58,7 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/otel": "1.0.91",
+    "@ai-sdk/otel": "1.0.93",
     "@opentelemetry/sdk-trace-base": "2.7.1",
     "@types/node": "22.19.19",
     "@types/ws": "^8.5.13",

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

@@ -1,6 +1,8 @@
 import type {
   Context,
   Experimental_SandboxSession as SandboxSession,
+  ToolApprovalResponse,
+  ToolResultPart,
   ToolSet,
 } from '@ai-sdk/provider-utils';
 import type {
@@ -29,11 +31,10 @@ import type {
   HarnessAgentResumeSessionState,
   HarnessAgentToolSpec,
 } from './harness-agent-types';
-import type { HarnessAgentToolApprovalContinuation } from './harness-agent-tool-approval-continuation';
-import type { HarnessAgentToolResultContinuation } from './harness-agent-tool-result-continuation';
 import { validateLifecycleStateData } from './internal/lifecycle-state-validation';
 import { runPrompt } from './internal/run-prompt';
 import { getRestrictedSandboxSession } from '../utils/get-restricted-sandbox-session';
+import type { HarnessAgentLifecycleCallbacks } from './internal/turn-telemetry';
 
 type HarnessAgentTurnResult<
   TOOLS extends ToolSet,
@@ -207,6 +208,7 @@ export class HarnessAgentSession {
     responseFormat: HarnessV1ResponseFormat | undefined;
     output: OUTPUT | undefined;
     telemetry: TelemetryOptions | undefined;
+    callbacks: HarnessAgentLifecycleCallbacks<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
     stopConditions: ReadonlyArray<StopCondition<TOOLS, RUNTIME_CONTEXT>>;
   }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
     const session = this.requireReusableSession();
@@ -246,6 +248,7 @@ export class HarnessAgentSession {
         responseFormat: options.responseFormat,
         output: options.output,
         telemetry: options.telemetry,
+        callbacks: options.callbacks,
         stopConditions: options.stopConditions,
         toolApproval: this.toolApproval,
         pendingToolApprovals: this.getPendingToolApprovals(),
@@ -305,13 +308,10 @@ export class HarnessAgentSession {
     responseFormat: HarnessV1ResponseFormat | undefined;
     output: OUTPUT | undefined;
     telemetry: TelemetryOptions | undefined;
+    callbacks: HarnessAgentLifecycleCallbacks<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
     stopConditions: ReadonlyArray<StopCondition<TOOLS, RUNTIME_CONTEXT>>;
-    toolApprovalContinuations?:
-      | readonly HarnessAgentToolApprovalContinuation[]
-      | undefined;
-    toolResultContinuations?:
-      | readonly HarnessAgentToolResultContinuation[]
-      | undefined;
+    toolApprovalContinuations?: readonly ToolApprovalResponse[] | undefined;
+    toolResultContinuations?: readonly ToolResultPart[] | undefined;
   }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
     const session = this.requireReusableSession();
     this.requireContinuableTurn();
@@ -345,6 +345,7 @@ export class HarnessAgentSession {
         responseFormat: options.responseFormat,
         output: options.output,
         telemetry: options.telemetry,
+        callbacks: options.callbacks,
         stopConditions: options.stopConditions,
         toolApproval: this.toolApproval,
         pendingToolApprovals: this.getPendingToolApprovals(),

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

@@ -19,6 +19,14 @@ import type {
 import type {
   ActiveTools,
   AgentCallParameters,
+  GenerateTextOnEndCallback,
+  GenerateTextOnStartCallback,
+  GenerateTextOnStepEndCallback,
+  GenerateTextOnStepStartCallback,
+  OnLanguageModelCallEndCallback,
+  OnLanguageModelCallStartCallback,
+  OnToolExecutionEndCallback,
+  OnToolExecutionStartCallback,
   OutputInterface as Output,
   Prompt,
   StopCondition,
@@ -78,10 +86,12 @@ type HarnessTools<TOOLS extends ToolSet> = ActiveTools<NoInfer<TOOLS>>;
 /**
  * Construction-time settings for a `HarnessAgent`.
  *
- * Prompt, abortSignal, callbacks, and custom call options belong on the
+ * Prompt, abortSignal, and custom call options belong on the
  * `AgentCallParameters` / `AgentStreamParameters` passed to `generate` /
- * `stream`. `prepareCall` can derive turn-scoped model, skills, instructions,
- * and tools from those custom call options.
+ * `stream`. Lifecycle callbacks can be configured here for every call, while
+ * the callbacks supported by `AgentCallParameters` can also be added per call.
+ * `prepareCall` can derive turn-scoped model, skills, instructions, and tools
+ * from custom call options.
  */
 type HarnessAgentToolFilteringSettings<TOOLS extends ToolSet> =
   | {
@@ -153,6 +163,14 @@ export type HarnessAgentSettings<
    */
   readonly instructions?: string;
 
+  /**
+   * Additional HTTP headers to be sent with every model request.
+   *
+   * `authorization`, `x-api-key`, `user-agent`, and `x-client-app` are
+   * managed by the harness and are not allowed.
+   */
+  readonly headers?: Record<string, string | undefined>;
+
   /**
    * Schema for validating the custom options passed to each agent call.
    */
@@ -242,6 +260,67 @@ export type HarnessAgentSettings<
     >
   >;
 
+  /**
+   * Called when an agent call begins, before any model steps.
+   */
+  readonly onStart?: GenerateTextOnStartCallback<
+    NoInfer<HarnessAllTools<THarness, TUserTools>>,
+    RUNTIME_CONTEXT,
+    NoInfer<OUTPUT>
+  >;
+
+  /**
+   * Called when a model step begins.
+   */
+  readonly onStepStart?: GenerateTextOnStepStartCallback<
+    NoInfer<HarnessAllTools<THarness, TUserTools>>,
+    NoInfer<RUNTIME_CONTEXT>,
+    NoInfer<OUTPUT>
+  >;
+
+  /**
+   * Called immediately before the harness begins emitting a model response.
+   */
+  readonly onLanguageModelCallStart?: OnLanguageModelCallStartCallback;
+
+  /**
+   * Called after a model response is complete and before its tool execution
+   * lifecycle callbacks are delivered.
+   */
+  readonly onLanguageModelCallEnd?: OnLanguageModelCallEndCallback<
+    NoInfer<HarnessAllTools<THarness, TUserTools>>
+  >;
+
+  /**
+   * Called before each harness or host tool execution is reported.
+   */
+  readonly onToolExecutionStart?: OnToolExecutionStartCallback<
+    NoInfer<HarnessAllTools<THarness, TUserTools>>
+  >;
+
+  /**
+   * Called after each harness or host tool execution is reported.
+   */
+  readonly onToolExecutionEnd?: OnToolExecutionEndCallback<
+    NoInfer<HarnessAllTools<THarness, TUserTools>>
+  >;
+
+  /**
+   * Called after each completed model step.
+   */
+  readonly onStepEnd?: GenerateTextOnStepEndCallback<
+    NoInfer<HarnessAllTools<THarness, TUserTools>>,
+    NoInfer<RUNTIME_CONTEXT>
+  >;
+
+  /**
+   * Called when an agent call completes successfully.
+   */
+  readonly onEnd?: GenerateTextOnEndCallback<
+    NoInfer<HarnessAllTools<THarness, TUserTools>>,
+    NoInfer<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-tool-approval-continuation.ts

@@ -5,17 +5,6 @@ import type {
   ToolApprovalResponse,
 } from '@ai-sdk/provider-utils';
 
-export type HarnessAgentToolApprovalContinuation = {
-  readonly approvalResponse: ToolApprovalResponse;
-  readonly toolCall: {
-    readonly type: 'tool-call';
-    readonly toolCallId: string;
-    readonly toolName: string;
-    readonly input: unknown;
-    readonly providerExecuted?: boolean;
-  };
-};
-
 /**
  * Extract approval decisions that should continue a suspended harness turn.
  *
@@ -28,14 +17,11 @@ export type HarnessAgentToolApprovalContinuation = {
  */
 export function collectHarnessAgentToolApprovalContinuations(input: {
   messages: readonly ModelMessage[];
-}): readonly HarnessAgentToolApprovalContinuation[] {
+}): readonly ToolApprovalResponse[] {
   const lastMessage = input.messages.at(-1);
   if (lastMessage?.role !== 'tool') return [];
 
-  const toolCallsByToolCallId = new Map<
-    string,
-    HarnessAgentToolApprovalContinuation['toolCall']
-  >();
+  const toolCallIds = new Set<string>();
   const approvalRequestsByApprovalId = new Map<string, ToolApprovalRequest>();
   for (const message of input.messages) {
     if (message.role !== 'assistant' || typeof message.content === 'string') {
@@ -43,15 +29,7 @@ export function collectHarnessAgentToolApprovalContinuations(input: {
     }
     for (const part of message.content) {
       if (part.type === 'tool-call') {
-        toolCallsByToolCallId.set(part.toolCallId, {
-          type: 'tool-call',
-          toolCallId: part.toolCallId,
-          toolName: part.toolName,
-          input: part.input,
-          ...(part.providerExecuted !== undefined
-            ? { providerExecuted: part.providerExecuted }
-            : {}),
-        });
+        toolCallIds.add(part.toolCallId);
       } else if (part.type === 'tool-approval-request') {
         approvalRequestsByApprovalId.set(part.approvalId, part);
       }
@@ -65,7 +43,7 @@ export function collectHarnessAgentToolApprovalContinuations(input: {
     }
   }
 
-  const continuations: HarnessAgentToolApprovalContinuation[] = [];
+  const continuations: ToolApprovalResponse[] = [];
   for (const part of lastMessage.content) {
     if (part.type !== 'tool-approval-response') continue;
 
@@ -77,17 +55,13 @@ export function collectHarnessAgentToolApprovalContinuations(input: {
     }
     if (toolResultIds.has(approvalRequest.toolCallId)) continue;
 
-    const toolCall = toolCallsByToolCallId.get(approvalRequest.toolCallId);
-    if (toolCall == null) {
+    if (!toolCallIds.has(approvalRequest.toolCallId)) {
       throw new HarnessError({
         message: `Tool approval request '${approvalRequest.approvalId}' references unknown tool call '${approvalRequest.toolCallId}'.`,
       });
     }
 
-    continuations.push({
-      approvalResponse: part,
-      toolCall,
-    });
+    continuations.push(part);
   }
 
   return continuations;

package/src/agent/harness-agent-tool-result-continuation.ts

@@ -1,62 +1,13 @@
-import type { ModelMessage, ToolResultOutput } from '@ai-sdk/provider-utils';
-
-export type HarnessAgentToolResultContinuation = {
-  readonly toolCallId: string;
-  readonly output: unknown;
-  readonly isError?: boolean;
-};
+import type { ModelMessage, ToolResultPart } from '@ai-sdk/provider-utils';
 
 /**
- * Extract client-provided tool results from the trailing tool message and
- * convert AI SDK model-output wrappers back into values a harness runtime can
- * return from its pending host-tool invocation.
+ * Extract client-provided tool results from the trailing tool message.
  */
 export function collectHarnessAgentToolResultContinuations(input: {
   messages: readonly ModelMessage[];
-}): readonly HarnessAgentToolResultContinuation[] {
+}): readonly ToolResultPart[] {
   const lastMessage = input.messages.at(-1);
   if (lastMessage?.role !== 'tool') return [];
 
-  return lastMessage.content
-    .filter(part => part.type === 'tool-result')
-    .map(part =>
-      toToolResultContinuation({
-        toolCallId: part.toolCallId,
-        output: part.output,
-      }),
-    );
-}
-
-function toToolResultContinuation(input: {
-  toolCallId: string;
-  output: ToolResultOutput;
-}): HarnessAgentToolResultContinuation {
-  switch (input.output.type) {
-    case 'text':
-    case 'json':
-      return {
-        toolCallId: input.toolCallId,
-        output: input.output.value,
-      };
-    case 'error-text':
-    case 'error-json':
-      return {
-        toolCallId: input.toolCallId,
-        output: input.output.value,
-        isError: true,
-      };
-    case 'execution-denied':
-      return {
-        toolCallId: input.toolCallId,
-        output: {
-          type: input.output.type,
-          reason: input.output.reason,
-        },
-      };
-    case 'content':
-      return {
-        toolCallId: input.toolCallId,
-        output: input.output,
-      };
-  }
+  return lastMessage.content.filter(part => part.type === 'tool-result');
 }

package/src/agent/harness-agent.ts

@@ -1,5 +1,6 @@
 import { HarnessCapabilityUnsupportedError } from '../errors/harness-capability-unsupported-error';
 import type {
+  HarnessV1,
   HarnessV1BuiltinToolFiltering,
   HarnessV1JSONSchema,
   HarnessV1NetworkSandboxSession,
@@ -9,12 +10,16 @@ import {
   asArray,
   asSchema,
   generateId,
+  normalizeHeaders,
   validateTypes,
   type Context,
   type Experimental_SandboxSession as SandboxSession,
   type ModelMessage,
+  type ToolApprovalResponse,
+  type ToolResultPart,
   type ToolSet,
 } from '@ai-sdk/provider-utils';
+import { mergeCallbacks } from 'ai/internal';
 import type {
   Agent,
   AgentCallParameters,
@@ -41,14 +46,8 @@ import type {
   HarnessAgentSkill,
   HarnessAgentToolSpec,
 } from './harness-agent-types';
-import {
-  collectHarnessAgentToolApprovalContinuations,
-  type HarnessAgentToolApprovalContinuation,
-} from './harness-agent-tool-approval-continuation';
-import {
-  collectHarnessAgentToolResultContinuations,
-  type HarnessAgentToolResultContinuation,
-} from './harness-agent-tool-result-continuation';
+import { collectHarnessAgentToolApprovalContinuations } from './harness-agent-tool-approval-continuation';
+import { collectHarnessAgentToolResultContinuations } from './harness-agent-tool-result-continuation';
 import {
   applyBootstrapRecipe,
   hashHarnessBootstrap,
@@ -68,6 +67,7 @@ import {
 import { resolveHarnessAgentToolFiltering } from './internal/tool-filtering';
 import { resolveSandboxDefaultWorkingDirectory } from '../utils/resolve-sandbox-default-working-directory';
 import { getRestrictedSandboxSession } from '../utils/get-restricted-sandbox-session';
+import type { HarnessAgentLifecycleCallbacks } from './internal/turn-telemetry';
 
 export type { HarnessAllTools } from './harness-agent-tool-types';
 
@@ -86,8 +86,8 @@ export interface HarnessAgentCallExtensions {
 }
 
 type HarnessAgentContinueTurnInput = {
-  toolApprovalContinuations: readonly HarnessAgentToolApprovalContinuation[];
-  toolResultContinuations: readonly HarnessAgentToolResultContinuation[];
+  toolApprovalContinuations: readonly ToolApprovalResponse[];
+  toolResultContinuations: readonly ToolResultPart[];
 };
 
 type PreparedHarnessAgentTurnSettings<
@@ -114,8 +114,8 @@ type PreparedHarnessAgentContinueTurnInput<
   THarness extends HarnessAgentAdapter<any>,
   TUserTools extends ToolSet,
 > = PreparedHarnessAgentTurnSettings<THarness, TUserTools> & {
-  toolApprovalContinuations: readonly HarnessAgentToolApprovalContinuation[];
-  toolResultContinuations: readonly HarnessAgentToolResultContinuation[];
+  toolApprovalContinuations: readonly ToolApprovalResponse[];
+  toolResultContinuations: readonly ToolResultPart[];
 };
 
 type HarnessAgentTurnResult<
@@ -206,6 +206,7 @@ export class HarnessAgent<
     | HarnessV1BuiltinToolFiltering
     | undefined;
   private readonly permissionMode: HarnessAgentPermissionMode;
+  private readonly headers: Readonly<Record<string, string>> | undefined;
 
   constructor(
     settings: HarnessAgentSettings<
@@ -222,8 +223,28 @@ export class HarnessAgent<
     this.stopConditions =
       settings.stopWhen == null ? [] : asArray(settings.stopWhen);
     this.sandboxConfig = sandboxConfig;
+    const forbiddenHeaders = new Set([
+      'authorization',
+      'x-api-key',
+      'user-agent',
+      'x-client-app',
+    ]);
+    const forbiddenHeader = Object.keys(settings.headers ?? {})
+      .map(name => name.toLowerCase())
+      .find(name => forbiddenHeaders.has(name));
+    if (forbiddenHeader != null) {
+      throw new Error(
+        `HarnessAgent: \`headers\` must not include the managed header \`${forbiddenHeader}\`.`,
+      );
+    }
+    const headers = normalizeHeaders(settings.headers);
+    this.headers = Object.keys(headers).length === 0 ? undefined : headers;
     this.id = settings.id;
     const userTools = settings.tools ?? ({} as TUserTools);
+    assertNoReservedQuestionTool({
+      harness: settings.harness,
+      userTools,
+    });
     this.permissionMode = resolvePermissionMode({
       permissionMode: settings.permissionMode,
     });
@@ -501,6 +522,7 @@ export class HarnessAgent<
     try {
       const baseStartOptions = {
         sessionId,
+        ...(this.headers == null ? {} : { headers: this.headers }),
         resumeFrom: validatedResumeFrom,
         continueFrom: effectiveContinueFrom,
         permissionMode: this.permissionMode,
@@ -609,8 +631,8 @@ export class HarnessAgent<
    */
   async continueGenerate(options: {
     session: HarnessAgentSession;
-    toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[];
-    toolResultContinuations?: readonly HarnessAgentToolResultContinuation[];
+    toolApprovalContinuations?: readonly ToolApprovalResponse[];
+    toolResultContinuations?: readonly ToolResultPart[];
     abortSignal?: AbortSignal;
   }): Promise<
     GenerateTextResult<
@@ -643,8 +665,8 @@ export class HarnessAgent<
    */
   async continueStream(options: {
     session: HarnessAgentSession;
-    toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[];
-    toolResultContinuations?: readonly HarnessAgentToolResultContinuation[];
+    toolApprovalContinuations?: readonly ToolApprovalResponse[];
+    toolResultContinuations?: readonly ToolResultPart[];
     abortSignal?: AbortSignal;
   }): Promise<
     StreamTextResult<
@@ -707,6 +729,7 @@ export class HarnessAgent<
         runtimeContext: input.runtimeContext,
         abortSignal: input.options.abortSignal,
         responseFormat,
+        callbacks: this._resolveLifecycleCallbacks(input.options),
       }),
       prompt: turnInput.prompt,
     });
@@ -733,6 +756,7 @@ export class HarnessAgent<
         runtimeContext: input.runtimeContext,
         abortSignal: input.abortSignal,
         responseFormat,
+        callbacks: this._resolveLifecycleCallbacks(),
       }),
       toolApprovalContinuations: turnInput.toolApprovalContinuations,
       toolResultContinuations: turnInput.toolResultContinuations,
@@ -744,6 +768,11 @@ export class HarnessAgent<
     runtimeContext: RUNTIME_CONTEXT;
     abortSignal: AbortSignal | undefined;
     responseFormat: HarnessV1ResponseFormat | undefined;
+    callbacks: HarnessAgentLifecycleCallbacks<
+      HarnessAllTools<THarness, TUserTools>,
+      RUNTIME_CONTEXT,
+      OUTPUT
+    >;
   }) {
     return {
       model: input.turnSettings.model,
@@ -758,10 +787,49 @@ export class HarnessAgent<
       responseFormat: input.responseFormat,
       output: this.settings.output,
       telemetry: this.settings.telemetry,
+      callbacks: input.callbacks,
       stopConditions: this.stopConditions,
     };
   }
 
+  private _resolveLifecycleCallbacks(
+    call?: AgentCallParameters<
+      CALL_OPTIONS,
+      HarnessAllTools<THarness, TUserTools>,
+      RUNTIME_CONTEXT
+    >,
+  ): HarnessAgentLifecycleCallbacks<
+    HarnessAllTools<THarness, TUserTools>,
+    RUNTIME_CONTEXT,
+    OUTPUT
+  > {
+    return {
+      onStart: mergeCallbacks(
+        this.settings.onStart,
+        call?.onStart ?? call?.experimental_onStart,
+      ),
+      onStepStart: mergeCallbacks(
+        this.settings.onStepStart,
+        call?.onStepStart ?? call?.experimental_onStepStart,
+      ),
+      onLanguageModelCallStart: this.settings.onLanguageModelCallStart,
+      onLanguageModelCallEnd: this.settings.onLanguageModelCallEnd,
+      onToolExecutionStart: mergeCallbacks(
+        this.settings.onToolExecutionStart,
+        call?.onToolExecutionStart ?? call?.experimental_onToolCallStart,
+      ),
+      onToolExecutionEnd: mergeCallbacks(
+        this.settings.onToolExecutionEnd,
+        call?.onToolExecutionEnd ?? call?.experimental_onToolCallFinish,
+      ),
+      onStepEnd: mergeCallbacks(
+        this.settings.onStepEnd,
+        call?.onStepEnd ?? call?.onStepFinish,
+      ),
+      onEnd: mergeCallbacks(this.settings.onEnd, call?.onEnd ?? call?.onFinish),
+    };
+  }
+
   private _resolveContinueTurnInput(options: {
     prompt?: string | ModelMessage[];
     messages?: ModelMessage[];
@@ -903,8 +971,8 @@ export class HarnessAgent<
   }
 
   private _prepareContinueTurnInput(options: {
-    toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[];
-    toolResultContinuations?: readonly HarnessAgentToolResultContinuation[];
+    toolApprovalContinuations?: readonly ToolApprovalResponse[];
+    toolResultContinuations?: readonly ToolResultPart[];
   }): PreparedHarnessAgentContinueTurnInput<THarness, TUserTools> {
     return {
       ...this._prepareTurnSettings({
@@ -925,6 +993,10 @@ export class HarnessAgent<
     tools?: TUserTools;
   }): PreparedHarnessAgentTurnSettings<THarness, TUserTools> {
     const userTools = options.tools ?? ({} as TUserTools);
+    assertNoReservedQuestionTool({
+      harness: this.settings.harness,
+      userTools,
+    });
     const tools = {
       ...this.settings.harness.builtinTools,
       ...userTools,
@@ -1028,6 +1100,23 @@ export class HarnessAgent<
   }
 }
 
+function assertNoReservedQuestionTool(input: {
+  harness: HarnessV1;
+  userTools: ToolSet;
+}): void {
+  if (
+    Object.prototype.hasOwnProperty.call(
+      input.harness.builtinTools,
+      'askUserQuestions',
+    ) &&
+    Object.prototype.hasOwnProperty.call(input.userTools, 'askUserQuestions')
+  ) {
+    throw new Error(
+      "HarnessAgent tool name 'askUserQuestions' is reserved for harness question requests.",
+    );
+  }
+}
+
 /*
  * `GenerateTextResult` view over a drained `streamText` run. Non-deprecated
  * members derive from `steps` (the single source of truth), and the deprecated