@vellumai/assistant 0.4.43 → 0.4.45

package/docs/architecture/integrations.md

@@ -2,14 +2,13 @@
 
 OAuth, messaging adapters, script proxy, and asset-tool architecture.
 
-## Integrations — OAuth2 + Unified Messaging + Twitter
+## Integrations — OAuth2 + Unified Messaging
 
 The integration framework lets Vellum connect to third-party services via OAuth2. The architecture follows these principles:
 
 - **Secrets never reach the LLM** — OAuth tokens are stored in the credential vault and accessed exclusively through the `TokenManager`, which provides tokens to tool executors via `withValidToken()`. The LLM never sees raw tokens.
-- **PKCE or client_secret flows** — Desktop apps use PKCE by default (S256). Providers that require a client secret (e.g. Slack) pass it during the OAuth2 flow and store it in credential metadata for autonomous refresh. Twitter uses PKCE with an optional client secret in `local_byo` mode.
+- **PKCE or client_secret flows** — Desktop apps use PKCE by default (S256). Providers that require a client secret (e.g. Slack) pass it during the OAuth2 flow and store it in credential metadata for autonomous refresh.
 - **Unified messaging layer** — All messaging platforms implement the `MessagingProvider` interface. Generic tools delegate to the provider, so adding a new platform is just implementing one adapter + an OAuth setup skill.
-- **Standalone integrations** — Not all integrations fit the messaging model. Twitter has its own OAuth2 flow and HTTP handlers (`twitter_auth_start`, `twitter_auth_status`) separate from the unified messaging layer.
 - **Provider registry** — Messaging providers register at daemon startup. The registry tracks which providers have stored credentials, enabling auto-selection when only one is connected.
 
 ### Unified Messaging Architecture
@@ -17,39 +16,67 @@ The integration framework lets Vellum connect to third-party services via OAuth2
 ```mermaid
 graph TB
     subgraph "Messaging Skill (bundled-skills/messaging/)"
-        SKILL_MD["SKILL.md<br/>agent instructions"]
-        TOOLS_JSON["TOOLS.json<br/>tool manifest"]
-        subgraph "Generic Tools"
-            AUTH_TEST["messaging_auth_test"]
-            LIST["messaging_list_conversations"]
-            READ["messaging_read"]
-            SEARCH["messaging_search"]
-            SEND["messaging_send"]
-            REPLY["messaging_reply"]
-            MARK_READ["messaging_mark_read"]
-            ACTIVITY["messaging_analyze_activity"]
-            STYLE["messaging_analyze_style"]
-            DRAFT["messaging_draft"]
-        end
-        subgraph "Slack-specific Tools"
-            REACT["slack_add_reaction"]
-            LEAVE["slack_leave_channel"]
-        end
-        subgraph "Gmail-specific Tools"
-            ARCHIVE["gmail_archive"]
-            LABEL["gmail_label"]
-            TRASH["gmail_trash"]
-            UNSUB["gmail_unsubscribe"]
-            GMAIL_DRAFT["gmail_draft"]
-        end
+        MSG_SKILL_MD["SKILL.md<br/>agent instructions"]
+        MSG_TOOLS_JSON["TOOLS.json<br/>tool manifest"]
+        AUTH_TEST["messaging_auth_test"]
+        LIST["messaging_list_conversations"]
+        READ["messaging_read"]
+        SEARCH["messaging_search"]
+        SEND["messaging_send (+ reply via thread_id)"]
+        MARK_READ["messaging_mark_read"]
+        STYLE["messaging_analyze_style"]
+        DRAFT["messaging_draft"]
+        SENDER_DIGEST["messaging_sender_digest"]
+        ARCHIVE_BY_SENDER["messaging_archive_by_sender"]
         SHARED["shared.ts<br/>resolveProvider + withProviderToken"]
     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/)"
+        SLACK_SKILL_MD["SKILL.md<br/>agent instructions"]
+        SLACK_SCAN["slack_scan_digest"]
+        SLACK_DETAILS["slack_channel_details"]
+        SLACK_CONFIGURE["slack_configure_channels"]
+        SLACK_REACT["slack_add_reaction"]
+        SLACK_DELETE["slack_delete_message"]
+        SLACK_EDIT["slack_edit_message"]
+        SLACK_LEAVE["slack_leave_channel"]
+        SLACK_PERMS["slack_channel_permissions"]
+    end
+
+    subgraph "Sequences Skill (bundled-skills/sequences/)"
+        SEQ_SKILL_MD["SKILL.md<br/>agent instructions"]
+        SEQ_CREATE["sequence_create"]
+        SEQ_LIST["sequence_list"]
+        SEQ_GET["sequence_get"]
+        SEQ_UPDATE["sequence_update"]
+        SEQ_DELETE["sequence_delete"]
+        SEQ_ENROLL["sequence_enroll"]
+        SEQ_ENROLLMENT_LIST["sequence_enrollment_list"]
+        SEQ_IMPORT["sequence_import"]
+        SEQ_ANALYTICS["sequence_analytics"]
+    end
+
     subgraph "Messaging Layer (messaging/)"
         PROVIDER_IF["MessagingProvider interface"]
         REGISTRY["Provider Registry"]
         TYPES["Platform-agnostic types<br/>Conversation, Message, SearchResult"]
-        ACTIVITY_ANALYZER["Activity Analyzer"]
         STYLE_ANALYZER["Style Analyzer"]
         DRAFT_STORE["Draft Store"]
     end
@@ -78,10 +105,9 @@ graph TB
     LIST --> SHARED
     SEARCH --> SHARED
     SEND --> SHARED
-    REACT --> SLACK_ADAPTER
-    ARCHIVE --> GMAIL_ADAPTER
-    ACTIVITY --> ACTIVITY_ANALYZER
     STYLE --> STYLE_ANALYZER
+    GMAIL_ARCHIVE --> GMAIL_ADAPTER
+    SLACK_REACT --> SLACK_ADAPTER
 ```
 
 ### Data Flow
