@vellumai/assistant 0.4.43 → 0.4.44

package/ARCHITECTURE.md

@@ -5,12 +5,11 @@ This document owns assistant-runtime architecture details. The repo-level archit
 ### Channel Onboarding Playbook Bootstrap
 
 - Transport metadata arrives via `session_create.transport` (HTTP) or `/channels/inbound` (`channelId`, optional `hints`, optional `uxBrief`).
-- Telegram webhook ingress now injects deterministic channel-safe transport metadata (`hints` + `uxBrief`) so non-dashboard channels defer Home Base-only UI tasks cleanly.
+- Telegram webhook ingress injects deterministic channel-safe transport metadata (`hints` + `uxBrief`) so non-dashboard channels defer dashboard-only UI tasks cleanly.
 - `OnboardingPlaybookManager` resolves `<channel>_onboarding.md`, checks `onboarding/playbooks/registry.json`, and applies per-channel first-time fast-path onboarding.
-- `OnboardingOrchestrator` derives onboarding-mode guidance (post-hatch sequence, USER.md capture, Home Base handoff) from playbook + transport context.
+- `OnboardingOrchestrator` derives onboarding-mode guidance (post-hatch sequence, USER.md capture) from playbook + transport context.
 - Session runtime assembly injects both `<channel_onboarding_playbook>` and `<onboarding_mode>` context before provider calls, then strips both from persisted conversation history.
-- Daemon startup runs `ensurePrebuiltHomeBaseSeeded()` to provision one idempotent prebuilt Home Base app in `~/.vellum/workspace/data/apps`.
-- Home Base onboarding buttons relay prefilled natural-language prompts to the main assistant; permission setup remains user-initiated and hatch + first-conversation flows avoid proactive permission asks.
+- Permission setup remains user-initiated and hatch + first-conversation flows avoid proactive permission asks.
 
 ### Guardian Actor Context (Unified Across Channels)
 
@@ -46,7 +45,7 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 | `actor:<assistantId>:<actorPrincipalId>` | `actor`        | Desktop, iOS, or CLI client                 |
 | `svc:gateway:<assistantId>`              | `svc_gateway`  | Gateway service (ingress, webhooks)         |
 | `svc:internal:<assistantId>:<sessionId>` | `svc_internal` | Internal service connections                |
-| `svc:daemon:<identifier>`                | `svc_daemon`   | Daemon service token (CLI bootstrap, local) |
+| `svc:daemon:<identifier>`                | `svc_daemon`   | Daemon service token (local)                |
 
 **Scope profiles:**
 
@@ -59,7 +58,7 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 
 **Identity lifecycle:**
 
-1. **Bootstrap (loopback-only, macOS/CLI)** — On first launch, the client calls `POST /v1/guardian/init` with `{ platform, deviceId }`. The endpoint is loopback-only and mints a JWT access token + refresh token pair. Returns `{ guardianPrincipalId, accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter, isNew }`.
+1. **Bootstrap (loopback-only, macOS)** — On first launch, the macOS client calls `POST /v1/guardian/init` with `{ platform, deviceId }`. The endpoint is loopback-only and mints a JWT access token + refresh token pair. Returns `{ guardianPrincipalId, accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter, isNew }`. The CLI obtains its bearer token during `hatch` and does not perform a separate bootstrap step.
 
 2. **iOS pairing** — iOS devices obtain JWTs through the QR pairing flow. The pairing response includes `accessToken` and `refreshToken` credentials.
 
@@ -719,7 +718,7 @@ graph LR
         CONFIG["config files<br/>Hot-reloaded by daemon<br/>(includes assistantFeatureFlagValues)"]
         ONBOARD_PLAYBOOKS["onboarding/playbooks/<br/>[channel]_onboarding.md<br/>assistant-updatable checklists"]
         ONBOARD_REGISTRY["onboarding/playbooks/registry.json<br/>channel-start index for fast-path + reconciliation"]
-        APPS_STORE["data/apps/<br/><app-id>.json + pages/*.html<br/>prebuilt Home Base seeded here"]
+        APPS_STORE["data/apps/<br/><app-id>.json + pages/*.html<br/>User-created apps stored here"]
         SKILLS_DIR["skills/<br/>managed skill directories<br/>SKILL.md + TOOLS.json + tools/"]
     end
 
