@vellumai/assistant 0.6.5 → 0.6.6

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,13 +16,14 @@ 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{"shouldAutoAllowHighRisk()<br/>(containerized bash?)"}
-    HIGH_CHECK -->|"yes"| AUTO_ALLOW
-    HIGH_CHECK -->|"no"| RISK_THRESHOLD{"Risk-based<br/>threshold fallback"}
+    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"]
@@ -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), `deny` (one-time), or `always_deny` (create deny rule). High-risk operations with an allow rule in containerized environments are auto-allowed at runtime by `DefaultApprovalPolicy.shouldAutoAllowHighRisk()` without requiring persisted state. All other risk-based decisions use the `autoApproveUpTo` threshold (default: `"low"`) -- tools at or below the threshold are auto-allowed, those above are prompted.
+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
 

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:**