@vellumai/assistant 0.3.5 → 0.3.7

package/src/skills/tool-manifest.ts

@@ -9,7 +9,7 @@ const VALID_EXECUTION_TARGETS = new Set(['host', 'sandbox']);
  * Throws descriptive errors for any validation failure.
  */
 export function parseToolManifest(raw: unknown): SkillToolManifest {
-  if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) {
+  if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
     throw new Error('TOOLS.json must be a JSON object');
   }
 
@@ -54,7 +54,7 @@ export function parseToolManifest(raw: unknown): SkillToolManifest {
 }
 
 function parseToolEntry(raw: unknown, prefix: string): SkillToolEntry {
-  if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) {
+  if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) {
     throw new Error(`${prefix}: each tool entry must be a JSON object`);
   }
 
@@ -97,7 +97,7 @@ function parseToolEntry(raw: unknown, prefix: string): SkillToolEntry {
   const risk = entry.risk as SkillToolEntry['risk'];
 
   // input_schema
-  if (!('input_schema' in entry) || entry.input_schema === null || typeof entry.input_schema !== 'object' || Array.isArray(entry.input_schema)) {
+  if (!('input_schema' in entry) || entry.input_schema == null || typeof entry.input_schema !== 'object' || Array.isArray(entry.input_schema)) {
     throw new Error(`${prefix}: missing or non-object "input_schema"`);
   }
   const input_schema = entry.input_schema as Record<string, unknown>;

package/src/skills/vellum-catalog-remote.ts

@@ -1,13 +1,14 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { gunzipSync } from 'node:zlib';
 
 import type { CatalogEntry } from '../tools/skills/vellum-catalog.js';
 import { getLogger } from '../util/logger.js';
+import { readPlatformToken } from '../util/platform.js';
 
 const log = getLogger('vellum-catalog-remote');
 
-const GITHUB_RAW_BASE =
-  'https://raw.githubusercontent.com/vellum-ai/vellum-assistant/main/assistant/src/config/vellum-skills';
+const PLATFORM_URL = process.env.VELLUM_ASSISTANT_PLATFORM_URL ?? 'https://assistant.vellum.ai';
 
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 
@@ -43,7 +44,20 @@ function getBundledSkillContent(skillId: string): string | null {
   }
 }
 
-/** Fetch catalog entries (cached, async). Falls back to bundled copy. */
+/** Build request headers, including platform token when available. */
+function buildPlatformHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {};
+  const token = readPlatformToken();
+  if (token) {
+    headers['X-Session-Token'] = token;
+  }
+  return headers;
+}
+
+/**
+ * Fetch catalog entries from the platform API. Falls back to bundled copy.
+ * Reads the platform token from ~/.vellum/platform-token automatically.
+ */
 export async function fetchCatalogEntries(): Promise<CatalogEntry[]> {
   const now = Date.now();
   if (cachedEntries && now - cacheTimestamp < CACHE_TTL_MS) {
@@ -51,8 +65,9 @@ export async function fetchCatalogEntries(): Promise<CatalogEntry[]> {
   }
 
   try {
-    const url = `${GITHUB_RAW_BASE}/catalog.json`;
+    const url = `${PLATFORM_URL}/v1/skills/`;
     const response = await fetch(url, {
+      headers: buildPlatformHeaders(),
       signal: AbortSignal.timeout(5000),
     });
 
@@ -63,14 +78,14 @@ export async function fetchCatalogEntries(): Promise<CatalogEntry[]> {
     const manifest: CatalogManifest = await response.json();
     const skills = manifest.skills;
     if (!Array.isArray(skills) || skills.length === 0) {
-      throw new Error('Remote catalog has invalid or empty skills array');
+      throw new Error('Platform catalog has invalid or empty skills array');
     }
     cachedEntries = skills;
     cacheTimestamp = now;
-    log.info({ count: cachedEntries.length }, 'Fetched remote vellum-skills catalog');
+    log.info({ count: cachedEntries.length }, 'Fetched vellum-skills catalog from platform API');
     return cachedEntries;
   } catch (err) {
-    log.warn({ err }, 'Failed to fetch remote catalog, falling back to bundled copy');
+    log.warn({ err }, 'Failed to fetch catalog from platform API, falling back to bundled copy');
     const bundled = loadBundledCatalog();
     // Cache the bundled result too so we don't re-fetch on every call during outage
     cachedEntries = bundled;
@@ -79,28 +94,72 @@ export async function fetchCatalogEntries(): Promise<CatalogEntry[]> {
   }
 }
 
-/** Fetch a skill's SKILL.md content from GitHub. Falls back to bundled copy. */
+/**
+ * Extract SKILL.md content from a tar archive (uncompressed).
+ * Tar format: 512-byte header blocks followed by file data blocks.
+ */
+function extractSkillMdFromTar(tarBuffer: Buffer): string | null {
+  let offset = 0;
+  while (offset + 512 <= tarBuffer.length) {
+    const header = tarBuffer.subarray(offset, offset + 512);
+
+    // Check for end-of-archive (two consecutive zero blocks)
+    if (header.every((b) => b === 0)) break;
+
+    // Extract filename (bytes 0-99, null-terminated)
+    const nameEnd = header.indexOf(0, 0);
+    const name = header.subarray(0, Math.min(nameEnd >= 0 ? nameEnd : 100, 100)).toString('utf-8');
+
+    // Extract file size (bytes 124-135, octal string)
+    const sizeStr = header.subarray(124, 136).toString('utf-8').trim();
+    const size = parseInt(sizeStr, 8) || 0;
+
+    offset += 512; // move past header
+
+    if (name.endsWith('SKILL.md') || name === 'SKILL.md') {
+      return tarBuffer.subarray(offset, offset + size).toString('utf-8');
+    }
+
+    // Skip to next header (data blocks are padded to 512 bytes)
+    offset += Math.ceil(size / 512) * 512;
+  }
+  return null;
+}
+
+/**
+ * Fetch a skill's SKILL.md content from the platform tar API.
+ * GET /v1/skills/{skill_id}/ returns a tar.gz archive containing all skill files.
+ * Falls back to bundled copy on failure.
+ */
 export async function fetchSkillContent(skillId: string): Promise<string | null> {
   try {
-    const url = `${GITHUB_RAW_BASE}/${encodeURIComponent(skillId)}/SKILL.md`;
+    const url = `${PLATFORM_URL}/v1/skills/${encodeURIComponent(skillId)}/`;
     const response = await fetch(url, {
-      signal: AbortSignal.timeout(10000),
+      headers: buildPlatformHeaders(),
+      signal: AbortSignal.timeout(15000),
     });
 
     if (!response.ok) {
       throw new Error(`HTTP ${response.status}: ${response.statusText}`);
     }
 
-    const content = await response.text();
-    log.info({ skillId }, 'Fetched remote SKILL.md');
-    return content;
+    const gzipBuffer = Buffer.from(await response.arrayBuffer());
+    const tarBuffer = gunzipSync(gzipBuffer);
+    const skillMd = extractSkillMdFromTar(tarBuffer);
+
+    if (skillMd) {
+      return skillMd;
+    }
+
+    log.warn({ skillId }, 'SKILL.md not found in platform tar archive, falling back to bundled');
   } catch (err) {
-    log.warn({ err, skillId }, 'Failed to fetch remote SKILL.md, falling back to bundled copy');
-    return getBundledSkillContent(skillId);
+    log.warn({ err, skillId }, 'Failed to fetch skill content from platform API, falling back to bundled');
   }
+
+  return getBundledSkillContent(skillId);
 }
 
-/** Check if a skill ID exists in the remote catalog. */
+/** Check if a skill ID exists in the catalog. */
 export async function checkVellumSkill(skillId: string): Promise<boolean> {
   const entries = await fetchCatalogEntries();
   return entries.some((e) => e.id === skillId);

package/src/slack/slack-webhook.ts

@@ -1,4 +1,5 @@
 import { getLogger } from '../util/logger.js';
+import { ProviderError } from '../util/errors.js';
 
 const log = getLogger('slack-webhook');
 
@@ -56,6 +57,6 @@ export async function postToSlackWebhook(
 
   if (!response.ok) {
     const body = await response.text();
-    throw new Error(`Slack webhook returned ${response.status}: ${body}`);
+    throw new ProviderError(`Slack webhook returned ${response.status}: ${body}`, 'slack', response.status);
   }
 }

package/src/swarm/orchestrator.ts

@@ -43,6 +43,12 @@ export async function executeSwarm(opts: ExecuteSwarmOptions): Promise<SwarmExec
   const { plan, limits, backend, workingDir, model, onStatus, signal } = opts;
   const startTime = Date.now();
 
+  // Safety net: reject cyclic plans even if the caller skipped validation
+  const cyclePath = detectCycle(plan.tasks);
+  if (cyclePath) {
+    throw new Error(`Swarm plan contains a dependency cycle: ${cyclePath.join(' -> ')}`);
+  }
+
   onStatus?.({ kind: 'plan_created', message: `Plan with ${plan.tasks.length} tasks` });
 
   const results = new Map<string, SwarmTaskResult>();
@@ -128,7 +134,7 @@ export async function executeSwarm(opts: ExecuteSwarmOptions): Promise<SwarmExec
         const r = results.get(depId);
         return r ? { taskId: depId, summary: r.summary } : null;
       })
-      .filter((d): d is { taskId: string; summary: string } => d !== null);
+      .filter((d): d is { taskId: string; summary: string } => d != null);
 
     let result = await runWorkerTask({
       task,
@@ -144,6 +150,11 @@ export async function executeSwarm(opts: ExecuteSwarmOptions): Promise<SwarmExec
     let retries = 0;
     while (result.status === 'failed' && retries < limits.maxRetriesPerTask && !signal?.aborted) {
       retries++;
+      // Exponential backoff with ±25% jitter to prevent thundering herd
+      const baseDelayMs = 1000 * Math.pow(2, retries - 1);
+      const jitter = baseDelayMs * 0.25 * (2 * Math.random() - 1);
+      await abortableSleep(baseDelayMs + jitter, signal);
+      if (signal?.aborted) break;
       result = await runWorkerTask({
         task,
         upstreamContext: plan.objective,
@@ -253,6 +264,86 @@ function blockDependents(
   }
 }
 
+/**
+ * DFS-based cycle detection. Returns the cycle path (e.g. ['a', 'b', 'c', 'a'])
+ * if a cycle exists, or null if the graph is a valid DAG.
+ */
+function detectCycle(tasks: SwarmTaskNode[]): string[] | null {
+  const adj = new Map<string, string[]>();
+  for (const t of tasks) {
+    adj.set(t.id, []);
+  }
+  for (const t of tasks) {
+    for (const dep of t.dependencies) {
+      // Edge from dep -> t.id (dep must finish before t)
+      adj.get(dep)?.push(t.id);
+    }
+  }
+
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map<string, number>();
+  for (const t of tasks) color.set(t.id, WHITE);
+
+  const parent = new Map<string, string>();
+
+  // Iterative DFS to avoid stack overflow on deep acyclic chains
+  for (const t of tasks) {
+    if (color.get(t.id) !== WHITE) continue;
+
+    const stack: Array<{ node: string; neighborIdx: number }> = [
+      { node: t.id, neighborIdx: 0 },
+    ];
+    color.set(t.id, GRAY);
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const neighbors = adj.get(frame.node) ?? [];
+
+      if (frame.neighborIdx >= neighbors.length) {
+        // All neighbors visited — mark node as fully processed
+        color.set(frame.node, BLACK);
+        stack.pop();
+        continue;
+      }
+
+      const neighbor = neighbors[frame.neighborIdx];
+      frame.neighborIdx++;
+
+      if (color.get(neighbor) === GRAY) {
+        // Back edge found — reconstruct cycle path
+        const cycle = [neighbor];
+        for (let i = stack.length - 1; i >= 0; i--) {
+          cycle.push(stack[i].node);
+          if (stack[i].node === neighbor) break;
+        }
+        cycle.reverse();
+        return cycle;
+      }
+
+      if (color.get(neighbor) === WHITE) {
+        parent.set(neighbor, frame.node);
+        color.set(neighbor, GRAY);
+        stack.push({ node: neighbor, neighborIdx: 0 });
+      }
+    }
+  }
+  return null;
+}
+
+/** Resolves after `ms` milliseconds, or immediately if the signal fires first. */
+function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener('abort', done, { once: true });
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', done);
+      resolve();
+    }
+  });
+}
+
 function buildMarkdownFallback(objective: string, results: SwarmTaskResult[]): string {
   const lines: string[] = [`## Swarm Results: ${objective}`, ''];
 

package/src/swarm/router-planner.ts

@@ -1,4 +1,5 @@
 import type { Provider, Message } from '../providers/types.js';
+import { parseJsonSafe } from '../util/json.js';
 import type { SwarmPlan, SwarmTaskNode } from './types.js';
 import type { SwarmLimits } from './limits.js';
 import { validateAndNormalizePlan } from './plan-validator.js';
@@ -61,7 +62,7 @@ export function parsePlanJSON(raw: string): { tasks: Array<{ id: string; role: s
   // Try all fenced code blocks — LLMs sometimes emit non-JSON blocks before the plan
   const fencedRegex = /```(?:json)?\s*\n?([\s\S]*?)\n?```/g;
   let match;
-  while ((match = fencedRegex.exec(raw)) !== null) {
+  while ((match = fencedRegex.exec(raw)) != null) {
     const result = tryParsePlan(match[1]);
     if (result) return result;
   }
@@ -71,15 +72,11 @@ export function parsePlanJSON(raw: string): { tasks: Array<{ id: string; role: s
 }
 
 function tryParsePlan(jsonStr: string): { tasks: Array<{ id: string; role: string; objective: string; dependencies: string[] }> } | null {
-  try {
-    const parsed = JSON.parse(jsonStr.trim());
-    if (parsed && Array.isArray(parsed.tasks)) {
-      return parsed;
-    }
-    return null;
-  } catch {
-    return null;
+  const parsed = parseJsonSafe<{ tasks?: unknown }>(jsonStr.trim());
+  if (parsed && Array.isArray(parsed.tasks)) {
+    return parsed as { tasks: Array<{ id: string; role: string; objective: string; dependencies: string[] }> };
   }
+  return null;
 }
 
 /**

package/src/swarm/worker-prompts.ts

@@ -1,5 +1,6 @@
 import type { SwarmRole, SwarmTaskResult } from './types.js';
 import { truncate } from '../util/truncate.js';
+import { parseJsonSafe } from '../util/json.js';
 
 /**
  * Build a role-specific worker prompt for a swarm task.
@@ -56,18 +57,14 @@ export function parseWorkerOutput(raw: string): Pick<SwarmTaskResult, 'summary'
 
   // Walk backwards to prefer the final valid contract block.
   for (let i = jsonBlocks.length - 1; i >= 0; i--) {
-    try {
-      const parsed = JSON.parse(jsonBlocks[i][1]);
-      if (typeof parsed.summary !== 'string') continue;
-      return {
-        summary: parsed.summary,
-        artifacts: Array.isArray(parsed.artifacts) ? parsed.artifacts : [],
-        issues: Array.isArray(parsed.issues) ? parsed.issues : [],
-        nextSteps: Array.isArray(parsed.nextSteps) ? parsed.nextSteps : [],
-      };
-    } catch {
-      // Malformed JSON — try the next block up.
-    }
+    const parsed = parseJsonSafe<Record<string, unknown>>(jsonBlocks[i][1]);
+    if (!parsed || typeof parsed.summary !== 'string') continue;
+    return {
+      summary: parsed.summary,
+      artifacts: Array.isArray(parsed.artifacts) ? parsed.artifacts : [],
+      issues: Array.isArray(parsed.issues) ? parsed.issues : [],
+      nextSteps: Array.isArray(parsed.nextSteps) ? parsed.nextSteps : [],
+    };
   }
 
   return {

package/src/tasks/task-compiler.ts

@@ -4,6 +4,7 @@ import { messages as messagesTable } from '../memory/schema.js';
 import { createTask } from './task-store.js';
 import type { Task } from './task-store.js';
 import { truncate } from '../util/truncate.js';
+import { parseJsonSafe } from '../util/json.js';
 import { sanitizeToolList } from './tool-sanitizer.js';
 
 /** Output schema for the task compiler. */
@@ -91,20 +92,14 @@ export function saveCompiledTask(compiled: CompiledTask, conversationId: string)
  * string or a JSON array of Anthropic content blocks.
  */
 function extractTextContent(content: string): string {
-  try {
-    const parsed = JSON.parse(content);
-    if (Array.isArray(parsed)) {
-      return parsed
-        .filter((block: Record<string, unknown>) => block.type === 'text')
-        .map((block: Record<string, unknown>) => block.text as string)
-        .join('\n');
-    }
-    // If it parsed but isn't an array, treat as plain text
-    return content;
-  } catch {
-    // Not JSON — it's a plain text message
-    return content;
+  const parsed = parseJsonSafe(content);
+  if (Array.isArray(parsed)) {
+    return parsed
+      .filter((block: Record<string, unknown>) => block.type === 'text')
+      .map((block: Record<string, unknown>) => block.text as string)
+      .join('\n');
   }
+  return content;
 }
 
 /**
@@ -118,22 +113,18 @@ function extractToolNames(
   for (const msg of msgs) {
     if (msg.role !== 'assistant') continue;
 
-    try {
-      const parsed = JSON.parse(msg.content);
-      if (!Array.isArray(parsed)) continue;
-
-      for (const block of parsed) {
-        if (
-          block &&
-          typeof block === 'object' &&
-          block.type === 'tool_use' &&
-          typeof block.name === 'string'
-        ) {
-          tools.add(block.name);
-        }
+    const parsed = parseJsonSafe(msg.content);
+    if (!Array.isArray(parsed)) continue;
+
+    for (const block of parsed) {
+      if (
+        block &&
+        typeof block === 'object' &&
+        block.type === 'tool_use' &&
+        typeof block.name === 'string'
+      ) {
+        tools.add(block.name);
       }
-    } catch {
-      // Not JSON content — skip
     }
   }
 

package/src/tasks/task-runner.ts

@@ -25,7 +25,7 @@ export interface TaskRunResult {
 export function renderTemplate(template: string, inputs: Record<string, string>): string {
   return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
     if (key in inputs) return inputs[key];
-    return match;
+    return `<MISSING: ${key}>`;
   });
 }
 

package/src/tools/assets/search.ts

@@ -12,7 +12,7 @@ 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 { getDb } from '../../memory/db.js';
+import { getDb, rawAll } from '../../memory/db.js';
 import { attachments, messageAttachments, messages, conversations } from '../../memory/schema.js';
 import type { StoredAttachment } from '../../memory/attachments-store.js';
 import { isAttachmentVisible, type AttachmentContext } from '../../daemon/media-visibility-policy.js';
@@ -151,17 +151,16 @@ export function searchAttachments(params: AssetSearchParams): StoredAttachment[]
       .where(eq(messages.conversationId, params.conversation_id))
       .all()
       .map((r) => r.attachmentId)
-      .filter((id): id is string => id !== null);
+      .filter((id): id is string => id !== undefined);
 
     if (linkedIds.length === 0) {
       return [];
     }
 
-    // Use raw SQL IN clause for the attachment ID set
-    const raw = (db as unknown as { $client: import('bun:sqlite').Database }).$client;
     const placeholders = linkedIds.map(() => '?').join(', ');
 
-    // Build WHERE clauses for raw query
+    // Build WHERE clauses for raw query (FTS5 virtual table not involved,
+    // but dynamic IN-list with optional filters is simpler in raw SQL)
     const whereParts: string[] = [`a.id IN (${placeholders})`];
     const bindValues: (string | number)[] = [...linkedIds];
 
@@ -182,15 +181,8 @@ export function searchAttachments(params: AssetSearchParams): StoredAttachment[]
       }
     }
     const limit = Math.min(params.limit ?? DEFAULT_LIMIT, MAX_RESULTS);
-    const stmt = raw.prepare(
-      `SELECT a.id, a.original_filename, a.mime_type, a.size_bytes, a.kind, a.thumbnail_base64, a.created_at
-       FROM attachments a
-       WHERE ${whereParts.join(' AND ')}
-       ORDER BY a.created_at DESC
-       LIMIT ?`,
-    );
 
-    const rows = stmt.all(...bindValues, limit) as Array<{
+    interface AttachmentRow {
       id: string;
       original_filename: string;
       mime_type: string;
@@ -198,7 +190,16 @@ export function searchAttachments(params: AssetSearchParams): StoredAttachment[]
       kind: string;
       thumbnail_base64: string | null;
       created_at: number;
-    }>;
+    }
+
+    const rows = rawAll<AttachmentRow>(
+      `SELECT a.id, a.original_filename, a.mime_type, a.size_bytes, a.kind, a.thumbnail_base64, a.created_at
+       FROM attachments a
+       WHERE ${whereParts.join(' AND ')}
+       ORDER BY a.created_at DESC
+       LIMIT ?`,
+      ...bindValues, limit,
+    );
 
     return rows.map((r) => ({
       id: r.id,

package/src/tools/browser/__tests__/auth-detector.test.ts

@@ -37,6 +37,7 @@ function mockPage(url: string, evaluateResult: unknown = null): Page {
     keyboard: { press: async () => {} },
     mouse: { click: async () => {}, move: async () => {}, wheel: async () => {} },
     bringToFront: async () => {},
+    on: () => {},
   };
 }
 

package/src/tools/browser/auto-navigate.ts

@@ -113,6 +113,7 @@ export async function autoNavigate(
     return [];
   }
 
+  await cdp.send('Page.bringToFront').catch(() => {});
   await cdp.send('Page.enable').catch(() => {});
 
   const rootUrl = `https://${domain}/`;

package/src/tools/browser/browser-execution.ts

@@ -93,6 +93,10 @@ export async function executeBrowserNavigate(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  if (context.signal?.aborted) {
+    return { content: 'Error: operation was cancelled', isError: true };
+  }
+
   const parsedUrl = parseUrl(input.url);
   if (!parsedUrl) {
     return { content: 'Error: url is required and must be a valid HTTP(S) URL', isError: true };
@@ -316,6 +320,10 @@ export async function executeBrowserNavigate(
       if (challenge?.type === 'captcha') {
         log.info('CAPTCHA detected, waiting up to 5s for auto-resolve');
         for (let i = 0; i < 5; i++) {
+          if (context.signal?.aborted) {
+            if (sender) updateBrowserStatus(context.sessionId, sender, 'idle');
+            return { content: 'Navigation cancelled.', isError: true };
+          }
           await new Promise((r) => setTimeout(r, 1000));
           const still = await detectCaptchaChallenge(page);
           if (!still) {
@@ -797,11 +805,15 @@ export async function executeBrowserWaitFor(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  if (context.signal?.aborted) {
+    return { content: 'Error: operation was cancelled', isError: true };
+  }
+
   const selector = typeof input.selector === 'string' && input.selector ? input.selector : null;
   const text = typeof input.text === 'string' && input.text ? input.text : null;
   const duration = typeof input.duration === 'number' ? input.duration : null;
 
-  const modeCount = [selector, text, duration].filter((v) => v !== null).length;
+  const modeCount = [selector, text, duration].filter((v) => v != null).length;
   if (modeCount === 0) {
     return { content: 'Error: Exactly one of selector, text, or duration is required.', isError: true };
   }