@vellumai/assistant 0.5.13 → 0.5.15

package/.env.example

@@ -21,12 +21,7 @@ VELLUM_PLATFORM_URL=https://dev-platform.vellum.ai
 
 # --- Sentry (crash reporting) ---
 # Omit to disable Sentry.
-SENTRY_DSN_ASSISTANT=https://db2d38a082e4ee35eeaea08c44b376ec@o4504590528675840.ingest.us.sentry.io/4510874712276992
-
-# --- Telemetry ---
-# Omit to disable telemetry reporting.
-TELEMETRY_PLATFORM_URL=https://platform.vellum.ai
-TELEMETRY_APP_TOKEN=e01cf85768cc3617e986f0a7f1966b72e25316526c5db54c8b94a9c3c5c9eaed
+SENTRY_DSN_ASSISTANT=
 
 # --- Network proxy ---
 # Comma-separated host patterns allowed through the proxy.

package/AGENTS.md

@@ -11,3 +11,7 @@ When you introduce a new env var that the assistant process needs to read at run
 `safe-env.ts` maintains the allowlist of env vars that are forwarded to agent-spawned child processes (bash tool, skill sandbox, etc.). Anything not on the list is stripped to prevent credential leakage. If your new var is needed by commands the agent runs, it must be added.
 
 **Default to including it.** If the var doesn't contain secrets (e.g. a URL, a feature flag, a path, a mode string), add it. Only omit it if it carries credential material (tokens, passwords, private keys) — those must stay isolated to CES.
+
+## Code comments
+
+When writing or updating comments, **do not reference code that has been removed.** Comments should describe the current state of the codebase, not narrate its history. Avoid phrases like "no longer does X", "previously used Y", or "was removed in PR Z" — future readers should not need to understand past implementations to understand the current code.

package/ARCHITECTURE.md

@@ -707,7 +707,6 @@ graph LR
 
     subgraph "~/.vellum/ (Root Files)"
         TRUST["protected/trust.json<br/>Tool permission rules"]
-        FF_TOKEN["feature-flag-token<br/>Client token for feature-flag API"]
     end
 
     subgraph "~/.vellum/workspace/ (Workspace Files)"

package/bunfig.toml

@@ -1,2 +1,3 @@
 [test]
 root = "./src"
+preload = ["./src/__tests__/test-preload.ts"]

package/docs/architecture/memory.md

@@ -260,10 +260,10 @@ The key distinction: normal compaction is a cost-optimized background process th
 | Config key                                            |                   Default | Purpose                                                              |
 | ----------------------------------------------------- | ------------------------: | -------------------------------------------------------------------- |
 | `memory.retrieval.dynamicBudget.enabled`              |                    `true` | Toggle per-turn recall budget calculation from live prompt headroom. |
-| `memory.retrieval.dynamicBudget.minInjectTokens`      |                    `1200` | Lower clamp for computed recall injection budget.                    |
-| `memory.retrieval.dynamicBudget.maxInjectTokens`      |                   `10000` | Upper clamp for computed recall injection budget.                    |
+| `memory.retrieval.dynamicBudget.minInjectTokens`      |                    `2400` | Lower clamp for computed recall injection budget.                    |
+| `memory.retrieval.dynamicBudget.maxInjectTokens`      |                   `16000` | Upper clamp for computed recall injection budget.                    |
 | `memory.retrieval.dynamicBudget.targetHeadroomTokens` |                   `10000` | Reserved headroom to keep free for response generation/tool traces.  |
-| `memory.retrieval.maxInjectTokens`                    |                   `10000` | Static fallback when dynamic budget is disabled.                     |
+| `memory.retrieval.maxInjectTokens`                    |                   `16000` | Static fallback when dynamic budget is disabled.                     |
 | `memory.retrieval.scopePolicy`                        | `'allow_global_fallback'` | Scope filtering strategy: `'strict'` or `'allow_global_fallback'`.   |
 
 ### Memory Recall Debugging Playbook

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.0.0
 info:
   title: Vellum Assistant API
-  version: 0.5.12
+  version: 0.5.13
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -3144,7 +3144,7 @@ paths:
     post:
       operationId: export_post
       summary: Export logs and audit data
