@vellumai/assistant 0.6.4 → 0.6.6

package/docs/architecture/integrations.md

@@ -31,24 +31,7 @@ graph TB
         SHARED["shared.ts<br/>resolveProvider + getProviderConnection"]
     end
 
-    subgraph "Gmail Skill (bundled-skills/gmail/)"
-        GMAIL_SKILL_MD["SKILL.md<br/>agent instructions"]
-        GMAIL_ARCHIVE["gmail_archive"]
-        GMAIL_LABEL["gmail_label"]
-        GMAIL_TRASH["gmail_trash"]
-        GMAIL_UNSUB["gmail_unsubscribe"]
-        GMAIL_DRAFT["gmail_draft"]
-        GMAIL_SEND_DRAFT["gmail_send_draft"]
-        GMAIL_ATTACHMENTS["gmail_attachments"]
-        GMAIL_FORWARD["gmail_forward"]
-        GMAIL_FOLLOW_UP["gmail_follow_up"]
-        GMAIL_FILTERS["gmail_filters"]
-        GMAIL_VACATION["gmail_vacation"]
-        GMAIL_SENDER_DIGEST["gmail_sender_digest"]
-        GMAIL_OUTREACH["gmail_outreach_scan"]
-    end
-
-    subgraph "Slack Skill (bundled-skills/slack/)"
+    subgraph "Slack Skill (skills/slack/)"
         SLACK_SKILL_MD["SKILL.md<br/>agent instructions"]
         SLACK_WEB_API["Web API via bash<br/>(network_mode: proxied)"]
     end
@@ -99,7 +82,6 @@ graph TB
     SEARCH --> SHARED
     SEND --> SHARED
     STYLE --> STYLE_ANALYZER
