@vellumai/assistant 0.5.9 → 0.5.11

package/AGENTS.md

@@ -2,4 +2,12 @@
 
 For error handling conventions (throw vs result objects vs null), see [docs/error-handling.md](docs/error-handling.md).
 
-Subdirectory-scoped rules live in local AGENTS.md files: `src/cli/`, `src/runtime/`, `src/approvals/`, `src/notifications/`.
+Subdirectory-scoped rules live in local AGENTS.md files: `src/cli/`, `src/runtime/`, `src/approvals/`, `src/notifications/`, `src/workspace/migrations/`.
+
+## Adding new environment variables
+
+When you introduce a new env var that the assistant process needs to read at runtime, **update `src/tools/terminal/safe-env.ts`** as well.
+
+`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.

package/ARCHITECTURE.md

@@ -321,7 +321,7 @@ The WhatsApp channel enables inbound and outbound messaging via the Meta WhatsAp
 - `WHATSAPP_APP_SECRET` — App secret for webhook signature verification
 - `WHATSAPP_WEBHOOK_VERIFY_TOKEN` — Token for the Meta webhook subscription handshake
 
-These can be set via environment variables or stored in the credential vault (keychain / encrypted store) under the `whatsapp` service prefix.
+These can be set via environment variables or stored in the credential vault (CES / encrypted store) under the `whatsapp` service prefix.
 
 **Limitations (v1)**: Rich approval UI (inline buttons) is not supported. Contacts and location message types are acknowledged but not forwarded.
 
@@ -343,7 +343,7 @@ All endpoints are JWT-authenticated via `Authorization: Bearer <jwt>`.
 
 **Credential storage pattern:**
 
-Both tokens are stored in the secure key store (macOS Keychain with encrypted file fallback):
+Both tokens are stored in the secure key store (CES credential store with encrypted file fallback):
 
 | Secure key                           | Content                                                                    |
 | ------------------------------------ | -------------------------------------------------------------------------- |
@@ -617,7 +617,7 @@ Release-driven update notification system that surfaces release notes to the ass
 
 The assistant feature-flag resolver (`src/config/assistant-feature-flags.ts`) is the canonical module for determining whether an assistant feature flag is enabled. It loads default values from the unified registry at `meta/feature-flags/feature-flag-registry.json` (bundled copy at `src/config/feature-flag-registry.json`) and resolves the effective state for each declared assistant-scope flag. Assistant feature flags are declaration-driven assistant-scoped booleans that can gate any assistant behavior; skill availability is one consumer.
 
-**Canonical key format:** `feature_flags.<flag_id>.enabled` (e.g., `feature_flags.contacts.enabled`).
+**Canonical key format:** Simple kebab-case (e.g., `contacts`, `ces-tools`).
 
 **Resolution priority** (highest wins):
 
@@ -645,7 +645,7 @@ The assistant feature-flag resolver (`src/config/assistant-feature-flags.ts`) is
 
 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.
 
-**Migration path:** The legacy `skills.<id>.enabled` key format is no longer supported. All code must use the canonical `feature_flags.<id>.enabled` format. Guard tests enforce canonical key usage and declaration coverage for literal key references in the unified registry.
+**Migration path:** The legacy `skills.<id>.enabled` and `feature_flags.<id>.enabled` key formats are no longer supported. All code must use simple kebab-case keys (e.g., `contacts`, `ces-tools`). Guard tests enforce canonical key usage and declaration coverage for literal key references in the unified registry.
 
 **Key source files:**
 
@@ -667,9 +667,9 @@ All six enforcement points derive the flag key via `skillFlagKey(skill)` — whi
 
 ```mermaid
 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)"]
+    subgraph "Credential Store"
+        K1["API Key<br/>service: vellum-assistant<br/>account: anthropic<br/>stored via CES"]
+        K2["Credential Secrets<br/>key: credential/{service}/{field}<br/>stored via secure-keys.ts<br/>(encrypted file fallback)"]
     end
 
     subgraph "UserDefaults (plist)"
