@vellumai/assistant 0.10.2 → 0.10.3-dev.202606252046.9075fd5

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 ─────────────────────────────────────────────────────────────
@@ -553,6 +765,15 @@ export class SubagentManager {
       ),
     );
     managed.state.completedAt = Date.now();
+    // Capture the conversation's latest usage before emitting the terminal
+    // status. `subagent_status_changed` ships `state.usage`, and the abort path
+    // (unlike the completion/failure paths, which sync at agent-loop exit) would
+    // otherwise send the {0,0,0} init usage — zeroing the client's token counts
+    // even though those tokens were already spent. `usageStats` accrues per LLM
+    // turn (see conversation-usage.ts), so this is the most recent total.
+    if (managed.conversation) {
+      managed.state.usage = { ...managed.conversation.usageStats };
+    }
     if (parentSendToClient) {
       // Route the status update through the stored parent sender so the
       // owning conversation's UI chip updates, even when the abort comes from a

package/src/subagent/types.ts

@@ -116,7 +116,8 @@ export type SubagentRole =
   | "researcher"
   | "coder"
   | "planner"
-  | "investigator";
+  | "investigator"
+  | "advisor";
 
 export interface SubagentRoleConfig {
   /**
@@ -180,7 +181,7 @@ export const SUBAGENT_ROLE_REGISTRY: Record<SubagentRole, SubagentRoleConfig> =
     },
     investigator: {
       allowedTools: [
-        "bash",
+        "code_search",
         "file_read",
         "file_list",
         "web_search",
@@ -191,11 +192,17 @@ export const SUBAGENT_ROLE_REGISTRY: Record<SubagentRole, SubagentRoleConfig> =
       skillIds: [],
       systemPromptPreamble: [
         "You are an investigation-focused subagent for root-cause analysis: debugging, log forensics, and tracing behavior across code.",
-        "Your shell access is for read-only investigation (grep, find, reading files and logs) — do not modify files or system state.",
-        "Working method: read whole files instead of many small line-range slices; prefer broad searches (e.g. grep -rn across a directory) over one-symbol-at-a-time queries.",
+        "You have read-only investigation tools only — there is no shell. Use code_search to search file contents across directories, file_list to enumerate paths, and file_read to read whole files and logs. You cannot modify files or system state.",
+        "Working method: read whole files instead of many small line-range slices; prefer broad code_search queries across a directory over one-symbol-at-a-time queries.",
         "Send notify_parent (urgency 'important') as soon as each finding is confirmed, so progress survives interruption.",
         "Your final message must be a compact root-cause report with these sections: Symptom, Root cause, Evidence (file:line references), Suggested fix, Open questions.",
         "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/telemetry/types.ts

@@ -391,6 +391,38 @@ export interface SkillLoadedTelemetryEvent extends ModelTelemetryEventBase {
   conversation_id: string | null;
 }
 
+/**
+ * Watchdog health event — one per watchdog check firing. The daemon's
+ * watchdog observes liveness/health signals (event-loop block, stream-idle
+ * stalls, restarts, ...) and emits one event per check firing.
+ *
+ * Deliberately minimal and forward-compatible, mirroring the platform
+ * `WatchdogTelemetryEventSerializer`:
+ *
+ *   - `check_name` — which watchdog check fired. Open string set (not a
+ *     closed enum) so the daemon can introduce a new check without a
+ *     coordinated serializer release; it is the primary group-by dimension
+ *     downstream. The infrastructure admin chart filters this to
+ *     `event_loop_blocked`.
+ *   - `value` — the single measured magnitude for the check (block ms, idle
+ *     ms, ...). Nullable: not every check carries a scalar. The platform
+ *     coerces ints to float, so the daemon need not distinguish.
+ *   - `detail` — open JSON bag for any extra fields the daemon attaches
+ *     (reason codes, secondary numbers, a human message) without a
+ *     platform-coordinated schema change. Null when the daemon attaches
+ *     nothing. Bounded server-side (4096 bytes serialized); an oversize bag
+ *     rejects only the single event, never the batch.
+ *
+ * Metadata only — no conversation content. Dedupe downstream on
+ * `daemon_event_id` (the daemon retries a batch on transient POST failure).
+ */
+export interface WatchdogTelemetryEvent extends TelemetryEventBase {
+  type: "watchdog";
+  check_name: string;
+  value: number | null;
+  detail: Record<string, unknown> | null;
+}
+
 /** Discriminated union of all telemetry event types. */
 export type TelemetryEvent =
   | LlmUsageTelemetryEvent
@@ -399,4 +431,5 @@ export type TelemetryEvent =
   | OnboardingTelemetryEvent
   | AuthFallbackTelemetryEvent
   | ToolExecutedTelemetryEvent
-  | SkillLoadedTelemetryEvent;
+  | SkillLoadedTelemetryEvent
+  | WatchdogTelemetryEvent;

package/src/telemetry/usage-telemetry-reporter.test.ts

@@ -1547,11 +1547,11 @@ describe("UsageTelemetryReporter", () => {
     // No HTTP call should have been made
     expect(mockFetch).not.toHaveBeenCalled();
 
-    // All 7 timestamp watermarks should have been advanced, and all 7 ID
+    // All 8 timestamp watermarks should have been advanced, and all 8 ID
     // watermarks pinned to the high-sorting sentinel (a truthy value keeps
     // the compound-cursor branch active while closing its same-millisecond
     // arm against opt-out rows).
-    expect(mockSetMemoryCheckpoint).toHaveBeenCalledTimes(14);
+    expect(mockSetMemoryCheckpoint).toHaveBeenCalledTimes(16);
 
     const calls = mockSetMemoryCheckpoint.mock.calls;
     const keys = calls.map((c) => c[0]);
@@ -1563,6 +1563,7 @@ describe("UsageTelemetryReporter", () => {
       "auth_fallback",
       "tool_executed",
       "skill_loaded",
+      "watchdog",
     ];
     for (const eventType of eventTypes) {
       expect(keys).toContain(`telemetry:${eventType}:last_reported_at`);