@vellumai/assistant 0.6.6 → 0.7.0

package/docs/architecture/memory.md

@@ -155,7 +155,7 @@ graph TB
         EMBED_Q["Generate dense + sparse<br/>query embeddings"]
         HYBRID["Hybrid Search<br/>dense + sparse RRF on Qdrant"]
         MERGE["Merge + Deduplicate<br/>weighted score combination"]
-        SCOPE["Scope Filter<br/>scope_id filtering<br/>(strict | global_fallback)<br/>Private conversations: own scope + 'default'"]
+        SCOPE["Scope Filter<br/>scope_id filtering<br/>(strict | global_fallback)<br/>Subagents: own scope + 'default'"]
         TIER["Tier Classification<br/>score > 0.8 → tier 1<br/>score > 0.6 → tier 2<br/>below → dropped"]
         STALE["Staleness Computation<br/>kind-specific lifetimes<br/>+ reinforcement from<br/>source conversation count"]
         DEMOTE["Stale Demotion<br/>very_stale tier 1 → tier 2"]
@@ -407,95 +407,6 @@ When the embedding backend or Qdrant is unavailable:
 
 ---
 
-## Private Conversations — Isolated Memory and Strict Side-Effect Controls
-
-Private conversations provide per-conversation memory isolation and stricter tool execution controls. When a conversation is created with `conversationType: 'private'`, the daemon assigns it a unique memory scope and enforces additional safeguards to prevent unintended side effects.
-
-### Schema Columns
-
-Two columns on the `conversations` table drive the feature:
-
-| Column              | Type                               | Values                                                                               | Purpose                                                                                                                        |
-| ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
-| `conversation_type` | `text NOT NULL DEFAULT 'standard'` | `'standard'` or `'private'`                                                          | Determines whether the conversation uses shared or isolated memory and permission policies                                     |
-| `memory_scope_id`   | `text NOT NULL DEFAULT 'default'`  | `'default'` for standard conversations; `'private:<uuid>'` for private conversations | Scopes all memory writes (items, segments) to this namespace; embeddings are isolated indirectly via their parent item/segment |
-
-### Memory Isolation
-
-```mermaid
-graph TB
-    subgraph "Standard Conversation"
-        STD_WRITE["Memory writes<br/>→ scope_id = 'default'"]
-        STD_READ["Memory recall<br/>reads scope_id = 'default' only"]
-    end
-
-    subgraph "Private Conversation"
-        PVT_WRITE["Memory writes<br/>→ scope_id = 'private:&lt;uuid&gt;'"]
-        PVT_READ["Memory recall<br/>reads scope_id = 'private:&lt;uuid&gt;'<br/>+ fallback to 'default'"]
-    end
-
-    subgraph "Shared Memory Pool"
-        DEFAULT_SCOPE["'default' scope<br/>(all standard conversation memories)"]
-        PRIVATE_SCOPE["'private:&lt;uuid&gt;' scope<br/>(isolated to one conversation)"]
-    end
-
-    STD_WRITE --> DEFAULT_SCOPE
-    STD_READ --> DEFAULT_SCOPE
-    PVT_WRITE --> PRIVATE_SCOPE
-    PVT_READ --> PRIVATE_SCOPE
-    PVT_READ -.->|"fallback"| DEFAULT_SCOPE
-```
-
-**Write isolation**: All memory items and segments created during a private conversation are tagged with its `memory_scope_id` (e.g. `'private:abc123'`). Embeddings are isolated indirectly — they reference scoped items/segments via `target_type`/`target_id`, so scope filtering at the item/segment level cascades to their embeddings. All scoped data is invisible to standard conversations and other private conversations.
-
-**Read fallback**: When recalling memories for a private conversation, the retriever queries both the conversation's own scope and the `'default'` scope. This ensures the assistant still has access to general knowledge (user profile, preferences, facts) learned in standard conversations, while private-conversation-specific memories take precedence in ranking. The fallback is implemented via `ScopePolicyOverride` with `fallbackToDefault: true`, which overrides the global scope policy on a per-call basis.
-
-### SessionMemoryPolicy
-
-The daemon derives a `SessionMemoryPolicy` from the conversation's `conversation_type` and `memory_scope_id` when creating or restoring a session:
-
-```typescript
-interface SessionMemoryPolicy {
-  scopeId: string; // 'default' or 'private:<uuid>'
-  includeDefaultFallback: boolean; // true for private conversations
-  strictSideEffects: boolean; // true for private conversations
-}
-```
-
-Standard conversations use `DEFAULT_MEMORY_POLICY` (`{ scopeId: 'default', includeDefaultFallback: false, strictSideEffects: false }`). Private conversations set all three fields: the private scope ID, default-fallback enabled, and strict side-effect controls enabled.
-
-### Strict Side-Effect Prompt Gate
-
-When `strictSideEffects` is `true` (all private conversations), the `ToolExecutor` promotes any `allow` permission decision to `prompt` for side-effect tools — even when a trust rule would normally auto-allow the invocation. Deny decisions are preserved unchanged; only `allow` -> `prompt` promotion occurs.
-
-```mermaid
-graph TB
-    TOOL["Tool invocation in<br/>private conversation"] --> PERM["Normal permission check<br/>(trust rules + risk level)"]
-    PERM --> DECISION{"Decision?"}
-    DECISION -->|"deny"| DENY["Blocked<br/>(unchanged)"]
-    DECISION -->|"prompt"| PROMPT["Prompt user<br/>(unchanged)"]
-    DECISION -->|"allow"| SIDE_CHECK{"isSideEffectTool()?"}
-    SIDE_CHECK -->|"no"| ALLOW["Auto-allow<br/>(read-only tools pass)"]
-    SIDE_CHECK -->|"yes"| FORCE_PROMPT["Promote to prompt<br/>'Private conversation: side-effect<br/>tools require explicit approval'"]
-```
-
-This ensures that file writes, bash commands, host operations, and other mutating tools always require explicit user confirmation in private conversations, providing an additional safety layer for sensitive conversations.
-
-### Key Source Files
-
-| File                                              | Role                                                                                       |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `assistant/src/memory/schema.ts`                  | `conversations` table: `conversationType` and `memoryScopeId` column definitions           |
-| `assistant/src/daemon/conversation.ts`            | `SessionMemoryPolicy` interface and `DEFAULT_MEMORY_POLICY` constant                       |
-| `assistant/src/daemon/server.ts`                  | `deriveMemoryPolicy()` — maps conversation type to memory policy                           |
-| `assistant/src/daemon/conversation-tool-setup.ts` | Propagates `memoryPolicy.strictSideEffects` as `forcePromptSideEffects` into `ToolContext` |
-| `assistant/src/tools/executor.ts`                 | `forcePromptSideEffects` gate — promotes allow to prompt for side-effect tools             |
-| `assistant/src/memory/search/types.ts`            | `ScopePolicyOverride` interface for per-call scope control                                 |
-| `assistant/src/memory/retriever.ts`               | `buildScopeFilter()` — builds scope ID list from override or global config                 |
-| `assistant/src/daemon/conversation-memory.ts`     | Wires `scopeId` and `includeDefaultFallback` into recall                                   |
-
----
-
 ## Workspace Context Injection — Directory Awareness
 
 The session injects a `<workspace>` directory listing into the first user message and after compaction, giving the model awareness of the sandbox filesystem structure. The block persists in conversation history (old-format `<workspace_top_level>` blocks from pre-change history are stripped for backward compatibility).

