@vellumai/assistant 0.4.37 → 0.4.40

package/docs/architecture/integrations.md

@@ -190,7 +190,7 @@ sequenceDiagram
 
 #### Dual-Path Operation Architecture
 
-The strategy router (`router.ts`) determines whether to use the OAuth or browser path for each operation. The preferred strategy is read from the `twitterOperationStrategy` config field (default: `auto`).
+The strategy router (`router.ts`) determines whether to use the OAuth or browser path for each operation. The preferred strategy is read from the `twitter.operationStrategy` config field (default: `auto`).
 
 ```mermaid
 flowchart TD
@@ -215,19 +215,19 @@ flowchart TD
 - **`oauth`**: Uses OAuth exclusively. Fails with an actionable error if credentials are not configured.
 - **`browser`**: Uses CDP exclusively. Fails with an actionable error if the browser session has expired.
 
-The strategy is persisted in the Vellum config file as `twitterOperationStrategy` and can be changed via `vellum x strategy set <oauth|browser|auto>`.
+The strategy is persisted in the Vellum config file as `twitter.operationStrategy` and can be changed via `vellum x strategy set <oauth|browser|auto>`.
 
 #### Twitter OAuth2 Specifics
 
-| Aspect | Detail |
-|--------|--------|
-| Auth URL | `https://twitter.com/i/oauth2/authorize` (from provider profile) |
-| Token URL | `https://api.x.com/2/oauth2/token` (from provider profile) |
-| Flow | PKCE (S256), optional client secret, via connect orchestrator |
-| Default scopes | `tweet.read`, `tweet.write`, `users.read`, `offline.access` (from provider profile) |
-| Identity verification | Provider profile `identityVerifier` → `GET https://api.x.com/2/users/me` with Bearer token |
-| Credential names | Canonical: `client_id`, `client_secret`; reads fall back to legacy `oauth_client_id`, `oauth_client_secret` |
-| IPC messages | `oauth_connect_start` / `oauth_connect_result` (generic), plus legacy `twitter_auth_start` / `twitter_auth_status` |
+| Aspect                | Detail                                                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Auth URL              | `https://twitter.com/i/oauth2/authorize` (from provider profile)                                                   |
+| Token URL             | `https://api.x.com/2/oauth2/token` (from provider profile)                                                         |
+| Flow                  | PKCE (S256), optional client secret, via connect orchestrator                                                      |
+| Default scopes        | `tweet.read`, `tweet.write`, `users.read`, `offline.access` (from provider profile)                                |
+| Identity verification | Provider profile `identityVerifier` → `GET https://api.x.com/2/users/me` with Bearer token                         |
+| Credential names      | Canonical: `client_id`, `client_secret`; reads fall back to legacy `oauth_client_id`, `oauth_client_secret`        |
+| IPC messages          | `oauth_connect_start` / `oauth_connect_result` (generic), plus legacy `twitter_auth_start` / `twitter_auth_status` |
 
 #### Twitter Credential Metadata Structure
 
