@vellumai/assistant 0.6.4 → 0.6.5

package/src/providers/speech-to-text/xai.test.ts

@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { XAIProvider } from "./xai.js";
+
+const TEST_API_KEY = "xai-test-key-for-unit-tests";
+
+describe("XAIProvider", () => {
+  let originalFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test("successful transcription returns trimmed text", async () => {
+    globalThis.fetch = (async (
+      _url: string | URL | Request,
+      _init?: RequestInit,
+    ) => {
+      return new Response(JSON.stringify({ text: "  hello  " }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+    const result = await provider.transcribe(
+      Buffer.from("fake-audio"),
+      "audio/ogg",
+    );
+
+    expect(result).toEqual({ text: "hello" });
+  });
+
+  test("API error throws with status and partial body", async () => {
+    const errorBody = JSON.stringify({
+      error: {
+        message: "Invalid API key provided",
+        type: "invalid_request_error",
+      },
+    });
+
+    globalThis.fetch = (async (
+      _url: string | URL | Request,
+      _init?: RequestInit,
+    ) => {
+      return new Response(errorBody, {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+
+    await expect(
+      provider.transcribe(Buffer.from("fake-audio"), "audio/wav"),
+    ).rejects.toThrow("xAI STT error (401)");
+  });
+
+  test("sends correct FormData structure (no model field, file blob with correct MIME)", async () => {
+    let capturedBody: FormData | undefined;
+    let capturedHeaders: HeadersInit | undefined;
+
+    globalThis.fetch = (async (
+      url: string | URL | Request,
+      init?: RequestInit,
+    ) => {
+      capturedBody = init?.body as FormData;
+      capturedHeaders = init?.headers;
+      expect(url).toBe("https://api.x.ai/v1/stt");
+      expect(init?.method).toBe("POST");
+
+      return new Response(JSON.stringify({ text: "transcribed" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+    await provider.transcribe(Buffer.from("fake-audio"), "audio/mpeg");
+
+    // Verify authorization header
+    expect(capturedHeaders).toEqual({
+      Authorization: `Bearer ${TEST_API_KEY}`,
+    });
+
+    // Verify FormData contents
+    expect(capturedBody).toBeInstanceOf(FormData);
+
+    // xAI does not use a `model` field.
+    expect(capturedBody!.get("model")).toBeNull();
+
+    const file = capturedBody!.get("file");
+    expect(file).toBeInstanceOf(Blob);
+    expect((file as Blob).type).toBe("audio/mpeg");
+  });
+
+  test("returns empty text when API returns empty text field", async () => {
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({ text: "" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+    const result = await provider.transcribe(
+      Buffer.from("silence"),
+      "audio/wav",
+    );
+
+    expect(result).toEqual({ text: "" });
+  });
+
+  test("returns empty text when API response has no text property", async () => {
+    globalThis.fetch = (async () => {
+      return new Response(JSON.stringify({}), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+    const result = await provider.transcribe(
+      Buffer.from("silence"),
+      "audio/wav",
+    );
+
+    expect(result).toEqual({ text: "" });
+  });
+
+  test("error body is truncated to 300 characters", async () => {
+    const longBody = "x".repeat(500);
+
+    globalThis.fetch = (async () => {
+      return new Response(longBody, { status: 500 });
+    }) as unknown as typeof fetch;
+
+    const provider = new XAIProvider(TEST_API_KEY);
+
+    try {
+      await provider.transcribe(Buffer.from("audio"), "audio/wav");
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      const msg = (err as Error).message;
+      expect(msg).toContain("xAI STT error (500)");
+      // The body portion should be at most 300 chars
+      const bodyPart = msg.replace("xAI STT error (500): ", "");
+      expect(bodyPart.length).toBeLessThanOrEqual(300);
+    }
+  });
+});

package/src/providers/speech-to-text/xai.ts

@@ -0,0 +1,97 @@
+import type { SttTranscribeResult } from "../../stt/types.js";
+
+export const XAI_STT_URL = "https://api.x.ai/v1/stt";
+export const DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * Derive a filename extension from a MIME type so the xAI STT API can detect
+ * the audio format. Falls back to "audio" when the MIME type is unrecognised.
+ */
+export function extensionFromMime(mimeType: string): string {
+  const map: Record<string, string> = {
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/mpeg": "mp3",
+    "audio/mp3": "mp3",
+    "audio/ogg": "ogg",
+    "audio/opus": "opus",
+    "audio/webm": "webm",
+    "audio/mp4": "m4a",
+    "audio/x-m4a": "m4a",
+    "audio/flac": "flac",
+  };
+  const base = mimeType.split(";")[0].trim().toLowerCase();
+  return map[base] ?? "audio";
+}
+
+/**
+ * Build a FormData payload for the xAI `/v1/stt` endpoint.
+ *
+ * xAI does not require a `model` field. The xAI docs explicitly require the
+ * `file` field to be appended LAST in the multipart body, so we only append
+ * the file here (no other fields in v1).
+ */
+export function buildXaiFormData(audio: Buffer, mimeType: string): FormData {
+  const ext = extensionFromMime(mimeType);
+
+  const formData = new FormData();
+  // xAI requires the `file` field to be LAST in the multipart body.
+  formData.append(
+    "file",
+    new Blob([new Uint8Array(audio)], { type: mimeType }),
+    `audio.${ext}`,
+  );
+
+  return formData;
+}
+
+/**
+ * Send audio to the xAI STT API and return the transcribed text.
+ *
+ * xAI returns a richer shape (`{ text, language, duration, words }`) — we only
+ * consume `text`.
+ */
+export async function xaiTranscribe(
+  apiKey: string,
+  audio: Buffer,
+  mimeType: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const formData = buildXaiFormData(audio, mimeType);
+
+  const effectiveSignal = signal ?? AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
+
+  const response = await fetch(XAI_STT_URL, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}` },
+    body: formData,
+    signal: effectiveSignal,
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `xAI STT error (${response.status}): ${body.slice(0, 300)}`,
+    );
+  }
+
+  const result = (await response.json()) as { text?: string };
+  return result.text?.trim() ?? "";
+}
+
+export class XAIProvider {
+  private readonly apiKey: string;
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async transcribe(
+    audio: Buffer,
+    mimeType: string,
+    signal?: AbortSignal,
+  ): Promise<SttTranscribeResult> {
+    const text = await xaiTranscribe(this.apiKey, audio, mimeType, signal);
+    return { text };
+  }
+}

package/src/providers/types.ts

@@ -1,3 +1,6 @@
+import type { LLMCallSite } from "../config/schemas/llm.js";
+import { ProviderError } from "../util/errors.js";
+
 export interface TextContent {
   type: "text";
   text: string;
@@ -126,12 +129,23 @@ export type ProviderEvent =
       toolUseId: string;
       input: Record<string, unknown>;
     }
-  | { type: "server_tool_complete"; toolUseId: string; isError: boolean; content?: unknown[] };
+  | {
+      type: "server_tool_complete";
+      toolUseId: string;
+      isError: boolean;
+      content?: unknown[];
+    };
 
 export interface SendMessageConfig {
   model?: string;
-  modelIntent?: ModelIntent;
-  effort?: "low" | "medium" | "high" | "max";
+  /**
+   * LLM call-site identifier. `RetryProvider` resolves
+   * provider/model/maxTokens/effort/speed/temperature/thinking/contextWindow
+   * via `resolveCallSiteConfig(callSite, config.llm)`, falling back to
+   * `llm.default` when no callSite-specific entry is present.
+   */
+  callSite?: LLMCallSite;
+  effort?: "low" | "medium" | "high" | "xhigh" | "max";
   speed?: "standard" | "fast";
   [key: string]: unknown;
 }
@@ -160,3 +174,79 @@ export interface Provider {
     options?: SendMessageOptions,
   ): Promise<ProviderResponse>;
 }
+
+// ── Context-overflow error ────────────────────────────────────────────
+
+export interface ContextOverflowErrorOptions {
+  /** Actual tokens the request was estimated/measured to consume, when the provider reports it. */
+  actualTokens?: number;
+  /** Context-window cap the provider enforced, when reported in the error body. */
+  maxTokens?: number;
+  /** HTTP status reported by the provider. Defaults to 400. */
+  statusCode?: number;
+  /** Underlying error to preserve the cause chain (standard Error.cause). */
+  cause?: unknown;
+}
+
+/**
+ * Thrown by provider clients when the request exceeded the model's context
+ * window (HTTP 400 `context_length_exceeded`, Anthropic's `prompt_too_long`,
+ * Gemini's resource-exhausted category, etc.).
+ *
+ * Extends `ProviderError` so existing `instanceof ProviderError` classifiers
+ * (`util/retry.ts`, `daemon/conversation-error.ts`) continue to see it as a
+ * typed 4xx provider error and apply the right policy. The
+ * `actualTokens`/`maxTokens` fields carry structured counts when the
+ * provider reports them, avoiding brittle regex parsing at the caller.
+ *
+ * A regex-on-message fallback still exists in
+ * `daemon/parse-actual-tokens-from-error.ts` as a safety net for adapters
+ * that rewrap the error (e.g. managed-proxy) before it reaches the agent
+ * loop.
+ */
+export class ContextOverflowError extends ProviderError {
+  public readonly actualTokens?: number;
+  public readonly maxTokens?: number;
+
+  constructor(
+    message: string,
+    provider: string,
+    options: ContextOverflowErrorOptions = {},
+  ) {
+    super(
+      message,
+      provider,
+      options.statusCode ?? 400,
+      options.cause !== undefined ? { cause: options.cause } : undefined,
+    );
+    this.name = "ContextOverflowError";
+    this.actualTokens = options.actualTokens;
+    this.maxTokens = options.maxTokens;
+  }
+}
+
+export function isContextOverflowError(
+  err: unknown,
+): err is ContextOverflowError {
+  return err instanceof ContextOverflowError;
+}
+
+/**
+ * Extract `actualTokens` / `maxTokens` from provider overflow messages of the
+ * form "N tokens > M maximum" or bare "N > M". Returns an empty object when
+ * neither count is parseable — callers should treat this as "matched the
+ * overflow signal but counts unknown".
+ */
+export function extractOverflowTokensFromMessage(message: string): {
+  actualTokens?: number;
+  maxTokens?: number;
+} {
+  const match = message.match(/(\d[\d,]*)\s*(?:tokens?\s*)?[>≥]\s*(\d[\d,]*)/i);
+  if (!match) return {};
+  const actual = parseInt(match[1].replace(/,/g, ""), 10);
+  const max = parseInt(match[2].replace(/,/g, ""), 10);
+  const out: { actualTokens?: number; maxTokens?: number } = {};
+  if (!isNaN(actual) && actual > 0) out.actualTokens = actual;
+  if (!isNaN(max) && max > 0) out.maxTokens = max;
+  return out;
+}

package/src/runtime/AGENTS.md

@@ -18,9 +18,9 @@ Approvals are **orthogonal to message sending**. The assistant asks for approval
 
 - **Discovery**: Clients discover pending approvals via SSE events (`confirmation_request`, `secret_request`) which include a `requestId`.
 - **Resolution**: Clients respond via standalone endpoints keyed by `requestId`:
-  - `POST /v1/confirm` — `{ requestId, decision, selectedPattern?, selectedScope? }`. Valid decisions: `"allow"`, `"allow_10m"`, `"allow_conversation"`, `"deny"`, `"always_allow"`, `"always_deny"`, `"always_allow_high_risk"`. For persistent decisions (`always_allow`, `always_deny`, `always_allow_high_risk`), `selectedPattern` and `selectedScope` are validated against the server-provided allowlist/scope options from the original confirmation request before trust rules are persisted.
+  - `POST /v1/confirm` — `{ requestId, decision, selectedPattern?, selectedScope? }`. Valid decisions: `"allow"`, `"allow_10m"`, `"allow_conversation"`, `"deny"`, `"always_allow"`, `"always_deny"`. For persistent decisions (`always_allow`, `always_deny`), `selectedPattern` and `selectedScope` are validated against the server-provided allowlist/scope options from the original confirmation request before trust rules are persisted.
   - `POST /v1/secret` — `{ requestId, value, delivery }`
-  - `POST /v1/trust-rules` — `{ requestId, pattern, scope, decision, allowHighRisk? }`. Validates pattern/scope against server-provided options. Does not resolve the confirmation itself.
+  - `POST /v1/trust-rules` — `{ requestId, pattern, scope, decision }`. Validates pattern/scope against server-provided options. Does not resolve the confirmation itself.
 - **Tracking**: The `pending-interactions` tracker (`assistant/src/runtime/pending-interactions.ts`) maps `requestId → conversation`. Use `register()` to track, `resolve()` to consume, `getByConversation()` to query.
 
 Do NOT couple approval handling to message sending. Do NOT add run/status tracking to the send path.

package/src/runtime/__tests__/agent-wake.test.ts

@@ -490,12 +490,53 @@ describe("wakeAgentForOpportunity", () => {
     expect(result.producedToolCalls).toBe(false);
   });
 
-  test("returns invoked: false when the conversation cannot be resolved", async () => {
+  test("returns invoked: false with reason 'not_found' when the conversation cannot be resolved", async () => {
     const result = await wakeAgentForOpportunity(
       { conversationId: "missing", hint: "x", source: "y" },
       { resolveTarget: async () => null },
     );
-    expect(result).toEqual({ invoked: false, producedToolCalls: false });
+    expect(result).toEqual({
+      invoked: false,
+      producedToolCalls: false,
+      reason: "not_found",
+    });
+  });
+
+  test("returns invoked: false with reason 'timeout' when the target stays busy past the wait-until-idle window", async () => {
+    // Resolver returns a target that is permanently `processing`. Fast-
+    // forward the injected `now` past the 30s deadline so waitUntilIdle
+    // returns false. Without the distinct `timeout` reason, callers
+    // cannot tell this case apart from "not_found".
+    const history: Message[] = [];
+    const target: WakeTarget = {
+      conversationId: "conv-busy",
+      agentLoop: { run: async () => history },
+      getMessages: () => history,
+      pushMessage: () => {},
+      emitAgentEvent: () => {},
+      isProcessing: () => true,
+      markProcessing: () => {},
+      persistTailMessage: async () => {},
+    };
+    let t = 0;
+    const now = () => {
+      // First call establishes the deadline at +30_000. Every subsequent
+      // call jumps past the deadline so the polling loop exits after one
+      // 50ms tick.
+      const v = t;
+      t += 31_000;
+      return v;
+    };
+
+    const result = await wakeAgentForOpportunity(
+      { conversationId: "conv-busy", hint: "x", source: "y" },
+      { resolveTarget: async () => target, now },
+    );
+    expect(result).toEqual({
+      invoked: false,
+      producedToolCalls: false,
+      reason: "timeout",
+    });
   });
 
   test("agent loop error is treated as a no-op", async () => {