@vellumai/assistant 0.10.3 → 0.10.4-staging.1

package/src/subagent/manager.ts

@@ -24,6 +24,7 @@ import { wrapWithCallSiteRouting } from "../providers/call-site-routing.js";
 import { resolveDefaultProvider } from "../providers/connection-resolution.js";
 import { RateLimitProvider } from "../providers/ratelimit.js";
 import { listProviders } from "../providers/registry.js";
+import type { Message, TextContent } from "../providers/types.js";
 import { createAbortReason } from "../util/abort-reasons.js";
 import { ProviderNotConfiguredError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
@@ -58,6 +59,38 @@ export function mergeSkillIds(
   return [...new Set([...roleSkillIds, ...(configSkillIds ?? [])])];
 }
 
+// ── Final-text extraction helper ────────────────────────────────────────
+
+/**
+ * Concatenate the `text` blocks of the conversation's trailing assistant
+ * message. Used by `spawnAndAwait` to return the child's final synthesis to
+ * the awaiting caller. Returns an empty string when the conversation has no
+ * assistant message or the final assistant message carries no text blocks
+ * (e.g. it ended on a tool_use).
+ */
+function extractFinalAssistantText(messages: Message[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message.role !== "assistant") continue;
+    return message.content
+      .filter((block): block is TextContent => block.type === "text")
+      .map((block) => block.text)
+      .join("");
+  }
+  return "";
+}
+
+/**
+ * Pull the user-visible text out of a streaming delta event, or null for any
+ * other event type. Used by the synchronous `onText` tap to forward
+ * `assistant_text_delta` / `assistant_thinking_delta` chunks to the caller.
+ */
+function extractDeltaText(msg: ServerMessage): string | null {
+  if (msg.type === "assistant_text_delta") return msg.text;
+  if (msg.type === "assistant_thinking_delta") return msg.thinking;
+  return null;
+}
+
 // ── Default subagent system prompt ──────────────────────────────────────
 
 function buildSubagentSystemPrompt(
@@ -110,6 +143,19 @@ interface ManagedSubagent {
    * the release to the TTL sweep rather than tearing down mid-drain.
    */
   hadEnqueuedMessages?: boolean;
+  /**
+   * Set on the synchronous `spawnAndAwait` path. When true, `runSubagent`
+   * skips the terminal parent-injection (`notifyParentTerminal`) — the awaiting
+   * caller receives the child's final text directly, so re-injecting a
+   * "read the result" notification into the parent would be redundant noise.
+   */
+  synchronous?: boolean;
+  /**
+   * Optional text tap for the synchronous path. When set, `wrappedSendToClient`
+   * forwards each `assistant_text_delta` / `assistant_thinking_delta` chunk to
+   * this callback IN ADDITION to the normal `subagent_event` envelope.
+   */
+  onText?: (chunk: string) => void;
 }
 
 export interface SubagentNotificationInfo {
@@ -121,6 +167,21 @@ export interface SubagentNotificationInfo {
   objective?: string;
 }
 
+/**
+ * Thrown by `spawnAndAwait` when the run is aborted (e.g. an external timeout)
+ * before reaching a terminal `completed` state. Carries `partialText` — the
+ * child's trailing assistant text captured at the moment of abort — so a caller
+ * that times out a long generation can still surface the partial result instead
+ * of discarding it. Extends `Error` with the same legacy message, so callers
+ * that only inspect `.message` keep working.
+ */
+export class SubagentAbortedError extends Error {
+  constructor(readonly partialText: string) {
+    super("Subagent run aborted before completion.");
+    this.name = "SubagentAbortedError";
+  }
+}
+
 export class SubagentManager {
   /** subagentId → ManagedSubagent */
   private subagents = new Map<string, ManagedSubagent>();
@@ -145,6 +206,30 @@ export class SubagentManager {
     config: Omit<SubagentConfig, "id">,
     parentSendToClient: (msg: ServerMessage) => void,
   ): Promise<string> {
+    const { subagentId } = await this.setUpSubagent(config, parentSendToClient);
+
+    // ── 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: shared spawn setup ──────────────────────────────────────
+
+  /**
+   * Perform all spawn-time setup shared by `spawn` and `spawnAndAwait`:
+   * enforce the depth limit, resolve role/provider/system prompt, construct
+   * the child Conversation, register it, and emit the `subagent_spawned`
+   * event. Does NOT start the agent loop — the caller decides whether to run
+   * fire-and-forget (`spawn`) or awaited (`spawnAndAwait`).
+   */
+  private async setUpSubagent(
+    config: Omit<SubagentConfig, "id">,
+    parentSendToClient: (msg: ServerMessage) => void,
+    opts?: { synchronous?: boolean; onText?: (chunk: string) => void },
+  ): Promise<{ subagentId: string; managed: ManagedSubagent }> {
     // ── Limit checks ────────────────────────────────────────────────
 
     // Depth check: prevent subagents from spawning nested subagents.
@@ -159,17 +244,20 @@ export class SubagentManager {
 
     // ── Resolve role ─────────────────────────────────────────────────
     const isFork = config.fork === true;
-    let role: SubagentRole = (config.role as SubagentRole) ?? "general";
+    const role: SubagentRole = (config.role as SubagentRole) ?? "general";
     if (isFork && role !== "general") {
+      // A context-inheriting subagent normally keeps the parent's `general`
+      // role so its KV cache stays aligned with the parent conversation. An
+      // explicit non-general role opts out of that alignment on purpose
+      // (e.g. the advisor role running on a stronger profile), so honor it.
       log.warn(
         {
           requestedRole: role,
           parentConversationId: config.parentConversationId,
           label: config.label,
         },
-        "Fork requested with non-general role — forcing general to preserve KV cache alignment",
+        "Fork requested with non-general role — caller opted out of parent KV-cache alignment",
       );
-      role = "general";
     }
     if (!SUBAGENT_ROLE_REGISTRY[role]) {
       throw new Error(
@@ -219,19 +307,21 @@ export class SubagentManager {
 
     let systemPrompt: string;
     if (isFork) {
-      // Forks use the parent's system prompt directly — no subagent preamble.
-      if (config.parentSystemPrompt) {
-        systemPrompt = config.parentSystemPrompt;
-      } else {
-        const resolved = parentConversation?.getCurrentSystemPrompt();
-        if (!resolved) {
-          throw new Error(
-            "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
-              "nor findConversation yielded one.",
-          );
-        }
-        systemPrompt = resolved;
+      // Forks default to the parent's system prompt verbatim — no subagent
+      // preamble — so the KV cache stays aligned with the parent. An explicit
+      // `systemPromptOverride` opts out of that alignment and takes precedence
+      // (e.g. the advisor role framing the inherited context as advice).
+      const resolved =
+        config.systemPromptOverride ??
+        config.parentSystemPrompt ??
+        parentConversation?.getCurrentSystemPrompt();
+      if (!resolved) {
+        throw new Error(
+          "Fork spawn requires a parent system prompt but neither config.parentSystemPrompt " +
+            "nor findConversation yielded one.",
+        );
       }
+      systemPrompt = resolved;
     } else {
       systemPrompt =
         config.systemPromptOverride ??
@@ -279,11 +369,20 @@ export class SubagentManager {
       conversation: null! as Conversation,
       state,
       parentSendToClient,
+      ...(opts?.synchronous ? { synchronous: true } : {}),
+      ...(opts?.onText ? { onText: opts.onText } : {}),
     };
 
     // Wrap sendToClient to envelope all events with the subagent ID.
     // Reads from managed.parentSendToClient so reconnects are picked up.
     const wrappedSendToClient = (msg: ServerMessage): void => {
+      // Tap streaming text/thinking deltas for the synchronous caller (if any),
+      // in addition to the normal envelope below. Reads from managed.onText so
+      // the synchronous path can forward chunks without altering event routing.
+      if (managed.onText) {
+        const text = extractDeltaText(msg);
+        if (text) managed.onText(text);
+      }
       managed.parentSendToClient({
         type: "subagent_event",
         subagentId,
@@ -298,7 +397,16 @@ export class SubagentManager {
       systemPrompt,
       wrappedSendToClient,
       workingDir,
-      { maxTokens, cacheTtl: "5m" },
+      {
+        maxTokens,
+        cacheTtl: "5m",
+        // The advisor consult runs tool-less for CLIENT tools but should ground
+        // its guidance with provider-native web search when the resolved
+        // provider supports it. This is a server tool the provider runs itself,
+        // so it stays one-shot — no client tool surfaced, allowlist unchanged.
+        // Other roles keep the default (no native search appended).
+        ...(role === "advisor" ? { enableNativeWebSearch: true } : {}),
+      },
     );
 
     // Mark conversation as having no direct client — it routes through parent.
@@ -325,16 +433,19 @@ export class SubagentManager {
       conversation.setAssistantId(parentConversation.assistantId);
     }
 
-    if (isFork) {
-      // Force the fork to use the parent's system prompt as-is without dynamic rebuild.
-      // This ensures KV cache alignment with the parent conversation.
+    if (isFork && !config.systemPromptOverride) {
+      // A verbatim-prompt fork pins the parent's system prompt as-is, skipping
+      // the dynamic rebuild so the KV cache stays aligned with the parent. A
+      // fork that supplies its own override prompt opts out of that alignment,
+      // so leave `hasSystemPromptOverride` at its default.
       conversation.hasSystemPromptOverride = true;
     }
 
-    // Apply role-based tool filter if the role defines one.
-    // Skip for forks — general role has allowedTools: undefined, and forks
-    // should have the same tool access as the parent.
-    if (!isFork && roleConfig.allowedTools) {
+    // Apply the role's tool allowlist when one is defined. The `general` role
+    // has `allowedTools: undefined`, so default forks (which keep the general
+    // role) are unaffected; a fork carrying an explicit role gets its
+    // allowlist applied like any other subagent.
+    if (roleConfig.allowedTools) {
       conversation.setSubagentAllowedTools(new Set(roleConfig.allowedTools));
     }
 
@@ -393,12 +504,65 @@ export class SubagentManager {
       "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, managed };
+  }
 
-    return subagentId;
+  // ── Spawn and await (synchronous) ─────────────────────────────────────
+
+  /**
+   * Spawn a subagent and AWAIT its run, resolving to the child's final
+   * assistant text. Unlike `spawn` (fire-and-forget), the caller blocks until
+   * the child reaches a terminal state and receives the text directly — so the
+   * terminal parent-injection (`notifyParentTerminal`) is skipped on this path.
+   *
+   * `opts.signal` aborts the underlying run when triggered (e.g. an external
+   * timeout). `opts.onText` receives each streaming text/thinking chunk in
+   * addition to the normal `subagent_event` envelope.
+   */
+  async spawnAndAwait(
+    config: Omit<SubagentConfig, "id">,
+    parentSendToClient: (msg: ServerMessage) => void,
+    opts?: { signal?: AbortSignal; onText?: (chunk: string) => void },
+  ): Promise<string> {
+    const { subagentId, managed } = await this.setUpSubagent(
+      config,
+      parentSendToClient,
+      { synchronous: true, ...(opts?.onText ? { onText: opts.onText } : {}) },
+    );
+
+    // Wire the external signal to abort the child conversation. If the signal
+    // is already aborted, abort immediately so the run rejects promptly.
+    const signal = opts?.signal;
+    const onAbort = (): void => {
+      // Route through the manager abort path so the subagent is marked terminal
+      // ("aborted") and broadcast as such. A bare conversation.abort() leaves
+      // status non-terminal, so runSubagent's success branch would record the
+      // run as "completed" once runAgentLoop resolves the consumed cancellation.
+      // Suppress the parent notification: the awaiting caller observes the abort
+      // as a thrown rejection, so a "do NOT re-spawn" injection would be
+      // redundant noise.
+      this.abort(subagentId, managed.parentSendToClient, undefined, {
+        suppressNotification: true,
+      });
+    };
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    try {
+      const finalText = await this.runSubagent(subagentId, config.objective);
+      // Surface aborts as a rejection so the caller's timeout path is
+      // observable — but carry the partial text on the error so a caller that
+      // timed out a long generation (e.g. the advisor consult) can still
+      // surface what was produced instead of throwing it away.
+      if (signal?.aborted) {
+        throw new SubagentAbortedError(finalText);
+      }
+      return finalText;
+    } finally {
+      signal?.removeEventListener("abort", onAbort);
+    }
   }
 
   // ── Internal: run the subagent ────────────────────────────────────────
@@ -406,14 +570,31 @@ export class SubagentManager {
   private async runSubagent(
     subagentId: string,
     objective: string,
-  ): Promise<void> {
+  ): Promise<string> {
     const managed = this.subagents.get(subagentId);
-    if (!managed) return;
+    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!;
 
+    // The child's trailing assistant text, captured after runAgentLoop resolves
+    // (before the `finally` releases the conversation). Returned to the
+    // synchronous `spawnAndAwait` caller; the fire-and-forget `spawn` caller
+    // ignores it.
+    let finalText = "";
+
+    // Aborted before the run started (e.g. an already-aborted signal on the
+    // synchronous spawnAndAwait path): the subagent is already terminal. Do not
+    // start the agent loop or reset status back to "running" — but still release
+    // the conversation, exactly as the post-run `finally` does for a terminal
+    // run. The loop never started, so no messages were enqueued; this matches
+    // the finally's non-deferred release branch.
+    if (TERMINAL_STATUSES.has(managed.state.status)) {
+      this.releaseConversation(managed);
+      return finalText;
+    }
+
     // Read the current parent sender so reconnects are picked up.
     const getSender = () => managed.parentSendToClient;
 
@@ -441,7 +622,16 @@ export class SubagentManager {
       // the fork tends to continue the parent conversation instead of
       // pivoting to the task — the inherited context is louder than a bare
       // objective buried after 100k+ tokens of chat history.
-      const message = managed.state.isFork
+      //
+      // The advisor consult is the exception: it is a fork, but its
+      // `systemPromptOverride` already frames the inherited context as advice
+      // ("you are a senior advisor … do not write its final deliverable"), so
+      // the generic "complete this task and return your findings" wrapper would
+      // fight that framing. The advisor's objective is already the bare advice
+      // request (`advisorRequestText()`), so it is sent uncontested.
+      const useForkFraming =
+        managed.state.isFork && managed.state.config.role !== "advisor";
+      const message = useForkFraming
         ? [
             "⎯⎯⎯ FORK TASK ⎯⎯⎯",
             "You have been forked from the parent conversation to execute a specific task.",
@@ -466,6 +656,9 @@ export class SubagentManager {
       });
 
       // Agent loop completed successfully.
+      // Capture the trailing assistant text before any release nulls the
+      // conversation reference. The fire-and-forget caller ignores the return.
+      finalText = extractFinalAssistantText(conversation.messages);
       // Copy usage stats from the conversation before sending status (which includes usage).
       managed.state.usage = { ...conversation.usageStats };
       // Only update state + notify if still non-terminal (guards against abort race).
@@ -476,7 +669,12 @@ export class SubagentManager {
         log.info({ subagentId }, "Subagent completed");
 
         // Notify the parent conversation so the LLM can call subagent_read.
-        this.notifyParentTerminal(managed, "completed");
+        // Skipped on the synchronous path — the awaiting caller receives the
+        // final text directly, so re-injecting a "read the result" prompt
+        // would be redundant noise in the parent.
+        if (!managed.synchronous) {
+          this.notifyParentTerminal(managed, "completed");
+        }
       }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
@@ -489,10 +687,22 @@ export class SubagentManager {
       // Only update status if not already terminal (e.g. aborted).
       if (!TERMINAL_STATUSES.has(managed.state.status)) {
         this.setStatus(subagentId, "failed", getSender(), errorMsg);
-        this.notifyParentTerminal(managed, "failed");
+        // Skip terminal parent-injection on the synchronous path — the failure
+        // surfaces to the awaiting caller as a rejected promise instead.
+        if (!managed.synchronous) {
+          this.notifyParentTerminal(managed, "failed");
+        }
       }
 
       log.error({ subagentId, err }, "Subagent failed");
+
+      // Surface the failure to the synchronous caller. The fire-and-forget
+      // path has no awaiter, so re-throwing there only feeds the `.catch()`
+      // logger in `spawn` — harmless but noisy — so it is confined to the
+      // synchronous path.
+      if (managed.synchronous) {
+        throw err;
+      }
     } finally {
       // Release the heavyweight Conversation — output is already persisted in DB.
       // drainQueue is async: it awaits buildPassthroughBatch (which awaits
@@ -516,6 +726,8 @@ export class SubagentManager {
         this.releaseConversation(managed);
       }
     }
+
+    return finalText;
   }
 
   // ── Abort ─────────────────────────────────────────────────────────────

package/src/subagent/types.ts

@@ -116,7 +116,8 @@ export type SubagentRole =
   | "researcher"
   | "coder"
   | "planner"
-  | "investigator";
+  | "investigator"
+  | "advisor";
 
 export interface SubagentRoleConfig {
   /**
@@ -198,4 +199,10 @@ export const SUBAGENT_ROLE_REGISTRY: Record<SubagentRole, SubagentRoleConfig> =
         "If you approach context limits, stop investigating and produce the report from what you have — a partial report delivered is worth more than a complete investigation lost.",
       ].join(" "),
     },
+    advisor: {
+      allowedTools: [],
+      skillIds: [],
+      systemPromptPreamble:
+        "You are a read-only senior advisor consulted for a one-shot strategic review. Read the inherited conversation, then return focused, high-leverage guidance in a single response. You have no tools — you cannot search, read files, or run commands — so reason from the context you were given.",
+    },
   };

package/src/tools/registry.ts

@@ -1,3 +1,4 @@
+import { isPluginDisabled } from "../plugins/disabled-state.js";
 import { getLogger } from "../util/logger.js";
 import { coreAppProxyTools } from "./apps/definitions.js";
 import { registerAppTools } from "./apps/registry.js";
@@ -556,9 +557,15 @@ export function getMcpToolDefinitions(): Tool[] {
  * {@link getMcpToolDefinitions} so a plugin install behaves like `mcp reload`.
  */
 export function getPluginToolDefinitions(): Tool[] {
-  return Array.from(tools.values()).filter(
-    (t) => ownersByName.get(t.name)?.kind === "plugin",
-  );
+  return Array.from(tools.values()).filter((t) => {
+    const owner = ownersByName.get(t.name);
+    if (owner?.kind !== "plugin") return false;
+    // Filter out tools contributed by disabled plugins at read time so
+    // `assistant plugins disable <name>` takes effect on the next turn
+    // without a daemon restart. Mirrors the `.disabled` sentinel filtering
+    // in `getHooksFor` (plugins/registry.ts).
+    return !isPluginDisabled(owner.id);
+  });
 }
 
 /**

package/src/tools/subagent/consult-deadline.ts

@@ -0,0 +1,49 @@
+/**
+ * A progress-aware deadline for the synchronous advisor consult.
+ *
+ * A reasoning advisor profile spends most of its window *thinking*, streaming
+ * reasoning tokens the whole time. A fixed wall-clock ceiling would cut it off
+ * mid-thought, so this aborts only after the consult goes `idleMs` without any
+ * streamed token (thinking or text) — i.e. genuine silence — with an absolute
+ * `maxMs` backstop so a runaway or looping stream can't block the parent
+ * forever.
+ *
+ * Usage: combine `signal` with the caller's own signal, call `recordProgress()`
+ * on every streamed chunk, and `dispose()` once the consult settles.
+ */
+export interface ConsultDeadline {
+  /** Aborts when the idle window lapses or the absolute max elapses. */
+  readonly signal: AbortSignal;
+  /** Reset the idle window — call on every streamed chunk (thinking or text). */
+  recordProgress(): void;
+  /** Clear both timers; call once the consult settles (success or failure). */
+  dispose(): void;
+}
+
+export function createConsultDeadline(opts: {
+  idleMs: number;
+  maxMs: number;
+}): ConsultDeadline {
+  const controller = new AbortController();
+  let idleTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const recordProgress = (): void => {
+    // Once aborted, don't re-arm — the consult is already being torn down.
+    if (controller.signal.aborted) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => controller.abort(), opts.idleMs);
+  };
+
+  // Absolute backstop, independent of streaming progress.
+  const maxTimer = setTimeout(() => controller.abort(), opts.maxMs);
+
+  // Arm the idle window immediately so time-to-first-token is bounded too.
+  recordProgress();
+
+  const dispose = (): void => {
+    if (idleTimer) clearTimeout(idleTimer);
+    clearTimeout(maxTimer);
+  };
+
+  return { signal: controller.signal, recordProgress, dispose };
+}