@@ -89,7 +115,7 @@ graph TB
 ```mermaid
 sequenceDiagram
     participant UI as Settings UI (Swift)
-    participant IPC as IPC Socket
+    participant HTTP as HTTP Transport
     participant Handler as Daemon Handlers
     participant Registry as IntegrationRegistry
     participant OAuth as OAuth2 PKCE Flow
@@ -101,15 +127,15 @@ sequenceDiagram
     participant API as Gmail REST API
 
     Note over UI,API: Connection Flow
-    UI->>IPC: integration_connect {integrationId: "gmail"}
-    IPC->>Handler: dispatch
+    UI->>HTTP: integration_connect {integrationId: "gmail"}
+    HTTP->>Handler: dispatch
     Handler->>Registry: getIntegration("gmail")
     Registry-->>Handler: IntegrationDefinition
     Handler->>OAuth: startOAuth2Flow(config)
     OAuth->>OAuth: generate code_verifier + code_challenge (S256)
     OAuth->>OAuth: start Bun.serve on random port
-    OAuth->>IPC: open_url (Google consent URL)
-    IPC->>Browser: open URL
+    OAuth->>HTTP: open_url (Google consent URL)
+    HTTP->>Browser: open URL
     Browser->>Google: user authorizes
     Google->>OAuth: callback with auth code
     OAuth->>Google: exchange code + code_verifier for tokens
@@ -117,8 +143,8 @@ sequenceDiagram
     OAuth->>Vault: setSecureKey (access + refresh)
     OAuth->>Vault: upsertCredentialMetadata (allowedTools, expiresAt)
     OAuth-->>Handler: success + account email
-    Handler->>IPC: integration_connect_result {success, accountInfo}
-    IPC->>UI: show connected state
+    Handler->>HTTP: integration_connect_result {success, accountInfo}
+    HTTP->>UI: show connected state
 
     Note over UI,API: Tool Execution Flow
     Tool->>TokenMgr: withValidToken("gmail", callback)
@@ -137,185 +163,46 @@ sequenceDiagram
     end
 ```
 