-    GMAIL_ARCHIVE --> GMAIL_ADAPTER
     SLACK_WEB_API --> SLACK_API
 ```
 
@@ -167,7 +149,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 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                                                  |
+| Shared connect orchestrator                | All OAuth providers route through `orchestrateOAuthConnect()`, which resolves profiles, resolves scopes, 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                                                                                                                                                                                                                     |
 | Caller-driven callback transport           | Transport (`loopback` or `gateway`) is chosen per-flow via the `callbackTransport` option on the connect API, defaulting to loopback. Desktop clients use loopback (no tunnel needed); web clients can pass `callback_transport: "gateway"`. Provider configuration no longer dictates transport. |
 | Unified `MessagingProvider` interface      | All platforms implement the same contract; generic tools work immediately for new providers                                                                                                                                                                                                       |
@@ -179,35 +161,33 @@ sequenceDiagram
 
 ### Source Files
 
-| File                                             | Role                                                                                               |
-| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
-| `assistant/src/security/oauth2.ts`               | OAuth2 flow: PKCE or client_secret, Bun.serve callback, token exchange                             |
-| `assistant/src/security/token-manager.ts`        | `withValidToken()` — auto-refresh, 401 retry, expiry buffer                                        |
-| `assistant/src/messaging/provider.ts`            | `MessagingProvider` interface                                                                      |
-| `assistant/src/messaging/provider-types.ts`      | Platform-agnostic types (Conversation, Message, SearchResult)                                      |
-| `assistant/src/messaging/registry.ts`            | Provider registry: register, lookup, list connected                                                |
-| `assistant/src/messaging/style-analyzer.ts`      | Writing style extraction from message corpus                                                       |
-| `assistant/src/messaging/draft-store.ts`         | Local draft storage (platform/id JSON files)                                                       |
-| `assistant/src/messaging/providers/slack/`       | Slack adapter, client, types                                                                       |
-| `assistant/src/messaging/providers/gmail/`       | Gmail adapter, client, types                                                                       |
-| `assistant/src/config/bundled-skills/messaging/` | Core messaging skill (send, read, search, reply across platforms)                                  |
-| `assistant/src/config/bundled-skills/gmail/`     | Gmail management skill (archive, label, triage, declutter)                                         |
-| `assistant/src/config/bundled-skills/sequences/` | Email sequence management skill (drip campaigns, enrollment, analytics)                            |
-| `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/seed-providers.ts`          | Provider seed data: injection templates, identity config, setup metadata (seeded to DB on startup) |
-| `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: `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`)                     |
+| File                                             | Role                                                                                                   |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `assistant/src/security/oauth2.ts`               | OAuth2 flow: PKCE or client_secret, Bun.serve callback, token exchange                                 |
+| `assistant/src/security/token-manager.ts`        | `withValidToken()` — auto-refresh, 401 retry, expiry buffer                                            |
+| `assistant/src/messaging/provider.ts`            | `MessagingProvider` interface                                                                          |
+| `assistant/src/messaging/provider-types.ts`      | Platform-agnostic types (Conversation, Message, SearchResult)                                          |
+| `assistant/src/messaging/registry.ts`            | Provider registry: register, lookup, list connected                                                    |
+| `assistant/src/messaging/style-analyzer.ts`      | Writing style extraction from message corpus                                                           |
+| `assistant/src/messaging/draft-store.ts`         | Local draft storage (platform/id JSON files)                                                           |
+| `assistant/src/messaging/providers/slack/`       | Slack adapter, client, types                                                                           |
+| `assistant/src/messaging/providers/gmail/`       | Gmail adapter, client, types                                                                           |
+| `assistant/src/config/bundled-skills/messaging/` | Core messaging skill (send, read, search, reply across platforms)                                      |
+| `assistant/src/config/bundled-skills/sequences/` | Email sequence management skill (drip campaigns, enrollment, analytics)                                |
+| `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/seed-providers.ts`          | Provider seed data: injection templates, identity config, setup metadata (seeded to DB on startup)     |
+| `assistant/src/oauth/connect-orchestrator.ts`    | Shared OAuth connect orchestrator: profile resolution, scope resolution, flow execution, token storage |
+| `assistant/src/oauth/connect-types.ts`           | Shared types: `AvailableScopes`, `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 — DB-Driven Provider Config, Scope Policy, and Connect Orchestrator
 
-The OAuth extensibility layer makes adding a new OAuth provider a fully declarative operation. All provider configuration — protocol fields (auth URLs, token URLs, scopes, scope policy), behavioral fields (identity verification, injection templates, setup metadata), and display metadata — is stored in the `oauth_providers` SQLite table and seeded on startup via `seed-providers.ts`. The shared **connect orchestrator** handles the full flow from provider resolution through token storage.
+The OAuth extensibility layer makes adding a new OAuth provider a fully declarative operation. All provider configuration — protocol fields (auth URLs, token URLs, scopes), behavioral fields (identity verification, injection templates, setup metadata), and display metadata — is stored in the `oauth_providers` SQLite table and seeded on startup via `seed-providers.ts`. The shared **connect orchestrator** handles the full flow from provider resolution through token storage.
 
 ### Provider Configuration (DB-Driven)
 
@@ -218,24 +198,19 @@ Each provider row includes:
 | Column group              | Fields                                                                                                                           | Purpose                                                                                |
 | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | **Protocol**              | `authUrl`, `tokenUrl`, `tokenEndpointAuthMethod`, `extraParams`, `loopbackPort`                                                  | OAuth2 flow parameters                                                                 |
-| **Scopes**                | `defaultScopes`, `scopePolicy`                                                                                                   | Deterministic scope resolution (user-customizable, preserved across seed restarts)     |
+| **Scopes**                | `defaultScopes`, `availableScopes`                                                                                               | Default scopes for connect flow; informational available scopes for assistant context  |
 | **Identity verification** | `identityUrl`, `identityMethod`, `identityHeaders`, `identityBody`, `identityResponsePaths`, `identityFormat`, `identityOkField` | Data-driven identity verifier fetches human-readable account info after token exchange |
 | **Injection templates**   | `injectionTemplates`                                                                                                             | Auto-applied credential injection rules for the script proxy                           |
 | **Setup metadata**        | `displayName`, `description`, `dashboardUrl`, `appType`, `setupNotes`, `requiresClientSecret`                                    | Metadata for the generic OAuth setup skill                                             |
 | **Ping config**           | `pingUrl`, `pingMethod`, `pingHeaders`, `pingBody`                                                                               | Health-check endpoint for `assistant oauth ping`                                       |
 
-### Scope Policy Engine
-
-`assistant/src/oauth/scope-policy.ts` exports `resolveScopes(profile, requestedScopes)`, which deterministically computes the final scope set:
+### Scope Resolution
 
-1. No requested scopes → returns `defaultScopes`.
-2. Requested scopes provided → starts with defaults, then validates each additional scope:
-   - Rejected if in `forbiddenScopes`.
-   - Rejected if `allowAdditionalScopes` is `false`.
-   - Rejected if not in `allowedOptionalScopes`.
-   - Accepted otherwise, added to the union.
+Scope resolution is simple — no validation layer:
 
-Returns `{ ok: true, scopes }` or `{ ok: false, error, allowedScopes }`.
+1. No requested scopes → uses `defaultScopes`.
+2. Requested scopes provided → uses the requested scopes directly (no validation — the OAuth provider rejects invalid scopes).
+3. `availableScopes` is informational context surfaced via CLI for the assistant to consult.
 
 ### Connect Orchestrator
 
@@ -243,7 +218,7 @@ Returns `{ ok: true, scopes }` or `{ ok: false, error, allowedScopes }`.
 
 1. **Receive canonical provider name** — the orchestrator receives the canonical provider name directly (e.g. `google`, `slack`).
 2. **Load provider row** — reads all config from the `oauth_providers` DB table.
-3. **Compute scopes** — `resolveScopes()` with scope policy enforcement.
+3. **Compute scopes** — uses requested scopes directly, or falls back to `defaultScopes`.
 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 generic data-driven identity verifier using the provider row's identity columns.
@@ -265,7 +240,7 @@ This replaces provider-specific handlers — any provider in the registry can be
 ### Adding a New OAuth Provider
 
 1. **Add seed data** to `PROVIDER_SEED_DATA` in `assistant/src/oauth/seed-providers.ts`:
-   - Set protocol fields: `authUrl`, `tokenUrl`, `defaultScopes`, `scopePolicy`, `loopbackPort`.
+   - Set protocol fields: `authUrl`, `tokenUrl`, `defaultScopes`, `availableScopes`, `loopbackPort`.
    - Set identity verification: `identityUrl`, `identityMethod`, `identityHeaders`, `identityResponsePaths`, `identityFormat`.
    - Set injection templates: `injectionTemplates` for providers whose tokens should be auto-injected by the script proxy.
    - Set setup metadata: `displayName`, `dashboardUrl`, `appType` enable the generic OAuth setup skill to guide users through app creation.
@@ -278,9 +253,8 @@ This replaces provider-specific handlers — any provider in the registry can be
 | File                                             | Role                                                                        |
 | ------------------------------------------------ | --------------------------------------------------------------------------- |
 | `assistant/src/oauth/seed-providers.ts`          | Provider seed data and startup seeding                                      |
-| `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 (`OAuthScopePolicy`, `OAuthConnectResult`)                     |
+| `assistant/src/oauth/connect-types.ts`           | Shared types (`AvailableScopes`, `OAuthConnectResult`)                      |
 | `assistant/src/oauth/token-persistence.ts`       | Token storage: credential store writes, metadata upsert, post-connect hooks |
 | `assistant/src/oauth/identity-verifier.ts`       | Generic data-driven identity verifier (reads config from provider DB row)   |
 | `assistant/src/daemon/handlers/oauth-connect.ts` | Generic `oauth_connect_start` / `oauth_connect_result` handler              |

