@vellumai/assistant 0.4.10 → 0.4.12

package/src/config/bundled-skills/messaging/tools/messaging-sender-digest.ts

@@ -43,7 +43,8 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
         senders,
         total_scanned: result.totalScanned,
         query_used: result.queryUsed,
-        note: `message_count reflects emails found per sender within the ${result.totalScanned} messages scanned. The archive tool may find additional messages beyond this sample.`,
+        ...(result.truncated ? { truncated: true } : {}),
+        note: `message_count reflects emails found per sender within the ${result.totalScanned} messages scanned. Use the message_ids array with the archive tool to archive exactly these messages.`,
       }));
     });
   } catch (e) {

package/src/config/bundled-skills/notion/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: "Notion"
+description: "Read and write Notion pages and databases using the Notion API"
+user-invocable: false
+metadata: {"vellum": {"emoji": "📝"}}
+---
+
+You have access to the Notion API via the stored OAuth token for `integration:notion`. Use `bash` with `network_mode: "proxied"` to call the Notion API — the proxy automatically injects the Bearer token for `api.notion.com`.
+
+## Authentication
+
+The Notion access token is stored securely and never exposed as plaintext. Use the credential proxy to inject the Bearer token automatically.
+
+**Step 1 — Get the credential ID:**
+```
+credential_store action=list
+```
+Find the entry with `service: "integration:notion"` and `field: "access_token"`. Note its `credential_id`.
+
+If no such entry exists, tell the user: "Notion is not connected yet. Load the **notion-oauth-setup** skill to set it up first."
+
+**Step 2 — Make authenticated API calls via the proxy:**
+
+Use `bash` with `network_mode: "proxied"` and `credential_ids: ["<credential_id>"]`. The proxy automatically injects `Authorization: Bearer <token>` and any required headers into requests to `api.notion.com`.
+
+Example:
+```
+bash:
+  network_mode: proxied
+  credential_ids: ["<credential_id from step 1>"]
+  command: |
+    curl -s -X POST https://api.notion.com/v1/search \
+      -H "Notion-Version: 2022-06-28" \
+      -H "Content-Type: application/json" \
+      -d '{}'
+```
+
+All Notion API calls go to `https://api.notion.com/v1/`. Always include the `Notion-Version: 2022-06-28` header.
+
+## Reading Pages
+
+### Get a page by ID
+```
+GET https://api.notion.com/v1/pages/{page_id}
+```
+Returns page properties. Use the page ID from a Notion URL — the last segment of the URL, e.g. for `https://notion.so/My-Page-abc123def456` the ID is `abc123def456` (formatted as UUID: `abc123de-f456-...`).
+
+### Get page content (blocks)
+```
+GET https://api.notion.com/v1/blocks/{block_id}/children?page_size=100
+```
+Pages are blocks too — use the page ID as the `block_id`. Iterates through the page's child blocks. Use `start_cursor` for pagination when `has_more` is `true`.
+
+**Block types and how to render them:**
+- `paragraph`: Read `paragraph.rich_text[].plain_text`
+- `heading_1`, `heading_2`, `heading_3`: Read `heading_N.rich_text[].plain_text`
+- `bulleted_list_item`, `numbered_list_item`: Read `*.rich_text[].plain_text`
+- `to_do`: Read `to_do.rich_text[].plain_text` and `to_do.checked`
+- `toggle`: Read `toggle.rich_text[].plain_text`; children are nested blocks
+- `code`: Read `code.rich_text[].plain_text` and `code.language`
+- `quote`: Read `quote.rich_text[].plain_text`
+- `callout`: Read `callout.rich_text[].plain_text`
+- `divider`: Render as `---`
+- `image`: Read `image.external.url` or `image.file.url`
+- `child_page`: Read `child_page.title`; use its `id` to recursively fetch if needed
+
+## Searching
+
+### Search pages and databases
+```
+POST https://api.notion.com/v1/search
+{
+  "query": "your search term",
+  "filter": { "value": "page", "property": "object" },
+  "sort": { "direction": "descending", "timestamp": "last_edited_time" },
+  "page_size": 10
+}
+```
+Omit `filter` to search both pages and databases. Use `filter.value: "database"` to search only databases.
+
+Returns `results[]` with `id`, `url`, `properties.title` (for pages), and `title[]` (for databases).
+
+## Reading Databases
+
+### Get database metadata
+```
+GET https://api.notion.com/v1/databases/{database_id}
+```
+Returns the database schema (all property definitions).
+
+### Query a database
+```
+POST https://api.notion.com/v1/databases/{database_id}/query
+{
+  "filter": {
+    "property": "Status",
+    "select": { "equals": "In Progress" }
+  },
+  "sorts": [
+    { "property": "Created", "direction": "descending" }
+  ],
+  "page_size": 20
+}
+```
+Omit `filter` to retrieve all rows. Returns `results[]` where each item is a page (database row).
+
+**Extracting property values from database rows:**
+- `title`: `properties.Name.title[].plain_text`
+- `rich_text`: `properties.Notes.rich_text[].plain_text`
+- `number`: `properties.Price.number`
+- `select`: `properties.Status.select.name`
+- `multi_select`: `properties.Tags.multi_select[].name`
+- `date`: `properties.Due.date.start` (ISO 8601)
+- `checkbox`: `properties.Done.checkbox`
+- `url`: `properties.Link.url`
+- `email`: `properties.Email.email`
+- `people`: `properties.Owner.people[].name`
+- `relation`: `properties.Projects.relation[].id` (array of page IDs)
+
+## Creating Pages
+
+### Create a new page
+```
+POST https://api.notion.com/v1/pages
+{
+  "parent": { "page_id": "<parent_page_id>" },
+  "properties": {
+    "title": {
+      "title": [{ "text": { "content": "My New Page" } }]
+    }
+  },
+  "children": [
+    {
+      "object": "block",
+      "type": "paragraph",
+      "paragraph": {
+        "rich_text": [{ "text": { "content": "Page content here." } }]
+      }
+    }
+  ]
+}
+```
+
+For database rows, use `"parent": { "database_id": "<database_id>" }` and include the database's required properties.
+
+## Updating Pages
+
+### Update page properties
+```
+PATCH https://api.notion.com/v1/pages/{page_id}
+{
+  "properties": {
+    "Status": { "select": { "name": "Done" } },
+    "Due": { "date": { "start": "2024-12-31" } }
+  }
+}
+```
+
+### Append blocks to a page
+```
+PATCH https://api.notion.com/v1/blocks/{block_id}/children
+{
+  "children": [
+    {
+      "object": "block",
+      "type": "paragraph",
+      "paragraph": {
+        "rich_text": [{ "text": { "content": "Appended content." } }]
+      }
+    },
+    {
+      "object": "block",
+      "type": "heading_2",
+      "heading_2": {
+        "rich_text": [{ "text": { "content": "A heading" } }]
+      }
+    },
+    {
+      "object": "block",
+      "type": "bulleted_list_item",
+      "bulleted_list_item": {
+        "rich_text": [{ "text": { "content": "A bullet point" } }]
+      }
+    },
+    {
+      "object": "block",
+      "type": "to_do",
+      "to_do": {
+        "rich_text": [{ "text": { "content": "A task" } }],
+        "checked": false
+      }
+    }
+  ]
+}
+```
+
+### Update a block's content
+```
+PATCH https://api.notion.com/v1/blocks/{block_id}
+{
+  "paragraph": {
+    "rich_text": [{ "text": { "content": "Updated text." } }]
+  }
+}
+```
+
+### Delete (archive) a block
+```
+DELETE https://api.notion.com/v1/blocks/{block_id}
+```
+
+## Archive / Delete Pages
+
+Notion does not permanently delete pages via the API — it archives them:
+```
+PATCH https://api.notion.com/v1/pages/{page_id}
+{
+  "archived": true
+}
+```
+
+## Pagination
+
+When a response includes `"has_more": true`, pass `"start_cursor": response.next_cursor` in the next request to get the next page of results.
+
+## Error Handling
+
+- **401 Unauthorized**: The access token is missing or expired. Ask the user to reconnect Notion via the **notion-oauth-setup** skill.
+- **403 Forbidden**: The integration doesn't have access to the requested page or database. Remind the user that they need to share the page/database with the "Vellum Assistant" integration in Notion (via the Share menu → "Add connections").
+- **404 Not Found**: The page or database ID doesn't exist or the integration can't see it. Verify the ID and check sharing settings.
+- **400 Bad Request**: Check the request body structure. The Notion API error response includes a `message` field with details.
+- **429 Too Many Requests**: Wait a few seconds and retry.
+
+## Tips
+
+- Notion page IDs in URLs are formatted without hyphens. The API accepts both forms: `abc123def456...` or `abc123de-f456-...`.
+- When extracting IDs from Notion URLs, strip any query parameters and trailing path components after the 32-character ID segment.
+- Always include `Notion-Version: 2022-06-28` header to get stable API behavior.
+- For rich text, concatenate all `plain_text` values in the array to get the full text content.
+- When creating content with rich text formatting (bold, italic, links), use the `annotations` and `href` fields in rich_text objects.

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

@@ -0,0 +1,127 @@
+---
+name: "Notion OAuth Setup"
+description: "Create a Notion integration and OAuth credentials for Notion integration using browser automation"
+user-invocable: true
+includes: ["browser", "public-ingress"]
+metadata: {"vellum": {"emoji": "🔑"}}
+---
+
+You are helping your user create a Notion integration (OAuth app) so Vellum can connect to their Notion workspace. Walk through each step below using `browser_navigate`, `browser_snapshot`, `browser_screenshot`, `browser_click`, `browser_type`, and `browser_extract` tools.
+
+**Tone:** Be friendly and reassuring throughout. Narrate what you're doing in plain language so the user always knows what's happening. After each step, briefly confirm what was accomplished before moving on.
+
+## Prerequisites
+
+Before starting, check that `ingress.publicBaseUrl` is configured (Settings > Public Ingress, or `INGRESS_PUBLIC_BASE_URL` env var). If it is not set, load and execute the **public-ingress** skill first (`skill_load` with `skill: "public-ingress"`) to set up an ngrok tunnel and persist the public URL. The OAuth redirect URI depends on this value.
+
+## Before You Start
+
+Tell the user:
+- "I'll walk you through creating a Notion integration so Vellum can read and write pages and databases in your workspace. The whole process takes a few minutes."
+- "I'll be automating the Notion integrations page in the browser — you'll be able to see everything I'm doing."
+- "I'll ask for your approval before each major step, so nothing happens without your say-so."
+- "No sensitive credentials will be shown in the conversation."
+
+## Step 1: Navigate to Notion Integrations
+
+Tell the user: "First, let me open the Notion integrations page."
+
+Use `browser_navigate` to go to `https://www.notion.so/my-integrations`.
+
+Take a `browser_screenshot` to show the user what loaded, then take a `browser_snapshot` to check the page state:
+- **If a sign-in page appears:** Tell the user "Please sign in to your Notion account in the browser window. Let me know when you're done." Wait for their confirmation, then take another snapshot.
+- **If the integrations dashboard loads:** Tell the user "Notion integrations page is loaded. Let's create your integration!" and continue to Step 2.
+
+## Step 2: Create a New Integration
+
+**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` and this message:
+
+> **Create a Notion Integration**
+>
+> I'm about to create a new Notion integration called "Vellum Assistant". This integration will only have the capabilities you approve — it won't access any pages or databases until you explicitly share them with it or authorize it via OAuth.
+
+Wait for the user to approve. If they decline, explain that the integration is required for OAuth and offer to try again or cancel.
+
+Once approved:
+1. Click "New integration" (or the "+" button)
+2. Select "Public" as the integration type (required for OAuth)
+3. Enter integration name: "Vellum Assistant"
+4. Select the user's workspace
+5. Click "Submit" or "Create"
+
+Take a `browser_screenshot` to show the result.
+
+Tell the user: "Integration created! Now let's configure the OAuth settings."
+
+## Step 3: Configure OAuth Settings
+
+Navigate to the integration's "Distribution" or "OAuth Domain & URIs" tab.
+
+**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` and this message:
+
+> **Configure OAuth Redirect URI**
+>
+> I'm about to add the OAuth redirect URI to your Notion integration. This allows Notion to send the authorization code back to Vellum after you approve the connection.
+
+Wait for the user to approve.
+
+Once approved:
+1. Find the "Redirect URIs" field
+2. Enter `${ingress.publicBaseUrl}/webhooks/oauth/callback` (e.g. `https://abc123.ngrok-free.app/webhooks/oauth/callback`). Read the `ingress.publicBaseUrl` value from the assistant's workspace config (Settings > Public Ingress) or the `INGRESS_PUBLIC_BASE_URL` environment variable.
+3. Save the settings
+
+Take a `browser_snapshot` to confirm.
+
+Tell the user: "Redirect URI configured. Now let's get your OAuth credentials."
+
+## Step 4: Extract Client ID and Client Secret
+
+Stay on the integration settings page and navigate to the "Secrets" or "OAuth Clients" section.
+
+Use `browser_extract` to read:
+1. **OAuth client_id** — this is the integration's OAuth client ID
+2. **OAuth client_secret** — click "Show" or "Reveal" first, then extract the value
+
+**Important:** Notion requires a client secret for the token exchange (sent via HTTP Basic Auth). Both values are needed.
+
+Tell the user: "Credentials extracted! Now let's connect your Notion workspace."
+
+## Step 5: Connect Notion
+
+Tell the user: "Opening Notion authorization so you can grant Vellum access to your workspace. You'll see a Notion consent page — just click 'Allow access'."
+
+Use the `credential_store` tool to connect Notion via OAuth2:
+
+```
+action: "oauth2_connect"
+service: "integration:notion"
+client_id: "<the extracted OAuth client_id>"
+client_secret: "<the extracted OAuth client_secret>"
+auth_url: "https://api.notion.com/v1/oauth/authorize"
+token_url: "https://api.notion.com/v1/oauth/token"
+scopes: []
+extra_params: {"owner": "user"}
+token_endpoint_auth_method: "client_secret_basic"
+```
+
+This will open the Notion authorization page in the user's browser. Wait for the flow to complete.
+
+## Step 6: Celebrate!
+
+Once connected, tell the user:
+
+"**Notion is connected!** You're all set. You can now read and write pages and databases in your Notion workspace through Vellum. Try asking me to list your databases or read a specific page!"
+
+Summarize what was accomplished:
+- Created a Notion public integration called "Vellum Assistant"
+- Configured the OAuth redirect URI
+- Connected your Notion workspace with read and write access
+
+## Error Handling
+
+- **Page load failures:** Retry navigation once. If it still fails, tell the user and ask them to check their internet connection.
+- **"Public" integration type not available:** The user may need to enable public integrations in their workspace settings. Guide them to Workspace Settings > Integrations.
+- **Element not found for click/type:** Take a fresh `browser_snapshot` to re-assess the page layout. Notion's UI may have changed; adapt your selectors.
+- **User declines an approval gate:** Don't push back. Explain briefly why the step matters, offer to try again, or cancel gracefully.
+- **OAuth flow timeout or failure:** Tell the user what happened and offer to retry. The integration is already created, so they only need to re-run the connect step.
+- **Any unexpected state:** Take a `browser_screenshot` and `browser_snapshot`, describe what you see, and ask the user for guidance.

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

@@ -0,0 +1,144 @@
+---
+name: "OAuth Setup"
+description: "Connect any OAuth service — create app credentials and authorize via browser automation"
+user-invocable: true
+includes: ["browser"]
+metadata: {"vellum": {"emoji": "🔑"}}
+---
+
+You are helping the user connect an OAuth-based service to Vellum. This is a generic setup flow that works for any provider with a well-known OAuth config.
+
+**Tone:** Be friendly and reassuring throughout. Narrate what you're doing in plain language so the user always knows what's happening. After each step, briefly confirm what was accomplished before moving on.
+
+## Input
+
+You will be given a `service` name (e.g., "discord", "linear", "spotify"). If not provided, ask the user which service they want to connect.
+
+## Step 1: Read the service config
+
+Use `credential_store` with `action: "describe"` and `service: "<name>"` to get the well-known OAuth config. This returns:
+- `scopes` — permissions to request
+- `redirectUri` — the callback URL to register
+- `callbackTransport` — loopback or gateway
+- `requiresClientSecret` — whether a client secret is needed
+- `authUrl` / `tokenUrl` — OAuth endpoints
+
+It may also include a `setup` object with rich metadata:
+- `setup.displayName` — the provider's name
+- `setup.dashboardUrl` — where to create the app
+- `setup.appType` — what kind of app to create
+- `setup.requiresClientSecret` — whether a client secret is needed
+- `setup.notes` — provider-specific guidance
+
+If no config is found, tell the user this service doesn't have a pre-configured setup and offer to help them configure it manually via `oauth2_connect`.
+
+## Step 2: Choose the flow based on setup metadata
+
+### If `setup` metadata is present (rich flow)
+
+Continue to Step 3 (Rich Flow).
+
+### If `setup` metadata is absent (manual flow)
+
+The provider has OAuth config (endpoints, scopes) but no setup automation metadata. Guide the user through a manual app creation:
+
+1. Tell the user: "I have the OAuth endpoints and scopes for this service, but I don't have developer dashboard automation for it. You'll need to create an OAuth app manually."
+2. Provide the details they need:
+   - **Scopes to request:** list the `scopes` from the config
+   - **Redirect URI:** show the `redirectUri` value
+   - **Whether a client secret is required:** use the top-level `requiresClientSecret` field
+3. Ask the user to:
+   - Go to the provider's developer dashboard
+   - Create an OAuth app (name it "Vellum Assistant")
+   - Set the redirect URI
+   - Configure the required scopes
+   - Copy the Client ID (and Client Secret if required)
+4. Once they provide the credentials, skip to **Step 8: Connect**.
+
+---
+
+## Rich Flow (when `setup` is present)
+
+### Step 3: Tell the user what's happening
+
+Tell the user:
+- "I'll walk you through creating a {setup.appType} so Vellum can connect to {setup.displayName}. The whole process takes a few minutes."
+- "I'll be automating the {setup.displayName} developer dashboard in the browser — you'll be able to see everything I'm doing."
+- "I'll ask for your approval before each major step, so nothing happens without your say-so."
+
+### Step 4: Navigate to the developer dashboard
+
+Use `browser_navigate` to go to `setup.dashboardUrl`.
+
+Take a `browser_screenshot` and `browser_snapshot`:
+- **If a sign-in page appears:** Tell the user to sign in and wait for confirmation.
+- **If the dashboard loads:** Continue to Step 5.
+
+### Step 5: Create an app
+
+**Ask for approval before proceeding.** Use `ui_show` with `surface_type: "confirmation"` explaining what you're about to create.
+
+Once approved:
+1. Find and click the "Create App" / "New Application" / "New Integration" button (adapt to the provider's UI)
+2. Name it "Vellum Assistant"
+3. Follow any guidance from `setup.notes`
+4. Complete the creation flow
+
+Take a `browser_screenshot` to confirm.
+
+### Step 6: Configure scopes/permissions
+
+**Ask for approval before proceeding.** List the `scopes` from the config and explain what each grants.
+
+Once approved, navigate to the OAuth/permissions section and add each scope. Follow `setup.notes` for any provider-specific guidance (e.g., "User Token Scopes" vs "Bot Token Scopes").
+
+Take a `browser_screenshot` after adding all scopes.
+
+### Step 7: Set redirect URL
+
+Check the `redirectUri` from the config:
+- If it mentions "not currently configured", `GATEWAY_BASE_URL`, or `INGRESS_PUBLIC_BASE_URL` — the user needs a public gateway URL configured. Check if one is set; if not, load the `public-ingress` skill first.
+- If it says "automatic" — skip this step entirely (no redirect URI needed).
+- Otherwise, enter the `redirectUri` exactly as provided.
+
+Take a `browser_snapshot` to confirm.
+
+### Step 7b: Extract credentials
+
+Navigate to the app's credentials/settings section.
+
+Use `browser_extract` to read:
+1. **Client ID** (or equivalent)
+2. **Client Secret** (if `requiresClientSecret` is true) — click "Show"/"Reveal" first if needed
+
+---
+
+## Step 8: Connect
+
+Tell the user you're opening the authorization page.
+
+Use `credential_store` with:
+```
+action: "oauth2_connect"
+service: "<service name>"
+client_id: "<extracted client ID>"
+client_secret: "<extracted client secret>"  (if required)
+```
+
+Everything else (endpoints, scopes, params) is auto-filled from the well-known config. Wait for the flow to complete.
+
+## Step 9: Celebrate!
+
+Once connected, tell the user:
+- If `setup` is present: "**{setup.displayName} is connected!** You're all set."
+- If `setup` is absent: "**{service} is connected!** You're all set."
+
+Summarize what was accomplished.
+
+## Error Handling
+
+- **Page load failures:** Retry once. If it still fails, ask the user to check their connection.
+- **Element not found:** Take a fresh `browser_snapshot`. The provider's UI may have changed — adapt dynamically.
+- **User declines an approval gate:** Don't push back. Explain why it matters, offer to retry or cancel.
+- **OAuth flow timeout or failure:** Offer to retry. The app is already created, so only the connect step needs to be re-run.
+- **Any unexpected state:** Take a `browser_screenshot` and `browser_snapshot`, describe what you see, and ask for guidance.