@vellumai/assistant 0.9.0-dev.202606181713.b269b6a → 0.9.0-dev.202606181735.ae6e1d8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.9.0-dev.202606181713.b269b6a",
+  "version": "0.9.0-dev.202606181735.ae6e1d8",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/plugin-tool-contribution.test.ts

@@ -190,13 +190,16 @@ describe("plugin tool contributions", () => {
     registerPlugin(plugin);
 
     await bootstrapPlugins();
-    // No tool should have been registered.
-    expect(getAllTools()).toHaveLength(0);
+    // `bootstrapPlugins` also registers the first-party defaults (the advisor
+    // default contributes the `advisor` tool), so the global tool set is not
+    // empty. What matters here is that the no-tools plugin contributed nothing
+    // of its own — its tool refcount stays at zero.
+    expect(getPluginRefCount("no-tools")).toBe(0);
 
     // Shutdown must also be safe — `unregisterPluginTools` is idempotent for
     // plugins that never contributed any tools.
     await runShutdownHooks("test-shutdown");
-    expect(getAllTools()).toHaveLength(0);
+    expect(getPluginRefCount("no-tools")).toBe(0);
   });
 
   test("tools declared before init() runs are only visible after bootstrap", async () => {

package/src/plugins/defaults/advisor/__tests__/advisor-state-store.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import type { Message } from "../../../../providers/types.js";
+import {
+  getCapture,
+  recordMessages,
+  recordSystemPrompt,
+  resetAdvisorStateForTests,
+  seedCapture,
+} from "../advisor-state-store.js";
+
+const userMsg = (t: string): Message => ({
+  role: "user",
+  content: [{ type: "text", text: t }],
+});
+
+afterEach(() => {
+  resetAdvisorStateForTests();
+});
+
+describe("advisor state store", () => {
+  test("records system prompt and messages independently per conversation", () => {
+    recordSystemPrompt("c1", "system A");
+    recordMessages("c1", [userMsg("hello")]);
+    recordSystemPrompt("c2", "system B");
+
+    expect(getCapture("c1")?.systemPrompt).toBe("system A");
+    expect(getCapture("c1")?.messages).toEqual([userMsg("hello")]);
+    expect(getCapture("c2")?.systemPrompt).toBe("system B");
+    expect(getCapture("c2")?.messages).toEqual([]);
+  });
+
+  test("seedCapture snapshots (copies) the array", () => {
+    const live: Message[] = [userMsg("one")];
+    seedCapture("c1", live);
+    live.push(userMsg("two"));
+    expect(getCapture("c1")?.messages).toEqual([userMsg("one")]);
+  });
+
+  test("getCapture returns undefined for an unseen conversation", () => {
+    expect(getCapture("nope")).toBeUndefined();
+  });
+});

package/src/plugins/defaults/advisor/__tests__/agent-loop-integration.test.ts

@@ -0,0 +1,134 @@
+/**
+ * End-to-end integration test: drives the REAL agent loop with all first-party
+ * defaults registered (so the advisor plugin's hooks + tool are live), and lets
+ * the REAL consult run. Only the provider boundary is stubbed:
+ *   - the executor's provider (a scripted mock provider), and
+ *   - `getConfiguredProvider`, so the advisor sub-call resolves to a second
+ *     scripted mock provider instead of a configured one.
+ *
+ * The advisor's inference genuinely runs through `consult` → `sendMessage`
+ * against the injected advisor provider, exercising the full hook-capture →
+ * tool.execute → consult → routed-inference path through the loop.
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import {
+  createMockProvider,
+  textResponse,
+} from "../../../../__tests__/helpers/mock-provider.js";
+import { AgentLoop } from "../../../../agent/loop.js";
+import type {
+  ContentBlock,
+  Message,
+  ProviderResponse,
+} from "../../../../providers/types.js";
+
+const ADVICE = "ADVICE: use a channel-based worker pool with graceful drain.";
+let advisorProvider: ReturnType<typeof createMockProvider> | null = null;
+
+const realProviderSendMessage =
+  await import("../../../../providers/provider-send-message.js");
+mock.module("../../../../providers/provider-send-message.js", () => ({
+  ...realProviderSendMessage,
+  getConfiguredProvider: async () => advisorProvider?.provider ?? null,
+}));
+
+const { resetPluginRegistryAndRegisterDefaults } =
+  await import("../../index.js");
+const advisorTool = (await import("../tools/advisor.js")).default;
+
+const userTurn: Message = {
+  role: "user",
+  content: [{ type: "text", text: "build a worker pool" }],
+};
+
+function textOf(content: ReadonlyArray<ContentBlock>): string {
+  return content.map((b) => (b.type === "text" ? b.text : "")).join("");
+}
+
+describe("advisor — agent-loop integration", () => {
+  beforeEach(() => {
+    resetPluginRegistryAndRegisterDefaults();
+    advisorProvider = createMockProvider([textResponse(ADVICE)]);
+  });
+
+  test("model calls advisor → hooks capture → consult routes through inference → advice returns", async () => {
+    const consultThenText: ProviderResponse = {
+      content: [
+        { type: "text", text: "Let me consult the advisor." },
+        { type: "tool_use", id: "call-1", name: "advisor", input: {} },
+      ],
+      model: "mock-model",
+      usage: { inputTokens: 10, outputTokens: 5 },
+      stopReason: "tool_use",
+    };
+    const { provider } = createMockProvider([
+      consultThenText,
+      textResponse("Done — implemented the worker pool."),
+    ]);
+
+    const conversationId = "advisor-itest";
+    const loop = new AgentLoop({
+      provider,
+      systemPrompt: "You are a coding agent.",
+      conversationId,
+      tools: [
+        {
+          name: "advisor",
+          description: "",
+          input_schema: { type: "object", properties: {} },
+        },
+      ],
+      toolExecutor: async (name, input) =>
+        name === "advisor"
+          ? advisorTool.execute!(input, { conversationId } as never)
+          : { content: `unknown tool ${name}`, isError: true },
+    });
+
+    const { history } = await loop.run({
+      requestId: "req-1",
+      messages: [userTurn],
+      onEvent: () => {},
+      callSite: "mainAgent",
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    // The advisor sub-call happened, routed through the inference call site.
+    expect(advisorProvider!.calls).toHaveLength(1);
+    const sub = advisorProvider!.calls[0];
+    expect(sub.options?.config?.callSite).toBe("inference");
+    expect(sub.options?.config?.overrideProfile).toBe("quality-optimized");
+    expect(sub.options?.config?.tool_choice).toEqual({ type: "none" });
+    expect(sub.options?.config?.max_tokens).toBe(2048);
+
+    // The advisor saw the captured transcript (task present; pending tool_use stripped).
+    expect(textOf(sub.messages[0].content)).toContain("build a worker pool");
+    expect(textOf(sub.messages[sub.messages.length - 1].content)).toContain(
+      "80 words",
+    );
+    // It also saw the model's CURRENT turn — the text it wrote right before the
+    // `advisor` tool_use — which `post-model-call` lifts out of `ctx.content`.
+    const transcript = sub.messages.map((m) => textOf(m.content)).join("\n");
+    expect(transcript).toContain("Let me consult the advisor.");
+
+    // The advisor saw the executor's system prompt (via pre-model-call).
+    expect(sub.options?.systemPrompt).toContain("senior technical advisor");
+    expect(sub.options?.systemPrompt).toContain("You are a coding agent.");
+
+    // The advice flowed back into the executor's history as the tool result.
+    const toolResult = history
+      .flatMap((m) => m.content)
+      .find((b) => b.type === "tool_result");
+    expect((toolResult as { content: string }).content).toContain(
+      "channel-based worker pool",
+    );
+
+    // The loop completed with the final answer.
+    const lastAssistant = [...history]
+      .reverse()
+      .find((m) => m.role === "assistant")!;
+    expect(textOf(lastAssistant.content)).toContain(
+      "implemented the worker pool",
+    );
+  });
+});

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

@@ -0,0 +1,147 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { Message } from "../../../../providers/types.js";
+
+// Stub the provider resolution; spread the real module so `extractAllText` /
+// `userMessage` (which the consult also uses) keep working.
+let sendMessageArgs: Record<string, unknown> | null = null;
+let responseText = "Use a channel-based worker pool; drain on shutdown.";
+let sendMessageError: Error | null = null;
+let providerResolves = true;
+
+const fakeProvider = {
+  name: "mock-advisor-provider",
+  async sendMessage(messages: unknown, options: unknown) {
+    sendMessageArgs = { messages, options } as Record<string, unknown>;
+    if (sendMessageError) throw sendMessageError;
+    return {
+      content: [{ type: "text", text: responseText }],
+      model: "mock-model",
+      usage: { inputTokens: 1, outputTokens: 1 },
+      stopReason: "end_turn",
+    };
+  },
+};
+
+const realPsm = await import("../../../../providers/provider-send-message.js");
+mock.module("../../../../providers/provider-send-message.js", () => ({
+  ...realPsm,
+  getConfiguredProvider: async () => (providerResolves ? fakeProvider : null),
+}));
+
+const { consultAdvisor } = await import("../consult.js");
+const advisorTool = (await import("../tools/advisor.js")).default;
+const { recordSystemPrompt, recordMessages, resetAdvisorStateForTests } =
+  await import("../advisor-state-store.js");
+
+const userMsg = (t: string): Message => ({
+  role: "user",
+  content: [{ type: "text", text: t }],
+});
+
+function optionConfig(): Record<string, unknown> {
+  const options = sendMessageArgs?.options as Record<string, unknown>;
+  return options.config as Record<string, unknown>;
+}
+
+beforeEach(() => {
+  sendMessageArgs = null;
+  responseText = "Use a channel-based worker pool; drain on shutdown.";
+  sendMessageError = null;
+  providerResolves = true;
+  resetAdvisorStateForTests();
+});
+
+describe("consultAdvisor", () => {
+  test("routes through the inference call site, tools off, capped, returns advice", async () => {
+    const messages: Message[] = [
+      userMsg("build a worker pool"),
+      {
+        role: "assistant",
+        content: [
+          { type: "thinking", thinking: "secret", signature: "s" },
+          { type: "text", text: "let me consult the advisor" },
+          { type: "tool_use", id: "t1", name: "advisor", input: {} },
+        ],
+      },
+    ];
+
+    const advice = await consultAdvisor({
+      systemPrompt: "You are a coding agent.",
+      messages,
+    });
+
+    expect(advice).toBe(responseText);
+
+    const config = optionConfig();
+    expect(config.callSite).toBe("inference");
+    expect(config.overrideProfile).toBe("quality-optimized");
+    expect(config.tool_choice).toEqual({ type: "none" });
+    expect(config.max_tokens).toBe(2048);
+
+    const sent = sendMessageArgs?.messages as Message[];
+    expect(sent[0]).toEqual(userMsg("build a worker pool"));
+    expect(sent[1]).toEqual({
+      role: "assistant",
+      content: [{ type: "text", text: "let me consult the advisor" }],
+    });
+    const lastText = (sent[sent.length - 1].content[0] as { text: string })
+      .text;
+    expect(lastText).toContain("80 words");
+
+    const options = sendMessageArgs?.options as { systemPrompt: string };
+    expect(options.systemPrompt).toContain("senior technical advisor");
+    expect(options.systemPrompt).toContain("You are a coding agent.");
+  });
+
+  test("soft-fails when no provider is configured", async () => {
+    providerResolves = false;
+    const advice = await consultAdvisor({
+      systemPrompt: null,
+      messages: [userMsg("hi")],
+    });
+    expect(advice).toContain("no inference provider");
+  });
+
+  test("returns a notice when there is no usable transcript", async () => {
+    const advice = await consultAdvisor({ systemPrompt: null, messages: [] });
+    expect(advice).toContain("no conversation context");
+    expect(sendMessageArgs).toBeNull();
+  });
+
+  test("falls back to a notice when the advisor returns blank text", async () => {
+    responseText = "   ";
+    const advice = await consultAdvisor({
+      systemPrompt: null,
+      messages: [userMsg("hi")],
+    });
+    expect(advice).toContain("no guidance");
+  });
+});
+
+describe("advisor tool.execute", () => {
+  test("reads the captured transcript and returns guidance as a non-error result", async () => {
+    recordSystemPrompt("c1", "You are a coding agent.");
+    recordMessages("c1", [userMsg("build a worker pool")]);
+
+    const result = await advisorTool.execute?.({}, {
+      conversationId: "c1",
+    } as never);
+
+    expect(result?.isError).toBe(false);
+    expect(result?.content).toBe(responseText);
+  });
+
+  test("degrades to a benign result (never throws) when the consult fails", async () => {
+    recordMessages("c2", [userMsg("hi")]);
+    sendMessageError = new Error("kaboom");
+
+    const result = await advisorTool.execute?.({}, {
+      conversationId: "c2",
+    } as never);
+
+    expect(result?.isError).toBe(false);
+    expect(result?.content).toContain("advisor unavailable");
+    expect(result?.content).toContain("kaboom");
+  });
+});

package/src/plugins/defaults/advisor/__tests__/hooks.test.ts

@@ -0,0 +1,138 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import type {
+  Message,
+  PostModelCallContext,
+  PreModelCallContext,
+  UserPromptSubmitContext,
+} from "@vellumai/plugin-api";
+
+import {
+  getCapture,
+  resetAdvisorStateForTests,
+} from "../advisor-state-store.js";
+import postModelCall from "../hooks/post-model-call.js";
+import preModelCall from "../hooks/pre-model-call.js";
+import userPromptSubmit from "../hooks/user-prompt-submit.js";
+import { STEERING_MARKER } from "../steering.js";
+
+const logger = { info() {}, warn() {}, error() {}, debug() {} };
+const userMsg = (t: string): Message => ({
+  role: "user",
+  content: [{ type: "text", text: t }],
+});
+
+beforeEach(() => {
+  resetAdvisorStateForTests();
+});
+
+describe("pre-model-call hook", () => {
+  test("records the original system prompt and injects steering on mainAgent", async () => {
+    const ctx = {
+      conversationId: "c1",
+      callSite: "mainAgent",
+      systemPrompt: "BASE PROMPT",
+      deferAssistantOutput: false,
+      logger,
+    } as unknown as PreModelCallContext;
+
+    await preModelCall(ctx);
+
+    expect(ctx.systemPrompt).toContain(STEERING_MARKER);
+    expect(ctx.systemPrompt?.startsWith("BASE PROMPT")).toBe(true);
+    expect(getCapture("c1")?.systemPrompt).toBe("BASE PROMPT");
+  });
+
+  test("ignores non-mainAgent calls", async () => {
+    const ctx = {
+      conversationId: "bg",
+      callSite: "inference",
+      systemPrompt: "BG",
+      deferAssistantOutput: false,
+      logger,
+    } as unknown as PreModelCallContext;
+
+    await preModelCall(ctx);
+    expect(ctx.systemPrompt).toBe("BG");
+    expect(getCapture("bg")).toBeUndefined();
+  });
+});
+
+describe("post-model-call hook", () => {
+  const base = {
+    content: [],
+    stopReason: "end_turn",
+    decision: "stop" as const,
+    logger,
+  };
+
+  test("snapshots the transcript on mainAgent", async () => {
+    const messages = [userMsg("hi")];
+    await postModelCall({
+      ...base,
+      conversationId: "c1",
+      callSite: "mainAgent",
+      messages,
+    } as unknown as PostModelCallContext);
+    expect(getCapture("c1")?.messages).toEqual(messages);
+  });
+
+  test("appends the model's current turn (ctx.content) to the snapshot", async () => {
+    const messages = [userMsg("task")];
+    const assistantTurn: Message = {
+      role: "assistant",
+      content: [
+        { type: "text", text: "thinking about it" },
+        { type: "tool_use", id: "t1", name: "advisor", input: {} },
+      ],
+    };
+    await postModelCall({
+      ...base,
+      content: assistantTurn.content,
+      conversationId: "c4",
+      callSite: "mainAgent",
+      messages,
+    } as unknown as PostModelCallContext);
+    const captured = getCapture("c4")?.messages;
+    expect(captured).toHaveLength(2);
+    expect(captured?.[1]).toEqual(assistantTurn);
+  });
+
+  test("ignores the advisor's own inference sub-call (recursion safety) and errors", async () => {
+    await postModelCall({
+      ...base,
+      conversationId: "c2",
+      callSite: "inference",
+      messages: [userMsg("hi")],
+    } as unknown as PostModelCallContext);
+    expect(getCapture("c2")).toBeUndefined();
+
+    await postModelCall({
+      ...base,
+      conversationId: "c3",
+      callSite: "mainAgent",
+      messages: [userMsg("hi")],
+      error: new Error("boom"),
+      stopReason: null,
+    } as unknown as PostModelCallContext);
+    expect(getCapture("c3")).toBeUndefined();
+  });
+});
+
+describe("user-prompt-submit hook", () => {
+  test("seeds the capture with the inbound history", async () => {
+    const messages = [userMsg("task")];
+    await userPromptSubmit({
+      conversationId: "c1",
+      latestMessages: messages,
+      originalMessages: messages,
+      prompt: "task",
+      userMessageId: "u1",
+      requestId: "r1",
+      modelProfileKey: null,
+      isNonInteractive: false,
+      logger,
+    } as unknown as UserPromptSubmitContext);
+    expect(getCapture("c1")?.messages).toEqual(messages);
+  });
+});

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

@@ -0,0 +1,147 @@
+import { describe, expect, test } from "bun:test";
+
+import type { ContentBlock, Message } from "../../../../providers/types.js";
+import { toAdvisorMessages } from "../transcript.js";
+
+const text = (t: string): ContentBlock => ({ type: "text", text: t });
+
+describe("toAdvisorMessages", () => {
+  test("drops thinking and redacted-thinking blocks", () => {
+    const messages: Message[] = [
+      { role: "user", content: [text("do the task")] },
+      {
+        role: "assistant",
+        content: [
+          { type: "thinking", thinking: "secret", signature: "sig" },
+          { type: "redacted_thinking", data: "blob" },
+          text("here is my answer"),
+        ],
+      },
+    ];
+    const out = toAdvisorMessages(messages);
+    expect(out).toHaveLength(2);
+    expect(out[1].content).toEqual([text("here is my answer")]);
+  });
+
+  test("strips the pending advisor tool_use from the final assistant turn", () => {
+    const messages: Message[] = [
+      { role: "user", content: [text("task")] },
+      {
+        role: "assistant",
+        content: [
+          text("let me consult the advisor"),
+          { type: "tool_use", id: "t1", name: "advisor", input: {} },
+        ],
+      },
+    ];
+    const out = toAdvisorMessages(messages);
+    expect(out[1].content).toEqual([text("let me consult the advisor")]);
+  });
+
+  test("preserves completed client tool_use / tool_result pairs in earlier turns", () => {
+    const messages: Message[] = [
+      { role: "user", content: [text("task")] },
+      {
+        role: "assistant",
+        content: [{ type: "tool_use", id: "a", name: "bash", input: {} }],
+      },
+      {
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: "a", content: "output" }],
+      },
+      { role: "assistant", content: [text("done")] },
+    ];
+    const out = toAdvisorMessages(messages);
+    expect(out[1].content[0]).toEqual({
+      type: "tool_use",
+      id: "a",
+      name: "bash",
+      input: {},
+    });
+    expect(out[2].content[0]).toEqual({
+      type: "tool_result",
+      tool_use_id: "a",
+      content: "output",
+    });
+  });
+
+  test("drops a web-search server_tool_use AND its result together — no orphan", () => {
+    const messages: Message[] = [
+      { role: "user", content: [text("look it up")] },
+      {
+        role: "assistant",
+        content: [
+          text("searching"),
+          { type: "server_tool_use", id: "ws1", name: "web_search", input: {} },
+        ],
+      },
+      {
+        role: "user",
+        content: [
+          {
+            type: "web_search_tool_result",
+            tool_use_id: "ws1",
+            content: [{ title: "x", url: "y" }],
+          },
+        ],
+      },
+      { role: "assistant", content: [text("found it; here is the answer")] },
+    ];
+    const out = toAdvisorMessages(messages);
+    const flat = out.flatMap((m) => m.content);
+    expect(flat.some((b) => b.type === "server_tool_use")).toBe(false);
+    expect(flat.some((b) => b.type === "web_search_tool_result")).toBe(false);
+    expect(flat).toContainEqual(text("searching"));
+    expect(flat).toContainEqual(text("found it; here is the answer"));
+  });
+
+  test("keeps top-level image blocks", () => {
+    const img: ContentBlock = {
+      type: "image",
+      source: { type: "base64", media_type: "image/png", data: "x" },
+    };
+    const messages: Message[] = [
+      { role: "user", content: [text("look at this"), img] },
+    ];
+    const out = toAdvisorMessages(messages);
+    expect(out[0].content).toEqual([text("look at this"), img]);
+  });
+
+  test("keeps image contentBlocks on a tool_result, dropping disallowed ones", () => {
+    const img: ContentBlock = {
+      type: "image",
+      source: { type: "base64", media_type: "image/png", data: "x" },
+    };
+    const messages: Message[] = [
+      {
+        role: "user",
+        content: [
+          {
+            type: "tool_result",
+            tool_use_id: "a",
+            content: "screenshot",
+            contentBlocks: [
+              img,
+              {
+                type: "file",
+                source: {
+                  type: "base64",
+                  media_type: "application/pdf",
+                  data: "z",
+                  filename: "f.pdf",
+                },
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    const out = toAdvisorMessages(messages);
+    expect(out[0].content[0]).toEqual({
+      type: "tool_result",
+      tool_use_id: "a",
+      content: "screenshot",
+      contentBlocks: [img],
+    });
+  });
+});

package/src/plugins/defaults/advisor/advisor-state-store.ts

@@ -0,0 +1,94 @@
+/**
+ * Per-conversation capture store for the advisor plugin.
+ *
+ * A tool's `execute` does not receive the conversation transcript — only
+ * lifecycle hooks do. So the hooks snapshot what the executor saw (the system
+ * prompt from `pre-model-call`, the running transcript from `post-model-call`)
+ * into this module-level store, keyed by conversation id, and the `advisor`
+ * tool reads the latest snapshot when the model calls it. This reproduces the
+ * advisor-tool property that the model calls the tool with no arguments and the
+ * full context is supplied for it.
+ *
+ * Bounded by a small LRU so a long-lived daemon does not accumulate state for
+ * every conversation it has ever served.
+ */
+
+import type { Message } from "../../../providers/types.js";
+
+export interface AdvisorCapture {
+  /** The executor's system prompt (steering stripped), or null if unseen. */
+  systemPrompt: string | null;
+  /** The transcript the executor most recently saw on a `mainAgent` call. */
+  messages: Message[];
+  /** Last-write timestamp, used for LRU eviction. */
+  updatedAt: number;
+}
+
+const MAX_CONVERSATIONS = 200;
+const store = new Map<string, AdvisorCapture>();
+
+/** Move an entry to most-recently-used and evict the oldest past the cap. */
+function bump(conversationId: string, entry: AdvisorCapture): void {
+  entry.updatedAt = Date.now();
+  store.delete(conversationId);
+  store.set(conversationId, entry);
+  while (store.size > MAX_CONVERSATIONS) {
+    const oldest = store.keys().next().value;
+    if (oldest === undefined) break;
+    store.delete(oldest);
+  }
+}
+
+function ensure(conversationId: string): AdvisorCapture {
+  return (
+    store.get(conversationId) ?? {
+      systemPrompt: null,
+      messages: [],
+      updatedAt: Date.now(),
+    }
+  );
+}
+
+/**
+ * Seed the 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.
+ */
+export function seedCapture(
+  conversationId: string,
+  messages: ReadonlyArray<Message>,
+): void {
+  const entry = ensure(conversationId);
+  entry.messages = [...messages];
+  bump(conversationId, entry);
+}
+
+/** Record the executor's system prompt (steering already stripped). */
+export function recordSystemPrompt(
+  conversationId: string,
+  systemPrompt: string | null,
+): void {
+  const entry = ensure(conversationId);
+  entry.systemPrompt = systemPrompt;
+  bump(conversationId, entry);
+}
+
+/** Snapshot the transcript the executor just saw (before tools run). */
+export function recordMessages(
+  conversationId: string,
+  messages: ReadonlyArray<Message>,
+): void {
+  const entry = ensure(conversationId);
+  entry.messages = [...messages];
+  bump(conversationId, entry);
+}
+
+/** The latest capture for a conversation, or `undefined` if none recorded. */
+export function getCapture(conversationId: string): AdvisorCapture | undefined {
+  return store.get(conversationId);
+}
+
+/** Test-only: clear all captured state. */
+export function resetAdvisorStateForTests(): void {
+  store.clear();
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Static behavioral configuration for the advisor plugin.
+ *
+ * The advisor *model* is the inference profile named by `profile`, applied as
+ * an `overrideProfile` on the general-purpose `inference` call site — so the
+ * consult routes through the workspace's configured provider (managed-proxy or
+ * BYOK) with no separate API key.
+ */
+export const ADVISOR_CONFIG = {
+  /**
+   * Inference profile the advisor consults. Defaults to the strongest managed
+   * profile; the resolver falls back to the active profile if it's absent.
+   */
+  profile: "quality-optimized",
+  /**
+   * Hard cap on advisor output tokens per consult. Mirrors the advisor tool's
+   * recommended 2048 (the provider floor is 1024).
+   */
+  maxTokens: 2048,
+  /** Soft word budget requested of the advisor, biasing toward a focused start. */
+  wordLimit: 80,
+  /** Abort the consult if the sub-call runs longer than this. */
+  timeoutMs: 60_000,
+  /** Inject the "call advisor before substantive work" steering. */
+  steeringEnabled: true,
+} as const;

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();
 }