@vellumai/assistant 0.6.0 → 0.6.2

package/src/subagent/manager.ts

@@ -23,7 +23,9 @@ import { getLogger } from "../util/logger.js";
 import { getSandboxWorkingDir } from "../util/platform.js";
 import {
   SUBAGENT_LIMITS,
+  SUBAGENT_ROLE_REGISTRY,
   type SubagentConfig,
+  type SubagentRole,
   type SubagentState,
   type SubagentStatus,
   TERMINAL_STATUSES,
@@ -31,35 +33,76 @@ import {
 
 const log = getLogger("subagent-manager");
 
+/** How long to keep terminal subagent metadata after the live conversation is released (ms). */
+const TERMINAL_RETENTION_MS = 30 * 60 * 1000; // 30 minutes
+/** How often to sweep expired terminal entries (ms). */
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+// ── Skill ID merge helper ──────────────────────────────────────────────
+
+/**
+ * Merge role-defined skill IDs with caller-provided skill IDs, deduplicating.
+ * Exported for direct unit testing.
+ */
+export function mergeSkillIds(
+  roleSkillIds: string[],
+  configSkillIds?: string[],
+): string[] {
+  return [...new Set([...roleSkillIds, ...(configSkillIds ?? [])])];
+}
+
 // ── Default subagent system prompt ──────────────────────────────────────
 
-function buildSubagentSystemPrompt(config: SubagentConfig): string {
+function buildSubagentSystemPrompt(
+  config: SubagentConfig,
+  role: SubagentRole,
+): string {
+  const roleConfig = SUBAGENT_ROLE_REGISTRY[role];
   const sections: string[] = [
-    "You are a focused subagent working on a specific task delegated by a parent assistant.",
-    "Complete the task thoroughly and concisely.",
+    roleConfig.systemPromptPreamble,
     "",
-    `## Your Task`,
+    "## Your Task",
     config.objective,
   ];
   if (config.context) {
     sections.push("", "## Context from Parent", config.context);
   }
+  sections.push(
+    "",
+    "## Constraints",
+    `- Role: ${role}`,
+    "- You cannot spawn nested subagents.",
+    "- Use notify_parent to report important findings or if you are blocked.",
+  );
   return sections.join("\n");
 }
 
 // ── Manager ─────────────────────────────────────────────────────────────
 
 interface ManagedSubagent {
-  conversation: Conversation;
+  /** Live conversation — null after the subagent reaches a terminal state and is released. */
+  conversation: Conversation | null;
   state: SubagentState;
   /** Mutable reference to the parent's current sendToClient. Updated on reconnect. */
   parentSendToClient: (msg: ServerMessage) => void;
+  /** Epoch ms after which this terminal entry can be removed by the TTL sweep. */
+  retainedUntil?: number;
+  /**
+   * Set to true when sendMessage enqueues a follow-up message while the
+   * initial objective loop is running.  runAgentLoop fires drainQueue without
+   * awaiting it, and drainQueue shift()s the item synchronously — so both
+   * hasQueuedMessages() and isProcessing() can return false while the drain
+   * is still active.  This flag lets the finally block in runSubagent defer
+   * the release to the TTL sweep rather than tearing down the conversation
+   * mid-drain.
+   */
+  hadEnqueuedMessages?: boolean;
 }
 
 export interface SubagentNotificationInfo {
   subagentId: string;
   label: string;
-  status: "completed" | "failed" | "aborted";
+  status: "running" | "completed" | "failed" | "aborted";
   error?: string;
   conversationId?: string;
 }
@@ -76,6 +119,8 @@ export class SubagentManager {
   private subagents = new Map<string, ManagedSubagent>();
   /** parentConversationId → Set<subagentId> */
   private parentToChildren = new Map<string, Set<string>>();
+  /** `${parentConversationId}:${normalizedLabel}` → subagentId */
+  private labelIndex = new Map<string, string>();
 
   /**
    * Optional callback to inject a completion/failure message into the parent
@@ -119,10 +164,20 @@ export class SubagentManager {
       );
     }
 
+    // ── Resolve role ─────────────────────────────────────────────────
+    const role: SubagentRole = (config.role as SubagentRole) ?? "general";
+    if (!SUBAGENT_ROLE_REGISTRY[role]) {
+      throw new Error(
+        `Invalid subagent role "${config.role}". Must be one of: ${Object.keys(SUBAGENT_ROLE_REGISTRY).join(", ")}`,
+      );
+    }
+    const roleConfig = SUBAGENT_ROLE_REGISTRY[role];
+
     // ── Create conversation ─────────────────────────────────────────
     const subagentId = uuid();
     const conversationRecord = bootstrapConversation({
       conversationType: "background",
+      source: "subagent",
       origin: "subagent",
       systemHint: `Subagent: ${config.label}`,
     });
@@ -141,7 +196,7 @@ export class SubagentManager {
 
     const systemPrompt =
       config.systemPromptOverride ??
-      buildSubagentSystemPrompt({ ...config, id: subagentId });
+      buildSubagentSystemPrompt({ ...config, id: subagentId }, role);
     const maxTokens = appConfig.maxTokens;
     const workingDir = getSandboxWorkingDir();
 
@@ -190,14 +245,45 @@ export class SubagentManager {
       workingDir,
       this.broadcastToAllClients, // forward parent's broadcast so tool side-effects (e.g. app_files_changed) reach all clients
       memoryPolicy,
+      undefined, // sharedCesClient
+      undefined, // speedOverride
+      "5m", // cacheTtl — subagents run tight tool-use loops, 5m is always hot
     );
 
     // Mark conversation as having no direct client — it routes through parent.
     // This ensures interactive prompts (host attachment reads) fail fast.
     conversation.updateClient(wrappedSendToClient, true);
+    conversation.setIsSubagent(true);
+
+    // Apply role-based tool filter if the role defines one.
+    if (roleConfig.allowedTools) {
+      conversation.setSubagentAllowedTools(new Set(roleConfig.allowedTools));
+    }
+
+    // Pre-activate skills defined by the role config, merged with any caller-provided skill IDs.
+    const mergedSkillIds = mergeSkillIds(
+      roleConfig.skillIds,
+      config.preactivatedSkillIds,
+    );
+    if (mergedSkillIds.length > 0) {
+      conversation.setPreactivatedSkillIds(mergedSkillIds);
+    }
 
     managed.conversation = conversation;
     this.subagents.set(subagentId, managed);
+    const labelKey = `${config.parentConversationId}:${config.label.toLowerCase().trim()}`;
+    if (this.labelIndex.has(labelKey)) {
+      log.warn(
+        {
+          label: config.label,
+          parentConversationId: config.parentConversationId,
+          existingSubagentId: this.labelIndex.get(labelKey),
+          newSubagentId: subagentId,
+        },
+        "Label collision: new subagent overwrites label index entry (previous subagent still accessible by UUID)",
+      );
+    }
+    this.labelIndex.set(labelKey, subagentId);
 
     // Track parent → child relationship.
     if (!this.parentToChildren.has(config.parentConversationId)) {
@@ -240,25 +326,26 @@ export class SubagentManager {
     const managed = this.subagents.get(subagentId);
     if (!managed) return;
 
+    // Capture the live conversation — it is non-null at this point because
+    // spawn() sets it before firing runSubagent.
+    const conversation = managed.conversation!;
+
     // 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.conversation.sendToClient;
+    const onEvent = conversation.sendToClient;
 
     try {
       // Send the objective as the first user message and process it.
-      const messageId = await managed.conversation.persistUserMessage(
-        objective,
-        [],
-      );
-      await managed.conversation.runAgentLoop(objective, messageId, onEvent);
+      const messageId = await conversation.persistUserMessage(objective, []);
+      await conversation.runAgentLoop(objective, messageId, onEvent);
 
       // Agent loop completed successfully.
       // Copy usage stats from the conversation before sending status (which includes usage).
-      managed.state.usage = { ...managed.conversation.usageStats };
+      managed.state.usage = { ...conversation.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();
@@ -267,21 +354,40 @@ export class SubagentManager {
         log.info({ subagentId }, "Subagent completed");
 
         // Notify the parent conversation so the LLM can call subagent_read.
-        this.notifyParent(managed, "completed", getSender());
+        this.notifyParentTerminal(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.conversation.usageStats };
+      // Copy usage from the captured conversation reference — managed.conversation
+      // may have been nulled by an external dispose() before catch runs.
+      managed.state.usage = { ...conversation.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());
+        this.notifyParentTerminal(managed, "failed", getSender());
       }
 
       log.error({ subagentId, err }, "Subagent failed");
+    } finally {
+      // Release the heavyweight Conversation — output is already persisted in DB.
+      // runAgentLoop fires drainQueue without awaiting it, and drainQueue shift()s
+      // the next item synchronously — so both hasQueuedMessages() and
+      // isProcessing() can return false while a drain is still active.  Use the
+      // hadEnqueuedMessages flag (set in sendMessage) to detect this case and
+      // defer the release to the TTL sweep rather than tearing down mid-drain.
+      if (managed.hadEnqueuedMessages) {
+        log.debug(
+          { subagentId },
+          "Deferring conversation release — messages were enqueued during run",
+        );
+        managed.retainedUntil = Date.now() + TERMINAL_RETENTION_MS;
+        this.ensureSweepRunning();
+      } else {
+        this.releaseConversation(managed);
+      }
     }
   }
 
@@ -312,7 +418,7 @@ export class SubagentManager {
       return false;
     }
 
-    managed.conversation.abort();
+    managed.conversation?.abort();
     managed.state.completedAt = Date.now();
     if (parentSendToClient) {
       // Route the status update through the stored parent sender so the
@@ -393,7 +499,8 @@ export class SubagentManager {
 
     const managed = this.subagents.get(subagentId);
     if (!managed) return "not_found";
-    if (TERMINAL_STATUSES.has(managed.state.status)) return "terminal";
+    if (TERMINAL_STATUSES.has(managed.state.status) || !managed.conversation)
+      return "terminal";
 
     const onEvent = managed.conversation.sendToClient;
     const requestId = uuid();
@@ -408,13 +515,15 @@ export class SubagentManager {
     if (result.rejected) {
       return "sent"; // error event already delivered via onEvent
     }
+    if (result.queued) {
+      managed.hadEnqueuedMessages = true;
+    }
     if (!result.queued) {
-      // Conversation is idle — send directly.  Fire-and-forget so we don't block.
-      const messageId = await managed.conversation.persistUserMessage(
-        trimmed,
-        [],
-      );
-      managed.conversation
+      // Capture conversation before the await — managed.conversation may be
+      // nulled by an external dispose() while persistUserMessage is awaited.
+      const conversation = managed.conversation;
+      const messageId = await conversation.persistUserMessage(trimmed, []);
+      conversation
         .runAgentLoop(trimmed, messageId, onEvent)
         .catch((err) => {
           log.error({ subagentId, err }, "Subagent message processing failed");
@@ -429,6 +538,15 @@ export class SubagentManager {
     return this.subagents.get(subagentId)?.state;
   }
 
+  getByLabel(
+    label: string,
+    parentConversationId: string,
+  ): SubagentState | undefined {
+    const key = `${parentConversationId}:${label.toLowerCase().trim()}`;
+    const id = this.labelIndex.get(key);
+    return id ? this.getState(id) : undefined;
+  }
+
   getChildrenOf(parentConversationId: string): SubagentState[] {
     const children = this.parentToChildren.get(parentConversationId);
     if (!children) return [];
@@ -465,6 +583,24 @@ export class SubagentManager {
 
   // ── Cleanup ───────────────────────────────────────────────────────────
 
+  /**
+   * Release the live Conversation from a terminal subagent, keeping only
+   * lightweight metadata (state, config, usage) for later queries.
+   * The conversation's output is already persisted in the database.
+   */
+  private releaseConversation(managed: ManagedSubagent): void {
+    if (!managed.conversation) return;
+    managed.conversation.dispose();
+    managed.conversation = null;
+    managed.retainedUntil = Date.now() + TERMINAL_RETENTION_MS;
+    this.ensureSweepRunning();
+
+    log.debug(
+      { subagentId: managed.state.config.id },
+      "Released live conversation for terminal subagent",
+    );
+  }
+
   /**
    * Dispose a subagent and remove it from tracking.
    * Should be called after the subagent reaches a terminal state
@@ -474,12 +610,24 @@ export class SubagentManager {
     const managed = this.subagents.get(subagentId);
     if (!managed) return;
 
-    if (!TERMINAL_STATUSES.has(managed.state.status)) {
-      managed.conversation.abort();
+    if (managed.conversation) {
+      if (!TERMINAL_STATUSES.has(managed.state.status)) {
+        managed.conversation.abort();
+      }
+      managed.conversation.dispose();
+      managed.conversation = null;
     }
-    managed.conversation.dispose();
     this.subagents.delete(subagentId);
 
+    // Remove from label index only if it still maps to this subagent
+    // (guards against stale delete when a newer subagent reused the label).
+    const label = managed.state.config.label;
+    const parentConvId = managed.state.config.parentConversationId;
+    const labelKey = `${parentConvId}:${label.toLowerCase().trim()}`;
+    if (this.labelIndex.get(labelKey) === subagentId) {
+      this.labelIndex.delete(labelKey);
+    }
+
     // Remove from parent tracking.
     const parentId = managed.state.config.parentConversationId;
     const siblings = this.parentToChildren.get(parentId);
@@ -493,11 +641,71 @@ export class SubagentManager {
 
   /** Dispose all subagents. Called on daemon shutdown. */
   disposeAll(): void {
+    this.stopSweep();
     for (const id of [...this.subagents.keys()]) {
       this.dispose(id);
     }
   }
 
+  // ── TTL sweep for terminal metadata ──────────────────────────────────
+
+  private sweepTimer?: ReturnType<typeof setInterval>;
+
+  private ensureSweepRunning(): void {
+    if (this.sweepTimer) return;
+    this.sweepTimer = setInterval(
+      () => this.sweepTerminal(),
+      SWEEP_INTERVAL_MS,
+    );
+    // Don't let the sweep timer keep the process alive.
+    if (
+      this.sweepTimer &&
+      typeof this.sweepTimer === "object" &&
+      "unref" in this.sweepTimer
+    ) {
+      (this.sweepTimer as { unref: () => void }).unref();
+    }
+  }
+
+  private stopSweep(): void {
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = undefined;
+    }
+  }
+
+  /** Remove terminal entries whose retention period has expired. */
+  private sweepTerminal(): void {
+    const now = Date.now();
+    const expired: string[] = [];
+    for (const [id, managed] of this.subagents) {
+      if (!managed.retainedUntil || now < managed.retainedUntil) continue;
+      // If the retention window has expired and the conversation is still live,
+      // release it now — the drain has had ample time to complete.
+      if (managed.conversation) {
+        this.releaseConversation(managed);
+        // releaseConversation resets retainedUntil to keep metadata around for
+        // another window; the entry will be swept on the next pass.
+        continue;
+      }
+      expired.push(id);
+    }
+    for (const id of expired) {
+      log.debug(
+        { subagentId: id },
+        "Sweeping expired terminal subagent metadata",
+      );
+      this.dispose(id);
+    }
+    // Stop the timer if there are no more entries to sweep.
+    const hasTerminal = [...this.subagents.values()].some(
+      (s) => s.retainedUntil !== undefined,
+    );
+    if (!hasTerminal) {
+      this.stopSweep();
+    }
+  }
+
   // ── Internals ─────────────────────────────────────────────────────────
 
   private setStatus(
@@ -529,11 +737,82 @@ export class SubagentManager {
     } as ServerMessage);
   }
 
+  // ── Child → Parent notification ────────────────────────────────────
+
+  /**
+   * Look up the parent info for a child conversation.
+   * Returns undefined if the conversationId doesn't belong to a subagent.
+   */
+  getParentInfo(childConversationId: string):
+    | {
+        parentConversationId: string;
+        subagentId: string;
+        label: string;
+        parentSendToClient: (msg: ServerMessage) => void;
+      }
+    | undefined {
+    for (const [subagentId, managed] of this.subagents) {
+      if (managed.state.conversationId === childConversationId) {
+        return {
+          parentConversationId: managed.state.config.parentConversationId,
+          subagentId,
+          label: managed.state.config.label,
+          parentSendToClient: managed.parentSendToClient,
+        };
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Send a notification from a running subagent to its parent conversation.
+   * Returns true if the notification was sent, false if the child is not a
+   * subagent, is in a terminal state, or the parent callback is not wired.
+   */
+  notifyParent(
+    childConversationId: string,
+    message: string,
+    urgency: string,
+  ): boolean {
+    const info = this.getParentInfo(childConversationId);
+    if (!info) return false;
+
+    const managed = this.subagents.get(info.subagentId);
+    if (!managed || TERMINAL_STATUSES.has(managed.state.status)) return false;
+    if (!this.onSubagentFinished) return false;
+
+    let notificationString = `[Subagent "${info.label}" — ${urgency}] ${message}`;
+    if (urgency === "blocked") {
+      notificationString +=
+        "\nUse subagent_message to send guidance to this subagent.";
+    }
+
+    try {
+      this.onSubagentFinished(
+        info.parentConversationId,
+        notificationString,
+        info.parentSendToClient,
+        {
+          subagentId: info.subagentId,
+          label: info.label,
+          status: "running",
+        },
+      );
+      return true;
+    } catch (err) {
+      log.error(
+        { subagentId: info.subagentId, err },
+        "Failed to notify parent from subagent",
+      );
+      return false;
+    }
+  }
+
   /**
    * Inject a completion/failure notification into the parent conversation
    * so the LLM automatically informs the user.
    */
-  private notifyParent(
+  private notifyParentTerminal(
     managed: ManagedSubagent,
     outcome: "completed" | "failed",
     parentSendToClient: (msg: ServerMessage) => void,

package/src/subagent/types.ts

@@ -41,6 +41,8 @@ export interface SubagentConfig {
   preactivatedSkillIds?: string[];
   /** Whether the parent should present the result to the user. Defaults to true. */
   sendResultToUser?: boolean;
+  /** Optional role for the subagent. Defaults handled by consumers. */
+  role?: SubagentRole;
 }
 
 // ── State (runtime) ─────────────────────────────────────────────────────
@@ -66,3 +68,69 @@ export const SUBAGENT_LIMITS = {
   /** Max nesting depth (1 = no nested subagents). */
   maxDepth: 1,
 } as const;
+
+// ── Roles ───────────────────────────────────────────────────────────────
+
+export type SubagentRole = "general" | "researcher" | "coder" | "planner";
+
+export interface SubagentRoleConfig {
+  /**
+   * When defined, only these tools are visible to the subagent.
+   * `undefined` means no filter (all tools available).
+   */
+  allowedTools?: string[];
+  /** Skill IDs to pre-activate on the subagent conversation. */
+  skillIds: string[];
+  /** Role-specific text prepended to the subagent system prompt. */
+  systemPromptPreamble: string;
+}
+
+export const SUBAGENT_ROLE_REGISTRY: Record<SubagentRole, SubagentRoleConfig> =
+  {
+    general: {
+      allowedTools: undefined,
+      skillIds: [],
+      systemPromptPreamble:
+        "You are a general-purpose subagent. Complete the delegated task thoroughly and concisely.",
+    },
+    researcher: {
+      allowedTools: [
+        "web_search",
+        "web_fetch",
+        "file_read",
+        "file_list",
+        "recall",
+        "notify_parent",
+      ],
+      skillIds: [],
+      systemPromptPreamble:
+        "You are a research-focused subagent with read-only access. Search the web, read files, and recall memories. You cannot write files or run shell commands.",
+    },
+    coder: {
+      allowedTools: [
+        "bash",
+        "file_read",
+        "file_write",
+        "file_edit",
+        "web_search",
+        "recall",
+        "notify_parent",
+      ],
+      skillIds: [],
+      systemPromptPreamble:
+        "You are a code-focused subagent with file and shell access. Read, write, and edit files, and run shell commands.",
+    },
+    planner: {
+      allowedTools: [
+        "file_read",
+        "file_list",
+        "web_search",
+        "web_fetch",
+        "recall",
+        "notify_parent",
+      ],
+      skillIds: [],
+      systemPromptPreamble:
+        "You are an analysis-focused subagent with read-only access. Read files, search the web, and synthesize findings. You cannot write files or run shell commands.",
+    },
+  };

package/src/tasks/task-runner.ts

@@ -60,10 +60,10 @@ export async function runTask(
 
   const run = createTaskRun(task.id);
   const conversation = bootstrapConversation({
-    // Schedule-triggered tasks use "standard" so they appear in the sidebar's
-    // Scheduled section; non-schedule tasks use "background" to stay out of
-    // the main conversation list.
-    conversationType: opts.source === "schedule" ? undefined : "background",
+    // Schedule-triggered tasks use "scheduled" so they don't crowd out
+    // interactive conversations in the main list; non-schedule tasks use
+    // "background" to stay out of the list entirely.
+    conversationType: opts.source === "schedule" ? "scheduled" : "background",
     source: opts.source === "schedule" ? "schedule" : "task",
     scheduleJobId: opts.scheduleJobId,
     groupId:

package/src/tools/apps/executors.ts

@@ -277,10 +277,10 @@ export interface AppRefreshInput {
   app_id: string;
 }
 
-export function executeAppRefresh(
+export async function executeAppRefresh(
   input: AppRefreshInput,
   store: AppStore,
-): ExecutorResult {
+): Promise<ExecutorResult> {
   const app = store.getApp(input.app_id);
   if (!app) {
     return {
@@ -289,9 +289,34 @@ export function executeAppRefresh(
     };
   }
 
-  // Empty update bumps updatedAt timestamp, triggering recompilation and
-  // surface refresh on the client side.
+  // Empty update bumps updatedAt timestamp, triggering surface refresh on
+  // the client side.
   const updated = store.updateApp(input.app_id, {});
+
+  // Multifile apps need an explicit compile so the LLM sees any errors
+  // (bad imports, syntax issues, etc.) instead of silently serving the
+  // stale scaffold placeholder from the initial app_create.
+  if (app.formatVersion === 2) {
+    const appDir = getAppDirPath(input.app_id);
+    const compileResult = await compileApp(appDir);
+    return {
+      content: JSON.stringify({
+        refreshed: true,
+        appId: updated.id,
+        name: updated.name,
+        compiled: compileResult.ok,
+        ...(compileResult.ok
+          ? { compile_duration_ms: compileResult.durationMs }
+          : {
+              compile_errors: compileResult.errors,
+              compile_warnings: compileResult.warnings,
+              compile_duration_ms: compileResult.durationMs,
+            }),
+      }),
+      isError: false,
+    };
+  }
+
   return {
     content: JSON.stringify({
       refreshed: true,