@vellumai/assistant 0.4.43 → 0.4.45

package/src/tools/shared/filesystem/image-read.ts

@@ -0,0 +1,192 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync, statSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { ImageContent } from "../../../providers/types.js";
+import type { ToolExecutionResult } from "../../types.js";
+
+export const IMAGE_EXTENSIONS = new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".webp",
+]);
+
+const MAX_SIZE_BYTES = 20 * 1024 * 1024; // 20 MB
+
+// Images above this threshold get auto-optimized via sips (macOS) to avoid
+// sending multi-MB base64 payloads to the LLM API.
+const OPTIMIZE_THRESHOLD_BYTES = 1 * 1024 * 1024; // 1 MB
+const OPTIMIZE_MAX_DIMENSION = 1568; // Anthropic's recommended max
+const OPTIMIZE_JPEG_QUALITY = 80;
+
+/**
+ * Detect the actual image format from the first bytes of the buffer.
+ * Returns the MIME type, or null if unrecognised.
+ */
+function detectMediaType(buf: Buffer): string | null {
+  if (buf.length < 12) return null;
+
+  // JPEG: FF D8 FF
+  if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+    return "image/jpeg";
+  }
+  // PNG: 89 50 4E 47 0D 0A 1A 0A
+  if (
+    buf[0] === 0x89 &&
+    buf[1] === 0x50 &&
+    buf[2] === 0x4e &&
+    buf[3] === 0x47
+  ) {
+    return "image/png";
+  }
+  // GIF: 47 49 46 38
+  if (
+    buf[0] === 0x47 &&
+    buf[1] === 0x49 &&
+    buf[2] === 0x46 &&
+    buf[3] === 0x38
+  ) {
+    return "image/gif";
+  }
+  // WebP: RIFF....WEBP
+  if (
+    buf[0] === 0x52 &&
+    buf[1] === 0x49 &&
+    buf[2] === 0x46 &&
+    buf[3] === 0x46 &&
+    buf[8] === 0x57 &&
+    buf[9] === 0x45 &&
+    buf[10] === 0x42 &&
+    buf[11] === 0x50
+  ) {
+    return "image/webp";
+  }
+
+  return null;
+}
+
+/**
+ * Use macOS `sips` to resize and convert an image to JPEG.
+ * Returns the path to the optimized temp file, or null if sips is unavailable.
+ */
+function optimizeWithSips(srcPath: string): string | null {
+  const tmpPath = join(tmpdir(), `vellum-view-image-${Date.now()}.jpg`);
+  try {
+    execFileSync(
+      "sips",
+      [
+        "--resampleHeightWidthMax",
+        String(OPTIMIZE_MAX_DIMENSION),
+        "-s",
+        "format",
+        "jpeg",
+        "-s",
+        "formatOptions",
+        String(OPTIMIZE_JPEG_QUALITY),
+        srcPath,
+        "--out",
+        tmpPath,
+      ],
+      { stdio: "pipe", timeout: 15_000 },
+    );
+    return tmpPath;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read an image file from disk, optionally optimize it, and return a
+ * ToolExecutionResult with base64-encoded image content blocks.
+ *
+ * The caller is responsible for path resolution and sandbox enforcement —
+ * `resolvedPath` must be an already-validated absolute path.
+ */
+export function readImageFile(resolvedPath: string): ToolExecutionResult {
+  let stat;
+  try {
+    stat = statSync(resolvedPath);
+  } catch {
+    return {
+      content: `Error: file not found: ${resolvedPath}`,
+      isError: true,
+    };
+  }
+
+  if (!stat.isFile()) {
+    return { content: `Error: ${resolvedPath} is not a file`, isError: true };
+  }
+
+  if (stat.size > MAX_SIZE_BYTES) {
+    const sizeMB = (stat.size / (1024 * 1024)).toFixed(1);
+    return {
+      content: `Error: image too large (${sizeMB} MB). Maximum is 20 MB.`,
+      isError: true,
+    };
+  }
+
+  let buffer: Buffer;
+  let optimized = false;
+  let tmpPath: string | null = null;
+
+  try {
+    if (stat.size > OPTIMIZE_THRESHOLD_BYTES) {
+      tmpPath = optimizeWithSips(resolvedPath);
+      if (tmpPath) {
+        buffer = readFileSync(tmpPath) as Buffer;
+        optimized = true;
+      } else {
+        buffer = readFileSync(resolvedPath) as Buffer;
+      }
+    } else {
+      buffer = readFileSync(resolvedPath) as Buffer;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error reading file: ${msg}`, isError: true };
+  } finally {
+    if (tmpPath) {
+      try {
+        unlinkSync(tmpPath);
+      } catch {
+        /* ignore cleanup errors */
+      }
+    }
+  }
+
+  // Detect actual format from magic bytes — never trust the file extension
+  // alone, since sips converts to JPEG and files can be misnamed.
+  const detectedType = detectMediaType(buffer);
+  if (!detectedType) {
+    return {
+      content: `Error: could not detect image format for ${resolvedPath}. The file may be corrupt.`,
+      isError: true,
+    };
+  }
+
+  const base64Data = buffer.toString("base64");
+
+  const imageBlock: ImageContent = {
+    type: "image" as const,
+    source: {
+      type: "base64" as const,
+      media_type: detectedType,
+      data: base64Data,
+    },
+  };
+
+  const sizeSuffix = optimized
+    ? ` (optimized from ${(stat.size / 1024).toFixed(0)} KB to ${(
+        buffer.length / 1024
+      ).toFixed(0)} KB)`
+    : "";
+
+  return {
+    content: `Image loaded: ${resolvedPath} (${buffer.length} bytes, ${detectedType})${sizeSuffix}`,
+    isError: false,
+    contentBlocks: [imageBlock],
+  };
+}

package/src/tools/side-effects.ts

@@ -23,8 +23,6 @@ const SIDE_EFFECT_TOOLS: ReadonlySet<string> = new Set([
   "browser_fill_credential",
   "document_create",
   "document_update",
-  "reminder_create",
-  "reminder_cancel",
   "schedule_create",
   "schedule_update",
   "schedule_delete",
@@ -35,7 +33,7 @@ const SIDE_EFFECT_TOOLS: ReadonlySet<string> = new Set([
  * (i.e. it can modify the filesystem, execute arbitrary commands, or trigger
  * external actions). Read-only and informational tools return `false`.
  *
- * For mixed-action tools (e.g. account_manage, credential_store), the optional
+ * For mixed-action tools (e.g. credential_store), the optional
  * `input` parameter is inspected to distinguish mutating actions (create,
  * update, cancel) from read-only ones (list, get).
  */
@@ -46,10 +44,6 @@ export function isSideEffectTool(
   if (SIDE_EFFECT_TOOLS.has(toolName)) return true;
 
   // Action-aware checks for mixed-action tools
-  if (toolName === "account_manage") {
-    const action = input?.action;
-    return action === "create" || action === "update";
-  }
   if (toolName === "credential_store") {
     const action = input?.action;
     return (

package/src/tools/skills/delete-managed.ts

@@ -1,73 +1,36 @@
-import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { deleteManagedSkill } from "../../skills/managed-store.js";
-import { registerTool } from "../registry.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
-
-export class DeleteManagedSkillTool implements Tool {
-  name = "delete_managed_skill";
-  description =
-    "Delete a managed skill from ~/.vellum/workspace/skills and remove it from the SKILLS.md index.";
-  category = "skills";
-  defaultRiskLevel = RiskLevel.High;
-
-  getDefinition(): ToolDefinition {
+import type { ToolContext, ToolExecutionResult } from "../types.js";
+
+/**
+ * Core execution logic for delete_managed_skill.
+ * Exported so bundled-skill executors and tests can call it directly.
+ */
+export async function executeDeleteManagedSkill(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const skillId = input.skill_id;
+  if (typeof skillId !== "string" || !skillId.trim()) {
     return {
-      name: this.name,
-      description: this.description,
-      input_schema: {
-        type: "object",
-        properties: {
-          skill_id: {
-            type: "string",
-            description: "The ID of the managed skill to delete.",
-          },
-          remove_from_index: {
-            type: "boolean",
-            description:
-              "Whether to remove the skill from SKILLS.md index (default: true).",
-          },
-          reason: {
-            type: "string",
-            description:
-              "Brief non-technical explanation of what you are deleting and why, shown to the user as a status update. Use simple language a non-technical person would understand.",
-          },
-        },
-        required: ["skill_id"],
-      },
+      content: "Error: skill_id is required and must be a non-empty string",
+      isError: true,
     };
   }
 
-  async execute(
-    input: Record<string, unknown>,
-    _context: ToolContext,
-  ): Promise<ToolExecutionResult> {
-    const skillId = input.skill_id;
-    if (typeof skillId !== "string" || !skillId.trim()) {
-      return {
-        content: "Error: skill_id is required and must be a non-empty string",
-        isError: true,
-      };
-    }
-
-    const removeFromIndex = input.remove_from_index !== false;
-
-    const result = deleteManagedSkill(skillId.trim(), removeFromIndex);
+  const removeFromIndex = input.remove_from_index !== false;
 
-    if (!result.deleted) {
-      return { content: `Error: ${result.error}`, isError: true };
-    }
+  const result = deleteManagedSkill(skillId.trim(), removeFromIndex);
 
-    return {
-      content: JSON.stringify({
-        deleted: true,
-        skill_id: skillId.trim(),
-        index_updated: result.indexUpdated,
-      }),
-      isError: false,
-    };
+  if (!result.deleted) {
+    return { content: `Error: ${result.error}`, isError: true };
   }
-}
 
-export const deleteManagedSkillTool: Tool = new DeleteManagedSkillTool();
-registerTool(deleteManagedSkillTool);
+  return {
+    content: JSON.stringify({
+      deleted: true,
+      skill_id: skillId.trim(),
+      index_updated: result.indexUpdated,
+    }),
+    isError: false,
+  };
+}

package/src/tools/skills/execute.ts

@@ -0,0 +1,54 @@
+import { RiskLevel } from "../../permissions/types.js";
+import type { ToolDefinition } from "../../providers/types.js";
+import { registerTool } from "../registry.js";
+import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+
+export class SkillExecuteTool implements Tool {
+  name = "skill_execute";
+  description =
+    "Execute a tool provided by a loaded skill. Use this instead of calling skill tools directly. The skill's instructions (from skill_load) describe available tools and their parameters.";
+  category = "skills";
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: "object",
+        properties: {
+          tool: {
+            type: "string",
+            description:
+              "The skill tool name to execute (e.g. 'browser_navigate', 'task_create')",
+          },
+          input: {
+            type: "object",
+            description:
+              "Tool-specific parameters as documented in the skill's instructions",
+          },
+          reason: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are doing and why, shown to the user as a status update.",
+          },
+        },
+        required: ["tool", "input"],
+      },
+    };
+  }
+
+  async execute(
+    _input: Record<string, unknown>,
+    _context: ToolContext,
+  ): Promise<ToolExecutionResult> {
+    return {
+      content:
+        "skill_execute should be intercepted at session level. If you see this error, the session dispatch is not configured.",
+      isError: true,
+    };
+  }
+}
+
+export const skillExecuteTool = new SkillExecuteTool();
+registerTool(skillExecuteTool);

package/src/tools/skills/load.ts

@@ -1,7 +1,10 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
 import { skillFlagKey } from "../../config/skill-state.js";
-import type { SkillSummary } from "../../config/skills.js";
+import type { SkillSummary, SkillToolManifest } from "../../config/skills.js";
 import { loadSkillBySelector, loadSkillCatalog } from "../../config/skills.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
@@ -9,6 +12,7 @@ import {
   indexCatalogById,
   validateIncludes,
 } from "../../skills/include-graph.js";
+import { parseToolManifestFile } from "../../skills/tool-manifest.js";
 import { computeSkillVersionHash } from "../../skills/version-hash.js";
 import { getLogger } from "../../util/logger.js";
 import { registerTool } from "../registry.js";
@@ -16,6 +20,87 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 const log = getLogger("skill-load");
 
+/**
+ * Attempt to load and parse TOOLS.json from a skill directory.
+ * Returns undefined if the file doesn't exist or fails to parse.
+ */
+function loadToolManifest(
+  directoryPath: string,
+): SkillToolManifest | undefined {
+  const manifestPath = join(directoryPath, "TOOLS.json");
+  if (!existsSync(manifestPath)) {
+    return undefined;
+  }
+  try {
+    return parseToolManifestFile(manifestPath);
+  } catch (err) {
+    log.warn(
+      { err, manifestPath },
+      "Failed to parse TOOLS.json for tool schema output",
+    );
+    return undefined;
+  }
+}
+
+/**
+ * Format a skill tool manifest into a human-readable "Available Tools" section
+ * that instructs the LLM to use `skill_execute` to invoke the tools.
+ *
+ * When `childSkillName` is provided, a lighter sub-heading is used instead of
+ * the full `## Available Tools` header + preamble, avoiding duplicate headers
+ * when parent and child skills both have TOOLS.json.
+ */
+function formatToolSchemas(
+  manifest: SkillToolManifest,
+  childSkillName?: string,
+): string {
+  const lines: string[] = childSkillName
+    ? [`### Tools from ${childSkillName}`, ""]
+    : [
+        "## Available Tools",
+        "",
+        "Use `skill_execute` to call these tools.",
+        "",
+      ];
+
+  const toolHeadingLevel = childSkillName ? "####" : "###";
+
+  for (const tool of manifest.tools) {
+    lines.push(`${toolHeadingLevel} ${tool.name}`);
+    lines.push(tool.description);
+
+    const schema = tool.input_schema;
+    const properties = schema.properties as
+      | Record<string, Record<string, unknown>>
+      | undefined;
+    if (properties && Object.keys(properties).length > 0) {
+      const requiredSet = new Set<string>(
+        Array.isArray(schema.required) ? (schema.required as string[]) : [],
+      );
+
+      lines.push("Parameters:");
+      for (const [paramName, paramDef] of Object.entries(properties)) {
+        const paramType =
+          typeof paramDef.type === "string" ? paramDef.type : "any";
+        const requiredLabel = requiredSet.has(paramName)
+          ? "required"
+          : "optional";
+        const descPart =
+          typeof paramDef.description === "string"
+            ? `: ${paramDef.description}`
+            : "";
+        lines.push(
+          `- ${paramName} (${paramType}, ${requiredLabel})${descPart}`,
+        );
+      }
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd();
+}
+
 export class SkillLoadTool implements Tool {
   name = "skill_load";
   description =
@@ -69,7 +154,8 @@ export class SkillLoadTool implements Tool {
 
     // Assistant feature flag gate: reject loading if the skill's flag is OFF
     const config = getConfig();
-    if (!isAssistantFeatureFlagEnabled(skillFlagKey(skill.id), config)) {
+    const flagKey = skillFlagKey(skill);
+    if (flagKey && !isAssistantFeatureFlagEnabled(flagKey, config)) {
       return {
         content: `Error: skill "${skill.id}" is currently unavailable (disabled by feature flag)`,
         isError: true,
@@ -114,15 +200,26 @@ export class SkillLoadTool implements Tool {
 
     const body = skill.body.length > 0 ? skill.body : "(No body content)";
 
+    // Load tool schemas for the main skill
+    const mainManifest = loadToolManifest(skill.directoryPath);
+    const toolSchemasSection = mainManifest
+      ? formatToolSchemas(mainManifest)
+      : undefined;
+
     // Build immediate children metadata section and load included skill bodies
     let immediateChildrenSection: string;
     const includedBodies: string[] = [];
+    let anyChildHasTools = false;
     if (skill.includes && skill.includes.length > 0 && catalogIndex) {
       const childLines: string[] = [];
       for (const childId of skill.includes) {
         const child = catalogIndex.get(childId);
         if (!child) continue;
-        if (!isAssistantFeatureFlagEnabled(skillFlagKey(childId), config))
+        const childFlagKey = skillFlagKey(child);
+        if (
+          childFlagKey &&
+          !isAssistantFeatureFlagEnabled(childFlagKey, config)
+        )
           continue;
 
         childLines.push(
@@ -135,6 +232,17 @@ export class SkillLoadTool implements Tool {
           includedBodies.push(
             `--- Included Skill: ${childLoaded.skill.displayName} (${childId}) ---\n${childLoaded.skill.body}`,
           );
+
+          // Load tool schemas for the included skill (lighter sub-heading)
+          const childManifest = loadToolManifest(
+            childLoaded.skill.directoryPath,
+          );
+          if (childManifest) {
+            anyChildHasTools = true;
+            includedBodies.push(
+              formatToolSchemas(childManifest, childLoaded.skill.displayName),
+            );
+          }
         }
       }
       immediateChildrenSection = `Included Skills (immediate):\n${childLines.join(
@@ -162,7 +270,11 @@ export class SkillLoadTool implements Tool {
       for (const childId of skill.includes) {
         const child = catalogIndex.get(childId);
         if (!child) continue;
-        if (!isAssistantFeatureFlagEnabled(skillFlagKey(childId), config))
+        const childFlagKey2 = skillFlagKey(child);
+        if (
+          childFlagKey2 &&
+          !isAssistantFeatureFlagEnabled(childFlagKey2, config)
+        )
           continue;
         let childHash: string | undefined;
         try {
@@ -189,6 +301,15 @@ export class SkillLoadTool implements Tool {
         "",
         body,
         "",
+        ...(toolSchemasSection ? [toolSchemasSection, ""] : []),
+        ...(!toolSchemasSection && anyChildHasTools
+          ? [
+              "## Available Tools",
+              "",
+              "Use `skill_execute` to call these tools.",
+              "",
+            ]
+          : []),
         ...includedBodies.flatMap((b) => [b, ""]),
         immediateChildrenSection,
         "",
@@ -200,4 +321,5 @@ export class SkillLoadTool implements Tool {
   }
 }
 
-registerTool(new SkillLoadTool());
+export const skillLoadTool = new SkillLoadTool();
+registerTool(skillLoadTool);