@vellumai/assistant 0.4.54 → 0.4.56

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

@@ -8,14 +8,17 @@ import {
   type ImageGenCredentials,
   mapGeminiError,
 } from "../../../../media/gemini-image-service.js";
-import { getAttachmentsByIds } from "../../../../memory/attachments-store.js";
-import { getConversationThreadType } from "../../../../memory/conversation-crud.js";
+import {
+  getAttachmentContent,
+  getAttachmentsByIds,
+} from "../../../../memory/attachments-store.js";
+import { getConversationType } from "../../../../memory/conversation-crud.js";
 import {
   buildManagedBaseUrl,
   resolveManagedProxyContext,
 } from "../../../../providers/managed-proxy/context.js";
 import type { ImageContent } from "../../../../providers/types.js";
-import { getSecureKeyAsync } from "../../../../security/secure-keys.js";
+import { getProviderKeyAsync } from "../../../../security/secure-keys.js";
 import { getAttachmentSourceConversations } from "../../../../tools/assets/search.js";
 import type {
   ToolContext,
@@ -34,11 +37,11 @@ function isAttachmentAccessible(
   if (sources.length === 0) {
     return true; // orphan attachments are universally visible
   }
-  const hasStandard = sources.some((s) => s.threadType !== "private");
+  const hasStandard = sources.some((s) => s.conversationType !== "private");
   if (hasStandard) {
     return true;
   }
-  // All sources are private — visible only if the caller is in one of those threads
+  // All sources are private — visible only if the caller is in one of those conversations
   return sources.some((s) =>
     isAttachmentVisible(
       { conversationId: s.conversationId, isPrivate: true },
@@ -52,7 +55,7 @@ export async function run(
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
   const config = getConfig();
-  const apiKey = await getSecureKeyAsync("gemini");
+  const apiKey = await getProviderKeyAsync("gemini");
 
   // Resolve credentials: prefer direct API key, fall back to managed proxy
   let credentials: ImageGenCredentials | undefined;
@@ -81,7 +84,9 @@ export async function run(
   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 model =
+    (input.model as string | undefined) ??
+    config.services["image-generation"].model;
   const variants = input.variants as number | undefined;
 
   // Resolve source images from attachments for edit mode
@@ -91,10 +96,10 @@ export async function run(
     const attachments = getAttachmentsByIds(attachmentIds);
 
     // Build visibility context for the current conversation
-    const threadType = getConversationThreadType(context.conversationId);
+    const conversationType = getConversationType(context.conversationId);
     const currentContext: AttachmentContext = {
       conversationId: context.conversationId,
-      isPrivate: threadType === "private",
+      isPrivate: conversationType === "private",
     };
 
     // Filter to only visible attachments using their originating context
@@ -110,10 +115,22 @@ export async function run(
       };
     }
 
-    sourceImages = visibleAttachments.map((att) => ({
-      mimeType: att.mimeType,
-      dataBase64: att.dataBase64,
-    }));
+    sourceImages = visibleAttachments
+      .map((att) => {
+        let buffer: Buffer | null | undefined;
+        try {
+          buffer = getAttachmentContent(att.id);
+        } catch {
+          // File-backed attachment may point to a missing or unreadable file
+          return undefined;
+        }
+        if (!buffer) return undefined;
+        return {
+          mimeType: att.mimeType,
+          dataBase64: buffer.toString("base64"),
+        };
+      })
+      .filter((img): img is NonNullable<typeof img> => img !== undefined);
   }
 
   try {

package/src/config/bundled-skills/media-processing/services/preprocess.ts

@@ -18,6 +18,7 @@ import {
   type ProcessingStage,
   updateProcessingStage,
 } from "../../../../memory/media-store.js";
+import { silentlyWithLog } from "../../../../util/silently.js";
 import {
   FFMPEG_PALETTE_TIMEOUT_MS,
   FFMPEG_PREPROCESS_TIMEOUT_MS,
@@ -629,7 +630,10 @@ export async function preprocessForAsset(
 
     return manifest;
   } catch (err) {
-    await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    await silentlyWithLog(
+      rm(tempDir, { recursive: true, force: true }),
+      "preprocess temp cleanup",
+    );
     const msg = (err as Error).message;
     updateProcessingStage(stage.id, {
       status: "failed",

package/src/config/bundled-skills/media-processing/tools/analyze-keyframes.ts

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import { getMediaAssetById } from "../../../../memory/media-store.js";
-import { getSecureKeyAsync } from "../../../../security/secure-keys.js";
+import { getProviderKeyAsync } from "../../../../security/secure-keys.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -29,7 +29,7 @@ export async function mapSegmentsForAsset(
   options: MapSegmentsOptions,
   onProgress?: (msg: string) => void,
 ): Promise<MapOutput> {
-  const apiKey = await getSecureKeyAsync("gemini");
+  const apiKey = await getProviderKeyAsync("gemini");
 
   if (!apiKey) {
     throw new Error(
@@ -121,7 +121,7 @@ export async function run(
     let output: MapOutput;
 
     if (mode === "direct_video") {
-      const apiKey = await getSecureKeyAsync("gemini");
+      const apiKey = await getProviderKeyAsync("gemini");
       if (!apiKey) {
         return {
           content:

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

@@ -6,7 +6,9 @@ metadata:
   emoji: "\U0001F4AC"
   vellum:
     display-name: "Messaging"
-    user-invocable: true
+    activation-hints:
+      - "Email, messaging, inbox management, read/send/search on any platform"
+      - "Handles credential flows -- do not improvise setup instructions"
 ---
 
 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.
@@ -32,9 +34,9 @@ When a platform is connected (auth test succeeds), always use the messaging API
 
 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 Slack and Telegram)
+### Public Ingress (required for Telegram)
 
-Slack and Telegram setup 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`. Gmail on the desktop app uses a loopback callback and does not require public ingress; the channel path (Path B in the google-oauth-applescript skill) handles public ingress internally when needed.
+Telegram setup requires a publicly reachable URL for webhook delivery. The **public-ingress** skill handles ngrok tunnel setup and persists the URL as `ingress.publicBaseUrl`. Slack uses Socket Mode and does not require public ingress. Gmail on the desktop app uses a loopback callback and does not require public ingress; the channel path (Path B in the google-oauth-applescript skill) handles public ingress internally when needed.
 
 ### Email Connection Flow
 
@@ -59,16 +61,12 @@ When the user asks to "connect my email", "set up email", "manage my email", or
 
 ### 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. Load the **slack-oauth-setup** skill:
-   - Call `skill_load` with `skill: "slack-oauth-setup"` to load the dependency skill.
-   - Tell the user Slack 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 Slack?"
-     - **detail:** "I'll walk you through creating a Slack App and connecting your workspace. The process takes a few minutes, and I'll ask for your approval before each step."
-     - **confirmLabel:** "Get Started"
-     - **cancelLabel:** "Not Now"
-   - Wait for the user to confirm before proceeding with the setup guide. If they decline, acknowledge and let them know they can set it up later.
-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.
+Slack connects via Socket Mode using a bot token and app-level token (not OAuth). Load the **slack-app-setup** skill, which guides the user through creating a Slack app from a pre-configured manifest, collecting tokens securely, and connecting the bot to their workspace:
+
+- Call `skill_load` with `skill: "slack-app-setup"` to load the dependency skill.
+- Tell the user Slack isn't connected yet and briefly explain what the setup involves, then follow the skill's guided flow.
+
+The slack-app-setup skill handles: manifest-driven app creation, app token and bot token collection via secure prompt (never accept tokens pasted in plaintext chat), token validation, workspace metadata storage, and optional guardian verification. Socket Mode connects automatically once both credentials are stored.
 
 ### Telegram
 

package/src/config/bundled-skills/messaging/TOOLS.json

@@ -276,10 +276,6 @@
             "type": "string",
             "description": "Platform (e.g. \"slack\", \"gmail\"). Required for create/list."
           },
-          "account": {
-            "type": "string",
-            "description": "Email address of the account to use. Required when multiple accounts are connected for the same platform. If omitted, uses the most recently connected account."
-          },
           "conversation_id": {
             "type": "string",
             "description": "Target conversation/channel ID (for create)"

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

@@ -6,7 +6,6 @@ metadata:
   emoji: "🔔"
   vellum:
     display-name: "Notifications"
-    user-invocable: true
 ---
 
 Use `send_notification` for user-facing alerts and notifications. This tool routes through the unified notification pipeline, which handles channel selection, delivery, deduplication, and audit logging.
@@ -22,17 +21,17 @@ Use `send_notification` for user-facing alerts and notifications. This tool rout
 - Never reuse a `dedupe_key` across logically distinct notifications, even if they are related. The key means "this exact event already fired," not "these events are in the same category."
 - If you omit `dedupe_key`, the LLM decision engine may generate one automatically based on signal context. This means even keyless signals can be deduplicated if the engine considers them duplicates of a recent event.
 
-## Threading
+## Conversation Grouping
 
-Thread grouping is handled by the LLM-powered decision engine, not by any parameter you pass. There is no explicit "post to thread X" parameter — thread reuse is inferred, not commanded.
+Conversation grouping is handled by the LLM-powered decision engine, not by any parameter you pass. There is no explicit "post to conversation X" parameter — conversation reuse is inferred, not commanded.
 
-**How it works:** The engine evaluates recent notification thread candidates and decides whether a new signal is a continuation of an existing thread based on `source_event_name`, provenance metadata, and message content. Use natural, descriptive titles and bodies — the engine groups by semantic relatedness, not string matching.
+**How it works:** The engine evaluates recent notification conversation candidates and decides whether a new signal is a continuation of an existing conversation based on `source_event_name`, provenance metadata, and message content. Use natural, descriptive titles and bodies — the engine groups by semantic relatedness, not string matching.
 
 **`source_event_name` is the primary grouping signal.** Use a stable event name for notifications that belong to the same logical stream (e.g. `dog.news.thread.reply` for all replies in a thread). Use a distinct event name when the notification represents a genuinely different kind of event.
 
 **Practical constraints:**
 
-- Thread candidates are scoped to the **last 24 hours** (max 5 per channel). You cannot reuse an old thread from days ago.
+- Conversation candidates are scoped to the **last 24 hours** (max 5 per channel). You cannot reuse an old conversation from days ago.
 - The engine will only reuse conversations originally created by the notification system (`source === 'notification'`). It will never append to a user-initiated conversation, even if it looks related.
 
 ## Important

package/src/config/bundled-skills/notifications/TOOLS.json

@@ -48,7 +48,7 @@
           },
           "conversation_id": {
             "type": "string",
-            "description": "Optional source conversation/session ID for notification context"
+            "description": "Optional source conversation ID for notification context"
           },
           "source_event_name": {
             "type": "string",

package/src/config/bundled-skills/notifications/tools/send-notification.ts

@@ -110,14 +110,14 @@ export async function run(
     asNonEmptyString(input.source_event_name) ?? "user.send_notification";
   const requestedConversationId =
     asNonEmptyString(input.conversation_id) ?? context.conversationId;
-  const sourceSessionId = requestedConversationId ?? context.sessionId;
+  const sourceSessionId = requestedConversationId ?? context.conversationId;
   const title = asNonEmptyString(input.title);
   const dedupeKey = asNonEmptyString(input.dedupe_key);
 
   const contextPayload: Record<string, unknown> = {
     requestedMessage: message,
     requestedByTool: "send_notification",
-    requestedBySessionId: context.sessionId,
+    requestedBySessionId: context.conversationId,
   };
   if (title) contextPayload.requestedTitle = title;
   if (requestedConversationId)

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

@@ -6,7 +6,10 @@ metadata:
   emoji: "\U0001F500"
   vellum:
     display-name: "Orchestration"
-    user-invocable: true
+    activation-hints:
+      - "Multiple independent work streams that benefit from parallel execution"
+    avoid-when:
+      - "Single-focus tasks -- work directly"
 ---
 
 Use `swarm_delegate` when facing complex multi-part tasks that benefit from parallel execution. The tool decomposes an objective into independent specialist subtasks, runs them concurrently, and synthesises the results.

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: phone-calls
-description: Set up Twilio for AI-powered voice calls — both outgoing calls on behalf of the user and incoming calls where the assistant answers as a receptionist
+description: "Make outgoing phone calls, receive incoming calls, and pull up past call transcripts. Everything needed for your assistant to act as an AI receptionist."
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "📞"
   vellum:
     display-name: "Phone Calls"
-    user-invocable: true
     includes:
       - "twilio-setup"
       - "public-ingress"
       - "elevenlabs-voice"
+    activation-hints:
+      - "Phone calling setup, Twilio config, placing/receiving calls"
+      - "Do NOT improvise Twilio setup from general knowledge"
+    avoid-when:
+      - "Don't confuse with voice-setup (local PTT/mic) or guardian-verify-setup"
 ---
 
 You are helping the user set up and manage phone calls via Twilio. This skill covers enabling the calls feature, placing outbound calls, receiving inbound calls, and interacting with live calls. Twilio credential storage, phone number provisioning, and public ingress are handled by the **twilio-setup** skill.
@@ -51,18 +55,26 @@ Before making real calls, offer a quick verification. Suggest a test call to the
 
 If they agree, ask for their personal phone number and place a test call with a simple task like "Introduce yourself and confirm the call system is working."
 
-## Step 5: Guardian Verification (Optional)
+## Step 5: Guardian Verification
 
-By going through Guardian Verification, the user will be recognized any time they call the assistant and will be able to interact with the assistant with elevated privileges. You should encourage the user to go through the guardian verification process, but not force it.
+The final step is for the user to verify themselves so that they are recognized when they call you. It's also a great way for them to hear what you sound like and decide if they want you to use a different voice.
 
-Load the `guardian-verify-setup` skill with `channel: "phone"`. The skill handles the full verification flow (outbound call, code entry, confirmation).
+Load the `guardian-verify-setup` skill and follow the instructions for guardian verification over the `phone` channel. This will require the user to provide you with their phone number and then for you to give them a call. Say something like:
 
-If the user declines, skip this step. To re-check guardian status later:
+> Want to do a quick verification call now so that you can hear what I sound like and also so that I recognize your number when you call me in the future?
+> I'll show a 6 digit code here in the chat and when you answer my call, enter it using your phone's keypad.
+
+You can check their verification status with:
 
 ```bash
 assistant channel-verification-sessions status --channel phone --json
 ```
 
+After they are verified, ask them what they think of your voice and offer to let them change it. Load up the `elevenlabs-voice` skill and follow the instructions there to see what voices are available and how to update your configured voice. Say something like:
+
+> Great, you're verified! What did you think of my voice? We can update it if you'd like.
+
+
 # Making Outbound Calls
 
 Use the `call_start` tool to place outbound calls. Every call requires:
@@ -150,7 +162,7 @@ During an active call, the user can interact with the AI voice agent via the HTT
 When the AI voice agent encounters something it needs user input for, it dispatches an **ASK_GUARDIAN** request to all configured guardian channels (mac desktop, Telegram). The call status changes to `waiting_on_user`.
 
 1. The question is delivered simultaneously to every configured channel. The first channel to respond wins (first-response-wins semantics) -- once one channel provides an answer, the other channels receive a "already answered" notice.
-2. On the mac desktop, a guardian request thread is created with the question. On Telegram, the question text and a request code are delivered via the gateway.
+2. On the mac desktop, a guardian request conversation is created with the question. On Telegram, the question text and a request code are delivered via the gateway.
 3. If DTMF callee verification is enabled, the callee must enter a verification code before the call proceeds (see the **DTMF Callee Verification** section above).
 4. The guardian provides an answer through whichever channel they prefer. The answer is routed to the AI voice agent, which continues the conversation naturally.
 
@@ -182,7 +194,7 @@ When there is **no pending question** but the call is still active, the user can
 
 The instruction is injected into the AI voice agent's conversation context as high-priority input, and the agent adjusts its behavior accordingly.
 
-**Note:** Steering is done via the HTTP API, not the desktop chat thread. The desktop thread only receives pointer/status messages about the call.
+**Note:** Steering is done via the HTTP API, not the desktop chat conversation. The desktop conversation only receives pointer/status messages about the call.
 
 ### Call status values
 

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

@@ -129,7 +129,7 @@ Phrases like "at the 45 minute mark", "at the top of the hour", "at noon", or "2
 
 **Resolution rules (in priority order):**
 
-1. **Session-anchored expressions** — if the user mentioned a start time earlier in conversation ("I got here at 9", "meeting started at 2:10"), interpret offset-style phrases ("the 45 minute mark", "20 minutes in") as `start_time + offset`.
+1. **Conversation-anchored expressions** — if the user mentioned a start time earlier in conversation ("I got here at 9", "meeting started at 2:10"), interpret offset-style phrases ("the 45 minute mark", "20 minutes in") as `start_time + offset`.
 
 2. **Clock-position expressions** — when no start time is in context, map directly to a wall-clock time:
    - "top of the hour" → next :00

package/src/config/bundled-skills/screen-watch/SKILL.md

@@ -6,7 +6,6 @@ metadata:
   emoji: "\U0001F441\uFE0F"
   vellum:
     display-name: "Screen Watch"
-    user-invocable: true
 ---
 
 Start observing the screen at regular intervals for a specified duration. Captures OCR text from the active window and provides periodic commentary.

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

@@ -6,7 +6,6 @@ metadata:
   emoji: "📧"
   vellum:
     display-name: "Email Sequences"
-    user-invocable: true
 ---
 
 You are an email sequence assistant. Use the sequence tools to help users create and manage automated multi-step email drip campaigns.

package/src/config/bundled-skills/sequences/TOOLS.json

@@ -34,9 +34,9 @@
                   "type": "string",
                   "description": "Prompt or body text for this step"
                 },
-                "reply_to_thread": {
+                "reply_in_same_conversation": {
                   "type": "boolean",
-                  "description": "Whether to reply in the existing thread (default true for step 2+)"
+                  "description": "Whether to reply in the same conversation (default true for step 2+)"
                 },
                 "require_approval": {
                   "type": "boolean",
@@ -164,9 +164,9 @@
                   "type": "string",
                   "description": "Prompt or body text for this step"
                 },
-                "reply_to_thread": {
+                "reply_in_same_conversation": {
                   "type": "boolean",
-                  "description": "Whether to reply in the existing thread"
+                  "description": "Whether to reply in the same conversation"
                 },
                 "require_approval": {
                   "type": "boolean",

package/src/config/bundled-skills/sequences/tools/sequence-create.ts

@@ -27,7 +27,8 @@ export async function run(
       delaySeconds: (s.delay_seconds as number) ?? 0,
       subjectTemplate: (s.subject as string) ?? `Step ${i + 1}`,
       bodyPrompt: (s.body_prompt as string) ?? "",
-      replyToThread: (s.reply_to_thread as boolean) ?? i > 0,
+      replyInSameConversation:
+        (s.reply_in_same_conversation as boolean) ?? i > 0,
       requireApproval: (s.require_approval as boolean) ?? false,
     }));
 

package/src/config/bundled-skills/sequences/tools/sequence-update.ts

@@ -101,7 +101,8 @@ export async function run(
         delaySeconds: (s.delay_seconds as number) ?? 0,
         subjectTemplate: (s.subject as string) ?? `Step ${i + 1}`,
         bodyPrompt: (s.body_prompt as string) ?? "",
-        replyToThread: (s.reply_to_thread as boolean) ?? i > 0,
+        replyInSameConversation:
+          (s.reply_in_same_conversation as boolean) ?? i > 0,
         requireApproval: (s.require_approval as boolean) ?? false,
       }),
     );

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

@@ -1,12 +1,11 @@
 ---
 name: settings
-description: Manage assistant voice, avatar, and system settings
+description: Manage assistant voice and system settings
 compatibility: "Designed for Vellum personal assistants"
 metadata:
   emoji: "\u2699\uFE0F"
   vellum:
     display-name: "Settings"
-    user-invocable: true
 ---
 
-Tools for managing assistant settings: voice configuration (TTS voice, PTT activation key, conversation timeout), avatar generation, system settings navigation, and in-app settings tab navigation.
+Tools for managing assistant settings: voice configuration (TTS voice, PTT activation key, conversation timeout), system settings navigation, and in-app settings tab navigation.

package/src/config/bundled-skills/settings/TOOLS.json

@@ -26,28 +26,6 @@
       "executor": "tools/voice-config-update.ts",
       "execution_target": "host"
     },
-    {
-      "name": "set_avatar",
-      "description": "Generate a custom avatar image from a text description. Saves the result as the assistant's avatar.",
-      "category": "system",
-      "risk": "low",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "description": {
-            "type": "string",
-            "description": "A text description of the desired avatar appearance, e.g. \"a friendly purple cat with green eyes wearing a tiny hat\"."
-          },
-          "reason": {
-            "type": "string",
-            "description": "Brief non-technical explanation of what you are creating and why, shown to the user as a status update. Use simple language a non-technical person would understand."
-          }
-        },
-        "required": ["description"]
-      },
-      "executor": "tools/set-avatar.ts",
-      "execution_target": "host"
-    },
     {
       "name": "open_system_settings",
       "description": "Open a specific macOS System Settings pane (e.g. Microphone or Speech Recognition privacy). Use this to guide the user through granting permissions that can only be toggled in System Settings.",

package/src/config/bundled-skills/skill-management/SKILL.md

@@ -5,7 +5,6 @@ metadata:
   emoji: "\U0001F9E9"
   vellum:
     display-name: "Skill Management"
-    user-invocable: true
 ---
 
 Manage the lifecycle of custom managed skills in `~/.vellum/workspace/skills`.

package/src/config/bundled-skills/skill-management/TOOLS.json

@@ -29,14 +29,6 @@
             "type": "string",
             "description": "Optional emoji icon for the skill."
           },
-          "user_invocable": {
-            "type": "boolean",
-            "description": "Whether users can invoke this skill directly (default: true)."
-          },
-          "disable_model_invocation": {
-            "type": "boolean",
-            "description": "Whether to prevent the model from auto-invoking this skill (default: false)."
-          },
           "overwrite": {
             "type": "boolean",
             "description": "Whether to overwrite an existing skill with the same ID (default: false)."

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

@@ -6,7 +6,6 @@ metadata:
   emoji: "💬"
   vellum:
     display-name: "Slack"
-    user-invocable: true
 ---
 
 You are a Slack assistant that helps users stay on top of their Slack workspace. Use the slack tools for channel scanning, thread summarization, and Slack-specific operations.

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

@@ -15,12 +15,12 @@ Subagent orchestration -- spawn background agents to work on tasks in parallel.
 Subagents follow this status flow: `pending` -> `running` -> `completed` / `failed` / `aborted`
 
 - **Spawn**: Use `subagent_spawn` with a label and objective. The subagent runs autonomously.
-- **Auto-notification**: The parent session is automatically notified when a subagent reaches a terminal status. Do NOT poll `subagent_status`.
+- **Auto-notification**: The parent conversation is automatically notified when a subagent reaches a terminal status. Do NOT poll `subagent_status`.
 - **Read output**: Use `subagent_read` only after the subagent reaches a terminal status (completed/failed/aborted).
 
 ## Ownership
 
-Only the parent session that spawned a subagent can interact with it (check status, send messages, abort, or read output).
+Only the parent conversation that spawned a subagent can interact with it (check status, send messages, abort, or read output).
 
 ## Silent Mode
 

package/src/config/bundled-skills/subagent/TOOLS.json

@@ -37,7 +37,7 @@
     },
     {
       "name": "subagent_status",
-      "description": "Get the status of a specific subagent or list all subagents for the current session. Only use this when the user explicitly asks about subagent status \u2014 do NOT poll automatically, as you will be notified when subagents complete.",
+      "description": "Get the status of a specific subagent or list all subagents for the current conversation. Only use this when the user explicitly asks about subagent status \u2014 do NOT poll automatically, as you will be notified when subagents complete.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -45,7 +45,7 @@
         "properties": {
           "subagent_id": {
             "type": "string",
-            "description": "Optional subagent ID to query. If omitted, returns all subagents for this session."
+            "description": "Optional subagent ID to query. If omitted, returns all subagents for this conversation."
           },
           "reason": {
             "type": "string",

package/src/config/bundled-skills/transcribe/tools/transcribe-media.ts

@@ -10,12 +10,16 @@ import {
 import { tmpdir } from "node:os";
 import { extname, join } from "node:path";
 
-import { getAttachmentsByIds } from "../../../../memory/attachments-store.js";
-import { getSecureKeyAsync } from "../../../../security/secure-keys.js";
+import {
+  getAttachmentsByIds,
+  getFilePathForAttachment,
+} from "../../../../memory/attachments-store.js";
+import { getProviderKeyAsync } from "../../../../security/secure-keys.js";
 import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
+import { silentlyWithLog } from "../../../../util/silently.js";
 import {
   FFMPEG_TRANSCODE_TIMEOUT_MS,
   FFPROBE_TIMEOUT_MS,
@@ -160,6 +164,26 @@ async function resolveSource(
         isError: true,
       };
     }
+    // Check if this is a file-backed attachment (large files stored on disk)
+    const onDiskPath = getFilePathForAttachment(attachment.id);
+    if (onDiskPath) {
+      // File-backed attachment — use the on-disk file directly
+      try {
+        await access(onDiskPath);
+      } catch {
+        return {
+          content: `Attachment file not found on disk: ${onDiskPath}`,
+          isError: true,
+        };
+      }
+      return {
+        inputPath: onDiskPath,
+        isVideo: mime.startsWith("video/"),
+        tempFile: null,
+      };
+    }
+
+    // Inline attachment — decode base64 to a temp file
     const ext = mime.startsWith("video/") ? ".mp4" : ".m4a";
     const tempPath = join(
       tmpdir(),
@@ -239,7 +263,10 @@ async function transcribeViaApi(
     return parts.join(" ");
   } finally {
     const { rm } = await import("node:fs/promises");
-    await rm(chunkDir, { recursive: true, force: true }).catch(() => {});
+    await silentlyWithLog(
+      rm(chunkDir, { recursive: true, force: true }),
+      "transcribe chunk cleanup",
+    );
   }
 }
 
@@ -332,7 +359,10 @@ async function transcribeViaLocal(
     return parts.join(" ");
   } finally {
     const { rm } = await import("node:fs/promises");
-    await rm(chunkDir, { recursive: true, force: true }).catch(() => {});
+    await silentlyWithLog(
+      rm(chunkDir, { recursive: true, force: true }),
+      "transcribe chunk cleanup",
+    );
   }
 }
 
@@ -419,7 +449,7 @@ export async function run(
   // Validate API key for api mode
   let openaiKey: string | undefined;
   if (mode === "api") {
-    openaiKey = await getSecureKeyAsync("openai");
+    openaiKey = await getProviderKeyAsync("openai");
     if (!openaiKey) {
       return {
         content: