@ai-sdk/harness 1.0.76 → 1.0.78

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

@@ -1,4 +1,8 @@
-import type { Context, ToolSet } from '@ai-sdk/provider-utils';
+import type {
+  Context,
+  Experimental_SandboxSession as SandboxSession,
+  ToolSet,
+} from '@ai-sdk/provider-utils';
 import type {
   OutputInterface as Output,
   StopCondition,
@@ -9,8 +13,10 @@ import type { HarnessAgentToolApprovalConfiguration } from './harness-agent-sett
 import type {
   HarnessV1BuiltinToolFiltering,
   HarnessV1NetworkSandboxSession,
+  HarnessV1PromptControl,
   HarnessV1ResponseFormat,
 } from '../v1';
+import { HarnessCapabilityUnsupportedError } from '../errors/harness-capability-unsupported-error';
 import type {
   HarnessAgentAdapter,
   HarnessAgentAdapterSession,
@@ -25,6 +31,7 @@ import type { HarnessAgentToolApprovalContinuation } from './harness-agent-tool-
 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';
 
 type HarnessAgentTurnResult<
   TOOLS extends ToolSet,
@@ -44,11 +51,18 @@ type HarnessAgentTurnState =
   | 'awaiting-tool-result'
   | 'suspended';
 
+type ActivePromptControl = {
+  readonly turnId: number;
+  readonly promise: Promise<HarnessV1PromptControl | undefined>;
+  resolve(control: HarnessV1PromptControl | undefined): void;
+  settled: boolean;
+};
+
 /**
  * Live harness session held by the caller.
  *
  * Created by {@link import('./harness-agent').HarnessAgent.createSession}.
- * Owns the underlying adapter session and the network sandbox session.
+ * Owns the underlying adapter session and holds its sandbox session.
  *
  * Pass the instance back to `agent.generate` / `agent.stream` on every
  * call; end the local handle with `detach()`, `stop()`, or `destroy()`.
@@ -68,7 +82,10 @@ export class HarnessAgentSession {
   private readonly sessionWorkDir: string;
   private readonly ownsSandboxLifecycle: boolean;
   private underlyingSession: HarnessAgentAdapterSession | undefined;
-  private sandboxSession: HarnessV1NetworkSandboxSession | undefined;
+  private sandboxSession:
+    | HarnessV1NetworkSandboxSession
+    | SandboxSession
+    | undefined;
   private readonly toolApproval:
     | HarnessAgentToolApprovalConfiguration
     | undefined;
@@ -84,6 +101,7 @@ export class HarnessAgentSession {
   private turnState: HarnessAgentTurnState;
   private turnSequence = 0;
   private activeTurnSequence = 0;
+  private activePromptControl: ActivePromptControl | undefined;
   private suspendedTurnState:
     | Promise<HarnessAgentContinueTurnState>
     | undefined;
@@ -98,7 +116,7 @@ export class HarnessAgentSession {
     sessionId: string;
     harness: HarnessAgentAdapter;
     underlyingSession: HarnessAgentAdapterSession;
-    sandboxSession: HarnessV1NetworkSandboxSession;
+    sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
     ownsSandboxLifecycle?: boolean;
     sessionWorkDir: string;
     toolApproval: HarnessAgentToolApprovalConfiguration | undefined;
@@ -130,11 +148,11 @@ export class HarnessAgentSession {
   }
 
   /**
-   * Active network sandbox session.
+   * Active sandbox session.
    *
    * @internal — accessed by session turn and lifecycle drivers.
    */
-  getSandboxSession(): HarnessV1NetworkSandboxSession {
+  getSandboxSession(): HarnessV1NetworkSandboxSession | SandboxSession {
     if (this.sessionState !== 'active' || this.sandboxSession == null) {
       throw new Error(
         `Harness session ${this.sessionId} has ended and cannot be reused.`,
@@ -189,7 +207,7 @@ export class HarnessAgentSession {
         activeTools: options.activeTools,
         toolSpecs: options.toolSpecs,
         builtinToolFiltering: options.builtinToolFiltering,
-        sandboxSession: sandboxSession.restricted(),
+        sandboxSession: getRestrictedSandboxSession(sandboxSession),
         sessionWorkDir: this.sessionWorkDir,
         runtimeContext: options.runtimeContext,
         abortSignal: options.abortSignal,
@@ -220,6 +238,9 @@ export class HarnessAgentSession {
         onTurnFailed: () => {
           this.finishTrackedTurn({ turnId });
         },
+        onPromptControlAvailable: control => {
+          this.setPromptControl({ turnId, control });
+        },
         isTurnSuspending: () =>
           this.activeTurnSequence === turnId && this.suspendedTurnState != null,
         onStopConditionMet: () =>
@@ -269,7 +290,7 @@ export class HarnessAgentSession {
         activeTools: options.activeTools,
         toolSpecs: options.toolSpecs,
         builtinToolFiltering: options.builtinToolFiltering,
-        sandboxSession: sandboxSession.restricted(),
+        sandboxSession: getRestrictedSandboxSession(sandboxSession),
         sessionWorkDir: this.sessionWorkDir,
         runtimeContext: options.runtimeContext,
         abortSignal: options.abortSignal,
@@ -302,6 +323,9 @@ export class HarnessAgentSession {
         onTurnFailed: () => {
           this.finishTrackedTurn({ turnId });
         },
+        onPromptControlAvailable: control => {
+          this.setPromptControl({ turnId, control });
+        },
         isTurnSuspending: () =>
           this.activeTurnSequence === turnId && this.suspendedTurnState != null,
         onStopConditionMet: () =>
@@ -328,6 +352,49 @@ export class HarnessAgentSession {
     await this.requireReusableSession().doCompact(customInstructions);
   }
 
+  /**
+   * Submit another user message to the active turn.
+   *
+   * The runtime accepts the message for its next safe input boundary. Output
+   * caused by the message remains part of the active turn's result stream.
+   */
+  async experimental_steerTurn(text: string): Promise<void> {
+    this.requireReusableSession();
+    const activePromptControl = this.activePromptControl;
+    if (
+      this.turnState !== 'running' ||
+      this.suspendedTurnState != null ||
+      activePromptControl == null
+    ) {
+      throw new Error(
+        `Harness session ${this.sessionId} has no running turn to steer.`,
+      );
+    }
+
+    const control = await activePromptControl.promise;
+    if (
+      control == null ||
+      this.sessionState !== 'active' ||
+      this.turnState !== 'running' ||
+      this.suspendedTurnState != null ||
+      this.activePromptControl !== activePromptControl ||
+      this.activeTurnSequence !== activePromptControl.turnId
+    ) {
+      throw new Error(
+        `Harness session ${this.sessionId} no longer has the running turn targeted for steering.`,
+      );
+    }
+
+    if (control.submitUserMessage == null) {
+      throw new HarnessCapabilityUnsupportedError({
+        message: `Harness '${this.harness.harnessId}' does not support steering active turns.`,
+        harnessId: this.harness.harnessId,
+      });
+    }
+
+    await control.submitUserMessage(text);
+  }
+
   /**
    * Park the session, returning a payload the caller can persist and later
    * pass to `agent.createSession({ sessionId, resumeFrom })` to reconnect.
@@ -388,7 +455,7 @@ export class HarnessAgentSession {
       return validated;
     } finally {
       this.endLocalHandle({ sessionState: 'stopped' });
-      if (this.ownsSandboxLifecycle) {
+      if (this.ownsSandboxLifecycle && 'stop' in sandboxSession) {
         await Promise.resolve(sandboxSession.stop()).catch(() => {});
       }
     }
@@ -407,9 +474,11 @@ export class HarnessAgentSession {
       await Promise.resolve(session.doDestroy()).catch(() => {});
     }
     if (!this.ownsSandboxLifecycle) return;
-    await Promise.resolve(
-      sandboxSession.destroy?.() ?? sandboxSession.stop(),
-    ).catch(() => {});
+    if ('stop' in sandboxSession) {
+      await Promise.resolve(
+        sandboxSession.destroy?.() ?? sandboxSession.stop(),
+      ).catch(() => {});
+    }
   }
 
   /**
@@ -474,6 +543,7 @@ export class HarnessAgentSession {
   private async suspendCurrentTurn(options: {
     session: HarnessAgentAdapterSession;
   }): Promise<HarnessAgentContinueTurnState> {
+    this.clearActivePromptControl();
     this.suspendedTurnState ??= (async () => {
       const raw = await options.session.doSuspendTurn();
       const validated = await validateLifecycleStateData({
@@ -546,12 +616,14 @@ export class HarnessAgentSession {
 
   private markAwaitingApprovalIfActive(): void {
     if (this.sessionState === 'active') {
+      this.clearActivePromptControl();
       this.turnState = 'awaiting-approval';
     }
   }
 
   private markAwaitingToolResultIfActive(): void {
     if (this.sessionState === 'active') {
+      this.clearActivePromptControl();
       this.turnState = 'awaiting-tool-result';
     }
   }
@@ -561,12 +633,63 @@ export class HarnessAgentSession {
     this.activeTurnSequence = turnId;
     this.suspendedTurnState = undefined;
     this.turnState = 'running';
+    this.clearActivePromptControl();
+    let resolve!: (control: HarnessV1PromptControl | undefined) => void;
+    const promise = new Promise<HarnessV1PromptControl | undefined>(
+      resolvePromise => {
+        resolve = resolvePromise;
+      },
+    );
+    this.activePromptControl = {
+      turnId,
+      promise,
+      resolve,
+      settled: false,
+    };
     return turnId;
   }
 
+  private setPromptControl(options: {
+    turnId: number;
+    control: HarnessV1PromptControl;
+  }): void {
+    const activePromptControl = this.activePromptControl;
+    if (
+      this.sessionState !== 'active' ||
+      this.turnState !== 'running' ||
+      this.activeTurnSequence !== options.turnId ||
+      activePromptControl?.turnId !== options.turnId
+    ) {
+      return;
+    }
+    this.settleActivePromptControl(options.control);
+  }
+
+  private settleActivePromptControl(
+    control: HarnessV1PromptControl | undefined,
+  ): void {
+    const activePromptControl = this.activePromptControl;
+    if (activePromptControl == null || activePromptControl.settled) return;
+    activePromptControl.settled = true;
+    activePromptControl.resolve(control);
+  }
+
+  private clearActivePromptControl(turnId?: number): void {
+    if (
+      turnId != null &&
+      this.activePromptControl != null &&
+      this.activePromptControl.turnId !== turnId
+    ) {
+      return;
+    }
+    this.settleActivePromptControl(undefined);
+    this.activePromptControl = undefined;
+  }
+
   private finishTrackedTurn(options: { turnId: number }): void {
     if (this.sessionState !== 'active') return;
     if (this.activeTurnSequence !== options.turnId) return;
+    this.clearActivePromptControl(options.turnId);
     this.pendingToolApprovals.clear();
     this.pendingToolResults.clear();
     this.suspendedTurnState = undefined;
@@ -576,6 +699,7 @@ export class HarnessAgentSession {
   private endLocalHandle(options: {
     sessionState: Exclude<HarnessAgentSessionState, 'active'>;
   }): void {
+    this.clearActivePromptControl();
     this.sessionState = options.sessionState;
     this.underlyingSession = undefined;
     this.sandboxSession = undefined;

package/src/agent/harness-agent.ts

@@ -11,6 +11,7 @@ import {
   asSchema,
   generateId,
   type Context,
+  type Experimental_SandboxSession as SandboxSession,
   type ModelMessage,
   type ToolSet,
 } from '@ai-sdk/provider-utils';
@@ -64,6 +65,8 @@ import {
   resolvePermissionMode,
 } from './internal/permission-mode';
 import { resolveHarnessAgentToolFiltering } from './internal/tool-filtering';
+import { resolveSandboxDefaultWorkingDirectory } from '../utils/resolve-sandbox-default-working-directory';
+import { getRestrictedSandboxSession } from '../utils/get-restricted-sandbox-session';
 
 export type { HarnessAllTools } from './harness-agent-tool-types';
 
@@ -108,12 +111,13 @@ export interface HarnessAgentCallExtensions {
  *    Adapter builtin tools (e.g. Claude Code's `Bash`) pass through
  *    untouched.
  *  - **Sandbox propagation.** On `createSession`, the agent uses a
- *    caller-provided network sandbox session when present; otherwise it calls
- *    the configured provider's `createSession()` (or `resumeSession()`). It
- *    passes the selected session into `doStart`. Its `restricted()` view (a tool-safe
- *    `Experimental_SandboxSession`) is handed to user-tool `execute()` calls
- *    via `experimental_sandbox`. Caller-provided sandboxes remain owned by the
- *    caller and are not stopped or destroyed by the harness layer.
+ *    caller-provided network or basic sandbox session when present; otherwise
+ *    it calls the configured provider's `createSession()` (or
+ *    `resumeSession()`). It passes the selected session into `doStart`. A
+ *    tool-safe `SandboxSession` is handed to user-tool
+ *    `execute()` calls via `experimental_sandbox`. Caller-provided sandboxes
+ *    remain owned by the caller and are not stopped or destroyed by the
+ *    harness layer.
  */
 export class HarnessAgent<
   THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter,
@@ -234,10 +238,10 @@ export class HarnessAgent<
      */
     continueFrom?: HarnessAgentContinueTurnState;
     /**
-     * Existing network sandbox session to run the harness in. When provided,
-     * the caller retains ownership of the sandbox lifecycle.
+     * Existing sandbox session to run the harness in. When provided, the
+     * caller retains ownership of the sandbox lifecycle.
      */
-    sandboxSession?: HarnessV1NetworkSandboxSession;
+    sandboxSession?: HarnessV1NetworkSandboxSession | SandboxSession;
     abortSignal?: AbortSignal;
   }): Promise<HarnessAgentSession> {
     const sessionId = options?.sessionId ?? generateId();
@@ -281,12 +285,19 @@ export class HarnessAgent<
     // Acquires the concrete sandbox session, either by starting fresh and then
     // creating a post-bootstrap snapshot, or by reusing a previously created
     // snapshot based on the bootstrap-based hashes.
-    let sandboxSession: HarnessV1NetworkSandboxSession;
+    let sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
     let sessionWorkDir: string;
     if (providedSandboxSession != null) {
       sandboxSession = providedSandboxSession;
+      const toolSafeSandboxSession =
+        getRestrictedSandboxSession(sandboxSession);
+      const defaultWorkingDirectory =
+        await resolveSandboxDefaultWorkingDirectory({
+          sandboxSession,
+          abortSignal,
+        });
       sessionWorkDir = resolveSessionWorkDir({
-        defaultWorkingDirectory: sandboxSession.defaultWorkingDirectory,
+        defaultWorkingDirectory,
         harnessId: harness.harnessId,
         sessionId,
         workDir: this.sandboxConfig.workDir,
@@ -297,10 +308,10 @@ export class HarnessAgent<
         const recipeIdentity = await hashHarnessBootstrap(recipe);
         try {
           await applyBootstrapRecipe({
-            session: sandboxSession.restricted(),
+            session: toolSafeSandboxSession,
             recipe,
             identity: recipeIdentity,
-            defaultWorkingDirectory: sandboxSession.defaultWorkingDirectory,
+            defaultWorkingDirectory,
             abortSignal,
           });
         } catch (err) {
@@ -325,12 +336,14 @@ export class HarnessAgent<
             harnessId: harness.harnessId,
           });
         }
-        sandboxSession = await sandboxProvider.resumeSession({
+        const resumedSandboxSession = await sandboxProvider.resumeSession({
           sessionId,
           abortSignal,
         });
+        sandboxSession = resumedSandboxSession;
         sessionWorkDir = resolveSessionWorkDir({
-          defaultWorkingDirectory: sandboxSession.defaultWorkingDirectory,
+          defaultWorkingDirectory:
+            resumedSandboxSession.defaultWorkingDirectory,
           harnessId: harness.harnessId,
           sessionId,
           workDir: this.sandboxConfig.workDir,
@@ -352,14 +365,16 @@ export class HarnessAgent<
           settings: this.sandboxConfig,
         });
 
-        sandboxSession = await sandboxProvider.createSession({
+        const createdSandboxSession = await sandboxProvider.createSession({
           sessionId,
           abortSignal,
           identity: sandboxBootstrapPlan.identity,
           onFirstCreate: sandboxBootstrapPlan.onFirstCreate,
         });
+        sandboxSession = createdSandboxSession;
         sessionWorkDir = resolveSessionWorkDir({
-          defaultWorkingDirectory: sandboxSession.defaultWorkingDirectory,
+          defaultWorkingDirectory:
+            createdSandboxSession.defaultWorkingDirectory,
           harnessId: harness.harnessId,
           sessionId,
           workDir: sandboxBootstrapPlan.workDir,
@@ -375,10 +390,11 @@ export class HarnessAgent<
         ) {
           try {
             await applyBootstrapRecipe({
-              session: sandboxSession.restricted(),
+              session: createdSandboxSession.restricted(),
               recipe: sandboxBootstrapPlan.recipe,
               identity: sandboxBootstrapPlan.recipeIdentity,
-              defaultWorkingDirectory: sandboxSession.defaultWorkingDirectory,
+              defaultWorkingDirectory:
+                createdSandboxSession.defaultWorkingDirectory,
               abortSignal,
             });
           } catch (err) {
@@ -400,7 +416,7 @@ export class HarnessAgent<
       });
       if (this.sandboxConfig.onSession != null) {
         await this.sandboxConfig.onSession({
-          session: sandboxSession.restricted(),
+          session: getRestrictedSandboxSession(sandboxSession),
           sessionWorkDir,
           abortSignal,
         });
@@ -586,6 +602,20 @@ export class HarnessAgent<
     return result;
   }
 
+  /**
+   * Submit another user message to a currently running session turn.
+   *
+   * The returned promise resolves after the runtime has accepted the message
+   * for its next safe input boundary. Output caused by the message remains in
+   * the current turn's stream.
+   */
+  async experimental_steer(options: {
+    session: HarnessAgentSession;
+    text: string;
+  }): Promise<void> {
+    await options.session.experimental_steerTurn(options.text);
+  }
+
   // ─── Internals ──────────────────────────────────────────────────────
 
   private _startTurn(input: {
@@ -923,9 +953,11 @@ function resolveSandboxConfig(
 }
 
 async function cleanupAfterStartFailure(input: {
-  sandboxSession: HarnessV1NetworkSandboxSession;
+  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
   ownsSandboxLifecycle: boolean;
 }): Promise<void> {
   if (!input.ownsSandboxLifecycle) return;
-  await Promise.resolve(input.sandboxSession.stop()).catch(() => {});
+  if ('stop' in input.sandboxSession) {
+    await Promise.resolve(input.sandboxSession.stop()).catch(() => {});
+  }
 }

package/src/agent/internal/run-prompt.ts

@@ -108,6 +108,7 @@ export function runPrompt<
   onToolResultSettled?: (toolCallId: string) => void;
   onTurnFinished?: () => void;
   onTurnFailed?: () => void;
+  onPromptControlAvailable?: (control: HarnessV1PromptControl) => void;
   /**
    * Reports that the adapter stream closed because the host intentionally
    * suspended the still-running turn at a workflow slice boundary.
@@ -213,6 +214,7 @@ export function runPrompt<
     }
 
     const { stream, control } = bridge;
+    input.onPromptControlAvailable?.(control);
     const reader = stream.getReader();
     const toolCallsByToolCallId = new Map<string, ToolCallTextStreamPart>();
     const rawToolCallsByToolCallId = new Map<

package/src/agent/internal/sandbox-bootstrap.ts

@@ -1,6 +1,7 @@
 import { posix } from 'node:path';
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
 import type { HarnessV1Bootstrap } from '../../v1';
+import { resolveSandboxDefaultWorkingDirectory } from '../../utils/resolve-sandbox-default-working-directory';
 import type { HarnessAgentSandboxConfig } from '../harness-agent-settings';
 import { applyBootstrapRecipe, hashHarnessBootstrap } from './bootstrap-recipe';
 
@@ -148,8 +149,8 @@ export async function runSandboxBootstrap({
 
   const resolvedDefaultWorkingDirectory =
     defaultWorkingDirectory ??
-    (await resolveDefaultWorkingDirectory({
-      session,
+    (await resolveSandboxDefaultWorkingDirectory({
+      sandboxSession: session,
       abortSignal,
     }));
 
@@ -181,32 +182,6 @@ export async function runSandboxBootstrap({
   await onBootstrap({ session, workDir: bootstrapWorkDir, abortSignal });
 }
 
-export async function resolveDefaultWorkingDirectory({
-  session,
-  abortSignal,
-}: {
-  readonly session: SandboxSession;
-  readonly abortSignal?: AbortSignal;
-}): Promise<string> {
-  const result = await session.run({
-    command: 'pwd',
-    abortSignal,
-  });
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `Failed to resolve sandbox default working directory (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
-    );
-  }
-
-  const cwd = result.stdout.trim();
-  if (!posix.isAbsolute(cwd)) {
-    throw new Error(
-      `Failed to resolve sandbox default working directory: expected an absolute path, got ${JSON.stringify(cwd)}.`,
-    );
-  }
-  return cwd === '/' ? cwd : cwd.replace(/\/+$/, '');
-}
-
 export async function ensureSandboxDirectory({
   session,
   workDir,

package/src/agent/prepare-sandbox-for-harness.ts

@@ -1,13 +1,13 @@
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
 import type { HarnessAgentSandboxConfig } from './harness-agent-settings';
 import type { HarnessAgentAdapter } from './harness-agent-types';
+import { resolveSandboxDefaultWorkingDirectory } from '../utils/resolve-sandbox-default-working-directory';
 import {
   applyBootstrapRecipe,
   hashHarnessBootstrap,
 } from './internal/bootstrap-recipe';
 import {
   normalizeSandboxWorkDir,
-  resolveDefaultWorkingDirectory,
   runSandboxBootstrap,
   validateSandboxBootstrapSettings,
 } from './internal/sandbox-bootstrap';
@@ -80,8 +80,8 @@ export async function prepareSandboxForHarness(options: {
 
     const recipeIdentity = await hashHarnessBootstrap(recipe);
     recipeIdentities[harness.harnessId] = recipeIdentity;
-    defaultWorkingDirectory ??= await resolveDefaultWorkingDirectory({
-      session: options.session,
+    defaultWorkingDirectory ??= await resolveSandboxDefaultWorkingDirectory({
+      sandboxSession: options.session,
       abortSignal: options.abortSignal,
     });
     await applyBootstrapRecipe({