@vellumai/assistant 0.8.8 → 0.8.9-staging.2

package/src/daemon/external-plugins-bootstrap.ts

@@ -2,21 +2,22 @@
  * Plugin bootstrap — runs every registered plugin's `init()` hook once during
  * daemon startup.
  *
- * Plugins register themselves via side-effect imports elsewhere in the boot
- * sequence (first-party) or at runtime (hot-reload). By the time
- * {@link bootstrapPlugins} runs, the registry has been fully populated for
- * this boot cycle. This function:
+ * The registry is populated before this runs: first-party defaults are
+ * registered explicitly (step 1 below), user plugins are registered by the
+ * user-plugin loader from the workspace `plugins/` directory, and hot-reload
+ * registers at runtime. By the time {@link bootstrapPlugins} runs, the
+ * registry has been fully populated for this boot cycle. This function:
  *
  * 1. Registers the canonical first-party default plugins via
- *    {@link registerDefaultPlugins} (one per pipeline). Registration is
- *    idempotent so repeat calls (e.g. during integration tests) do not throw.
+ *    {@link registerDefaultPlugins}. Registration is idempotent so repeat
+ *    calls (e.g. during integration tests) do not throw.
  * 2. Walks {@link getRegisteredPlugins} in registration order.
  * 3. For each plugin, consults `manifest.requiresFlag` against
  *    {@link isAssistantFeatureFlagEnabled}. If any listed flag is disabled,
  *    the plugin is skipped wholesale — no `init()`, no tool/route/skill
  *    contributions, no entry in the shutdown hook, and the plugin is also
- *    dropped from the registry via {@link unregisterPlugin} so its middleware
- *    stops participating in pipeline runs. This is the primary mechanism for
+ *    dropped from the registry via {@link unregisterPlugin} so none of its
+ *    hooks participate in the turn lifecycle. This is the primary mechanism for
  *    shipping experimental plugins behind a feature flag.
  * 4. Resolves the plugin's `manifest.requiresCredential` entries via the
  *    credential store helper ({@link getSecureKeyAsync}). In Docker mode
@@ -64,7 +65,6 @@ import { getConfig } from "../config/loader.js";
 import type { AssistantConfig } from "../config/schema.js";
 import { HOOKS } from "../plugin-api/constants.js";
 import { registerDefaultPlugins } from "../plugins/defaults/index.js";