@@ -254,73 +254,73 @@ When the OAuth2 flow completes, the handler stores credential metadata at `integ
 
 #### Available Twitter Tools
 
-| Tool / Command | Mechanism | Description |
-|----------------|-----------|-------------|
-| `vellum x post` | Strategy router (OAuth or CDP) | Post a tweet. Uses the configured strategy (`auto` by default). |
-| `vellum x reply` | Strategy router (OAuth or CDP) | Reply to a tweet. Uses the configured strategy (`auto` by default). |
-| `vellum x timeline` | CDP | Fetch a user's recent tweets. Browser path only. |
-| `vellum x search` | CDP | Search tweets. Browser path only. |
-| `vellum x home` | CDP | Fetch home timeline. Browser path only. |
-| `vellum x notifications` | CDP | Fetch notifications. Browser path only. |
-| `vellum x bookmarks` | CDP | Fetch bookmarks. Browser path only. |
-| `vellum x likes` | CDP | Fetch a user's liked tweets. Browser path only. |
-| `vellum x followers` | CDP | Fetch a user's followers. Browser path only. |
-| `vellum x following` | CDP | Fetch who a user follows. Browser path only. |
-| `vellum x media` | CDP | Fetch a user's media tweets. Browser path only. |
-| `vellum x strategy` | Config | Get or set the operation strategy (`oauth`, `browser`, `auto`). |
-| `vellum x status` | IPC + local | Check browser session, OAuth connection, and strategy status. |
+| Tool / Command           | Mechanism                      | Description                                                         |
+| ------------------------ | ------------------------------ | ------------------------------------------------------------------- |
+| `vellum x post`          | Strategy router (OAuth or CDP) | Post a tweet. Uses the configured strategy (`auto` by default).     |
+| `vellum x reply`         | Strategy router (OAuth or CDP) | Reply to a tweet. Uses the configured strategy (`auto` by default). |
+| `vellum x timeline`      | CDP                            | Fetch a user's recent tweets. Browser path only.                    |
+| `vellum x search`        | CDP                            | Search tweets. Browser path only.                                   |
+| `vellum x home`          | CDP                            | Fetch home timeline. Browser path only.                             |
+| `vellum x notifications` | CDP                            | Fetch notifications. Browser path only.                             |
+| `vellum x bookmarks`     | CDP                            | Fetch bookmarks. Browser path only.                                 |
+| `vellum x likes`         | CDP                            | Fetch a user's liked tweets. Browser path only.                     |
+| `vellum x followers`     | CDP                            | Fetch a user's followers. Browser path only.                        |
+| `vellum x following`     | CDP                            | Fetch who a user follows. Browser path only.                        |
+| `vellum x media`         | CDP                            | Fetch a user's media tweets. Browser path only.                     |
+| `vellum x strategy`      | Config                         | Get or set the operation strategy (`oauth`, `browser`, `auto`).     |
+| `vellum x status`        | IPC + local                    | Check browser session, OAuth connection, and strategy status.       |
 
 Note: OAuth2 scopes (`tweet.read`, `tweet.write`, `users.read`, `offline.access`) are requested during the auth flow. The `post` and `reply` operations use these tokens when the OAuth path is selected. Read operations require the browser path.
 
 ### Key Design Decisions
 
-| Decision | Rationale |
-|----------|-----------|
-| PKCE by default, optional client_secret | Desktop apps prefer PKCE; some providers (Slack) require a secret, which is stored in credential metadata for autonomous refresh |
-| Shared connect orchestrator | All OAuth providers route through `orchestrateOAuthConnect()`, which resolves profiles, enforces scope policy, runs the flow, stores tokens, and verifies identity. Adding a provider is a declarative profile entry, not new orchestration code |
-| Canonical credential naming | Writes use `client_id`/`client_secret`; reads fall back to legacy `oauth_client_id`/`oauth_client_secret` for backward compatibility |
-| Gateway callback transport | OAuth callbacks are now routed through the gateway at `${ingress.publicBaseUrl}/webhooks/oauth/callback` instead of a loopback redirect URI. This enables OAuth flows to work in remote and tunneled deployments. |
-| Unified `MessagingProvider` interface | All platforms implement the same contract; generic tools work immediately for new providers |
-| Twitter outside unified messaging | Twitter is a broadcast/read platform, not a conversation platform — it doesn't fit the `MessagingProvider` contract |
-| Dual-path Twitter strategy | OAuth is more reliable for posting (no browser session dependency) but only supports post/reply. Browser path supports all operations. `auto` strategy gives the best of both: OAuth when possible, browser as fallback. User can override via `vellum x strategy set`. |
-| Provider auto-selection | If only one provider is connected, tools skip the `platform` parameter — seamless single-platform UX |
-| Token expiry in credential metadata | Reuses existing `CredentialMetadata` store; `expiresAt` field enables proactive refresh with 5min buffer |
-| Confidence scores on medium-risk tools | LLM self-reports confidence (0-1); enables future trust calibration without blocking execution |
-| Platform-specific extension tools | Operations unique to one platform (e.g. Gmail labels, Slack reactions) are separate tools, not forced into the generic interface |
-| Twitter identity verification before token storage | OAuth2 tokens are only persisted after a successful `GET /2/users/me` call, preventing storage of invalid or mismatched credentials |
+| Decision                                           | Rationale                                                                                                                                                                                                                                                               |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PKCE by default, optional client_secret            | Desktop apps prefer PKCE; some providers (Slack) require a secret, which is stored in credential metadata for autonomous refresh                                                                                                                                        |
+| Shared connect orchestrator                        | All OAuth providers route through `orchestrateOAuthConnect()`, which resolves profiles, enforces scope policy, runs the flow, stores tokens, and verifies identity. Adding a provider is a declarative profile entry, not new orchestration code                        |
+| Canonical credential naming                        | Writes use `client_id`/`client_secret`; reads fall back to legacy `oauth_client_id`/`oauth_client_secret` for backward compatibility                                                                                                                                    |
+| Gateway callback transport                         | OAuth callbacks are now routed through the gateway at `${ingress.publicBaseUrl}/webhooks/oauth/callback` instead of a loopback redirect URI. This enables OAuth flows to work in remote and tunneled deployments.                                                       |
+| Unified `MessagingProvider` interface              | All platforms implement the same contract; generic tools work immediately for new providers                                                                                                                                                                             |
+| Twitter outside unified messaging                  | Twitter is a broadcast/read platform, not a conversation platform — it doesn't fit the `MessagingProvider` contract                                                                                                                                                     |
+| Dual-path Twitter strategy                         | OAuth is more reliable for posting (no browser session dependency) but only supports post/reply. Browser path supports all operations. `auto` strategy gives the best of both: OAuth when possible, browser as fallback. User can override via `vellum x strategy set`. |
+| Provider auto-selection                            | If only one provider is connected, tools skip the `platform` parameter — seamless single-platform UX                                                                                                                                                                    |
+| Token expiry in credential metadata                | Reuses existing `CredentialMetadata` store; `expiresAt` field enables proactive refresh with 5min buffer                                                                                                                                                                |
+| Confidence scores on medium-risk tools             | LLM self-reports confidence (0-1); enables future trust calibration without blocking execution                                                                                                                                                                          |
+| Platform-specific extension tools                  | Operations unique to one platform (e.g. Gmail labels, Slack reactions) are separate tools, not forced into the generic interface                                                                                                                                        |
+| Twitter identity verification before token storage | OAuth2 tokens are only persisted after a successful `GET /2/users/me` call, preventing storage of invalid or mismatched credentials                                                                                                                                     |
 
 ### 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/activity-analyzer.ts` | Activity classification for conversations |
