@vellumai/assistant 0.4.11 → 0.4.13

package/src/config/bundled-skills/messaging/tools/gmail-archive-by-query.ts

@@ -7,7 +7,11 @@ import { err,ok } from './shared.js';
 const BATCH_MODIFY_LIMIT = 1000;
 const MAX_MESSAGES = 5000;
 
-export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+export async function run(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+  if (!context.triggeredBySurfaceAction) {
+    return err('This tool requires user confirmation via a surface action. Present results in a selection table with action buttons and wait for the user to click before proceeding.');
+  }
+
   const query = input.query as string;
 
   if (!query) {

package/src/config/bundled-skills/messaging/tools/gmail-batch-archive.ts

@@ -4,7 +4,13 @@ import { withValidToken } from '../../../../security/token-manager.js';
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
 import { err,ok } from './shared.js';
 
-export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+const BATCH_MODIFY_LIMIT = 1000;
+
+export async function run(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+  if (!context.triggeredBySurfaceAction) {
+    return err('This tool requires user confirmation via a surface action. Present results in a selection table with action buttons and wait for the user to click before proceeding.');
+  }
+
   const messageIds = input.message_ids as string[];
 
   if (!messageIds?.length) {
@@ -14,7 +20,10 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
   try {
     const provider = getMessagingProvider('gmail');
     return withValidToken(provider.credentialService, async (token) => {
-      await batchModifyMessages(token, messageIds, { removeLabelIds: ['INBOX'] });
+      for (let i = 0; i < messageIds.length; i += BATCH_MODIFY_LIMIT) {
+        const chunk = messageIds.slice(i, i + BATCH_MODIFY_LIMIT);
+        await batchModifyMessages(token, chunk, { removeLabelIds: ['INBOX'] });
+      }
       return ok(`Archived ${messageIds.length} message(s).`);
     });
   } catch (e) {

package/src/config/bundled-skills/messaging/tools/gmail-outreach-scan.ts

@@ -70,6 +70,7 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
   const maxSenders = (input.max_senders as number) ?? 30;
   const timeRange = (input.time_range as string) ?? '90d';
   const minConfidence = (input.min_confidence as number) ?? 0.5;
+  const inputPageToken = input.page_token as string | undefined;
 
   const query = `in:inbox -has:unsubscribe newer_than:${timeRange}`;
 
@@ -78,7 +79,8 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
     return withValidToken(provider.credentialService, async (token) => {
       // Paginate through listMessages to collect up to maxMessages IDs
       const allMessageIds: string[] = [];
-      let pageToken: string | undefined;
+      let pageToken: string | undefined = inputPageToken;
+      let truncated = false;
 
       while (allMessageIds.length < maxMessages) {
         const pageSize = Math.min(100, maxMessages - allMessageIds.length);
@@ -90,6 +92,10 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
         if (!pageToken) break;
       }
 
+      if (allMessageIds.length >= maxMessages && pageToken) {
+        truncated = true;
+      }
+
       if (allMessageIds.length === 0) {
         return ok(JSON.stringify({ senders: [], total_scanned: 0, outreach_detected: 0, message: 'No emails found matching the query.' }));
       }
@@ -215,6 +221,7 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
         senders,
         total_scanned: allMessageIds.length,
         outreach_detected: totalOutreachDetected,
+        ...(truncated ? { truncated: true, next_page_token: pageToken } : {}),
       }));
     });
   } catch (e) {

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

@@ -4,8 +4,8 @@ import { withValidToken } from '../../../../security/token-manager.js';
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
 import { err,ok } from './shared.js';
 
-const MAX_MESSAGES_CAP = 2000;
-const MAX_IDS_PER_SENDER = 1000;
+const MAX_MESSAGES_CAP = 500;
+const MAX_IDS_PER_SENDER = 500;
 const MAX_SAMPLE_SUBJECTS = 3;
 
 interface SenderAggregation {
@@ -38,13 +38,15 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
   const query = (input.query as string) ?? 'category:promotions newer_than:90d';
   const maxMessages = Math.min((input.max_messages as number) ?? 500, MAX_MESSAGES_CAP);
   const maxSenders = (input.max_senders as number) ?? 30;
+  const inputPageToken = input.page_token as string | undefined;
 
   try {
     const provider = getMessagingProvider('gmail');
     return withValidToken(provider.credentialService, async (token) => {
       // Paginate through listMessages to collect up to maxMessages IDs
       const allMessageIds: string[] = [];
-      let pageToken: string | undefined;
+      let pageToken: string | undefined = inputPageToken;
+      let truncated = false;
 
       while (allMessageIds.length < maxMessages) {
         const pageSize = Math.min(100, maxMessages - allMessageIds.length);
@@ -56,6 +58,11 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
         if (!pageToken) break;
       }
 
+      // If we stopped because we hit the cap but there were still more pages, flag truncation
+      if (allMessageIds.length >= maxMessages && pageToken) {
+        truncated = true;
+      }
+
       if (allMessageIds.length === 0) {
         return ok(JSON.stringify({ senders: [], total_scanned: 0, message: 'No emails found matching the query. Try broadening the search (e.g. remove category filter or extend date range).' }));
       }
@@ -165,7 +172,8 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
         senders: result,
         total_scanned: allMessageIds.length,
         query_used: query,
-        note: `message_count reflects emails found per sender within the ${allMessageIds.length} messages scanned. The archive tool may find additional messages beyond this sample.`,
+        ...(truncated ? { truncated: true, next_page_token: pageToken } : {}),
+        note: `message_count reflects emails found per sender within the ${allMessageIds.length} messages scanned. Use the message_ids array with gmail_batch_archive to archive exactly these messages.`,
       }));
     });
   } catch (e) {

package/src/config/bundled-skills/messaging/tools/gmail-unsubscribe.ts

@@ -5,7 +5,11 @@ import { isPrivateOrLocalHost, resolveHostAddresses, resolveRequestAddress } fro
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
 import { err, ok, pinnedHttpsRequest } from './shared.js';
 
-export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+export async function run(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+  if (!context.triggeredBySurfaceAction) {
+    return err('This tool requires user confirmation via a surface action. Present results in a selection table with action buttons and wait for the user to click before proceeding.');
+  }
+
   const messageId = input.message_id as string;
 
   if (!messageId) {

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

@@ -1,7 +1,11 @@
 import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
 import { err, ok, resolveProvider, withProviderToken } from './shared.js';
 
-export async function run(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+export async function run(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+  if (!context.triggeredBySurfaceAction) {
+    return err('This tool requires user confirmation via a surface action. Present results in a selection table with action buttons and wait for the user to click before proceeding.');
+  }
+
   const platform = input.platform as string | undefined;
   const query = input.query as string;
 

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

@@ -6,6 +6,7 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
   const query = (input.query as string) ?? 'category:promotions newer_than:90d';
   const maxMessages = input.max_messages as number | undefined;
   const maxSenders = input.max_senders as number | undefined;
+  const pageToken = input.page_token as string | undefined;
 
   try {
     const provider = resolveProvider(platform);
@@ -15,13 +16,14 @@ export async function run(input: Record<string, unknown>, _context: ToolContext)
     }
 
     return withProviderToken(provider, async (token) => {
-      const result = await provider.senderDigest!(token, query, { maxMessages, maxSenders });
+      const result = await provider.senderDigest!(token, query, { maxMessages, maxSenders, pageToken });
 
       if (result.senders.length === 0) {
         return ok(JSON.stringify({
           senders: [],
           total_scanned: result.totalScanned,
           query_used: result.queryUsed,
+          ...(result.truncated ? { truncated: true, next_page_token: result.nextPageToken } : {}),
           message: 'No emails found matching the query. Try broadening the search (e.g. remove category filter or extend date range).',
         }));
       }
@@ -43,7 +45,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, next_page_token: result.nextPageToken } : {}),
+        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.