@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/security/AGENTS.md

@@ -2,6 +2,6 @@
 
 ## Integration API Key Patterns
 
-When adding a new third-party integration, check whether the service uses a recognizable API key prefix (e.g., `lin_api_`, `sk-ant-`, `ghp_`). If it does, add a corresponding entry to `PREFIX_PATTERNS` in `secret-patterns.ts`. This is the single source of truth for prefix-based secret detection — ingress blocking, tool output scanning, and log redaction all consume this list.
+When adding a new third-party integration, check whether the service uses a recognizable API key prefix (e.g., `lin_api_`, `sk-ant-`, `ghp_`). If it does, add a corresponding entry to `PREFIX_PATTERNS` in `packages/service-contracts/src/secret-detection.ts` (`@vellumai/service-contracts/secret-detection`). This is the single source of truth for prefix-based secret detection — ingress blocking, tool output scanning, log redaction, and the web composer guard all consume this list. `secret-patterns.ts` in this directory is a re-export that preserves existing daemon import paths.
 
 OAuth-only services with opaque access tokens (no fixed prefix) do not need a pattern.

package/src/security/credential-key.ts

@@ -12,3 +12,20 @@
 export function credentialKey(service: string, field: string): string {
   return `credential/${service}/${field}`;
 }
+
+/**
+ * Normalize a credential reference to the vault-key form.
+ *
+ * The secrets API names credentials `{service}:{field}` on the wire (e.g.
+ * `openrouter:api_key`), while the vault stores them as
+ * `credential/{service}/{field}`. Callers routinely reuse the wire name where
+ * a vault key is expected, producing references that never resolve. Map the
+ * wire name to the vault key (same lastIndexOf split the secrets routes use);
+ * leave anything else untouched.
+ */
+export function normalizeCredentialRef(ref: string): string {
+  if (ref.startsWith("credential/")) return ref;
+  const colonIdx = ref.lastIndexOf(":");
+  if (colonIdx < 1 || colonIdx === ref.length - 1) return ref;
+  return credentialKey(ref.slice(0, colonIdx), ref.slice(colonIdx + 1));
+}

package/src/security/secret-ingress.ts

@@ -9,6 +9,15 @@
  * false positives on legitimate user input.
  */
 
+import {
+  isPlaceholderContext,
+  isPlaceholderValue,
+  TOKEN_SHAPE,
+  TOKEN_SHAPE_LABEL,
+  TOKEN_SHAPE_MAX_LENGTH,
+  TOKEN_SHAPE_MIN_LENGTH,
+} from "@vellumai/service-contracts/secret-detection";
+
 import { getConfig } from "../config/loader.js";
 import { memoizePluginPatternDerivation } from "./plugin-secret-patterns.js";
 import { isAllowlisted } from "./secret-allowlist.js";
@@ -52,112 +61,10 @@ const getGlobalPatterns = memoizePluginPatternDerivation(
   ],
 );
 
-// ---------------------------------------------------------------------------
-// Placeholder detection (inline — not imported from secret-scanner.ts)
-// ---------------------------------------------------------------------------
-
-const KNOWN_PLACEHOLDERS = new Set([
-  "your-api-key-here",
-  "your_api_key_here",
-  "insert-your-key-here",
-  "insert_your_key_here",
-  "replace-with-your-key",
-  "replace_with_your_key",
-  "xxx",
-  "xxxxxxxx",
-  "test",
-  "example",
-  "sample",
-  "demo",
-  "placeholder",
-  "changeme",
-  "CHANGEME",
-  "TODO",
-  "FIXME",
-  "your-token-here",
-  "your_token_here",
-  "my-api-key",
-  "my_api_key",
-]);
-
-const PLACEHOLDER_PREFIXES = [
-  "sk-test-",
-  "sk_test_",
-  "fake_",
-  "fake-",
-  "dummy_",
-  "dummy-",
-  "test_",
-  "test-",
-  "example_",
-  "example-",
-  "sample_",
-  "sample-",
-  "mock_",
-  "mock-",
-];
-
-/**
- * Check if the text immediately before a matched value indicates
- * a placeholder context (e.g. "fake_", "test_").
- */
-function isPlaceholderContext(preContext: string): boolean {
-  const lower = preContext.toLowerCase();
-  for (const prefix of PLACEHOLDER_PREFIXES) {
-    if (lower.endsWith(prefix)) return true;
-  }
-  return false;
-}
-
-/**
- * Check if a matched value is a placeholder/test value that should not
- * trigger blocking.
- */
-function isPlaceholder(value: string): boolean {
-  const lower = value.toLowerCase();
-
-  // Known placeholder values
-  if (KNOWN_PLACEHOLDERS.has(lower)) return true;
-
-  // Placeholder prefixes
-  for (const prefix of PLACEHOLDER_PREFIXES) {
-    if (lower.startsWith(prefix)) return true;
-  }
-
-  // Repeated characters in the variable portion (e.g. "AKIA" + "X" x 16)
-  // Strip known prefixes to isolate the variable part
-  const variablePart = value
-    .replace(
-      /^(?:AKIA|gh[pousr]_|github_pat_|glpat-|sk_live_|rk_live_|xoxb-|xoxp-|xapp-|sk-ant-|sk-proj-|sk-or-v1-|AIza|GOCSPX-|SK|SG\.|npm_|pypi-|key-|lin_api_|ntn_|fw_|pplx-|-----BEGIN [A-Z ]*PRIVATE KEY-----)/,
-      "",
-    )
-    .replace(/[^A-Za-z0-9]/g, "");
-  if (variablePart.length >= 8) {
-    const firstChar = variablePart[0];
-    if (variablePart.split("").every((c) => c === firstChar)) return true;
-  }
-
-  return false;
-}
-
 // ---------------------------------------------------------------------------
 // Token-shape heuristic (whole-message only)
 // ---------------------------------------------------------------------------
 