-| `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/` | Unified messaging skill (SKILL.md, TOOLS.json, tools/) |
-| `assistant/src/watcher/providers/slack.ts` | Slack watcher for DMs, mentions, thread replies |
-| `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/provider-profiles.ts` | Provider profile registry: auth URLs, token URLs, scopes, policies, identity verifiers |
-| `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: `OAuthProviderProfile`, `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 IPC handler (`oauth_connect_start` / `oauth_connect_result`) |
-| `assistant/src/daemon/handlers/twitter-auth.ts` | Legacy Twitter OAuth2 flow handlers (`twitter_auth_start`, `twitter_auth_status`) |
-| `assistant/src/twitter/client.ts` | Twitter CDP client: GraphQL mutations/queries via Chrome DevTools Protocol |
-| `assistant/src/twitter/oauth-client.ts` | OAuth-backed Twitter client: X API v2 post/reply via stored tokens using `withValidToken()` |
-| `assistant/src/twitter/router.ts` | Strategy router: selects OAuth or browser path based on `twitterOperationStrategy` config |
-| `assistant/src/twitter/session.ts` | Twitter browser session persistence (cookie import/export) |
-| `assistant/src/cli/twitter.ts` | `vellum x` CLI command group (post, reply, strategy, refresh, status, login, logout, and read operations) |
-| `assistant/src/config/bundled-skills/twitter/SKILL.md` | X (Twitter) bundled skill instructions |
+| 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/activity-analyzer.ts`         | Activity classification for conversations                                                                 |
+| `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/`       | Unified messaging skill (SKILL.md, TOOLS.json, tools/)                                                    |
+| `assistant/src/watcher/providers/slack.ts`             | Slack watcher for DMs, mentions, thread replies                                                           |
+| `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/provider-profiles.ts`             | Provider profile registry: auth URLs, token URLs, scopes, policies, identity verifiers                    |
+| `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: `OAuthProviderProfile`, `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 IPC handler (`oauth_connect_start` / `oauth_connect_result`)                        |
+| `assistant/src/daemon/handlers/twitter-auth.ts`        | Legacy Twitter OAuth2 flow handlers (`twitter_auth_start`, `twitter_auth_status`)                         |
+| `assistant/src/twitter/client.ts`                      | Twitter CDP client: GraphQL mutations/queries via Chrome DevTools Protocol                                |
+| `assistant/src/twitter/oauth-client.ts`                | OAuth-backed Twitter client: X API v2 post/reply via stored tokens using `withValidToken()`               |
+| `assistant/src/twitter/router.ts`                      | Strategy router: selects OAuth or browser path based on `twitter.operationStrategy` config                |
+| `assistant/src/twitter/session.ts`                     | Twitter browser session persistence (cookie import/export)                                                |
+| `assistant/src/cli/twitter.ts`                         | `vellum x` CLI command group (post, reply, strategy, refresh, status, login, logout, and read operations) |
+| `assistant/src/config/bundled-skills/twitter/SKILL.md` | X (Twitter) bundled skill instructions                                                                    |
 
 ---
 
@@ -332,15 +332,15 @@ The OAuth extensibility layer makes adding a new OAuth provider a declarative op
 
 `assistant/src/oauth/provider-profiles.ts` contains the `PROVIDER_PROFILES` map — a canonical registry of well-known OAuth providers. Each profile (`OAuthProviderProfile`) declares:
 
-| Field | Purpose |
-|-------|---------|
-| `authUrl` / `tokenUrl` | OAuth2 authorization and token endpoints |
-| `defaultScopes` | Scopes requested on every connect attempt |
-| `scopePolicy` | Controls whether additional scopes are allowed (see Scope Policy below) |
-| `callbackTransport` | `'loopback'` (local redirect) or `'gateway'` (public ingress) |
-| `identityVerifier` | Async function that fetches human-readable account info (e.g. `@username`, email) after token exchange |
-| `setup` | Optional metadata for the generic OAuth setup skill (display name, dashboard URL, app type) |
-| `injectionTemplates` | Auto-applied credential injection rules for the script proxy |
+| Field                  | Purpose                                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ |
+| `authUrl` / `tokenUrl` | OAuth2 authorization and token endpoints                                                               |
+| `defaultScopes`        | Scopes requested on every connect attempt                                                              |
+| `scopePolicy`          | Controls whether additional scopes are allowed (see Scope Policy below)                                |
+| `callbackTransport`    | `'loopback'` (local redirect) or `'gateway'` (public ingress)                                          |
+| `identityVerifier`     | Async function that fetches human-readable account info (e.g. `@username`, email) after token exchange |
+| `setup`                | Optional metadata for the generic OAuth setup skill (display name, dashboard URL, app type)            |
+| `injectionTemplates`   | Auto-applied credential injection rules for the script proxy                                           |
 
 Registered providers: `integration:gmail`, `integration:slack`, `integration:notion`, `integration:twitter`. Short aliases (e.g. `gmail`, `twitter`) are resolved via `SERVICE_ALIASES`.
 
@@ -394,18 +394,17 @@ This replaces provider-specific IPC handlers — any provider in the registry ca
 
 ### Key Source Files
 
-| File | Role |
-|------|------|
-| `assistant/src/oauth/provider-profiles.ts` | Provider profile registry and alias resolution |
-| `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 (`OAuthProviderProfile`, `OAuthScopePolicy`, `OAuthConnectResult`) |
-| `assistant/src/oauth/token-persistence.ts` | Token storage: keychain writes, metadata upsert, post-connect hooks |
-| `assistant/src/daemon/handlers/oauth-connect.ts` | Generic `oauth_connect_start` / `oauth_connect_result` IPC handler |
+| File                                             | Role                                                                            |
+| ------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `assistant/src/oauth/provider-profiles.ts`       | Provider profile registry and alias resolution                                  |
+| `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 (`OAuthProviderProfile`, `OAuthScopePolicy`, `OAuthConnectResult`) |
+| `assistant/src/oauth/token-persistence.ts`       | Token storage: keychain writes, metadata upsert, post-connect hooks             |
+| `assistant/src/daemon/handlers/oauth-connect.ts` | Generic `oauth_connect_start` / `oauth_connect_result` IPC handler              |
 
 ---
 
-
 ---
 
 ## Script Proxy — Proxied Bash Execution and Credential Injection
@@ -536,14 +535,14 @@ sequenceDiagram
 
 **Policy decisions** are deterministic and structured:
 
-| Decision | Meaning |
-|---|---|
-| `matched` | Exactly one credential template matches the host — inject it |
-| `ambiguous` | Multiple credential templates match — caller must disambiguate |
-| `missing` | Credentials exist but none match this host — no rewrite |
-| `unauthenticated` | No credentials configured for the session |
+| Decision                 | Meaning                                                                    |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `matched`                | Exactly one credential template matches the host — inject it               |
+| `ambiguous`              | Multiple credential templates match — caller must disambiguate             |
+| `missing`                | Credentials exist but none match this host — no rewrite                    |
+| `unauthenticated`        | No credentials configured for the session                                  |
 | `ask_missing_credential` | A known template pattern matches but no credential is bound to the session |
-| `ask_unauthenticated` | Completely unknown host — prompt for unauthenticated access |
+| `ask_unauthenticated`    | Completely unknown host — prompt for unauthenticated access                |
 
 **Trust rule persistence**: The `createProxyApprovalCallback` in `session-tool-setup.ts` is wired into the session startup path and routes policy "ask" decisions through the existing `PermissionPrompter` UI. Trust rules use the `network_request` tool name (not `proxy:*`) with URL-based scope patterns (e.g., `https://api.example.com/*`), aligning with the `buildCommandCandidates()` allowlist generation in `checker.ts`.
 
