@vellumai/assistant 0.12.0 → 0.12.1-dev.202609141913.5e16607

package/src/oauth/byo-connection.ts

@@ -21,11 +21,29 @@ const log = getLogger("byo-oauth-connection");
 /** Default per-request timeout to prevent hung requests from blocking indefinitely. */
 const REQUEST_TIMEOUT_MS = 30_000;
 
+/**
+ * How the access token is attached to an outbound request. Almost every
+ * provider reads `Authorization: Bearer <token>`; a few use their own header
+ * (Shopify's Admin API reads `X-Shopify-Access-Token` and ignores
+ * Authorization entirely). Derived from the provider's header-type injection
+ * template so the seed is the single source of truth.
+ */
+export interface BYOTokenHeader {
+  name: string;
+  /** Text placed before the token, e.g. `"Bearer "`, `"Bot "`, or `""`. */
+  valuePrefix: string;
+}
+
 export interface BYOOAuthConnectionOptions {
   id: string;
   provider: string;
   baseUrl: string;
   accountInfo: string | null;
+  /**
+   * Token header override. When omitted the connection falls back to
+   * `Authorization: Bearer` (or `Bot` for discord_channel).
+   */
+  tokenHeader?: BYOTokenHeader | null;
 }
 
 export class BYOOAuthConnection implements OAuthConnection {
@@ -34,12 +52,14 @@ export class BYOOAuthConnection implements OAuthConnection {
   readonly accountInfo: string | null;
 
   private readonly baseUrl: string;
+  private readonly tokenHeader: BYOTokenHeader | null;
 
   constructor(opts: BYOOAuthConnectionOptions) {
     this.id = opts.id;
     this.provider = opts.provider;
     this.baseUrl = opts.baseUrl;
     this.accountInfo = opts.accountInfo;
+    this.tokenHeader = opts.tokenHeader ?? null;
   }
 
   async request(req: OAuthConnectionRequest): Promise<OAuthConnectionResponse> {
@@ -51,8 +71,12 @@ export class BYOOAuthConnection implements OAuthConnection {
         // Discord bot tokens authenticate with the `Bot ` scheme, not
         // `Bearer`. Sending Bearer here reaches Discord as an unusable
         // credential and comes back 401, which reads as a revoked token.
-        const authScheme =
-          this.provider === "discord_channel" ? "Bot" : "Bearer";
+        // Providers with their own token header (Shopify) override the
+        // whole thing via `tokenHeader`.
+        const tokenHeader: BYOTokenHeader = this.tokenHeader ?? {
+          name: "Authorization",
+          valuePrefix: this.provider === "discord_channel" ? "Bot " : "Bearer ",
+        };
         const requestPath = isTelegram
           ? buildTelegramBotApiPath(req.path, token)
           : req.path;
@@ -93,16 +117,22 @@ export class BYOOAuthConnection implements OAuthConnection {
           }
         }
         if (!isTelegram) {
-          headers.set("Authorization", `${authScheme} ${token}`);
+          // The credential always wins over a caller-supplied value, and a
+          // provider that reads its own header must not also receive a
+          // stray Authorization the caller happened to send.
+          if (tokenHeader.name.toLowerCase() !== "authorization") {
+            headers.delete("Authorization");
+          }
+          headers.set(tokenHeader.name, `${tokenHeader.valuePrefix}${token}`);
         }
 
         const resp = await fetch(fullUrl, {
           method: req.method,
           headers,
           body: hasBody
-            ? (binaryBody !== undefined
-                ? Buffer.from(binaryBody)
-                : (rawBody ?? JSON.stringify(req.body)))
+            ? binaryBody !== undefined
+              ? Buffer.from(binaryBody)
+              : (rawBody ?? JSON.stringify(req.body))
             : undefined,
           // Following a redirect would replay a POST as a GET against a URL
           // the caller never asked for, and hide the 3xx from them.

package/src/oauth/connection-resolver.test.ts

@@ -75,6 +75,7 @@ import {
   resolveEffectiveBaseUrl,
   resolveOAuthConnection,
   resolveOAuthConnectionWithMeta,
+  resolveTokenHeader,
 } from "./connection-resolver.js";
 import { PlatformOAuthConnection } from "./platform-connection.js";
 
@@ -753,3 +754,75 @@ describe("resolveEffectiveBaseUrl", () => {
     ).toBe("https://gmail.googleapis.com/gmail/v1/users/me");
   });
 });
+
+describe("resolveTokenHeader", () => {
+  const shopify = JSON.stringify([
+    {
+      hostPattern: "*.myshopify.com",
+      injectionType: "header",
+      headerName: "X-Shopify-Access-Token",
+      valuePrefix: "",
+    },
+  ]);
+
+  test("returns null when the provider declares no templates", () => {
+    expect(resolveTokenHeader(undefined, "https://api.example.com")).toBeNull();
+    expect(resolveTokenHeader(null, "https://api.example.com")).toBeNull();
+    expect(resolveTokenHeader("[]", "https://api.example.com")).toBeNull();
+  });
+
+  test("returns null for malformed JSON", () => {
+    expect(
+      resolveTokenHeader("{not json", "https://api.example.com"),
+    ).toBeNull();
+  });
+
+  test("ignores non-header injection templates", () => {
+    const query = JSON.stringify([
+      {
+        hostPattern: "api.example.com",
+        injectionType: "query",
+        headerName: "",
+      },
+    ]);
+    expect(resolveTokenHeader(query, "https://api.example.com")).toBeNull();
+  });
+
+  test("picks the template whose wildcard host pattern matches the base URL", () => {
+    const templates = JSON.stringify([
+      {
+        hostPattern: "api.other.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
+      ...JSON.parse(shopify),
+    ]);
+    expect(
+      resolveTokenHeader(templates, "https://example-store.myshopify.com"),
+    ).toEqual({ name: "X-Shopify-Access-Token", valuePrefix: "" });
+  });
+
+  test("falls back to the first header template when the host cannot be matched", () => {
+    // A still-templated base URL is not a parseable URL.
+    expect(resolveTokenHeader(shopify, "https://{tenant_host}")).toEqual({
+      name: "X-Shopify-Access-Token",
+      valuePrefix: "",
+    });
+  });
+
+  test("preserves the Bot prefix for discord_channel", () => {
+    const discord = JSON.stringify([
+      {
+        hostPattern: "discord.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bot ",
+      },
+    ]);
+    expect(resolveTokenHeader(discord, "https://discord.com/api")).toEqual({
+      name: "Authorization",
+      valuePrefix: "Bot ",
+    });
+  });
+});

package/src/oauth/connection-resolver.ts

@@ -6,7 +6,7 @@ import {
 } from "../config/schemas/services.js";
 import { VellumPlatformClient } from "../platform/client.js";
 import { getLogger } from "../util/logger.js";
-import { BYOOAuthConnection } from "./byo-connection.js";
+import { BYOOAuthConnection, type BYOTokenHeader } from "./byo-connection.js";
 import type { OAuthConnection } from "./connection.js";
 import { getConnectionAccessTokenResult } from "./credential-token-resolver.js";
 import { syncManualTokenConnection } from "./manual-token-connection.js";
@@ -215,15 +215,108 @@ export async function resolveOAuthConnectionWithMeta(
     );
   }
 
+  const effectiveBaseUrl = resolveEffectiveBaseUrl(
+    conn.provider,
+    baseUrl,
+    conn.metadata,
+  );
   const connection = new BYOOAuthConnection({
     id: conn.id,
     provider: conn.provider,
-    baseUrl: resolveEffectiveBaseUrl(conn.provider, baseUrl, conn.metadata),
+    baseUrl: effectiveBaseUrl,
     accountInfo: conn.accountInfo,
+    tokenHeader: resolveTokenHeader(
+      providerRow?.injectionTemplates,
+      effectiveBaseUrl,
+    ),
   });
   return { connection, ambiguous, allAccounts };
 }
 
+/**
+ * Pick the header a provider expects its access token in from the seed's
+ * header-type injection templates.
+ *
+ * Prefers the template whose `hostPattern` matches the base URL's host
+ * (`*.myshopify.com` style globs included), then falls back to the first
+ * header template. Returns `null` when the provider declares none, which
+ * leaves `BYOOAuthConnection` on its `Authorization: Bearer` default.
+ *
+ * Shopify is why this exists: its Admin API reads `X-Shopify-Access-Token`
+ * and ignores `Authorization`, so a Bearer header reaches the shop as an
+ * unauthenticated request and comes back 401.
+ */
+export function resolveTokenHeader(
+  rawTemplates: string | null | undefined,
+  baseUrl: string,
+): BYOTokenHeader | null {
+  if (!rawTemplates) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawTemplates);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(parsed)) {
+    return null;
+  }
+
+  const headerTemplates = parsed.filter(
+    (
+      t,
+    ): t is {
+      hostPattern?: unknown;
+      headerName: string;
+      valuePrefix?: unknown;
+    } =>
+      typeof t === "object" &&
+      t !== null &&
+      (t as { injectionType?: unknown }).injectionType === "header" &&
+      typeof (t as { headerName?: unknown }).headerName === "string" &&
+      (t as { headerName: string }).headerName.trim() !== "",
+  );
+  if (headerTemplates.length === 0) {
+    return null;
+  }
+
+  let host = "";
+  try {
+    host = new URL(baseUrl).hostname.toLowerCase();
+  } catch {
+    // Templated or malformed base URLs (e.g. a still-unfilled
+    // `https://{tenant_host}`) cannot be matched by host; fall through to
+    // the first header template.
+  }
+  const matching =
+    host === ""
+      ? undefined
+      : headerTemplates.find(
+          (t) =>
+            typeof t.hostPattern === "string" &&
+            hostMatchesPattern(host, t.hostPattern),
+        );
+  const chosen = matching ?? headerTemplates[0];
+  return {
+    name: chosen.headerName.trim(),
+    valuePrefix:
+      typeof chosen.valuePrefix === "string" ? chosen.valuePrefix : "",
+  };
+}
+
+function hostMatchesPattern(host: string, pattern: string): boolean {
+  const p = pattern.trim().toLowerCase();
+  if (p === "") {
+    return false;
+  }
+  if (p.startsWith("*.")) {
+    const suffix = p.slice(1); // ".myshopify.com"
+    return host.endsWith(suffix) && host.length > suffix.length;
+  }
+  return host === p;
+}
+
 /**
  * Resolve the effective API base URL for a connection, preferring per-tenant
  * values stored on the connection's `metadata` over the provider's static

package/src/oauth/seed-providers.ts

@@ -1329,6 +1329,171 @@ export const PROVIDER_SEED_DATA: Record<
     identityUrl: "https://api.link.com/userinfo",
     identityResponsePaths: ["email", "phone"],
   },
+  shopify: {
+    provider: "shopify",
+    // Shopify is per-tenant: every OAuth endpoint lives on the merchant's own
+    // myshopify.com domain, so these carry a {tenant_host} placeholder the
+    // platform fills in from the shop domain the user supplies at connect
+    // time. There is no global Shopify authorization host to point at.
+    authorizeUrl: "https://{tenant_host}/admin/oauth/authorize",
+    tokenExchangeUrl: "https://{tenant_host}/admin/oauth/access_token",
+    // Requesting `expiring=1` at token exchange yields a short-lived access
+    // token plus a refresh token, which is refreshed against the same
+    // per-shop endpoint.
+    refreshUrl: "https://{tenant_host}/admin/oauth/access_token",
+    pingUrl: "https://{tenant_host}/admin/api/2026-07/shop.json",
+    baseUrl: "https://{tenant_host}",
+    displayLabel: "Shopify",
+    description: "Products, orders, customers, and inventory",
+    dashboardUrl: "https://shopify.dev/dashboard",
+    clientIdPlaceholder: null,
+    logoUrl: "https://cdn.simpleicons.org/shopify",
+    // Shopify parses `scope` as a comma-separated list. A space-separated
+    // list is read as one malformed scope and the request is rejected.
+    scopeSeparator: ",",
+    // Admin API scopes only: Storefront, Customer Account and Shop APIs are
+    // buyer-facing surfaces an assistant has no use for. Every scope here is
+    // grantable without Shopify approval -- the approval-gated ones
+    // (read_all_orders, customer payment methods, subscription contracts,
+    // dispute evidence) are deliberately absent, because Shopify rejects the
+    // whole authorization request if the app cannot grant a requested scope.
+    // A write_* grant implies its read_* counterpart, so the response may
+    // name only the write scope.
+    defaultScopes: [
+      "read_products",
+      "write_products",
+      "read_orders",
+      "write_orders",
+      "read_draft_orders",
+      "write_draft_orders",
+      "read_customers",
+      "write_customers",
+      "read_inventory",
+      "read_locations",
+      "read_fulfillments",
+      "read_discounts",
+      "write_discounts",
+      "read_price_rules",
+    ],
+    availableScopes: [
+      {
+        scope: "read_products",
+        description: "Read products, variants, and collections",
+      },
+      {
+        scope: "write_products",
+        description: "Create and update products, variants, and collections",
+      },
+      {
+        scope: "read_orders",
+        description: "Read orders, transactions, and abandoned checkouts",
+      },
+      {
+        scope: "write_orders",
+        description: "Create and update orders and fulfillments",
+      },
+      { scope: "read_draft_orders", description: "Read draft orders" },
+      {
+        scope: "write_draft_orders",
+        description: "Create and update draft orders",
+      },
+      {
+        scope: "read_customers",
+        description: "Read customers, segments, and companies",
+      },
+      {
+        scope: "write_customers",
+        description: "Create and update customers and segments",
+      },
+      {
+        scope: "read_inventory",
+        description: "Read inventory levels and items",
+      },
+      {
+        scope: "write_inventory",
+        description: "Adjust inventory levels and items",
+      },
+      { scope: "read_locations", description: "Read store locations" },
+      { scope: "read_fulfillments", description: "Read fulfillment services" },
+      {
+        scope: "write_fulfillments",
+        description: "Create and update fulfillment services",
+      },
+      { scope: "read_discounts", description: "Read discounts" },
+      { scope: "write_discounts", description: "Create and update discounts" },
+      { scope: "read_price_rules", description: "Read price rules" },
+      {
+        scope: "write_price_rules",
+        description: "Create and update price rules",
+      },
+      { scope: "read_files", description: "Read files uploaded to the store" },
+      { scope: "write_files", description: "Upload and update files" },
+      { scope: "read_gift_cards", description: "Read gift cards" },
+      {
+        scope: "write_gift_cards",
+        description: "Create and update gift cards",
+      },
+      { scope: "read_returns", description: "Read returns" },
+      { scope: "write_returns", description: "Create and update returns" },
+      { scope: "read_markets", description: "Read markets" },
+      { scope: "read_locales", description: "Read shop locales" },
+      {
+        scope: "read_shipping",
+        description: "Read shipping and delivery carrier services",
+      },
+      { scope: "read_analytics", description: "Read analytics and reports" },
+      {
+        scope: "read_marketing_events",
+        description: "Read marketing events and activities",
+      },
+      { scope: "read_order_edits", description: "Read order edits" },
+      {
+        scope: "write_order_edits",
+        description: "Create and apply order edits",
+      },
+      {
+        scope: "read_metaobjects",
+        description: "Read metaobjects and their definitions",
+      },
+      {
+        scope: "write_metaobjects",
+        description: "Create and update metaobjects",
+      },
+      { scope: "read_translations", description: "Read translated content" },
+      {
+        scope: "read_shopify_payments_payouts",
+        description: "Read Shopify Payments payouts and balance",
+      },
+      {
+        scope: "read_shopify_payments_disputes",
+        description: "Read Shopify Payments disputes",
+      },
+    ],
+    loopbackPort: 17341,
+    managedServiceConfigKey: "shopify-oauth",
+    injectionTemplates: [
+      {
+        hostPattern: "*.myshopify.com",
+        injectionType: "header",
+        headerName: "X-Shopify-Access-Token",
+        valuePrefix: "",
+      },
+    ],
+    appType: "App",
+    setupNotes: [
+      "Shopify OAuth is per-shop: the authorize, token and API endpoints all live on the merchant's own myshopify.com domain, so connecting requires the shop domain (for example your-store.myshopify.com) alongside the usual credentials.",
+      "The Admin API authenticates with the X-Shopify-Access-Token header rather than an Authorization Bearer header.",
+    ],
+    // The Admin API's shop endpoint nests its payload under "shop"; the
+    // myshopify domain is the stable, human-recognisable handle.
+    identityUrl: "https://{tenant_host}/admin/api/2026-07/shop.json",
+    identityResponsePaths: ["shop.myshopify_domain", "shop.name"],
+    // Gated like monday/figma/stripe-link: the platform side and the
+    // shop-domain input in the clients land separately, and until both are
+    // in place a visible Shopify tile would offer a connect flow that
+    // cannot complete.
+    featureFlag: "shopify-oauth",
+  },
 };
 
 export const SEEDED_PROVIDER_KEYS = new Set(Object.keys(PROVIDER_SEED_DATA));

package/src/outbound-proxy/certs.ts

@@ -2,6 +2,8 @@ import { X509Certificate } from "node:crypto";
 import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { writeCombinedCABundle } from "../util/ca-bundle.js";
+
 const CA_CERT_FILENAME = "ca.pem";
 const CA_KEY_FILENAME = "ca-key.pem";
 const COMBINED_CA_FILENAME = "combined-ca-bundle.pem";
@@ -263,11 +265,7 @@ export async function ensureCombinedCABundle(
   }
 
   try {
-    const [systemCAs, proxyCACert] = await Promise.all([
-      readFile(systemBundlePath, "utf-8"),
-      readFile(caCertPath, "utf-8"),
-    ]);
-    await writeFile(combinedPath, systemCAs + "\n" + proxyCACert);
+    await writeCombinedCABundle(systemBundlePath, caCertPath, combinedPath);
     return combinedPath;
   } catch {
     return null;

package/src/permissions/checker.test.ts

@@ -15,13 +15,16 @@ mock.module("../config/assistant-feature-flags.js", () => ({
 }));
 
 // `buildPolicyContext` (used by the integration tests below) precomputes the
-// proc-to-skills gate via `isV3TierActive`. Drive it through this slot so a
-// test can put the production threading path in the active / inactive state.
+// retrospective skill-improvement gate. Keep the v3 tier active while the
+// dedicated gate changes so the production threading test covers the new
+// opt-out rather than the old v3 condition.
 let mockV3TierActive = true;
+let mockSkillImprovementActive = true;
 mock.module("../config/memory-v3-gate.js", () => ({
   isMemoryEnabled: (config?: { memory?: { enabled?: boolean } }) =>
     config?.memory?.enabled !== false,
   isV3TierActive: () => mockV3TierActive,
+  isSkillImprovementActive: () => mockSkillImprovementActive,
   isMemoryV3Live: () => mockV3TierActive,
   usesConceptPageMemory: (memory?: {
     enabled?: boolean;
@@ -219,6 +222,7 @@ describe("Permission Checker (gateway IPC)", () => {
     mockCachedThreshold = "low";
     mockRefreshedThreshold = null;
     mockV3TierActive = true;
+    mockSkillImprovementActive = true;
     thresholdCallLog.length = 0;
     mockSkillCatalog = [];
     mockResolvedSkill = null;
@@ -1173,10 +1177,11 @@ describe("Permission Checker (gateway IPC)", () => {
     });
 
     test("grant does NOT fire when proc-to-skills is inactive, even for the retrospective turn", async () => {
-      // Same retrospective ToolContext, but the feature is inactive (flag off
-      // or v3 not live). buildPolicyContext stamps `procToSkillsActive: false`,
-      // so the grant is dead and the high-risk scaffold prompts.
-      mockV3TierActive = false;
+      // The retrospective keeps its live v3 tier, but this independent flag is
+      // off. buildPolicyContext stamps `procToSkillsActive: false`, so the
+      // grant is dead and the high-risk scaffold prompts.
+      mockV3TierActive = true;
+      mockSkillImprovementActive = false;
       mockIpcClassifyRiskResult = {
         risk: "high",
         reason: "Skill scaffold",

package/src/persistence/compaction-log-store-clickhouse.ts

@@ -26,6 +26,7 @@
  */
 import type { AgentEvent } from "../agent/loop.js";
 import { getConfig } from "../config/loader.js";
+import { resolvePlatformAssistantIdOrNull } from "../config/platform-identity.js";
 import type { CompactionLogsClickHouseConfig } from "../config/schemas/compaction-logs.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
@@ -136,7 +137,7 @@ export interface ClickHouseCompactionLogStoreDeps {
   resolveUrl?: () => Promise<string | null>;
   /** Override the credential read for `clickhouse:password`. */
   resolvePassword?: () => Promise<string | null>;
-  /** Override the credential read for `vellum:platform_assistant_id`. */
+  /** Override the in-memory platform assistant id. */
   resolveAssistantId?: () => Promise<string | null>;
   /** Override fetch for testing. */
   fetchImpl?: CompactionLogFetch;
@@ -163,8 +164,7 @@ export class ClickHouseCompactionLogStore {
       deps.resolvePassword ??
       (() => readCredentialOrNull("clickhouse", "password"));
     this.resolveAssistantId =
-      deps.resolveAssistantId ??
-      (() => readCredentialOrNull("vellum", "platform_assistant_id"));
+      deps.resolveAssistantId ?? resolvePlatformAssistantIdOrNull;
     this.fetchImpl = deps.fetchImpl ?? globalThis.fetch.bind(globalThis);
   }