@ai-sdk/harness 1.0.132 → 1.0.133

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness",
-  "version": "1.0.132",
+  "version": "1.0.133",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

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

@@ -17,6 +17,7 @@ import type {
   HarnessV1BuiltinToolFiltering,
   HarnessV1NetworkSandboxSession,
   HarnessV1PromptControl,
+  HarnessV1ReadHistoryResult,
   HarnessV1ResponseFormat,
   HarnessV1Skill,
   HarnessV1TurnSettings,
@@ -482,22 +483,53 @@ export class HarnessAgentSession {
       );
     }
     const session = this.underlyingSession;
-    try {
-      if (this.turnState !== 'idle') {
-        return this.toResumeStateWithContinuation({
-          continueFrom: await this.finalizeCurrentTurnSuspension({ session }),
-        });
-      }
-      const raw = await session.doDetach();
-      const validated = await validateLifecycleStateData({
-        harness: this.harness,
-        state: raw,
-        expectedType: 'resume-session',
+    const state =
+      this.turnState !== 'idle'
+        ? this.toResumeStateWithContinuation({
+            continueFrom: await this.finalizeCurrentTurnSuspension({ session }),
+          })
+        : await validateLifecycleStateData({
+            harness: this.harness,
+            state: await session.doDetach(),
+            expectedType: 'resume-session',
+          });
+    this.endLocalHandle({ sessionState: 'detached' });
+    return state;
+  }
+
+  /**
+   * Read the conversation history the runtime itself persisted, normalized
+   * by the adapter. Includes exchanges that happened outside this process —
+   * the same conversation continued interactively in the agent's own CLI,
+   * for instance — which the live event stream never saw.
+   *
+   * Pass a previous result's `cursor` as `since` to read only the delta. A
+   * conversation with no recorded messages yet resolves to an empty
+   * `messages` array.
+   *
+   * Throws `HarnessCapabilityUnsupportedError` when the adapter does not
+   * implement history reads, and
+   * `HarnessHistoryUnavailableError` when the adapter supports them but
+   * cannot reach the runtime's store from this environment.
+   */
+  async readHistory(options?: {
+    since?: string;
+  }): Promise<HarnessV1ReadHistoryResult> {
+    if (this.sessionState !== 'active' || this.underlyingSession == null) {
+      throw new Error(
+        `Harness session ${this.sessionId} is not active and cannot read history.`,
+      );
+    }
+    const session = this.underlyingSession;
+    if (typeof session.doReadHistory !== 'function') {
+      throw new HarnessCapabilityUnsupportedError({
+        harnessId: this.harness.harnessId,
+        message: `Harness '${this.harness.harnessId}' does not support reading the runtime's conversation history.`,
       });
-      return validated;
-    } finally {
-      this.endLocalHandle({ sessionState: 'detached' });
     }
+    return await session.doReadHistory({
+      ...(options?.since != null ? { since: options.since } : {}),
+    });
   }
 
   /**

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

@@ -366,34 +366,47 @@ export function runPrompt<
       pendingStopBoundary = undefined;
     };
 
-    // Accumulate the model response until its step boundary. Harness runtimes
-    // may execute tools before emitting `finish-step`, so tool lifecycle
-    // notifications and consumer-visible tool outcomes are held until then.
+    // Accumulate the model response until its step boundary. Tool lifecycle
+    // notifications and consumer-visible tool outcomes are published as each
+    // tool runs; `finish-step` remains the boundary for step accounting.
     let stepText = '';
     let stepReasoning = '';
     let stepToolCalls: ContentPart<TOOLS>[] = [];
     let stepProviderToolResults: ContentPart<TOOLS>[] = [];
     let stepApprovalRequests: ContentPart<TOOLS>[] = [];
     let bufferedToolOutcomes: Array<() => void> = [];
-    const toolExecutions = new Map<
-      string,
-      {
-        toolCall: TypedToolCall<TOOLS>;
-        toolOutput?: TypedToolResult<TOOLS> | TypedToolError<TOOLS>;
-        toolExecutionMs?: number;
-      }
-    >();
+    type ToolExecutionState = {
+      toolCall: TypedToolCall<TOOLS>;
+      toolOutput?: TypedToolResult<TOOLS> | TypedToolError<TOOLS>;
+      toolExecutionMs?: number;
+      executionStartedAt?: number;
+      startNotification?: Promise<void>;
+      endNotification?: Promise<void>;
+    };
+    const toolExecutions = new Map<string, ToolExecutionState>();
+    const publishToolExecutionStart = async (
+      execution: ToolExecutionState,
+    ): Promise<void> => {
+      execution.startNotification ??= lifecycle.toolExecutionStart({
+        toolCall: execution.toolCall,
+      });
+      await execution.startNotification;
+    };
+    const publishToolExecutionEnd = async (
+      execution: ToolExecutionState,
+    ): Promise<void> => {
+      if (execution.toolOutput == null) return;
+      await publishToolExecutionStart(execution);
+      execution.endNotification ??= lifecycle.toolExecutionEnd({
+        toolCall: execution.toolCall,
+        toolOutput: execution.toolOutput,
+        toolExecutionMs: execution.toolExecutionMs ?? 0,
+      });
+      await execution.endNotification;
+    };
     const publishToolExecutions = async (): Promise<void> => {
       for (const execution of toolExecutions.values()) {
-        if (execution.toolOutput == null) continue;
-        await lifecycle.toolExecutionStart({
-          toolCall: execution.toolCall,
-        });
-        await lifecycle.toolExecutionEnd({
-          toolCall: execution.toolCall,
-          toolOutput: execution.toolOutput,
-          toolExecutionMs: execution.toolExecutionMs ?? 0,
-        });
+        await publishToolExecutionEnd(execution);
       }
       for (const publish of bufferedToolOutcomes) publish();
       toolExecutions.clear();
@@ -749,6 +762,9 @@ export function runPrompt<
       toolExecutions.set(rawToolCall.toolCallId, {
         toolCall: toolCall as TypedToolCall<TOOLS>,
       });
+      await publishToolExecutionStart(
+        toolExecutions.get(rawToolCall.toolCallId)!,
+      );
       const executionStartedAt = Date.now();
       const execution = await maybeExecuteHostTool({
         event: rawToolCall,
@@ -772,16 +788,14 @@ export function runPrompt<
             },
             input.sessionWorkDir,
           ) as Extract<HarnessV1StreamPart, { type: 'tool-result' }>;
-          bufferedToolOutcomes.push(() => {
-            result.enqueue({
-              type: 'tool-result',
-              toolCallId: rawToolCall.toolCallId,
-              toolName: rawToolCall.toolName,
-              input: undefined,
-              output: stripped.result,
-              preliminary: true,
-            } as TextStreamPart<TOOLS>);
-          });
+          result.enqueue({
+            type: 'tool-result',
+            toolCallId: rawToolCall.toolCallId,
+            toolName: rawToolCall.toolName,
+            input: undefined,
+            output: stripped.result,
+            preliminary: true,
+          } as TextStreamPart<TOOLS>);
         },
       });
       if (!execution.executed) {
@@ -795,13 +809,11 @@ export function runPrompt<
         outcome: execution.outcome,
       });
       toolExecution.toolExecutionMs = Date.now() - executionStartedAt;
-      bufferedToolOutcomes.push(() => {
-        enqueueHostToolOutcome({
-          toolCall,
-          outcome: execution.outcome,
-        });
+      await publishToolExecutionEnd(toolExecution);
+      enqueueHostToolOutcome({
+        toolCall,
+        outcome: execution.outcome,
       });
-      await publishToolExecutions();
       return 'continued';
     };
 
@@ -1007,11 +1019,7 @@ export function runPrompt<
           displayValue,
           translateOptions,
         );
-        if (value.type === 'tool-result') {
-          bufferedToolOutcomes.push(() => {
-            for (const part of translatedParts) result.enqueue(part);
-          });
-        } else {
+        if (value.type !== 'tool-result') {
           for (const part of translatedParts) result.enqueue(part);
         }
 
@@ -1059,9 +1067,13 @@ export function runPrompt<
           const toolCall = toolCallsByToolCallId.get(value.toolCallId);
           if (toolCall != null) {
             stepToolCalls.push(toolCall as ContentPart<TOOLS>);
-            toolExecutions.set(value.toolCallId, {
+            const execution: ToolExecutionState = {
               toolCall: toolCall as TypedToolCall<TOOLS>,
-            });
+            };
+            toolExecutions.set(value.toolCallId, execution);
+            if (value.providerExecuted === true) {
+              await publishToolExecutionStart(execution);
+            }
           }
         }
 
@@ -1080,6 +1092,13 @@ export function runPrompt<
                   output: value.result,
                 } as TypedToolResult<TOOLS>);
           }
+          if (
+            execution?.toolExecutionMs == null &&
+            execution?.executionStartedAt != null
+          ) {
+            execution.toolExecutionMs =
+              Date.now() - execution.executionStartedAt;
+          }
           if (
             rawToolCallsByToolCallId.get(value.toolCallId)?.providerExecuted ===
               true &&
@@ -1089,6 +1108,10 @@ export function runPrompt<
               execution.toolOutput as ContentPart<TOOLS>,
             );
           }
+          if (execution != null) {
+            await publishToolExecutionEnd(execution);
+          }
+          for (const part of translatedParts) result.enqueue(part);
         }
 
         if (value.type === 'tool-approval-request') {
@@ -1267,16 +1290,20 @@ export function runPrompt<
               type: 'execution-denied',
               reason: customToolApprovalDecision.reason,
             };
+            const execution = toolExecutions.get(toolCall.toolCallId);
+            if (execution != null) {
+              await publishToolExecutionStart(execution);
+            }
             await submitToolResult({
               toolCallId: toolCall.toolCallId,
               output,
             });
-            const execution = toolExecutions.get(toolCall.toolCallId);
             if (execution != null) {
               execution.toolOutput = toToolOutput({
                 toolCall: parsedToolCall,
                 outcome: { ok: true, output },
               });
+              await publishToolExecutionEnd(execution);
             }
             continue;
           }
@@ -1353,7 +1380,15 @@ export function runPrompt<
           }
           startHostToolExecution(
             (async () => {
+              const toolExecution = toolExecutions.get(toolCall.toolCallId);
+              if (toolExecution == null) {
+                throw new Error(
+                  `Harness '${input.harness.harnessId}' could not track host tool '${toolCall.toolName}'.`,
+                );
+              }
+              await publishToolExecutionStart(toolExecution);
               const executionStartedAt = Date.now();
+              toolExecution.executionStartedAt = executionStartedAt;
               const execution = await maybeExecuteHostTool({
                 event: toolCall,
                 parsedToolCall: validatedHostToolCall,
@@ -1384,16 +1419,14 @@ export function runPrompt<
                     },
                     input.sessionWorkDir,
                   ) as Extract<HarnessV1StreamPart, { type: 'tool-result' }>;
-                  bufferedToolOutcomes.push(() => {
-                    result.enqueue({
-                      type: 'tool-result',
-                      toolCallId: toolCall.toolCallId,
-                      toolName: toolCall.toolName,
-                      input: undefined,
-                      output: stripped.result,
-                      preliminary: true,
-                    } as TextStreamPart<TOOLS>);
-                  });
+                  result.enqueue({
+                    type: 'tool-result',
+                    toolCallId: toolCall.toolCallId,
+                    toolName: toolCall.toolName,
+                    input: undefined,
+                    output: stripped.result,
+                    preliminary: true,
+                  } as TextStreamPart<TOOLS>);
                 },
               });
               if (!execution.executed) {
@@ -1401,14 +1434,12 @@ export function runPrompt<
                   `Harness '${input.harness.harnessId}' could not execute host tool '${toolCall.toolName}'.`,
                 );
               }
-              const toolExecution = toolExecutions.get(toolCall.toolCallId);
-              if (toolExecution != null) {
-                toolExecution.toolOutput = toToolOutput({
-                  toolCall: parsedToolCall,
-                  outcome: execution.outcome,
-                });
-                toolExecution.toolExecutionMs = Date.now() - executionStartedAt;
-              }
+              toolExecution.toolOutput = toToolOutput({
+                toolCall: parsedToolCall,
+                outcome: execution.outcome,
+              });
+              toolExecution.toolExecutionMs = Date.now() - executionStartedAt;
+              await publishToolExecutionEnd(toolExecution);
             })(),
           );
         }

package/src/errors/harness-history-unavailable-error.ts

@@ -0,0 +1,41 @@
+import { AISDKError } from '@ai-sdk/provider';
+import { HarnessError } from './harness-error';
+
+const name = 'AI_HarnessHistoryUnavailableError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Thrown by `readHistory` when the adapter supports history reads but cannot
+ * reach the runtime's store from the current environment — for example the
+ * store lives inside a remote sandbox, or the transcript directory is
+ * missing or unreadable.
+ *
+ * Distinct from `HarnessCapabilityUnsupportedError` (the adapter does not
+ * implement history reads at all) so hosts can retry or degrade differently.
+ * A conversation with no recorded messages yet is not an error; it resolves
+ * to an empty result instead.
+ */
+export class HarnessHistoryUnavailableError extends HarnessError {
+  private readonly [symbol] = true;
+
+  readonly harnessId?: string;
+
+  constructor({
+    message,
+    harnessId,
+    cause,
+  }: {
+    message: string;
+    harnessId?: string;
+    cause?: unknown;
+  }) {
+    super({ message, cause });
+    Object.defineProperty(this, 'name', { value: name });
+    this.harnessId = harnessId;
+  }
+
+  static isInstance(error: unknown): error is HarnessHistoryUnavailableError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './v1';
 export * from './errors/harness-error';
 export * from './errors/harness-capability-unsupported-error';
+export * from './errors/harness-history-unavailable-error';
 export * from './errors/harness-sandbox-authentication-error';

package/src/utils/credential-forwarding.ts

@@ -28,14 +28,16 @@ export async function applyCredentialForwarding({
   return forwardedEnvironment;
 }
 
-export async function createSandboxCredentialEnvironment({
+export async function resolveSandboxCredentialEnvironment({
   environment,
   credentialEnvironmentVariables,
   credentialForwarding,
+  previousSandboxCredentialEnvironment,
 }: {
   environment: Readonly<Record<string, string>>;
   credentialEnvironmentVariables: ReadonlyArray<string>;
   credentialForwarding: HarnessV1CredentialForwarding | undefined;
+  previousSandboxCredentialEnvironment?: Readonly<Record<string, string>>;
 }): Promise<Record<string, string>> {
   const sandboxCredentialEnvironment: Record<string, string> = {};
 
@@ -44,6 +46,18 @@ export async function createSandboxCredentialEnvironment({
   )) {
     if (environment[environmentVariableName] == null) continue;
 
+    if (
+      previousSandboxCredentialEnvironment != null &&
+      Object.prototype.hasOwnProperty.call(
+        previousSandboxCredentialEnvironment,
+        environmentVariableName,
+      )
+    ) {
+      sandboxCredentialEnvironment[environmentVariableName] =
+        previousSandboxCredentialEnvironment[environmentVariableName];
+      continue;
+    }
+
     const placeholder = generateSandboxCredentialPlaceholder();
     sandboxCredentialEnvironment[environmentVariableName] =
       credentialForwarding == null

package/src/utils/index.ts

@@ -28,7 +28,7 @@ export {
 export { isLinux, isMacOS, isWindows } from './os';
 export {
   applyCredentialForwarding,
-  createSandboxCredentialEnvironment,
+  resolveSandboxCredentialEnvironment,
 } from './credential-forwarding';
 export {
   createCredentialRequestTransformation,

package/src/v1/harness-v1-message.ts

@@ -0,0 +1,150 @@
+import type {
+  LanguageModelV4CustomPart,
+  LanguageModelV4FilePart,
+  LanguageModelV4ReasoningFilePart,
+  LanguageModelV4ReasoningPart,
+  LanguageModelV4TextPart,
+  LanguageModelV4ToolApprovalResponsePart,
+  LanguageModelV4ToolCallPart,
+  LanguageModelV4ToolResultOutput,
+  LanguageModelV4ToolResultPart,
+} from '@ai-sdk/provider';
+import type { HarnessV1Metadata } from './harness-v1-metadata';
+
+type LanguageModelV4ToolResultContentPart = Extract<
+  LanguageModelV4ToolResultOutput,
+  { type: 'content' }
+>['value'][number];
+
+export type HarnessV1TextPart = Omit<
+  LanguageModelV4TextPart,
+  'providerOptions'
+>;
+
+export type HarnessV1FilePart = Omit<
+  LanguageModelV4FilePart,
+  'providerOptions'
+>;
+
+export type HarnessV1CustomPart = Omit<
+  LanguageModelV4CustomPart,
+  'providerOptions'
+>;
+
+export type HarnessV1ReasoningPart = Omit<
+  LanguageModelV4ReasoningPart,
+  'providerOptions'
+>;
+
+export type HarnessV1ReasoningFilePart = Omit<
+  LanguageModelV4ReasoningFilePart,
+  'providerOptions'
+>;
+
+export type HarnessV1ToolCallPart = Omit<
+  LanguageModelV4ToolCallPart,
+  'providerOptions'
+> & {
+  nativeName?: string;
+};
+
+export type HarnessV1ToolResultOutput =
+  | Omit<
+      Extract<LanguageModelV4ToolResultOutput, { type: 'text' }>,
+      'providerOptions'
+    >
+  | Omit<
+      Extract<LanguageModelV4ToolResultOutput, { type: 'json' }>,
+      'providerOptions'
+    >
+  | Omit<
+      Extract<LanguageModelV4ToolResultOutput, { type: 'execution-denied' }>,
+      'providerOptions'
+    >
+  | Omit<
+      Extract<LanguageModelV4ToolResultOutput, { type: 'error-text' }>,
+      'providerOptions'
+    >
+  | Omit<
+      Extract<LanguageModelV4ToolResultOutput, { type: 'error-json' }>,
+      'providerOptions'
+    >
+  | {
+      type: 'content';
+      value: Array<
+        | Omit<
+            Extract<LanguageModelV4ToolResultContentPart, { type: 'text' }>,
+            'providerOptions'
+          >
+        | Omit<
+            Extract<LanguageModelV4ToolResultContentPart, { type: 'file' }>,
+            'providerOptions'
+          >
+        | Omit<
+            Extract<LanguageModelV4ToolResultContentPart, { type: 'custom' }>,
+            'providerOptions'
+          >
+      >;
+    };
+
+export type HarnessV1ToolResultPart = Omit<
+  LanguageModelV4ToolResultPart,
+  'output' | 'providerOptions'
+> & {
+  output: HarnessV1ToolResultOutput;
+};
+
+export type HarnessV1ToolApprovalResponsePart = Omit<
+  LanguageModelV4ToolApprovalResponsePart,
+  'providerOptions'
+>;
+
+export type HarnessV1MessagePart =
+  | HarnessV1TextPart
+  | HarnessV1FilePart
+  | HarnessV1CustomPart
+  | HarnessV1ReasoningPart
+  | HarnessV1ReasoningFilePart
+  | HarnessV1ToolCallPart
+  | HarnessV1ToolResultPart
+  | HarnessV1ToolApprovalResponsePart;
+
+export type HarnessV1UserMessage = {
+  readonly role: 'user';
+  readonly content: Array<HarnessV1TextPart | HarnessV1FilePart>;
+  readonly at?: string;
+  readonly harnessMetadata?: HarnessV1Metadata;
+};
+
+export type HarnessV1AssistantMessage = {
+  readonly role: 'assistant';
+  readonly content: Array<
+    | HarnessV1TextPart
+    | HarnessV1FilePart
+    | HarnessV1CustomPart
+    | HarnessV1ReasoningPart
+    | HarnessV1ReasoningFilePart
+    | HarnessV1ToolCallPart
+    | HarnessV1ToolResultPart
+  >;
+  readonly at?: string;
+  readonly harnessMetadata?: HarnessV1Metadata;
+};
+
+export type HarnessV1ToolMessage = {
+  readonly role: 'tool';
+  readonly content: Array<
+    HarnessV1ToolResultPart | HarnessV1ToolApprovalResponsePart
+  >;
+  readonly at?: string;
+  readonly harnessMetadata?: HarnessV1Metadata;
+};
+
+/**
+ * A persisted harness message using V4 prompt content shapes and metadata
+ * scoped to the adapter that produced it.
+ */
+export type HarnessV1Message =
+  | HarnessV1UserMessage
+  | HarnessV1AssistantMessage
+  | HarnessV1ToolMessage;

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

@@ -11,6 +11,7 @@ import type {
   HarnessV1TurnSettings,
 } from './harness-v1-lifecycle-state';
 import type { HarnessV1StreamPart } from './harness-v1-stream-part';
+import type { HarnessV1Message } from './harness-v1-message';
 import type { HarnessV1BuiltinToolFiltering } from './harness-v1-tool-filtering';
 
 /**
@@ -90,6 +91,15 @@ export type HarnessV1StartOptions = {
   readonly sessionWorkDir: string;
 };
 
+/**
+ * Result of `HarnessV1Session.doReadHistory`.
+ */
+export type HarnessV1ReadHistoryResult = {
+  readonly messages: ReadonlyArray<HarnessV1Message>;
+  /** Opaque position; pass back as `since` to read only what follows. */
+  readonly cursor: string;
+};
+
 /**
  * Options passed to `HarnessV1Session.doPromptTurn`.
  */
@@ -192,6 +202,34 @@ export type HarnessV1Session = {
    */
   doCompact(customInstructions?: string): PromiseLike<void>;
 
+  /**
+   * Read the conversation history the runtime itself persisted, normalized
+   * to `HarnessV1Message`.
+   *
+   * The session's history can grow outside the harness contract: the same
+   * runtime conversation may be continued interactively (`claude --resume`),
+   * by another process, or before this session attached. Hosts that render a
+   * continuous record of the conversation — not just the turns they drove —
+   * need to read that history back, and the runtime's own store is the only
+   * source that has it. The adapter owns its runtime's persistence format,
+   * so the read belongs here rather than in every host.
+   *
+   * `since` is the `cursor` from a previous read; the result then contains
+   * only messages recorded after it. The cursor is adapter-owned and opaque
+   * to the host.
+   *
+   * Optional capability: adapters that cannot read their runtime's store
+   * omit the method entirely, and the agent surfaces that as
+   * `HarnessCapabilityUnsupportedError`. An adapter that implements it but
+   * cannot reach the store from the current environment (e.g. it lives
+   * inside a remote sandbox) throws `HarnessHistoryUnavailableError`. A
+   * conversation with no recorded messages yet is not an error — it resolves
+   * to an empty `messages` array.
+   */
+  doReadHistory?(options: {
+    readonly since?: string;
+  }): PromiseLike<HarnessV1ReadHistoryResult>;
+
   /**
    * Continue the in-flight turn **without a new user prompt**, returning the
    * same control surface as `doPromptTurn`. Used to keep consuming a turn that

package/src/v1/index.ts

@@ -13,9 +13,26 @@ export type {
 export type {
   HarnessV1ContinueTurnOptions,
   HarnessV1PromptTurnOptions,
+  HarnessV1ReadHistoryResult,
   HarnessV1Session,
   HarnessV1StartOptions,
 } from './harness-v1-session';
+export type {
+  HarnessV1AssistantMessage,
+  HarnessV1CustomPart,
+  HarnessV1FilePart,
+  HarnessV1Message,
+  HarnessV1MessagePart,
+  HarnessV1ReasoningFilePart,
+  HarnessV1ReasoningPart,
+  HarnessV1TextPart,
+  HarnessV1ToolApprovalResponsePart,
+  HarnessV1ToolCallPart,
+  HarnessV1ToolMessage,
+  HarnessV1ToolResultOutput,
+  HarnessV1ToolResultPart,
+  HarnessV1UserMessage,
+} from './harness-v1-message';
 export type { HarnessV1Observability } from './harness-v1-observability';
 export type { HarnessV1PromptControl } from './harness-v1-prompt-control';
 export type { HarnessV1CallWarning } from './harness-v1-call-warning';