@@ -566,10 +565,10 @@ Each proxy session is bound to a conversation and tracks authorized credential I
 
 The proxy generates and manages a local Certificate Authority for MITM interception:
 
-| Component | Location | Purpose |
-|---|---|---|
-| CA cert | `{dataDir}/proxy-ca/ca.pem` | Self-signed root cert (valid 10 years, permissions 0644) |
-| CA key | `{dataDir}/proxy-ca/ca-key.pem` | CA private key (permissions 0600) |
+| Component  | Location                                   | Purpose                                                  |
+| ---------- | ------------------------------------------ | -------------------------------------------------------- |
+| CA cert    | `{dataDir}/proxy-ca/ca.pem`                | Self-signed root cert (valid 10 years, permissions 0644) |
+| CA key     | `{dataDir}/proxy-ca/ca-key.pem`            | CA private key (permissions 0600)                        |
 | Leaf certs | `{dataDir}/proxy-ca/issued/{hostname}.pem` | Per-hostname certs (cached, verified against current CA) |
 
 `ensureLocalCA()` is idempotent — it only generates the CA if the files do not already exist. Leaf certificates are cached and revalidated via `X509Certificate.checkIssued()` to detect stale certs from a previous CA.
@@ -602,20 +601,20 @@ The proxy subsystem intercepts outbound HTTPS requests and injects stored creden
 
 ### Key Source Files
 
