@vellumai/assistant 0.6.2 → 0.6.4

package/src/security/oauth2.ts

@@ -33,13 +33,13 @@ export type TokenEndpointAuthMethod =
   | "client_secret_post";
 
 export interface OAuth2Config {
-  authUrl: string;
-  tokenUrl: string;
+  authorizeUrl: string;
+  tokenExchangeUrl: string;
   scopes: string[];
   clientId: string;
   /** Client secret for providers that require it (e.g. Slack). PKCE is always used regardless. */
   clientSecret?: string;
-  extraParams?: Record<string, string>;
+  authorizeParams?: Record<string, string>;
   /** URL to fetch user identity info after OAuth. If omitted, account info is not fetched. */
   userinfoUrl?: string;
   /**
@@ -49,6 +49,20 @@ export interface OAuth2Config {
    * Defaults to `client_secret_post`.
    */
   tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
+  /**
+   * Separator used to join scopes in the authorize URL and split the
+   * granted-scope string returned by the token endpoint. Defaults to
+   * `" "` (space) per the OAuth 2.0 spec, but providers like Linear
+   * use `","` (comma).
+   */
+  scopeSeparator: string;
+  /**
+   * Body encoding format for the token exchange and refresh requests.
+   * - `"form"` (default): `application/x-www-form-urlencoded` with `URLSearchParams`.
+   * - `"json"`: `application/json` with `JSON.stringify`.
+   * Providers like Notion require JSON-encoded bodies at their token endpoint.
+   */
+  tokenExchangeBodyFormat?: "form" | "json";
 }
 
 export interface OAuth2TokenResult {
@@ -106,6 +120,7 @@ async function exchangeCodeForTokens(
   codeVerifier: string,
 ): Promise<OAuth2FlowResult> {
   const authMethod = config.tokenEndpointAuthMethod ?? "client_secret_post";
+  const bodyFormat = config.tokenExchangeBodyFormat ?? "form";
 
   const tokenBody: Record<string, string> = {
     grant_type: "authorization_code",
@@ -115,7 +130,11 @@ async function exchangeCodeForTokens(
   };
 
   const headers: Record<string, string> = {
-    "Content-Type": "application/x-www-form-urlencoded",
+    "Content-Type":
+      bodyFormat === "json"
+        ? "application/json"
+        : "application/x-www-form-urlencoded",
+    Accept: "application/json",
   };
 
   if (config.clientSecret && authMethod === "client_secret_basic") {
@@ -130,10 +149,13 @@ async function exchangeCodeForTokens(
     }
   }
 
-  const tokenResp = await fetch(config.tokenUrl, {
+  const tokenResp = await fetch(config.tokenExchangeUrl, {
     method: "POST",
     headers,
-    body: new URLSearchParams(tokenBody),
+    body:
+      bodyFormat === "json"
+        ? JSON.stringify(tokenBody)
+        : new URLSearchParams(tokenBody),
   });
 
   if (!tokenResp.ok) {
@@ -187,9 +209,19 @@ async function exchangeCodeForTokens(
       (tokenData.token_type as string | undefined),
   };
 
+  // Defensive split: providers (e.g. GitHub, Slack) may return comma-separated
+  // scopes in token responses regardless of the scope_separator used to join
+  // outbound authorize URLs, so we tolerate both spaces and commas here. When
+  // a provider explicitly configures a non-default separator (e.g. Linear uses
+  // ","), we honor that to keep symmetric round-tripping of configured scopes.
+  const splitPattern =
+    config.scopeSeparator === " " ? /[ ,]/ : config.scopeSeparator;
   const grantedScopes =
     typeof tokens.scope === "string"
-      ? tokens.scope.split(/[ ,]/).filter(Boolean)
+      ? tokens.scope
+          .split(splitPattern)
+          .map((s) => s.trim())
+          .filter(Boolean)
       : [...config.scopes];
 
   return { tokens, grantedScopes, rawTokenResponse: tokenData };
@@ -228,18 +260,18 @@ async function runGatewayFlow(
   });
 
   const authParams = new URLSearchParams({
-    ...config.extraParams,
+    ...config.authorizeParams,
     client_id: config.clientId,
     redirect_uri: redirectUri,
     response_type: "code",
-    scope: config.scopes.join(" "),
+    scope: config.scopes.join(config.scopeSeparator),
     state,
     code_challenge: codeChallenge,
     code_challenge_method: "S256",
   });
 
-  const authUrl = `${config.authUrl}?${authParams}`;
-  callbacks.openUrl(authUrl);
+  const authorizeUrl = `${config.authorizeUrl}?${authParams}`;
+  callbacks.openUrl(authorizeUrl);
 
   const code = await codePromise;
 
@@ -401,22 +433,22 @@ function startLoopbackServerAndWaitForCode(
       );
 
       const authParams = new URLSearchParams({
-        ...config.extraParams,
+        ...config.authorizeParams,
         client_id: config.clientId,
         redirect_uri: boundRedirectUri,
         response_type: "code",
-        scope: config.scopes.join(" "),
+        scope: config.scopes.join(config.scopeSeparator),
         state,
         code_challenge: codeChallenge,
         code_challenge_method: "S256",
       });
 
-      const authUrl = `${config.authUrl}?${authParams}`;
+      const authorizeUrl = `${config.authorizeUrl}?${authParams}`;
       log.info(
-        { authUrlLength: authUrl.length, state },
+        { authorizeUrlLength: authorizeUrl.length, state },
         "oauth2 loopback: built auth URL, calling openUrl callback",
       );
-      callbacks.openUrl(authUrl);
+      callbacks.openUrl(authorizeUrl);
       log.info("oauth2 loopback: openUrl callback returned");
     });
 
@@ -439,7 +471,7 @@ function startLoopbackServerAndWaitForCode(
 // ---------------------------------------------------------------------------
 
 export interface OAuth2PreparedFlow {
-  authUrl: string;
+  authorizeUrl: string;
   state: string;
   /** Resolves when the user completes authorization and tokens are exchanged. */
   completion: Promise<OAuth2FlowResult>;
@@ -493,17 +525,17 @@ export async function prepareOAuth2Flow(
   });
 
   const authParams = new URLSearchParams({
-    ...config.extraParams,
+    ...config.authorizeParams,
     client_id: config.clientId,
     redirect_uri: redirectUri,
     response_type: "code",
-    scope: config.scopes.join(" "),
+    scope: config.scopes.join(config.scopeSeparator),
     state,
     code_challenge: codeChallenge,
     code_challenge_method: "S256",
   });
 
-  const authUrl = `${config.authUrl}?${authParams}`;
+  const authorizeUrl = `${config.authorizeUrl}?${authParams}`;
 
   const completion = codePromise.then(async (code) => {
     return await exchangeCodeForTokens(config, code, redirectUri, codeVerifier);
@@ -511,7 +543,7 @@ export async function prepareOAuth2Flow(
 
   log.debug({ transport: "gateway", state }, "Prepared deferred OAuth2 flow");
 
-  return { authUrl, state, completion };
+  return { authorizeUrl, state, completion };
 }
 
 /**
@@ -533,17 +565,17 @@ async function prepareLoopbackFlow(
   );
 
   const authParams = new URLSearchParams({
-    ...config.extraParams,
+    ...config.authorizeParams,
     client_id: config.clientId,
     redirect_uri: redirectUri,
     response_type: "code",
-    scope: config.scopes.join(" "),
+    scope: config.scopes.join(config.scopeSeparator),
     state,
     code_challenge: codeChallenge,
     code_challenge_method: "S256",
   });
 
-  const authUrl = `${config.authUrl}?${authParams}`;
+  const authorizeUrl = `${config.authorizeUrl}?${authParams}`;
 
   const completion = codePromise.then(async (code) => {
     return await exchangeCodeForTokens(config, code, redirectUri, codeVerifier);
@@ -554,7 +586,7 @@ async function prepareLoopbackFlow(
     "Prepared deferred OAuth2 flow (loopback)",
   );
 
-  return { authUrl, state, completion };
+  return { authorizeUrl, state, completion };
 }
 
 /**
@@ -763,13 +795,15 @@ export async function startOAuth2Flow(
  * Supports both PKCE (no secret) and client_secret flows.
  */
 export async function refreshOAuth2Token(
-  tokenUrl: string,
+  tokenExchangeUrl: string,
   clientId: string,
   refreshToken: string,
   clientSecret?: string,
   tokenEndpointAuthMethod?: TokenEndpointAuthMethod,
+  tokenExchangeBodyFormat?: "form" | "json",
 ): Promise<OAuth2TokenResult> {
   const authMethod = tokenEndpointAuthMethod ?? "client_secret_post";
+  const bodyFormat = tokenExchangeBodyFormat ?? "form";
 
   const body: Record<string, string> = {
     grant_type: "refresh_token",
@@ -777,7 +811,11 @@ export async function refreshOAuth2Token(
   };
 
   const headers: Record<string, string> = {
-    "Content-Type": "application/x-www-form-urlencoded",
+    "Content-Type":
+      bodyFormat === "json"
+        ? "application/json"
+        : "application/x-www-form-urlencoded",
+    Accept: "application/json",
   };
 
   if (clientSecret && authMethod === "client_secret_basic") {
@@ -792,10 +830,11 @@ export async function refreshOAuth2Token(
     }
   }
 
-  const resp = await fetch(tokenUrl, {
+  const resp = await fetch(tokenExchangeUrl, {
     method: "POST",
     headers,
-    body: new URLSearchParams(body),
+    body:
+      bodyFormat === "json" ? JSON.stringify(body) : new URLSearchParams(body),
   });
 
   if (!resp.ok) {

package/src/security/secure-keys.ts

@@ -17,6 +17,8 @@
  * sidecar and credential data.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
+
 import type {
   SecureKeyBackend,
   SecureKeyDeleteResult,
@@ -75,6 +77,18 @@ let _lastReconnectAttempt = 0;
 /** In-flight reconnection promise — concurrent callers share the same attempt. */
 let _reconnectInFlight: Promise<boolean> | undefined;
 
+/**
+ * Per-async-context flag set while we are running the user-registered
+ * `_cesReconnect` callback. Reentrant credential reads from within the
+ * callback (on the same async call chain) must not `await`
+ * `_reconnectInFlight` — that would await the caller's own reconnect and
+ * deadlock until `CREDENTIAL_OP_TIMEOUT_MS` (45s) fires. Using
+ * AsyncLocalStorage (rather than a module-level boolean) scopes the guard
+ * to the actual reentrant stack, so unrelated concurrent callers keep
+ * sharing the in-flight reconnect promise normally.
+ */
+const _reconnectContext = new AsyncLocalStorage<true>();
+
 /**
  * Set to true when a ces-http operation returns an unreachable result.
  * Triggers CES RPC reconnection on the next resolveBackendAsync() call so
@@ -86,6 +100,15 @@ let _cesHttpUnreachable = false;
 /** Minimum interval between CES reconnection attempts. */
 const RECONNECT_COOLDOWN_MS = 3_000;
 
+/**
+ * Hard timeout for each public credential operation (resolve + backend call).
+ * Prevents indefinite blocking when CES reconnection or backend operations hang.
+ *
+ * Set to 45s to comfortably cover the CES HTTP set worst case (~34s:
+ * 3 fetch attempts × 10s REQUEST_TIMEOUT_MS + 2 × 2s SET_RETRY_DELAY_MS).
+ */
+const CREDENTIAL_OP_TIMEOUT_MS = 45_000;
+
 /** Inject a CES RPC client for credential routing. Resets the resolved backend. */
 export function setCesClient(client: CesClient | undefined): void {
   _cesClient = client;
@@ -231,6 +254,15 @@ function tryFailoverToCesHttpBackend(
 async function attemptCesReconnection(): Promise<boolean> {
   if (!_cesReconnect) return false;
 
+  // Reentrancy guard. A nested credential read from inside the reconnect
+  // callback must not `await` our own in-flight promise — that would
+  // deadlock on the 45-second credential-op timeout. Report the reconnect
+  // as failed so the caller sees "unreachable" and falls back (env vars,
+  // dead-backend response) without blocking. Concurrent callers on other
+  // async chains don't see the ALS store, so they still share the
+  // in-flight promise normally.
+  if (_reconnectContext.getStore()) return false;
+
   // If a reconnection is already in flight, share it.
   if (_reconnectInFlight) return _reconnectInFlight;
 
@@ -240,7 +272,7 @@ async function attemptCesReconnection(): Promise<boolean> {
   _lastReconnectAttempt = Date.now();
   log.warn("Credential backend unavailable — attempting CES reconnection");
 
-  _reconnectInFlight = (async () => {
+  _reconnectInFlight = _reconnectContext.run(true, async () => {
     try {
       const newClient = await _cesReconnect!();
       if (newClient) {
@@ -253,7 +285,7 @@ async function attemptCesReconnection(): Promise<boolean> {
       log.warn({ err }, "CES reconnection failed");
     }
     return false;
-  })();
+  });
 
   try {
     return await _reconnectInFlight;
@@ -308,16 +340,58 @@ function updateCesHttpReachability(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Timeout helper
+// ---------------------------------------------------------------------------
+
+const CREDENTIAL_TIMEOUT_MSG = "Credential operation timed out";
+
+/**
+ * Race a credential operation against a hard deadline. If the operation
+ * does not settle within `CREDENTIAL_OP_TIMEOUT_MS`, return the supplied
+ * fallback value so callers degrade gracefully instead of hanging.
+ *
+ * Non-timeout errors from `op()` are propagated to callers rather than
+ * silently swallowed — only genuine timeouts return the fallback.
+ */
+async function withCredentialTimeout<T>(
+  op: () => Promise<T>,
+  fallback: T,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      log.warn(CREDENTIAL_TIMEOUT_MSG + " — returning fallback");
+      resolve(fallback);
+    }, CREDENTIAL_OP_TIMEOUT_MS);
+
+    op().then(
+      (val) => {
+        clearTimeout(timer);
+        resolve(val);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}
+
 /**
  * List all account names from the resolved backend (async).
  *
  * Queries exactly one backend — no cross-store merge.
  */
 export async function listSecureKeysAsync(): Promise<CredentialListResult> {
-  const backend = await resolveBackendAsync();
-  const result = await backend.list();
-  updateCesHttpReachability(backend, result.unreachable);
-  return result;
+  return withCredentialTimeout(
+    async () => {
+      const backend = await resolveBackendAsync();
+      const result = await backend.list();
+      updateCesHttpReachability(backend, result.unreachable);
+      return result;
+    },
+    { accounts: [], unreachable: true },
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -336,13 +410,18 @@ export async function listSecureKeysAsync(): Promise<CredentialListResult> {
 export async function getSecureKeyResultAsync(
   account: string,
 ): Promise<SecureKeyResult> {
-  const backend = await resolveBackendAsync();
-  const result = await backend.get(account);
-  updateCesHttpReachability(backend, result.unreachable);
-  if (result.value != null) {
-    return { value: result.value, unreachable: false };
-  }
-  return { value: undefined, unreachable: result.unreachable };
+  return withCredentialTimeout(
+    async () => {
+      const backend = await resolveBackendAsync();
+      const result = await backend.get(account);
+      updateCesHttpReachability(backend, result.unreachable);
+      if (result.value != null) {
+        return { value: result.value, unreachable: false };
+      }
+      return { value: undefined, unreachable: result.unreachable };
+    },
+    { value: undefined, unreachable: true },
+  );
 }
 
 /**
@@ -364,16 +443,18 @@ export async function setSecureKeyAsync(
   account: string,
   value: string,
 ): Promise<boolean> {
-  const backend = await resolveBackendAsync();
-  const ok = await backend.set(account, value);
-  if (!ok) {
-    log.warn(
-      { account, backend: backend.name },
-      "Credential backend set failed",
-    );
-  }
-  updateCesHttpReachability(backend, !ok);
-  return ok;
+  return withCredentialTimeout(async () => {
+    const backend = await resolveBackendAsync();
+    const ok = await backend.set(account, value);
+    if (!ok) {
+      log.warn(
+        { account, backend: backend.name },
+        "Credential backend set failed",
+      );
+    }
+    updateCesHttpReachability(backend, !ok);
+    return ok;
+  }, false);
 }
 
 /**
@@ -384,10 +465,45 @@ export async function setSecureKeyAsync(
 export async function deleteSecureKeyAsync(
   account: string,
 ): Promise<DeleteResult> {
-  const backend = await resolveBackendAsync();
-  const result = await backend.delete(account);
-  updateCesHttpReachability(backend, result === "error");
-  return result;
+  return withCredentialTimeout(async () => {
+    const backend = await resolveBackendAsync();
+    const result = await backend.delete(account);
+    updateCesHttpReachability(backend, result === "error");
+    return result;
+  }, "error");
+}
+
+/**
+ * Bulk-set multiple credentials in a single operation.
+ *
+ * Uses the backend's native `bulkSet` when available (CES RPC / HTTP),
+ * otherwise falls back to individual `set` calls.
+ */
+export async function bulkSetSecureKeysAsync(
+  credentials: Array<{ account: string; value: string }>,
+): Promise<Array<{ account: string; ok: boolean }>> {
+  return withCredentialTimeout(
+    async () => {
+      const backend = await resolveBackendAsync();
+      if (backend.bulkSet) {
+        const results = await backend.bulkSet(credentials);
+        const anyFailed = results.some((r) => !r.ok);
+        updateCesHttpReachability(backend, anyFailed);
+        return results;
+      }
+      // Fallback: loop individual sets
+      const results = [];
+      let anyFailed = false;
+      for (const { account, value } of credentials) {
+        const ok = await backend.set(account, value);
+        if (!ok) anyFailed = true;
+        results.push({ account, ok });
+      }
+      updateCesHttpReachability(backend, anyFailed);
+      return results;
+    },
+    credentials.map((c) => ({ account: c.account, ok: false })),
+  );
 }
 
 // ---------------------------------------------------------------------------

package/src/security/token-manager.ts

@@ -1,7 +1,7 @@
 /**
  * Token manager for OAuth2 credentials.
  *
- * Reads refresh configuration (tokenUrl, clientId, authMethod) exclusively
+ * Reads refresh configuration (refreshUrl with fallback to tokenExchangeUrl, clientId, authMethod) exclusively
  * from the SQLite oauth-store (provider + app + connection rows). After a
  * successful refresh, writes tokens to new-format secure key paths and
  * updates the oauth_connection row.
@@ -90,20 +90,27 @@ const secureKeyBackend: SecureKeyBackend = {
 
 /** Shared shape for resolved refresh configuration. */
 interface RefreshConfig {
-  tokenUrl: string;
+  /**
+   * Token endpoint used for the refresh grant. Resolved from
+   * `provider.refreshUrl` when set to a non-empty string, otherwise
+   * `provider.tokenExchangeUrl` (matching platform's Python `or` semantics).
+   */
+  tokenExchangeUrl: string;
   clientId: string;
   /** OAuth client secret (optional — PKCE flows may omit it). */
   secret?: string;
   refreshToken?: string;
   authMethod?: TokenEndpointAuthMethod;
+  tokenExchangeBodyFormat?: "form" | "json";
   connId: string;
 }
 
 /**
  * Resolve refresh configuration from the SQLite oauth-store.
  *
- * Looks up connection -> app -> provider to read tokenUrl, clientId, and
- * authMethod. Throws `TokenExpiredError` if the connection is not found
+ * Looks up connection -> app -> provider to read the refresh endpoint (preferring
+ * `provider.refreshUrl`, falling back to `provider.tokenExchangeUrl`), clientId,
+ * and authMethod. Throws `TokenExpiredError` if the connection is not found
  * or incomplete.
  */
 async function resolveRefreshConfig(
@@ -126,7 +133,7 @@ async function resolveRefreshConfig(
     );
   }
 
-  const provider = getProvider(conn.providerKey);
+  const provider = getProvider(conn.provider);
   if (!provider) {
     throw new TokenExpiredError(
       service,
@@ -134,9 +141,16 @@ async function resolveRefreshConfig(
     );
   }
 
-  const tokenUrl = provider.tokenUrl;
+  // Prefer provider.refreshUrl when set; fall back to tokenExchangeUrl.
+  // This mirrors platform's `oauth_app.refresh_url or oauth_app.token_exchange_url`
+  // in `token_service.py:112`, so both repos resolve the refresh endpoint
+  // identically for managed and BYO flows. We use `||` (not `??`) so empty
+  // strings fall back to tokenExchangeUrl — matching Python's `or` semantics
+  // and preventing a malformed provider row with `refreshUrl: ""` from
+  // resolving to an empty endpoint.
+  const tokenExchangeUrl = provider.refreshUrl || provider.tokenExchangeUrl;
   const resolvedClientId = app.clientId;
-  if (!tokenUrl || !resolvedClientId) {
+  if (!tokenExchangeUrl || !resolvedClientId) {
     throw new TokenExpiredError(
       service,
       `Missing OAuth2 refresh config for "${service}".${recoveryHint(service)}`,
@@ -153,13 +167,18 @@ async function resolveRefreshConfig(
     | TokenEndpointAuthMethod
     | undefined;
 
+  const tokenExchangeBodyFormat =
+    (provider.tokenExchangeBodyFormat as "form" | "json" | undefined) ??
+    undefined;
+
   return {
     connId: conn.id,
-    tokenUrl,
+    tokenExchangeUrl,
     clientId: resolvedClientId,
     secret,
     refreshToken,
     authMethod,
+    tokenExchangeBodyFormat,
   };
 }
 
@@ -175,10 +194,11 @@ async function resolveRefreshConfig(
 async function doRefresh(service: string, connId: string): Promise<string> {
   const refreshConfig = await resolveRefreshConfig(service, connId);
   const {
-    tokenUrl,
+    tokenExchangeUrl,
     clientId: resolvedClientId,
     secret,
     authMethod,
+    tokenExchangeBodyFormat,
     refreshToken,
   } = refreshConfig;
 
@@ -204,11 +224,12 @@ async function doRefresh(service: string, connId: string): Promise<string> {
   let result;
   try {
     result = await refreshOAuth2Token(
-      tokenUrl,
+      tokenExchangeUrl,
       resolvedClientId,
       refreshToken,
       secret,
       authMethod,
+      tokenExchangeBodyFormat,
     );
   } catch (err) {
     circuitBreaker.recordFailure(connId);

package/src/sequence/engine.ts

@@ -6,6 +6,7 @@
  * sends through the messaging layer.
  */
 
+import { emitFeedEvent } from "../home/emit-feed-event.js";
 import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
 import { getMessages } from "../memory/conversation-crud.js";
 import type { ScheduleMessageProcessor } from "../schedule/scheduler.js";
@@ -200,6 +201,28 @@ async function processEnrollment(
   recordSend(sequence.id);
   recordEvent(sequence.id, enrollment.id, "send", step.index);
 
+  // Fire-and-forget home-feed activity log entry. Each (enrollment,
+  // step) pair is a distinct real signal (an email actually went
+  // out), so the dedupKey embeds both — repeat emits for the same
+  // step are impossible because the enrollment advances after this
+  // line, but if they did occur they'd land on the same entry.
+  void emitFeedEvent({
+    source: "assistant",
+    title: sequence.name,
+    summary: `Sent step ${step.index + 1} of ${sequence.steps.length} to ${enrollment.contactEmail}.`,
+    dedupKey: `sequence-step:${enrollment.id}:${step.index}`,
+  }).catch((err) => {
+    log.warn(
+      {
+        err,
+        sequenceId: sequence.id,
+        enrollmentId: enrollment.id,
+        step: step.index,
+      },
+      "Failed to emit sequence step feed event",
+    );
+  });
+
   // Advance to the next step
   const nextStepIndex = enrollment.currentStep + 1;
   if (nextStepIndex >= sequence.steps.length) {

package/src/sequence/types.ts

@@ -26,7 +26,7 @@ export interface Sequence {
   id: string;
   name: string;
   description: string | null;
-  channel: string; // messaging channel (gmail, agentmail, slack)
+  channel: string; // messaging channel (gmail, email, slack)
   steps: SequenceStep[];
   exitOnReply: boolean;
   status: SequenceStatus;