@vellumai/assistant 0.8.10 → 0.8.11-staging.1

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

@@ -9,7 +9,7 @@
  *     injection is bit-for-bit identical — the only difference is the
  *     side-effect telemetry write.
  *   - `memory-v3-live`: live injection. The injector (`memoryV3Injector` in
- *     `./injector.ts`) additionally renders the working-set selection into a
+ *     `./injector.ts`) additionally renders this turn's selections into a
  *     `<memory>` block and returns it at v2's dynamic-memory placement
  *     (`after-memory-prefix`). Selections are still logged.
  *   - both OFF: orchestration is skipped entirely.
@@ -17,8 +17,8 @@
  * On each turn (either flag on):
  *   1. Lazy-init the v3 lanes ONCE across the whole process (section index,
  *      section-grain BM25 needle, dense lane config, link-graph edge graph,
- *      carry-forward working set), memoizing the init promise so concurrent
- *      first turns share a single build.
+ *      curated core set, frecency hot set), memoizing the init promise so
+ *      concurrent first turns share a single build.
  *   2. Build a {@link MemoryRoutingTurn} from the conversation's recent messages.
  *   3. Run {@link orchestrate} and record its selection set to
  *      `memory_v3_selections` with a best-effort lane attribution.
@@ -46,8 +46,11 @@ import {
 } from "../../../util/platform.js";
 import { stripCommentLines } from "../../../util/strip-comment-lines.js";
 import { capabilityOrDiskBody } from "./capabilities.js";
+import { renderCard } from "./card.js";
+import { loadCoreSet } from "./core-set.js";
 import type { EdgeGraph } from "./edge.js";
 import { buildEdgeGraph } from "./edge.js";
+import { computeHotSet } from "./hot-set.js";
 import type { OrchestrateResult } from "./orchestrate.js";
 import { orchestrate } from "./orchestrate.js";
 import { ensureSectionCollection } from "./section-dense-store.js";
@@ -60,7 +63,6 @@ import {
   type SelectionSource,
   type Slug,
 } from "./types.js";
-import { WorkingSet } from "./working-set.js";
 
 export const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
 export const MEMORY_V3_LIVE = "memory-v3-live" as const;