package/docs/architecture/memory.md

@@ -177,9 +177,7 @@ graph TB
         OVF_T2["Tier 2: Tool-result truncation<br/>4,000 chars per result"]
         OVF_T3["Tier 3: Media/file stubbing"]
         OVF_T4["Tier 4: Injection downgrade<br/>→ minimal mode"]
-        OVF_POLICY["Overflow policy resolver<br/>auto_compress / request_approval / fail_gracefully"]
-        OVF_APPROVE["Approval gate<br/>PermissionPrompter"]
-        OVF_DENY["Graceful deny message<br/>(not conversation_error)"]
+        OVF_LATEST["Auto-compress latest turn<br/>(force=true, minKeepRecentUserTurns=0)"]
     end
 
     MSG_IN --> STORE
@@ -237,11 +235,8 @@ graph TB
     OVF_T1 --> OVF_T2
     OVF_T2 --> OVF_T3
     OVF_T3 --> OVF_T4
-    OVF_T4 --> OVF_POLICY
-    OVF_POLICY -->|"interactive"| OVF_APPROVE
-    OVF_POLICY -->|"non-interactive"| OVF_T1
-    OVF_APPROVE -->|"denied"| OVF_DENY
-    OVF_APPROVE -->|"approved"| OVF_T1
+    OVF_T4 --> OVF_LATEST
+    OVF_LATEST -.->|"uses"| SUMMARIZE
     OVF_T1 -.->|"uses"| SUMMARIZE
 ```
 
@@ -251,7 +246,7 @@ Normal context compaction (the "Context Window Management" subgraph above) runs
 
 When compaction alone is insufficient — either because the conversation grew too fast between turns or because a single turn contains extremely large payloads — the overflow recovery pipeline takes over. The pipeline's first tier (forced compaction) reuses the same `maybeCompact()` summarization machinery but with emergency parameters: `force: true` bypasses cooldown guards, `minKeepRecentUserTurns: 0` allows summarizing even the most recent history, and `targetInputTokensOverride` sets a tighter budget. Subsequent tiers (tool-result truncation, media stubbing, injection downgrade) apply progressively more aggressive payload reduction without involving the summarizer.
 
-If all four reducer tiers are exhausted, the overflow policy resolver determines whether to compress the latest user turn. In interactive sessions, the user is prompted for approval before this lossy step. If the user declines, the session emits a graceful assistant explanation message rather than a `conversation_error`, ending the turn cleanly. Non-interactive sessions auto-compress without prompting.
+If all four reducer tiers are exhausted, the overflow policy resolver determines whether to compress the latest user turn. All sessions — interactive and non-interactive alike — auto-compress the latest turn without prompting. The only explicit opt-out is setting `contextWindow.overflowRecovery.interactiveLatestTurnCompression` (or `nonInteractiveLatestTurnCompression`) to `"drop"`, which short-circuits to a graceful failure instead. Disabling overflow recovery entirely (`contextWindow.overflowRecovery.enabled: false`) also yields a graceful failure.
 
 The key distinction: normal compaction is a cost-optimized background process that preserves conversational quality; overflow recovery is a convergence mechanism that prioritizes session survival over context richness. Both share the same summarization infrastructure but operate under different pressure thresholds and constraints.
 
@@ -303,16 +298,16 @@ stateDiagram-v2
 
 **Item extraction** uses LLM-powered extraction (with pattern-based fallback) to identify memorable information from conversation messages. Each extracted item belongs to one of eight kinds:
 
-| Kind         | Description                                                        | Base Lifetime |
-| ------------ | ------------------------------------------------------------------ | ------------- |
-| `identity`   | Personal info, facts, relationships                                | 6 months      |
-| `preference` | Likes, dislikes, preferred approaches/tools                        | 3 months      |
+| Kind         | Description                                                          | Base Lifetime |
+| ------------ | -------------------------------------------------------------------- | ------------- |
+| `identity`   | Personal info, facts, relationships                                  | 6 months      |
+| `preference` | Likes, dislikes, preferred approaches/tools                          | 3 months      |
 | `journal`    | Experiential reflections, journal-style notes, forward-looking items | 3 months      |
-| `constraint` | Rules, requirements, directives                                    | 1 month       |
-| `project`    | Project details, repos, tech stacks, action items                  | 2 weeks       |
-| `decision`   | Choices made, approaches selected                                  | 2 weeks       |
-| `event`      | Deadlines, milestones, meetings, dates                             | 3 days        |
-| `capability` | Skill catalog entries (system-generated, not LLM-extracted)        | never expires |
+| `constraint` | Rules, requirements, directives                                      | 1 month       |
+| `project`    | Project details, repos, tech stacks, action items                    | 2 weeks       |
+| `decision`   | Choices made, approaches selected                                    | 2 weeks       |
+| `event`      | Deadlines, milestones, meetings, dates                               | 3 days        |
+| `capability` | Skill catalog entries (system-generated, not LLM-extracted)          | never expires |
 
 **Supersession chains** replace the old conflict resolution system. When the LLM extracts a new item that updates an existing one, it sets `supersedes` to the old item's ID and `overrideConfidence` to one of three levels:
 
@@ -552,13 +547,13 @@ The Anthropic provider places `cache_control: { type: 'ephemeral' }` on the **la
 
 ### Key files
 
-| File                                                    | Role                                                                                                                                       |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `assistant/src/workspace/top-level-scanner.ts`          | Synchronous directory scanner with `MAX_TOP_LEVEL_ENTRIES` cap                                                                             |
-| `assistant/src/workspace/top-level-renderer.ts`         | Renders `TopLevelSnapshot` to `<workspace>` XML block                                                                                      |
-| `assistant/src/daemon/conversation-runtime-assembly.ts` | Runtime injections and legacy-block strip helpers (`<workspace>`, `<turn_context>`, `<channel_onboarding_playbook>`, `<onboarding_mode>`)  |
-| `assistant/src/onboarding/onboarding-orchestrator.ts`   | Builds assistant-owned onboarding runtime guidance from channel playbook + transport metadata                                              |
-| `assistant/src/daemon/conversation-agent-loop.ts`       | Agent loop orchestration, runtime injection wiring, legacy-block strip chain                                                               |
+| File                                                    | Role                                                                                                                                      |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `assistant/src/workspace/top-level-scanner.ts`          | Synchronous directory scanner with `MAX_TOP_LEVEL_ENTRIES` cap                                                                            |
+| `assistant/src/workspace/top-level-renderer.ts`         | Renders `TopLevelSnapshot` to `<workspace>` XML block                                                                                     |
+| `assistant/src/daemon/conversation-runtime-assembly.ts` | Runtime injections and legacy-block strip helpers (`<workspace>`, `<turn_context>`, `<channel_onboarding_playbook>`, `<onboarding_mode>`) |
+| `assistant/src/onboarding/onboarding-orchestrator.ts`   | Builds assistant-owned onboarding runtime guidance from channel playbook + transport metadata                                             |
+| `assistant/src/daemon/conversation-agent-loop.ts`       | Agent loop orchestration, runtime injection wiring, legacy-block strip chain                                                              |
 
 ---
 
@@ -593,11 +588,11 @@ graph TB
 
 ### Key files
 
-| File                                                    | Role                                                                                                          |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `assistant/src/daemon/date-context.ts`                  | `formatTurnTimestamp()` — generates the timestamp string used in `<turn_context>`                             |
-| `assistant/src/daemon/conversation-runtime-assembly.ts` | `buildUnifiedTurnContextBlock()` — constructs the unified `<turn_context>` block; legacy block strip helpers  |
-| `assistant/src/daemon/conversation-agent-loop.ts`       | Wiring: builds turn context, passes to `applyRuntimeInjections`                                               |
+| File                                                    | Role                                                                                                         |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `assistant/src/daemon/date-context.ts`                  | `formatTurnTimestamp()` — generates the timestamp string used in `<turn_context>`                            |
+| `assistant/src/daemon/conversation-runtime-assembly.ts` | `buildUnifiedTurnContextBlock()` — constructs the unified `<turn_context>` block; legacy block strip helpers |
+| `assistant/src/daemon/conversation-agent-loop.ts`       | Wiring: builds turn context, passes to `applyRuntimeInjections`                                              |
 
 ---
 

package/docs/architecture/security.md

@@ -16,22 +16,24 @@ graph TB
 
     FIND_RULE -->|"Deny rule"| DENY["decision: deny<br/>Blocked by rule"]
     FIND_RULE -->|"Ask rule"| PROMPT_ASK["decision: prompt<br/>Always ask user"]
-    FIND_RULE -->|"Allow rule"| RISK_CHECK{"Risk level?"}
-    FIND_RULE -->|"No match"| NO_MATCH{"Fallback logic"}
+    FIND_RULE -->|"Allow rule / No match"| SANDBOX_CHECK{"sandboxAutoApprove?<br/>(bash + allowlisted +<br/>containerized)"}
+
+    SANDBOX_CHECK -->|"yes"| AUTO_SANDBOX["decision: allow<br/>Sandbox auto-approve"]
+    SANDBOX_CHECK -->|"no, has Allow rule"| RISK_CHECK{"Risk level?"}
+    SANDBOX_CHECK -->|"no, no match"| NO_MATCH{"Fallback logic"}
 
     RISK_CHECK -->|"Low / Medium"| AUTO_ALLOW["decision: allow<br/>Auto-allowed by rule"]
-    RISK_CHECK -->|"High"| HIGH_CHECK{"allowHighRisk<br/>on rule?"}
-    HIGH_CHECK -->|"true"| AUTO_ALLOW
-    HIGH_CHECK -->|"false / absent"| PROMPT_HIGH["decision: prompt<br/>High risk override"]
+    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/>invocation?"}
+    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_FALLBACK_WS{"Risk level?"}
-    RISK_FALLBACK_WS -->|"Low"| AUTO_WS_LOW["decision: allow<br/>Low risk auto-allow"]
-    RISK_FALLBACK_WS -->|"Medium"| PROMPT_WS_MED["decision: prompt"]
-    RISK_FALLBACK_WS -->|"High"| PROMPT_WS_HIGH["decision: prompt"]
+    WS_CHECK -->|"no"| 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
@@ -49,7 +51,7 @@ The `permissions.mode` config option (`workspace` or `strict`) controls the defa
 | `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 with `allowHighRisk: true`             | Auto-allowed (even high risk)                 | Auto-allowed (even high risk)                 |