@@ -1736,7 +1735,7 @@ Every event published through the hub is wrapped in an `AssistantEvent` (defined
 | `assistantId` | `string`            | Logical assistant identifier (`"self"` for HTTP runs) |
 | `sessionId`   | `string?`           | Resolved conversation ID when available               |
 | `emittedAt`   | `string` (ISO-8601) | Server-side timestamp                                 |
-| `message`     | `ServerMessage`     | The outbound message payload                           |
+| `message`     | `ServerMessage`     | The outbound message payload                          |
 
 ### SSE Frame Format
 
@@ -1766,12 +1765,12 @@ Keep-alive heartbeats (every 30 s by default):
 
 ### Key Source Files
 
-| File                                            | Role                                                                                |
-| ----------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `assistant/src/runtime/assistant-event.ts`      | `AssistantEvent` type, `buildAssistantEvent()` factory, SSE framing helpers         |
-| `assistant/src/runtime/assistant-event-hub.ts`  | `AssistantEventHub` class and process-level singleton                               |
-| `assistant/src/runtime/routes/events-routes.ts` | `handleSubscribeAssistantEvents()` — SSE route handler                              |
-| `assistant/src/daemon/server.ts`                | Session event paths that publish to the hub (`send` → `publishAssistantEvent`)      |
+| File                                            | Role                                                                           |
+| ----------------------------------------------- | ------------------------------------------------------------------------------ |
+| `assistant/src/runtime/assistant-event.ts`      | `AssistantEvent` type, `buildAssistantEvent()` factory, SSE framing helpers    |
+| `assistant/src/runtime/assistant-event-hub.ts`  | `AssistantEventHub` class and process-level singleton                          |
+| `assistant/src/runtime/routes/events-routes.ts` | `handleSubscribeAssistantEvents()` — SSE route handler                         |
+| `assistant/src/daemon/server.ts`                | Session event paths that publish to the hub (`send` → `publishAssistantEvent`) |
 
 ---
 

package/README.md

@@ -36,15 +36,15 @@ cp .env.example .env
 
 ## Configuration
 
-| Variable               | Required | Default                     | Description                                       |
-| ---------------------- | -------- | --------------------------- | ------------------------------------------------- |
-| `ANTHROPIC_API_KEY`    | Yes      | —                           | Anthropic Claude API key                          |
-| `OPENAI_API_KEY`       | No       | —                           | OpenAI API key                                    |
-| `GEMINI_API_KEY`       | No       | —                           | Google Gemini API key                             |
-| `OLLAMA_API_KEY`       | No       | —                           | API key for authenticated Ollama deployments      |
-| `OLLAMA_BASE_URL`      | No       | `http://127.0.0.1:11434/v1` | Ollama base URL                                   |
-| `RUNTIME_HTTP_PORT`    | No       | —                           | Enable the HTTP server (required for gateway/web) |
-| `RUNTIME_HTTP_HOST`    | No       | `127.0.0.1`                 | HTTP server bind address                          |
+| Variable            | Required | Default                     | Description                                       |
+| ------------------- | -------- | --------------------------- | ------------------------------------------------- |
+| `ANTHROPIC_API_KEY` | Yes      | —                           | Anthropic Claude API key                          |
+| `OPENAI_API_KEY`    | No       | —                           | OpenAI API key                                    |
+| `GEMINI_API_KEY`    | No       | —                           | Google Gemini API key                             |
+| `OLLAMA_API_KEY`    | No       | —                           | API key for authenticated Ollama deployments      |
+| `OLLAMA_BASE_URL`   | No       | `http://127.0.0.1:11434/v1` | Ollama base URL                                   |
+| `RUNTIME_HTTP_PORT` | No       | —                           | Enable the HTTP server (required for gateway/web) |
+| `RUNTIME_HTTP_HOST` | No       | `127.0.0.1`                 | HTTP server bind address                          |
 
 ## Update Bulletin
 
@@ -112,7 +112,6 @@ assistant/
 │   ├── messaging/            # Message processing pipeline
 │   ├── context/              # Context assembly and compaction
 │   ├── playbooks/            # Channel onboarding playbooks
-│   ├── home-base/            # Home Base app-link bootstrap
 │   ├── hooks/                # Git-style lifecycle hooks
 │   ├── media/                # Media processing and attachments
 │   ├── schedule/             # Reminders and recurrence scheduling (cron + RRULE)
@@ -265,9 +264,9 @@ The channel guardian service generates verification challenge instructions with
 
 ### Vellum Guardian Identity (Actor Tokens)
 
-The vellum channel (macOS, iOS, CLI) uses JWTs to bind guardian identity to HTTP requests. This enables identity-based authentication for the local desktop/mobile channel, paralleling how external channels (Telegram) use `actorExternalId` for guardian identity.
+The vellum channel (macOS, iOS) uses JWTs to bind guardian identity to HTTP requests. This enables identity-based authentication for the local desktop/mobile channel, paralleling how external channels (Telegram) use `actorExternalId` for guardian identity. The CLI authenticates using its bearer token obtained during `hatch`.
 
-- **Bootstrap**: After hatch, the macOS client calls `POST /v1/guardian/init` with `{ platform, deviceId }`. Returns `{ guardianPrincipalId, accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter, isNew }`. The endpoint is idempotent -- repeated calls with the same device return the same principal but mint fresh credentials.
+- **Bootstrap**: After hatch, the macOS client calls `POST /v1/guardian/init` with `{ platform, deviceId }`. Returns `{ guardianPrincipalId, accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter, isNew }`. The endpoint is idempotent -- repeated calls with the same device return the same principal but mint fresh credentials. The CLI does not bootstrap separately; it uses the bearer token minted during `hatch`.
 - **iOS pairing**: The pairing response includes `accessToken` and `refreshToken` credentials automatically when a vellum guardian binding exists.
 - **Local identity**: Local connections resolve identity server-side via `resolveLocalGuardianContext()` without requiring a JWT.
 - **HTTP enforcement**: All vellum HTTP routes require a valid JWT via the `Authorization: Bearer <jwt>` header. The JWT carries identity claims (`sub` with principal type and ID) and scope permissions. Route-level enforcement in `route-policy.ts` checks scopes and principal types.

package/docs/architecture/integrations.md

@@ -9,7 +9,7 @@ The integration framework lets Vellum connect to third-party services via OAuth2
 - **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.
 - **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.
+- **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
@@ -139,7 +139,7 @@ sequenceDiagram
 
 ### 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 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
 
@@ -184,46 +184,36 @@ sequenceDiagram
     IPC->>UI: show connected state
 ```
 
-#### Dual-Path Operation Architecture
+#### Two-Mode 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`).
+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["vellum x post / reply"] --> Router["Strategy Router (router.ts)"]
-    Router --> StratCheck{Preferred strategy?}
+    CLI["assistant x post / reply / timeline / search"] --> Router["Mode Router (router.ts)"]
+    Router --> ModeCheck{Integration mode?}
 
