@vellumai/assistant 0.4.46 → 0.4.49

package/src/config/bundled-skills/claude-code/TOOLS.json

@@ -37,10 +37,6 @@
             "type": "string",
             "enum": ["general", "researcher", "coder", "reviewer"],
             "description": "Worker profile that scopes tool access. Defaults to general (backward compatible)."
-          },
-          "reason": {
-            "type": "string",
-            "description": "Brief non-technical explanation of what you are delegating and why, shown to the user as a status update. Use simple language a non-technical person would understand."
           }
         }
       },

package/src/config/bundled-skills/computer-use/SKILL.md

@@ -10,13 +10,10 @@ metadata:
     disable-model-invocation: true
 ---
 
-This skill provides the 12 computer*use*\* action tools for controlling
-the macOS desktop (used by CU sessions).
+This skill provides the computer_use_* action tools for controlling
+the macOS desktop. CU tools run through the main agent loop via HostCuProxy.
 
-The `computer_use_request_control` escalation tool is registered in the core
-registry (not this skill) so text_qa sessions can execute it directly.
-
-The skill is internally preactivated for computer-use sessions.
+The skill is internally preactivated for sessions with a connected desktop client.
 
 Tools in this skill are proxy tools — execution is forwarded to the connected
 macOS client, never handled locally by the assistant.

package/src/config/bundled-skills/computer-use/TOOLS.json

