@vellumai/assistant 0.3.3 → 0.3.5

package/src/runtime/routes/run-routes.ts

@@ -5,6 +5,7 @@ import { getOrCreateConversation } from '../../memory/conversation-key-store.js'
 import * as attachmentsStore from '../../memory/attachments-store.js';
 import * as runsStore from '../../memory/runs-store.js';
 import { addRule } from '../../permissions/trust-store.js';
+import { getTool } from '../../tools/registry.js';
 import { getLogger } from '../../util/logger.js';
 import type { RunOrchestrator } from '../run-orchestrator.js';
 
@@ -200,8 +201,13 @@ export async function handleAddTrustRule(
   }
 
   try {
+    // Only persist executionTarget for skill-origin tools — core tools don't
+    // set it in their PolicyContext, so a persisted value would prevent the
+    // rule from ever matching on subsequent permission checks.
+    const tool = getTool(confirmation.toolName);
+    const executionTarget = tool?.origin === 'skill' ? confirmation.executionTarget : undefined;
     addRule(confirmation.toolName, pattern, scope, decision, undefined, {
-      executionTarget: confirmation.executionTarget,
+      executionTarget,
     });
     log.info(
       { tool: confirmation.toolName, pattern, scope, decision, runId },

package/src/runtime/run-orchestrator.ts

@@ -18,6 +18,7 @@ import type { Run } from '../memory/runs-store.js';
 import type { Session } from '../daemon/session.js';
 import type { ServerMessage } from '../daemon/ipc-protocol.js';
 import { resolveChannelCapabilities } from '../daemon/session-runtime-assembly.js';
+import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.js';
 import type { UserDecision } from '../permissions/types.js';
 import { checkIngressForSecrets } from '../security/secret-ingress.js';
 import { IngressBlockedError } from '../util/errors.js';
@@ -37,7 +38,11 @@ interface PendingRunState {
 }
 
 export interface RunOrchestratorDeps {
-  getOrCreateSession: (conversationId: string) => Promise<Session>;
+  getOrCreateSession: (conversationId: string, transport?: {
+    channelId: string;
+    hints?: string[];
+    uxBrief?: string;
+  }) => Promise<Session>;
   resolveAttachments: (attachmentIds: string[]) => Array<{
     id: string;
     filename: string;
@@ -67,6 +72,20 @@ export interface RunStartOptions {
    * default 'http-api'.
    */
   sourceChannel?: string;
+  /**
+   * Transport hints from sourceMetadata (e.g. reply-context cues).
+   * Forwarded to the session so the agent loop can incorporate them.
+   */
+  hints?: string[];
+  /**
+   * Brief UX context from sourceMetadata (e.g. UI surface description).
+   * Forwarded to the session so the agent loop can tailor its response.
+   */
+  uxBrief?: string;
+  /** Assistant scope for multi-assistant channels. */
+  assistantId?: string;
+  /** Guardian trust/identity context for the inbound actor. */
+  guardianContext?: GuardianRuntimeContext;
 }
 
 // ---------------------------------------------------------------------------
@@ -104,7 +123,17 @@ export class RunOrchestrator {
       throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
     }
 
-    const session = await this.deps.getOrCreateSession(conversationId);
+    // Build transport metadata when channel context is available so the
+    // session receives the same hints/uxBrief as the non-orchestrator path.
+    const transport = options?.sourceChannel
+      ? {
+          channelId: options.sourceChannel,
+          hints: options.hints,
+          uxBrief: options.uxBrief,
+        }
+      : undefined;
+
+    const session = await this.deps.getOrCreateSession(conversationId, transport);
 
     if (session.isProcessing()) {
       throw new Error('Session is already processing a message');
@@ -121,6 +150,8 @@ export class RunOrchestrator {
       ...session.memoryPolicy,
       strictSideEffects,
     };
+    session.setAssistantId(options?.assistantId ?? 'self');
+    session.setGuardianContext(options?.guardianContext ?? null);
 
     const attachments = attachmentIds
       ? this.deps.resolveAttachments(attachmentIds)
@@ -201,6 +232,8 @@ export class RunOrchestrator {
       // Reset channel capabilities so a subsequent IPC/desktop session on the
       // same conversation is not incorrectly treated as an HTTP-API client.
       session.setChannelCapabilities(null);
+      session.setGuardianContext(null);
+      session.setAssistantId('self');
       // Reset the session's client callback to a no-op so the stale
       // closure doesn't intercept events from future runs on the same session.
       // Set hasNoClient=true here since the run is done and no HTTP caller
@@ -251,13 +284,20 @@ export class RunOrchestrator {
    * - `'run_not_found'`   – no run exists with the given ID
    * - `'no_pending_decision'` – run exists but is not awaiting a confirmation
    */
-  submitDecision(runId: string, decision: UserDecision): 'applied' | 'run_not_found' | 'no_pending_decision' {
+  submitDecision(
+    runId: string,
+    decision: UserDecision,
+    decisionContext?: string,
+  ): 'applied' | 'run_not_found' | 'no_pending_decision' {
     const pendingState = this.pending.get(runId);
     if (pendingState) {
       runsStore.clearRunConfirmation(runId);
       pendingState.session.handleConfirmationResponse(
         pendingState.prompterRequestId,
         decision,
+        undefined,
+        undefined,
+        decisionContext,
       );
       this.pending.delete(runId);
       return 'applied';

package/src/security/secret-scanner.ts

@@ -457,6 +457,216 @@ function scanEntropy(
   return matches;
 }
 
+// ---------------------------------------------------------------------------
+// Encoded secret detection — decode + re-scan pass
+// ---------------------------------------------------------------------------
+
+/**
+ * Find percent-encoded segments containing 3+ encoded bytes, using a linear
+ * scan instead of a regex with nested quantifiers (which caused catastrophic
+ * backtracking on long near-miss inputs).
+ */
+function findPercentEncodedSegments(text: string): Array<{ start: number; end: number; match: string }> {
+  const results: Array<{ start: number; end: number; match: string }> = [];
+  const len = text.length;
+  const isUrlChar = (ch: string) => /[A-Za-z0-9_.~+/\-]/.test(ch);
+  const isHexDigit = (ch: string) => /[0-9A-Fa-f]/.test(ch);
+
+  let i = 0;
+  while (i < len) {
+    // Look for the start of a percent-encoded segment
+    if (text[i] !== '%' && !isUrlChar(text[i])) { i++; continue; }
+
+    // Walk a candidate segment of URL-safe chars and %XX sequences
+    const start = i;
+    let pctCount = 0;
+    while (i < len) {
+      if (text[i] === '%' && i + 2 < len && isHexDigit(text[i + 1]) && isHexDigit(text[i + 2])) {
+        pctCount++;
+        i += 3;
+      } else if (isUrlChar(text[i])) {
+        i++;
+      } else {
+        break;
+      }
+    }
+
+    if (pctCount >= 3) {
+      results.push({ start, end: i, match: text.slice(start, i) });
+    }
+    // Avoid re-scanning the same position if we didn't advance
+    if (i === start) i++;
+  }
+  return results;
+}
+
+/** Hex-escape sequences: \xHH patterns (3+ consecutive) */
+const HEX_ESCAPE_RE = /(?:\\x[0-9A-Fa-f]{2}){3,}/g;
+
+/** Candidate base64 segments — 24+ chars that could encode a secret (≥18 decoded bytes) */
+const ENCODED_BASE64_RE = /\b([A-Za-z0-9+/\-_]{24,}={0,3})(?=\W|$)/g;
+
+/** Continuous hex-encoded bytes — 32+ hex chars (16+ bytes decoded) */
+const CONTINUOUS_HEX_RE = /\b([0-9a-fA-F]{32,})\b/g;
+
+/** Check if decoded content is printable ASCII text */
+function isPrintableText(s: string): boolean {
+  return s.length > 0 && /^[\x20-\x7E\t\n\r]+$/.test(s);
+}
+
+function tryDecodeBase64(encoded: string): string | null {
+  try {
+    // Handle both standard and URL-safe base64
+    const standardized = encoded.replace(/-/g, '+').replace(/_/g, '/');
+    const decoded = Buffer.from(standardized, 'base64').toString('utf-8');
+    if (!isPrintableText(decoded)) return null;
+    // Verify round-trip to reject garbage decodes
+    const reEncoded = Buffer.from(decoded, 'utf-8').toString('base64').replace(/=+$/, '');
+    if (standardized.replace(/=+$/, '') !== reEncoded) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
+function tryDecodePercentEncoded(encoded: string): string | null {
+  try {
+    const decoded = decodeURIComponent(encoded);
+    if (decoded === encoded) return null;
+    if (!isPrintableText(decoded)) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
+function tryDecodeHexEscapes(encoded: string): string | null {
+  try {
+    const decoded = encoded.replace(/\\x([0-9A-Fa-f]{2})/g, (_, hex) =>
+      String.fromCharCode(parseInt(hex, 16)),
+    );
+    if (decoded === encoded) return null;
+    if (!isPrintableText(decoded)) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
+function tryDecodeContinuousHex(encoded: string): string | null {
+  try {
+    // Odd-length strings can't be decoded as pairs of hex digits
+    if (encoded.length % 2 !== 0) return null;
+    // Decode pairs of hex digits to bytes
+    const bytes: number[] = [];
+    for (let i = 0; i < encoded.length; i += 2) {
+      bytes.push(parseInt(encoded.slice(i, i + 2), 16));
+    }
+    const decoded = String.fromCharCode(...bytes);
+    if (!isPrintableText(decoded)) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
+/** Check if an encoded segment overlaps with any existing match range */
+function overlapsExisting(start: number, end: number, ranges: Set<string>): boolean {
+  for (const rangeKey of ranges) {
+    const sep = rangeKey.indexOf(':');
+    const rStart = Number(rangeKey.slice(0, sep));
+    const rEnd = Number(rangeKey.slice(sep + 1));
+    if (start < rEnd && end > rStart) return true;
+  }
+  return false;
+}
+
+/**
+ * Scan for encoded secrets by decoding candidate segments and running
+ * pattern matching on the decoded content. Catches base64-encoded,
+ * hex-encoded, and percent-encoded secrets that raw regex would miss.
+ */
+function scanEncoded(
+  text: string,
+  existingRanges: Set<string>,
+): SecretMatch[] {
+  const matches: SecretMatch[] = [];
+
+  // Helper: try to match decoded content against known secret patterns
+  const tryMatchDecoded = (
+    encoded: string,
+    decoded: string,
+    startIndex: number,
+    endIndex: number,
+    encoding: string,
+  ) => {
+    for (const pattern of PATTERNS) {
+      pattern.regex.lastIndex = 0;
+      let pm: RegExpExecArray | null;
+      while ((pm = pattern.regex.exec(decoded)) !== null) {
+        const value = pm[1] ?? pm[0];
+        if (isPlaceholder(value)) continue;
+        if (isAllowlisted(value)) continue;
+        if (pattern.type === 'AWS Secret Key' && !isLikelyAwsSecret(value)) continue;
+
+        const key = `${startIndex}:${endIndex}`;
+        existingRanges.add(key);
+        matches.push({
+          type: `${pattern.type} (${encoding})`,
+          startIndex,
+          endIndex,
+          redactedValue: redact(encoded),
+        });
+        return;
+      }
+    }
+  };
+
+  // Percent-encoded segments: use linear-time scanner instead of regex
+  if (text.includes('%')) {
+    for (const seg of findPercentEncodedSegments(text)) {
+      if (seg.match.length > 1000) continue;
+      if (overlapsExisting(seg.start, seg.end, existingRanges)) continue;
+      const decoded = tryDecodePercentEncoded(seg.match);
+      if (!decoded) continue;
+      tryMatchDecoded(seg.match, decoded, seg.start, seg.end, 'percent-encoded');
+    }
+  }
+
+  // Regex-based decoders for the remaining encodings
+  const decoders: Array<{
+    regex: RegExp;
+    decode: (s: string) => string | null;
+    encoding: string;
+    quickCheck?: (t: string) => boolean;
+  }> = [
+    { regex: HEX_ESCAPE_RE, decode: tryDecodeHexEscapes, encoding: 'hex-escaped', quickCheck: (t) => t.includes('\\x') },
+    { regex: ENCODED_BASE64_RE, decode: tryDecodeBase64, encoding: 'base64-encoded' },
+    { regex: CONTINUOUS_HEX_RE, decode: tryDecodeContinuousHex, encoding: 'hex-encoded' },
+  ];
+
+  for (const { regex, decode, encoding, quickCheck } of decoders) {
+    if (quickCheck && !quickCheck(text)) continue;
+    regex.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = regex.exec(text)) !== null) {
+      const encoded = m[1] ?? m[0];
+      if (encoded.length > 1000) continue;
+      const startIndex = m.index + (m[0].indexOf(encoded));
+      const endIndex = startIndex + encoded.length;
+
+      if (overlapsExisting(startIndex, endIndex, existingRanges)) continue;
+
+      const decoded = decode(encoded);
+      if (!decoded) continue;
+
+      tryMatchDecoded(encoded, decoded, startIndex, endIndex, encoding);
+    }
+  }
+
+  return matches;
+}
+
 // ---------------------------------------------------------------------------
 // Scan function
 // ---------------------------------------------------------------------------
@@ -508,6 +718,10 @@ export function scanText(text: string, entropyConfig?: Partial<EntropyConfig>):
   const entropyMatches = scanEntropy(text, eConfig, seen);
   matches.push(...entropyMatches);
 
+  // Encoded secret detection — decode candidate segments and re-scan
+  const encodedMatches = scanEncoded(text, seen);
+  matches.push(...encodedMatches);
+
   // Sort by position; at same start, wider match first so redaction covers the full span
   matches.sort((a, b) => a.startIndex - b.startIndex || b.endIndex - a.endIndex);
   return matches;
@@ -547,4 +761,8 @@ export {
   redact as _redact,
   PATTERNS as _PATTERNS,
   hasSecretContext as _hasSecretContext,
+  tryDecodeBase64 as _tryDecodeBase64,
+  tryDecodePercentEncoded as _tryDecodePercentEncoded,
+  tryDecodeHexEscapes as _tryDecodeHexEscapes,
+  tryDecodeContinuousHex as _tryDecodeContinuousHex,
 };

package/src/skills/frontmatter.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared frontmatter parsing for SKILL.md files.
+ *
+ * Frontmatter is a YAML-like block delimited by `---` at the top of a file.
+ * This module provides a single implementation used by the skill catalog loader,
+ * the Vellum catalog installer, and the CC command registry.
+ */
+
+/** Matches a `---` delimited frontmatter block at the start of a file. */
+export const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+export interface FrontmatterParseResult {
+  /** Key-value pairs extracted from the frontmatter block. */
+  fields: Record<string, string>;
+  /** The remaining file content after the frontmatter block. */
+  body: string;
+}
+
+/**
+ * Parse frontmatter fields from file content.
+ *
+ * Extracts key-value pairs from the `---` delimited block at the top of the
+ * file. Handles single- and double-quoted values, and unescapes common escape
+ * sequences (`\n`, `\r`, `\\`, `\"`) in double-quoted values.
+ *
+ * Returns `null` if no frontmatter block is found.
+ */
+export function parseFrontmatterFields(content: string): FrontmatterParseResult | null {
+  const match = content.match(FRONTMATTER_REGEX);
+  if (!match) return null;
+
+  const frontmatter = match[1];
+  const fields: Record<string, string> = {};
+
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const separatorIndex = trimmed.indexOf(':');
+    if (separatorIndex === -1) continue;
+
+    const key = trimmed.slice(0, separatorIndex).trim();
+    let value = trimmed.slice(separatorIndex + 1).trim();
+
+    const isDoubleQuoted = value.startsWith('"') && value.endsWith('"');
+    const isSingleQuoted = value.startsWith("'") && value.endsWith("'");
+    if (isDoubleQuoted || isSingleQuoted) {
+      value = value.slice(1, -1);
+      if (isDoubleQuoted) {
+        // Unescape sequences produced by buildSkillMarkdown's esc().
+        // Only for double-quoted values — single-quoted YAML treats backslashes literally.
+        // Single-pass to avoid misinterpreting \\n (escaped backslash + n) as a newline.
+        value = value.replace(/\\(["\\nr])/g, (_, ch) => {
+          if (ch === 'n') return '\n';
+          if (ch === 'r') return '\r';
+          return ch; // handles \\ → \ and \" → "
+        });
+      }
+    }
+    fields[key] = value;
+  }
+
+  return { fields, body: content.slice(match[0].length) };
+}

package/src/skills/slash-commands.ts

@@ -155,6 +155,10 @@ export function formatUnknownSlashSkillMessage(
 /**
  * Rewrite user input for a known slash command into a model-facing prompt
  * that explicitly instructs the model to invoke the skill.
+ *
+ * For the claude-code skill, trailing arguments are routed via the `command`
+ * input (not `prompt`) so that .claude/commands/*.md templates are loaded
+ * and $ARGUMENTS substitution is applied.
  */
 export function rewriteKnownSlashCommandPrompt(params: {
   rawInput: string;
@@ -162,6 +166,25 @@ export function rewriteKnownSlashCommandPrompt(params: {
   skillName: string;
   trailingArgs: string;
 }): string {
+  // For the claude-code skill, route trailing args through the `command` input
+  // so CC command templates (.claude/commands/*.md) are loaded and $ARGUMENTS
+  // substitution is applied, rather than sending them as a raw prompt.
+  if (params.skillId === 'claude-code' && params.trailingArgs) {
+    // Extract the command name (first word of trailing args) and remaining arguments
+    const parts = params.trailingArgs.split(/\s+/);
+    const commandName = parts[0];
+    const commandArgs = parts.slice(1).join(' ');
+
+    const lines = [
+      `The user invoked the slash command \`/${params.skillId}\`.`,
+      `Execute the Claude Code command "${commandName}" using the claude_code tool with command="${commandName}".`,
+    ];
+    if (commandArgs) {
+      lines.push(`Pass the following as the \`arguments\` input: ${commandArgs}`);
+    }
+    return lines.join('\n');
+  }
+
   const lines = [
     `The user invoked the slash command \`/${params.skillId}\`.`,
     `Please invoke the "${params.skillName}" skill (ID: ${params.skillId}).`,

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

@@ -0,0 +1,107 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { CatalogEntry } from '../tools/skills/vellum-catalog.js';
+import { getLogger } from '../util/logger.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 CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+
+interface CatalogManifest {
+  version: number;
+  skills: CatalogEntry[];
+}
+
+let cachedEntries: CatalogEntry[] | null = null;
+let cacheTimestamp = 0;
+
+function getBundledCatalogPath(): string {
+  return join(import.meta.dir, '..', 'config', 'vellum-skills', 'catalog.json');
+}
+
+function loadBundledCatalog(): CatalogEntry[] {
+  try {
+    const raw = readFileSync(getBundledCatalogPath(), 'utf-8');
+    const manifest: CatalogManifest = JSON.parse(raw);
+    return manifest.skills ?? [];
+  } catch (err) {
+    log.warn({ err }, 'Failed to read bundled catalog.json');
+    return [];
+  }
+}
+
+function getBundledSkillContent(skillId: string): string | null {
+  try {
+    const skillPath = join(import.meta.dir, '..', 'config', 'vellum-skills', skillId, 'SKILL.md');
+    return readFileSync(skillPath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/** Fetch catalog entries (cached, async). Falls back to bundled copy. */
+export async function fetchCatalogEntries(): Promise<CatalogEntry[]> {
+  const now = Date.now();
+  if (cachedEntries && now - cacheTimestamp < CACHE_TTL_MS) {
+    return cachedEntries;
+  }
+
+  try {
+    const url = `${GITHUB_RAW_BASE}/catalog.json`;
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(5000),
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    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');
+    }
+    cachedEntries = skills;
+    cacheTimestamp = now;
+    log.info({ count: cachedEntries.length }, 'Fetched remote vellum-skills catalog');
+    return cachedEntries;
+  } catch (err) {
+    log.warn({ err }, 'Failed to fetch remote catalog, 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;
+    cacheTimestamp = now;
+    return bundled;
+  }
+}
+
+/** Fetch a skill's SKILL.md content from GitHub. Falls back to bundled copy. */
+export async function fetchSkillContent(skillId: string): Promise<string | null> {
+  try {
+    const url = `${GITHUB_RAW_BASE}/${encodeURIComponent(skillId)}/SKILL.md`;
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(10000),
+    });
+
+    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;
+  } catch (err) {
+    log.warn({ err, skillId }, 'Failed to fetch remote SKILL.md, falling back to bundled copy');
+    return getBundledSkillContent(skillId);
+  }
+}
+
+/** Check if a skill ID exists in the remote catalog. */
+export async function checkVellumSkill(skillId: string): Promise<boolean> {
+  const entries = await fetchCatalogEntries();
+  return entries.some((e) => e.id === skillId);
+}

package/src/tools/assets/materialize.ts

@@ -41,8 +41,8 @@ function formatBytes(bytes: number): string {
 /**
  * Load an attachment row (including base64 data) by its primary key.
  *
- * Not scoped by assistantId because ToolContext doesn't carry it.
- * Cross-thread isolation is enforced by the visibility check in execute().
+ * Not scoped by assistantId because attachment access is enforced by
+ * conversation visibility checks in execute().
  */
 function loadAttachmentById(
   attachmentId: string,