@vellumai/assistant 0.3.0

package/src/config/bundled-skills/image-studio/tools/media-generate-image.ts

@@ -0,0 +1,115 @@
+import type { ToolContext, ToolExecutionResult } from '../../../../tools/types.js';
+import type { ImageContent } from '../../../../providers/types.js';
+import { getConfig } from '../../../../config/loader.js';
+import { generateImage, mapGeminiError } from '../../../../media/gemini-image-service.js';
+import { getAttachmentsByIds } from '../../../../memory/attachments-store.js';
+import { isAttachmentVisible, type AttachmentContext } from '../../../../daemon/media-visibility-policy.js';
+import { getConversationThreadType } from '../../../../memory/conversation-store.js';
+import { getAttachmentSourceConversations } from '../../../../tools/assets/search.js';
+
+/**
+ * Check whether an attachment is visible from the given context.
+ * Mirrors the logic in tools/assets/search.ts:isAttachmentVisibleFromContext.
+ */
+function isAttachmentAccessible(attachmentId: string, currentContext: AttachmentContext): boolean {
+  const sources = getAttachmentSourceConversations(attachmentId);
+  if (sources.length === 0) {
+    return true; // orphan attachments are universally visible
+  }
+  const hasStandard = sources.some((s) => s.threadType !== 'private');
+  if (hasStandard) {
+    return true;
+  }
+  // All sources are private — visible only if the caller is in one of those threads
+  return sources.some(
+    (s) => isAttachmentVisible({ conversationId: s.conversationId, isPrivate: true }, currentContext),
+  );
+}
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const config = getConfig();
+  const apiKey = config.apiKeys.gemini;
+
+  if (!apiKey) {
+    return {
+      content: 'No Gemini API key configured. Please set your Gemini API key to use image generation.',
+      isError: true,
+    };
+  }
+
+  const prompt = input.prompt as string;
+  const mode = (input.mode as 'generate' | 'edit') ?? 'generate';
+  const attachmentIds = input.attachment_ids as string[] | undefined;
+  const model = (input.model as string | undefined) ?? config.imageGenModel;
+  const variants = input.variants as number | undefined;
+
+  // Resolve source images from attachments for edit mode
+  let sourceImages: Array<{ mimeType: string; dataBase64: string }> | undefined;
+
+  if (attachmentIds && attachmentIds.length > 0) {
+    const attachments = getAttachmentsByIds(attachmentIds);
+
+    // Build visibility context for the current conversation
+    const threadType = getConversationThreadType(context.conversationId);
+    const currentContext: AttachmentContext = {
+      conversationId: context.conversationId,
+      isPrivate: threadType === 'private',
+    };
+
+    // Filter to only visible attachments using their originating context
+    const visibleAttachments = attachments.filter((att) =>
+      isAttachmentAccessible(att.id, currentContext),
+    );
+
+    if (visibleAttachments.length === 0 && attachmentIds.length > 0) {
+      return {
+        content: 'None of the specified attachments could be found or are accessible.',
+        isError: true,
+      };
+    }
+
+    sourceImages = visibleAttachments.map((att) => ({
+      mimeType: att.mimeType,
+      dataBase64: att.dataBase64,
+    }));
+  }
+
+  try {
+    const result = await generateImage(apiKey, {
+      prompt,
+      mode,
+      sourceImages,
+      model,
+      variants,
+    });
+
+    const imageCount = result.images.length;
+    let content = `Generated ${imageCount} image${imageCount !== 1 ? 's' : ''} using ${result.resolvedModel}.`;
+    if (result.text) {
+      content += `\n\n${result.text}`;
+    }
+
+    const contentBlocks: ImageContent[] = result.images.map((img) => ({
+      type: 'image' as const,
+      source: {
+        type: 'base64' as const,
+        media_type: img.mimeType,
+        data: img.dataBase64,
+      },
+    }));
+
+    return {
+      content,
+      isError: false,
+      contentBlocks,
+    };
+  } catch (error) {
+    return {
+      content: mapGeminiError(error),
+      isError: true,
+    };
+  }
+}

