@vellumai/assistant 0.6.5 → 0.7.0

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

@@ -1,80 +0,0 @@
-{
-  "version": 1,
-  "tools": [
-    {
-      "name": "send_notification",
-      "description": "Send an immediate notification. Fires instantly with no delay capability. For one-time future alerts, use schedule_create with fire_at. For recurring alerts, use schedule_create with expression (cron/RRULE). The router decides channels/copy from preferences and urgency hints. Include a confidence score (0-1).",
-      "category": "notifications",
-      "risk": "medium",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "message": {
-            "type": "string",
-            "description": "Notification message the user should receive"
-          },
-          "title": {
-            "type": "string",
-            "description": "Optional notification title"
-          },
-          "urgency": {
-            "type": "string",
-            "enum": ["low", "medium", "high"],
-            "description": "Urgency hint (default: \"medium\")"
-          },
-          "requires_action": {
-            "type": "boolean",
-            "description": "Whether the notification expects user action (default: true)"
-          },
-          "is_async_background": {
-            "type": "boolean",
-            "description": "Whether the event is asynchronous/background work (default: false)"
-          },
-          "visible_in_source_now": {
-            "type": "boolean",
-            "description": "Set true when user is already viewing the source context (default: false)"
-          },
-          "deadline_at": {
-            "type": "number",
-            "description": "Optional deadline timestamp in epoch milliseconds"
-          },
-          "preferred_channels": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "enum": ["vellum", "telegram", "slack"]
-            },
-            "description": "Optional routing hints for preferred channels (not deterministic)"
-          },
-          "conversation_id": {
-            "type": "string",
-            "description": "Optional source conversation ID for notification context"
-          },
-          "source_event_name": {
-            "type": "string",
-            "description": "Optional event name for audit and dedupe grouping (default: \"user.send_notification\")"
-          },
-          "deep_link_metadata": {
-            "type": "object",
-            "description": "Optional metadata clients can use for deep linking"
-          },
-          "dedupe_key": {
-            "type": "string",
-            "description": "Optional dedupe key to suppress duplicate notifications"
-          },
-          "confidence": {
-            "type": "number",
-            "description": "Confidence score (0-1) for this action"
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief non-technical explanation of why this tool is being called"
-          }
-        },
-        "required": ["message", "confidence"]
-      },
-      "executor": "tools/send-notification.ts",
-      "execution_target": "host"
-    }
-  ]
-}

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

