@vellumai/assistant 0.4.50 → 0.4.51

package/docs/architecture/integrations.md

@@ -151,7 +151,7 @@ sequenceDiagram
 
     Note over UI,API: Tool Execution Flow
     Tool->>TokenMgr: withValidToken("gmail", callback)
-    TokenMgr->>Store: getConnectionByProvider("integration:gmail")
+    TokenMgr->>Store: getConnectionByProvider("integration:google")
     TokenMgr->>Vault: getSecureKey("oauth_connection/{conn.id}/access_token")
     TokenMgr->>Store: check oauth_connections.expires_at
     alt Token expired
@@ -228,7 +228,7 @@ The OAuth extensibility layer makes adding a new OAuth provider a declarative op
 
 Protocol fields (`authUrl`, `tokenUrl`, `defaultScopes`, `scopePolicy`, `callbackTransport`) are stored in the `oauth_providers` database table rather than in code.
 
-Registered providers: `integration:gmail`, `integration:slack`, `integration:notion`. Short aliases (e.g. `gmail`, `slack`) are resolved via `resolveService()`.
+Registered providers: `integration:google`, `integration:slack`, `integration:notion`. Short aliases (e.g. `gmail`, `slack`) are resolved via `resolveService()`.
 
 ### Scope Policy Engine
 

package/docs/architecture/keychain-broker.md

@@ -55,11 +55,11 @@ graph LR
 
 ### TypeScript side (runtime + gateway)
 
-| File                                               | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `assistant/src/security/keychain-broker-client.ts` | Async UDS client for the runtime. Persistent socket connection, request/response correlation, auth token caching with auto-refresh on `UNAUTHORIZED`. Falls back gracefully (returns safe defaults, never throws).                                                                                                                                                                                                                                                      |
-| `assistant/src/security/secure-keys.ts`            | Unified API surface. Sync variants use encrypted store only. Async variants (`getSecureKeyAsync`, `setSecureKeyAsync`, `deleteSecureKeyAsync`) try broker first. **Reads** fall back to the encrypted store when the broker is unavailable or key is not found. **Writes** return `false` on broker failure (no encrypted-store fallback). **Deletes** return `"deleted"`, `"not-found"`, or `"error"` to let callers distinguish idempotent no-ops from real failures. |
-| `gateway/src/credential-reader.ts`                 | Read-only credential reader. Tries broker via native async UDS connection (`node:net`), falls back to encrypted store. All public credential read functions are async.                                                                                                                                                                                                                                                                                                  |
+| File                                               | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `assistant/src/security/keychain-broker-client.ts` | Async UDS client for the runtime. Persistent socket connection, request/response correlation, auth token caching with auto-refresh on `UNAUTHORIZED`. Falls back gracefully (returns safe defaults, never throws).                                                                                                                                                                                                                                                                                            |
+| `assistant/src/security/secure-keys.ts`            | Unified API surface. Sync variants use encrypted store only. Async variants (`getSecureKeyAsync`, `setSecureKeyAsync`, `deleteSecureKeyAsync`) check the encrypted store first for reads (instant), falling back to the broker for keys that may exist only in the macOS Keychain. **Writes** go to both stores; return `false` on broker failure (no encrypted-store fallback). **Deletes** return `"deleted"`, `"not-found"`, or `"error"` to let callers distinguish idempotent no-ops from real failures. |
+| `gateway/src/credential-reader.ts`                 | Read-only credential reader. Tries broker via native async UDS connection (`node:net`), falls back to encrypted store. All public credential read functions are async.                                                                                                                                                                                                                                                                                                                                        |
 
 ## Message Contract
 