-### Twitter Integration Architecture
-
-Twitter uses a standalone OAuth2 flow separate from the unified messaging layer. It supports a dual-path operation architecture: an **OAuth path** that calls X API v2 directly for posting and replying, and a **Browser path** that uses Chrome DevTools Protocol (CDP) for all operations including read-only ones. A strategy router (`router.ts`) selects the appropriate path based on user preference and capability.
-
-#### Twitter OAuth2 Flow
-
-Twitter's OAuth2 flow delegates to the shared **connect orchestrator** (`oauth/connect-orchestrator.ts`). The Twitter provider profile in the registry defines auth/token URLs, default scopes, and an identity verifier. The daemon handler (`daemon/handlers/oauth-connect.ts`) resolves credentials from the keychain using canonical names (`client_id`, `client_secret`), then calls `orchestrateOAuthConnect()`.
-
-```mermaid
-sequenceDiagram
-    participant UI as Settings UI (Swift)
-    participant IPC as IPC Socket
-    participant Handler as oauth-connect handler
-    participant Orchestrator as ConnectOrchestrator
-    participant ScopePolicy as Scope Policy
-    participant OAuth as OAuth2 PKCE Flow
-    participant Browser as System Browser
-    participant Twitter as Twitter OAuth Server
-    participant Vault as Credential Vault
-    participant API as X API (v2)
-
-    Note over UI,API: Connection Flow (via generic orchestrator)
-    UI->>IPC: oauth_connect_start {service: "twitter"}
-    IPC->>Handler: dispatch
-    Handler->>Handler: resolve client_id / client_secret from keychain
-    Handler->>Orchestrator: orchestrateOAuthConnect(options)
-    Orchestrator->>Orchestrator: resolveService("twitter") → "integration:twitter"
-    Orchestrator->>Orchestrator: getProviderProfile("integration:twitter")
-    Orchestrator->>ScopePolicy: resolveScopes(profile, requestedScopes)
-    ScopePolicy-->>Orchestrator: {ok: true, scopes}
-    Orchestrator->>OAuth: startOAuth2Flow(config)
-    OAuth->>OAuth: generate code_verifier + code_challenge (S256)
-    OAuth->>IPC: open_url (twitter.com/i/oauth2/authorize)
-    IPC->>Browser: open URL
-    Browser->>Twitter: user authorizes
-    Twitter->>OAuth: callback with auth code
-    OAuth->>Twitter: exchange code + code_verifier at api.x.com/2/oauth2/token
-    Twitter-->>OAuth: access + refresh tokens
-    OAuth-->>Orchestrator: tokens + grantedScopes
-    Orchestrator->>API: identityVerifier → GET /2/users/me
-    API-->>Orchestrator: username
-    Orchestrator->>Vault: storeOAuth2Tokens (access + refresh + metadata)
-    Orchestrator-->>Handler: {success, grantedScopes, accountInfo: "@username"}
-    Handler->>IPC: oauth_connect_result {success, accountInfo}
-    IPC->>UI: show connected state
-```
-
-#### 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 `twitter.operationStrategy` config field (default: `auto`).
-
-```mermaid
-flowchart TD
-    CLI["vellum x post / reply"] --> Router["Strategy Router (router.ts)"]
-    Router --> StratCheck{Preferred strategy?}
-
-    StratCheck -->|oauth| OAuthOnly["OAuth Client (oauth-client.ts)"]
-    OAuthOnly --> XAPI["X API v2 POST /tweets"]
-
-    StratCheck -->|browser| BrowserOnly["Browser Client (client.ts)"]
-    BrowserOnly --> CDP["Chrome CDP GraphQL mutation"]
-
-    StratCheck -->|auto| AutoCheck{"OAuth available &\noperation supported?"}
-    AutoCheck -->|yes| TryOAuth["Try OAuth Client"]
-    TryOAuth -->|success| XAPI
-    TryOAuth -->|failure| Fallback["Fallback to Browser Client"]
-    Fallback --> CDP
-    AutoCheck -->|no| BrowserOnly
-```
-
-- **`auto`** (default): Checks `oauthIsAvailable()` (access token stored) and `oauthSupportsOperation()` (currently `post` and `reply`). If both pass, tries OAuth first. On OAuth failure, falls back to browser. If OAuth is not available or the operation is unsupported, uses browser directly.
-- **`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 `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      | `client_id`, `client_secret`                                                                                       |
-| HTTP endpoints        | `oauth_connect_start` / `oauth_connect_result` (generic), plus legacy `twitter_auth_start` / `twitter_auth_status` |
-
-#### Twitter Credential Metadata Structure
-
-When the OAuth2 flow completes, the handler stores credential metadata at `integration:twitter` / `access_token`:
-
-```
-{
-  accountInfo: "@username",
-  allowedTools: ["twitter_post"],
-  allowedDomains: [],
-  oauth2TokenUrl: "https://api.x.com/2/oauth2/token",
-  oauth2ClientId: "<user's client ID>",
-  oauth2ClientSecret: "<optional>",
-  grantedScopes: ["tweet.read", "tweet.write", "users.read", "offline.access"],
-  expiresAt: <epoch ms>
-}
-```
-
-#### Twitter Operation Paths
-
-**OAuth path** (`oauth-client.ts`): The `oauthPostTweet` function calls X API v2 (`POST https://api.x.com/2/tweets`) with a Bearer token obtained via `withValidToken('integration:twitter', ...)`. The token manager handles automatic refresh if the stored token is expired. Supports `post` and `reply` (by including `reply.in_reply_to_tweet_id` in the request body). All other operations (timeline, search, etc.) throw `UnsupportedOAuthOperationError` and are not available via this path.
-
-**Browser path** (`client.ts`): Connects to Chrome via CDP (`localhost:9222`), finds an authenticated x.com tab, and executes GraphQL mutations/queries through the browser's session cookies. Supports all operations including read-only ones (timeline, search, home, notifications, bookmarks, likes, followers, following, media). Session management is handled by Ride Shotgun recordings (`vellum x refresh`).
-
-#### 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.       |
-
-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                        | All reads and writes use `client_id`/`client_secret` as canonical field names                                                                                                                                                                                           |
-| 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                | All reads and writes use `client_id`/`client_secret` as canonical field names                                                                                                                                                                    |
+| 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                                                                                                                                                      |
+| 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                                                                                                                 |
+| Identity verification before token storage | OAuth2 tokens are only persisted after a successful identity verification 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/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 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/cli/commands/twitter/client.ts`         | Twitter CDP client: GraphQL mutations/queries via Chrome DevTools Protocol                                |
-| `assistant/src/cli/commands/twitter/oauth-client.ts`   | OAuth-backed Twitter client: X API v2 post/reply via stored tokens using `withValidToken()`               |
-| `assistant/src/cli/commands/twitter/router.ts`         | Strategy router: selects OAuth or browser path based on `twitter.operationStrategy` config                |
-| `assistant/src/cli/commands/twitter/session.ts`        | Twitter browser session persistence (cookie import/export)                                                |
-| `assistant/src/cli/commands/twitter/index.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/style-analyzer.ts`      | Writing style extraction from message corpus                                                       |
+| `assistant/src/messaging/draft-store.ts`         | Local draft storage (platform/id JSON files)                                                       |
+| `assistant/src/messaging/providers/slack/`       | Slack adapter, client, types                                                                       |
+| `assistant/src/messaging/providers/gmail/`       | Gmail adapter, client, types                                                                       |
+| `assistant/src/config/bundled-skills/messaging/` | Core messaging skill (send, read, search, reply across platforms)                                  |
+| `assistant/src/config/bundled-skills/gmail/`     | Gmail management skill (archive, label, triage, declutter)                                         |
+| `assistant/src/config/bundled-skills/sequences/` | Email sequence management skill (drip campaigns, enrollment, analytics)                            |
+| `assistant/src/watcher/providers/gmail.ts`       | Gmail watcher using History API                                                                    |
+| `assistant/src/watcher/providers/github.ts`      | GitHub watcher for PRs, issues, review requests, and mentions                                      |
+| `assistant/src/watcher/providers/linear.ts`      | Linear watcher for assigned issues, status changes, and @mentions                                  |
+| `assistant/src/oauth/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 handler (`oauth_connect_start` / `oauth_connect_result`)                     |
 
 ---
 