@@ -71,10 +73,12 @@ const log = getLogger("memory-v3-shadow");
 const RECENT_CONTEXT_MESSAGES = 6;
 
 /**
- * The lazily-built, process-lifetime v3 lanes. The working set is stateful
- * (carry-forward across turns), so it is intentionally shared across every
- * shadow turn rather than rebuilt per turn — that is the whole point of the
- * carry-forward lane.
+ * The lazily-built, process-lifetime v3 lanes. The core and hot sets are
+ * computed here (not per turn) because they are the candidate pool's STABLE
+ * PREFIX — recomputing them mid-conversation would reorder the prefix and bust
+ * the selector's KV cache. Lane memoization is the recompute cadence:
+ * `invalidateLanes()` (called by the maintain job at consolidation) forces a
+ * rebuild on the next turn.
  */
 export interface ShadowLanes {
   sectionIndex: SectionIndex;
@@ -83,9 +87,20 @@ export interface ShadowLanes {
    *  collection. */
   denseConfig: AssistantConfig;
   edgeGraph: EdgeGraph;
-  workingSet: WorkingSet;
+  /** Curated core set in file order, filtered to pages in the section index. */
+  coreSlugs: string[];
+  /** Frecency hot set in score order: core excluded, filtered to pages in the
+   *  section index. */
+  hotSlugs: string[];
+  /** Pre-rendered FULL cards for the stable-prefix (core+hot) slugs, keyed by
+   *  slug. Frozen at lane build so the selector's stable prefix is
+   *  byte-identical across turns until the next invalidation. */
+  prefixCards: Map<Slug, string>;
 }
 
+/** Milliseconds per day — converts `hotSet.halfLifeDays` config to ms. */
+const DAY_MS = 24 * 60 * 60 * 1000;
+
 /**
  * Memoized init promise. Caching the PROMISE (not the resolved value) means
  * concurrent first turns all await the same build instead of racing several
@@ -151,11 +166,49 @@ async function initLanes(config: AssistantConfig): Promise<ShadowLanes> {
 
   const sectionIndex = await buildSectionIndex(slugs, pageBody);
   const needle = buildSectionNeedle(sectionIndex);
+
+  // The stable-prefix lanes. Core is the maintainer-curated file (file order
+  // preserved — it is the prefix's stable sort), filtered to pages that exist
+  // in the live section index so a dangling entry can never reach the pool.
+  // Hot is the frecency top-K over `memory_v3_selections` with core excluded
+  // (hot never duplicates core), filtered the same way — selection rows can
+  // outlive their pages. Both are recomputed only on lane invalidation (the
+  // consolidation cadence), keeping the prefix stable between rebuilds.
+  const coreSlugs = loadCoreSet(getWorkspaceDir()).filter((slug) =>
+    sectionIndex.byArticle.has(slug),
+  );
+  const hotSlugs = computeHotSet(
+    { db: getDb() },
+    {
+      k: config.memory.v3.hotSet.k,
+      halfLifeMs: config.memory.v3.hotSet.halfLifeDays * DAY_MS,
+      now: Date.now(),
+      excludeSlugs: new Set(coreSlugs),
+    },
+  )
+    .map((entry) => entry.slug)
+    .filter((slug) => sectionIndex.byArticle.has(slug));
+
+  // Pre-render the stable-prefix cards ONCE per lane build: the selector's
+  // stable prefix must be byte-identical across turns to ride the provider KV
+  // cache, so the cards are frozen here (lane invalidation at consolidation is
+  // the recompute point) instead of being re-read per turn. Capability slugs
+  // render their capability content; disk pages render raw (frontmatter +
+  // body) so `kind: index` pages surface their `links:` map in the card TOC.
+  const prefixCards = new Map<Slug, string>();
+  for (const slug of [...coreSlugs, ...hotSlugs]) {
+    const raw = await capabilityOrDiskBody(
+      slug,
+      async (s) => (await loadPage(s))?.raw ?? "",
+    );
+    prefixCards.set(slug, renderCard(slug, raw));
+  }
+
   const edgeGraph = await buildEdgeGraph(pageIndex.entries, pageRaw, {
     hubDegree: config.memory.v3.edge.hubDegree,
   });
   // Ensuring the dense collection is best-effort: the needle + edge lanes and
-  // carry-forward are in-memory and independent of Qdrant, so a Qdrant outage
+  // the core/hot prefix are in-memory and independent of Qdrant, so a Qdrant outage
   // must NOT reject lane init (which would return `null` from observeTurn and
   // disable ALL of v3, plus poison the memoized lanes until invalidation). On
   // failure we log and continue with the dense lane degraded — denseLane already
@@ -170,17 +223,14 @@ async function initLanes(config: AssistantConfig): Promise<ShadowLanes> {
     );
   }
 
-  const workingSet = new WorkingSet(
-    config.memory.v3.workingSet.maxPages,
-    config.memory.v3.workingSet.evictWindow,
-  );
-
   return {
     sectionIndex,
     needle,
     denseConfig: config,
     edgeGraph,
-    workingSet,
+    coreSlugs,
+    hotSlugs,
+    prefixCards,
   };
 }
 
@@ -273,33 +323,31 @@ interface SelectionRow {
 }
 
 /**
- * Map an orchestrate result onto telemetry rows with precise per-lane source
- * attribution.
- *
- * - A current selection is tagged with the candgen lane that FIRST surfaced its
- *   page this turn — `result.laneBySlug` (`"needle"` / `"dense"` / `"edge"`),
- *   recorded at pool-build time. (`"needle"` is the fallback if a selected slug
- *   is somehow absent from the lane map, which should not happen since every
- *   pooled candidate is recorded there.)
- * - A slug in `finalInjection` but NOT re-selected this turn → `"carry-forward"`.
+ * Map an orchestrate result onto telemetry rows with per-lane source
+ * attribution, by pool position: a selection of a stable-prefix page is
+ * attributed `"core"` / `"hot"` (the lane that placed it in the pool), and any
+ * other selection is attributed the finder lane that FIRST surfaced it
+ * (`"needle"` / `"dense"` / `"edge"`, recorded at pool-build time). A finder
+ * hit on a core/hot page therefore still logs as core/hot — the prefix is
+ * where the candidate lived. (`"needle"` is the fallback if a selected slug is
+ * somehow absent from every lane, which should not happen since every pooled
+ * candidate comes from one.)
  */
 export function attributeSelections(result: OrchestrateResult): SelectionRow[] {
-  const rows: SelectionRow[] = [];
-  const seen = new Set<Slug>();
-  for (const sel of result.currentSelections) {
-    seen.add(sel.slug);
-    rows.push({
-      slug: sel.slug,
-      source: result.laneBySlug.get(sel.slug) ?? "needle",
-      pinned: sel.pinned ? 1 : 0,
-    });
-  }
-  for (const slug of result.finalInjection) {
-    if (seen.has(slug)) continue;
-    seen.add(slug);
-    rows.push({ slug, source: "carry-forward", pinned: 0 });
-  }
-  return rows;
+  const core = new Set<Slug>(result.lanes.core);
+  const hot = new Set<Slug>(result.lanes.hot);
+  const finderLane = new Map(
+    result.lanes.finder.map((c) => [c.slug, c.lane] as const),
+  );
+  return result.selections.map((sel) => ({
+    slug: sel.slug,
+    source: core.has(sel.slug)
+      ? ("core" as const)
+      : hot.has(sel.slug)
+        ? ("hot" as const)
+        : (finderLane.get(sel.slug) ?? "needle"),
+    pinned: sel.pinned ? 1 : 0,
+  }));
 }
 
 /** Write the attributed selection rows to `memory_v3_selections`. */
@@ -338,6 +386,7 @@ export async function observeTurn(
     if (!turn) return null;
 
     const cfg = getConfig();
+    if (cfg.memory.enabled === false) return null;
     const lanes = await getLanes(cfg);
     const v3 = cfg.memory.v3;
     const result = await orchestrate(turn, {
@@ -345,7 +394,9 @@ export async function observeTurn(
       needle: lanes.needle,
       denseConfig: lanes.denseConfig,
       edgeGraph: lanes.edgeGraph,
-      workingSet: lanes.workingSet,
+      coreSlugs: lanes.coreSlugs,
+      hotSlugs: lanes.hotSlugs,
+      prefixCards: lanes.prefixCards,
       needleK: v3.needleK,
       denseK: v3.denseK,
       edgeSeeds: v3.edge.seedCount,
@@ -377,6 +428,8 @@ export async function runShadowObservation(
   conversationId: string,
   turnIndex: number,
 ): Promise<void> {
-  if (!isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, getConfig())) return;
+  const config = getConfig();
+  if (config.memory.enabled === false) return;
+  if (!isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config)) return;
   await observeTurn(conversationId, turnIndex);
 }

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

@@ -10,6 +10,26 @@ export type Slug = string;
  */
 export const MEMORY_V3_BLOCK_ID = "memory-v3" as const;
 
+/**
+ * `meta` key under which the v3 cards block carries its attachment-commit
+ * callback. The injector defers its everInjected-store write (and the
+ * prune-valve schedule) into this callback; runtime assembly invokes it only
+ * when the turn's tail is a user message — the same gate as metadata capture
+ * — so a block that silently fails to attach never claims its cards in the
+ * dedup store. Shared between the producer (`injector.ts`) and the consumer
+ * (`conversation-runtime-assembly.ts`) so a rename is a compile error on both
+ * sides instead of a silent never-commit.
+ */
+export const MEMORY_V3_COMMIT_META_KEY = "memoryV3Commit" as const;
+
+/**
+ * Injection-block id for the v3 ephemeral `<memory_spotlight>` block (the
+ * current window's matched sections, re-rendered at the user tail each turn).
+ * Distinct from {@link MEMORY_V3_BLOCK_ID}: the spotlight never participates
+ * in v2 suppression and is never persisted to message metadata.
+ */
+export const MEMORY_V3_SPOTLIGHT_BLOCK_ID = "memory-v3-spotlight" as const;
+
 /**
  * A single section of a page: the lead (text before the first `## heading`,
  * ordinal 0) or a heading-delimited block. Over-long sections are split into
@@ -40,13 +60,6 @@ export interface SelectedPage {
   pinned: boolean;
 }
 
-export interface WorkingSetEntry {
-  slug: Slug;
-  selectedAtTurn: number;
-  pinned: boolean;
-  lastSeenTurn: number;
-}
-
 export interface MemoryRoutingTurn {
   conversationId: string;
   turnNumber: number;
@@ -68,25 +81,29 @@ export interface MemoryRoutingTurn {
  * exactly one place and the runtime list (used for telemetry roll-ups and
  * source validation) can never drift from the type.
  *
+ * `core` / `hot` are the stable-prefix lanes (curated core set, frecency hot
+ * set); `needle` / `dense` / `edge` are the per-turn finder lanes.
+ *
  * The `memory_v3_selections.source` column is free-text, so tightening this set
- * needs no migration: any historical rows with older labels still read back
- * fine via the permissive `z.string()` row schema.
+ * needs no migration: any historical rows with retired labels (e.g. the old
+ * per-turn carry source) still read back fine via the permissive `z.string()`
+ * row schema — they just don't aggregate into a named bucket.
  */
 export const SELECTION_SOURCES = [
+  "core",
+  "hot",
   "needle",
   "dense",
   "edge",
-  "carry-forward",
 ] as const;
 
 export type SelectionSource = (typeof SELECTION_SOURCES)[number];
 
 /**
- * The candidate-generation lanes — the strict subset of {@link SelectionSource}
- * a pooled candidate can be tagged with at pool-build time. (`carry-forward` is
- * the one source assigned later, by the orchestrator's working-set union, not by
- * a candgen lane.) Defined as `Exclude<SelectionSource, "carry-forward">` so it
- * can never drift from {@link SELECTION_SOURCES}: adding a lane there widens this
- * automatically.
+ * The per-turn finder lanes — the strict subset of {@link SelectionSource} a
+ * finder candidate can be tagged with at pool-build time. (`core` / `hot` are
+ * assigned by stable-prefix membership, not by a finder.) Defined via
+ * `Exclude` so it can never drift from {@link SELECTION_SOURCES}: adding a
+ * finder lane there widens this automatically.
  */
-export type CandidateLane = Exclude<SelectionSource, "carry-forward">;
+export type FinderLane = Exclude<SelectionSource, "core" | "hot">;

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

@@ -50,23 +50,21 @@ function countUserTurns(messages: ReadonlyArray<Message>): number {
 }
 
 const stop: PluginHookFn<StopContext> = async (ctx) => {
-  // Only re-title at a genuine turn end. A `"continue"` decision means an
-  // earlier hook is re-querying the model (e.g. an empty-response nudge), so
-  // defer to the eventual terminal stop.
-  if (ctx.decision !== "stop") return;
+  // 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.
+  if (ctx.exitReason !== "no_tool_calls") return;
 
   if (getConfig().conversations.skipAutoRetitling) return;
 
   if (countUserTurns(ctx.messages) !== SECOND_PASS_USER_TURN) return;
 
   const { conversationId } = ctx;
-  // Deferred to a later macrotask so the just-completed turn lands first. The
-  // hook fires at the stop boundary, before the loop appends the turn's
-  // assistant reply to history and emits `message_complete` (which persists
-  // it). The service regenerates from the most recent stored messages, so it
-  // must run after the reply is persisted to reflect it. The service is itself
-  // fire-and-forget and re-checks replaceability, owning provider resolution,
-  // persistence, and the resulting broadcast.
+  // Deferred to a later macrotask so the just-completed turn's persistence
+  // settles first. The service regenerates from the most recent stored
+  // messages, so it must run after the reply is persisted to reflect it. The
+  // service is itself fire-and-forget and re-checks replaceability, owning
+  // provider resolution, persistence, and the resulting broadcast.
   setTimeout(() => {
     queueRegenerateConversationTitle({ conversationId });
   }, 0);

package/src/plugins/pipeline.ts

@@ -4,7 +4,9 @@
  * A "hook" is a named lifecycle event (`user-prompt-submit`, `post-tool-use`,
  * …) that every registered plugin may handle. The runner walks each plugin's
  * hook for a given event in registration order, threading a context value
- * through the chain so hooks can observe and transform it.
+ * through the chain so hooks can observe and transform it. A hook either
+ * mutates the context in place (returning `void`) or returns a partial
+ * context whose fields are merged onto the threaded value.
  *
  * Design doc: `.private/plans/agent-plugin-system.md`.
  */
@@ -17,9 +19,10 @@ import { getHooksFor } from "./registry.js";
 /**
  * Execute a hook chain: walk every registered plugin's hook for `name` in
  * registration order, threading `initialCtx` through each. Hooks may either
- * mutate the context in place (returning `void`) or return a new context
- * that replaces the threaded value for subsequent hooks. The final context
- * after the chain settles is returned.
+ * mutate the context in place (returning `void`) or return a partial context
+ * whose fields are merged onto the threaded value — keys the hook returns
+ * overwrite the running context, every other field is preserved. The final
+ * context after the chain settles is returned.
  *
  * @param name        The hook identifier — pick one from {@link HOOKS}.
  * @param initialCtx  Context the first hook receives.
@@ -35,7 +38,7 @@ export async function runHook<TCtx>(
   for (const hook of getHooksFor<TCtx>(name)) {
     const result = await hook(active);
     if (result !== undefined) {
-      active = result;
+      active = { ...active, ...result };
     }
   }
   return active;

package/src/plugins/types.ts

@@ -317,12 +317,11 @@ export interface Injector {
 }
 
 // ─── Model-visible capability slots ──────────────────────────────────────────
-// Concrete shapes are defined by the tool/route/skill registries. Tool
-// contributions (PR 31) use the canonical `Tool` interface; route
-// contributions (PR 32) use the `SkillRoute` shape from the skill-route
-// registry; skill contributions (PR 33) ship with the concrete
-// `PluginSkillRegistration` shape below so plugins can declare
-// catalog-discoverable skills today.
+// Concrete shapes are defined by the tool/route registries. Tool
+// contributions use the canonical `Tool` interface; route contributions use
+// the `SkillRoute` shape from the skill-route registry. Skills ship on disk
+// inside an installed plugin (`plugins/<name>/skills/<id>/SKILL.md`) and are
+// discovered by the skill catalog loader, so they need no contribution slot.
 
 /**
  * HTTP route registration contributed by a plugin. Plugins express routes as
@@ -336,49 +335,6 @@ export interface Injector {
  */
 export type PluginRouteRegistration = SkillRoute;
 
-/**
- * A skill contributed by a plugin.
- *
- * When a plugin declares {@link Plugin.skills}, the bootstrap registers each
- * entry into an in-memory side catalog that {@link loadSkillCatalog} merges
- * into its output. The entry is then discoverable by the model's `skill_load`
- * / `skill_execute` flow under `source: "plugin"` — the same code paths used
- * for filesystem-backed skills.
- *
- * The fields mirror the subset of `SkillSummary` / `SkillDefinition` that
- * makes sense for an in-memory contribution. Inline commands and reference
- * files are out of scope for plugin skills in this PR — add them later if a
- * real plugin needs them.
- */
-export interface PluginSkillRegistration {
-  /** Stable skill id (kebab-case). Must be unique across the catalog. */
-  id: string;
-  /**
-   * Skill "name" as surfaced to the model. Matches the SKILL.md frontmatter
-   * `name` field for filesystem skills.
-   */
-  name: string;
-  /**
-   * Human-readable display name shown in UI lists. Defaults to `name` when
-   * omitted — matches the filesystem-skill default.
-   */
-  displayName?: string;
-  /** One-line description shown by `skill_load` / UI. */
-  description: string;
-  /** Full skill body returned when `skill_load` fires for this skill. */
-  body: string;
-  /** Optional emoji shown beside the skill in UI surfaces. */
-  emoji?: string;
-  /** Optional assistant feature-flag key — when set and the flag is OFF, the skill is filtered out. */
-  featureFlag?: string;
-  /** Compact routing cues injected into `<available_skills>` to guide selection. */
-  activationHints?: string[];
-  /** Conditions under which this skill should NOT be loaded. */
-  avoidWhen?: string[];
-  /** IDs of child skills that this skill includes (metadata-only, not auto-activated). */
-  includes?: string[];
-}
-
 // ─── Plugin ──────────────────────────────────────────────────────────────────
 
 /**
@@ -420,8 +376,6 @@ export interface Plugin {
   tools?: Tool[];
   /** HTTP route registrations served by the assistant. */
   routes?: PluginRouteRegistration[];
-  /** Skill registrations loaded at startup. */
-  skills?: PluginSkillRegistration[];
 }
 
 // ─── Errors ──────────────────────────────────────────────────────────────────

package/src/providers/cache-control.ts

@@ -0,0 +1,26 @@
+import type { ContentBlock } from "./types.js";
+
+/**
+ * Build a text content block carrying an ephemeral `cache_control` breakpoint
+ * with a 1h TTL, marking a byte-stable prefix the provider KV cache should
+ * persist across calls.
+ *
+ * The Anthropic SDK accepts the field as an extra property on text blocks, but
+ * the internal `TextContent` type intentionally omits it (only the Anthropic
+ * provider transforms it onto the wire — block-level `cache_control` is
+ * preserved through `toAnthropicBlockSafe`), so we reach through a `Record`
+ * cast for the same reason `anthropic/client.ts` does — it keeps the core
+ * types provider-agnostic. The 1h TTL matches the provider's auto-applied
+ * breakpoints (see `cacheTtl` in `providers/anthropic/client.ts`); the
+ * `extended-cache-ttl-2025-04-11` beta header is added unconditionally for
+ * non-Haiku models in `client.ts` (Haiku models have the `ttl` stripped
+ * provider-side), so this works without any call-site config.
+ */
+export function cachedTextBlock(text: string): ContentBlock {
+  const block: ContentBlock = { type: "text", text };
+  (block as unknown as Record<string, unknown>).cache_control = {
+    type: "ephemeral",
+    ttl: "1h",
+  };
+  return block;
+}

package/src/providers/inference/__tests__/base-url-route-validation.test.ts

@@ -37,8 +37,7 @@ mock.module("../../../memory/db-connection.js", () => ({
 }));
 
 mock.module("../../../config/assistant-feature-flags.js", () => ({
-  isAssistantFeatureFlagEnabled: (flag: string) =>
-    flag === "openai-compatible-endpoints",
+  isAssistantFeatureFlagEnabled: () => false,
 }));
 
 mock.module("../../../config/loader.js", () => ({

package/src/providers/model-catalog.ts

@@ -1040,6 +1040,19 @@ const RAW_PROVIDER_CATALOG: ProviderCatalogEntry[] = [
         pricing: { inputPer1mTokens: 0.6, outputPer1mTokens: 2.5 },
       },
       // MiniMax
+      {
+        id: "minimax/minimax-m3",
+        displayName: "MiniMax M3",
+        // The model supports 1M context, but OpenRouter's only route
+        // (MiniMax) accepts 524,288 tokens; advertise the routed limit.
+        contextWindowTokens: 524288,
+        maxOutputTokens: 512000,
+        supportsThinking: true,
+        supportsCaching: false,
+        supportsVision: true,
+        supportsToolUse: true,
+        pricing: { inputPer1mTokens: 0.3, outputPer1mTokens: 1.2 },
+      },
       {
         id: "minimax/minimax-m2.7",
         displayName: "MiniMax M2.7",
@@ -1212,7 +1225,6 @@ const RAW_PROVIDER_CATALOG: ProviderCatalogEntry[] = [
     setupHint:
       "Enter the base URL of your endpoint and at least one model identifier.",
     apiKeyPlaceholder: "Your provider's API key",
-    featureFlag: "openai-compatible-endpoints",
     models: [],
     defaultModel: "",
   },