@@ -1,152 +0,0 @@
-import { getDeliverableChannels } from "../../../../channels/config.js";
-import { emitNotificationSignal } from "../../../../notifications/emit-signal.js";
-import type { AttentionHints } from "../../../../notifications/signal.js";
-import type { NotificationChannel } from "../../../../notifications/types.js";
-import type {
-  ToolContext,
-  ToolExecutionResult,
-} from "../../../../tools/types.js";
-import { err, ok } from "./shared.js";
-
-const INVALID = Symbol("invalid");
-
-const VALID_URGENCY = new Set<AttentionHints["urgency"]>([
-  "low",
-  "medium",
-  "high",
-]);
-const VALID_CHANNEL_HINTS = new Set<NotificationChannel>(
-  getDeliverableChannels() as NotificationChannel[],
-);
-
-function asNonEmptyString(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
-function parseBool(value: unknown, defaultValue: boolean): boolean {
-  return typeof value === "boolean" ? value : defaultValue;
-}
-
-function parseDeadlineAt(value: unknown): number | undefined | typeof INVALID {
-  if (value == null) return undefined;
-  if (typeof value === "number" && Number.isFinite(value))
-    return Math.trunc(value);
-  if (typeof value === "string") {
-    const parsed = Number(value);
-    if (Number.isFinite(parsed)) return Math.trunc(parsed);
-  }
-  return INVALID;
-}
-
-function parseObject(
-  value: unknown,
-): Record<string, unknown> | undefined | typeof INVALID {
-  if (value === undefined) return undefined;
-  if (!value || typeof value !== "object" || Array.isArray(value))
-    return INVALID;
-  return value as Record<string, unknown>;
-}
-
-function parsePreferredChannels(
-  value: unknown,
-): NotificationChannel[] | undefined | typeof INVALID {
-  if (value === undefined) return undefined;
-  if (!Array.isArray(value)) return INVALID;
-
-  const channels: NotificationChannel[] = [];
-  for (const item of value) {
-    if (
-      typeof item !== "string" ||
-      !VALID_CHANNEL_HINTS.has(item as NotificationChannel)
-    ) {
-      return INVALID;
-    }
-    channels.push(item as NotificationChannel);
-  }
-  return [...new Set(channels)];
-}
-
-export async function run(
-  input: Record<string, unknown>,
-  context: ToolContext,
-): Promise<ToolExecutionResult> {
-  const message = asNonEmptyString(input.message);
-  if (!message) {
-    return err("message is required.");
-  }
-
-  const urgencyInput = asNonEmptyString(input.urgency)?.toLowerCase();
-  if (
-    urgencyInput &&
-    !VALID_URGENCY.has(urgencyInput as AttentionHints["urgency"])
-  ) {
-    return err("urgency must be one of: low, medium, high.");
-  }
-  const urgency =
-    (urgencyInput as AttentionHints["urgency"] | undefined) ?? "medium";
-
-  const deadlineAt = parseDeadlineAt(input.deadline_at);
-  if (deadlineAt === INVALID) {
-    return err("deadline_at must be a valid epoch timestamp (milliseconds).");
-  }
-
-  const deepLinkMetadata = parseObject(input.deep_link_metadata);
-  if (deepLinkMetadata === INVALID) {
-    return err("deep_link_metadata must be an object.");
-  }
-
-  const preferredChannels = parsePreferredChannels(input.preferred_channels);
-  if (preferredChannels === INVALID) {
-    return err(
-      `preferred_channels must be an array containing only: ${[
-        ...VALID_CHANNEL_HINTS,
-      ].join(", ")}.`,
-    );
-  }
-
-  const sourceEventName =
-    asNonEmptyString(input.source_event_name) ?? "user.send_notification";
-  const requestedConversationId =
-    asNonEmptyString(input.conversation_id) ?? context.conversationId;
-  const sourceContextId = requestedConversationId ?? context.conversationId;
-  const title = asNonEmptyString(input.title);
-  const dedupeKey = asNonEmptyString(input.dedupe_key);
-
-  const contextPayload: Record<string, unknown> = {
-    requestedMessage: message,
-    requestedByTool: "send_notification",
-    requestedByContextId: context.conversationId,
-  };
-  if (title) contextPayload.requestedTitle = title;
-  if (requestedConversationId)
-    contextPayload.requestedByConversationId = requestedConversationId;
-  if (preferredChannels && preferredChannels.length > 0)
-    contextPayload.preferredChannels = preferredChannels;
-  if (deepLinkMetadata) contextPayload.deepLinkMetadata = deepLinkMetadata;
-
-  try {
-    await emitNotificationSignal({
-      sourceEventName,
-      sourceChannel: "assistant_tool",
-      sourceContextId,
-      attentionHints: {
-        requiresAction: parseBool(input.requires_action, true),
-        urgency,
-        deadlineAt,
-        isAsyncBackground: parseBool(input.is_async_background, false),
-        visibleInSourceNow: parseBool(input.visible_in_source_now, false),
-      },
-      contextPayload,
-      dedupeKey,
-      throwOnError: true,
-    });
-
-    return ok(
-      "Notification request queued. Channel selection and delivery are handled by the notification router.",
-    );
-  } catch (e) {
-    return err(e instanceof Error ? e.message : String(e));
-  }
-}

package/src/config/bundled-skills/notifications/tools/shared.ts

@@ -1,13 +0,0 @@
-/**
- * Shared utilities for notifications skill tools.
- */
-
-import type { ToolExecutionResult } from "../../../../tools/types.js";
-
-export function ok(content: string): ToolExecutionResult {
-  return { content, isError: false };
-}
-
-export function err(message: string): ToolExecutionResult {
-  return { content: message, isError: true };
-}

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

@@ -1,27 +0,0 @@
----
-name: screen-watch
-description: Observe the screen at regular intervals with OCR
-compatibility: "Designed for Vellum personal assistants"
-metadata:
-  emoji: "\U0001F441\uFE0F"
-  vellum:
-    display-name: "Screen Watch"
----
-
-Start observing the screen at regular intervals for a specified duration. Captures OCR text from the active window and provides periodic commentary.
-
-## Usage
-
-Use `start_screen_watch` when the user wants you to monitor what's happening on their screen. The tool captures OCR text from the active window at configurable intervals and provides commentary based on a specified focus area.
-
-## Parameters
-
-- **focus_area** (required) - What to focus on observing
-- **duration_minutes** - How long to watch in minutes (1-15, default 5)
-- **interval_seconds** - Seconds between screen captures (5-30, default 10)
-
-## Constraints
-
-- Only one active watch session per conversation at a time
-- Duration is clamped to 1-15 minutes
-- Capture interval is clamped to 5-30 seconds

package/src/config/bundled-skills/screen-watch/TOOLS.json

@@ -1,35 +0,0 @@
-{
-  "version": 1,
-  "tools": [
-    {
-      "name": "start_screen_watch",
-      "description": "Start observing the screen at regular intervals for a specified duration. Captures OCR text from the active window and provides periodic commentary.",
-      "category": "observation",
-      "risk": "low",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "duration_minutes": {
-            "type": "number",
-            "description": "How long to watch in minutes (1-15, default 5)"
-          },
-          "interval_seconds": {
-            "type": "number",
-            "description": "Seconds between screen captures (5-30, default 10)"
-          },
-          "focus_area": {
-            "type": "string",
-            "description": "What to focus on observing"
-          },
-          "activity": {
-            "type": "string",
-            "description": "Brief non-technical explanation of what you are watching and why, shown to the user as a status update. Use simple language a non-technical person would understand."
-          }
-        },
-        "required": ["focus_area"]
-      },
-      "executor": "tools/start-screen-watch.ts",
-      "execution_target": "host"
-    }
-  ]
-}

