@vellumai/assistant 0.8.4 → 0.8.6

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

@@ -49,12 +49,8 @@ import semver from "semver";
 import { z } from "zod";
 
 import assistantPkg from "../../package.json" with { type: "json" };
-import type {
-  LoadedPluginTool,
-  PluginTool,
-  RiskLevel,
-  ToolExecutionResult,
-} from "../tools/types.js";
+import { finalizeTool } from "../tools/tool-defaults.js";
+import type { LoadedTool, ToolDefinition } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
 import { registerPlugin } from "./registry.js";
 import type {
@@ -62,7 +58,6 @@ import type {
   PluginHookFn,
   PluginHooks,
   PluginManifest,
-  PluginToolRegistration,
 } from "./types.js";
 
 const PLUGIN_API_PEER_DEP = "@vellumai/plugin-api";
@@ -122,64 +117,6 @@ function deriveToolName(toolFileBaseName: string): string {
   return toToolNameSegment(toolFileBaseName);
 }
 
-/**
- * Defaults applied by {@link applyPluginToolDefaults} when a plugin tool
- * omits one of the normally-required fields. Exported as a constant so
- * tests and callers can reference the same source of truth.
- *
- * The default `execute` returns an error result so the model sees a clear
- * "this tool isn't wired up" signal at call time. The plugin still loads
- * cleanly — broken individual tools must never block daemon boot.
- */
-export const PLUGIN_TOOL_DEFAULTS = Object.freeze({
-  description: "",
-  defaultRiskLevel: "medium" as RiskLevel,
-  input_schema: Object.freeze({
-    type: "object",
-    properties: {},
-    additionalProperties: false,
-  }) as object,
-});
-
-/**
- * Fill the four normally-required {@link PluginTool} fields with documented
- * defaults when the author omitted them. Returns a {@link LoadedPluginTool}
- * that is safe to register.
- */
-function applyPluginToolDefaults(
-  tool: PluginTool,
-  name: string,
-): LoadedPluginTool {
-  const description =
-    typeof tool.description === "string"
-      ? tool.description
-      : PLUGIN_TOOL_DEFAULTS.description;
-  const defaultRiskLevel =
-    typeof tool.defaultRiskLevel === "string"
-      ? tool.defaultRiskLevel
-      : PLUGIN_TOOL_DEFAULTS.defaultRiskLevel;
-  const input_schema =
-    tool.input_schema !== null &&
-    typeof tool.input_schema === "object"
-      ? tool.input_schema
-      : PLUGIN_TOOL_DEFAULTS.input_schema;
-  const execute =
-    typeof tool.execute === "function"
-      ? tool.execute
-      : async (): Promise<ToolExecutionResult> => ({
-          content: `plugin tool ${name} has no execute implementation`,
-          isError: true,
-        });
-  return {
-    ...tool,
-    name,
-    description,
-    defaultRiskLevel,
-    input_schema,
-    execute,
-  };
-}
-
 /**
  * Dynamic-import `absolutePath` and return its default export. Throws when
  * the module has no default export — callers attribute the error.
@@ -339,17 +276,17 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
   const hooks = await loadHooks(pluginDir, name);
   if (hooks !== undefined) plugin.hooks = hooks;
 
-  const tools: PluginToolRegistration[] = [];
+  const tools: LoadedTool[] = [];
   for (const { name: toolName, path: toolPath } of listSurfaceDir(
     join(pluginDir, "tools"),
   )) {
-    const tool = await importDefault<PluginTool>(toolPath);
+    const tool = await importDefault<ToolDefinition>(toolPath);
     if (tool === null || typeof tool !== "object") {
       throw new Error(
         `external plugin ${name}: ${toolPath} default export must be an object`,
       );
     }
-    tools.push(applyPluginToolDefaults(tool, deriveToolName(toolName)));
+    tools.push(finalizeTool(tool, deriveToolName(toolName)));
   }
   if (tools.length > 0) plugin.tools = tools;
 

package/src/plugins/types.ts

@@ -32,6 +32,7 @@ import type { RepairResult } from "../daemon/history-repair.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import type { PkbContextConversation } from "../daemon/pkb-context-tracker.js";
 import type { TrustContext } from "../daemon/trust-context.js";
+import type { MessageRole } from "../memory/conversation-crud.js";
 import type { QdrantSparseVector } from "../memory/qdrant-client.js";
 import type {
   ContentBlock,
@@ -43,7 +44,7 @@ import type {
 } from "../providers/types.js";
 import type { SkillRoute } from "../runtime/skill-route-registry.js";
 import type {
-  LoadedPluginTool,
+  LoadedTool,
   ToolContext,
   ToolExecutionResult,
 } from "../tools/types.js";
@@ -439,18 +440,25 @@ export interface OverflowReduceResult {
  * Pipeline arguments for `persistence` — a discriminated union over the
  * message-CRUD operations plugins may observe, redirect, or short-circuit:
  *
- * - `add`    — append a new message (`addMessage`). Mirrors
- *              `addMessage(conversationId, role, content, metadata?, opts?)`.
- *              When `syncToDisk` is set, the default plugin also runs
- *              {@link syncMessageToDisk} against the just-persisted row so
- *              the JSONL disk view stays consistent. The `createdAtMs` field
- *              carries the conversation's creation timestamp — needed to
- *              resolve the disk-view directory path.
- * - `update` — shallow-merge metadata into an existing message
- *              (`updateMessageMetadata`). Returns `void`.
- * - `delete` — remove a single message (`deleteMessageById`). Returns the
- *              {@link DeletedMemoryIds}-shaped segment/summary IDs the caller
- *              must clean up out-of-band.
+ * - `add`           — append a new message (`addMessage`). Mirrors
+ *                     `addMessage(conversationId, role, content, metadata?, opts?)`.
+ *                     When `syncToDisk` is set, the default plugin also runs
+ *                     {@link syncMessageToDisk} against the just-persisted row
+ *                     so the JSONL disk view stays consistent. The
+ *                     `createdAtMs` field carries the conversation's creation
+ *                     timestamp — needed to resolve the disk-view directory.
+ * - `reserve`       — pre-allocate an empty assistant anchor row
+ *                     (`reserveMessage`) so the agent loop can stamp streaming
+ *                     events with stable identity before any content is
+ *                     produced. Returns the same row shape as `add`.
+ * - `updateContent` — overwrite the content of an existing message
+ *                     (`updateMessageContent`). Used to finalize a previously
+ *                     reserved row, and by consolidation paths.
+ * - `update`        — shallow-merge metadata into an existing message
+ *                     (`updateMessageMetadata`). Returns `void`.
+ * - `delete`        — remove a single message (`deleteMessageById`). Returns
+ *                     the {@link DeletedMemoryIds}-shaped segment/summary IDs
+ *                     the caller must clean up out-of-band.
  *
  * The discriminated `op` field lets plugin middleware narrow the union and
  * tailor behavior per-operation (e.g. "only observe deletes", "redirect
@@ -459,7 +467,7 @@ export interface OverflowReduceResult {
 export type PersistAddArgs = {
   readonly op: "add";
   readonly conversationId: string;
-  readonly role: string;
+  readonly role: MessageRole;
   readonly content: string;
   readonly metadata?: Record<string, unknown>;
   readonly addOptions?: { readonly skipIndexing?: boolean };
@@ -473,6 +481,19 @@ export type PersistAddArgs = {
   readonly createdAtMs?: number;
 };
 
+export type PersistReserveArgs = {
+  readonly op: "reserve";
+  readonly conversationId: string;
+  readonly role: MessageRole;
+  readonly metadata?: Record<string, unknown>;
+};
+
+export type PersistUpdateContentArgs = {
+  readonly op: "updateContent";
+  readonly messageId: string;
+  readonly content: string;
+};
+
 export type PersistUpdateArgs = {
   readonly op: "update";
   readonly messageId: string;
@@ -486,6 +507,8 @@ export type PersistDeleteArgs = {
 
 export type PersistArgs =
   | PersistAddArgs
+  | PersistReserveArgs
+  | PersistUpdateContentArgs
   | PersistUpdateArgs
   | PersistDeleteArgs;
 
@@ -506,6 +529,25 @@ export type PersistAddResult = {
   };
 };
 
+/**
+ * Result row returned by a `reserve` op — same row shape as `add` but with
+ * empty `content` (`"[]"`) and tagged distinctly so middleware can branch
+ * on intent.
+ */
+export type PersistReserveResult = {
+  readonly op: "reserve";
+  readonly message: {
+    readonly id: string;
+    readonly conversationId: string;
+    readonly role: string;
+    readonly content: string;
+    readonly createdAt: number;
+    readonly metadata?: string;
+  };
+};
+
+export type PersistUpdateContentResult = { readonly op: "updateContent" };
+
 export type PersistUpdateResult = { readonly op: "update" };
 
 /** IDs of segments/summaries the caller must remove from Qdrant. */
@@ -517,6 +559,8 @@ export type PersistDeleteResult = {
 
 export type PersistResult =
   | PersistAddResult
+  | PersistReserveResult
+  | PersistUpdateContentResult
   | PersistUpdateResult
   | PersistDeleteResult;
 
@@ -1007,19 +1051,6 @@ export interface Injector {
 // `PluginSkillRegistration` shape below so plugins can declare
 // catalog-discoverable skills today.
 
-/**
- * Tool registration contributed by a plugin. Uses the narrow
- * {@link LoadedPluginTool} shape. External plugin authors declare the
- * nameless `PluginTool` file shape; the loader derives `name` from the
- * `tools/<name>.ts` basename before storing it on `plugin.tools`. Authors
- * also leave category / ownership metadata to the bootstrap, which stamps
- * `category: "plugin"`, `origin: "plugin"`, and
- * `ownerPluginId: <plugin.name>` before handing the batch to
- * `registerPluginTools`. The registration boundary synthesizes
- * `getDefinition()` from `{name, description, input_schema}` so the canonical
- * {@link Tool} interface used by the internal registry stays unchanged.
- */
-export type PluginToolRegistration = LoadedPluginTool;
 /**
  * HTTP route registration contributed by a plugin. Plugins express routes as
  * {@link SkillRoute} values — the same shape the skill-route registry
@@ -1120,8 +1151,16 @@ export interface Plugin {
   manifest: PluginManifest;
   /** Lifecycle hooks (init, shutdown). See {@link PluginHooks}. */
   hooks?: PluginHooks;
-  /** Tool registrations visible to the model. */
-  tools?: PluginToolRegistration[];
+  /**
+   * Tool registrations visible to the model. External plugin authors
+   * declare the nameless `ToolDefinition` file shape (from
+   * `@vellumai/plugin-api`); the loader derives `name` from the
+   * `tools/<name>.ts` basename and runs the definition through
+   * `finalizeTool` to fill omitted required fields, producing the
+   * `LoadedTool` values stored here. Category / ownership metadata is
+   * stamped by `registerPluginTools` at registration time.
+   */
+  tools?: LoadedTool[];
   /** HTTP route registrations served by the assistant. */
   routes?: PluginRouteRegistration[];
   /** Skill registrations loaded at startup. */

package/src/proactive-artifact/aux-message-injector.ts

@@ -71,10 +71,23 @@ export async function injectAuxAssistantMessage(params: {
     });
   }
 
-  params.broadcastMessage({
-    type: "conversation_list_invalidated",
-    reason: "reordered",
-  });
+  // The injected aux message bumps `lastMessageAt`, which can move the
+  // row in the paginated sidebar window — that's a shape change. macOS
+  // refreshes its full list on `conversation_list_invalidated`; web
+  // refreshes via the paired `sync_changed` `conversationsList` tag.
+  //
+  // TODO(electron-cutover): drop the `conversation_list_invalidated`
+  // emission once macOS migrates to the Electron client and consumes
+  // `sync_changed` directly. See `runtime/sync/resource-sync-events.ts`
+  // for the symmetric helper used by route handlers.
+  params.broadcastMessage(
+    {
+      type: "conversation_list_invalidated",
+      reason: "reordered",
+    },
+    undefined,
+    { targetInterfaceId: "macos" },
+  );
   params.broadcastMessage({
     type: "sync_changed",
     tags: [

package/src/proactive-artifact/job.test.ts

@@ -163,6 +163,7 @@ mock.module("../memory/conversation-crud.js", () => ({
     addMessageCalls.push({ conversationId, role, content, metadata, opts });
     return { id: `msg-${addMessageCalls.length}` };
   },
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
 // emitNotificationSignal mock

package/src/prompts/__tests__/system-prompt.test.ts

@@ -58,7 +58,7 @@ mock.module("../../config/loader.js", () => ({
   setNestedValue: () => {},
 }));
 
-const { buildSystemPrompt, maybeReseedBootstrapForCohort } =
+const { buildSystemPrompt, maybeReseedBootstrap } =
   await import("../system-prompt.js");
 
 describe("buildSystemPrompt — tool routing guidance", () => {
@@ -73,12 +73,12 @@ describe("buildSystemPrompt — tool routing guidance", () => {
   });
 });
 
-describe("maybeReseedBootstrapForCohort — content-automation template", () => {
+describe("maybeReseedBootstrap — content-automation template", () => {
   const templatesDir = join(import.meta.dirname!, "..", "templates");
 
   beforeEach(() => {
     mkdirSync(TEST_DIR, { recursive: true });
-    // Seed the workspace with the generic BOOTSTRAP.md so the cohort
+    // Seed the workspace with the generic BOOTSTRAP.md so the bootstrap
     // reseed detects it as an unmodified template and overwrites it.
     copyFileSync(
       join(templatesDir, "BOOTSTRAP.md"),
@@ -87,7 +87,7 @@ describe("maybeReseedBootstrapForCohort — content-automation template", () =>
   });
 
   function reseedAndRead(): string {
-    maybeReseedBootstrapForCohort("content-automation");
+    maybeReseedBootstrap("BOOTSTRAP-CONTENT-AUTOMATION.md");
     return readFileSync(join(TEST_DIR, "BOOTSTRAP.md"), "utf-8");
   }
 

package/src/prompts/__tests__/task-progress-hint-section.test.ts

@@ -54,8 +54,9 @@ mock.module("../../config/loader.js", () => ({
   setNestedValue: () => {},
 }));
 
-const { buildSystemPrompt, ensurePromptFiles, SYSTEM_PROMPT_CACHE_BOUNDARY } =
-  await import("../system-prompt.js");
+const { buildSystemPrompt, ensurePromptFiles } = await import(
+  "../system-prompt.js"
+);
 
 describe("task_progress hint in parallel-tool-calls section", () => {
   beforeEach(() => {
@@ -85,11 +86,4 @@ describe("task_progress hint in parallel-tool-calls section", () => {
     expect(withExcludePrefix).toContain("task_progress");
   });
 
-  test("hint lives in the static (cached) block before SYSTEM_PROMPT_CACHE_BOUNDARY", () => {
-    const result = buildSystemPrompt();
-    const boundaryIdx = result.indexOf(SYSTEM_PROMPT_CACHE_BOUNDARY);
-    expect(boundaryIdx).toBeGreaterThan(-1);
-    const staticBlock = result.slice(0, boundaryIdx);
-    expect(staticBlock).toContain("task_progress");
-  });
 });

package/src/prompts/persona-resolver.ts

@@ -77,31 +77,46 @@ function resolveUserFilename(
 ): string | null {
   let filename: string | null = null;
 
-  if (trustContext === undefined) {
-    // Desktop / native (no gateway) — resolve via guardian contact,
-    // preferring the vellum-channel guardian when multiple exist.
-    const vellumGuardian = findGuardianForChannel("vellum");
-    const guardian = vellumGuardian ?? listGuardianChannels();
-    if (guardian) {
-      filename = guardian.contact.userFile ?? "guardian.md";
-    }
-  } else if (trustContext.requesterExternalUserId) {
-    // Channel-routed request — look up contact by channel identity
-    const contactWithChannels = findContactByChannelExternalId(
-      trustContext.sourceChannel,
-      trustContext.requesterExternalUserId,
-    );
-    if (contactWithChannels) {
-      filename = contactWithChannels.userFile ?? null;
-    } else if (trustContext.trustClass === "guardian") {
-      // Managed desktop: the JWT principal ID used as requesterExternalUserId
-      // may differ from the contact channel's external_user_id (they are
-      // separate identity concepts). Fall back to the channel-type guardian.
-      const guardian = findGuardianForChannel(trustContext.sourceChannel);
+  try {
+    if (trustContext === undefined) {
+      // Desktop / native (no gateway) — resolve via guardian contact,
+      // preferring the vellum-channel guardian when multiple exist.
+      const vellumGuardian = findGuardianForChannel("vellum");
+      const guardian = vellumGuardian ?? listGuardianChannels();
       if (guardian) {
         filename = guardian.contact.userFile ?? "guardian.md";
       }
+    } else if (trustContext.requesterExternalUserId) {
+      // Channel-routed request — look up contact by channel identity
+      const contactWithChannels = findContactByChannelExternalId(
+        trustContext.sourceChannel,
+        trustContext.requesterExternalUserId,
+      );
+      if (contactWithChannels) {
+        filename = contactWithChannels.userFile ?? null;
+      } else if (trustContext.trustClass === "guardian") {
+        // Managed desktop: the JWT principal ID used as requesterExternalUserId
+        // may differ from the contact channel's external_user_id (they are
+        // separate identity concepts). Fall back to the channel-type guardian.
+        const guardian = findGuardianForChannel(trustContext.sourceChannel);
+        if (guardian) {
+          filename = guardian.contact.userFile ?? "guardian.md";
+        }
+      }
     }
+  } catch (err) {
+    // Contacts table may be absent — happens during early bootstrap
+    // before migrations run, in CLI smoke commands that don't touch
+    // the DB, and in tests that build the system prompt without first
+    // initializing a schema. Treat the same as "no guardian found"
+    // so callers fall back to `users/default.md`. Mirrors the same
+    // try/catch pattern used by `renderConnectedServices()` around
+    // `listConnections()`.
+    log.debug(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Contacts lookup failed during persona resolution; treating as no guardian",
+    );
+    return null;
   }
 
   // Validate basename to prevent path traversal

package/src/prompts/sections.ts

@@ -110,6 +110,7 @@ interface ResolvedSection {
 
 function resolveSection(
   id: string,
+  ctx: SectionRenderContext,
   workspaceDir: string,
 ): ResolvedSection | null {
   const workspacePath = join(workspaceDir, `${id}.md`);
@@ -139,15 +140,28 @@ function resolveSection(
 
   // A bundled section may delegate its body to a workspace file outside
   // the section override directory (e.g. `SOUL.md` at the workspace
-  // root).  Read it now; missing/empty files yield "", which
-  // `renderSection` then gates off via its empty-body check (or via the
-  // section's `transform`, if set).
+  // root).  `workspacePath` may be a single path or an array of paths
+  // tried in order — the first one whose file exists and has non-empty
+  // content wins.  Each entry may reference `{{ctx-key}}` variables
+  // (e.g. `users/{{userSlug}}.md`) that are interpolated against the
+  // render context before resolution.  Missing/empty files yield "",
+  // which `renderSection` then gates off via its empty-body check (or
+  // via the section's `transform`, if set).
   if (bundled.workspacePath) {
-    const filePath = getWorkspacePromptPath(bundled.workspacePath);
+    const paths = Array.isArray(bundled.workspacePath)
+      ? bundled.workspacePath
+      : [bundled.workspacePath];
     let body = "";
-    if (existsSync(filePath)) {
+    for (const pathTemplate of paths) {
+      const interpolated = interpolateWorkspacePath(pathTemplate, ctx);
+      const filePath = getWorkspacePromptPath(interpolated);
+      if (!existsSync(filePath)) continue;
       try {
-        body = readFileSync(filePath, "utf-8");
+        const content = readFileSync(filePath, "utf-8");
+        if (content.trim().length > 0) {
+          body = content;
+          break;
+        }
       } catch (err) {
         log.warn({ err, filePath, id }, "Failed to read section workspacePath");
       }
@@ -162,12 +176,30 @@ function resolveSection(
   };
 }
 
+/**
+ * Interpolate `{{key}}` references in a workspace-path template against
+ * `ctx`. Section / inverted-section tags are not supported in paths —
+ * only flat variable substitution. Unresolved keys stay literal so a
+ * typo surfaces as a missing file rather than silently rendering an
+ * unrelated section.
+ */
+function interpolateWorkspacePath(
+  template: string,
+  ctx: SectionRenderContext,
+): string {
+  return template.replace(VARIABLE, (match, key: string) => {
+    const value = ctx[key];
+    if (value === undefined || value === null) return match;
+    return String(value);
+  });
+}
+
 function renderSection(
   id: string,
   ctx: SectionRenderContext,
   workspaceDir: string,
 ): string | null {
-  const section = resolveSection(id, workspaceDir);
+  const section = resolveSection(id, ctx, workspaceDir);
   if (section === null) return null;
 
   if (!isEnabled(section.enabled, ctx)) return null;