@vellumai/assistant 0.11.0 → 0.11.1-staging.2

package/ARCHITECTURE.md

@@ -624,10 +624,10 @@ Real-time conversation chat message capture on macOS uses a WebSocket-based stre
 
 Two provider adapters are supported, each implementing the `StreamingTranscriber` interface from `src/stt/types.ts`:
 
-| Provider          | Adapter                                                     | Mode          | Mechanism                                                                                                                                                                                                                                             |
-| ----------------- | ----------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Deepgram**      | `src/providers/speech-to-text/deepgram-realtime.ts`         | `realtime-ws` | Opens a WebSocket to Deepgram's `/v1/listen` endpoint, forwards raw PCM audio, normalizes Deepgram's `is_final`/`speech_final` semantics into `partial`/`final` events. Uses model `nova-2`.                                                          |
-| **Google Gemini** | `src/providers/speech-to-text/google-gemini-live-stream.ts` | `realtime-ws` | Opens a bidirectional streaming session against Gemini's Live API (`ai.live.connect`), forwards PCM audio frames, and normalizes `serverContent.inputTranscription` events into `partial`/`final` events. Uses model `gemini-live-2.5-flash-preview`. |
+| Provider          | Adapter                                                     | Mode          | Mechanism                                                                                                                                                                                                                                                    |
+| ----------------- | ----------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Deepgram**      | `src/providers/speech-to-text/deepgram-realtime.ts`         | `realtime-ws` | Opens a WebSocket to Deepgram's `/v1/listen` endpoint, forwards raw PCM audio, normalizes Deepgram's `is_final`/`speech_final` semantics into `partial`/`final` events. Uses model `nova-2`.                                                                 |
+| **Google Gemini** | `src/providers/speech-to-text/google-gemini-live-stream.ts` | `realtime-ws` | Opens a bidirectional streaming session against Gemini's Live API (`ai.live.connect`), forwards PCM audio frames, and normalizes `serverContent.inputTranscription` events into `partial`/`final` events. Uses model `gemini-2.5-flash-native-audio-latest`. |
 
 **Provider-specific behavior differences:**
 
@@ -717,6 +717,7 @@ The web client implements these flows in `clients/web/src/domains/chat/voice/`:
 **Cross-boundary notes:**
 
 - The `services.stt` config block is the single source of truth for STT provider selection across the daemon batch boundary, the conversation streaming boundary, the client service-first boundary, and the telephony boundary. The batch and streaming resolvers (`resolveBatchTranscriber()`, `resolveStreamingTranscriber()`) both read from `services.stt.provider` and resolve credentials through the same catalog; the telephony boundary's media-stream STT session uses these same resolvers — it selects streaming vs batch transcription via `resolveStreamingTranscriber()`/`resolveBatchTranscriber()` under the `calls.voice.telephonyStreaming` flag, gated by `resolveTelephonySttCapability()`, while call placement/TwiML is gated by `resolveTelephonyCredentialReadiness()`. The daemon provider catalog (`src/providers/speech-to-text/provider-catalog.ts`) is the authoritative registry of supported providers. Native clients fetch display metadata via `GET /v1/stt/providers`.
+- **Spoken language** is a second axis on the same block: `services.stt.language` is read by `resolveStreamingTranscriber()` and `resolveBatchTranscriber()` and forwarded to the adapters that accept one (Deepgram, xAI, and the managed relay, which passes it to Deepgram server-side). Callers may override it per streaming session, but none need to: reading it in the resolvers means every boundary inherits the setting. Gemini and Whisper take no language option and auto-detect natively, so they ignore it. Leaving it unset is **not** auto-detection on Deepgram or the managed relay: Deepgram's default is English, so non-English speech transcribes as English-sounding nonsense. `"multi"` selects nova-3 code-switching across English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, and Dutch, the mode to use when a speaker mixes languages inside one utterance. BYOK Deepgram pins `model=nova-3` for **any** explicitly configured language, not just `"multi"`: the curated roster is verified against nova-3 (the default nova-2 supports only a subset, and rejects `"multi"` outright), and `deepgramLanguageOptions()` owns the model+language pairing so every call site inherits the rule; leaving the language unset keeps the adapter default model with no language param. `"multi"` is never forwarded to xAI (it is not a BCP-47 code; xAI auto-handles multilingual audio). The managed relay pins nova-3 and allowlists `language`, so streaming needs no platform-side change; managed **batch** goes through the platform speech proxy, which accepts no language parameter, so forwarding it there is deferred pending a platform-side change.
 - Conversation streaming does not replace the client service-first batch path. When streaming is available, it runs concurrently during recording and provides real-time partials and finals. The batch path remains the fallback for providers that do not support streaming, when streaming fails mid-session, or when streaming produces no final transcript.
 - Credential mapping is catalog-driven: `provider-secret-catalog.ts` derives STT API-key provider names from the daemon catalog via `listCredentialProviderNames()`, deduplicating against the LLM/search provider list. Adding a provider to the catalog automatically includes its credential name in `API_KEY_PROVIDERS`.
 - Terminology: "STT", "transcription", and "speech recognition" all refer to the same operation (converting audio to text).
