@vellumai/assistant 0.9.0 → 0.10.0-staging.2

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,21 @@
+/**
+ * Static behavioral configuration for the advisor.
+ *
+ * The advisor *model* is no longer hardcoded here: it routes through the
+ * dedicated `advisor` call site, whose default profile (`quality-optimized`)
+ * lives in CALL_SITE_DEFAULTS and is overridden per workspace by
+ * `llm.advisorProfile`. Whether the advisor is active is decided per chat
+ * profile by `ProfileEntry.advisorEnabled` (default on).
+ */
+export const ADVISOR_CONFIG = {
+  // No advisor-specific output cap: the consult omits `max_tokens` (so the
+  // resolver applies the profile's normal output budget) and the request text
+  // carries no word limit. The advisor decides its own length.
+  /** Abort the consult if the sub-call runs longer than this. */
+  timeoutMs: 60_000,
+  /**
+   * Global kill-switch for the steering injection. The per-chat-profile
+   * `advisorEnabled` toggle gates it further; this stays as a hard off switch.
+   */
+  steeringEnabled: true,
+} as const;

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

@@ -0,0 +1,93 @@
+/**
+ * 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 { getConfig } from "../../../config/loader.js";
+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";
+
+// Dedicated advisor call site. Its default profile (`quality-optimized`) lives
+// in CALL_SITE_DEFAULTS; a workspace overrides which profile the advisor runs
+// on via `llm.advisorProfile`, which we float above the call-site layers.
+const ADVISOR_CALL_SITE: LLMCallSite = "advisor";
+
+/**
+ * Resolve the routing override for the advisor consult. When the workspace has
+ * set `llm.advisorProfile`, force it above the call-site layers so it is
+ * authoritative; otherwise return `{}` so the `advisor` call site resolves to
+ * its default profile.
+ */
+function advisorOverride(): {
+  overrideProfile?: string;
+  forceOverrideProfile?: boolean;
+} {
+  const advisorProfile = getConfig().llm.advisorProfile;
+  return advisorProfile
+    ? { overrideProfile: advisorProfile, forceOverrideProfile: true }
+    : {};
+}
+
+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 override = advisorOverride();
+
+  const provider = await getConfiguredProvider(ADVISOR_CALL_SITE, override);
+  if (!provider) {
+    return "(advisor unavailable: no inference provider is configured)";
+  }
+
+  // Append the consult instruction as the final user turn, then run a
+  // tool-less completion through the resolved provider. No `max_tokens` is
+  // set, so the resolver applies the profile's normal output budget rather
+  // than an advisor-specific cap.
+  const messages: Message[] = [...history, userMessage(advisorRequestText())];
+
+  const response = await provider.sendMessage(messages, {
+    systemPrompt: buildAdvisorSystem(params.systemPrompt),
+    config: {
+      callSite: ADVISOR_CALL_SITE,
+      ...override,
+      tool_choice: { type: "none" },
+    },
+    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,30 @@
+/**
+ * `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 { advisorEnabledForProfile } from "../advisor-gate.js";
+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));
+
+  // Steer the model to consult only when the steering is globally on AND the
+  // chat profile this turn routes to has the advisor enabled (default on).
+  if (
+    ADVISOR_CONFIG.steeringEnabled &&
+    advisorEnabledForProfile(ctx.modelProfile)
+  ) {
+    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,67 @@
+/**
+ * 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 you start building or implementing: once you understand what's being asked, consult it to shape the plan — it can lay out the plan when you don't have one yet, or pressure-test and sharpen a plan you've already drafted. Orient yourself first (read the relevant files, understand the task), then call advisor before you commit to an approach and start producing work. Also call it when you get stuck, when you're weighing a change in direction, 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 advisor consulted by another AI agent working on a task — most often at the planning stage, before it starts building, but sometimes partway through. The entire conversation above is the agent's working context: its task or goal, every tool call it has made, and every result it has seen. The agent has paused to consult you because you bring a second, independent perspective it cannot get from inside its own reasoning loop. Your job is to maximize its odds of completing the task correctly and efficiently.
+
+Evaluate the work along these dimensions, and lead with whatever matters most right now:
+
+- Approach & plan: If the agent has already drafted a plan or chosen an approach, pressure-test it — is it the right one, or is there a materially better path? If it hasn't committed to one yet, lay out a concrete plan for how to proceed. Either way, be specific about the path you would take and why.
+- Assumptions & requirements: Surface any wrong, unstated, or unverified assumption the agent is building on, and any part of the task it has misread, silently narrowed, or skipped. These are the failures it is least able to see itself.
+- Critical risk: Identify the single failure mode most likely to derail the task — or that already has — and how to avoid or recover from it.
+- Next step: Give one concrete action the agent can take immediately. Name the specific file, function, command, interface, or decision involved — not a generic direction.
+- Verification: If the agent has no clear way to confirm its work is correct, tell it how it will know.
+
+How to advise:
+- Be specific and grounded. Cite what you actually see in the transcript — a particular result, a line of reasoning, a command that failed. Never invent details that aren't there; if a decisive fact is missing, say what the agent should go find out.
+- Be decisive. Give a clear recommendation, not a menu of equally weighted options. When genuinely uncertain, say so and state what would resolve it.
+- Prioritize ruthlessly. Lead with the highest-leverage point. Don't restate at length what the agent already did well, and don't pad the response with minor nitpicks — a focused, well-reasoned critique beats an exhaustive one.
+- Stay in your lane. Advise the agent; do not role-play as it, write its final deliverable, or take its next action for it. If the agent is already on the right track, confirm it and sharpen the plan rather than manufacturing objections.
+
+Write as much as the guidance genuinely needs, and no more.`;
+  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; imposes no length limit — the advisor decides how much to say.
+ */
+export function advisorRequestText(): string {
+  return `Review the conversation above — the task, the tool calls, and their results — and give focused strategic guidance on how to proceed.`;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * 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 { advisorEnabledForProfile } from "../advisor-gate.js";
+import { getCapture } from "../advisor-state-store.js";
+import { consultAdvisor } from "../consult.js";
+
+const advisorTool: ToolDefinition = {
+  name: "advisor",
+  description:
+    "Consult a stronger advisor model to shape your plan and get strategic guidance. " +
+    "Takes NO parameters — your full conversation (the task, every tool call, and every " +
+    "result) is forwarded automatically. Call it BEFORE you start building: it can lay out " +
+    "a plan when you don't have one yet, or review and sharpen the plan you've already " +
+    "drafted. Also call it when you're stuck, when weighing a change in approach, and once " +
+    "before declaring a task complete. Give its guidance serious weight.",
+  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> {
+    // Defense-in-depth: the steering is already gated per profile, but a model
+    // could still call the tool. Honor the chat profile this turn runs under —
+    // the per-turn override (per-conversation / profile-session) when present,
+    // else the workspace active profile.
+    if (!advisorEnabledForProfile(ctx.overrideProfile ?? null)) {
+      return {
+        content: "(advisor is disabled for the active profile)",
+        isError: false,
+      };
+    }
+    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";
@@ -54,6 +61,10 @@ import memoryRetrievalPkg from "./memory-retrieval/package.json" with { type: "j
 import memoryV3PostCompact from "./memory-v3-shadow/hooks/post-compact.js";
 import memoryV3UserPromptSubmit from "./memory-v3-shadow/hooks/user-prompt-submit.js";
 import memoryV3Pkg from "./memory-v3-shadow/package.json" with { type: "json" };
+import surfaceCompletionNudgePostModelCall from "./surface-completion-nudge/hooks/post-model-call.js";
+import surfaceCompletionNudgeStop from "./surface-completion-nudge/hooks/stop.js";
+import { resetSurfaceCompletionNudgeStoreForTests } from "./surface-completion-nudge/nudge-state-store.js";
+import surfaceCompletionNudgePkg from "./surface-completion-nudge/package.json" with { type: "json" };
 import taskProgressNudgePostToolUse, {
   resetTaskProgressNudgeStateForTests,
 } from "./task-progress-nudge/hooks/post-tool-use.js";
@@ -259,6 +270,25 @@ export const defaultTaskProgressNudgePlugin: Plugin = {
   },
 };
 
+/**
+ * `surface-completion-nudge` — a `post-model-call` hook that, when a user-facing
+ * turn is about to end with a progress surface (a `task_progress` card or
+ * `work_result`) the model showed but never advanced to a terminal status or
+ * dismissed, nudges the model once to close it and re-queries so it can act; the
+ * `stop` hook clears the one-shot bound on a terminal stop so the next run
+ * nudges afresh.
+ */
+export const defaultSurfaceCompletionNudgePlugin: Plugin = {
+  manifest: {
+    name: surfaceCompletionNudgePkg.name,
+    version: surfaceCompletionNudgePkg.version,
+  },
+  hooks: {
+    "post-model-call": surfaceCompletionNudgePostModelCall,
+    stop: surfaceCompletionNudgeStop,
+  },
+};
+
 /**
  * `tool-result-truncate` — a `post-tool-use` hook that tail-drops an oversized
  * tool result down to a character budget derived from the model's context
@@ -274,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
@@ -289,11 +343,15 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     defaultToolErrorPlugin,
     defaultExplorationDriftPlugin,
     defaultTaskProgressNudgePlugin,
+    defaultSurfaceCompletionNudgePlugin,
     defaultHistoryRepairPlugin,
     defaultImageRecoveryPlugin,
     defaultCompactionPlugin,
     defaultTitleGeneratePlugin,
     memoryV3ShadowPlugin,
+    // Registered last so its capture hooks observe the fully-processed turn
+    // (memory injections, history repair) that the executor actually sees.
+    defaultAdvisorPlugin,
   ];
 }
 
@@ -339,5 +397,7 @@ export function resetPluginRegistryAndRegisterDefaults(): void {
   resetImageRecoveryStoreForTests();
   resetExplorationDriftStateForTests();
   resetTaskProgressNudgeStateForTests();
+  resetSurfaceCompletionNudgeStoreForTests();
+  resetAdvisorStateForTests();
   registerDefaultPlugins();
 }