@vellumai/assistant 0.3.0

package/src/tools/skills/load.ts

@@ -0,0 +1,139 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+import { loadSkillBySelector, loadSkillCatalog } from '../../config/skills.js';
+import type { SkillSummary } from '../../config/skills.js';
+import { indexCatalogById, validateIncludes } from '../../skills/include-graph.js';
+import { computeSkillVersionHash } from '../../skills/version-hash.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('skill-load');
+
+export class SkillLoadTool implements Tool {
+  name = 'skill_load';
+  description = 'Load full instructions for a configured skill from ~/.vellum/workspace/skills.';
+  category = 'skills';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          skill: {
+            type: 'string',
+            description: 'The skill id or skill name to load.',
+          },
+        },
+        required: ['skill'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const selector = input.skill;
+    if (typeof selector !== 'string' || selector.trim().length === 0) {
+      return { content: 'Error: skill is required and must be a non-empty string', isError: true };
+    }
+
+    const loaded = loadSkillBySelector(selector);
+    if (!loaded.skill) {
+      return { content: `Error: ${loaded.error ?? 'Failed to load skill'}`, isError: true };
+    }
+
+    const skill = loaded.skill;
+
+    // Load catalog for include validation and child metadata output
+    let catalogIndex: Map<string, SkillSummary> | undefined;
+    if (skill.includes && skill.includes.length > 0) {
+      const catalog = loadSkillCatalog();
+      catalogIndex = indexCatalogById(catalog);
+
+      // Validate recursive includes (fail-closed)
+      const validation = validateIncludes(skill.id, catalogIndex);
+      if (!validation.ok) {
+        if (validation.error === 'missing') {
+          return {
+            content: `Error: skill "${skill.id}" includes "${validation.missingChildId}" which was not found (referenced by "${validation.parentId}" via path: ${validation.path.join(' → ')})`,
+            isError: true,
+          };
+        }
+        if (validation.error === 'cycle') {
+          return {
+            content: `Error: skill "${skill.id}" has a circular include chain: ${validation.cyclePath.join(' → ')}`,
+            isError: true,
+          };
+        }
+        return {
+          content: `Error: skill "${skill.id}" has an invalid include graph`,
+          isError: true,
+        };
+      }
+    }
+
+    const body = skill.body.length > 0 ? skill.body : '(No body content)';
+
+    // Build immediate children metadata section
+    let immediateChildrenSection: string;
+    if (skill.includes && skill.includes.length > 0 && catalogIndex) {
+      const childLines: string[] = [];
+      for (const childId of skill.includes) {
+        const child = catalogIndex.get(childId);
+        if (child) {
+          childLines.push(`  - ${child.id}: ${child.name} — ${child.description} (${child.skillFilePath})`);
+        }
+      }
+      immediateChildrenSection = `Included Skills (immediate):\n${childLines.join('\n')}`;
+    } else {
+      immediateChildrenSection = 'Included Skills (immediate): none';
+    }
+
+    let versionHash: string | undefined;
+    try {
+      versionHash = computeSkillVersionHash(skill.directoryPath);
+    } catch (err) {
+      log.warn({ err, skillId: skill.id }, 'Failed to compute skill version hash for marker');
+    }
+
+    const versionAttr = versionHash ? ` version="${versionHash}"` : '';
+
+    // Emit markers for included skills so their tools get projected
+    const includeMarkers: string[] = [];
+    if (skill.includes && skill.includes.length > 0 && catalogIndex) {
+      for (const childId of skill.includes) {
+        const child = catalogIndex.get(childId);
+        if (!child) continue;
+        let childHash: string | undefined;
+        try {
+          childHash = computeSkillVersionHash(child.directoryPath);
+        } catch (err) {
+          log.warn({ err, skillId: childId }, 'Failed to compute included skill version hash');
+        }
+        const childVersionAttr = childHash ? ` version="${childHash}"` : '';
+        includeMarkers.push(`<loaded_skill id="${childId}"${childVersionAttr} />`);
+      }
+    }
+
+    return {
+      content: [
+        `Skill: ${skill.name}`,
+        `ID: ${skill.id}`,
+        `Description: ${skill.description}`,
+        `Path: ${skill.skillFilePath}`,
+        '',
+        body,
+        '',
+        immediateChildrenSection,
+        '',
+        `<loaded_skill id="${skill.id}"${versionAttr} />`,
+        ...includeMarkers,
+      ].join('\n'),
+      isError: false,
+    };
+  }
+}
+
+registerTool(new SkillLoadTool());

