@ai-sdk/harness 1.0.100 → 1.0.102

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @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
+
+- 951c54d: feat(harness): support `askUserQuestions` tool including support for normalization across harness adapters
+- Updated dependencies [a51cc94]
+- Updated dependencies [d1904d3]
+- Updated dependencies [84e5a79]
+- Updated dependencies [a8e8ad0]
+  - ai@7.0.92
+
 ## 1.0.100
 
 ### Patch Changes

package/agent/index.ts

@@ -28,14 +28,8 @@ export type {
   HarnessAgentToolSpec,
 } from '../src/agent/harness-agent-types';
 export { HarnessAgentSession } from '../src/agent/harness-agent-session';
-export {
-  collectHarnessAgentToolApprovalContinuations,
-  type HarnessAgentToolApprovalContinuation,
-} from '../src/agent/harness-agent-tool-approval-continuation';
-export {
-  collectHarnessAgentToolResultContinuations,
-  type HarnessAgentToolResultContinuation,
-} from '../src/agent/harness-agent-tool-result-continuation';
+export { collectHarnessAgentToolApprovalContinuations } from '../src/agent/harness-agent-tool-approval-continuation';
+export { collectHarnessAgentToolResultContinuations } from '../src/agent/harness-agent-tool-result-continuation';
 export {
   prepareHarnessSandboxTemplate,
   prewarmHarness,

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, 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 { Experimental_SandboxSession, UserModelMessage, ToolResultPart, ProviderOptions, ToolSet, FlexibleSchema, Tool, Context, MaybePromiseLike, Arrayable, ToolApprovalResponse, ModelMessage } from '@ai-sdk/provider-utils';
+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';
 
@@ -347,6 +347,7 @@ type HarnessV1PromptControl = {
         toolCallId: string;
         output: unknown;
         isError?: boolean;
+        toolResult?: ToolResultPart;
     }): PromiseLike<void>;
     /**
      * Respond to a `tool-approval-request` the adapter emitted.
@@ -465,6 +466,7 @@ type HarnessV1PendingToolResult = {
     readonly toolCallId: string;
     readonly toolName: string;
     readonly input: string;
+    readonly providerOptions?: ProviderOptions;
 };
 /**
  * Framework-owned settings captured when a turn begins. The same settings are
@@ -695,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
@@ -1015,6 +1021,40 @@ declare const HARNESS_V1_BUILTIN_TOOLS: {
     readonly webSearch: Tool<{
         query: string;
     }, unknown, _ai_sdk_provider_utils.Context>;
+    readonly askUserQuestions: _ai_sdk_provider_utils.FunctionTool<{
+        allowPartialAnswers: boolean;
+        questions: {
+            id: string;
+            question: string;
+            header?: string | undefined;
+            options?: {
+                id: string;
+                label: string;
+                description?: string | undefined;
+                preview?: string | undefined;
+            }[] | undefined;
+            allowMultiple?: boolean | undefined;
+            allowFreeForm?: boolean | {
+                secret: boolean;
+            } | undefined;
+        }[];
+    }, {
+        action: "answered";
+        answers: Record<string, {
+            optionIds: string[];
+            freeform?: string | undefined;
+        }>;
+    } | {
+        action: "partially-answered";
+        answers: Record<string, {
+            optionIds: string[];
+            freeform?: string | undefined;
+        }>;
+    } | {
+        action: "declined";
+    } | {
+        action: "cancelled";
+    }>;
 };
 type HarnessV1BuiltinToolName = keyof typeof HARNESS_V1_BUILTIN_TOOLS;
 type HarnessV1BuiltinToolUseKind = 'readonly' | 'edit' | 'bash';
@@ -1248,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> = {
     /**
@@ -1308,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.
      */
@@ -1343,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.
@@ -1391,43 +1473,16 @@ type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAge
     readonly onLog?: (event: HarnessDiagnostic) => void;
 } & HarnessAgentToolFilteringSettings<HarnessAllTools<THarness, TUserTools>>;
 
-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.
- *
- * AI SDK clients send approval decisions as a trailing `role: "tool"` message
- * containing `tool-approval-response` parts. The response only carries the
- * approval id, so the harness has to recover the matching approval request
- * locally to find the original tool call before it can resume the paused turn.
- * Responses that already have a tool result are ignored, because those
- * approvals were already consumed by a prior continuation.
- */
-declare function collectHarnessAgentToolApprovalContinuations(input: {
-    messages: readonly ModelMessage[];
-}): readonly HarnessAgentToolApprovalContinuation[];
-
-type HarnessAgentToolResultContinuation = {
-    readonly toolCallId: string;
-    readonly output: unknown;
-    readonly isError?: boolean;
+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>;
 };
