@vellumai/assistant 0.10.3-dev.202606301846.839df2b → 0.10.3-dev.202606302045.155be34

package/openapi.yaml

@@ -17916,6 +17916,44 @@ paths:
                           additionalProperties: false
                         backgroundToolNotification:
                           type: boolean
+                        backgroundToolCompletion:
+                          type: object
+                          properties:
+                            id:
+                              type: string
+                            toolName:
+                              type: string
+                            conversationId:
+                              type: string
+                            command:
+                              type: string
+                            startedAt:
+                              type: number
+                            status:
+                              type: string
+                              enum:
+                                - completed
+                                - failed
+                                - cancelled
+                            exitCode:
+                              anyOf:
+                                - type: number
+                                - type: "null"
+                            output:
+                              type: string
+                            completedAt:
+                              type: number
+                          required:
+                            - id
+                            - toolName
+                            - conversationId
+                            - command
+                            - startedAt
+                            - status
+                            - exitCode
+                            - output
+                            - completedAt
+                          additionalProperties: false
                         slackMessage:
                           type: object
                           properties:
@@ -22630,7 +22668,7 @@ paths:
     post:
       operationId: schedules_post
       summary: Create schedule
-      description: Create a new recurring schedule. Currently restricted to mode='execute'.
+      description: Create a new recurring schedule (execute, script, or workflow mode).
       tags:
         - schedules
       requestBody:
@@ -22664,12 +22702,20 @@ paths:
                   description: Whether the schedule starts active (default true)
                 mode:
                   type: string
-                  description: "'execute' (default) or 'workflow' (flag-gated)"
+                  description: "'execute' (default), 'script', or 'workflow' (flag-gated)"
                 workflowName:
                   type: string
                   description: Saved workflow to trigger (required for workflow mode)
                 workflowArgs:
                   description: Args passed to the workflow run (workflow mode)
+                script:
+                  type: string
+                  description: Shell command run on each fire (required for script mode)
+                timeoutMs:
+                  anyOf:
+                    - type: number
+                    - type: "null"
+                  description: Script execution timeout override in ms (script mode)
                 inferenceProfile:
                   anyOf:
                     - type: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.3-dev.202606301846.839df2b",
+  "version": "0.10.3-dev.202606302045.155be34",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/anthropic-provider.test.ts

@@ -3245,11 +3245,14 @@ describe("AnthropicProvider — deprecated sampling params (temperature / top_p
     lastStreamParams = null;
   });
 
-  // opus-4-7 / opus-4-8 (and, conservatively, fable) reject `temperature`,
-  // `top_p`, and `top_k` with a 400; the provider must strip all three.
+  // opus-4-7 / opus-4-8 / sonnet-5 (and, conservatively, fable) reject
+  // `temperature`, `top_p`, and `top_k` with a 400; the provider must strip
+  // all three. The OpenRouter `anthropic/...` form delegates here too.
   for (const model of [
     "claude-opus-4-8",
     "claude-opus-4-7",
+    "claude-sonnet-5",
+    "anthropic/claude-sonnet-5",
     "claude-fable-5",
   ]) {
     test(`strips temperature, top_p, and top_k for ${model}`, async () => {

package/src/__tests__/background-shell-bash.test.ts

@@ -189,6 +189,10 @@ describe("bash tool background mode", () => {
     // Command stdout is fenced as untrusted output, not inlined in the hint.
     expect(wakeCall.untrustedOutput?.content).toContain("bg_output_12345");
     expect(wakeCall.untrustedOutput?.source).toBe("tool_result");
+    // Durable completion record stamped onto the persisted wake.
+    expect(wakeCall.backgroundToolCompletion?.id).toBe("bg-test1234");
+    expect(wakeCall.backgroundToolCompletion?.status).toBe("completed");
+    expect(wakeCall.backgroundToolCompletion?.exitCode).toBe(0);
   });
 
   test("failing background process delivers an error hint via wake", async () => {
@@ -210,6 +214,9 @@ describe("bash tool background mode", () => {
     expect(wakeCall.hint).toContain("bg-test1234");
     // The command fails with exit code 1, so the hint should reflect failure
     expect(wakeCall.hint).toContain("exit=1");
+    expect(wakeCall.backgroundToolCompletion?.id).toBe("bg-test1234");
+    expect(wakeCall.backgroundToolCompletion?.status).toBe("failed");
+    expect(wakeCall.backgroundToolCompletion?.exitCode).toBe(1);
   });
 
   test("cancelled background process wakes with the cancellation, not a completed result", async () => {
@@ -234,6 +241,8 @@ describe("bash tool background mode", () => {
     expect(wakeCall.hint).toContain("cancelled");
     expect(wakeCall.hint).not.toContain("completed");
     expect(wakeCall.untrustedOutput?.content).toContain("cancelled");
+    expect(wakeCall.backgroundToolCompletion?.id).toBe("bg-test1234");
+    expect(wakeCall.backgroundToolCompletion?.status).toBe("cancelled");
   });
 
   test("foreground mode still works when background is not set", async () => {

package/src/__tests__/background-shell-host-bash.test.ts

@@ -118,6 +118,7 @@ mock.module("../daemon/host-bash-proxy.js", () => ({
 // Import under test — MUST come after mock.module calls.
 // ---------------------------------------------------------------------------
 
+import type { CompletedBackgroundTool } from "../tools/background-tool-registry.js";
 import { hostShellTool } from "../tools/host-terminal/host-shell.js";
 import type { ToolContext, ToolExecutionResult } from "../tools/types.js";
 
@@ -258,6 +259,11 @@ describe("host_bash background mode — proxy path", () => {
       maxChars: 40_000,
     });
     expect(wakeCall.source).toBe("background-tool");
+    const completion =
+      wakeCall.backgroundToolCompletion as CompletedBackgroundTool;
+    expect(completion.id).toBe("bg-test-0001");
+    expect(completion.status).toBe("completed");
+    expect(completion.exitCode).toBeNull();
   });
 
   test("calls wakeAgentForOpportunity on proxy error result", async () => {
@@ -398,6 +404,11 @@ describe("host_bash background mode — direct execution path", () => {
     expect((wakeCall.untrustedOutput as { content: string }).content).toContain(
       "hello world",
     );
+    const completion =
+      wakeCall.backgroundToolCompletion as CompletedBackgroundTool;
+    expect(completion.id).toBe("bg-test-0001");
+    expect(completion.status).toBe("completed");
+    expect(completion.exitCode).toBe(0);
   });
 
   test("calls wakeAgentForOpportunity with error hint on non-zero exit", async () => {

package/src/__tests__/conversation-initial-prompt.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Tests for construction-time system-prompt resolution.
+ *
+ * A conversation's system prompt is built once at construction and frozen for
+ * every turn (the agent loop never re-resolves it), so the persona slot must
+ * resolve correctly here. With no construction-time identity the default-build
+ * path must warm the gateway guardian binding BEFORE building (else a cold cache
+ * pins `users/default.md`); a channel-routed conversation that already carries
+ * the requester's trust context must build with it so the requester's profile
+ * resolves instead of the guardian/default one.
+ *
+ * Dependency seams are injected so this exercises the sequencing without mocking
+ * the widely-imported guardian-delivery / system-prompt modules (those global
+ * module mocks leak across files in the shared-process test runner).
+ */
+import { describe, expect, test } from "bun:test";
+
+import {
+  resolveInitialSystemPrompt,
+  warmGuardianBindings,
+} from "../daemon/conversation-initial-prompt.js";
+import type { ConversationCreateOptions } from "../daemon/handlers/shared.js";
+import type { TrustContext } from "../daemon/trust-context.js";
+
+function spyDeps() {
+  const calls: string[] = [];
+  const builtWith: Array<TrustContext | undefined> = [];
+  return {
+    calls,
+    builtWith,
+    deps: {
+      warm: async () => {
+        calls.push("warm");
+      },
+      build: (trustContext: TrustContext | undefined) => {
+        calls.push("build");
+        builtWith.push(trustContext);
+        return "BUILD";
+      },
+    },
+  };
+}
+
+const REQUESTER_TRUST = {
+  sourceChannel: "slack",
+  trustClass: "trusted_contact",
+  requesterExternalUserId: "user-123",
+} as unknown as TrustContext;
+
+describe("warmGuardianBindings", () => {
+  test("warms both the vellum-channel key and the unfiltered fallback key", async () => {
+    const keys: string[] = [];
+    await warmGuardianBindings(async (input) => {
+      keys.push(input?.channelTypes?.join(",") ?? "ALL");
+      return null;
+    });
+    // Both keys the persona resolver reads — peekGuardianForChannel("vellum")
+    // and its peekAnyGuardian() fallback — must be warmed.
+    expect(keys.sort()).toEqual(["ALL", "vellum"]);
+  });
+});
+
+describe("resolveInitialSystemPrompt", () => {
+  test("no construction-time identity: warms the guardian binding, then builds with no trust context", async () => {
+    const { calls, builtWith, deps } = spyDeps();
+    const result = await resolveInitialSystemPrompt(undefined, deps);
+
+    expect(result).toBe("BUILD");
+    // The warm MUST precede the build so the persona slot resolves the
+    // guardian's users/<slug>.md instead of users/default.md on a cold cache.
+    expect(calls).toEqual(["warm", "build"]);
+    expect(builtWith).toEqual([undefined]);
+  });
+
+  test("channel-routed: threads the requester trust context and skips the guardian warm", async () => {
+    const { calls, builtWith, deps } = spyDeps();
+    const result = await resolveInitialSystemPrompt(
+      { trustContext: REQUESTER_TRUST } as ConversationCreateOptions,
+      deps,
+    );
+
+    expect(result).toBe("BUILD");
+    // The requester's identity resolves the persona via a DB lookup, so no
+    // guardian-cache warm is needed and the trust context must reach the build.
+    expect(calls).toEqual(["build"]);
+    expect(builtWith).toEqual([REQUESTER_TRUST]);
+  });
+
+  test("an explicit override is used verbatim and skips the warm and build", async () => {
+    const { calls, deps } = spyDeps();
+    const result = await resolveInitialSystemPrompt(
+      { systemPromptOverride: "CUSTOM PROMPT" } as ConversationCreateOptions,
+      deps,
+    );
+
+    expect(result).toBe("CUSTOM PROMPT");
+    expect(calls).toEqual([]);
+  });
+
+  test("an explicit empty-string override is honored verbatim (not treated as absent)", async () => {
+    const { calls, deps } = spyDeps();
+    const result = await resolveInitialSystemPrompt(
+      { systemPromptOverride: "" } as ConversationCreateOptions,
+      deps,
+    );
+
+    expect(result).toBe("");
+    expect(calls).toEqual([]);
+  });
+});

package/src/__tests__/conversation-loop-db-lock-resilience.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Regression tests for SQLite write-contention resilience in the agent loop.
+ *
+ * When another writer holds the SQLite write lock long enough that
+ * `busy_timeout` elapses, an in-loop content write throws `SQLITE_BUSY`
+ * ("database is locked"). The turn-finalizing write at `message_complete` is on
+ * `dispatchAgentEvent`'s re-throw allowlist, so before this resilience layer a
+ * single transient lock aborted the whole turn and surfaced to the user as
+ * "Processing failed: database is locked".
+ *
+ * These tests pin the two guarantees:
+ *  1. A transient `SQLITE_BUSY` is retried and the row is finalized normally.
+ *  2. A persistent `SQLITE_BUSY` is swallowed (logged) so the turn continues
+ *     instead of throwing — a later write (this turn or the next) overwrites
+ *     the dropped content.
+ */
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ── Mock platform (must precede imports that read it) ─────────────────────────
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({ memory: {} }),
+  loadConfig: () => ({}),
+}));
+
+// `updateMessageContent` throws `SQLITE_BUSY` for the first
+// `updateContentFailuresRemaining` calls, then records the content written.
+let updateContentFailuresRemaining = 0;
+const writtenContentById = new Map<string, string>();
+const updateMessageContentMock = mock((id: string, content: string) => {
+  if (updateContentFailuresRemaining > 0) {
+    updateContentFailuresRemaining -= 1;
+    throw Object.assign(new Error("database is locked"), {
+      code: "SQLITE_BUSY",
+    });
+  }
+  writtenContentById.set(id, content);
+});
+
+// Stand-in for the `conversations.seq` column, mirroring the monotonic,
+// ignore-non-positive semantics of the real `recordConversationPersistedSeq`.
+const persistedSeqByConversation = new Map<string, number>();
+
+mock.module("../persistence/conversation-crud.js", () => ({
+  setConversationProcessingStartedAt: () => {},
+  isConversationProcessing: () => false,
+  getConversation: () => null,
+  getMessageById: () => null,
+  updateMessageContent: updateMessageContentMock,
+  provenanceFromTrustContext: () => ({}),
+  reserveMessage: async (_conversationId: string, role: string) => ({
+    id: role === "user" ? "tool-result-row" : "assistant-row",
+  }),
+  recordConversationPersistedSeq: (id: string, seq: number) => {
+    if (!Number.isFinite(seq) || seq <= 0) return;
+    const prev = persistedSeqByConversation.get(id);
+    if (prev == null || prev < seq) persistedSeqByConversation.set(id, seq);
+  },
+  getConversationPersistedSeq: (id: string) =>
+    persistedSeqByConversation.get(id) ?? null,
+}));
+
+mock.module("../persistence/conversation-disk-view.js", () => ({
+  syncMessageToDisk: () => {},
+}));
+
+mock.module("../persistence/llm-request-log-store.js", () => ({
+  recordRequestLog: () => {},
+  backfillMessageIdOnLogs: () => {},
+}));
+
+mock.module("../plugins/defaults/memory/memory-recall-log-store.js", () => ({
+  backfillMemoryRecallLogMessageId: () => {},
+}));
+
+mock.module(
+  "../plugins/defaults/memory/memory-v2-activation-log-store.js",
+  () => ({
+    backfillMemoryV2ActivationMessageId: () => {},
+  }),
+);
+
+// ── Imports (after mocks) ─────────────────────────────────────────────────────
+import type { AgentEvent } from "../agent/loop.js";
+import type {
+  EventHandlerDeps,
+  EventHandlerState,
+} from "../daemon/conversation-agent-loop-handlers.js";
+import {
+  createEventHandlerState,
+  handleMessageComplete,
+} from "../daemon/conversation-agent-loop-handlers.js";
+import type { ServerMessage } from "../daemon/message-protocol.js";
+import { getConversationPersistedSeq } from "../persistence/conversation-crud.js";
+
+const CONVERSATION_ID = "test-session-id";
+
+function createMockDeps(): EventHandlerDeps {
+  return {
+    ctx: {
+      conversationId: CONVERSATION_ID,
+      provider: { name: "anthropic" },
+      traceEmitter: { emit: () => {} },
+      streamThinking: false,
+      emitActivityState: () => {},
+      markWorkspaceTopLevelDirty: () => {},
+      currentTurnSurfaces: [],
+    } as unknown as EventHandlerDeps["ctx"],
+    onEvent: (_msg: ServerMessage) => {},
+    reqId: "test-req-id",
+    isFirstMessage: false,
+    shouldGenerateTitle: false,
+    rlog: new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }) as unknown as EventHandlerDeps["rlog"],
+    turnChannelContext: {
+      userMessageChannel: "vellum",
+      assistantMessageChannel: "vellum",
+    } as EventHandlerDeps["turnChannelContext"],
+    turnInterfaceContext: {
+      userMessageInterface: "macos",
+      assistantMessageInterface: "macos",
+    } as EventHandlerDeps["turnInterfaceContext"],
+  } as EventHandlerDeps;
+}
+
+const MESSAGE_COMPLETE_EVENT = {
+  type: "message_complete",
+  message: { role: "assistant", content: [{ type: "text", text: "done" }] },
+} as Extract<AgentEvent, { type: "message_complete" }>;
+
+describe("agent loop SQLite write-contention resilience", () => {
+  let state: EventHandlerState;
+
+  beforeEach(() => {
+    state = createEventHandlerState();
+    // A row was reserved at llm_call_started; message_complete finalizes it.
+    state.lastAssistantMessageId = "assistant-row";
+    state.assistantRowAwaitingFinalization = true;
+    state.lastPersistedContentSeq = 5;
+    updateContentFailuresRemaining = 0;
+    writtenContentById.clear();
+    persistedSeqByConversation.clear();
+    updateMessageContentMock.mockClear();
+  });
+
+  test("retries a transient SQLITE_BUSY and finalizes the assistant row", async () => {
+    // GIVEN the finalize write loses the write-lock race twice before winning
+    updateContentFailuresRemaining = 2;
+
+    // WHEN message_complete drains
+    await handleMessageComplete(
+      state,
+      createMockDeps(),
+      MESSAGE_COMPLETE_EVENT,
+    );
+
+    // THEN it retried until the write committed (2 failures + 1 success) ...
+    expect(updateMessageContentMock).toHaveBeenCalledTimes(3);
+    expect(writtenContentById.get("assistant-row")).toContain("done");
+    // ... the finalization completed ...
+    expect(state.assistantRowAwaitingFinalization).toBe(false);
+    // ... and the persisted seq advanced because the content is durable.
+    expect(getConversationPersistedSeq(CONVERSATION_ID)).toBe(5);
+  });
+
+  test("swallows a persistent SQLITE_BUSY without aborting the turn", async () => {
+    // GIVEN every finalize attempt loses the race (lock held past every retry)
+    updateContentFailuresRemaining = Number.POSITIVE_INFINITY;
+
+    // WHEN message_complete drains, it must resolve rather than throw — a thrown
+    // SQLITE_BUSY here is on dispatchAgentEvent's re-throw allowlist and would
+    // kill the turn.
+    await expect(
+      handleMessageComplete(state, createMockDeps(), MESSAGE_COMPLETE_EVENT),
+    ).resolves.toBeUndefined();
+
+    // THEN the write was attempted (initial try + the retries) ...
+    expect(updateMessageContentMock.mock.calls.length).toBeGreaterThan(1);
+    // ... no content landed ...
+    expect(writtenContentById.has("assistant-row")).toBe(false);
+    // ... and the seq was NOT advanced past content that never became durable.
+    expect(getConversationPersistedSeq(CONVERSATION_ID)).toBeNull();
+  });
+});

package/src/__tests__/list-messages-background-tool-completion.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Tests for handleListMessages background-tool completion projection.
+ *
+ * A backgrounded bash/host_bash run posts a `<background_event
+ * source="background-tool">` wake on completion, stamped with
+ * `metadata.backgroundToolCompletion`. The history projection must surface
+ * that structured record (and the `backgroundToolNotification` flag) so the
+ * web can rebuild a terminal inline card after a daemon restart.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+mock.module("../config/loader.js", () => ({
+  getConfig: () => ({
+    ui: {},
+    model: "test",
+    provider: "test",
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0 },
+  }),
+}));
+
+import { ConversationMessageSchema } from "../api/responses/conversation-message.js";
+import {
+  addMessage,
+  createConversation,
+} from "../persistence/conversation-crud.js";
+import { getDb } from "../persistence/db-connection.js";
+import { initializeDb } from "../persistence/db-init.js";
+import { handleListMessages } from "../runtime/routes/conversation-routes.js";
+
+await initializeDb();
+
+function resetTables() {
+  const db = getDb();
+  db.run("DELETE FROM message_attachments");
+  db.run("DELETE FROM attachments");
+  db.run("DELETE FROM messages");
+  db.run("DELETE FROM conversations");
+}
+
+interface ProjectedMessage {
+  role: string;
+  backgroundToolNotification?: boolean;
+  backgroundToolCompletion?: Record<string, unknown>;
+}
+
+describe("handleListMessages background-tool completion projection", () => {
+  beforeEach(resetTables);
+
+  test("projects backgroundToolCompletion from the wake row metadata", async () => {
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([{ type: "text", text: "run a long command" }]),
+    );
+
+    const completion = {
+      id: "bg-1",
+      toolName: "bash",
+      conversationId: conv.id,
+      command: "sleep 5 && echo done",
+      startedAt: 1000,
+      status: "completed" as const,
+      exitCode: 0,
+      output: "done\n",
+      completedAt: 2000,
+    };
+    // Mirror persistWakeTriggerMessage: a user-role
+    // `<background_event source="background-tool">` row carrying the structured
+    // completion. Not flagged `hidden`; the client suppresses it from the
+    // transcript via `backgroundToolNotification`.
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([
+        {
+          type: "text",
+          text: '<background_event source="background-tool">Background command completed (id=bg-1, exit=0):</background_event>',
+        },
+      ]),
+      {
+        metadata: {
+          kind: "background-event",
+          backgroundEventSource: "background-tool",
+          automated: true,
+          backgroundToolCompletion: completion,
+        },
+      },
+    );
+
+    const response = handleListMessages({
+      queryParams: { conversationId: conv.id },
+    }) as { messages: ProjectedMessage[] };
+
+    // Every projected message validates against the wire schema.
+    for (const message of response.messages) {
+      expect(() => ConversationMessageSchema.parse(message)).not.toThrow();
+    }
+
+    const wakeRow = response.messages.find(
+      (m) => m.backgroundToolCompletion !== undefined,
+    );
+    expect(wakeRow).toBeDefined();
+    expect(wakeRow?.backgroundToolNotification).toBe(true);
+    expect(wakeRow?.backgroundToolCompletion).toEqual(completion);
+  });
+
+  test("omits backgroundToolCompletion when the row carries no completion metadata", async () => {
+    const conv = createConversation();
+    await addMessage(
+      conv.id,
+      "user",
+      JSON.stringify([{ type: "text", text: "hello" }]),
+    );
+    await addMessage(
+      conv.id,
+      "assistant",
+      JSON.stringify([{ type: "text", text: "hi there" }]),
+    );
+
+    const response = handleListMessages({
+      queryParams: { conversationId: conv.id },
+    }) as { messages: ProjectedMessage[] };
+
+    expect(response.messages).toHaveLength(2);
+    for (const message of response.messages) {
+      expect(message.backgroundToolCompletion).toBeUndefined();
+      expect(message.backgroundToolNotification).toBeUndefined();
+      expect(() => ConversationMessageSchema.parse(message)).not.toThrow();
+    }
+  });
+});

package/src/__tests__/schedule-routes.test.ts

@@ -1241,7 +1241,7 @@ describe("POST /schedules — create", () => {
     expect(job.description).toBe("Description fallback");
   });
 
-  test("rejects modes other than execute/workflow", async () => {
+  test("rejects modes other than execute/workflow/script", async () => {
     await expect(
       postCreate({
         name: "x",
@@ -1250,7 +1250,9 @@ describe("POST /schedules — create", () => {
         message: "hi",
         mode: "notify",
       }),
-    ).rejects.toThrow("Only 'execute' and 'workflow' modes are supported");
+    ).rejects.toThrow(
+      "Only 'execute', 'script', and 'workflow' modes are supported",
+    );
   });
 
   test("rejects an unparseable expression", async () => {

package/src/api/index.ts

@@ -404,6 +404,7 @@ export {
   DictationRequestSchema,
 } from "./requests/dictation.js";
 export {
+  type BackgroundToolCompletion,
   type ConversationAttachmentBlock,
   ConversationAttachmentBlockSchema,
   type ConversationContentBlock,

package/src/api/responses/conversation-message.ts

@@ -296,6 +296,29 @@ export type ConversationAcpNotification = z.infer<
   typeof ConversationAcpNotificationSchema
 >;
 
+// ---------------------------------------------------------------------------
+// Background-tool completion
+// ---------------------------------------------------------------------------
+
+/** Structured terminal record of a backgrounded bash/host_bash run, carrying
+ *  everything a web `BackgroundTaskEntry` needs to rebuild a completed inline
+ *  card from history. Mirrors the `background_tool_completed` SSE event plus
+ *  the registry fields (`toolName`, `command`, `startedAt`). */
+export const BackgroundToolCompletionSchema = z.object({
+  id: z.string(),
+  toolName: z.string(),
+  conversationId: z.string(),
+  command: z.string(),
+  startedAt: z.number(),
+  status: z.enum(["completed", "failed", "cancelled"]),
+  exitCode: z.number().nullable(),
+  output: z.string(),
+  completedAt: z.number(),
+});
+export type BackgroundToolCompletion = z.infer<
+  typeof BackgroundToolCompletionSchema
+>;
+
 // ---------------------------------------------------------------------------
 // Slack message envelope
 // ---------------------------------------------------------------------------
@@ -549,6 +572,12 @@ export const ConversationMessageSchema = z.object({
    *  notifications, the row stays in state (the LLM reads it) but is filtered
    *  from the rendered transcript — the inline card carries the status. */
   backgroundToolNotification: z.boolean().optional(),
+  /** Structured completion of a backgrounded bash/host_bash run, stamped on the
+   *  same persisted background-event wake row as `backgroundToolNotification`.
+   *  Lets the web reconstruct a terminal inline card after a daemon restart
+   *  (the in-memory completed ring does not survive restarts). `id` equals the
+   *  spawning tool call's `{backgrounded,id}` id. */
+  backgroundToolCompletion: BackgroundToolCompletionSchema.optional(),
   slackMessage: ConversationSlackMessageSchema.optional(),
   /**
    * Queue state for a user message that is still waiting in the daemon's