package/src/tools/skills/sandbox-runner.ts

@@ -0,0 +1,279 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type { ToolExecutionResult, ToolContext } from '../types.js';
+import { getConfig } from '../../config/loader.js';
+import { wrapCommand } from '../terminal/sandbox.js';
+import { buildSanitizedEnv } from '../terminal/safe-env.js';
+import { computeSkillVersionHash } from '../../skills/version-hash.js';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_CHARS = 50_000;
+
+/**
+ * Wrapper script that imports the target skill tool script, feeds it
+ * JSON input via an env var, and prints the ToolExecutionResult as JSON
+ * to stdout. This runs inside the sandbox subprocess.
+ */
+function buildRunnerSource(scriptPath: string): string {
+  return `
+const mod = await import(${JSON.stringify(scriptPath)});
+
+if (typeof mod.run !== 'function') {
+  console.log(JSON.stringify({ __skill_error: 'Script does not export a "run" function' }));
+  process.exit(1);
+}
+
+let input;
+try {
+  input = JSON.parse(process.env.__SKILL_INPUT_JSON ?? '{}');
+} catch {
+  console.log(JSON.stringify({ __skill_error: 'Invalid JSON in __SKILL_INPUT_JSON' }));
+  process.exit(1);
+}
+
+let context;
+try {
+  context = JSON.parse(process.env.__SKILL_CONTEXT_JSON ?? '{}');
+} catch {
+  context = {};
+}
+
+try {
+  const result = await mod.run(input, context);
+  console.log(JSON.stringify({ __skill_result: result }));
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  console.log(JSON.stringify({ __skill_result: { content: 'Script threw an error: ' + message, isError: true } }));
+}
+`;
+}
+
+/**
+ * Execute a skill tool script in a sandboxed subprocess.
+ *
+ * Follows the same subprocess isolation pattern used by the
+ * evaluate_typescript_code tool: writes a runner script to a temp dir,
+ * spawns it via the sandbox backend, passes input through env vars,
+ * and reads a structured JSON result from stdout.
+ */
+export async function runSkillToolScriptSandbox(
+  skillDir: string,
+  executorPath: string,
+  input: Record<string, unknown>,
+  context: ToolContext,
+  options?: {
+    timeoutMs?: number;
+    expectedSkillVersionHash?: string;
+    skillDirHashResolver?: (skillDir: string) => string;
+  },
+): Promise<ToolExecutionResult> {
+  const scriptPath = resolve(join(skillDir, executorPath));
+  const resolvedSkillDir = resolve(skillDir) + '/';
+  if (!scriptPath.startsWith(resolvedSkillDir)) {
+    return { content: `Skill tool script path "${executorPath}" escapes the skill directory`, isError: true };
+  }
+
+  // Block execution if the skill has been modified since approval.
+  if (options?.expectedSkillVersionHash) {
+    try {
+      const resolver = options.skillDirHashResolver ?? computeSkillVersionHash;
+      const currentHash = resolver(resolvedSkillDir);
+      if (currentHash !== options.expectedSkillVersionHash) {
+        return {
+          content: `Skill version mismatch: expected ${options.expectedSkillVersionHash} but current is ${currentHash}. The skill has been modified since it was approved. Please reload the skill to re-approve.`,
+          isError: true,
+        };
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        content: `Failed to verify skill version hash for "${executorPath}": ${message}`,
+        isError: true,
+      };
+    }
+  }
+
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  const runDir = join(skillDir, '.vellum-skill-run', randomUUID());
+
+  try {
+    mkdirSync(runDir, { recursive: true });
+    writeFileSync(join(runDir, '__skill_runner.ts'), buildRunnerSource(scriptPath), 'utf-8');
+
+    return await spawnRunner(runDir, input, context, timeoutMs, executorPath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: `Failed to run skill tool script "${executorPath}" in sandbox: ${message}`, isError: true };
+  } finally {
+    try {
+      rmSync(runDir, { recursive: true, force: true });
+    } catch {
+      // best effort cleanup
+    }
+  }
+}
+
+function spawnRunner(
+  runDir: string,
+  input: Record<string, unknown>,
+  context: ToolContext,
+  timeoutMs: number,
+  executorPath: string,
+): Promise<ToolExecutionResult> {
+  return new Promise<ToolExecutionResult>((resolve) => {
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    let timedOut = false;
+
+    const config = getConfig();
+    const sandboxConfig = context.sandboxOverride != null
+      ? { ...config.sandbox, enabled: context.sandboxOverride }
+      : config.sandbox;
+
+    const bunRunCmd = 'bun run __skill_runner.ts';
+    const wrapped = wrapCommand(bunRunCmd, runDir, sandboxConfig);
+
+    const env = buildSanitizedEnv();
+    env.__SKILL_INPUT_JSON = JSON.stringify(input);
+    // Pass a serializable subset of context to the subprocess
+    env.__SKILL_CONTEXT_JSON = JSON.stringify({
+      workingDir: context.workingDir,
+      sessionId: context.sessionId,
+      conversationId: context.conversationId,
+    });
+
+    const child = spawn(wrapped.command, wrapped.args, {
+      cwd: runDir,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, timeoutMs);
+
+    // Cooperative cancellation via AbortSignal
+    const onAbort = () => {
+      child.kill('SIGKILL');
+    };
+    if (context.signal) {
+      if (context.signal.aborted) {
+        child.kill('SIGKILL');
+      } else {
+        context.signal.addEventListener('abort', onAbort, { once: true });
+      }
+    }
+
+    child.stdout.on('data', (data: Buffer) => stdoutChunks.push(data));
+    child.stderr.on('data', (data: Buffer) => stderrChunks.push(data));
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      context.signal?.removeEventListener('abort', onAbort);
+
+      if (timedOut) {
+        resolve({
+          content: `Skill tool script "${executorPath}" timed out after ${timeoutMs}ms`,
+          isError: true,
+          status: 'timeout',
+        });
+        return;
+      }
+
+      const stdout = Buffer.concat(stdoutChunks).toString();
+      const stderr = Buffer.concat(stderrChunks).toString();
+
+      // Parse structured result from stdout
+      const result = parseSkillResult(stdout, executorPath);
+      if (result) {
+        resolve(result);
+        return;
+      }
+
+      // No structured result — fall back to raw output
+      if (code !== 0) {
+        const truncatedStderr = stderr.length > MAX_OUTPUT_CHARS
+          ? stderr.slice(0, MAX_OUTPUT_CHARS) + '\n[stderr truncated]'
+          : stderr;
+        resolve({
+          content: `Skill tool script "${executorPath}" exited with code ${code}:\n${truncatedStderr}`,
+          isError: true,
+        });
+        return;
+      }
+
+      const truncatedStdout = stdout.length > MAX_OUTPUT_CHARS
+        ? stdout.slice(0, MAX_OUTPUT_CHARS) + '\n[stdout truncated]'
+        : stdout;
+      resolve({ content: truncatedStdout, isError: false });
+    });
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      context.signal?.removeEventListener('abort', onAbort);
+      resolve({
+        content: `Failed to spawn skill tool script "${executorPath}": ${err.message}`,
+        isError: true,
+      });
+    });
+  });
+}
+
+/**
+ * Scan stdout for the last occurrence of our structured result marker.
+ * Uses the same backward-scanning approach as evaluate-typescript.
+ */
+function parseSkillResult(stdout: string, executorPath: string): ToolExecutionResult | null {
+  let searchFrom = stdout.length;
+  while (searchFrom > 0) {
+    const markerIdx = stdout.lastIndexOf('__skill_result', searchFrom - 1);
+    if (markerIdx === -1) break;
+
+    const lineStart = stdout.lastIndexOf('\n', markerIdx) + 1;
+    const lineEnd = stdout.indexOf('\n', markerIdx);
+    const line = stdout.slice(lineStart, lineEnd === -1 ? undefined : lineEnd);
+
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === 'object' && '__skill_result' in parsed) {
+        const result = parsed.__skill_result;
+        if (result && typeof result === 'object' && 'content' in result) {
+          return result as ToolExecutionResult;
+        }
+      }
+    } catch {
+      // malformed line — keep scanning
+    }
+    searchFrom = lineStart;
+  }
+
+  // Check for error marker
+  searchFrom = stdout.length;
+  while (searchFrom > 0) {
+    const markerIdx = stdout.lastIndexOf('__skill_error', searchFrom - 1);
+    if (markerIdx === -1) break;
+
+    const lineStart = stdout.lastIndexOf('\n', markerIdx) + 1;
+    const lineEnd = stdout.indexOf('\n', markerIdx);
+    const line = stdout.slice(lineStart, lineEnd === -1 ? undefined : lineEnd);
+
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === 'object' && '__skill_error' in parsed) {
+        return {
+          content: `Skill tool script "${executorPath}": ${parsed.__skill_error}`,
+          isError: true,
+        };
+      }
+    } catch {
+      // malformed line — keep scanning
+    }
+    searchFrom = lineStart;
+  }
+
+  return null;
+}

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