-| File | Role |
-|---|---|
-| `assistant/src/tools/network/script-proxy/server.ts` | Proxy server factory — HTTP forwarding, CONNECT handling, MITM dispatch |
-| `assistant/src/tools/network/script-proxy/policy.ts` | Policy engine — evaluates requests against credential templates |
-| `assistant/src/tools/network/script-proxy/mitm-handler.ts` | MITM TLS interception — loopback TLS server, request rewrite, upstream forwarding |
-| `assistant/src/tools/network/script-proxy/connect-tunnel.ts` | Plain CONNECT tunnel — raw TCP bidirectional pipe |
-| `assistant/src/tools/network/script-proxy/http-forwarder.ts` | HTTP proxy forwarder — absolute-URL form forwarding with policy callback |
-| `assistant/src/tools/network/script-proxy/session-manager.ts` | Session lifecycle — create, start, stop, idle timeout, env var generation |
-| `assistant/src/tools/network/script-proxy/certs.ts` | Local CA management — ensureLocalCA, issueLeafCert, getCAPath |
-| `assistant/src/tools/network/script-proxy/logging.ts` | Log sanitization (header/URL redaction) and safe decision trace builders for policy and credential resolution |
-| `assistant/src/tools/network/script-proxy/types.ts` | Type definitions — session, policy decisions, approval callback |
-| `assistant/src/tools/executor.ts` | `persistentDecisionsAllowed` gate — disables trust rule saving for proxied bash |
-| `assistant/src/daemon/session-tool-setup.ts` | `createProxyApprovalCallback` — wired into session startup, uses `network_request` tool name with URL-based trust rules |
-| `assistant/src/permissions/checker.ts` | `network_request` trust rule matching and risk classification (Medium) |
+| File                                                          | Role                                                                                                                    |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `assistant/src/tools/network/script-proxy/server.ts`          | Proxy server factory — HTTP forwarding, CONNECT handling, MITM dispatch                                                 |
+| `assistant/src/tools/network/script-proxy/policy.ts`          | Policy engine — evaluates requests against credential templates                                                         |
+| `assistant/src/tools/network/script-proxy/mitm-handler.ts`    | MITM TLS interception — loopback TLS server, request rewrite, upstream forwarding                                       |
+| `assistant/src/tools/network/script-proxy/connect-tunnel.ts`  | Plain CONNECT tunnel — raw TCP bidirectional pipe                                                                       |
+| `assistant/src/tools/network/script-proxy/http-forwarder.ts`  | HTTP proxy forwarder — absolute-URL form forwarding with policy callback                                                |
+| `assistant/src/tools/network/script-proxy/session-manager.ts` | Session lifecycle — create, start, stop, idle timeout, env var generation                                               |
+| `assistant/src/tools/network/script-proxy/certs.ts`           | Local CA management — ensureLocalCA, issueLeafCert, getCAPath                                                           |
+| `assistant/src/tools/network/script-proxy/logging.ts`         | Log sanitization (header/URL redaction) and safe decision trace builders for policy and credential resolution           |
+| `assistant/src/tools/network/script-proxy/types.ts`           | Type definitions — session, policy decisions, approval callback                                                         |
+| `assistant/src/tools/executor.ts`                             | `persistentDecisionsAllowed` gate — disables trust rule saving for proxied bash                                         |
+| `assistant/src/daemon/session-tool-setup.ts`                  | `createProxyApprovalCallback` — wired into session startup, uses `network_request` tool name with URL-based trust rules |
+| `assistant/src/permissions/checker.ts`                        | `network_request` trust rule matching and risk classification (Medium)                                                  |
 
 ### Runtime Wiring Summary
 
