@vellumai/assistant 0.6.3 → 0.6.5

package/bun.lock

@@ -11,17 +11,19 @@
         "@modelcontextprotocol/sdk": "1.27.1",
         "@qdrant/js-client-rest": "1.17.0",
         "@resvg/resvg-js": "2.6.2",
+        "@resvg/resvg-js-darwin-arm64": "2.6.2",
+        "@resvg/resvg-js-darwin-x64": "2.6.2",
         "@sentry/node": "10.43.0",
         "@vellumai/ces-contracts": "file:../packages/ces-contracts",
         "@vellumai/credential-storage": "file:../packages/credential-storage",
         "@vellumai/egress-proxy": "file:../packages/egress-proxy",
-        "agentmail": "0.1.19",
         "archiver": "7.0.1",
         "commander": "13.1.0",
         "croner": "10.0.1",
         "dotenv": "17.3.1",
-        "drizzle-orm": "0.38.4",
+        "drizzle-orm": "0.45.2",
         "jszip": "3.10.1",
+        "marked": "18.0.0",
         "minimatch": "10.2.4",
         "openai": "6.29.0",
         "pino": "9.14.0",
@@ -29,8 +31,8 @@
         "playwright": "1.58.2",
         "postgres": "3.4.8",
         "qrcode": "1.5.4",
-        "react": "19.2.4",
         "rrule": "2.8.1",
+        "tar-stream": "3.1.7",
         "tldts": "7.0.25",
         "tree-sitter-bash": "0.25.1",
         "uuid": "11.1.0",
@@ -42,7 +44,6 @@
         "@types/archiver": "7.0.0",
         "@types/bun": "1.3.10",
         "@types/node": "25.5.0",
-        "@types/react": "19.2.14",
         "@types/uuid": "10.0.0",
         "drizzle-kit": "0.30.6",
         "eslint": "10.0.3",