@@ -0,0 +1,150 @@
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { registerTool } from '../registry.js';
+import { createManagedSkill } from '../../skills/managed-store.js';
+
+/** Strip embedded newlines/carriage returns to prevent YAML frontmatter injection. */
+function sanitizeFrontmatterValue(value: string): string {
+  return value.replace(/[\r\n]+/g, ' ').trim();
+}
+
+export class ScaffoldManagedSkillTool implements Tool {
+  name = 'scaffold_managed_skill';
+  description = 'Create or update a managed skill in ~/.vellum/workspace/skills. The skill becomes available for skill_load immediately.';
+  category = 'skills';
+  defaultRiskLevel = RiskLevel.High;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          skill_id: {
+            type: 'string',
+            description: 'Unique identifier for the skill (lowercase slug, e.g. "my-skill").',
+          },
+          name: {
+            type: 'string',
+            description: 'Human-readable name for the skill.',
+          },
+          description: {
+            type: 'string',
+            description: 'Short description of what the skill does.',
+          },
+          body_markdown: {
+            type: 'string',
+            description: 'The full skill body in markdown — instructions, prompts, templates, etc.',
+          },
+          emoji: {
+            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).',
+          },
+          add_to_index: {
+            type: 'boolean',
+            description: 'Whether to add the skill to SKILLS.md index (default: true).',
+          },
+          includes: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Optional list of child skill IDs that this skill includes (metadata only, no auto-activation).',
+          },
+        },
+        required: ['skill_id', 'name', 'description', 'body_markdown'],
+      },
+    };
+  }
+
+  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 name = input.name;
+    if (typeof name !== 'string' || !name.trim()) {
+      return { content: 'Error: name is required and must be a non-empty string', isError: true };
+    }
+
+    const description = input.description;
+    if (typeof description !== 'string' || !description.trim()) {
+      return { content: 'Error: description is required and must be a non-empty string', isError: true };
+    }
+
+    const bodyMarkdown = input.body_markdown;
+    if (typeof bodyMarkdown !== 'string' || !bodyMarkdown.trim()) {
+      return { content: 'Error: body_markdown is required and must be a non-empty string', isError: true };
+    }
+
+    // Validate and normalize includes
+    let includes: string[] | undefined;
+    if (input.includes !== undefined) {
+      if (!Array.isArray(input.includes)) {
+        return { content: 'Error: includes must be an array of strings', isError: true };
+      }
+      for (const item of input.includes) {
+        if (typeof item !== 'string') {
+          return { content: 'Error: each element in includes must be a non-empty string', isError: true };
+        }
+        if (!item.trim()) {
+          return { content: 'Error: each element in includes must be a non-empty string', isError: true };
+        }
+      }
+      const normalized: string[] = [];
+      const seen = new Set<string>();
+      for (const item of input.includes as string[]) {
+        const trimmed = item.trim();
+        if (seen.has(trimmed)) continue;
+        seen.add(trimmed);
+        normalized.push(trimmed);
+      }
+      if (normalized.length > 0) {
+        includes = normalized;
+      }
+    }
+
+    const result = createManagedSkill({
+      id: skillId.trim(),
+      name: sanitizeFrontmatterValue(name),
+      description: sanitizeFrontmatterValue(description),
+      bodyMarkdown: bodyMarkdown,
+      emoji: typeof input.emoji === 'string' ? sanitizeFrontmatterValue(input.emoji) : undefined,
+      userInvocable: typeof input.user_invocable === 'boolean' ? input.user_invocable : undefined,
+      disableModelInvocation: typeof input.disable_model_invocation === 'boolean' ? input.disable_model_invocation : undefined,
+      overwrite: input.overwrite === true,
+      addToIndex: input.add_to_index !== false,
+      includes,
+    });
+
+    if (!result.created) {
+      return { content: `Error: ${result.error}`, isError: true };
+    }
+
+    return {
+      content: JSON.stringify({
+        created: true,
+        skill_id: skillId.trim(),
+        path: result.path,
+        index_updated: result.indexUpdated,
+      }),
+      isError: false,
+    };
+  }
+}
+
+export const scaffoldManagedSkillTool: Tool = new ScaffoldManagedSkillTool();
+registerTool(scaffoldManagedSkillTool);