@@ -690,13 +689,13 @@ graph TB
 
 ### Search Capabilities
 
-| Parameter | Type | Description |
-|---|---|---|
-| `mime_type` | string | MIME type filter with wildcard support (`image/*`, `application/pdf`) |
-| `filename` | string | Case-insensitive substring match on original filename |
-| `recency` | enum | Time-based filter: `last_hour`, `last_24_hours`, `last_7_days`, `last_30_days`, `last_90_days` |
-| `conversation_id` | string | Scope results to attachments in a specific conversation |
-| `limit` | number | Maximum results (default 20, max 100) |
+| Parameter         | Type   | Description                                                                                    |
+| ----------------- | ------ | ---------------------------------------------------------------------------------------------- |
+| `mime_type`       | string | MIME type filter with wildcard support (`image/*`, `application/pdf`)                          |
+| `filename`        | string | Case-insensitive substring match on original filename                                          |
+| `recency`         | enum   | Time-based filter: `last_hour`, `last_24_hours`, `last_7_days`, `last_30_days`, `last_90_days` |
+| `conversation_id` | string | Scope results to attachments in a specific conversation                                        |
+| `limit`           | number | Maximum results (default 20, max 100)                                                          |
 
 ### Materialize Safeguards
 
@@ -707,13 +706,12 @@ graph TB
 
 ### Key Source Files
 