@@ -56,8 +57,8 @@
     },
   },
   "overrides": {
-    "lodash": "^4.18.0",
-    "path-to-regexp": "^8.4.0",
+    "lodash": "4.18.1",
+    "path-to-regexp": "8.4.2",
   },
   "packages": {
     "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@0.16.1", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-1ad+Sc/0sCtZGHthxxvgEUo5Wsbw16I+aF+YwdiLnPwkZG8KAGUEAPK6LM6Pf69lCyJPt1Aomk1d+8oE3C4ZEw=="],
@@ -356,8 +357,6 @@
 
     "@types/pg-pool": ["@types/pg-pool@2.0.7", "", { "dependencies": { "@types/pg": "*" } }, "sha512-U4CwmGVQcbEuqpyju8/ptOKg6gEC+Tqsvj2xS9o1g71bUh8twxnC6ZL5rZKCsGN0iyH0CwgUyc9VR5owNQF9Ng=="],
 
-    "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
-
     "@types/readdir-glob": ["@types/readdir-glob@1.1.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-raiuEPUYqXu+nvtY2Pe8s8FEmZ3x5yAH4VkLdihcPdalvsHltomrRC9BzuStrJ9yk06470hS0Crw0f1pXqD+Hg=="],
 
     "@types/retry": ["@types/retry@0.12.0", "", {}, "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA=="],
@@ -404,8 +403,6 @@
 
     "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
 
-    "agentmail": ["agentmail@0.1.19", "", { "dependencies": { "ws": "^8.16.0" } }, "sha512-L0au0GnyH24Ob7l0QrkkdwJWL25Aa26f6YnuQlpvwtQMVOTu6IiMftJ8LnVVwQtKwBSZ6cWLS+9SdCvgw+LWGg=="],
-
     "ajv": ["ajv@6.14.0", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw=="],
 
     "ajv-formats": ["ajv-formats@3.0.1", "", { "dependencies": { "ajv": "^8.0.0" } }, "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ=="],
@@ -500,8 +497,6 @@
 
     "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
 
-    "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
-
     "data-uri-to-buffer": ["data-uri-to-buffer@4.0.1", "", {}, "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A=="],
 
     "dateformat": ["dateformat@4.6.3", "", {}, "sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA=="],
@@ -520,7 +515,7 @@
 
     "drizzle-kit": ["drizzle-kit@0.30.6", "", { "dependencies": { "@drizzle-team/brocli": "^0.10.2", "@esbuild-kit/esm-loader": "^2.5.5", "esbuild": "^0.19.7", "esbuild-register": "^3.5.0", "gel": "^2.0.0" }, "bin": { "drizzle-kit": "bin.cjs" } }, "sha512-U4wWit0fyZuGuP7iNmRleQyK2V8wCuv57vf5l3MnG4z4fzNTjY/U13M8owyQ5RavqvqxBifWORaR3wIUzlN64g=="],
 
-    "drizzle-orm": ["drizzle-orm@0.38.4", "", { "peerDependencies": { "@aws-sdk/client-rds-data": ">=3", "@cloudflare/workers-types": ">=4", "@electric-sql/pglite": ">=0.2.0", "@libsql/client": ">=0.10.0", "@libsql/client-wasm": ">=0.10.0", "@neondatabase/serverless": ">=0.10.0", "@op-engineering/op-sqlite": ">=2", "@opentelemetry/api": "^1.4.1", "@planetscale/database": ">=1", "@prisma/client": "*", "@tidbcloud/serverless": "*", "@types/better-sqlite3": "*", "@types/pg": "*", "@types/react": ">=18", "@types/sql.js": "*", "@vercel/postgres": ">=0.8.0", "@xata.io/client": "*", "better-sqlite3": ">=7", "bun-types": "*", "expo-sqlite": ">=14.0.0", "knex": "*", "kysely": "*", "mysql2": ">=2", "pg": ">=8", "postgres": ">=3", "react": ">=18", "sql.js": ">=1", "sqlite3": ">=5" }, "optionalPeers": ["@aws-sdk/client-rds-data", "@cloudflare/workers-types", "@electric-sql/pglite", "@libsql/client", "@libsql/client-wasm", "@neondatabase/serverless", "@op-engineering/op-sqlite", "@opentelemetry/api", "@planetscale/database", "@prisma/client", "@tidbcloud/serverless", "@types/better-sqlite3", "@types/pg", "@types/react", "@types/sql.js", "@vercel/postgres", "@xata.io/client", "better-sqlite3", "bun-types", "expo-sqlite", "knex", "kysely", "mysql2", "pg", "postgres", "react", "sql.js", "sqlite3"] }, "sha512-s7/5BpLKO+WJRHspvpqTydxFob8i1vo2rEx4pY6TGY7QSMuUfWUuzaY0DIpXCkgHOo37BaFC+SJQb99dDUXT3Q=="],
+    "drizzle-orm": ["drizzle-orm@0.45.2", "", { "peerDependencies": { "@aws-sdk/client-rds-data": ">=3", "@cloudflare/workers-types": ">=4", "@electric-sql/pglite": ">=0.2.0", "@libsql/client": ">=0.10.0", "@libsql/client-wasm": ">=0.10.0", "@neondatabase/serverless": ">=0.10.0", "@op-engineering/op-sqlite": ">=2", "@opentelemetry/api": "^1.4.1", "@planetscale/database": ">=1.13", "@prisma/client": "*", "@tidbcloud/serverless": "*", "@types/better-sqlite3": "*", "@types/pg": "*", "@types/sql.js": "*", "@upstash/redis": ">=1.34.7", "@vercel/postgres": ">=0.8.0", "@xata.io/client": "*", "better-sqlite3": ">=7", "bun-types": "*", "expo-sqlite": ">=14.0.0", "gel": ">=2", "knex": "*", "kysely": "*", "mysql2": ">=2", "pg": ">=8", "postgres": ">=3", "sql.js": ">=1", "sqlite3": ">=5" }, "optionalPeers": ["@aws-sdk/client-rds-data", "@cloudflare/workers-types", "@electric-sql/pglite", "@libsql/client", "@libsql/client-wasm", "@neondatabase/serverless", "@op-engineering/op-sqlite", "@opentelemetry/api", "@planetscale/database", "@prisma/client", "@tidbcloud/serverless", "@types/better-sqlite3", "@types/pg", "@types/sql.js", "@upstash/redis", "@vercel/postgres", "@xata.io/client", "better-sqlite3", "bun-types", "expo-sqlite", "gel", "knex", "kysely", "mysql2", "pg", "postgres", "sql.js", "sqlite3"] }, "sha512-kY0BSaTNYWnoDMVoyY8uxmyHjpJW1geOmBMdSSicKo9CIIWkSxMIj2rkeSR51b8KAPB7m+qysjuHme5nKP+E5Q=="],
 
     "dunder-proto": ["dunder-proto@1.0.1", "", { "dependencies": { "call-bind-apply-helpers": "^1.0.1", "es-errors": "^1.3.0", "gopd": "^1.2.0" } }, "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A=="],
 
@@ -758,6 +753,8 @@
 
     "lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
 
+    "marked": ["marked@18.0.0", "", { "bin": { "marked": "bin/marked.js" } }, "sha512-2e7Qiv/HJSXj8rDEpgTvGKsP8yYtI9xXHKDnrftrmnrJPaFNM7VRb2YCzWaX4BP1iCJ/XPduzDJZMFoqTCcIMA=="],
+
     "math-intrinsics": ["math-intrinsics@1.1.0", "", {}, "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g=="],
 
     "media-typer": ["media-typer@1.1.0", "", {}, "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw=="],
@@ -902,8 +899,6 @@
 
     "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
 
-    "react": ["react@19.2.4", "", {}, "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ=="],
-
     "readable-stream": ["readable-stream@4.7.0", "", { "dependencies": { "abort-controller": "^3.0.0", "buffer": "^6.0.3", "events": "^3.3.0", "process": "^0.11.10", "string_decoder": "^1.3.0" } }, "sha512-oIGGmcpTLwPga8Bn6/Z75SVaH1z5dUut2ibSyAMVhmUggWpmDn2dapB0n7f8nwaSiRtepAsfJyfXIO5DCVAODg=="],
 
     "readdir-glob": ["readdir-glob@1.1.3", "", { "dependencies": { "minimatch": "^5.1.0" } }, "sha512-v05I2k7xN8zXvPD9N+z/uhXPaj0sUFCe2rcWZIpBsqxfP7xXFQ0tipAd/wjj1YxWyWtUS5IDJpOG82JKt2EAVA=="],
@@ -994,7 +989,7 @@
 
     "strip-json-comments": ["strip-json-comments@5.0.3", "", {}, "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw=="],
 
-    "tar-stream": ["tar-stream@3.1.8", "", { "dependencies": { "b4a": "^1.6.4", "bare-fs": "^4.5.5", "fast-fifo": "^1.2.0", "streamx": "^2.15.0" } }, "sha512-U6QpVRyCGHva435KoNWy9PRoi2IFYCgtEhq9nmrPPpbRacPs9IH4aJ3gbrFC8dPcXvdSZ4XXfXT5Fshbp2MtlQ=="],
+    "tar-stream": ["tar-stream@3.1.7", "", { "dependencies": { "b4a": "^1.6.4", "fast-fifo": "^1.2.0", "streamx": "^2.15.0" } }, "sha512-qJj60CXt7IU1Ffyc3NJMjh6EkuCFej46zUqJ4J7pqYlThyd9bO0XBTmcOIhSzZJVWfsLks0+nle/j538YAW9RQ=="],
 
     "teex": ["teex@1.0.1", "", { "dependencies": { "streamx": "^2.12.5" } }, "sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg=="],
 
@@ -1104,6 +1099,8 @@
 
     "ajv-formats/ajv": ["ajv@8.18.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A=="],
 
+    "archiver/tar-stream": ["tar-stream@3.1.8", "", { "dependencies": { "b4a": "^1.6.4", "bare-fs": "^4.5.5", "fast-fifo": "^1.2.0", "streamx": "^2.15.0" } }, "sha512-U6QpVRyCGHva435KoNWy9PRoi2IFYCgtEhq9nmrPPpbRacPs9IH4aJ3gbrFC8dPcXvdSZ4XXfXT5Fshbp2MtlQ=="],
+
     "cross-spawn/which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
 
     "ecdsa-sig-formatter/safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],

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
 ```
 
@@ -191,7 +173,6 @@ sequenceDiagram
 | `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                                      |

package/docs/architecture/security.md

@@ -20,18 +20,19 @@ graph TB
     FIND_RULE -->|"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"| HIGH_CHECK{"shouldAutoAllowHighRisk()<br/>(containerized bash?)"}
+    HIGH_CHECK -->|"yes"| AUTO_ALLOW
+    HIGH_CHECK -->|"no"| 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 +50,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 +72,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 +165,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). 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.
 
 ### Canonical Paths
 
@@ -272,18 +272,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/backup-troubleshooting.md

@@ -0,0 +1,52 @@
+# Backup — Troubleshooting
+
+Operational procedures for diagnosing and recovering from snapshot issues.
+
+## "snapshot in progress" errors that don't clear
+
+### Symptom
+
+Backup CLI commands (`vellum backup create`) and scheduled snapshot ticks repeatedly fail with one of:
+
+- `snapshot in progress (locked by pid <N>)`
+- `snapshot in progress (lock holder unidentified; possible partial write)`
+- `snapshot in progress (lock contended)`
+
+The errors persist across retries and do not resolve on their own.
+
+### Cause
+
+The snapshot system uses a cross-process lock file to prevent two processes from running the backup pipeline concurrently (which could corrupt backup bundles or race the retention pruner). The lock file is created atomically via `O_CREAT | O_EXCL` and contains the holder's PID.
+
+In rare cases a writer can crash after creating the lock file but before writing its PID, leaving a zero-byte or malformed lock file with no live holder. The acquire loop cannot safely unlink such a file (it could belong to a live holder that has just won `O_EXCL` but not yet flushed its PID), so it surfaces contention indefinitely.
+
+### Recovery
+
+1. Confirm no backup is actually in progress — check the assistant log for recent `snapshot-worker` activity and look for a running process holding the lock.
+
+2. Inspect the lock file:
+
+   ```bash
+   ls -l ~/.vellum/backups/.snapshot.lock
+   cat ~/.vellum/backups/.snapshot.lock
+   ```
+
+   If the file is empty, zero-byte, or contains no parseable PID, it is stuck debris from a crashed writer.
+
+   If it contains a PID, verify the process is gone:
+
+   ```bash
+   kill -0 <pid> 2>&1  # "No such process" means the holder is dead
+   ```
+
+3. Remove the lock file:
+
+   ```bash
+   rm ~/.vellum/backups/.snapshot.lock
+   ```
+
+4. Retry the backup operation. The next acquire attempt will succeed on the now-empty slot.
+
+### Docker mode
+
+In containerized deployments the backup root is controlled by `VELLUM_BACKUP_DIR` (default `/workspace/.backups/`). The lock file lives one level above the local backups directory — adjust the path in the commands above accordingly, e.g. `/workspace/.backups/.snapshot.lock`.

package/docs/browser-use-architecture-phase2.md

@@ -0,0 +1,174 @@
+# Browser Use Architecture — Phase 2
+
+## 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.
+
+This document describes the runtime architecture, backend precedence rules, 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.                                                              |
+
+## Wire Diagram
+
+```
+macOS app (user message)
+    |
+    v
+POST /v1/messages  { interface: "macos", ... }
+    |
+    v
+conversation-routes.ts
+    |-- setTurnInterfaceContext({ userMessageInterface: "macos", ... })
+    |-- resolveHostBrowserSender()
+    |       |
+    |       +-- ChromeExtensionRegistry.get(guardianId)
+    |               |
+    |               +-- entry found? --> registrySender (WS to extension)
+    |               |                    hostBrowserSenderOverride = registrySender
+    |               |                    provision HostBrowserProxy
+    |               |
+    |               +-- entry not found? --> SSE hub sender (default)
+    |                                        hostBrowserSenderOverride = undefined
+    |
+    v
+Agent loop invokes browser tool
+    |
+    v
+getCdpClient(toolContext)
+    |-- toolContext.hostBrowserProxy set?
+    |       AND hostBrowserProxy.isAvailable()?
+    |       --> candidate: extension (priority 1)
+    |
+    |-- transportInterface === "macos"
+    |       AND desktopAuto.enabled?
+    |       AND cooldown NOT active?
+    |       --> candidate: cdp-inspect (priority 2)
+    |
+    |-- always --> candidate: local (priority 3)
+    |
+    v
+ScopedCdpClient.send(method, params)
+    |
+    +-- Try candidate 1 (extension)
+    |       transport_error? --> failover to candidate 2
+    |       cdp_error? --> propagate immediately (no failover)
+    |       success? --> sticky for remainder of invocation
+    |
+    +-- Try candidate 2 (cdp-inspect)
+    |       transport_error? --> record cooldown, failover to candidate 3
+    |       success? --> sticky
+    |
+    +-- Try candidate 3 (local)
+            last resort -- errors propagate
+```
+
+## 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                                                             |
+
+After the first successful CDP command on any backend, that backend becomes **sticky** for the remainder of the tool invocation.
+
+## Desktop-auto cdp-inspect Cooldown
+
+When cdp-inspect fails with a transport error during a desktop-auto attempt:
+
+1. The factory records `_desktopAutoCooldownSince = Date.now()`.
+2. Subsequent `buildCandidateList()` calls skip cdp-inspect while `Date.now() - cooldownSince < cooldownMs`.
+3. Default cooldown is 30 seconds (`desktopAuto.cooldownMs`).
+4. Cooldown only applies to desktop-auto candidates (reason starts with `"desktopAuto:"`). Explicitly configured cdp-inspect is never suppressed.
+
+## Manual QA Checklist
+
+### Scenario 1: Extension Connected (macOS)
+
+**Setup:**
+
+1. Pair the browser extension (chrome extension installed, `assistant pair browser-extension` completed or cloud pairing via platform).
+2. Open the macOS app and verify the extension WebSocket is connected (check runtime logs for `browser-relay: registered connection`).
+
+**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 real Chrome session (visible browser activity in the user's Chrome, not a separate Playwright window).
+
+**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).
+- Extension WebSocket receives `host_browser_request` frames.
+
+### Scenario 2: Extension Absent + cdp-inspect Enabled
+
+**Setup:**
+
+1. No browser extension connected (or extension not installed).
+2. Launch Chrome with `--remote-debugging-port=9222`.
+3. Optionally set `hostBrowser.cdpInspect.enabled: true` in config (or rely on `desktopAuto.enabled: true` default for macOS).
+
+**Test:**
+
+1. Send a message that triggers browser automation.
+2. Observe the assistant attaches to the existing Chrome via CDP (commands execute in the already-running Chrome, not a new Playwright window).
+
+**Expected telemetry/log signals:**
+
+- `cdp-factory` log: `CDP factory: built candidate list` with `candidates: [{kind: "cdp-inspect", ...}, {kind: "local", ...}]`
+- `cdp-factory` log: `CDP factory: candidate succeeded, backend is now sticky` with `candidateKind: "cdp-inspect"`
+- No `browserManager` launch log (Playwright not started).
+- cdp-inspect discovery log: successful WebSocket connection to `ws://localhost:9222/...`.
+
+### Scenario 3: Extension Absent + cdp-inspect Disabled/Unavailable
+
+**Setup:**
+
+1. No browser extension connected.
+2. Chrome NOT launched with `--remote-debugging-port` (the common default).
+3. `desktopAuto.enabled: true` (default).
+
+**Test:**
+
+1. Send a message that triggers browser automation.
+2. Observe the assistant opens a Playwright-managed Chromium window (sacrificial profile).
+
+**Expected telemetry/log signals:**
+
+- `cdp-factory` log: `CDP factory: built candidate list` with `candidates: [{kind: "cdp-inspect", reason: "desktopAuto: ..."}, {kind: "local", ...}]`
+- `cdp-factory` log: `CDP factory: transport-level failure, failing over to next candidate` with `candidateKind: "cdp-inspect"`
+- `cdp-factory` log: `CDP factory: recording desktop-auto cdp-inspect cooldown after transport failure`
+- `cdp-factory` log: `CDP factory: candidate succeeded, backend is now sticky` with `candidateKind: "local"`
+- `browserManager` launch log visible (Playwright starting).
+- Subsequent turns within 30 seconds: `cdp-factory` log shows `desktop-auto cdp-inspect skipped (cooldown active)` and candidates are `[{kind: "local"}]` only.
+
+### Verifying Which Backend Executed
+
+In all scenarios, the definitive signal is the `cdp-factory` structured log:
+
+```
+CDP factory: candidate succeeded, backend is now sticky
+  candidateKind: "extension" | "cdp-inspect" | "local"
+  conversationId: "<id>"
+  method: "<first CDP method called>"
+```
+
+Filter runtime logs with:
+
+```bash
+grep "cdp-factory" ~/.vellum/workspace/data/logs/vellum.log
+```

package/docs/error-handling.md

@@ -69,3 +69,114 @@ Returning `undefined` is acceptable only for **lookup functions** where "not fou
 | Memory retriever (`memory/retriever.ts`)              | Result object (`MemoryRecallResult`) with degraded/reason fields                | Graceful degradation — embedding failures, search failures degrade quality without crashing                                    |
 | Filesystem tools (`path-policy.ts`, `edit-engine.ts`) | Discriminated union (`{ ok, reason }`)                                          | Validation outcomes that the caller must handle (out of bounds, not found, ambiguous)                                          |
 | Subagent manager (`subagent/manager.ts`)              | Throws for precondition violations, string literal unions for expected outcomes | Depth limit exceeded is a bug; `sendMessage` returns `'not_found' \| 'terminal' \| 'queue_full'` as expected states            |
+| Interactive UI (`cli/commands/ui.ts`)                 | Result object (`InteractiveUiResult`) with `status` + exit codes                | User cancel and timeout are expected operational outcomes, not errors. IPC failures are exceptional.                           |
+
+## 4. Interactive UI interactions (`assistant ui confirm` / `assistant ui request`)
+
+The `assistant ui` commands present blocking interactive surfaces (confirmations, forms) to the user and wait for a response. Their error model distinguishes three categories:
+
+### Expected outcomes (not errors)
+
+User decisions — including declining — are normal operational results:
+
+**`assistant ui confirm`** maps outcomes to exit codes for simple shell branching:
+
+| Status                              | Exit code | Meaning                                                                  |
+| ----------------------------------- | --------- | ------------------------------------------------------------------------ |
+| `submitted` (confirmed)             | 0         | User completed the interaction. Proceed with the gated action.           |
+| `submitted` (denied via `actionId`) | 1         | User explicitly chose the deny/secondary action. Abort gracefully.       |
+| `cancelled`                         | 1         | User dismissed the surface without choosing an action. Abort gracefully. |
+| `timed_out`                         | 1         | No user response within the timeout window. Abort safely.                |
+
+**`assistant ui request`** always exits 0 on successful IPC (regardless of user action). Use `--json` and check the `status` field to branch on user decisions.
+
+Scripts must handle all three non-confirmation outcomes. A `cancelled` status means the user deliberately chose not to proceed — log it as a normal flow, not an error. A `timed_out` status means the user was unresponsive — abort without side effects.
+
+### Cancellation reasons (`ui request` only)
+
+When using `assistant ui request --json`, a `cancelled` result includes a `cancellationReason` field that distinguishes **user-driven** cancellations from **operational fail-closed** cancellations. This allows scripts to choose different recovery strategies depending on why the surface was cancelled.
+
+> **Note:** `assistant ui confirm --json` does not include `cancellationReason`. For confirmations, use the exit code (0 = confirmed, non-zero = denied/cancelled) or check the `status` field.
+
+#### User-driven cancellation
+
+| `cancellationReason` | Meaning                                                                                                                                                                      |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `user_dismissed`     | The user explicitly closed or dismissed the surface (e.g. clicked the close button, pressed Escape). This is a deliberate user choice — handle it the same as a deny action. |
+
+#### Operational (fail-closed) cancellations
+
+These indicate the surface could not be shown or could not complete due to infrastructure/environment conditions. The runtime fails closed to `{ status: "cancelled" }` (a normal `ok: true` result) rather than raising an IPC error, so scripts must inspect `cancellationReason` to distinguish them from user dismissals.
+
+| `cancellationReason`     | Meaning                                                                                                                 |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `no_interactive_surface` | No UI resolver is registered — the channel is headless, API-only, or does not support interactive surfaces.             |
+| `conversation_not_found` | The target conversation could not be located (not in memory and not restorable from storage).                           |
+| `resolver_unavailable`   | A UI resolver is registered but the surface transport is disconnected (e.g. the desktop client dropped its connection). |
+| `resolver_error`         | The UI resolver threw an unexpected error while attempting to show the surface.                                         |
+
+**Why this matters**: A `user_dismissed` cancellation requires no special handling — the user made a conscious choice. An operational cancellation (`no_interactive_surface`, `conversation_not_found`, etc.) may warrant retry logic, a fallback path, or logging for investigation. Scripts that only check `status === "cancelled"` continue to work but cannot differentiate the two categories.
+
+### Operational errors (exceptional)
+
+These indicate infrastructure or configuration problems, not user decisions:
+
+- **IPC unavailable**: The daemon is not running or the socket is unreachable. The CLI exits non-zero with an error message.
+- **No conversation context**: Neither `--conversation-id` nor `__SKILL_CONTEXT_JSON` provided a valid conversation ID.
+- **Invalid payload**: Malformed JSON in `--payload` or stdin.
+
+In `--json` mode, operational errors return `{ "ok": false, "error": "<message>" }`. Without `--json`, they print to stderr and exit non-zero.
+
+### Branching pattern for `ui confirm`
+
+The `ui confirm --json` output includes `ok`, `confirmed`, `status`, `actionId`, `surfaceId`, and optional `decisionToken`/`summary` — but does **not** include `cancellationReason`. Branch on `status` and `confirmed`:
+
+```typescript
+const proc = Bun.spawn(
+  [
+    "assistant",
+    "ui",
+    "confirm",
+    "--title",
+    "Send email",
+    "--message",
+    `Send to ${recipient}?`,
+    "--confirm-label",
+    "Send",
+    "--deny-label",
+    "Cancel",
+    "--json",
+  ],
+  { stdout: "pipe" },
+);
+
+const raw = await new Response(proc.stdout).text();
+const result = JSON.parse(raw);
+
+if (!result.ok) {
+  // Operational error — IPC failure, no conversation, etc.
+  throw new Error(`UI confirm failed: ${result.error}`);
+}
+
+switch (result.status) {
+  case "submitted":
+    if (result.confirmed) {
+      // User confirmed — proceed with the action
+      await sendEmail(draftId);
+    } else {
+      // User denied — abort gracefully
+      return { sent: false, reason: "User declined" };
+    }
+    break;
+  case "cancelled":
+    // User dismissed the surface — treat like a deny
+    return { sent: false, reason: "User dismissed" };
+  case "timed_out":
+    // No response — abort safely
+    return { sent: false, reason: "Timed out" };
+}
+```
+
+For `ui request --json`, the output additionally includes a `cancellationReason` field when `status` is `"cancelled"`, allowing scripts to distinguish user dismissal (`user_dismissed`) from operational failures (`no_interactive_surface`, `conversation_not_found`, etc.). See the [cancellation reasons](#cancellation-reasons-ui-request-only) section above and `skills/AGENTS.md` for the `ui request` branching pattern.
+
+The key distinction: **cancellation and denial are user decisions** (handle gracefully, no error logging). **IPC failures and missing context are bugs** (throw or log as errors).