-/**
- * A single token-shaped value: an alphanumeric head, a separator-delimited
- * secret keyword infix, and a >=16-char tail (e.g. `virlo_tkn_JF…`). The
- * capture group isolates the tail for placeholder checks. Applied only when
- * the entire trimmed message is one such token — the whole-message and
- * keyword-infix requirements keep false positives near zero without any
- * entropy scoring.
- */
-const TOKEN_SHAPE =
-  /^[A-Za-z0-9][A-Za-z0-9_-]*[_-](?:tkn|token|key|secret|api|pat|sk|auth)[_-]([A-Za-z0-9_-]{16,})$/i;
-
-const TOKEN_SHAPE_MIN_LENGTH = 20;
-const TOKEN_SHAPE_MAX_LENGTH = 512;
-
 /**
  * Check whether the entire message content is a single token-shaped value
  * that should be blocked (no whitespace, plausible length, keyword infix,
@@ -181,7 +88,7 @@ function isBlockedTokenShapedMessage(content: string): boolean {
   // Check both the full value (test_/fake_ prefixes) and the tail after the
   // keyword infix (repeated-char fillers like "xxxxxxxxxxxxxxxx")
   const tail = match[1]!;
-  if (isPlaceholder(trimmed) || isPlaceholder(tail)) {
+  if (isPlaceholderValue(trimmed) || isPlaceholderValue(tail)) {
     return false;
   }
 
@@ -226,7 +133,9 @@ export function checkIngressForSecrets(content: string): IngressCheckResult {
       // a small window before it for placeholder prefixes like "fake_")
       const contextStart = Math.max(0, match.index - 10);
       const preContext = content.slice(contextStart, match.index);
-      if (isPlaceholder(value) || isPlaceholderContext(preContext)) continue;
+      if (isPlaceholderValue(value) || isPlaceholderContext(preContext)) {
+        continue;
+      }
 
       // Skip user-allowlisted values
       if (isAllowlisted(value)) continue;
@@ -242,7 +151,7 @@ export function checkIngressForSecrets(content: string): IngressCheckResult {
     secretDetection.blockTokenShapedMessages &&
     isBlockedTokenShapedMessage(content)
   ) {
-    detectedTypes.push("Token-shaped value");
+    detectedTypes.push(TOKEN_SHAPE_LABEL);
   }
 
   if (detectedTypes.length === 0) {

package/src/security/secret-patterns.ts

@@ -1,142 +1,11 @@
 /**
- * Shared prefix-based secret patterns — the single source of truth.
- *
- * Ingress blocking, tool output scanning, and log redaction all consume
- * this list.  When adding a new integration, add its API key pattern here.
- *
- * This module is intentionally data-only: no imports, no entropy logic,
- * no config — safe for hot-path consumers like log serializers.
+ * Prefix-based secret patterns — sourced from the shared
+ * `@vellumai/service-contracts/secret-detection` module, the single source
+ * of truth for prefix-based secret detection across the daemon and clients.
  */
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface SecretPrefixPattern {
-  /** Human-readable label shown in block notices and redaction tags. */
-  label: string;
-  /**
-   * Regex that matches the token value.  Must NOT include the `g` flag or
-   * capture groups — consumers add those as needed.
-   */
-  regex: RegExp;
-}
-
-// ---------------------------------------------------------------------------
-// Prefix patterns
-// ---------------------------------------------------------------------------
-
-/**
- * High-confidence, prefix-based secret patterns.
- *
- * Each entry matches a known API key / token format by its distinctive
- * prefix.  Patterns that require surrounding context (entropy analysis,
- * keyword proximity, URL structure) do NOT belong here — they stay in
- * `secret-scanner.ts` as scanner-only patterns.
- *
- * **When adding a new third-party integration, add its API key pattern
- * here.**  If the service uses only opaque OAuth access tokens (no fixed
- * prefix), no pattern is needed.
- */
-export const PREFIX_PATTERNS: SecretPrefixPattern[] = [
-  // -- AWS --
-  { label: "AWS Access Key", regex: /AKIA[0-9A-Z]{16}/ },
-
-  // -- GitHub --
-  { label: "GitHub Token", regex: /gh[pousr]_[A-Za-z0-9_]{36,}/ },
-  { label: "GitHub Fine-Grained PAT", regex: /github_pat_[A-Za-z0-9_]{22,}/ },
-
-  // -- GitLab --
-  { label: "GitLab Token", regex: /glpat-[A-Za-z0-9\-_]{20,}/ },
-
-  // -- Stripe --
-  { label: "Stripe Secret Key", regex: /sk_live_[A-Za-z0-9]{24,}/ },
-  { label: "Stripe Restricted Key", regex: /rk_live_[A-Za-z0-9]{24,}/ },
-
-  // -- Slack --
-  {
-    label: "Slack Bot Token",
-    regex: /xoxb-[0-9]{10,}-[0-9]{10,}-[A-Za-z0-9]{24,}/,
-  },
-  {
-    label: "Slack User Token",
-    regex: /xoxp-[0-9]{10,}-[0-9]{10,}-[0-9]{10,}-[a-f0-9]{32}/,
-  },
-  {
-    label: "Slack App Token",
-    regex: /xapp-[0-9]+-[A-Za-z0-9]+-[0-9]+-[A-Za-z0-9]+/,
-  },
-
-  // -- Telegram --
-  {
-    label: "Telegram Bot Token",
-    // Format: <bot_id>:<secret> where bot_id is 8–10 digits, secret is 35 chars
-    regex: /[0-9]{8,10}:[A-Za-z0-9_-]{35}/,
-  },
-
-  // -- Anthropic --
-  { label: "Anthropic API Key", regex: /sk-ant-[A-Za-z0-9\-_]{80,}/ },
-
-  // -- OpenAI --
-  {
-    label: "OpenAI API Key",
-    regex: /sk-[A-Za-z0-9]{20}T3BlbkFJ[A-Za-z0-9]{20}/,
-  },
-  { label: "OpenAI Project Key", regex: /sk-proj-[A-Za-z0-9\-_]{40,}/ },
-
-  // -- Google --
-  { label: "Google API Key", regex: /AIza[A-Za-z0-9\-_]{35}/ },
-  {
-    label: "Google OAuth Client Secret",
-    regex: /GOCSPX-[A-Za-z0-9\-_]{28}/,
-  },
-
-  // -- Twilio --
-  { label: "Twilio API Key", regex: /SK[0-9a-f]{32}/ },
-
-  // -- SendGrid --
-  {
-    label: "SendGrid API Key",
-    regex: /SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}/,
-  },
-
-  // -- Mailgun --
-  { label: "Mailgun API Key", regex: /key-[A-Za-z0-9]{32}/ },
-
-  // -- npm --
-  { label: "npm Token", regex: /npm_[A-Za-z0-9]{36}/ },
-
-  // -- PyPI --
-  { label: "PyPI API Token", regex: /pypi-[A-Za-z0-9\-_]{50,}/ },
-
-  // -- Private keys --
-  {
-    label: "Private Key",
-    regex:
-      /-----BEGIN (?:RSA |DSA |EC |OPENSSH |PGP )?PRIVATE KEY(?:\s+BLOCK)?-----/,
-  },
-
-  // -- Linear --
-  { label: "Linear API Key", regex: /lin_api_[A-Za-z0-9]{32,}/ },
-
-  // -- Notion --
-  { label: "Notion Integration Token", regex: /ntn_[A-Za-z0-9]{40,}/ },
-
-  // -- OpenRouter --
-  { label: "OpenRouter API Key", regex: /sk-or-v1-[A-Za-z0-9\-_]{40,}/ },
-
-  // -- Vercel AI Gateway --
-  { label: "Vercel AI Gateway API Key", regex: /vck_[A-Za-z0-9\-_]{24,}/ },
-
-  // -- Fireworks --
-  { label: "Fireworks API Key", regex: /fw_[A-Za-z0-9]{32,}/ },
-
-  // -- Perplexity --
-  { label: "Perplexity API Key", regex: /pplx-[A-Za-z0-9]{40,}/ },
-
-  // -- Tavily --
-  { label: "Tavily API Key", regex: /tvly-[A-Za-z0-9]{20,}/ },
-
-  // -- Firecrawl --
-  { label: "Firecrawl API Key", regex: /fc-[A-Za-z0-9]{20,}/ },
-];
+export {
+  PREFIX_PATTERNS,
+  REDACTION_PREFIX_PATTERNS,
+  type SecretPrefixPattern,
+} from "@vellumai/service-contracts/secret-detection";

