@ai-sdk/harness 1.0.92 → 1.0.93

package/src/bridge/index.ts

@@ -293,8 +293,27 @@ export interface RunBridgeOptions<TStart extends { type: 'start' }> {
   bridgeType: string;
   /** Directory for `bridge-meta.json` / `start-config.json`. Created if absent. */
   bridgeStateDir: string;
-  /** Drive one prompt turn. Rejections surface to the host as an `error` event. */
+  /**
+   * Drive one prompt turn. Rejections surface to the host as an `error`
+   * event.
+   *
+   * Contract: once `turn.abortSignal` fires, wind down promptly — turns are
+   * serialized, and a replacement `start` waits up to
+   * {@link turnTeardownGraceMs} for this promise to settle before it
+   * proceeds anyway.
+   */
   onStart(start: TStart, turn: BridgeTurn): Promise<void>;
+  /**
+   * How long a replacement `start` waits for the previous turn's teardown
+   * after aborting it, in milliseconds. Turns are serialized so an aborted
+   * turn cannot emit into its replacement's event log or overlap its runtime
+   * process — but only within this bound: an adapter that does not settle
+   * `onStart` after its abort signal fires forfeits the protection for that
+   * boundary, and the new turn proceeds anyway rather than blocking forever.
+   * The default of ten seconds exceeds the Claude bridge's five-second
+   * hard-abort fallback.
+   */
+  turnTeardownGraceMs?: number;
   /**
    * Produce the adapter-defined runtime resume data for `stop`. Defaults to
    * `{}`.
@@ -355,6 +374,7 @@ export async function runBridge<TStart extends { type: 'start' }>(
   options: RunBridgeOptions<TStart>,
 ): Promise<BridgeHandle> {
   const { bridgeType, bridgeStateDir, onStart, onStop, onDestroy } = options;
+  const teardownGraceMs = options.turnTeardownGraceMs ?? 10_000;
   const expectedToken = options.token ?? procEnv.BRIDGE_CHANNEL_TOKEN ?? '';
   const bridgeWsPort =
     options.port ?? parseInt(procEnv.BRIDGE_WS_PORT ?? '0', 10);
@@ -384,6 +404,12 @@ export async function runBridge<TStart extends { type: 'start' }>(
   let isFirstTurn = true;
   let turnAbort: AbortController | undefined;
   let currentUserMessages: InternalBridgeUserMessageQueue | undefined;
+  /**
+   * Settles when the in-flight turn has fully wound down — `onStart`
+   * returned or threw AND its completion state was recorded. `undefined`
+   * between turns. A new `start` fences on this so turns never overlap.
+   */
+  let activeTurn: Promise<void> | undefined;
 
   // Diagnostics. Resolved per turn from `start.debug` with a sandbox-side
   // env fallback; gates console capture + structured `debug-event`s.
@@ -658,10 +684,44 @@ export async function runBridge<TStart extends { type: 'start' }>(
   ): Promise<void> => {
     switch (msg.type) {
       case 'start': {
+        /*
+         * A new turn replaces the active one — but only after the active one
+         * has fully wound down. Inbound frames are dispatched concurrently,
+         * and the host settles a caller abort immediately, so a retry's
+         * `start` can arrive while the aborted turn is still tearing down
+         * (e.g. a graceful interrupt). Without this fence the old turn would
+         * keep emitting into the new turn's cleared event log, two runtime
+         * processes would run side by side, and the old turn's completion
+         * would mark the bridge `waiting` underneath the new turn. Abort the
+         * old turn to hasten its teardown; adapters are expected to bound
+         * that teardown themselves (e.g. a hard-abort fallback), but the
+         * runtime does not rely on it: the wait is capped by the teardown
+         * grace period, after which the new turn proceeds anyway — the
+         * pre-fence overlapping behavior — rather than hanging behind a
+         * teardown that never settles.
+         */
+        for (;;) {
+          const pendingTurn = activeTurn;
+          if (pendingTurn == null) break;
+          turnAbort?.abort();
+          currentUserMessages?.close(
+            new Error('A new bridge turn replaced the active turn.'),
+          );
+          let graceTimer: ReturnType<typeof setTimeout> | undefined;
+          const settled = await Promise.race([
+            pendingTurn.then(() => true as const),
+            new Promise<false>(resolve => {
+              graceTimer = setTimeout(() => resolve(false), teardownGraceMs);
+              graceTimer.unref?.();
+            }),
+          ]);
+          clearTimeout(graceTimer);
+          if (!settled) break;
+        }
+        let turnFinished!: () => void;
+        const thisTurn = new Promise<void>(resolve => (turnFinished = resolve));
+        activeTurn = thisTurn;
         activeSocket = ws; // asking for a turn claims the event stream
-        currentUserMessages?.close(
-          new Error('A new bridge turn replaced the active turn.'),
-        );
         const firstTurn = isFirstTurn;
         isFirstTurn = false;
         eventLog = []; // clear previous turn; keep seqCounter monotonic
@@ -727,8 +787,15 @@ export async function runBridge<TStart extends { type: 'start' }>(
           if (currentUserMessages === userMessages) {
             currentUserMessages = undefined;
           }
-          currentTurnState = 'waiting';
-          void writeBridgeMeta('waiting');
+          // Only the still-active turn records completion: after a fence
+          // timeout a replacement turn is already running, and this stale
+          // completion must not mark the bridge waiting underneath it.
+          if (activeTurn === thisTurn) {
+            activeTurn = undefined;
+            currentTurnState = 'waiting';
+            void writeBridgeMeta('waiting');
+          }
+          turnFinished();
         }
         return;
       }

package/src/utils/index.ts

@@ -30,6 +30,7 @@ export {
   writeSkills,
   type SkillFilePathMode,
   type WriteSkillsOptions,
+  type WriteSkillsResult,
 } from './write-skills';
 export {
   markBridgeStarting,

package/src/utils/write-skills.ts

@@ -1,8 +1,16 @@
+import { createHash } from 'node:crypto';
 import path from 'node:path';
-import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+import {
+  safeParseJSON,
+  type Experimental_SandboxSession,
+} from '@ai-sdk/provider-utils';
 import type { HarnessV1Skill } from '../v1';
 import { shellQuote } from './shell-quote';
 
+const SKILLS_MANIFEST_FILENAME = '.ai-sdk-harness-skills.json';
+const SKILLS_MANIFEST_VERSION = 1;
+const SAFE_MANIFEST_SKILL_NAME = /^[A-Za-z0-9._-]+$/;
+
 export type SkillFilePathMode = 'relative' | 'strip-leading-slashes';
 
 export type WriteSkillsOptions = {
@@ -20,6 +28,33 @@ export type WriteSkillsOptions = {
   trailingNewline?: boolean;
 };
 
+export type WriteSkillsResult = {
+  changed: boolean;
+  written: string[];
+  removed: string[];
+  unchanged: string[];
+};
+
+type ProjectedSkill = {
+  readonly name: string;
+  readonly hash: string;
+  readonly files: ReadonlyArray<{
+    readonly path: string;
+    readonly content: string;
+  }>;
+};
+
+type SkillsManifestEntry = {
+  readonly name: string;
+  readonly hash: string;
+};
+
+type SkillsManifest = {
+  readonly version: typeof SKILLS_MANIFEST_VERSION;
+  readonly state: 'complete' | 'pending';
+  readonly skills: ReadonlyArray<SkillsManifestEntry>;
+};
+
 export async function writeSkills({
   sandbox,
   rootDir,
@@ -31,50 +66,365 @@ export async function writeSkills({
   invalidSkillFilePathMessage = ({ skillName, filePath }) =>
     `Invalid skill file path for ${skillName}: ${filePath}`,
   trailingNewline = false,
-}: WriteSkillsOptions): Promise<void> {
-  for (const skill of skills) {
-    validateSkillName({
-      name: skill.name,
-      pattern: skillNamePattern,
-      message: invalidSkillNameMessage,
+}: WriteSkillsOptions): Promise<WriteSkillsResult> {
+  const projectedSkills = skills
+    .map(skill =>
+      projectSkill({
+        skill,
+        skillNamePattern,
+        invalidSkillNameMessage,
+        filePathMode,
+        invalidSkillFilePathMessage,
+        trailingNewline,
+      }),
+    )
+    .sort((a, b) => a.name.localeCompare(b.name));
+  assertUniqueSkillNames(projectedSkills);
+
+  const manifestPath = path.posix.join(rootDir, SKILLS_MANIFEST_FILENAME);
+  const existingManifest = await readSkillsManifest({
+    sandbox,
+    manifestPath,
+    abortSignal,
+  });
+  const nextEntries = projectedSkills.map(({ name, hash }) => ({ name, hash }));
+  const nextByName = new Map(nextEntries.map(entry => [entry.name, entry]));
+
+  /*
+   * Delete pending-manifest directories before rewriting the requested skills;
+   * any listed directory may contain only part of its intended files.
+   */
+  if (existingManifest?.state === 'pending') {
+    await ensureSkillsDirectory({ sandbox, rootDir, abortSignal });
+    const recoveryNames = existingManifest.skills.map(skill => skill.name);
+    await removeSkillDirectories({
+      sandbox,
+      rootDir,
+      skillNames: recoveryNames,
+      abortSignal,
+    });
+    const removed = recoveryNames
+      .filter(name => !nextByName.has(name))
+      .sort((a, b) => a.localeCompare(b));
+    await writeProjectedSkills({
+      sandbox,
+      rootDir,
+      skills: projectedSkills,
+      abortSignal,
+    });
+    await writeSkillsManifest({
+      sandbox,
+      manifestPath,
+      manifest: {
+        version: SKILLS_MANIFEST_VERSION,
+        state: 'complete',
+        skills: nextEntries,
+      },
+      abortSignal,
     });
-    for (const file of skill.files ?? []) {
+    return {
+      changed: recoveryNames.length > 0 || projectedSkills.length > 0,
+      written: projectedSkills.map(skill => skill.name),
+      removed,
+      unchanged: [],
+    };
+  }
+
+  const previousEntries = existingManifest?.skills ?? [];
+  const previousByName = new Map(
+    previousEntries.map(entry => [entry.name, entry]),
+  );
+  const removed = previousEntries
+    .filter(entry => !nextByName.has(entry.name))
+    .map(entry => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+  const written = projectedSkills
+    .filter(skill => previousByName.get(skill.name)?.hash !== skill.hash)
+    .map(skill => skill.name)
+    .sort((a, b) => a.localeCompare(b));
+  const unchanged = projectedSkills
+    .filter(skill => previousByName.get(skill.name)?.hash === skill.hash)
+    .map(skill => skill.name)
+    .sort((a, b) => a.localeCompare(b));
+  const changed = removed.length > 0 || written.length > 0;
+
+  if (!changed && existingManifest != null) {
+    return { changed: false, written, removed, unchanged };
+  }
+
+  const previouslyOwned = new Set(previousEntries.map(entry => entry.name));
+  for (const skillName of written) {
+    if (previouslyOwned.has(skillName)) continue;
+    await assertSkillDirectoryAvailable({
+      sandbox,
+      rootDir,
+      skillName,
+      abortSignal,
+    });
+  }
+
+  await ensureSkillsDirectory({ sandbox, rootDir, abortSignal });
+
+  const pendingNames = Array.from(
+    new Set([
+      ...previousEntries.map(entry => entry.name),
+      ...nextEntries.map(entry => entry.name),
+    ]),
+  ).sort((a, b) => a.localeCompare(b));
+  await writeSkillsManifest({
+    sandbox,
+    manifestPath,
+    manifest: {
+      version: SKILLS_MANIFEST_VERSION,
+      state: 'pending',
+      skills: pendingNames.map(name => ({
+        name,
+        hash: nextByName.get(name)?.hash ?? previousByName.get(name)!.hash,
+      })),
+    },
+    abortSignal,
+  });
+
+  await removeSkillDirectories({
+    sandbox,
+    rootDir,
+    skillNames: [
+      ...removed,
+      ...written.filter(name => previouslyOwned.has(name)),
+    ],
+    abortSignal,
+  });
+  const writtenSet = new Set(written);
+  await writeProjectedSkills({
+    sandbox,
+    rootDir,
+    skills: projectedSkills.filter(skill => writtenSet.has(skill.name)),
+    abortSignal,
+  });
+  await writeSkillsManifest({
+    sandbox,
+    manifestPath,
+    manifest: {
+      version: SKILLS_MANIFEST_VERSION,
+      state: 'complete',
+      skills: nextEntries,
+    },
+    abortSignal,
+  });
+
+  return { changed, written, removed, unchanged };
+}
+
+async function ensureSkillsDirectory({
+  sandbox,
+  rootDir,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  rootDir: string;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  await runSandboxCommand({
+    sandbox,
+    command: `mkdir -p ${shellQuote(rootDir)}`,
+    abortSignal,
+    errorMessage: `Failed to create skills directory: ${rootDir}`,
+  });
+}
+
+function projectSkill({
+  skill,
+  skillNamePattern,
+  invalidSkillNameMessage,
+  filePathMode,
+  invalidSkillFilePathMessage,
+  trailingNewline,
+}: {
+  skill: HarnessV1Skill;
+  skillNamePattern: RegExp;
+  invalidSkillNameMessage: (input: { name: string }) => string;
+  filePathMode: SkillFilePathMode;
+  invalidSkillFilePathMessage: (input: {
+    skillName: string;
+    filePath: string;
+  }) => string;
+  trailingNewline: boolean;
+}): ProjectedSkill {
+  const name = validateSkillName({
+    name: skill.name,
+    pattern: skillNamePattern,
+    message: invalidSkillNameMessage,
+  });
+  const files = new Map<string, string>();
+  files.set('SKILL.md', renderSkillFile({ skill, trailingNewline }));
+  for (const file of skill.files ?? []) {
+    files.set(
       normalizeSkillFilePath({
         skillName: skill.name,
         filePath: file.path,
         mode: filePathMode,
         message: invalidSkillFilePathMessage,
-      });
+      }),
+      file.content,
+    );
+  }
+  const projectedFiles = Array.from(files, ([filePath, content]) => ({
+    path: filePath,
+    content,
+  })).sort((a, b) => a.path.localeCompare(b.path));
+  const hash = createHash('sha256');
+  for (const file of projectedFiles) {
+    hash.update(String(Buffer.byteLength(file.path)));
+    hash.update(':');
+    hash.update(file.path);
+    hash.update(String(Buffer.byteLength(file.content)));
+    hash.update(':');
+    hash.update(file.content);
+  }
+  return { name, hash: hash.digest('hex'), files: projectedFiles };
+}
+
+async function readSkillsManifest({
+  sandbox,
+  manifestPath,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  manifestPath: string;
+  abortSignal?: AbortSignal;
+}): Promise<SkillsManifest | undefined> {
+  const content = await sandbox.readTextFile({
+    path: manifestPath,
+    abortSignal,
+  });
+  if (content == null) return undefined;
+  const parsed = await safeParseJSON({ text: content });
+  if (!parsed.success || !isSkillsManifest(parsed.value)) {
+    throw new Error(`Invalid AI SDK harness skills manifest: ${manifestPath}`);
+  }
+  return parsed.value;
+}
+
+function isSkillsManifest(value: unknown): value is SkillsManifest {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const manifest = value as Record<string, unknown>;
+  if (
+    manifest.version !== SKILLS_MANIFEST_VERSION ||
+    (manifest.state !== 'complete' && manifest.state !== 'pending') ||
+    !Array.isArray(manifest.skills)
+  ) {
+    return false;
+  }
+  const names = new Set<string>();
+  for (const entry of manifest.skills) {
+    if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) {
+      return false;
     }
+    const skill = entry as Record<string, unknown>;
+    if (
+      typeof skill.name !== 'string' ||
+      !isSafeManifestSkillName(skill.name) ||
+      typeof skill.hash !== 'string' ||
+      !/^[a-f0-9]{64}$/.test(skill.hash) ||
+      names.has(skill.name)
+    ) {
+      return false;
+    }
+    names.add(skill.name);
   }
+  return true;
+}
 
-  await sandbox.run({
-    command: `mkdir -p ${shellQuote(rootDir)}`,
+async function writeSkillsManifest({
+  sandbox,
+  manifestPath,
+  manifest,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  manifestPath: string;
+  manifest: SkillsManifest;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  const temporaryPath = `${manifestPath}.tmp`;
+  await sandbox.writeTextFile({
+    path: temporaryPath,
+    content: `${JSON.stringify(manifest, null, 2)}\n`,
+    abortSignal,
+  });
+  await runSandboxCommand({
+    sandbox,
+    command: `mv -f ${shellQuote(temporaryPath)} ${shellQuote(manifestPath)}`,
     abortSignal,
+    errorMessage: `Failed to update skills manifest: ${manifestPath}`,
   });
+}
 
-  for (const skill of skills) {
-    const name = validateSkillName({
-      name: skill.name,
-      pattern: skillNamePattern,
-      message: invalidSkillNameMessage,
-    });
-    const skillDir = path.posix.join(rootDir, name);
-    await sandbox.writeTextFile({
-      path: path.posix.join(skillDir, 'SKILL.md'),
-      content: renderSkillFile({ skill, trailingNewline }),
-      abortSignal,
-    });
+async function assertSkillDirectoryAvailable({
+  sandbox,
+  rootDir,
+  skillName,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  rootDir: string;
+  skillName: string;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  const skillDir = path.posix.join(rootDir, skillName);
+  const result = await sandbox.run({
+    command: `test ! -e ${shellQuote(skillDir)}`,
+    abortSignal,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Cannot write harness skill '${skillName}': ${skillDir} already exists and is not owned by the AI SDK harness.`,
+    );
+  }
+}
 
-    for (const file of skill.files ?? []) {
-      const filePath = normalizeSkillFilePath({
-        skillName: skill.name,
-        filePath: file.path,
-        mode: filePathMode,
-        message: invalidSkillFilePathMessage,
-      });
+async function removeSkillDirectories({
+  sandbox,
+  rootDir,
+  skillNames,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  rootDir: string;
+  skillNames: ReadonlyArray<string>;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  if (skillNames.length === 0) return;
+  const directories = Array.from(new Set(skillNames))
+    .sort((a, b) => a.localeCompare(b))
+    .map(name => shellQuote(path.posix.join(rootDir, name)))
+    .join(' ');
+  await runSandboxCommand({
+    sandbox,
+    command: `rm -rf -- ${directories}`,
+    abortSignal,
+    errorMessage: `Failed to replace harness skills in: ${rootDir}`,
+  });
+}
+
+async function writeProjectedSkills({
+  sandbox,
+  rootDir,
+  skills,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  rootDir: string;
+  skills: ReadonlyArray<ProjectedSkill>;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  for (const skill of skills) {
+    const skillDir = path.posix.join(rootDir, skill.name);
+    for (const file of skill.files) {
       await sandbox.writeTextFile({
-        path: path.posix.join(skillDir, filePath),
+        path: path.posix.join(skillDir, file.path),
         content: file.content,
         abortSignal,
       });
@@ -82,6 +432,40 @@ export async function writeSkills({
   }
 }
 
+async function runSandboxCommand({
+  sandbox,
+  command,
+  abortSignal,
+  errorMessage,
+}: {
+  sandbox: Experimental_SandboxSession;
+  command: string;
+  abortSignal?: AbortSignal;
+  errorMessage: string;
+}): Promise<void> {
+  const result = await sandbox.run({ command, abortSignal });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `${errorMessage} (exit ${result.exitCode})${result.stderr ? `: ${result.stderr}` : ''}`,
+    );
+  }
+}
+
+function assertUniqueSkillNames(skills: ReadonlyArray<ProjectedSkill>): void {
+  for (let index = 1; index < skills.length; index++) {
+    if (skills[index - 1]!.name === skills[index]!.name) {
+      throw new Error(`Duplicate skill name: ${skills[index]!.name}`);
+    }
+  }
+}
+
+function isSafeManifestSkillName(name: string): boolean {
+  SAFE_MANIFEST_SKILL_NAME.lastIndex = 0;
+  const matches = SAFE_MANIFEST_SKILL_NAME.test(name);
+  SAFE_MANIFEST_SKILL_NAME.lastIndex = 0;
+  return matches && name !== '.' && name !== '..' && !name.includes('/');
+}
+
 function validateSkillName({
   name,
   pattern,
@@ -91,7 +475,10 @@ function validateSkillName({
   pattern: RegExp;
   message?: (input: { name: string }) => string;
 }): string {
-  if (!pattern.test(name) || name === '.' || name === '..') {
+  pattern.lastIndex = 0;
+  const matches = pattern.test(name);
+  pattern.lastIndex = 0;
+  if (!matches || name === '.' || name === '..') {
     throw new Error(message?.({ name }) ?? `Invalid skill name: ${name}`);
   }
   return name;

package/src/v1/harness-v1-lifecycle-state.ts

@@ -1,4 +1,6 @@
 import type { JSONValue } from '@ai-sdk/provider';
+import type { HarnessV1Skill } from './harness-v1-skill';
+import type { HarnessV1ToolSpec } from './harness-v1-tool-spec';
 
 export type HarnessV1PendingToolApproval = {
   readonly approvalId: string;
@@ -16,6 +18,35 @@ export type HarnessV1PendingToolResult = {
   readonly input: string;
 };
 
+/**
+ * Framework-owned settings captured when a turn begins. The same settings are
+ * passed to fresh and continued turns and persisted with unfinished-turn state
+ * so a resumed continuation cannot pick up configuration from a later turn.
+ */
+export type HarnessV1TurnSettings = {
+  /**
+   * Skills made available to the underlying runtime for this turn. Adapters
+   * must replace skills from the preceding completed turn before starting a
+   * fresh turn. Rerun-based continuations use them to reconstruct the turn.
+   */
+  readonly skills: ReadonlyArray<HarnessV1Skill>;
+
+  /**
+   * Free-form instructions for this turn. Adapters should apply them through
+   * the runtime's native system or developer instruction mechanism when
+   * supported. Rerun-based continuations use them to reconstruct the turn.
+   */
+  readonly instructions?: string;
+
+  /**
+   * Host-defined tools made available to the underlying runtime for this turn.
+   * The harness emits `tool-call` events when the runtime calls one and waits
+   * for `submitToolResult`. Rerun-based continuations use them to reconstruct
+   * the turn.
+   */
+  readonly tools: ReadonlyArray<HarnessV1ToolSpec>;
+};
+
 type HarnessV1LifecycleStateBase = {
   /**
    * Identifier of the harness that produced this state. Used by adapters to
@@ -70,6 +101,13 @@ export type HarnessV1ContinueTurnState = HarnessV1LifecycleStateBase & {
    * result before the underlying turn can continue.
    */
   readonly pendingToolResults?: readonly HarnessV1PendingToolResult[];
+
+  /**
+   * Framework-owned settings captured when the unfinished turn began. They
+   * are persisted outside adapter data so a resumed continuation cannot pick
+   * up settings prepared for a later turn.
+   */
+  readonly turnSettings?: HarnessV1TurnSettings;
 };
 
 export type HarnessV1LifecycleState =