package/src/config/bundled-skills/macos-automation/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: "macOS Automation"
+description: "Automate native macOS apps and system interactions via osascript (AppleScript)"
+user-invocable: false
+disable-model-invocation: false
+metadata: {"vellum": {"emoji": "🍎", "os": ["darwin"]}}
+---
+
+Use this skill to interact with native macOS apps and system-level features via `osascript` (AppleScript) through `host_bash`. Always prefer osascript over browser automation or computer-use for anything involving a native macOS app.
+
+## Supported Apps
+
+**Communication:** Messages, Mail, Microsoft Outlook, FaceTime
+**Contacts & Calendar:** Contacts, Calendar, Reminders
+**Notes & Writing:** Notes, TextEdit, Pages, BBEdit, CotEditor
+**Files:** Finder, Path Finder
+**Browsers:** Safari, Google Chrome
+**Music & Media:** Music (iTunes), Spotify, VLC, Podcasts, TV
+**Productivity:** OmniFocus, Things 3, OmniOutliner, OmniPlan, OmniGraffle
+**Office:** Microsoft Word, Microsoft Excel, Numbers, Keynote
+**Developer tools:** Xcode, Terminal, iTerm2, Script Editor
+**System:** System Events (UI scripting for any app), System Settings
+**Automation:** Keyboard Maestro, Alfred, Automator
+**Creative:** Adobe Photoshop, Final Cut Pro
+
+For any unlisted app, check scriptability first:
+```bash
+osascript -e 'tell application "AppName" to get name'
+```
+
+## Examples
+
+```bash
+# Send an iMessage
+osascript -e 'tell application "Messages" to send "Hello!" to buddy "user@example.com"'
+
+# Look up a contact
+osascript -e 'tell application "Contacts" to get {name, phones} of every person whose name contains "Marina"'
+
+# Read upcoming calendar events
+osascript -e 'tell application "Calendar" to get summary of every event of calendar "Home" whose start date > (current date)'
+
+# Create a reminder
+osascript -e 'tell application "Reminders" to make new reminder with properties {name:"Buy milk", due date:((current date) + 1 * hours)}'
+
+# Send an email
+osascript -e 'tell application "Mail" to send (make new outgoing message with properties {subject:"Hi", content:"Hello", visible:true})'
+
+# Create a note
+osascript -e 'tell application "Notes" to make new note at folder "Notes" with properties {body:"My note"}'
+
+# Open a URL in Safari
+osascript -e 'tell application "Safari" to open location "https://example.com"'
+
+# Play/pause Music
+osascript -e 'tell application "Music" to playpause'
+
+# Display a system notification
+osascript -e 'display notification "Done!" with title "Vellum"'
+```
+
+## Tips
+
+- For multi-line scripts, write them to a `.applescript` file and run with `osascript path/to/script.applescript`
+- Use `System Events` for UI scripting apps that don't have their own AppleScript dictionary
+- AppleScript permissions are gated by macOS TCC — if a command fails with a permission error, use `request_system_permission` to prompt the user

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

