@vellumai/assistant 0.3.0

package/src/skills/version-hash.ts

@@ -0,0 +1,110 @@
+import { readdirSync, readFileSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+
+/**
+ * Directories/files to exclude from skill hashing — these are transient
+ * runtime artifacts that do not affect the skill's behavior.
+ */
+const EXCLUDED_NAMES = new Set([
+  '.vellum-skill-run',
+  'node_modules',
+  '.git',
+  '__pycache__',
+  '.DS_Store',
+]);
+
+/**
+ * Collect all files under `dir` in sorted order, excluding transient entries.
+ * Uses an `ancestors` set of real directory paths currently on the recursion
+ * stack to detect symlink cycles without suppressing legitimate duplicate
+ * symlink targets reached via different paths.
+ */
+function collectFiles(dir: string, base: string, ancestors: Set<string> = new Set()): string[] {
+  const entries: string[] = [];
+
+  let realDir: string;
+  try {
+    realDir = realpathSync(dir);
+  } catch {
+    return entries;
+  }
+  if (ancestors.has(realDir)) return entries;
+  ancestors.add(realDir);
+
+  let items: string[];
+  try {
+    items = readdirSync(dir).sort();
+  } catch {
+    ancestors.delete(realDir);
+    return entries;
+  }
+
+  for (const name of items) {
+    if (EXCLUDED_NAMES.has(name)) continue;
+    const full = join(dir, name);
+    let stat;
+    try {
+      stat = lstatSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isSymbolicLink()) {
+      let resolved: string;
+      try {
+        resolved = realpathSync(full);
+      } catch {
+        continue;
+      }
+      let resolvedStat;
+      try {
+        resolvedStat = statSync(resolved);
+      } catch {
+        continue;
+      }
+      if (resolvedStat.isDirectory()) {
+        entries.push(...collectFiles(full, base, ancestors));
+      } else if (resolvedStat.isFile()) {
+        entries.push(relative(base, full));
+      }
+      continue;
+    }
+    if (stat.isDirectory()) {
+      entries.push(...collectFiles(full, base, ancestors));
+    } else if (stat.isFile()) {
+      entries.push(relative(base, full));
+    }
+  }
+
+  ancestors.delete(realDir);
+  return entries;
+}
+
+/**
+ * Compute a deterministic version hash for a skill directory.
+ *
+ * The hash is computed from:
+ * - Sorted relative file paths (normalized to forward slashes)
+ * - File content lengths
+ * - File content bytes
+ *
+ * The result is a canonical string in the format `v1:<hex-sha256>`.
+ * File traversal order does not affect the result.
+ */
+export function computeSkillVersionHash(skillDir: string): string {
+  const files = collectFiles(skillDir, skillDir);
+  const hash = createHash('sha256');
+
+  for (const relPath of files) {
+    const normalized = relPath.replaceAll('\\', '/');
+    const content = readFileSync(join(skillDir, relPath));
+    hash.update(normalized);
+    hash.update('\0');
+    hash.update(String(content.length));
+    hash.update('\0');
+    hash.update(content);
+    hash.update('\n');
+  }
+
+  return `v1:${hash.digest('hex')}`;
+}

package/src/slack/slack-webhook.ts

@@ -0,0 +1,61 @@
+import { getLogger } from '../util/logger.js';
+
+const log = getLogger('slack-webhook');
+
+/**
+ * Post a rich Block Kit message to a Slack Incoming Webhook URL.
+ *
+ * Uses the Block Kit format so the message renders nicely in Slack with
+ * a header, description section, and context footer.
+ */
+export async function postToSlackWebhook(
+  webhookUrl: string,
+  appName: string,
+  appDescription: string,
+  appIcon: string,
+): Promise<void> {
+  const blocks = [
+    {
+      type: 'header',
+      text: {
+        type: 'plain_text',
+        text: `${appIcon} ${appName}`,
+        emoji: true,
+      },
+    },
+    {
+      type: 'section',
+      text: {
+        type: 'mrkdwn',
+        text: appDescription || '_No description_',
+      },
+    },
+    {
+      type: 'context',
+      elements: [
+        {
+          type: 'mrkdwn',
+          text: `Shared from Vellum Assistant`,
+        },
+      ],
+    },
+  ];
+
+  const payload = {
+    blocks,
+    text: `${appIcon} ${appName}: ${appDescription || 'No description'}`,
+  };
+
+  log.info({ appName }, 'Posting app to Slack webhook');
+
+  const response = await fetch(webhookUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Slack webhook returned ${response.status}: ${body}`);
+  }
+}

package/src/subagent/index.ts

@@ -0,0 +1,19 @@
+export type {
+  SubagentStatus,
+  SubagentConfig,
+  SubagentState,
+} from './types.js';
+export { TERMINAL_STATUSES, SUBAGENT_LIMITS } from './types.js';
+export { SubagentManager } from './manager.js';
+
+import { SubagentManager } from './manager.js';
+
+/** Singleton SubagentManager instance shared across the daemon. */
+let _instance: SubagentManager | null = null;
+
+export function getSubagentManager(): SubagentManager {
+  if (!_instance) {
+    _instance = new SubagentManager();
+  }
+  return _instance;
+}

package/src/subagent/manager.ts

@@ -0,0 +1,511 @@
+/**
+ * SubagentManager — owns the lifecycle of all subagent sessions.
+ *
+ * Responsibilities:
+ *   - spawn / abort / dispose subagent sessions
+ *   - enforce concurrency and depth limits
+ *   - route events from child sessions through parent's socket
+ *   - inject completion summaries back into parent context
+ */
+
+import { v4 as uuid } from 'uuid';
+import { Session, type SessionMemoryPolicy } from '../daemon/session.js';
+import { createConversation } from '../memory/conversation-store.js';
+import { getConfig } from '../config/loader.js';
+import { getFailoverProvider } from '../providers/registry.js';
+import { RateLimitProvider } from '../providers/ratelimit.js';
+import { getSandboxWorkingDir } from '../util/platform.js';
+import { getLogger } from '../util/logger.js';
+import type { ServerMessage } from '../daemon/ipc-contract.js';
+import {
+  type SubagentConfig,
+  type SubagentState,
+  type SubagentStatus,
+  SUBAGENT_LIMITS,
+  TERMINAL_STATUSES,
+} from './types.js';
+
+const log = getLogger('subagent-manager');
+
+// ── Default subagent system prompt ──────────────────────────────────────
+
+function buildSubagentSystemPrompt(config: SubagentConfig): string {
+  const sections: string[] = [
+    'You are a focused subagent working on a specific task delegated by a parent assistant.',
+    'Complete the task thoroughly and concisely.',
+    '',
+    `## Your Task`,
+    config.objective,
+  ];
+  if (config.context) {
+    sections.push('', '## Context from Parent', config.context);
+  }
+  return sections.join('\n');
+}
+
+// ── Manager ─────────────────────────────────────────────────────────────
+
+interface ManagedSubagent {
+  session: Session;
+  state: SubagentState;
+  /** Mutable reference to the parent's current sendToClient. Updated on reconnect. */
+  parentSendToClient: (msg: ServerMessage) => void;
+}
+
+export interface SubagentNotificationInfo {
+  subagentId: string;
+  label: string;
+  status: 'completed' | 'failed' | 'aborted';
+  error?: string;
+  conversationId?: string;
+}
+
+export type ParentNotifyCallback = (
+  parentSessionId: string,
+  message: string,
+  sendToClient: (msg: ServerMessage) => void,
+  notification: SubagentNotificationInfo,
+) => void;
+
+export class SubagentManager {
+  /** subagentId → ManagedSubagent */
+  private subagents = new Map<string, ManagedSubagent>();
+  /** parentSessionId → Set<subagentId> */
+  private parentToChildren = new Map<string, Set<string>>();
+
+  /**
+   * Optional callback to inject a completion/failure message into the parent
+   * session's conversation so the LLM can automatically inform the user.
+   * Wired by DaemonServer at startup.
+   */
+  onSubagentFinished?: ParentNotifyCallback;
+
+  /**
+   * Shared rate-limit timestamps array from the daemon server.
+   * Set by DaemonServer at startup so subagents share the global rate limit.
+   */
+  sharedRequestTimestamps: number[] = [];
+
+  // ── Spawn ───────────────────────────────────────────────────────────
+
+  /**
+   * Spawn a new subagent.  Returns the subagent ID immediately.
+   * The subagent's agent loop is started asynchronously (fire-and-forget).
+   */
+  async spawn(
+    config: Omit<SubagentConfig, 'id'>,
+    parentSendToClient: (msg: ServerMessage) => void,
+  ): Promise<string> {
+    // ── Limit checks ────────────────────────────────────────────────
+
+    // Depth check: prevent subagents from spawning nested subagents.
+    const isParentASubagent = [...this.subagents.values()].some(
+      (s) => s.state.conversationId === config.parentSessionId,
+    );
+    if (isParentASubagent) {
+      throw new Error(
+        `Cannot spawn subagent: parent is itself a subagent (max depth ${SUBAGENT_LIMITS.maxDepth}).`,
+      );
+    }
+
+    // ── Create conversation ─────────────────────────────────────────
+    const subagentId = uuid();
+    const conversation = createConversation({
+      title: `Subagent: ${config.label}`,
+      threadType: 'background',
+    });
+
+    // ── Build session dependencies ──────────────────────────────────
+    const appConfig = getConfig();
+    let provider = getFailoverProvider(appConfig.provider, appConfig.providerOrder);
+    const { rateLimit } = appConfig;
+    if (rateLimit.maxRequestsPerMinute > 0 || rateLimit.maxTokensPerSession > 0) {
+      provider = new RateLimitProvider(provider, rateLimit, this.sharedRequestTimestamps);
+    }
+
+    const systemPrompt = config.systemPromptOverride ?? buildSubagentSystemPrompt({ ...config, id: subagentId });
+    const maxTokens = appConfig.maxTokens;
+    const workingDir = getSandboxWorkingDir();
+
+    const memoryPolicy: SessionMemoryPolicy = {
+      scopeId: `subagent:${subagentId}`,
+      includeDefaultFallback: true,
+      strictSideEffects: false,
+    };
+
+    // ── Initialise state ────────────────────────────────────────────
+    const now = Date.now();
+    const state: SubagentState = {
+      config: { ...config, id: subagentId },
+      status: 'pending',
+      conversationId: conversation.id,
+      createdAt: now,
+      usage: { inputTokens: 0, outputTokens: 0, estimatedCost: 0 },
+    };
+
+    // Store the managed subagent early so the wrapper can read the mutable
+    // parentSendToClient reference — this ensures reconnects are picked up.
+    const managed: ManagedSubagent = {
+      session: undefined as unknown as Session,
+      state,
+      parentSendToClient,
+    };
+
+    // Wrap sendToClient to envelope all events with the subagent ID.
+    // Reads from managed.parentSendToClient so reconnects are picked up.
+    const wrappedSendToClient = (msg: ServerMessage): void => {
+      managed.parentSendToClient({
+        type: 'subagent_event',
+        subagentId,
+        event: msg,
+      } as ServerMessage);
+    };
+
+    const session = new Session(
+      conversation.id,
+      provider,
+      systemPrompt,
+      maxTokens,
+      wrappedSendToClient,
+      workingDir,
+      undefined, // no broadcastToAllClients for subagents
+      memoryPolicy,
+    );
+
+    // Mark session as having no direct IPC client — it routes through parent.
+    // This ensures interactive prompts (host attachment reads) fail fast.
+    session.updateClient(wrappedSendToClient, true);
+
+    managed.session = session;
+    this.subagents.set(subagentId, managed);
+
+    // Track parent → child relationship.
+    if (!this.parentToChildren.has(config.parentSessionId)) {
+      this.parentToChildren.set(config.parentSessionId, new Set());
+    }
+    this.parentToChildren.get(config.parentSessionId)!.add(subagentId);
+
+    // Notify client that a subagent was spawned.
+    parentSendToClient({
+      type: 'subagent_spawned',
+      subagentId,
+      parentSessionId: config.parentSessionId,
+      label: config.label,
+      objective: config.objective,
+    } as ServerMessage);
+
+    log.info(
+      { subagentId, parentSessionId: config.parentSessionId, label: config.label },
+      'Subagent spawned',
+    );
+
+    // ── Kick off the agent loop (fire-and-forget) ───────────────────
+    this.runSubagent(subagentId, config.objective).catch((err) => {
+      log.error({ subagentId, err }, 'Subagent run failed unexpectedly');
+    });
+
+    return subagentId;
+  }
+
+  // ── Internal: run the subagent ────────────────────────────────────────
+
+  private async runSubagent(
+    subagentId: string,
+    objective: string,
+  ): Promise<void> {
+    const managed = this.subagents.get(subagentId);
+    if (!managed) return;
+
+    // Read the current parent sender so reconnects are picked up.
+    const getSender = () => managed.parentSendToClient;
+
+    this.setStatus(subagentId, 'running', getSender());
+    managed.state.startedAt = Date.now();
+
+    const onEvent = managed.session.sendToClient;
+
+    try {
+      // Send the objective as the first user message and process it.
+      const messageId = managed.session.persistUserMessage(objective, []);
+      await managed.session.runAgentLoop(objective, messageId, onEvent);
+
+      // Agent loop completed successfully.
+      // Copy usage stats from the session before sending status (which includes usage).
+      managed.state.usage = { ...managed.session.usageStats };
+      // Only update state + notify if still non-terminal (guards against abort race).
+      if (!TERMINAL_STATUSES.has(managed.state.status)) {
+        managed.state.completedAt = Date.now();
+        this.setStatus(subagentId, 'completed', getSender());
+
+        log.info({ subagentId }, 'Subagent completed');
+
+        // Notify the parent session so the LLM can call subagent_read.
+        this.notifyParent(managed, 'completed', getSender());
+      }
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      managed.state.error = errorMsg;
+      managed.state.completedAt = Date.now();
+      managed.state.usage = { ...managed.session.usageStats };
+
+      // Only update status if not already terminal (e.g. aborted).
+      if (!TERMINAL_STATUSES.has(managed.state.status)) {
+        this.setStatus(subagentId, 'failed', getSender(), errorMsg);
+        this.notifyParent(managed, 'failed', getSender());
+      }
+
+      log.error({ subagentId, err }, 'Subagent failed');
+    }
+  }
+
+  // ── Abort ─────────────────────────────────────────────────────────────
+
+  abort(
+    subagentId: string,
+    parentSendToClient?: (msg: ServerMessage) => void,
+    callerSessionId?: string,
+    options?: { suppressNotification?: boolean },
+  ): boolean {
+    const managed = this.subagents.get(subagentId);
+    if (!managed) return false;
+    if (TERMINAL_STATUSES.has(managed.state.status)) return false;
+    // If a caller session is specified, verify ownership.
+    if (callerSessionId && managed.state.config.parentSessionId !== callerSessionId) {
+      log.warn({ subagentId, callerSessionId, parentSessionId: managed.state.config.parentSessionId },
+        'Abort rejected: caller does not own this subagent');
+      return false;
+    }
+
+    managed.session.abort();
+    managed.state.completedAt = Date.now();
+    if (parentSendToClient) {
+      // Route the status update through the stored parent sender so the
+      // owning session's UI chip updates, even when the abort comes from a
+      // different socket (e.g. after thread switching). Fall back to the
+      // caller-provided sender if no stored sender exists.
+      const statusSender = managed.parentSendToClient ?? parentSendToClient;
+      this.setStatus(subagentId, 'aborted', statusSender);
+      // Notify parent that the subagent was explicitly aborted — tell it NOT to re-spawn.
+      // Skip when the parent LLM itself called subagent_abort (it already has the tool result).
+      if (this.onSubagentFinished && !options?.suppressNotification) {
+        const label = managed.state.config.label;
+        const message =
+          `[Subagent "${label}" was explicitly aborted]\n\n` +
+          `This subagent was cancelled on purpose. Do NOT re-spawn or retry it.`;
+        try {
+          // Use the managed subagent's stored parentSendToClient so the
+          // notification routes to the parent session's socket, not the
+          // aborting socket (which may be a different thread after switching).
+          this.onSubagentFinished(
+            managed.state.config.parentSessionId,
+            message,
+            managed.parentSendToClient,
+            { subagentId, label, status: 'aborted', conversationId: managed.state.conversationId },
+          );
+        } catch (err) {
+          log.error({ subagentId, err }, 'Failed to notify parent about abort');
+        }
+      }
+    } else {
+      managed.state.status = 'aborted';
+    }
+
+    log.info({ subagentId }, 'Subagent aborted');
+    return true;
+  }
+
+  /**
+   * Abort all subagents belonging to a parent session.
+   * Called when the parent session is aborted or evicted.
+   */
+  abortAllForParent(
+    parentSessionId: string,
+    parentSendToClient?: (msg: ServerMessage) => void,
+  ): number {
+    const children = this.parentToChildren.get(parentSessionId);
+    if (!children) return 0;
+
+    let count = 0;
+    for (const childId of children) {
+      if (this.abort(childId, parentSendToClient)) {
+        count++;
+      }
+    }
+
+    // Dispose all children — the parent session is going away so nobody
+    // will call subagent_read.  Use snapshot since dispose mutates the set.
+    for (const childId of [...children]) {
+      this.dispose(childId);
+    }
+
+    return count;
+  }
+
+  // ── Send message to subagent ──────────────────────────────────────────
+
+  sendMessage(subagentId: string, content: string): boolean {
+    const trimmed = content?.trim();
+    if (!trimmed) return false;
+
+    const managed = this.subagents.get(subagentId);
+    if (!managed) return false;
+    if (TERMINAL_STATUSES.has(managed.state.status)) return false;
+
+    const onEvent = managed.session.sendToClient;
+    const requestId = uuid();
+
+    // If the session is busy, queue the message; otherwise process immediately.
+    const result = managed.session.enqueueMessage(trimmed, [], onEvent, requestId);
+    if (result.rejected) return false;
+    if (!result.queued) {
+      // Session is idle — send directly.  Fire-and-forget so we don't block.
+      const messageId = managed.session.persistUserMessage(trimmed, []);
+      managed.session.runAgentLoop(trimmed, messageId, onEvent).catch((err) => {
+        log.error({ subagentId, err }, 'Subagent message processing failed');
+      });
+    }
+    return true;
+  }
+
+  // ── Queries ───────────────────────────────────────────────────────────
+
+  getState(subagentId: string): SubagentState | undefined {
+    return this.subagents.get(subagentId)?.state;
+  }
+
+  getChildrenOf(parentSessionId: string): SubagentState[] {
+    const children = this.parentToChildren.get(parentSessionId);
+    if (!children) return [];
+    return [...children]
+      .map((id) => this.subagents.get(id)?.state)
+      .filter((s): s is SubagentState => s !== undefined);
+  }
+
+  /** Total number of active (non-terminal) subagents. */
+  get activeCount(): number {
+    return [...this.subagents.values()].filter(
+      (s) => !TERMINAL_STATUSES.has(s.state.status),
+    ).length;
+  }
+
+  /**
+   * Update the parent sender for all active children of a session.
+   * Called when the parent client reconnects to a new socket.
+   */
+  updateParentSender(parentSessionId: string, newSendToClient: (msg: ServerMessage) => void): void {
+    const children = this.parentToChildren.get(parentSessionId);
+    if (!children) return;
+
+    for (const childId of children) {
+      const managed = this.subagents.get(childId);
+      if (managed && !TERMINAL_STATUSES.has(managed.state.status)) {
+        managed.parentSendToClient = newSendToClient;
+      }
+    }
+  }
+
+  // ── Cleanup ───────────────────────────────────────────────────────────
+
+  /**
+   * Dispose a subagent and remove it from tracking.
+   * Should be called after the subagent reaches a terminal state
+   * and its data is no longer needed.
+   */
+  dispose(subagentId: string): void {
+    const managed = this.subagents.get(subagentId);
+    if (!managed) return;
+
+    if (!TERMINAL_STATUSES.has(managed.state.status)) {
+      managed.session.abort();
+    }
+    managed.session.dispose();
+    this.subagents.delete(subagentId);
+
+    // Remove from parent tracking.
+    const parentId = managed.state.config.parentSessionId;
+    const siblings = this.parentToChildren.get(parentId);
+    if (siblings) {
+      siblings.delete(subagentId);
+      if (siblings.size === 0) {
+        this.parentToChildren.delete(parentId);
+      }
+    }
+  }
+
+  /** Dispose all subagents. Called on daemon shutdown. */
+  disposeAll(): void {
+    for (const id of [...this.subagents.keys()]) {
+      this.dispose(id);
+    }
+  }
+
+  // ── Internals ─────────────────────────────────────────────────────────
+
+  private setStatus(
+    subagentId: string,
+    status: SubagentStatus,
+    parentSendToClient: (msg: ServerMessage) => void,
+    error?: string,
+  ): void {
+    const managed = this.subagents.get(subagentId);
+    if (!managed) return;
+
+    // Idempotent terminal state guard.
+    if (TERMINAL_STATUSES.has(managed.state.status) && managed.state.status !== status) {
+      return;
+    }
+
+    managed.state.status = status;
+    if (error !== undefined) managed.state.error = error;
+
+    parentSendToClient({
+      type: 'subagent_status_changed',
+      subagentId,
+      status,
+      error,
+      usage: managed.state.usage,
+    } as ServerMessage);
+  }
+
+  /**
+   * Inject a completion/failure notification into the parent session
+   * so the LLM automatically informs the user.
+   */
+  private notifyParent(
+    managed: ManagedSubagent,
+    outcome: 'completed' | 'failed',
+    parentSendToClient: (msg: ServerMessage) => void,
+  ): void {
+    if (!this.onSubagentFinished) return;
+
+    const { config } = managed.state;
+    let message: string;
+
+    if (outcome === 'completed') {
+      message =
+        `[Subagent "${config.label}" completed]\n\n` +
+        `Use subagent_read with subagent_id "${config.id}" to retrieve the full output.\n` +
+        `Do NOT re-spawn this subagent — just read and share the results.`;
+    } else {
+      const error = managed.state.error ?? 'Unknown error';
+      message =
+        `[Subagent "${config.label}" failed]\n\n` +
+        `Error: ${error}\n` +
+        `Do NOT re-spawn or retry this subagent unless the user explicitly asks.`;
+    }
+
+    const notification: SubagentNotificationInfo = {
+      subagentId: config.id,
+      label: config.label,
+      status: outcome,
+      conversationId: managed.state.conversationId,
+      ...(outcome === 'failed' ? { error: managed.state.error ?? 'Unknown error' } : {}),
+    };
+
+    try {
+      this.onSubagentFinished(config.parentSessionId, message, parentSendToClient, notification);
+    } catch (err) {
+      log.error({ subagentId: config.id, err }, 'Failed to notify parent session');
+    }
+  }
+}