@ai-sdk/harness 1.0.101 → 1.0.102

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness",
-  "version": "1.0.101",
+  "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.92"
+    "ai": "7.0.93"
   },
   "peerDependencies": {
     "ws": "^8.21.0",
@@ -58,7 +58,7 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/otel": "1.0.92",
+    "@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

@@ -34,6 +34,7 @@ import type {
 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,6 +308,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>>;
     toolApprovalContinuations?: readonly ToolApprovalResponse[] | undefined;
     toolResultContinuations?: readonly ToolResultPart[] | undefined;
@@ -341,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.ts

@@ -10,6 +10,7 @@ import {
   asArray,
   asSchema,
   generateId,
+  normalizeHeaders,
   validateTypes,
   type Context,
   type Experimental_SandboxSession as SandboxSession,
@@ -18,6 +19,7 @@ import {
   type ToolResultPart,
   type ToolSet,
 } from '@ai-sdk/provider-utils';
+import { mergeCallbacks } from 'ai/internal';
 import type {
   Agent,
   AgentCallParameters,
@@ -65,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';
 
@@ -203,6 +206,7 @@ export class HarnessAgent<
     | HarnessV1BuiltinToolFiltering
     | undefined;
   private readonly permissionMode: HarnessAgentPermissionMode;
+  private readonly headers: Readonly<Record<string, string>> | undefined;
 
   constructor(
     settings: HarnessAgentSettings<
@@ -219,6 +223,22 @@ 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({
@@ -502,6 +522,7 @@ export class HarnessAgent<
     try {
       const baseStartOptions = {
         sessionId,
+        ...(this.headers == null ? {} : { headers: this.headers }),
         resumeFrom: validatedResumeFrom,
         continueFrom: effectiveContinueFrom,
         permissionMode: this.permissionMode,
@@ -708,6 +729,7 @@ export class HarnessAgent<
         runtimeContext: input.runtimeContext,
         abortSignal: input.options.abortSignal,
         responseFormat,
+        callbacks: this._resolveLifecycleCallbacks(input.options),
       }),
       prompt: turnInput.prompt,
     });
@@ -734,6 +756,7 @@ export class HarnessAgent<
         runtimeContext: input.runtimeContext,
         abortSignal: input.abortSignal,
         responseFormat,
+        callbacks: this._resolveLifecycleCallbacks(),
       }),
       toolApprovalContinuations: turnInput.toolApprovalContinuations,
       toolResultContinuations: turnInput.toolResultContinuations,
@@ -745,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,
@@ -759,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[];

package/src/agent/internal/harness-stream-text-result.ts

@@ -1,6 +1,6 @@
 import {
   DelayedPromise,
-  generateId,
+  type InferToolSetContext,
   type AssistantModelMessage,
   type Context,
   type ToolModelMessage,
@@ -154,9 +154,10 @@ export class HarnessStreamTextResult<
 
   private readonly tools: TOOLS;
   private readonly runtimeContext: RUNTIME_CONTEXT;
-  private readonly toolsContext: never;
+  private readonly toolsContext: InferToolSetContext<TOOLS>;
   private readonly providerName: string;
-  private readonly modelId: string;
+  private readonly callId: string;
+  private modelId: string;
   private readonly outputSpecification: OUTPUT | undefined;
 
   // Accumulators that span the whole turn.
@@ -170,16 +171,18 @@ export class HarnessStreamTextResult<
   constructor(options: {
     tools: TOOLS;
     runtimeContext: RUNTIME_CONTEXT;
-    toolsContext: never;
+    toolsContext: InferToolSetContext<TOOLS>;
     harnessId: string;
-    sessionId: string;
+    callId: string;
+    modelId: string;
     output: OUTPUT | undefined;
   }) {
     this.tools = options.tools;
     this.runtimeContext = options.runtimeContext;
     this.toolsContext = options.toolsContext;
     this.providerName = `harness:${options.harnessId}`;
-    this.modelId = options.sessionId;
+    this.callId = options.callId;
+    this.modelId = options.modelId;
     this.outputSpecification = options.output;
 
     let controllerRef!: ReadableStreamDefaultController<TextStreamPart<TOOLS>>;
@@ -224,6 +227,12 @@ export class HarnessStreamTextResult<
     this.appendToCurrentStepContent(part);
   }
 
+  setModelId(modelId: string): void {
+    if (this.stepsBuffer.length === 0) {
+      this.modelId = modelId;
+    }
+  }
+
   /**
    * Push a continuation input into the consumer stream without attributing it
    * to the next model step. Approval responses and client tool results arrive
@@ -262,7 +271,7 @@ export class HarnessStreamTextResult<
     const rawFinishReason = input.finishReason.raw;
 
     const step = new DefaultStepResult<TOOLS, RUNTIME_CONTEXT>({
-      callId: generateId(),
+      callId: this.callId,
       stepNumber: this.stepNumber,
       provider: this.providerName,
       modelId: this.modelId,
@@ -276,7 +285,7 @@ export class HarnessStreamTextResult<
       warnings: input.warnings.length > 0 ? input.warnings : undefined,
       request: {},
       response: {
-        id: generateId(),
+        id: `${this.callId}-${this.stepNumber}`,
         timestamp: new Date(),
         modelId: this.modelId,
         messages: [],
@@ -363,7 +372,7 @@ export class HarnessStreamTextResult<
       this.stepsBuffer.length > 0
         ? this.stepsBuffer[this.stepsBuffer.length - 1]!
         : new DefaultStepResult<TOOLS, RUNTIME_CONTEXT>({
-            callId: generateId(),
+            callId: this.callId,
             stepNumber: 0,
             provider: this.providerName,
             modelId: this.modelId,
@@ -377,7 +386,7 @@ export class HarnessStreamTextResult<
             warnings: undefined,
             request: {},
             response: {
-              id: generateId(),
+              id: `${this.callId}-0`,
               timestamp: new Date(),
               modelId: this.modelId,
               messages: [],
@@ -823,6 +832,19 @@ export class HarnessStreamTextResult<
         }
         return;
       }
+      case 'reasoning-delta': {
+        const last =
+          this.currentStepContent[this.currentStepContent.length - 1];
+        if (last && last.type === 'reasoning') {
+          (last as { text: string }).text += part.text;
+        } else {
+          this.currentStepContent.push({
+            type: 'reasoning',
+            text: part.text,
+          } as ContentPart<TOOLS>);
+        }
+        return;
+      }
       case 'tool-call':
       case 'tool-approval-request':
       case 'tool-approval-response':
@@ -833,9 +855,7 @@ export class HarnessStreamTextResult<
         } as ContentPart<TOOLS>);
         return;
       default:
-        // text-start/end, reasoning-*, raw, error, finish-step, finish are
-        // not directly stored as ContentParts. (Reasoning content parts
-        // would belong here; we omit them for v0.)
+        // Boundary, raw, error, and finish parts are not ContentParts.
         return;
     }
   }