@vellumai/assistant 0.9.0-dev.202606181513.fd39213 → 0.9.0-dev.202606181735.ae6e1d8

package/src/plugins/defaults/advisor/consult.ts

@@ -0,0 +1,76 @@
+/**
+ * Run one advisor consult.
+ *
+ * Routed entirely through the assistant's own inference: `getConfiguredProvider`
+ * resolves the general-purpose `inference` call site (with the advisor profile
+ * applied as an `overrideProfile`) to a provider/model/credentials from the
+ * configured profiles — managed-proxy or BYOK, no separate API key. The consult
+ * then runs a tool-less, capped one-shot completion through `provider.sendMessage`
+ * and returns the text.
+ */
+
+import type { LLMCallSite } from "../../../config/schemas/llm.js";
+import {
+  extractAllText,
+  getConfiguredProvider,
+  userMessage,
+} from "../../../providers/provider-send-message.js";
+import type { Message } from "../../../providers/types.js";
+import { ADVISOR_CONFIG } from "./config.js";
+import { advisorRequestText, buildAdvisorSystem } from "./steering.js";
+import { toAdvisorMessages } from "./transcript.js";
+
+// The general-purpose call site; the model is selected via `overrideProfile`.
+const ADVISOR_CALL_SITE: LLMCallSite = "inference";
+
+export interface ConsultParams {
+  systemPrompt: string | null;
+  messages: ReadonlyArray<Message>;
+  signal?: AbortSignal;
+}
+
+/** Combine the caller's signal with a consult timeout. */
+function withTimeout(signal: AbortSignal | undefined, ms: number): AbortSignal {
+  const timeout = AbortSignal.timeout(ms);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+/**
+ * Returns the advisor's guidance text, or a short benign notice when the
+ * advisor can't run. Callers should surface the string as a non-error tool
+ * result so the executor continues regardless.
+ */
+export async function consultAdvisor(params: ConsultParams): Promise<string> {
+  const history = toAdvisorMessages(params.messages);
+  if (history.length === 0) {
+    return "(advisor: no conversation context is available yet)";
+  }
+
+  const provider = await getConfiguredProvider(ADVISOR_CALL_SITE, {
+    overrideProfile: ADVISOR_CONFIG.profile,
+  });
+  if (!provider) {
+    return "(advisor unavailable: no inference provider is configured)";
+  }
+
+  // Append the consult instruction as the final user turn, then run a
+  // tool-less, capped completion through the resolved provider.
+  const messages: Message[] = [
+    ...history,
+    userMessage(advisorRequestText(ADVISOR_CONFIG.wordLimit)),
+  ];
+
+  const response = await provider.sendMessage(messages, {
+    systemPrompt: buildAdvisorSystem(params.systemPrompt),
+    config: {
+      callSite: ADVISOR_CALL_SITE,
+      overrideProfile: ADVISOR_CONFIG.profile,
+      tool_choice: { type: "none" },
+      max_tokens: ADVISOR_CONFIG.maxTokens,
+    },
+    signal: withTimeout(params.signal, ADVISOR_CONFIG.timeoutMs),
+  });
+
+  const advice = extractAllText(response).trim();
+  return advice.length > 0 ? advice : "(advisor returned no guidance)";
+}

package/src/plugins/defaults/advisor/hooks/post-model-call.ts

@@ -0,0 +1,34 @@
+/**
+ * `post-model-call` hook: snapshot the transcript the executor just saw. Fires
+ * after the model returns its message (which may carry the `advisor` tool_use)
+ * but before tools run, so when `advisor.execute()` runs an instant later it
+ * reads exactly this snapshot.
+ *
+ * Pure observer: never mutates `content` or the continue/stop `decision`. Gated
+ * to the user-facing reply, so background/subagent/compaction calls — and the
+ * advisor's own `inference`-call-site sub-call — are ignored.
+ */
+
+import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+
+import { recordMessages } from "../advisor-state-store.js";
+
+const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+  if (ctx.callSite !== "mainAgent") return;
+  if (ctx.error) return;
+  // `ctx.messages` is the pre-reply history; the turn the model just produced —
+  // including any text/plan it wrote before the `advisor` tool_use — lives in
+  // `ctx.content` and is not yet in `messages`. Append it (cloned) so the
+  // advisor reviews the full current transcript, not just the prior history.
+  // `transcript.ts` strips the pending tool_use from this final assistant turn.
+  const messages =
+    ctx.content.length > 0
+      ? [
+          ...ctx.messages,
+          { role: "assistant" as const, content: [...ctx.content] },
+        ]
+      : ctx.messages;
+  recordMessages(ctx.conversationId, messages);
+};
+
+export default postModelCall;