-/**
- * 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.
- */
-declare function collectHarnessAgentToolResultContinuations(input: {
-    messages: readonly ModelMessage[];
-}): readonly HarnessAgentToolResultContinuation[];
 
 type HarnessAgentTurnResult<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context, OUTPUT extends OutputInterface> = {
     result: StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
@@ -1503,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: {
@@ -1518,9 +1574,10 @@ 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 HarnessAgentToolApprovalContinuation[] | undefined;
-        toolResultContinuations?: readonly HarnessAgentToolResultContinuation[] | undefined;
+        toolApprovalContinuations?: readonly ToolApprovalResponse[] | undefined;
+        toolResultContinuations?: readonly ToolResultPart[] | undefined;
     }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
     /**
      * Ask the underlying runtime to compact its context. The runtime performs
@@ -1656,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;
@@ -1703,8 +1761,8 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
      */
     continueGenerate(options: {
         session: HarnessAgentSession;
-        toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[];
-        toolResultContinuations?: readonly HarnessAgentToolResultContinuation[];
+        toolApprovalContinuations?: readonly ToolApprovalResponse[];
+        toolResultContinuations?: readonly ToolResultPart[];
         abortSignal?: AbortSignal;
     }): Promise<GenerateTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT>>;
     /**
@@ -1717,8 +1775,8 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
      */
     continueStream(options: {
         session: HarnessAgentSession;
-        toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[];
-        toolResultContinuations?: readonly HarnessAgentToolResultContinuation[];
+        toolApprovalContinuations?: readonly ToolApprovalResponse[];
+        toolResultContinuations?: readonly ToolResultPart[];
         abortSignal?: AbortSignal;
     }): Promise<StreamTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT>>;
     /**
@@ -1735,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;
@@ -1745,6 +1804,27 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
     private _resolveResponseFormat;
 }
 
+/**
+ * Extract approval decisions that should continue a suspended harness turn.
+ *
+ * AI SDK clients send approval decisions as a trailing `role: "tool"` message
+ * containing `tool-approval-response` parts. The response only carries the
+ * approval id, so the harness has to recover the matching approval request
+ * locally to find the original tool call before it can resume the paused turn.
+ * Responses that already have a tool result are ignored, because those
+ * approvals were already consumed by a prior continuation.
+ */
+declare function collectHarnessAgentToolApprovalContinuations(input: {
+    messages: readonly ModelMessage[];
+}): readonly ToolApprovalResponse[];
+
+/**
+ * Extract client-provided tool results from the trailing tool message.
+ */
+declare function collectHarnessAgentToolResultContinuations(input: {
+    messages: readonly ModelMessage[];
+}): readonly ToolResultPart[];
+
 type SandboxBootstrapSettings = Omit<HarnessAgentSandboxConfig, 'onSession'>;
 /**
  * Prepare a harness's sandbox template without running an agent. Idempotent: if
@@ -1902,4 +1982,4 @@ interface TraceTreeReporterOptions {
 }
 declare function createTraceTreeReporter(options?: TraceTreeReporterOptions): Telemetry;
 
-export { type FileReporter, type FileReporterOptions, HarnessAgent, type HarnessAgentAdapter, type HarnessAgentAdapterSession, type HarnessAgentBuiltinTool, type HarnessAgentBuiltinToolName, type HarnessAgentBuiltinToolUseKind, type HarnessAgentBuiltinTools, type HarnessAgentContinueTurnOptions, type HarnessAgentContinueTurnState, type HarnessAgentLifecycleState, type HarnessAgentPendingToolApproval, type HarnessAgentPendingToolResult, type HarnessAgentPermissionMode, type HarnessAgentPrompt, type HarnessAgentPromptControl, type HarnessAgentPromptTurnOptions, type HarnessAgentResumeSessionState, type HarnessAgentSandboxConfig, HarnessAgentSession, type HarnessAgentSettings, type HarnessAgentSkill, type HarnessAgentStartOptions, type HarnessAgentStreamPart, type HarnessAgentToolApprovalConfiguration, type HarnessAgentToolApprovalContinuation, type HarnessAgentToolResultContinuation, type HarnessAgentToolSpec, type HarnessAllTools, HarnessCapabilityUnsupportedError, type HarnessDebugConfig, type HarnessDebugLevel, type HarnessDiagnostic, type HarnessDiagnosticConsumer, HarnessError, HarnessSandboxAuthenticationError, type PrepareSandboxForHarnessResult, type TraceTreeReporterOptions, collectHarnessAgentToolApprovalContinuations, collectHarnessAgentToolResultContinuations, createFileReporter, createTraceTreeReporter, getHarnessErrorMessage, prepareHarnessSandboxTemplate, prepareSandboxForHarness, prewarmHarness };
+export { type FileReporter, type FileReporterOptions, HarnessAgent, type HarnessAgentAdapter, type HarnessAgentAdapterSession, type HarnessAgentBuiltinTool, type HarnessAgentBuiltinToolName, type HarnessAgentBuiltinToolUseKind, type HarnessAgentBuiltinTools, type HarnessAgentContinueTurnOptions, type HarnessAgentContinueTurnState, type HarnessAgentLifecycleState, type HarnessAgentPendingToolApproval, type HarnessAgentPendingToolResult, type HarnessAgentPermissionMode, type HarnessAgentPrompt, type HarnessAgentPromptControl, type HarnessAgentPromptTurnOptions, type HarnessAgentResumeSessionState, type HarnessAgentSandboxConfig, HarnessAgentSession, type HarnessAgentSettings, type HarnessAgentSkill, type HarnessAgentStartOptions, type HarnessAgentStreamPart, type HarnessAgentToolApprovalConfiguration, type HarnessAgentToolSpec, type HarnessAllTools, HarnessCapabilityUnsupportedError, type HarnessDebugConfig, type HarnessDebugLevel, type HarnessDiagnostic, type HarnessDiagnosticConsumer, HarnessError, HarnessSandboxAuthenticationError, type PrepareSandboxForHarnessResult, type TraceTreeReporterOptions, collectHarnessAgentToolApprovalContinuations, collectHarnessAgentToolResultContinuations, createFileReporter, createTraceTreeReporter, getHarnessErrorMessage, prepareHarnessSandboxTemplate, prepareSandboxForHarness, prewarmHarness };