@vellumai/assistant 0.4.29 → 0.4.30

package/src/config/bundled-skills/google-calendar/TOOLS.json

@@ -9,13 +9,39 @@
       "input_schema": {
         "type": "object",
         "properties": {
-          "calendar_id": { "type": "string", "description": "Calendar ID to query (default \"primary\")" },
-          "time_min": { "type": "string", "description": "Start of time range in ISO 8601 format (e.g. \"2024-01-15T00:00:00Z\"). Defaults to now." },
-          "time_max": { "type": "string", "description": "End of time range in ISO 8601 format (e.g. \"2024-01-22T00:00:00Z\"). Defaults to 7 days from now." },
-          "max_results": { "type": "number", "description": "Maximum number of events to return (default 25, max 250)" },
-          "query": { "type": "string", "description": "Free text search terms to filter events" },
-          "single_events": { "type": "boolean", "description": "Whether to expand recurring events into individual instances (default true)" },
-          "order_by": { "type": "string", "enum": ["startTime", "updated"], "description": "Sort order (default \"startTime\"). Only valid when single_events is true." }
+          "calendar_id": {
+            "type": "string",
+            "description": "Calendar ID to query (default \"primary\")"
+          },
+          "time_min": {
+            "type": "string",
+            "description": "Start of time range in ISO 8601 format (e.g. \"2024-01-15T00:00:00Z\"). Defaults to now."
+          },
+          "time_max": {
+            "type": "string",
+            "description": "End of time range in ISO 8601 format (e.g. \"2024-01-22T00:00:00Z\"). Defaults to 7 days from now."
+          },
+          "max_results": {
+            "type": "number",
+            "description": "Maximum number of events to return (default 25, max 250)"
+          },
+          "query": {
+            "type": "string",
+            "description": "Free text search terms to filter events"
+          },
+          "single_events": {
+            "type": "boolean",
+            "description": "Whether to expand recurring events into individual instances (default true)"
+          },
+          "order_by": {
+            "type": "string",
+            "enum": ["startTime", "updated"],
+            "description": "Sort order (default \"startTime\"). Only valid when single_events is true."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
         }
       },
       "executor": "tools/calendar-list-events.ts",
@@ -29,8 +55,18 @@
       "input_schema": {
         "type": "object",
         "properties": {
-          "event_id": { "type": "string", "description": "The calendar event ID" },
-          "calendar_id": { "type": "string", "description": "Calendar ID (default \"primary\")" }
+          "event_id": {
+            "type": "string",
+            "description": "The calendar event ID"
+          },
+          "calendar_id": {
+            "type": "string",
+            "description": "Calendar ID (default \"primary\")"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
         },
         "required": ["event_id"]
       },
@@ -45,19 +81,49 @@
       "input_schema": {
         "type": "object",
         "properties": {
-          "summary": { "type": "string", "description": "Event title" },
-          "start": { "type": "string", "description": "Start time in ISO 8601 format (e.g. \"2024-01-15T09:00:00-05:00\") or date for all-day events (\"2024-01-15\")" },
-          "end": { "type": "string", "description": "End time in ISO 8601 format or date for all-day events" },
-          "description": { "type": "string", "description": "Event description or notes" },
-          "location": { "type": "string", "description": "Event location" },
+          "summary": {
+            "type": "string",
+            "description": "Event title"
+          },
+          "start": {
+            "type": "string",
+            "description": "Start time in ISO 8601 format (e.g. \"2024-01-15T09:00:00-05:00\") or date for all-day events (\"2024-01-15\")"
+          },
+          "end": {
+            "type": "string",
+            "description": "End time in ISO 8601 format or date for all-day events"
+          },
+          "description": {
+            "type": "string",
+            "description": "Event description or notes"
+          },
+          "location": {
+            "type": "string",
+            "description": "Event location"
+          },
           "attendees": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Email addresses of attendees to invite"
           },
-          "timezone": { "type": "string", "description": "IANA timezone (e.g. \"America/New_York\"). Required when start/end don't include timezone offset." },
-          "calendar_id": { "type": "string", "description": "Calendar ID (default \"primary\")" },
-          "confidence": { "type": "number", "description": "Confidence score (0-1) for this action" }
+          "timezone": {
+            "type": "string",
+            "description": "IANA timezone (e.g. \"America/New_York\"). Required when start/end don't include timezone offset."
+          },
+          "calendar_id": {
+            "type": "string",
+            "description": "Calendar ID (default \"primary\")"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
         },
         "required": ["summary", "start", "end", "confidence"]
       },
@@ -72,14 +138,29 @@
       "input_schema": {
         "type": "object",
         "properties": {
-          "time_min": { "type": "string", "description": "Start of time range in ISO 8601 format" },
-          "time_max": { "type": "string", "description": "End of time range in ISO 8601 format" },
+          "time_min": {
+            "type": "string",
+            "description": "Start of time range in ISO 8601 format"
+          },
+          "time_max": {
+            "type": "string",
+            "description": "End of time range in ISO 8601 format"
+          },
           "calendar_ids": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Calendar IDs to check (default [\"primary\"])"
           },
-          "timezone": { "type": "string", "description": "IANA timezone for interpreting results (e.g. \"America/New_York\")" }
+          "timezone": {
+            "type": "string",
+            "description": "IANA timezone for interpreting results (e.g. \"America/New_York\")"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
         },
         "required": ["time_min", "time_max"]
       },
@@ -94,10 +175,27 @@
       "input_schema": {
         "type": "object",
         "properties": {
-          "event_id": { "type": "string", "description": "The calendar event ID" },
-          "response": { "type": "string", "enum": ["accepted", "declined", "tentative"], "description": "RSVP response" },
-          "calendar_id": { "type": "string", "description": "Calendar ID (default \"primary\")" },
-          "confidence": { "type": "number", "description": "Confidence score (0-1) for this action" }
+          "event_id": {
+            "type": "string",
+            "description": "The calendar event ID"
+          },
+          "response": {
+            "type": "string",
+            "enum": ["accepted", "declined", "tentative"],
+            "description": "RSVP response"
+          },
+          "calendar_id": {
+            "type": "string",
+            "description": "Calendar ID (default \"primary\")"
+          },
+          "confidence": {
+            "type": "number",
+            "description": "Confidence score (0-1) for this action"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
+          }
         },
         "required": ["event_id", "response", "confidence"]
       },

package/src/config/bundled-skills/guardian-verify-setup/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: "Guardian Verify Setup"
-description: "Set up guardian verification for voice or Telegram channels via outbound verification flow"
+description: "Set up guardian verification for voice, Telegram, or Slack channels via outbound verification flow"
 user-invocable: true
 metadata: { "vellum": { "emoji": "\ud83d\udd10" } }
 ---
 
-You are helping your user set up guardian verification for a messaging channel (voice or Telegram). This links their identity as the trusted guardian for the chosen channel. Use gateway control-plane APIs for outbound actions, and use `vellum integrations guardian status` for status reads.
+You are helping your user set up guardian verification for a messaging channel (voice, Telegram, or Slack). This links their identity as the trusted guardian for the chosen channel. Use gateway control-plane APIs for outbound actions, and use `vellum integrations guardian status` for status reads.
 
 ## Prerequisites
 
 - Use the injected `INTERNAL_GATEWAY_BASE_URL` for gateway API calls.
-- Never call the assistant runtime port directly; always call the gateway URL.
+- Never call the daemon runtime port directly; always call the gateway URL.
 - The bearer token is available as the `$GATEWAY_AUTH_TOKEN` environment variable for control-plane `curl` requests.
 - Run shell commands for this skill with `bash`.
 - Keep narration minimal: execute required calls first, then provide a concise status update. Do not narrate internal install/check/load chatter unless something fails.
@@ -21,8 +21,9 @@ Ask the user which channel they want to verify:
 
 - **voice** -- verify a phone number for voice calls
 - **telegram** -- verify a Telegram account
+- **slack** -- verify a Slack account
 
-If the user's intent already specifies a channel (e.g. "verify my phone number for voice calls"), skip the prompt and proceed.
+If the user's intent already specifies a channel (e.g. "verify my phone number for voice calls", "verify me on Slack"), skip the prompt and proceed.
 
 ## Step 2: Collect Destination
 
@@ -32,6 +33,7 @@ Based on the chosen channel, ask for the required destination:
 - **Telegram**: Ask for their Telegram chat ID (numeric) or @handle. Explain:
   - If they know their numeric chat ID, provide it directly. The bot will send the code to that chat.
   - If they only know their @handle, the flow uses a bootstrap deep-link that they must click first.
+- **Slack**: Ask for their Slack user ID. Explain that this is their Slack member ID (e.g. U01ABCDEF), not their display name or email. They can find it in their Slack profile under "More" > "Copy member ID". The bot will send a verification code via Slack DM.
 
 ## Step 3: Start Outbound Verification
 
@@ -44,7 +46,7 @@ curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/outbound/st
   -d '{"channel": "<channel>", "destination": "<destination>"}'
 ```
 
-Replace `<channel>` with `voice` or `telegram`, and `<destination>` with the phone number or Telegram destination.
+Replace `<channel>` with `voice`, `telegram`, or `slack`, and `<destination>` with the phone number, Telegram destination, or Slack user ID.
 
 ### On success (`success: true`)
 
@@ -53,6 +55,7 @@ Report the exact next action based on the channel:
 - **Voice**: The response includes a `secret` field with the verification code. Tell the user the code BEFORE the call connects: "I'm calling [number] now. Your verification code is [secret]. When you answer the call, enter this code using your phone's keypad." The `/outbound/start` API call already initiates the voice call. Do NOT place a separate `call_start` call. **After delivering the code, immediately begin the voice auto-check polling loop** (see [Voice Auto-Check Polling](#voice-auto-check-polling) below).
 - **Telegram with chat ID** (no `telegramBootstrapUrl` in response): The response includes a `secret` field. Show it in the current chat: "Your verification code is **[secret]**. I've also sent it to your Telegram. Open the Telegram bot chat and reply with that 6-digit code to complete verification." If the response does not contain a `secret` field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3 or resend (Step 4).
 - **Telegram with handle** (`telegramBootstrapUrl` present in response): "Tap this deep-link first: [telegramBootstrapUrl]. After Telegram binds your identity, I'll send your verification code."
+- **Slack**: The response includes a `secret` field with the verification code. Show it in the current chat: "Your verification code is **[secret]**. I've also sent it to you as a Slack DM. Open the DM from the Vellum bot in Slack and reply with that 6-digit code to complete verification." The DM channel ID is captured automatically during this process for future message delivery. If the response does not contain a `secret` field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3 or resend (Step 4). **After delivering the code, immediately begin the Slack auto-check polling loop** (see [Slack Auto-Check Polling](#slack-auto-check-polling) below).
 
 After reporting the bootstrap URL for Telegram handle flows, wait for the user to confirm they clicked the link. Then check guardian status (Step 6) to see if the bootstrap completed and a code was sent.
 
@@ -60,14 +63,14 @@ After reporting the bootstrap URL for Telegram handle flows, wait for the user t
 
 Handle each error code:
 
-| Error code            | Action                                                                                                                                                                     |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `missing_destination` | Ask the user to provide their phone number or Telegram destination.                                                                                                        |
-| `invalid_destination` | Tell the user the format is invalid. For phone: suggest E.164 format (+15551234567). For Telegram: explain that group chat IDs (negative numbers) are not supported.       |
-| `already_bound`       | Tell the user a guardian is already bound for this channel. Ask if they want to replace it. If yes, re-run the start request with `"rebind": true` added to the JSON body. |
-| `rate_limited`        | Tell the user they have sent too many verification attempts to this destination. Ask them to wait and try again later.                                                     |
-| `unsupported_channel` | Tell the user the channel is not supported. Only voice and telegram are valid.                                                                                             |
-| `no_bot_username`     | Telegram bot is not configured. Load and run the `telegram-setup` skill first.                                                                                             |
+| Error code            | Action                                                                                                                                                                                                                                             |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `missing_destination` | Ask the user to provide their phone number, Telegram destination, or Slack user ID.                                                                                                                                                                |
+| `invalid_destination` | Tell the user the format is invalid. For phone: suggest E.164 format (+15551234567). For Telegram: explain that group chat IDs (negative numbers) are not supported. For Slack: explain that the value must be a Slack member ID (e.g. U01ABCDEF). |
+| `already_bound`       | Tell the user a guardian is already bound for this channel. Ask if they want to replace it. If yes, re-run the start request with `"rebind": true` added to the JSON body.                                                                         |
+| `rate_limited`        | Tell the user they have sent too many verification attempts to this destination. Ask them to wait and try again later.                                                                                                                             |
+| `unsupported_channel` | Tell the user the channel is not supported. Only voice, telegram, and slack are valid.                                                                                                                                                             |
+| `no_bot_username`     | Telegram bot is not configured. Load and run the `telegram-setup` skill first.                                                                                                                                                                     |
 
 ## Step 4: Handle Resend
 
@@ -84,6 +87,7 @@ On success, report the next action based on the channel:
 
 - **Voice**: The resend response includes a fresh `secret` field with a new verification code. Tell the user the new code BEFORE the call connects — just like the initial start flow: "I'm calling [number] again. Your new verification code is [secret]. When you answer the call, enter this code using your phone's keypad." The `/outbound/resend` API call already initiates the voice call. Do NOT place a separate `call_start` call. **After delivering the code, immediately begin the voice auto-check polling loop** (see [Voice Auto-Check Polling](#voice-auto-check-polling) below).
 - **Telegram**: The resend response includes a fresh `secret` field. Show the new code in the current chat: "Your new verification code is **[secret]**. I've also sent it to your Telegram. Open the Telegram bot chat and reply with that 6-digit code to complete verification." If the response does not contain a `secret` field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3.
+- **Slack**: The resend response includes a fresh `secret` field. Show the new code in the current chat: "Your new verification code is **[secret]**. I've also sent it to you as a Slack DM. Reply to the DM with that 6-digit code to complete verification. (resent)" If the response does not contain a `secret` field, treat this as a control-plane error: tell the user something went wrong and ask them to retry from Step 3. **After delivering the code, immediately begin the Slack auto-check polling loop** (see [Slack Auto-Check Polling](#slack-auto-check-polling) below).
 
 ### Resend errors
 
@@ -129,19 +133,48 @@ vellum integrations guardian status --channel voice --json
 6. If the 2-minute timeout is reached without `bound: true`: proactively tell the user — "I've been checking for about 2 minutes but verification hasn't completed yet. The code may have expired or wasn't entered. Would you like me to resend a new code (Step 4) or start a new session (Step 3)?"
 
 **Rebind guard:**
-When in a **rebind flow** (i.e., the `start_outbound` request included `"rebind": true` because a binding already existed), do NOT treat the first `bound: true` poll result as success. The pre-existing binding will already show `bound: true` before the user has entered the new code, which would be a false positive. To guard against this:
+When in a **rebind flow** (i.e., the `start_outbound` request included `"rebind": true` because a binding already existed), do NOT treat `bound: true` alone as success. The pre-existing binding will show `bound: true` before the user has entered the new code, which would be a false positive. To guard against this:
 
-- Note the `bound_at` timestamp from the **first** poll response as a baseline.
-- Only report success when a subsequent poll shows `bound: true` with a `bound_at` timestamp **strictly newer** than the baseline. This proves the new outbound session was consumed.
-- If the status endpoint does not include `bound_at`, fall back to skipping the first poll result entirely and only start evaluating `bound: true` from the **second poll onward** (giving the user time to enter the new code).
-- Non-rebind flows (fresh verification with no prior binding) are unaffected — the first `bound: true` is trustworthy.
+- Only report success when BOTH conditions are met: `bound: true` AND `verificationSessionId` is **absent** from the status response. The `verificationSessionId` field is present while a verification session is still active (pending). When the user enters the correct code, the session is consumed and `verificationSessionId` disappears from subsequent status responses. This proves the new outbound session was consumed and the binding is fresh.
+- If a poll shows `bound: true` but `verificationSessionId` is still present, the old binding is still active and the new code has not yet been consumed — continue polling.
+- Non-rebind flows (fresh verification with no prior binding) are unaffected — the first `bound: true` is trustworthy because there was no prior binding to confuse the result.
 
 **Important polling rules:**
 
-- This polling loop is voice-only. Do NOT poll for Telegram channels (Telegram has its own bot-driven flow).
+- This polling loop is voice-only. Do NOT poll for Telegram channels (Telegram has its own bot-driven flow). For Slack, use the separate Slack Auto-Check Polling loop below.
 - Do NOT require the user to ask "did it work?" — the whole point is proactive confirmation.
 - If the user sends a message while polling is in progress, handle their message normally. If their message is about verification status, the next poll iteration will provide the answer.
 
+## Slack Auto-Check Polling
+
+For **Slack** verification: after telling the user their code and instructing them to reply in the Slack DM (in Step 3 or Step 4), proactively poll for completion so the user gets instant confirmation.
+
+**Polling procedure:**
+
+1. Wait ~15 seconds after delivering the code (to give the user time to open the Slack DM and reply with the code).
+2. Check the binding status via Vellum CLI:
+
+```bash
+vellum integrations guardian status --channel slack --json
+```
+
+3. If the response shows `bound: true`: immediately send a proactive success message in the current chat — "Slack verification complete! Your Slack account is now the trusted guardian. The DM channel has been captured for future message delivery." Stop polling.
+4. If not yet bound: wait ~15 seconds and poll again.
+5. Continue polling for up to **2 minutes** (approximately 8 attempts).
+6. If the 2-minute timeout is reached without `bound: true`: proactively tell the user — "I've been checking for about 2 minutes but verification hasn't completed yet. The code may have expired or wasn't entered. Would you like me to resend a new code (Step 4) or start a new session (Step 3)?"
+
+**Rebind guard:**
+When in a **rebind flow** (i.e., the `start_outbound` request included `"rebind": true` because a binding already existed), do NOT treat `bound: true` alone as success. The pre-existing binding will show `bound: true` before the user has entered the new code, which would be a false positive. To guard against this:
+
+- Only report success when BOTH conditions are met: `bound: true` AND `verificationSessionId` is **absent** from the status response. The `verificationSessionId` field is present while a verification session is still active (pending). When the user enters the correct code, the session is consumed and `verificationSessionId` disappears from subsequent status responses. This proves the new outbound session was consumed and the binding is fresh.
+- If a poll shows `bound: true` but `verificationSessionId` is still present, the old binding is still active and the new code has not yet been consumed — continue polling.
+- Non-rebind flows (fresh verification with no prior binding) are unaffected — the first `bound: true` is trustworthy because there was no prior binding to confuse the result.
+
+**Important polling rules:**
+
+- Do NOT require the user to ask "did it work?" — the whole point is proactive confirmation.
+- If the user sends a message while polling is in progress, handle their message normally.
+
 ## Step 6: Check Guardian Status
 
 After the user reports entering the code, verify the binding was created:
@@ -166,7 +199,7 @@ curl -s -X POST "$INTERNAL_GATEWAY_BASE_URL/v1/integrations/guardian/revoke" \
   -d '{"channel": "<channel>"}'
 ```
 
-Replace `<channel>` with the channel to unbind from (e.g. `voice`, `telegram`).
+Replace `<channel>` with the channel to unbind from (e.g. `voice`, `telegram`, `slack`).
 
 ### On success (`success: true`)
 
@@ -181,5 +214,5 @@ The response includes `bound: false` after the operation completes. Check the pr
 - The resend cooldown is 15 seconds between sends, with a maximum of 5 sends per session.
 - Per-destination rate limiting allows up to 10 sends within a 1-hour rolling window.
 - Guardian verification is identity-bound: the code can only be consumed by the identity matching the destination provided at start time.
-- **Missing `secret` guardrail**: For voice and Telegram chat-ID flows, the API response MUST include a `secret` field. If `secret` is unexpectedly absent from a start or resend response that otherwise indicates success, treat this as a control-plane error. Do NOT fabricate a code or tell the user to proceed without one. Instead, tell the user something went wrong and ask them to retry the start (Step 3) or resend (Step 4).
+- **Missing `secret` guardrail**: For voice, Telegram chat-ID, and Slack flows, the API response MUST include a `secret` field. If `secret` is unexpectedly absent from a start or resend response that otherwise indicates success, treat this as a control-plane error. Do NOT fabricate a code or tell the user to proceed without one. Instead, tell the user something went wrong and ask them to retry the start (Step 3) or resend (Step 4).
 - **Revoking a guardian**: To remove the current guardian from a channel, use the revoke API (Step 7). This revokes the binding AND revokes the guardian's contact record, so they lose access to the channel. A new guardian can then be verified for that channel.

package/src/config/bundled-skills/image-studio/TOOLS.json

@@ -20,17 +20,27 @@
           },
           "attachment_ids": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "IDs of attached source images to edit (required for edit mode)"
           },
           "model": {
             "type": "string",
-            "enum": ["gemini-2.5-flash-image", "gemini-3-pro-image", "gemini-3-pro-image-preview"],
+            "enum": [
+              "gemini-2.5-flash-image",
+              "gemini-3-pro-image",
+              "gemini-3-pro-image-preview"
+            ],
             "description": "Which model to use for generation. If omitted, uses the user's configured preference."
           },
           "variants": {
             "type": "number",
             "description": "Number of image variants to generate (1-4, default: 1)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["prompt"]

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

@@ -109,14 +109,20 @@ export async function run(
       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,
-      },
-    }));
+    const contentBlocks: ImageContent[] = result.images.map((img) => {
+      const block: ImageContent = {
+        type: "image" as const,
+        source: {
+          type: "base64" as const,
+          media_type: img.mimeType,
+          data: img.dataBase64,
+        },
+      };
+      if (img.title) {
+        (block as unknown as Record<string, unknown>)._title = img.title;
+      }
+      return block;
+    });
 
     return {
       content,

package/src/config/bundled-skills/knowledge-graph/TOOLS.json

@@ -16,7 +16,9 @@
           },
           "seeds": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Entity names or aliases to use as starting points"
           },
           "steps": {
@@ -26,12 +28,16 @@
               "properties": {
                 "relation_types": {
                   "type": "array",
-                  "items": { "type": "string" },
+                  "items": {
+                    "type": "string"
+                  },
                   "description": "Relation types to follow (e.g., 'uses', 'works_on', 'depends_on')"
                 },
                 "entity_types": {
                   "type": "array",
-                  "items": { "type": "string" },
+                  "items": {
+                    "type": "string"
+                  },
                   "description": "Entity types to include (e.g., 'person', 'project', 'tool')"
                 }
               }
@@ -45,6 +51,10 @@
           "include_items": {
             "type": "boolean",
             "description": "Include associated memory items for each found entity (default: true)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["query_type", "seeds"]

package/src/config/bundled-skills/media-processing/SKILL.md

@@ -200,7 +200,7 @@ Be specific and factual. Describe what you see, not what you infer happened betw
 
 ### Clip Delivery
 
-The `generate_clip` tool automatically opens clips in the user's default video player after extraction. Clips are saved persistently in the asset's pipeline directory (`pipeline/<assetId>/clips/`). The `clipPath` field in the tool response contains the absolute file path.
+The `generate_clip` tool automatically opens clips in the user's default video player after extraction (handled internally — do **not** run `open` via `host_bash`). Clips are saved persistently in the asset's pipeline directory (`pipeline/<assetId>/clips/`), falling back to a temp directory when the source location is read-only. Each clip gets a unique filename so concurrent or repeated extractions at the same range never collide. The `clipPath` field in the tool response contains the absolute file path.
 
 The tool handles high-bitrate and incompatible codec sources automatically — it tries stream copy first for speed, then falls back to H.264 re-encoding if needed. **Always use `generate_clip` rather than manual ffmpeg commands.**
 

package/src/config/bundled-skills/media-processing/TOOLS.json

@@ -20,6 +20,10 @@
           "metadata": {
             "type": "object",
             "description": "Optional JSON metadata to attach to the asset (e.g., pipeline config, source info)"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["file_path"]
@@ -47,6 +51,10 @@
             "type": "string",
             "enum": ["registered", "processing", "indexed", "failed"],
             "description": "Filter assets by processing status"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         }
       },
@@ -97,6 +105,10 @@
             "type": "string",
             "enum": ["api", "local"],
             "description": "Transcription backend: 'api' (OpenAI Whisper cloud) or 'local' (whisper.cpp). Default: 'local'."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["asset_id"]
@@ -146,6 +158,10 @@
             "type": "number",
             "minimum": 0,
             "description": "Maximum retry attempts per segment on failure. Default: 3"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["asset_id", "system_prompt", "output_schema"]
@@ -176,6 +192,10 @@
           "model": {
             "type": "string",
             "description": "LLM model to use for analysis. Default: 'claude-sonnet-4-6'"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["asset_id", "query"]
@@ -219,6 +239,10 @@
           "title": {
             "type": "string",
             "description": "Short descriptive title for the clip (e.g. 'snow-dive-closeup', 'goal-celebration'). Used as the filename. If omitted, falls back to timestamp-based naming."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["asset_id", "start_time", "end_time"]
@@ -237,6 +261,10 @@
           "asset_id": {
             "type": "string",
             "description": "ID of the media asset to diagnose"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
         "required": ["asset_id"]

package/src/config/bundled-skills/media-processing/tools/generate-clip.ts

@@ -6,7 +6,9 @@
  * This is a generic media-processing primitive with no domain-specific logic.
  */
 
-import { mkdir, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { access, constants, mkdir, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { uploadFileBackedAttachment } from "../../../../memory/attachments-store.js";
@@ -132,13 +134,31 @@ export async function run(
 
   // Save clips to the asset's pipeline directory so they persist for
   // attachment delivery (tmpdir files get cleaned up before the sandbox
-  // attachment system can serve them).
-  const clipDir = join(dirname(asset.filePath), "pipeline", assetId, "clips");
-  await mkdir(clipDir, { recursive: true });
+  // attachment system can serve them). Fall back to a temp directory when the
+  // source directory is read-only (external mounts, protected folders, etc.).
+  const preferredDir = join(
+    dirname(asset.filePath),
+    "pipeline",
+    assetId,
+    "clips",
+  );
+  let clipDir: string;
+  try {
+    await mkdir(preferredDir, { recursive: true });
+    await access(preferredDir, constants.W_OK);
+    clipDir = preferredDir;
+  } catch {
+    clipDir = join(tmpdir(), "vellum-clips", assetId);
+    await mkdir(clipDir, { recursive: true });
+  }
 
+  // Include a short unique suffix to prevent filename collisions when
+  // concurrent or repeated calls target the same time range.
+  const timestampSuffix = `${formatTimestamp(startTime).replace(/:/g, "")}-${formatTimestamp(endTime).replace(/:/g, "")}`;
+  const uniqueSuffix = randomUUID().slice(0, 8);
   const clipFilename = title
-    ? `${sanitizeFilename(title)}.${outputFormat}`
-    : `clip-${formatTimestamp(startTime).replace(/:/g, "")}-${formatTimestamp(endTime).replace(/:/g, "")}.${outputFormat}`;
+    ? `${sanitizeFilename(title)}-${timestampSuffix}-${uniqueSuffix}.${outputFormat}`
+    : `clip-${timestampSuffix}-${uniqueSuffix}.${outputFormat}`;
   const clipPath = join(clipDir, clipFilename);
 
   try {