@ai-sdk/harness 1.0.122 → 1.0.123

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

@@ -1,7 +1,7 @@
 /**
  * One file to write into the sandbox as part of an adapter's bootstrap recipe.
  * Absolute paths are used as-is. Relative paths are resolved against the
- * sandbox's default working directory. Paths should live under
+ * harness state directory (`$HOME/.ai-sdk-harness`). Paths should live under
  * {@link HarnessV1Bootstrap.bootstrapDir}.
  */
 export interface HarnessV1BootstrapFile {
@@ -33,10 +33,10 @@ export interface HarnessV1Bootstrap {
 
   /**
    * Path inside the sandbox where this recipe writes its state. Absolute paths
-   * are used as-is. Relative paths are resolved against the sandbox's default
-   * working directory. The marker file lives directly under it. Files
-   * declared in {@link files} should also use this prefix so an adapter upgrade
-   * can sweep stale state by clearing the directory.
+   * are used as-is. Relative paths are resolved against the harness state
+   * directory (`$HOME/.ai-sdk-harness`). The marker file lives directly under
+   * it. Files declared in {@link files} should also use this prefix so an
+   * adapter upgrade can sweep stale state by clearing the directory.
    */
   readonly bootstrapDir: string;
 

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

@@ -1,3 +1,4 @@
+import { posix } from 'node:path';
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
 
 /**
@@ -9,6 +10,29 @@ export type HarnessV1PortEndpoint = {
   readonly headers?: Readonly<Record<string, string>>;
 };
 
+/**
+ * Fixed directory, relative to the sandbox's own HOME, that holds every
+ * piece of state the harness machinery generates.
+ */
+const HARNESS_V1_STATE_DIRECTORY_NAME = '.ai-sdk-harness';
+
+/**
+ * Fixed, non-configurable path for harness-generated state (bootstrap files,
+ * markers, and `.agent-runs`) under the sandbox's own HOME, never under
+ * {@link HarnessV1NetworkSandboxSession.defaultWorkingDirectory}. Resolve HOME
+ * with `resolveSandboxHomeDir` when it is not already known. This works from
+ * provider creation hooks that only have a plain sandbox session. The
+ * framework also calls this with a symbolic `$HOME` when hashing bootstrap
+ * recipes, so changes to the state path invalidate existing templates.
+ */
+export function harnessStateDirectoryPath({
+  sandboxHomeDir,
+}: {
+  sandboxHomeDir: string;
+}): string {
+  return posix.join(sandboxHomeDir, HARNESS_V1_STATE_DIRECTORY_NAME);
+}
+
 /**
  * Network sandbox session returned by `HarnessV1SandboxProvider.createSession()`. The
  * harness keeps this for the lifetime of a session. It is itself a

package/src/v1/index.ts

@@ -63,6 +63,8 @@ export type {
   HarnessV1RequestTransformation,
   HarnessV1RequestTransformationSources,
 } from './harness-v1-network-sandbox-session';
+export { harnessStateDirectoryPath } from './harness-v1-network-sandbox-session';
+export { harnessSessionDataDirectoryPath } from './harness-session-data-directory-path';
 export type { HarnessV1Skill } from './harness-v1-skill';
 export type { HarnessV1StreamPart } from './harness-v1-stream-part';
 export {