package/docs/architecture/security.md

@@ -26,39 +26,26 @@ graph TB
     RISK_CHECK -->|"High"| RISK_THRESHOLD{"Risk-based<br/>threshold fallback"}
 
     NO_MATCH -->|"tool.origin === 'skill'"| PROMPT_SKILL["decision: prompt<br/>Skill tools always ask"]
-    NO_MATCH -->|"strict mode"| PROMPT_STRICT["decision: prompt<br/>No implicit auto-allow"]
-    NO_MATCH -->|"workspace mode (default)"| WS_CHECK{"Workspace-scoped<br/>+ Low risk?"}
-    WS_CHECK -->|"yes"| AUTO_WS["decision: allow<br/>Workspace-scoped auto-allow"]
-    WS_CHECK -->|"no"| RISK_THRESHOLD
+    NO_MATCH -->|"workspace-scoped<br/>+ Low risk"| AUTO_WS["decision: allow<br/>Workspace-scoped auto-allow"]
+    NO_MATCH -->|"otherwise"| RISK_THRESHOLD
 
     RISK_THRESHOLD{"risk ≤ autoApproveUpTo<br/>threshold?"}
     RISK_THRESHOLD -->|"yes"| AUTO_THRESHOLD["decision: allow<br/>within auto-approve threshold"]
     RISK_THRESHOLD -->|"no"| PROMPT_THRESHOLD["decision: prompt<br/>above auto-approve threshold"]
 ```
 
-### Permission Modes: Workspace and Strict
+### Auto-Approve Threshold
 
-The `permissions.mode` config option (`workspace` or `strict`) controls the default behavior when no trust rule matches a tool invocation. The default is `workspace`.
+Auto-approve thresholds are **gateway-owned** — they live in the gateway's SQLite database and are read by the assistant via IPC (`get_global_thresholds`, `get_conversation_threshold`). Users control thresholds via the **Settings UI** (Permissions & Privacy tab) or the **per-conversation risk tolerance picker**. When the gateway is unreachable, the assistant defaults to `"none"` (Strict) — fail-closed with no local fallback.
 
-| Behavior                                           | Workspace mode (default)                      | Strict mode                                   |
-| -------------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
-| Workspace-scoped ops with no matching rule         | Auto-allowed                                  | Prompted                                      |
-| Non-workspace low-risk tools with no matching rule | Auto-allowed                                  | Prompted                                      |
-| Medium-risk tools with no matching rule            | Prompted                                      | Prompted                                      |
-| High-risk tools with no matching rule              | Prompted                                      | Prompted                                      |
-| `skill_load` with no matching rule                 | Prompted                                      | Prompted                                      |
-| `skill_load` with system default rule              | Auto-allowed (`skill_load:*` at priority 100) | Auto-allowed (`skill_load:*` at priority 100) |
-| `browser_*` skill tools with system default rules  | Auto-allowed (priority 100 allow rules)       | Auto-allowed (priority 100 allow rules)       |
-| Skill-origin tools with no matching rule           | Prompted                                      | Prompted                                      |
-| Allow rules for non-high-risk tools                | Auto-allowed                                  | Auto-allowed                                  |
-| Allow rules + containerized bash (high risk)       | Auto-allowed (runtime check)                  | Auto-allowed (runtime check)                  |
-| Deny rules                                         | Blocked                                       | Blocked                                       |
+| `autoApproveUpTo` | Low-risk tools | Medium-risk tools | High-risk tools |
+| ------------------ | -------------- | ----------------- | --------------- |
+| `"none"`           | Prompted       | Prompted          | Prompted        |
+| `"low"` (default)  | Auto-allowed   | Prompted          | Prompted        |
+| `"medium"`         | Auto-allowed   | Auto-allowed      | Prompted        |
+| `"high"`           | Auto-allowed   | Auto-allowed      | Auto-allowed    |
 
-**Workspace mode** (default) auto-allows operations scoped to the workspace (file reads/writes/edits within the workspace directory, sandboxed bash) without prompting. Host operations, network requests, and operations outside the workspace still follow the normal approval flow. Explicit deny and ask rules override auto-allow.
-
-**Strict mode** is designed for security-conscious deployments where every tool action must have an explicit matching rule in the trust store. It eliminates implicit auto-allow for any risk level, ensuring the user has consciously approved each class of tool usage.
-
-> **Migration note:** Existing config files with `permissions.mode = "legacy"` are automatically migrated to `workspace` during config loading. The `legacy` value is not a supported steady-state mode.
+When set to `"none"`, every tool invocation requires explicit approval. Explicit deny and ask rules always take precedence over the threshold.
 
 ### Trust Rules (v3 Schema)
 
@@ -101,11 +88,11 @@ The `skill_load` tool generates version-aware command candidates for rule matchi
 2. `skill_load:<skill-id>` — matches any-version rules
 3. `skill_load:<raw-selector>` — matches the raw user-provided selector
 
-In strict mode, `skill_load` without a matching rule is always prompted. The allowlist options presented to the user include both version-specific and any-version patterns. Note: the system default allow rule `skill_load:*` (priority 100) now globally allows all skill loads in both modes (see "System Default Allow Rules" below).
+When `autoApproveUpTo` is `"none"`, `skill_load` without a matching rule is always prompted. The allowlist options presented to the user include both version-specific and any-version patterns. Note: the system default allow rule `skill_load:*` (priority 100) globally allows all skill loads regardless of threshold (see "System Default Allow Rules" below).
 
 ### Starter Approval Bundle
 
-The starter bundle is an opt-in set of low-risk allow rules that reduces prompt noise, particularly in strict mode. It covers read-only tools that never mutate the filesystem or execute arbitrary code:
+The starter bundle is an opt-in set of low-risk allow rules that reduces prompt noise, particularly when `autoApproveUpTo` is `"none"`. It covers read-only tools that never mutate the filesystem or execute arbitrary code:
 
 | Rule             | Tool             | Pattern             |
 | ---------------- | ---------------- | ------------------- |
@@ -136,7 +123,7 @@ In addition to the opt-in starter bundle, the permission system seeds unconditio
 | `default:allow-browser_extract-global`         | `browser_extract`         | `browser_extract:*`         | (same)                                                                                                   |
 | `default:allow-browser_fill_credential-global` | `browser_fill_credential` | `browser_fill_credential:*` | (same)                                                                                                   |
 
-These rules are emitted by `getDefaultRuleTemplates()` in `assistant/src/permissions/defaults.ts`. Because they use priority 100 (equal to user rules), they take effect in both workspace and strict modes. The `skill_load` rule means skill activation never prompts; the `browser_*` rules mean the browser skill's tools behave identically to the old core `headless-browser` tool from a permission standpoint.
+These rules are emitted by `getDefaultRuleTemplates()` in `assistant/src/permissions/defaults.ts`. Because they use priority 100 (equal to user rules), they take effect regardless of the `autoApproveUpTo` threshold. The `skill_load` rule means skill activation never prompts; the `browser_*` rules mean the browser skill's tools behave identically to the old core `headless-browser` tool from a permission standpoint.
 
 ### Shell Command Identity and Allowlist Options
 
@@ -184,7 +171,6 @@ File tool candidates include canonical (symlink-resolved) absolute paths via `no
 | `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                                                                                                                  |
-| `assistant/src/config/schema.ts`              | `PermissionsConfigSchema` — `permissions.mode` (`workspace` / `strict`)                                                                                                             |
 | `assistant/src/tools/executor.ts`             | `ToolExecutor` — orchestrates risk classification, permission check, and execution                                                                                                  |
 | `assistant/src/daemon/handlers/config.ts`     | `handleToolPermissionSimulate()` — dry-run simulation handler                                                                                                                       |
 
@@ -194,11 +180,10 @@ The `tool_permission_simulate` HTTP endpoint lets clients dry-run a tool invocat
 
 **Simulation semantics:**
 
-- The request specifies `toolName`, `input`, and optional context overrides (`workingDir`, `isInteractive`, `forcePromptSideEffects`, `executionTarget`).
+- The request specifies `toolName`, `input`, and optional context overrides (`workingDir`, `isInteractive`).
 - The daemon runs `classifyRisk()` and `check()` against the live trust rules, then returns the decision (`allow`, `deny`, or `prompt`), risk level, reason, matched rule ID, and (when decision is `prompt`) the full `promptPayload` with allowlist/scope options.
 - **Simulation-only allow/deny**: A simulated `allow` or `deny` decision does not persist any state. No trust rules are created or modified.
 - **Always-allow persistence**: When the tester UI's "Always Allow" action is used, the client sends a separate `add_trust_rule` message that persists the rule to `trust.json`, identical to the existing confirmation flow.
-- **Private-conversation override**: When `forcePromptSideEffects` is true, side-effect tools that would normally be auto-allowed are promoted to `prompt`.
 - **Non-interactive override**: When `isInteractive` is false, `prompt` decisions are converted to `deny` (no client available to approve).
 
 ---

package/docs/credential-execution-service.md

@@ -172,14 +172,16 @@ Audit logs record every materialization event with: grant ID, credential ID, too
 
 CES and the assistant share contract definitions and credential-storage abstractions through three private packages in `packages/`:
 
-| Package                        | Purpose                                                                                                                   | Consumers                            |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| `@vellumai/ces-contracts`      | RPC protocol types, method names, protocol version constant, grant shapes, credential handle types, and rendering helpers | `assistant/`, `credential-executor/` |
-| `@vellumai/credential-storage` | Credential store read API (static secrets and OAuth runtime), unified credential handle abstraction                       | `assistant/`, `credential-executor/` |
-| `@vellumai/egress-proxy`       | Session-scoped egress proxy lifecycle (create, start, stop, env-var injection)                                            | `assistant/`, `credential-executor/` |
+| Package                          | Purpose                                                                                                                                                                                                                    | Consumers                            |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `@vellumai/service-contracts`    | RPC protocol types, method names, protocol version constant, grant shapes, credential handle types, and rendering helpers. Consumed via explicit domain subpaths (e.g. `@vellumai/service-contracts/credential-rpc`). | `assistant/`, `credential-executor/` |
+| `@vellumai/credential-storage`   | Credential store read API (static secrets and OAuth runtime), unified credential handle abstraction                                                                                                                         | `assistant/`, `credential-executor/` |
+| `@vellumai/egress-proxy`         | Session-scoped egress proxy lifecycle (create, start, stop, env-var injection)                                                                                                                                             | `assistant/`, `credential-executor/` |
 
 These packages are the **only** allowed shared-code path between the assistant and CES. Direct source imports between `assistant/` and `credential-executor/` remain banned. The packages are built locally via `workspace:*` references and copied into the CES Docker image at build time (`COPY packages/ ...` in `credential-executor/Dockerfile`).
 
+New code must import from `@vellumai/service-contracts` using explicit subpaths (e.g. `@vellumai/service-contracts/credential-rpc`, `@vellumai/service-contracts/trust-rules`). The aggregate root import (`@vellumai/service-contracts`) must not be used in `assistant/`, `gateway/`, or `credential-executor/` source — always use explicit domain subpaths.
+
 ## Secure Command Auth Adapters
 
 CES materializes credentials into the command execution environment through pluggable auth adapters. Each adapter type has different security properties:

package/docs/skills.md

@@ -14,7 +14,7 @@ Skill-origin tools follow a stricter default permission policy than core tools:
 
 | Scenario                                          | Core tool behavior            | Skill tool behavior |
 | ------------------------------------------------- | ----------------------------- | ------------------- |
-| Low risk, no matching rule                        | Auto-allowed (workspace mode) | **Prompted**        |
+| Low risk, no matching rule                        | Auto-allowed (at default threshold) | **Prompted**        |
 | Medium risk, no matching rule                     | Prompted                      | Prompted            |
 | High risk, no matching rule                       | Prompted                      | Prompted            |
 | Allow rule matches, non-high risk                 | Auto-allowed                  | Auto-allowed        |
@@ -25,7 +25,7 @@ Even if a skill's `TOOLS.json` declares `"risk": "low"` for one of its tools, th
 
 ## Skill Load Approval
 
-The `skill_load` tool activates a skill within the current session. In **strict mode** (`permissions.mode = 'strict'`), loading a skill requires an explicit matching trust rule. In **workspace mode** (default), `skill_load` is prompted unless a matching trust rule exists.
+The `skill_load` tool activates a skill within the current session. When `autoApproveUpTo` is set to `"none"`, loading a skill requires an explicit matching trust rule. At the default threshold (`"low"`), `skill_load` is prompted unless a matching trust rule exists.
 
 When `skill_load` is invoked, the permission checker generates multiple command candidates for rule matching:
 
@@ -87,11 +87,11 @@ The path classifier resolves symlinks before checking paths against skill root d
 
 The `normalizeFilePath()` function walks up the directory tree to find the nearest existing ancestor, resolves it via `realpathSync`, and re-appends the remaining segments.
 
-## Strict Mode
+## Strict Threshold (`autoApproveUpTo: "none"`)
 
-When `permissions.mode` is set to `strict` in the assistant configuration, **all** tool actions require a matching trust rule. There is no implicit auto-allow for any risk level. This means:
+When the gateway threshold is set to `"none"`, **all** tool actions require a matching trust rule or explicit approval. There is no implicit auto-allow for any risk level. This means:
 
-- Low-risk tools that would normally auto-execute in workspace mode (e.g., `file_read`, `web_search`) will prompt unless a trust rule allows them.
+- Low-risk tools that would normally auto-execute at the default threshold (e.g., `file_read`, `web_search`) will prompt unless a trust rule allows them.
 - `skill_load` requires an explicit rule match, even though it is classified as low risk.
 - The **starter bundle** can be accepted to seed common safe rules and reduce prompt noise.
 
@@ -137,15 +137,15 @@ Writing to skill source paths is classified as high risk because it could alter
 
 **Fix**: If you trust the operation, approve it. To permanently allow it, select "Always allow". Note that high-risk file operations will still prompt for each invocation since runtime auto-allow only applies to containerized bash.
 
-### "Why is strict mode prompting for everything?"
+### "Why is everything prompting?"
 
-Strict mode requires an explicit trust rule for every tool action. There is no implicit auto-allow.
+When `autoApproveUpTo` is set to `"none"`, every tool action requires an explicit trust rule or approval. There is no implicit auto-allow for any risk level.
 
-**Fix**: Accept the starter approval bundle to seed common safe rules. Then approve additional tools as needed — each approval creates a persistent trust rule.
+**Fix**: Accept the starter approval bundle to seed common safe rules. Then approve additional tools as needed — each approval creates a persistent trust rule. Alternatively, raise `autoApproveUpTo` to `"low"` to auto-approve low-risk tools.
 
-### "Why does skill_load prompt in strict mode but not in workspace mode?"
+### "Why does skill_load prompt at some thresholds but not others?"
 
-In workspace mode, `skill_load` may be auto-allowed by system default rules (e.g., `skill_load:*` at priority 100). In strict mode, low-risk auto-allow is disabled, so an explicit rule is needed.
+At the default threshold (`"low"`), `skill_load` may be auto-allowed by system default rules (e.g., `skill_load:*` at priority 100). At `"none"`, low-risk auto-allow is disabled, so an explicit rule is needed.
 
 **Fix**: Create a rule for the specific skill (version-specific or any-version) or accept the starter bundle if it covers your needs.
 

package/docs/stt-provider-onboarding.md

@@ -49,66 +49,38 @@ If the new provider introduces a credential-store key that is not already presen
 
 If the new provider **shares** an existing credential name (e.g. reuses `"openai"`), the deduplication logic in `sttApiKeyProviderNames()` handles it — no changes needed.
 
-## 6. Client catalog entry
+## 6. Client display metadata
 
-**File:** `meta/stt-provider-catalog.json`
+All client-facing metadata is part of the daemon's provider catalog entry (`src/providers/speech-to-text/provider-catalog.ts`). When adding a new provider, include these fields in the catalog entry:
 
-Add a new entry to the `providers` array with the following fields:
+| Field              | Description                                                               |
+| ------------------ | ------------------------------------------------------------------------- |
+| `displayName`      | Human-readable name shown in client settings UI.                          |
+| `subtitle`         | Short description displayed below the provider selector.                  |
+| `setupMode`        | `"api-key"` (inline key field) or `"cli"` (instructions-only).            |
+| `setupHint`        | Brief guidance shown during setup.                                        |
+| `credentialsGuide` | Object with `description`, `url`, and `linkLabel` for the key mgmt page.  |
 
-| Field                       | Description                                                                                                                           |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                        | Must match the `SttProviderId` used in step 1.                                                                                        |
-| `displayName`               | Human-readable name shown in client settings UI.                                                                                      |
-| `subtitle`                  | Short description displayed below the provider selector.                                                                              |
-| `setupMode`                 | `"api-key"` (inline key field) or `"cli"` (instructions-only).                                                                        |
-| `setupHint`                 | Brief guidance shown during setup.                                                                                                    |
-| `apiKeyProviderName`        | Must match the `credentialProvider` value from the daemon catalog entry.                                                              |
-| `conversationStreamingMode` | Must match the `conversationStreamingMode` value from the daemon catalog entry (`"realtime-ws"`, `"incremental-batch"`, or `"none"`). |
+Native clients fetch this metadata at launch via `GET /v1/stt/providers`. No separate client-side file updates are needed.
 
 **Naming/mapping examples:**
 
-| Provider ID      | `credentialProvider` / `apiKeyProviderName` | Key ownership |
-| ---------------- | ------------------------------------------- | ------------- |
-| `openai-whisper` | `openai`                                    | shared        |
-| `deepgram`       | `deepgram`                                  | exclusive     |
-| `google-gemini`  | `gemini`                                    | shared        |
-| `xai`            | `xai`                                       | exclusive     |
+| Provider ID      | `credentialProvider` | Key ownership |
+| ---------------- | -------------------- | ------------- |
+| `openai-whisper` | `openai`             | shared        |
+| `deepgram`       | `deepgram`           | exclusive     |
+| `google-gemini`  | `gemini`             | shared        |
+| `xai`            | `xai`                | exclusive     |
 
 When the provider ID differs from the credential provider name (e.g. `google-gemini` maps to `gemini`), the key is **shared** with other services that use the same credential. The `sttKeyIsExclusive` / `sttKeyIsShared` helpers in the macOS settings layer derive this automatically from the catalog.
 
-Insertion order in the JSON array must match the daemon catalog insertion order.
-
-### Client-side code
-
-**File:** `clients/shared/Utilities/STTProviderRegistry.swift`
-
-Add a matching fallback entry in `fallbackRegistry` with the same `id`, `displayName`, `subtitle`, `setupMode`, `setupHint`, `apiKeyProviderName`, and `conversationStreamingMode` as the JSON catalog entry. The fallback keeps client startup resilient when the bundled JSON is missing.
-
 ### macOS settings key behavior
 
 **File:** `clients/macos/vellum-assistant/Features/Settings/SettingsStore.swift`
 
 The `sttKeyIsExclusive(for:)` / `sttKeyIsShared(for:)` helpers derive shared-vs-exclusive key behavior from the catalog automatically: if `apiKeyProviderName == id`, the key is exclusive; otherwise it is shared. No new conditionals are needed unless the provider has a non-standard key-ownership model.
 
-## 7. Parity tests
-
-**File:** `src/__tests__/stt-catalog-parity.test.ts`
-
-The existing parity test suite enforces that:
-
-- Daemon and client catalog provider IDs are identical and in the same order.
-- Each entry's `apiKeyProviderName` matches the daemon's `credentialProvider`.
-- The client catalog has all required fields populated.
-
-Run the test after completing steps 1-6:
-
-```bash
-cd assistant && bun test src/__tests__/stt-catalog-parity.test.ts
-```
-
-If any assertion fails, the error message identifies which side is out of sync and what to fix.
-
-## 8. Verify unified STT architecture
+## 7. Verify unified STT architecture
 
 `services.stt.provider` is the single source of truth for all STT routing, including telephony. There is no separate telephony STT config path.
 

package/examples/plugins/echo/bun.lock

@@ -0,0 +1,25 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/plugin-echo-example",
+      "devDependencies": {
+        "@types/bun": "1.3.10",
+        "@types/node": "25.5.0",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+
+    "@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
+
+    "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+  }
+}

package/knip.json

@@ -3,32 +3,18 @@
     "src/**/*.test.ts",
     "src/**/__tests__/**/*.ts",
     "scripts/**/*.ts",
-    "src/daemon/main.ts",
-    "src/messaging/providers/*/types.ts",
-    "src/messaging/providers/*/client.ts",
-    "src/memory/graph/inspect.ts",
-    "../skills/meet-join/**/*.test.ts",
-    "../skills/meet-join/**/__tests__/**/*.ts",
-    "!../skills/meet-join/bot/**",
-    "../skills/meet-join/contracts/**/__tests__/**/*.ts",
-    "../skills/meet-join/meet-controller-ext/scripts/build.ts",
-    "../skills/meet-join/meet-controller-ext/src/background.ts",
-    "../skills/meet-join/meet-controller-ext/src/content.ts",
-    "../skills/meet-join/meet-controller-ext/src/avatar/avatar.ts",
-    "../skills/meet-join/meet-controller-ext/src/messaging/content-bridge.ts"
-  ],
-  "project": [
-    "src/**/*.ts",
-    "src/**/*.tsx",
-    "scripts/**/*.ts",
-    "../skills/meet-join/**/*.ts",
-    "!../skills/meet-join/bot/**"
+    "src/daemon/main.ts!"
   ],
+  "project": ["src/**/*.ts!", "src/**/*.tsx!", "scripts/**/*.ts"],
   "ignoreDependencies": [
-    "@vellumai/ces-contracts",
+    "@vellumai/ces-client",
     "@vellumai/credential-storage",
     "@vellumai/egress-proxy",
+    "@vellumai/gateway-client",
+    "@vellumai/service-contracts",
     "@resvg/resvg-js-darwin-arm64",
-    "@resvg/resvg-js-darwin-x64"
+    "@resvg/resvg-js-darwin-x64",
+    "@vellumai/skill-host-contracts",
+    "madge"
   ]
 }

package/node_modules/@vellumai/ces-client/bun.lock

@@ -0,0 +1,33 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/ces-client",
+      "dependencies": {
+        "@vellumai/service-contracts": "file:../service-contracts",
+      },
+      "devDependencies": {
+        "@types/bun": "1.2.4",
+        "typescript": "5.7.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.2.4", "", { "dependencies": { "bun-types": "1.2.4" } }, "sha512-QtuV5OMR8/rdKJs213iwXDpfVvnskPXY/S0ZiFbsTjQZycuqPbMW8Gf/XhLfwE5njW8sxI2WjISURXPlHypMFA=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "@types/ws": ["@types/ws@8.5.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
+
+    "@vellumai/service-contracts": ["@vellumai/service-contracts@file:../service-contracts", { "dependencies": { "zod": "4.3.6" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
+
+    "bun-types": ["bun-types@1.2.4", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-nDPymR207ZZEoWD4AavvEaa/KZe/qlrbMSchqpQwovPZCKc7pwMoENjEtHgMKaAjJhy+x6vfqSBA1QU3bJgs0Q=="],
+
+    "typescript": ["typescript@5.7.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+
+    "zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+  }
+}

package/node_modules/@vellumai/ces-client/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@vellumai/ces-client",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./http-credentials": "./src/http-credentials.ts",
+    "./http-log-export": "./src/http-log-export.ts",
+    "./rpc-client": "./src/rpc-client.ts",
+    "./credential-rpc": "./src/credential-rpc.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "dependencies": {
+    "@vellumai/service-contracts": "file:../service-contracts"
+  },
+  "devDependencies": {
+    "@types/bun": "1.2.4",
+    "typescript": "5.7.3"
+  }
+}