@@ -1,9 +1,27 @@
 {
   "version": 1,
   "tools": [
+    {
+      "name": "computer_use_observe",
+      "description": "Capture the current screen state. Returns the accessibility tree with [ID] element references and optionally a screenshot.\n\nThe accessibility tree shows interactive elements like [3] AXButton 'Save' or [17] AXTextField 'Search'. Use element_id to target these elements in subsequent actions — this is much more reliable than pixel coordinates.\n\nCall this before your first computer use action, or to check screen state without acting.",
+      "category": "computer-use",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
+        },
+        "required": ["reason"]
+      },
+      "executor": "tools/computer-use-observe.ts",
+      "execution_target": "host"
+    },
     {
       "name": "computer_use_click",
-      "description": "Click on a UI element by its [ID] from the accessibility tree, or at raw screen coordinates as fallback. Supports single click, double-click, and right-click via the click_type parameter.",
+      "description": "Click an element on screen. Prefer element_id (from the accessibility tree) over x/y coordinates.",
       "category": "computer-use",
       "risk": "low",
       "input_schema": {
@@ -42,7 +60,7 @@
     },
     {
       "name": "computer_use_type_text",
-      "description": "Type text at the current cursor position. The target field must already be focused (click it first).",
+      "description": "Type text at the current cursor position. First click a text field (by element_id) to focus it, then call this tool. If a field shows 'FOCUSED', skip the click.",
       "category": "computer-use",
       "risk": "low",
       "input_schema": {
@@ -235,7 +253,7 @@
     },
     {
       "name": "computer_use_run_applescript",
-      "description": "Execute an AppleScript to control applications via Apple's scripting bridge. Use this for operations that are more reliable through scripting than UI interaction: setting a browser URL directly, navigating Finder to a path, querying app state (tab count, window titles, document status), or clicking deeply nested menu items. The script's return value (if any) will be reported back. NEVER use \"do shell script\" \u2014 it is blocked for security. Keep scripts short and targeted to a single operation.",
+      "description": "Run an AppleScript command. Prefer this over click/type when possible \u2014 it doesn't move the cursor or interrupt the user. Never use 'do shell script' inside AppleScript (blocked for security).",
       "category": "computer-use",
       "risk": "low",
       "input_schema": {
@@ -261,7 +279,7 @@
     },
     {
       "name": "computer_use_done",
-      "description": "Task is complete",
+      "description": "Signal that the computer use task is complete. Provide a summary of what was accomplished. This ends the computer use session.",
       "category": "computer-use",
       "risk": "low",
       "input_schema": {

package/src/config/bundled-skills/contacts/tools/google-contacts.ts

@@ -3,8 +3,7 @@ import {
   searchContacts,
 } from "../../../../messaging/providers/gmail/people-client.js";
 import type { Person } from "../../../../messaging/providers/gmail/people-types.js";
-import { getMessagingProvider } from "../../../../messaging/registry.js";
-import { withValidToken } from "../../../../security/token-manager.js";
+import { resolveOAuthConnection } from "../../../../oauth/connection-resolver.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -44,43 +43,41 @@ export async function run(
   }
 
   try {
-    const provider = getMessagingProvider("gmail");
-    return await withValidToken(provider.credentialService, async (token) => {
-      switch (action) {
-        case "list": {
-          const pageSize = (input.page_size as number) ?? 50;
-          const pageToken = input.page_token as string | undefined;
+    const connection = resolveOAuthConnection("integration:gmail");
+    switch (action) {
+      case "list": {
+        const pageSize = (input.page_size as number) ?? 50;
+        const pageToken = input.page_token as string | undefined;
 
-          const resp = await listContacts(token, pageSize, pageToken);
-          const contacts = (resp.connections ?? []).map(formatContact);
+        const resp = await listContacts(connection, pageSize, pageToken);
+        const contacts = (resp.connections ?? []).map(formatContact);
 
-          const result: Record<string, unknown> = {
-            contacts,
-            total: resp.totalPeople ?? contacts.length,
-          };
-          if (resp.nextPageToken) result.nextPageToken = resp.nextPageToken;
+        const result: Record<string, unknown> = {
+          contacts,
+          total: resp.totalPeople ?? contacts.length,
+        };
+        if (resp.nextPageToken) result.nextPageToken = resp.nextPageToken;
 
-          return ok(JSON.stringify(result, null, 2));
-        }
-
-        case "search": {
-          const query = input.query as string;
-          if (!query) return err("query is required for search action.");
+        return ok(JSON.stringify(result, null, 2));
+      }
 
-          const resp = await searchContacts(token, query);
-          const contacts = (resp.results ?? []).map((r) =>
-            formatContact(r.person),
-          );
+      case "search": {
+        const query = input.query as string;
+        if (!query) return err("query is required for search action.");
 
-          return ok(
-            JSON.stringify({ contacts, total: contacts.length }, null, 2),
-          );
-        }
+        const resp = await searchContacts(connection, query);
+        const contacts = (resp.results ?? []).map((r) =>
+          formatContact(r.person),
+        );
 
-        default:
-          return err(`Unknown action "${action}". Use list or search.`);
+        return ok(
+          JSON.stringify({ contacts, total: contacts.length }, null, 2),
+        );
       }
-    });
+
+      default:
+        return err(`Unknown action "${action}". Use list or search.`);
+    }
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e));
   }

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

@@ -30,11 +30,11 @@ Do not offer AgentMail as an option or mention it unless the user specifically a
 ### Gmail
 
 1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "gmail"`. The tool auto-fills Google's OAuth endpoints and looks up any previously stored client credentials — so this single call may be all that's needed.
-2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Load the **google-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
-   - Call `skill_load` with `skill: "google-oauth-setup"` to load the dependency skill.
+2. **If it fails because no client_id is found:** The user needs to create Google Cloud OAuth credentials first. Load the **google-oauth-applescript** skill:
+   - Call `skill_load` with `skill: "google-oauth-applescript"` to load the dependency skill.
    - Tell the user Gmail isn't connected yet and briefly explain what the setup involves, then use `ui_show` with `surface_type: "confirmation"` to ask for permission to start:
      - **message:** "Ready to set up Gmail?"
-     - **detail:** "I'll open a browser where you sign in to Google, then automate everything else — creating a project, enabling APIs, and connecting your account. Takes 2-3 minutes and you can watch in the browser preview panel."
+     - **detail:** "I'll open a few pages in your browser and walk you through setting up Google Cloud credentials — creating a project, enabling APIs, and connecting your account. Takes about 5 minutes."
      - **confirmLabel:** "Get Started"
      - **cancelLabel:** "Not Now"
    - If the user confirms, briefly acknowledge (e.g., "Setting up Gmail now...") and proceed with the setup guide. If they decline, acknowledge and let them know they can set it up later.
@@ -45,7 +45,7 @@ Do not offer AgentMail as an option or mention it unless the user specifically a
 When a Gmail tool fails with a token or authorization error:
 
 1. **Try to reconnect silently.** Call `credential_store` with `action: "oauth2_connect"` and `service: "gmail"`. This often resolves expired tokens automatically.
-2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected — let me set that up") and immediately follow the connection setup flow for Gmail (e.g., install and load **google-oauth-setup**). The user came to you to get something done, not to troubleshoot OAuth — make it seamless.
+2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected — let me set that up") and immediately follow the connection setup flow for Gmail (e.g., install and load **google-oauth-applescript**). The user came to you to get something done, not to troubleshoot OAuth — make it seamless.
 3. **Never try alternative approaches.** Don't use bash, curl, browser automation, or any workaround. If the Gmail tools can't do it, the reconnection flow is the answer.
 4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.
 

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

@@ -3,8 +3,7 @@ import {
   listMessages,
   modifyMessage,
 } from "../../../../messaging/providers/gmail/client.js";
-import { getMessagingProvider } from "../../../../messaging/registry.js";
-import { withValidToken } from "../../../../security/token-manager.js";
+import { resolveOAuthConnection } from "../../../../oauth/connection-resolver.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -35,49 +34,47 @@ export async function run(
     }
 
     try {
-      const provider = getMessagingProvider("gmail");
-      return await withValidToken(provider.credentialService, async (token) => {
-        const allMessageIds: string[] = [];
-        let pageToken: string | undefined;
-        let truncated = false;
+      const connection = resolveOAuthConnection("integration:gmail");
+      const allMessageIds: string[] = [];
+      let pageToken: string | undefined;
+      let truncated = false;
 
-        while (allMessageIds.length < MAX_MESSAGES) {
-          const listResp = await listMessages(
-            token,
-            query,
-            Math.min(500, MAX_MESSAGES - allMessageIds.length),
-            pageToken,
-          );
-          const ids = (listResp.messages ?? []).map((m) => m.id);
-          if (ids.length === 0) break;
-          allMessageIds.push(...ids);
-          pageToken = listResp.nextPageToken ?? undefined;
-          if (!pageToken) break;
-        }
+      while (allMessageIds.length < MAX_MESSAGES) {
+        const listResp = await listMessages(
+          connection,
+          query,
+          Math.min(500, MAX_MESSAGES - allMessageIds.length),
+          pageToken,
+        );
+        const ids = (listResp.messages ?? []).map((m) => m.id);
+        if (ids.length === 0) break;
+        allMessageIds.push(...ids);
+        pageToken = listResp.nextPageToken ?? undefined;
+        if (!pageToken) break;
+      }
 
-        if (allMessageIds.length >= MAX_MESSAGES && pageToken) {
-          truncated = true;
-        }
+      if (allMessageIds.length >= MAX_MESSAGES && pageToken) {
+        truncated = true;
+      }
 
-        if (allMessageIds.length === 0) {
-          return ok("No messages matched the query. Nothing archived.");
-        }
+      if (allMessageIds.length === 0) {
+        return ok("No messages matched the query. Nothing archived.");
+      }
 
-        for (let i = 0; i < allMessageIds.length; i += BATCH_MODIFY_LIMIT) {
-          const chunk = allMessageIds.slice(i, i + BATCH_MODIFY_LIMIT);
-          await batchModifyMessages(token, chunk, {
-            removeLabelIds: ["INBOX"],
-          });
-        }
+      for (let i = 0; i < allMessageIds.length; i += BATCH_MODIFY_LIMIT) {
+        const chunk = allMessageIds.slice(i, i + BATCH_MODIFY_LIMIT);
+        await batchModifyMessages(connection, chunk, {
+          removeLabelIds: ["INBOX"],
+        });
+      }
 
-        const summary = `Archived ${allMessageIds.length} message(s) matching query: ${query}`;
-        if (truncated) {
-          return ok(
-            `${summary}\n\nNote: this operation was capped at ${MAX_MESSAGES} messages. Additional messages matching the query may remain in the inbox. Run the command again to archive more.`,
-          );
-        }
-        return ok(summary);
-      });
+      const summary = `Archived ${allMessageIds.length} message(s) matching query: ${query}`;
+      if (truncated) {
+        return ok(
+          `${summary}\n\nNote: this operation was capped at ${MAX_MESSAGES} messages. Additional messages matching the query may remain in the inbox. Run the command again to archive more.`,
+        );
+      }
+      return ok(summary);
     } catch (e) {
       return err(e instanceof Error ? e.message : String(e));
     }
@@ -106,11 +103,9 @@ export async function run(
   } else if (messageId) {
     // Single message path
     try {
-      const provider = getMessagingProvider("gmail");
-      return await withValidToken(provider.credentialService, async (token) => {
-        await modifyMessage(token, messageId, { removeLabelIds: ["INBOX"] });
-        return ok("Message archived.");
-      });
+      const connection = resolveOAuthConnection("integration:gmail");
+      await modifyMessage(connection, messageId, { removeLabelIds: ["INBOX"] });
+      return ok("Message archived.");
     } catch (e) {
       return err(e instanceof Error ? e.message : String(e));
     }
@@ -126,23 +121,21 @@ export async function run(
   }
 
   try {
-    const provider = getMessagingProvider("gmail");
-    return await withValidToken(provider.credentialService, async (token) => {
-      if (messageIds.length === 1) {
-        await modifyMessage(token, messageIds[0], {
-          removeLabelIds: ["INBOX"],
-        });
-        return ok("Message archived.");
-      }
+    const connection = resolveOAuthConnection("integration:gmail");
+    if (messageIds.length === 1) {
+      await modifyMessage(connection, messageIds[0], {
+        removeLabelIds: ["INBOX"],
+      });
+      return ok("Message archived.");
+    }
 
-      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).`);
-    });
+    for (let i = 0; i < messageIds.length; i += BATCH_MODIFY_LIMIT) {
+      const chunk = messageIds.slice(i, i + BATCH_MODIFY_LIMIT);
+      await batchModifyMessages(connection, chunk, {
+        removeLabelIds: ["INBOX"],
+      });
+    }
+    return ok(`Archived ${messageIds.length} message(s).`);
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e));
   }