-      description: Export audit records, daemon logs, workspace contents, and config as a tar.gz archive.
+      description: Export audit records, assistant logs, workspace contents, and config as a tar.gz archive.
       tags:
         - export
       responses:
@@ -3158,24 +3158,19 @@ paths:
               type: object
               properties:
                 auditLimit:
+                  description: Max audit records (default 1000)
                   type: integer
                   minimum: -9007199254740991
                   maximum: 9007199254740991
-                  description: Max audit records (default 1000)
                 conversationId:
-                  type: string
                   description: Scope to a single conversation
+                  type: string
                 startTime:
-                  type: number
                   description: Lower bound epoch ms
-                endTime:
                   type: number
+                endTime:
                   description: Upper bound epoch ms
-              required:
-                - auditLimit
-                - conversationId
-                - startTime
-                - endTime
+                  type: number
               additionalProperties: false
   /v1/guardian-actions/decision:
     post:
@@ -3316,6 +3311,52 @@ paths:
                   - cpu
                   - migrations
                 additionalProperties: false
+  /v1/healthz:
+    get:
+      operationId: healthz_get
+      summary: Detailed health check (alias)
+      description: Alias for /v1/health. Returns runtime health including version, disk, memory, CPU, and migration status.
+      tags:
+        - system
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                  timestamp:
+                    type: string
+                  version:
+                    type: string
+                  disk:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                  memory:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                  cpu:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                  migrations:
+                    type: object
+                    properties: {}
+                    additionalProperties: {}
+                required:
+                  - status
+                  - timestamp
+                  - version
+                  - disk
+                  - memory
+                  - cpu
+                  - migrations
+                additionalProperties: false
   /v1/heartbeat/checklist:
     get:
       operationId: heartbeat_checklist_get
@@ -3968,6 +4009,38 @@ paths:
       responses:
         "200":
           description: Successful response
+  /v1/logs/export:
+    post:
+      operationId: logs_export_post
+      summary: Export logs and audit data (alias)
+      description: Alias for /v1/export. Export audit records, assistant logs, workspace contents, and config as a tar.gz archive.
+      tags:
+        - export
+      responses:
+        "200":
+          description: Successful response
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auditLimit:
+                  description: Max audit records (default 1000)
+                  type: integer
+                  minimum: -9007199254740991
+                  maximum: 9007199254740991
+                conversationId:
+                  description: Scope to a single conversation
+                  type: string
+                startTime:
+                  description: Lower bound epoch ms
+                  type: number
+                endTime:
+                  description: Upper bound epoch ms
+                  type: number
+              additionalProperties: false
   /v1/memory-items:
     get:
       operationId: memoryitems_get
@@ -4644,6 +4717,28 @@ paths:
           required: true
           schema:
             type: string
+  /v1/oauth/providers:
+    get:
+      operationId: oauth_providers_get
+      tags:
+        - oauth-providers
+      responses:
+        "200":
+          description: Successful response
+  /v1/oauth/providers/{providerKey}:
+    get:
+      operationId: oauth_providers_by_providerKey_get
+      tags:
+        - oauth-providers
+      responses:
+        "200":
+          description: Successful response
+      parameters:
+        - name: providerKey
+          in: path
+          required: true
+          schema:
+            type: string
   /v1/oauth/start:
     post:
       operationId: oauth_start_post
@@ -6281,17 +6376,27 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  id:
-                    type: string
-                    description: Event ID
-                  event_name:
-                    type: string
-                required:
-                  - id
-                  - event_name
-                additionalProperties: false
+                anyOf:
+                  - type: object
+                    properties:
+                      id:
+                        type: string
+                        description: Event ID
+                      event_name:
+                        type: string
+                    required:
+                      - id
+                      - event_name
+                    additionalProperties: false
+                  - type: object
+                    properties:
+                      skipped:
+                        type: boolean
+                        const: true
+                        description: Event skipped due to usage data collection being disabled
+                    required:
+                      - skipped
+                    additionalProperties: false
       requestBody:
         required: true
         content:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/access-request-decision.test.ts