package/src/security/secret-scanner.ts

@@ -12,7 +12,7 @@
 import { memoizePluginPatternDerivation } from "./plugin-secret-patterns.js";
 import { isAllowlisted } from "./secret-allowlist.js";
 import {
-  PREFIX_PATTERNS,
+  REDACTION_PREFIX_PATTERNS,
   type SecretPrefixPattern,
 } from "./secret-patterns.js";
 
@@ -71,9 +71,14 @@ function derivePluginScannerPattern(p: SecretPrefixPattern): SecretPattern {
   };
 }
 
-// Static patterns derived from the shared source of truth.
+// Static patterns derived from the shared source of truth. This scanner
+// redacts by replacing the matched span in place, so it uses the bounded
+// whole-block private-key matcher (via REDACTION_PREFIX_PATTERNS): the match
+// must cover header → body → footer or the key body would survive redaction.
+// The bound keeps it O(n) on large serialized strings; `detectSecretsInText`
+// (chat) keeps the unbounded whole-block matcher for full-key capture.
 const PREFIX_DERIVED: SecretPattern[] =
-  PREFIX_PATTERNS.map(deriveScannerPattern);
+  REDACTION_PREFIX_PATTERNS.map(deriveScannerPattern);
 
 // Scanner-only patterns that require surrounding context or are not
 // simple prefix matches — these stay defined here.

