@ai-sdk/harness 1.0.92 → 1.0.94

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-bridge-protocol.ts

@@ -21,6 +21,9 @@ import {
   harnessV1TextStartPartSchema,
   harnessV1ToolApprovalRequestPartSchema,
   harnessV1ToolCallPartSchema,
+  harnessV1ToolInputDeltaPartSchema,
+  harnessV1ToolInputEndPartSchema,
+  harnessV1ToolInputStartPartSchema,
   harnessV1ToolResultPartSchema,
 } from './harness-v1-stream-part';
 
@@ -213,6 +216,9 @@ export const harnessV1BridgeOutboundMessageSchema = z.discriminatedUnion(
     harnessV1ReasoningStartPartSchema,
     harnessV1ReasoningDeltaPartSchema,
     harnessV1ReasoningEndPartSchema,
+    harnessV1ToolInputStartPartSchema,
+    harnessV1ToolInputDeltaPartSchema,
+    harnessV1ToolInputEndPartSchema,
     harnessV1ToolCallPartSchema,
     harnessV1ToolApprovalRequestPartSchema,
     harnessV1ToolResultPartSchema,

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,42 @@ 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 = {
+  /**
+   * Model identifier selected for this turn. Adapters interpret this value
+   * according to the underlying harness runtime. Rerun-based continuations
+   * reuse it when reconstructing the turn.
+   */
+  readonly model?: string;
+
+  /**
+   * 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 +108,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 =

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

@@ -8,10 +8,9 @@ import type { HarnessV1ResponseFormat } from './harness-v1-response-format';
 import type {
   HarnessV1ContinueTurnState,
   HarnessV1ResumeSessionState,
+  HarnessV1TurnSettings,
 } from './harness-v1-lifecycle-state';
-import type { HarnessV1Skill } from './harness-v1-skill';
 import type { HarnessV1StreamPart } from './harness-v1-stream-part';
-import type { HarnessV1ToolSpec } from './harness-v1-tool-spec';
 import type { HarnessV1BuiltinToolFiltering } from './harness-v1-tool-filtering';
 
 /**
@@ -29,12 +28,6 @@ export type HarnessV1StartOptions = {
    */
   readonly sessionId: string;
 
-  /**
-   * Skills made available to the underlying runtime for the lifetime of
-   * the session. Adapters decide how to surface them.
-   */
-  readonly skills?: ReadonlyArray<HarnessV1Skill>;
-
   /**
    * Optional resume payload returned by a prior session lifecycle method. When
    * provided, the adapter should resume the existing session before accepting a
@@ -95,7 +88,7 @@ export type HarnessV1StartOptions = {
 /**
  * Options passed to `HarnessV1Session.doPromptTurn`.
  */
-export type HarnessV1PromptTurnOptions = {
+export type HarnessV1PromptTurnOptions = HarnessV1TurnSettings & {
   /**
    * Fresh input for this turn — either a plain string or a single
    * `ModelMessage`. The harness session owns its own conversation history,
@@ -109,22 +102,6 @@ export type HarnessV1PromptTurnOptions = {
    */
   readonly responseFormat?: HarnessV1ResponseFormat;
 
-  /**
-   * Host-defined tools to make available to the underlying runtime for this
-   * turn. The harness emits `tool-call` events when the runtime calls one
-   * and waits for `submitToolResult`.
-   */
-  readonly tools?: ReadonlyArray<HarnessV1ToolSpec>;
-
-  /**
-   * Free-form instructions for the session. The framework supplies the same
-   * value on every turn. Adapters should append it to the runtime's native
-   * system or developer prompt when supported. Otherwise, they should prepend
-   * it to the first user message of a fresh session and rely on the runtime's
-   * persisted history when resuming.
-   */
-  readonly instructions?: string;
-
   /**
    * Signal that aborts the in-flight turn. The adapter must cancel any
    * underlying work and resolve `done` (with an error if appropriate).
@@ -147,27 +124,13 @@ export type HarnessV1PromptTurnOptions = {
  * in-flight turn rather than starting a new one. It is used to continue a turn
  * that was previously suspended temporarily, e.g. by the workflow slice loop.
  */
-export type HarnessV1ContinueTurnOptions = {
+export type HarnessV1ContinueTurnOptions = HarnessV1TurnSettings & {
   /**
    * Response format of the in-flight turn. Rerun-based adapters use this when
    * reconstructing the turn; attach-based adapters may ignore it.
    */
   readonly responseFormat?: HarnessV1ResponseFormat;
 
-  /**
-   * Host-defined tools to make available for the continued turn. Same shape
-   * as `doPromptTurn`'s `tools`. An adapter that purely attaches to a live turn
-   * may ignore them; an adapter that re-drives the turn (rerun) needs them.
-   */
-  readonly tools?: ReadonlyArray<HarnessV1ToolSpec>;
-
-  /**
-   * Free-form session instructions. An adapter that re-drives the runtime may
-   * need these to reconstruct its native system or developer prompt. An
-   * adapter that attaches to a live turn may ignore them.
-   */
-  readonly instructions?: string;
-
   /**
    * Signal that aborts the continued turn. The adapter must cancel any
    * underlying work and resolve `done` (with an error if appropriate).
@@ -202,14 +165,6 @@ export type HarnessV1Session = {
    */
   readonly isResume: boolean;
 
-  /**
-   * The model id the underlying runtime is configured to use, if the adapter
-   * knows it (e.g. from its settings). Surfaced into telemetry as
-   * `gen_ai.request.model` and the trace span labels. Omitted when the adapter
-   * defers to the runtime's own default and has no concrete id.
-   */
-  readonly modelId?: string;
-
   /**
    * Run one prompt turn. Returns a control handle the host uses to feed
    * tool results, approvals, and user messages back into the turn while it