@vellumai/assistant 0.4.44 → 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 via the shared connect orchestrator, plus a managed mode that routes through the platform proxy. It sits outside 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,167 +163,46 @@ sequenceDiagram
     end
 ```
 
-### Twitter Integration Architecture
-
-Twitter uses a standalone OAuth2 flow separate from the unified messaging layer. It supports a two-mode operation architecture determined by the `twitter.integrationMode` config field: **managed** mode routes all API calls through the Vellum platform proxy (which holds the OAuth credentials), while **OAuth** mode uses locally-stored OAuth2 tokens to call X API v2 directly. A mode router (`router.ts`) selects the appropriate path based on the caller-provided mode.
-
-#### 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
-```
-
-#### Two-Mode Operation Architecture
-
-The mode router (`router.ts`) determines whether to use the managed or OAuth path for each operation. The mode is determined by the `twitter.integrationMode` config field: `"managed"` routes through the platform proxy, everything else uses OAuth directly.
-
-```mermaid
-flowchart TD
-    CLI["assistant x post / reply / timeline / search"] --> Router["Mode Router (router.ts)"]
-    Router --> ModeCheck{Integration mode?}
-
-    ModeCheck -->|managed| ManagedPath["Platform Proxy Client (platform-proxy-client.ts)"]
-    ManagedPath --> PlatformAPI["Platform → X API v2"]
-
-    ModeCheck -->|oauth| OAuthPath["OAuth Client (oauth-client.ts)"]
-    OAuthPath --> XAPI["X API v2 POST /tweets"]
-```
-
-- **`managed`**: Routes all API calls through the Vellum platform proxy. The platform holds the OAuth credentials and forwards requests on behalf of the assistant. Supports both write operations (post, reply) and read operations (timeline, tweet detail, search, user lookup). This is the default when the user has a managed assistant.
-- **`oauth`**: Uses locally-stored OAuth2 Bearer tokens to call X API v2 directly. Supports only write operations (post, reply). Read operations throw an error directing the user to use managed mode.
-
-#### 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)                                   |
-
-#### 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
-
-**Managed path** (`platform-proxy-client.ts`): Routes API calls through the Vellum platform proxy at `${platformBaseUrl}/api/v1/assistants/${assistantId}/integrations/twitter/proxy/*`. The platform holds the OAuth credentials and forwards requests to X API v2 on behalf of the assistant. Supports all operations: post, reply, user lookup, user tweets, tweet detail, and search. Errors from the proxy surface as `TwitterProxyError` with structured error codes and retryability hints.
-
-**OAuth path** (`oauth-client.ts`): The `oauthPostTweet` function calls X API v2 (`POST https://api.x.com/2/tweets`) with a Bearer token provided by the caller. Supports `post` and `reply` (by including `reply.in_reply_to_tweet_id` in the request body). Read operations are not supported via this path and will throw an error directing the user to use managed mode.
-
-#### Available Twitter Tools
-
-| Tool / Command         | Mechanism                      | Description                                                                                |
-| ---------------------- | ------------------------------ | ------------------------------------------------------------------------------------------ |
-| `assistant x post`     | Mode router (OAuth or managed) | Post a tweet. Defaults to OAuth; pass `--managed` to route through the platform proxy.     |
-| `assistant x reply`    | Mode router (OAuth or managed) | Reply to a tweet. Defaults to OAuth; pass `--managed` to route through the platform proxy. |
-| `assistant x timeline` | Managed only                   | Fetch a user's recent tweets. Resolves screen name to user ID, then fetches timeline.      |
-| `assistant x tweet`    | Managed only                   | Fetch a single tweet and its reply thread via conversation ID search.                      |
-| `assistant x search`   | Managed only                   | Search tweets. Supports `Top`, `Latest`, `People`, and `Media` product types.              |
-| `assistant x status`   | HTTP (daemon)                  | Check OAuth connection and managed mode availability.                                      |
-
-Note: Write operations (post, reply) support both OAuth and managed modes. Read operations (timeline, tweet, search) require managed mode because the OAuth path only supports `post` and `reply`.
-
 ### 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                                                                                                                                                                    |
-| Two-mode Twitter architecture (managed + OAuth)    | Managed mode delegates to the platform proxy which holds credentials — no local browser or session management needed. OAuth mode provides direct API access for users with their own developer credentials. Read operations require managed mode since OAuth only supports post/reply. |
-| 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/cli/commands/twitter/oauth-client.ts`   | OAuth-backed Twitter client: X API v2 post/reply via Bearer token                                  |
-| `assistant/src/cli/commands/twitter/router.ts`         | Mode router: selects managed or OAuth path based on caller-provided `TwitterMode`                  |
-| `assistant/src/cli/commands/twitter/types.ts`          | Shared types: `PostTweetResult`, `UserInfo`, `TweetEntry`, `NotificationEntry`                     |
-| `assistant/src/cli/commands/twitter/index.ts`          | `assistant x` CLI command group (post, reply, timeline, tweet, search, status)                     |
-| `assistant/src/twitter/platform-proxy-client.ts`       | Platform-managed Twitter proxy client: routes API calls through the Vellum platform                |
-| `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`)                     |
 
 ---
 
@@ -319,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
 
@@ -348,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)