@@ -337,7 +224,7 @@ The OAuth extensibility layer makes adding a new OAuth provider a declarative op
 | `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`.
+Registered providers: `integration:gmail`, `integration:slack`, `integration:notion`. Short aliases (e.g. `gmail`, `slack`) are resolved via `SERVICE_ALIASES`.
 
 ### Scope Policy Engine
 
@@ -366,7 +253,7 @@ Returns `{ ok: true, scopes }` or `{ ok: false, error, allowedScopes }`.
 
 Result is a discriminated union: `{ success, deferred, grantedScopes, accountInfo }` or `{ success: false, error }`.
 
-### Generic Daemon IPC
+### Generic Daemon HTTP API
 
 `assistant/src/daemon/handlers/oauth-connect.ts` handles `oauth_connect_start` messages. The handler:
 

package/docs/architecture/keychain-broker.md

@@ -61,7 +61,7 @@ graph LR
 | `assistant/src/security/secure-keys.ts`            | Unified API surface. Sync variants use encrypted store only. Async variants (`getSecureKeyAsync`, `setSecureKeyAsync`, `deleteSecureKeyAsync`) try broker first. **Reads** fall back to the encrypted store when the broker is unavailable or key is not found. **Writes** return `false` on broker failure (no encrypted-store fallback). **Deletes** return `"deleted"`, `"not-found"`, or `"error"` to let callers distinguish idempotent no-ops from real failures. |
 | `gateway/src/credential-reader.ts`                 | Read-only credential reader. Tries broker via native async UDS connection (`node:net`), falls back to encrypted store. All public credential read functions are async.                                                                                                                                                                                                                                                                                                  |
 