package/src/config/bundled-skills/gmail/tools/gmail-attachments.ts

@@ -6,8 +6,7 @@ import {
   getMessage,
 } from "../../../../messaging/providers/gmail/client.js";
 import type { GmailMessagePart } from "../../../../messaging/providers/gmail/types.js";
-import { getMessagingProvider } from "../../../../messaging/registry.js";
-import { withValidToken } from "../../../../security/token-manager.js";
+import { resolveOAuthConnection } from "../../../../oauth/connection-resolver.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -57,17 +56,15 @@ export async function run(
 
   if (action === "list") {
     try {
-      const provider = getMessagingProvider("gmail");
-      return await withValidToken(provider.credentialService, async (token) => {
-        const message = await getMessage(token, messageId, "full");
-        const attachments = collectAttachments(message.payload?.parts);
+      const connection = resolveOAuthConnection("integration:gmail");
+      const message = await getMessage(connection, messageId, "full");
+      const attachments = collectAttachments(message.payload?.parts);
 
-        if (attachments.length === 0) {
-          return ok("No attachments found on this message.");
-        }
+      if (attachments.length === 0) {
+        return ok("No attachments found on this message.");
+      }
 
-        return ok(JSON.stringify(attachments, null, 2));
-      });
+      return ok(JSON.stringify(attachments, null, 2));
     } catch (e) {
       return err(e instanceof Error ? e.message : String(e));
     }
@@ -81,26 +78,26 @@ export async function run(
     if (!filename) return err("filename is required for download.");
 
     try {
-      const provider = getMessagingProvider("gmail");
-      return await withValidToken(provider.credentialService, async (token) => {
-        const attachment = await getAttachment(token, messageId, attachmentId);
+      const connection = resolveOAuthConnection("integration:gmail");
+      const attachment = await getAttachment(
+        connection,
+        messageId,
+        attachmentId,
+      );
 
-        // Gmail returns base64url; convert to standard base64 then to Buffer
-        const base64 = attachment.data.replace(/-/g, "+").replace(/_/g, "/");
-        const buffer = Buffer.from(base64, "base64");
+      // Gmail returns base64url; convert to standard base64 then to Buffer
+      const base64 = attachment.data.replace(/-/g, "+").replace(/_/g, "/");
+      const buffer = Buffer.from(base64, "base64");
 
-        const outputDir = context.workingDir ?? process.cwd();
-        // Sanitize filename: strip path separators to prevent traversal attacks from crafted MIME filenames
-        const safeName = basename(filename).replace(/\.\./g, "_");
-        const outputPath = resolve(outputDir, safeName);
-        if (!outputPath.startsWith(outputDir))
-          return err("Invalid filename: path traversal detected.");
-        await writeFile(outputPath, buffer);
+      const outputDir = context.workingDir ?? process.cwd();
+      // Sanitize filename: strip path separators to prevent traversal attacks from crafted MIME filenames
+      const safeName = basename(filename).replace(/\.\./g, "_");
+      const outputPath = resolve(outputDir, safeName);
+      if (!outputPath.startsWith(outputDir))
+        return err("Invalid filename: path traversal detected.");
+      await writeFile(outputPath, buffer);
 
-        return ok(
-          `Attachment saved to ${outputPath} (${buffer.length} bytes).`,
-        );
-      });
+      return ok(`Attachment saved to ${outputPath} (${buffer.length} bytes).`);
     } catch (e) {
       return err(e instanceof Error ? e.message : String(e));
     }

package/src/config/bundled-skills/gmail/tools/gmail-draft.ts

@@ -1,6 +1,5 @@
 import { createDraft } from "../../../../messaging/providers/gmail/client.js";
-import { getMessagingProvider } from "../../../../messaging/registry.js";
-import { withValidToken } from "../../../../security/token-manager.js";
+import { resolveOAuthConnection } from "../../../../oauth/connection-resolver.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -23,21 +22,19 @@ export async function run(
   if (!body) return err("body is required.");
 
   try {
-    const provider = getMessagingProvider("gmail");
-    return await withValidToken(provider.credentialService, async (token) => {
-      const draft = await createDraft(
-        token,
-        to,
-        subject,
-        body,
-        inReplyTo,
-        cc,
-        bcc,
-      );
-      return ok(
-        `Draft created (ID: ${draft.id}). It will appear in your Gmail Drafts.`,
-      );
-    });
+    const connection = resolveOAuthConnection("integration:gmail");
+    const draft = await createDraft(
+      connection,
+      to,
+      subject,
+      body,
+      inReplyTo,
+      cc,
+      bcc,
+    );
+    return ok(
+      `Draft created (ID: ${draft.id}). It will appear in your Gmail Drafts.`,
+    );
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e));
   }