@@ -0,0 +1,153 @@
+---
+name: "Messaging"
+description: "Read, search, send, and manage messages across Slack, Gmail, Telegram, and other platforms"
+user-invocable: true
+metadata: {"vellum": {"emoji": "💬"}}
+---
+
+You are a unified messaging assistant with access to multiple platforms (Slack, Gmail, Telegram, and more). Use the messaging tools to help users read, search, organize, draft, and send messages across all connected platforms.
+
+## Connection Setup
+
+Before using any messaging tool, verify that the platform is connected by calling `messaging_auth_test` with the appropriate `platform` parameter. If the call fails with a token/authorization error, follow the steps below.
+
+### Public Ingress (required for all platforms)
+
+Gmail, Slack, and Telegram setup all require a publicly reachable URL for OAuth callbacks or webhook delivery. The **public-ingress** skill handles ngrok tunnel setup and persists the URL as `ingress.publicBaseUrl`. Each setup skill below declares `public-ingress` as a dependency and will prompt you to run it if `ingress.publicBaseUrl` is not configured.
+
+### 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. Install and load the **google-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
+   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "google-oauth-setup"`.
+   - Then call `skill_load` with `skill: "google-oauth-setup"`.
+   - Tell the user: *"Gmail isn't connected yet. I've loaded a setup guide that will walk you through creating Google credentials and connecting your account."*
+3. **If the user provides a client_id directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "gmail"`, and `client_id: "<their value>"`. Include `client_secret` too if they provide one. Everything else is auto-filled.
+
+### Slack
+1. **Try connecting directly first.** Call `credential_store` with `action: "oauth2_connect"` and `service: "slack"`. The tool auto-fills Slack's OAuth endpoints and looks up any previously stored client credentials.
+2. **If it fails because no client_id is found:** The user needs to create a Slack App first. Install and load the **slack-oauth-setup** skill (which depends on **public-ingress** for the redirect URI):
+   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "slack-oauth-setup"`.
+   - Then call `skill_load` with `skill: "slack-oauth-setup"`.
+   - Tell the user: *"Slack isn't connected yet. I've loaded a setup guide that will walk you through creating a Slack App and connecting your workspace."*
+3. **If the user provides client_id and client_secret directly in chat:** Call `credential_store` with `action: "oauth2_connect"`, `service: "slack"`, `client_id`, and `client_secret`. Everything else is auto-filled. Note: Slack always requires a client_secret.
+
+### Telegram
+Telegram uses a bot token (not OAuth). Install and load the **telegram-setup** skill (which depends on **public-ingress** for the webhook URL) which automates the full setup:
+   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "telegram-setup"`.
+   - Then call `skill_load` with `skill: "telegram-setup"`.
+   - Tell the user: *"I've loaded a setup guide for Telegram. It will walk you through connecting a Telegram bot to your assistant."*
+
+The telegram-setup skill handles: verifying the bot token from @BotFather, generating a webhook secret, registering bot commands, and storing credentials securely via the secure credential prompt flow. **Never accept a Telegram bot token pasted in plaintext chat — always use the secure prompt.** Webhook registration with Telegram is handled automatically by the gateway on startup and whenever credentials change.
+
+### SMS (Twilio)
+SMS messaging uses Twilio as the telephony provider. Twilio credentials and phone number configuration are shared with the **phone-calls** skill. Load the **twilio-setup** skill to configure Twilio:
+   - Call `vellum_skills_catalog` with `action: "install"` and `skill_id: "twilio-setup"`.
+   - Then call `skill_load` with `skill: "twilio-setup"`.
+   - Tell the user: *"I've loaded a setup guide for Twilio. It will walk you through configuring your Twilio account for SMS and voice calls."*
+
+The twilio-setup skill handles: credential storage (Account SID + Auth Token), phone number provisioning or assignment, and public ingress setup. Once Twilio is configured, SMS is available automatically — no additional feature flag is needed. The assistant's Twilio phone number is used for both outbound SMS and voice calls.
+
+## Platform Selection
+
+- If the user specifies a platform (e.g., "check my Slack"), pass it as the `platform` parameter.
+- If only one platform is connected, it is auto-selected.
+- If multiple platforms are connected and the user doesn't specify, ask which platform they mean — or search across all of them.
+
+## Capabilities
+
+### Universal (Slack, Gmail)
+- **Auth Test**: Verify connection and show account info
+- **List Conversations**: Show channels, inboxes, DMs with unread counts
+- **Read Messages**: Read message history from a conversation
+- **Search**: Search messages with platform-appropriate query syntax
+- **Send**: Send a message (high risk — requires user approval)
+- **Reply**: Reply in a thread (medium risk)
+- **Mark Read**: Mark conversation as read
+
+### Telegram
+Telegram is supported as a messaging provider with limited capabilities compared to Slack and Gmail due to Bot API constraints:
+
+- **Send**: Send a message to a known chat ID (high risk — requires user approval)
+- **Auth Test**: Verify bot token and show bot info
+
+**Not available** (Bot API limitations):
+- List conversations — the Bot API does not expose a method to enumerate chats a bot belongs to
+- Read message history — bots cannot retrieve past messages from a chat
+- Search messages — no search API is available for bots
+
+**Bot-account limits:**
+- The bot can only message users or groups that have previously interacted with it (sent `/start` or been added to a group). Bots cannot initiate conversations with arbitrary phone numbers.
+- Future support for MTProto user-account sessions may lift some of these restrictions.
+
+### Slack-specific
+- **Add Reaction**: Add an emoji reaction to a message
+- **Leave Channel**: Leave a Slack channel
+
+### Gmail-specific
+- **Archive**: Remove message from inbox
+- **Label**: Add/remove labels
+- **Trash**: Move to trash
+- **Unsubscribe**: Unsubscribe via List-Unsubscribe header
+- **Draft (native)**: Create a draft in Gmail's Drafts folder
+
+## Slack Search Syntax
+
+When searching Slack, the query is passed directly to Slack's search API:
+
+| Operator | Example | What it finds |
+|---|---|---|
+| `from:` | `from:@alice` | Messages from a specific user |
+| `in:` | `in:#general` | Messages in a specific channel |
+| `has:` | `has:link` | Messages containing links |
+| `before:` | `before:2024-01-01` | Messages before a date |
+| `after:` | `after:2024-01-01` | Messages after a date |
+| `has:reaction` | `has:reaction` | Messages with reactions |
+| `has:star` | `has:star` | Starred messages |
+
+## Gmail Search Syntax
+
+When searching Gmail, the query uses Gmail's search operators:
+
+| Operator | Example | What it finds |
+|---|---|---|
+| `from:` | `from:alice@example.com` | Messages from a specific sender |
+| `to:` | `to:bob@example.com` | Messages sent to a recipient |
+| `subject:` | `subject:meeting` | Messages with a word in the subject |
+| `newer_than:` | `newer_than:7d` | Messages from the last 7 days |
+| `older_than:` | `older_than:30d` | Messages older than 30 days |
+| `is:unread` | `is:unread` | Unread messages |
+| `has:attachment` | `has:attachment` | Messages with attachments |
+| `label:` | `label:work` | Messages with a specific label |
+
+## Drafting vs Sending
+
+- Default to drafting (local draft or Gmail native draft) when the user wants to compose.
+- Only send when the user explicitly requests it.
+- When uncertain, always default to drafting.
+
+## Personalized Drafting
+
+When drafting messages, check your `<dynamic-user-profile>` for style items (e.g., "writing style: tone"). If present, match the user's natural voice.
+
+If no style items exist and the user asks you to draft a message, suggest running `messaging_analyze_style`:
+
+> "I can analyze your sent messages to learn your writing style so drafts sound like you. Want me to do that?"
+
+## Confidence Scores
+
+Medium and high risk tools require a confidence score between 0 and 1:
+
+- **0.9-1.0**: User explicitly requested this exact action
+- **0.7-0.8**: Action is strongly implied by context
+- **0.5-0.6**: Reasonable inference but some ambiguity
+- **Below 0.5**: Ask the user to confirm before proceeding
+
+## Activity Analysis
+
+Use `messaging_analyze_activity` to classify channels or conversations by activity level (high, medium, low, dead). Useful for decluttering — suggest leaving dead channels or archiving old emails.
+
+## Batch Operations
+
+- Gmail batch tools (`gmail_batch_archive`, `gmail_batch_label`) accept arrays of message IDs.
+- First search or list messages to collect IDs, then apply batch actions.
+- Always confirm with the user before batch operations on large numbers of messages.