-## IPC Contract
+## Message Contract
 
 ### Transport
 

package/docs/architecture/memory.md

@@ -7,7 +7,7 @@ Assistant memory and context-injection architecture details.
 ```mermaid
 graph TB
     subgraph "Write Path"
-        MSG_IN["Incoming Message<br/>(IPC or HTTP)"]
+        MSG_IN["Incoming Message<br/>(HTTP)"]
         STORE["ConversationStore.addMessage()<br/>Drizzle ORM → SQLite"]
         INDEX["Memory Indexer"]
         SEGMENT["Split into segments<br/>→ memory_segments"]
@@ -242,7 +242,7 @@ Two trust gates enforce trust-class-based access control over the memory pipelin
 
 - **Read gate** (`session-memory.ts`): When the current session's actor is untrusted, the memory recall pipeline returns a no-op context — no recall injection, no dynamic profile, no conflict resolution. This ensures untrusted actors cannot surface or exploit previously extracted memory.
 
-Trust policy is **cross-channel and trust-class-based**: decisions use `trustContext.trustClass`, not the channel string. Desktop/IPC sessions default to `trustClass: 'guardian'`. External channels (Telegram, SMS, WhatsApp, phone) provide explicit trust context via the resolver. Messages without provenance metadata are treated as trusted (guardian); all new messages carry provenance.
+Trust policy is **cross-channel and trust-class-based**: decisions use `trustContext.trustClass`, not the channel string. Desktop sessions default to `trustClass: 'guardian'`. External channels (Telegram, SMS, WhatsApp, phone) provide explicit trust context via the resolver. Messages without provenance metadata are treated as trusted (guardian); all new messages carry provenance.
 
 ---
 

package/docs/architecture/scheduling.md

@@ -104,7 +104,7 @@ One reminder creates one notification signal. The routing intent on that single
 
 Channel availability is resolved when the signal is emitted (not when the reminder is created):
 
-- **Vellum** — always connected (local IPC)
+- **Vellum** — always connected (local HTTP)
 - **Telegram** — connected when an active guardian binding exists
 - **SMS** — connected when an active guardian binding exists
 

package/docs/architecture/security.md

@@ -179,7 +179,7 @@ File tool candidates include canonical (symlink-resolved) absolute paths via `no
 | `assistant/src/permissions/checker.ts`        | `classifyRisk()`, `check()`, `buildCommandCandidates()`, allowlist/scope generation                                                                                                 |
 | `assistant/src/permissions/shell-identity.ts` | `analyzeShellCommand()`, `deriveShellActionKeys()`, `buildShellCommandCandidates()`, `buildShellAllowlistOptions()` — parser-based shell command identity and action key derivation |
 | `assistant/src/permissions/trust-store.ts`    | Rule persistence, `findHighestPriorityRule()`, execution-target matching, starter bundle                                                                                            |
-| `assistant/src/permissions/prompter.ts`       | IPC prompt flow: `confirmation_request` → `confirmation_response`                                                                                                                   |
+| `assistant/src/permissions/prompter.ts`       | HTTP prompt flow: `confirmation_request` → `confirmation_response`                                                                                                                   |
 | `assistant/src/permissions/defaults.ts`       | Default rule templates (system ask rules for host tools, CU, etc.)                                                                                                                  |
 | `assistant/src/skills/version-hash.ts`        | `computeSkillVersionHash()` — deterministic SHA-256 of skill source files                                                                                                           |
 | `assistant/src/skills/path-classifier.ts`     | `isSkillSourcePath()`, `normalizeFilePath()`, skill root detection                                                                                                                  |
@@ -220,30 +220,30 @@ sequenceDiagram
     participant Model as LLM
     participant Vault as credential_store tool
     participant Prompter as SecretPrompter
-    participant IPC as IPC Socket
+    participant HTTP as HTTP Transport
     participant UI as SecretPromptManager (Swift)
     participant Keychain as macOS Keychain
 
     Model->>Vault: action: "prompt", service, field, label
     Vault->>Prompter: requestSecret(service, field, label, ...)
