@vellumai/assistant 0.3.0

package/src/tools/shared/filesystem/file-ops-service.ts

@@ -0,0 +1,215 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import type { PathResult, PathFailureReason } from './path-policy.js';
+import { checkFileSizeOnDisk, checkContentSize } from './size-guard.js';
+import { applyEdit } from './edit-engine.js';
+import type {
+  ReadInput, ReadResult,
+  WriteInput, WriteResult,
+  EditInput, EditResult,
+} from './types.js';
+import * as Err from './errors.js';
+
+// ---------------------------------------------------------------------------
+// Path policy hook
+// ---------------------------------------------------------------------------
+
+/**
+ * A function that validates a raw path and returns a resolved absolute path
+ * or an error string. Both sandbox and host policies satisfy this shape.
+ */
+export type PathPolicy = (
+  rawPath: string,
+  options?: { mustExist?: boolean },
+) => PathResult;
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+function pathError(path: string, reason: PathFailureReason, detail: string): Err.FsError {
+  switch (reason) {
+    case 'not_absolute': return Err.pathNotAbsolute(path);
+    case 'out_of_bounds': return { code: 'PATH_OUT_OF_BOUNDS', message: detail, path };
+  }
+}
+
+export class FileSystemOps {
+  private policy: PathPolicy;
+  private sizeLimit: number | undefined;
+
+  constructor(policy: PathPolicy, options?: { sizeLimit?: number }) {
+    this.policy = policy;
+    this.sizeLimit = options?.sizeLimit;
+  }
+
+  // -------------------------------------------------------------------------
+  // Read
+  // -------------------------------------------------------------------------
+
+  readFileSafe(input: ReadInput): ReadResult {
+    const pathCheck = this.policy(input.path, { mustExist: true });
+    if (!pathCheck.ok) {
+      return { ok: false, error: pathError(input.path, pathCheck.reason, pathCheck.error) };
+    }
+    const filePath = pathCheck.resolved;
+
+    if (!existsSync(filePath)) {
+      return { ok: false, error: Err.notFound(filePath) };
+    }
+
+    const stat = statSync(filePath);
+    if (!stat.isFile()) {
+      return { ok: false, error: Err.notAFile(filePath) };
+    }
+
+    const sizeErr = checkFileSizeOnDisk(filePath, this.sizeLimit);
+    if (sizeErr) {
+      return { ok: false, error: Err.sizeLimitExceeded(filePath, sizeErr) };
+    }
+
+    try {
+      const raw = readFileSync(filePath, 'utf-8');
+      const lines = raw.split('\n');
+
+      const offset = (input.offset ?? 1) - 1;
+      const limit = input.limit ?? lines.length;
+      const selected = lines.slice(Math.max(0, offset), offset + limit);
+
+      const numbered = selected
+        .map((line, i) => {
+          const lineNum = offset + i + 1;
+          return `${String(lineNum).padStart(6)}  ${line}`;
+        })
+        .join('\n');
+
+      return { ok: true, value: { content: numbered } };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { ok: false, error: Err.ioError(filePath, msg) };
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Write
+  // -------------------------------------------------------------------------
+
+  writeFileSafe(input: WriteInput): WriteResult {
+    const pathCheck = this.policy(input.path, { mustExist: false });
+    if (!pathCheck.ok) {
+      return { ok: false, error: pathError(input.path, pathCheck.reason, pathCheck.error) };
+    }
+    const filePath = pathCheck.resolved;
+
+    const sizeErr = checkContentSize(input.content, filePath, this.sizeLimit);
+    if (sizeErr) {
+      return { ok: false, error: Err.sizeLimitExceeded(filePath, sizeErr) };
+    }
+
+    try {
+      const dir = dirname(filePath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+
+      let oldContent = '';
+      const isNewFile = !existsSync(filePath);
+      if (!isNewFile) {
+        try {
+          oldContent = readFileSync(filePath, 'utf-8');
+        } catch {
+          // Unreadable existing file — keep oldContent as empty string.
+        }
+      }
+
+      writeFileSync(filePath, input.content);
+
+      return {
+        ok: true,
+        value: {
+          filePath,
+          isNewFile,
+          oldContent,
+          newContent: input.content,
+        },
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { ok: false, error: Err.ioError(filePath, msg) };
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Edit
+  // -------------------------------------------------------------------------
+
+  editFileSafe(input: EditInput): EditResult {
+    const pathCheck = this.policy(input.path, { mustExist: true });
+    if (!pathCheck.ok) {
+      return { ok: false, error: pathError(input.path, pathCheck.reason, pathCheck.error) };
+    }
+    const filePath = pathCheck.resolved;
+
+    // Size-check the file on disk (swallow ENOENT — readFileSync gives a clearer error)
+    try {
+      const sizeErr = checkFileSizeOnDisk(filePath, this.sizeLimit);
+      if (sizeErr) {
+        return { ok: false, error: Err.sizeLimitExceeded(filePath, sizeErr) };
+      }
+    } catch {
+      // Fall through — the readFileSync below will surface NOT_FOUND.
+    }
+
+    let content: string;
+    try {
+      content = readFileSync(filePath, 'utf-8');
+    } catch (err) {
+      const code = err instanceof Error && 'code' in err
+        ? (err as NodeJS.ErrnoException).code
+        : undefined;
+      if (code === 'EISDIR') {
+        return { ok: false, error: Err.notAFile(filePath) };
+      }
+      if (code === 'ENOENT') {
+        return { ok: false, error: Err.notFound(filePath) };
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      return { ok: false, error: Err.ioError(filePath, msg) };
+    }
+
+    if (input.oldString.length === 0) {
+      return { ok: false, error: Err.matchNotFound(filePath) };
+    }
+
+    const result = applyEdit(content, input.oldString, input.newString, input.replaceAll);
+
+    if (!result.ok) {
+      if (result.reason === 'not_found') {
+        return { ok: false, error: Err.matchNotFound(filePath) };
+      }
+      return { ok: false, error: Err.matchAmbiguous(filePath, result.matchCount) };
+    }
+
+    try {
+      writeFileSync(filePath, result.updatedContent);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { ok: false, error: Err.ioError(filePath, msg) };
+    }
+
+    return {
+      ok: true,
+      value: {
+        filePath,
+        matchCount: result.matchCount,
+        oldContent: content,
+        newContent: result.updatedContent,
+        matchMethod: result.matchMethod,
+        similarity: result.similarity,
+        actualOld: result.actualOld,
+        actualNew: result.actualNew,
+      },
+    };
+  }
+}

package/src/tools/shared/filesystem/format-diff.ts

@@ -0,0 +1,35 @@
+const MAX_DIFF_LINES = 8;
+
+/**
+ * Build a compact inline diff from an old→new string replacement.
+ * Lines are prefixed with - / + and truncated if the change is large.
+ */
+export function formatEditDiff(oldString: string, newString: string): string {
+  const removed = oldString.length > 0
+    ? truncateLines(oldString.split('\n'), MAX_DIFF_LINES).map(l => `- ${l}`)
+    : [];
+  const added = newString.length > 0
+    ? truncateLines(newString.split('\n'), MAX_DIFF_LINES).map(l => `+ ${l}`)
+    : [];
+
+  return [...removed, ...added].join('\n');
+}
+
+/**
+ * Build a one-line summary for a file write.
+ */
+export function formatWriteSummary(oldContent: string, newContent: string, isNewFile: boolean): string {
+  const newLineCount = newContent.split('\n').length;
+  if (isNewFile) {
+    return `(new file, ${newLineCount} line${newLineCount !== 1 ? 's' : ''})`;
+  }
+  const oldLineCount = oldContent.split('\n').length;
+  return `(${oldLineCount} → ${newLineCount} lines)`;
+}
+
+function truncateLines(lines: string[], max: number): string[] {
+  if (lines.length <= max) return lines;
+  const kept = lines.slice(0, max);
+  kept.push(`... (${lines.length - max} more lines)`);
+  return kept;
+}

package/src/tools/shared/filesystem/path-policy.ts

@@ -0,0 +1,125 @@
+import { resolve, relative, dirname, basename, join, isAbsolute } from 'node:path';
+import { realpathSync } from 'node:fs';
+
+/**
+ * Result type shared by both sandbox and host path policies.
+ */
+export type PathFailureReason = 'not_absolute' | 'out_of_bounds';
+
+export type PathResult =
+  | { ok: true; resolved: string }
+  | { ok: false; reason: PathFailureReason; error: string };
+
+// The Docker sandbox mounts the host workspace at /workspace inside the
+// container. The model generates container-scoped paths (e.g.
+// "/workspace/scratch/file.png") that need to be remapped to the host
+// boundary directory before validation.
+const CONTAINER_WORKSPACE_PREFIX = '/workspace/';
+const CONTAINER_WORKSPACE_EXACT = '/workspace';
+
+// ---------------------------------------------------------------------------
+// Sandbox policy
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a user-supplied path against a boundary directory and verify
+ * that the result stays within it.
+ *
+ * For existing paths, symlinks are resolved via realpathSync so a symlink
+ * pointing outside the boundary is caught. For new paths (e.g. file_write),
+ * pass `mustExist: false` — the nearest existing ancestor directory is
+ * resolved via realpathSync to catch symlinks in parent dirs.
+ *
+ * Paths starting with `/workspace/` are treated as container-scoped and
+ * remapped relative to the boundary directory (the Docker sandbox mounts
+ * the host workspace at /workspace).
+ */
+export function sandboxPolicy(
+  rawPath: string,
+  boundaryDir: string,
+  options?: { mustExist?: boolean },
+): PathResult {
+  const mustExist = options?.mustExist ?? true;
+
+  // Remap container-scoped /workspace paths to the host boundary dir.
+  // Skip remapping if the path already starts with boundaryDir to avoid
+  // double-nesting (e.g. /workspace/project/file.ts → /workspace/project/project/file.ts
+  // when boundaryDir is /workspace/project).
+  let effectivePath = rawPath;
+  if (
+    !rawPath.startsWith(boundaryDir + '/') &&
+    rawPath !== boundaryDir
+  ) {
+    if (rawPath.startsWith(CONTAINER_WORKSPACE_PREFIX)) {
+      effectivePath = rawPath.slice(CONTAINER_WORKSPACE_PREFIX.length);
+    } else if (rawPath === CONTAINER_WORKSPACE_EXACT) {
+      effectivePath = '.';
+    }
+  }
+
+  const resolved = resolve(boundaryDir, effectivePath);
+
+  // Resolve symlinks to catch symlink-based escapes.
+  // For mustExist=false, walk up to the nearest existing ancestor and
+  // resolve it, then re-append the trailing components.
+  let realResolved = resolved;
+  if (mustExist) {
+    try {
+      realResolved = realpathSync(resolved);
+    } catch {
+      // File doesn't exist — will be caught by the tool's own existence check
+      realResolved = resolved;
+    }
+  } else {
+    let current = resolved;
+    const trailing: string[] = [];
+    while (current !== dirname(current)) {
+      try {
+        const real = realpathSync(current);
+        realResolved = trailing.length > 0 ? join(real, ...trailing) : real;
+        break;
+      } catch {
+        trailing.unshift(basename(current));
+        current = dirname(current);
+      }
+    }
+  }
+
+  // Resolve the boundary directory's real path too (in case it's a symlink)
+  let realBoundary: string;
+  try {
+    realBoundary = realpathSync(boundaryDir);
+  } catch {
+    realBoundary = boundaryDir;
+  }
+
+  const rel = relative(realBoundary, realResolved);
+  if (rel.startsWith('..') || resolve(realBoundary, rel) !== realResolved) {
+    return {
+      ok: false,
+      reason: 'out_of_bounds',
+      error: `Path "${rawPath}" resolves to "${realResolved}" which is outside the working directory "${realBoundary}"`,
+    };
+  }
+
+  return { ok: true, resolved };
+}
+
+// ---------------------------------------------------------------------------
+// Host policy
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a path for host filesystem access.
+ * Only requirement: the path must be absolute. No sandbox boundary check.
+ */
+export function hostPolicy(rawPath: string): PathResult {
+  if (!isAbsolute(rawPath)) {
+    return {
+      ok: false,
+      reason: 'not_absolute',
+      error: `path must be absolute for host file access: ${rawPath}`,
+    };
+  }
+  return { ok: true, resolved: rawPath };
+}

package/src/tools/shared/filesystem/size-guard.ts

@@ -0,0 +1,41 @@
+import { statSync } from 'node:fs';
+
+/** Default maximum file size: 100 MB */
+export const MAX_FILE_SIZE_BYTES = 100 * 1024 * 1024;
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Check whether a file on disk exceeds the size limit.
+ * Returns an error string if the file is too large, or undefined if OK.
+ */
+export function checkFileSizeOnDisk(
+  filePath: string,
+  limit: number = MAX_FILE_SIZE_BYTES,
+): string | undefined {
+  const stat = statSync(filePath);
+  if (stat.size > limit) {
+    return `File size (${formatBytes(stat.size)}) exceeds the ${formatBytes(limit)} limit: ${filePath}`;
+  }
+  return undefined;
+}
+
+/**
+ * Check whether content to be written exceeds the size limit.
+ * Returns an error string if the content is too large, or undefined if OK.
+ */
+export function checkContentSize(
+  content: string,
+  filePath: string,
+  limit: number = MAX_FILE_SIZE_BYTES,
+): string | undefined {
+  const size = Buffer.byteLength(content, 'utf-8');
+  if (size > limit) {
+    return `Content size (${formatBytes(size)}) exceeds the ${formatBytes(limit)} limit for: ${filePath}`;
+  }
+  return undefined;
+}

package/src/tools/shared/filesystem/types.ts

@@ -0,0 +1,80 @@
+import type { FsError } from './errors.js';
+
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+
+export interface ReadInput {
+  path: string;
+  /** 1-indexed line number to start reading from. */
+  offset?: number;
+  /** Maximum number of lines to read. */
+  limit?: number;
+}
+
+export interface ReadOutput {
+  /** The (possibly line-numbered) file content. */
+  content: string;
+}
+
+export type ReadResult =
+  | { ok: true; value: ReadOutput }
+  | { ok: false; error: FsError };
+
+// ---------------------------------------------------------------------------
+// Write
+// ---------------------------------------------------------------------------
+
+export interface WriteInput {
+  path: string;
+  content: string;
+}
+
+export interface WriteOutput {
+  /** Absolute path that was written to. */
+  filePath: string;
+  /** True when the file did not exist before this write. */
+  isNewFile: boolean;
+  /** Previous content (empty string for new files or unreadable files). */
+  oldContent: string;
+  /** The content that was written. */
+  newContent: string;
+}
+
+export type WriteResult =
+  | { ok: true; value: WriteOutput }
+  | { ok: false; error: FsError };
+
+// ---------------------------------------------------------------------------
+// Edit
+// ---------------------------------------------------------------------------
+
+export interface EditInput {
+  path: string;
+  oldString: string;
+  newString: string;
+  replaceAll: boolean;
+}
+
+export interface EditOutput {
+  /** Absolute path that was edited. */
+  filePath: string;
+  /** Number of replacements made. */
+  matchCount: number;
+  /** File content before the edit. */
+  oldContent: string;
+  /** File content after the edit. */
+  newContent: string;
+  /** How the match was found (exact, whitespace-normalized, or fuzzy). */
+  matchMethod: 'exact' | 'whitespace' | 'fuzzy';
+  /** Match similarity score (0–1). Always 1 for exact/whitespace, <1 for fuzzy. */
+  similarity: number;
+  /** The text that was actually matched in the file (may differ from the requested old_string for fuzzy/whitespace matches). */
+  actualOld: string;
+  /** The replacement text actually written (may have adjusted indentation for non-exact matches). */
+  actualNew: string;
+}
+
+export type EditResult =
+  | { ok: true; value: EditOutput }
+  | { ok: false; error: FsError };

package/src/tools/shared/shell-output.ts

@@ -0,0 +1,52 @@
+export const MAX_OUTPUT_LENGTH = 50_000;
+
+export interface ShellOutputResult {
+  content: string;
+  status: string | undefined;
+  isError: boolean;
+}
+
+/**
+ * Format the raw stdout/stderr/exit-code from a spawned shell command into the
+ * final tool result.  Both `shell.ts` (sandbox bash) and `host-shell.ts`
+ * (host_bash) must produce identical output formatting — this shared function
+ * is the single source of truth for that logic.
+ */
+export function formatShellOutput(
+  stdout: string,
+  stderr: string,
+  code: number | null,
+  timedOut: boolean,
+  timeoutSec: number,
+): ShellOutputResult {
+  let output = stdout;
+  if (stderr) {
+    output += (output ? '\n' : '') + stderr;
+  }
+
+  const statusParts: string[] = [];
+
+  if (timedOut) {
+    const msg = `<command_timeout seconds="${timeoutSec}" />`;
+    output += `\n${msg}`;
+    statusParts.push(msg);
+  }
+
+  if (output.length > MAX_OUTPUT_LENGTH) {
+    const msg = '<output_truncated limit="50K" />';
+    output = output.slice(0, MAX_OUTPUT_LENGTH) + `\n${msg}`;
+    statusParts.push(msg);
+  }
+
+  if (!output.trim()) {
+    output = code === 0 ? '<command_completed />' : `<command_exit code="${code}" />`;
+  } else if (code !== 0 && !timedOut) {
+    statusParts.push(`<command_exit code="${code}" />`);
+  }
+
+  return {
+    content: output,
+    status: statusParts.length > 0 ? statusParts.join('\n') : undefined,
+    isError: code !== 0 || timedOut,
+  };
+}

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

@@ -0,0 +1,60 @@
+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 { deleteManagedSkill } from '../../skills/managed-store.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 {
+    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).',
+          },
+        },
+        required: ['skill_id'],
+      },
+    };
+  }
+
+  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);
+
+    if (!result.deleted) {
+      return { content: `Error: ${result.error}`, isError: true };
+    }
+
+    return {
+      content: JSON.stringify({
+        deleted: true,
+        skill_id: skillId.trim(),
+        index_updated: result.indexUpdated,
+      }),
+      isError: false,
+    };
+  }
+}
+
+export const deleteManagedSkillTool: Tool = new DeleteManagedSkillTool();
+registerTool(deleteManagedSkillTool);