package/src/tools/skills/script-contract.ts

@@ -0,0 +1,6 @@
+import type { ToolExecutionResult, ToolContext } from '../types.js';
+
+/** The exported interface a skill tool script must implement. */
+export interface SkillToolScript {
+  run(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult>;
+}

package/src/tools/skills/skill-script-runner.ts

@@ -0,0 +1,86 @@
+import type { ToolExecutionResult, ToolContext, ExecutionTarget } from '../types.js';
+import type { SkillToolScript } from './script-contract.js';
+import { join, resolve } from 'node:path';
+import { runSkillToolScriptSandbox } from './sandbox-runner.js';
+import { computeSkillVersionHash } from '../../skills/version-hash.js';
+
+export interface RunSkillToolScriptOptions {
+  /** Where to execute: 'host' runs in-process, 'sandbox' runs in an isolated subprocess. */
+  target?: ExecutionTarget;
+  /** Timeout in ms for sandbox execution. Ignored for host execution. */
+  timeoutMs?: number;
+  /** The skill version hash that was valid at approval time. When set, the runner
+   *  verifies the skill hasn't changed since the user approved it and blocks
+   *  execution on mismatch. */
+  expectedSkillVersionHash?: string;
+  /** Function to compute the current version hash for a skill directory. Defaults
+   *  to `computeSkillVersionHash` from the version-hash module. Provided as an
+   *  option to support testing and custom resolution strategies. */
+  skillDirHashResolver?: (skillDir: string) => string;
+}
+
+/**
+ * Execute a skill tool script on the host backend.
+ * Dynamically imports the script file and calls its exported `run()` function.
+ */
+export async function runSkillToolScript(
+  skillDir: string,
+  executorPath: string,
+  input: Record<string, unknown>,
+  context: ToolContext,
+  options?: RunSkillToolScriptOptions,
+): Promise<ToolExecutionResult> {
+  if (options?.target === 'sandbox') {
+    return runSkillToolScriptSandbox(skillDir, executorPath, input, context, {
+      timeoutMs: options.timeoutMs,
+      expectedSkillVersionHash: options.expectedSkillVersionHash,
+      skillDirHashResolver: options.skillDirHashResolver,
+    });
+  }
+
+  const scriptPath = resolve(join(skillDir, executorPath));
+  const resolvedSkillDir = resolve(skillDir) + '/';
+  if (!scriptPath.startsWith(resolvedSkillDir)) {
+    return { content: `Skill tool script path "${executorPath}" escapes the skill directory`, isError: true };
+  }
+
+  // Block execution if the skill has been modified since approval.
+  if (options?.expectedSkillVersionHash) {
+    const resolver = options.skillDirHashResolver ?? computeSkillVersionHash;
+    let currentHash: string;
+    try {
+      currentHash = resolver(resolvedSkillDir);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        content: `Failed to compute skill version hash for "${resolvedSkillDir}": ${message}`,
+        isError: true,
+      };
+    }
+    if (currentHash !== options.expectedSkillVersionHash) {
+      return {
+        content: `Skill version mismatch: expected ${options.expectedSkillVersionHash} but current is ${currentHash}. The skill has been modified since it was approved. Please reload the skill to re-approve.`,
+        isError: true,
+      };
+    }
+  }
+
+  let module: SkillToolScript;
+  try {
+    module = await import(scriptPath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: `Failed to load skill tool script "${executorPath}": ${message}`, isError: true };
+  }
+
+  if (typeof module.run !== 'function') {
+    return { content: `Skill tool script "${executorPath}" does not export a "run" function`, isError: true };
+  }
+
+  try {
+    return await module.run(input, context);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: `Skill tool script "${executorPath}" threw an error: ${message}`, isError: true };
+  }
+}