@ai-sdk/harness 1.0.53 → 1.0.55

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @ai-sdk/harness
 
+## 1.0.55
+
+### Patch Changes
+
+- 2c0a8aa: fix(harness): remove unused and unnecessary `workingDirectory` property from `HarnessV1BootstrapCommand`
+- 861d423: feat(harness): improve harness sandbox auth error handling and expose `getHarnessErrorMessage()` helper
+- 8f10600: fix(harness): rename harness bridge `detach` to `stop` and `shutdown` to `destroy` for clarity
+  - ai@7.0.49
+
+## 1.0.54
+
+### Patch Changes
+
+- ai@7.0.48
+
 ## 1.0.53
 
 ### Patch Changes

package/README.md

@@ -114,9 +114,7 @@ Implement the `HarnessV1` factory and a `HarnessV1Session` whose `doPromptTurn`
 Bootstrap recipe paths may be absolute or relative. Relative `bootstrapDir` and
 file paths are resolved against `sandboxSession.defaultWorkingDirectory`.
 The framework creates `bootstrapDir` before writing files, and bootstrap
-commands run from that directory by default. A relative command
-`workingDirectory` override is resolved against the sandbox's default working
-directory. Prefer a relative directory such as
+commands always run from that directory. Prefer a relative directory such as
 `.harness-bootstrap/my-harness` so bootstrap assets are kept with the sandbox's
 snapshot-persistent working tree.
 

package/agent/index.ts

@@ -52,6 +52,8 @@ export type {
 } from '../src/agent/observability/types';
 export { HarnessError } from '../src/errors/harness-error';
 export { HarnessCapabilityUnsupportedError } from '../src/errors/harness-capability-unsupported-error';
+export { HarnessSandboxAuthenticationError } from '../src/errors/harness-sandbox-authentication-error';
+export { getHarnessErrorMessage } from '../src/agent/get-harness-error-message';
 export {
   createFileReporter,
   createTraceTreeReporter,

package/dist/agent/index.d.ts

@@ -90,12 +90,6 @@ interface HarnessV1BootstrapFile {
  */
 interface HarnessV1BootstrapCommand {
     readonly command: string;
-    /**
-     * Absolute working directories are used as-is. Relative working directories
-     * are resolved against the sandbox's default working directory. When
-     * omitted, the command runs from the recipe's bootstrap directory.
-     */
-    readonly workingDirectory?: string;
 }
 /**
  * Adapter-owned bootstrap recipe. The adapter declares the files and commands
@@ -1010,6 +1004,12 @@ interface HarnessV1SandboxProvider {
      * leave this undefined.
      */
     readonly bridgePorts?: ReadonlyArray<number>;
+    /**
+     * Providers should throw `HarnessSandboxAuthenticationError` when sandbox
+     * acquisition fails because credentials are missing, invalid, or not
+     * authorized. This lets framework integrations distinguish configuration
+     * failures from general sandbox infrastructure errors.
+     */
     readonly createSession: (options?: {
         /**
          * Stable per-session identifier. When supplied, the provider names the
@@ -1608,14 +1608,14 @@ declare function prepareSandboxForHarness(options: {
     readonly abortSignal?: AbortSignal;
 }): Promise<PrepareSandboxForHarnessResult>;
 
-declare const symbol$1: unique symbol;
+declare const symbol$2: unique symbol;
 /**
  * Base error type for failures originating in or signalled by a harness
  * adapter. Specific failure modes (e.g. unsupported capability) extend this
  * class.
  */
 declare class HarnessError extends AISDKError {
-    private readonly [symbol$1];
+    private readonly [symbol$2];
     constructor({ message, cause }: {
         message: string;
         cause?: unknown;
@@ -1623,7 +1623,7 @@ declare class HarnessError extends AISDKError {
     static isInstance(error: unknown): error is HarnessError;
 }
 
-declare const symbol: unique symbol;
+declare const symbol$1: unique symbol;
 /**
  * Thrown when a caller asks the harness to do something the adapter (or the
  * supplied sandbox) does not support, e.g. requesting manual compaction from
@@ -1634,7 +1634,7 @@ declare const symbol: unique symbol;
  * is recorded as structured context for tooling.
  */
 declare class HarnessCapabilityUnsupportedError extends HarnessError {
-    private readonly [symbol];
+    private readonly [symbol$1];
     readonly harnessId?: string;
     constructor({ message, harnessId, cause, }: {
         message: string;
@@ -1644,6 +1644,32 @@ declare class HarnessCapabilityUnsupportedError extends HarnessError {
     static isInstance(error: unknown): error is HarnessCapabilityUnsupportedError;
 }
 
+declare const symbol: unique symbol;
+/**
+ * Thrown when a sandbox provider cannot authenticate or authorize the
+ * operation needed to create or resume a harness sandbox. Providers should
+ * preserve the underlying SDK failure as `cause` and supply a message that
+ * explains how the consumer can configure credentials.
+ */
+declare class HarnessSandboxAuthenticationError extends HarnessError {
+    private readonly [symbol];
+    readonly sandboxProviderId: string;
+    constructor({ message, sandboxProviderId, cause, }: {
+        message: string;
+        sandboxProviderId: string;
+        cause?: unknown;
+    });
+    static isInstance(error: unknown): error is HarnessSandboxAuthenticationError;
+}
+
+/**
+ * Returns a client-safe message for errors produced by the harness runtime.
+ * Messages from explicitly reviewed harness error types are preserved. All
+ * other errors are masked so provider, sandbox, and server details are not
+ * exposed to clients by default.
+ */
+declare function getHarnessErrorMessage(error: unknown): string;
+
 /**
  * A harness observability reporter that writes a unified, non-lossy
  * `events.jsonl` containing **both** the telemetry span lifecycle (turn / step
@@ -1683,4 +1709,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, type PrepareSandboxForHarnessResult, type TraceTreeReporterOptions, collectHarnessAgentToolApprovalContinuations, collectHarnessAgentToolResultContinuations, createFileReporter, createTraceTreeReporter, 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 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 };