@ai-sdk/harness 1.0.101 → 1.0.102

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @ai-sdk/harness
 
+## 1.0.102
+
+### Patch Changes
+
+- fe86f8f: feat(harness): support established lifecycle callbacks from `ToolLoopAgent` on `HarnessAgent` too
+- 255cccf: feat(harness): add `writeInstructions` helper and support filesystem based `instructionsMapping` in ACP backed harness adapters
+- eeed977: feat(harness): allow passing arbitrary headers with inference requests via `headers` property in `HarnessAgentSettings`
+- a39c8bf: chore(harness): clarify `writeSkills` helper intent to require materializing skills in HOME directory
+- Updated dependencies [df6c009]
+- Updated dependencies [6ee74a3]
+- Updated dependencies [f13d371]
+- Updated dependencies [d4485fe]
+- Updated dependencies [4f201cc]
+- Updated dependencies [8cdb2a7]
+- Updated dependencies [0f2281e]
+- Updated dependencies [fc8e8ac]
+- Updated dependencies [ee8391e]
+  - ai@7.0.93
+
 ## 1.0.101
 
 ### 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, ToolResultPart, ProviderOptions, ToolSet, FlexibleSchema, Tool, Context, MaybePromiseLike, Arrayable, ToolApprovalResponse, ModelMessage } from '@ai-sdk/provider-utils';
-import { OutputInterface, AgentCallParameters, Prompt, StopCondition, ToolApprovalStatus, TelemetryOptions, ActiveTools, StreamTextResult, Agent, GenerateTextResult, AgentStreamParameters, Telemetry } from 'ai';
+import { OutputInterface, AgentCallParameters, Prompt, StopCondition, GenerateTextOnStartCallback, GenerateTextOnStepStartCallback, OnLanguageModelCallStartCallback, OnLanguageModelCallEndCallback, OnToolExecutionStartCallback, OnToolExecutionEndCallback, GenerateTextOnStepEndCallback, GenerateTextOnEndCallback, ToolApprovalStatus, TelemetryOptions, ActiveTools, StreamTextResult, Agent, GenerateTextResult, AgentStreamParameters, Telemetry } from 'ai';
 import { z } from 'zod/v4';
 import { JSONSchema7, JSONValue, LanguageModelV4StreamPart, LanguageModelV4ToolCall, LanguageModelV4ToolApprovalRequest, LanguageModelV4ToolResult, LanguageModelV4FinishReason, LanguageModelV4Usage, AISDKError } from '@ai-sdk/provider';
 
@@ -697,6 +697,10 @@ type HarnessV1BuiltinToolFiltering = {
  * calling the adapter, so adapters never need to derive provider-specific paths.
  */
 type HarnessV1StartOptions = {
+    /**
+     * Additional normalized HTTP headers to send with model requests.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
     /**
      * Stable identifier for this harness session. Used as the underlying
      * resource name where the adapter has a notion of a named session
@@ -1284,10 +1288,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> = {
     /**
@@ -1344,6 +1350,13 @@ type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAge
      * turns.
      */
     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.
      */
@@ -1379,6 +1392,39 @@ type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAge
      * When omitted, the harness runs until the turn naturally finishes or pauses.
      */
     readonly stopWhen?: Arrayable<StopCondition<NoInfer<HarnessAllTools<THarness, TUserTools>>, RUNTIME_CONTEXT>>;
+    /**
+     * 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.
@@ -1427,6 +1473,17 @@ type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAge
     readonly onLog?: (event: HarnessDiagnostic) => void;
 } & HarnessAgentToolFilteringSettings<HarnessAllTools<THarness, TUserTools>>;
 
+type HarnessAgentLifecycleCallbacks<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context, OUTPUT extends OutputInterface> = {
+    onStart?: GenerateTextOnStartCallback<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
+    onStepStart?: GenerateTextOnStepStartCallback<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
+    onLanguageModelCallStart?: OnLanguageModelCallStartCallback;
+    onLanguageModelCallEnd?: OnLanguageModelCallEndCallback<TOOLS>;
+    onToolExecutionStart?: OnToolExecutionStartCallback<TOOLS>;
+    onToolExecutionEnd?: OnToolExecutionEndCallback<TOOLS>;
+    onStepEnd?: GenerateTextOnStepEndCallback<TOOLS, RUNTIME_CONTEXT>;
+    onEnd?: GenerateTextOnEndCallback<TOOLS, RUNTIME_CONTEXT>;
+};
+
 type HarnessAgentTurnResult<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context, OUTPUT extends OutputInterface> = {
     result: StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
     done: Promise<void>;
@@ -1501,6 +1558,7 @@ declare 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>;
     continueTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context, OUTPUT extends OutputInterface>(options: {
@@ -1516,6 +1574,7 @@ declare 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;
@@ -1654,6 +1713,7 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
     private readonly sandboxConfig;
     private readonly builtinToolFiltering;
     private readonly permissionMode;
+    private readonly headers;
     constructor(settings: HarnessAgentSettings<THarness, TUserTools, RUNTIME_CONTEXT, OUTPUT, CALL_OPTIONS>);
     /** Identifier of the harness backing this agent. */
     get harnessId(): string;
@@ -1733,6 +1793,7 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
     private _startPromptTurn;
     private _startContinueTurn;
     private _buildTurnOptions;
+    private _resolveLifecycleCallbacks;
     private _resolveContinueTurnInput;
     private _resolvePromptTurnInput;
     private _preparePromptTurnInput;