@ai-sdk/harness 0.0.0 → 1.0.0-canary.3

package/src/agent/harness-diagnostics.ts

@@ -0,0 +1,88 @@
+/*
+ * Host/consumer-facing observability types.
+ *
+ * These are deliberately NOT part of the `HarnessV1` adapter spec (`src/v1`):
+ * no harness adapter implements or consumes them. Adapters only deal with the
+ * wire frames (`HarnessV1BridgeSandboxLog` / `HarnessV1BridgeDebugEvent`) and
+ * the `HarnessV1Observability` handle the framework hands to `doStart`. The
+ * framework normalizes those frames into the `HarnessDiagnostic` shape below
+ * for consumers (`HarnessAgentSettings.onLog`) and reporters. Hence no `V1`
+ * affix and a home outside the spec.
+ */
+
+/** Severity of a diagnostic. */
+export type HarnessDebugLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+
+/**
+ * Consumer-facing diagnostics configuration. Set on `HarnessAgentSettings` to
+ * enable bridge log forwarding and the `HARNESS_DEBUG` stderr default in code.
+ * `HARNESS_DEBUG` / `HARNESS_DEBUG_LEVEL` / `HARNESS_DEBUG_SUBSYSTEMS` env vars
+ * fill any unset field — a convenience default, never the only path.
+ */
+export type HarnessDebugConfig = {
+  /** Master switch. Nothing is captured or forwarded when false/unset. */
+  readonly enabled?: boolean;
+  /** Threshold; events at or above this severity are emitted. Default `debug`. */
+  readonly level?: HarnessDebugLevel;
+  /** Dotted-prefix subsystem filter for structured events. */
+  readonly subsystems?: ReadonlyArray<string>;
+};
+
+/**
+ * A forwarded bridge diagnostic, normalized for host consumers.
+ *
+ * The bridge emits two raw frame kinds — captured console lines (`sandbox-log`)
+ * and structured events (`debug-event`). The framework normalizes both into
+ * this single shape before handing them to a consumer's `onLog` callback, the
+ * `HARNESS_DEBUG` stderr default, and observability reporters. Diagnostics are
+ * kept first-class and per-line — they are never folded into telemetry spans.
+ */
+export type HarnessDiagnostic = {
+  /**
+   * Severity. Structured events carry their own level; captured console lines
+   * map `stderr` → `'warn'` and `stdout` → `'info'`.
+   */
+  readonly level: HarnessDebugLevel;
+
+  /** Human-readable line (console capture) or message (structured event). */
+  readonly message: string;
+
+  /**
+   * Dotted subsystem. For captured console output this is
+   * `sandbox.log.<source>`; for structured events it is the adapter-supplied
+   * subsystem (e.g. `bridge.turn`).
+   */
+  readonly subsystem: string;
+
+  /** `'log'` = captured console line; `'event'` = structured `bridgeLog`. */
+  readonly kind: 'log' | 'event';
+
+  /** Originating sandbox source label (console capture). */
+  readonly source?: string;
+
+  /** Which standard stream the line came from (console capture). */
+  readonly stream?: 'stdout' | 'stderr';
+
+  /** Structured attributes (structured events only). */
+  readonly attrs?: Record<string, unknown>;
+
+  /** Error payload (structured events only). */
+  readonly error?: { name?: string; message: string; stack?: string };
+
+  /** The harness session this diagnostic originated from. */
+  readonly sessionId?: string;
+
+  /** Host receipt time (epoch ms). */
+  readonly timestamp: number;
+};
+
+/**
+ * A telemetry integration that also wants the per-line diagnostics stream. The
+ * framework calls `ingestDiagnostic` for every forwarded bridge diagnostic in
+ * addition to driving the standard `Telemetry` span lifecycle, so a single
+ * reporter object (e.g. `createFileReporter`) registered in
+ * `telemetry.integrations` receives both spans and logs.
+ */
+export interface HarnessDiagnosticConsumer {
+  ingestDiagnostic?(diagnostic: HarnessDiagnostic): void;
+}

package/src/agent/internal/bootstrap-recipe.ts