@@ -1142,7 +1142,7 @@ Skills can expose custom tools via a `TOOLS.json` manifest alongside their `SKIL
 
 ### Bundled Skill Retrieval Contract (CLI-First)
 
-Config/status retrieval instructions in bundled `SKILL.md` files are CLI-first. Retrieval should flow through canonical `vellum` CLI surfaces (`assistant config get` for generic settings, secure credential surfaces for secrets, and domain reads where available) instead of direct gateway curl snippets or keychain lookups.
+Config/status retrieval instructions in bundled `SKILL.md` files are CLI-first. Retrieval should flow through canonical `vellum` CLI surfaces (`assistant config get` for generic settings, secure credential surfaces for secrets, and domain reads where available) instead of direct gateway curl snippets or credential store lookups.
 
 ```mermaid
 graph LR
@@ -1156,7 +1156,7 @@ Rules enforced by guard tests:
 
 - Retrieval reads use `bash` + canonical CLI surfaces (`assistant config get` and domain read commands where available).
 - Direct gateway `curl` + manual bearer headers are for control-plane writes/actions, not retrieval reads.
-- Bundled skill docs must not instruct direct keychain lookups (`security find-generic-password`, `secret-tool`) for retrieval.
+- Bundled skill docs must not instruct direct credential store lookups (`security find-generic-password`, `secret-tool`) for retrieval.
 - `host_bash` is not used for Vellum CLI retrieval commands unless intentionally allowlisted.
 - Outbound credentialed API calls use CES tools (`make_authenticated_request`, `run_authenticated_command`) so credential materialization happens in a separate process. Command output (stdout/stderr) is forwarded back to the assistant and may contain credential values if the command echoes them, so the isolation covers injection, not output. `host_bash` is available as a user-approved escape hatch but is outside the strong secrecy guarantee.
 
@@ -1264,7 +1264,7 @@ graph TB
 
 Skills can embed dynamic shell output in their SKILL.md body using `!`command``tokens. When`skill_load` processes a skill containing these tokens, the commands are executed at load time through a sandboxed runner and their output is substituted inline. This enables externally authored skills to include project-specific context (e.g., directory listings, config values) without requiring manual edits.
 
-**Feature flag:** `feature_flags.inline-skill-commands.enabled` (default: enabled). When disabled, loading a skill that contains `!`command`` tokens fails closed with an error rather than leaving raw tokens in the prompt.
+**Feature flag:** `inline-skill-commands` (default: enabled). When disabled, loading a skill that contains `!`command`` tokens fails closed with an error rather than leaving raw tokens in the prompt.
 
 #### Syntax and Parsing
 
@@ -1935,44 +1935,44 @@ Connected channels are resolved at signal emission time: vellum is always includ
 
 ## Storage Summary
 