-| File | Role |
-|---|---|
-| `assistant/src/tools/assets/search.ts` | `asset_search` tool — cross-thread attachment metadata search with visibility filtering |
-| `assistant/src/tools/assets/materialize.ts` | `asset_materialize` tool — decode and write attachment to sandbox path |
-| `assistant/src/daemon/media-visibility-policy.ts` | Pure policy module — `isAttachmentVisible()`, `filterVisibleAttachments()` |
-| `assistant/src/memory/schema.ts` | `attachments` and `message_attachments` table schemas |
-| `assistant/src/memory/conversation-store.ts` | `getConversationThreadType()` — thread type lookup for visibility context |
+| File                                              | Role                                                                                    |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `assistant/src/tools/assets/search.ts`            | `asset_search` tool — cross-thread attachment metadata search with visibility filtering |
+| `assistant/src/tools/assets/materialize.ts`       | `asset_materialize` tool — decode and write attachment to sandbox path                  |
+| `assistant/src/daemon/media-visibility-policy.ts` | Pure policy module — `isAttachmentVisible()`, `filterVisibleAttachments()`              |
+| `assistant/src/memory/schema.ts`                  | `attachments` and `message_attachments` table schemas                                   |
+| `assistant/src/memory/conversation-store.ts`      | `getConversationThreadType()` — thread type lookup for visibility context               |
 
 ---
-

package/docs/runbook-trusted-contacts.md

@@ -50,7 +50,7 @@ curl -s "$BASE/v1/contacts" \
 ### Via CLI
 
 ```bash
-vellum contacts list --role contact
+assistant contacts list --role contact
 ```
 
 Response shape:

package/docs/trusted-contact-access.md

@@ -35,7 +35,7 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 5. **Guardian receives the verification code.** The assistant delivers the code to the guardian's verified channel (Telegram chat, SMS, etc.).
 6. **Guardian gives the code to the requester out-of-band** (in person, text message, phone call, etc.). This out-of-band transfer is the trust anchor: it proves the requester has a real-world relationship with the guardian.
 7. **Requester enters the code** back to the assistant on the same channel. The inbound message handler intercepts bare 6-digit codes when a pending verification session exists for that channel.
-8. **Assistant verifies the code and activates the user.** `validateAndConsumeChallenge()` hashes the code, matches it against the pending session, verifies identity binding (the code must come from the expected channel identity), consumes the challenge, and calls `upsertMember()` with `status: 'active'` and `policy: 'allow'`.
+8. **Assistant verifies the code and activates the user.** `validateAndConsumeChallenge()` hashes the code, matches it against the pending session, verifies identity binding (the code must come from the expected channel identity), consumes the challenge, and calls `upsertContactChannel()` with `status: 'active'` and `policy: 'allow'`.
 9. **All subsequent messages are accepted normally.** The ingress ACL finds an active member record and allows the message through.
 
 ## Lifecycle States
@@ -92,11 +92,11 @@ Identity binding ensures the verification code can only be consumed by the inten
 
 ### Stage: `active` (code verified, trusted contact created)
 
