@elizaos/app-core 2.0.0-beta.2 → 2.0.11-beta.5

package/scripts/lib/apple-entitlement-audit.test.mjs

@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it } from "vitest";
+
+import {
+  assertMasEntitlementRuntimeEvidence,
+  assertReviewedAppleStoreEntitlements,
+  scanAppleAppBundleForNativeRuntimeSignals,
+  validateEntitlementsAgainstTarget,
+} from "./apple-entitlement-audit.mjs";
+
+describe("apple entitlement audit", () => {
+  it("accepts the reviewed App Store entitlement sources", () => {
+    assert.doesNotThrow(() => assertReviewedAppleStoreEntitlements());
+  });
+
+  it("flags MAS allow-unsigned-executable-memory without current evidence", () => {
+    const manifest = {
+      targets: [
+        {
+          id: "macos-mas-app",
+          distribution: "mac-app-store",
+          allowedEntitlements: {
+            "com.apple.security.app-sandbox": {
+              value: true,
+              justification: "Mac App Store sandbox is required.",
+            },
+            "com.apple.security.cs.allow-unsigned-executable-memory": {
+              value: true,
+              reviewSensitive: true,
+              appReviewJustification:
+                "Temporary runtime exception that must be backed by current evidence.",
+            },
+          },
+        },
+      ],
+    };
+
+    const errors = validateEntitlementsAgainstTarget({
+      entitlements: {
+        "com.apple.security.app-sandbox": true,
+        "com.apple.security.cs.allow-unsigned-executable-memory": true,
+      },
+      targetId: "macos-mas-app",
+      manifest,
+      label: "fixture",
+    });
+
+    assert.ok(
+      errors.some((error) => error.includes("needs currentEvidence")),
+      errors.join("\n"),
+    );
+  });
+
+  it("flags unexpected MAS disable-library-validation as review-sensitive", () => {
+    const manifest = {
+      targets: [
+        {
+          id: "macos-mas-app",
+          distribution: "mac-app-store",
+          allowedEntitlements: {
+            "com.apple.security.app-sandbox": {
+              value: true,
+              justification: "Mac App Store sandbox is required.",
+            },
+          },
+        },
+      ],
+    };
+
+    const errors = validateEntitlementsAgainstTarget({
+      entitlements: {
+        "com.apple.security.app-sandbox": true,
+        "com.apple.security.cs.disable-library-validation": true,
+      },
+      targetId: "macos-mas-app",
+      manifest,
+      label: "fixture",
+    });
+
+    assert.ok(
+      errors.some((error) =>
+        error.includes(
+          "unexpected entitlement com.apple.security.cs.disable-library-validation (review-sensitive)",
+        ),
+      ),
+      errors.join("\n"),
+    );
+  });
+
+  it("scans a built app bundle for JIT and native-library signals", () => {
+    const tmp = mkdtempSync(path.join(os.tmpdir(), "apple-entitlement-audit-"));
+    try {
+      const app = path.join(tmp, "Fixture.app");
+      const macos = path.join(app, "Contents", "MacOS");
+      mkdirSync(macos, { recursive: true });
+      writeFileSync(
+        path.join(macos, "bun"),
+        Buffer.concat([
+          Buffer.from([0xfe, 0xed, 0xfa, 0xcf]),
+          Buffer.from(
+            "\0_pthread_jit_write_protect_np\0_MAP_JIT\0_dlopen\0libNativeWrapper.dylib\0",
+          ),
+        ]),
+      );
+
+      const scan = scanAppleAppBundleForNativeRuntimeSignals(app);
+
+      assert.equal(scan.machOCount, 1);
+      assert.equal(scan.jitExecutableMemory.length, 1);
+      assert.ok(scan.dynamicLibraryLoading.length >= 1);
+      assert.doesNotThrow(() =>
+        assertMasEntitlementRuntimeEvidence({
+          entitlements: {
+            "com.apple.security.cs.allow-jit": true,
+          },
+          scan,
+          label: "fixture",
+        }),
+      );
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("requires built-app evidence when a MAS JIT entitlement is present", () => {
+    assert.throws(
+      () =>
+        assertMasEntitlementRuntimeEvidence({
+          entitlements: {
+            "com.apple.security.cs.allow-jit": true,
+          },
+          scan: {
+            jitExecutableMemory: [],
+            dynamicLibraryLoading: [],
+          },
+          label: "fixture",
+        }),
+      /no JIT or executable-memory native-symbol evidence/,
+    );
+  });
+});

package/scripts/lib/bun-version-guard.mjs

@@ -1,5 +1,7 @@
+// The repo standardizes on the Bun 1.4 canary line (the Rust rewrite). Anything
+// at or above 1.4 — canary or, once it lands, stable — is accepted.
 const RECOMMENDED_BUN_MAJOR = 1;
-const RECOMMENDED_BUN_MINOR = 3;
+const RECOMMENDED_BUN_MINOR = 4;
 
 function parseBunVersion(rawVersion) {
   const trimmed = String(rawVersion ?? "").trim();
@@ -15,9 +17,9 @@ function parseBunVersion(rawVersion) {
 }
 
 /**
- * Returns a non-fatal advisory string if the given Bun version string is
- * canary or outside the recommended 1.3.x range. Returns null if OK or if
- * no version is provided.
+ * Returns a non-fatal advisory string if the given Bun version is older than
+ * the recommended Bun 1.4 canary (Rust) line. Returns null if OK or if no
+ * version is provided.
  *
  * @param {string | undefined} [raw] - The Bun version string to check.
  *   Defaults to `globalThis.Bun?.version`.
@@ -25,20 +27,18 @@ function parseBunVersion(rawVersion) {
 export function getBunVersionAdvisory(raw = globalThis.Bun?.version) {
   if (!raw) return null;
   const parsed = parseBunVersion(raw);
+  const advisory = `Recommended: Bun ${RECOMMENDED_BUN_MAJOR}.${RECOMMENDED_BUN_MINOR}.x (canary, Rust build). Run \`bun upgrade --canary\`.`;
   if (!parsed) {
-    return `Detected Bun ${raw}. Recommended: Bun ${RECOMMENDED_BUN_MAJOR}.${RECOMMENDED_BUN_MINOR}.x stable.`;
-  }
-
-  if (parsed.suffix.includes("canary")) {
-    return `Detected Bun ${parsed.raw} (canary). Canary can break module interop; prefer Bun ${RECOMMENDED_BUN_MAJOR}.${RECOMMENDED_BUN_MINOR}.x stable.`;
+    return `Detected Bun ${raw}. ${advisory}`;
   }
 
   if (
-    parsed.major !== RECOMMENDED_BUN_MAJOR ||
-    parsed.minor !== RECOMMENDED_BUN_MINOR
+    parsed.major > RECOMMENDED_BUN_MAJOR ||
+    (parsed.major === RECOMMENDED_BUN_MAJOR &&
+      parsed.minor >= RECOMMENDED_BUN_MINOR)
   ) {
-    return `Detected Bun ${parsed.raw}. Recommended: Bun ${RECOMMENDED_BUN_MAJOR}.${RECOMMENDED_BUN_MINOR}.x stable.`;
+    return null;
   }
 
-  return null;
+  return `Detected Bun ${parsed.raw}. ${advisory}`;
 }

package/scripts/lib/capacitor-plugin-build-needed.mjs

@@ -1,12 +1,13 @@
 /**
  * Returns true if any Capacitor plugin under the given directory (typically
- * `eliza/packages/native-plugins`) needs a rebuild (missing dist or src /
- * config newer than dist marker).
+ * `eliza/plugins`, formerly `eliza/packages/native/plugins`) needs a rebuild
+ * (missing dist or src / config newer than dist marker).
  */
 import fs from "node:fs";
 import path from "node:path";
 
 const SRC_EXTS = new Set([".ts", ".tsx"]);
+const NATIVE_PLUGIN_DIR_PREFIX = "plugin-native-";
 
 function newestMtimeInDir(dir) {
   let max = 0;
@@ -46,7 +47,7 @@ function distMarkerPath(pluginRoot) {
 
 export function capacitorPluginsBuildNeeded(pluginsDir, pluginNames) {
   for (const name of pluginNames) {
-    const root = path.join(pluginsDir, name);
+    const root = path.join(pluginsDir, `${NATIVE_PLUGIN_DIR_PREFIX}${name}`);
     const marker = distMarkerPath(root);
     if (!marker) {
       return true;

package/scripts/lib/capacitor-plugin-names.mjs

@@ -5,27 +5,38 @@ import { fileURLToPath } from "node:url";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 /**
- * Absolute path to `eliza/packages/native-plugins` (Capacitor + Electrobun
- * plugin packages). Resolved relative to this script so build scripts and
- * repo utilities share one root regardless of the host fork's layout.
+ * Absolute path to `eliza/plugins` — the workspace plugin root. Native
+ * plugins live under `plugin-native-*` (formerly
+ * `packages/native/plugins/*`). Resolved relative to this script so build
+ * scripts and repo utilities share one root regardless of the host fork's
+ * layout.
  */
-const sourceNativePluginsRoot = path.resolve(
-  __dirname,
-  "../../../native-plugins",
-);
+const NATIVE_PLUGIN_DIR_PREFIX = "plugin-native-";
+const sourcePluginsRoot = path.resolve(__dirname, "../../../../plugins");
 
-export const NATIVE_PLUGINS_ROOT = fs.existsSync(sourceNativePluginsRoot)
-  ? sourceNativePluginsRoot
+export const NATIVE_PLUGINS_ROOT = fs.existsSync(sourcePluginsRoot)
+  ? sourcePluginsRoot
   : path.resolve(process.cwd(), "node_modules");
 
-/** Short names of each real workspace package under {@link NATIVE_PLUGINS_ROOT}. */
-export const CAPACITOR_PLUGIN_NAMES = fs.existsSync(sourceNativePluginsRoot)
+/**
+ * Short names of each real native workspace plugin (without the
+ * `plugin-native-` prefix), matching the historical directory names that
+ * lived under `packages/native/plugins/`.
+ */
+export const CAPACITOR_PLUGIN_NAMES = fs.existsSync(sourcePluginsRoot)
   ? fs
       .readdirSync(NATIVE_PLUGINS_ROOT, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name)
+      .filter(
+        (entry) =>
+          entry.isDirectory() &&
+          entry.name.startsWith(NATIVE_PLUGIN_DIR_PREFIX),
+      )
+      .map((entry) => entry.name.slice(NATIVE_PLUGIN_DIR_PREFIX.length))
       .filter((name) => {
-        const pluginDir = path.join(NATIVE_PLUGINS_ROOT, name);
+        const pluginDir = path.join(
+          NATIVE_PLUGINS_ROOT,
+          `${NATIVE_PLUGIN_DIR_PREFIX}${name}`,
+        );
         return (
           fs.existsSync(path.join(pluginDir, "package.json")) &&
           fs.existsSync(path.join(pluginDir, "src", "index.ts"))
@@ -33,3 +44,8 @@ export const CAPACITOR_PLUGIN_NAMES = fs.existsSync(sourceNativePluginsRoot)
       })
       .sort((left, right) => left.localeCompare(right))
   : [];
+
+/** Resolve the absolute plugin directory for a short native plugin name. */
+export function resolveNativePluginDir(name) {
+  return path.join(NATIVE_PLUGINS_ROOT, `${NATIVE_PLUGIN_DIR_PREFIX}${name}`);
+}

package/scripts/lib/desktop-preflight.mjs

@@ -35,11 +35,15 @@ export function parseBunVersion(rawVersion) {
 
 export function isSupportedBunVersion(rawVersion) {
   const parsed = parseBunVersion(rawVersion);
-  if (
-    parsed.major == null ||
-    parsed.minor == null ||
-    parsed.channel !== "stable"
-  ) {
+  if (parsed.major == null || parsed.minor == null) {
+    return false;
+  }
+  // The repo standardizes on the Bun 1.4 canary (Rust) line, so accept canary
+  // at or above 1.4. Stable >= 1.3 stays supported for anyone still on it.
+  if (parsed.channel === "canary") {
+    return parsed.major > 1 || (parsed.major === 1 && parsed.minor >= 4);
+  }
+  if (parsed.channel !== "stable") {
     return false;
   }
   if (parsed.major > 1) return true;

package/scripts/lib/desktop-startup-embedding-warmup-policy.mjs

@@ -0,0 +1,51 @@
+const SKIP_ENV = "ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP";
+const OPT_IN_ENV = "ELIZA_ENABLE_STARTUP_LOCAL_EMBEDDING_WARMUP";
+const DEFER_ENV = "ELIZA_DEFER_LOCAL_EMBEDDING_WARMUP";
+
+function isTruthyEnvValue(value) {
+  const normalized = value?.trim().toLowerCase();
+  return (
+    normalized === "1" ||
+    normalized === "true" ||
+    normalized === "yes" ||
+    normalized === "on"
+  );
+}
+
+export function resolveDesktopStartupEmbeddingWarmupPolicy(env = process.env) {
+  const skipRaw = env[SKIP_ENV]?.trim();
+  if (skipRaw) {
+    return {
+      env: { [SKIP_ENV]: skipRaw },
+      effective: isTruthyEnvValue(skipRaw) ? "skipped" : "startup background",
+      source: `env set - ${SKIP_ENV}=${skipRaw}`,
+      change: `unset ${SKIP_ENV}, or set ${OPT_IN_ENV}=1 when no skip override is present`,
+    };
+  }
+
+  if (isTruthyEnvValue(env.CI)) {
+    return {
+      env: { [SKIP_ENV]: "1" },
+      effective: "skipped",
+      source: "default - CI",
+      change: `set ${SKIP_ENV}=0 to allow CI startup warmup`,
+    };
+  }
+
+  const optInRaw = env[OPT_IN_ENV]?.trim();
+  if (isTruthyEnvValue(optInRaw)) {
+    return {
+      env: {},
+      effective: "startup background",
+      source: `env set - ${OPT_IN_ENV}=${optInRaw}`,
+      change: `unset ${OPT_IN_ENV} for default desktop fast startup`,
+    };
+  }
+
+  return {
+    env: { [DEFER_ENV]: "1" },
+    effective: "deferred background",
+    source: "default - desktop dev fast startup",
+    change: `set ${OPT_IN_ENV}=1 to start warmup during runtime bootstrap, or ${SKIP_ENV}=1 to disable it`,
+  };
+}

package/scripts/lib/desktop-startup-embedding-warmup-policy.test.mjs

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveDesktopStartupEmbeddingWarmupPolicy } from "./desktop-startup-embedding-warmup-policy.mjs";
+
+describe("desktop startup embedding warmup policy", () => {
+  it("defaults desktop startup to deferred background GGUF embedding warmup", () => {
+    const policy = resolveDesktopStartupEmbeddingWarmupPolicy({});
+
+    expect(policy.env).toEqual({ ELIZA_DEFER_LOCAL_EMBEDDING_WARMUP: "1" });
+    expect(policy.effective).toBe("deferred background");
+    expect(policy.source).toContain("desktop dev fast startup");
+  });
+
+  it("skips startup embedding warmup by default in CI", () => {
+    const policy = resolveDesktopStartupEmbeddingWarmupPolicy({ CI: "true" });
+
+    expect(policy.env).toEqual({ ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP: "1" });
+    expect(policy.effective).toBe("skipped");
+    expect(policy.source).toContain("CI");
+  });
+
+  it("allows explicit startup embedding warmup opt-in", () => {
+    const policy = resolveDesktopStartupEmbeddingWarmupPolicy({
+      ELIZA_ENABLE_STARTUP_LOCAL_EMBEDDING_WARMUP: "1",
+    });
+
+    expect(policy.env).toEqual({});
+    expect(policy.effective).toBe("startup background");
+    expect(policy.source).toContain(
+      "ELIZA_ENABLE_STARTUP_LOCAL_EMBEDDING_WARMUP=1",
+    );
+  });
+
+  it("preserves an explicit skip override ahead of the opt-in alias", () => {
+    const policy = resolveDesktopStartupEmbeddingWarmupPolicy({
+      ELIZA_ENABLE_STARTUP_LOCAL_EMBEDDING_WARMUP: "1",
+      ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP: "true",
+    });
+
+    expect(policy.env).toEqual({
+      ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP: "true",
+    });
+    expect(policy.effective).toBe("skipped");
+    expect(policy.source).toContain("ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP=true");
+  });
+
+  it("preserves an explicit false skip override", () => {
+    const policy = resolveDesktopStartupEmbeddingWarmupPolicy({
+      ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP: "0",
+    });
+
+    expect(policy.env).toEqual({ ELIZA_SKIP_LOCAL_EMBEDDING_WARMUP: "0" });
+    expect(policy.effective).toBe("startup background");
+  });
+});

package/scripts/lib/duet-bridge.d.mts

@@ -0,0 +1,63 @@
+/**
+ * Type declarations for `duet-bridge.mjs` — the in-memory audio routing for the
+ * two-agents-talking-endlessly harness (`voice-duet.mjs`) and the
+ * `voice-duet.e2e.test.ts` stub-backend wiring path.
+ */
+
+/**
+ * Linear-interpolation resample of mono `Float32Array` PCM. Returns the input
+ * unchanged when the rates already match.
+ */
+export function resampleLinear(
+  pcm: Float32Array,
+  fromRate: number,
+  toRate: number,
+): Float32Array;
+
+/**
+ * One direction of the duet cross-ring: takes a producing agent's TTS PCM,
+ * resamples 24 kHz → 16 kHz, and forwards each chunk to the consumer's mic.
+ */
+export class DuetSink {
+  constructor(
+    onResampled: (pcm: Float32Array, sampleRate: number) => void,
+    opts?: { targetRate?: number; sourceRate?: number },
+  );
+  onResampled: (pcm: Float32Array, sampleRate: number) => void;
+  targetRate: number;
+  sourceRate: number;
+  write(pcm: Float32Array, sampleRate?: number): void;
+  drain(): void;
+  bufferedSamples(): number;
+  /** Total INPUT samples written to this sink (at the source rate). */
+  totalWritten(): number;
+  /** Total OUTPUT samples forwarded (at `targetRate`). */
+  totalForwarded(): number;
+  /** `Date.now()` of the most recent `write()`, or 0 if none. */
+  lastWriteAt(): number;
+  /** Seconds of audio (at the source rate) forwarded so far. */
+  forwardedSeconds(): number;
+}
+
+/**
+ * The duet's two cross-rings: `aToB` carries agent A's speech into agent B's
+ * ear; `bToA` carries B's reply back to A.
+ */
+export class DuetAudioBridge {
+  constructor(args: {
+    micSourceA: { push(pcm: Float32Array): void };
+    micSourceB: { push(pcm: Float32Array): void };
+    opts?: {
+      ringMs?: number;
+      targetRate?: number;
+      onForward?: (dir: "aToB" | "bToA", pcm: Float32Array) => void;
+    };
+  });
+  ringMs: number;
+  aToB: DuetSink;
+  bToA: DuetSink;
+  /** The sink the harness assigns to engine A's scheduler. */
+  sinkForA(): DuetSink;
+  /** The sink the harness assigns to engine B's scheduler. */
+  sinkForB(): DuetSink;
+}

package/scripts/lib/duet-bridge.mjs

@@ -0,0 +1,193 @@
+/**
+ * Audio routing for the two-agents-talking-endlessly harness (`voice-duet.mjs`).
+ *
+ * Both agents are local processes, so the duet NEVER goes through speakers /
+ * mic — agent A's TTS PCM is resampled and pushed straight into agent B's
+ * `PushMicSource` via an in-memory ring, and symmetrically B → A.
+ *
+ *   A.scheduler.sink ── DuetSink(aToB) ──→ PcmRingBuffer ──→ B.micSource.push
+ *   B.scheduler.sink ── DuetSink(bToA) ──→ PcmRingBuffer ──→ A.micSource.push
+ *
+ * The TTS emits 24 kHz mono; the VAD + Qwen3-ASR want 16 kHz mono — one
+ * linear-interpolation resample in the `DuetSink`, zero file writes.
+ *
+ * `DuetSink` also reports the **`peer-utterance-end`** instant: when the
+ * producing agent's TTS has settled (its turn is done AND no PCM has arrived
+ * for `quietGapMs`), the consuming agent's tracer should mark
+ * `peer-utterance-end` — that is the headline `t0` for the duet round-trip.
+ * The harness drives that explicitly off `bridge.settle()`; `DuetSink` exposes
+ * `lastWriteAt()` / `totalWritten()` so the harness can detect "drained".
+ *
+ * Pure JS, no FFI, no native deps — used both by the live harness and by
+ * `voice-duet.e2e.test.ts`'s stub-backend wiring path.
+ */
+
+const TTS_SAMPLE_RATE = 24_000;
+const ASR_SAMPLE_RATE = 16_000;
+
+/**
+ * Linear-interpolation resample of mono `Float32Array` PCM. Cheap and good
+ * enough for a benchmark / VAD-feed (the ASR/VAD are robust to it). Returns the
+ * input unchanged when the rates already match.
+ *
+ * @param {Float32Array} pcm
+ * @param {number} fromRate
+ * @param {number} toRate
+ * @returns {Float32Array}
+ */
+export function resampleLinear(pcm, fromRate, toRate) {
+  if (!(pcm instanceof Float32Array)) {
+    throw new TypeError("resampleLinear: pcm must be a Float32Array");
+  }
+  if (fromRate <= 0 || toRate <= 0) {
+    throw new RangeError("resampleLinear: rates must be positive");
+  }
+  if (fromRate === toRate || pcm.length === 0) return pcm;
+  const ratio = fromRate / toRate;
+  const outLen = Math.max(1, Math.floor(pcm.length / ratio));
+  const out = new Float32Array(outLen);
+  for (let i = 0; i < outLen; i++) {
+    const srcPos = i * ratio;
+    const i0 = Math.floor(srcPos);
+    const i1 = Math.min(pcm.length - 1, i0 + 1);
+    const frac = srcPos - i0;
+    out[i] = pcm[i0] * (1 - frac) + pcm[i1] * frac;
+  }
+  return out;
+}
+
+/**
+ * An `AudioSink` (the shape `VoiceScheduler` writes PCM into) that resamples
+ * each chunk to `targetRate` and forwards it to a callback (the harness pushes
+ * it into the peer's ring / `PushMicSource`). Tracks last-write time and total
+ * samples so the harness can detect "the producer has drained".
+ */
+export class DuetSink {
+  /**
+   * @param {(pcm: Float32Array, sampleRate: number) => void} onResampled
+   *   called once per chunk with PCM at `targetRate`.
+   * @param {object} [opts]
+   * @param {number} [opts.targetRate] default 16 kHz (the ASR/VAD rate).
+   * @param {number} [opts.sourceRate] default 24 kHz (the TTS rate). Each
+   *   `write` may carry its own rate; this is only the assumed default when a
+   *   write doesn't say.
+   */
+  constructor(onResampled, opts = {}) {
+    if (typeof onResampled !== "function") {
+      throw new TypeError("DuetSink: onResampled must be a function");
+    }
+    this.onResampled = onResampled;
+    this.targetRate = opts.targetRate ?? ASR_SAMPLE_RATE;
+    this.sourceRate = opts.sourceRate ?? TTS_SAMPLE_RATE;
+    this._totalWritten = 0;
+    this._totalOut = 0;
+    this._lastWriteAt = 0;
+    this._buffered = 0;
+  }
+
+  /** @param {Float32Array} pcm @param {number} sampleRate */
+  write(pcm, sampleRate) {
+    if (!(pcm instanceof Float32Array) || pcm.length === 0) return;
+    const sr =
+      Number.isFinite(sampleRate) && sampleRate > 0
+        ? sampleRate
+        : this.sourceRate;
+    this._totalWritten += pcm.length;
+    this._buffered += pcm.length;
+    this._lastWriteAt = Date.now();
+    const resampled = resampleLinear(pcm, sr, this.targetRate);
+    this._totalOut += resampled.length;
+    this.onResampled(resampled, this.targetRate);
+  }
+
+  drain() {
+    this._buffered = 0;
+  }
+
+  bufferedSamples() {
+    return this._buffered;
+  }
+
+  /** Total INPUT samples written to this sink (at the source rate). */
+  totalWritten() {
+    return this._totalWritten;
+  }
+
+  /** Total OUTPUT samples forwarded (at `targetRate`). */
+  totalForwarded() {
+    return this._totalOut;
+  }
+
+  /** `Date.now()` of the most recent `write()`, or 0 if none. */
+  lastWriteAt() {
+    return this._lastWriteAt;
+  }
+
+  /** Seconds of audio (at the source rate) forwarded so far. */
+  forwardedSeconds() {
+    return this._totalOut / this.targetRate;
+  }
+}
+
+/**
+ * The duet's two cross-rings: `aToB` carries agent A's speech into agent B's
+ * ear; `bToA` carries B's reply back to A. Each direction is one `DuetSink`
+ * plus the peer's `PushMicSource` it feeds. The harness wires the engines'
+ * scheduler sinks to these and pumps `PushMicSource` frames into the VADs.
+ *
+ * `ringMs` sizes the implicit buffering (the `PushMicSource` re-frames; the
+ * "ring" here is just the sink + push pair — bounded by the producer pacing).
+ * It's a sweep knob (`--ring-ms`); a too-small value would underrun a real
+ * streaming TTS, a too-big one adds latency. Recorded in the report.
+ */
+export class DuetAudioBridge {
+  /**
+   * @param {object} args
+   * @param {object} args.micSourceA  agent A's `PushMicSource`.
+   * @param {object} args.micSourceB  agent B's `PushMicSource`.
+   * @param {object} [args.opts]
+   * @param {number} [args.opts.ringMs] target cross-ring size in ms (sweep knob).
+   * @param {number} [args.opts.targetRate] ASR/VAD rate (default 16 kHz).
+   * @param {(dir: "aToB"|"bToA", pcm: Float32Array) => void} [args.opts.onForward]
+   *   observability hook (the harness uses it to count PCM crossing each way).
+   */
+  constructor({ micSourceA, micSourceB, opts = {} }) {
+    this.ringMs = opts.ringMs ?? 200;
+    const targetRate = opts.targetRate ?? ASR_SAMPLE_RATE;
+    const onForward = opts.onForward;
+    // A speaks → resample → push into B's mic source.
+    this.aToB = new DuetSink(
+      (pcm) => {
+        onForward?.("aToB", pcm);
+        try {
+          micSourceB.push(pcm);
+        } catch {
+          /* a stopped mic source ignores pushes — fine */
+        }
+      },
+      { targetRate },
+    );
+    // B replies → resample → push into A's mic source.
+    this.bToA = new DuetSink(
+      (pcm) => {
+        onForward?.("bToA", pcm);
+        try {
+          micSourceA.push(pcm);
+        } catch {
+          /* ignore */
+        }
+      },
+      { targetRate },
+    );
+  }
+
+  /** The sink the harness assigns to engine A's scheduler. */
+  sinkForA() {
+    return this.aToB;
+  }
+
+  /** The sink the harness assigns to engine B's scheduler. */
+  sinkForB() {
+    return this.bToA;
+  }
+}

package/scripts/lib/node-path-env.mjs

@@ -2,10 +2,12 @@ import path from "node:path";
 
 export function extendNodePathEnv(baseEnv, rootDir) {
   const rootModules = path.join(rootDir, "node_modules");
+  const bunModules = path.join(rootModules, ".bun", "node_modules");
+  const modulePaths = [rootModules, bunModules];
   return {
     ...baseEnv,
     NODE_PATH: baseEnv.NODE_PATH
-      ? `${rootModules}${path.delimiter}${baseEnv.NODE_PATH}`
-      : rootModules,
+      ? `${modulePaths.join(path.delimiter)}${path.delimiter}${baseEnv.NODE_PATH}`
+      : modulePaths.join(path.delimiter),
   };
 }