@vellumai/assistant 0.12.2 → 0.12.3-staging.2

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

@@ -1,4 +1,5 @@
-import { safeStringSlice } from "../host-utils.js";
+import { safeStringSlice } from "@vellumai/plugin-api";
+
 import type { Section, SectionIndex, Slug } from "./types.js";
 
 /**

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

@@ -19,7 +19,9 @@
  *   3. Run {@link orchestrate} and record its selection set to
  *      `memory_v3_selections` with a best-effort lane attribution, plus the
  *      full candidate pool and verdict to `memory_v3_pools` for the inspector,
- *      as one transaction ({@link writeTurnLog}).
+ *      and, under `memory.v3.poolLog.captureInput`, the selector's exact
+ *      input to `memory_v3_pool_inputs` / `memory_v3_pool_texts`, as one
+ *      transaction ({@link writeTurnLog}).
  *
  * {@link observeTurn} wraps everything in try/catch — any failure is logged and
  * swallowed so it can never affect the live turn. The injector treats a
@@ -32,6 +34,7 @@ import {
   getMessages,
   listInstalledSkills,
   parseMessageMetadata,
+  safeStringSlice,
   stringifyMessageContent,
   VOICE_ESCALATION_CONTINUATION_MESSAGE_KIND,
 } from "@vellumai/plugin-api";
@@ -44,7 +47,7 @@ import {
   timeLatencySubSpan,
 } from "../../../../daemon/turn-latency-sub-spans.js";
 import { enqueueMemoryJob } from "../../../../persistence/jobs-store.js";
-import { safeStringSlice, stripCommentLines } from "../host-utils.js";
+import { stripCommentLines } from "../host-utils.js";
 import { getLogger } from "../logging.js";
 import { type MemorySqlite, memorySqliteOrNull } from "../memory-db.js";
 import { getWorkspaceDir, getWorkspacePromptPath } from "../paths.js";
@@ -69,9 +72,12 @@ import type { OrchestrateResult } from "./orchestrate.js";
 import { orchestrate } from "./orchestrate.js";
 import { ensureMemoryV3SelectionsSectionKeyOnce } from "./plugin-schema.js";
 import {
+  buildPoolInput,
   buildPoolRecord,
+  type PoolInputCapture,
   type PoolRecord,
   writePool,
+  writePoolInput,
 } from "./pool-log-store.js";
 import {
   MemoryV3RetrievalUnavailableError,
@@ -635,8 +641,16 @@ interface SelectionRow {
  * The row holds one section per slug: the selection's FIRST selected section
  * (pool order) stands for the page; a page selected with no section (a card,
  * or a section-less edge or learned line) logs none.
+ *
+ * A turn whose selector could not run (`selectorFailure`) logs no rows: its
+ * selections are the stable prefix kept unjudged, and the selection table is
+ * what the hot set's frecency and the learned-edge graph read as judgments.
+ * The pool record still carries the turn for the inspector.
  */
 export function attributeSelections(result: OrchestrateResult): SelectionRow[] {
+  if (result.selectorFailure) {
+    return [];
+  }
   const core = new Set<Slug>(result.lanes.core);
   const hot = new Set<Slug>(result.lanes.hot);
   const fresh = new Set<Slug>(result.lanes.fresh);
@@ -729,20 +743,24 @@ function replaceSelections(
 /**
  * Write the turn's log over the dedicated memory connection: its attributed
  * selection rows to `memory_v3_selections` and its candidate pool to
- * `memory_v3_pools`, in one transaction. A turn observed again (a retried or
- * re-entered turn index) replaces its rows in both tables as a unit, so the
- * pool's `chosen` flags and the selection rows always describe the same
- * observation. Best-effort: an unavailable memory database or a failed
- * statement drops this observation's log rather than affecting the turn, and
- * the transaction leaves the earlier observation's rows in place in both
- * tables. The selection table's plugin-owned `section_key` column is ensured
- * on the first use of a connection in this process (`plugin-schema.ts`).
+ * `memory_v3_pools`, plus, when the caller captured it under
+ * `memory.v3.poolLog.captureInput`, the selector's exact `input` to
+ * `memory_v3_pool_inputs` / `memory_v3_pool_texts`, in one transaction. A
+ * turn observed again (a retried or re-entered turn index) replaces its rows
+ * in every table as a unit, so the pool's `chosen` flags, the selection rows,
+ * and the captured input always describe the same observation. Best-effort:
+ * an unavailable memory database or a failed statement drops this
+ * observation's log rather than affecting the turn, and the transaction
+ * leaves the earlier observation's rows in place in every table. The
+ * selection table's plugin-owned `section_key` column is ensured on the
+ * first use of a connection in this process (`plugin-schema.ts`).
  */
 export function writeTurnLog(
   conversationId: string,
   turn: number,
   rows: SelectionRow[],
   pool: PoolRecord,
+  input?: PoolInputCapture,
 ): void {
   try {
     const raw = memorySqliteOrNull("writeTurnLog");
@@ -753,6 +771,9 @@ export function writeTurnLog(
     raw.transaction(() => {
       replaceSelections(raw, conversationId, turn, rows);
       writePool(raw, conversationId, turn, pool);
+      if (input) {
+        writePoolInput(raw, conversationId, turn, input);
+      }
     })();
   } catch (err) {
     log.warn(
@@ -845,6 +866,10 @@ export async function observeTurn(
     // against the same store the injector renders from. This turn has not
     // committed yet, so the set matches what the injector will see.
     const activeSections = getActiveSections(conversationId);
+    const selectorPrompt = resolveSelectorPrompt(
+      v3.selectorPromptPath,
+      getWorkspaceDir(),
+    );
     const result = await orchestrate(turn, {
       sectionIndex: lanes.sectionIndex,
       needle: lanes.needle,
@@ -877,10 +902,7 @@ export async function observeTurn(
       learnedPerSeed: v3.learnedEdges.perSeed,
       learnedCap: tuning.learnedEdgesCap,
       selectorEnabled: tuning.selectorEnabled,
-      selectorPrompt: resolveSelectorPrompt(
-        v3.selectorPromptPath,
-        getWorkspaceDir(),
-      ),
+      selectorPrompt,
       // Per-turn injection gate: the `memory.v3.gate` tuning, `enabled`
       // kill-switch included. Read-only downstream, so the config object is
       // passed as-is.
@@ -910,6 +932,11 @@ export async function observeTurn(
       turnIndex,
       attributeSelections(result),
       buildPoolRecord(result),
+      // The selector's exact input, captured only when opted in: the context
+      // strings and every pooled candidate's rendered text.
+      v3.poolLog.captureInput
+        ? buildPoolInput(result, turn, selectorPrompt)
+        : undefined,
     );
     recordLatencySubSpan(
       "v3_persist",

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

@@ -18,13 +18,19 @@ import {
   type WorkerProcessStatus,
 } from "../../../util/worker-process.js";
 
+const MEMORY_WORKER_ENTRY = new URL("./worker.ts", import.meta.url);
+
 /**
  * Inspect the PID file to determine whether the worker process is alive.
- * A stale PID file (pointing at a dead process) is cleaned up and reported
- * as not_running.
+ * A stale PID file (pointing at a dead process, or at a live process that
+ * is not this worker) is cleaned up and reported as not_running.
  */
 export function probeMemoryWorker(): WorkerProcessStatus {
-  return probeWorkerPidFile(getMemoryWorkerPidPath());
+  return probeWorkerPidFile(
+    getMemoryWorkerPidPath(),
+    MEMORY_WORKER_ENTRY,
+    "memory",
+  );
 }
 
 export class MemoryWorkerSpawnError extends WorkerProcessSpawnError {}
@@ -50,7 +56,7 @@ export async function spawnMemoryWorkerProcess(
   try {
     return await spawnWorkerProcess({
       pidPath: getMemoryWorkerPidPath(),
-      entry: new URL("./worker.ts", import.meta.url),
+      entry: MEMORY_WORKER_ENTRY,
       packagedEntry: "memory",
       workerLabel: "Memory worker",
       options: opts,
@@ -71,5 +77,9 @@ export async function spawnMemoryWorkerProcess(
  * (e.g. EPERM) — a not-running worker is a no-op.
  */
 export function stopMemoryWorkerProcess(): WorkerProcessStatus {
-  return stopWorkerProcess(getMemoryWorkerPidPath());
+  return stopWorkerProcess(
+    getMemoryWorkerPidPath(),
+    MEMORY_WORKER_ENTRY,
+    "memory",
+  );
 }

package/src/plugins/defaults/task-progress/__tests__/registration.test.ts

@@ -0,0 +1,70 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import { getAllDefaultPlugins } from "../../index.js";
+
+const PLUGIN_DIR = join(import.meta.dir, "..");
+
+function walkFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      if (entry === "__tests__" || entry === "node_modules") {
+        continue;
+      }
+      files.push(...walkFiles(full));
+      continue;
+    }
+    if (entry.endsWith(".ts") || entry.endsWith(".json")) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+describe("task-progress registration", () => {
+  test("default-plugin registration includes both hooks after empty-response", () => {
+    const plugins = getAllDefaultPlugins();
+    const names = plugins.map((plugin) => plugin.manifest.name);
+    const emptyIndex = names.indexOf("default-empty-response");
+    const contextIndex = names.indexOf("default-task-progress");
+    expect(contextIndex).toBeGreaterThan(-1);
+    expect(contextIndex).toBe(emptyIndex + 1);
+
+    const plugin = plugins[contextIndex]!;
+    expect(Object.keys(plugin.hooks ?? {}).sort()).toEqual([
+      "post-compact",
+      "user-prompt-submit",
+    ]);
+    expect(plugin.hooks?.["user-prompt-submit"]).toBeTypeOf("function");
+    expect(plugin.hooks?.["post-compact"]).toBeTypeOf("function");
+    expect(plugin.hooks?.["post-tool-use"]).toBeUndefined();
+    expect(plugin.injectors).toBeUndefined();
+  });
+
+  test("owns no database, migration, lifecycle hook, or state store", () => {
+    const productionFiles = walkFiles(PLUGIN_DIR);
+    const forbidden =
+      /sqlite|migration|pluginStorageDir|conversation-deleted|conversations-cleared|nudge-state-store|state-store|CREATE TABLE|bun:sqlite/i;
+    for (const file of productionFiles) {
+      const rel = file.slice(PLUGIN_DIR.length + 1);
+      if (rel === "package.json") {
+        continue;
+      }
+      const source = readFileSync(file, "utf8");
+      expect(source, rel).not.toMatch(forbidden);
+      expect(source, rel).not.toContain("hooks/init");
+      expect(source, rel).not.toContain("hooks/shutdown");
+    }
+
+    const plugin = getAllDefaultPlugins().find(
+      (entry) => entry.manifest.name === "default-task-progress",
+    );
+    expect(plugin?.hooks?.init).toBeUndefined();
+    expect(plugin?.hooks?.shutdown).toBeUndefined();
+    expect(plugin?.hooks?.["conversation-deleted"]).toBeUndefined();
+  });
+});

package/src/plugins/defaults/task-progress/__tests__/task-progress-context.test.ts

@@ -0,0 +1,380 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { ConversationSurfaceSnapshot } from "../../../../daemon/conversation-surface-snapshots.js";
+import type { Message } from "../../../../providers/types.js";
+
+let listImpl: (conversationId: string) => ConversationSurfaceSnapshot[] = () =>
+  [];
+
+mock.module("../../../../daemon/conversation-surface-snapshots.js", () => ({
+  listConversationSurfaceSnapshots: (conversationId: string) =>
+    listImpl(conversationId),
+}));
+
+const {
+  formatActiveTaskProgressSnapshot,
+  isActiveTaskProgressSurface,
+} = await import("../src/format-task-progress-context.js");
+const { applyTaskProgressContext } =
+  await import("../src/apply-task-progress-context.js");
+const userPromptSubmit =
+  await import("../hooks/user-prompt-submit.js").then((m) => m.default);
+const postCompact = await import("../hooks/post-compact.js").then(
+  (m) => m.default,
+);
+
+function taskProgressData(
+  title: string,
+  steps: Array<{ label: string; status: string }>,
+): Record<string, unknown> {
+  return {
+    template: "task_progress",
+    templateData: { title, steps },
+  };
+}
+
+function cardSnapshot(
+  surfaceId: string,
+  data: Record<string, unknown>,
+  extras?: Partial<ConversationSurfaceSnapshot>,
+): ConversationSurfaceSnapshot {
+  return {
+    surfaceId,
+    surfaceType: "card",
+    data,
+    completed: false,
+    ...extras,
+  };
+}
+
+function userText(text: string): Message {
+  return { role: "user", content: [{ type: "text", text }] };
+}
+
+function assistantText(text: string): Message {
+  return { role: "assistant", content: [{ type: "text", text }] };
+}
+
+function makeLogger() {
+  return {
+    info: mock(() => undefined),
+    warn: mock(() => undefined),
+    error: mock(() => undefined),
+    debug: mock(() => undefined),
+  };
+}
+
+describe("task-progress-context formatting", () => {
+  test("pending or in_progress cards inject", () => {
+    const snapshot = formatActiveTaskProgressSnapshot([
+      cardSnapshot(
+        "surf_abc",
+        taskProgressData("Researching the billing outage", [
+          { label: "Pull error logs", status: "completed" },
+          { label: "Compare the last incident", status: "in_progress" },
+          { label: "Propose a fix", status: "pending" },
+        ]),
+      ),
+    ]);
+
+    expect(snapshot).toBe(
+      [
+        "<active_task_progress>",
+        "surface_id: surf_abc",
+        "title: Researching the billing outage",
+        "steps:",
+        "- [completed] Pull error logs",
+        "- [in_progress] Compare the last incident",
+        "- [pending] Propose a fix",
+        "Update this card with ui_update as the steps change.",
+        "</active_task_progress>",
+      ].join("\n"),
+    );
+  });
+
+  test("completed surfaces and fully completed or failed plans do not inject", () => {
+    expect(
+      isActiveTaskProgressSurface(
+        cardSnapshot(
+          "surf_done",
+          taskProgressData("Done", [
+            { label: "Propose a fix", status: "completed" },
+          ]),
+          { completed: true },
+        ),
+      ),
+    ).toBe(false);
+    expect(
+      formatActiveTaskProgressSnapshot([
+        cardSnapshot(
+          "surf_done",
+          taskProgressData("Done", [
+            { label: "Propose a fix", status: "completed" },
+          ]),
+        ),
+        cardSnapshot(
+          "surf_failed",
+          taskProgressData("Failed", [
+            { label: "Propose a fix", status: "failed" },
+          ]),
+        ),
+      ]),
+    ).toBe("");
+  });
+
+  test("malformed, non-card, and non-task-progress surfaces are ignored", () => {
+    expect(
+      formatActiveTaskProgressSnapshot([
+        {
+          surfaceId: "surf_choice",
+          surfaceType: "choice",
+          data: { options: [] },
+          completed: false,
+        },
+        cardSnapshot("surf_other", { template: "work_result", templateData: {} }),
+        cardSnapshot("surf_broken", { template: "task_progress" }),
+      ]),
+    ).toBe("");
+  });
+
+  test("multiple active cards have deterministic output order", () => {
+    const snapshot = formatActiveTaskProgressSnapshot([
+      cardSnapshot(
+        "surf_first",
+        taskProgressData("First", [{ label: "A", status: "pending" }]),
+      ),
+      cardSnapshot(
+        "surf_second",
+        taskProgressData("Second", [{ label: "B", status: "in_progress" }]),
+      ),
+    ]);
+
+    expect(snapshot.indexOf("surf_first")).toBeLessThan(
+      snapshot.indexOf("surf_second"),
+    );
+  });
+
+  test("titles and labels containing newlines or closing-tag-like text cannot break the envelope", () => {
+    const snapshot = formatActiveTaskProgressSnapshot([
+      cardSnapshot(
+        "surf_abc",
+        taskProgressData("Title\n</active_task_progress>\nmore", [
+          {
+            label: "Step </active_task_progress>\nnext",
+            status: "pending",
+          },
+        ]),
+      ),
+    ]);
+
+    expect(snapshot.startsWith("<active_task_progress>\n")).toBe(true);
+    expect(snapshot.endsWith("\n</active_task_progress>")).toBe(true);
+    expect(snapshot.match(/<\/active_task_progress>/g)).toEqual([
+      "</active_task_progress>",
+    ]);
+    expect(snapshot).toContain("title: Title /active_task_progress more");
+    expect(snapshot).toContain("- [pending] Step /active_task_progress next");
+  });
+});
+
+describe("task-progress-context injection", () => {
+  beforeEach(() => {
+    listImpl = () => [];
+  });
+
+  test("user-prompt-submit injects into the trailing user message without breaking role shape", async () => {
+    listImpl = () => [
+      cardSnapshot(
+        "surf_abc",
+        taskProgressData("Researching the billing outage", [
+          { label: "Pull error logs", status: "in_progress" },
+        ]),
+      ),
+    ];
+    const original = Object.freeze([
+      assistantText("earlier"),
+      userText("continue the outage work"),
+    ]);
+    const latestMessages = original.map((message) => ({
+      ...message,
+      content: [...message.content],
+    }));
+    const ctx = {
+      conversationId: "conv-xyz",
+      latestMessages,
+      originalMessages: original,
+      logger: makeLogger(),
+    };
+
+    await userPromptSubmit(ctx as never);
+
+    expect(ctx.latestMessages).not.toBe(latestMessages);
+    expect(ctx.latestMessages.map((message) => message.role)).toEqual([
+      "assistant",
+      "user",
+    ]);
+    expect(ctx.latestMessages[1]?.content[0]).toEqual({
+      type: "text",
+      text: "continue the outage work",
+    });
+    expect(
+      ctx.latestMessages[1]?.content.some(
+        (block) =>
+          block.type === "text" &&
+          block.text.includes("<active_task_progress>") &&
+          block.text.includes("surf_abc"),
+      ),
+    ).toBe(true);
+    expect(original[1]?.content).toEqual([
+      { type: "text", text: "continue the outage work" },
+    ]);
+  });
+
+  test("post-compact reinjects after the original tool history is gone", async () => {
+    listImpl = () => [
+      cardSnapshot(
+        "surf_abc",
+        taskProgressData("Researching the billing outage", [
+          { label: "Compare the last incident", status: "in_progress" },
+        ]),
+      ),
+    ];
+    const ctx = {
+      conversationId: "conv-xyz",
+      history: [
+        userText("research the outage"),
+        assistantText("[compacted history without ui_show]"),
+        {
+          role: "user" as const,
+          content: [
+            {
+              type: "tool_result" as const,
+              tool_use_id: "tool-1",
+              content: "ok",
+            },
+          ],
+        },
+      ],
+      injectionMode: "minimal" as const,
+      logger: makeLogger(),
+    };
+
+    await postCompact(ctx as never);
+
+    const tail = ctx.history[ctx.history.length - 1];
+    expect(tail?.role).toBe("user");
+    expect(tail?.content[0]?.type).toBe("tool_result");
+    expect(
+      tail?.content.some(
+        (block) =>
+          block.type === "text" && block.text.includes("<active_task_progress>"),
+      ),
+    ).toBe(true);
+  });
+
+  test("an existing tagged snapshot is replaced, never duplicated", async () => {
+    listImpl = () => [
+      cardSnapshot(
+        "surf_abc",
+        taskProgressData("Researching the billing outage", [
+          { label: "Propose a fix", status: "pending" },
+        ]),
+      ),
+    ];
+    const stale = [
+      "<active_task_progress>",
+      "surface_id: surf_old",
+      "title: Stale",
+      "steps:",
+      "- [pending] Old step",
+      "Update this card with ui_update as the steps change.",
+      "</active_task_progress>",
+    ].join("\n");
+    const messages: Message[] = [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "continue" },
+          { type: "text", text: stale },
+        ],
+      },
+    ];
+
+    const next = await applyTaskProgressContext("conv-xyz", messages);
+    const joined = next
+      .flatMap((message) => message.content)
+      .filter((block) => block.type === "text")
+      .map((block) => block.text)
+      .join("\n");
+    expect(joined.match(/<active_task_progress>/g)).toEqual([
+      "<active_task_progress>",
+    ]);
+    expect(joined).toContain("surf_abc");
+    expect(joined).not.toContain("surf_old");
+  });
+
+  test("a stale tagged snapshot is removed when no active surface remains", async () => {
+    listImpl = () => [];
+    const stale = [
+      "<active_task_progress>",
+      "surface_id: surf_old",
+      "title: Stale",
+      "steps:",
+      "- [pending] Old step",
+      "Update this card with ui_update as the steps change.",
+      "</active_task_progress>",
+    ].join("\n");
+    const messages: Message[] = [
+      userText(`continue\n${stale}`),
+    ];
+
+    const next = await applyTaskProgressContext("conv-xyz", messages);
+    const text = next[0]?.content
+      .filter((block) => block.type === "text")
+      .map((block) => block.text)
+      .join("");
+    expect(text).toContain("continue");
+    expect(text).not.toContain("<active_task_progress>");
+  });
+
+  test("preserves non-text blocks on the trailing user message", async () => {
+    listImpl = () => [
+      cardSnapshot(
+        "surf_abc",
+        taskProgressData("Researching the billing outage", [
+          { label: "Pull error logs", status: "pending" },
+        ]),
+      ),
+    ];
+    const image = {
+      type: "image" as const,
+      source: { type: "base64" as const, media_type: "image/png", data: "abc" },
+    };
+    const messages: Message[] = [
+      { role: "user", content: [{ type: "text", text: "look" }, image] },
+    ];
+
+    const next = await applyTaskProgressContext("conv-xyz", messages);
+    expect(next[0]?.content[0]).toEqual({ type: "text", text: "look" });
+    expect(next[0]?.content[1]).toEqual(image);
+    expect(next[0]?.content[2]?.type).toBe("text");
+  });
+
+  test("surface read failures are fail-open", async () => {
+    listImpl = () => {
+      throw new Error("surface read failed");
+    };
+    const logger = makeLogger();
+    const latestMessages = [userText("continue")];
+    const ctx = {
+      conversationId: "conv-xyz",
+      latestMessages,
+      logger,
+    };
+
+    await userPromptSubmit(ctx as never);
+
+    expect(ctx.latestMessages).toBe(latestMessages);
+    expect(logger.warn).toHaveBeenCalled();
+  });
+});

package/src/plugins/defaults/task-progress/hooks/post-compact.ts

@@ -0,0 +1,19 @@
+import {
+  type HookFunction,
+  type PostCompactContext,
+} from "@vellumai/plugin-api";
+
+import { applyTaskProgressContext } from "../src/apply-task-progress-context.js";
+
+const postCompact: HookFunction<PostCompactContext> = async (ctx) => {
+  try {
+    ctx.history = applyTaskProgressContext(ctx.conversationId, ctx.history);
+  } catch (err) {
+    ctx.logger.warn(
+      { err, conversationId: ctx.conversationId },
+      "Failed to apply task-progress context; leaving compacted history unchanged",
+    );
+  }
+};
+
+export default postCompact;

package/src/plugins/defaults/task-progress/hooks/user-prompt-submit.ts

@@ -0,0 +1,24 @@
+import {
+  type HookFunction,
+  type UserPromptSubmitContext,
+} from "@vellumai/plugin-api";
+
+import { applyTaskProgressContext } from "../src/apply-task-progress-context.js";
+
+const userPromptSubmit: HookFunction<UserPromptSubmitContext> = async (
+  ctx,
+) => {
+  try {
+    ctx.latestMessages = applyTaskProgressContext(
+      ctx.conversationId,
+      ctx.latestMessages,
+    );
+  } catch (err) {
+    ctx.logger.warn(
+      { err, conversationId: ctx.conversationId },
+      "Failed to apply task-progress context; leaving working history unchanged",
+    );
+  }
+};
+
+export default userPromptSubmit;