package/src/security/store-path-override.ts

@@ -11,10 +11,10 @@
  *
  * State is held on `globalThis.vellumAssistant.storePathOverride` so
  * test helpers in `__tests__/` can read/write it WITHOUT importing this
- * module — they declare the same slot shape locally and access the
- * globalThis namespace directly. See
- * `__tests__/encrypted-store-test-helpers.ts` for the test-side mirror;
- * the slot shape MUST stay in sync between the two.
+ * module. Both sides reference the shared ambient `VellumStorePathOverride`
+ * type (declared in `src/vellum-assistant-namespace.d.ts`), which types the
+ * slot without adding a runtime import between them. See
+ * `__tests__/encrypted-store-test-helpers.ts` for the test-side writer.
  *
  * Note: the new test preload places `VELLUM_WORKSPACE_DIR` at
  * `<tmpRoot>/workspace`, so `getProtectedDir()` resolves to
@@ -27,18 +27,8 @@
  *   - `__tests__/encrypted-store-test-helpers.ts` (writes for tests, via globalThis)
  */
 
-type PathSlot = {
-  storePath: string | null;
-  storeKeyPath: string | null;
-};
-
-type VellumAssistantNamespace = {
-  storePathOverride?: PathSlot;
-};
-
-function slot(): PathSlot {
-  const g = globalThis as { vellumAssistant?: VellumAssistantNamespace };
-  const ns = (g.vellumAssistant ??= {});
+function slot(): VellumStorePathOverride {
+  const ns = (globalThis.vellumAssistant ??= {});
   return (ns.storePathOverride ??= { storePath: null, storeKeyPath: null });
 }
 

package/src/sequence/store.ts

@@ -11,6 +11,7 @@ import { and, asc, eq, lte, sql } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getDb } from "../persistence/db-connection.js";
+import { isLifecycleQuiesced } from "../persistence/lifecycle-quiesce.js";
 import { rawChanges } from "../persistence/raw-query.js";
 import { sequenceEnrollments, sequences } from "../persistence/schema/index.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
