@vellumai/assistant 0.6.3 → 0.6.4

package/src/stt/wav-encoder.ts

@@ -0,0 +1,175 @@
+/**
+ * Shared PCM16LE-to-WAV utility for STT streaming adapters.
+ *
+ * Wraps raw PCM16LE audio bytes in a valid 44-byte RIFF/WAVE header so that
+ * STT providers that require WAV input (e.g. OpenAI Whisper) can consume
+ * audio captured from streaming sessions.
+ *
+ * This helper is intentionally decoupled from any specific provider adapter
+ * so it can be reused across batch and streaming transcription paths.
+ */
+
+// ---------------------------------------------------------------------------
+// Format options
+// ---------------------------------------------------------------------------
+
+/**
+ * Audio format parameters for the PCM-to-WAV encoder.
+ *
+ * Adapters pass the hardware sample rate captured during the streaming
+ * handshake so the WAV header accurately describes the audio data.
+ */
+export interface WavFormatOptions {
+  /** Sample rate in Hz (e.g. 16000, 44100, 48000). Must be positive. */
+  sampleRate: number;
+  /** Number of audio channels (1 = mono, 2 = stereo). Must be positive. */
+  channels: number;
+  /**
+   * Bits per sample. Defaults to 16 (PCM16LE).
+   *
+   * Only 8, 16, 24, and 32 are supported — these are the standard PCM bit
+   * depths that fit evenly into whole bytes.
+   */
+  bitsPerSample?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+const SUPPORTED_BIT_DEPTHS = new Set([8, 16, 24, 32]);
+
+/**
+ * Validate format options and throw descriptive errors for invalid
+ * configurations. Called internally before encoding.
+ */
+function validateFormatOptions(options: WavFormatOptions): void {
+  const { sampleRate, channels, bitsPerSample = 16 } = options;
+
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+    throw new Error(
+      `Invalid sampleRate: ${sampleRate}. Must be a positive finite number.`,
+    );
+  }
+
+  if (
+    !Number.isFinite(channels) ||
+    channels <= 0 ||
+    !Number.isInteger(channels)
+  ) {
+    throw new Error(
+      `Invalid channels: ${channels}. Must be a positive integer.`,
+    );
+  }
+
+  if (!SUPPORTED_BIT_DEPTHS.has(bitsPerSample)) {
+    throw new Error(
+      `Unsupported bitsPerSample: ${bitsPerSample}. ` +
+        `Supported values: ${[...SUPPORTED_BIT_DEPTHS].join(", ")}.`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// WAV header constants
+// ---------------------------------------------------------------------------
+
+/** Total size of the RIFF/WAVE header for PCM data. */
+const WAV_HEADER_SIZE = 44;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap raw PCM audio bytes in a valid 44-byte RIFF/WAVE header.
+ *
+ * @param pcmData - Raw PCM audio data (e.g. PCM16LE samples).
+ * @param options - Audio format options describing the PCM data.
+ * @returns A `Buffer` containing a complete WAV file (header + PCM payload).
+ *
+ * @example
+ * ```ts
+ * const wav = encodePcm16LeToWav(rawPcmBuffer, {
+ *   sampleRate: 16000,
+ *   channels: 1,
+ * });
+ * ```
+ */
+export function encodePcm16LeToWav(
+  pcmData: Buffer,
+  options: WavFormatOptions,
+): Buffer {
+  validateFormatOptions(options);
+
+  const { sampleRate, channels, bitsPerSample = 16 } = options;
+
+  const bytesPerSample = bitsPerSample / 8;
+  const blockAlign = channels * bytesPerSample;
+  const byteRate = sampleRate * blockAlign;
+  const dataSize = pcmData.length;
+  const fileSize = WAV_HEADER_SIZE + dataSize;
+
+  const buffer = Buffer.alloc(fileSize);
+  let offset = 0;
+
+  // ---- RIFF chunk descriptor ----
+  // ChunkID: "RIFF"
+  buffer.write("RIFF", offset, "ascii");
+  offset += 4;
+
+  // ChunkSize: file size minus 8 bytes (RIFF header)
+  buffer.writeUInt32LE(fileSize - 8, offset);
+  offset += 4;
+
+  // Format: "WAVE"
+  buffer.write("WAVE", offset, "ascii");
+  offset += 4;
+
+  // ---- fmt sub-chunk ----
+  // Subchunk1ID: "fmt "
+  buffer.write("fmt ", offset, "ascii");
+  offset += 4;
+
+  // Subchunk1Size: 16 for PCM
+  buffer.writeUInt32LE(16, offset);
+  offset += 4;
+
+  // AudioFormat: 1 = PCM (uncompressed)
+  buffer.writeUInt16LE(1, offset);
+  offset += 2;
+
+  // NumChannels
+  buffer.writeUInt16LE(channels, offset);
+  offset += 2;
+
+  // SampleRate
+  buffer.writeUInt32LE(sampleRate, offset);
+  offset += 4;
+
+  // ByteRate = SampleRate * NumChannels * BitsPerSample / 8
+  buffer.writeUInt32LE(byteRate, offset);
+  offset += 4;
+
+  // BlockAlign = NumChannels * BitsPerSample / 8
+  buffer.writeUInt16LE(blockAlign, offset);
+  offset += 2;
+
+  // BitsPerSample
+  buffer.writeUInt16LE(bitsPerSample, offset);
+  offset += 2;
+
+  // ---- data sub-chunk ----
+  // Subchunk2ID: "data"
+  buffer.write("data", offset, "ascii");
+  offset += 4;
+
+  // Subchunk2Size: size of the raw audio data
+  buffer.writeUInt32LE(dataSize, offset);
+  offset += 4;
+
+  // ---- PCM payload ----
+  pcmData.copy(buffer, offset);
+
+  return buffer;
+}

package/src/subagent/manager.ts

@@ -19,6 +19,7 @@ import type { ServerMessage } from "../daemon/message-protocol.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
 import { RateLimitProvider } from "../providers/ratelimit.js";
 import { getProvider } from "../providers/registry.js";
+import { createAbortReason } from "../util/abort-reasons.js";
 import { getLogger } from "../util/logger.js";
 import { getSandboxWorkingDir } from "../util/platform.js";
 import {
@@ -88,13 +89,19 @@ interface ManagedSubagent {
   /** Epoch ms after which this terminal entry can be removed by the TTL sweep. */
   retainedUntil?: number;
   /**
-   * Set to true when sendMessage enqueues a follow-up message while the
-   * initial objective loop is running.  runAgentLoop fires drainQueue without
-   * awaiting it, and drainQueue shift()s the item synchronously — so both
-   * hasQueuedMessages() and isProcessing() can return false while the drain
-   * is still active.  This flag lets the finally block in runSubagent defer
-   * the release to the TTL sweep rather than tearing down the conversation
-   * mid-drain.
+   * Sticky monotonic flag: set to true when sendMessage enqueues a follow-up
+   * message while a run is in progress, and never cleared. Needed because the
+   * drain dispatch is racy against the observation window around runAgentLoop's
+   * `finally`: drainQueue is async — it awaits buildPassthroughBatch (which
+   * awaits resolveSlash) before shifting anything — and runAgentLoop fires it
+   * without awaiting. So between the moment `finally` schedules drainQueue and
+   * the moment a queued item is actually dispatched by drainBatch /
+   * drainSingleMessage, `hasQueuedMessages()` and `isProcessing()` can each
+   * flip in either direction (queue empties mid-await, or `processing` flips
+   * false while items are still pending). Checking this sticky flag lets the
+   * finally block in runSubagent reason about "any queued work existed for
+   * this subagent during the run" without racing drain dispatch, and defer
+   * the release to the TTL sweep rather than tearing down mid-drain.
    */
   hadEnqueuedMessages?: boolean;
 }
@@ -464,11 +471,16 @@ export class SubagentManager {
       log.error({ subagentId, err }, "Subagent failed");
     } finally {
       // Release the heavyweight Conversation — output is already persisted in DB.
-      // runAgentLoop fires drainQueue without awaiting it, and drainQueue shift()s
-      // the next item synchronously — so both hasQueuedMessages() and
-      // isProcessing() can return false while a drain is still active.  Use the
-      // hadEnqueuedMessages flag (set in sendMessage) to detect this case and
-      // defer the release to the TTL sweep rather than tearing down mid-drain.
+      // drainQueue is async: it awaits buildPassthroughBatch (which awaits
+      // resolveSlash) before shifting anything, and runAgentLoop fires it
+      // without awaiting. That means by the time this finally runs, a drain
+      // may already be scheduled but not yet dispatched — so checking
+      // hasQueuedMessages() / isProcessing() here races the dispatch and can
+      // observe an empty queue (or `processing === false`) while queued work
+      // is still pending. The hadEnqueuedMessages flag (set in sendMessage)
+      // is a sticky monotonic marker that any queued work existed during this
+      // run, letting us defer the release to the TTL sweep rather than
+      // tearing down mid-drain.
       if (managed.hadEnqueuedMessages) {
         log.debug(
           { subagentId },
@@ -509,7 +521,13 @@ export class SubagentManager {
       return false;
     }
 
-    managed.conversation?.abort();
+    managed.conversation?.abort(
+      createAbortReason(
+        "subagent_aborted",
+        "SubagentManager.abort",
+        managed.conversation.conversationId,
+      ),
+    );
     managed.state.completedAt = Date.now();
     if (parentSendToClient) {
       // Route the status update through the stored parent sender so the
@@ -704,7 +722,13 @@ export class SubagentManager {
 
     if (managed.conversation) {
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
-        managed.conversation.abort();
+        managed.conversation.abort(
+          createAbortReason(
+            "subagent_aborted",
+            "SubagentManager.dispose",
+            managed.conversation.conversationId,
+          ),
+        );
       }
       managed.conversation.dispose();
       managed.conversation = null;

package/src/tools/browser/__tests__/browser-mode.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, test } from "bun:test";
+
+import type { BrowserMode } from "../browser-mode.js";
+import { normalizeBrowserMode } from "../browser-mode.js";
+
+describe("normalizeBrowserMode", () => {
+  // ── Defaults ──────────────────────────────────────────────────────────
+
+  test("undefined defaults to auto", () => {
+    const result = normalizeBrowserMode(undefined);
+    expect(result).toEqual({ mode: "auto" });
+  });
+
+  test("null defaults to auto", () => {
+    const result = normalizeBrowserMode(null);
+    expect(result).toEqual({ mode: "auto" });
+  });
+
+  test("empty string defaults to auto", () => {
+    const result = normalizeBrowserMode("");
+    expect(result).toEqual({ mode: "auto" });
+  });
+
+  // ── Canonical values ──────────────────────────────────────────────────
+
+  const canonicalValues: BrowserMode[] = [
+    "auto",
+    "extension",
+    "cdp-inspect",
+    "local",
+  ];
+
+  for (const value of canonicalValues) {
+    test(`canonical value "${value}" normalizes to itself`, () => {
+      const result = normalizeBrowserMode(value);
+      expect(result).toEqual({ mode: value });
+    });
+  }
+
+  // ── Aliases ───────────────────────────────────────────────────────────
+
+  test('alias "cdp-debugger" normalizes to "cdp-inspect"', () => {
+    const result = normalizeBrowserMode("cdp-debugger");
+    expect(result).toEqual({ mode: "cdp-inspect" });
+  });
+
+  test('alias "playwright" normalizes to "local"', () => {
+    const result = normalizeBrowserMode("playwright");
+    expect(result).toEqual({ mode: "local" });
+  });
+
+  // ── Case insensitivity ────────────────────────────────────────────────
+
+  test("uppercase input is normalized", () => {
+    const result = normalizeBrowserMode("AUTO");
+    expect(result).toEqual({ mode: "auto" });
+  });
+
+  test("mixed-case alias is normalized", () => {
+    const result = normalizeBrowserMode("Playwright");
+    expect(result).toEqual({ mode: "local" });
+  });
+
+  test("mixed-case cdp-debugger alias is normalized", () => {
+    const result = normalizeBrowserMode("CDP-Debugger");
+    expect(result).toEqual({ mode: "cdp-inspect" });
+  });
+
+  // ── Whitespace trimming ───────────────────────────────────────────────
+
+  test("leading/trailing whitespace is trimmed", () => {
+    const result = normalizeBrowserMode("  local  ");
+    expect(result).toEqual({ mode: "local" });
+  });
+
+  // ── Invalid values ────────────────────────────────────────────────────
+
+  test("unknown string returns error with accepted values", () => {
+    const result = normalizeBrowserMode("headless");
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error).toContain('Invalid browser_mode "headless"');
+      expect(result.error).toContain("Accepted values:");
+      expect(result.error).toContain("auto");
+      expect(result.error).toContain("extension");
+      expect(result.error).toContain("cdp-inspect");
+      expect(result.error).toContain("cdp-debugger");
+      expect(result.error).toContain("local");
+      expect(result.error).toContain("playwright");
+      expect(result.error).toContain("Aliases:");
+      expect(result.error).toContain("cdp-debugger->cdp-inspect");
+      expect(result.error).toContain("playwright->local");
+    }
+  });
+
+  test("non-string input returns error", () => {
+    const result = normalizeBrowserMode(42);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error).toContain('Invalid browser_mode "42"');
+    }
+  });
+
+  test("boolean input returns error", () => {
+    const result = normalizeBrowserMode(true);
+    expect("error" in result).toBe(true);
+    if ("error" in result) {
+      expect(result.error).toContain('Invalid browser_mode "true"');
+    }
+  });
+
+  // ── Error message determinism ─────────────────────────────────────────
+
+  test("error message is deterministic across calls", () => {
+    const r1 = normalizeBrowserMode("bogus");
+    const r2 = normalizeBrowserMode("bogus");
+    expect(r1).toEqual(r2);
+  });
+});

package/src/tools/browser/__tests__/browser-status.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import type { ToolContext } from "../../types.js";
+import {
+  BROWSER_STATUS_INPUT_FIELD,
+  BROWSER_STATUS_MODE,
+} from "../browser-status-constants.js";
+import { CdpError } from "../cdp-client/errors.js";
+
+type ProbeOutcome = "ok" | "fail";
+
+const probeOutcomes: Record<string, ProbeOutcome> = {
+  [BROWSER_STATUS_MODE.EXTENSION]: "ok",
+  [BROWSER_STATUS_MODE.CDP_INSPECT]: "ok",
+  [BROWSER_STATUS_MODE.LOCAL]: "ok",
+};
+
+const buildCandidateListMock = mock((_context: ToolContext) => [
+  { kind: BROWSER_STATUS_MODE.EXTENSION, reason: "mock" },
+  { kind: BROWSER_STATUS_MODE.CDP_INSPECT, reason: "mock" },
+  { kind: BROWSER_STATUS_MODE.LOCAL, reason: "mock" },
+]);
+
+const getCdpClientMock = mock(
+  (_context: ToolContext, options?: { mode?: string }) => {
+    const mode = (options?.mode ?? "auto") as string;
+    const outcome = probeOutcomes[mode];
+    return {
+      kind: mode,
+      conversationId: "test-conversation",
+      send: mock(async () => {
+        if (outcome === "fail") {
+          throw new CdpError("transport_error", `${mode} probe failed`);
+        }
+        return { result: { value: "complete" } };
+      }),
+      dispose: mock(() => {}),
+    };
+  },
+);
+
+mock.module("../cdp-client/factory.js", () => ({
+  buildCandidateList: buildCandidateListMock,
+  getCdpClient: getCdpClientMock,
+  isDesktopAutoCooldownActive: () => false,
+}));
+
+mock.module("../../../config/loader.js", () => ({
+  getConfig: () => ({
+    hostBrowser: {
+      cdpInspect: {
+        enabled: true,
+        host: "localhost",
+        port: 9222,
+        probeTimeoutMs: 500,
+        desktopAuto: { enabled: true, cooldownMs: 30_000 },
+      },
+    },
+  }),
+}));
+
+mock.module("../runtime-check.js", () => ({
+  checkBrowserRuntime: async () => ({
+    playwrightAvailable: true,
+    chromiumInstalled: true,
+    chromiumPath: "/tmp/chromium",
+    error: null,
+  }),
+}));
+
+mock.module("../browser-manager.js", () => ({
+  browserManager: {
+    getPreferredBackendKind: () => null,
+  },
+}));
+
+const { executeBrowserStatus } = await import("../browser-execution.js");
+
+function makeContext(overrides: Partial<ToolContext> = {}): ToolContext {
+  return {
+    workingDir: "/tmp",
+    conversationId: "test-conversation",
+    trustClass: "guardian",
+    ...overrides,
+  } as ToolContext;
+}
+
+describe("executeBrowserStatus", () => {
+  test("reports extension preflight-unavailable when no host browser proxy is bound", async () => {
+    const result = await executeBrowserStatus({}, makeContext());
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    const extension = payload.modes.find(
+      (m: { mode: string }) => m.mode === BROWSER_STATUS_MODE.EXTENSION,
+    );
+    expect(extension).toBeDefined();
+    expect(extension.available).toBe(false);
+    expect(extension.verified).toBe("preflight");
+  });
+
+  test("supports mode filtering via browser_mode", async () => {
+    const result = await executeBrowserStatus(
+      { browser_mode: BROWSER_STATUS_MODE.LOCAL },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+    const payload = JSON.parse(result.content);
+    expect(payload.checkedModes).toEqual([BROWSER_STATUS_MODE.LOCAL]);
+    expect(payload.modes).toHaveLength(1);
+    expect(payload.modes[0].mode).toBe(BROWSER_STATUS_MODE.LOCAL);
+  });
+
+  test("validates check_local_launch type", async () => {
+    const result = await executeBrowserStatus(
+      { [BROWSER_STATUS_INPUT_FIELD.CHECK_LOCAL_LAUNCH]: "yes" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain(
+      `${BROWSER_STATUS_INPUT_FIELD.CHECK_LOCAL_LAUNCH} must be a boolean`,
+    );
+  });
+});