-| What                                     | Where                                                             | Format                              | ORM/Driver                         | Retention                                               |
-| ---------------------------------------- | ----------------------------------------------------------------- | ----------------------------------- | ---------------------------------- | ------------------------------------------------------- |
-| API key                                  | macOS Keychain                                                    | Encrypted binary                    | `/usr/bin/security` CLI            | Permanent                                               |
-| Credential secrets                       | macOS Keychain (or encrypted file fallback)                       | Encrypted binary                    | `secure-keys.ts` wrapper           | Permanent (until deleted via tool)                      |
-| Credential metadata                      | `~/.vellum/workspace/data/credentials/metadata.json`              | JSON                                | Atomic file write                  | Permanent (until deleted via tool)                      |
-| Integration OAuth tokens                 | macOS Keychain (or encrypted file fallback, via `secure-keys.ts`) | Encrypted binary                    | `TokenManager` auto-refresh        | Until disconnected or revoked                           |
-| User preferences                         | UserDefaults                                                      | plist                               | Foundation                         | Permanent                                               |
-| Session logs                             | `~/Library/.../logs/session-*.json`                               | JSON per session                    | Swift Codable                      | Unbounded                                               |
-| Conversations & messages                 | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite + WAL                        | Drizzle ORM (Bun)                  | Permanent                                               |
-| Memory segments                          | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent                                               |
-| Extracted facts                          | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent, deduped                                      |
-| Embeddings                               | `~/.vellum/workspace/data/db/assistant.db`                        | JSON float arrays                   | Drizzle ORM                        | Permanent                                               |
-| Async job queue                          | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Completed jobs persist                                  |
-| Attachments                              | `~/.vellum/workspace/data/db/assistant.db`                        | Base64 in SQLite                    | Drizzle ORM                        | Permanent                                               |
-| Sandbox filesystem                       | `~/.vellum/workspace`                                             | Real filesystem tree                | Node FS APIs                       | Persistent across sessions                              |
-| Tool permission rules                    | `~/.vellum/protected/trust.json`                                  | JSON                                | File I/O                           | Permanent                                               |
-| Web users & assistants                   | PostgreSQL                                                        | Relational                          | Drizzle ORM (pg)                   | Permanent                                               |
-| Trace events                             | In-memory (TraceStore)                                            | Structured events                   | Swift ObservableObject             | Max 5,000 per session, ephemeral                        |
-| Media embed settings                     | `~/.vellum/workspace/config.json` (`ui.mediaEmbeds`)              | JSON                                | `WorkspaceConfigIO` (atomic merge) | Permanent                                               |
-| Media embed MIME cache                   | In-memory (`ImageMIMEProbe`)                                      | `NSCache` (500 entries)             | HTTP HEAD                          | Ephemeral; cleared on app restart                       |
-| Tasks & task runs                        | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent                                               |
-| Work items (Task Queue)                  | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; archived items retained                      |
-| Recurrence schedules & runs              | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; supports cron and RRULE syntax               |
-| Watchers & events                        | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent, cascade on watcher delete                    |
-| Proxy CA cert + key                      | `{dataDir}/proxy-ca/`                                             | PEM files (ca.pem, ca-key.pem)      | openssl CLI                        | Permanent (10-year validity)                            |
-| Proxy leaf certs                         | `{dataDir}/proxy-ca/issued/`                                      | PEM files per hostname              | openssl CLI, cached                | 1-year validity, re-issued on CA change                 |
-| Proxy sessions                           | In-memory (SessionManager)                                        | Map<ProxySessionId, ManagedSession> | Manual lifecycle                   | Ephemeral; 5min idle timeout, cleared on shutdown       |
-| Call sessions, events, pending questions | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent, cascade on session delete                    |
-| Active call controllers                  | In-memory (CallState)                                             | Map<callSessionId, CallController>  | Manual lifecycle                   | Ephemeral; cleared on call end or destroy               |
-| Guardian bindings                        | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; revoked bindings retained                    |
-| Channel verification sessions            | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; consumed/expired sessions retained           |
-| Guardian approval requests               | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; decision outcome retained                    |
-| Contact invites                          | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; token hash stored, raw token never persisted |
-| Contacts & channels                      | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; revoked/blocked contacts retained            |
-| Notification events                      | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; deduplicated by dedupeKey                    |
-| Notification decisions                   | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; FK to notification_events                    |
-| Notification deliveries                  | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; FK to notification_decisions                 |
-| Notification preferences                 | `~/.vellum/workspace/data/db/assistant.db`                        | SQLite                              | Drizzle ORM                        | Permanent; per-assistant conversational preferences     |
+| What                                     | Where                                                | Format                              | ORM/Driver                         | Retention                                               |
+| ---------------------------------------- | ---------------------------------------------------- | ----------------------------------- | ---------------------------------- | ------------------------------------------------------- |
+| API key                                  | CES / encrypted file store                           | Encrypted binary                    | CES API / `secure-keys.ts`         | Permanent                                               |
+| Credential secrets                       | CES / encrypted file store                           | Encrypted binary                    | `secure-keys.ts` wrapper           | Permanent (until deleted via tool)                      |
+| Credential metadata                      | `~/.vellum/workspace/data/credentials/metadata.json` | JSON                                | Atomic file write                  | Permanent (until deleted via tool)                      |
+| Integration OAuth tokens                 | CES / encrypted file store (via `secure-keys.ts`)    | Encrypted binary                    | `TokenManager` auto-refresh        | Until disconnected or revoked                           |
+| User preferences                         | UserDefaults                                         | plist                               | Foundation                         | Permanent                                               |
+| Session logs                             | `~/Library/.../logs/session-*.json`                  | JSON per session                    | Swift Codable                      | Unbounded                                               |
+| Conversations & messages                 | `~/.vellum/workspace/data/db/assistant.db`           | SQLite + WAL                        | Drizzle ORM (Bun)                  | Permanent                                               |
+| Memory segments                          | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent                                               |
+| Extracted facts                          | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent, deduped                                      |
+| Embeddings                               | `~/.vellum/workspace/data/db/assistant.db`           | JSON float arrays                   | Drizzle ORM                        | Permanent                                               |
+| Async job queue                          | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Completed jobs persist                                  |
+| Attachments                              | `~/.vellum/workspace/data/db/assistant.db`           | Base64 in SQLite                    | Drizzle ORM                        | Permanent                                               |
+| Sandbox filesystem                       | `~/.vellum/workspace`                                | Real filesystem tree                | Node FS APIs                       | Persistent across sessions                              |
+| Tool permission rules                    | `~/.vellum/protected/trust.json`                     | JSON                                | File I/O                           | Permanent                                               |
+| Web users & assistants                   | PostgreSQL                                           | Relational                          | Drizzle ORM (pg)                   | Permanent                                               |
+| Trace events                             | In-memory (TraceStore)                               | Structured events                   | Swift ObservableObject             | Max 5,000 per session, ephemeral                        |
+| Media embed settings                     | `~/.vellum/workspace/config.json` (`ui.mediaEmbeds`) | JSON                                | `WorkspaceConfigIO` (atomic merge) | Permanent                                               |
+| Media embed MIME cache                   | In-memory (`ImageMIMEProbe`)                         | `NSCache` (500 entries)             | HTTP HEAD                          | Ephemeral; cleared on app restart                       |
+| Tasks & task runs                        | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent                                               |
+| Work items (Task Queue)                  | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; archived items retained                      |
+| Recurrence schedules & runs              | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; supports cron and RRULE syntax               |
+| Watchers & events                        | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent, cascade on watcher delete                    |
+| Proxy CA cert + key                      | `{dataDir}/proxy-ca/`                                | PEM files (ca.pem, ca-key.pem)      | openssl CLI                        | Permanent (10-year validity)                            |
+| Proxy leaf certs                         | `{dataDir}/proxy-ca/issued/`                         | PEM files per hostname              | openssl CLI, cached                | 1-year validity, re-issued on CA change                 |
+| Proxy sessions                           | In-memory (SessionManager)                           | Map<ProxySessionId, ManagedSession> | Manual lifecycle                   | Ephemeral; 5min idle timeout, cleared on shutdown       |
+| Call sessions, events, pending questions | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent, cascade on session delete                    |
+| Active call controllers                  | In-memory (CallState)                                | Map<callSessionId, CallController>  | Manual lifecycle                   | Ephemeral; cleared on call end or destroy               |
+| Guardian bindings                        | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; revoked bindings retained                    |
+| Channel verification sessions            | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; consumed/expired sessions retained           |
+| Guardian approval requests               | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; decision outcome retained                    |
+| Contact invites                          | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; token hash stored, raw token never persisted |
+| Contacts & channels                      | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; revoked/blocked contacts retained            |
+| Notification events                      | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; deduplicated by dedupeKey                    |
+| Notification decisions                   | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; FK to notification_events                    |
+| Notification deliveries                  | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; FK to notification_decisions                 |
+| Notification preferences                 | `~/.vellum/workspace/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent; per-assistant conversational preferences     |
 
 ### Sensitive Tool Output Placeholder Substitution
 

package/Dockerfile

@@ -52,6 +52,8 @@ RUN apt-get update && apt-get install -y \
     sudo \
     htop \
     procps \
+    jq \
+    uuid-runtime \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy bun binary from builder instead of re-installing

package/README.md

@@ -204,7 +204,7 @@ The runtime exposes a RESTful HTTP API for Twilio configuration, credential mana
 | Method | Path                                        | Description                                                                                                                                 |
 | ------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | GET    | `/v1/integrations/twilio/config`            | Returns current state: `hasCredentials` (boolean) and `phoneNumber` (if assigned)                                                           |
-| POST   | `/v1/integrations/twilio/credentials`       | Validates and stores Account SID and Auth Token in secure storage (Keychain / encrypted file)                                               |
+| POST   | `/v1/integrations/twilio/credentials`       | Validates and stores Account SID and Auth Token in secure storage (CES / encrypted file store)                                               |
 | DELETE | `/v1/integrations/twilio/credentials`       | Removes stored credentials. Preserves the phone number in config so re-entering credentials resumes working without reassigning the number. |
 | GET    | `/v1/integrations/twilio/numbers`           | Lists all incoming phone numbers on the Twilio account with their capabilities                                                              |
 | POST   | `/v1/integrations/twilio/numbers/provision` | Purchases a new phone number. Accepts optional `areaCode` and `country`. Auto-assigns and configures webhooks when ingress is available.    |

package/docs/architecture/integrations.md

@@ -50,14 +50,7 @@ graph TB
 
     subgraph "Slack Skill (bundled-skills/slack/)"
         SLACK_SKILL_MD["SKILL.md<br/>agent instructions"]
-        SLACK_SCAN["slack_scan_digest"]
-        SLACK_DETAILS["slack_channel_details"]
-        SLACK_CONFIGURE["slack_configure_channels"]
-        SLACK_REACT["slack_add_reaction"]
-        SLACK_DELETE["slack_delete_message"]
-        SLACK_EDIT["slack_edit_message"]
-        SLACK_LEAVE["slack_leave_channel"]
-        SLACK_PERMS["slack_channel_permissions"]
+        SLACK_WEB_API["Web API via bash<br/>(network_mode: proxied)"]
     end
 
     subgraph "Sequences Skill (bundled-skills/sequences/)"
@@ -107,7 +100,7 @@ graph TB
     SEND --> SHARED
     STYLE --> STYLE_ANALYZER
     GMAIL_ARCHIVE --> GMAIL_ADAPTER
-    SLACK_REACT --> SLACK_ADAPTER
+    SLACK_WEB_API --> SLACK_API
 ```
 
 ### Data Flow
