@vellumai/assistant 0.11.3 → 0.11.4-staging.2

package/src/plugin-api/__tests__/oauth-callback-url-export.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Guards that `resolveOauthCallbackUrl` reaches plugins.
+ *
+ * The shim written into `<workspaceDir>/node_modules/@vellumai/plugin-api`
+ * re-binds whatever `Object.keys()` finds on the plugin-api namespace, so an
+ * export missing from `index.ts` is missing from every installed plugin with
+ * no other signal than a plugin failing to import it.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { PLUGIN_API_EXPORTS } from "../../embedded/plugin-api.js";
+import * as pluginApi from "../index.js";
+
+describe("plugin-api OAuth callback export", () => {
+  test("is exported from the plugin-api surface", () => {
+    expect(typeof pluginApi.resolveOauthCallbackUrl).toEqual("function");
+  });
+
+  test("is carried into the generated shim's binding list", () => {
+    expect(PLUGIN_API_EXPORTS).toContain("resolveOauthCallbackUrl");
+  });
+
+  test("takes no arguments, so a plugin cannot vary the URI", () => {
+    // The value a Client ID Metadata Document publishes and the value the
+    // host later authorizes with have to be the same string.
+    expect(pluginApi.resolveOauthCallbackUrl.length).toEqual(0);
+  });
+});

package/src/plugin-api/conversation-turn.ts

@@ -14,6 +14,7 @@
  */
 
 import type { AssistantEvent } from "../api/index.js";
+import type { ChannelId } from "../channels/types.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
 import type { UserMessageAttachment } from "../daemon/message-types/shared.js";
 import type { ContentBlock, MediaSource } from "../providers/types.js";
@@ -22,12 +23,62 @@ import type { ContentBlock, MediaSource } from "../providers/types.js";
 // Public types
 // ---------------------------------------------------------------------------
 