@@ -820,14 +821,18 @@ graph LR
         SL["logs/session-*.json<br/>───────────────<br/>Per-session JSON log<br/>task, start/end times, result<br/>Per-turn: AX tree, screenshot,<br/>action, token usage"]
     end
 
+    subgraph "$VELLUM_WORKSPACE_DIR/data/db/assistant-memory.db (SQLite + WAL)"
+        direction TB
+        SEG["memory_segments<br/>───────────────<br/>Text chunks for retrieval<br/>Linked to messages<br/>token_estimate per segment"]
+        SUM["memory_summaries<br/>───────────────<br/>scope: conversation | weekly<br/>Compressed history for context<br/>window management"]
+        EMB["memory_embeddings<br/>───────────────<br/>target: segment | item | summary<br/>provider + model metadata<br/>vector_json (float array)<br/>Powers semantic search"]
+    end
+
     subgraph "$VELLUM_WORKSPACE_DIR/data/db/assistant.db (SQLite + WAL)"
         direction TB
         CONV["conversations<br/>───────────────<br/>id, title, timestamps<br/>token counts, estimated cost<br/>context_summary (compaction)<br/>conversation_type: 'standard' | 'background' | 'scheduled'"]
         MSG["messages<br/>───────────────<br/>id, conversation_id (FK)<br/>role: user | assistant<br/>content: JSON array<br/>created_at"]
         TOOL["tool_invocations<br/>───────────────<br/>tool_name, input, result<br/>decision, risk_level<br/>duration_ms"]
-        SEG["memory_segments<br/>───────────────<br/>Text chunks for retrieval<br/>Linked to messages<br/>token_estimate per segment"]
-        SUM["memory_summaries<br/>───────────────<br/>scope: conversation | weekly<br/>Compressed history for context<br/>window management"]
-        EMB["memory_embeddings<br/>───────────────<br/>target: segment | item | summary<br/>provider + model metadata<br/>vector_json (float array)<br/>Powers semantic search"]
         JOBS["memory_jobs<br/>───────────────<br/>Async task queue<br/>Types: embed, extract,<br/>summarize, backfill, cleanup<br/>Status: pending → running →<br/>completed | failed"]
         ATT["attachments<br/>───────────────<br/>base64-encoded file data<br/>mime_type, size_bytes<br/>Linked to messages via<br/>message_attachments join"]
         REM["reminders<br/>───────────────<br/>One-time scheduled reminders<br/>label, message, fireAt<br/>mode: notify | execute<br/>status: pending → fired | cancelled<br/>routing_intent: single_channel |<br/>multi_channel | all_channels<br/>routing_hints_json (free-form)"]
@@ -1967,9 +1972,9 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | User preferences                         | UserDefaults                                           | plist                               | Foundation                         | Permanent                                               |
 | Session logs                             | `~/Library/.../logs/session-*.json`                    | JSON per session                    | Swift Codable                      | Unbounded                                               |
 | Conversations & messages                 | `$VELLUM_WORKSPACE_DIR/data/db/assistant.db`           | SQLite + WAL                        | Drizzle ORM (Bun)                  | Permanent                                               |
-| Memory segments                          | `$VELLUM_WORKSPACE_DIR/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent                                               |
+| Memory segments                          | `$VELLUM_WORKSPACE_DIR/data/db/assistant-memory.db`    | SQLite                              | Drizzle ORM                        | Permanent                                               |
 | Extracted facts                          | `$VELLUM_WORKSPACE_DIR/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent, deduped                                      |
