@ai-sdk/harness 1.0.132 → 1.0.133

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ai-sdk/harness
 
+## 1.0.133
+
+### Patch Changes
+
+- b2049fa: fix(harness): expose `resolveSandboxCredentialEnvironment()` helper in favor of `createSandboxCredentialEnvironment()` and use it across bridge backed adapters
+- 11f0e71: feat (harness): add `HarnessAgentSession.readHistory({ since })` contract to return normalized session history, to implement per individual harness adapter
+- 2b9195b: fix(harness): emit tool lifecycle events and results as each tool runs
+- 446725d: fix(harness): surface detach failures and keep session handles usable
+  - ai@7.0.122
+
 ## 1.0.132
 
 ### Patch Changes

package/dist/agent/index.d.ts

@@ -3,7 +3,7 @@ import { Experimental_SandboxSession, UserModelMessage, ToolResultPart, Provider
 import { ToolsContextSettings } from 'ai/internal';
 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';
+import { JSONSchema7, JSONValue, LanguageModelV4StreamPart, LanguageModelV4ToolCall, LanguageModelV4ToolApprovalRequest, LanguageModelV4ToolResult, LanguageModelV4FinishReason, LanguageModelV4Usage, LanguageModelV4TextPart, LanguageModelV4FilePart, LanguageModelV4CustomPart, LanguageModelV4ReasoningPart, LanguageModelV4ReasoningFilePart, LanguageModelV4ToolCallPart, LanguageModelV4ToolResultPart, LanguageModelV4ToolResultOutput, LanguageModelV4ToolApprovalResponsePart, AISDKError } from '@ai-sdk/provider';
 
 /**
  * One file to write into the sandbox as part of an adapter's bootstrap recipe.
@@ -681,6 +681,65 @@ type HarnessV1StreamPart = {
     rawValue: unknown;
 };
 
+type LanguageModelV4ToolResultContentPart = Extract<LanguageModelV4ToolResultOutput, {
+    type: 'content';
+}>['value'][number];
+type HarnessV1TextPart = Omit<LanguageModelV4TextPart, 'providerOptions'>;
+type HarnessV1FilePart = Omit<LanguageModelV4FilePart, 'providerOptions'>;
+type HarnessV1CustomPart = Omit<LanguageModelV4CustomPart, 'providerOptions'>;
+type HarnessV1ReasoningPart = Omit<LanguageModelV4ReasoningPart, 'providerOptions'>;
+type HarnessV1ReasoningFilePart = Omit<LanguageModelV4ReasoningFilePart, 'providerOptions'>;
+type HarnessV1ToolCallPart = Omit<LanguageModelV4ToolCallPart, 'providerOptions'> & {
+    nativeName?: string;
+};
+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'>>;
+};
+type HarnessV1ToolResultPart = Omit<LanguageModelV4ToolResultPart, 'output' | 'providerOptions'> & {
+    output: HarnessV1ToolResultOutput;
+};
+type HarnessV1ToolApprovalResponsePart = Omit<LanguageModelV4ToolApprovalResponsePart, 'providerOptions'>;
+type HarnessV1UserMessage = {
+    readonly role: 'user';
+    readonly content: Array<HarnessV1TextPart | HarnessV1FilePart>;
+    readonly at?: string;
+    readonly harnessMetadata?: HarnessV1Metadata;
+};
+type HarnessV1AssistantMessage = {
+    readonly role: 'assistant';
+    readonly content: Array<HarnessV1TextPart | HarnessV1FilePart | HarnessV1CustomPart | HarnessV1ReasoningPart | HarnessV1ReasoningFilePart | HarnessV1ToolCallPart | HarnessV1ToolResultPart>;
+    readonly at?: string;
+    readonly harnessMetadata?: HarnessV1Metadata;
+};
+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.
+ */
+type HarnessV1Message = HarnessV1UserMessage | HarnessV1AssistantMessage | HarnessV1ToolMessage;
+
 type HarnessV1BuiltinToolFiltering = {
     mode: 'allow';
     toolNames: string[];
@@ -757,6 +816,14 @@ type HarnessV1StartOptions = {
      */
     readonly sessionWorkDir: string;
 };
+/**
+ * Result of `HarnessV1Session.doReadHistory`.
+ */
+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`.
  */
@@ -846,6 +913,33 @@ type HarnessV1Session = {
      * `customInstructions`, when supported, steer the compaction summary.
      */
     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
@@ -1639,6 +1733,24 @@ declare class HarnessAgentSession {
      * unusable.
      */
     detach(): Promise<HarnessAgentResumeSessionState>;
+    /**
+     * 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.
+     */
+    readHistory(options?: {
+        since?: string;
+    }): Promise<HarnessV1ReadHistoryResult>;
     /**
      * Persist enough state to resume later, then stop the runtime and any
      * harness-owned sandbox.

package/dist/agent/index.js

@@ -1753,17 +1753,25 @@ function runPrompt(input) {
     let stepApprovalRequests = [];
     let bufferedToolOutcomes = [];
     const toolExecutions = /* @__PURE__ */ new Map();
+    const publishToolExecutionStart = async (execution) => {
+      execution.startNotification ??= lifecycle.toolExecutionStart({
+        toolCall: execution.toolCall
+      });
+      await execution.startNotification;
+    };
+    const publishToolExecutionEnd = async (execution) => {
+      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 () => {
       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();
@@ -2048,6 +2056,9 @@ function runPrompt(input) {
       toolExecutions.set(rawToolCall.toolCallId, {
         toolCall
       });
+      await publishToolExecutionStart(
+        toolExecutions.get(rawToolCall.toolCallId)
+      );
       const executionStartedAt = Date.now();
       const execution = await maybeExecuteHostTool({
         event: rawToolCall,
@@ -2068,15 +2079,13 @@ function runPrompt(input) {
             },
             input.sessionWorkDir
           );
-          bufferedToolOutcomes.push(() => {
-            result.enqueue({
-              type: "tool-result",
-              toolCallId: rawToolCall.toolCallId,
-              toolName: rawToolCall.toolName,
-              input: void 0,
-              output: stripped.result,
-              preliminary: true
-            });
+          result.enqueue({
+            type: "tool-result",
+            toolCallId: rawToolCall.toolCallId,
+            toolName: rawToolCall.toolName,
+            input: void 0,
+            output: stripped.result,
+            preliminary: true
           });
         }
       });
@@ -2091,13 +2100,11 @@ function runPrompt(input) {
         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";
     };
     try {
@@ -2239,11 +2246,7 @@ function runPrompt(input) {
           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);
         }
         let validatedHostToolCall;
@@ -2277,9 +2280,13 @@ function runPrompt(input) {
           const toolCall = toolCallsByToolCallId.get(value.toolCallId);
           if (toolCall != null) {
             stepToolCalls.push(toolCall);
-            toolExecutions.set(value.toolCallId, {
+            const execution = {
               toolCall
-            });
+            };
+            toolExecutions.set(value.toolCallId, execution);
+            if (value.providerExecuted === true) {
+              await publishToolExecutionStart(execution);
+            }
           }
         }
         if (value.type === "tool-result") {
@@ -2295,11 +2302,18 @@ function runPrompt(input) {
               output: value.result
             };
           }
+          if (execution?.toolExecutionMs == null && execution?.executionStartedAt != null) {
+            execution.toolExecutionMs = Date.now() - execution.executionStartedAt;
+          }
           if (rawToolCallsByToolCallId.get(value.toolCallId)?.providerExecuted === true && execution?.toolOutput != null) {
             stepProviderToolResults.push(
               execution.toolOutput
             );
           }
+          if (execution != null) {
+            await publishToolExecutionEnd(execution);
+          }
+          for (const part of translatedParts) result.enqueue(part);
         }
         if (value.type === "tool-approval-request") {
           const toolCall = toolCallsByToolCallId.get(value.toolCallId);
@@ -2457,16 +2471,20 @@ function runPrompt(input) {
               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;
           }
@@ -2531,7 +2549,15 @@ function runPrompt(input) {
           }
           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,
@@ -2551,15 +2577,13 @@ function runPrompt(input) {
                     },
                     input.sessionWorkDir
                   );
-                  bufferedToolOutcomes.push(() => {
-                    result.enqueue({
-                      type: "tool-result",
-                      toolCallId: toolCall.toolCallId,
-                      toolName: toolCall.toolName,
-                      input: void 0,
-                      output: stripped.result,
-                      preliminary: true
-                    });
+                  result.enqueue({
+                    type: "tool-result",
+                    toolCallId: toolCall.toolCallId,
+                    toolName: toolCall.toolName,
+                    input: void 0,
+                    output: stripped.result,
+                    preliminary: true
                   });
                 }
               });
@@ -2568,14 +2592,12 @@ function runPrompt(input) {
                   `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);
             })()
           );
         }
@@ -3023,22 +3045,47 @@ var HarnessAgentSession = class {
       );
     }
     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) {
+    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 } : {}
+    });
   }
   /**
    * Persist enough state to resume later, then stop the runtime and any