@@ -181,6 +181,6 @@ Sync APIs are acceptable for startup paths (e.g. provider initialization, config
 
 ## Migration
 
-Existing encrypted store keys remain accessible — the encrypted store is always consulted as a **read** fallback when the broker does not have a key. Successful writes from async code paths go to both the broker (keychain) and the encrypted store, keeping both in sync. If a broker write or delete fails, the operation returns `false` without falling back to the encrypted store alone, preventing stale divergence. Callers must inspect the boolean return value and handle failures (typically by logging a warning). There is no one-time migration step required.
+Existing encrypted store keys remain accessible — async reads check the encrypted store **first** (instant), falling back to the broker for keys that may exist only in the macOS Keychain. Successful writes from async code paths go to both the broker (keychain) and the encrypted store, keeping both in sync. If a broker write or delete fails, the operation returns `false` without falling back to the encrypted store alone, preventing stale divergence. Callers must inspect the boolean return value and handle failures (typically by logging a warning). There is no one-time migration step required.
 
 The old `keychain.ts` module (which called `/usr/bin/security` CLI directly) has been deleted. The old keychain-to-encrypted migration code has been removed. All keychain access now flows exclusively through the broker.

package/knip.json

@@ -0,0 +1,32 @@
+{
+  "entry": ["src/**/*.test.ts", "src/**/__tests__/**/*.ts", "scripts/**/*.ts"],
+  "project": ["src/**/*.ts", "src/**/*.tsx", "scripts/**/*.ts"],
+  "ignore": [
+    "src/browser-extension-relay/client.ts",
+    "src/contacts/index.ts",
+    "src/daemon/main.ts",
+    "src/daemon/tls-certs.ts",
+    "src/errors.ts",
+    "src/events/index.ts",
+    "src/followups/index.ts",
+    "src/playbooks/index.ts",
+    "src/runtime/auth/index.ts",
+    "src/tasks/candidate-store.ts",
+    "src/tools/browser/api-map.ts",
+    "src/tools/browser/auto-navigate.ts",
+    "src/tools/browser/headless-browser.ts",
+    "src/tools/browser/recording-store.ts",
+    "src/tools/tasks/index.ts"
+  ],
+  "ignoreDependencies": [
+    "@hono/node-server",
+    "@vellumai/cli",
+    "esbuild",
+    "hono",
+    "ink",
+    "preact",
+    "quicktype-core",
+    "tree-sitter-bash",
+    "typescript-json-schema"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.4.50",
+  "version": "0.4.51",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
@@ -16,13 +16,14 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint",
+    "lint:unused": "knip --include files,dependencies,unlisted",
     "typecheck": "bunx tsc --noEmit",
     "test": "bash scripts/test.sh",
     "test:coverage": "COVERAGE=true bash scripts/test.sh",
     "test:stable": "EXCLUDE_EXPERIMENTAL=true bash scripts/test.sh",
     "test:bench": "find src/__tests__ -maxdepth 1 -type f -name '*.benchmark.test.ts' -print0 | xargs -0 -P 1 -I {} bun test {}",
     "test:filesystem-tools": "bash scripts/test-filesystem-tools.sh",
-    "postinstall": "cd .. && (git config core.hooksPath || git config core.hooksPath .githooks 2>/dev/null || true) && (bun run meta/feature-flags/sync-bundled-copies.ts 2>/dev/null || true)"
+    "postinstall": "cd .. && (git config core.hooksPath || git config core.hooksPath .githooks 2>/dev/null || true) && ([ -f meta/feature-flags/sync-bundled-copies.ts ] && bun run meta/feature-flags/sync-bundled-copies.ts 2>/dev/null || true)"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.42",

package/src/__tests__/btw-routes.test.ts

@@ -19,13 +19,21 @@ mock.module("../util/logger.js", () => ({
     }),
 }));
 
-const mockGetOrCreateConversation = mock((_key: string) => ({
-  conversationId: "conv-test-123",
-  created: false,
-}));
+const mockGetConversationByKey = mock(
+  (_key: string): { conversationId: string } | null => ({
+    conversationId: "conv-test-123",
+  }),
+);
 
 mock.module("../memory/conversation-key-store.js", () => ({
-  getOrCreateConversation: mockGetOrCreateConversation,
+  getConversationByKey: mockGetConversationByKey,
+  // Ensure getOrCreateConversation is never called — BTW must not create
+  // persistent conversations.
+  getOrCreateConversation: () => {
+    throw new Error(
+      "getOrCreateConversation must not be called from btw-routes",
+    );
+  },
 }));
 
 const mockAddMessage = mock(() => {});
@@ -323,4 +331,52 @@ describe("POST /v1/btw", () => {
     // processing should still be false — the handler never sets it
     expect(session.processing).toBe(false);
   });
+
+  // -- No conversation creation (regression) --
+
+  test("unknown conversationKey does not create a DB conversation", async () => {
+    // Simulate a greeting request for a draft thread — no conversation exists.
+    mockGetConversationByKey.mockReturnValueOnce(null);
+
+    const session = makeMockSession();
+    const deps = makeSendMessageDeps(session);
+    const getOrCreateSessionSpy = deps.getOrCreateSession as ReturnType<
+      typeof mock
+    >;
+
+    const res = await callHandler(
+      { conversationKey: "greeting-abc123", content: "Generate a greeting" },
+      { sendMessageDeps: deps },
+    );
+    await readStream(res);
+
+    expect(res.status).toBe(200);
+
+    // Read-only lookup should be called
+    expect(mockGetConversationByKey).toHaveBeenCalledWith("greeting-abc123");
+
+    // Session should be created with the raw key (no DB conversation created)
+    expect(getOrCreateSessionSpy).toHaveBeenCalledWith("greeting-abc123");
+  });
+
+  test("known conversationKey resolves to existing conversation ID", async () => {
+    mockGetConversationByKey.mockReturnValueOnce({
+      conversationId: "existing-conv-id",
+    });
+
+    const session = makeMockSession();
+    const deps = makeSendMessageDeps(session);
+    const getOrCreateSessionSpy = deps.getOrCreateSession as ReturnType<
+      typeof mock
+    >;
+
+    const res = await callHandler(
+      { conversationKey: "my-thread-key", content: "What is 2+2?" },
+      { sendMessageDeps: deps },
+    );
+    await readStream(res);
+
+    expect(res.status).toBe(200);
+    expect(getOrCreateSessionSpy).toHaveBeenCalledWith("existing-conv-id");
+  });
 });

