@vellumai/assistant 0.8.5 → 0.8.7

package/src/plugins/defaults/tool-result-truncate/terminal.ts

@@ -0,0 +1,113 @@
+/**
+ * Default `toolResultTruncate` behavior: tail-drops oversized tool-result text
+ * down to a character budget, plus the truncation primitive it wraps.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ */
+
+import type {
+  ToolResultTruncateArgs,
+  ToolResultTruncateResult,
+} from "./types.js";
+
+const HIGH_SURROGATE_START = 0xd800;
+const HIGH_SURROGATE_END = 0xdbff;
+const LOW_SURROGATE_START = 0xdc00;
+const LOW_SURROGATE_END = 0xdfff;
+
+function isHighSurrogate(code: number): boolean {
+  return code >= HIGH_SURROGATE_START && code <= HIGH_SURROGATE_END;
+}
+
+function isLowSurrogate(code: number): boolean {
+  return code >= LOW_SURROGATE_START && code <= LOW_SURROGATE_END;
+}
+
+/**
+ * Slice a string by code-unit indices without splitting a surrogate pair, so
+ * the result never ends or begins mid-emoji. Indices are clamped to the
+ * string bounds; a cut that would land between a high/low surrogate is nudged
+ * inward to the nearest whole code point.
+ */
+function safeStringSlice(
+  str: string,
+  start = 0,
+  end: number = str.length,
+): string {
+  let safeStart = Math.max(0, Math.min(str.length, start));
+  let safeEnd = Math.max(safeStart, Math.min(str.length, end));
+
+  if (safeEnd < str.length && safeEnd > safeStart) {
+    const lastCode = str.charCodeAt(safeEnd - 1);
+    if (isHighSurrogate(lastCode)) {
+      safeEnd--;
+    }
+  }
+
+  if (safeStart > 0 && safeStart < str.length) {
+    const firstCode = str.charCodeAt(safeStart);
+    if (isLowSurrogate(firstCode)) {
+      safeStart++;
+      if (safeStart > safeEnd) safeEnd = safeStart;
+    }
+  }
+
+  return str.slice(safeStart, safeEnd);
+}
+
+/**
+ * Minimum number of characters to preserve when truncating.
+ */
+export const MIN_KEEP_CHARS = 2_000;
+
+/**
+ * Suffix appended to truncated tool results.
+ */
+export const TRUNCATION_SUFFIX =
+  "\n\n[Content truncated — original exceeded size limit. Use offset/limit parameters or request specific sections for large content.]";
+
+/**
+ * Truncate text with newline-boundary awareness.
+ *
+ * If `text.length <= maxChars`, the text is returned as-is.
+ * Otherwise we look for the last newline that falls within 80% of the budget
+ * so we get a clean cut. At least `MIN_KEEP_CHARS` characters are always
+ * preserved.
+ */
+export function truncateToolResultText(text: string, maxChars: number): string {
+  if (text.length <= maxChars) {
+    return text;
+  }
+
+  const effectiveMax = Math.max(maxChars, MIN_KEEP_CHARS);
+  const cutPoint = effectiveMax - TRUNCATION_SUFFIX.length;
+
+  // Look for a newline within the last 20% of the budget for a clean break.
+  const threshold = Math.floor(cutPoint * 0.8);
+  const lastNewline = text.lastIndexOf("\n", cutPoint);
+
+  const sliceEnd = lastNewline >= threshold ? lastNewline : cutPoint;
+
+  // If sliceEnd covers the full text, nothing was actually removed — return
+  // the original text without appending the suffix.
+  if (sliceEnd >= text.length) {
+    return text;
+  }
+
+  return safeStringSlice(text, 0, sliceEnd) + TRUNCATION_SUFFIX;
+}
+
+/**
+ * Truncate a single tool-result block's content to `args.maxChars`. Exported
+ * so the agent loop can call it directly and tests can verify the default
+ * behavior.
+ */
+export function defaultToolResultTruncateTerminal(
+  args: ToolResultTruncateArgs,
+): ToolResultTruncateResult {
+  const truncated = truncateToolResultText(args.content, args.maxChars);
+  return {
+    content: truncated,
+    truncated: truncated !== args.content,
+  };
+}

