@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/plugins/defaults/memory/memory-retrospective-enqueue.ts

@@ -8,6 +8,13 @@
 //     musings from the retrospective agent's own writes).
 //   - Source isn't a `scheduled` thread or a memory-consolidation background
 //     (low yield — see `isLowYieldRetrospectiveSource`).
+//   - The unprocessed tail contains user activity, when
+//     `memory.retrospective.requireUserActivity` is on. Assistant-only
+//     stretches (proactive sends composed by turns running elsewhere) carry
+//     no user turn, so their window anchor is undecidable and their content
+//     is a recap of work captured at its source; the gate defers them until
+//     real user activity arrives. Living here, every trigger kind funnels
+//     through one check.
 //
 // All trigger types funnel through `upsertMemoryRetrospectiveJob` which
 // coalesces rapid enqueues into a single pending row per conversation.
@@ -23,10 +30,12 @@
 // hooks ran (crash / IPC drop) and the conversation then went idle. See
 // `memory-retrospective-sweep.ts`.
 
+import { getConfig } from "../../../config/loader.js";
 import {
   getConversation,
   getConversationSource,
 } from "../../../persistence/conversation-crud.js";
+import { MEMORY_V2_CONSOLIDATION_SOURCE } from "../../../persistence/conversation-types.js";
 import {
   isMemoryEnabled,
   upsertMemoryRetrospectiveJob,
@@ -34,8 +43,9 @@ import {
 import { type TrustClass } from "../../../runtime/actor-trust-resolver.js";
 import { resolveCapabilities } from "../../../runtime/capabilities.js";
 import { getLogger } from "./logging.js";
+import { hasQualifyingUserMessageAfter } from "./memory-retrospective-accounting.js";
 import { isMemoryRetrospectiveSource } from "./memory-retrospective-constants.js";
-import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./substrate/constants.js";
+import { getRetrospectiveState } from "./memory-retrospective-state.js";
 
 const log = getLogger("memory-retrospective-enqueue");
 
@@ -47,14 +57,19 @@ export type MemoryRetrospectiveTrigger =
 
 const COMPACTION_DEBOUNCE_MS = 500;
 
+/**
+ * Returns true when a job row was upserted, false when a gate skipped the
+ * enqueue (or the upsert failed). The sweep counts only true returns toward
+ * its per-pass cap.
+ */
 export function enqueueMemoryRetrospectiveIfEnabled(args: {
   conversationId: string;
   trigger: MemoryRetrospectiveTrigger;
-}): void {
+}): boolean {
   const { conversationId, trigger } = args;
 
   if (!isMemoryEnabled()) {
-    return;
+    return false;
   }
 
   if (isMemoryRetrospectiveConversation(conversationId)) {
@@ -62,7 +77,7 @@ export function enqueueMemoryRetrospectiveIfEnabled(args: {
       { conversationId, trigger },
       "Skipping memory-retrospective enqueue: source is a memory-retrospective conversation",
     );
-    return;
+    return false;
   }
 
   if (isLowYieldRetrospectiveSource(conversationId)) {
@@ -70,7 +85,11 @@ export function enqueueMemoryRetrospectiveIfEnabled(args: {
       { conversationId, trigger },
       "Skipping memory-retrospective enqueue: scheduled or consolidation source",
     );
-    return;
+    return false;
+  }
+
+  if (!passesUserActivityGate(conversationId, trigger)) {
+    return false;
   }
 
   const runAfter =
@@ -83,6 +102,46 @@ export function enqueueMemoryRetrospectiveIfEnabled(args: {
       { err, conversationId, trigger },
       "Failed to upsert memory-retrospective job",
     );
+    return false;
+  }
+  return true;
+}
+
+/**
+ * The `memory.retrospective.requireUserActivity` gate: pass when the config
+ * is off or the unprocessed tail (everything after the conversation's
+ * `lastProcessedMessageId`) contains at least one user message carrying
+ * non-tool_result content. A gate that cannot be evaluated (config or DB
+ * unavailable) passes — an unevaluable gate must not silence retrospectives.
+ */
+function passesUserActivityGate(
+  conversationId: string,
+  trigger: MemoryRetrospectiveTrigger,
+): boolean {
+  try {
+    if (!getConfig().memory.retrospective.requireUserActivity) {
+      return true;
+    }
+    const state = getRetrospectiveState(conversationId);
+    if (
+      hasQualifyingUserMessageAfter(
+        conversationId,
+        state?.lastProcessedMessageId ?? null,
+      )
+    ) {
+      return true;
+    }
+    log.debug(
+      { conversationId, trigger },
+      "Skipping memory-retrospective enqueue: no user activity in the unprocessed tail",
+    );
+    return false;
+  } catch (err) {
+    log.warn(
+      { err, conversationId, trigger },
+      "User-activity gate check failed; enqueueing anyway",
+    );
+    return true;
   }
 }
 

package/src/plugins/defaults/memory/memory-retrospective-job.ts

@@ -80,7 +80,10 @@ import { wakeAgentForOpportunity } from "../../../runtime/agent-wake.js";
 import { recordWatchdogEvent } from "../../../telemetry/watchdog-events-store.js";
 import { findMostRecentRetrospectiveFor } from "./find-most-recent-retrospective-for.js";
 import { getLogger } from "./logging.js";
-import { getRetrospectiveMessagesAfter } from "./memory-retrospective-accounting.js";
+import {
+  getRetrospectiveMessagesAfter,
+  messagesHaveUserActivity,
+} from "./memory-retrospective-accounting.js";
 import {
   MEMORY_RETROSPECTIVE_FORK_SOURCE,
   MEMORY_RETROSPECTIVE_GROUP_ID,
@@ -125,6 +128,7 @@ const MEMORY_RETROSPECTIVE_RUN_CHECK_NAME = "memory_retrospective_run";
 export type MemoryRetrospectiveOutcome =
   | { kind: "disabled" }
   | { kind: "no_new_messages" }
+  | { kind: "no_user_activity" }
   | { kind: "source_dormant" }
   | { kind: "source_processing" }
   | { kind: "wake_failed"; reason?: string; conversationId?: string }
@@ -174,6 +178,7 @@ export async function memoryRetrospectiveJob(
   try {
     outcome = await runForkBasedRetrospective(sourceConversationId, config, {
       enforceSweepLookback: true,
+      enforceUserActivityGate: true,
     });
   } catch (err) {
     emitRunOutcome("error", err instanceof Error ? err.message : String(err));
@@ -209,6 +214,14 @@ export async function runForkBasedRetrospective(
      * window.
      */
     enforceSweepLookback?: boolean;
+    /**
+     * Apply the `memory.retrospective.requireUserActivity` gate to the loaded
+     * slice. The queue handler passes this so rows that predate the enqueue
+     * gate (or that lost their user activity to a cursor race) complete as
+     * no-ops; the CLI's manual command omits it — an operator's explicit
+     * request overrides the gate.
+     */
+    enforceUserActivityGate?: boolean;
   },
 ): Promise<MemoryRetrospectiveOutcome> {
   // Start stamp for the retrospective's end-to-end wall time, surfaced as
@@ -305,6 +318,23 @@ export async function runForkBasedRetrospective(
     return { kind: "no_new_messages" };
   }
 
+  // Execution-time twin of the enqueue funnel's user-activity gate. An
+  // assistant-only slice has no user turn to anchor the review window on and
+  // recaps work captured at its source, so it is deferred, not run: both
+  // state pointers stay untouched and the slice is reviewed by the first
+  // retrospective after real user activity arrives.
+  if (
+    opts?.enforceUserActivityGate === true &&
+    config.memory.retrospective.requireUserActivity &&
+    !messagesHaveUserActivity(newMessages)
+  ) {
+    log.info(
+      { sourceConversationId, newMessageCount: newMessages.length },
+      "memory-retrospective (fork): unprocessed tail has no user activity; skipping",
+    );
+    return { kind: "no_user_activity" };
+  }
+
   const cutoffMessage = newMessages[newMessages.length - 1];
   if (!cutoffMessage) {
     return { kind: "no_new_messages" };
@@ -497,6 +527,11 @@ export async function runForkBasedRetrospective(
       hintRole: "user",
       skipHintInjection: true,
       suppressAutoCompaction: true,
+      // Finalization consumes the window (cursor advance + prior-retro GC)
+      // on `invoked: true`, so an empty reply with no usable output must
+      // fail the wake and leave the window retryable instead of reading as
+      // a successful pass (LUM-3013).
+      requireUsableOutput: true,
       // The fork's title already reads "(Retrospective)", so an empty-body
       // "Conversation Woke" surface card on top of it would be noise. Suppress
       // it — clients should display the fork as a normal background conv.

package/src/plugins/defaults/memory/memory-retrospective-sweep.ts

@@ -42,7 +42,9 @@
 //   - Enqueues route through `enqueueMemoryRetrospectiveIfEnabled`, whose
 //     `upsertMemoryRetrospectiveJob` coalesces against any already-pending job,
 //     so a conversation already queued by an event trigger is never
-//     double-processed.
+//     double-processed. An enqueue the funnel's gates decline (recursion,
+//     low-yield, user-activity) returns false and does not consume the
+//     per-pass cap.
 //   - Enqueues are capped at `SWEEP_MAX_ENQUEUES_PER_PASS` per pass. Inside
 //     the lookback window, organic stalled work is a handful of conversations;
 //     a pass wanting more signals an anomalous backlog. Each pass re-scans
@@ -65,6 +67,7 @@ import { and, asc, gt, ne, notInArray } from "drizzle-orm";
 import type { AssistantConfig } from "../../../config/types.js";
 import { AUTO_ANALYSIS_SOURCE } from "../../../persistence/auto-analysis-constants.js";
 import { getConversationRecentProvenanceTrustClass } from "../../../persistence/conversation-crud.js";
+import { MEMORY_V2_CONSOLIDATION_SOURCE } from "../../../persistence/conversation-types.js";
 import { getDb } from "../../../persistence/db-connection.js";
 import type { MemoryJob } from "../../../persistence/jobs-store.js";
 import {
@@ -77,7 +80,6 @@ import { countRetrospectiveMessagesAfter } from "./memory-retrospective-accounti
 import { MEMORY_RETROSPECTIVE_SOURCES } from "./memory-retrospective-constants.js";
 import { enqueueMemoryRetrospectiveIfEnabled } from "./memory-retrospective-enqueue.js";
 import { getRetrospectiveState } from "./memory-retrospective-state.js";
-import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./substrate/constants.js";
 
 const log = getLogger("memory-retrospective-sweep");
 
@@ -277,7 +279,14 @@ export async function runRetrospectiveSweep(
         continue;
       }
 
-      enqueueMemoryRetrospectiveIfEnabled({ conversationId, trigger: "sweep" });
+      if (
+        !enqueueMemoryRetrospectiveIfEnabled({
+          conversationId,
+          trigger: "sweep",
+        })
+      ) {
+        continue;
+      }
       enqueued += 1;
       if (enqueued >= SWEEP_MAX_ENQUEUES_PER_PASS) {
         log.warn(

package/src/plugins/defaults/memory/src/__tests__/memory-v2-simulate-route.test.ts

@@ -35,6 +35,7 @@ import type { ToolDefinition } from "../../llm-helpers.js";
 mock.module("../../substrate/skill-store.js", () => ({
   SKILL_SLUG_PREFIX: "skills/",
   listSkillEntries: () => [],
+  listAlwaysCandidateSkillSlugs: () => [],
   seedV2SkillEntries: async () => undefined,
 }));
 

package/src/plugins/defaults/memory/substrate/__tests__/skill-store.test.ts

@@ -15,6 +15,10 @@
  *     slugs (`"skills/example-skill"`).
  *   - It swallows errors from the embedding backend — the function resolves
  *     and the cache is unchanged from prior state.
+ *   - `listAlwaysCandidateSkillSlugs` serves pins (and their renderable cards)
+ *     from the local catalog before any seed run completes, applies the same
+ *     enablement/flag filtering the seeding path does, and yields to the seeded
+ *     snapshot once one lands.
  *
  * Hermetic by design: the embedding backend, Qdrant module, and feature-flag
  * resolver are module-mocked so the suite never reaches a real backend. One
@@ -55,6 +59,7 @@ interface BackfillCall {
 
 interface TestState {
   catalog: SkillSummary[] | null;
+  catalogThrows: Error | null;
   resolved: ResolvedSkill[] | null;
   fullCatalog: CatalogSkill[];
   fullCatalogThrows: Error | null;
@@ -69,10 +74,12 @@ interface TestState {
   backfillReturn: number;
   backfillThrows: Error | null;
   callSequence: Array<"upsert" | "prune" | "backfill">;
+  catalogLoadCount: number;
 }
 
 const state: TestState = {
   catalog: [],
+  catalogThrows: null,
   resolved: [],
   fullCatalog: [],
   fullCatalogThrows: null,
@@ -87,10 +94,17 @@ const state: TestState = {
   backfillReturn: 0,
   backfillThrows: null,
   callSequence: [],
+  catalogLoadCount: 0,
 };
 
 mock.module("../../../../../config/skills.js", () => ({
-  loadSkillCatalog: () => state.catalog ?? [],
+  loadSkillCatalog: () => {
+    state.catalogLoadCount += 1;
+    if (state.catalogThrows) {
+      throw state.catalogThrows;
+    }
+    return state.catalog ?? [];
+  },
 }));
 
 mock.module("../../../../../config/skill-state.js", () => ({
@@ -187,6 +201,7 @@ mock.module("../../../../../skills/catalog-cache.js", () => ({
 const {
   seedV2SkillEntries,
   getSkillCapability,
+  listAlwaysCandidateSkillSlugs,
   listSkillEntries,
   _resetSkillStoreForTests,
 } = await import("../skill-store.js");
@@ -210,6 +225,7 @@ function makeSummary(overrides: Partial<SkillSummary> = {}): SkillSummary {
 
 function resetState(): void {
   state.catalog = [];
+  state.catalogThrows = null;
   state.resolved = [];
   state.fullCatalog = [];
   state.fullCatalogThrows = null;
@@ -224,6 +240,7 @@ function resetState(): void {
   state.backfillReturn = 0;
   state.backfillThrows = null;
   state.callSequence.length = 0;
+  state.catalogLoadCount = 0;
   _resetSkillStoreForTests();
 }
 
@@ -286,6 +303,34 @@ describe("seedV2SkillEntries", () => {
     expect(state.upsertCalls[0].slug).toBe("skills/example-skill-a");
   });
 
+  test("reports enabled always-candidate skills and excludes disabled ones", async () => {
+    const pinned = makeSummary({
+      id: "example-skill-a",
+      alwaysCandidate: true,
+    });
+    const pinnedButDisabled = makeSummary({
+      id: "example-skill-b",
+      alwaysCandidate: true,
+    });
+    const ordinary = makeSummary({ id: "example-skill-c" });
+    state.catalog = [pinned, pinnedButDisabled, ordinary];
+    state.resolved = [
+      { summary: pinned, state: "enabled" },
+      { summary: pinnedButDisabled, state: "disabled" },
+      { summary: ordinary, state: "enabled" },
+    ];
+    state.embedReturn = [
+      [0.1, 0.2, 0.3],
+      [0.4, 0.5, 0.6],
+    ];
+
+    await seedV2SkillEntries();
+
+    expect(await listAlwaysCandidateSkillSlugs()).toEqual([
+      "skills/example-skill-a",
+    ]);
+  });
+
   test("does not re-seed an installed-but-disabled skill from the remote catalog", async () => {
     // Regression: if `seenIds` is built only from enabled skills, a locally
     // installed-but-disabled skill falls through to the catalog loop and gets
@@ -880,6 +925,155 @@ Write a local article draft.
   });
 });
 
+describe("listAlwaysCandidateSkillSlugs — pre-seed catalog fallback", () => {
+  // Always-candidate membership is a static catalog fact. The boot seed is
+  // fire-and-forget and needs Qdrant plus a configured embedding backend, so on
+  // a freshly hatched assistant turn 1 lands before it finishes. Reading the
+  // catalog directly is what keeps the pin (and its card) alive on that turn.
+
+  test("reports always-candidate slugs before any seed run completes", async () => {
+    const pinned = makeSummary({
+      id: "example-skill-a",
+      displayName: "Skill A",
+      alwaysCandidate: true,
+    });
+    const ordinary = makeSummary({ id: "example-skill-b" });
+    state.catalog = [pinned, ordinary];
+    state.resolved = [
+      { summary: pinned, state: "enabled" },
+      { summary: ordinary, state: "enabled" },
+    ];
+
+    expect(await listAlwaysCandidateSkillSlugs()).toEqual([
+      "skills/example-skill-a",
+    ]);
+    // No seed ran, so nothing was embedded.
+    expect(state.upsertCalls).toHaveLength(0);
+  });
+
+  test("excludes disabled and flag-gated skills exactly as the seeding path does", async () => {
+    const pinned = makeSummary({
+      id: "example-skill-a",
+      alwaysCandidate: true,
+    });
+    const pinnedButDisabled = makeSummary({
+      id: "example-skill-b",
+      alwaysCandidate: true,
+    });
+    // Flag gating is resolved host-side: the gated skill is absent from
+    // `resolveSkillStates`, so it surfaces as `state: "unavailable"`.
+    const pinnedButGated = makeSummary({
+      id: "example-skill-c",
+      alwaysCandidate: true,
+      featureFlag: "off-flag",
+    });
+    state.catalog = [pinned, pinnedButDisabled, pinnedButGated];
+    state.resolved = [
+      { summary: pinned, state: "enabled" },
+      { summary: pinnedButDisabled, state: "disabled" },
+    ];
+
+    expect(await listAlwaysCandidateSkillSlugs()).toEqual([
+      "skills/example-skill-a",
+    ]);
+    expect(getSkillCapability("example-skill-b")).toBeNull();
+    expect(getSkillCapability("example-skill-c")).toBeNull();
+  });
+
+  test("renders the pinned skill's card content on the fallback path", async () => {
+    // The load-bearing half: `renderInjectionBlock` resolves each pinned slug
+    // through `getSkillCapability`, so a pin whose card does not resolve is
+    // silently dropped from the block.
+    const pinned = makeSummary({
+      id: "example-skill-a",
+      displayName: "Skill A",
+      description: "Draws inline visuals",
+      activationHints: ["user asks for a chart", "user asks for a diagram"],
+      avoidWhen: ["user wants a spreadsheet"],
+      alwaysCandidate: true,
+    });
+    state.catalog = [pinned];
+    state.resolved = [{ summary: pinned, state: "enabled" }];
+
+    const slugs = await listAlwaysCandidateSkillSlugs();
+    expect(slugs).toEqual(["skills/example-skill-a"]);
+
+    const entry = getSkillCapability(slugs[0]);
+    expect(entry).not.toBeNull();
+    expect(entry?.id).toBe("example-skill-a");
+    expect(entry?.content).toContain('The "Skill A" skill');
+    expect(entry?.content).toContain("Draws inline visuals");
+    // The larger always-candidate budget switches the hints to a bulleted list,
+    // proving the fallback renders through the same `buildSkillContent` budget
+    // the seeding path uses.
+    expect(entry?.content).toContain("Use when:\n- user asks for a chart");
+    expect(entry?.content).toContain("Avoid when:\n- user wants a spreadsheet");
+    // Bare-id lookup resolves the same entry.
+    expect(getSkillCapability("example-skill-a")).toEqual(entry);
+  });
+
+  test("scans the catalog once and reuses the fallback across turns", async () => {
+    const pinned = makeSummary({
+      id: "example-skill-a",
+      alwaysCandidate: true,
+    });
+    state.catalog = [pinned];
+    state.resolved = [{ summary: pinned, state: "enabled" }];
+
+    await listAlwaysCandidateSkillSlugs();
+    const afterFirst = state.catalogLoadCount;
+    expect(afterFirst).toBeGreaterThan(0);
+
+    await listAlwaysCandidateSkillSlugs();
+    await listAlwaysCandidateSkillSlugs();
+
+    expect(state.catalogLoadCount).toBe(afterFirst);
+  });
+
+  test("the seeded snapshot replaces the fallback once a seed completes", async () => {
+    const pinned = makeSummary({
+      id: "example-skill-a",
+      displayName: "Skill A",
+      alwaysCandidate: true,
+    });
+    state.catalog = [pinned];
+    state.resolved = [{ summary: pinned, state: "enabled" }];
+
+    expect(await listAlwaysCandidateSkillSlugs()).toEqual([
+      "skills/example-skill-a",
+    ]);
+
+    // The user disables the skill, then a seed run lands: the seeded snapshot
+    // is authoritative and the stale fallback must not resurrect the pin.
+    state.resolved = [{ summary: pinned, state: "disabled" }];
+    state.embedReturn = [];
+    await seedV2SkillEntries();
+
+    expect(await listAlwaysCandidateSkillSlugs()).toEqual([]);
+    expect(getSkillCapability("example-skill-a")).toBeNull();
+    expect(listSkillEntries()).toEqual([]);
+  });
+
+  test("a catalog read failure degrades to an empty pin set and is retried next turn", async () => {
+    const pinned = makeSummary({
+      id: "example-skill-a",
+      alwaysCandidate: true,
+    });
+    state.catalog = [pinned];
+    state.resolved = [{ summary: pinned, state: "enabled" }];
+    state.catalogThrows = new Error("skills directory unreadable");
+
+    expect(await listAlwaysCandidateSkillSlugs()).toEqual([]);
+
+    // A failed build is not latched, so the next turn picks the catalog up.
+    state.catalogThrows = null;
+
+    expect(await listAlwaysCandidateSkillSlugs()).toEqual([
+      "skills/example-skill-a",
+    ]);
+  });
+});
+
 describe("getSkillCapability", () => {
   test("returns null before any seed run", () => {
     expect(getSkillCapability("example-skill-a")).toBeNull();

package/src/plugins/defaults/memory/substrate/consolidation-job.ts

@@ -83,6 +83,7 @@ import {
   getMemoryCheckpoint,
   setMemoryCheckpoint,
 } from "../../../../persistence/checkpoints.js";
+import { MEMORY_V2_CONSOLIDATION_SOURCE } from "../../../../persistence/conversation-types.js";
 import {
   enqueueMemoryJob,
   hasPendingJobOfType,
@@ -99,7 +100,6 @@ import {
   releaseLock,
   tryAcquireLock,
 } from "./consolidation-lock.js";
-import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./constants.js";
 import { getPageIndex, type PageParseFailure } from "./page-index.js";
 import { resolveConsolidationPrompt } from "./prompts/consolidation.js";
 import { resolveSubstrateTuning } from "./tuning.js";