@vellumai/assistant 0.5.2 → 0.5.4

package/src/skills/inline-command-expansions.ts

@@ -0,0 +1,204 @@
+/**
+ * Canonical parser for inline command expansion tokens in skill bodies.
+ *
+ * Syntax: !\`command\`
+ *
+ * These tokens are parsed from the markdown body of a SKILL.md file (after
+ * frontmatter extraction). Tokens inside fenced code blocks are ignored so
+ * that documentation examples or literal snippets do not accidentally execute.
+ *
+ * The parser fails closed on malformed tokens: unmatched backticks, empty
+ * commands, or nested backticks that make the command text ambiguous are
+ * rejected rather than best-effort expanded.
+ */
+
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("inline-command-expansions");
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** A single parsed inline command expansion descriptor. */
+export interface InlineCommandExpansion {
+  /** The raw command text between the backticks (trimmed). */
+  command: string;
+  /** Byte offset of the `!` character in the original body string. */
+  startOffset: number;
+  /** Byte offset one past the closing backtick in the original body string. */
+  endOffset: number;
+  /** Stable placeholder ID derived from encounter order (0-indexed). */
+  placeholderId: number;
+}
+
+/** Result of parsing a skill body for inline command expansions. */
+export interface InlineCommandExpansionResult {
+  /** Successfully parsed expansion descriptors, in encounter order. */
+  expansions: InlineCommandExpansion[];
+  /** Malformed tokens that were rejected (fail-closed). */
+  errors: InlineCommandExpansionError[];
+}
+
+/** A malformed inline command expansion token. */
+export interface InlineCommandExpansionError {
+  /** The raw matched text that was rejected. */
+  raw: string;
+  /** Byte offset in the original body. */
+  offset: number;
+  /** Human-readable reason for rejection. */
+  reason: string;
+}
+
+// ─── Fenced code block stripping ──────────────────────────────────────────────
+
+/**
+ * Build a set of character ranges that fall inside fenced code blocks.
+ * A fenced code block starts with a line matching ``` (with optional info
+ * string) and ends with a line matching ``` (or end of string).
+ */
+function buildFencedCodeRanges(body: string): Array<[number, number]> {
+  const ranges: Array<[number, number]> = [];
+  // Match fenced code block delimiters: ``` optionally followed by info string
+  const fenceRe = /^(`{3,}|~{3,})(.*)?$/gm;
+  let openFence: { index: number; delimiter: string } | undefined;
+
+  let match: RegExpExecArray | undefined;
+  while ((match = fenceRe.exec(body) ?? undefined) !== undefined) {
+    const delimiter = match[1];
+    if (openFence === undefined) {
+      // Opening fence
+      openFence = {
+        index: match.index,
+        delimiter: delimiter[0].repeat(delimiter.length),
+      };
+    } else if (
+      delimiter[0] === openFence.delimiter[0] &&
+      delimiter.length >= openFence.delimiter.length &&
+      // Closing fence must be bare (no info string after it)
+      (!match[2] || match[2].trim() === "")
+    ) {
+      // Closing fence — range covers from opening fence to end of closing fence line
+      ranges.push([openFence.index, match.index + match[0].length]);
+      openFence = undefined;
+    }
+    // Otherwise ignore (nested fence-like lines inside a code block)
+  }
+
+  // If a fence was opened but never closed, treat everything from the opening
+  // fence to EOF as inside a code block.
+  if (openFence !== undefined) {
+    ranges.push([openFence.index, body.length]);
+  }
+
+  return ranges;
+}
+
+function isInsideFencedCode(
+  offset: number,
+  ranges: Array<[number, number]>,
+): boolean {
+  for (const [start, end] of ranges) {
+    if (offset >= start && offset < end) return true;
+  }
+  return false;
+}
+
+// ─── Parser ───────────────────────────────────────────────────────────────────
+
+/**
+ * Parse inline command expansion tokens (`!\`...\``) from a skill body.
+ *
+ * The body must be the markdown content _after_ frontmatter has been stripped.
+ * Tokens inside fenced code blocks are skipped.
+ *
+ * Returns both the successfully parsed expansions and any malformed tokens
+ * that were rejected (fail-closed).
+ */
+export function parseInlineCommandExpansions(
+  body: string,
+): InlineCommandExpansionResult {
+  const expansions: InlineCommandExpansion[] = [];
+  const errors: InlineCommandExpansionError[] = [];
+
+  const fencedRanges = buildFencedCodeRanges(body);
+
+  // Match !\`...\` tokens. The regex captures the content between the backticks.
+  // We use a non-greedy match to find the first closing backtick.
+  const tokenRe = /!\`([^`]*)\`/g;
+
+  let match: RegExpExecArray | undefined;
+  let placeholderCounter = 0;
+
+  while ((match = tokenRe.exec(body) ?? undefined) !== undefined) {
+    const startOffset = match.index;
+    const endOffset = startOffset + match[0].length;
+    const rawCommand = match[1];
+
+    // Skip tokens inside fenced code blocks
+    if (isInsideFencedCode(startOffset, fencedRanges)) {
+      continue;
+    }
+
+    // Fail closed: empty command
+    if (rawCommand.trim().length === 0) {
+      errors.push({
+        raw: match[0],
+        offset: startOffset,
+        reason: "Empty command text",
+      });
+      continue;
+    }
+
+    // Fail closed: nested backticks (would make command text ambiguous)
+    if (rawCommand.includes("`")) {
+      errors.push({
+        raw: match[0],
+        offset: startOffset,
+        reason: "Nested backticks in command text",
+      });
+      continue;
+    }
+
+    expansions.push({
+      command: rawCommand.trim(),
+      startOffset,
+      endOffset,
+      placeholderId: placeholderCounter++,
+    });
+  }
+
+  // Also detect malformed tokens: !\` without a closing backtick.
+  // These are unmatched opening tokens that didn't match the regex above.
+  const unmatchedRe = /!\`/g;
+  const matchedStarts = new Set<number>();
+  // Re-run the token regex to collect all matched positions
+  tokenRe.lastIndex = 0;
+  while ((match = tokenRe.exec(body) ?? undefined) !== undefined) {
+    matchedStarts.add(match.index);
+  }
+
+  let unmatchedMatch: RegExpExecArray | undefined;
+  while ((unmatchedMatch = unmatchedRe.exec(body) ?? undefined) !== undefined) {
+    const offset = unmatchedMatch.index;
+
+    // Skip if this was already matched as a complete token
+    if (matchedStarts.has(offset)) continue;
+
+    // Skip if inside a fenced code block
+    if (isInsideFencedCode(offset, fencedRanges)) continue;
+
+    errors.push({
+      raw: body.slice(offset, Math.min(offset + 40, body.length)),
+      offset,
+      reason: "Unmatched opening backtick (no closing backtick found)",
+    });
+  }
+
+  if (errors.length > 0) {
+    log.warn(
+      { errorCount: errors.length, errors },
+      "Malformed inline command expansion tokens detected",
+    );
+  }
+
+  return { expansions, errors };
+}

package/src/skills/inline-command-render.ts

@@ -0,0 +1,127 @@
+/**
+ * Renderer for inline command expansion tokens in skill bodies.
+ *
+ * Given a skill body and its parsed `InlineCommandExpansion` descriptors,
+ * replaces each `!\`command\`` token by executing the command through the
+ * sandbox-only runner and wrapping the result in XML tags:
+ *
+ *   <inline_skill_command index="0">...output...</inline_skill_command>
+ *
+ * Render failures produce stable inline stubs rather than dumping raw
+ * shell stderr into the prompt:
+ *
+ *   <inline_skill_command index="0">[inline command unavailable: <reason>]</inline_skill_command>
+ */
+
+import { getLogger } from "../util/logger.js";
+import type { InlineCommandExpansion } from "./inline-command-expansions.js";
+import type { InlineCommandResult } from "./inline-command-runner.js";
+import { runInlineCommand } from "./inline-command-runner.js";
+
+const log = getLogger("inline-command-render");
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** Result of rendering all inline command expansions in a skill body. */
+export interface InlineCommandRenderResult {
+  /** The body with all inline command tokens replaced. */
+  renderedBody: string;
+  /** Count of successfully expanded tokens. */
+  expandedCount: number;
+  /** Count of tokens that failed to expand (rendered as stubs). */
+  failedCount: number;
+}
+
+// ─── Failure reason mapping ───────────────────────────────────────────────────
+
+/**
+ * Map a machine-readable failure reason to a human-readable stub message
+ * suitable for inclusion in the prompt. These messages are intentionally
+ * terse and deterministic so they don't leak raw stderr or confuse the LLM.
+ */
+function failureReasonToStub(result: InlineCommandResult): string {
+  switch (result.failureReason) {
+    case "timeout":
+      return "command timed out";
+    case "non_zero_exit":
+      return "command failed";
+    case "binary_output":
+      return "command produced binary output";
+    case "spawn_failure":
+      return "command could not be started";
+    default:
+      return "unknown error";
+  }
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Render all inline command expansion tokens in a skill body.
+ *
+ * Each `!\`command\`` token is executed through the sandbox-only runner and
+ * replaced with its output wrapped in XML tags. Expansions are processed
+ * sequentially (not in parallel) to keep execution order deterministic and
+ * avoid overwhelming the sandbox.
+ *
+ * @param body  The skill body containing `!\`command\`` tokens.
+ * @param expansions  Parsed expansion descriptors from `parseInlineCommandExpansions`.
+ * @param workingDir  The conversation's working directory (repo root).
+ */
+export async function renderInlineCommands(
+  body: string,
+  expansions: InlineCommandExpansion[],
+  workingDir: string,
+): Promise<InlineCommandRenderResult> {
+  if (expansions.length === 0) {
+    return { renderedBody: body, expandedCount: 0, failedCount: 0 };
+  }
+
+  let expandedCount = 0;
+  let failedCount = 0;
+
+  // Process replacements in reverse offset order so that earlier offsets
+  // remain valid after splicing in replacement text.
+  const sorted = [...expansions].sort((a, b) => b.startOffset - a.startOffset);
+
+  let result = body;
+
+  for (const expansion of sorted) {
+    const commandResult = await runInlineCommand(expansion.command, workingDir);
+
+    let replacement: string;
+    if (commandResult.ok) {
+      replacement = wrapInXml(expansion.placeholderId, commandResult.output);
+      expandedCount++;
+    } else {
+      const stub = failureReasonToStub(commandResult);
+      replacement = wrapInXml(
+        expansion.placeholderId,
+        `[inline command unavailable: ${stub}]`,
+      );
+      failedCount++;
+      log.warn(
+        {
+          command: expansion.command,
+          placeholderId: expansion.placeholderId,
+          failureReason: commandResult.failureReason,
+        },
+        "Inline command expansion failed, rendering stub",
+      );
+    }
+
+    // Replace the original token with the rendered output
+    result =
+      result.slice(0, expansion.startOffset) +
+      replacement +
+      result.slice(expansion.endOffset);
+  }
+
+  return { renderedBody: result, expandedCount, failedCount };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function wrapInXml(index: number, content: string): string {
+  return `<inline_skill_command index="${index}">${content}</inline_skill_command>`;
+}

package/src/skills/inline-command-runner.ts

@@ -0,0 +1,242 @@
+/**
+ * Sandbox-only runner for inline command expansions (`!\`command\``).
+ *
+ * Executes the literal command string in the sandbox without going through the
+ * general `bash` tool's permission path. Security constraints:
+ *
+ * - Network mode forced off (no outbound connections)
+ * - Sanitized environment variables only (no API keys, tokens, credentials)
+ * - No credential proxy, no CES client, no host fallback
+ * - Uses the conversation working directory as `cwd` so repo-local commands
+ *   remain interoperable with externally authored skills that expect project
+ *   context.
+ *
+ * Output handling:
+ * - Captures stdout only (stderr is discarded)
+ * - Strips ANSI escape sequences
+ * - Rejects binary-ish output
+ * - Clamps output to a fixed cap
+ * - Returns deterministic sanitized error results for timeout, non-zero exit,
+ *   or spawn failures (no raw stderr dumps)
+ */
+
+import { spawn } from "node:child_process";
+
+import { getConfig } from "../config/loader.js";
+import { buildSanitizedEnv } from "../tools/terminal/safe-env.js";
+import { wrapCommand } from "../tools/terminal/sandbox.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("inline-command-runner");
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Maximum wall-clock time for an inline command before it is killed. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** Maximum output characters before truncation. */
+const MAX_OUTPUT_CHARS = 20_000;
+
+/**
+ * ANSI escape sequence pattern (covers SGR, cursor movement, erase, etc.).
+ * Matches: ESC[ ... final_byte  and  ESC] ... ST  (OSC sequences).
+ */
+const ANSI_RE = /\x1b\[[0-9;]*[A-Za-z]|\x1b\][^\x07]*(?:\x07|\x1b\\)/g;
+
+/**
+ * Heuristic for binary output: if more than 10% of the characters are
+ * non-printable (control chars excluding \t, \n, \r) then reject.
+ */
+const BINARY_THRESHOLD = 0.1;
+
+// ─── Result type ─────────────────────────────────────────────────────────────
+
+/** Deterministic result shape returned by the inline command runner. */
+export interface InlineCommandResult {
+  /** The sanitized stdout output, or a human-readable error description. */
+  output: string;
+  /** Whether the command completed successfully. */
+  ok: boolean;
+  /**
+   * Machine-readable failure reason.
+   * - `"timeout"` — command exceeded the wall-clock limit
+   * - `"non_zero_exit"` — command exited with a non-zero code
+   * - `"binary_output"` — stdout contained binary-ish data
+   * - `"spawn_failure"` — the subprocess could not be spawned
+   * - `undefined` — success
+   */
+  failureReason?:
+    | "timeout"
+    | "non_zero_exit"
+    | "binary_output"
+    | "spawn_failure";
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export interface InlineCommandRunnerOptions {
+  /** Override the default timeout (ms). */
+  timeoutMs?: number;
+  /** Override the default output cap (chars). */
+  maxOutputChars?: number;
+}
+
+/**
+ * Run an inline command expansion in the sandbox.
+ *
+ * @param command  The literal command string from the `!\`...\`` token.
+ * @param workingDir  The conversation's working directory (repo root).
+ * @param options  Optional overrides for timeout and output cap.
+ */
+export async function runInlineCommand(
+  command: string,
+  workingDir: string,
+  options?: InlineCommandRunnerOptions,
+): Promise<InlineCommandResult> {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxChars = options?.maxOutputChars ?? MAX_OUTPUT_CHARS;
+
+  // Build sandbox-wrapped command. Always use the sandbox config with
+  // network forced off — inline commands never need network access.
+  const config = getConfig();
+  const sandboxConfig = { ...config.sandbox, enabled: true };
+
+  const wrapped = wrapCommand(command, workingDir, sandboxConfig, {
+    networkMode: "off",
+  });
+
+  // Build a minimal, sanitized environment. Explicitly exclude gateway URL,
+  // workspace dir, and data dir since inline commands have no business calling
+  // internal APIs, mutating workspace state, or accessing instance-scoped data.
+  const env = buildSanitizedEnv();
+  delete env.INTERNAL_GATEWAY_BASE_URL;
+  delete env.VELLUM_WORKSPACE_DIR;
+  delete env.VELLUM_DATA_DIR;
+
+  return new Promise<InlineCommandResult>((resolve) => {
+    let timedOut = false;
+    const stdoutChunks: Buffer[] = [];
+
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(wrapped.command, wrapped.args, {
+        cwd: workingDir,
+        env,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn({ command, error: message }, "Failed to spawn inline command");
+      resolve({
+        output: "Inline command could not be started.",
+        ok: false,
+        failureReason: "spawn_failure",
+      });
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+
+    child.stdout!.on("data", (data: Buffer) => stdoutChunks.push(data));
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+
+      // ── Timeout ──────────────────────────────────────────────────────
+      if (timedOut) {
+        log.debug({ command, timeoutMs }, "Inline command timed out");
+        resolve({
+          output: `Inline command timed out after ${timeoutMs}ms.`,
+          ok: false,
+          failureReason: "timeout",
+        });
+        return;
+      }
+
+      // ── Non-zero exit ────────────────────────────────────────────────
+      if (code !== 0) {
+        log.debug(
+          { command, exitCode: code },
+          "Inline command exited with non-zero code",
+        );
+        resolve({
+          output: `Inline command failed (exit code ${code}).`,
+          ok: false,
+          failureReason: "non_zero_exit",
+        });
+        return;
+      }
+
+      // ── Process stdout ───────────────────────────────────────────────
+      const raw = Buffer.concat(stdoutChunks).toString("utf-8");
+
+      // Strip ANSI sequences first — these are terminal artifacts, not
+      // binary data. Stripping before the binary check prevents legitimate
+      // color-coded tool output from being rejected.
+      let cleaned = raw.replace(ANSI_RE, "");
+
+      // Reject binary-ish output (after ANSI stripping)
+      if (isBinaryish(cleaned)) {
+        log.debug({ command }, "Inline command produced binary-ish output");
+        resolve({
+          output: "Inline command produced binary output.",
+          ok: false,
+          failureReason: "binary_output",
+        });
+        return;
+      }
+
+      // Clamp to max output
+      if (cleaned.length > maxChars) {
+        cleaned = cleaned.slice(0, maxChars) + "\n[output truncated]";
+      }
+
+      // Trim trailing whitespace
+      cleaned = cleaned.trimEnd();
+
+      resolve({
+        output: cleaned,
+        ok: true,
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      log.warn({ command, error: err.message }, "Inline command spawn error");
+      resolve({
+        output: "Inline command could not be started.",
+        ok: false,
+        failureReason: "spawn_failure",
+      });
+    });
+  });
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Heuristic check for binary output. Returns true if more than
+ * {@link BINARY_THRESHOLD} of the characters are non-printable control
+ * characters (excluding tab, newline, carriage return).
+ */
+function isBinaryish(text: string): boolean {
+  if (text.length === 0) return false;
+
+  let controlCount = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    // Control characters: 0x00-0x1F (excluding \t=0x09, \n=0x0A, \r=0x0D)
+    // and 0x7F (DEL)
+    if (
+      (code <= 0x1f && code !== 0x09 && code !== 0x0a && code !== 0x0d) ||
+      code === 0x7f
+    ) {
+      controlCount++;
+    }
+  }
+
+  return controlCount / text.length > BINARY_THRESHOLD;
+}

package/src/skills/transitive-version-hash.ts

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+
+import type { SkillSummary } from "../config/skills.js";
+import { validateIncludes } from "./include-graph.js";
+import { computeSkillVersionHash } from "./version-hash.js";
+
+/**
+ * Error thrown when the include graph is invalid (missing nodes or cycles).
+ * The permission layer depends on exact approval candidates, so we fail closed
+ * rather than returning a partial or potentially misleading hash.
+ */
+export class TransitiveHashError extends Error {
+  constructor(
+    message: string,
+    public readonly code: "missing" | "cycle",
+  ) {
+    super(message);
+    this.name = "TransitiveHashError";
+  }
+}
+
+/**
+ * Compute a transitive version hash for a skill and all its included children.
+ *
+ * The hash covers:
+ * 1. The DFS-ordered list of visited skill IDs (so the graph structure matters)
+ * 2. Each visited skill's directory hash (via `computeSkillVersionHash`)
+ *
+ * This means editing any included child skill invalidates the parent's
+ * transitive hash, which is required for version-pinned inline-command
+ * approval.
+ *
+ * Fails closed (throws `TransitiveHashError`) when:
+ * - A child referenced in `includes` is missing from the catalog index
+ * - The include graph contains a cycle
+ *
+ * @param rootSkillId  The skill ID to start traversal from.
+ * @param catalogIndex A `Map<skillId, SkillSummary>` built via `indexCatalogById`.
+ * @returns A canonical hash string in the format `tv1:<hex-sha256>`.
+ */
+export function computeTransitiveSkillVersionHash(
+  rootSkillId: string,
+  catalogIndex: Map<string, SkillSummary>,
+): string {
+  // Validate the include graph first — fail closed on any issue.
+  const validation = validateIncludes(rootSkillId, catalogIndex);
+
+  if (!validation.ok) {
+    if (validation.error === "cycle") {
+      throw new TransitiveHashError(
+        `Cycle detected in include graph: ${validation.cyclePath.join(" -> ")}`,
+        "cycle",
+      );
+    }
+    // validation.error === "missing"
+    throw new TransitiveHashError(
+      `Missing child skill "${validation.missingChildId}" referenced by "${validation.parentId}" (path: ${validation.path.join(" -> ")})`,
+      "missing",
+    );
+  }
+
+  // validation.ok === true, so visited contains all skill IDs in DFS pre-order.
+  const { visited } = validation;
+
+  const hash = createHash("sha256");
+
+  for (const skillId of visited) {
+    // Fold the skill ID into the digest so graph structure matters.
+    hash.update(skillId);
+    hash.update("\0");
+
+    const skill = catalogIndex.get(skillId);
+    if (!skill) {
+      // Should be unreachable after validateIncludes succeeds, but fail closed.
+      throw new TransitiveHashError(
+        `Skill "${skillId}" disappeared from catalog index after validation`,
+        "missing",
+      );
+    }
+
+    // Fold the per-directory content hash so file changes propagate.
+    const dirHash = computeSkillVersionHash(skill.directoryPath);
+    hash.update(dirHash);
+    hash.update("\n");
+  }
+
+  return `tv1:${hash.digest("hex")}`;
+}