@ai-sdk/harness 1.0.92 → 1.0.93

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

@@ -15,6 +15,8 @@ import type {
   HarnessV1NetworkSandboxSession,
   HarnessV1PromptControl,
   HarnessV1ResponseFormat,
+  HarnessV1Skill,
+  HarnessV1TurnSettings,
 } from '../v1';
 import { HarnessCapabilityUnsupportedError } from '../errors/harness-capability-unsupported-error';
 import type {
@@ -40,6 +42,7 @@ type HarnessAgentTurnResult<
 > = {
   result: StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
   done: Promise<void>;
+  ready: Promise<void>;
 };
 
 type HarnessAgentSessionState = 'active' | 'detached' | 'stopped' | 'destroyed';
@@ -58,6 +61,13 @@ type ActivePromptControl = {
   settled: boolean;
 };
 
+type ActiveTurnSettings = {
+  readonly persisted: HarnessV1TurnSettings;
+  readonly tools: ToolSet;
+  readonly activeTools: ToolSet;
+  readonly builtinToolFiltering: HarnessV1BuiltinToolFiltering | undefined;
+};
+
 /**
  * Live harness session held by the caller.
  *
@@ -105,6 +115,8 @@ export class HarnessAgentSession {
   private suspendedTurnState:
     | Promise<HarnessAgentContinueTurnState>
     | undefined;
+  private activeTurnSettings: ActiveTurnSettings | undefined;
+  private persistedTurnSettings: HarnessV1TurnSettings | undefined;
 
   /**
    * Whether this session was created from `resumeFrom` or `continueFrom`.
@@ -122,6 +134,7 @@ export class HarnessAgentSession {
     toolApproval: HarnessAgentToolApprovalConfiguration | undefined;
     pendingToolApprovals?: readonly HarnessAgentPendingToolApproval[];
     pendingToolResults?: readonly HarnessAgentPendingToolResult[];
+    turnSettings?: HarnessV1TurnSettings;
     turnState?: HarnessAgentTurnState;
   }) {
     this.sessionId = options.sessionId;
@@ -137,6 +150,7 @@ export class HarnessAgentSession {
     for (const pendingResult of options.pendingToolResults ?? []) {
       this.pendingToolResults.set(pendingResult.toolCallId, pendingResult);
     }
+    this.persistedTurnSettings = options.turnSettings;
     this.turnState =
       options.turnState ??
       (this.pendingToolApprovals.size > 0
@@ -181,6 +195,7 @@ export class HarnessAgentSession {
     OUTPUT extends Output,
   >(options: {
     prompt: HarnessAgentPrompt;
+    skills: ReadonlyArray<HarnessV1Skill>;
     instructions: string | undefined;
     tools: TOOLS;
     activeTools: ToolSet;
@@ -195,6 +210,19 @@ export class HarnessAgentSession {
   }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
     const session = this.requireReusableSession();
     this.requirePromptableTurn();
+    this.persistedTurnSettings = {
+      skills: options.skills,
+      ...(options.instructions == null
+        ? {}
+        : { instructions: options.instructions }),
+      tools: options.toolSpecs,
+    };
+    this.activeTurnSettings = {
+      persisted: this.persistedTurnSettings,
+      tools: options.tools,
+      activeTools: options.activeTools,
+      builtinToolFiltering: options.builtinToolFiltering,
+    };
     const sandboxSession = this.getSandboxSession();
     const turnId = this.startTrackedTurn();
     try {
@@ -202,6 +230,7 @@ export class HarnessAgentSession {
         harness: this.harness,
         session,
         prompt: options.prompt,
+        skills: options.skills,
         instructions: options.instructions,
         tools: options.tools,
         activeTools: options.activeTools,
@@ -246,7 +275,10 @@ export class HarnessAgentSession {
         onStopConditionMet: () =>
           this.captureStopConditionBoundary({ session, turnId }),
       });
-      return turn;
+      return {
+        ...turn,
+        ready: this.waitForPromptControl({ turnId }),
+      };
     } catch (error) {
       this.finishTrackedTurn({ turnId });
       throw error;
@@ -258,6 +290,7 @@ export class HarnessAgentSession {
     RUNTIME_CONTEXT extends Context,
     OUTPUT extends Output,
   >(options: {
+    skills: ReadonlyArray<HarnessV1Skill>;
     instructions: string | undefined;
     tools: TOOLS;
     activeTools: ToolSet;
@@ -278,6 +311,14 @@ export class HarnessAgentSession {
   }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
     const session = this.requireReusableSession();
     this.requireContinuableTurn();
+    const turnSettings = this.resolveActiveTurnSettings({
+      skills: options.skills,
+      instructions: options.instructions,
+      tools: options.tools,
+      activeTools: options.activeTools,
+      toolSpecs: options.toolSpecs,
+      builtinToolFiltering: options.builtinToolFiltering,
+    });
     const sandboxSession = this.getSandboxSession();
     const turnId = this.startTrackedTurn();
     try {
@@ -285,11 +326,12 @@ export class HarnessAgentSession {
         harness: this.harness,
         session,
         mode: 'continue',
-        instructions: options.instructions,
-        tools: options.tools,
-        activeTools: options.activeTools,
-        toolSpecs: options.toolSpecs,
-        builtinToolFiltering: options.builtinToolFiltering,
+        skills: turnSettings.persisted.skills,
+        instructions: turnSettings.persisted.instructions,
+        tools: turnSettings.tools as TOOLS,
+        activeTools: turnSettings.activeTools,
+        toolSpecs: [...turnSettings.persisted.tools],
+        builtinToolFiltering: turnSettings.builtinToolFiltering,
         sandboxSession: getRestrictedSandboxSession(sandboxSession),
         sessionWorkDir: this.sessionWorkDir,
         runtimeContext: options.runtimeContext,
@@ -331,7 +373,10 @@ export class HarnessAgentSession {
         onStopConditionMet: () =>
           this.captureStopConditionBoundary({ session, turnId }),
       });
-      return turn;
+      return {
+        ...turn,
+        ready: this.waitForPromptControl({ turnId }),
+      };
     } catch (error) {
       this.finishTrackedTurn({ turnId });
       throw error;
@@ -521,6 +566,7 @@ export class HarnessAgentSession {
   private addPendingToolState(
     state: HarnessAgentContinueTurnState,
   ): HarnessAgentContinueTurnState {
+    const turnSettings = this.persistedTurnSettings;
     const pendingToolApprovals = this.getPendingToolApprovals();
     const pendingToolResults = this.getPendingToolResults();
     if (pendingToolApprovals.length === 0 && pendingToolResults.length === 0) {
@@ -529,10 +575,12 @@ export class HarnessAgentSession {
         harnessId: state.harnessId,
         specificationVersion: state.specificationVersion,
         data: state.data,
+        ...(turnSettings == null ? {} : { turnSettings }),
       };
     }
     return {
       ...state,
+      ...(turnSettings == null ? {} : { turnSettings }),
       ...(pendingToolApprovals.length > 0 ? { pendingToolApprovals } : {}),
       ...(pendingToolResults.length > 0 ? { pendingToolResults } : {}),
     };
@@ -663,6 +711,14 @@ export class HarnessAgentSession {
     this.settleActivePromptControl(options.control);
   }
 
+  private async waitForPromptControl(options: {
+    turnId: number;
+  }): Promise<void> {
+    const activePromptControl = this.activePromptControl;
+    if (activePromptControl?.turnId !== options.turnId) return;
+    await activePromptControl.promise;
+  }
+
   private settleActivePromptControl(
     control: HarnessV1PromptControl | undefined,
   ): void {
@@ -691,9 +747,53 @@ export class HarnessAgentSession {
     this.pendingToolApprovals.clear();
     this.pendingToolResults.clear();
     this.suspendedTurnState = undefined;
+    this.activeTurnSettings = undefined;
+    this.persistedTurnSettings = undefined;
     this.turnState = 'idle';
   }
 
+  private resolveActiveTurnSettings(options: {
+    skills: ReadonlyArray<HarnessV1Skill>;
+    instructions: string | undefined;
+    tools: ToolSet;
+    activeTools: ToolSet;
+    toolSpecs: HarnessAgentToolSpec[];
+    builtinToolFiltering: HarnessV1BuiltinToolFiltering | undefined;
+  }): ActiveTurnSettings {
+    if (this.activeTurnSettings != null) {
+      return this.activeTurnSettings;
+    }
+    const persisted =
+      this.persistedTurnSettings ??
+      ({
+        skills: options.skills,
+        ...(options.instructions == null
+          ? {}
+          : { instructions: options.instructions }),
+        tools: options.toolSpecs,
+      } satisfies HarnessV1TurnSettings);
+    this.persistedTurnSettings = persisted;
+
+    const activeTools: ToolSet = {};
+    for (const toolSpec of persisted.tools) {
+      const tool = options.activeTools[toolSpec.name];
+      if (tool == null) {
+        throw new Error(
+          `HarnessAgent cannot continue turn because tool '${toolSpec.name}' is no longer available.`,
+        );
+      }
+      activeTools[toolSpec.name] = tool;
+    }
+
+    this.activeTurnSettings = {
+      persisted,
+      tools: options.tools,
+      activeTools,
+      builtinToolFiltering: options.builtinToolFiltering,
+    };
+    return this.activeTurnSettings;
+  }
+
   private endLocalHandle(options: {
     sessionState: Exclude<HarnessAgentSessionState, 'active'>;
   }): void {

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

@@ -12,11 +12,15 @@ import type {
   Arrayable,
   Context,
   Experimental_SandboxSession as SandboxSession,
+  FlexibleSchema,
+  MaybePromiseLike,
   ToolSet,
 } from '@ai-sdk/provider-utils';
 import type {
   ActiveTools,
+  AgentCallParameters,
   OutputInterface as Output,
+  Prompt,
   StopCondition,
   TelemetryOptions,
   ToolApprovalStatus,
@@ -74,9 +78,10 @@ type HarnessTools<TOOLS extends ToolSet> = ActiveTools<NoInfer<TOOLS>>;
 /**
  * Construction-time settings for a `HarnessAgent`.
  *
- * Per-call settings (prompt, abortSignal, callbacks) belong on the
+ * Prompt, abortSignal, callbacks, and custom call options belong on the
  * `AgentCallParameters` / `AgentStreamParameters` passed to `generate` /
- * `stream` and are not duplicated here.
+ * `stream`. `prepareCall` can derive turn-scoped skills, instructions, and
+ * tools from those custom call options.
  */
 type HarnessAgentToolFilteringSettings<TOOLS extends ToolSet> =
   | {
@@ -101,6 +106,7 @@ export type HarnessAgentSettings<
   TUserTools extends ToolSet = {},
   RUNTIME_CONTEXT extends Context = Context,
   OUTPUT extends Output = never,
+  CALL_OPTIONS = never,
 > = {
   /**
    * The harness adapter driving the underlying agent runtime. Its
@@ -115,6 +121,12 @@ export type HarnessAgentSettings<
    */
   readonly id?: string;
 
+  /**
+   * Model identifier passed to the harness adapter when a session starts.
+   * Supported values are defined by the selected harness.
+   */
+  readonly model?: string;
+
   /**
    * Tools available to the underlying runtime in addition to the harness's
    * own builtins. The agent forwards each tool to the harness as a
@@ -127,19 +139,86 @@ export type HarnessAgentSettings<
   readonly tools?: TUserTools;
 
   /**
-   * Skills made available to the underlying runtime for the lifetime of
-   * the session. Each adapter decides how to surface skills (file in the
-   * working tree, prompt prefix, …).
+   * Skills made available to the underlying runtime. Each adapter decides how
+   * to surface skills. `prepareCall` can replace them between completed turns.
    */
   readonly skills?: ReadonlyArray<HarnessAgentSkill>;
 
   /**
-   * Instructions for the underlying agent runtime. Adapters append this to a
+   * Instructions for the underlying agent runtime. Adapters append these to a
    * native system or developer prompt when supported. Otherwise, they prepend
-   * it to the first user message of a fresh session.
+   * them to the user message. `prepareCall` can replace them between completed
+   * turns.
    */
   readonly instructions?: string;
 
+  /**
+   * Schema for validating the custom options passed to each agent call.
+   */
+  readonly callOptionsSchema?: FlexibleSchema<CALL_OPTIONS>;
+
+  /**
+   * Prepares the prompt and the settings that may vary between completed
+   * turns. The prepared values are frozen for the lifetime of the turn,
+   * including any suspended-turn continuations.
+   *
+   * Preserve the remaining arguments with the rest-spread pattern when a
+   * field should be removable by returning `undefined`:
+   *
+   * ```ts
+   * prepareCall: ({ options, ...rest }) => ({
+   *   ...rest,
+   *   instructions: options.instructions,
+   * })
+   * ```
+   */
+  readonly prepareCall?: (
+    options: Omit<
+      AgentCallParameters<
+        CALL_OPTIONS,
+        HarnessAllTools<THarness, TUserTools>,
+        RUNTIME_CONTEXT
+      >,
+      | 'abortSignal'
+      | 'timeout'
+      | 'onStart'
+      | 'experimental_onStart'
+      | 'onStepStart'
+      | 'experimental_onStepStart'
+      | 'onToolExecutionStart'
+      | 'experimental_onToolCallStart'
+      | 'onToolExecutionEnd'
+      | 'experimental_onToolCallFinish'
+      | 'onStepEnd'
+      | 'onStepFinish'
+      | 'onEnd'
+      | 'onFinish'
+      | 'experimental_sandbox'
+    > &
+      Pick<
+        HarnessAgentSettings<
+          THarness,
+          TUserTools,
+          RUNTIME_CONTEXT,
+          NoInfer<OUTPUT>,
+          CALL_OPTIONS
+        >,
+        'skills' | 'instructions' | 'tools'
+      >,
+  ) => MaybePromiseLike<
+    Pick<
+      HarnessAgentSettings<
+        THarness,
+        TUserTools,
+        RUNTIME_CONTEXT,
+        NoInfer<OUTPUT>,
+        CALL_OPTIONS
+      >,
+      'skills' | 'instructions' | 'tools'
+    > &
+      Omit<Prompt, 'system' | 'instructions' | 'allowSystemInMessages'>
+  >;
+
   /**
    * Optional specification for generating typed output. The same output
    * requirement is active for every turn run by this agent.