@@ -8,28 +8,7 @@
  * - Stale: handles already-resolved requests gracefully.
  * - Idempotent: approving same request twice does not create duplicate sessions.
  */
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
-
-// ---------------------------------------------------------------------------
-// Test isolation: in-memory SQLite via temp directory
-// ---------------------------------------------------------------------------
-
-const testDir = mkdtempSync(join(tmpdir(), "access-request-decision-test-"));
-
-mock.module("../util/platform.js", () => ({
-  getRootDir: () => testDir,
-  getDataDir: () => testDir,
-  isMacOS: () => process.platform === "darwin",
-  isLinux: () => process.platform === "linux",
-  isWindows: () => process.platform === "win32",
-  getPidPath: () => join(testDir, "test.pid"),
-  getDbPath: () => join(testDir, "test.db"),
-  getLogPath: () => join(testDir, "test.log"),
-  ensureDataDir: () => {},
-}));
+import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 mock.module("../util/logger.js", () => ({
   getLogger: () =>
@@ -56,7 +35,7 @@ mock.module("../runtime/gateway-client.js", () => ({
   },
 }));
 
-import { getDb, initializeDb, resetDb } from "../memory/db.js";
+import { getDb, initializeDb } from "../memory/db.js";
 import {
   createApprovalRequest,
   getApprovalRequestById,
@@ -72,15 +51,6 @@ import {
 
 initializeDb();
 
-afterAll(() => {
-  resetDb();
-  try {
-    rmSync(testDir, { recursive: true });
-  } catch {
-    /* best effort */
-  }
-});
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

package/src/__tests__/actor-token-service.test.ts

@@ -6,25 +6,7 @@
  * that middleware is replaced by the JWT auth middleware in
  * runtime/auth/middleware.ts (tested in auth/middleware.test.ts).
  */
-import { mkdtempSync, realpathSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
-
-const testDir = realpathSync(mkdtempSync(join(tmpdir(), "actor-token-test-")));
-
-mock.module("../util/platform.js", () => ({
-  getRootDir: () => testDir,
-  getDataDir: () => testDir,
-  getDbPath: () => join(testDir, "test.db"),
-  normalizeAssistantId: (id: string) => (id === "self" ? "self" : id),
-  isMacOS: () => process.platform === "darwin",
-  isLinux: () => process.platform === "linux",
-  isWindows: () => process.platform === "win32",
-  getPidPath: () => join(testDir, "test.pid"),
-  getLogPath: () => join(testDir, "test.log"),
-  ensureDataDir: () => {},
-}));
+import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 mock.module("../util/logger.js", () => ({
   getLogger: () =>
@@ -40,7 +22,6 @@ mock.module("../config/env.js", () => ({
   getRuntimeGatewayOriginSecret: () => undefined,
   isHttpAuthDisabledWithoutSafetyGate: () => false,
   checkUnrecognizedEnvVars: () => {},
-  getBaseDataDir: () => testDir,
 }));
 
 import { findGuardianForChannel } from "../contacts/contact-store.js";
@@ -110,12 +91,6 @@ beforeEach(() => {
   db.run("DELETE FROM contacts");
 });
 
-afterAll(() => {
-  try {
-    rmSync(testDir, { recursive: true, force: true });
-  } catch {}
-});
-
 // ---------------------------------------------------------------------------
 // Hash-only storage
 // ---------------------------------------------------------------------------
@@ -462,7 +437,6 @@ describe("pairing credential flow", () => {
     const ctx = {
       pairingStore: store,
       bearerToken,
-      featureFlagToken: undefined,
       pairingBroadcast: () => {},
     };
 
@@ -520,7 +494,6 @@ describe("pairing credential flow", () => {
     const ctx = {
       pairingStore: store,
       bearerToken,
-      featureFlagToken: undefined,
       pairingBroadcast: () => {},
     };
 
@@ -577,7 +550,6 @@ describe("pairing credential flow", () => {
     const ctx = {
       pairingStore: store,
       bearerToken,
-      featureFlagToken: undefined,
       pairingBroadcast: () => {},
     };
 
@@ -637,7 +609,6 @@ describe("pairing credential flow", () => {
     const ctx = {
       pairingStore: store,
       bearerToken,
-      featureFlagToken: undefined,
       pairingBroadcast: () => {},
     };
 
@@ -727,4 +698,3 @@ describe("bootstrap private-network guard", () => {
     expect(res.status).toBe(200);
   });
 });
-

package/src/__tests__/anthropic-provider.test.ts

@@ -37,25 +37,37 @@ mock.module("@anthropic-ai/sdk", () => ({
     constructor(args: Record<string, unknown>) {
       lastConstructorArgs = { ...args };
     }
+    #streamImpl = (
+      params: Record<string, unknown>,
+      options?: Record<string, unknown>,
+    ) => {
+      lastStreamParams = JSON.parse(JSON.stringify(params));
+      _lastStreamOptions = options ?? null;
+      const handlers: Record<string, ((...args: unknown[]) => void)[]> = {};
+      return {
+        on(event: string, cb: (...args: unknown[]) => void) {
+          (handlers[event] ??= []).push(cb);
+          return this;
+        },
+        async finalMessage() {
+          // Fire text events
+          for (const cb of handlers["text"] ?? []) cb("Hello");
+          return fakeResponse;
+        },
+      };
+    };
     messages = {
       stream: (
         params: Record<string, unknown>,
         options?: Record<string, unknown>,
-      ) => {
-        lastStreamParams = JSON.parse(JSON.stringify(params));
-        _lastStreamOptions = options ?? null;
-        const handlers: Record<string, ((...args: unknown[]) => void)[]> = {};
-        return {
-          on(event: string, cb: (...args: unknown[]) => void) {
-            (handlers[event] ??= []).push(cb);
-            return this;
-          },
-          async finalMessage() {
-            // Fire text events
-            for (const cb of handlers["text"] ?? []) cb("Hello");
-            return fakeResponse;
-          },
-        };
+      ) => this.#streamImpl(params, options),
+    };
+    beta = {
+      messages: {
+        stream: (
+          params: Record<string, unknown>,
+          options?: Record<string, unknown>,
+        ) => this.#streamImpl(params, options),
       },
     };
   },
@@ -138,16 +150,16 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
   // -----------------------------------------------------------------------
   // System prompt cache control
   // -----------------------------------------------------------------------
-  test("system prompt has cache_control ephemeral", async () => {
+  test("system prompt has cache_control ephemeral with 1h TTL", async () => {
     await provider.sendMessage([userMsg("Hi")], undefined, "You are helpful.");
 
     const system = lastStreamParams!.system as Array<{
       type: string;
       text: string;
-      cache_control?: { type: string };
+      cache_control?: { type: string; ttl?: string };
     }>;
     expect(system).toHaveLength(1);
-    expect(system[0].cache_control).toEqual({ type: "ephemeral" });
+    expect(system[0].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
   });
 
   test("no system param when system prompt is omitted", async () => {
@@ -166,13 +178,13 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
     const system = lastStreamParams!.system as Array<{
       type: string;
       text: string;
-      cache_control?: { type: string };
+      cache_control?: { type: string; ttl?: string };
     }>;
     expect(system).toHaveLength(2);
     expect(system[0].text).toBe(staticBlock);
-    expect(system[0].cache_control).toEqual({ type: "ephemeral" });
+    expect(system[0].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
     expect(system[1].text).toBe(dynamicBlock);
-    expect(system[1].cache_control).toEqual({ type: "ephemeral" });
+    expect(system[1].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
   });
 
   // -----------------------------------------------------------------------
@@ -183,7 +195,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
 
     const tools = lastStreamParams!.tools as Array<{
       name: string;
-      cache_control?: { type: string };
+      cache_control?: { type: string; ttl?: string };
     }>;
     expect(tools).toHaveLength(3);
 
@@ -192,7 +204,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
     expect(tools[1].cache_control).toBeUndefined();
 
     // Last tool: cache_control ephemeral
-    expect(tools[2].cache_control).toEqual({ type: "ephemeral" });
+    expect(tools[2].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
   });
 
   test("single tool gets cache_control", async () => {
@@ -200,10 +212,10 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
 
     const tools = lastStreamParams!.tools as Array<{
       name: string;
-      cache_control?: { type: string };
+      cache_control?: { type: string; ttl?: string };
     }>;
     expect(tools).toHaveLength(1);
-    expect(tools[0].cache_control).toEqual({ type: "ephemeral" });
+    expect(tools[0].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
   });
 
   test("no tools param when tools are omitted", async () => {
@@ -223,7 +235,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       content: Array<{
         type: string;
         text: string;
-        cache_control?: { type: string };
+        cache_control?: { type: string; ttl?: string };
       }>;
     }>;
     const lastUser = messages[messages.length - 1];
@@ -248,7 +260,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       content: Array<{
         type: string;
         text: string;
-        cache_control?: { type: string };
+        cache_control?: { type: string; ttl?: string };
       }>;
     }>;
 
@@ -264,7 +276,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
     // Second user turn (second-to-last): cache_control ephemeral
     const secondUserLastBlock =
       userMessages[1].content[userMessages[1].content.length - 1];
-    expect(secondUserLastBlock.cache_control).toEqual({ type: "ephemeral" });
+    expect(secondUserLastBlock.cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
 
     // Third user turn (last): no cache_control
     const thirdUserLastBlock =
@@ -280,7 +292,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       content: Array<{
         type: string;
         text: string;
-        cache_control?: { type: string };
+        cache_control?: { type: string; ttl?: string };
       }>;
     }>;
     const userMessages = sent.filter((m) => m.role === "user");
@@ -303,12 +315,12 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
 
     const sent = lastStreamParams!.messages as Array<{
       role: string;
-      content: Array<{ type: string; cache_control?: { type: string } }>;
+      content: Array<{ type: string; cache_control?: { type: string; ttl?: string } }>;
     }>;
     const userMsgs = sent.filter((m) => m.role === "user");
     // First user msg (second-to-last) should get cache
     const firstLast = userMsgs[0].content[userMsgs[0].content.length - 1];
-    expect(firstLast.cache_control).toEqual({ type: "ephemeral" });
+    expect(firstLast.cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
     // tool_result msg (last) should NOT get cache
     const secondLast = userMsgs[1].content[userMsgs[1].content.length - 1];
     expect(secondLast.cache_control).toBeUndefined();
@@ -330,7 +342,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       content: Array<{
         type: string;
         text: string;
-        cache_control?: { type: string };
+        cache_control?: { type: string; ttl?: string };
       }>;
     }>;
     const assistantMsgs = sent.filter((m) => m.role === "assistant");
@@ -361,7 +373,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       content: Array<{
         type: string;
         text: string;
-        cache_control?: { type: string };
+        cache_control?: { type: string; ttl?: string };
       }>;
     }>;
     const user = sent[0];
@@ -402,7 +414,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       content: Array<{
         type: string;
         text: string;
-        cache_control?: { type: string };
+        cache_control?: { type: string; ttl?: string };
       }>;
     }>;
     const user = sent[0];
@@ -436,7 +448,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       content: Array<{
         type: string;
         text: string;
-        cache_control?: { type: string };
+        cache_control?: { type: string; ttl?: string };
       }>;
     }>;
     const user = sent[0];
@@ -1309,7 +1321,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
       content: Array<{
         type: string;
         text: string;
-        cache_control?: { type: string };
+        cache_control?: { type: string; ttl?: string };
       }>;
     }>;
     const userMsgs = sent.filter((m) => m.role === "user");
@@ -1321,7 +1333,7 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
 
     // Turn 2 (second-to-last): cache on last block only
     expect(userMsgs[1].content[0].cache_control).toBeUndefined();
-    expect(userMsgs[1].content[1].cache_control).toEqual({ type: "ephemeral" });
+    expect(userMsgs[1].content[1].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
 
     // Turn 3 (last): no cache
     expect(userMsgs[2].content[0].cache_control).toBeUndefined();
@@ -1548,16 +1560,17 @@ describe("AnthropicProvider — Managed Proxy Fallback", () => {
 
     // System prompt cache control
     const system = lastStreamParams!.system as Array<{
-      cache_control?: { type: string };
+      cache_control?: { type: string; ttl?: string };
     }>;
-    expect(system[0].cache_control).toEqual({ type: "ephemeral" });
+    expect(system[0].cache_control).toEqual({ type: "ephemeral", ttl: "1h" });
 
     // Last tool cache control
     const tools = lastStreamParams!.tools as Array<{
-      cache_control?: { type: string };
+      cache_control?: { type: string; ttl?: string };
     }>;
     expect(tools[tools.length - 1].cache_control).toEqual({
       type: "ephemeral",
+      ttl: "1h",
     });
   });
 });