-| Embeddings                               | `$VELLUM_WORKSPACE_DIR/data/db/assistant.db`           | JSON float arrays                   | Drizzle ORM                        | Permanent                                               |
+| Embeddings                               | `$VELLUM_WORKSPACE_DIR/data/db/assistant-memory.db`    | JSON float arrays                   | Drizzle ORM                        | Permanent                                               |
 | Async job queue                          | `$VELLUM_WORKSPACE_DIR/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Completed jobs persist                                  |
 | Attachments                              | `$VELLUM_WORKSPACE_DIR/data/db/assistant.db`           | Base64 in SQLite                    | Drizzle ORM                        | Permanent                                               |
 | Sandbox filesystem                       | `$VELLUM_WORKSPACE_DIR`                                | Real filesystem tree                | Node FS APIs                       | Persistent across sessions                              |

package/Dockerfile

@@ -22,6 +22,7 @@ ENV PATH="/root/.bun/bin:${PATH}"
 # Note that we don't need source code to resolve cross-workspace dependencies.
 COPY package.json bun.lock ./
 COPY patches ./patches
+COPY clients/docs/package.json ./clients/docs/
 COPY clients/macos/package.json ./clients/macos/
 COPY clients/web/package.json ./clients/web/
 COPY cli/package.json ./cli/

package/docs/architecture/memory.md

@@ -67,6 +67,9 @@ graph LR
     CONS --> VIEWS["essentials / threads / recent"]
     CONS --> REEMBED["memory_v2_reembed →<br/>concept-page Qdrant collection"]
     CONS --> MAINT["memory_v3_maintain<br/>(v3-live follow-up)"]
+    ING["POST /v1/memory/ingest<br/>(deterministic batch import)"] --> PAGES
+    ING --> REEMBED
+    ING --> MAINT
 ```
 
 - `handleRemember` (`graph/tool-handlers.ts`) appends timestamped bullets to
@@ -85,6 +88,62 @@ graph LR
     failure-backoff-respecting);
   - manual "Run now" via `POST /v1/consolidation/run-now`.
     Failed runs enter an exponential backoff (transient vs billing curves).
+- **Ingestion** (`substrate/ingest.ts`, exposed as `POST /v1/memory/ingest`;
+  generated HTTP operation id `memory_ingest_post`, IPC method
+  `memory_ingest`) is the second sanctioned writer of
+  `memory/concepts/`: a deterministic batch import of fully-formed,
+  page-shaped markdown (frontmatter + body) that bypasses the buffer
+  entirely. The bypass is load-bearing, not a shortcut: buffer timestamps
+  have minute precision, so a bulk append lands every entry on one shared
+  minute stamp, the chunker's timestamp cutoff cannot split inside that
+  minute, and its same-minute burst guard falls back to processing the
+  whole buffer in a single oversized run. Ingest writes validated pages
+  directly instead. Purely mechanical: each page is validated and reported
+  individually, writes hold the consolidation lock so a batch cannot
+  interleave with a consolidation pass, and a batch that wrote at least one
+  page enqueues the same reindex follow-ups as consolidation
+  (`memory_v2_reembed`, `memory_v3_maintain`). Consolidation remains the only
+  LLM-driven writer.
+
+### Ingestion tracks and provenance
+
+Two user-facing flows feed the ingest route, chosen by the shape of the
+source material rather than its size:
+
+- **Distilled import** (`skills/assistant-migration`): memory exported from
+  another assistant is parsed, creator-reviewed, and shaped into concept
+  pages. The input is already distilled, so everything approved becomes
+  pages; assistant exports route here regardless of size because they need
+  candidate parsing and creator review.
+- **Large-corpus skim** (`skills/memory-corpus-ingest`): the raw dataset
+  (recording archives, document dumps) is cold-stored under a workspace
+  imports directory and never enters the memory corpus. Only a small map of
+  roughly 10 to 50 skim pages is ingested, each pointing back at the raw
+  files, and a drill-in retrieval skill authored alongside searches the cold
+  store on demand.
+
+Both stage pages on disk and write them through the `assistant memory ingest`
+CLI (`src/cli/commands/memory/memory-ingest.ts`: staging directory, JSON
+manifest, or stdin; dry-run; overwrite; 200-page batches). The one exception
+is a migration yielding only a handful of approved facts: assistant-migration
+saves those through the normal `remember` tool, so they enter via the buffer
+like any organic capture instead of the ingest route.
+
+Ingested pages carry provenance frontmatter with distinct consumers:
+
+- `source:` marks a page's origin, by convention `import:<provider>`
+  (e.g. `import:chatgpt`), so imported pages stay distinguishable from
+  consolidation-authored ones, which never carry the key.
+- `origin_date:` (ISO 8601 date or datetime) declares when the page's
+  content is from and drives `PageIndexEntry.freshAt`, the effective-recency
+  signal: any finite parse is accepted (pre-epoch dates included; an
+  offset-less datetime is read as UTC), and an absent or unparseable value
+  falls back to file mtime. The v3 fresh lane ranks on `freshAt` and the
+  card's `dated` stamp renders it, so a backdated import ranks by what its
+  content is about rather than when it reached disk. `modifiedAt` stays raw
+  mtime because the maintain job's re-embed delta diffs on it. Synthetic
+  entries (skills, CLI commands) carry `freshAt: null` and are skipped by
+  recency ranking.
 
 ### Read paths
 

package/docs/stt-provider-onboarding.md

@@ -30,6 +30,8 @@ This ensures the exhaustive switch in `daemon-batch-transcriber.ts` produces a c
 
 The `services.stt.providers` map uses a sparse `z.record(z.string(), ...)` schema, so adding a new provider does **not** require a workspace migration to seed a `services.stt.providers.<id>` entry. Users only need to set `services.stt.provider` to the new ID and supply credentials.
 
+**Language handling.** `services.stt.language` is resolved centrally in `resolveStreamingTranscriber()` (and in `resolveBatchTranscriber()` for the daemon-batch boundary), so a new adapter inherits it for free: accept a `language` option in the adapter's constructor and forward it to the provider. If the provider auto-detects natively and has no language parameter (as Gemini and Whisper do), accept nothing and let the resolver's value be ignored; document that choice in the adapter, because "no language param" means auto-detect for some providers and _English_ for others (Deepgram), and that difference is an easy source of silent wrong-language transcription. A provider that supports both batch and streaming must forward the language on **both** paths, not just the streaming one.
+
 ## 4. Adapter wiring
 
 **File:** `src/stt/daemon-batch-transcriber.ts`
@@ -52,13 +54,14 @@ If the new provider **shares** an existing credential name (e.g. reuses `"openai
 
 All client-facing metadata is part of the daemon's provider catalog entry (`src/providers/speech-to-text/provider-catalog.ts`). When adding a new provider, include these fields in the catalog entry:
 
-| Field              | Description                                                               |
-| ------------------ | ------------------------------------------------------------------------- |
-| `displayName`      | Human-readable name shown in client settings UI.                          |
-| `subtitle`         | Short description displayed below the provider selector.                  |
-| `setupMode`        | `"api-key"` (inline key field) or `"cli"` (instructions-only).            |
-| `setupHint`        | Brief guidance shown during setup.                                        |
-| `credentialsGuide` | Object with `description`, `url`, and `linkLabel` for the key mgmt page.  |
+| Field               | Description                                                                                                                                                             |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `displayName`       | Human-readable name shown in client settings UI.                                                                                                                        |
+| `subtitle`          | Short description displayed below the provider selector.                                                                                                                |
+| `setupMode`         | `"api-key"` (inline key field) or `"cli"` (instructions-only).                                                                                                          |
+| `setupHint`         | Brief guidance shown during setup.                                                                                                                                      |
+| `languageSelection` | `"manual"` (provider takes a language parameter, clients show a picker) or `"auto"` (native detection, picker hidden). See the "Language handling" paragraph in step 3. |
+| `credentialsGuide`  | Object with `description`, `url`, and `linkLabel` for the key mgmt page.                                                                                                |
 
 Native clients fetch this metadata at launch via `GET /v1/stt/providers`. No separate client-side file updates are needed.
 

package/eslint.config.mjs

@@ -15,7 +15,7 @@ const eslintConfig = defineConfig([
       // Require braces on every control-statement body (if/else/for/
       // while/do). A braceless body is a maintenance hazard: a second
       // line added under the condition reads as guarded but always runs.
-      curly: ["warn", "all"],
+      curly: ["error", "all"],
       "simple-import-sort/imports": [
         "error",
         {
@@ -49,6 +49,39 @@ const eslintConfig = defineConfig([
       "@typescript-eslint/no-explicit-any": "off",
     },
   },
+  // Managed-column profile resolution (`getEffectiveProfile(s)`) resolves
+  // default profiles against the vellum column only, ignoring
+  // `llm.defaultProvider`; on a BYO install that is not the body that
+  // dispatches. Runtime code must use `resolveDefaultProfileForProvider` /
+  // `getEffectiveProfilesForProvider` instead. The allowlist below is the
+  // full set of intentional managed-column consumers: the catalog itself,
+  // hatch-time seeding (writes managed stubs by design), and write-path
+  // validation.
+  {
+    files: ["src/**/*.ts"],
+    ignores: [
+      "src/config/default-profile-catalog.ts",
+      "src/config/seed-inference-profiles.ts",
+      "src/config/inference-profile-validation.ts",
+      "**/__tests__/**",
+      "**/*.test.ts",
+    ],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["**/default-profile-catalog.js"],
+              importNames: ["getEffectiveProfile", "getEffectiveProfiles"],
+              message:
+                "Managed-column resolution ignores llm.defaultProvider. Use resolveDefaultProfileForProvider / getEffectiveProfilesForProvider with the parsed config's llm.defaultProvider ?? null.",
+            },
+          ],
+        },
+      ],
+    },
+  },
   // `cli/no-daemon-internals` keeps daemon-internal modules out of the CLI's
   // static import graph, so `assistant …` invocations (including the bash-tool
   // fast path) don't pay the memory cost of loading daemon subsystems. Keep at

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/package.json

@@ -7,6 +7,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./channels": "./src/channels.ts",
+    "./conversation-handle": "./src/conversation-handle.ts",
     "./client-metadata": "./src/client-metadata.ts",
     "./credential-rpc": "./src/credential-rpc.ts",
     "./ingress": "./src/ingress.ts",

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/conversation-handle.test.ts

@@ -0,0 +1,316 @@
+import { describe, expect, test } from "bun:test";
+
+import { CHANNEL_IDS } from "../channels.js";
+import {
+  CONVERSATION_HANDLE_PROVIDERS,
+  ConversationHandleSchema,
+  deserializeConversationHandle,
+  safeDeserializeConversationHandle,
+  serializeConversationHandle,
+  type ConversationHandle,
+} from "../conversation-handle.js";
+
+// Representative handles, one per provider surface the contract must cover.
+const slackChannel: ConversationHandle = {
+  provider: "slack",
+  connectionId: "conn-slack-1",
+  teamId: "T0123ABCD",
+  channelId: "C0123ABCD",
+};
+
+const slackThread: ConversationHandle = {
+  provider: "slack",
+  connectionId: "conn-slack-1",
+  teamId: "T0123ABCD",
+  channelId: "C0123ABCD",
+  threadTs: "1700000000.000100",
+};
+
+const slackDm: ConversationHandle = {
+  provider: "slack",
+  connectionId: "conn-slack-1",
+  teamId: "T0123ABCD",
+  channelId: "D0456EFGH",
+};
+
+const telegramChat: ConversationHandle = {
+  provider: "telegram",
+  connectionId: "conn-telegram-1",
+  chatId: "123456789",
+  subconversation: { kind: "chat" },
+};
+
+const telegramMessageThread: ConversationHandle = {
+  provider: "telegram",
+  connectionId: "conn-telegram-1",
+  chatId: "-1001234567890",
+  subconversation: { kind: "message_thread", id: "42" },
+};
+
+const telegramDirectMessagesTopic: ConversationHandle = {
+  provider: "telegram",
+  connectionId: "conn-telegram-1",
+  chatId: "-1009876543210",
+  subconversation: { kind: "direct_messages_topic", id: "77" },
+};
+
+const discordChannel: ConversationHandle = {
+  provider: "discord",
+  connectionId: "conn-discord-1",
+  guildId: "123456789012345678",
+  channelId: "223456789012345678",
+};
+
+const discordThread: ConversationHandle = {
+  provider: "discord",
+  connectionId: "conn-discord-1",
+  guildId: "123456789012345678",
+  channelId: "223456789012345678",
+  threadId: "323456789012345678",
+};
+
+const REPRESENTATIVE_HANDLES: ConversationHandle[] = [
+  slackChannel,
+  slackThread,
+  slackDm,
+  telegramChat,
+  telegramMessageThread,
+  telegramDirectMessagesTopic,
+  discordChannel,
+  discordThread,
+];
+
+describe("CONVERSATION_HANDLE_PROVIDERS", () => {
+  test("is a subset of the canonical channel ids", () => {
+    for (const provider of CONVERSATION_HANDLE_PROVIDERS) {
+      expect(CHANNEL_IDS).toContain(provider);
+    }
+  });
+});
+
+describe("round-trip", () => {
+  test.each(REPRESENTATIVE_HANDLES.map((h) => [h] as const))(
+    "serialization and schema parsing preserve %j",
+    (handle) => {
+      const wire = serializeConversationHandle(handle);
+      expect(safeDeserializeConversationHandle(wire)).toEqual(handle);
+      expect(deserializeConversationHandle(wire)).toEqual(handle);
+      // The wire form is plain JSON, so a generic JSON hop plus schema parse
+      // reconstructs the same handle.
+      expect(ConversationHandleSchema.parse(JSON.parse(wire))).toEqual(handle);
+    },
+  );
+});
+
+describe("provider discrimination", () => {
+  test("rejects unknown providers", () => {
+    expect(
+      ConversationHandleSchema.safeParse({
+        provider: "mastodon",
+        connectionId: "conn-1",
+      }).success,
+    ).toBe(false);
+  });
+
+  test("rejects canonical channels that have no handle shape", () => {
+    // whatsapp is a canonical ChannelId but not (yet) a handle provider, so
+    // it must fail schema parsing rather than fall through to some default.
+    expect(
+      ConversationHandleSchema.safeParse({
+        provider: "whatsapp",
+        connectionId: "conn-1",
+        chatId: "+15555550100",
+      }).success,
+    ).toBe(false);
+  });
+
+  test("rejects cross-provider coordinate mixes", () => {
+    // Telegram handle carrying Slack routing fields.
+    expect(
+      ConversationHandleSchema.safeParse({
+        provider: "telegram",
+        connectionId: "conn-1",
+        teamId: "T0123ABCD",
+        channelId: "C0123ABCD",
+      }).success,
+    ).toBe(false);
+    // Slack handle carrying Telegram routing fields.
+    expect(
+      ConversationHandleSchema.safeParse({
+        ...slackChannel,
+        chatId: "123456789",
+      }).success,
+    ).toBe(false);
+    // Discord handle carrying a Telegram subconversation.
+    expect(
+      ConversationHandleSchema.safeParse({
+        ...discordChannel,
+        subconversation: { kind: "chat" },
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("telegram subconversations", () => {
+  test("chat, message_thread, and direct_messages_topic are distinct", () => {
+    const parsedThread = ConversationHandleSchema.parse(telegramMessageThread);
+    const parsedTopic = ConversationHandleSchema.parse(
+      telegramDirectMessagesTopic,
+    );
+    if (
+      parsedThread.provider !== "telegram" ||
+      parsedTopic.provider !== "telegram"
+    ) {
+      throw new Error("expected telegram handles");
+    }
+    expect(parsedThread.subconversation.kind).toBe("message_thread");
+    expect(parsedTopic.subconversation.kind).toBe("direct_messages_topic");
+  });
+
+  test("rejects a chat subconversation carrying an id", () => {
+    expect(
+      ConversationHandleSchema.safeParse({
+        ...telegramChat,
+        subconversation: { kind: "chat", id: "42" },
+      }).success,
+    ).toBe(false);
+  });
+
+  test("rejects a message_thread subconversation missing its id", () => {
+    expect(
+      ConversationHandleSchema.safeParse({
+        ...telegramChat,
+        subconversation: { kind: "message_thread" },
+      }).success,
+    ).toBe(false);
+  });
+
+  test("rejects an unknown subconversation kind", () => {
+    expect(
+      ConversationHandleSchema.safeParse({
+        ...telegramChat,
+        subconversation: { kind: "topic", id: "42" },
+      }).success,
+    ).toBe(false);
+  });
+
+  test("rejects flattened untyped topic fields", () => {
+    // message_thread_id and direct_messages_topic_id must not ride along as
+    // loose fields next to (or instead of) the typed subconversation.
+    for (const extra of [
+      { topicId: "42" },
+      { messageThreadId: "42" },
+      { directMessagesTopicId: "42" },
+    ]) {
+      expect(
+        ConversationHandleSchema.safeParse({
+          ...telegramChat,
+          ...extra,
+        }).success,
+      ).toBe(false);
+    }
+  });
+});
+
+describe("message coordinates stay out of the handle", () => {
+  test.each([
+    [{ ...telegramChat, messageId: "9001" }],
+    [{ ...telegramChat, replyToMessageId: "9001" }],
+    [{ ...slackThread, messageTs: "1700000000.000200" }],
+    [{ ...discordThread, messageId: "423456789012345678" }],
+  ])("rejects %j", (value) => {
+    expect(ConversationHandleSchema.safeParse(value).success).toBe(false);
+  });
+
+  test("rejects a smuggled internal conversationId", () => {
+    // The Vellum internal conversation id is a separate identity and never
+    // lives inside the provider handle.
+    expect(
+      ConversationHandleSchema.safeParse({
+        ...slackChannel,
+        conversationId: "conv-xyz",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("field validation", () => {
+  test("requires a non-empty connectionId on every variant", () => {
+    for (const handle of [slackChannel, telegramChat, discordChannel]) {
+      expect(
+        ConversationHandleSchema.safeParse({
+          ...handle,
+          connectionId: "",
+        }).success,
+      ).toBe(false);
+      const { connectionId: _omitted, ...withoutConnection } = handle;
+      expect(ConversationHandleSchema.safeParse(withoutConnection).success).toBe(
+        false,
+      );
+    }
+  });
+
+  test("rejects whitespace and control characters in connectionId", () => {
+    expect(
+      ConversationHandleSchema.safeParse({
+        ...slackChannel,
+        connectionId: "conn 1",
+      }).success,
+    ).toBe(false);
+    expect(
+      ConversationHandleSchema.safeParse({
+        ...slackChannel,
+        connectionId: "conn\n1",
+      }).success,
+    ).toBe(false);
+  });
+
+  test.each([
+    [{ ...slackChannel, teamId: "C0123ABCD" }],
+    [{ ...slackChannel, channelId: "T0123ABCD" }],
+    [{ ...slackThread, threadTs: "not-a-ts" }],
+    // The gateway's block-actions reply routing falls back to a Slack
+    // envelope id (a UUID) when no thread_ts exists. A handle only ever
+    // carries a real thread_ts, so envelope-id-shaped values must fail here
+    // instead of becoming durable identity.
+    [{ ...slackThread, threadTs: "8a17bf85-6a58-4b60-8c81-63d8b5ab8c73" }],
+    [{ ...telegramChat, chatId: "12ab34" }],
+    [{ ...telegramMessageThread, subconversation: { kind: "message_thread", id: "-42" } }],
+    [{ ...discordChannel, guildId: "123456789012345678901" }],
+    [{ ...discordThread, threadId: "thread-1" }],
+  ])("rejects malformed coordinates in %j", (value) => {
+    expect(ConversationHandleSchema.safeParse(value).success).toBe(false);
+  });
+
+  test("coordinates are strings, not numbers", () => {
+    expect(
+      ConversationHandleSchema.safeParse({
+        ...telegramChat,
+        chatId: 123456789,
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("serialization helpers", () => {
+  test("serializeConversationHandle validates before serializing", () => {
+    expect(() =>
+      serializeConversationHandle({
+        ...telegramChat,
+        chatId: "not-a-chat-id",
+      } as ConversationHandle),
+    ).toThrow();
+  });
+
+  test("safeDeserializeConversationHandle returns null on malformed input", () => {
+    expect(safeDeserializeConversationHandle("not json")).toBeNull();
+    expect(safeDeserializeConversationHandle("42")).toBeNull();
+    expect(safeDeserializeConversationHandle('{"provider":"slack"}')).toBeNull();
+  });
+
+  test("deserializeConversationHandle throws on malformed input", () => {
+    expect(() => deserializeConversationHandle("not json")).toThrow(
+      "not a valid conversation handle serialization",
+    );
+  });
+});

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/redacted-credential.test.ts

@@ -8,7 +8,7 @@ import {
   parseRedactedSentinel,
   REDACTED_SENTINEL_CLOSE,
   REDACTED_SENTINEL_OPEN,
-} from "../redacted-credential";
+} from "../redacted-credential.js";
 
 describe("buildRedactedSentinel", () => {
   test("plain shape carries only the type", () => {