@vellumai/assistant 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

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
 // ---------------------------------------------------------------------------
@@ -158,6 +280,9 @@ export async function runConversationTurn(
     await import("../persistence/conversation-crud.js");
   const { publishConversationListAndMetadataChanged } =
     await import("../runtime/sync/resource-sync-events.js");
+  const { parseInterfaceId } = await import("../channels/types.js");
+  const { resolveChannelCapabilities } =
+    await import("../daemon/conversation-runtime-assembly.js");
 
   // Plugin-driven turns run as the guardian: plugins are installed by the
   // guardian, so their conversations inherit guardian trust. This lets the
@@ -166,8 +291,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 +341,51 @@ 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;
+  // The interface the message arrived on. `plugin` is in both the channel
+  // and interface unions, matching gateway inbound. Tool gating reads this
+  // as `transportInterface`; unset, the loop falls back to `web`.
+  const turnInterfaceContext = options.channel
+    ? (() => {
+        const iface = parseInterfaceId(options.channel.sourceChannel);
+        return iface
+          ? {
+              userMessageInterface: iface,
+              assistantMessageInterface: iface,
+            }
+          : null;
+      })()
+    : null;
+  if (options.channel) {
+    conversation.setChannelCapabilities(
+      resolveChannelCapabilities(
+        options.channel.sourceChannel,
+        turnInterfaceContext?.userMessageInterface,
+      ),
+    );
+  }
+  // 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 ?? {}),
+    ...(turnInterfaceContext ?? {}),
+  };
+
   // 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 +408,7 @@ export async function runConversationTurn(
       onEvent,
       requestId,
       isInteractive: false,
