@ai-sdk/harness 1.0.122 → 1.0.124

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

@@ -1,7 +1,9 @@
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import { harnessStateDirectoryPath } from '../v1';
 import type { HarnessAgentSandboxConfig } from './harness-agent-settings';
 import type { HarnessAgentAdapter } from './harness-agent-types';
 import { resolveSandboxDefaultWorkingDirectory } from '../utils/resolve-sandbox-default-working-directory';
+import { resolveSandboxHomeDir } from '../utils/sandbox-home-dir';
 import {
   applyBootstrapRecipe,
   hashHarnessBootstrap,
@@ -67,7 +69,7 @@ export async function prepareSandboxForHarness(options: {
       : normalizeSandboxWorkDir(sandboxConfig.workDir);
   const recipeIdentities: Record<string, string> = {};
   const skippedHarnessIds: string[] = [];
-  let defaultWorkingDirectory: string | undefined;
+  let stateDirectory: string | undefined;
 
   for (const harness of harnesses) {
     const recipe = await harness.getBootstrap?.({
@@ -80,20 +82,27 @@ export async function prepareSandboxForHarness(options: {
 
     const recipeIdentity = await hashHarnessBootstrap(recipe);
     recipeIdentities[harness.harnessId] = recipeIdentity;
-    defaultWorkingDirectory ??= await resolveSandboxDefaultWorkingDirectory({
-      sandboxSession: options.session,
-      abortSignal: options.abortSignal,
+    // Harness infrastructure always lives under the sandbox's own HOME,
+    // never the working directory.
+    stateDirectory ??= harnessStateDirectoryPath({
+      sandboxHomeDir: await resolveSandboxHomeDir({
+        sandbox: options.session,
+        abortSignal: options.abortSignal,
+      }),
     });
     await applyBootstrapRecipe({
       session: options.session,
       recipe,
       identity: recipeIdentity,
-      defaultWorkingDirectory,
+      stateDirectory,
       abortSignal: options.abortSignal,
     });
   }
 
   if (sandboxConfig.onBootstrap != null) {
+    const defaultWorkingDirectory = await resolveSandboxDefaultWorkingDirectory(
+      { sandboxSession: options.session, abortSignal: options.abortSignal },
+    );
     await runSandboxBootstrap({
       session: options.session,
       workDir,

package/src/bridge/index.ts

@@ -934,7 +934,6 @@ export async function runBridge<TStart extends { type: 'start' }>(
         const data = (await onStop?.()) ?? {};
         sendControl(ws, { type: 'bridge-stop', data });
         drainThenExit(ws, 1000, 'stop');
-        return;
       }
     }
   };

package/src/utils/sandbox-channel.ts

@@ -83,6 +83,11 @@ type Listener<TOut extends { type: string }, T extends EventTypeOf<TOut>> = (
   event: Extract<TOut, { type: T }>,
 ) => void;
 
+type BufferedEvent<TOut extends { type: string }> = {
+  message: TOut;
+  listeners?: ReadonlyArray<Listener<TOut, EventTypeOf<TOut>>>;
+};
+
 /*
  * The agent and utilities entrypoints bundle this module separately. A global
  * symbol lets the agent recognize metadata attached by the channel's bundle
@@ -172,11 +177,18 @@ async function awaitWebSocketConnection({
 /**
  * Host-side typed wrapper around the bridge WebSocket connection.
  *
- * Buffers inbound messages until a listener for their type is registered, so
- * callers that subscribe asynchronously do not miss early frames. Inbound
- * dispatch is serialised through a promise chain so a `close` event that
- * arrives on the same microtask as the final `finish` message does not fire
- * close handlers until the message has been dispatched.
+ * Buffers inbound messages in arrival order while listeners attach, so callers
+ * do not miss or reorder early frames. Listener registration drains the
+ * ordered prefix synchronously. Selective listeners are given through the
+ * current task (including its microtasks) to attach before unhandled event
+ * types are retained independently, so they cannot block subscribed event
+ * types indefinitely. A listener that claims an already-buffered event still
+ * receives it if it unsubscribes before that ordered drain completes. Use
+ * {@link SandboxChannel.beginListenerAttachment} to define an explicit
+ * attachment boundary that spans asynchronous work. Inbound dispatch is
+ * serialised through a promise chain so a `close` event that arrives on the
+ * same microtask as the final `finish` message does not fire close handlers
+ * until the message has been dispatched.
  *
  * Survives transient disconnects. The bridge keeps running and
  * accumulates events in an in-memory log keyed by a monotonic `seq`; on an
@@ -193,7 +205,12 @@ export class SandboxChannel<
     EventTypeOf<TOut>,
     Set<Listener<TOut, EventTypeOf<TOut>>>
   >();
-  private readonly buffered = new Map<EventTypeOf<TOut>, TOut[]>();
+  private readonly buffered: BufferedEvent<TOut>[] = [];
+  private readonly bufferedByType = new Map<EventTypeOf<TOut>, TOut[]>();
+  private bufferedOffset = 0;
+  private flushingBuffered = false;
+  private bufferedFlushScheduled = false;
+  private listenerAttachmentDepth = 0;
   private readonly onCloseHandlers = new Set<
     (code: number, reason: string) => void
   >();
@@ -309,19 +326,46 @@ export class SandboxChannel<
     }
     set.add(listener as unknown as Listener<TOut, EventTypeOf<TOut>>);
 
-    const buffered = this.buffered.get(type);
-    if (buffered) {
-      this.buffered.delete(type);
-      for (const event of buffered) {
-        listener(event as Extract<TOut, { type: T }>);
-      }
+    this.captureBufferedListeners(type);
+    if (this.listenerAttachmentDepth > 0) {
+      return () => {
+        set!.delete(listener as unknown as Listener<TOut, EventTypeOf<TOut>>);
+      };
     }
 
+    this.flushBufferedType(type);
+    this.flushBuffered();
+    this.scheduleSelectiveBufferedFlush();
+
     return () => {
       set!.delete(listener as unknown as Listener<TOut, EventTypeOf<TOut>>);
     };
   }
 
+  /**
+   * Hold buffered event delivery while a consumer attaches a related set of
+   * listeners, including across asynchronous boundaries. Call the returned
+   * function once registration is complete. Buffered events are then replayed
+   * in arrival order; event types that remain unhandled are retained
+   * independently so they do not block subscribed types.
+   */
+  beginListenerAttachment(): () => void {
+    this.listenerAttachmentDepth++;
+    let finished = false;
+    return () => {
+      if (finished) return;
+      finished = true;
+      this.listenerAttachmentDepth--;
+      if (this.listenerAttachmentDepth > 0) return;
+
+      for (const type of this.listeners.keys()) {
+        this.flushBufferedType(type);
+      }
+      this.flushBuffered();
+      this.scheduleSelectiveBufferedFlush();
+    };
+  }
+
   onClose(handler: (code: number, reason: string) => void): void {
     this.onCloseHandlers.add(handler);
   }
@@ -645,13 +689,18 @@ export class SandboxChannel<
     }
     const type = message.type as EventTypeOf<TOut>;
     const set = this.listeners.get(type);
-    if (!set || set.size === 0) {
-      let bucket = this.buffered.get(type);
-      if (!bucket) {
-        bucket = [];
-        this.buffered.set(type, bucket);
-      }
-      bucket.push(message);
+    if (
+      this.listenerAttachmentDepth > 0 ||
+      this.bufferedOffset < this.buffered.length ||
+      !set ||
+      set.size === 0
+    ) {
+      this.buffered.push({
+        message,
+        ...(set != null && set.size > 0 ? { listeners: Array.from(set) } : {}),
+      });
+      this.flushBuffered();
+      this.scheduleSelectiveBufferedFlush();
       return;
     }
     for (const listener of set) {
@@ -659,6 +708,110 @@ export class SandboxChannel<
     }
   }
 
+  private flushBuffered({
+    selective = false,
+  }: { selective?: boolean } = {}): void {
+    if (this.flushingBuffered || this.listenerAttachmentDepth > 0) return;
+    this.flushingBuffered = true;
+    try {
+      while (this.bufferedOffset < this.buffered.length) {
+        const bufferedEvent = this.buffered[this.bufferedOffset];
+        const message = bufferedEvent.message;
+        const type = message.type as EventTypeOf<TOut>;
+        const set = this.listeners.get(type);
+        const listeners =
+          bufferedEvent.listeners ??
+          (set != null && set.size > 0 ? Array.from(set) : undefined);
+        if (!listeners || listeners.length === 0) {
+          if (!selective) return;
+          this.bufferedOffset++;
+          const buffered = this.bufferedByType.get(type);
+          if (buffered) {
+            buffered.push(message);
+          } else {
+            this.bufferedByType.set(type, [message]);
+          }
+          continue;
+        }
+
+        this.bufferedOffset++;
+        for (const listener of listeners) {
+          listener(message as Extract<TOut, { type: EventTypeOf<TOut> }>);
+        }
+      }
+    } finally {
+      if (this.bufferedOffset > 0) {
+        this.buffered.splice(0, this.bufferedOffset);
+        this.bufferedOffset = 0;
+      }
+      this.flushingBuffered = false;
+    }
+  }
+
+  private captureBufferedListeners(type: EventTypeOf<TOut>): void {
+    const set = this.listeners.get(type);
+    if (!set || set.size === 0) return;
+
+    for (let i = this.bufferedOffset; i < this.buffered.length; i++) {
+      const bufferedEvent = this.buffered[i];
+      if (
+        bufferedEvent.listeners == null &&
+        bufferedEvent.message.type === type
+      ) {
+        bufferedEvent.listeners = Array.from(set);
+      }
+    }
+  }
+
+  private flushBufferedType(type: EventTypeOf<TOut>): void {
+    const buffered = this.bufferedByType.get(type);
+    if (!buffered) return;
+
+    let offset = 0;
+    try {
+      while (offset < buffered.length) {
+        const set = this.listeners.get(type);
+        if (!set || set.size === 0) return;
+
+        const message = buffered[offset++];
+        for (const listener of set) {
+          listener(message as Extract<TOut, { type: EventTypeOf<TOut> }>);
+        }
+      }
+    } finally {
+      if (offset === buffered.length) {
+        this.bufferedByType.delete(type);
+      } else if (offset > 0) {
+        buffered.splice(0, offset);
+      }
+    }
+  }
+
+  private scheduleSelectiveBufferedFlush(): void {
+    if (
+      this.bufferedFlushScheduled ||
+      this.bufferedOffset >= this.buffered.length ||
+      !this.hasListeners() ||
+      this.listenerAttachmentDepth > 0
+    ) {
+      return;
+    }
+
+    this.bufferedFlushScheduled = true;
+    setTimeout(() => {
+      this.bufferedFlushScheduled = false;
+      if (this.listenerAttachmentDepth > 0) return;
+      this.flushBuffered({ selective: true });
+    }, 0);
+  }
+
+  private hasListeners(): boolean {
+    for (const listeners of this.listeners.values()) {
+      if (listeners.size > 0) return true;
+    }
+    return false;
+  }
+
   private attachEventCheckpoint(options: {
     event: TOut;
     eventId: number;

package/src/utils/write-instructions.ts

@@ -207,7 +207,7 @@ function resolveInstructionsFilePath({
     );
   }
   const containsTraversal = instructionsFile
-    .split(/[\\\/]/)
+    .split(/[\\/]/)
     .some(segment => segment === '..');
   const normalizedInstructionsFile = path.posix.normalize(
     instructionsFile.trim(),

package/src/utils/write-skills.ts

@@ -551,7 +551,7 @@ function resolveSkillsRootDir({
     );
   }
   const containsTraversal = skillsDir
-    .split(/[\\\/]/)
+    .split(/[\\/]/)
     .some(segment => segment === '..');
   const normalizedSkillsDir = path.posix.normalize(skillsDir.trim());
   const normalizedNoTrailingSlash = normalizedSkillsDir.replace(/\/+$/, '');

package/src/v1/harness-session-data-directory-path.ts

@@ -0,0 +1,28 @@
+import { posix } from 'node:path';
+
+export function encodeHarnessPathSegment(value: string): string {
+  const encoded = encodeURIComponent(value);
+  if (encoded === '') return '%';
+  if (encoded === '.') return '%2E';
+  if (encoded === '..') return '%2E%2E';
+  return encoded;
+}
+
+/**
+ * Return the per-session harness state path under `.agent-runs`. Session IDs
+ * occupy one encoded path segment, so path separators and parent-directory
+ * references cannot move session data outside the harness state directory.
+ */
+export function harnessSessionDataDirectoryPath({
+  stateDirectory,
+  sessionId,
+}: {
+  stateDirectory: string;
+  sessionId: string;
+}): string {
+  return posix.join(
+    stateDirectory,
+    '.agent-runs',
+    encodeHarnessPathSegment(sessionId),
+  );
+}

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 {