@@ -0,0 +1,124 @@
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { HarnessV1Bootstrap } from '../../v1';
+
+/**
+ * Version of the bootstrap recipe shape itself. Bump to force every existing
+ * snapshot/marker to be invalidated regardless of recipe content.
+ */
+export const BOOTSTRAP_SCHEMA_VERSION = 1;
+
+/**
+ * Deterministic 16-char hex identity derived from the recipe's content
+ * (harnessId, bootstrapDir, file paths + contents, commands, schema version).
+ * Two adapters with equivalent recipes produce the same identity; any
+ * content change produces a different identity.
+ *
+ * Used by sandbox providers as part of the persistent sandbox name so
+ * recipe changes automatically invalidate snapshots.
+ */
+export async function hashBootstrap(
+  recipe: HarnessV1Bootstrap,
+): Promise<string> {
+  const encoder = new TextEncoder();
+  const chunks: Uint8Array[] = [];
+  const pushString = (value: string) => {
+    chunks.push(encoder.encode(value));
+    chunks.push(encoder.encode('\0'));
+  };
+
+  pushString(recipe.harnessId);
+  pushString(recipe.bootstrapDir);
+
+  const sortedFiles = [...recipe.files].sort((a, b) =>
+    a.path.localeCompare(b.path),
+  );
+  for (const file of sortedFiles) {
+    pushString(file.path);
+    pushString(file.content);
+  }
+
+  pushString(JSON.stringify(recipe.commands));
+  pushString(String(BOOTSTRAP_SCHEMA_VERSION));
+
+  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const buffer = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    buffer.set(chunk, offset);
+    offset += chunk.length;
+  }
+
+  const digest = await crypto.subtle.digest('SHA-256', buffer);
+  const bytes = new Uint8Array(digest);
+  let hex = '';
+  for (let i = 0; i < 8; i++) {
+    hex += bytes[i].toString(16).padStart(2, '0');
+  }
+  return hex;
+}
+
+/**
+ * Absolute path of the marker file the framework writes after a recipe runs
+ * successfully. Presence of this path inside the sandbox indicates the
+ * recipe with the matching `identity` has already been applied.
+ */
+export function bootstrapMarkerPath(
+  recipe: HarnessV1Bootstrap,
+  identity: string,
+): string {
+  return `${recipe.bootstrapDir}/.bootstrap-${identity}.ok`;
+}
+
+/**
+ * Apply a bootstrap recipe to a sandbox session idempotently. Reads the
+ * marker file; if it exists, returns immediately. Otherwise writes the
+ * recipe's files, runs its commands sequentially, and writes the marker
+ * on success.
+ *
+ * Safe to call multiple times. For sandboxes that already contain the
+ * recipe (resumed from snapshot, reused across sessions, or applied by
+ * an earlier process) this is a single fast read.
+ */
+export async function applyBootstrapRecipe(
+  session: SandboxSession,
+  recipe: HarnessV1Bootstrap,
+  identity: string,
+  options?: { abortSignal?: AbortSignal },
+): Promise<void> {
+  const markerPath = bootstrapMarkerPath(recipe, identity);
+
+  const existingMarker = await session.readTextFile({
+    path: markerPath,
+    abortSignal: options?.abortSignal,
+  });
+  if (existingMarker !== null) {
+    return;
+  }
+
+  for (const file of recipe.files) {
+    await session.writeTextFile({
+      path: file.path,
+      content: file.content,
+      abortSignal: options?.abortSignal,
+    });
+  }
+
+  for (const cmd of recipe.commands) {
+    const result = await session.run({
+      command: cmd.command,
+      workingDirectory: cmd.workingDirectory,
+      abortSignal: options?.abortSignal,
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Bootstrap command failed for harness '${recipe.harnessId}' (exit ${result.exitCode}): ${cmd.command}\n${result.stderr || result.stdout}`,
+      );
+    }
+  }
+
+  await session.writeTextFile({
+    path: markerPath,
+    content: '',
+    abortSignal: options?.abortSignal,
+  });
+}

package/src/agent/internal/bridge-port-registry.ts

@@ -0,0 +1,52 @@
+/**
+ * Process-wide registry for bridge-port leases. Used when a sandbox provider
+ * wraps a caller-provided sandbox with a pre-declared port pool — each
+ * concurrent harness session leases one port from the pool, releases on
+ * session stop or destroy. Multiple sessions on the same provider instance
+ * share the same pool; different provider instances (even wrapping the same
+ * underlying sandbox) get independent registries.
+ *
+ * Sized to the typical case: one provider object passed to N HarnessAgents.
+ * Callers that need cross-process coordination must layer that on top.
+ */
+
+type RegistryEntry = {
+  readonly pool: ReadonlyArray<number>;
+  readonly leases: Map<string, number>;
+};
+
+const registries = new WeakMap<object, RegistryEntry>();
+
+export function acquireBridgePort(options: {
+  poolKey: object;
+  pool: ReadonlyArray<number>;
+  sessionId: string;
+}): number {
+  let entry = registries.get(options.poolKey);
+  if (entry == null) {
+    entry = { pool: options.pool, leases: new Map() };
+    registries.set(options.poolKey, entry);
+  }
+  const existing = entry.leases.get(options.sessionId);
+  if (existing != null) return existing;
+
+  const leased = new Set(entry.leases.values());
+  for (const port of entry.pool) {
+    if (!leased.has(port)) {
+      entry.leases.set(options.sessionId, port);
+      return port;
+    }
+  }
+  throw new Error(
+    `No available bridge port — pool of ${entry.pool.length} ports is fully leased.`,
+  );
+}
+
+export function releaseBridgePort(options: {
+  poolKey: object;
+  sessionId: string;
+}): void {
+  const entry = registries.get(options.poolKey);
+  if (entry == null) return;
+  entry.leases.delete(options.sessionId);
+}