@vellumai/assistant 0.4.34 → 0.4.35

package/package.json

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

package/src/__tests__/assistant-id-boundary-guard.test.ts

@@ -481,8 +481,8 @@ describe("assistant ID boundary", () => {
     const repoRoot = getRepoRoot();
 
     // Scan all Drizzle schema files for assistantId column definitions.
-    // The Drizzle ORM pattern is `assistantId: text(` for defining a text
-    // column named assistantId.
+    // Match `assistantId:` followed by any Drizzle column builder (text(,
+    // integer(, blob(, real(, etc.) — not just text(.
     const schemaGlobs = [
       "assistant/src/memory/schema/*.ts",
       "assistant/src/memory/schema/**/*.ts",
@@ -492,7 +492,7 @@ describe("assistant ID boundary", () => {
     try {
       grepOutput = execFileSync(
         "git",
-        ["grep", "-nE", "assistantId\\s*:\\s*text\\(", "--", ...schemaGlobs],
+        ["grep", "-nE", "assistantId\\s*:", "--", ...schemaGlobs],
         { encoding: "utf-8", cwd: repoRoot },
       ).trim();
     } catch (err) {
@@ -546,6 +546,9 @@ describe("assistant ID boundary", () => {
     // Scan store files for exported function signatures that include
     // assistantId as a parameter. This covers memory stores, contact stores,
     // notification stores, credential/token stores, and call stores.
+    //
+    // We read each file and extract full parameter lists (which may span
+    // multiple lines) from exported functions to catch multiline signatures.
     const storeGlobs = [
       "assistant/src/memory/*.ts",
       "assistant/src/contacts/*.ts",
@@ -556,52 +559,68 @@ describe("assistant ID boundary", () => {
       "assistant/src/calls/call-store.ts",
     ];
 
-    // Match exported function declarations/expressions with assistantId in
-    // their parameter lists. Patterns:
-    //   export function foo(assistantId
-    //   export function foo(bar, assistantId
-    //   export async function foo(assistantId
-    //   export const foo = (assistantId
-    //   export const foo = async (assistantId
-    // We use a broad pattern that catches assistantId appearing after an
-    // opening paren in an export context.
-    const pattern =
-      "export\\s+(async\\s+)?function\\s+\\w+\\s*\\([^)]*assistantId|export\\s+const\\s+\\w+\\s*=\\s*(async\\s+)?\\([^)]*assistantId";
-
-    let grepOutput = "";
-    try {
-      grepOutput = execFileSync(
-        "git",
-        ["grep", "-nE", pattern, "--", ...storeGlobs],
-        { encoding: "utf-8", cwd: repoRoot },
-      ).trim();
-    } catch (err) {
-      // Exit code 1 means no matches — happy path
-      if ((err as { status?: number }).status === 1) {
-        return;
+    // Find matching files using git ls-files with each glob
+    const matchedFiles: string[] = [];
+    for (const glob of storeGlobs) {
+      try {
+        const output = execFileSync("git", ["ls-files", "--", glob], {
+          encoding: "utf-8",
+          cwd: repoRoot,
+        }).trim();
+        if (output) {
+          matchedFiles.push(...output.split("\n").filter((f) => f.length > 0));
+        }
+      } catch {
+        // Ignore errors — glob may not match anything
       }
-      throw err;
     }
 
-    const allLines = grepOutput.split("\n").filter((l) => l.length > 0);
-    const violations = allLines.filter((line) => {
-      const filePath = line.split(":")[0];
-      if (isTestFile(filePath)) return false;
-      if (isMigrationFile(filePath)) return false;
+    const violations: string[] = [];
 
-      // Allow comments
-      const parts = line.split(":");
-      const content = parts.slice(2).join(":").trim();
-      if (
-        content.startsWith("//") ||
-        content.startsWith("*") ||
-        content.startsWith("/*")
+    // Regex to find the start of an exported function declaration or
+    // arrow-function expression. We capture everything from `export` up to
+    // and including the opening parenthesis of the parameter list.
+    const exportFnStartRegex =
+      /export\s+(?:async\s+)?function\s+\w+\s*\(|export\s+const\s+\w+\s*=\s*(?:async\s+)?\(/g;
+
+    for (const relPath of matchedFiles) {
+      if (isTestFile(relPath) || isMigrationFile(relPath)) continue;
+
+      const content = readFileSync(join(repoRoot, relPath), "utf-8");
+
+      exportFnStartRegex.lastIndex = 0;
+      for (
+        let match = exportFnStartRegex.exec(content);
+        match;
+        match = exportFnStartRegex.exec(content)
       ) {
-        return false;
-      }
+        // Find the matching closing paren to extract the full parameter list,
+        // which may span multiple lines.
+        const parenStart = match.index + match[0].length - 1; // index of '('
+        let depth = 1;
+        let paramEnd = parenStart + 1;
+        for (let i = parenStart + 1; i < content.length && depth > 0; i++) {
+          if (content[i] === "(") depth++;
+          if (content[i] === ")") depth--;
+          if (depth === 0) {
+            paramEnd = i;
+            break;
+          }
+        }
 
-      return true;
-    });
+        const paramList = content.slice(parenStart + 1, paramEnd);
+
+        // Check if the parameter list contains assistantId as a word boundary
+        if (/\bassistantId\b/.test(paramList)) {
+          // Determine the line number of the export keyword for reporting
+          const lineNum = content.slice(0, match.index).split("\n").length;
+          const firstLine = content
+            .slice(match.index, match.index + match[0].length)
+            .trim();
+          violations.push(`${relPath}:${lineNum}: ${firstLine}...`);
+        }
+      }
+    }
 
     if (violations.length > 0) {
       const message = [

package/src/config/bundled-skills/google-oauth-setup/SKILL.md

@@ -1,20 +1,20 @@
 ---
 name: "Google OAuth Setup"
-description: "Set up Google Cloud OAuth credentials for Gmail and Calendar using browser automation"
+description: "Set up Google Cloud OAuth credentials for Gmail and Calendar"
 user-invocable: true
 credential-setup-for: "gmail"
-includes: ["browser", "public-ingress"]
-metadata: {"vellum": {"emoji": "\ud83d\udd11"}}
+includes: ["public-ingress"]
+metadata: { "vellum": { "emoji": "\ud83d\udd11" } }
 ---
 
 You are helping your user set up Google Cloud OAuth credentials so Gmail and Google Calendar integrations can connect.
 
 ## Client Check
 
-Determine whether the user has browser automation available (macOS desktop app) or is on a non-interactive channel (Telegram, SMS, etc.).
+Determine which setup path to use based on the user's client:
 
-- **macOS desktop app**: Follow the **Automated Setup** path below.
-- **Telegram or other channel** (no browser automation): Follow the **Manual Setup for Channels** path below.
+- **macOS desktop app**: Follow **Path B: CLI Setup** below.
+- **Telegram or other channel** (no browser automation): Follow **Path A: Manual Setup for Channels** below.
 
 ---
 
@@ -29,6 +29,7 @@ Tell the user:
 > **Setting up Gmail & Calendar from Telegram**
 >
 > Since I can't automate the browser from here, I'll walk you through each step with direct links. You'll need:
+>
 > 1. A Google account with access to Google Cloud Console
 > 2. About 5 minutes
 >
@@ -96,6 +97,7 @@ Tell the user:
 ### Channel Step 5: Create OAuth Credentials (Web Application)
 
 Before sending Step 4 to the user, resolve the concrete callback URL:
+
 - Read the configured public gateway URL (`ingress.publicBaseUrl`). If it is missing, run the `public-ingress` skill first.
 - Build `oauthCallbackUrl` as `<public gateway URL>/webhooks/oauth/callback`.
 - When you send the instructions below, replace `OAUTH_CALLBACK_URL` with that concrete value. Never send placeholders literally.
@@ -140,7 +142,7 @@ credential_store store:
 
 **Step 6b: Client Secret (requires split entry to avoid security filters)**
 
-The Client Secret starts with `GOCSPX-` which triggers the ingress secret scanner on channel messages. To work around this, ask the user to send only the portion *after* the prefix.
+The Client Secret starts with `GOCSPX-` which triggers the ingress secret scanner on channel messages. To work around this, ask the user to send only the portion _after_ the prefix.
 
 Tell the user:
 
@@ -192,229 +194,165 @@ After the user authorizes (they'll come back and say so, or you can suggest they
 
 ---
 
-# Path B: Automated Setup (macOS Desktop App)
-
-You will automate the entire GCP setup via the browser while the user watches in the Chrome window on the side. The user's only manual actions are: signing in to their Google account, and copy-pasting credentials from the Chrome window into secure prompts.
-
-## Browser Interaction Principles
-
-Google Cloud Console's UI changes frequently. Do NOT memorize or depend on specific element IDs, CSS selectors, or DOM structures. Instead:
-
-1. **Snapshot first, act second.** Before every interaction, use `browser_snapshot` to discover interactive elements and their IDs. This is your primary navigation tool; it gives you the accessibility tree with clickable/typeable element IDs. Use `browser_screenshot` for visual context when the snapshot alone isn't enough.
-2. **Adapt to what you see.** If an element's label or position differs from what you expect, use the snapshot to find the correct element. GCP may rename buttons, reorganize menus, or change form layouts at any time.
-3. **Verify after every action.** After clicking, typing, or navigating, take a new snapshot to confirm the action succeeded. If it didn't, try an alternative interaction (e.g., if a dropdown didn't open on click, try pressing Space or Enter on the element).
-4. **Never assume DOM structure.** Dropdowns may be `<select>`, `<mat-select>`, `<div role="listbox">`, or something else entirely. Use the snapshot to identify element types and interact accordingly.
-5. **When stuck after 2 attempts, describe and ask.** Take a screenshot, describe what you see to the user, and ask for guidance.
-
-## Anti-Loop Guardrails
+# Path B: CLI Setup (macOS Desktop App)
 
-Each step has a **retry budget of 3 attempts**. An attempt is one try at the step's primary action (e.g., clicking a button, filling a form). If a step fails after 3 attempts:
+**IMPORTANT: Always use `host_bash` (not `bash`) for all commands in this path.** The `gcloud` and `gws` CLIs need host access for Homebrew/npm installation, browser-based authentication, and interactive terminal prompts — none of which are available inside the sandbox.
 
-1. **Stop trying.** Do not continue retrying the same approach.
-2. **Fall back to manual.** Tell the user what you were trying to do and ask them to complete that step manually in the Chrome window (which they can see on the side). Give them the direct URL and clear text instructions.
-3. **Resume automation** at the next step once the user confirms the manual step is done.
+You will set up Google Cloud OAuth credentials using the `gcloud` and `gws` command-line tools. This avoids browser automation entirely — the user only needs to sign in once via the browser and copy-paste credentials from terminal output into secure prompts.
 
-If **two or more steps** require manual fallback, abandon the automated flow entirely and switch to giving the user the remaining steps as clear text instructions with links, using "Desktop app" as the OAuth application type.
+## CLI Step 1: Confirm
 
-## Things That Do Not Work: Do Not Attempt
-
-These actions are technically impossible in the browser automation environment. Attempting them wastes time and leads to loops:
-
-- **Downloading files.** `browser_click` on a Download button does not save files to disk. There is NO JSON file to find at `~/Downloads` or anywhere else. Never click Download buttons.
-- **Clipboard operations.** You cannot copy/paste via browser automation. The user must manually copy values from the Chrome window.
-- **Deleting and recreating OAuth clients** to get a fresh secret. This orphans the stored client_id and causes `invalid_client` errors.
-- **Navigating away from the credential dialog** before both credentials are stored. You will lose the Client Secret display and cannot get it back without creating a new client.
-
-## Step 1: Single Upfront Confirmation
-
-Use `ui_show` with `surface_type: "confirmation"`. Set `message` to just the title, and `detail` to the body:
+Use `ui_show` with `surface_type: "confirmation"`:
 
 - **message:** `Set up Google Cloud for Gmail & Calendar`
 - **detail:**
   > Here's what will happen:
-  > 1. **A browser opens on the side** so you can watch everything I do
-  > 2. **You sign in** to your Google account in the browser
-  > 3. **I automate everything** including project creation, APIs, OAuth config, and credentials
-  > 4. **One copy-paste** where I'll ask you to copy the Client Secret from the browser into a secure prompt
+  >
+  > 1. **Install CLI tools** (`gcloud` and `gws`) if not already installed
+  > 2. **You sign in** to your Google account once via the browser
+  > 3. **CLI automates everything** — project creation, APIs, consent screen, and credentials
+  > 4. **You copy-paste credentials** from the terminal output into secure prompts
   > 5. **You authorize Vellum** with one click
   >
-  > The whole thing takes 2-3 minutes. Ready?
-
-If the user declines, acknowledge and stop. No further confirmations are needed after this point.
-
-## Step 2: Open Google Cloud Console and Sign In
+  > Takes about a minute after first-time setup. Ready?
 
-**Goal:** The user is signed in and the Google Cloud Console dashboard is loaded.
-
-Navigate to `https://console.cloud.google.com/`.
-
-Take a screenshot to check the page state:
-
-- **Sign-in page:** Tell the user: "Please sign in to your Google account in the Chrome window on the right side of your screen." Then auto-detect sign-in completion by polling with `browser_screenshot` every 5-10 seconds to check if the URL has moved away from `accounts.google.com` to `console.cloud.google.com`. Do NOT ask the user to "let me know when you're done"; detect it automatically. Once sign-in is detected, tell the user: "Signed in! Starting the automated setup now..."
-- **Already signed in:** Tell the user: "Already signed in, starting setup now..." and continue immediately.
-- **CAPTCHA:** The browser automation's built-in handoff will handle this. If it persists, tell the user: "There's a CAPTCHA in the browser, please complete it and I'll continue automatically."
-
-**What you should see when done:** URL contains `console.cloud.google.com` and no sign-in overlay is visible.
-
-## Step 3: Create or Select a Project
-
-**Goal:** A GCP project named "Vellum Assistant" exists and is selected.
-
-Tell the user: "Creating Google Cloud project..."
-
-Navigate to `https://console.cloud.google.com/projectcreate`.
-
-Take a `browser_snapshot`. Find the project name input field (look for an element with label containing "Project name" or a text input near the top of the form). Type "Vellum Assistant" into it.
-
-Look for a "Create" button in the snapshot and click it. Wait 10-15 seconds for project creation, then take a screenshot to check for:
-- **Success message** or redirect to the new project dashboard. Note the project ID from the URL or page content.
-- **"Project name already in use" error**: that's fine. Navigate to `https://console.cloud.google.com/cloud-resource-manager` to find and select the existing "Vellum Assistant" project. Use `browser_extract` to read the project ID from the page.
-- **Organization restriction or quota error**: tell the user what happened and ask them to resolve it.
-
-**What you should see when done:** The project selector in the top bar shows the project name, and you have the project ID (something like `vellum-assistant-12345`).
+If the user declines, acknowledge and stop.
 
-Tell the user: "Project created!"
+## CLI Step 2: Install Prerequisites
 
-## Step 4: Enable Gmail and Calendar APIs
+Check for and install each prerequisite. If any installation fails (e.g., Homebrew not available, corporate restrictions), tell the user what went wrong and provide manual installation instructions.
 
-**Goal:** Both the Gmail API and Google Calendar API are enabled for the project.
+### gcloud
 
-Tell the user: "Enabling Gmail and Calendar APIs..."
+```bash
+which gcloud
+```
 
-Navigate to each API's library page and enable it if not already enabled:
-1. `https://console.cloud.google.com/apis/library/gmail.googleapis.com?project=PROJECT_ID`
-2. `https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=PROJECT_ID`
+If missing:
 
-For each page: take a `browser_snapshot`. Look for:
-- **"Enable" button**: click it, wait a few seconds, take another snapshot to confirm.
-- **"Manage" button or "API enabled" text**: the API is already enabled. Skip it.
+```bash
+brew install google-cloud-sdk
+```
 
-**What you should see when done:** Both API pages show "Manage" or "API enabled" status.
+After installation, verify it works:
 
-Tell the user: "APIs enabled!"
+```bash
+gcloud --version
+```
 
-## Step 5: Configure OAuth Consent Screen
+### gws
 
-**Goal:** An OAuth consent screen is configured with External user type, the required scopes, and the user added as a test user.
+```bash
+which gws
+```
 
-Tell the user: "Setting up OAuth consent screen. This is the longest step but it's fully automated..."
+If missing:
 
-Navigate to `https://console.cloud.google.com/apis/credentials/consent?project=PROJECT_ID`.
+```bash
+npm install -g @googleworkspace/cli
+```
 
-Take a `browser_snapshot` and `browser_screenshot`. Check the page state:
+After installation, verify it works:
 
-### If the consent screen is already configured
+```bash
+gws --version
+```
 
-You'll see a dashboard showing the app name ("Vellum Assistant" or similar) with an "Edit App" button. **Skip to Step 6.**
+## CLI Step 3: Sign In to Google
 
-### If you see a user type selection (External / Internal)
+Tell the user: "Opening your browser so you can sign in to Google..."
 
-Select **"External"** and click **Create** or **Get Started**.
+```bash
+gcloud auth login
+```
 
-### Consent screen form (wizard or single-page)
+This opens the browser for Google sign-in. Wait for the command to complete — it prints the authenticated account email on success.
 
-Google Cloud uses either a multi-page wizard or a single-page form. Adapt to what you see:
+If the user is already authenticated (`gcloud auth list` shows an active account), skip this step and tell the user: "Already signed in, continuing setup..."
 
-**App information section:**
-- **App name**: Type "Vellum Assistant" in the app name field.
-- **User support email**: This is typically a dropdown showing the signed-in user's email. Use `browser_snapshot` to find a `<select>` or clickable dropdown element near "User support email". Select the user's email.
-- **Developer contact email**: Type the user's email into this field. (Use the same email visible in the support email dropdown if you can read it, or use `browser_extract` to find the email shown on the page.)
-- Click **Save and Continue** if on a multi-page wizard.
+## CLI Step 4: GCP Project Setup
 
-**Scopes section:**
-- Click **"Add or Remove Scopes"** (or similar button).
-- In the scope picker dialog, look for a text input labeled **"Manually add scopes"** or **"Filter"** at the bottom or top of the dialog.
-- Paste all 6 scopes at once as a comma-separated string into that input:
-  ```
-  https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/gmail.send,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/calendar.events,https://www.googleapis.com/auth/userinfo.email
-  ```
-- Click **"Add to Table"** or **"Update"** to confirm the scopes.
-- If no manual input is available, you'll need to search for and check each scope individually using the scope tree. Search for each scope URL in the filter box and check its checkbox.
-- Click **Save and Continue** (or **Update** then **Save and Continue**).
+Tell the user: "Setting up your Google Cloud project, APIs, and credentials..."
 
-**Test users section:**
-- Click **"Add Users"** or similar.
-- Enter the user's email address.
-- Click **Add** then **Save and Continue**.
+```bash
+gws auth setup
+```
 
-**Summary section:**
-- Click **"Back to Dashboard"** or **"Submit"**.
+This command automates:
 
-**What you should see when done:** A consent screen dashboard showing "Vellum Assistant" as the app name.
+- GCP project creation (or selection of an existing one)
+- OAuth consent screen configuration
+- OAuth credential creation
 
-Tell the user: "Consent screen configured!"
+Wait for the command to complete. It may have interactive prompts — let them run in the terminal and the user can respond if needed.
 
-## Step 6: Create OAuth Credentials and Capture Them
+Note the **project ID** from the output — you'll need it for the next step.
 
-**Goal:** A "Desktop app" OAuth client exists, and both its Client ID and Client Secret are stored in the vault.
+## CLI Step 5: Enable Additional APIs
 
-Tell the user: "Creating OAuth credentials..."
+`gws auth setup` enables the APIs it needs, but Vellum also requires the Calendar and People APIs. Enable them explicitly using the project ID from step 4:
 
-### 6a: Create the credential
+```bash
+gcloud services enable calendar-json.googleapis.com --project=PROJECT_ID
+gcloud services enable people.googleapis.com --project=PROJECT_ID
+```
 
-Navigate to `https://console.cloud.google.com/apis/credentials?project=PROJECT_ID`.
+If either command reports the API is already enabled, that's fine — continue.
 
-Take a `browser_snapshot`. Find and click a button labeled **"Create Credentials"** or **"+ Create Credentials"**. A dropdown menu should appear. Take another snapshot and click **"OAuth client ID"**.
+## CLI Step 5b: Update OAuth Consent Screen Scopes
 
-On the creation form (take a snapshot to see the fields):
-- **Application type**: Find the dropdown and select **"Desktop app"**. This may be a `<select>` element or a custom dropdown. Use the snapshot to identify it. You might need to click the dropdown first, then take another snapshot to see the options, then click "Desktop app".
-- **Name**: Type "Vellum Assistant" in the name field.
-- Do NOT add any redirect URIs. The desktop app flow doesn't need them.
+`gws auth setup` configures the consent screen with Gmail scopes only. Vellum also needs Calendar, Contacts, and userinfo scopes. Tell the user to add the missing scopes:
 
-Click **"Create"** to submit the form.
+> **Update consent screen scopes**
+>
+> Open: `https://console.cloud.google.com/apis/credentials/consent/edit?project=PROJECT_ID`
+>
+> 1. Click through to the **Scopes** page (click **Save and Continue** on the first page)
+> 2. Click **Add or Remove Scopes** and ensure all of these are present:
+>    - `https://www.googleapis.com/auth/gmail.readonly`
+>    - `https://www.googleapis.com/auth/gmail.modify`
+>    - `https://www.googleapis.com/auth/gmail.send`
+>    - `https://www.googleapis.com/auth/calendar.readonly`
+>    - `https://www.googleapis.com/auth/calendar.events`
+>    - `https://www.googleapis.com/auth/userinfo.email`
+>    - `https://www.googleapis.com/auth/contacts.readonly`
+> 3. Click **Update**, then **Save and Continue** through the remaining pages
 
-### 6b: Capture credentials from the dialog
+(Substitute the actual project ID into the URL.)
 
-After creation, a dialog will display the **Client ID** and **Client Secret**. This is the critical step.
+The Gmail scopes may already be present from `gws auth setup` — add any that are missing.
 
-**First**, try to auto-read the **Client ID** using `browser_extract`. The Client ID matches the pattern `*.apps.googleusercontent.com`. Search the extracted text for this pattern. If found, store it:
+## CLI Step 6: Collect Credentials
 
-```
-credential_store store:
-  service: "integration:gmail"
-  field: "client_id"
-  value: "<the Client ID extracted from the page>"
-```
+The `gws auth setup` output or the GCP Console shows the Client ID and Client Secret. Ask the user to copy-paste them into secure prompts.
 
-If `browser_extract` fails to find the Client ID, prompt the user instead:
+**Client ID:**
 
 ```
 credential_store prompt:
   service: "integration:gmail"
   field: "client_id"
   label: "Google OAuth Client ID"
-  description: "Copy the Client ID from the dialog in the Chrome window and paste it here. It looks like 123456789-xxxxx.apps.googleusercontent.com"
+  description: "Copy the Client ID from the setup output or GCP Console. It looks like 123456789-xxxxx.apps.googleusercontent.com"
   placeholder: "xxxxx.apps.googleusercontent.com"
 ```
 
-**Then**, whether the Client ID was auto-read or prompted, tell the user:
-
-> "Got the Client ID! Now I need the Client Secret. You can see it in the dialog in the Chrome window. It starts with `GOCSPX-`. Please copy it and paste it into the secure prompt below."
-
-And present the secure prompt:
+**Client Secret:**
 
 ```
 credential_store prompt:
   service: "integration:gmail"
   field: "client_secret"
   label: "Google OAuth Client Secret"
-  description: "Copy the Client Secret from the Google Cloud Console dialog and paste it here."
+  description: "Copy the Client Secret from the setup output or GCP Console. It starts with GOCSPX-"
   placeholder: "GOCSPX-..."
 ```
 
-Wait for the user to complete the prompt. **Do not take any other browser actions until the user has pasted the secret.** The dialog must stay open so they can see and copy the value.
-
-If the user has trouble locating the secret, take a `browser_screenshot` and describe where the secret field is on the screen, but do NOT attempt to read the secret value yourself. It must come from the user for accuracy.
-
-**What you should see when done:** `credential_store list` shows both `client_id` and `client_secret` for `integration:gmail`.
-
-Tell the user: "Credentials stored securely!"
+Wait for both prompts to be completed before continuing.
 
-## Step 7: OAuth2 Authorization
+## CLI Step 7: Authorize
 
-**Goal:** The user authorizes Vellum to access their Gmail and Calendar via OAuth.
-
-Tell the user: "Starting the authorization flow — a Google sign-in page will open in a few seconds. Just click 'Allow' when it appears."
+Tell the user: "Starting the authorization flow — a Google sign-in page will open. Just click 'Allow' when it appears."
 
 Use `credential_store` with:
 
@@ -429,15 +367,6 @@ This auto-reads client_id and client_secret from the secure store and auto-fills
 
 **Verify:** The `oauth2_connect` call returns a success message with the connected account email.
 
-## Step 8: Done!
+## CLI Step 8: Done!
 
 Tell the user: "**Gmail and Calendar are connected!** You can now read, search, and send emails, plus view and manage your calendar. Try asking me to check your inbox or show your upcoming events!"
-
-## Error Handling
-
-- **Page load failures:** Retry navigation once. If it still fails, tell the user and ask them to check their internet connection.
-- **Permission errors in GCP:** The user may need billing enabled or organization-level permissions. Explain clearly and ask them to resolve it.
-- **Consent screen already configured:** Don't overwrite. Skip to credential creation.
-- **Element not found:** Take a fresh `browser_snapshot` to re-assess. The GCP UI may have changed. Describe what you see and try alternative approaches. If stuck after 2 attempts, ask the user for guidance. They can see the Chrome window too.
-- **OAuth flow timeout or failure:** Offer to retry. The credentials are already stored, so reconnecting only requires re-running the authorization flow.
-- **Any unexpected state:** Take a `browser_screenshot`, describe what you see, and ask the user for guidance.

package/src/memory/db-init.ts

@@ -36,7 +36,6 @@ import {
   migrateBackfillContactInteractionStats,
   migrateBackfillGuardianPrincipalId,
   migrateCallSessionMode,
-  migrateDropAssistantIdColumns,
   migrateCanonicalGuardianDeliveriesDestinationIndex,
   migrateCanonicalGuardianRequesterChatId,
   migrateChannelInboundDeliveredSegments,
@@ -46,6 +45,7 @@ import {
   migrateContactsNotesColumn,
   migrateContactsRolePrincipal,
   migrateConversationsThreadTypeIndex,
+  migrateDropAssistantIdColumns,
   migrateDropLegacyMemberGuardianTables,
   migrateFkCascadeRebuilds,
   migrateGuardianActionFollowup,

package/src/memory/migrations/026-guardian-verification-sessions.ts

@@ -1,4 +1,5 @@
 import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
 
 /**
  * Extend channel_guardian_verification_challenges with outbound verification
@@ -83,13 +84,31 @@ export function migrateGuardianVerificationSessions(database: DrizzleDb): void {
   }
 
   // -- Indexes for session lookups --
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_active ON channel_guardian_verification_challenges(assistant_id, channel, status)`,
-  );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_identity ON channel_guardian_verification_challenges(assistant_id, channel, expected_external_user_id, expected_chat_id, status)`,
-  );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_destination ON channel_guardian_verification_challenges(assistant_id, channel, destination_address)`,
-  );
+  if (
+    tableHasColumn(
+      database,
+      "channel_guardian_verification_challenges",
+      "assistant_id",
+    )
+  ) {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_active ON channel_guardian_verification_challenges(assistant_id, channel, status)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_identity ON channel_guardian_verification_challenges(assistant_id, channel, expected_external_user_id, expected_chat_id, status)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_destination ON channel_guardian_verification_challenges(assistant_id, channel, destination_address)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_active ON channel_guardian_verification_challenges(channel, status)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_identity ON channel_guardian_verification_challenges(channel, expected_external_user_id, expected_chat_id, status)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_destination ON channel_guardian_verification_challenges(channel, destination_address)`,
+    );
+  }
 }

package/src/memory/migrations/027a-guardian-bootstrap-token.ts

@@ -1,4 +1,5 @@
 import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
 
 /**
  * Add bootstrap_token_hash column to channel_guardian_verification_challenges.
@@ -16,7 +17,19 @@ export function migrateGuardianBootstrapToken(database: DrizzleDb): void {
   }
 
   // Index for looking up pending_bootstrap sessions by bootstrap token hash
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_bootstrap ON channel_guardian_verification_challenges(assistant_id, channel, bootstrap_token_hash, status)`,
-  );
+  if (
+    tableHasColumn(
+      database,
+      "channel_guardian_verification_challenges",
+      "assistant_id",
+    )
+  ) {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_bootstrap ON channel_guardian_verification_challenges(assistant_id, channel, bootstrap_token_hash, status)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_sessions_bootstrap ON channel_guardian_verification_challenges(channel, bootstrap_token_hash, status)`,
+    );
+  }
 }

package/src/memory/migrations/038-actor-token-records.ts

@@ -1,4 +1,5 @@
 import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
 
 /**
  * Create the actor_token_records table for hash-only actor token persistence.
@@ -24,9 +25,15 @@ export function createActorTokenRecordsTable(database: DrizzleDb): void {
   `);
 
   // Unique active token per device binding
-  database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_actor_tokens_active_device
+  if (tableHasColumn(database, "actor_token_records", "assistant_id")) {
+    database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_actor_tokens_active_device
       ON actor_token_records(assistant_id, guardian_principal_id, hashed_device_id)
       WHERE status = 'active'`);
+  } else {
+    database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_actor_tokens_active_device
+      ON actor_token_records(guardian_principal_id, hashed_device_id)
+      WHERE status = 'active'`);
+  }
 
   // Token hash lookup for verification
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_actor_tokens_hash

package/src/memory/migrations/039-actor-refresh-token-records.ts

@@ -1,4 +1,5 @@
 import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
 
 /**
  * Create the actor_refresh_token_records table for hash-only refresh token persistence.
@@ -34,10 +35,18 @@ export function createActorRefreshTokenRecordsTable(database: DrizzleDb): void {
   // Unique active refresh token per device binding.
   // DROP first so that databases that already created the older non-unique
   // index with the same name get upgraded to UNIQUE.
-  database.run(/*sql*/ `DROP INDEX IF EXISTS idx_refresh_tokens_active_device`);
-  database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_refresh_tokens_active_device
+  if (tableHasColumn(database, "actor_refresh_token_records", "assistant_id")) {
+    database.run(
+      /*sql*/ `DROP INDEX IF EXISTS idx_refresh_tokens_active_device`,
+    );
+    database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_refresh_tokens_active_device
       ON actor_refresh_token_records(assistant_id, guardian_principal_id, hashed_device_id)
       WHERE status = 'active'`);
+  } else {
+    database.run(/*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_refresh_tokens_active_device
+      ON actor_refresh_token_records(guardian_principal_id, hashed_device_id)
+      WHERE status = 'active'`);
+  }
 
   // Family lookup for replay detection (revoke entire family)
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_refresh_tokens_family

package/src/memory/migrations/110-channel-guardian.ts

@@ -1,4 +1,5 @@
 import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
 
 /**
  * Channel guardian tables: bindings, verification challenges, approval requests,
@@ -43,9 +44,21 @@ export function createChannelGuardianTables(database: DrizzleDb): void {
     )
   `);
 
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_channel_guardian_challenges_lookup ON channel_guardian_verification_challenges(assistant_id, channel, challenge_hash, status)`,
-  );
+  if (
+    tableHasColumn(
+      database,
+      "channel_guardian_verification_challenges",
+      "assistant_id",
+    )
+  ) {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_channel_guardian_challenges_lookup ON channel_guardian_verification_challenges(assistant_id, channel, challenge_hash, status)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_channel_guardian_challenges_lookup ON channel_guardian_verification_challenges(channel, challenge_hash, status)`,
+    );
+  }
 
   database.run(/*sql*/ `
     CREATE TABLE IF NOT EXISTS channel_guardian_approval_requests (
@@ -139,7 +152,15 @@ export function createChannelGuardianTables(database: DrizzleDb): void {
     /* already exists */
   }
 
-  database.run(
-    /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_guardian_rate_limits_actor ON channel_guardian_rate_limits(assistant_id, channel, actor_external_user_id, actor_chat_id)`,
-  );
+  if (
+    tableHasColumn(database, "channel_guardian_rate_limits", "assistant_id")
+  ) {
+    database.run(
+      /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_guardian_rate_limits_actor ON channel_guardian_rate_limits(assistant_id, channel, actor_external_user_id, actor_chat_id)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_guardian_rate_limits_actor ON channel_guardian_rate_limits(channel, actor_external_user_id, actor_chat_id)`,
+    );
+  }
 }

package/src/memory/migrations/112-assistant-inbox.ts

@@ -1,5 +1,6 @@
 import type { DrizzleDb } from "../db-connection.js";
 import { migrateBackfillInboxThreadStateFromBindings } from "./014-backfill-inbox-thread-state.js";
+import { tableHasColumn } from "./schema-introspection.js";
 
 /**
  * Assistant inbox tables: ingress invites, ingress members, inbox thread state.
@@ -28,12 +29,21 @@ export function createAssistantInboxTables(database: DrizzleDb): void {
   database.run(
     /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_ingress_invites_token_hash ON assistant_ingress_invites(token_hash)`,
   );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_ingress_invites_channel_status ON assistant_ingress_invites(assistant_id, source_channel, status, expires_at)`,
-  );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_ingress_invites_channel_created ON assistant_ingress_invites(assistant_id, source_channel, created_at)`,
-  );
+  if (tableHasColumn(database, "assistant_ingress_invites", "assistant_id")) {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_ingress_invites_channel_status ON assistant_ingress_invites(assistant_id, source_channel, status, expires_at)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_ingress_invites_channel_created ON assistant_ingress_invites(assistant_id, source_channel, created_at)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_ingress_invites_channel_status ON assistant_ingress_invites(source_channel, status, expires_at)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_ingress_invites_channel_created ON assistant_ingress_invites(source_channel, created_at)`,
+    );
+  }
 
   database.run(/*sql*/ `
     CREATE TABLE IF NOT EXISTS assistant_ingress_members (
@@ -90,15 +100,29 @@ export function createAssistantInboxTables(database: DrizzleDb): void {
     )
   `);
 
-  database.run(
-    /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_inbox_thread_state_channel ON assistant_inbox_thread_state(assistant_id, source_channel, external_chat_id)`,
-  );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_inbox_thread_state_last_msg ON assistant_inbox_thread_state(assistant_id, last_message_at)`,
-  );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_inbox_thread_state_escalation ON assistant_inbox_thread_state(assistant_id, has_pending_escalation, last_message_at)`,
-  );
+  if (
+    tableHasColumn(database, "assistant_inbox_thread_state", "assistant_id")
+  ) {
+    database.run(
+      /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_inbox_thread_state_channel ON assistant_inbox_thread_state(assistant_id, source_channel, external_chat_id)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_inbox_thread_state_last_msg ON assistant_inbox_thread_state(assistant_id, last_message_at)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_inbox_thread_state_escalation ON assistant_inbox_thread_state(assistant_id, has_pending_escalation, last_message_at)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_inbox_thread_state_channel ON assistant_inbox_thread_state(source_channel, external_chat_id)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_inbox_thread_state_last_msg ON assistant_inbox_thread_state(last_message_at)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_inbox_thread_state_escalation ON assistant_inbox_thread_state(has_pending_escalation, last_message_at)`,
+    );
+  }
 
   migrateBackfillInboxThreadStateFromBindings(database);
 }

package/src/memory/migrations/114-notifications.ts

@@ -2,6 +2,7 @@ import type { DrizzleDb } from "../db-connection.js";
 import { migrateNotificationTablesSchema } from "./019-notification-tables-schema-migration.js";
 import { migrateNotificationDeliveryPairingColumns } from "./027-notification-delivery-pairing-columns.js";
 import { migrateNotificationDeliveryClientAck } from "./028-notification-delivery-client-ack.js";
+import { tableHasColumn } from "./schema-introspection.js";
 
 /**
  * Notification system tables: preferences, events, decisions, and deliveries.
@@ -24,12 +25,18 @@ export function createNotificationTables(database: DrizzleDb): void {
     )
   `);
 
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_preferences_assistant_id ON notification_preferences(assistant_id)`,
-  );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_preferences_assistant_priority ON notification_preferences(assistant_id, priority DESC)`,
-  );
+  if (tableHasColumn(database, "notification_preferences", "assistant_id")) {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_preferences_assistant_id ON notification_preferences(assistant_id)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_preferences_assistant_priority ON notification_preferences(assistant_id, priority DESC)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_preferences_priority ON notification_preferences(priority DESC)`,
+    );
+  }
 
   database.run(/*sql*/ `
     CREATE TABLE IF NOT EXISTS notification_events (
@@ -46,12 +53,21 @@ export function createNotificationTables(database: DrizzleDb): void {
     )
   `);
 
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_events_assistant_event_created ON notification_events(assistant_id, source_event_name, created_at)`,
-  );
-  database.run(
-    /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_events_dedupe ON notification_events(assistant_id, dedupe_key) WHERE dedupe_key IS NOT NULL`,
-  );
+  if (tableHasColumn(database, "notification_events", "assistant_id")) {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_events_assistant_event_created ON notification_events(assistant_id, source_event_name, created_at)`,
+    );
+    database.run(
+      /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_events_dedupe ON notification_events(assistant_id, dedupe_key) WHERE dedupe_key IS NOT NULL`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_events_event_created ON notification_events(source_event_name, created_at)`,
+    );
+    database.run(
+      /*sql*/ `CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_events_dedupe ON notification_events(dedupe_key) WHERE dedupe_key IS NOT NULL`,
+    );
+  }
 
   database.run(/*sql*/ `
     CREATE TABLE IF NOT EXISTS notification_decisions (
@@ -97,9 +113,15 @@ export function createNotificationTables(database: DrizzleDb): void {
   database.run(
     /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_decision_id ON notification_deliveries(notification_decision_id)`,
   );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_assistant_status ON notification_deliveries(assistant_id, status)`,
-  );
+  if (tableHasColumn(database, "notification_deliveries", "assistant_id")) {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_assistant_status ON notification_deliveries(assistant_id, status)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_status ON notification_deliveries(status)`,
+    );
+  }
 
   // Add conversation pairing audit columns (idempotent ALTER TABLE)
   migrateNotificationDeliveryPairingColumns(database);

package/src/memory/migrations/117-conversation-attention.ts

@@ -1,4 +1,5 @@
 import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
 
 /**
  * Conversation attention tables: append-only evidence log and single-row
@@ -24,9 +25,17 @@ export function createConversationAttentionTables(database: DrizzleDb): void {
   database.run(
     /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_events_conv_observed ON conversation_attention_events(conversation_id, observed_at DESC)`,
   );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_events_assistant_observed ON conversation_attention_events(assistant_id, observed_at DESC)`,
-  );
+  if (
+    tableHasColumn(database, "conversation_attention_events", "assistant_id")
+  ) {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_events_assistant_observed ON conversation_attention_events(assistant_id, observed_at DESC)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_events_observed ON conversation_attention_events(observed_at)`,
+    );
+  }
   database.run(
     /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_events_channel_observed ON conversation_attention_events(source_channel, observed_at DESC)`,
   );
@@ -50,10 +59,25 @@ export function createConversationAttentionTables(database: DrizzleDb): void {
     )
   `);
 
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_state_assistant_latest_msg ON conversation_assistant_attention_state(assistant_id, latest_assistant_message_at DESC)`,
-  );
-  database.run(
-    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_state_assistant_last_seen ON conversation_assistant_attention_state(assistant_id, last_seen_assistant_message_at DESC)`,
-  );
+  if (
+    tableHasColumn(
+      database,
+      "conversation_assistant_attention_state",
+      "assistant_id",
+    )
+  ) {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_state_assistant_latest_msg ON conversation_assistant_attention_state(assistant_id, latest_assistant_message_at DESC)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_state_assistant_last_seen ON conversation_assistant_attention_state(assistant_id, last_seen_assistant_message_at DESC)`,
+    );
+  } else {
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_state_latest_msg ON conversation_assistant_attention_state(latest_assistant_message_at)`,
+    );
+    database.run(
+      /*sql*/ `CREATE INDEX IF NOT EXISTS idx_conv_attn_state_last_seen ON conversation_assistant_attention_state(last_seen_assistant_message_at)`,
+    );
+  }
 }

package/src/memory/migrations/schema-introspection.ts

@@ -0,0 +1,18 @@
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Startup still replays the historical table/index bootstrap helpers on every
+ * process launch, so migrations need a cheap way to branch on the live schema.
+ */
+export function tableHasColumn(
+  database: DrizzleDb,
+  tableName: string,
+  columnName: string,
+): boolean {
+  const raw = getSqliteFrom(database);
+  const columns = raw.query(`PRAGMA table_info(${tableName})`).all() as Array<{
+    name: string;
+  }>;
+
+  return columns.some((column) => column.name === columnName);
+}

package/src/runtime/http-server.ts

@@ -127,6 +127,7 @@ import {
 } from "./routes/pairing-routes.js";
 import { secretRouteDefinitions } from "./routes/secret-routes.js";
 import { surfaceActionRouteDefinitions } from "./routes/surface-action-routes.js";
+import { surfaceContentRouteDefinitions } from "./routes/surface-content-routes.js";
 import { trustRulesRouteDefinitions } from "./routes/trust-rules-routes.js";
 import { twilioRouteDefinitions } from "./routes/twilio-routes.js";
 
@@ -183,15 +184,7 @@ export class RuntimeHttpServer {
   private pairingStore = new PairingStore();
   private pairingBroadcast?: (msg: ServerMessage) => void;
   private sendMessageDeps?: SendMessageDeps;
-  private findSession?: (sessionId: string) =>
-    | {
-        handleSurfaceAction(
-          surfaceId: string,
-          actionId: string,
-          data?: Record<string, unknown>,
-        ): void;
-      }
-    | undefined;
+  private findSession?: RuntimeHttpServerOptions["findSession"];
   private router: HttpRouter;
 
   constructor(options: RuntimeHttpServerOptions = {}) {
@@ -847,6 +840,7 @@ export class RuntimeHttpServer {
       ...approvalRouteDefinitions(),
       ...trustRulesRouteDefinitions(),
       ...surfaceActionRouteDefinitions({ findSession: this.findSession }),
+      ...surfaceContentRouteDefinitions({ findSession: this.findSession }),
       ...guardianActionRouteDefinitions(),
 
       ...contactRouteDefinitions(),

package/src/runtime/http-types.ts

@@ -2,6 +2,7 @@
  * Shared types for the runtime HTTP server and its route handlers.
  */
 import type { ChannelId, InterfaceId } from "../channels/types.js";
+import type { SurfaceData, SurfaceType } from "../daemon/ipc-contract/surfaces.js";
 import type { Session } from "../daemon/session.js";
 import type { TrustContext } from "../daemon/session-runtime-assembly.js";
 import type {
@@ -169,7 +170,7 @@ export interface RuntimeHttpServerOptions {
   guardianFollowUpConversationGenerator?: GuardianFollowUpConversationGenerator;
   /** Dependencies for the POST /v1/messages queue-if-busy handler. */
   sendMessageDeps?: SendMessageDeps;
-  /** Lookup an active session by ID (for surface actions). Returns undefined if not found. */
+  /** Lookup an active session by ID (for surface actions and content fetches). */
   findSession?: (sessionId: string) =>
     | {
         handleSurfaceAction(
@@ -177,6 +178,17 @@ export interface RuntimeHttpServerOptions {
           actionId: string,
           data?: Record<string, unknown>,
         ): void;
+        surfaceState: Map<
+          string,
+          { surfaceType: SurfaceType; data: SurfaceData; title?: string }
+        >;
+        currentTurnSurfaces?: Array<{
+          surfaceId: string;
+          surfaceType: SurfaceType;
+          title?: string;
+          data: SurfaceData;
+          actions?: Array<{ id: string; label: string; style?: string }>;
+        }>;
       }
     | undefined;
 }

package/src/runtime/routes/guardian-bootstrap-routes.ts

@@ -114,7 +114,7 @@ export async function handleGuardianBootstrap(
       );
     }
 
-    if (platform !== "macos" && platform !== "cli") {
+    if (platform !== "macos" && platform !== "cli" && platform !== "web") {
       return httpError(
         "BAD_REQUEST",
         "Invalid platform. Bootstrap is macOS/CLI-only; iOS uses QR pairing.",

package/src/runtime/routes/surface-content-routes.ts

@@ -0,0 +1,104 @@
+/**
+ * Route handler for fetching surface content by ID.
+ *
+ * GET /v1/surfaces/:surfaceId — return the full surface payload from the
+ * session's in-memory surface state. Used by clients to re-hydrate surfaces
+ * whose data was stripped during memory compaction.
+ */
+import type { SurfaceData, SurfaceType } from "../../daemon/ipc-contract/surfaces.js";
+import { getLogger } from "../../util/logger.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+const log = getLogger("surface-content-routes");
+
+/** Narrow interface for looking up surface state from a session. */
+interface SurfaceContentTarget {
+  surfaceState: Map<
+    string,
+    { surfaceType: SurfaceType; data: SurfaceData; title?: string }
+  >;
+  currentTurnSurfaces?: Array<{
+    surfaceId: string;
+    surfaceType: SurfaceType;
+    title?: string;
+    data: SurfaceData;
+    actions?: Array<{ id: string; label: string; style?: string }>;
+  }>;
+}
+
+export type SurfaceContentSessionLookup = (
+  sessionId: string,
+) => SurfaceContentTarget | undefined;
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function surfaceContentRouteDefinitions(deps: {
+  findSession?: SurfaceContentSessionLookup;
+}): RouteDefinition[] {
+  return [
+    {
+      endpoint: "surfaces/:surfaceId",
+      method: "GET",
+      handler: ({ url, params }) => {
+        if (!deps.findSession) {
+          return httpError(
+            "NOT_IMPLEMENTED",
+            "Surface content lookup not available",
+            501,
+          );
+        }
+
+        const sessionId = url.searchParams.get("sessionId");
+        if (!sessionId) {
+          return httpError("BAD_REQUEST", "sessionId query parameter is required", 400);
+        }
+
+        const surfaceId = params.surfaceId;
+        if (!surfaceId) {
+          return httpError("BAD_REQUEST", "surfaceId path parameter is required", 400);
+        }
+
+        const session = deps.findSession(sessionId);
+        if (!session) {
+          return httpError(
+            "NOT_FOUND",
+            "No active session found for this sessionId",
+            404,
+          );
+        }
+
+        // Look up the surface in the session's in-memory state.
+        const stored = session.surfaceState.get(surfaceId);
+        if (stored) {
+          log.info({ sessionId, surfaceId }, "Surface content served from surfaceState");
+          return Response.json({
+            surfaceId,
+            surfaceType: stored.surfaceType,
+            title: stored.title ?? null,
+            data: stored.data,
+          });
+        }
+
+        // Fall back to currentTurnSurfaces in case the surface hasn't been
+        // committed to surfaceState yet (e.g. mid-turn).
+        const turnSurface = session.currentTurnSurfaces?.find(
+          (s) => s.surfaceId === surfaceId,
+        );
+        if (turnSurface) {
+          log.info({ sessionId, surfaceId }, "Surface content served from currentTurnSurfaces");
+          return Response.json({
+            surfaceId,
+            surfaceType: turnSurface.surfaceType,
+            title: turnSurface.title ?? null,
+            data: turnSurface.data,
+          });
+        }
+
+        return httpError("NOT_FOUND", "Surface not found in session", 404);
+      },
+    },
+  ];
+}