@vellumai/assistant 0.12.2-staging.6 → 0.12.2-staging.7

package/src/daemon/conversation-tool-setup.ts

@@ -22,6 +22,10 @@ import {
 import { supportsChannelReaction } from "../messaging/providers/index.js";
 import type { PermissionPrompter } from "../permissions/prompter.js";
 import type { SecretPrompter } from "../permissions/secret-prompter.js";
+import {
+  hashConversationToolSurface,
+  recordConversationToolSurface,
+} from "../persistence/conversation-tool-surface.js";
 import { getBindingByConversation } from "../persistence/external-conversation-store.js";
 import { getAllDefaultPluginNames } from "../plugins/defaults/main.js";
 import { isActivationSession } from "../plugins/defaults/memory/activation-session-store.js";
@@ -943,6 +947,50 @@ export function canSpawnSubagentsForTurn(ctx: Conversation): boolean {
   );
 }
 
+/**
+ * Build the agent loop's `onToolsSent` observer for a conversation: record
+ * the tool array each provider call sends so a later fork wake can replay it
+ * (`recordConversationToolSurface`). Only the loop's send boundary sees the
+ * sent array. The resolver is also consulted out of band (the token count
+ * behind `/compact` and `/clean`, compaction estimates), where a read outside
+ * any turn resolves a clientless surface that would overwrite the one the
+ * conversation's turns actually send.
+ *
+ * Arrays that are not the conversation's own surface are skipped: a replaying
+ * wake sends its source's array, an empty array is a tools-disabled call (a
+ * fork replaying it could never call `remember`), and disk-pressure cleanup
+ * mode narrows the wire to cleanup tools. Best-effort: a failed write is
+ * logged and the array still counts as recorded, so a persistent failure logs
+ * once per distinct surface rather than once per provider call.
+ */
+export function createWireToolSurfaceRecorder(
+  ctx: Conversation,
+): (tools: ToolDefinition[]) => void {
+  return (tools) => {
+    if (
+      !ctx.conversationId ||
+      ctx.wireToolReplay ||
+      tools.length === 0 ||
+      ctx.diskPressureCleanupModeActive === true
+    ) {
+      return;
+    }
+    try {
+      ctx.recordedToolSurfaceHash = recordConversationToolSurface(
+        ctx.conversationId,
+        tools,
+        ctx.recordedToolSurfaceHash,
+      );
+    } catch (err) {
+      log.warn(
+        { err, conversationId: ctx.conversationId },
+        "failed to record the conversation's wire tool surface; continuing",
+      );
+      ctx.recordedToolSurfaceHash = hashConversationToolSurface(tools);
+    }
+  };
+}
+
 /**
  * Build a resolveTools callback that merges base tool definitions with
  * dynamically projected skill tools on each agent turn. Also updates
@@ -1237,6 +1285,14 @@ export function createResolveToolsCallback(
 
     ctx.allowedToolNames = turnAllowed;
 
-    return applyActivityField(allBaseDefs);
+    // A wake replaying its source's recorded surface sends that array
+    // verbatim: the wire tool block is the first tier of the provider cache
+    // prefix (tools → system → messages), so only the same bytes read the
+    // source's cached prefix instead of rewriting it. Execution is unaffected:
+    // `allowedToolNames` above and the executor's allowlist gate still decide
+    // what may run.
+    return ctx.wireToolReplay
+      ? [...ctx.wireToolReplay]
+      : applyActivityField(allBaseDefs);
   };
 }

package/src/daemon/conversation.ts

@@ -181,6 +181,7 @@ import {
   canSpawnSubagentsForTurn,
   createResolveToolsCallback,
   createToolExecutor,
+  createWireToolSurfaceRecorder,
 } from "./conversation-tool-setup.js";
 import { canonicalizeTimeZone } from "./date-context.js";
 import { HostAppControlProxy } from "./host-app-control-proxy.js";
@@ -452,6 +453,21 @@ export class Conversation {
    * @internal
    */
   toolContextPin?: WakeToolContextPin;