-      metadata: { ...PLUGIN_TURN_MESSAGE_METADATA },
+      metadata,
     });
     if (enqueueResult.rejected) {
       throw new Error(
@@ -236,12 +423,15 @@ export async function runConversationTurn(
     };
   }
 
+  conversation.setTurnChannelContext(turnChannelContext);
+  conversation.setTurnInterfaceContext(turnInterfaceContext);
+
   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

@@ -67,7 +67,11 @@
  */
 
 export type { HookName } from "./constants.js";
-export { HOOKS, INTERNAL_NUDGE_OUTPUT_SUPPRESSION } from "./constants.js";
+export {
+  HOOKS,
+  INTERNAL_NUDGE_OUTPUT_SUPPRESSION,
+  VOICE_ESCALATION_CONTINUATION_MESSAGE_KIND,
+} from "./constants.js";
 // Conversation message/content shapes. A hook receives the live message
 // history (e.g. `PostToolUseContext.latestMessages: Message[]`), so plugins
 // that inspect or narrow content blocks — reading a `tool_use` block's input,
@@ -173,6 +177,18 @@ export {
   CredentialResolutionError,
   resolveCredential,
 } from "./resolve-credential.js";
+// Store a credential's plaintext value (the same write `assistant credentials
+// set` performs), creating it or replacing an existing one, named by UUID or a
+// "service/field" reference. A plugin may only write credentials whose `field`
+// matches its manifest name, and the write fails closed with no plugin in
+// context. Throws CredentialStoreError when there is no calling plugin, the ref
+// is malformed, the value is invalid, the store rejects the write, or the
+// credential is out of the plugin's scope.
+export type {
+  StoreCredentialOptions,
+  StoredCredentialRef,
+} from "./store-credential.js";
+export { CredentialStoreError, storeCredential } from "./store-credential.js";
 // Resolve the public URL a third party should deliver to for one of the
 // plugin's own ingress routes. Which URL is correct depends on how the
 // assistant is reachable (a managed platform callback route, or a configured
@@ -180,6 +196,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 +371,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 +401,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/resolve-credential.ts

@@ -9,8 +9,9 @@
  *
  * ## Plugin scoping
  *
- * When a plugin is in context — its hook or tool is executing, tracked by
- * {@link ../plugins/plugin-execution-context.getCurrentPluginName} — resolution
+ * When a plugin is in context (its hook, tool, or one of its own
+ * `/x/plugins/<name>/` routes is executing, tracked by
+ * {@link ../plugins/plugin-execution-context.getCurrentPluginName}), resolution
  * is restricted: the plugin may only resolve credentials whose `field` equals
  * the plugin's own manifest name. A plugin named `acme` can therefore read
  * `openai/acme` or `stripe/acme` but not `openai/api_key`. Outside any plugin

package/src/plugin-api/store-credential.ts

@@ -0,0 +1,146 @@
+/**
+ * Plugin-facing credential storage.
+ *
+ * {@link storeCredential} writes a credential's plaintext to the secure store,
+ * the same write `assistant credentials set` performs, naming it either by an
+ * existing credential's UUID or by a `"service/field"` string, the same
+ * vocabulary {@link ./resolve-credential.resolveCredential} reads back. A
+ * plugin that obtains a token for itself (an OAuth exchange it drives, a key a
+ * user hands it through its own route) persists it here instead of inventing
+ * its own on-disk secret file.
+ *
+ * ## Plugin scoping
+ *
+ * A plugin may only write credentials whose `field` equals its manifest name,
+ * so `acme` writes `openai/acme` or `stripe/acme` but never `openai/api_key`.
+ * The name comes from the execution context
+ * ({@link ../plugins/plugin-execution-context.getCurrentPluginName}), which the
+ * host establishes around a plugin's hook, tool, and route invocations.
+ *
+ * Unlike the read path, this **fails closed**: with no plugin in context there
+ * is nobody to scope the write to, so it is refused rather than treated as an
+ * unscoped host write. A plugin's module body is evaluated by the loader
+ * outside any context, and an unscoped branch there would let top-level code
+ * overwrite the user's own credentials. Host-internal callers that legitimately
+ * write unscoped (the `credentials/set` route, the CLI behind it) compose
+ * {@link ../tools/credentials/store.storeCredentialValue} directly. This
+ * matches the plugin-owned index (`indexDocument`), which likewise requires a
+ * context because a write with no owner has nothing to attribute.
+ */
+
+import { getCurrentPluginName } from "../plugins/plugin-execution-context.js";
+import { parseServiceFieldRef } from "../tools/credentials/ref-parse.js";
+import { resolveCredentialRef } from "../tools/credentials/resolve.js";
+import { storeCredentialValue } from "../tools/credentials/store.js";
+
+/**
+ * Raised when a credential cannot be stored: the reference is malformed, the
+ * value is empty or invalid for its service, the secure backend rejected the
+ * write, or the calling plugin is not permitted to write the credential.
+ */
+export class CredentialStoreError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialStoreError";
+  }
+}
+
+export interface StoreCredentialOptions {
+  /** Human-friendly alias shown in credential listings. */
+  label?: string;
+  /** What the credential is for, surfaced to the agent. */
+  description?: string;
+  /**
+   * Skip the retroactive sweep that removes the value from recent transcripts.
+   * The sweep exists because a secret is often pasted into chat before it is
+   * stored; pass `true` only for a value that provably never transited a
+   * conversation, such as a token minted by an OAuth refresh.
+   */
+  skipTranscriptScrub?: boolean;
+}
+
+/** Identity of the credential that was written. */
+export interface StoredCredentialRef {
+  credentialId: string;
+  service: string;
+  field: string;
+}
+
+/**
+ * Store a credential's plaintext value, creating it or replacing the value of
+ * an existing one.
+ *
+ * @param ref A credential UUID (an existing credential) or a `"service/field"`
+ *   string (created when no such credential exists).
+ * @param value The plaintext value. Edge whitespace is trimmed.
+ * @returns The identity of the stored credential, which
+ *   {@link ./resolve-credential.resolveCredential} accepts as a ref.
+ * @throws {CredentialStoreError} when no plugin is in context, the ref is
+ *   malformed or names no credential, the value is empty or invalid for its
+ *   service, the store rejects the write, or the calling plugin is not scoped
+ *   to the credential.
+ */
+export async function storeCredential(
+  ref: string,
+  value: string,
+  options: StoreCredentialOptions = {},
+): Promise<StoredCredentialRef> {
+  // Both gates run before anything is written, so a refused write never
+  // touches the secure backend. Fail closed when there is no plugin to scope
+  // to: a plugin's module body is evaluated outside any context, and an
+  // unscoped branch there would be a way to overwrite the user's credentials.
+  const pluginName = getCurrentPluginName();
+  if (pluginName === undefined) {
+    throw new CredentialStoreError(
+      "storeCredential requires an active plugin execution context (no calling plugin found). " +
+        "Call it from a hook, tool, or route handler rather than at module scope.",
+    );
+  }
+
+  const target = resolveStoreTarget(ref);
+  if (target.field !== pluginName) {
+    throw new CredentialStoreError(
+      `Plugin "${pluginName}" may only store credentials whose field matches its name; ` +
+        `"${target.service}/${target.field}" is out of scope.`,
+    );
+  }
+
+  try {
+    return await storeCredentialValue({
+      service: target.service,
+      field: target.field,
+      value,
+      alias: options.label,
+      usageDescription: options.description,
+      skipTranscriptScrub: options.skipTranscriptScrub,
+    });
+  } catch (err) {
+    throw new CredentialStoreError(
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+}
+
+/**
+ * Resolve the `ref` a write targets. An existing credential (by UUID or by
+ * `"service/field"`) keeps its identity; otherwise the ref must name the
+ * service and field of the credential to create, which a bare UUID cannot.
+ */
+function resolveStoreTarget(ref: string): { service: string; field: string } {
+  if (!ref || ref.trim().length === 0) {
+    throw new CredentialStoreError("Credential reference is required");
+  }
+
+  const existing = resolveCredentialRef(ref);
+  if (existing) {
+    return { service: existing.service, field: existing.field };
+  }
+
+  const parsed = parseServiceFieldRef(ref);
+  if (!parsed) {
+    throw new CredentialStoreError(
+      `Cannot store credential: "${ref}" matches no stored credential and is not a "service/field" reference`,
+    );
+  }
+  return parsed;
+}

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);

package/src/plugin-api/webhook-url.ts

@@ -90,22 +90,24 @@ function registrationType(plugin: string, route: string): string {
 }
 
 /**
- * Drop a trailing slash from a resolved callback URL.
+ * Keep a trailing slash on a resolved callback URL.
  *
- * The platform appends one to the callback URLs it hands back, and a provider
- * given `.../events-comms/` delivers to that spelling verbatim. The gateway
- * matches a plugin route against its declared path, which may never end in a
- * slash (see `IngressRouteSchema`), so the slash comes off once here rather
- * than at each plugin that registers a URL.
+ * Django in front of managed callbacks canonicalizes onto `/`. A vendor given
+ * the slashless spelling is 301'd, and clients that follow a 301 on POST
+ * typically retry as GET and drop the body. The gateway serves both spellings
+ * of a plugin webhook, so the slashed URL is the one to hand out.
  *
- * Only the path is ever trimmed: this resolver passes no query parameters, and
- * a URL carrying one is left alone rather than truncated.
+ * Query-bearing URLs are left alone: this resolver passes no query
+ * parameters, and appending there would cut into the query rather than the
+ * path. The callback path registered with the platform stays slashless. The
+ * platform strips slashes on store, and Django's path converter typically
+ * does not include the final `/` in the lookup key.
  */
-function withoutTrailingSlash(url: string): string {
+function withTrailingSlash(url: string): string {
   if (url.includes("?") || url.includes("#")) {
     return url;
   }
-  return url.replace(/\/+$/, "");
+  return url.endsWith("/") ? url : `${url}/`;
 }
 
 /**
@@ -147,5 +149,5 @@ export async function resolveWebhookUrl(
     undefined,
     sourceIdentifier,
   );
-  return withoutTrailingSlash(resolved);
+  return withTrailingSlash(resolved);
 }