@vellumai/cli 0.10.11-staging.2 → 0.10.12-dev.202607242227.e52a30c

package/node_modules/@vellumai/service-contracts/src/__tests__/secret-detection.test.ts

@@ -0,0 +1,449 @@
+import { describe, expect, test } from "bun:test";
+
+// Self-referencing package import — proves the `./secret-detection` subpath
+// export resolves for consumers.
+import * as subpathExport from "@vellumai/service-contracts/secret-detection";
+
+import {
+  detectSecretsInText,
+  isCompletePrivateKeyBlock,
+  PEM_REDACTION_MAX_BODY_LENGTH,
+  PREFIX_PATTERNS,
+  PRIVATE_KEY_REDACTION_REGEX,
+  REDACTION_PREFIX_PATTERNS,
+  TOKEN_SHAPE,
+  TOKEN_SHAPE_LABEL,
+  TOKEN_SHAPE_MAX_LENGTH,
+} from "../secret-detection.js";
+
+// All fixtures below are synthetic lookalike tokens — never real key material.
+
+function matchingLabels(text: string): string[] {
+  return PREFIX_PATTERNS.filter((p) => p.regex.test(text)).map((p) => p.label);
+}
+
+const ALNUM = "abcdefghijklmnopqrstuvwxyz0123456789";
+
+/** Lowercase-alphanumeric filler of the given length (no separators, so it
+ * can never form another pattern's prefix like `npm_` or `key-`). */
+function filler(length: number): string {
+  return ALNUM.repeat(Math.ceil(length / ALNUM.length)).slice(0, length);
+}
+
+/** One synthetic fixture per provider family, keyed by pattern label. */
+const FIXTURES: Record<string, string> = {
+  "AWS Access Key": "AKIAABCDEFGHIJKLMNOP",
+  "GitHub Token": `ghp_${filler(36)}`,
+  "GitHub Fine-Grained PAT": `github_pat_${filler(22)}`,
+  "GitLab Token": `glpat-${filler(20)}`,
+  "Stripe Secret Key": `sk_live_${filler(24)}`,
+  "Stripe Restricted Key": `rk_live_${filler(24)}`,
+  "Slack Bot Token": `xoxb-1234567890-1234567890-${filler(24)}`,
+  "Slack User Token": `xoxp-1234567890-1234567890-1234567890-${"0123456789abcdef".repeat(2)}`,
+  "Slack App Token": "xapp-1-abc123-4567-defghij890",
+  "Telegram Bot Token": `123456789:${filler(35)}`,
+  "Anthropic API Key": `sk-ant-${filler(80)}`,
+  "OpenAI API Key": `sk-${filler(20)}T3BlbkFJ${filler(20)}`,
+  "OpenAI Project Key": `sk-proj-${filler(40)}`,
+  "Google API Key": `AIza${filler(35)}`,
+  "Google OAuth Client Secret": `GOCSPX-${filler(28)}`,
+  "Twilio API Key": `SK${"0123456789abcdef".repeat(2)}`,
+  "SendGrid API Key": `SG.${filler(22)}.${filler(43)}`,
+  "Mailgun API Key": `key-${filler(32)}`,
+  "npm Token": `npm_${filler(36)}`,
+  "PyPI API Token": `pypi-${filler(50)}`,
+  "Private Key": "-----BEGIN OPENSSH PRIVATE KEY-----",
+  "Linear API Key": `lin_api_${filler(32)}`,
+  "Notion Integration Token": `ntn_${filler(40)}`,
+  "OpenRouter API Key": `sk-or-v1-${filler(40)}`,
+  "Vercel AI Gateway API Key": `vck_${filler(24)}`,
+  "Fireworks API Key": `fw_${filler(32)}`,
+  "Perplexity API Key": `pplx-${filler(40)}`,
+  "Tavily API Key": `tvly-${filler(20)}`,
+  "Firecrawl API Key": `fc-${filler(20)}`,
+};
+
+describe("subpath export", () => {
+  test("@vellumai/service-contracts/secret-detection resolves to this module", () => {
+    expect(subpathExport.PREFIX_PATTERNS).toBe(PREFIX_PATTERNS);
+    expect(subpathExport.detectSecretsInText).toBe(detectSecretsInText);
+  });
+});
+
+describe("PREFIX_PATTERNS", () => {
+  test("every pattern has a fixture", () => {
+    expect(Object.keys(FIXTURES).sort()).toEqual(
+      PREFIX_PATTERNS.map((p) => p.label).sort(),
+    );
+  });
+
+  test("pattern labels are unique", () => {
+    const labels = PREFIX_PATTERNS.map((p) => p.label);
+    expect(new Set(labels).size).toBe(labels.length);
+  });
+
+  // Label-uniqueness invariant: each fixture matches exactly one pattern, so
+  // a detected value always maps to an unambiguous label.
+  for (const [label, fixture] of Object.entries(FIXTURES)) {
+    test(`${label} fixture matches exactly that pattern`, () => {
+      expect(matchingLabels(fixture)).toEqual([label]);
+    });
+  }
+
+  test("does not match a short vck_ string", () => {
+    expect(matchingLabels("vck_abc")).toEqual([]);
+  });
+});
+
+describe("detectSecretsInText — prefix patterns", () => {
+  for (const [label, fixture] of Object.entries(FIXTURES)) {
+    test(`detects a ${label} with the right label and span`, () => {
+      const text = `my key is ${fixture} thanks`;
+      const start = text.indexOf(fixture);
+      expect(detectSecretsInText(text)).toEqual([
+        {
+          label,
+          value: fixture,
+          start,
+          end: start + fixture.length,
+          wholeMessage: false,
+        },
+      ]);
+    });
+  }
+
+  test("does not mutate the shared pattern objects' lastIndex", () => {
+    detectSecretsInText(`ghp_${filler(36)}`);
+    for (const p of PREFIX_PATTERNS) {
+      expect(p.regex.lastIndex).toBe(0);
+    }
+  });
+});
+
+describe("detectSecretsInText — placeholder suppression", () => {
+  test("known placeholder text returns no matches", () => {
+    expect(detectSecretsInText("your-api-key-here")).toEqual([]);
+    expect(detectSecretsInText("sk-xxxxxxxxxxxxxxxxxxxxxxxx")).toEqual([]);
+  });
+
+  test("placeholder-prefixed token-shaped message is suppressed", () => {
+    expect(detectSecretsInText(`fake_key_${filler(20)}`)).toEqual([]);
+    expect(detectSecretsInText(`test_api_${filler(16)}`)).toEqual([]);
+    expect(detectSecretsInText(`dummy-token-${filler(16)}`)).toEqual([]);
+  });
+
+  test("token-shaped message with a placeholder tail is suppressed", () => {
+    // TOKEN_SHAPE matches with tail "replace_with_your_key", which is a
+    // known placeholder.
+    expect(detectSecretsInText("acme_key_replace_with_your_key")).toEqual([]);
+  });
+
+  test("placeholder pre-context suppresses a prefix match (fake_ghp_...)", () => {
+    // The GitHub regex matches starting at `ghp_`, so the `fake_` marker
+    // sits in the pre-context window rather than the matched value.
+    expect(detectSecretsInText(`fake_${"ghp_" + filler(36)}`)).toEqual([]);
+    expect(
+      detectSecretsInText(`docs use example_ghp_${filler(36)} as a stand-in`),
+    ).toEqual([]);
+  });
+
+  test("repeated-character variable portion suppresses a prefix match", () => {
+    // AKIA followed by 16 repeated placeholder characters.
+    expect(detectSecretsInText("AKIAXXXXXXXXXXXXXXXX")).toEqual([]);
+    expect(detectSecretsInText(`set AWS_KEY=AKIA${"X".repeat(16)}`)).toEqual(
+      [],
+    );
+  });
+
+  test("the same tokens without placeholder context still match", () => {
+    const github = `ghp_${filler(36)}`;
+    expect(detectSecretsInText(github).map((m) => m.label)).toEqual([
+      "GitHub Token",
+    ]);
+    expect(
+      detectSecretsInText("AKIAABCDEFGHIJKLMNOP").map((m) => m.label),
+    ).toEqual(["AWS Access Key"]);
+  });
+
+  test("token-shaped message with a repeated-character tail is suppressed", () => {
+    expect(detectSecretsInText(`my_key_${"x".repeat(16)}`)).toEqual([]);
+  });
+});
+
+describe("detectSecretsInText — whole-message token shape", () => {
+  test("a whole-message token-shaped value is detected", () => {
+    const token = `virlo_tkn_${filler(20)}`;
+    expect(TOKEN_SHAPE.test(token)).toBe(true);
+    expect(detectSecretsInText(token)).toEqual([
+      {
+        label: TOKEN_SHAPE_LABEL,
+        value: token,
+        start: 0,
+        end: token.length,
+        wholeMessage: true,
+      },
+    ]);
+  });
+
+  test("surrounding whitespace is trimmed and the span covers the token", () => {
+    const token = `acme_secret_${filler(18)}`;
+    expect(detectSecretsInText(`  ${token} \n`)).toEqual([
+      {
+        label: TOKEN_SHAPE_LABEL,
+        value: token,
+        start: 2,
+        end: 2 + token.length,
+        wholeMessage: true,
+      },
+    ]);
+  });
+
+  test("a normal sentence returns no matches", () => {
+    expect(
+      detectSecretsInText("can you review my pull request today?"),
+    ).toEqual([]);
+    expect(detectSecretsInText("")).toEqual([]);
+  });
+
+  test("token shape is not applied when a prefix pattern already matched", () => {
+    const key = `glpat-${filler(20)}`;
+    const results = detectSecretsInText(key);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.label).toBe("GitLab Token");
+  });
+
+  test("a token-shaped value over the max length is not matched", () => {
+    // Same shape as a valid token but a tail longer than the shared max — the
+    // daemon ingress caps the whole-message heuristic here, so the client must
+    // too or a >512-char paste would warn client-side yet pass server-side.
+    const tail = filler(TOKEN_SHAPE_MAX_LENGTH + 1);
+    const token = `virlo_tkn_${tail}`;
+    expect(token.length).toBeGreaterThan(TOKEN_SHAPE_MAX_LENGTH);
+    expect(TOKEN_SHAPE.test(token)).toBe(true);
+    expect(detectSecretsInText(token)).toEqual([]);
+  });
+
+  test("a token-shaped value exactly at the max length is still matched", () => {
+    const prefix = "virlo_tkn_";
+    const token = `${prefix}${filler(TOKEN_SHAPE_MAX_LENGTH - prefix.length)}`;
+    expect(token.length).toBe(TOKEN_SHAPE_MAX_LENGTH);
+    const results = detectSecretsInText(token);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.label).toBe(TOKEN_SHAPE_LABEL);
+  });
+});
+
+describe("REDACTION_PREFIX_PATTERNS — bounded whole-block private key", () => {
+  const FAKE_PEM_BODY =
+    "MIIFAKEfakefakefakefakefakefakefakefakefake\n" +
+    "FAKEfakefakefakefakefakefakefakefakefake==";
+  const FULL_PEM_BLOCK = `-----BEGIN RSA PRIVATE KEY-----\n${FAKE_PEM_BODY}\n-----END RSA PRIVATE KEY-----`;
+
+  function redactionPrivateKeyRegex(): RegExp {
+    const entry = REDACTION_PREFIX_PATTERNS.find(
+      (p) => p.label === "Private Key",
+    );
+    expect(entry).toBeDefined();
+    return new RegExp(entry!.regex.source, "g");
+  }
+
+  test("the redaction private-key entry is the bounded whole-block matcher", () => {
+    const entry = REDACTION_PREFIX_PATTERNS.find(
+      (p) => p.label === "Private Key",
+    );
+    expect(entry!.regex.source).toBe(PRIVATE_KEY_REDACTION_REGEX.source);
+  });
+
+  test("the redaction variant matches the WHOLE block, not just the header", () => {
+    const regex = redactionPrivateKeyRegex();
+    const match = regex.exec(FULL_PEM_BLOCK);
+    expect(match).not.toBeNull();
+    // The full header→body→footer span, so an in-place replace removes the
+    // key body and footer, not only the BEGIN line.
+    expect(match![0]).toBe(FULL_PEM_BLOCK);
+  });
+
+  test("an in-place replace with the redaction regex leaves no body or footer", () => {
+    const regex = redactionPrivateKeyRegex();
+    const text = `before\n${FULL_PEM_BLOCK}\nafter`;
+    const redacted = text.replace(regex, "[REDACTED]");
+    expect(redacted).toBe("before\n[REDACTED]\nafter");
+    // The base64 body and the END footer are gone.
+    expect(redacted).not.toContain("MIIFAKE");
+    expect(redacted).not.toContain("-----END");
+    expect(redacted).not.toContain("-----BEGIN");
+  });
+
+  test("a footerless key still redacts header-only (truncated-key fallback)", () => {
+    const regex = redactionPrivateKeyRegex();
+    const text = `-----BEGIN RSA PRIVATE KEY-----\n${FAKE_PEM_BODY}`;
+    const match = regex.exec(text);
+    expect(match).not.toBeNull();
+    // No END within the bound → optional footer group fails → header-only
+    // match, preserving the detection-fires guarantee.
+    expect(match![0]).toBe("-----BEGIN RSA PRIVATE KEY-----");
+  });
+
+  test("a body longer than the bound falls back to header-only, not a hang", () => {
+    const regex = redactionPrivateKeyRegex();
+    // Footer sits just past the body bound, so the whole-block branch can't
+    // reach it and the match degrades to the header (fail-open on redaction:
+    // an unbounded key is not a realistic PEM).
+    const overlongBody = "a".repeat(PEM_REDACTION_MAX_BODY_LENGTH + 100);
+    const text = `-----BEGIN RSA PRIVATE KEY-----\n${overlongBody}\n-----END RSA PRIVATE KEY-----`;
+    const match = regex.exec(text);
+    expect(match).not.toBeNull();
+    expect(match![0]).toBe("-----BEGIN RSA PRIVATE KEY-----");
+  });
+
+  test("many footerless BEGIN headers redact fast (bounded, no O(n²) hang)", () => {
+    const regex = redactionPrivateKeyRegex();
+    // A pathological paste: thousands of footerless headers, each followed by
+    // filler that an unbounded matcher would rescan hunting for a footer. The
+    // body bound caps each rescan, so the whole sweep stays linear.
+    const chunk = `-----BEGIN RSA PRIVATE KEY-----\n${filler(200)}\n`;
+    const text = chunk.repeat(5000);
+    const startedAt = Date.now();
+    const redacted = text.replace(regex, "[REDACTED]");
+    const elapsedMs = Date.now() - startedAt;
+    expect(redacted).toContain("[REDACTED]");
+    expect(redacted).not.toContain("-----BEGIN");
+    expect(elapsedMs).toBeLessThan(2000);
+  });
+
+  test("every non-private-key pattern is shared verbatim with PREFIX_PATTERNS", () => {
+    for (let i = 0; i < PREFIX_PATTERNS.length; i++) {
+      if (PREFIX_PATTERNS[i]!.label === "Private Key") {
+        continue;
+      }
+      expect(REDACTION_PREFIX_PATTERNS[i]).toBe(PREFIX_PATTERNS[i]);
+    }
+  });
+
+  test("detectSecretsInText still captures the whole block (P1 stays fixed)", () => {
+    const results = detectSecretsInText(FULL_PEM_BLOCK);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.label).toBe("Private Key");
+    expect(results[0]!.value).toBe(FULL_PEM_BLOCK);
+  });
+});
+
+describe("detectSecretsInText — PEM private-key blocks", () => {
+  // Clearly fake PEM material — never a real key.
+  const FAKE_PEM_BODY =
+    "MIIFAKEfakefakefakefakefakefakefakefakefake\n" +
+    "FAKEfakefakefakefakefakefakefakefakefake==";
+  const FULL_PEM_BLOCK = `-----BEGIN RSA PRIVATE KEY-----\n${FAKE_PEM_BODY}\n-----END RSA PRIVATE KEY-----`;
+
+  test("a complete PEM block is one match spanning header through footer", () => {
+    const text = `here is my key\n${FULL_PEM_BLOCK}\nplease use it`;
+    const start = text.indexOf(FULL_PEM_BLOCK);
+    expect(detectSecretsInText(text)).toEqual([
+      {
+        label: "Private Key",
+        value: FULL_PEM_BLOCK,
+        start,
+        end: start + FULL_PEM_BLOCK.length,
+        wholeMessage: false,
+      },
+    ]);
+  });
+
+  test("a PGP private-key block with the BLOCK suffix is captured whole", () => {
+    const block = `-----BEGIN PGP PRIVATE KEY BLOCK-----\n${FAKE_PEM_BODY}\n-----END PGP PRIVATE KEY BLOCK-----`;
+    const results = detectSecretsInText(block);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.value).toBe(block);
+  });
+
+  test("a header with a body but no END footer still fires — header-only span", () => {
+    // Truncated / partially pasted key: detection must not regress, the
+    // daemon ingress relies on the header alone to block.
+    const text = `-----BEGIN RSA PRIVATE KEY-----\n${FAKE_PEM_BODY}`;
+    const results = detectSecretsInText(text);
+    expect(results).toEqual([
+      {
+        label: "Private Key",
+        value: "-----BEGIN RSA PRIVATE KEY-----",
+        start: 0,
+        end: "-----BEGIN RSA PRIVATE KEY-----".length,
+        wholeMessage: false,
+      },
+    ]);
+    expect(isCompletePrivateKeyBlock(results[0]!.value)).toBe(false);
+  });
+
+  test("adjacent complete blocks match separately, not as one giant span", () => {
+    const text = `${FULL_PEM_BLOCK}\n\n${FULL_PEM_BLOCK}`;
+    const results = detectSecretsInText(text);
+    expect(results).toHaveLength(2);
+    expect(results[0]!.value).toBe(FULL_PEM_BLOCK);
+    expect(results[1]!.value).toBe(FULL_PEM_BLOCK);
+    expect(results[1]!.start).toBeGreaterThanOrEqual(results[0]!.end);
+  });
+
+  test("a footerless header never swallows a later complete block", () => {
+    // The body is tempered — it cannot cross another BEGIN header — so the
+    // truncated first key matches header-only and the second key matches
+    // as its own complete block.
+    const text = `-----BEGIN EC PRIVATE KEY-----\ntruncated\n\n${FULL_PEM_BLOCK}`;
+    const results = detectSecretsInText(text);
+    expect(results.map((r) => r.value)).toEqual([
+      "-----BEGIN EC PRIVATE KEY-----",
+      FULL_PEM_BLOCK,
+    ]);
+  });
+
+  test("a token-lookalike run inside the block body loses to the block", () => {
+    // Base64 can legally contain an AKIA + 16-uppercase run; the Private
+    // Key pattern is first in PREFIX_PATTERNS so the whole-block span wins
+    // the overlap dedupe instead of being fragmented by the AWS pattern.
+    const block = `-----BEGIN RSA PRIVATE KEY-----\nAKIAABCDEFGHIJKLMNOP\n${FAKE_PEM_BODY}\n-----END RSA PRIVATE KEY-----`;
+    const results = detectSecretsInText(block);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.label).toBe("Private Key");
+    expect(results[0]!.value).toBe(block);
+  });
+});
+
+describe("isCompletePrivateKeyBlock", () => {
+  test("true for a value ending at the END footer", () => {
+    expect(
+      isCompletePrivateKeyBlock(
+        "-----BEGIN OPENSSH PRIVATE KEY-----\nMIIFAKEfake==\n-----END OPENSSH PRIVATE KEY-----",
+      ),
+    ).toBe(true);
+  });
+
+  test("false for a header-only match and for non-PEM values", () => {
+    expect(
+      isCompletePrivateKeyBlock("-----BEGIN OPENSSH PRIVATE KEY-----"),
+    ).toBe(false);
+    expect(isCompletePrivateKeyBlock(`ghp_${filler(36)}`)).toBe(false);
+  });
+});
+
+describe("detectSecretsInText — multiple and overlapping matches", () => {
+  test("multiple secrets yield sorted, non-overlapping matches", () => {
+    const aws = "AKIAABCDEFGHIJKLMNOP";
+    const github = `ghp_${filler(36)}`;
+    // GitHub appears before AWS in the text but after it in pattern order.
+    const text = `first ${github} then ${aws} done`;
+    const results = detectSecretsInText(text);
+    expect(results.map((r) => r.label)).toEqual([
+      "GitHub Token",
+      "AWS Access Key",
+    ]);
+    for (let i = 1; i < results.length; i++) {
+      expect(results[i]!.start).toBeGreaterThanOrEqual(results[i - 1]!.end);
+    }
+  });
+
+  test("overlapping spans keep the first pattern in list order", () => {
+    // The GitHub token's tail embeds an `npm_…` run; GitHub Token precedes
+    // npm Token in PREFIX_PATTERNS, so only the GitHub match survives.
+    const value = `ghp_npm_${filler(36)}`;
+    const results = detectSecretsInText(value);
+    expect(results.map((r) => r.label)).toEqual(["GitHub Token"]);
+  });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * 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:
+ * 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",
+] 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)
+  );
+}

package/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/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";