package/src/config/bundled-skills/gmail/tools/gmail-filters.ts

@@ -7,8 +7,7 @@ import type {
   GmailFilterAction,
   GmailFilterCriteria,
 } from "../../../../messaging/providers/gmail/types.js";
-import { getMessagingProvider } from "../../../../messaging/registry.js";
-import { withValidToken } from "../../../../security/token-manager.js";
+import { resolveOAuthConnection } from "../../../../oauth/connection-resolver.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -26,57 +25,53 @@ export async function run(
   }
 
   try {
-    const provider = getMessagingProvider("gmail");
-    return await withValidToken(provider.credentialService, async (token) => {
-      switch (action) {
-        case "list": {
-          const filters = await listFilters(token);
-          if (filters.length === 0) {
-            return ok("No filters configured.");
-          }
-          return ok(JSON.stringify(filters, null, 2));
+    const connection = resolveOAuthConnection("integration:gmail");
+    switch (action) {
+      case "list": {
+        const filters = await listFilters(connection);
+        if (filters.length === 0) {
+          return ok("No filters configured.");
         }
+        return ok(JSON.stringify(filters, null, 2));
+      }
 
-        case "create": {
-          const criteria: GmailFilterCriteria = {};
-          if (input.from) criteria.from = input.from as string;
-          if (input.to) criteria.to = input.to as string;
-          if (input.subject) criteria.subject = input.subject as string;
-          if (input.query) criteria.query = input.query as string;
-          if (input.has_attachment !== undefined)
-            criteria.hasAttachment = input.has_attachment as boolean;
-
-          const filterAction: GmailFilterAction = {};
-          if (input.add_label_ids)
-            filterAction.addLabelIds = input.add_label_ids as string[];
-          if (input.remove_label_ids)
-            filterAction.removeLabelIds = input.remove_label_ids as string[];
-          if (input.forward) filterAction.forward = input.forward as string;
+      case "create": {
+        const criteria: GmailFilterCriteria = {};
+        if (input.from) criteria.from = input.from as string;
+        if (input.to) criteria.to = input.to as string;
+        if (input.subject) criteria.subject = input.subject as string;
+        if (input.query) criteria.query = input.query as string;
+        if (input.has_attachment !== undefined)
+          criteria.hasAttachment = input.has_attachment as boolean;
 
-          if (Object.keys(criteria).length === 0) {
-            return err(
-              "At least one filter criteria is required (from, to, subject, query, or has_attachment).",
-            );
-          }
+        const filterAction: GmailFilterAction = {};
+        if (input.add_label_ids)
+          filterAction.addLabelIds = input.add_label_ids as string[];
+        if (input.remove_label_ids)
+          filterAction.removeLabelIds = input.remove_label_ids as string[];
+        if (input.forward) filterAction.forward = input.forward as string;
 
-          const filter = await createFilter(token, criteria, filterAction);
-          return ok(`Filter created (ID: ${filter.id}).`);
+        if (Object.keys(criteria).length === 0) {
+          return err(
+            "At least one filter criteria is required (from, to, subject, query, or has_attachment).",
+          );
         }
 
-        case "delete": {
-          const filterId = input.filter_id as string;
-          if (!filterId) return err("filter_id is required for delete action.");
+        const filter = await createFilter(connection, criteria, filterAction);
+        return ok(`Filter created (ID: ${filter.id}).`);
+      }
 
-          await deleteFilter(token, filterId);
-          return ok("Filter deleted.");
-        }
+      case "delete": {
+        const filterId = input.filter_id as string;
+        if (!filterId) return err("filter_id is required for delete action.");
 
-        default:
-          return err(
-            `Unknown action "${action}". Use list, create, or delete.`,
-          );
+        await deleteFilter(connection, filterId);
+        return ok("Filter deleted.");
       }
-    });
+
+      default:
+        return err(`Unknown action "${action}". Use list, create, or delete.`);
+    }
   } catch (e) {
     return err(e instanceof Error ? e.message : String(e));
   }