+| Allow rules + containerized bash (high risk)       | Auto-allowed (runtime check)                  | Auto-allowed (runtime check)                  |
 | Deny rules                                         | Blocked                                       | Blocked                                       |
 
 **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.
@@ -71,7 +73,6 @@ Rules are stored in `~/.vellum/protected/trust.json` with version `3`. Each rule
 | `decision`        | `allow \| deny \| ask` | What to do when the rule matches                                         |
 | `priority`        | `number`               | Higher priority wins; deny wins ties at equal priority                   |
 | `executionTarget` | `string?`              | `sandbox` or `host` — restricts by execution context                     |
-| `allowHighRisk`   | `boolean?`             | When true, auto-allows even high-risk invocations                        |
 
 Missing optional fields act as wildcards. A rule with no `executionTarget` matches any target.
 
@@ -165,7 +166,7 @@ When a permission prompt is sent to the client (via `confirmation_request` SSE e
 | `allowlistOptions` | Suggested patterns for "always allow" rules         |
 | `scopeOptions`     | Suggested scopes for rule persistence               |
 
-The user can respond with: `allow` (one-time), `always_allow` (create allow rule), `always_allow_high_risk` (create allow rule with `allowHighRisk: true`), `deny` (one-time), or `always_deny` (create deny rule).
+The user can respond with: `allow` (one-time), `always_allow` (create allow rule), `deny` (one-time), or `always_deny` (create deny rule). In containerized environments, commands tagged with `sandboxAutoApprove` in their risk spec are auto-allowed via the approval policy's sandbox auto-approve check; non-allowlisted commands (network tools, runtimes, package managers) use the user's `autoApproveUpTo` threshold. All other risk-based decisions use the `autoApproveUpTo` threshold (default: `"low"`) -- tools at or below the threshold are auto-allowed, those above are prompted.
 
 ### Canonical Paths
 
@@ -272,18 +273,18 @@ The `allowOneTimeSend` config gate (default: `false`) enables a secondary "Send
 
 ### Storage Layout
 
-| Component           | Location                                             | What it stores                                                                                                                                               |
-| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Component           | Location                                             | What it stores                                                                                                                                                   |
+| ------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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                                                                              |
+| 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                                                                                  |
 
 ### Key Files
 
 | 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 CES 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/browser-use-architecture-phase2.md

@@ -2,23 +2,39 @@
 
 ## Overview
 
-Phase 2 of browser automation introduced a three-tier backend selection chain for macOS-originated turns, enabling the assistant to prefer the user's real Chrome session (via the paired extension) over a sandboxed Playwright instance. When the extension is unavailable, the system falls back through cdp-inspect (direct Chrome DevTools Protocol attach) before resorting to the local Playwright browser.
+Phase 2 of browser automation introduced a three-tier backend selection chain for macOS-originated turns, enabling the assistant to prefer the user's real Chrome session over a sandboxed Playwright instance. Two transport paths exist for the top-priority "extension" backend:
 
-This document describes the runtime architecture, backend precedence rules, and the manual QA playbook for verifying correct backend selection.
+1. **Chrome Extension Registry (WebSocket)**: When the user has the Vellum Chrome Extension installed and paired, `host_browser_request` frames route through the `ChromeExtensionRegistry` singleton over a dedicated `/v1/browser-relay` WebSocket.
+2. **macOS Host Browser Proxy (SSE)**: When the macOS desktop client is connected but the Chrome extension is absent, `host_browser_request` frames travel through `assistantEventHub` (SSE). The desktop client receives the frames via its SSE connection, executes CDP commands against the local Chrome, and POSTs results back to `/v1/host-browser-result`.
+
+When neither transport is available, the system falls back through cdp-inspect (direct Chrome DevTools Protocol attach) before resorting to the local Playwright browser.
+
+This document describes the runtime architecture, backend precedence rules, transport matrix, and the manual QA playbook for verifying correct backend selection.
 
 ## Component Inventory
 
-| Component                   | Location                                           | Role                                                                                                                                                                                   |
-| --------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **ChromeExtensionRegistry** | `runtime/chrome-extension-registry.ts`             | Tracks active extension WebSocket connections keyed by `(guardianId, clientInstanceId)`. Populated on WS `open`, drained on WS `close`.                                                |
-| **HostBrowserProxy**        | `daemon/host-browser-proxy.ts`                     | Per-conversation proxy that dispatches `host_browser_request` frames and awaits `host_browser_result` responses.                                                                       |
-| **CDP Factory**             | `tools/browser/cdp-client/factory.ts`              | Builds the ordered candidate list and returns a `ScopedCdpClient` with per-invocation failover.                                                                                        |
-| **BrowserSessionManager**   | `browser-session/manager.ts`                       | Routes CDP commands through the selected backend with session tracking.                                                                                                                |
-| **CdpInspectClient**        | `tools/browser/cdp-client/cdp-inspect-client.ts`   | Connects to a host Chrome instance via its remote-debugging WebSocket endpoint.                                                                                                        |
-| **LocalCdpClient**          | `tools/browser/cdp-client/local-cdp-client.ts`     | Drives Playwright's CDPSession against the sacrificial-profile browser.                                                                                                                |
-| **ExtensionCdpClient**      | `tools/browser/cdp-client/extension-cdp-client.ts` | Routes CDP commands through the HostBrowserProxy to the user's real Chrome.                                                                                                            |
-| **conversation-routes.ts**  | `runtime/routes/conversation-routes.ts`            | Wires `resolveHostBrowserSender()` to set `hostBrowserSenderOverride` when the extension is connected. Sets `turnInterfaceContext` from the `interface` field on the incoming message. |
-| **Desktop-auto config**     | `config/schemas/host-browser.ts`                   | `desktopAuto.enabled` (default `true`) and `desktopAuto.cooldownMs` (default 30s) control automatic cdp-inspect on macOS.                                                              |
+| Component                   | Location                                           | Role                                                                                                                                                                              |
+| --------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **ChromeExtensionRegistry** | `runtime/chrome-extension-registry.ts`             | Tracks active extension WebSocket connections keyed by `(guardianId, clientInstanceId)`. Populated on WS `open`, drained on WS `close`.                                           |
+| **HostBrowserProxy**        | `daemon/host-browser-proxy.ts`                     | Per-conversation proxy that dispatches `host_browser_request` frames and awaits `host_browser_result` responses. Wired to either the registry sender or the SSE hub sender.       |
+| **CDP Factory**             | `tools/browser/cdp-client/factory.ts`              | Builds the ordered candidate list and returns a `ScopedCdpClient` with per-invocation failover.                                                                                   |
+| **BrowserSessionManager**   | `browser-session/manager.ts`                       | Routes CDP commands through the selected backend with session tracking.                                                                                                           |
+| **CdpInspectClient**        | `tools/browser/cdp-client/cdp-inspect-client.ts`   | Connects to a host Chrome instance via its remote-debugging WebSocket endpoint.                                                                                                   |
+| **LocalCdpClient**          | `tools/browser/cdp-client/local-cdp-client.ts`     | Drives Playwright's CDPSession against the sacrificial-profile browser.                                                                                                           |
+| **ExtensionCdpClient**      | `tools/browser/cdp-client/extension-cdp-client.ts` | Routes CDP commands through the HostBrowserProxy to the user's real Chrome.                                                                                                       |
+| **conversation-routes.ts**  | `runtime/routes/conversation-routes.ts`            | Wires `resolveHostBrowserSender()` to set `hostBrowserSenderOverride` when the extension is connected. For macOS without extension, provisions the proxy with the SSE hub sender. |
+| **Desktop-auto config**     | `config/schemas/host-browser.ts`                   | `desktopAuto.enabled` (default `true`) and `desktopAuto.cooldownMs` (default 30s) control automatic cdp-inspect on macOS.                                                         |
+
+## Transport Matrix
+
+The following table shows how `host_browser_request` frames are delivered to the client based on the originating interface and extension connectivity:
+
+| Interface          | Extension Connected | Transport                       | Sender                                          | Notes                                                                  |
+| ------------------ | ------------------- | ------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
+| `chrome-extension` | Yes (always)        | WebSocket (`/v1/browser-relay`) | `ChromeExtensionRegistry.send(guardianId, msg)` | The only transport for chrome-extension turns; SSE fallback is invalid |
+| `macos`            | Yes                 | WebSocket (`/v1/browser-relay`) | `ChromeExtensionRegistry.send(guardianId, msg)` | Extension takes priority; browser tools route through user's Chrome    |
+| `macos`            | No                  | SSE (`assistantEventHub`)       | `onEvent` hub publisher                         | macOS host browser proxy mode; desktop client handles CDP locally      |
+| Other              | Any                 | N/A                             | No browser proxy provisioned                    | Falls through to cdp-inspect or local Playwright                       |
 
 ## Wire Diagram
 
@@ -37,10 +53,12 @@ conversation-routes.ts
     |               |
     |               +-- entry found? --> registrySender (WS to extension)
     |               |                    hostBrowserSenderOverride = registrySender
-    |               |                    provision HostBrowserProxy
+    |               |                    provision HostBrowserProxy(registrySender)
     |               |
     |               +-- entry not found? --> SSE hub sender (default)
     |                                        hostBrowserSenderOverride = undefined
+    |                                        provision HostBrowserProxy(onEvent)
+    |                                        [macOS natively supports host_browser]
     |
     v
 Agent loop invokes browser tool
@@ -50,6 +68,8 @@ getCdpClient(toolContext)
     |-- toolContext.hostBrowserProxy set?
     |       AND hostBrowserProxy.isAvailable()?
     |       --> candidate: extension (priority 1)
+    |       [Transport: WS via registry when extension present,
+    |        SSE via hub when macOS host proxy only]
     |
     |-- transportInterface === "macos"
     |       AND desktopAuto.enabled?
@@ -61,7 +81,7 @@ getCdpClient(toolContext)
     v
 ScopedCdpClient.send(method, params)
     |
-    +-- Try candidate 1 (extension)
+    +-- Try candidate 1 (extension / macOS host proxy)
     |       transport_error? --> failover to candidate 2
     |       cdp_error? --> propagate immediately (no failover)
     |       success? --> sticky for remainder of invocation
@@ -76,11 +96,11 @@ ScopedCdpClient.send(method, params)
 
 ## Backend Precedence (macOS)
 
-| Priority | Backend            | When selected                                                                            | Failover trigger                                                                         |
-| -------- | ------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| 1        | Extension          | `hostBrowserProxy` present and `isAvailable()` is `true`                                 | Transport error (WebSocket disconnected, send failed)                                    |
-| 2        | cdp-inspect        | Config `enabled: true`, OR macOS + `desktopAuto.enabled` (default) + cooldown not active | Transport error (endpoint unreachable, WS connect failure). Records cooldown on failure. |
-| 3        | Local (Playwright) | Always present as final fallback                                                         | Errors propagate to the tool                                                             |
+| Priority | Backend                      | When selected                                                                                                                                                                   | Transport                  | Failover trigger                                                                         |
+| -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
+| 1        | Extension / macOS host proxy | `hostBrowserProxy` present and `isAvailable()` is `true`. On macOS, the proxy is always provisioned (SSE sender when no extension, registry-routed when extension is connected) | WS (registry) or SSE (hub) | Transport error (WebSocket disconnected, SSE send failed)                                |
+| 2        | cdp-inspect                  | Config `enabled: true`, OR macOS + `desktopAuto.enabled` (default) + cooldown not active                                                                                        | Direct CDP WebSocket       | Transport error (endpoint unreachable, WS connect failure). Records cooldown on failure. |
+| 3        | Local (Playwright)           | Always present as final fallback                                                                                                                                                | In-process CDP             | Errors propagate to the tool                                                             |
 
 After the first successful CDP command on any backend, that backend becomes **sticky** for the remainder of the tool invocation.
 
@@ -114,6 +134,29 @@ When cdp-inspect fails with a transport error during a desktop-auto attempt:
 - No `browserManager` launch log (Playwright not started).
 - Extension WebSocket receives `host_browser_request` frames.
 
+### Scenario 1b: macOS Host Browser Proxy (No Extension)
+
+**Setup:**
+
+1. macOS desktop client is running and connected to the assistant via SSE.
+2. No browser extension is installed or connected.
+3. Chrome is running on the desktop machine.
+
+**Test:**
+
+1. Send a message that triggers browser automation (e.g. "navigate to example.com and take a screenshot").
+2. Observe the assistant drives the user's Chrome session via the macOS host browser proxy (the desktop client receives `host_browser_request` frames over SSE and executes CDP commands locally).
+
+**Expected telemetry/log signals:**
+
+- `cdp-factory` log: `CDP factory: built candidate list` with `candidates: [{kind: "extension", ...}, {kind: "cdp-inspect", ...}, {kind: "local", ...}]`
+- `cdp-factory` log: `CDP factory: candidate succeeded, backend is now sticky` with `candidateKind: "extension"`
+- No `browserManager` launch log (Playwright not started).
+- SSE event stream delivers `host_browser_request` frames (not WebSocket relay).
+- `browser_status` output shows `transport: "macos-sse"` in the extension mode details.
+
+**Difference from Scenario 1:** The transport is SSE-based (`assistantEventHub`), not the `/v1/browser-relay` WebSocket. The `hostBrowserSenderOverride` is `undefined` because no registry entry exists. The proxy is provisioned because macOS natively supports `host_browser`.
+
 ### Scenario 2: Extension Absent + cdp-inspect Enabled
 
 **Setup:**