@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/config/schemas/tts.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import { TTS_PROVIDER_IDS } from "../../tts/types.js";
+import { baseLanguageSubtag } from "../../util/language-subtag.js";
 import {
   DEFAULT_ELEVENLABS_VOICE_ID,
   VALID_CONVERSATION_TIMEOUTS,
@@ -14,6 +15,53 @@ import {
  * legacy top-level schemas (`elevenlabs.*`, `fishAudio.*`) so that
  * migration can copy values 1:1.
  */
+
+/**
+ * Optional per-language voice override map for a TTS provider block.
+ * Keys parse to lowercase base language subtags (e.g. "hi", "ja"); values
+ * are provider voice identifiers. Live voice consults the map when a turn's
+ * spoken language is known and no explicit voice was requested.
+ *
+ * Key normalization happens at parse time so runtime lookups are a single
+ * exact match: each key is lowercased, cut at the first `-`/`_`, and
+ * trimmed ("hi-IN" and "HI" both store as "hi"). Keys that normalize to
+ * the empty string are dropped; when two keys normalize to the same
+ * subtag, the first entry wins.
+ */
+function languageVoicesSchema(providerId: string, valuesDescription: string) {
+  return z
+    .record(
+      z.string({
+        error: `services.tts.providers.${providerId}.languageVoices keys must be strings`,
+      }),
+      z.string({
+        error: `services.tts.providers.${providerId}.languageVoices values must be strings`,
+      }),
+      {
+        error: `services.tts.providers.${providerId}.languageVoices must be an object mapping language subtags to voice identifiers`,
+      },
+    )
+    .transform((map) => {
+      const normalized = new Map<string, string>();
+      for (const [key, voice] of Object.entries(map)) {
+        const subtag = baseLanguageSubtag(key);
+        if (!subtag || normalized.has(subtag)) {
+          continue;
+        }
+        normalized.set(subtag, voice);
+      }
+      return Object.fromEntries(normalized);
+    })
+    .optional()
+    .describe(
+      "Per-language voice overrides for live voice. Keys are normalized on " +
+        'save to lowercase base language subtags ("hi-IN" and "HI" both ' +
+        `store as "hi"); ${valuesDescription} ` +
+        "Applied when the turn's spoken language matches an entry and no " +
+        "explicit voice is requested.",
+    );
+}
+
 export const TtsElevenLabsProviderConfigSchema = z
   .object({
     voiceId: z
@@ -79,6 +127,10 @@ export const TtsElevenLabsProviderConfigSchema = z
       )
       .default(30)
       .describe("Seconds of silence before voice conversation auto-ends"),
+    languageVoices: languageVoicesSchema(
+      "elevenlabs",
+      "values are ElevenLabs voice IDs.",
+    ),
   })
   .describe("ElevenLabs provider configuration under services.tts");
 
@@ -150,6 +202,10 @@ export const TtsDeepgramProviderConfigSchema = z
       })
       .default("mp3")
       .describe("Output audio format for call/runtime playback"),
+    languageVoices: languageVoicesSchema(
+      "deepgram",
+      "values are Deepgram TTS model identifiers (e.g. an aura-2 voice).",
+    ),
   })
   .describe("Deepgram provider configuration under services.tts");
 
@@ -221,6 +277,13 @@ const TtsVellumProviderConfigSchema = z
       .describe(
         "Managed TTS voice model (e.g. aura-2-thalia-en). Unset means the platform's default voice. The platform rejects voices it does not offer.",
       ),
+    languageVoices: languageVoicesSchema(
+      "vellum",
+      "values are managed TTS voice models (e.g. aura-2-thalia-en) and must " +
+        "be voices offered by the platform rate card: an unpriced model is " +
+        "rejected by the relay (missing_price), the same contract as " +
+        "services.tts.providers.vellum.model.",
+    ),
   })
   .describe("Vellum managed provider configuration under services.tts");
 

