@vellumai/assistant 0.4.46 → 0.4.49

package/ARCHITECTURE.md

@@ -347,8 +347,8 @@ Both tokens are stored in the secure key store (macOS Keychain with encrypted fi
 
 | Secure key                           | Content                                                                    |
 | ------------------------------------ | -------------------------------------------------------------------------- |
-| `credential:slack_channel:bot_token` | Slack bot token (used for `chat.postMessage` and `auth.test`)              |
-| `credential:slack_channel:app_token` | Slack app token (`xapp-...`, used for Socket Mode `apps.connections.open`) |
+| `credential/slack_channel/bot_token` | Slack bot token (used for `chat.postMessage` and `auth.test`)              |
+| `credential/slack_channel/app_token` | Slack app token (`xapp-...`, used for Socket Mode `apps.connections.open`) |
 
 Workspace metadata (team ID, team name, bot user ID, bot username) is stored as JSON in the credential metadata store under `('slack_channel', 'bot_token')`.
 
@@ -468,7 +468,7 @@ A complementary access-granting flow where the guardian proactively creates a sh
 
 | Channel  | Status   | Prerequisites                                                                                                                                                 |
 | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Telegram | Shipped  | Bot username resolved from credential metadata or `TELEGRAM_BOT_USERNAME` env                                                                                 |
+| Telegram | Shipped  | Bot username resolved from credential metadata or config                                                                                                      |
 | Voice    | Shipped  | Identity-bound voice code redemption via DTMF/speech in the relay state machine. Always-on canonical behavior with personalized friend/guardian name prompts. |
 | Slack    | Deferred | Needs DM-safe ingress — Socket Mode handles channel messages but DM-initiated invite flows need routing                                                       |
 
@@ -641,7 +641,7 @@ The assistant feature-flag resolver (`src/config/assistant-feature-flags.ts`) is
 | **3. `skill_load` tool**           | `executeSkillLoad()` in `tools/skills/load.ts`           | If the model attempts to load a flagged-off skill by name, the tool returns an error: `"skill is currently unavailable (disabled by feature flag)"`.                                                        |
 | **4. Runtime tool projection**     | `projectSkillTools()` in `daemon/session-skill-tools.ts` | Even if a skill was previously active in a session (has `<loaded_skill>` markers in history), the per-turn projection drops it when the flag is OFF. Already-registered tools are unregistered.             |
 | **5. Included child skills**       | `executeSkillLoad()` in `tools/skills/load.ts`           | When a parent skill includes children via the `includes` directive, each child is independently checked against its feature flag. Flagged-off children are silently excluded from the loaded skill content. |
-| **6. Skill install gate**          | `handleInstallSkill()` in `daemon/handlers/skills.ts`    | When a client requests skill installation, the handler checks the skill's feature flag before proceeding. If the flag is OFF, the install is rejected with an error.                                        |
+| **6. Skill install gate**          | `handleSkillsInstall()` in `daemon/handlers/skills.ts`   | When a client requests skill installation, the handler checks the skill's feature flag before proceeding. If the flag is OFF, the install is rejected with an error.                                        |
 
 All six enforcement points derive the flag key via `skillFlagKey(skill)` — which returns `undefined` for ungated skills, short-circuiting the check — and then call `isAssistantFeatureFlagEnabled(flagKey, config)` for consistency.
 
@@ -657,7 +657,7 @@ All six enforcement points derive the flag key via `skillFlagKey(skill)` — whi
 | `src/tools/skills/load.ts`                      | `executeSkillLoad()` — enforcement points 3 and 5                                                                                                                         |
 | `src/daemon/session-skill-tools.ts`             | `projectSkillTools()` — enforcement point 4                                                                                                                               |
 | `src/config/schema.ts`                          | `assistantFeatureFlagValues` field definition in `AssistantConfig` (Zod schema)                                                                                           |
-| `src/daemon/handlers/skills.ts`                 | `handleSkillsList()` — uses `resolveSkillStates()` for client responses; `handleInstallSkill()` — enforcement point 6                                                     |
+| `src/daemon/handlers/skills.ts`                 | `handleSkillsList()` — uses `resolveSkillStates()` for client responses; `handleSkillsInstall()` — enforcement point 6                                                    |
 | `meta/feature-flags/feature-flag-registry.json` | Unified feature flag registry (repo root) — all declared flags with scope, label, default values, and descriptions                                                        |
 | `src/config/feature-flag-registry.json`         | Bundled copy of the unified registry for compiled binary resolution                                                                                                       |
 
@@ -669,7 +669,7 @@ All six enforcement points derive the flag key via `skillFlagKey(skill)` — whi
 graph LR
     subgraph "macOS Keychain"
         K1["API Key<br/>service: vellum-assistant<br/>account: anthropic<br/>stored via /usr/bin/security CLI"]
-        K2["Credential Secrets<br/>key: credential:{service}:{field}<br/>stored via secure-keys.ts<br/>(encrypted file fallback if Keychain unavailable)"]
+        K2["Credential Secrets<br/>key: credential/{service}/{field}<br/>stored via secure-keys.ts<br/>(encrypted file fallback if Keychain unavailable)"]
     end
 
     subgraph "UserDefaults (plist)"
@@ -1709,7 +1709,7 @@ graph TB
     end
 
     subgraph "SSE Transport"
-        SSE_ROUTE["SSE Route<br/>GET /v1/events?conversationKey=...<br/>(events-routes.ts)<br/>──────────────────────<br/>ReadableStream + CountQueuingStrategy(16)<br/>Heartbeat every 30 s<br/>Slow-consumer shed"]
+        SSE_ROUTE["SSE Route<br/>GET /v1/events[?conversationKey=...]<br/>(events-routes.ts)<br/>──────────────────────<br/>ReadableStream + CountQueuingStrategy(16)<br/>Heartbeat every 30 s<br/>Slow-consumer shed"]
     end
 
     subgraph "Clients"

package/README.md

@@ -73,7 +73,6 @@ For low-level development (e.g., working on the assistant runtime itself):
 ```bash
 bun run src/index.ts daemon start   # start daemon only
 bun run src/index.ts                # interactive CLI session
-bun run src/index.ts dev            # dev mode (auto-restart on file changes)
 ```
 
 ### CLI commands
@@ -84,7 +83,6 @@ bun run src/index.ts dev            # dev mode (auto-restart on file changes)
 | `vellum sleep`                                | Stop assistant + gateway processes               |
 | `vellum ps`                                   | List assistants and per-assistant process status |
 | `assistant`                                   | Launch interactive CLI session                   |
-| `assistant dev`                               | Run assistant with auto-restart on file changes  |
 | `assistant sessions list\|new\|export\|clear` | Manage conversation sessions                     |
 | `assistant config set\|get\|list`             | Manage configuration                             |
 | `assistant keys set\|list\|delete`            | Manage API keys in secure storage                |
@@ -241,12 +239,9 @@ The per-assistant mapping is propagated to the gateway via the config file watch
 
 ### Phone Number Resolution Order
 
-At runtime, `getTwilioConfig()` resolves the phone number using this priority chain:
+At runtime, `getTwilioConfig()` resolves the phone number from **`twilio.phoneNumber` in config** — the primary source of truth, written by `provision_number` and `assign_number`.
 
-1. **`TWILIO_PHONE_NUMBER` env var** — highest priority, explicit override for dev/CI.
-2. **`twilio.phoneNumber` in config** — the primary source of truth, written by `provision_number` and `assign_number`.
-
-If no number is found after both sources, an error is thrown.
+If no number is found, an error is thrown.
 
 ### Assistant-Scoped Guardian State
 
@@ -476,22 +471,6 @@ docker run --rm -p 3001:3001 \
 
 The image exposes port `3001` and bundles the `assistant` CLI binary.
 
-## Ride Shotgun
-
-Ride Shotgun is a background screen-watching feature that observes user workflows. It has two modes:
-
-- **Observe mode** — captures periodic screenshots and generates a workflow summary via the LLM.
-- **Learn mode** — records browser network traffic alongside screenshots to capture API patterns. The assistant owns CDP browser lifecycle: `ride-shotgun-handler.ts` calls `ensureChromeWithCdp()` to launch or connect to Chrome with remote debugging, so clients do not need to pre-launch Chrome with `--remote-debugging-port`.
-
-Key modules:
-
-| File                                    | Purpose                                                 |
-| --------------------------------------- | ------------------------------------------------------- |
-| `src/daemon/ride-shotgun-handler.ts`    | Session orchestration, CDP bootstrap, network recording |
-| `src/tools/browser/chrome-cdp.ts`       | Reusable Chrome CDP launcher (`ensureChromeWithCdp`)    |
-| `src/tools/browser/network-recorder.ts` | CDP-based network traffic capture                       |
-| `src/tools/browser/recording-store.ts`  | Session recording persistence                           |
-
 ## Troubleshooting
 
 ### Guardian and gateway-origin issues

package/docs/architecture/integrations.md

@@ -28,7 +28,7 @@ graph TB
         DRAFT["messaging_draft"]
         SENDER_DIGEST["messaging_sender_digest"]
         ARCHIVE_BY_SENDER["messaging_archive_by_sender"]
-        SHARED["shared.ts<br/>resolveProvider + withProviderToken"]
+        SHARED["shared.ts<br/>resolveProvider + getProviderConnection"]
     end
 
     subgraph "Gmail Skill (bundled-skills/gmail/)"
@@ -121,7 +121,8 @@ sequenceDiagram
     participant OAuth as OAuth2 PKCE Flow
     participant Browser as System Browser
     participant Google as Google OAuth Server
-    participant Vault as Credential Vault
+    participant Store as SQLite OAuth Store
+    participant Vault as Secure Keychain
     participant TokenMgr as TokenManager
     participant Tool as Gmail Tool Executor
     participant API as Gmail REST API
@@ -140,20 +141,25 @@ sequenceDiagram
     Google->>OAuth: callback with auth code
     OAuth->>Google: exchange code + code_verifier for tokens
     Google-->>OAuth: access + refresh tokens
-    OAuth->>Vault: setSecureKey (access + refresh)
-    OAuth->>Vault: upsertCredentialMetadata (allowedTools, expiresAt)
+    OAuth->>Store: storeOAuth2Tokens() → upsert oauth_app + oauth_connection rows
+    Store->>Vault: setSecureKeyAsync("oauth_connection/{id}/access_token")
+    Store->>Vault: setSecureKeyAsync("oauth_connection/{id}/refresh_token")
+    Store->>Store: write expiresAt, grantedScopes to oauth_connections
     OAuth-->>Handler: success + account email
     Handler->>HTTP: integration_connect_result {success, accountInfo}
     HTTP->>UI: show connected state
 
     Note over UI,API: Tool Execution Flow
     Tool->>TokenMgr: withValidToken("gmail", callback)
-    TokenMgr->>Vault: getSecureKey("integration:gmail:access_token")
-    TokenMgr->>Vault: getMetadata (check expiresAt)
+    TokenMgr->>Store: getConnectionByProvider("integration:gmail")
+    TokenMgr->>Vault: getSecureKey("oauth_connection/{conn.id}/access_token")
+    TokenMgr->>Store: check oauth_connections.expires_at
     alt Token expired
+        TokenMgr->>Store: resolveRefreshConfig() → tokenUrl, clientId from provider/app rows
         TokenMgr->>Google: refresh with refresh_token
         Google-->>TokenMgr: new access token
-        TokenMgr->>Vault: update access token + expiresAt
+        TokenMgr->>Vault: setSecureKeyAsync("oauth_connection/{id}/access_token")
+        TokenMgr->>Store: updateConnection(expiresAt)
     end
     TokenMgr->>Tool: callback(validToken)
     Tool->>API: Gmail REST API call with Bearer token
@@ -167,13 +173,13 @@ sequenceDiagram
 
 | Decision                                   | Rationale                                                                                                                                                                                                                                        |
 | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| PKCE by default, optional client_secret    | Desktop apps prefer PKCE; some providers (Slack) require a secret, which is stored in credential metadata for autonomous refresh                                                                                                                 |
+| PKCE by default, optional client_secret    | Desktop apps prefer PKCE; some providers (Slack) require a secret, which is stored in the secure keychain (`oauth_app/{id}/client_secret`) for autonomous refresh                                                                                |
 | Shared connect orchestrator                | All OAuth providers route through `orchestrateOAuthConnect()`, which resolves profiles, enforces scope policy, runs the flow, stores tokens, and verifies identity. Adding a provider is a declarative profile entry, not new orchestration code |
 | Canonical credential naming                | All reads and writes use `client_id`/`client_secret` as canonical field names                                                                                                                                                                    |
 | Gateway callback transport                 | OAuth callbacks are now routed through the gateway at `${ingress.publicBaseUrl}/webhooks/oauth/callback` instead of a loopback redirect URI. This enables OAuth flows to work in remote and tunneled deployments.                                |
 | Unified `MessagingProvider` interface      | All platforms implement the same contract; generic tools work immediately for new providers                                                                                                                                                      |
 | Provider auto-selection                    | If only one provider is connected, tools skip the `platform` parameter — seamless single-platform UX                                                                                                                                             |
-| Token expiry in credential metadata        | Reuses existing `CredentialMetadata` store; `expiresAt` field enables proactive refresh with 5min buffer                                                                                                                                         |
+| Token expiry in SQLite oauth-store         | `oauth_connections.expires_at` column tracks token expiry; `TokenManager` reads it for proactive refresh with 5min buffer. No separate metadata store needed                                                                                     |
 | Confidence scores on medium-risk tools     | LLM self-reports confidence (0-1); enables future trust calibration without blocking execution                                                                                                                                                   |
 | Platform-specific extension tools          | Operations unique to one platform (e.g. Gmail labels, Slack reactions) are separate tools, not forced into the generic interface                                                                                                                 |
 | Identity verification before token storage | OAuth2 tokens are only persisted after a successful identity verification call, preventing storage of invalid or mismatched credentials                                                                                                          |
@@ -197,34 +203,32 @@ sequenceDiagram
 | `assistant/src/watcher/providers/gmail.ts`       | Gmail watcher using History API                                                                    |
 | `assistant/src/watcher/providers/github.ts`      | GitHub watcher for PRs, issues, review requests, and mentions                                      |
 | `assistant/src/watcher/providers/linear.ts`      | Linear watcher for assigned issues, status changes, and @mentions                                  |
-| `assistant/src/oauth/provider-profiles.ts`       | Provider profile registry: auth URLs, token URLs, scopes, policies, identity verifiers             |
+| `assistant/src/oauth/provider-behaviors.ts`      | Provider behavior registry: identity verifiers, setup metadata, injection templates                |
 | `assistant/src/oauth/connect-orchestrator.ts`    | Shared OAuth connect orchestrator: profile resolution, scope policy, flow execution, token storage |
 | `assistant/src/oauth/scope-policy.ts`            | Deterministic scope resolution and policy enforcement                                              |
-| `assistant/src/oauth/connect-types.ts`           | Shared types: `OAuthProviderProfile`, `OAuthScopePolicy`, `OAuthConnectResult`                     |
+| `assistant/src/oauth/connect-types.ts`           | Shared types: `OAuthProviderBehavior`, `OAuthScopePolicy`, `OAuthConnectResult`                    |
 | `assistant/src/oauth/token-persistence.ts`       | Token storage helper: persists tokens, metadata, and runs post-connect hooks                       |
 | `assistant/src/daemon/handlers/oauth-connect.ts` | Generic OAuth connect handler (`oauth_connect_start` / `oauth_connect_result`)                     |
 
 ---
 
-## OAuth Extensibility — Provider Profiles, Scope Policy, and Connect Orchestrator
+## OAuth Extensibility — Provider Behaviors, Scope Policy, and Connect Orchestrator
 
-The OAuth extensibility layer makes adding a new OAuth provider a declarative operation. Instead of writing custom auth handlers, new providers are added as entries in the **provider profile registry**. The shared **connect orchestrator** handles the full flow from profile resolution through token storage.
+The OAuth extensibility layer makes adding a new OAuth provider a declarative operation. Protocol fields (auth URLs, token URLs, scopes, scope policy) are stored in the `oauth_providers` database table, while behavioral fields (identity verifiers, setup metadata, injection templates) live in the **provider behavior registry**. The shared **connect orchestrator** handles the full flow from provider resolution through token storage.
 
-### Provider Profile Registry
+### Provider Behavior Registry
 
-`assistant/src/oauth/provider-profiles.ts` contains the `PROVIDER_PROFILES` map — a canonical registry of well-known OAuth providers. Each profile (`OAuthProviderProfile`) declares:
+`assistant/src/oauth/provider-behaviors.ts` contains the `PROVIDER_BEHAVIORS` map — a registry of behavioral aspects for well-known OAuth providers. Each behavior (`OAuthProviderBehavior`) declares:
 
-| Field                  | Purpose                                                                                                |
-| ---------------------- | ------------------------------------------------------------------------------------------------------ |
-| `authUrl` / `tokenUrl` | OAuth2 authorization and token endpoints                                                               |
-| `defaultScopes`        | Scopes requested on every connect attempt                                                              |
-| `scopePolicy`          | Controls whether additional scopes are allowed (see Scope Policy below)                                |
-| `callbackTransport`    | `'loopback'` (local redirect) or `'gateway'` (public ingress)                                          |
-| `identityVerifier`     | Async function that fetches human-readable account info (e.g. `@username`, email) after token exchange |
-| `setup`                | Optional metadata for the generic OAuth setup skill (display name, dashboard URL, app type)            |
-| `injectionTemplates`   | Auto-applied credential injection rules for the script proxy                                           |
+| Field                | Purpose                                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------------------ |
+| `identityVerifier`   | Async function that fetches human-readable account info (e.g. `@username`, email) after token exchange |
+| `setup`              | Optional metadata for the generic OAuth setup skill (display name, dashboard URL, app type)            |
+| `injectionTemplates` | Auto-applied credential injection rules for the script proxy                                           |
 
-Registered providers: `integration:gmail`, `integration:slack`, `integration:notion`. Short aliases (e.g. `gmail`, `slack`) are resolved via `SERVICE_ALIASES`.
+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()`.
 
 ### Scope Policy Engine
 
@@ -244,9 +248,9 @@ Returns `{ ok: true, scopes }` or `{ ok: false, error, allowedScopes }`.
 `assistant/src/oauth/connect-orchestrator.ts` exports `orchestrateOAuthConnect(options)`, which runs the full OAuth2 flow:
 
 1. **Resolve service** — alias expansion via `resolveService()`.
-2. **Load profile** — `getProviderProfile()` from the registry.
+2. **Load behavior** — `getProviderBehavior()` from the registry; load protocol fields from the `oauth_providers` DB table.
 3. **Compute scopes** — `resolveScopes()` with scope policy enforcement.
-4. **Build OAuth config** — merge profile defaults with caller overrides.
+4. **Build OAuth config** — assemble protocol-level config from the DB provider row.
 5. **Run flow** — interactive (opens browser, blocks until completion) or deferred (returns auth URL for the caller to deliver).
 6. **Verify identity** — runs the profile's `identityVerifier` if defined.
 7. **Store tokens** — `storeOAuth2Tokens()` persists access/refresh tokens, client credentials, and metadata.
@@ -266,24 +270,24 @@ This replaces provider-specific handlers — any provider in the registry can be
 
 ### Adding a New OAuth Provider
 
-1. **Declare a profile** in `PROVIDER_PROFILES` (`oauth/provider-profiles.ts`):
+1. **Register protocol fields** in the `oauth_providers` database table (via CLI or migration):
    - Set `authUrl`, `tokenUrl`, `defaultScopes`, `scopePolicy`, and `callbackTransport`.
-   - Add a `SERVICE_ALIASES` entry if a shorthand name is desired.
-2. **Optional: add an identity verifier** — an async function on the profile that fetches the user's account info from the provider's API.
-3. **Optional: add setup metadata** — `setup.displayName`, `setup.dashboardUrl`, `setup.appType` enable the generic OAuth setup skill to guide users through app creation.
-4. **Optional: add injection templates** — for providers whose tokens should be auto-injected by the script proxy.
-5. **No handler code needed** — the generic `oauth_connect_start` handler and the connect orchestrator handle the flow automatically.
+2. **Optional: declare behavioral fields** in `PROVIDER_BEHAVIORS` (`oauth/provider-behaviors.ts`):
+   - Add an `identityVerifier` — an async function that fetches the user's account info from the provider's API.
+   - Add `setup` metadata — `displayName`, `dashboardUrl`, `appType` enable the generic OAuth setup skill to guide users through app creation.
+   - Add `injectionTemplates` — for providers whose tokens should be auto-injected by the script proxy.
+3. **No handler code needed** — the generic `oauth_connect_start` handler and the connect orchestrator handle the flow automatically.
 
 ### Key Source Files
 
-| File                                             | Role                                                                            |
-| ------------------------------------------------ | ------------------------------------------------------------------------------- |
-| `assistant/src/oauth/provider-profiles.ts`       | Provider profile registry and alias resolution                                  |
-| `assistant/src/oauth/scope-policy.ts`            | Scope resolution and policy enforcement (pure, no I/O)                          |
-| `assistant/src/oauth/connect-orchestrator.ts`    | Shared connect orchestrator (profile → scopes → flow → tokens)                  |
-| `assistant/src/oauth/connect-types.ts`           | Shared types (`OAuthProviderProfile`, `OAuthScopePolicy`, `OAuthConnectResult`) |
-| `assistant/src/oauth/token-persistence.ts`       | Token storage: keychain writes, metadata upsert, post-connect hooks             |
-| `assistant/src/daemon/handlers/oauth-connect.ts` | Generic `oauth_connect_start` / `oauth_connect_result` handler                  |
+| File                                             | Role                                                                             |
+| ------------------------------------------------ | -------------------------------------------------------------------------------- |
+| `assistant/src/oauth/provider-behaviors.ts`      | Provider behavior registry and alias resolution                                  |
+| `assistant/src/oauth/scope-policy.ts`            | Scope resolution and policy enforcement (pure, no I/O)                           |
+| `assistant/src/oauth/connect-orchestrator.ts`    | Shared connect orchestrator (profile → scopes → flow → tokens)                   |
+| `assistant/src/oauth/connect-types.ts`           | Shared types (`OAuthProviderBehavior`, `OAuthScopePolicy`, `OAuthConnectResult`) |
+| `assistant/src/oauth/token-persistence.ts`       | Token storage: keychain writes, metadata upsert, post-connect hooks              |
+| `assistant/src/daemon/handlers/oauth-connect.ts` | Generic `oauth_connect_start` / `oauth_connect_result` handler                   |
 
 ---
 

package/docs/architecture/keychain-broker.md

@@ -66,7 +66,7 @@ graph LR
 ### Transport
 
 - Unix domain socket: `~/.vellum/keychain-broker.sock`
-- Socket path is passed to daemon/gateway via `VELLUM_KEYCHAIN_BROKER_SOCKET` environment variable
+- Socket path is derived from the data directory (e.g., `join(getRootDir(), "keychain-broker.sock")`)
 - Newline-delimited JSON (`\n` as message boundary)
 
 ### Request envelope
@@ -157,8 +157,8 @@ XPC provides stronger caller identity guarantees via audit tokens and code requi
 
 ## Developer Experience
 
-- **Debug builds:** The `#if !DEBUG` guard compiles out the entire `KeychainBrokerServer`. The `VELLUM_KEYCHAIN_BROKER_SOCKET` env var is not set, so clients see the broker as unavailable and use the encrypted store. Developers never encounter keychain prompts during the edit-build-run cycle.
-- **Release builds:** The broker starts automatically with the app. The daemon discovers it via the socket env var and token file. No configuration needed.
+- **Debug builds:** The `#if !DEBUG` guard compiles out the entire `KeychainBrokerServer`. The broker socket is not created, so clients see the broker as unavailable and use the encrypted store. Developers never encounter keychain prompts during the edit-build-run cycle.
+- **Release builds:** The broker starts automatically with the app. The daemon discovers the broker via the derived socket path (`join(getRootDir(), "keychain-broker.sock")`) and token file. No configuration needed.
 - **CLI-only / headless:** No macOS app means no broker socket. All storage uses the encrypted file store. This is the expected path for CI, servers, and non-macOS platforms.
 
 ## Callsite Policy

package/docs/architecture/security.md

@@ -179,7 +179,7 @@ File tool candidates include canonical (symlink-resolved) absolute paths via `no
 | `assistant/src/permissions/checker.ts`        | `classifyRisk()`, `check()`, `buildCommandCandidates()`, allowlist/scope generation                                                                                                 |
 | `assistant/src/permissions/shell-identity.ts` | `analyzeShellCommand()`, `deriveShellActionKeys()`, `buildShellCommandCandidates()`, `buildShellAllowlistOptions()` — parser-based shell command identity and action key derivation |
 | `assistant/src/permissions/trust-store.ts`    | Rule persistence, `findHighestPriorityRule()`, execution-target matching, starter bundle                                                                                            |
-| `assistant/src/permissions/prompter.ts`       | HTTP prompt flow: `confirmation_request` → `confirmation_response`                                                                                                                   |
+| `assistant/src/permissions/prompter.ts`       | HTTP prompt flow: `confirmation_request` → `confirmation_response`                                                                                                                  |
 | `assistant/src/permissions/defaults.ts`       | Default rule templates (system ask rules for host tools, CU, etc.)                                                                                                                  |
 | `assistant/src/skills/version-hash.ts`        | `computeSkillVersionHash()` — deterministic SHA-256 of skill source files                                                                                                           |
 | `assistant/src/skills/path-classifier.ts`     | `isSkillSourcePath()`, `normalizeFilePath()`, skill root detection                                                                                                                  |
@@ -233,7 +233,7 @@ sequenceDiagram
         UI->>HTTP: secret_response {requestId, value, delivery: "store"}
         HTTP->>Prompter: resolve(value, "store")
         Prompter->>Vault: {value, delivery: "store"}
-        Vault->>Keychain: setSecureKey("credential:svc:field", value)
+        Vault->>Keychain: setSecureKey("credential/svc/field", value)
         Vault->>Model: "Credential stored securely" (no value in output)
     else One-Time Send (if enabled)
         UI->>HTTP: secret_response {requestId, value, delivery: "transient_send"}
@@ -272,7 +272,7 @@ graph TB
     TOOL["Tool (e.g. browser_fill_credential)"] --> BROKER["CredentialBroker.use(service, field, tool, domain)"]
     BROKER --> POLICY{"Check policy:<br/>allowedTools + allowedDomains"}
     POLICY -->|denied| REJECT["PolicyDenied error"]
-    POLICY -->|allowed| FETCH["getSecureKey(credential:svc:field)"]
+    POLICY -->|allowed| FETCH["getSecureKey(credential/svc/field)"]
     FETCH --> INJECT["Inject value into tool execution<br/>(never returned to model)"]
 ```
 
@@ -290,7 +290,7 @@ The `allowOneTimeSend` config gate (default: `false`) enables a secondary "Send
 
 | Component           | Location                                             | What it stores                                                                                                                                               |
 | ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Secret values       | macOS Keychain (primary) or encrypted file fallback  | Encrypted credential values keyed as `credential:{service}:{field}`. Falls back to encrypted file backend on Linux/headless or when Keychain is unavailable. |
+| Secret values       | macOS Keychain (primary) or encrypted file fallback  | Encrypted credential values keyed as `credential/{service}/{field}`. Falls back to encrypted file backend on Linux/headless or when Keychain is unavailable. |
 | Credential metadata | `~/.vellum/workspace/data/credentials/metadata.json` | Service, field, label, policy (allowedTools, allowedDomains), timestamps                                                                                     |
 | Config              | `~/.vellum/workspace/config.*`                       | `secretDetection` settings: enabled, action, entropyThreshold, allowOneTimeSend                                                                              |
 
@@ -303,7 +303,7 @@ The `allowOneTimeSend` config gate (default: `false`) enables a secondary "Send
 | `assistant/src/tools/credentials/metadata-store.ts`  | JSON file metadata CRUD for credential records                        |
 | `assistant/src/tools/credentials/broker.ts`          | Brokered credential access with policy enforcement and transient send |
 | `assistant/src/tools/credentials/policy-validate.ts` | Policy input validation (allowedTools, allowedDomains)                |
-| `assistant/src/permissions/secret-prompter.ts`       | HTTP secret_request/secret_response flow                               |
+| `assistant/src/permissions/secret-prompter.ts`       | HTTP secret_request/secret_response flow                              |
 | `assistant/src/security/secret-scanner.ts`           | Regex + entropy-based secret detection                                |
 | `assistant/src/security/secret-ingress.ts`           | Inbound message secret blocking                                       |
 | `clients/macos/.../SecretPromptManager.swift`        | Floating panel UI for secure credential entry                         |

package/docs/runbook-trusted-contacts.md

@@ -1,17 +1,12 @@
 # Trusted Contacts — Operator Runbook
 
-Operational procedures for inspecting, managing, and debugging the trusted contact access flow. HTTP commands use the assistant runtime API (default `http://localhost:7821`) with bearer authentication.
-
-> **Note:** The `/v1/contacts` endpoints are served by the assistant runtime, not
-> the gateway. If you prefer to route through the gateway (`localhost:7830`), set
-> `GATEWAY_RUNTIME_PROXY_ENABLED=true` in the gateway environment — the proxy is
-> disabled by default and these routes will 404 without it.
+Operational procedures for inspecting, managing, and debugging the trusted contact access flow. HTTP commands use the gateway API (default `http://localhost:7830`) with bearer authentication.
 
 ## Prerequisites
 
 ```bash
-# Base URL — assistant runtime (adjust if using a non-default port)
-BASE=http://localhost:7821
+# Base URL — gateway (adjust if using a non-default port)
+BASE=http://localhost:7830
 
 # Bearer token: for operator use, retrieve from the daemon process environment
 # or use `assistant` CLI commands which handle auth automatically.

package/hook-templates/debug-prompt-logger/hook.json

@@ -1,6 +1,6 @@
 {
   "name": "debug-prompt-logger",
-  "description": "Logs system prompt and conversation history to stderr when VELLUM_DEBUG=1",
+  "description": "Logs system prompt and conversation history to stderr before each LLM call",
   "version": "1.0.0",
   "events": ["pre-llm-call"],
   "script": "run.sh"

package/hook-templates/debug-prompt-logger/run.sh

@@ -1,8 +1,6 @@
 #!/usr/bin/env bash
 # Debug Prompt Logger — prints the system prompt and conversation
-# history before each LLM call. Only active when VELLUM_DEBUG=1.
-
-[ "$VELLUM_DEBUG" != "1" ] && exit 0
+# history before each LLM call. Runs whenever the hook is installed.
 
 data=$(cat)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.4.46",
+  "version": "0.4.49",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

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

@@ -41,7 +41,6 @@ mock.module("../config/env.js", () => ({
   getGatewayBaseUrl: () => "http://localhost:7822",
   getRuntimeGatewayOriginSecret: () => undefined,
   isHttpAuthDisabledWithoutSafetyGate: () => false,
-  getEnableMonitoring: () => false,
   checkUnrecognizedEnvVars: () => {},
   getBaseDataDir: () => testDir,
 }));

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

@@ -666,6 +666,162 @@ describe("AnthropicProvider — Cache-Control Characterization", () => {
     ).toBe(true);
   });
 
+  // -----------------------------------------------------------------------
+  // ensureToolPairing — server_tool_use / web_search_tool_result pairing
+  // -----------------------------------------------------------------------
+
+  test("server_tool_use with missing web_search_tool_result gets synthetic result injected", async () => {
+    const messages: Message[] = [
+      userMsg("Search for something"),
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "server_tool_use",
+            id: "srvtoolu_abc123",
+            name: "web_search",
+            input: { query: "test" },
+          },
+        ],
+      },
+      userMsg("Thanks"), // user text but no web_search_tool_result
+    ];
+    await provider.sendMessage(messages);
+
+    const sent = lastStreamParams!.messages as Array<{
+      role: string;
+      content: Array<{
+        type: string;
+        tool_use_id?: string;
+        content?: unknown;
+      }>;
+    }>;
+
+    // The user message after assistant should contain a synthetic web_search_tool_result
+    const userAfterAssistant = sent[2];
+    expect(userAfterAssistant.role).toBe("user");
+    expect(userAfterAssistant.content[0].type).toBe("web_search_tool_result");
+    expect(userAfterAssistant.content[0].tool_use_id).toBe("srvtoolu_abc123");
+  });
+
+  test("server_tool_use at end of messages gets synthetic web_search_tool_result appended", async () => {
+    const messages: Message[] = [
+      userMsg("Search something"),
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "server_tool_use",
+            id: "srvtoolu_end",
+            name: "web_search",
+            input: { query: "test" },
+          },
+        ],
+      },
+    ];
+    await provider.sendMessage(messages);
+
+    const sent = lastStreamParams!.messages as Array<{
+      role: string;
+      content: Array<{ type: string; tool_use_id?: string }>;
+    }>;
+
+    // A synthetic user message should have been appended
+    expect(sent).toHaveLength(3);
+    expect(sent[2].role).toBe("user");
+    expect(sent[2].content[0].type).toBe("web_search_tool_result");
+    expect(sent[2].content[0].tool_use_id).toBe("srvtoolu_end");
+  });
+
+  test("server_tool_use with matching web_search_tool_result passes through unchanged", async () => {
+    const messages: Message[] = [
+      userMsg("Search something"),
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "server_tool_use",
+            id: "srvtoolu_ok",
+            name: "web_search",
+            input: { query: "test" },
+          },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          {
+            type: "web_search_tool_result",
+            tool_use_id: "srvtoolu_ok",
+            content: [
+              {
+                type: "web_search_result",
+                url: "https://example.com",
+                title: "Example",
+                encrypted_content: "enc_abc",
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    await provider.sendMessage(messages);
+
+    const sent = lastStreamParams!.messages as Array<{
+      role: string;
+      content: Array<{ type: string; tool_use_id?: string }>;
+    }>;
+
+    // No synthetic messages or blocks added
+    expect(sent).toHaveLength(3);
+    const resultBlocks = sent[2].content.filter(
+      (b) => b.type === "web_search_tool_result",
+    );
+    expect(resultBlocks).toHaveLength(1);
+    expect(resultBlocks[0].tool_use_id).toBe("srvtoolu_ok");
+  });
+
+  test("mixed tool_use and server_tool_use with partial results gets missing ones filled", async () => {
+    const messages: Message[] = [
+      userMsg("Do things"),
+      {
+        role: "assistant",
+        content: [
+          { type: "tool_use", id: "tu_a", name: "file_read", input: {} },
+          {
+            type: "server_tool_use",
+            id: "srvtoolu_b",
+            name: "web_search",
+            input: { query: "test" },
+          },
+        ],
+      },
+      // Only tu_a has a result
+      toolResultMsg("tu_a", "result A"),
+    ];
+    await provider.sendMessage(messages);
+
+    const sent = lastStreamParams!.messages as Array<{
+      role: string;
+      content: Array<{
+        type: string;
+        tool_use_id?: string;
+      }>;
+    }>;
+
+    const userAfterAssistant = sent[2];
+    // Should have tool_result for tu_a and synthetic web_search_tool_result for srvtoolu_b
+    expect(userAfterAssistant.content).toHaveLength(2);
+    expect(userAfterAssistant.content[0]).toMatchObject({
+      type: "tool_result",
+      tool_use_id: "tu_a",
+    });
+    expect(userAfterAssistant.content[1]).toMatchObject({
+      type: "web_search_tool_result",
+      tool_use_id: "srvtoolu_b",
+    });
+  });
+
   test("assistant message with only unknown blocks gets placeholder text", async () => {
     const messages: Message[] = [
       userMsg("Start"),