-    Prompter->>IPC: secret_request {requestId, service, field, label, allowOneTimeSend}
-    IPC->>UI: Show SecretPromptView (floating panel)
+    Prompter->>HTTP: secret_request {requestId, service, field, label, allowOneTimeSend}
+    HTTP->>UI: Show SecretPromptView (floating panel)
     UI->>UI: User enters value in SecureField
     alt Store (default)
-        UI->>IPC: secret_response {requestId, value, delivery: "store"}
-        IPC->>Prompter: resolve(value, "store")
+        UI->>HTTP: secret_response {requestId, value, delivery: "store"}
+        HTTP->>Prompter: resolve(value, "store")
         Prompter->>Vault: {value, delivery: "store"}
         Vault->>Keychain: setSecureKey("credential:svc:field", value)
         Vault->>Model: "Credential stored securely" (no value in output)
     else One-Time Send (if enabled)
-        UI->>IPC: secret_response {requestId, value, delivery: "transient_send"}
-        IPC->>Prompter: resolve(value, "transient_send")
+        UI->>HTTP: secret_response {requestId, value, delivery: "transient_send"}
+        HTTP->>Prompter: resolve(value, "transient_send")
         Prompter->>Vault: {value, delivery: "transient_send"}
         Note over Vault: Hands value to CredentialBroker<br/>for single-use consumption
         Vault->>Model: "One-time credential provided" (no value in output)
     else Cancel
-        UI->>IPC: secret_response {requestId, value: null}
-        IPC->>Prompter: resolve(null)
+        UI->>HTTP: secret_response {requestId, value: null}
+        HTTP->>Prompter: resolve(null)
         Prompter->>Vault: null
         Vault->>Model: "User cancelled"
     end
@@ -303,7 +303,7 @@ The `allowOneTimeSend` config gate (default: `false`) enables a secondary "Send
 | `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)                |
-| `assistant/src/permissions/secret-prompter.ts`       | IPC secret_request/secret_response flow                               |
+| `assistant/src/permissions/secret-prompter.ts`       | HTTP secret_request/secret_response flow                               |
 | `assistant/src/security/secret-scanner.ts`           | Regex + entropy-based secret detection                                |
 | `assistant/src/security/secret-ingress.ts`           | Inbound message secret blocking                                       |
 | `clients/macos/.../SecretPromptManager.swift`        | Floating panel UI for secure credential entry                         |

package/docs/error-handling.md

@@ -21,7 +21,7 @@ throw new ConfigError("Missing required provider configuration");
 // Good: subagent manager throws when depth limit is exceeded
 throw new AssistantError(
   "Cannot spawn subagent: parent is itself a subagent",
-  ErrorCode.DAEMON_ERROR
+  ErrorCode.DAEMON_ERROR,
 );
 ```
 

package/docs/trusted-contact-access.md

@@ -31,7 +31,7 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 
    This ensures unknown inbound access attempts always trigger guardian notification, even when the requester's source channel has no guardian binding.
 
-4. **Guardian approves the request.** The guardian responds to the notification (via Telegram inline button, macOS app, or IPC). On approval, the assistant creates a verification session via `createOutboundSession()` and generates a 6-digit verification code.
+4. **Guardian approves the request.** The guardian responds to the notification (via Telegram inline button, macOS app, or local app). On approval, the assistant creates a verification session via `createOutboundSession()` and generates a 6-digit verification code.
 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.
@@ -162,7 +162,7 @@ sequenceDiagram
     Note over G: Guardian sees access request<br/>with requester identity
 
     alt Guardian approves
-        G->>A: Approve (inline button / IPC / plain text)
+        G->>A: Approve (inline button / HTTP / plain text)
         A->>A: resolveApprovalRequest(id, 'approved')
         A->>A: createOutboundSession(bound to requester identity)
         A-->>G: "Approved. Verification code: 847293.<br/>Give this to the requester."
@@ -182,7 +182,7 @@ sequenceDiagram
         A->>A: Process message normally
 
     else Guardian denies
-        G->>A: Deny (inline button / IPC / plain text)
+        G->>A: Deny (inline button / HTTP / plain text)
         A->>A: resolveApprovalRequest(id, 'denied')
         A-->>U: (No notification — user only knows<br/>they were denied if they message again)