package/src/config/bundled-skills/settings/tools/avatar-get.ts

@@ -1,40 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-import { writeTraitsAndRenderAvatar } from "../../../../avatar/traits-png-sync.js";
-import { readImageFile } from "../../../../tools/shared/filesystem/image-read.js";
-import type {
-  ToolContext,
-  ToolExecutionResult,
-} from "../../../../tools/types.js";
-import { getAvatarDir, getAvatarImagePath } from "../../../../util/platform.js";
-
-export async function run(
-  _input: Record<string, unknown>,
-  _context: ToolContext,
-): Promise<ToolExecutionResult> {
-  const avatarPath = getAvatarImagePath();
-
-  if (!existsSync(avatarPath)) {
-    // Check for native character traits and regenerate the static PNG
-    const traitsPath = join(getAvatarDir(), "character-traits.json");
-    if (existsSync(traitsPath)) {
-      try {
-        const traits = JSON.parse(readFileSync(traitsPath, "utf-8"));
-        const result = writeTraitsAndRenderAvatar(traits);
-        if (result.ok && existsSync(avatarPath)) {
-          return readImageFile(avatarPath);
-        }
-      } catch {
-        // Fall through to default message
-      }
-    }
-    return {
-      content:
-        "No avatar is currently set — no custom image and no character traits found.",
-      isError: false,
-    };
-  }
-
-  return readImageFile(avatarPath);
-}

package/src/config/bundled-skills/settings/tools/avatar-remove.ts