package/src/plugins/defaults/advisor/hooks/pre-model-call.ts

@@ -0,0 +1,24 @@
+/**
+ * `pre-model-call` hook: for the user-facing reply (`mainAgent`), capture the
+ * executor's system prompt (steering stripped) so the advisor can be given it
+ * as context, and inject the advisor steering so the model reaches for the
+ * tool. Idempotent via the steering marker.
+ */
+
+import type { PluginHookFn, PreModelCallContext } from "@vellumai/plugin-api";
+
+import { recordSystemPrompt } from "../advisor-state-store.js";
+import { ADVISOR_CONFIG } from "../config.js";
+import { appendSteering, stripSteering } from "../steering.js";
+
+const preModelCall: PluginHookFn<PreModelCallContext> = async (ctx) => {
+  if (ctx.callSite !== "mainAgent") return;
+
+  recordSystemPrompt(ctx.conversationId, stripSteering(ctx.systemPrompt));
+
+  if (ADVISOR_CONFIG.steeringEnabled) {
+    ctx.systemPrompt = appendSteering(ctx.systemPrompt);
+  }
+};
+
+export default preModelCall;

package/src/plugins/defaults/advisor/hooks/user-prompt-submit.ts

@@ -0,0 +1,19 @@
+/**
+ * `user-prompt-submit` hook: seed the per-conversation capture at the start of a
+ * user turn with the inbound history, so an advisor call on the very first model
+ * turn still has context even before `post-model-call` snapshots the running
+ * transcript.
+ */
+
+import type {
+  PluginHookFn,
+  UserPromptSubmitContext,
+} from "@vellumai/plugin-api";
+
+import { seedCapture } from "../advisor-state-store.js";
+
+const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+  seedCapture(ctx.conversationId, ctx.latestMessages);
+};
+
+export default userPromptSubmit;

package/src/plugins/defaults/advisor/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "default-advisor",
+  "version": "1.0.0",
+  "description": "First-party default plugin that adds an `advisor` tool: a no-argument tool the model calls mid-task to consult a stronger inference profile on the full conversation transcript for strategic guidance, routed through the assistant's own inference.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/advisor/steering.ts