package/src/contacts/__tests__/guardian-delivery-reader.test.ts

@@ -44,6 +44,7 @@ import {
   getGuardianDeliveryFresh,
   guardianForChannel,
   invalidateGuardianDeliveryCache,
+  warmGuardianBindings,
 } from "../guardian-delivery-reader.js";
 
 const METHOD = "resolve_guardian_delivery";
@@ -299,3 +300,18 @@ describe("selectors", () => {
     expect(anyGuardian([])).toBeUndefined();
   });
 });
+
+describe("warmGuardianBindings", () => {
+  test("warms both the vellum-channel key and the unfiltered fallback key", async () => {
+    const keys: string[] = [];
+    await warmGuardianBindings(async (input) => {
+      keys.push(input?.channelTypes?.join(",") ?? "ALL");
+      return null;
+    });
+    // Both keys the sync persona resolvers read — peekGuardianForChannel
+    // ("vellum") and the peekAnyGuardian() fallback — must be warmed;
+    // warming only the channel key leaves the any-channel fallback cold for
+    // guardians bound on non-vellum channels.
+    expect(keys.sort()).toEqual(["ALL", "vellum"]);
+  });
+});

package/src/contacts/guardian-delivery-reader.ts

@@ -151,8 +151,8 @@ export async function getGuardianDelivery(input?: {
  * Returns the fresh cached list for the given channel filter, or `undefined`
  * when the cache is cold or expired. Used by sync hot paths (SSE subscribe)
  * that cannot await {@link getGuardianDelivery} but must resolve the SAME
- * gateway-owned principal the async paths land on. A cold/expired return lets
- * the caller fall back to the local store as before.
+ * gateway-owned principal the async paths land on. There is no fallback
+ * fetch: on a cold/expired cache the caller proceeds without a principal.
  */
 export function peekCachedGuardianDelivery(input?: {
   channelTypes?: string[];
@@ -181,6 +181,33 @@ export async function getGuardianDeliveryFresh(input?: {
   });
 }
 
+type GuardianDeliveryFetch = (input?: {
+  channelTypes?: string[];
+}) => Promise<unknown>;
+
+/**
+ * Warm both guardian-binding cache keys the sync persona resolvers read: the
+ * `"vellum"`-channel key for `peekGuardianForChannel("vellum")` and the
+ * unfiltered key for the `peekAnyGuardian()` fallback. Warming only one key
+ * still resolves `users/default.md` when the guardian lives on a non-vellum
+ * channel (phone / Telegram).
+ *
+ * Uses the FRESH reader so warmup bypasses a stale/empty cached entry: a
+ * gateway-side binding write (onboarding, rebind) does not invalidate the
+ * daemon cache, so a non-fresh read could return an empty binding cached
+ * before the guardian existed and freeze `users/default.md` until the TTL
+ * expires. The fresh reads repopulate the cache the sync `peek*` resolvers
+ * then read. Best-effort: the reader swallows failures.
+ */
+export async function warmGuardianBindings(
+  fetchDelivery: GuardianDeliveryFetch = getGuardianDeliveryFresh,
+): Promise<void> {
+  await Promise.all([
+    fetchDelivery({ channelTypes: ["vellum"] }),
+    fetchDelivery(),
+  ]);
+}
+
 /**
  * Clear ALL cached guardian deliveries so contact mutations refetch on the next
  * read. Called by {@link notifyContactsChanged} after a contact write, and

package/src/context/compactor.ts

@@ -865,10 +865,10 @@ function resolveTailFloorIndex(messages: Message[], tailIndex: number): number {
 // Retained-image hydration
 // ---------------------------------------------------------------------------
 
-function buildRetainedImageBlocks(
+async function buildRetainedImageBlocks(
   filenames: string[],
   manifest: ManifestEntry[],
-): { blocks: ImageContent[]; resolved: string[]; missing: string[] } {
+): Promise<{ blocks: ImageContent[]; resolved: string[]; missing: string[] }> {
   const blocks: ImageContent[] = [];
   const resolved: string[] = [];
   const missing: string[] = [];
@@ -887,7 +887,7 @@ function buildRetainedImageBlocks(
     // Run the same downscale pass the agent uses when first sending an
     // image. Without this, attachments that exceed the provider's per-image
     // byte limit (Anthropic: 5 MB) crash the next turn after compaction.
-    const optimized = optimizeImageForTransport(
+    const optimized = await optimizeImageForTransport(
       content.toString("base64"),
       sourceMime,
     );
@@ -1393,7 +1393,7 @@ export async function runAssistantDrivenCompaction(
     blocks: retainedImageBlocks,
     resolved,
     missing,
-  } = buildRetainedImageBlocks(parsed.retainedImageFilenames, manifest);
+  } = await buildRetainedImageBlocks(parsed.retainedImageFilenames, manifest);
   if (missing.length > 0) {
     log.warn(
       { missing },

package/src/context/post-turn-tool-result-truncation.ts

@@ -37,20 +37,43 @@ export const TRUNCATION_MARKER = "\u2014 full result:";
 export const TRUNCATION_EXEMPT_TOOLS = new Set<string>(["skill_load"]);
 
 /**
- * File-read tools that page spooled `.tool-results/` content back into context.
- * `file_read` reads inside the workspace; `host_file_read` reads anywhere on the
- * host. Both are (a) exempt from the result-time spool pass — re-stubbing a read
- * of a spooled file would hand back another stub, so the content could never be
- * paged back at all — and (b) recognized by {@link derefToolResultReReads}, so a
- * re-read of a spooled file collapses to a stub instead of duplicating content
- * already in context. Sharing one set keeps the two passes from drifting if a
- * new file-read tool is added.
+ * File-read tools that can page spooled `.tool-results/` content back into
+ * context. `file_read` reads inside the workspace; `host_file_read` reads
+ * anywhere on the host. A new file-read tool belongs here so
+ * {@link isSpooledToolResultRead} recognizes it.
  */
 export const FILE_READ_TOOL_NAMES = new Set<string>([
   "file_read",
   "host_file_read",
 ]);
 
+/**
+ * Whether a tool call is a file read aimed at a spooled `.tool-results/` file.
+ *
+ * Such a read is the model paging content back in, so both passes treat it
+ * specially: the result-time spool pass leaves it alone (re-stubbing it would
+ * write a fresh copy and hand back another stub, putting the content out of
+ * reach for good), and {@link derefToolResultReReads} collapses it at turn end
+ * (its prefix and suffix are already in context above). A file read aimed
+ * anywhere else is ordinary tool output and gets no such treatment.
+ */
+export function isSpooledToolResultRead(
+  toolName: string | undefined,
+  input: Record<string, unknown> | undefined,
+): boolean {
+  if (toolName === undefined || !FILE_READ_TOOL_NAMES.has(toolName)) {
+    return false;
+  }
+  const filePath = input?.path ?? input?.file_path;
+  if (typeof filePath !== "string") {
+    return false;
+  }
+  // The path in the stub comes from `join`, so it is backslash-separated on
+  // Windows. Compare on a normalized form: a missed match would let the spool
+  // pass stub this read and put the saved content permanently out of reach.
+  return filePath.replace(/\\/g, "/").includes(`/${TOOL_RESULT_DIR}/`);
+}
+
 /**
  * Build a map of tool_use_id -> originating tool name by walking the tool_use
  * blocks in assistant messages. A tool_result only carries `tool_use_id`, so
@@ -329,14 +352,7 @@ export function derefToolResultReReads(messages: Message[]): {
         continue;
       }
       const tu = block as ToolUseContent;
-      if (!FILE_READ_TOOL_NAMES.has(tu.name)) {
-        continue;
-      }
-      const filePath = tu.input.path ?? tu.input.file_path;
-      if (typeof filePath !== "string") {
-        continue;
-      }
-      if (filePath.includes(`/${TOOL_RESULT_DIR}/`)) {
+      if (isSpooledToolResultRead(tu.name, tu.input)) {
         reReadToolUseIds.add(tu.id);
       }
     }

package/src/context/strip-injections.ts

@@ -136,6 +136,48 @@ export function stripSpotlightInjections(messages: Message[]): Message[] {
   return stripUserTextBlocksByPrefix(messages, [MEMORY_SPOTLIGHT_MATCHER]);
 }
 
+/**
+ * Whether the TURN-STARTING user message carries a memory-v3
+ * `<memory_spotlight>` block.
+ *
+ * The spotlight is the only injected block that is strip-and-replaced from
+ * every user message each turn, so its presence is exactly what makes that
+ * message volatile across turns. Every other injected block (turn context,
+ * workspace, `<info>`, `<memory>` cards, NOW.md) is frozen into history and
+ * re-renders byte-identically, so a message without a spotlight is a stable
+ * cache anchor. Providers consume this through the `mutableLatestUserMessage`
+ * config field when placing cache breakpoints.
+ *
+ * The turn start is the most recent user message carrying TEXT content, which
+ * is the same message the Anthropic client anchors on. Tool-result messages
+ * are skipped: they are user-role but carry no injected blocks, and letting
+ * them answer this question would flip the signal to `false` partway through a
+ * tool loop. The provider would then mark the very same turn-start block at a
+ * different TTL than it did on the turn's first request, billing a second
+ * write for one reusable prefix. Anchoring on the turn start keeps the signal
+ * constant for every request in the turn.
+ *
+ * Detection uses {@link MEMORY_SPOTLIGHT_MATCHER}, the same full-wrapper
+ * matcher {@link stripSpotlightInjections} strips with, so the two can never
+ * disagree about which blocks are ephemeral.
+ */
+export function turnStartUserMessageHasSpotlight(messages: Message[]): boolean {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role !== "user") {
+      continue;
+    }
+    const textBlocks = message.content.filter((block) => block.type === "text");
+    if (textBlocks.length === 0) {
+      continue;
+    }
+    return textBlocks.some((block) =>
+      textBlockMatchesInjection(block.text, [MEMORY_SPOTLIGHT_MATCHER]),
+    );
+  }
+  return false;
+}
+
 /** `<NOW.md>` scratchpad prefixes (current tag, pre-line-limit variant, legacy `<now_scratchpad>`) — shared with `stripNowScratchpad` so the two strip paths can't drift. */
 export const NOW_SCRATCHPAD_STRIP_PREFIXES: InjectionMatcher[] = [
   "<NOW.md Always keep this up to date",

package/src/context/tool-result-spool.ts

@@ -4,8 +4,8 @@ import { join } from "node:path";
 import type { ContentBlock, ToolResultContent } from "../providers/types.js";
 import {
   buildTruncatedContent,
-  FILE_READ_TOOL_NAMES,
   getToolResultFilePath,
+  isSpooledToolResultRead,
   isTruncationEligible,
   TOOL_RESULT_DIR,
 } from "./post-turn-tool-result-truncation.js";
@@ -32,27 +32,32 @@ export const RESULT_TIME_SPOOL_EXEMPT_TOOLS = new Set<string>(["web_fetch"]);
 
 /**
  * Whether a tool result is eligible for the result-time spool/stub pass: the
- * post-turn pass's shared rules plus the AX-tree exemption, minus the file-read
- * tools ({@link FILE_READ_TOOL_NAMES}) and the explicit self-sized reads
- * ({@link RESULT_TIME_SPOOL_EXEMPT_TOOLS}). The file-read tools are the model's
- * only way to page spooled content back into context: stubbing a read of a
- * `.tool-results/` file would spool a fresh copy and hand back another stub, so
- * oversized content could never be read at all. Explicit reads are therefore
- * honored in full; the post-turn pass still truncates them at turn end, after
- * the model has consumed the content.
+ * post-turn pass's shared rules plus the AX-tree exemption, minus reads of
+ * already-spooled `.tool-results/` files ({@link isSpooledToolResultRead}) and
+ * the explicit self-sized reads ({@link RESULT_TIME_SPOOL_EXEMPT_TOOLS}).
+ *
+ * The spooled-read exemption is what keeps paging possible: a file read is the
+ * model's only way to pull spooled content back into context, so stubbing a
+ * read of a `.tool-results/` file would write a fresh copy and hand back
+ * another stub, putting that content out of reach for good. It is scoped by
+ * target path rather than by tool name, because a file read aimed anywhere
+ * else is ordinary oversized output with no such circularity, and exempting it
+ * keeps a whole file inline on every LLM call for the rest of the turn.
+ * Explicit self-sized reads are honored in full; the post-turn pass still
+ * truncates them at turn end, after the model has consumed the content.
  */
 function isSpoolEligible(
   tr: ToolResultContent,
   toolName: string | undefined,
+  toolInput: Record<string, unknown> | undefined,
 ): boolean {
   if (!isTruncationEligible(tr, toolName)) {
     return false;
   }
-  if (
-    toolName !== undefined &&
-    (FILE_READ_TOOL_NAMES.has(toolName) ||
-      RESULT_TIME_SPOOL_EXEMPT_TOOLS.has(toolName))
-  ) {
+  if (isSpooledToolResultRead(toolName, toolInput)) {
+    return false;
+  }
+  if (toolName !== undefined && RESULT_TIME_SPOOL_EXEMPT_TOOLS.has(toolName)) {
     return false;
   }
   if (tr.content.includes(AX_TREE_TAG)) {
@@ -72,8 +77,8 @@ function isSpoolEligible(
  * rewriting an earlier message between calls would invalidate the cache from
  * that point on every iteration. The model still gets the head/tail preview
  * plus the on-disk path, so it can page the full content back in with
- * `file_read` or `host_file_read` (whose results are exempt from this pass)
- * when it actually needs it.
+ * `file_read` or `host_file_read` (a read of a `.tool-results/` path is exempt
+ * from this pass) when it actually needs it.
  *
  * Uses the same file paths, stub bytes, and eligibility rules as
  * `postTurnTruncateToolResults`, whose `TRUNCATION_MARKER` guard then skips
@@ -89,7 +94,15 @@ export function spoolAndStubOversizedToolResults(
   blocks: ContentBlock[],
   options: {
     conversationDir: string;
-    toolNameById: (toolUseId: string) => string | undefined;
+    /**
+     * The originating call for a `tool_use_id`. A `tool_result` carries only
+     * the id, and eligibility turns on both the tool's name and the path it
+     * was pointed at, so the two travel together rather than as separate
+     * lookups that could disagree.
+     */
+    toolCallById: (
+      toolUseId: string,
+    ) => { name: string; input: Record<string, unknown> } | undefined;
   },
 ): number {
   let stubbedCount = 0;
@@ -98,7 +111,8 @@ export function spoolAndStubOversizedToolResults(
     if (block.type !== "tool_result") {
       continue;
     }
-    if (!isSpoolEligible(block, options.toolNameById(block.tool_use_id))) {
+    const toolCall = options.toolCallById(block.tool_use_id);
+    if (!isSpoolEligible(block, toolCall?.name, toolCall?.input)) {
       continue;
     }
 

package/src/credential-execution/ces-runtime.ts

@@ -176,6 +176,9 @@ export async function startCes(config: AssistantConfig): Promise<void> {
       },
     });
     if (client) {
+      log.info(
+        "CES client injected into credential resolver at startup; credential reads route through CES RPC",
+      );
       setCesClient(client);
     } else {
       // The handshake lost the startup race, so provider init proceeds on the

package/src/credential-execution/client.ts

@@ -9,6 +9,15 @@
  * delegated to the shared package.
  */
 
+import {
+  type CesRpcClient,
+  type CesRpcClientConfig,
+  type CesTransport,
+  createCesRpcClient,
+} from "@vellumai/ces-client/rpc-client";
+
+import { getLogger } from "../util/logger.js";
+
 export {
   type CesRpcClient as CesClient,
   type CesRpcClientConfig as CesClientConfig,
@@ -17,5 +26,17 @@ export {
   CesHandshakeError,
   type CesTransport,
   CesTransportError,
-  createCesRpcClient as createCesClient,
 } from "@vellumai/ces-client/rpc-client";
+
+const log = getLogger("ces-rpc-client");
+
+/**
+ * Construct a CES RPC client wired to the assistant logger so handshake-ready
+ * and close transitions are visible in the daemon logs.
+ */
+export function createCesClient(
+  transport: CesTransport,
+  config?: CesRpcClientConfig,
+): CesRpcClient {
+  return createCesRpcClient(transport, { logger: log, ...config });
+}

package/src/credential-execution/process-manager.test.ts

@@ -125,3 +125,102 @@ describe("CesProcessManager.onTransportClose", () => {
     await pm.stop();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Transport-death logging: WARN only for genuinely-unexpected death
+// ---------------------------------------------------------------------------
+
+type LogCall = { level: string; msg: string };
+
+function makeRecordingLogger(): {
+  calls: LogCall[];
+  logger: NonNullable<Parameters<typeof createCesProcessManager>[0]["logger"]>;
+} {
+  const calls: LogCall[] = [];
+  const rec =
+    (level: string) =>
+    (...args: unknown[]) => {
+      const msg = typeof args[0] === "string" ? args[0] : args[1];
+      calls.push({ level, msg: typeof msg === "string" ? msg : "" });
+    };
+  const logger = {
+    info: rec("info"),
+    warn: rec("warn"),
+    debug: rec("debug"),
+    error: rec("error"),
+  } as unknown as NonNullable<
+    Parameters<typeof createCesProcessManager>[0]["logger"]
+  >;
+  return { calls, logger };
+}
+
+describe("CesProcessManager transport-death logging", () => {
+  let tempDir: string;
+  let server: Server;
+  let connections: Array<import("node:net").Socket>;
+
+  beforeEach(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "ces-pm-log-test-"));
+    mockSocketPath = join(tempDir, "ces.sock");
+    connections = [];
+    server = createServer((socket) => {
+      connections.push(socket);
+      socket.on("error", () => {});
+    });
+    await new Promise<void>((resolve) =>
+      server.listen(mockSocketPath, resolve),
+    );
+  });
+
+  afterEach(async () => {
+    for (const sock of connections) {
+      sock.destroy();
+    }
+    connections = [];
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("logs WARN when the transport dies unexpectedly (remote close)", async () => {
+    const { calls, logger } = makeRecordingLogger();
+    const pm = createCesProcessManager({ logger });
+    const transport = await pm.start();
+
+    // The remote (server) closes the connection: genuinely-unexpected death.
+    for (const sock of connections) {
+      sock.destroy();
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(transport.isAlive()).toBe(false);
+
+    expect(
+      calls.some(
+        (c) => c.level === "warn" && c.msg.includes("died unexpectedly"),
+      ),
+    ).toBe(true);
+
+    await pm.stop();
+  });
+
+  test("does not log WARN on an intentional stop()", async () => {
+    const { calls, logger } = makeRecordingLogger();
+    const pm = createCesProcessManager({ logger });
+    await pm.start();
+
+    await pm.stop();
+    // Let the socket close event propagate after destroy().
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(
+      calls.some(
+        (c) => c.level === "warn" && c.msg.includes("died unexpectedly"),
+      ),
+    ).toBe(false);
+    expect(
+      calls.some(
+        (c) =>
+          c.level === "debug" && c.msg.includes("CES socket transport closed"),
+      ),
+    ).toBe(true);
+  });
+});