+  /**
+   * Tool definitions sent verbatim in place of the resolved wire array, for
+   * a wake replaying its source conversation's recorded surface
+   * (`recordConversationToolSurface`). Set and restored alongside the
+   * allowlist by `scopeWakeAllowedTools`; read only where the resolver returns
+   * the wire array, so it never widens what may execute.
+   * @internal
+   */
+  wireToolReplay?: readonly ToolDefinition[];
+  /**
+   * Hash of the wire tool array last recorded for this conversation in this
+   * process, so an unchanged surface is not rewritten on every provider call.
+   * @internal
+   */
+  recordedToolSurfaceHash?: string;
   /** @internal */ readonly skillProjectionState = new Map<string, string>();
   /** @internal */ readonly skillProjectionCache: SkillProjectionCache = {};
   /** @internal */ usageStats: UsageStats = {
@@ -1038,6 +1054,7 @@ export class Conversation {
       tools: toolDefs.length > 0 ? toolDefs : undefined,
       toolExecutor: toolDefs.length > 0 ? toolExecutor : undefined,
       resolveTools,
+      onToolsSent: createWireToolSurfaceRecorder(this),
       resolveConversationDir: () => {
         const conv = getConversation(this.conversationId);
         if (!conv) {

package/src/daemon/daemon-control.ts

@@ -258,15 +258,11 @@ async function getDaemonStatus(): Promise<{
   return { running: true, pid };
 }
 
-function getStartupLockPath(): string {
-  return getDaemonStartupLockPath();
-}
-
 /** Attempt to acquire a startup lock. Returns true on success. Stale locks
  *  (older than STARTUP_LOCK_STALE_MS) are forcibly removed to prevent
  *  permanent deadlocks from a crashed caller. */
 function acquireStartupLock(): boolean {
-  const lockPath = getStartupLockPath();
+  const lockPath = getDaemonStartupLockPath();
   try {
     // Ensure the root directory exists before attempting the lock file write.
     // On a first-time run, getRootDir() may not exist yet, and writeFileSync
@@ -293,7 +289,7 @@ function acquireStartupLock(): boolean {
 
 function releaseStartupLock(): void {
   try {
-    unlinkSync(getStartupLockPath());
+    unlinkSync(getDaemonStartupLockPath());
   } catch {
     /* already removed */
   }

package/src/daemon/orphan-reaper.ts

@@ -1,9 +1,10 @@
 /**
  * Periodic reaper for orphaned subprocesses that reparent to the daemon.
  *
- * Tools run commands in their own process group (`detached: true`) and, on
- * timeout/abort, group-kill with `process.kill(-pgid, SIGKILL)` (the bash and
- * host_bash tools, and the skill sandbox runner). The
+ * POSIX tools run commands in their own process group (`detached: true`) and,
+ * on timeout/abort, group-kill with `process.kill(-pgid, SIGKILL)` (the bash
+ * and host_bash tools, and the skill sandbox runner). Windows piped shell
+ * children stay attached and are torn down with `taskkill /T`. The
  * immediate child is reaped by Bun/libuv, but its descendants — e.g. git's
  * transport helpers or a skill runner's `bun` process — were never spawned by
  * the daemon, so when the group dies they reparent to PID 1. When the daemon

package/src/daemon/tool-setup-types.ts

@@ -59,6 +59,12 @@ export interface SubagentToolStats {
  * parity for desktop/web sources; channel-routed sources resolve every tool
  * gate identically under `hasNoClient: true` with or without them.)
  *
+ * A wake that also carries its source's recorded wire array
+ * (`Conversation.wireToolReplay`, set by `scopeWakeAllowedTools`) sends that
+ * array verbatim, so the pin then shapes only the execution-side inventory
+ * (`allowedToolNames`); the pin alone carries wire parity for a source with
+ * no recorded surface.
+ *
  * Tool-definition resolution ONLY. The executor callback and host-proxy
  * attachment paths never read the pin, so it cannot make a host tool
  * runnable: in execution gate mode every non-allowlisted call is rejected

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

@@ -22,7 +22,7 @@ import {
 import { syncMessageToDisk } from "../persistence/conversation-disk-view.js";
 import { backfillMessageIdOnLogs } from "../persistence/llm-request-log-store.js";
 import { resolveMediaSourceData } from "../providers/media-resolve.js";
-import type { Message } from "../providers/types.js";
+import type { Message, ToolDefinition } from "../providers/types.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
 import type { CompletedBackgroundTool } from "../tools/background-tool-registry.js";
@@ -350,38 +350,60 @@ export async function persistWakeTriggerMessage(
   }
 }
 
+/**
+ * How a wake's tool allowlist is applied beyond the allowlist itself. Every
+ * field is set on the conversation together with the allowlist and restored
+ * with it.
+ */
+export interface WakeToolScopeOptions {
+  /** How the allowlist is enforced; see {@link SubagentToolGateMode}. */
+  gateMode?: SubagentToolGateMode;
+  /**
+   * Freezes the client-context inputs for tool-definition resolution
+   * (execution-gate-mode cache-parity wakes); see {@link WakeToolContextPin}.
+   * Its `requestOrigin`, when set, is stamped onto the conversation's per-turn
+   * origin so the permission checker's origin-scoped auto-grants fire.
+   */
+  toolContextPin?: WakeToolContextPin;
+  /**
+   * Skills whose bundled tools join the turn's active set
+   * (`allowedToolNames`) so they are callable without a prior `skill_load`.
+   */
+  preactivateSkillIds?: readonly string[];
+  /**
+   * Sent verbatim as the wake's wire tool array in place of the resolved one
+   * (the source conversation's recorded surface, replayed for provider
+   * prompt-cache parity). Changes nothing about what may execute.
+   */
+  wireToolDefinitions?: readonly ToolDefinition[];
+}
+
 /**
  * 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.
- *
- * `gateMode` controls how the allowlist is enforced — see
- * {@link SubagentToolGateMode}. `toolContextPin`, when provided
- * (execution-gate-mode cache-parity wakes), freezes the client-context
- * inputs for tool-definition resolution — see {@link WakeToolContextPin}.
- * Its `requestOrigin`, when set, is stamped onto the conversation's per-turn
- * origin so the permission checker's origin-scoped auto-grants fire for the
- * wake. `preactivateSkillIds`, when non-empty, activates those skills' bundled
- * tools in the turn's active set (`allowedToolNames`) for the wake so they are
- * callable without a prior `skill_load`. All are set and restored alongside the
- * allowlist.
  */
 export function scopeWakeAllowedTools(
   conversation: Conversation,
   tools: ReadonlySet<string>,
-  gateMode: SubagentToolGateMode = "wire",
-  toolContextPin?: WakeToolContextPin,
-  preactivateSkillIds?: readonly string[],
+  {
+    gateMode = "wire",
+    toolContextPin,
+    preactivateSkillIds,
+    wireToolDefinitions,
+  }: WakeToolScopeOptions = {},
 ): () => void {
   const previous = conversation.subagentAllowedTools;
   const previousGateMode = conversation.subagentToolGateMode;
   const previousToolContextPin = conversation.toolContextPin;
   const previousRequestOrigin = conversation.currentTurnRequestOrigin;
   const previousPreactivated = conversation.preactivatedSkillIds;
+  const previousWireToolReplay = conversation.wireToolReplay;
   conversation.setSubagentAllowedTools(new Set(tools));
   conversation.subagentToolGateMode = gateMode;
   conversation.toolContextPin = toolContextPin;
+  conversation.wireToolReplay = wireToolDefinitions;
   if (toolContextPin?.requestOrigin !== undefined) {
     conversation.currentTurnRequestOrigin = toolContextPin.requestOrigin;
   }
@@ -394,5 +416,6 @@ export function scopeWakeAllowedTools(
     conversation.toolContextPin = previousToolContextPin;
     conversation.currentTurnRequestOrigin = previousRequestOrigin;
     conversation.setPreactivatedSkillIds(previousPreactivated);
+    conversation.wireToolReplay = previousWireToolReplay;
   };
 }

package/src/desktop/desktop-automation-lease.test.ts

@@ -35,7 +35,9 @@ function fixture() {
   const started = mock(async () => {});
   const released = mock(() => {});
   const releaseBrowser = mock(async () => {});
+  const notify = mock(async () => {});
   const lease = new DesktopAutomationLease({
+    notify,
     enabled: () => enabled,
     ready: () => ready,
     ensureReady,
@@ -50,6 +52,7 @@ function fixture() {
   cleanups.push(lease);
   return {
     lease,
+    notify,
     ensureReady,
     install,
     failSetup: () => setup.reject(new Error("download failed")),
@@ -128,6 +131,7 @@ test("cancellation stops running and queued browser commands without blocking a
   const callback = mock(operation);
   const queued = f.lease.runBrowser(context, callback);
   abort.abort();
+  expect(f.lease.isActive).toBe(false);
   expect(await running).toBeInstanceOf(Error);
   expect((await queued).isError).toBe(true);
   expect(callback).not.toHaveBeenCalled();
@@ -206,3 +210,142 @@ test("disabled, unidentified, cancelled and released browser calls cannot instal
   await expect(f.lease.runBrowser(context, operation)).rejects.toThrow();
   expect(f.ensureReady).not.toHaveBeenCalled();
 });
+
+test("activity follows the browser lease and clears before failed cleanup", async () => {
+  const f = fixture();
+  expect(f.lease.isActive).toBe(false);
+  await f.lease.runBrowser(context, operation);
+  expect(f.lease.isActive).toBe(true);
+  expect(f.notify).toHaveBeenCalledTimes(1);
+  await f.lease.runBrowser(context, operation);
+  expect(f.notify).toHaveBeenCalledTimes(1);
+  f.releaseBrowser.mockRejectedValueOnce(new Error("cleanup failed"));
+  await expect(f.lease.runBrowser(context, operation, true)).rejects.toThrow(
+    "cleanup failed",
+  );
+  expect(f.lease.isActive).toBe(false);
+  expect(f.notify).toHaveBeenCalledTimes(2);
+  await f.lease.runBrowser(context, operation, true);
+  expect(f.notify).toHaveBeenCalledTimes(2);
+});
+
+test("turn completion releases only its own desktop before cleanup finishes", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  f.lease.releaseForConversation("conv-456");
+  expect(f.lease.isActive).toBe(true);
+  expect(f.notify).toHaveBeenCalledTimes(1);
+
+  const cleanup = Promise.withResolvers<void>();
+  f.releaseBrowser.mockImplementationOnce(() => cleanup.promise);
+  f.lease.releaseForConversation(context.conversationId);
+  expect(f.lease.isActive).toBe(false);
+  expect(f.notify).toHaveBeenCalledTimes(2);
+  await Bun.sleep(0);
+  expect(f.released).not.toHaveBeenCalled();
+
+  const callback = mock(operation);
+  const next = f.lease.runBrowser(context, callback);
+  await Bun.sleep(0);
+  expect(callback).not.toHaveBeenCalled();
+  cleanup.resolve();
+  expect((await next).isError).toBe(false);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  expect(f.started).toHaveBeenCalledTimes(2);
+  expect(f.lease.isActive).toBe(true);
+});
+
+test("turn completion cancels running and queued desktop work", async () => {
+  const f = fixture();
+  const started = Promise.withResolvers<void>();
+  const running = f.lease
+    .runBrowser(context, async (signal) => {
+      started.resolve();
+      await new Promise<void>((_resolve, reject) => {
+        signal.addEventListener("abort", () => reject(new Error("aborted")), {
+          once: true,
+        });
+      });
+      return operation();
+    })
+    .catch((error: unknown) => error);
+  await started.promise;
+  const callback = mock(operation);
+  const queued = f.lease.runBrowser(context, callback);
+  f.lease.releaseForConversation(context.conversationId);
+  expect(f.lease.isActive).toBe(false);
+  expect(await running).toBeInstanceOf(Error);
+  expect((await queued).isError).toBe(true);
+  expect(callback).not.toHaveBeenCalled();
+  await f.lease.runBrowser(context, callback);
+  expect(callback).toHaveBeenCalledTimes(1);
+});
+
+test("turn handoff retries failed cleanup without another turn or restart", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  f.releaseBrowser.mockRejectedValueOnce(new Error("Chrome cleanup timed out"));
+  f.lease.releaseForConversation(context.conversationId);
+  expect(f.lease.isActive).toBe(false);
+  await Bun.sleep(0);
+  expect(f.released).not.toHaveBeenCalled();
+  await Bun.sleep(1_100);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  const nextContext = { ...context, conversationId: "conv-456" };
+  expect((await f.lease.runBrowser(nextContext, operation)).isError).toBe(
+    false,
+  );
+  await f.lease.runBrowser(nextContext, operation, true);
+});
+
+test("a delayed cleanup retry cannot release a replacement owner", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  f.releaseBrowser.mockRejectedValueOnce(new Error("Chrome cleanup timed out"));
+  f.lease.releaseForConversation(context.conversationId);
+  await f.lease.runBrowser(context, operation, true);
+  const nextContext = { ...context, conversationId: "conv-456" };
+  await f.lease.runBrowser(nextContext, operation);
+  await Bun.sleep(1_100);
+  expect(f.lease.isActive).toBe(true);
+  expect(f.released).toHaveBeenCalledTimes(1);
+  await f.lease.runBrowser(nextContext, operation, true);
+});
+
+test("cleanup retries preserve commands queued behind an explicit handoff", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  f.releaseBrowser.mockRejectedValueOnce(new Error("Chrome cleanup timed out"));
+  f.lease.releaseForConversation(context.conversationId);
+  await Bun.sleep(0);
+  const cleanup = Promise.withResolvers<void>();
+  f.releaseBrowser.mockImplementationOnce(() => cleanup.promise);
+  const detached = f.lease.runBrowser(context, operation, true);
+  await Bun.sleep(0);
+  const callback = mock(operation);
+  const next = f.lease.runBrowser(context, callback);
+  await Bun.sleep(1_100);
+  cleanup.resolve();
+  await detached;
+  expect((await next).isError).toBe(false);
+  expect(callback).toHaveBeenCalledTimes(1);
+  expect(f.lease.isActive).toBe(true);
+});
+
+test("turn completion cancels commands queued behind an in-progress detach", async () => {
+  const f = fixture();
+  await f.lease.runBrowser(context, operation);
+  const cleanup = Promise.withResolvers<void>();
+  f.releaseBrowser.mockImplementationOnce(() => cleanup.promise);
+  const detached = f.lease.runBrowser(context, operation, true);
+  await Bun.sleep(0);
+  const callback = mock(operation);
+  const queued = f.lease.runBrowser(context, callback);
+  f.lease.releaseForConversation(context.conversationId);
+  cleanup.resolve();
+  await detached;
+  expect((await queued).isError).toBe(true);
+  expect(callback).not.toHaveBeenCalled();
+  await f.lease.runBrowser(context, callback);
+  expect(callback).toHaveBeenCalledTimes(1);
+});

package/src/desktop/desktop-automation-lease.ts

@@ -1,4 +1,5 @@
 import { getConfig } from "../config/loader.js";
+import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import type { ToolContext, ToolExecutionResult } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
 import { desktopDependencyInstaller } from "./desktop-dependencies.js";
@@ -35,14 +36,29 @@ export class DesktopAutomationLease {
       ready: () => boolean;
       ensureReady: (signal: AbortSignal) => Promise<void>;
       manager: () => DesktopSessionManager;
+      notify: () => Promise<unknown>;
     } = {
       enabled: () => isVirtualDesktopEnabled(getConfig()),
       ready: () => desktopDependencyInstaller.getStatus().state === "ready",
       ensureReady: (signal) => desktopDependencyInstaller.ensureReady(signal),
       manager: getDesktopSessionManager,
+      notify: async () =>
+        broadcastMessage({ type: "desktop_activity_changed" }),
     },
   ) {}
 
+  get isActive(): boolean {
+    return this.owner !== null && !this.owner.abort.signal.aborted;
+  }
+
+  private notify(): void {
+    void this.deps
+      .notify()
+      .catch((err) =>
+        log.warn({ err }, "Desktop browser activity notification failed"),
+      );
+  }
+
   private exclusive<T>(run: () => Promise<T>): Promise<T> {
     const next = this.tail.then(run, run);
     this.tail = next.catch(() => {});
@@ -84,9 +100,25 @@ export class DesktopAutomationLease {
     }
     this.generation += 1;
     owner.abort.abort();
-    void this.exclusive(() => this.release()).catch((err) =>
-      log.warn({ err }, "Desktop browser session cleanup failed"),
-    );
+    this.releaseCancelledOwner(owner);
+  }
+
+  private releaseCancelledOwner(owner: Owner): void {
+    void this.exclusive(async () => {
+      if (this.owner === owner) {
+        await this.release();
+      }
+    }).catch((err) => {
+      log.warn({ err }, "Desktop browser session cleanup failed");
+      const retry = setTimeout(() => this.releaseCancelledOwner(owner), 1_000);
+      retry.unref?.();
+    });
+  }
+
+  releaseForConversation(conversationId: string): void {
+    if (this.owner?.conversationId === conversationId) {
+      this.cancel(this.owner);
+    }
   }
 
   private bindCancellation(owner: Owner, signal?: AbortSignal): void {
@@ -122,6 +154,10 @@ export class DesktopAutomationLease {
       throw new Error("The desktop is busy or shutting down");
     }
     this.owner = owner;
+    owner.abort.signal.addEventListener("abort", () => this.notify(), {
+      once: true,
+    });
+    this.notify();
     this.bindCancellation(owner, context.signal);
     const cancel = () => this.cancel(owner);
     this.watchdog = setInterval(() => {

package/src/messaging/provider-message-metadata.ts

@@ -30,9 +30,9 @@ import { CHANNEL_IDS } from "../channels/types.js";
  * The schema passes through what it does not name, so a provider carries its
  * own fields (Slack's file markers and timezone labels) on this same object
  * and validates them with its own schema. This is how `SourceMetadataSchema`
- * already carries `slackBotMentioned` and the email fields on the wire: one
- * object per row, no per-provider sub-envelope, and no second copy of
- * anything named here.
+ * carries `botMentioned` and the email fields on the wire: one object per
+ * row, no per-provider sub-envelope, and no second copy of anything named
+ * here.
  */
 
 const providerReactionMetadataSchema = z.object({

package/src/notifications/__tests__/copy-composer.test.ts

@@ -503,6 +503,76 @@ describe("composeFallbackCopy plugin schedule templates", () => {
   });
 });
 
+// ── activity.complete rendering ───────────────────────────────────────
+
+describe("activity.complete copy", () => {
+  function completeSignal(
+    contextPayload: Record<string, unknown>,
+  ): NotificationSignal {
+    return makeSignal({
+      sourceEventName: "activity.complete",
+      contextPayload,
+    });
+  }
+
+  test("a producer-authored title survives the fallback path", () => {
+    // The home feed reads the payload title first; the popup must say the
+    // same thing when the classifier was unreachable.
+    const copy = composeFallbackCopy(
+      completeSignal({
+        title: "Skill updated: Weekly Report Export",
+        summary: "Added the retry after an expired session.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Skill updated: Weekly Report Export");
+    expect(copy.vellum?.body).toBe("Added the retry after an expired session.");
+  });
+
+  test("the pass-through's requestedTitle is honored when no title is set", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        requestedTitle: "Nightly export finished",
+        summary: "Wrote 12 files to the reports folder.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe("Nightly export finished");
+  });
+
+  test("without an authored title the headline is the summary's first sentence", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        summary:
+          "Added the retry after an expired session. Dropped the login step.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe(
+      "Added the retry after an expired session.",
+    );
+  });
+
+  test("an authored title the normalizer rejects falls back to the derived one", () => {
+    const copy = composeFallbackCopy(
+      completeSignal({
+        title: "Skill\nupdated",
+        summary: "Added the retry after an expired session.",
+      }),
+      CHANNELS,
+    );
+    expect(copy.vellum?.title).toBe(
+      "Added the retry after an expired session.",
+    );
+  });
+
+  test("neither a title nor a summary still says something happened", () => {
+    const copy = composeFallbackCopy(completeSignal({}), CHANNELS);
+    expect(copy.vellum?.title).toBe("Activity complete");
+    expect(copy.vellum?.body).toBe("An activity has completed");
+  });
+});
+
 // ── deriveTitle ───────────────────────────────────────────────────────
 
 describe("deriveTitle", () => {

package/src/notifications/copy-composer.ts

@@ -346,14 +346,22 @@ const TEMPLATES: Partial<Record<NotificationSourceEventName, CopyTemplate>> = {
 
   // Titled by what was done rather than by the kind of event: the summary's
   // first sentence is the outcome ("Finished the fuel-system diagnostic app"),
-  // which is what a reader scanning the bell wants to see. A summary without
-  // one still gets a title that says something happened.
+  // which is what a reader scanning the bell wants to see. A producer that
+  // names its subject in the payload keeps that name here, read in the same
+  // order the home feed reads it, so the headline is the same whether or not
+  // the classifier ran. A summary with neither still gets a title that says
+  // something happened.
   "activity.complete": (payload) => {
     const summary = nonEmpty(
       typeof payload.summary === "string" ? payload.summary : undefined,
     );
+    const authored = normalizeTitle(
+      readPayloadString(payload, "title") ??
+        readPayloadString(payload, "requestedTitle") ??
+        "",
+    );
     return {
-      title: summary ? deriveTitle(summary) : "Activity complete",
+      title: authored || (summary ? deriveTitle(summary) : "Activity complete"),
       body: summary ?? "An activity has completed",
     };
   },

package/src/persistence/conversation-plugin-facade.ts

@@ -1,3 +1,4 @@
+import type { ToolDefinition } from "../providers/types.js";
 import type {
   AddMessageOptions,
   ConversationRow,
@@ -52,6 +53,18 @@ export async function getMessages(
   return fn(conversationId);
 }
 
+/**
+ * The tool definitions the conversation's most recent live turn sent to the
+ * provider, or `null` when none has been recorded.
+ */
+export async function getConversationToolSurface(
+  conversationId: string,
+): Promise<ToolDefinition[] | null> {
+  const { getConversationToolSurface: fn } =
+    await import("./conversation-tool-surface.js");
+  return fn(conversationId);
+}
+
 /** Whether the conversation currently has a turn in flight. */
 export async function isConversationProcessing(id: string): Promise<boolean> {
   const { isConversationProcessing: fn } =