@vellumai/assistant 0.11.3 → 0.11.4-staging.1

package/src/plugins/defaults/memory/substrate/__tests__/static-context.test.ts

@@ -5,6 +5,7 @@
  *   - Reads the four files in canonical order and joins them under headings.
  *   - Skips empty / missing files.
  *   - Returns null when every file is empty or missing.
+ *   - Caps the Buffer section at `consolidation_max_buffer_lines`.
  */
 
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
@@ -33,12 +34,19 @@ mock.module("../../../../../util/logger.js", () => ({
 
 let configMemoryV2Enabled = true;
 let configMemoryEnabled = true;
+// Mirrors the `memory.v2.consolidation_max_buffer_lines` schema default; the
+// Buffer-cap tests move it.
+let configMaxBufferLines: number | null = 100;
 
-// static-context reads its gates through the plugin's own config accessor.
+// static-context reads its gates and the substrate tuning through the
+// plugin's own config accessor.
 mock.module("../../config.js", () => ({
   getMemoryConfig: () => ({
     enabled: configMemoryEnabled,
-    v2: { enabled: configMemoryV2Enabled },
+    v2: {
+      enabled: configMemoryV2Enabled,
+      consolidation_max_buffer_lines: configMaxBufferLines,
+    },
   }),
 }));
 
@@ -70,6 +78,7 @@ describe("readMemoryV2StaticContent", () => {
     mkdirSync(TEST_DIR, { recursive: true });
     configMemoryV2Enabled = true;
     configMemoryEnabled = true;
+    configMaxBufferLines = 100;
   });
 
   afterEach(() => {
@@ -165,6 +174,194 @@ describe("readMemoryV2StaticContent", () => {
   });
 });
 
+describe("readMemoryV2StaticContent Buffer cap", () => {
+  /** `n` timestamped buffer entries, oldest first, in `remember()`'s shape. */
+  function bufferEntries(n: number): string {
+    return Array.from(
+      { length: n },
+      (_, i) => `- [Jan 1, 9:00 AM] entry-${i}`,
+    ).join("\n");
+  }
+
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+    configMemoryV2Enabled = true;
+    configMemoryEnabled = true;
+    configMaxBufferLines = 10;
+  });
+
+  afterEach(() => {
+    cleanupMemoryDir();
+  });
+
+  test("passes a buffer at or under the cap through byte-identically", () => {
+    const buffer = bufferEntries(10);
+    writeMemoryFile("buffer.md", buffer);
+
+    expect(readMemoryV2StaticContent()).toBe(`## Buffer\n\n${buffer}`);
+  });
+
+  test("keeps the newest entries and drops the oldest when over the cap", () => {
+    writeMemoryFile("buffer.md", bufferEntries(30));
+
+    const text = readMemoryV2StaticContent()!;
+    expect(text).toContain(
+      "(Older entries trimmed. Read memory/buffer.md for the full backlog.)",
+    );
+    // The cap counts non-empty lines, matching the scheduler's
+    // `countBufferLines`, so exactly the newest 10 entries survive.
+    const kept = text
+      .split("\n")
+      .filter((line) => line.startsWith("- ["))
+      .map((line) => line.slice(line.lastIndexOf(" ") + 1));
+    expect(kept).toEqual(
+      Array.from({ length: 10 }, (_, i) => `entry-${i + 20}`),
+    );
+  });
+
+  test("never opens mid-entry when the cap lands inside a multiline fact", () => {
+    // The 5-line fact straddles the cap: counting back 10 non-empty lines
+    // lands on one of its continuation lines. Injecting from there would show
+    // orphan bullets with no timestamp and no opening clause.
+    const multiline = [
+      "- [Jan 1, 9:00 AM] the straddling fact",
+      "  - [ ] a checklist item inside the fact",
+      "  continuation prose",
+      "  - another bullet",
+      "  closing line",
+    ].join("\n");
+    writeMemoryFile(
+      "buffer.md",
+      `${bufferEntries(20)}\n${multiline}\n${bufferEntries(8)}`,
+    );
+
+    const text = readMemoryV2StaticContent()!;
+    const body = text.slice(text.indexOf("buffer.md for the full backlog.)\n"));
+    const firstLine = body.split("\n")[1]!;
+    expect(firstLine).toMatch(/^- \[Jan 1, 9:00 AM\]/);
+    // The partial entry is dropped whole: none of its continuation lines
+    // survive on their own.
+    expect(text).not.toContain("continuation prose");
+    expect(text).not.toContain("the straddling fact");
+  });
+
+  test("keeps the newest entry attributable when its body alone exceeds the cap", () => {
+    // The newest entry has no successor to fall back to: counting back 10
+    // non-empty lines lands inside its body and there is no later timestamped
+    // entry to open on. Dropping it would leave the section with no facts at
+    // all, so the entry's opening line is kept and its head elided.
+    writeMemoryFile(
+      "buffer.md",
+      [
+        ...Array.from(
+          { length: 20 },
+          (_, i) => `- [Jan 1, 9:00 AM] entry-${i}`,
+        ),
+        "- [Jan 2, 9:00 AM] the oversized fact",
+        ...Array.from({ length: 14 }, (_, i) => `  body line ${i}`),
+      ].join("\n"),
+    );
+
+    const text = readMemoryV2StaticContent()!;
+    const body = text
+      .slice(text.indexOf("full backlog.)\n") + "full backlog.)\n".length)
+      .split("\n")
+      .filter((line) => line.trim().length > 0);
+
+    // Opens on the entry's own timestamped line, never on an orphan body line.
+    expect(body[0]).toBe("- [Jan 2, 9:00 AM] the oversized fact");
+    expect(body[1]).toBe(
+      "(This entry's body was trimmed. Read memory/buffer.md for the rest of it.)",
+    );
+    // The retained tail is the newest end of the body, not its head.
+    expect(body.at(-1)).toBe("  body line 13");
+    expect(body).toContain("  body line 4");
+    expect(body).not.toContain("  body line 3");
+    // Bounded at the cap plus exactly the opening line and the marker, so the
+    // oversized entry cannot reintroduce an unbounded injection.
+    expect(body).toHaveLength(12);
+    // The older entries are still dropped.
+    expect(text).not.toContain("entry-19");
+  });
+
+  test("does not claim a trim when the newest entry's body exactly fills the cap", () => {
+    // The cut lands on the line right after the opening, so nothing of the
+    // entry was elided and the marker would be a lie.
+    writeMemoryFile(
+      "buffer.md",
+      [
+        ...Array.from(
+          { length: 20 },
+          (_, i) => `- [Jan 1, 9:00 AM] entry-${i}`,
+        ),
+        "- [Jan 2, 9:00 AM] the exact-fit fact",
+        ...Array.from({ length: 10 }, (_, i) => `  body line ${i}`),
+      ].join("\n"),
+    );
+
+    const text = readMemoryV2StaticContent()!;
+    const body = text
+      .slice(text.indexOf("full backlog.)\n") + "full backlog.)\n".length)
+      .split("\n")
+      .filter((line) => line.trim().length > 0);
+
+    expect(body[0]).toBe("- [Jan 2, 9:00 AM] the exact-fit fact");
+    expect(text).not.toContain("This entry's body was trimmed");
+    // The entry survives whole: opening line plus its full 10-line body.
+    expect(body).toHaveLength(11);
+    expect(body.at(-1)).toBe("  body line 9");
+    expect(body).toContain("  body line 0");
+  });
+
+  test("keeps a multiline entry intact when it sits fully inside the cap", () => {
+    const multiline = [
+      "- [Jan 1, 9:00 AM] a fact with a body",
+      "  second line of the same fact",
+    ].join("\n");
+    writeMemoryFile("buffer.md", `${bufferEntries(20)}\n${multiline}`);
+
+    const text = readMemoryV2StaticContent()!;
+    expect(text).toContain("a fact with a body");
+    expect(text).toContain("second line of the same fact");
+  });
+
+  test("falls back to the line cut for a buffer with no timestamped entries", () => {
+    // A hand-written buffer that never went through `remember()` has no entry
+    // structure to preserve, so the line-based cut stands rather than dropping
+    // everything.
+    const handWritten = Array.from(
+      { length: 30 },
+      (_, i) => `just a line ${i}`,
+    ).join("\n");
+    writeMemoryFile("buffer.md", handWritten);
+
+    const text = readMemoryV2StaticContent()!;
+    expect(text).toContain("just a line 29");
+    expect(text).not.toContain("just a line 0");
+  });
+
+  test("leaves the buffer unbounded when the size trigger is disabled", () => {
+    configMaxBufferLines = null;
+    const buffer = bufferEntries(30);
+    writeMemoryFile("buffer.md", buffer);
+
+    expect(readMemoryV2StaticContent()).toBe(`## Buffer\n\n${buffer}`);
+  });
+
+  test("caps only the Buffer section, never the curated views", () => {
+    const long = Array.from({ length: 30 }, (_, i) => `line-${i}`).join("\n");
+    writeMemoryFile("essentials.md", long);
+    writeMemoryFile("threads.md", long);
+    writeMemoryFile("recent.md", long);
+    writeMemoryFile("buffer.md", bufferEntries(30));
+
+    const lines = readMemoryV2StaticContent()!.split("\n");
+    expect(lines.filter((line) => line === "line-0")).toHaveLength(3);
+    expect(lines.filter((line) => line === "line-29")).toHaveLength(3);
+    expect(lines.some((line) => line.endsWith("entry-0"))).toBe(false);
+  });
+});
+
 describe("shouldExposePersonalMemory", () => {
   test("allows guardian-trusted local conversations", () => {
     expect(

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

@@ -91,7 +91,10 @@ import {
   type MemoryJobType,
 } from "../../../../persistence/jobs-store.js";
 import { runBackgroundJob } from "../../../../runtime/background-job-runner.js";
-import { formatBufferTimestamp } from "../graph/tool-handlers.js";
+import {
+  formatBufferTimestamp,
+  matchBufferEntryStart,
+} from "../buffer-format.js";
 import { getLogger } from "../logging.js";
 import { getWorkspaceDir } from "../paths.js";
 import {
@@ -597,32 +600,36 @@ function readBufferContent(bufferPath: string): string {
 
 /**
  * Extract the bracketed timestamp from a `buffer.md` entry line
- * (`- [Mon D, h:mm AM/PM] …`, see `formatBufferEntry`). Returned verbatim so
- * it can serve directly as a consolidation cutoff — both sides of the agent's
- * "timestamp ≥ cutoff" comparison then share the exact `formatBufferTimestamp`
- * shape.
+ * (`- [Mon D, h:mm AM/PM] …`, see {@link formatRememberEntry}). Returned
+ * verbatim so it can serve directly as a consolidation cutoff: both sides of
+ * the agent's "timestamp >= cutoff" comparison then share the exact
+ * {@link formatBufferTimestamp} shape.
  *
- * The bracket contents must match that shape exactly: a remembered fact's
- * continuation lines can themselves start with `- [` (markdown checklists
- * `- [ ] …`, wikilink bullets `- [[…]]`), and counting those as entries
- * would inflate the per-run budget — or worse, hand the agent a garbage
- * cutoff like a blank string. Returns `null` for anything that isn't a real
- * timestamped entry start.
+ * Recognition is delegated to the shared matcher, so a remembered fact's
+ * continuation lines never register as entries. That matters here beyond
+ * tidiness: counting a fact's `- [ ] …` checklist lines or an indented
+ * entry-shaped body line as entries would inflate the per-run budget, or hand
+ * the agent a cutoff drawn from the middle of a fact.
  */
 function extractBufferEntryTimestamp(line: string): string | null {
-  const match = /^\s*-\s*\[([A-Z][a-z]{2} \d{1,2}, \d{1,2}:\d{2} [AP]M)\]/.exec(
-    line,
-  );
-  return match ? match[1] : null;
+  return matchBufferEntryStart(line)?.timestamp ?? null;
 }
 
 /**
  * Count non-empty lines in `memory/buffer.md`. Used by the scheduler to
  * implement the size-based consolidation trigger. Missing file → 0.
  *
- * Each entry is one line (`- [Mon D, h:mm AM/PM] …\n`), so non-empty-line
- * count == entry count for a well-formed buffer; blank lines and trailing
- * newlines don't inflate the count.
+ * Lines, deliberately, not entries. A multiline `remember()` fact is one
+ * entry spread over several lines, so the two counts diverge and each answers
+ * a different question. This trigger and the injected-Buffer cap that reuses
+ * it (`capBufferSection` in `static-context.ts`) both care about how much
+ * context the buffer costs, which scales with lines. The per-run budget
+ * `consolidation_max_entries_per_run` cares about how many facts the agent
+ * must file, so it counts entry-start lines instead.
+ *
+ * Do not "fix" this to count entries: a single 200-line fact is a context
+ * problem the trigger should fire on, even though it is one entry. Blank
+ * lines and trailing newlines don't inflate the count.
  */
 export function countBufferLines(bufferPath: string): number {
   return countNonEmptyLines(readBufferContent(bufferPath));

package/src/plugins/defaults/memory/substrate/skill-content.ts

@@ -22,6 +22,13 @@ export interface SkillCapabilityInput {
  */
 export const ALWAYS_CANDIDATE_CARD_CHARS = 900;
 
+/**
+ * Character budget for an ordinary skill's capability statement. A statement
+ * that overruns is hard-truncated, dropping its trailing activation hints and
+ * its entire avoid-when list from what the selector sees.
+ */
+export const DEFAULT_CARD_CHARS = 500;
+
 /**
  * Render the prose-style capability statement embedded into the unified
  * `memory_v2_concept_pages` Qdrant collection (under the `skills/<id>` slug
@@ -32,7 +39,7 @@ export const ALWAYS_CANDIDATE_CARD_CHARS = 900;
  */
 export function buildSkillContent(
   input: SkillCapabilityInput,
-  maxChars = 500,
+  maxChars: number = DEFAULT_CARD_CHARS,
 ): string {
   const list = maxChars > 500;
   let content = `The "${input.displayName}" skill (${input.id}) is available. ${input.description}.`;

package/src/plugins/defaults/memory/substrate/static-context.ts

@@ -19,29 +19,180 @@
 // Refresh cadence is owned by the caller: the agent loop only passes the
 // content through when `mode === "full"` (first turn / post-compaction),
 // matching the existing PKB auto-inject pattern.
+//
+// Three of the four files are curated aggregate views that consolidation
+// keeps lean. `memory/buffer.md` is not: it is the raw append-only staging
+// log that `remember()` writes and consolidation drains, so its length is
+// bounded only by how far behind consolidation has fallen. The injected
+// Buffer section is therefore capped: see `capBufferSection`.
 
 import type { ChannelId } from "../../../../channels/types.js";
 import { usesConceptPageMemory } from "../../../../config/memory-v3-gate.js";
 import { readPromptFile } from "../../../../prompts/system-prompt.js";
+import { type BufferEntryLines, splitBufferEntries } from "../buffer-format.js";
 import { getMemoryConfig } from "../config.js";
 import { getWorkspacePromptPath } from "../paths.js";
+import { resolveSubstrateTuning } from "./tuning.js";
 
 interface MemoryV2StaticBlock {
   heading: string;
   file: string;
 }
 
+const BUFFER_FILE = "memory/buffer.md";
+
 const MEMORY_V2_STATIC_BLOCKS: readonly MemoryV2StaticBlock[] = [
   { heading: "## Essentials", file: "memory/essentials.md" },
   { heading: "## Threads", file: "memory/threads.md" },
   { heading: "## Recent", file: "memory/recent.md" },
-  { heading: "## Buffer", file: "memory/buffer.md" },
+  { heading: "## Buffer", file: BUFFER_FILE },
 ];
 
+/**
+ * Leader line on a Buffer section that was capped, so the model knows the
+ * section is a tail rather than the whole backlog and where the rest lives.
+ */
+const BUFFER_INJECTION_NOTICE =
+  "(Older entries trimmed. Read memory/buffer.md for the full backlog.)";
+
+/**
+ * Cap the Buffer section at its most recent `maxLines` non-empty lines,
+ * returning the content unchanged when it already fits or when `maxLines` is
+ * `null`.
+ *
+ * The bound is `consolidation_max_buffer_lines`, the same threshold at which
+ * the scheduler already considers the buffer overdue for consolidation (see
+ * `jobs-worker.ts`). Reusing it means the injected buffer never exceeds one
+ * consolidation's worth of backlog, and that a workspace whose consolidation
+ * keeps up sees byte-identical output. `null` disables the size trigger, so
+ * the operator has opted out of size-based buffer management and the
+ * injection is left unbounded to match.
+ *
+ * The unit is the entry, not the line. `remember()` stores a multiline fact
+ * as one timestamped line plus its body, so trimming by raw line count can
+ * land inside a fact and inject continuation lines stripped of the timestamp
+ * and opening clause that give them meaning. Whole entries are taken
+ * newest-first while they fit, which makes a mid-entry cut unrepresentable.
+ * Retained lines keep their original spacing; the notice replaces everything
+ * before them.
+ *
+ * `maxLines` is still measured in non-empty lines, because that is what the
+ * scheduler counts (`countBufferLines`), so the two readings of "how big is
+ * the buffer" agree. See {@link capOversizedNewestEntry} for the one case
+ * that can exceed it.
+ */
+function capBufferSection(content: string, maxLines: number | null): string {
+  if (maxLines === null) {
+    return content;
+  }
+  const lines = content.split("\n");
+  if (countNonEmpty(lines) <= maxLines) {
+    return content;
+  }
+
+  const entries = splitBufferEntries(lines);
+  const kept: BufferEntryLines[] = [];
+  let budget = maxLines;
+  // Newest-first: the buffer is append-only, so the tail is the most recent.
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i]!;
+    // A headless leading group is prose before the first entry, not a fact.
+    if (entry.start === null) {
+      break;
+    }
+    const cost = countNonEmpty(entry.lines);
+    if (cost > budget) {
+      break;
+    }
+    budget -= cost;
+    kept.unshift(entry);
+  }
+
+  const body =
+    kept.length > 0
+      ? kept.flatMap((entry) => entry.lines).join("\n")
+      : capOversizedNewestEntry(lines, entries, maxLines);
+  return `${BUFFER_INJECTION_NOTICE}\n${body}`;
+}
+
+/**
+ * Marker replacing the elided head of an entry too large to inject whole, so
+ * the retained tail reads as a fragment of the entry above it rather than as
+ * the whole fact.
+ */
+const ENTRY_BODY_TRIMMED_NOTICE =
+  "(This entry's body was trimmed. Read memory/buffer.md for the rest of it.)";
+
+/**
+ * Render the tail when not even the newest entry fits inside the cap.
+ *
+ * There is no whole entry to fall back to here, and all three options cost
+ * something. Dropping the entry would leave the section with a "trimmed"
+ * notice and no facts at all, which is the worst outcome because the newest
+ * fact is usually the one that mattered. Admitting it whole would reopen the
+ * unbounded injection the cap exists to prevent, since a fact has no size
+ * limit. So the entry keeps its opening line, which carries the timestamp and
+ * first clause the tail needs to be readable, then the marker, then as much
+ * of the tail as the cap allows. Every injected line stays attributable to a
+ * timestamped entry, at a fixed cost of two lines over `maxLines`.
+ *
+ * Two cases return early. When the cut falls on the opening line's immediate
+ * successor nothing was actually elided, so the entry is returned whole
+ * without a marker that would claim a trim that did not happen. When the
+ * buffer has no entry structure at all, it is hand-written and never went
+ * through `remember()`, so there is nothing to preserve and the plain line
+ * cut stands.
+ */
+function capOversizedNewestEntry(
+  lines: string[],
+  entries: readonly BufferEntryLines[],
+  maxLines: number,
+): string {
+  const cut = lineCutStart(lines, maxLines);
+  const newest = entries.at(-1);
+  if (newest === undefined || newest.start === null) {
+    return lines.slice(cut).join("\n");
+  }
+  const elidedHead = countNonEmpty(lines.slice(newest.firstLine + 1, cut)) > 0;
+  if (!elidedHead) {
+    return lines.slice(newest.firstLine).join("\n");
+  }
+  return [
+    lines[newest.firstLine]!,
+    ENTRY_BODY_TRIMMED_NOTICE,
+    ...lines.slice(cut),
+  ].join("\n");
+}
+
+/**
+ * Index of the first line in the trailing window of `maxLines` non-empty
+ * lines, advanced past any blank lines that would otherwise open the section.
+ */
+function lineCutStart(lines: readonly string[], maxLines: number): number {
+  let kept = 0;
+  let cut = lines.length;
+  while (cut > 0 && kept < maxLines) {
+    cut--;
+    if (lines[cut]!.trim().length > 0) {
+      kept++;
+    }
+  }
+  while (cut < lines.length && lines[cut]!.trim().length === 0) {
+    cut++;
+  }
+  return cut;
+}
+
+/** Non-empty line count, the unit the scheduler's `countBufferLines` uses. */
+function countNonEmpty(lines: readonly string[]): number {
+  return lines.filter((line) => line.trim().length > 0).length;
+}
+
 /**
  * Build the static memory block, gated on concept-page memory being active
  * ({@link usesConceptPageMemory}). Empty/missing files are skipped; returns
- * `null` when the gate is off or every file is empty.
+ * `null` when the gate is off or every file is empty. The Buffer section is
+ * capped by {@link capBufferSection}.
  *
  * `excludeBuffer` drops the `## Buffer` section. The consolidation run sets
  * it: the agent's contract there is the `memory/buffer.md` FILE — it reads,
@@ -57,17 +208,22 @@ export function readMemoryV2StaticContent(
   if (!usesConceptPageMemory(memoryConfig)) {
     return null;
   }
+  const maxBufferLines =
+    resolveSubstrateTuning(memoryConfig).consolidation_max_buffer_lines;
 
   const sections: string[] = [];
   for (const { heading, file } of MEMORY_V2_STATIC_BLOCKS) {
-    if (options.excludeBuffer === true && file === "memory/buffer.md") {
+    const isBuffer = file === BUFFER_FILE;
+    if (options.excludeBuffer === true && isBuffer) {
       continue;
     }
     const content = readPromptFile(getWorkspacePromptPath(file));
     if (!content) {
       continue;
     }
-    sections.push(`${heading}\n\n${content}`);
+    sections.push(
+      `${heading}\n\n${isBuffer ? capBufferSection(content, maxBufferLines) : content}`,
+    );
   }
   return sections.length > 0 ? sections.join("\n\n") : null;
 }

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

@@ -44,10 +44,8 @@ import {
   conversations,
   messages,
 } from "../../../../persistence/schema/index.js";
-import {
-  appendBufferAndArchive,
-  formatRememberEntry,
-} from "../graph/tool-handlers.js";
+import { formatRememberEntry } from "../buffer-format.js";
+import { appendBufferAndArchive } from "../graph/tool-handlers.js";
 import {
   extractToolUse,
   type ToolDefinition,

package/src/plugins/defaults/memory/v1/graph/extraction.ts

@@ -1365,7 +1365,9 @@ function resolveConversationTimestamp(conversationId: string): number | null {
   const db = getDb();
   // Use the last message timestamp, not the conversation creation time.
   // A conversation can span hours/days — memories should be timestamped
-  // to when the relevant content was actually discussed.
+  // to when the relevant content was actually discussed. Any-state read,
+  // deliberately: only `createdAt` is consumed, and a streaming last row
+  // still marks when discussion happened.
   const lastMsg = db
     .select({ createdAt: messages.createdAt })
     .from(messages)

package/src/plugins/defaults/memory/v3/prune.ts

@@ -293,6 +293,8 @@ export function collectPersistedV3Cards(conversationId: string): Set<string> {
   const rows = getSqliteFrom(getDb())
     .query(
       /*sql*/ `
+      -- Any-state scan: only metadata markers are read, and the marker is
+      -- written by the injection path on rows it owns regardless of state.
       SELECT metadata FROM messages
       WHERE conversation_id = ? AND metadata LIKE '%' || ? || '%'
     `,

package/src/plugins/defaults/memory/v3/selection-log-store.ts

@@ -97,6 +97,8 @@ function forkSourceIdsOf(messageIds: string[]): string[] {
     .query(
       /*sql*/ `
       SELECT json_extract(metadata, '$.forkSourceMessageId') AS src
+      -- No completeness predicate: ids come from this store's own selection
+      -- log, written for rows the injection pipeline already processed.
       FROM messages
       WHERE id IN (${placeholders})
     `,

package/src/plugins/defaults/memory/worker.ts

@@ -27,6 +27,7 @@ import {
   cleanupWorkerPidFile,
   startWorkerPidFileGuard,
 } from "../../../util/worker-process.js";
+import { registerWorkerPluginSurface } from "../../worker-plugin-surface.js";
 import { registerMemoryPluginJobHandlers } from "./job-handler-registration.js";
 import { startMemoryJobsWorkerLoop } from "./jobs-worker.js";
 import { getLogger } from "./logging.js";
@@ -59,9 +60,11 @@ async function main(): Promise<void> {
   // and are rejected.
   await rehydratePlatformCredentials();
 
-  // This process does not run plugin bootstrap, so self-register the job
-  // handlers the worker dispatches from before starting it — the memory
-  // plugin's own plus the host's non-plugin domain handlers.
+  // Jobs in this process wake real agent conversations, so it registers the
+  // default plugin hook surface (hooks and injectors, no init hooks) the same
+  // way the daemon does, and the job handlers the worker dispatches from: the
+  // memory plugin's own plus the host's non-plugin domain handlers.
+  registerWorkerPluginSurface();
   registerMemoryPluginJobHandlers();
 
   // Populate the tool registry (core built-ins + workspace tools), exactly as

package/src/plugins/external-plugin-loader.ts

@@ -92,6 +92,12 @@ const PluginPackageJsonSchema = z
     version: z.string().optional(),
     peerDependencies: z.record(z.string(), z.string()).optional(),
     credentialKeyPatterns: z.unknown().optional(),
+    /** Human title, when the package name is not one ("@vellumai/imessage"). */
+    displayName: z.string().min(1).optional(),
+    /** Standard npm field, reused as the one-line description clients show. */
+    description: z.string().min(1).optional(),
+    /** Lucide icon name without the `lucide-` prefix, matching `ChannelInfo`. */
+    icon: z.string().min(1).optional(),
   })
   .passthrough();
 
@@ -466,6 +472,47 @@ export async function loadExternalPlugin(
  * surface the failure through their own channel (e.g. the schedule
  * reconciler's per-day deduped notification).
  */
+/**
+ * How a plugin presents itself: its title, its one line, its glyph.
+ *
+ * Every field is optional and none of them gate anything. A surface that
+ * shows a plugin falls back rather than hiding it, so a missing `icon`
+ * costs an icon and not the row.
+ */
+export interface PluginPresentation {
+  displayName?: string;
+  description?: string;
+  icon?: string;
+}
+
+/**
+ * Read a plugin's presentation fields from its manifest.
+ *
+ * Separate from {@link parsePluginManifest} because the two answer different
+ * questions: that one decides whether a plugin is loadable, this one only
+ * dresses it for display. An unreadable or invalid manifest yields `undefined`
+ * here rather than an error, since a caller showing a plugin has already
+ * established it exists.
+ */
+export async function parsePluginPresentation(
+  pluginDir: string,
+): Promise<PluginPresentation | undefined> {
+  let rawPkg: unknown;
+  try {
+    rawPkg = JSON.parse(
+      await readFile(join(pluginDir, "package.json"), "utf8"),
+    );
+  } catch {
+    return undefined;
+  }
+  const parsed = PluginPackageJsonSchema.safeParse(rawPkg);
+  if (!parsed.success) {
+    return undefined;
+  }
+  const { displayName, description, icon } = parsed.data;
+  return { displayName, description, icon };
+}
+
 export async function parsePluginManifest(
   pluginDir: string,
   opts: { quiet?: boolean } = {},