@@ -224,6 +225,13 @@ export function claimDueEnrollments(
   now: number,
   limit = 10,
 ): SequenceEnrollment[] {
+  // Drain gate: while a quiesce lease is active, claim nothing — a sequence
+  // step's outreach starts before any row the drain snapshot can see.
+  // Fail-open via the lease read.
+  if (isLifecycleQuiesced()) {
+    return [];
+  }
+
   const db = getDb();
   const candidates = db
     .select()

package/src/signals/emit-event.ts

@@ -1,7 +1,7 @@
 /**
  * Handle generic event signals from the CLI.
  *
- * When the CLI writes a JSON-encoded {@link ServerMessage} to
+ * When the CLI writes a JSON-encoded {@link AssistantEvent} to
  * `signals/emit-event`, the daemon's ConfigWatcher detects the file
  * change and invokes {@link handleEmitEventSignal}, which reads the
  * payload and publishes it to connected clients via the in-process
@@ -15,9 +15,8 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import type { ServerMessage } from "../daemon/message-protocol.js";
-import { buildAssistantEvent } from "../runtime/assistant-event.js";
-import { assistantEventHub } from "../runtime/assistant-event-hub.js";
+import type { AssistantEvent } from "../api/index.js";
+import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { getLogger } from "../util/logger.js";
 import { getSignalsDir } from "../util/platform.js";
 
@@ -26,13 +25,9 @@ const log = getLogger("signal:emit-event");
 export function handleEmitEventSignal(): void {
   try {
     const content = readFileSync(join(getSignalsDir(), "emit-event"), "utf-8");
-    const message = JSON.parse(content) as ServerMessage;
+    const message = JSON.parse(content) as AssistantEvent;
 
-    assistantEventHub
-      .publish(buildAssistantEvent(message))
-      .catch((err: unknown) => {
-        log.error({ err }, "Failed to publish event from signal");
-      });
+    broadcastMessage(message);
 
     log.info({ type: message.type }, "Emit-event signal handled");
   } catch (err) {

package/src/signals/event-stream.ts

@@ -24,8 +24,8 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 
+import type { AssistantEventEnvelope } from "../api/index.js";
 import { getIsContainerized } from "../config/env-registry.js";
-import type { AssistantEvent } from "../runtime/assistant-event.js";
 import { getSignalsDir } from "../util/platform.js";
 
 // ── Write side (daemon) ──────────────────────────────────────────────
@@ -42,7 +42,9 @@ const CACHE_TTL_MS = 10_000;
 function getSubscriberDirs(conversationId: string): string[] {
   const now = Date.now();
   const cached = subscriberCache.get(conversationId);
-  if (cached && now < cached.expiry) return cached.dirs;
+  if (cached && now < cached.expiry) {
+    return cached.dirs;
+  }
 
   const dir = eventsDir();
   if (!existsSync(dir)) {
@@ -85,12 +87,16 @@ let sequence = 0;
  */
 export function appendEventToStream(
   conversationId: string,
-  event: AssistantEvent,
+  event: AssistantEventEnvelope,
 ): void {
-  if (getIsContainerized()) return;
+  if (getIsContainerized()) {
+    return;
+  }
 
   const dirs = getSubscriberDirs(conversationId);
-  if (dirs.length === 0) return;
+  if (dirs.length === 0) {
+    return;
+  }
 
   const timestamp = `${Date.now()}-${String(sequence++).padStart(6, "0")}`;
   const payload = JSON.stringify(event);
@@ -120,7 +126,7 @@ export interface EventStreamWatcher {
 
 /**
  * Register as a subscriber for a conversation's event stream and
- * invoke `callback` for each new {@link AssistantEvent} written.
+ * invoke `callback` for each new {@link AssistantEventEnvelope} written.
  *
  * Creates a subscriber directory at
  * `signals/events/<conversationId>.<pid>/`. The daemon writes each
@@ -131,7 +137,7 @@ export interface EventStreamWatcher {
  */
 export function watchEventStream(
   conversationId: string,
-  callback: (event: AssistantEvent) => void,
+  callback: (event: AssistantEventEnvelope) => void,
 ): EventStreamWatcher {
   if (getIsContainerized()) {
     return { dispose() {} };
@@ -148,7 +154,9 @@ export function watchEventStream(
   let disposed = false;
 
   const readNewEvents = (): void => {
-    if (disposed) return;
+    if (disposed) {
+      return;
+    }
     let files: string[];
     try {
       files = readdirSync(subDir).sort();
@@ -156,11 +164,13 @@ export function watchEventStream(
       return;
     }
     for (const file of files) {
-      if (processedFiles.has(file)) continue;
+      if (processedFiles.has(file)) {
+        continue;
+      }
       processedFiles.add(file);
       try {
         const data = readFileSync(join(subDir, file), "utf-8");
-        const event = JSON.parse(data) as AssistantEvent;
+        const event = JSON.parse(data) as AssistantEventEnvelope;
         callback(event);
       } catch {
         // Skip unreadable or malformed event files.