-    StratCheck -->|oauth| OAuthOnly["OAuth Client (oauth-client.ts)"]
-    OAuthOnly --> XAPI["X API v2 POST /tweets"]
+    ModeCheck -->|managed| ManagedPath["Platform Proxy Client (platform-proxy-client.ts)"]
+    ManagedPath --> PlatformAPI["Platform → X API v2"]
 
-    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
+    ModeCheck -->|oauth| OAuthPath["OAuth Client (oauth-client.ts)"]
+    OAuthPath --> XAPI["X API v2 POST /tweets"]
 ```
 
-- **`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>`.
+- **`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), 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      | `client_id`, `client_secret`                                                               |
+| HTTP endpoints        | `oauth_connect_start` / `oauth_connect_result` (generic)                                   |
 
 #### Twitter Credential Metadata Structure
 
@@ -244,78 +234,70 @@ When the OAuth2 flow completes, the handler stores credential metadata at `integ
 
 #### 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.
+**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.
 
-**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`).
+**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                                                         |
-| ------------------------ | ------------------------------ | ------------------------------------------------------------------- |
-| `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.
+| 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                                                                                                                                                     |
-| 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                                                                                                                                                                                            |
+| 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                                                                                                                                                    |
 
 ### 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/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                                                             |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.4.43",
+  "version": "0.4.44",
   "type": "module",
   "bin": {
     "assistant": "./src/index.ts"

package/src/__tests__/approval-routes-http.test.ts

@@ -112,7 +112,6 @@ function makeIdleSession(opts?: {
     setCommandIntent: () => {},
     setTurnChannelContext: () => {},
     setTurnInterfaceContext: () => {},
-    setStateSignalListener: () => {},
     updateClient: () => {},
     enqueueMessage: () => ({ queued: false, requestId: "noop" }),
     hasAnyPendingConfirmation: () => false,
@@ -171,7 +170,6 @@ function makeConfirmationEmittingSession(opts?: {
     setCommandIntent: () => {},
     setTurnChannelContext: () => {},
     setTurnInterfaceContext: () => {},
-    setStateSignalListener: () => {},
     updateClient: () => {},
     enqueueMessage: () => ({ queued: false, requestId: "noop" }),
     hasAnyPendingConfirmation: () => false,

package/src/__tests__/bundled-asset.test.ts

@@ -124,7 +124,7 @@ describe("resolveBundledDir", () => {
       process.execPath = join(macosDir, "vellum-daemon");
 
       const result = resolveBundledDir(
-        "/$bunfs/root/src/home-base/prebuilt",
+        "/$bunfs/root/src/widgets/prebuilt",
         ".",
         "prebuilt",
       );

package/src/__tests__/checker.test.ts

@@ -637,27 +637,26 @@ describe("Permission Checker", () => {
       expect(result.decision).toBe("prompt");
     });
 
-    test("host_bash rm is always high risk → prompt", async () => {
+    test("host_bash rm is always prompted via default ask rule", async () => {
       const result = await check(
         "host_bash",
         { command: "rm file.txt" },
         "/tmp",
       );
       expect(result.decision).toBe("prompt");
-      expect(result.reason).toContain("High risk");
+      expect(result.reason).toContain("ask rule");
     });
 
-    test("plain rm (without -rf) is high risk and prompts despite default allow rule", async () => {
-      // Validates that ALL rm commands are escalated to High risk, not just rm -rf.
-      // The default allow rule for host_bash auto-approves Low/Medium risk but
-      // High risk always prompts.
+    test("plain rm (without -rf) prompts via default ask rule", async () => {
+      // The default ask rule for host_bash prompts ALL commands regardless
+      // of risk level — rm commands are no exception.
       const result = await check(
         "host_bash",
         { command: "rm single-file.txt" },
         "/tmp",
       );
       expect(result.decision).toBe("prompt");
-      expect(result.reason).toContain("High risk");
+      expect(result.reason).toContain("ask rule");
 
       // Also verify rm -rf still prompts
       const rfResult = await check(
@@ -666,7 +665,7 @@ describe("Permission Checker", () => {
         "/tmp",
       );
       expect(rfResult.decision).toBe("prompt");
-      expect(rfResult.reason).toContain("High risk");
+      expect(rfResult.reason).toContain("ask rule");
     });
 
     test("rm is high risk even with matching trust rule → prompt", async () => {
@@ -807,11 +806,11 @@ describe("Permission Checker", () => {
       expect(result.matchedRule?.id).toBe("default:ask-host_file_edit-global");
     });
 
-    test("host_bash auto-allows low risk via default allow rule", async () => {
+    test("host_bash prompts low risk via default ask rule", async () => {
       const result = await check("host_bash", { command: "ls" }, "/tmp");
-      expect(result.decision).toBe("allow");
-      expect(result.reason).toContain("Matched trust rule");
-      expect(result.matchedRule?.id).toBe("default:allow-host_bash-global");
+      expect(result.decision).toBe("prompt");
+      expect(result.reason).toContain("ask rule");
+      expect(result.matchedRule?.id).toBe("default:ask-host_bash-global");
     });
 
     test("scaffold_managed_skill prompts by default via managed skill ask rule", async () => {
@@ -2232,11 +2231,12 @@ describe("Permission Checker", () => {
       expect(result.matchedRule?.id).toBe("default:allow-bash-global");
     });
 
-    test("host_bash auto-allows low risk in strict mode (default allow rule is a matching rule)", async () => {
+    test("host_bash prompts low risk in strict mode (default ask rule matches)", async () => {
       testConfig.permissions.mode = "strict";
       const result = await check("host_bash", { command: "ls" }, "/tmp");
-      expect(result.decision).toBe("allow");
-      expect(result.matchedRule?.id).toBe("default:allow-host_bash-global");
+      expect(result.decision).toBe("prompt");
+      expect(result.reason).toContain("ask rule");
+      expect(result.matchedRule?.id).toBe("default:ask-host_bash-global");
     });
 
     test("high-risk host_bash (rm) with no matching rule returns prompt in strict mode", async () => {
@@ -3570,15 +3570,16 @@ describe("Permission Checker", () => {
         expect(result.matchedRule?.id).toBe("default:allow-bash-global");
       });
 
-      test("low-risk host_bash auto-allows in strict mode (default allow rule is a matching rule)", async () => {
+      test("low-risk host_bash prompts in strict mode (default ask rule matches)", async () => {
         testConfig.permissions.mode = "strict";
         const result = await check(
           "host_bash",
           { command: "echo hello" },
           "/tmp",
         );
-        expect(result.decision).toBe("allow");
-        expect(result.matchedRule?.id).toBe("default:allow-host_bash-global");
+        expect(result.decision).toBe("prompt");
+        expect(result.reason).toContain("ask rule");
+        expect(result.matchedRule?.id).toBe("default:ask-host_bash-global");
       });
 
       test("low-risk file_read with no rule prompts in strict mode", async () => {
@@ -3660,10 +3661,11 @@ describe("Permission Checker", () => {
     //    target-scoped. ───────────────────────────────────────────────
 
     describe("Invariant 4: host execution approvals are explicit and target-scoped", () => {
-      test("host_bash auto-allows low risk via default allow rule", async () => {
+      test("host_bash prompts low risk via default ask rule", async () => {
         const result = await check("host_bash", { command: "ls" }, "/tmp");
-        expect(result.decision).toBe("allow");
-        expect(result.matchedRule?.id).toBe("default:allow-host_bash-global");
+        expect(result.decision).toBe("prompt");
+        expect(result.reason).toContain("ask rule");
+        expect(result.matchedRule?.id).toBe("default:ask-host_bash-global");
       });
 
       test("host_file_read prompts by default (no implicit allow)", async () => {
@@ -3740,7 +3742,7 @@ describe("Permission Checker", () => {
         expect(matchResult.matchedRule?.id).toBe("inv4-target-scoped");
 
         // Different target — the target-scoped rule should NOT match;
-        // falls back to the default host_bash allow rule (auto-allows medium risk)
+        // falls back to the default host_bash ask rule (prompts)
         const noMatchResult = await check(
           "host_bash",
           { command: "run script.js" },
@@ -3749,8 +3751,9 @@ describe("Permission Checker", () => {
             executionTarget: "/usr/local/bin/bun",
           },
         );
-        expect(noMatchResult.decision).toBe("allow");
-        expect(noMatchResult.matchedRule?.id).not.toBe("inv4-target-scoped");
+        expect(noMatchResult.decision).toBe("prompt");
+        expect(noMatchResult.reason).toContain("ask rule");
+        expect(noMatchResult.matchedRule?.id).toBe("default:ask-host_bash-global");
       });
     });
 
@@ -4310,7 +4313,7 @@ describe("bash network_mode=proxied — no special-casing", () => {
 
   test("proxied bash follows normal rules (auto-allowed by default rule)", async () => {
     // Proxied bash is no longer force-prompted — the default allow-bash rule
-    // auto-allows low/medium risk commands regardless of network_mode.
+    // prompts low/medium risk commands regardless of network_mode.
     const result = await check(
       "bash",
       { command: "curl https://api.example.com", network_mode: "proxied" },
@@ -4722,10 +4725,10 @@ describe("workspace mode — auto-allow workspace-scoped operations", () => {
     expect(result.reason).toContain("ask rule");
   });
 
-  test("host_bash → allow (default allow rule matches)", async () => {
+  test("host_bash → prompt (default ask rule matches)", async () => {
     const result = await check("host_bash", { command: "ls" }, workspaceDir);
-    expect(result.decision).toBe("allow");
-    expect(result.reason).toContain("Matched trust rule");
+    expect(result.decision).toBe("prompt");
+    expect(result.reason).toContain("ask rule");
   });
 
   // ── explicit rules still take precedence in workspace mode ──