@vellumai/cli 0.11.6 → 0.11.7-staging.2

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/attachment-naming.ts

@@ -0,0 +1,118 @@
+/**
+ * Attachment filename contract shared by the daemon (which materializes
+ * `vellum://` links and `<vellum-attachment>` directives into stored
+ * attachments) and the web client (which resolves clicked links back to
+ * those attachments). Both sides must agree on the stored filename, so the
+ * naming rule lives here once.
+ */
+
+const EXTENSION_MIME_MAP: Record<string, string> = {
+  // Images
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  ico: "image/x-icon",
+  bmp: "image/bmp",
+  heic: "image/heic",
+  heif: "image/heif",
+
+  // Documents
+  pdf: "application/pdf",
+  json: "application/json",
+  xml: "application/xml",
+  csv: "text/csv",
+  txt: "text/plain",
+  md: "text/markdown",
+  html: "text/html",
+  css: "text/css",
+  js: "text/javascript",
+  ts: "text/typescript",
+
+  // Audio
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  flac: "audio/flac",
+  aac: "audio/aac",
+  m4a: "audio/x-m4a",
+  opus: "audio/opus",
+
+  // Video
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mov: "video/quicktime",
+  mpeg: "video/mpeg",
+
+  // Archives
+  zip: "application/zip",
+  gz: "application/gzip",
+  tar: "application/x-tar",
+};
+
+/**
+ * Infer a MIME type from a filename extension.
+ * Returns `application/octet-stream` when the extension is unrecognised.
+ */
+export function inferMimeType(filename: string): string {
+  const dot = filename.lastIndexOf(".");
+  if (dot === -1) {
+    return "application/octet-stream";
+  }
+  const ext = filename.slice(dot + 1).toLowerCase();
+  return EXTENSION_MIME_MAP[ext] ?? "application/octet-stream";
+}
+
+/**
+ * Pick the stored attachment filename for a materialized file directive.
+ *
+ * Explicit filenames (`<vellum-attachment filename="..." />` attributes)
+ * are an authoring contract and always used verbatim. Link display text
+ * (`[label](vellum://...)`) is cosmetic: it is only honored as the filename
+ * when it carries a recognized extension. A bare label
+ * (e.g. `[desktop](vellum://.../shot.png)`) would otherwise produce an
+ * extensionless download with an `application/octet-stream` MIME type,
+ * which macOS opens as raw text. In that case the label keeps the path's
+ * extension (`desktop.png`), staying unique per link even when several
+ * links share a basename; the raw basename is the last resort.
+ *
+ * The basename fallback splits on both `/` and `\\` so it handles POSIX
+ * sandbox paths, `vellum://` URL paths, and Windows host paths alike.
+ * Splitting on both separators regardless of the runtime platform also
+ * covers Windows host paths resolved by a non-Windows daemon, which
+ * platform-selected `node:path` semantics cannot.
+ */
+export function resolveAttachmentFilename(
+  preferred: string | undefined,
+  resolvedPath: string,
+  filenameSource: "explicit" | "label" = "explicit",
+): string {
+  const fallback =
+    resolvedPath.split(/[\\/]/).filter(Boolean).pop() ?? resolvedPath;
+  if (!preferred) {
+    return fallback;
+  }
+  if (filenameSource === "explicit") {
+    return preferred;
+  }
+  if (inferMimeType(preferred) !== "application/octet-stream") {
+    return preferred;
+  }
+  // Bare label: keep the label as a per-link disambiguator (two links to
+  // different files sharing a basename must not collide, because the
+  // transcript resolves clicks by filename) and append the path's
+  // extension so the stored name carries the correct type. Skip the
+  // append when the label already ends with that extension (a label like
+  // `report.xlsx` for `report.xlsx` must not become `report.xlsx.xlsx`).
+  const dot = fallback.lastIndexOf(".");
+  if (dot > 0 && dot < fallback.length - 1) {
+    const ext = fallback.slice(dot + 1);
+    if (preferred.toLowerCase().endsWith(`.${ext.toLowerCase()}`)) {
+      return preferred;
+    }
+    return `${preferred}.${ext}`;
+  }
+  return fallback;
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+
+export const CHANNEL_IDS = [
+  "telegram",
+  "phone",
+  "vellum",
+  "whatsapp",
+  "slack",
+  "email",
+  "platform",
+  "a2a",
+  "discord",
+  "plugin",
+] as const;
+
+export type ChannelId = (typeof CHANNEL_IDS)[number];
+
+export function isChannelId(value: unknown): value is ChannelId {
+  return (
+    typeof value === "string" &&
+    (CHANNEL_IDS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * The provider key holding each channel's bot credential.
+ *
+ * Two senses of "connected" share the provider registry: a provider the user
+ * authorized so the assistant can act **as them** (`slack`, `discord`,
+ * `google`), and a bot credential letting people reach the assistant **as
+ * itself**. Nothing in a provider key says which, and the naming actively
+ * misleads: `slack` and `discord` name the user integration while their bots
+ * take a `_channel` suffix, yet `telegram` *is* the bot, because Telegram has
+ * no user-identity integration.
+ *
+ * That irregularity is why this is stated rather than derived from the key,
+ * and it is stated here because this file already owns what a channel is.
+ *
+ * Deliberately only the key. What fields each credential requires is declared
+ * once already, per service, in the gateway's credential specs; restating it
+ * here would be a second copy of a different fact.
+ *
+ * Channels absent from this map reach the assistant without a bot credential
+ * of their own: `phone` through the voice provider, `vellum` and `platform`
+ * internally.
+ */
+export const CHANNEL_BOT_PROVIDER = {
+  slack: "slack_channel",
+  discord: "discord_channel",
+  telegram: "telegram",
+} as const satisfies Partial<Record<ChannelId, string>>;
+
+/**
+ * Whether a provider key names a bot the assistant is reached through, rather
+ * than a grant letting it act as the user. This is the "which sense of
+ * connected" question, for any provider key.
+ */
+export function isChannelBotProvider(providerKey: string): boolean {
+  return (Object.values(CHANNEL_BOT_PROVIDER) as readonly string[]).includes(
+    providerKey,
+  );
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/client-metadata.ts

@@ -0,0 +1,46 @@
+/**
+ * Client-metadata analytics headers.
+ *
+ * The web client attaches these to every daemon request via
+ * `getClientRegistrationHeaders()` (`clients/web/src/lib/telemetry/
+ * client-identity.ts`), the gateway allows them through webview CORS
+ * (`gateway/src/http/middleware/cors.ts`) and forwards them to the daemon
+ * by `x-vellum-*` prefix, and the daemon persists them under
+ * `metadata.client` on user messages (`handleSendMessage`), where
+ * `turn-events-store` projects them onto `TurnTelemetryEvent.client` for
+ * downstream analytics.
+ *
+ * Keys are the persisted `metadata.client` field names; values are the
+ * lowercase HTTP header names (HTTP header matching is case-insensitive).
+ */
+export const CLIENT_METADATA_HEADERS = {
+  browser_family: "x-vellum-browser-family",
+  browser_version: "x-vellum-browser-version",
+  os: "x-vellum-client-os",
+  interface_version: "x-vellum-interface-version",
+} as const;
+
+export type ClientMetadataField = keyof typeof CLIENT_METADATA_HEADERS;
+
+/**
+ * Bound on client-metadata header values: lowercase alphanumerics plus
+ * dot / underscore / dash, at most 64 chars. Enforced identically by the
+ * sender (web client) and the reader (daemon) so malformed or oversized
+ * values are dropped rather than transmitted or persisted.
+ */
+const CLIENT_METADATA_VALUE_RE = /^[a-z0-9._-]{1,64}$/;
+
+/**
+ * Normalize a candidate client-metadata value (trim + lowercase) and
+ * validate it against {@link CLIENT_METADATA_VALUE_RE}. Returns `undefined`
+ * for empty or out-of-bounds values.
+ */
+export function sanitizeClientMetadataValue(
+  value: string | undefined | null,
+): string | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (!normalized) {
+    return undefined;
+  }
+  return CLIENT_METADATA_VALUE_RE.test(normalized) ? normalized : undefined;
+}

package/node_modules/@vellumai/local-mode/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/local-mode/node_modules/@vellumai/service-contracts/src/credential-rpc.ts

@@ -0,0 +1,21 @@
+/**
+ * @vellumai/service-contracts/credential-rpc
+ *
+ * Domain entrypoint for the CES (Credential Execution Service) transport and
+ * RPC surface. Re-exports the transport/RPC/handles/error contracts without
+ * the trust-rule helpers.
+ *
+ * Prefer this subpath over the root `.` import when you only need the
+ * credential RPC surface:
+ *
+ *   import { CesRpcMethod, GetCredentialSchema } from "@vellumai/service-contracts/credential-rpc";
+ *
+ * For trust-rule types use the dedicated subpath:
+ *
+ *   import { TrustRule, parseTrustRule } from "@vellumai/service-contracts/trust-rules";
+ */
+
+export * from "./transport.js";
+export * from "./error.js";
+export * from "./handles.js";
+export * from "./rpc.js";

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/error.ts

@@ -0,0 +1,26 @@
+/**
+ * RPC error schema — extracted to its own module to avoid circular
+ * dependencies between index.ts and rpc.ts.
+ */
+
+import { z } from "zod";
+
+export const RpcErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  /** Optional structured details for debugging. */
+  details: z.record(z.string(), z.unknown()).optional(),
+});
+export type RpcError = z.infer<typeof RpcErrorSchema>;
+
+/**
+ * Error returned when a local_static credential handle is used in managed
+ * mode. v2 stores use a UID-independent `store.key` file that removes the
+ * technical barrier (legacy v1 relied on PBKDF2 key derivation from user
+ * identity, which broke across container users). The restriction is now a
+ * policy choice: managed deployments use platform_oauth handles exclusively
+ * for simpler lifecycle and centralized token management.
+ */
+export const MANAGED_LOCAL_STATIC_REJECTION_ERROR =
+  "local_static credential handles are not supported in managed mode. " +
+  "Use platform_oauth handles for managed deployments.";