@vellumai/plugin-api 0.11.3-dev.202608110433.eba8e13 → 0.11.3-dev.202608111333.7065e2a

package/index.d.ts

@@ -4000,6 +4000,41 @@ declare interface BaseSubscriberEntry {
  */
 export declare function buildMessageExcerpt(rawContent: string, query: string): Promise<string>;
 
+/**
+ * Canonical channel-id vocabulary shared between the assistant daemon and the
+ * gateway.
+ *
+ * A "channel" is an external messaging surface an actor can reach the
+ * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
+ * internal ids (`vellum` for native app conversations, `platform` for the
+ * internal control plane). This is the single source of truth for that set:
+ *
+ * One id, `plugin`, does not name a surface: it names *every* surface a plugin
+ * brings. A plugin channel's real identity is the plugin, which is workspace
+ * state and cannot be a compile-time union member, so the plugin name travels
+ * in `sourceMetadata.plugin` and is prefixed onto every external id the gateway
+ * forwards (`imessage:+15551234567`). Two plugins therefore share a channel
+ * row — one admission floor, one set of channel-wide defaults — while their
+ * conversations, contacts, and trust records stay disjoint. See
+ * `gateway/src/channels/plugin-inbound.ts` for what that concedes.
+ *
+ * the assistant adopts it wholesale as its `ChannelId`, and the gateway
+ * asserts its own (narrower) inbound list is a subset of it so the two sides
+ * cannot silently drift.
+ *
+ * Both packages depend on `@vellumai/service-contracts`, so hoisting the set
+ * here (rather than maintaining a copy on each side) means adding or renaming
+ * a channel happens in exactly one place.
+ *
+ * Note that a consumer may legitimately handle only a *subset* of these — the
+ * gateway, for example, never ingresses `platform`. Use a local list guarded
+ * by `satisfies readonly ChannelId[]` for those cases rather than redefining
+ * the union.
+ */
+declare const CHANNEL_IDS: readonly ["telegram", "phone", "vellum", "whatsapp", "slack", "email", "platform", "a2a", "discord", "plugin"];
+
+declare type ChannelId = (typeof CHANNEL_IDS)[number];
+
 export declare const CLI_COMMAND_HELP: readonly CliCommandHelp[];
 
 declare interface CliArgumentHelp {
@@ -4105,6 +4140,43 @@ declare type ConfiguredProviderOptions = Pick<ResolveCallSiteOpts, "overrideProf
 
 export declare type ContentBlock = TextContent | ThinkingContent | RedactedThinkingContent | ImageContent | FileContent | ToolUseContent | ToolResultContent | ServerToolUseContent | WebSearchToolResultContent | UiSurfaceContent;
 
+/**
+ * The chat a turn belongs to, in the channel's own terms.
+ *
+ * Supplied instead of a `conversationId` when the caller knows where the
+ * message came from but not which conversation that is. The pair resolves to
+ * the same conversation an inbound message on those coordinates would land
+ * in, because it resolves through the same binding.
+ *
+ * That sameness is the reason this exists at all. A caller could keep its own
+ * `externalChatId -> conversationId` map and pass the id, and turns would run
+ * in the right place. What it could not do is make the rest of the assistant
+ * agree: conversation reset is addressed by channel coordinates
+ * (`handleDeleteConversation`), the deny lanes attach an access-request card
+ * by them (`findInboundConversationId`), and the conversation and session
+ * APIs read the channel, chat name and sender off the external binding. A
+ * private map is a second name for the same conversation, and everything
+ * keyed on the public one quietly misses.
+ */
+export declare interface ConversationChannelAddress {
+    /** Channel the message arrived on. */
+    sourceChannel: ChannelId;
+    /** The chat, in the channel's own id space. */
+    externalChatId: string;
+    /**
+     * Thread within the chat, where the channel has threads. Only Slack and
+     * Telegram scope a conversation by thread; elsewhere this is carried as
+     * binding metadata and does not split the conversation.
+     */
+    externalThreadId?: string | null;
+    /** Human-readable chat name, for the conversation list. */
+    externalChatName?: string | null;
+    /** Who sent it, in the channel's id space. */
+    externalUserId?: string | null;
+    displayName?: string | null;
+    username?: string | null;
+}
+
 /** How a conversation was created / its execution mode. */
 declare type ConversationCreateType = "standard" | "background" | "scheduled";
 
@@ -6029,9 +6101,22 @@ export declare function runConversationTurn(options: RunConversationTurnOptions)
 export declare interface RunConversationTurnOptions {
     /**
      * Conversation to run the turn in. If omitted, a new conversation is
-     * created (its ID is generated with `uuidv7` and returned in the result).
+     * created (its ID is generated with `uuidv7` and returned in the result),
+     * unless {@link RunConversationTurnOptions.channel} says which chat this
+     * belongs to, in which case that chat's conversation is used.
      */
     conversationId?: string;
+    /**
+     * The chat this turn belongs to, resolved to a conversation and bound to
+     * the channel. See {@link ConversationChannelAddress}.
+     *
+     * Ignored when `conversationId` is given: an explicit conversation is the
+     * caller saying which one, and re-resolving would overrule it. A caller
+     * that wants both the binding and a conversation of its own choosing is
+     * describing two different conversations, which is a bug worth surfacing
+     * as one rather than silently picking a winner.
+     */
+    channel?: ConversationChannelAddress;
     /**
      * User message content blocks for this turn. Text blocks become the
      * user message body; image/file blocks are resolved to inline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.11.3-dev.202608110433.eba8e13",
+  "version": "0.11.3-dev.202608111333.7065e2a",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",