package/src/plugins/defaults/tool-result-truncate/types.ts

@@ -0,0 +1,22 @@
+/**
+ * Argument and result shapes for the default `toolResultTruncate` behavior.
+ */
+
+/**
+ * Input to tool-result truncation: the raw tool-result text and the character
+ * budget the caller computed from the context-window share.
+ */
+export type ToolResultTruncateArgs = {
+  readonly content: string;
+  readonly maxChars: number;
+};
+
+/**
+ * Output of tool-result truncation: the (possibly truncated) content and a
+ * boolean indicating whether the input was actually shortened. Callers use
+ * `truncated` for telemetry / warnings.
+ */
+export type ToolResultTruncateResult = {
+  readonly content: string;
+  readonly truncated: boolean;
+};

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

@@ -50,7 +50,7 @@ import { z } from "zod";
 
 import assistantPkg from "../../package.json" with { type: "json" };
 import { finalizeTool } from "../tools/tool-defaults.js";
-import type { LoadedTool, ToolDefinition } from "../tools/types.js";
+import type { Tool, ToolDefinition } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
 import { registerPlugin } from "./registry.js";
 import type {
@@ -276,7 +276,7 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
   const hooks = await loadHooks(pluginDir, name);
   if (hooks !== undefined) plugin.hooks = hooks;
 
-  const tools: LoadedTool[] = [];
+  const tools: Tool[] = [];
   for (const { name: toolName, path: toolPath } of listSurfaceDir(
     join(pluginDir, "tools"),
   )) {

package/src/plugins/pipeline.ts

@@ -36,17 +36,6 @@ import {
   type TurnContext,
 } from "./types.js";
 
-// Side-effect import: register every first-party default plugin at module
-// load so downstream consumers (production bootstrap AND tests that skip
-// `bootstrapPlugins()`) observe a fully-populated registry by default.
-// Every code path that calls `runPipeline` imports this module, so by the
-// time the first pipeline runs the defaults are already in place. User
-// plugins load via `loadUserPlugins()` inside `bootstrapPlugins()` (which
-// runs AFTER all static side-effect imports), so the onion ordering
-// (defaults inner, user middleware outer) across all 14 pipelines is
-// preserved in production.
-import "./defaults/index.js";
-
 const moduleLogger = getLogger("plugin-pipeline");
 
 // ─── Default timeouts ───────────────────────────────────────────────────────
@@ -67,7 +56,6 @@ export const DEFAULT_TIMEOUTS: Record<PipelineName, number | null> = {
   llmCall: null,
   toolExecute: null,
   memoryRetrieval: null,
-  historyRepair: null,
   tokenEstimate: null,
   compaction: null,
   overflowReduce: null,

package/src/plugins/types.ts

@@ -16,6 +16,8 @@
  * Design doc: `.private/plans/agent-plugin-system.md`.
  */
 
+import type { CompactionCircuitClosedEvent } from "../api/events/compaction-circuit-closed.js";
+import type { CompactionCircuitOpenEvent } from "../api/events/compaction-circuit-open.js";
 import type { ContextWindowConfig } from "../config/schemas/inference.js";
 import type {
   ContextWindowManager,
@@ -28,11 +30,11 @@ import type {
   ChannelCommandContext,
   InjectionMode,
 } from "../daemon/conversation-runtime-assembly.js";
-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 { PluginHookFn } from "../plugin-api/types.js";
 import type {
   ContentBlock,
   Message,
@@ -42,12 +44,12 @@ import type {
   ToolDefinition,
 } from "../providers/types.js";
 import type { SkillRoute } from "../runtime/skill-route-registry.js";
-import type {
-  LoadedTool,
-  ToolContext,
-  ToolExecutionResult,
-} from "../tools/types.js";
+import type { Tool, ToolContext, ToolExecutionResult } from "../tools/types.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
+import type {
+  ToolResultTruncateArgs,
+  ToolResultTruncateResult,
+} from "./defaults/tool-result-truncate/types.js";
 
 // ─── Manifest ────────────────────────────────────────────────────────────────
 
@@ -88,11 +90,12 @@ export interface PluginManifest {
   config?: unknown;
 }
 
-// ─── Init / Shutdown context ─────────────────────────────────────────────────
-// Public types — defined in `assistant/src/plugin-api/types.ts` and re-exported
-// here so existing internal call sites keep working. Plugin authors will
-// import these from `@vellumai/plugin-api` once that package is published.
+// ─── Public plugin-API types ─────────────────────────────────────────────────
+// Defined in `assistant/src/plugin-api/types.ts` and re-exported here so
+// existing internal call sites keep working. Plugin authors import these from
+// `@vellumai/plugin-api`.
 export type {
+  PluginHookFn,
   PluginInitContext,
   PluginShutdownContext,
 } from "../plugin-api/types.js";
@@ -122,7 +125,6 @@ export type PipelineName =
   | "llmCall"
   | "toolExecute"
   | "memoryRetrieval"
-  | "historyRepair"
   | "tokenEstimate"
   | "compaction"
   | "overflowReduce"
@@ -144,22 +146,20 @@ export type TurnResult = { readonly output: unknown };
 /**
  * Pipeline arguments for `llmCall` — mirrors the inputs to
  * {@link Provider.sendMessage}. The terminal handler (the default plugin)
- * delegates straight to `args.provider.sendMessage(args.messages, args.tools,
- * args.systemPrompt, args.options)`; middleware may observe or rewrite any
- * field before that call, short-circuit with a synthetic {@link LLMCallResult},
- * or post-process the response on the way out.
+ * delegates straight to `args.provider.sendMessage(args.messages, args.options)`;
+ * middleware may observe or rewrite any field before that call, short-circuit
+ * with a synthetic {@link LLMCallResult}, or post-process the response on the
+ * way out.
  *
  * `provider` is passed in `args` (rather than resolved from the runtime) so
  * middleware can swap it deterministically per-call. `options` carries the
- * full `SendMessageOptions` bag — `config`, `onEvent`, and `signal` — so
- * middleware can substitute streaming handlers or cancellation signals
- * without reconstructing them.
+ * full `SendMessageOptions` bag — `tools`, `systemPrompt`, `config`,
+ * `onEvent`, and `signal` — so middleware can substitute streaming handlers,
+ * tool sets, or cancellation signals without reconstructing them.
  */
 export type LLMCallArgs = {
   readonly provider: Provider;
   readonly messages: Message[];
-  readonly tools?: ToolDefinition[];
-  readonly systemPrompt?: string;
   readonly options?: SendMessageOptions;
 };
 export type LLMCallResult = ProviderResponse;
@@ -235,32 +235,6 @@ export interface MemoryResult {
   readonly memoryGraphBlocks: ReadonlyArray<MemoryBlock>;
 }
 
-/**
- * Arguments for the `historyRepair` pipeline. `history` is the pre-repair
- * message list scheduled for the next provider call; `provider` is the
- * downstream provider key (`ctx.provider.name`) so plugins that want to
- * special-case repair per provider can discriminate without looking up the
- * ambient provider from `TurnContext`.
- *
- * The pipeline currently wraps only the standard pre-run repair pass
- * (`repairHistory`). The orchestrator's one-shot deep-repair fallback
- * (`deepRepairHistory`), invoked only after a provider ordering error,
- * remains a direct call. Adding a `mode` discriminator here would be
- * premature — deep-repair has no known plugin-level consumer yet.
- */
-export type HistoryRepairArgs = {
-  readonly history: Message[];
-  readonly provider: string;
-};
-
-/**
- * Result of the `historyRepair` pipeline. Carries both the repaired message
- * list and the `RepairStats` record the orchestrator logs when any repair
- * happened — the default plugin forwards the shape unchanged from
- * {@link repairHistory}.
- */
-export type HistoryRepairResult = RepairResult;
-
 /**
  * Inputs to the `tokenEstimate` pipeline. The default middleware delegates
  * these straight to {@link estimatePromptTokensRaw}; custom plugins may
@@ -439,18 +413,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, options?)`.
+ *                     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 +440,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 +454,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 +480,8 @@ export type PersistDeleteArgs = {
 
 export type PersistArgs =
   | PersistAddArgs
+  | PersistReserveArgs
+  | PersistUpdateContentArgs
   | PersistUpdateArgs
   | PersistDeleteArgs;
 
@@ -506,6 +502,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 +532,8 @@ export type PersistDeleteResult = {
 
 export type PersistResult =
   | PersistAddResult
+  | PersistReserveResult
+  | PersistUpdateContentResult
   | PersistUpdateResult
   | PersistDeleteResult;
 
@@ -558,26 +575,6 @@ export type TitleGenerateArgs = TitleArgs;
  */
 export type TitleGenerateResult = TitleResult;
 
-/**
- * Input to the `toolResultTruncate` pipeline: the raw tool-result text and
- * the character budget the caller computed from the context-window share
- * (see `calculateMaxToolResultChars` in `context/tool-result-truncation.ts`).
- */
-export type ToolResultTruncateArgs = {
-  readonly content: string;
-  readonly maxChars: number;
-};
-
-/**
- * Output of the `toolResultTruncate` pipeline: the (possibly truncated)
- * content and a boolean flag indicating whether the pipeline actually
- * shortened the input. Callers use `truncated` for telemetry / warnings.
- */
-export type ToolResultTruncateResult = {
-  readonly content: string;
-  readonly truncated: boolean;
-};
-
 /**
  * Snapshot of the just-completed assistant turn plus retry/context counters
  * the `emptyResponse` pipeline needs to decide whether to nudge, accept, or
@@ -613,6 +610,17 @@ export interface EmptyResponseArgs {
    * visible text. See `agent/loop.ts` for why the whole-run scan matters.
    */
   readonly priorAssistantHadVisibleText: boolean;
+  /**
+   * Provider-reported stop reason for the assistant turn being evaluated.
+   * `null`/`undefined` when the provider didn't report one (older
+   * providers, partial responses). The default terminal uses this to
+   * distinguish an explicit safety-classifier refusal (Anthropic's
+   * `"refusal"`) from an organically-empty turn — refusals deserve a
+   * nudge even on the very first model call of the run, whereas an
+   * organically-empty first call usually means the model legitimately
+   * had nothing to say.
+   */
+  readonly stopReason: string | null | undefined;
 }
 
 /**
@@ -685,8 +693,11 @@ export type ToolErrorResult = ToolErrorDecision;
  *
  * `onEvent` is optional — when provided, the default plugin emits
  * `compaction_circuit_open` / `compaction_circuit_closed` transition events
- * through it. Callers that just want to query without emitting (or without
- * a `ServerMessage` sink handy) can omit it.
+ * through it. Its parameter is narrowed to {@link CompactionCircuitEvent} (the
+ * only two messages this pipeline ever emits) rather than the full
+ * `ServerMessage` union, so a caller whose outbound channel can carry just
+ * these two events can satisfy it. Callers that only want to query without
+ * emitting can omit it.
  */
 export type CircuitBreakerArgs = {
   readonly key: string;
@@ -696,9 +707,20 @@ export type CircuitBreakerArgs = {
     consecutiveCompactionFailures: number;
     compactionCircuitOpenUntil: number | null;
   };
-  readonly onEvent?: (msg: ServerMessage) => void;
+  readonly onEvent?: (msg: CompactionCircuitEvent) => void;
 };
 
+/**
+ * The complete set of transition events the `circuitBreaker` pipeline emits:
+ * `compaction_circuit_open` when the breaker trips and `compaction_circuit_closed`
+ * on the open→closed transition. Both are a subset of `ServerMessage`, so any
+ * existing `ServerMessage` sink remains assignable to a
+ * `(msg: CompactionCircuitEvent) => void` parameter.
+ */
+export type CompactionCircuitEvent =
+  | CompactionCircuitOpenEvent
+  | CompactionCircuitClosedEvent;
+
 /**
  * Result of a `circuitBreaker` pipeline invocation.
  *
@@ -723,7 +745,6 @@ export interface PipelineMiddlewareMap {
   llmCall: Middleware<LLMCallArgs, LLMCallResult>;
   toolExecute: Middleware<ToolExecuteArgs, ToolExecuteResult>;
   memoryRetrieval: Middleware<MemoryArgs, MemoryResult>;
-  historyRepair: Middleware<HistoryRepairArgs, HistoryRepairResult>;
   tokenEstimate: Middleware<TokenEstimateArgs, TokenEstimateResult>;
   compaction: Middleware<CompactionArgs, CompactionResult>;
   overflowReduce: Middleware<OverflowReduceArgs, OverflowReduceResult>;
@@ -1064,22 +1085,6 @@ export interface PluginSkillRegistration {
 
 // ─── Plugin ──────────────────────────────────────────────────────────────────
 
-/**
- * A plugin lifecycle hook. Receives a per-lifecycle context shape and
- * may return either a transformed context or `void`. Today's runtime
- * consumes only the resolved-or-rejected nature of the promise; the
- * `TCtx` return is reserved for future hooks that fan a transformed
- * context out to downstream plugins.
- *
- * Each known hook key has a documented context shape:
- *   - `init` — {@link PluginInitContext}
- *   - `shutdown` — {@link PluginShutdownContext}
- *
- * Unknown keys are populated by the loader for forward compatibility
- * but are not invoked by today's runtime.
- */
-export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
-
 /**
  * Map of lifecycle hooks contributed by a plugin. Keys match file
  * basenames under `<plugin>/hooks/` — the external loader populates one
@@ -1113,10 +1118,10 @@ export interface Plugin {
    * `@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
+   * `Tool` values stored here. Category / ownership metadata is
    * stamped by `registerPluginTools` at registration time.
    */
-  tools?: LoadedTool[];
+  tools?: Tool[];
   /** HTTP route registrations served by the assistant. */
   routes?: PluginRouteRegistration[];
   /** Skill registrations loaded at startup. */

package/src/plugins/user-loader.ts

@@ -37,8 +37,8 @@
  *
  * Call order relative to the rest of the plugin system:
  *
- *     first-party registrations (static side-effect imports)
- *       → loadUserPlugins()          ← this module
+ *     first-party default registrations (explicit, at daemon startup)
+ *       → loadUserPlugins()          ← this module (closes registration)
  *         → bootstrapPlugins()       (init for everyone registered so far)
  *
  * Design doc: `.private/plans/agent-plugin-system.md` (PR 29).
@@ -92,7 +92,8 @@ const USER_PLUGIN_IMPORT_TIMEOUT_MS = 10_000;
 export async function loadUserPlugins(
   options: { importTimeoutMs?: number } = {},
 ): Promise<void> {
-  const importTimeoutMs = options.importTimeoutMs ?? USER_PLUGIN_IMPORT_TIMEOUT_MS;
+  const importTimeoutMs =
+    options.importTimeoutMs ?? USER_PLUGIN_IMPORT_TIMEOUT_MS;
 
   // Materialize the workspace-level `@vellumai/plugin-api` shim *before*
   // we dynamic-import any user plugins. The shim file must exist on disk

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

@@ -50,7 +50,6 @@ export async function injectAuxAssistantMessage(params: {
     params.conversationId,
     "assistant",
     JSON.stringify([{ type: "text", text: params.text }]),
-    undefined,
     { skipIndexing: true },
   );
 

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

@@ -90,7 +90,6 @@ mock.module("../daemon/process-message.js", () => ({
   processMessage: async (
     conversationId: string,
     prompt: string,
-    _attachmentIds: unknown,
     options: unknown,
   ) => {
     processMessageCalls.push({ conversationId, prompt, options });
@@ -148,8 +147,7 @@ let addMessageCalls: Array<{
   conversationId: string;
   role: string;
   content: string;
-  metadata: unknown;
-  opts: unknown;
+  options: unknown;
 }> = [];
 
 mock.module("../memory/conversation-crud.js", () => ({
@@ -157,12 +155,12 @@ mock.module("../memory/conversation-crud.js", () => ({
     conversationId: string,
     role: string,
     content: string,
-    metadata: unknown,
-    opts: unknown,
+    options: unknown,
   ) => {
-    addMessageCalls.push({ conversationId, role, content, metadata, opts });
+    addMessageCalls.push({ conversationId, role, content, options });
     return { id: `msg-${addMessageCalls.length}` };
   },
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
 // emitNotificationSignal mock
@@ -181,6 +179,15 @@ mock.module("../notifications/emit-signal.js", () => ({
   },
 }));
 
+// app sync invalidation mock
+let publishAppsChangedCalls: Array<string | undefined> = [];
+
+mock.module("../runtime/sync/resource-sync-events.js", () => ({
+  publishAppsChanged: (originClientId?: string) => {
+    publishAppsChangedCalls.push(originClientId);
+  },
+}));
+
 // findConversation mock
 type MockConversation = {
   processing: boolean;
@@ -303,6 +310,7 @@ function resetState() {
   releaseClaimCalls = 0;
   addMessageCalls = [];
   emitSignalCalls = [];
+  publishAppsChangedCalls = [];
   broadcastCalls = [];
   mockConversations = new Map();
   logWarnCalls = [];
@@ -462,10 +470,13 @@ describe("runProactiveArtifactJob", () => {
         type: "app_files_changed",
         appId: "app-123",
       });
+      expect(publishAppsChangedCalls).toEqual([undefined]);
 
       // Message injection: addMessage called with skipIndexing
       expect(addMessageCalls).toHaveLength(1);
-      expect(addMessageCalls[0].opts).toEqual({ skipIndexing: true });
+      expect(
+        (addMessageCalls[0].options as Record<string, unknown>).skipIndexing,
+      ).toBe(true);
       expect(addMessageCalls[0].conversationId).toBe("conv-1");
       const injectedAppContent = JSON.parse(addMessageCalls[0].content);
       expect(injectedAppContent[0].text).toContain("Library");
@@ -714,7 +725,9 @@ describe("injectAuxAssistantMessage", () => {
     expect(addMessageCalls).toHaveLength(1);
     expect(addMessageCalls[0].conversationId).toBe("conv-inject-1");
     expect(addMessageCalls[0].role).toBe("assistant");
-    expect(addMessageCalls[0].opts).toEqual({ skipIndexing: true });
+    expect(
+      (addMessageCalls[0].options as Record<string, unknown>).skipIndexing,
+    ).toBe(true);
 
     // Pushed to in-memory messages
     expect(messages).toHaveLength(1);

package/src/proactive-artifact/job.ts

@@ -31,6 +31,7 @@ import {
   extractText,
   getConfiguredProvider,
 } from "../providers/provider-send-message.js";
+import { publishAppsChanged } from "../runtime/sync/resource-sync-events.js";
 import { getLogger } from "../util/logger.js";
 import { injectAuxAssistantMessage } from "./aux-message-injector.js";
 import {
@@ -160,6 +161,7 @@ export async function runProactiveArtifactJob(params: {
 
     if (artifactType === "app") {
       params.broadcastMessage({ type: "app_files_changed", appId: artifactId });
+      publishAppsChanged();
     }
 
     // ── Post-build message copy ─────────────────────────────────────
@@ -284,7 +286,7 @@ For apps, keep scope tight — single file or 2-3 files max, under ~300 lines. S
 
 Write the source code following the skill instructions, then compile via app_refresh.`;
 
-  await processMessage(conversation.id, prompt, undefined, {
+  await processMessage(conversation.id, prompt, {
     callSite: "proactiveArtifactBuild",
     trustContext: INTERNAL_GUARDIAN_TRUST_CONTEXT,
   });