-import { installPluginRuntime } from "../plugins/external-api.js";
 import { buildExternalPlugin } from "../plugins/external-plugin-loader.js";
 import {
   registerPluginSkills,
@@ -186,21 +186,17 @@ function getDisabledPluginFlag(
  * Bring the plugin layer up during daemon startup. Runs the full sequence in
  * the one order the rest of the system depends on:
  *
- * 1. Install the `globalThis.__vellumPluginRuntime` bridge so plugins can touch
- *    it from their module body (see `plugins/external-api.ts` — compiled-binary
- *    module identity).
- * 2. Register the first-party defaults so their middleware composes innermost,
+ * 1. Register the first-party defaults so their middleware composes innermost,
  *    ahead of any user plugins.
- * 3. Load user plugins from `<workspaceDir>/plugins/*`. A failing user plugin is
+ * 2. Load user plugins from `<workspaceDir>/plugins/*`. A failing user plugin is
  *    logged and skipped; `loadUserPlugins()` closes the registration window
  *    when it returns, so the defaults must already be registered by then.
- * 4. Run every registered plugin's `init()` via {@link bootstrapPlugins}.
+ * 3. Run every registered plugin's `init()` via {@link bootstrapPlugins}.
  *
  * Plugin bootstrap is wrapped so a failing plugin cannot block daemon startup —
  * the daemon comes up with degraded plugin functionality instead.
  */
 export async function initializePlugins(): Promise<void> {
-  installPluginRuntime();
   registerDefaultPlugins();
   await loadUserPlugins();
   try {
@@ -261,9 +257,8 @@ export async function bootstrapPlugins(): Promise<void> {
   // Tear down a plugin's contributions AND remove it from the registry. The
   // two steps always move together on the bootstrap failure path: the former
   // clears tools/routes/skills (so they stop appearing to the model/HTTP
-  // server), the latter drops the plugin's entry from the Map (so
-  // `getMiddlewaresFor` doesn't re-enter an uninitialized plugin on the next
-  // pipeline invocation).
+  // server), the latter drops the plugin's entry from the Map (so the registry
+  // doesn't expose an uninitialized plugin's hooks).
   // Shutdown context is identical for every plugin in this boot — construct
   // once and reuse across the bootstrap-failure rollback and the normal
   // shutdown hook below. Only `assistantVersion` is exposed today; future

package/src/daemon/handlers/conversations.ts

@@ -8,9 +8,11 @@ import { createAbortReason } from "../../util/abort-reasons.js";
 import { truncate } from "../../util/truncate.js";
 import { regenerate } from "../conversation-history.js";
 import {
-  clearAllActiveConversations,
   conversationEntries,
   findConversation,
+} from "../conversation-registry.js";
+import {
+  clearAllActiveConversations,
   getOrCreateConversation,
   touchConversation,
 } from "../conversation-store.js";

package/src/daemon/handlers/skills.ts

@@ -31,7 +31,10 @@ import {
   isTextMimeType as isTextMime,
   MAX_INLINE_TEXT_SIZE,
 } from "../../runtime/routes/workspace-utils.js";
-import { getCachedCatalogSync, getCatalog } from "../../skills/catalog-cache.js";
+import {
+  getCachedCatalogSync,
+  getCatalog,
+} from "../../skills/catalog-cache.js";
 import type { SkillFileEntry } from "../../skills/catalog-files.js";
 import {
   catalogSkillToSlim,

package/src/daemon/host-proxy-preactivation.ts

@@ -34,9 +34,7 @@ import { getLogger } from "../util/logger.js";
 const log = getLogger("host-proxy-preactivation");
 
 /**
- * Subset of Conversation/ProcessConversationContext that
- * `preactivateHostProxySkills` needs. Both `Conversation` and
- * `ProcessConversationContext` satisfy this structurally.
+ * Subset of `Conversation` that `preactivateHostProxySkills` needs.
  */
 export interface HostProxyPreactivationTarget {
   readonly conversationId: string;

package/src/daemon/lifecycle.ts

@@ -60,7 +60,6 @@ import { sweepConceptPageFrontmatter } from "../memory/v2/frontmatter-sweep.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import { backfillManualTokenConnections } from "../oauth/manual-token-connection.js";
 import { seedOAuthProviders } from "../oauth/seed-providers.js";
-import { backfillGuardIfNeeded } from "../proactive-artifact/index.js";
 import { ensurePromptFiles } from "../prompts/system-prompt.js";
 import { runProviderConnectionsBackfill } from "../providers/inference/backfill.js";
 import { resolveManagedProxyContext } from "../providers/platform-proxy/context.js";
@@ -98,6 +97,7 @@ import {
   updateWorkItem,
 } from "../work-items/work-item-store.js";
 import { WorkspaceHeartbeatService } from "../workspace/heartbeat-service.js";
+import { repairAdaptiveThinkingOnManagedProfiles } from "../workspace/migrations/097-enable-adaptive-thinking-managed-profiles.js";
 import { WORKSPACE_MIGRATIONS } from "../workspace/migrations/registry.js";
 import { runWorkspaceMigrations } from "../workspace/migrations/runner.js";
 import {
@@ -589,6 +589,26 @@ export async function runDaemon(): Promise<void> {
       );
     }
 
+    // Re-run the adaptive thinking repair after overlay merge + profile seeding.
+    // Workspace migration 097 enables adaptive thinking on managed profiles, but
+    // it runs before mergeDefaultWorkspaceConfig() which can overwrite the fix
+    // with overlay profiles that have thinking disabled or absent. On-platform
+    // instances where the overlay supplies "balanced" / "quality-optimized"
+    // profiles without thinking enabled would be stuck permanently because the
+    // migration is already checkpointed as completed. This idempotent repair
+    // ensures thinking is enabled regardless of overlay ordering.
+    if (defaultConfigMerge.hadOverlay) {
+      try {
+        repairAdaptiveThinkingOnManagedProfiles(getWorkspaceDir());
+        log.info("Post-overlay adaptive thinking repair complete");
+      } catch (err) {
+        log.warn(
+          { err },
+          "Post-overlay adaptive thinking repair failed — continuing startup",
+        );
+      }
+    }
+
     log.info("Daemon startup: loading config");
     const config = loadConfig();
 
@@ -1276,12 +1296,6 @@ export async function runDaemon(): Promise<void> {
       "Heartbeat service configured",
     );
 
-    try {
-      backfillGuardIfNeeded();
-    } catch (err) {
-      log.warn({ err }, "Proactive artifact backfill failed");
-    }
-
     // Filing yields to the memory v2 consolidation job when v2 is enabled —
     // both serve the same role (periodic background memory processing) and
     // running both is redundant. The consolidation job runs through the

package/src/daemon/server.ts

@@ -39,6 +39,8 @@ import {
   conversationEntries,
   deleteConversation,
   getConversationMap,
+} from "./conversation-registry.js";
+import {
   getOrCreateConversation as getOrCreateActiveConversation,
   initConversationLifecycle,
   setCesClientPromise,

package/src/daemon/wake-conversation-ops.ts

@@ -0,0 +1,269 @@
+/**
+ * Daemon-side side effects a wake performs against a live
+ * {@link Conversation}, used by `wakeAgentForOpportunity()` in
+ * `runtime/agent-wake.ts`.
+ *
+ * These are kept as standalone functions (rather than methods on
+ * `Conversation`) so the wake-specific concerns — event→wire translation,
+ * the wake ui_surface card, and the wake's one-shot tail persistence —
+ * stay out of the conversation class. They live in the daemon layer
+ * because they translate agent-loop events into client wire frames and
+ * touch the message store, so `runtime/agent-wake.ts` references only the
+ * erased `Conversation` type and never imports `message-protocol.ts`.
+ */
+
+import type { AgentEvent } from "../agent/loop.js";
+import {
+  addMessage,
+  getConversation,
+  provenanceFromTrustContext,
+} from "../memory/conversation-crud.js";
+import { syncMessageToDisk } from "../memory/conversation-disk-view.js";
+import { backfillMessageIdOnLogs } from "../memory/llm-request-log-store.js";
+import type { Message } from "../providers/types.js";
+import { broadcastMessage } from "../runtime/assistant-event-hub.js";
+import { getLogger } from "../util/logger.js";
+import type { Conversation } from "./conversation.js";
+import type { ServerMessage } from "./message-protocol.js";
+
+const log = getLogger("wake-conversation-ops");
+
+/**
+ * Translate a raw {@link AgentEvent} from the agent loop into the
+ * corresponding {@link ServerMessage} wire frame. The normal user-turn
+ * path does this via the full state-aware handler in
+ * `conversation-agent-loop-handlers.ts`; the wake path has no tool
+ * accounting, title generation, or activity-state tracking to worry
+ * about, so we only need the subset that produces client-visible
+ * frames. Events that have no client-visible wire shape (usage, error,
+ * preview/input-json deltas, etc.) are dropped — they produce no UI.
+ */
+function translateAgentEventToServerMessage(
+  event: AgentEvent,
+  conversationId: string,
+): ServerMessage | null {
+  switch (event.type) {
+    case "text_delta":
+      return {
+        type: "assistant_text_delta",
+        text: event.text,
+        conversationId,
+      };
+    case "thinking_delta":
+      return {
+        type: "assistant_thinking_delta",
+        thinking: event.thinking,
+        conversationId,
+      };
+    case "tool_use":
+      return {
+        type: "tool_use_start",
+        toolName: event.name,
+        input: event.input,
+        conversationId,
+        toolUseId: event.id,
+      };
+    case "tool_use_preview_start":
+      return {
+        type: "tool_use_preview_start",
+        toolUseId: event.toolUseId,
+        toolName: event.toolName,
+        conversationId,
+      };
+    case "tool_output_chunk":
+      return {
+        type: "tool_output_chunk",
+        chunk: event.chunk,
+        conversationId,
+        toolUseId: event.toolUseId,
+      };
+    case "tool_result": {
+      const imageBlocks = event.contentBlocks?.filter(
+        (b): b is Extract<typeof b, { type: "image" }> => b.type === "image",
+      );
+      const imageDataList = imageBlocks?.length
+        ? imageBlocks.map((b) => b.source.data)
+        : undefined;
+      return {
+        type: "tool_result",
+        toolName: "",
+        result: event.content,
+        isError: event.isError,
+        diff: event.diff,
+        status: event.status,
+        conversationId,
+        imageData: imageDataList?.[0],
+        imageDataList,
+        toolUseId: event.toolUseId,
+      };
+    }
+    case "server_tool_start":
+      return {
+        type: "tool_use_start",
+        toolName: event.name,
+        input: event.input,
+        conversationId,
+        toolUseId: event.toolUseId,
+      };
+    case "server_tool_complete": {
+      let resultText = "";
+      if (Array.isArray(event.content) && event.content.length > 0) {
+        resultText = (event.content as unknown[])
+          .filter(
+            (r): r is { type: string; title: string; url: string } =>
+              typeof r === "object" &&
+              r != null &&
+              (r as { type?: string }).type === "web_search_result",
+          )
+          .map((r) => `${r.title}\n${r.url}`)
+          .join("\n\n");
+      }
+      return {
+        type: "tool_result",
+        toolName: "web_search",
+        result: resultText,
+        isError: event.isError,
+        conversationId,
+        toolUseId: event.toolUseId,
+      };
+    }
+    case "message_complete":
+      return {
+        type: "message_complete",
+        conversationId,
+      };
+    case "input_json_delta":
+    case "usage":
+    case "error":
+    case "provider_error":
+    case "max_tokens_reached":
+    case "context_compacting":
+    case "compaction_circuit_open":
+    case "compaction_circuit_closed":
+    case "compaction_completed":
+    case "history_stripped":
+    case "agent_loop_exit":
+      return null;
+    case "llm_call_started":
+      // The wake path persists its assistant tail via
+      // `persistWakeTailMessage` (an `addMessage`-shaped call) rather than
+      // the main event-handler's `reserve` → `updateContent` pipeline, so
+      // there is no row to reserve here. Translation returns null and the
+      // wake path's existing end-of-turn persist continues to mint the row.
+      return null;
+  }
+}
+
+/**
+ * Translate a raw agent event to its wire frame and broadcast it to
+ * connected clients. No-op for events with no client-visible shape.
+ */
+export function emitWakeAgentEvent(
+  conversation: Conversation,
+  event: AgentEvent,
+): void {
+  const frame = translateAgentEventToServerMessage(
+    event,
+    conversation.conversationId,
+  );
+  if (!frame) return;
+  broadcastMessage(frame);
+}
+
+/**
+ * Emit the live ui_surface card announcing that a wake produced output.
+ * The `surfaceId` matches the `ui_surface` content block injected into
+ * the wake's first assistant tail message so the client renders one card,
+ * not two.
+ */
+export function broadcastWakeSurface(
+  conversation: Conversation,
+  source: string,
+  hint: string,
+  surfaceId: string,
+): void {
+  broadcastMessage({
+    type: "ui_surface_show",
+    conversationId: conversation.conversationId,
+    surfaceId,
+    surfaceType: "card",
+    data: {
+      title: "Conversation Woke",
+      body: hint,
+      metadata: [{ label: "Source", value: source }],
+    },
+    display: "inline",
+  });
+}
+
+/**
+ * Persist a single tail message produced by a wake (assistant outputs and
+ * intervening tool_result user messages). Builds the channel/interface
+ * metadata, persists via the canonical `addMessage` path, syncs the row to
+ * the disk view, and backfills the message id onto this turn's LLM request
+ * logs so wake-produced messages match the user-turn persistence path.
+ */
+export async function persistWakeTailMessage(
+  conversation: Conversation,
+  message: Message,
+): Promise<void> {
+  const turnChannelCtx = conversation.getTurnChannelContext();
+  const turnInterfaceCtx = conversation.getTurnInterfaceContext();
+  const metadata: Record<string, unknown> = {
+    ...provenanceFromTrustContext(conversation.trustContext),
+    userMessageChannel: turnChannelCtx?.userMessageChannel ?? "vellum",
+    assistantMessageChannel:
+      turnChannelCtx?.assistantMessageChannel ?? "vellum",
+    userMessageInterface: turnInterfaceCtx?.userMessageInterface ?? "web",
+    assistantMessageInterface:
+      turnInterfaceCtx?.assistantMessageInterface ?? "web",
+  };
+  const persisted = await addMessage(
+    conversation.conversationId,
+    message.role,
+    JSON.stringify(message.content),
+    { metadata },
+  );
+  if (message.role === "assistant") {
+    try {
+      backfillMessageIdOnLogs(conversation.conversationId, persisted.id);
+    } catch (err) {
+      log.warn(
+        { err, conversationId: conversation.conversationId },
+        "wake persist: backfill messageId on LLM logs failed (non-fatal)",
+      );
+    }
+  }
+  try {
+    const convRow = getConversation(conversation.conversationId);
+    if (convRow) {
+      syncMessageToDisk(
+        conversation.conversationId,
+        persisted.id,
+        convRow.createdAt,
+      );
+    }
+  } catch (err) {
+    log.warn(
+      { err, conversationId: conversation.conversationId },
+      "wake persist: syncMessageToDisk failed (non-fatal)",
+    );
+  }
+}
+
+/**
+ * Temporarily restrict the tools visible/executable during a wake by
+ * reusing the conversation's subagent allowlist slot. Returns a restore
+ * callback that reinstates the previous allowlist so the wake can release
+ * the scope before any queued user turn is drained.
+ */
+export function scopeWakeAllowedTools(
+  conversation: Conversation,
+  tools: ReadonlySet<string>,
+): () => void {
+  const previous = conversation.subagentAllowedTools;
+  conversation.setSubagentAllowedTools(new Set(tools));
+  return () => {
+    conversation.setSubagentAllowedTools(previous);
+  };
+}

package/src/embedded/plugin-api.ts

@@ -8,7 +8,7 @@
  * means plugin-api ships as part of the assistant binary's regular code
  * graph; in JIT/Docker, it loads from source.
  *
- * The loaded namespace is then installed on `globalThis` under a versioned
+ * The loaded namespace is then installed on `globalThis` under a well-known
  * symbol. The boot-time shim writer (`ensurePluginApiShim`) enumerates
  * {@link PLUGIN_API_EXPORTS} and generates a tiny ESM module at
  * `<workspaceDir>/node_modules/@vellumai/plugin-api/index.js` that
@@ -26,7 +26,7 @@
 import * as pluginApi from "../plugin-api/index.js";
 
 /** Symbol key under which the plugin-api namespace is published on globalThis. */
-export const PLUGIN_API_REGISTRY_KEY = Symbol.for("vellum.plugin-api.v1");
+export const PLUGIN_API_REGISTRY_KEY = Symbol.for("vellum.plugin-api");
 
 // Install on globalThis once at module-load time. The shim writer reads
 // `PLUGIN_API_EXPORTS` to know which bindings to re-export; the shim's

package/src/export/__tests__/transcript-formatter.test.ts

@@ -9,6 +9,7 @@ type TestMessage = {
   content: string;
   createdAt: number;
   metadata: string | null;
+  clientMessageId: string | null;
 };
 
 const parentMessages: TestMessage[] = [
@@ -19,6 +20,7 @@ const parentMessages: TestMessage[] = [
     content: JSON.stringify([{ type: "text", text: "go research foo" }]),
     createdAt: 1_700_000_000_000,
     metadata: null,
+    clientMessageId: null,
   },
   {
     id: "msg-parent-2",
@@ -34,6 +36,7 @@ const parentMessages: TestMessage[] = [
         conversationId: "child-conv-1",
       },
     }),
+    clientMessageId: null,
   },
 ];
 
@@ -47,6 +50,7 @@ const childMessages: TestMessage[] = [
     ]),
     createdAt: 1_700_000_002_000,
     metadata: null,
+    clientMessageId: null,
   },
   {
     id: "msg-child-2",
@@ -57,6 +61,7 @@ const childMessages: TestMessage[] = [
     ]),
     createdAt: 1_700_000_003_000,
     metadata: null,
+    clientMessageId: null,
   },
 ];
 

package/src/heartbeat/__tests__/heartbeat-service.test.ts

@@ -85,6 +85,7 @@ const stubConfig: {
     activeHoursStart: number | null;
     activeHoursEnd: number | null;
     maxConsecutiveRuns: number | null;
+    maxDailyRuns: number | null;
     disposition: string;
   };
 } = {
@@ -94,6 +95,7 @@ const stubConfig: {
     activeHoursStart: null,
     activeHoursEnd: null,
     maxConsecutiveRuns: null,
+    maxDailyRuns: null,
     disposition: "Default disposition text.",
   },
 };
@@ -195,6 +197,7 @@ mock.module("../heartbeat-run-store.js", () => ({
   markStaleRunsAsMissed: () => 0,
   markStaleRunningAsError: () => 0,
   countCompletedHeartbeatRuns: () => 10,
+  countCompletedRunsToday: () => 0,
   countRecentConsecutiveRuns: () => 0,
 }));
 

package/src/heartbeat/heartbeat-run-store.ts

@@ -24,7 +24,8 @@ export type HeartbeatSkipReason =
   | "outside_active_hours"
   | "overlap"
   | "pre_first_user_message"
-  | "max_consecutive_runs";
+  | "max_consecutive_runs"
+  | "max_daily_runs";
 
 export interface HeartbeatRunRecord {
   id: string;
@@ -217,6 +218,27 @@ export function countCompletedHeartbeatRuns(): number {
   return row?.count ?? 0;
 }
 
+/**
+ * Count heartbeat runs that completed with status `ok` today (local midnight).
+ */
+export function countCompletedRunsToday(): number {
+  const db = getDb();
+  const now = new Date();
+  const startOfDay = new Date(
+    now.getFullYear(),
+    now.getMonth(),
+    now.getDate(),
+  ).getTime();
+  const row = db
+    .select({ count: sql<number>`count(*)` })
+    .from(heartbeatRuns)
+    .where(
+      sql`${heartbeatRuns.status} = 'ok' AND ${heartbeatRuns.scheduledFor} >= ${startOfDay}`,
+    )
+    .get();
+  return row?.count ?? 0;
+}
+
 /**
  * Count the most recent consecutive heartbeat runs with status `ok`,
  * walking backwards from newest. Stops at the first non-`ok` status

package/src/heartbeat/heartbeat-service.ts

@@ -25,6 +25,7 @@ import { stripCommentLines } from "../util/strip-comment-lines.js";
 import {
   completeHeartbeatRun,
   countCompletedHeartbeatRuns,
+  countCompletedRunsToday,
   countRecentConsecutiveRuns,
   insertPendingHeartbeatRun,
   markStaleRunningAsError,
@@ -187,6 +188,13 @@ export class HeartbeatService {
     );
   }
 
+  /** Whether the daily run cap has been reached. */
+  get isDailyCapReached(): boolean {
+    const config = getConfig().heartbeat;
+    if (config.maxDailyRuns == null) return false;
+    return countCompletedRunsToday() >= config.maxDailyRuns;
+  }
+
   async runManagedWakeIfDue(
     options: ManagedWakeHeartbeatRunOptions = {},
   ): Promise<ManagedWakeHeartbeatRunResult> {
@@ -551,6 +559,24 @@ export class HeartbeatService {
       return false;
     }
 
+    // Daily run cap — stop burning tokens when the daily budget is exhausted.
+    // Force runs bypass the cap.
+    if (
+      !force &&
+      config.maxDailyRuns != null &&
+      countCompletedRunsToday() >= config.maxDailyRuns
+    ) {
+      log.debug(
+        { maxDailyRuns: config.maxDailyRuns },
+        "Daily run cap reached, skipping",
+      );
+      if (runId) skipHeartbeatRun(runId, "max_daily_runs");
+      if (!this.cronMode) {
+        this.scheduleNextRun(config.intervalMs);
+      }
+      return false;
+    }
+
     // Overlap prevention
     if (this.activeRun) {
       log.debug("Previous heartbeat run still active, skipping");

package/src/ipc/__tests__/browser-ipc.test.ts

@@ -55,7 +55,7 @@ mock.module("../../browser/operations.js", () => ({
   },
 }));
 
-mock.module("../../daemon/conversation-store.js", () => ({
+mock.module("../../daemon/conversation-registry.js", () => ({
   findConversation: (conversationId: string) => {
     mockFindConversationCalls.push(conversationId);
     return mockConversation ?? undefined;

package/src/ipc/__tests__/ui-request-route.test.ts

@@ -32,9 +32,9 @@ let mockSurfaceResult: InteractiveUiResult = {
 let mockSurfaceThrows: Error | null = null;
 
 // Re-export the real module and override only findConversation.
-const realStore = await import("../../daemon/conversation-store.js");
-mock.module("../../daemon/conversation-store.js", () => ({
-  ...realStore,
+const realRegistry = await import("../../daemon/conversation-registry.js");
+mock.module("../../daemon/conversation-registry.js", () => ({
+  ...realRegistry,
   findConversation: (_conversationId: string) => mockConversation ?? undefined,
 }));
 

package/src/ipc/skill-routes/__tests__/memory.test.ts

@@ -137,6 +137,21 @@ describe("host.memory.addMessage", () => {
       }),
     ).rejects.toThrow();
   });
+
+  test("rejects the non-renderable system role", async () => {
+    // GIVEN the messages store is UI-facing (ConversationMessage), so only
+    // renderable turns may be persisted via this facet
+    // WHEN a skill attempts to add a system row
+    // THEN the route rejects it instead of persisting agent-context scaffolding
+    await expect(
+      memoryAddMessageRoute.handler({
+        conversationId: "c",
+        role: "system",
+        content: "agent-context scaffolding",
+      }),
+    ).rejects.toThrow();
+    expect(addMessageSpy).not.toHaveBeenCalled();
+  });
 });
 
 describe("host.memory.wakeAgentForOpportunity", () => {