+/**
+ * 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 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;
+}
+
 export 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
@@ -121,6 +172,77 @@ function extractContentAndAttachments(
   return { text: textParts.join("\n"), attachments };
 }
 
+/**
+ * Resolve a chat to its conversation, binding the two if they are not already.
+ *
+ * Two writes, the same two `handleChannelInbound` makes for an arriving
+ * message, and for the same reasons. The conversation key is what makes the
+ * chat resolve to this conversation next time and what conversation reset
+ * addresses; the external binding is what the conversation and session APIs
+ * read to show which channel a conversation came from and who is on the other
+ * end. One without the other is a conversation that is half-registered, and
+ * which half is missing decides which feature quietly stops working.
+ *
+ * Deliberately not `recordInbound`, which is the same resolution plus an
+ * inbound event row. That row exists to dedup a vendor's redelivery and to
+ * correlate later edits, and a caller driving a turn on its own schedule has
+ * neither a vendor nor a message id to correlate. Plugin deliveries are
+ * deduped upstream in the gateway before the message ever gets here.
+ */
+async function resolveChannelConversation(
+  channel: ConversationChannelAddress,
+  conversationType?: "standard" | "background",
+): Promise<{ conversationId: string; created: boolean }> {
+  const { findInboundConversationId, resolveInboundConversation } =
+    await import("../persistence/delivery-crud.js");
+  const { upsertBinding } =
+    await import("../persistence/external-conversation-store.js");
+
+  // Asked before resolving, because resolving is what creates it: once the id
+  // is in hand a new conversation is indistinguishable from an existing one,
+  // and the caller announces only the new. `findInboundConversationId` is the
+  // read-only mirror of the resolution below, so the two agree on what
+  // "already bound" means, including the Slack flat-key alias.
+  const created =
+    findInboundConversationId(
+      channel.sourceChannel,
+      channel.externalChatId,
+      channel.externalThreadId,
+    ) === null;
+
+  const { conversationId } = resolveInboundConversation(
+    channel.sourceChannel,
+    channel.externalChatId,
+    channel.externalThreadId,
+    // Both apply only if this call is what mints the conversation. `origin` is
+    // first-message attribution, which a chat's first turn is the only chance
+    // to record.
+    {
+      origin: channel.sourceChannel,
+      ...(conversationType ? { conversationType } : {}),
+    },
+  );
+
+  // Refreshed on every turn rather than only on creation, because the sender's
+  // display name and the chat's name are the vendor's to change and the
+  // conversation list shows whichever we last heard. The optional fields pass
+  // through as given: a caller that omits one on a later turn knows only the
+  // chat coordinates this time, which `upsertBinding` reads as silence rather
+  // than as the sender having no name.
+  upsertBinding({
+    conversationId,
+    sourceChannel: channel.sourceChannel,
+    externalChatId: channel.externalChatId,
+    externalChatName: channel.externalChatName,
+    externalThreadId: channel.externalThreadId ?? null,
+    externalUserId: channel.externalUserId,
+    displayName: channel.displayName,
+    username: channel.username,
+  });
+
+  return { conversationId, created };
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -166,8 +288,25 @@ export async function runConversationTurn(
   // below) without requiring a client to approve prompts.
   const { INTERNAL_GUARDIAN_TRUST_CONTEXT } =
     await import("../daemon/trust-context.js");
-  const conversationId = options.conversationId ?? uuidv7();
-  const rowExisted = getConversation(conversationId) != null;
+
+  // A channel address resolves through the same binding an inbound message
+  // uses, so a turn addressed by chat lands in that chat's conversation
+  // rather than a private one only this caller can find.
+  const channelConversation =
+    !options.conversationId && options.channel
+      ? await resolveChannelConversation(
+          options.channel,
+          options.conversationType,
+        )
+      : undefined;
+  const conversationId =
+    options.conversationId ?? channelConversation?.conversationId ?? uuidv7();
+  // A channel address reports its own novelty, since resolving it creates the
+  // row: asking the DB here answers yes for a conversation minted a line ago
+  // and swallows the announcement it is owed.
+  const rowExisted = channelConversation
+    ? !channelConversation.created
+    : getConversation(conversationId) != null;
   const conversation = await getOrCreateConversation(conversationId, {
     trustContext: INTERNAL_GUARDIAN_TRUST_CONTEXT,
     ...(options.conversationType
@@ -199,6 +338,28 @@ export async function runConversationTurn(
     resolveMediaSourceData,
   );
 
+  // The channel this turn speaks on. Runtime assembly reads the per-turn
+  // context first and falls back to the conversation's `originChannel`, then
+  // to `vellum`, so a turn into a conversation carrying no origin runs as
+  // `vellum` without this: the wrong channel for the message row and for the
+  // channel-permission cascade the tools are approved against. Null when the
+  // caller names no channel, which both restores that fallback and clears any
+  // context left by a previous turn.
+  const turnChannelContext = options.channel
+    ? {
+        userMessageChannel: options.channel.sourceChannel,
+        assistantMessageChannel: options.channel.sourceChannel,
+      }
+    : null;
+  // Carried on the metadata as well, because a queued turn is drained after
+  // this call returns and reads its channel from there. Without it the drain
+  // inherits whichever turn was in flight, which on a shared conversation is
+  // some other channel entirely.
+  const metadata = {
+    ...PLUGIN_TURN_MESSAGE_METADATA,
+    ...(turnChannelContext ?? {}),
+  };
+
   // Build the event emitter: fan out to SSE/event-hub subscribers via
   // broadcastMessage, then invoke the collector callback. This mirrors the
   // buildEventEmitter pattern from process-message.ts so plugin-driven
@@ -221,7 +382,7 @@ export async function runConversationTurn(
       onEvent,
       requestId,
       isInteractive: false,
-      metadata: { ...PLUGIN_TURN_MESSAGE_METADATA },
+      metadata,
     });
     if (enqueueResult.rejected) {
       throw new Error(
@@ -236,12 +397,14 @@ export async function runConversationTurn(
     };
   }
 
+  conversation.setTurnChannelContext(turnChannelContext);
+
   const userMessageId = await conversation.processMessage({
     content: text,
     attachments,
     onEvent,
     isInteractive: false,
-    metadata: { ...PLUGIN_TURN_MESSAGE_METADATA },
+    metadata,
     ...(options.callSite ? { callSite: options.callSite } : {}),
   });
 

package/src/plugin-api/index.ts

@@ -180,6 +180,16 @@ export {
 // the same resolution as `webhooks register`, and registers the callback route
 // on the managed branches. The plugin defaults to the one in context.
 export { resolveWebhookUrl, type WebhookUrlOptions } from "./webhook-url.js";
+// Resolve the redirect URI an authorization server should send a user back
+// to after consent. One shared route serves every OAuth flow in the
+// assistant, demultiplexed by OAuth `state`, so this takes no arguments and
+// returns the same URL for every caller and every attempt. A plugin needs it
+// when it publishes something that has to name the redirect URI ahead of the
+// flow, such as a Client ID Metadata Document, whose `redirect_uris` an
+// authorization server matches exactly. Throws when no public ingress is
+// configured and the assistant is not connected to the platform, which is the
+// case where no URL would work.
+export { resolveOauthCallbackUrl } from "../inbound/oauth-callback-url.js";
 // Resolve a provider for a call site (optionally overriding the profile) so a
 // plugin can run inference through the workspace's configured profiles and
 // credentials — managed-proxy or BYOK — without supplying its own API key.
@@ -345,21 +355,26 @@ export { synthesizeText, TtsSynthesisError } from "../tts/synthesize-text.js";
 export type { TtsSynthesisResult } from "../tts/types.js";
 // Streaming speech-to-text — open a live transcription session against the
 // assistant's globally configured STT provider stack. The plugin feeds audio
-// chunks via `sendAudio` and receives partial/final transcript events through
-// the `start(onEvent)` callback, closing with `stop`. `SttStreamServerEvent`
-// and its variants type the events handed to `onEvent`; `SttErrorCategory`
-// classifies `error` events; `SttProviderId` names the resolved session's
-// provider.
+// chunks via `sendAudio` and receives transcript and turn-boundary events
+// through the `start(onEvent)` callback, closing with `stop`.
+// `SttStreamServerEvent` types the events handed to `onEvent`; every member of
+// that union is exported alongside it so a plugin can name each variant in an
+// exhaustive switch. `SttErrorCategory` classifies `error` events;
+// `SttProviderId` names the resolved session's provider.
 export type {
   StreamingTranscriber,
   SttErrorCategory,
   SttProviderId,
   SttStreamServerClosedEvent,
+  SttStreamServerEagerTurnEndEvent,
   SttStreamServerErrorEvent,
   SttStreamServerEvent,
   SttStreamServerFinalEvent,
   SttStreamServerFinalizedEvent,
   SttStreamServerPartialEvent,
+  SttStreamServerTurnEndEvent,
+  SttStreamServerTurnResumedEvent,
+  SttStreamServerTurnStartEvent,
 } from "../stt/types.js";
 export { openTranscriptionSession } from "./transcription-session.js";
 // Conversation agent-loop turn — run a full conversation turn (persist user
@@ -370,6 +385,7 @@ export { openTranscriptionSession } from "./transcription-session.js";
 // (e.g. meeting-bot flushing a transcript excerpt) should prefer this over the
 // stateless `provider.sendMessage()` call.
 export type {
+  ConversationChannelAddress,
   RunConversationTurnOptions,
   RunConversationTurnResult,
 } from "./conversation-turn.js";

package/src/plugin-api/vision-support.test.ts

@@ -107,7 +107,7 @@ describe("doesSupportVision", () => {
       managed: { provider: "vellum", model: "claude-fable-5" },
       "managed-text": {
         provider: "vellum",
-        model: "accounts/fireworks/models/deepseek-v4-flash",
+        model: "accounts/fireworks/models/deepseek-v4-flash-0731",
       },
     });
     expect(doesSupportVision(profile("managed"))).toBe(true);