@@ -1,64 +0,0 @@
-import { existsSync, unlinkSync } from "node:fs";
-
-import { buildAssistantEvent } from "../../../../runtime/assistant-event.js";
-import { assistantEventHub } from "../../../../runtime/assistant-event-hub.js";
-import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../../../runtime/assistant-scope.js";
-import type {
-  ToolContext,
-  ToolExecutionResult,
-} from "../../../../tools/types.js";
-import { getLogger } from "../../../../util/logger.js";
-import { getAvatarImagePath } from "../../../../util/platform.js";
-import { updateIdentityAvatarSection } from "./identity-avatar.js";
-
-const log = getLogger("avatar-remove");
-
-export async function run(
-  _input: Record<string, unknown>,
-  _context: ToolContext,
-): Promise<ToolExecutionResult> {
-  const avatarPath = getAvatarImagePath();
-
-  if (!existsSync(avatarPath)) {
-    return {
-      content: "No custom avatar to remove — already using the default.",
-      isError: false,
-    };
-  }
-
-  try {
-    unlinkSync(avatarPath);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    log.error({ error: message }, "Failed to remove avatar image");
-    return { content: `Error removing avatar: ${message}`, isError: true };
-  }
-
-  // character-traits.json is intentionally preserved so the native
-  // character avatar is restored automatically.
-
-  // Notify connected clients so the avatar refreshes immediately.
-  assistantEventHub
-    .publish(
-      buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, {
-        type: "avatar_updated",
-        avatarPath,
-      }),
-    )
-    .catch((err) => {
-      log.warn({ err }, "Failed to publish avatar_updated event");
-    });
-
-  // Update IDENTITY.md to reflect the avatar was removed.
-  updateIdentityAvatarSection(
-    "Default character avatar (no custom image set)",
-    log,
-  );
-
-  log.info("Custom avatar removed, reverting to character avatar");
-
-  return {
-    content: "Custom avatar removed. The character avatar has been restored.",
-    isError: false,
-  };
-}

package/src/config/bundled-skills/settings/tools/avatar-update.ts

@@ -1,88 +0,0 @@
-import { copyFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-import { buildAssistantEvent } from "../../../../runtime/assistant-event.js";
-import { assistantEventHub } from "../../../../runtime/assistant-event-hub.js";
-import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../../../runtime/assistant-scope.js";
-import type {
-  ToolContext,
-  ToolExecutionResult,
-} from "../../../../tools/types.js";
-import { getLogger } from "../../../../util/logger.js";
-import {
-  getAvatarImagePath,
-  getWorkspaceDir,
-} from "../../../../util/platform.js";
-import { updateIdentityAvatarSection } from "./identity-avatar.js";
-
-const log = getLogger("avatar-update");
-
-/** Canonical path where the custom avatar PNG is stored. */
-function getAvatarPath(): string {
-  return getAvatarImagePath();
-}
-
-export async function run(
-  input: Record<string, unknown>,
-  _context: ToolContext,
-): Promise<ToolExecutionResult> {
-  const sourcePath = input.image_path as string | undefined;
-
-  if (!sourcePath || typeof sourcePath !== "string") {
-    return {
-      content:
-        'Error: "image_path" is required. Provide the path to the image file (absolute or relative to workspace).',
-      isError: true,
-    };
-  }
-
-  const workspaceDir = getWorkspaceDir();
-  const resolvedSource = sourcePath.startsWith("/")
-    ? sourcePath
-    : join(workspaceDir, sourcePath);
-
-  if (!existsSync(resolvedSource)) {
-    return {
-      content: `Error: source file not found: ${resolvedSource}`,
-      isError: true,
-    };
-  }
-
-  const avatarPath = getAvatarPath();
-  const avatarDir = dirname(avatarPath);
-
-  try {
-    mkdirSync(avatarDir, { recursive: true });
-    copyFileSync(resolvedSource, avatarPath);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    log.error({ error: message }, "Failed to copy avatar image");
-    return { content: `Error copying avatar: ${message}`, isError: true };
-  }
-
-  // Keep character-traits.json and character-ascii.txt so the character
-  // avatar can be restored if the custom image is later removed.
-
-  // Notify connected clients so the avatar refreshes immediately.
-  assistantEventHub
-    .publish(
-      buildAssistantEvent(DAEMON_INTERNAL_ASSISTANT_ID, {
-        type: "avatar_updated",
-        avatarPath,
-      }),
-    )
-    .catch((err) => {
-      log.warn({ err }, "Failed to publish avatar_updated event");
-    });
-
-  // Clear any stale avatar description from IDENTITY.md so the assistant
-  // is prompted to describe the new image on next read.
-  updateIdentityAvatarSection(null, log);
-
-  log.info({ avatarPath, source: resolvedSource }, "Avatar updated");
-
-  return {
-    content: `Avatar updated from ${sourcePath}. The app will refresh automatically. The avatar description in IDENTITY.md has been cleared — describe what the new avatar looks like by updating the ## Avatar section in IDENTITY.md with a plain-text description (not an image link).`,
-    isError: false,
-  };
-}

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

@@ -1,84 +0,0 @@
----
-name: skills-catalog
-description: Discover bundled skills and search/install community skills from the skills.sh registry
-compatibility: "Designed for Vellum personal assistants"
-metadata:
-  emoji: "\U0001F9E9"
-  vellum:
-    display-name: "Skills Catalog"
-    activation-hints:
-      - "what can you do"
-      - "find a skill"
-      - "install a skill"
-      - "community skills"
-      - "skills.sh"
-      - "search for skills"
-    avoid-when:
-      - "User is asking about a specific bundled skill already visible in the catalog"
----
-
-You can help the user discover what skills are available and find community skills to extend the assistant's capabilities.
-
-## Bundled skills (first-party)
-
-First-party skills are **bundled** with the assistant - they are compiled in and always available. They do not need to be installed or downloaded. To activate a bundled skill, use the `skill_load` tool:
-
-```
-skill_load skill=<skill-id>
-```
-
-The skill catalog shown in the system prompt lists all bundled skills with their IDs. When a user asks about capabilities, refer to this list to find relevant bundled skills and load them as needed.
-
-## Community skills (skills.sh)
-
-Community skills are published on the skills.sh registry and can be searched, inspected, and installed on demand using the `assistant skills` CLI.
-
-### Searching for community skills
-
-```bash
-assistant skills search "<query>"
-```
-
-Returns matching skills with their slug, source, install counts, and security audit badges. Use this when the user asks for a capability not covered by bundled skills.
-
-### Installing a community skill
-
-**Trust model - check the source guardian before installing:**
-
-- **Vellum-owned** (`vellum-ai/*`): First-party skills published by the Vellum team. Install these directly without prompting - they are vetted and trusted.
-- **Third-party** (any other guardian): Ask the user for permission first. Present the skill name, source, audit results, and install count. Say something like: "I found a community skill that could help, but it's published by a third party - we haven't vetted it. Want to install it anyway?"
-
-```bash
-assistant skills add <owner>/<repo>@<skill-name>
-```
-
-For example:
-```bash
-assistant skills add vercel-labs/skills@find-skills
-```
-
-Once installed, the skill appears in the workspace skills directory and can be loaded with `skill_load` like any other skill.
-
-## Typical flow
-
-1. **User asks about capabilities** - "Can you order food?" or "What can you do?"
-   - Check the bundled skills list in the system prompt
-   - Present relevant skills to the user
-   - Load any that match with `skill_load`
-
-2. **User wants a capability not covered by bundled skills** - "Can you do X?"
-   - Search with `assistant skills search "<query>"`
-   - Present matching results with descriptions, install counts, and audit badges
-   - Check the source guardian to determine trust level (see trust model above)
-   - Install with `assistant skills add <owner>/<repo>@<skill-name>`
-   - Load it with `skill_load`
-
-3. **Skill has dependencies** - if `includes` lists other skill IDs, load those first with `skill_load`
-
-## Notes
-
-- Bundled skills are always available and do not need installation
-- Community skills are installed to the workspace skills directory
-- After installing a community skill, it is auto-enabled and immediately loadable
-- Skills can be enabled or disabled via feature flags without uninstalling them
-- Never install third-party community skills without explicit user confirmation