@vellumai/cli 0.11.0-dev.202607302326.a10ae93 → 0.11.0-dev.202607310047.8d3af62

package/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/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/service-contracts/src/conversation-handle.ts

@@ -0,0 +1,246 @@
+/**
+ * Durable conversation handles: the external provider conversation a Vellum
+ * conversation is bound to, in a serializable, schema-validated form.
+ *
+ * A handle answers "which provider conversation, reached through which Vellum
+ * channel connection". The same handle is usable for inbound conversation
+ * binding and for later outbound delivery, so it carries exactly two things:
+ * the connection identity needed to recover the correct provider credentials,
+ * and the provider-native routing coordinates. Message coordinates (message
+ * ids, reply-to relationships), actors, and content are per-event data and are
+ * deliberately not part of the handle.
+ *
+ * The handle names the provider-side conversation only. Vellum's internal
+ * `conversationId` is a separate identity and never appears inside a handle;
+ * the binding between the two lives wherever handles are persisted.
+ *
+ * Every variant is a strict object, so a field from another provider, a
+ * flattened `threadId`/`topicId`, or a smuggled message id fails validation
+ * instead of riding along untyped.
+ */
+
+import { z } from "zod";
+
+import type { ChannelId } from "./channels.js";
+
+// ---------------------------------------------------------------------------
+// Field validators
+// ---------------------------------------------------------------------------
+
+/** Upper bound on any single handle field. */
+const MAX_FIELD_LENGTH = 256;
+
+/**
+ * The Vellum channel connection (installation) the conversation belongs to.
+ * Opaque to this contract: it identifies which stored provider credentials
+ * and provider account reach the conversation, not any provider object.
+ */
+const connectionId = () =>
+  z
+    .string()
+    .min(1)
+    .max(MAX_FIELD_LENGTH)
+    .regex(
+      /^[^\s\p{Cc}]+$/u,
+      "must not contain whitespace or control characters",
+    );
+
+/** A Telegram Bot API integer id as decimal digits (int64 width). */
+const telegramId = () =>
+  z.string().regex(/^\d{1,19}$/, "must be decimal digits");
+
+/** Bot API `chat.id`: negative for groups, supergroups, and channels. */
+const telegramChatId = () =>
+  z
+    .string()
+    .regex(/^-?\d{1,19}$/, "must be decimal digits, optionally negative");
+
+const slackTeamId = () =>
+  z
+    .string()
+    .max(MAX_FIELD_LENGTH)
+    .regex(/^T[A-Z0-9]{2,}$/, "must be a Slack workspace id, e.g. T0123ABCD");
+
+/** `C…` public channel, `D…` DM, `G…` private channel or legacy group DM. */
+const slackChannelId = () =>
+  z
+    .string()
+    .max(MAX_FIELD_LENGTH)
+    .regex(
+      /^[CDG][A-Z0-9]{2,}$/,
+      "must be a Slack conversation id, e.g. C0123ABCD",
+    );
+
+/** A Slack message timestamp, the thread key (`thread_ts`). */
+const slackThreadTs = () =>
+  z
+    .string()
+    .regex(
+      /^\d{10}\.\d{6}$/,
+      "must be a Slack message timestamp, e.g. 1700000000.000100",
+    );
+
+/** A Discord snowflake as decimal digits. */
+const discordSnowflake = () =>
+  z.string().regex(/^\d{1,20}$/, "must be a Discord snowflake");
+
+// ---------------------------------------------------------------------------
+// Telegram
+// ---------------------------------------------------------------------------
+
+/**
+ * Where inside a Telegram chat the conversation lives. `message_thread`
+ * carries a Bot API `message_thread_id` (forum topics and private-chat topic
+ * mode); `direct_messages_topic` carries a `direct_messages_topic_id`
+ * (channel direct-messages monoforums). They are different Bot API routing
+ * fields, so they are distinct variants rather than one untyped topic id, and
+ * the union makes a mixed shape unrepresentable.
+ */
+export const TelegramSubconversationSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("chat") }),
+  z.strictObject({ kind: z.literal("message_thread"), id: telegramId() }),
+  z.strictObject({
+    kind: z.literal("direct_messages_topic"),
+    id: telegramId(),
+  }),
+]);
+
+export type TelegramSubconversation = z.infer<
+  typeof TelegramSubconversationSchema
+>;
+
+export const TelegramConversationHandleSchema = z.strictObject({
+  provider: z.literal("telegram"),
+  connectionId: connectionId(),
+  /** Bot API `chat.id`. Negative for groups, supergroups, and channels. */
+  chatId: telegramChatId(),
+  subconversation: TelegramSubconversationSchema,
+});
+
+// ---------------------------------------------------------------------------
+// Slack
+// ---------------------------------------------------------------------------
+
+/**
+ * Slack routing keeps its native shape: conversation ids are unique only
+ * within a workspace, and a thread is keyed by the parent message's
+ * `thread_ts`. `threadTs` absent means the conversation is the channel
+ * itself, not that the producer may omit it.
+ */
+export const SlackConversationHandleSchema = z.strictObject({
+  provider: z.literal("slack"),
+  connectionId: connectionId(),
+  /** Workspace id (`T…`). */
+  teamId: slackTeamId(),
+  /** Conversation id: `C…` channel, `D…` DM, `G…` private or group DM. */
+  channelId: slackChannelId(),
+  /** `thread_ts` of the thread parent, on a threaded conversation only. */
+  threadTs: slackThreadTs().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Discord
+// ---------------------------------------------------------------------------
+
+/**
+ * Discord routing keeps its native shape: a thread is itself a channel
+ * snowflake under a parent channel, and the adapter admits guild messages
+ * only, so the guild is always part of the handle.
+ */
+export const DiscordConversationHandleSchema = z.strictObject({
+  provider: z.literal("discord"),
+  connectionId: connectionId(),
+  /** Guild (server) snowflake. */
+  guildId: discordSnowflake(),
+  /** Parent channel snowflake, the conversation itself outside a thread. */
+  channelId: discordSnowflake(),
+  /** Thread or forum-post snowflake, on a thread conversation only. */
+  threadId: discordSnowflake().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// The union
+// ---------------------------------------------------------------------------
+
+/**
+ * Providers that have a durable handle shape. Every entry must be a canonical
+ * `ChannelId`; the `satisfies` clause enforces that at compile time.
+ */
+export const CONVERSATION_HANDLE_PROVIDERS = [
+  "discord",
+  "slack",
+  "telegram",
+] as const satisfies readonly ChannelId[];
+
+export type ConversationHandleProvider =
+  (typeof CONVERSATION_HANDLE_PROVIDERS)[number];
+
+/**
+ * Handle variant per provider. The `satisfies Record<…>` annotation is the
+ * exhaustiveness gate: adding a provider to `CONVERSATION_HANDLE_PROVIDERS`
+ * fails to compile until its handle shape is spelled out here.
+ */
+export const CONVERSATION_HANDLE_SCHEMAS = {
+  discord: DiscordConversationHandleSchema,
+  slack: SlackConversationHandleSchema,
+  telegram: TelegramConversationHandleSchema,
+} as const satisfies Record<ConversationHandleProvider, z.ZodObject>;
+
+export const ConversationHandleSchema = z.discriminatedUnion("provider", [
+  CONVERSATION_HANDLE_SCHEMAS.discord,
+  CONVERSATION_HANDLE_SCHEMAS.slack,
+  CONVERSATION_HANDLE_SCHEMAS.telegram,
+]);
+
+export type ConversationHandle = z.infer<typeof ConversationHandleSchema>;
+
+/** The handle variant for one provider, e.g. `ConversationHandleFor<"slack">`. */
+export type ConversationHandleFor<P extends ConversationHandleProvider> =
+  Extract<ConversationHandle, { provider: P }>;
+
+// ---------------------------------------------------------------------------
+// Serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a handle to its JSON wire form. The handle is validated first, so
+ * the output is always the serialization of a valid handle.
+ *
+ * @throws {z.ZodError} when the value is not a valid {@link ConversationHandle}.
+ */
+export function serializeConversationHandle(
+  handle: ConversationHandle,
+): string {
+  return JSON.stringify(ConversationHandleSchema.parse(handle));
+}
+
+/**
+ * Inverse of {@link serializeConversationHandle}. Returns `null` for anything
+ * that is not the JSON serialization of a valid handle: malformed JSON, an
+ * unknown provider, a missing or malformed coordinate, or a field the
+ * provider's shape does not declare.
+ */
+export function safeDeserializeConversationHandle(
+  text: string,
+): ConversationHandle | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const result = ConversationHandleSchema.safeParse(value);
+  return result.success ? result.data : null;
+}
+
+/**
+ * Inverse of {@link serializeConversationHandle}, throwing instead of
+ * returning `null`.
+ */
+export function deserializeConversationHandle(text: string): ConversationHandle {
+  const handle = safeDeserializeConversationHandle(text);
+  if (handle === null) {
+    throw new Error("not a valid conversation handle serialization");
+  }
+  return handle;
+}

package/node_modules/@vellumai/service-contracts/src/index.ts

@@ -20,6 +20,7 @@
 
 export * from "./channels.js";
 export * from "./client-metadata.js";
+export * from "./conversation-handle.js";
 export * from "./transport.js";
 export * from "./error.js";
 export * from "./handles.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.11.0-dev.202607302326.a10ae93",
+  "version": "0.11.0-dev.202607310047.8d3af62",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {