@vellumai/assistant 0.6.3 → 0.6.5

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

@@ -17,8 +17,10 @@ import {
 } from "../daemon/conversation.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { CallSiteRoutingProvider } from "../providers/call-site-routing.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 +90,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;
 }
@@ -148,7 +156,9 @@ export class SubagentManager {
    * `onSubagentFinished`.  Used by fork spawn to resolve the parent's
    * system prompt when `config.parentSystemPrompt` is not provided.
    */
-  resolveParentConversation?: (conversationId: string) => Conversation | undefined;
+  resolveParentConversation?: (
+    conversationId: string,
+  ) => Conversation | undefined;
 
   // ── Spawn ───────────────────────────────────────────────────────────
 
@@ -204,7 +214,19 @@ export class SubagentManager {
 
     // ── Build conversation dependencies ─────────────────────────────
     const appConfig = getConfig();
-    let provider = getProvider(appConfig.services.inference.provider);
+    let provider = getProvider(appConfig.llm.default.provider);
+    // Per-call `options.config.callSite` (e.g. `subagentSpawn`) can resolve
+    // to a provider name that differs from `llm.default.provider`. Wrap the
+    // default provider so the actual transport routes correctly per call,
+    // rather than only forwarding metadata to the default's HTTP client.
+    // See `providers/call-site-routing.ts`.
+    provider = new CallSiteRoutingProvider(provider, (name) => {
+      try {
+        return getProvider(name);
+      } catch {
+        return undefined;
+      }
+    });
     const { rateLimit } = appConfig;
     if (rateLimit.maxRequestsPerMinute > 0) {
       provider = new RateLimitProvider(
@@ -220,19 +242,21 @@ export class SubagentManager {
       if (config.parentSystemPrompt) {
         systemPrompt = config.parentSystemPrompt;
       } else if (this.resolveParentConversation) {
-        const parentConv = this.resolveParentConversation(config.parentConversationId);
+        const parentConv = this.resolveParentConversation(
+          config.parentConversationId,
+        );
         const resolved = parentConv?.getCurrentSystemPrompt();
         if (!resolved) {
           throw new Error(
             "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
-            "nor resolveParentConversation yielded one.",
+              "nor resolveParentConversation yielded one.",
           );
         }
         systemPrompt = resolved;
       } else {
         throw new Error(
           "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
-          "is set nor resolveParentConversation callback is wired.",
+            "is set nor resolveParentConversation callback is wired.",
         );
       }
     } else {
@@ -240,7 +264,7 @@ export class SubagentManager {
         config.systemPromptOverride ??
         buildSubagentSystemPrompt({ ...config, id: subagentId }, role);
     }
-    const maxTokens = appConfig.maxTokens;
+    const maxTokens = appConfig.llm.default.maxTokens;
     const workingDir = getSandboxWorkingDir();
 
     const memoryPolicy: ConversationMemoryPolicy = isFork
@@ -259,10 +283,16 @@ export class SubagentManager {
     const now = Date.now();
     // For forks, default sendResultToUser to false (silent) unless explicitly true.
     const resolvedSendResultToUser = isFork
-      ? (config.sendResultToUser === true ? true : false)
+      ? config.sendResultToUser === true
+        ? true
+        : false
       : config.sendResultToUser;
     const state: SubagentState = {
-      config: { ...config, id: subagentId, sendResultToUser: resolvedSendResultToUser },
+      config: {
+        ...config,
+        id: subagentId,
+        sendResultToUser: resolvedSendResultToUser,
+      },
       status: "pending",
       conversationId: conversationRecord.id,
       isFork,
@@ -406,7 +436,9 @@ export class SubagentManager {
       // This prepends the inherited context so the fork has full conversational
       // awareness while the objective becomes the latest user turn.
       if (managed.state.isFork && managed.state.config.parentMessages) {
-        conversation.injectInheritedContext(managed.state.config.parentMessages);
+        conversation.injectInheritedContext(
+          managed.state.config.parentMessages,
+        );
         // Release the parent message arrays now that they've been injected — holding
         // them in SubagentState.config would retain significant memory until the TTL
         // sweep disposes this entry (up to 30 minutes for terminal subagents).
@@ -432,7 +464,9 @@ export class SubagentManager {
           ].join("\n")
         : objective;
       const messageId = await conversation.persistUserMessage(message, []);
-      await conversation.runAgentLoop(message, messageId, onEvent);
+      await conversation.runAgentLoop(message, messageId, onEvent, {
+        callSite: "subagentSpawn",
+      });
 
       // Agent loop completed successfully.
       // Copy usage stats from the conversation before sending status (which includes usage).
@@ -464,11 +498,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 +548,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
@@ -616,7 +661,9 @@ export class SubagentManager {
       const conversation = managed.conversation;
       const messageId = await conversation.persistUserMessage(trimmed, []);
       conversation
-        .runAgentLoop(trimmed, messageId, onEvent)
+        .runAgentLoop(trimmed, messageId, onEvent, {
+          callSite: "subagentSpawn",
+        })
         .catch((err) => {
           log.error({ subagentId, err }, "Subagent message processing failed");
         });
@@ -704,7 +751,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;
@@ -876,8 +929,7 @@ export class SubagentManager {
     const prefix = managed.state.isFork ? "Fork" : "Subagent";
     let notificationString = `[${prefix} "${info.label}" — ${urgency}] ${message}`;
     if (urgency === "blocked") {
-      notificationString +=
-        `\nUse subagent_message to send guidance to this ${prefix.toLowerCase()}.`;
+      notificationString += `\nUse subagent_message to send guidance to this ${prefix.toLowerCase()}.`;
     }
 
     try {

package/src/tasks/ephemeral-permissions.ts

@@ -1,5 +1,10 @@
+import { SCOPED_TOOLS } from "@vellumai/ces-contracts";
+
 import type { TrustRule } from "../permissions/types.js";
 
+/** O(1) lookup set for scoped tool names. */
+const SCOPED_TOOLS_SET: ReadonlySet<string> = new Set(SCOPED_TOOLS);
+
 // In-memory map: task_run_id -> ephemeral rules
 const activeTaskRules = new Map<string, TrustRule[]>();
 
@@ -29,9 +34,8 @@ export function clearTaskRunRules(taskRunId: string): void {
  * default rules (50) so pre-approved tools aren't shadowed by default
  * `ask` rules (which would trigger prompting and auto-deny in
  * non-interactive task runs), but below user rules (100) so user deny
- * rules still take precedence. `allowHighRisk` is intentionally omitted:
- * high-risk tool invocations still flow through the normal risk-classification
- * path rather than being blanket-approved.
+ * rules still take precedence. High-risk tool invocations still flow through
+ * the normal risk-classification path rather than being blanket-approved.
  */
 export function buildTaskRules(
   taskRunId: string,
@@ -42,7 +46,8 @@ export function buildTaskRules(
     id: `ephemeral:${taskRunId}:${tool}`,
     tool,
     pattern: "**",
-    scope: "everywhere",
+    // Only include scope for scoped tools — non-scoped tools don't carry scope.
+    ...(SCOPED_TOOLS_SET.has(tool) ? { scope: "everywhere" } : {}),
     decision: "allow" as const,
     priority: 75,
     createdAt: Date.now(),

package/src/telemetry/usage-telemetry-reporter.ts

@@ -45,6 +45,7 @@ const CHECKPOINT_KEY_LIFECYCLE_WATERMARK =
 const CHECKPOINT_KEY_LIFECYCLE_WATERMARK_ID =
   "telemetry:lifecycle:last_reported_id";
 const REPORT_INTERVAL_MS = 5 * 60 * 1000;
+const INITIAL_FLUSH_DELAY_MS = 30_000; // Delay first flush to let CES handshake complete
 const BATCH_SIZE = 500;
 const MAX_CONSECUTIVE_BATCHES = 10;
 const TELEMETRY_PATH = "/v1/telemetry/ingest/";
@@ -54,13 +55,21 @@ const TELEMETRY_PATH = "/v1/telemetry/ingest/";
 // ---------------------------------------------------------------------------
 
 export class UsageTelemetryReporter {
+  private initialFlushTimer: ReturnType<typeof setTimeout> | null = null;
   private timer: ReturnType<typeof setInterval> | null = null;
   private activeFlush: Promise<void> | null = null;
 
   start(): void {
-    this.flush().catch((err) => {
-      log.warn({ err }, "Initial usage telemetry flush failed");
-    });
+    // Delay the first flush to allow the credential infrastructure (CES
+    // handshake) to complete. Without this delay, VellumPlatformClient.create()
+    // returns null because the credential backend hasn't resolved yet, causing
+    // telemetry to fall back to anonymous mode permanently.
+    this.initialFlushTimer = setTimeout(() => {
+      this.initialFlushTimer = null;
+      this.flush().catch((err) => {
+        log.warn({ err }, "Initial usage telemetry flush failed");
+      });
+    }, INITIAL_FLUSH_DELAY_MS);
     this.timer = setInterval(() => {
       this.flush().catch((err) => {
         log.warn({ err }, "Scheduled usage telemetry flush failed");
@@ -69,6 +78,10 @@ export class UsageTelemetryReporter {
   }
 
   async stop(): Promise<void> {
+    if (this.initialFlushTimer) {
+      clearTimeout(this.initialFlushTimer);
+      this.initialFlushTimer = null;
+    }
     if (this.timer) {
       clearInterval(this.timer);
       this.timer = null;
@@ -157,6 +170,15 @@ export class UsageTelemetryReporter {
       // Resolve auth context — authenticated path uses client, anonymous path
       // sends unauthenticated (telemetry endpoints are public).
       const client = await VellumPlatformClient.create();
+      log.debug(
+        {
+          authenticated: !!client,
+          usageCount: events.length,
+          turnCount: turnEvents.length,
+          lifecycleCount: lifecycleEvents.length,
+        },
+        "Telemetry flush: resolved auth context",
+      );
 
       // Build payload
       const typedEvents: TelemetryEvent[] = [
@@ -222,9 +244,9 @@ export class UsageTelemetryReporter {
       }
 
       if (!resp.ok) {
-        await resp.text(); // consume body to release connection
+        const body = await resp.text();
         log.warn(
-          { status: resp.status },
+          { status: resp.status, authenticated: !!client, body },
           "Usage telemetry POST failed — will retry next cycle",
         );
         return;

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);
+  });
+});