package/src/__tests__/config-watcher.test.ts

@@ -120,6 +120,14 @@ mock.module("../providers/registry.js", () => ({
   initializeProviders: () => {},
 }));
 
+mock.module("../signals/mcp-reload.js", () => ({
+  handleMcpReloadSignal: () => {},
+}));
+
+mock.module("../signals/confirm.js", () => ({
+  handleConfirmationSignal: () => {},
+}));
+
 let resetAllowlistCallCount = 0;
 mock.module("../security/secret-allowlist.js", () => ({
   resetAllowlist: () => {

package/src/__tests__/credential-security-invariants.test.ts

@@ -236,6 +236,7 @@ describe("Invariant 2: no generic plaintext secret read API", () => {
       "oauth/oauth-store.ts", // OAuth provider disconnect (delete stored tokens)
       "cli/commands/oauth/connections.ts", // CLI OAuth connection delete (legacy credential cleanup)
       "oauth/manual-token-connection.ts", // manual-token provider backfill (keychain credential existence check)
+      "cli/commands/doctor.ts", // CLI diagnostic API key verification via secure storage
     ]);
 
     const thisDir = dirname(fileURLToPath(import.meta.url));
@@ -504,7 +505,7 @@ describe("Invariant 6: oauth2ClientSecret not in metadata, only in secure store"
 
   test("upsertCredentialMetadata does not accept oauth2ClientSecret or other OAuth fields", () => {
     const record = upsertCredentialMetadata(
-      "integration:gmail",
+      "integration:google",
       "access_token",
       {
         allowedTools: ["api_request"],
@@ -517,14 +518,14 @@ describe("Invariant 6: oauth2ClientSecret not in metadata, only in secure store"
 
   test("client secret is read from secure store, not metadata", () => {
     setSecureKey(
-      credentialKey("integration:gmail", "client_secret"),
+      credentialKey("integration:google", "client_secret"),
       "my-secret",
     );
-    upsertCredentialMetadata("integration:gmail", "access_token", {
+    upsertCredentialMetadata("integration:google", "access_token", {
       allowedTools: ["api_request"],
     });
 
-    const meta = getCredentialMetadata("integration:gmail", "access_token");
+    const meta = getCredentialMetadata("integration:google", "access_token");
     expect(meta).toBeDefined();
     expect("oauth2ClientSecret" in meta!).toBe(false);
     // OAuth-specific fields are no longer in metadata (v5)
@@ -533,7 +534,7 @@ describe("Invariant 6: oauth2ClientSecret not in metadata, only in secure store"
 
     // Secret is in secure store
     expect(
-      getSecureKey(credentialKey("integration:gmail", "client_secret")),
+      getSecureKey(credentialKey("integration:google", "client_secret")),
     ).toBe("my-secret");
   });
 
@@ -543,7 +544,7 @@ describe("Invariant 6: oauth2ClientSecret not in metadata, only in secure store"
       credentials: [
         {
           credentialId: "cred-v2-secret",
-          service: "integration:gmail",
+          service: "integration:google",
           field: "access_token",
           allowedTools: [],
           allowedDomains: [],
@@ -561,7 +562,7 @@ describe("Invariant 6: oauth2ClientSecret not in metadata, only in secure store"
       "utf-8",
     );
 
-    const meta = getCredentialMetadata("integration:gmail", "access_token");
+    const meta = getCredentialMetadata("integration:google", "access_token");
     expect(meta).toBeDefined();
     expect("oauth2ClientSecret" in meta!).toBe(false);
 

package/src/__tests__/credential-vault-unit.test.ts

@@ -531,8 +531,8 @@ describe("credential_store tool — prompt action", () => {
 describe("credential_store tool — oauth2_connect error paths", () => {
   /** Well-known provider rows returned by the mocked getProvider */
   const wellKnownProviders: Record<string, object> = {
-    "integration:gmail": {
-      key: "integration:gmail",
+    "integration:google": {
+      key: "integration:google",
       authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
       tokenUrl: "https://oauth2.googleapis.com/token",
       defaultScopes: JSON.stringify(["https://mail.google.com/"]),
@@ -624,9 +624,10 @@ describe("credential_store tool — oauth2_connect error paths", () => {
     expect(result.content).toContain("client_id is required");
   });
 
-  test("requires interactive context", async () => {
-    // Register custom-svc as a provider so the orchestrator finds it
-    // and reaches the non-interactive check (gateway transport).
+  test("non-interactive loopback oauth2_connect returns deferred auth URL", async () => {
+    // After the blanket non-interactive guard was removed (#16337),
+    // loopback-transport flows succeed with a deferred auth URL so the
+    // agent can present it to the user.
     mockGetProvider.mockImplementation((key: string) => {
       if (key === "custom-svc") {
         return {
@@ -651,11 +652,11 @@ describe("credential_store tool — oauth2_connect error paths", () => {
       },
       { ..._ctx, isInteractive: false },
     );
-    expect(result.isError).toBe(true);
-    expect(result.content).toContain("non-interactive session");
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("mock-auth-url.example.com");
   });
 
-  test("resolves gmail alias to integration:gmail", async () => {
+  test("resolves gmail alias to integration:google", async () => {
     // Even with alias resolution, missing client_id should still fail
     const result = await credentialStoreTool.execute(
       {
@@ -687,13 +688,13 @@ describe("credential_store tool — oauth2_connect error paths", () => {
     // and store client_secret in the secure store.
     mockGetMostRecentAppByProvider.mockImplementation(() => ({
       id: "test-app-id",
-      providerKey: "integration:gmail",
+      providerKey: "integration:google",
       clientId: "stored-client-id-123",
       clientSecretCredentialPath: "oauth_app/test-app-id/client_secret",
       createdAt: Date.now(),
     }));
     mockGetProvider.mockImplementation(() => ({
-      key: "integration:gmail",
+      key: "integration:google",
       authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
       tokenUrl: "https://oauth2.googleapis.com/token",
       defaultScopes: JSON.stringify(["https://mail.google.com/"]),
@@ -731,12 +732,12 @@ describe("credential_store tool — oauth2_connect error paths", () => {
     mockGetAppByProviderAndClientId.mockImplementation(
       (providerKey: string, cId: string) => {
         if (
-          providerKey === "integration:gmail" &&
+          providerKey === "integration:google" &&
           cId === "caller-supplied-client-id"
         ) {
           return {
             id: "matched-app-id",
-            providerKey: "integration:gmail",
+            providerKey: "integration:google",
             clientId: "caller-supplied-client-id",
             clientSecretCredentialPath:
               "oauth_app/matched-app-id/client_secret",
@@ -747,7 +748,7 @@ describe("credential_store tool — oauth2_connect error paths", () => {
       },
     );
     mockGetProvider.mockImplementation(() => ({
-      key: "integration:gmail",
+      key: "integration:google",
       authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
       tokenUrl: "https://oauth2.googleapis.com/token",
       defaultScopes: JSON.stringify(["https://mail.google.com/"]),
@@ -782,13 +783,13 @@ describe("credential_store tool — oauth2_connect error paths", () => {
     // use getMostRecentAppByProvider (the fallback heuristic).
     mockGetMostRecentAppByProvider.mockImplementation(() => ({
       id: "recent-app-id",
-      providerKey: "integration:gmail",
+      providerKey: "integration:google",
       clientId: "recent-client-id",
       clientSecretCredentialPath: "oauth_app/recent-app-id/client_secret",
       createdAt: Date.now(),
     }));
     mockGetProvider.mockImplementation(() => ({
-      key: "integration:gmail",
+      key: "integration:google",
       authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
       tokenUrl: "https://oauth2.googleapis.com/token",
       defaultScopes: JSON.stringify(["https://mail.google.com/"]),
@@ -822,7 +823,7 @@ describe("credential_store tool — oauth2_connect error paths", () => {
     // report the missing secret error.
     mockGetAppByProviderAndClientId.mockImplementation(() => undefined);
     mockGetProvider.mockImplementation(() => ({
-      key: "integration:gmail",
+      key: "integration:google",
       authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
       tokenUrl: "https://oauth2.googleapis.com/token",
       defaultScopes: JSON.stringify(["https://mail.google.com/"]),
@@ -853,12 +854,12 @@ describe("credential_store tool — oauth2_connect error paths", () => {
     // guardrail.
     mockGetMostRecentAppByProvider.mockImplementation(() => ({
       id: "test-app-id-no-secret",
-      providerKey: "integration:gmail",
+      providerKey: "integration:google",
       clientId: "stored-client-id-456",
       createdAt: Date.now(),
     }));
     mockGetProvider.mockImplementation(() => ({
-      key: "integration:gmail",
+      key: "integration:google",
       authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
       tokenUrl: "https://oauth2.googleapis.com/token",
       defaultScopes: JSON.stringify(["https://mail.google.com/"]),

package/src/__tests__/credential-vault.test.ts

@@ -735,7 +735,7 @@ describe("credential_store tool", () => {
       await credentialStoreTool.execute(
         {
           action: "store",
-          service: "integration:gmail",
+          service: "integration:google",
           field: "api_key",
           value: "test-value",
         },
@@ -743,9 +743,9 @@ describe("credential_store tool", () => {
       );
 
       // Simulate an active OAuth connection for this service
-      mockConnections.set("integration:gmail", {
+      mockConnections.set("integration:google", {
         id: "conn-gmail",
-        providerKey: "integration:gmail",
+        providerKey: "integration:google",
         oauthAppId: "app-gmail",
         expiresAt: Date.now() + 3600_000,
       });
@@ -753,7 +753,7 @@ describe("credential_store tool", () => {
       const result = await credentialStoreTool.execute(
         {
           action: "delete",
-          service: "integration:gmail",
+          service: "integration:google",
           field: "api_key",
         },
         _ctx,
@@ -764,7 +764,7 @@ describe("credential_store tool", () => {
       // Verify disconnectOAuthProvider was called with the service name
       expect(mockDisconnectOAuthProvider).toHaveBeenCalledTimes(1);
       expect(mockDisconnectOAuthProvider).toHaveBeenCalledWith(
-        "integration:gmail",
+        "integration:google",
       );
     });
   });
@@ -1343,7 +1343,7 @@ describe("withValidToken refresh deduplication", () => {
   }
 
   test("3 concurrent 401 refreshes for the same service call doRefresh exactly once", async () => {
-    setupService("integration:gmail");
+    setupService("integration:google");
 
     let resolveRefresh!: (value: {
       accessToken: string;
@@ -1367,9 +1367,9 @@ describe("withValidToken refresh deduplication", () => {
 
     // Launch 3 concurrent withValidToken calls — all will get a non-expired
     // token first, call the callback, get a 401, and then try to refresh.
-    const p1 = withValidToken("integration:gmail", callback);
-    const p2 = withValidToken("integration:gmail", callback);
-    const p3 = withValidToken("integration:gmail", callback);
+    const p1 = withValidToken("integration:google", callback);
+    const p2 = withValidToken("integration:google", callback);
+    const p3 = withValidToken("integration:google", callback);
 
     // Let the event loop tick so all 3 calls enter the 401 retry path
     await new Promise((r) => setTimeout(r, 10));
@@ -1391,7 +1391,7 @@ describe("withValidToken refresh deduplication", () => {
   });
 
   test("concurrent refreshes for different services proceed independently", async () => {
-    setupService("integration:gmail");
+    setupService("integration:google");
     setupService("integration:slack");
 
     let resolveGmail!: (value: {
@@ -1436,7 +1436,7 @@ describe("withValidToken refresh deduplication", () => {
       return `slack-${token}`;
     };
 
-    const p1 = withValidToken("integration:gmail", gmailCallback);
+    const p1 = withValidToken("integration:google", gmailCallback);
     const p2 = withValidToken("integration:slack", slackCallback);
 
     await new Promise((r) => setTimeout(r, 10));
@@ -1455,7 +1455,7 @@ describe("withValidToken refresh deduplication", () => {
   });
 
   test("deduplication cleans up after refresh completes, allowing subsequent refreshes", async () => {
-    setupService("integration:gmail");
+    setupService("integration:google");
 
     let refreshCount = 0;
     mockRefreshOAuth2Token.mockImplementation(() => {
@@ -1470,7 +1470,7 @@ describe("withValidToken refresh deduplication", () => {
 
     // First call triggers a refresh (old token → 401 → refresh → token-1)
     const r1 = await withValidToken(
-      "integration:gmail",
+      "integration:google",
       async (token: string) => {
         if (token !== "token-1") throw err401;
         return token;
@@ -1482,7 +1482,7 @@ describe("withValidToken refresh deduplication", () => {
     // Second call also triggers a 401 to verify dedup state was cleaned up
     // and a new refresh is allowed (not deduplicated with the first).
     const r2 = await withValidToken(
-      "integration:gmail",
+      "integration:google",
       async (token: string) => {
         if (token !== "token-2") throw err401;
         return token;
@@ -1495,7 +1495,7 @@ describe("withValidToken refresh deduplication", () => {
   });
 
   test("deduplication propagates refresh errors to all waiting callers", async () => {
-    setupService("integration:gmail");
+    setupService("integration:google");
 
     mockRefreshOAuth2Token.mockImplementation(() =>
       Promise.reject(
@@ -1513,8 +1513,8 @@ describe("withValidToken refresh deduplication", () => {
     };
 
     // Launch 2 concurrent calls — both should fail with the same error
-    const p1 = withValidToken("integration:gmail", callback);
-    const p2 = withValidToken("integration:gmail", callback);
+    const p1 = withValidToken("integration:google", callback);
+    const p2 = withValidToken("integration:google", callback);
 
     const results = await Promise.allSettled([p1, p2]);