@@ -0,0 +1,51 @@
+/**
+ * Prompt fragments for the advisor plugin:
+ *  - `appendSteering` / `stripSteering` — the executor-facing steering block the
+ *    `pre-model-call` hook injects so the model reaches for the advisor tool at
+ *    the right times.
+ *  - `buildAdvisorSystem` / `advisorRequestText` — the advisor-facing framing for
+ *    the consult itself.
+ */
+
+/** Idempotency marker; the steering block is appended at the end of the prompt. */
+export const STEERING_MARKER = "<!-- advisor:steering -->";
+
+const STEERING_BODY = `You have an \`advisor\` tool backed by a stronger reviewer model. It takes NO parameters — calling it forwards your entire conversation automatically (the task, every tool call, every result). Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. Orientation (reading files, fetching a source) is not substantive work; do that first, then call advisor. Also call it when stuck, when changing approach, and once before you declare the task done. Give its guidance serious weight; only override it when primary-source evidence contradicts a specific claim, and say so when you do.`;
+
+const ADVISOR_STEERING = `${STEERING_MARKER}\n${STEERING_BODY}`;
+
+/** Append the steering block to the executor's system prompt (idempotent). */
+export function appendSteering(systemPrompt: string | null): string | null {
+  if (systemPrompt === null) return null;
+  if (systemPrompt.includes(STEERING_MARKER)) return systemPrompt;
+  return `${systemPrompt}\n\n${ADVISOR_STEERING}`;
+}
+
+/** Remove a previously-appended steering block, recovering the original prompt. */
+export function stripSteering(systemPrompt: string | null): string | null {
+  if (systemPrompt === null) return null;
+  const idx = systemPrompt.indexOf(STEERING_MARKER);
+  if (idx === -1) return systemPrompt;
+  return systemPrompt.slice(0, idx).trimEnd();
+}
+
+/**
+ * System prompt for the advisor sub-call. Frames the advisor's role and, for
+ * context, quotes the executor's own system prompt (as the advisor tool does —
+ * the advisor sees the system prompt as context about the executor's task).
+ */
+export function buildAdvisorSystem(
+  originalSystemPrompt: string | null,
+): string {
+  const base = `You are a senior technical advisor consulted by another AI agent partway through a task. You can see the agent's full conversation above: its task, every tool call it has made, and every result it has seen. Give concise, high-leverage strategic guidance — the right approach, the key risk or failure mode to avoid, and the single most important next step. Do not role-play as the agent or produce its final deliverable; advise it. If the agent is already on track, say so briefly and sharpen its plan.`;
+  if (!originalSystemPrompt) return base;
+  return `${base}\n\nFor context, the agent is operating under this system prompt:\n<agent_system_prompt>\n${originalSystemPrompt}\n</agent_system_prompt>`;
+}
+
+/**
+ * The final user turn appended to the transcript for the advisor sub-call. Asks
+ * for guidance and carries the soft word-limit nudge.
+ */
+export function advisorRequestText(wordLimit: number): string {
+  return `Review the conversation above — the task, the tool calls, and their results — and give focused strategic guidance on how to proceed. (Advisor: keep your guidance under ~${wordLimit} words — a focused starting point, not a comprehensive plan.)`;
+}

package/src/plugins/defaults/advisor/tools/advisor.ts

