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

package/src/plugins/defaults/memory-v3-shadow/__tests__/shadow-plugin.test.ts

@@ -808,7 +808,7 @@ describe("memory-v3 shadow plugin", () => {
   });
 });
 
-describe("memory-v3 infrastructure-failure handling (hard-fail vs swallow)", () => {
+describe("memory-v3 infrastructure-failure handling", () => {
   const throwInfra = () =>
     orchestrateSpy.mockImplementationOnce(async () => {
       throw new MemoryV3RetrievalUnavailableError(
@@ -816,14 +816,12 @@ describe("memory-v3 infrastructure-failure handling (hard-fail vs swallow)", ()
       );
     });
 
-  test("LIVE injector HARD-FAILS the turn on an infra failure (no silent memory loss)", async () => {
+  test("LIVE injector logs and degrades to no v3 block on an infra failure", async () => {
     liveEnabled = true;
     shadowEnabled = false;
     throwInfra();
 
-    await expect(produce("conv-infra-live", 0)).rejects.toThrow(
-      MemoryV3RetrievalUnavailableError,
-    );
+    expect(await produce("conv-infra-live", 0)).toBeNull();
   });
 
   test("SHADOW injector swallows an infra failure (v2 fallback) — no throw, no block", async () => {
@@ -832,7 +830,7 @@ describe("memory-v3 infrastructure-failure handling (hard-fail vs swallow)", ()
     throwInfra();
 
     // Shadow mode: v2 retrieval still ran this turn, so the v3 injector returns
-    // null rather than failing the turn.
+    // null.
     expect(await produce("conv-infra-shadow", 0)).toBeNull();
   });
 
@@ -853,8 +851,6 @@ describe("memory-v3 infrastructure-failure handling (hard-fail vs swallow)", ()
       throw new Error("some unexpected non-infra bug");
     });
 
-    // Only INFRA failures hard-fail; any other error stays non-fatal so a bug
-    // in one lane can't take every turn down.
     expect(await produce("conv-nonfatal-live", 0)).toBeNull();
   });
 });

package/src/plugins/defaults/memory-v3-shadow/hooks/post-compact.ts

@@ -7,8 +7,8 @@
  * `../injector.js` and re-apply it here. Until then this hook does nothing.
  */
 
-import type { PluginHookFn } from "@vellumai/plugin-api";
+import type { HookFunction } from "@vellumai/plugin-api";
 
-const postCompact: PluginHookFn = async () => {};
+const postCompact: HookFunction = async () => {};
 
 export default postCompact;

package/src/plugins/defaults/memory-v3-shadow/hooks/user-prompt-submit.ts

@@ -10,10 +10,10 @@
  */
 
 import type {
-  PluginHookFn,
+  HookFunction,
   UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
-const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async () => {};
+const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async () => {};
 
 export default userPromptSubmit;

package/src/plugins/defaults/memory-v3-shadow/injector.ts

@@ -63,6 +63,10 @@
 import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
 import { getConfig } from "../../../config/loader.js";
 import { isMemoryV3Live } from "../../../config/memory-v3-gate.js";
+import {
+  type PendingConversationNotice,
+  queueConversationNotice,
+} from "../../../daemon/conversation-notices.js";
 import { isPersonalMemoryAllowed } from "../../../daemon/trust-context.js";
 import {
   wrapMemoryBlock,
@@ -120,6 +124,26 @@ function lruSet<V>(map: Map<string, V>, key: string, value: V): void {
   map.set(key, value);
 }
 
+function queueMemoryV3ConversationNotice(
+  err: MemoryV3RetrievalUnavailableError,
+  ctx: TurnContext,
+  live: boolean,
+): void {
+  if (!live) return;
+  const notice: PendingConversationNotice = err.conversationNotice ?? {
+    source: "memory_v3",
+    code: "UNKNOWN",
+    userMessage:
+      "Memory is temporarily unavailable, so this response may not use your saved memories. You can retry in a moment.",
+    errorCategory: "memory_v3_degraded",
+  };
+  queueConversationNotice(
+    ctx.conversationId,
+    `memory_v3:${ctx.turnIndex}:${notice.errorCategory ?? notice.code}`,
+    notice,
+  );
+}
+
 // ─── shared per-turn orchestration memo ─────────────────────────────────────
 
 interface ObservedTurn {
@@ -245,16 +269,16 @@ export const memoryV3Injector: Injector = {
     try {
       observed = await observeTurnOnce(ctx.conversationId, ctx.turnIndex);
     } catch (err) {
-      // A memory-v3 INFRASTRUCTURE failure (the selector lost its provider —
-      // e.g. a transient CES credential blip). Under `memory-v3-live` the
-      // user-prompt-submit hook already skipped v2 retrieval, so swallowing
-      // here would ship the turn with NO memory at all — exactly the silent
-      // degradation we want to eliminate. Hard-fail the turn instead (a clean,
-      // retryable error). In shadow mode v2 still ran this turn, so fall back
-      // to it (return null). Non-infra errors are already swallowed inside
-      // observeTurn; anything else reaching here stays non-fatal.
-      if (live && err instanceof MemoryV3RetrievalUnavailableError) {
-        throw err;
+      if (err instanceof MemoryV3RetrievalUnavailableError) {
+        queueMemoryV3ConversationNotice(err, ctx, live);
+        log.error(
+          {
+            err: err.message,
+            conversationId: ctx.conversationId,
+            mode: live ? "live" : "shadow",
+          },
+          "memory-v3 selection failed; skipping v3 memory for this turn",
+        );
       }
       return null;
     }
@@ -405,12 +429,16 @@ export const memoryV3SpotlightInjector: Injector = {
         placement: "after-memory-prefix",
       };
     } catch (err) {
-      // Live-only injector: an infra failure must hard-fail the turn. The cards
-      // injector (ordered ahead of this one) normally throws first, so this
-      // path is defensive — it keeps the behavior correct if the cards injector
-      // is ever disabled or reordered.
       if (err instanceof MemoryV3RetrievalUnavailableError) {
-        throw err;
+        queueMemoryV3ConversationNotice(err, ctx, true);
+        log.error(
+          {
+            err: err.message,
+            conversationId: ctx.conversationId,
+          },
+          "memory-v3 spotlight selection failed; skipping spotlight",
+        );
+        return null;
       }
       log.warn(
         {

package/src/plugins/defaults/memory-v3-shadow/orchestrate.ts

@@ -119,6 +119,10 @@ export interface OrchestrateDeps {
   /** Hard cap on total learned-lane surfaced articles; `0` disables the pass
    *  (canonical value: `memory.v3.learnedEdges.cap`). */
   learnedCap?: number;
+  /** The selector's system prompt. Omitted → the selector's bundled default.
+   *  The live caller resolves `memory.v3.selectorPromptPath` (workspace-relative
+   *  file override) via `resolveSelectorPrompt` and threads the result here. */
+  selectorPrompt?: string;
 }
 
 /** A finder-lane candidate: the slug, the descriptor that justified it, and
@@ -378,8 +382,13 @@ export async function orchestrate(
 
   // Step 3: a SINGLE forced-tool select over the cache-ordered pool. The
   // selections come back slug-deduped (pinned flags ORed) — `selectPool`'s
-  // contract.
-  const selections = await selectPool({ stable, finder: finderTail }, turn);
+  // contract. `selectorPrompt` is the (optionally overridden) instruction
+  // scaffold; `undefined` falls through to the bundled default.
+  const selections = await selectPool(
+    { stable, finder: finderTail },
+    turn,
+    deps.selectorPrompt,
+  );
 
   return {
     selections,

package/src/plugins/defaults/memory-v3-shadow/pool-select.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Tests for `pool-select.ts` `selectPool` — focused on error SURFACING:
+ *   - a provider call that THROWS on every attempt surfaces the underlying
+ *     provider error (e.g. an upstream HTTP 4xx) in the thrown
+ *     `MemoryV3RetrievalUnavailableError` message, rather than the generic
+ *     "no usable selection" string that hid it;
+ *   - a 200 response carrying no usable `tool_use` still throws the generic
+ *     "no usable selection" message;
+ *   - happy paths preserved: explicit ids → selection, omitted ids → keepAll,
+ *     empty pool → [].
+ *
+ * `mock.module` is process-global and leaks into sibling files in a directory
+ * run, so the provider-send-message stub DELEGATES to the real implementation
+ * (keeping the real `extractToolUse`) unless this test is actively running
+ * (`selectMockActive`) — mirrors `prune.test.ts` / `ever-injected-store.test.ts`.
+ */
+
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type {
+  ContentBlock,
+  Provider,
+  ProviderResponse,
+} from "../../../providers/types.js";
+import type { MemoryRoutingTurn, Slug } from "./types.js";
+
+const realProviderSend = {
+  ...(await import("../../../providers/provider-send-message.js")),
+};
+
+let selectMockActive = false;
+let sendMessageImpl: (() => Promise<ProviderResponse>) | null = null;
+
+const mockProvider = {
+  name: "mock-memory-v3-selector",
+  async sendMessage(): Promise<ProviderResponse> {
+    if (!sendMessageImpl) throw new Error("sendMessageImpl not configured");
+    return sendMessageImpl();
+  },
+} as unknown as Provider;
+
+mock.module("../../../providers/provider-send-message.js", () => ({
+  ...realProviderSend,
+  getConfiguredProvider: (
+    ...args: Parameters<typeof realProviderSend.getConfiguredProvider>
+  ) =>
+    selectMockActive
+      ? Promise.resolve(mockProvider)
+      : realProviderSend.getConfiguredProvider(...args),
+}));
+
+const { MemoryV3RetrievalUnavailableError, selectPool } =
+  await import("./pool-select.js");
+
+function response(content: ContentBlock[]): ProviderResponse {
+  return {
+    content,
+    model: "mock",
+    usage: { inputTokens: 0, outputTokens: 0 },
+  } as ProviderResponse;
+}
+
+const turn: MemoryRoutingTurn = {
+  conversationId: "conv-1",
+  turnNumber: 0,
+  currentMessage: "echo something back",
+  recentContext: "",
+};
+
+const pool = {
+  stable: [],
+  finder: [{ slug: "page-a" as Slug, descriptor: "a descriptor" }],
+};
+
+describe("selectPool", () => {
+  beforeEach(() => {
+    selectMockActive = true;
+    sendMessageImpl = null;
+  });
+  afterAll(() => {
+    selectMockActive = false;
+  });
+
+  test("a provider throw surfaces the underlying error in the thrown message", async () => {
+    const upstream = "Together AI API error (400): 400 status code (no body)";
+    sendMessageImpl = async () => {
+      throw new Error(upstream);
+    };
+    let caught: unknown;
+    try {
+      await selectPool(pool, turn);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(MemoryV3RetrievalUnavailableError);
+    expect((caught as Error).message).toContain(
+      "provider call failed after retries",
+    );
+    // The real upstream error is no longer hidden behind the generic message.
+    expect((caught as Error).message).toContain(upstream);
+  });
+
+  test("a 200 with no usable tool_use throws the generic message", async () => {
+    sendMessageImpl = async () =>
+      response([{ type: "text", text: "I cannot call the tool." }]);
+    let caught: unknown;
+    try {
+      await selectPool(pool, turn);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(MemoryV3RetrievalUnavailableError);
+    expect((caught as Error).message).toBe(
+      "memory-v3 pool selector returned no usable selection after retries",
+    );
+  });
+
+  test("explicit ids select the matching candidates", async () => {
+    sendMessageImpl = async () =>
+      response([
+        {
+          type: "tool_use",
+          id: "call-1",
+          name: "select_pages",
+          input: { ids: [1] },
+        },
+      ]);
+    expect(await selectPool(pool, turn)).toEqual([
+      { slug: "page-a", pinned: false },
+    ]);
+  });
+
+  test("omitted ids keep all candidates (recall-safe)", async () => {
+    sendMessageImpl = async () =>
+      response([
+        { type: "tool_use", id: "call-1", name: "select_pages", input: {} },
+      ]);
+    expect(await selectPool(pool, turn)).toEqual([
+      { slug: "page-a", pinned: false },
+    ]);
+  });
+
+  test("an empty candidate pool returns no selections", async () => {
+    expect(await selectPool({ stable: [], finder: [] }, turn)).toEqual([]);
+  });
+});

package/src/plugins/defaults/memory-v3-shadow/pool-select.ts

@@ -41,15 +41,16 @@
  *   - infrastructure failure (selector provider unavailable — e.g. a transient
  *     CES credential blip drops the API key — or no usable `tool_use` / schema
  *     mismatch surviving the short re-prompt retry) → throw
- *     {@link MemoryV3RetrievalUnavailableError}. There is NO deterministic-lane
- *     fallback: the LIVE injector propagates this to hard-fail the turn
- *     (retryable) rather than silently shipping it with no `<memory>` block,
- *     while the shadow/observation path swallows it and lets v2 retrieval serve
- *     the turn.
+ *     {@link MemoryV3RetrievalUnavailableError}. The live injector treats this
+ *     as a logged memory miss for the turn; shadow/observation callers swallow
+ *     it so v2 retrieval can serve the turn.
  */
 
 import { z } from "zod";
 
+import { classifyConversationError } from "../../../daemon/conversation-error.js";
+import type { PendingConversationNotice } from "../../../daemon/conversation-notices.js";
+import { loadPromptOverride } from "../../../memory/prompt-override.js";
 import { cachedTextBlock } from "../../../providers/cache-control.js";
 import {
   extractToolUse,
@@ -76,17 +77,43 @@ const log = getLogger("memory-v3-pool-select");
  * re-prompt retry. Deliberately DISTINCT from a deliberate empty selection
  * (`ids: []`) and an empty candidate pool, both of which return normally.
  *
- * The LIVE memory-v3 injector propagates this to hard-fail the turn (a clean,
- * retryable failure) rather than silently shipping with no memory; the
+ * The live memory-v3 injector logs this as a memory miss for the turn; the
  * shadow/observation path catches and swallows it.
  */
 export class MemoryV3RetrievalUnavailableError extends Error {
-  constructor(message: string) {
-    super(message);
+  readonly conversationNotice?: PendingConversationNotice;
+
+  constructor(
+    message: string,
+    options?: {
+      cause?: unknown;
+      conversationNotice?: PendingConversationNotice;
+    },
+  ) {
+    super(
+      message,
+      options?.cause === undefined ? undefined : { cause: options.cause },
+    );
     this.name = "MemoryV3RetrievalUnavailableError";
+    this.conversationNotice = options?.conversationNotice;
   }
 }
 
+function providerBillingNoticeFromError(
+  error: unknown,
+): PendingConversationNotice | undefined {
+  const classified = classifyConversationError(error, {
+    phase: "agent_loop",
+  });
+  if (classified.code !== "PROVIDER_BILLING") return undefined;
+  return {
+    source: "memory_v3",
+    code: classified.code,
+    userMessage: classified.userMessage,
+    errorCategory: classified.errorCategory,
+  };
+}
+
 /** A dynamic-tail (finder) candidate: the slug plus the descriptor that
  *  justifies it — a matched section for a needle/dense hit, or a curated link
  *  description for an edge page. Rendered as a one-line snippet, prefixed
@@ -201,6 +228,28 @@ A page can be relevant because of the current situation — the date or the live
 
 If the conversation is centrally ABOUT a page (rather than only peripherally relevant to it), mark that page as pinned. Call \`select_pages\` with the chosen IDs. Omit \`ids\` only as a recall-safe fallback when you cannot judge the pool (keeps every candidate); return \`[]\` when candidates are present but none are relevant.`;
 
+/**
+ * Resolve the selector system prompt: the file at `overridePath` when it is set
+ * and usable, otherwise the bundled {@link SYSTEM_PROMPT}. Path resolution and
+ * fallback follow the shared override loader (workspace-relative; a missing,
+ * empty, oversized, or unreadable file degrades to the bundled prompt with a
+ * warning). The selector prompt takes no placeholders — the candidate pool is
+ * the user message — so an override file is used verbatim.
+ */
+export function resolveSelectorPrompt(
+  overridePath: string | null,
+  workspaceDir: string,
+): string {
+  return (
+    loadPromptOverride({
+      overridePath,
+      workspaceDir,
+      log,
+      label: "memory-v3 selector prompt",
+    }) ?? SYSTEM_PROMPT
+  );
+}
+
 /** Collapse a descriptor to one line and cap its length for a finder line. */
 function renderSnippet(descriptor: string): string {
   return truncate(descriptor.replace(/\s+/g, " ").trim(), SNIPPET_MAX_CHARS);
@@ -315,10 +364,15 @@ function dedupeBySlug(
  * relevant" signal); an explicit `[]` keeps none; an infrastructure failure
  * (after a short re-prompt retry) keeps none, degrading to the deterministic
  * recall lanes the orchestrator unions in.
+ *
+ * `systemPrompt` is the selector's instruction scaffold; it defaults to the
+ * bundled {@link SYSTEM_PROMPT} and is overridable via `memory.v3.selectorPromptPath`
+ * (resolved by {@link resolveSelectorPrompt} at the call site).
  */
 export async function selectPool(
   pool: SelectorPool,
   turn: MemoryRoutingTurn,
+  systemPrompt: string = SYSTEM_PROMPT,
 ): Promise<SelectedPage[]> {
   // The concatenated numbering: ids 1…m are the stable-prefix cards, ids
   // m+1… are the finder lines.
@@ -340,7 +394,7 @@ export async function selectPool(
         stableCount: pool.stable.length,
         finderCount: pool.finder.length,
       },
-      "pool selector provider unavailable — failing the turn rather than dropping memory",
+      "pool selector provider unavailable",
     );
     throw new MemoryV3RetrievalUnavailableError(
       "memory-v3 pool selector provider unavailable",
@@ -394,6 +448,12 @@ export async function selectPool(
   // (no usable tool_use, or tool input that fails the schema) re-prompts before
   // we give up. `null` from an attempt means "unusable, retry"; the provider
   // layer already backs off transient throws, so this loop adds no delay.
+  //
+  // `lastError` captures the most recent attempt's thrown provider error —
+  // `retryForResult` swallows attempt throws, so without this an infrastructure
+  // failure (e.g. an upstream HTTP 4xx/5xx) is indistinguishable from a 200 that
+  // carried no usable tool_use. It is cleared on every attempt that reaches a
+  // response, so it reflects the LAST attempt's failure mode.
   let lastError: unknown = null;
   const parsed = await retryForResult(async () => {
     attempt += 1;
@@ -401,7 +461,7 @@ export async function selectPool(
     try {
       response = await provider.sendMessage([userMsg], {
         tools: [SELECT_PAGES_TOOL],
-        systemPrompt: SYSTEM_PROMPT,
+        systemPrompt,
         config: {
           callSite: MEMORY_V3_SELECT_CALL_SITE,
           tool_choice: { type: "tool" as const, name: SELECT_PAGES_TOOL_NAME },
@@ -476,10 +536,14 @@ export async function selectPool(
           providerName: provider.name,
           failures,
         },
-        "pool selector provider call failed after retries — failing the turn rather than dropping memory",
+        "pool selector provider call failed after retries",
       );
       throw new MemoryV3RetrievalUnavailableError(
         `memory-v3 pool selector provider call failed after retries: ${redactedDetail}`,
+        {
+          cause: lastError,
+          conversationNotice: providerBillingNoticeFromError(lastError),
+        },
       );
     }
     log.warn(
@@ -491,7 +555,7 @@ export async function selectPool(
         providerName: provider.name,
         failures,
       },
-      "pool selector returned no usable tool_use after retries — failing the turn rather than dropping memory",
+      "pool selector returned no usable tool_use after retries",
     );
     throw new MemoryV3RetrievalUnavailableError(
       "memory-v3 pool selector returned no usable selection after retries",

package/src/plugins/defaults/memory-v3-shadow/shadow-plugin.ts

@@ -56,7 +56,10 @@ import { computeHotSet } from "./hot-set.js";
 import { computeLearnedEdgeGraph } from "./learned-edges.js";
 import type { OrchestrateResult } from "./orchestrate.js";
 import { orchestrate } from "./orchestrate.js";
-import { MemoryV3RetrievalUnavailableError } from "./pool-select.js";
+import {
+  MemoryV3RetrievalUnavailableError,
+  resolveSelectorPrompt,
+} from "./pool-select.js";
 import { ensureSectionCollection } from "./section-dense-store.js";
 import type { SectionNeedle } from "./section-needle.js";
 import { buildSectionNeedle } from "./section-needle.js";
@@ -576,6 +579,10 @@ export async function observeTurn(
       learnedGraph: lanes.learnedGraph,
       learnedPerSeed: v3.learnedEdges.perSeed,
       learnedCap: v3.learnedEdges.cap,
+      selectorPrompt: resolveSelectorPrompt(
+        v3.selectorPromptPath,
+        getWorkspaceDir(),
+      ),
     });
 
     // A zero-selection turn over a non-trivial pool is unusual enough to be
@@ -598,13 +605,9 @@ export async function observeTurn(
     writeSelections(conversationId, turnIndex, rows);
     return result;
   } catch (err) {
-    // An INFRASTRUCTURE failure (the selector lost its provider — e.g. a
-    // transient CES credential blip) must NOT be silently swallowed: re-throw
-    // so the LIVE injector hard-fails the turn (a clean, retryable failure)
-    // rather than shipping it with no `<memory>` block. The shadow/observation
-    // callers (the injector in shadow mode, runShadowObservation) catch this
-    // and swallow it, so observation never fails a turn. Other (non-infra)
-    // errors stay non-fatal and degrade to no v3 block, as before.
+    // Infrastructure failures are surfaced to callers that want distinct
+    // logging from ordinary orchestration misses. Observation callers swallow
+    // them so memory-v3 never fails the turn.
     if (err instanceof MemoryV3RetrievalUnavailableError) {
       throw err;
     }
@@ -634,8 +637,6 @@ export async function runShadowObservation(
   try {
     await observeTurn(conversationId, turnIndex);
   } catch {
-    // Shadow observation is fire-and-forget and must NEVER fail a turn.
-    // `observeTurn` now re-throws infra failures so the LIVE injector can
-    // hard-fail on them; here (observation only) we swallow them.
+    // Shadow observation is fire-and-forget and must never fail a turn.
   }
 }

package/src/plugins/defaults/surface-completion-nudge/hooks/post-model-call.ts

@@ -45,7 +45,7 @@
  * the `post-model-call` chain — later hooks see (and may override) its decision.
  */
 
-import type { PluginHookFn, PostModelCallContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostModelCallContext } from "@vellumai/plugin-api";
 
 import type { ContentBlock, Message } from "../../../../providers/types.js";
 import {
@@ -246,7 +246,7 @@ function hasDanglingProgressSurface(messages: ReadonlyArray<Message>): boolean {
   return false;
 }
 
-const postModelCall: PluginHookFn<PostModelCallContext> = async (ctx) => {
+const postModelCall: HookFunction<PostModelCallContext> = async (ctx) => {
   // A provider rejection carries no turn content to assess (a recovery hook
   // owns the rejection).
   if (ctx.error) return;

package/src/plugins/defaults/surface-completion-nudge/hooks/stop.ts

@@ -11,11 +11,11 @@
  * refused).
  */
 
-import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+import type { HookFunction, StopContext } from "@vellumai/plugin-api";
 
 import { clearSurfaceCompletionNudged } from "../nudge-state-store.js";
 
-const stop: PluginHookFn<StopContext> = async (ctx) => {
+const stop: HookFunction<StopContext> = async (ctx) => {
   clearSurfaceCompletionNudged(ctx.conversationId);
 };
 

package/src/plugins/defaults/task-progress-nudge/hooks/post-tool-use.ts

@@ -45,7 +45,7 @@
  * below it (a new turn restarts counting low).
  */
 
-import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostToolUseContext } from "@vellumai/plugin-api";
 
 import type { ContentBlock, Message } from "../../../../providers/types.js";
 import { isWeakOpenModel } from "../../../../providers/weak-open-model.js";
@@ -134,7 +134,7 @@ function scanTurn(messages: ReadonlyArray<Message>): {
   return { rounds, taskProgressShown };
 }
 
-const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+const postToolUse: HookFunction<PostToolUseContext> = async (ctx) => {
   if (!isWeakOpenModel(ctx.model)) return;
 
   const { rounds, taskProgressShown } = scanTurn(ctx.messages);

package/src/plugins/defaults/title-generate/hooks/stop.ts

@@ -18,7 +18,7 @@
  * stateless and means a mid-run array rewrite (compaction) can't invalidate it.
  */
 
-import type { PluginHookFn, StopContext } from "@vellumai/plugin-api";
+import type { HookFunction, StopContext } from "@vellumai/plugin-api";
 
 import { getConfig } from "../../../../config/loader.js";
 import { getConversation } from "../../../../memory/conversation-crud.js";
@@ -65,7 +65,7 @@ function shouldRetryFallbackTitle(conversation: {
   );
 }
 
-const stop: PluginHookFn<StopContext> = async (ctx) => {
+const stop: HookFunction<StopContext> = async (ctx) => {
   // Re-title only at a genuine successful turn end (the model returned a reply
   // with no tool calls). Any other terminal — a provider rejection, abort, or
   // an output-limit cutoff — produced no new topic to re-title from.

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

@@ -11,14 +11,14 @@
  */
 
 import type {
-  PluginHookFn,
+  HookFunction,
   UserPromptSubmitContext,
 } from "@vellumai/plugin-api";
 
 import { getConversation } from "../../../../memory/conversation-crud.js";
 import { queueGenerateConversationTitle } from "../../../../memory/conversation-title-service.js";
 
-const userPromptSubmit: PluginHookFn<UserPromptSubmitContext> = async (ctx) => {
+const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (ctx) => {
   // System conversations (background/scheduled) carry a deterministic title
   // from bootstrap. Their own job prompts arrive as non-interactive turns and
   // must not spend an LLM call on a title nobody reads — only a genuine user

package/src/plugins/defaults/tool-error/hooks/post-tool-use.ts

@@ -22,7 +22,7 @@
  * result for the tool resets its streak.
  */
 
-import type { PluginHookFn, PostToolUseContext } from "@vellumai/plugin-api";
+import type { HookFunction, PostToolUseContext } from "@vellumai/plugin-api";
 
 import type { Message } from "../../../../providers/types.js";
 
@@ -85,7 +85,7 @@ function priorConsecutiveErrors(
   return streak;
 }
 
-const postToolUse: PluginHookFn<PostToolUseContext> = async (ctx) => {
+const postToolUse: HookFunction<PostToolUseContext> = async (ctx) => {
   if (ctx.toolResponse.is_error !== true) return;
 
   const namesById = toolNamesById(ctx.messages);