@@ -122,7 +115,7 @@ sequenceDiagram
     participant Browser as System Browser
     participant Google as Google OAuth Server
     participant Store as SQLite OAuth Store
-    participant Vault as Secure Keychain
+    participant Vault as Credential Store
     participant TokenMgr as TokenManager
     participant Tool as Gmail Tool Executor
     participant API as Gmail REST API
@@ -173,7 +166,7 @@ sequenceDiagram
 
 | Decision                                   | Rationale                                                                                                                                                                                                                                        |
 | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 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                                                                                |
+| PKCE by default, optional client_secret    | Desktop apps prefer PKCE; some providers (Slack) require a secret, which is stored in the credential store (`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.                                |
@@ -261,7 +254,7 @@ Result is a discriminated union: `{ success, deferred, grantedScopes, accountInf
 
 `assistant/src/daemon/handlers/oauth-connect.ts` handles `oauth_connect_start` messages. The handler:
 
-1. Resolves client credentials from the keychain using canonical names (`client_id`, `client_secret`).
+1. Resolves client credentials from the credential store using canonical names (`client_id`, `client_secret`).
 2. Validates that required credentials exist (including `client_secret` when the provider requires it).
 3. Delegates to `orchestrateOAuthConnect()`.
 4. Sends `oauth_connect_result` back to the client.
@@ -286,7 +279,7 @@ This replaces provider-specific handlers — any provider in the registry can be
 | `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/oauth/token-persistence.ts`       | Token storage: credential store writes, metadata upsert, post-connect hooks      |
 | `assistant/src/daemon/handlers/oauth-connect.ts` | Generic `oauth_connect_start` / `oauth_connect_result` handler                   |
 
 ---

package/docs/architecture/memory.md

@@ -154,7 +154,6 @@ graph TB
         BUDGET["Dynamic Recall Budget<br/>computeRecallBudget()<br/>from prompt headroom"]
         EMBED_Q["Generate dense + sparse<br/>query embeddings"]
         HYBRID["Hybrid Search<br/>dense + sparse RRF on Qdrant"]
-        RECENCY["Recency Search<br/>conversation-scoped, DB only"]
         MERGE["Merge + Deduplicate<br/>weighted score combination"]
         SCOPE["Scope Filter<br/>scope_id filtering<br/>(strict | global_fallback)<br/>Private conversations: own scope + 'default'"]
         TIER["Tier Classification<br/>score > 0.8 → tier 1<br/>score > 0.6 → tier 2<br/>below → dropped"]
@@ -218,9 +217,7 @@ graph TB
     EMBED_Q --> SPARSE_GEN
     EMBED_Q --> HYBRID
     HYBRID --> RRF
-    QUERY --> RECENCY
     HYBRID --> SCOPE
-    RECENCY --> SCOPE
     SCOPE --> MERGE
     MERGE --> TIER
     TIER --> STALE
@@ -337,24 +334,22 @@ The recall pipeline runs on every turn that passes the `needsMemory` gate (skips
 
 3. **Hybrid search on Qdrant**: When both dense and sparse vectors are available, the pipeline uses Qdrant's query API with two prefetch stages (dense and sparse, each fetching up to 40 candidates) fused via Reciprocal Rank Fusion (RRF). Falls back to dense-only search when sparse vectors are unavailable.
 
-4. **Recency supplement**: A DB-only recency search fetches the 5 most recent segments from the current conversation, providing conversation-local context even when vector search misses.
+4. **Merge and deduplicate**: Hybrid candidates are deduplicated by key. A weighted final score is computed: `0.4 + importance * 0.25 + confidence * 0.15 + recency * 0.2`, where `recency` is a logarithmic time-decay score (ACT-R inspired) based on when the item was last seen.
 
-5. **Merge and deduplicate**: Hybrid and recency candidates are merged by key. Duplicate entries keep the highest scores from each source. A weighted final score is computed: `semantic * 0.7 + recency * 0.2 + confidence * 0.1`.
-
-6. **Tier classification** (`tier-classifier.ts`): Score-based, deterministic classification:
+5. **Tier classification** (`tier-classifier.ts`): Score-based, deterministic classification:
    - `finalScore > 0.8` → **tier 1** (high relevance)
    - `finalScore > 0.6` → **tier 2** (possibly relevant)
    - Below 0.6 → dropped
 
-7. **Staleness computation** (`staleness.ts`): Each item candidate is annotated with a staleness level based on its age relative to a kind-specific base lifetime (see table above). The effective lifetime is extended by a reinforcement factor: `baseLifetime * (1 + 0.3 * (sourceConversationCount - 1))`, so items mentioned across multiple conversations age more slowly. Staleness levels:
+6. **Staleness computation** (`staleness.ts`): Each item candidate is annotated with a staleness level based on its age relative to a kind-specific base lifetime (see table above). The effective lifetime is extended by a reinforcement factor: `baseLifetime * (1 + 0.3 * (sourceConversationCount - 1))`, so items mentioned across multiple conversations age more slowly. Staleness levels:
    - `ratio < 0.5` → `fresh`
    - `ratio <= 1.0` → `aging`
    - `ratio <= 2.0` → `stale`
    - `ratio > 2.0` → `very_stale`
 
-8. **Stale demotion**: `very_stale` tier 1 candidates are demoted to tier 2, preventing old information from occupying prime injection space.
+7. **Stale demotion**: `very_stale` tier 1 candidates are demoted to tier 2, preventing old information from occupying prime injection space.
 
-9. **Two-layer XML injection** (`formatting.ts`): Budget-aware rendering into four XML sections:
+8. **Two-layer XML injection** (`formatting.ts`): Budget-aware rendering into four XML sections:
 
    ```xml
    <memory_context __injected>
@@ -380,7 +375,7 @@ The recall pipeline runs on every turn that passes the `needsMemory` gate (skips
 
    Empty sections are omitted. Each section has a per-item token budget (150 tokens for tier 1, 100 for tier 2). Tier 1 sections consume budget first; tier 2 uses the remainder.
 
-10. **Injection strategy**: The rendered `<memory_context __injected>` block is prepended as a text content block to the last user message (`injectMemoryRecallAsUserBlock`), following the same pattern as workspace, temporal, and other runtime injections. Stripping is handled by the generic `stripUserTextBlocksByPrefix` mechanism matching the `<memory_context __injected>` prefix (with a backward-compat entry for the legacy `<memory_context>` prefix from older history). This avoids synthetic message pairs and preserves prompt prefix caching between turns.
+9. **Injection strategy**: The rendered `<memory_context __injected>` block is prepended as a text content block to the last user message (`injectMemoryRecallAsUserBlock`), following the same pattern as workspace, temporal, and other runtime injections. Stripping is handled by the generic `stripUserTextBlocksByPrefix` mechanism matching the `<memory_context __injected>` prefix (with a backward-compat entry for the legacy `<memory_context>` prefix from older history). This avoids synthetic message pairs and preserves prompt prefix caching between turns.
 
 ### Internal-Only Trust Gating
 
@@ -412,7 +407,7 @@ When the embedding backend or Qdrant is unavailable:
 
 - A **circuit breaker** on Qdrant (`qdrant-circuit-breaker.ts`) tracks consecutive failures and short-circuits search calls when the breaker is open.
 - If embedding generation fails and `memory.embeddings.required` is `true`, recall returns an empty result with a degradation status (`embedding_generation_failed` or `embedding_provider_down`).
-- If embeddings are optional (default), the pipeline falls back to recency-only search.
+- If embeddings are optional (default), the pipeline returns empty results (no fallback search path exists without Qdrant).
 - Degradation status is reported to clients via `memory_status` events.
 
 ---

package/docs/architecture/security.md

@@ -222,7 +222,7 @@ sequenceDiagram
     participant Prompter as SecretPrompter
     participant HTTP as HTTP Transport
     participant UI as SecretPromptManager (Swift)
-    participant Keychain as macOS Keychain
+    participant Store as Credential Store (CES / encrypted file)
 
     Model->>Vault: action: "prompt", service, field, label
     Vault->>Prompter: requestSecret(service, field, label, ...)
@@ -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: setSecureKeyAsync("credential/svc/field", value)
+        Vault->>Store: setSecureKeyAsync("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"}
@@ -265,7 +265,7 @@ graph TB
 The `allowOneTimeSend` config gate (default: `false`) enables a secondary "Send Once" button in the secret prompt UI. When used:
 
 - The secret value is handed to the `CredentialBroker`, which holds it in memory for the next `consume` or `browserFill` call
-- The value is **not** persisted to the keychain
+- The value is **not** persisted to the credential store
 - The broker discards the value after a single use
 - The vault tool output confirms delivery without including the secret value — the value is never returned to the model
 - The config gate must be explicitly enabled by the operator
@@ -274,7 +274,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       | CES credential store or encrypted file store         | Encrypted credential values keyed as `credential/{service}/{field}`. Stored via CES RPC (primary), CES HTTP (containerized), or encrypted file store (fallback). |
 | 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                                                                              |
 
@@ -283,7 +283,7 @@ The `allowOneTimeSend` config gate (default: `false`) enables a secondary "Send
 | File                                                 | Role                                                                  |
 | ---------------------------------------------------- | --------------------------------------------------------------------- |
 | `assistant/src/tools/credentials/vault.ts`           | `credential_store` tool — store, list, delete, prompt actions         |
-| `assistant/src/security/secure-keys.ts`              | Async secure key CRUD via keychain broker and encrypted file store    |
+| `assistant/src/security/secure-keys.ts`              | Async secure key CRUD via CES and encrypted file store               |
 | `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)                |

package/docs/credential-execution-service.md

@@ -56,7 +56,7 @@ CES tools use the standard `class ... implements Tool` registration pattern. The
 
 ### 1. `host_bash` is outside the strong secrecy guarantee
 
-The existing `host_bash` tool executes commands on the host machine without any credential isolation. When an agent uses `host_bash`, it has full access to the host environment, including any credentials stored in environment variables, config files, or keychains accessible to the user. CES does not attempt to intercept or sandbox `host_bash` invocations.
+The existing `host_bash` tool executes commands on the host machine without any credential isolation. When an agent uses `host_bash`, it has full access to the host environment, including any credentials stored in environment variables, config files, or credential stores accessible to the user. CES does not attempt to intercept or sandbox `host_bash` invocations.
 
 **Implication**: `host_bash` represents a weaker security tier. Agents that require the strong secrecy guarantee must use `run_authenticated_command` instead. Trust rules and permission policies should reflect this distinction — managed deployments may deny `host_bash` entirely for untrusted agents while allowing `run_authenticated_command`.
 
@@ -237,13 +237,13 @@ CES is rolled out incrementally via feature flags, all defaulting to `false` (of
 
 Enable flags in this order. Each flag is safe to enable independently, but later flags depend on earlier ones being on for meaningful behavior.
 
-| Order | Flag                                        | Gate                                                                                                                                                | Safe to enable alone?                                                                                                           |
-| ----- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| 1     | `feature_flags.ces-tools.enabled`           | Register CES tools (`run_authenticated_command`, `make_authenticated_request`, `manage_secure_command_tool`) in the agent loop                      | Yes — tools register but are not invoked unless the agent discovers credentials that require CES                                |
-| 2     | `feature_flags.ces-shell-lockdown.enabled`  | Enforce shell lockdown for untrusted agents with CES-active credentials; direct shell access to credentialed services is denied                     | Yes — only activates when CES credentials are present                                                                           |
-| 3     | `feature_flags.ces-secure-install.enabled`  | Route tool/command installation through CES secure bundle pipeline instead of direct shell                                                          | Yes — falls back to standard install if CES is unavailable                                                                      |
-| 4     | `feature_flags.ces-grant-audit.enabled`     | Gate CLI execution of grant listing, grant revocation, and audit inspection commands (commands are always registered but check the flag at runtime) | Yes — read-only inspection surfaces                                                                                             |
-| 5     | `feature_flags.ces-managed-sidecar.enabled` | Use managed sidecar transport (Unix socket) instead of local child-process transport                                                                | **No** — requires the CES sidecar container to be present in the pod template. Only enable after the sidecar image is deployed. |
+| Order | Flag                  | Gate                                                                                                                                                | Safe to enable alone?                                                                                                           |
+| ----- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| 1     | `ces-tools`           | Register CES tools (`run_authenticated_command`, `make_authenticated_request`, `manage_secure_command_tool`) in the agent loop                      | Yes — tools register but are not invoked unless the agent discovers credentials that require CES                                |
+| 2     | `ces-shell-lockdown`  | Enforce shell lockdown for untrusted agents with CES-active credentials; direct shell access to credentialed services is denied                     | Yes — only activates when CES credentials are present                                                                           |
+| 3     | `ces-secure-install`  | Route tool/command installation through CES secure bundle pipeline instead of direct shell                                                          | Yes — falls back to standard install if CES is unavailable                                                                      |
+| 4     | `ces-grant-audit`     | Gate CLI execution of grant listing, grant revocation, and audit inspection commands (commands are always registered but check the flag at runtime) | Yes — read-only inspection surfaces                                                                                             |
+| 5     | `ces-managed-sidecar` | Use managed sidecar transport (Unix socket) instead of local child-process transport                                                                | **No** — requires the CES sidecar container to be present in the pod template. Only enable after the sidecar image is deployed. |
 
 ### Dark-launching the managed sidecar
 
@@ -325,7 +325,7 @@ Risks that are acknowledged and accepted for v1, documented here so they are exp
 
 ### 1. `host_bash` is a weaker security tier
 
-`host_bash` executes commands on the host machine with full access to the host environment. CES does not intercept or sandbox `host_bash` invocations. An untrusted agent with `host_bash` access can read credentials from environment variables, config files, or keychains.
+`host_bash` executes commands on the host machine with full access to the host environment. CES does not intercept or sandbox `host_bash` invocations. An untrusted agent with `host_bash` access can read credentials from environment variables, config files, or credential stores.
 
 **Mitigation**: Trust rules and permission policies should deny `host_bash` for untrusted agents in managed deployments. This is a policy enforcement, not a technical guarantee. The CES process-boundary isolation only protects operations routed through CES tools.
 

package/docs/skills.md

@@ -198,7 +198,7 @@ Malformed tokens do not silently pass through — they are collected as errors a
 
 ### Feature flag
 
-Inline command expansion is gated by the `inline-skill-commands` feature flag (key: `feature_flags.inline-skill-commands.enabled`). The flag defaults to **enabled**.
+Inline command expansion is gated by the `inline-skill-commands` feature flag (key: `inline-skill-commands`). The flag defaults to **enabled**.
 
 When the flag is disabled and a skill contains inline command expansion tokens, `skill_load` returns an error rather than delivering unexpanded tokens to the model. This fail-closed behavior prevents the LLM from seeing raw expansion tokens and attempting to interpret them.
 

package/node_modules/@vellumai/credential-storage/src/index.ts

@@ -73,8 +73,8 @@ export interface InjectionTemplate {
 export type SecureKeyDeleteResult = "deleted" | "not-found" | "error";
 
 /**
- * Abstraction over the underlying secure-key backend (e.g. macOS Keychain,
- * encrypted file store). Implementations handle platform-specific details.
+ * Abstraction over the underlying secure-key backend (e.g. encrypted file
+ * store). Implementations handle platform-specific details.
  */
 export interface SecureKeyBackend {
   /** Retrieve a secret value by key. Returns undefined if not found. */

package/node_modules/@vellumai/credential-storage/src/static-credentials.ts

@@ -233,7 +233,7 @@ export class StaticCredentialMetadataStore {
 
   /**
    * Throws if the metadata file has an unrecognized version.
-   * Call this before performing irreversible keychain operations
+   * Call this before performing irreversible credential store operations
    * so the operation fails cleanly before any side effects.
    */
   assertWritable(): void {