-| Store                       | Table                                      | Record                                                                                                                                                                                              |
-| --------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `contacts-write.ts`         | `contacts` / `contact_channels`            | Upserted via `upsertMember()`: creates a contact record and a `contact_channels` entry with `status: 'active'`, `policy: 'allow'`, channel type, `externalUserId`, `externalChatId`, `displayName`. |
-| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | Updated to `status: 'consumed'`, `consumedByExternalUserId`, `consumedByChatId` set.                                                                                                                |
-| `channel-guardian-store.ts` | `channel_guardian_rate_limits`             | Reset via `resetRateLimit()` on successful verification.                                                                                                                                            |
+| Store                       | Table                                      | Record                                                                                                                                                                                                      |
+| --------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contacts-write.ts`         | `contacts` / `contact_channels`            | Upserted via `upsertContactChannel()`: creates a contact record and a `contact_channels` entry with `status: 'active'`, `policy: 'allow'`, channel type, `externalUserId`, `externalChatId`, `displayName`. |
+| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | Updated to `status: 'consumed'`, `consumedByExternalUserId`, `consumedByChatId` set.                                                                                                                        |
+| `channel-guardian-store.ts` | `channel_guardian_rate_limits`             | Reset via `resetRateLimit()` on successful verification.                                                                                                                                                    |
 
 ### Stage: `denied` (guardian rejected)
 
@@ -132,15 +132,15 @@ Voice calls have a dedicated in-call guardian approval flow that differs from th
 3. On name capture, `notifyGuardianOfAccessRequest` creates a canonical guardian request (`kind: 'access_request'`) and notifies the guardian.
 4. Relay transitions to `awaiting_guardian_decision` and polls `canonical_guardian_requests` for status changes.
 5. Guardian approves or denies via any channel. All decisions route through `applyCanonicalGuardianDecision`.
-6. On approval: the `access_request` resolver directly activates the caller as a trusted contact (`upsertMember` with `status: 'active'`, `policy: 'allow'`) — no verification session needed since the caller is already authenticated by their phone number.
+6. On approval: the `access_request` resolver directly activates the caller as a trusted contact (`upsertContactChannel` with `status: 'active'`, `policy: 'allow'`) — no verification session needed since the caller is already authenticated by their phone number.
 7. On denial or timeout: the caller hears a denial message and the call ends.
 
 **Key difference from text-channel flow:** Voice approvals skip the verification session step because the caller's phone identity is already known from the active call. Text-channel approvals still mint a 6-digit verification code for out-of-band identity confirmation.
 
-| Store                         | Table                           | Record                                                                                |
-| ----------------------------- | ------------------------------- | ------------------------------------------------------------------------------------- |
-| `canonical-guardian-store.ts` | `canonical_guardian_requests`   | `kind: 'access_request'`, `status: 'pending'` -> `'approved'` or `'denied'`           |
-| `contacts-write.ts`           | `contacts` / `contact_channels` | On approval: upserted via `upsertMember()` with `status: 'active'`, `policy: 'allow'` |
+| Store                         | Table                           | Record                                                                                        |
+| ----------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
+| `canonical-guardian-store.ts` | `canonical_guardian_requests`   | `kind: 'access_request'`, `status: 'pending'` -> `'approved'` or `'denied'`                   |
+| `contacts-write.ts`           | `contacts` / `contact_channels` | On approval: upserted via `upsertContactChannel()` with `status: 'active'`, `policy: 'allow'` |
 
 ## Sequence Diagram
 
@@ -174,7 +174,7 @@ sequenceDiagram
         A->>A: validateAndConsumeChallenge()
         A->>A: Identity check: actorId matches expected
         A->>A: Hash matches, not expired → consume
-        A->>A: upsertMember(status: 'active', policy: 'allow')
+        A->>A: upsertContactChannel(status: 'active', policy: 'allow')
         A-->>U: "Verification successful! You now have access."
 
         U->>A: Subsequent messages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.4.37",
+  "version": "0.4.40",
   "type": "module",
   "bin": {
     "assistant": "./src/index.ts"
@@ -39,6 +39,7 @@
     "croner": "^10.0.1",
     "dotenv": "^17.3.1",
     "drizzle-orm": "^0.38.4",
+    "esbuild": "^0.24.0",
     "ink": "^6.7.0",
     "jszip": "^3.10.1",
     "minimatch": "^10.2.4",
@@ -46,6 +47,7 @@
     "pino": "^9.6.0",
     "pino-pretty": "^13.1.3",
     "playwright": "^1.58.2",
+    "preact": "^10.25.0",
     "postgres": "^3.4.8",
     "qrcode": "^1.5.4",
     "react": "^19.2.4",

package/src/__tests__/__snapshots__/ipc-snapshot.test.ts.snap

@@ -628,13 +628,6 @@ exports[`IPC message snapshots ClientMessage types share_app_cloud serializes to
 }
 `;
 
-exports[`IPC message snapshots ClientMessage types share_to_slack serializes to expected JSON 1`] = `
-{
-  "appId": "app-001",
-  "type": "share_to_slack",
-}
-`;
-
 exports[`IPC message snapshots ClientMessage types slack_webhook_config serializes to expected JSON 1`] = `
 {
   "action": "get",
@@ -2234,13 +2227,6 @@ exports[`IPC message snapshots ServerMessage types share_app_cloud_response seri
 }
 `;
 
-exports[`IPC message snapshots ServerMessage types share_to_slack_response serializes to expected JSON 1`] = `
-{
-  "success": true,
-  "type": "share_to_slack_response",
-}
-`;
-
 exports[`IPC message snapshots ServerMessage types slack_webhook_config_response serializes to expected JSON 1`] = `
 {
   "success": true,