@@ -0,0 +1,52 @@
+/**
+ * The `advisor` tool — a no-argument tool the model calls to consult a stronger
+ * model for strategic guidance. The model supplies no input; the plugin reads
+ * the transcript captured by the lifecycle hooks and runs the consult, routed
+ * through the assistant's own inference.
+ *
+ * Default export = the tool definition. `defaults/index.ts` finalizes it and
+ * attaches it to the advisor plugin's `tools` array, which `bootstrapPlugins`
+ * registers into the model-visible tool catalog.
+ */
+
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "@vellumai/plugin-api";
+import { RiskLevel } from "@vellumai/plugin-api";
+
+import { getCapture } from "../advisor-state-store.js";
+import { consultAdvisor } from "../consult.js";
+
+const advisorTool: ToolDefinition = {
+  name: "advisor",
+  description:
+    "Consult a stronger advisor model for strategic guidance. Takes NO parameters — your " +
+    "full conversation (the task, every tool call, and every result) is forwarded " +
+    "automatically. Call it before substantive work, when you're stuck, when changing " +
+    "approach, and once before declaring a task complete.",
+  input_schema: { type: "object", properties: {}, additionalProperties: false },
+  // Read-only advice; low risk so the consult isn't gated behind a prompt.
+  defaultRiskLevel: RiskLevel.Low,
+  async execute(
+    _input: Record<string, unknown>,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> {
+    try {
+      const capture = getCapture(ctx.conversationId);
+      const advice = await consultAdvisor({
+        systemPrompt: capture?.systemPrompt ?? null,
+        messages: capture?.messages ?? [],
+        signal: ctx.signal,
+      });
+      return { content: advice, isError: false };
+    } catch (err) {
+      // Degrade like the advisor tool: never fail the turn over a consult.
+      const reason = err instanceof Error ? err.message : String(err);
+      return { content: `(advisor unavailable: ${reason})`, isError: false };
+    }
+  },
+};
+
+export default advisorTool;

package/src/plugins/defaults/advisor/transcript.ts

@@ -0,0 +1,76 @@
+/**
+ * Convert a captured executor transcript into the message list sent to the
+ * advisor sub-call.
+ *
+ * Strips blocks the advisor shouldn't (or can't) replay:
+ *  - thinking / redacted-thinking (the advisor tool drops thinking),
+ *  - files,
+ *  - `server_tool_use` AND `web_search_tool_result` — provider-side tool calls
+ *    (e.g. web search) and their results are dropped *together*. Dropping the
+ *    result without its paired `server_tool_use` would leave an orphaned call
+ *    block the provider rejects, so any consult after prior web-search history
+ *    would fail; dropping both keeps the sequence valid.
+ *
+ * Images are preserved — top-level and nested inside `tool_result.contentBlocks`
+ * (which are recursively sanitized) — so the advisor sees what the executor saw.
+ * Visual tasks depend on it; the advisor profile is expected to be vision-capable.
+ *
+ * It also strips the *pending* client tool calls from the final assistant turn:
+ * at capture time (a `post-model-call` before tools run) the last assistant
+ * message carries the `advisor` tool_use with no matching `tool_result` yet, so
+ * sending it would be a dangling call. Earlier, completed `tool_use` /
+ * `tool_result` pairs are preserved intact.
+ */
+
+import type { ContentBlock, Message } from "../../../providers/types.js";
+
+/** Drop disallowed blocks; recursively sanitize tool_result content. `null` = drop. */
+function sanitize(block: ContentBlock): ContentBlock | null {
+  switch (block.type) {
+    case "thinking":
+    case "redacted_thinking":
+    case "file":
+    case "server_tool_use":
+    case "web_search_tool_result":
+      return null;
+    case "tool_result": {
+      if (!block.contentBlocks) return block;
+      // Keep images (and other allowed blocks) nested in the tool result; drop
+      // the disallowed ones.
+      const contentBlocks = block.contentBlocks
+        .map(sanitize)
+        .filter((b): b is ContentBlock => b !== null);
+      return {
+        ...block,
+        contentBlocks: contentBlocks.length > 0 ? contentBlocks : undefined,
+      };
+    }
+    default:
+      // text, image, tool_use — kept.
+      return block;
+  }
+}
+
+export function toAdvisorMessages(messages: ReadonlyArray<Message>): Message[] {
+  const out: Message[] = [];
+  const lastIndex = messages.length - 1;
+
+  messages.forEach((message, index) => {
+    let content = message.content
+      .map(sanitize)
+      .filter((b): b is ContentBlock => b !== null);
+
+    // The final assistant turn's client tool calls have no results yet — drop
+    // them so we never send a dangling tool_use. (server_tool_use is already
+    // dropped above.)
+    if (index === lastIndex && message.role === "assistant") {
+      content = content.filter(
+        (b) => b.type !== "tool_use" && b.type !== "server_tool_use",
+      );
+    }
+
+    if (content.length > 0) out.push({ role: message.role, content });
+  });
+
+  return out;
+}

package/src/plugins/defaults/index.ts

@@ -24,8 +24,15 @@
  * {@link registerDefaultPlugins} at call time.
  */
 
+import { finalizeTool } from "../../tools/tool-defaults.js";
 import { registerPlugin, resetPluginRegistryForTests } from "../registry.js";
 import { type Plugin, PluginExecutionError } from "../types.js";
+import { resetAdvisorStateForTests } from "./advisor/advisor-state-store.js";
+import advisorPostModelCall from "./advisor/hooks/post-model-call.js";
+import advisorPreModelCall from "./advisor/hooks/pre-model-call.js";
+import advisorUserPromptSubmit from "./advisor/hooks/user-prompt-submit.js";
+import advisorPkg from "./advisor/package.json" with { type: "json" };
+import advisorTool from "./advisor/tools/advisor.js";
 import compactionPkg from "./compaction/package.json" with { type: "json" };
 import emptyResponsePostModelCall from "./empty-response/hooks/post-model-call.js";
 import emptyResponseStop from "./empty-response/hooks/stop.js";
@@ -297,6 +304,30 @@ export const defaultToolResultTruncatePlugin: Plugin = {
   },
 };
 
+/**
+ * `advisor` — adds the model-visible `advisor` tool: a no-argument tool the
+ * model calls to consult a stronger inference profile (the `inference` call
+ * site with a `quality-optimized` override) on the full transcript, routed
+ * through the assistant's own inference. Three hooks feed it: `user-prompt-submit`
+ * seeds the capture, `pre-model-call` records the executor's system prompt and
+ * injects the steering that nudges the model to consult, and `post-model-call`
+ * snapshots the transcript the tool reads. `finalizeTool` fills the tool's
+ * defaults so it satisfies `Tool`, and `bootstrapPlugins` registers it into the
+ * catalog.
+ */
+export const defaultAdvisorPlugin: Plugin = {
+  manifest: {
+    name: advisorPkg.name,
+    version: advisorPkg.version,
+  },
+  hooks: {
+    "user-prompt-submit": advisorUserPromptSubmit,
+    "pre-model-call": advisorPreModelCall,
+    "post-model-call": advisorPostModelCall,
+  },
+  tools: [finalizeTool(advisorTool, "advisor")],
+};
+
 /**
  * Full set of first-party default plugins. Used by
  * {@link registerDefaultPlugins} to drive the registration loop; the array
@@ -318,6 +349,9 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     defaultCompactionPlugin,
     defaultTitleGeneratePlugin,
     memoryV3ShadowPlugin,
+    // Registered last so its capture hooks observe the fully-processed turn
+    // (memory injections, history repair) that the executor actually sees.
+    defaultAdvisorPlugin,
   ];
 }
 
@@ -364,5 +398,6 @@ export function resetPluginRegistryAndRegisterDefaults(): void {
   resetExplorationDriftStateForTests();
   resetTaskProgressNudgeStateForTests();
   resetSurfaceCompletionNudgeStoreForTests();
+  resetAdvisorStateForTests();
   registerDefaultPlugins();
 }

package/src/runtime/routes/inbound-stages/background-dispatch.test.ts

@@ -845,7 +845,7 @@ describe("Slack thinking status timing", () => {
           channel: channelId,
           threadTs,
           status: expect.any(String),
-          loadingMessages: ["Working on it..."],
+          loadingMessages: ["Thinking\u2026"],
         },
       );
       const threadStatus = deliveredChannelReplies[0]!.payload
@@ -948,13 +948,13 @@ describe("Slack thinking status timing", () => {
         channel: channelId,
         threadTs,
         status: expect.any(String),
-        loadingMessages: ["Working on it..."],
+        loadingMessages: ["Thinking\u2026"],
       },
       {
         channel: channelId,
         threadTs,
         status: expect.any(String),
-        loadingMessages: ["Working on it..."],
+        loadingMessages: ["Thinking\u2026"],
       },
       {
         channel: channelId,

package/src/runtime/routes/inbound-stages/background-dispatch.ts

@@ -577,7 +577,7 @@ function createSlackThinkingStatusController(params: {
 }
 
 const SLACK_THINKING_MAX_DURATION_MS = 120_000;
-const SLACK_GENERIC_LOADING_MESSAGES = ["Working on it..."] as const;
+const SLACK_GENERIC_LOADING_MESSAGES = ["Thinking…"] as const;
 const SLACK_THINKING_STATUSES = ["is on it", "is working hard"] as const;
 
 function getRandomSlackThinkingStatus(): string {