@vellumai/assistant 0.10.12 → 0.11.0-staging.1

package/src/persistence/migrations/351-schedule-skill-script-handoff.ts

@@ -0,0 +1,39 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Add the script-handoff and skill-binding columns to `cron_jobs`.
+ *
+ * - `then_execute` — when set on a script-mode schedule, the firing hands the
+ *   script's stdout to an agent turn instead of only recording it on the run
+ *   row. Defaults to 0 so every pre-existing script schedule keeps its
+ *   no-LLM behaviour.
+ * - `skill_id` — the managed skill whose `scripts/` the command invokes. NULL
+ *   (all pre-existing rows) means the schedule is not bound to a skill.
+ * - `skill_version_hash` — the skill's content hash at creation time,
+ *   re-checked before each firing so a rewritten script cannot keep running
+ *   under the original approval.
+ *
+ * Idempotent — the PRAGMA guard makes re-running a no-op once the columns
+ * exist.
+ */
+export function migrateScheduleSkillScriptHandoff(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+
+  const columns = raw.query(`PRAGMA table_info(cron_jobs)`).all() as Array<{
+    name: string;
+  }>;
+  const columnNames = new Set(columns.map((c) => c.name));
+
+  if (!columnNames.has("then_execute")) {
+    raw.exec(
+      `ALTER TABLE cron_jobs ADD COLUMN then_execute INTEGER NOT NULL DEFAULT 0`,
+    );
+  }
+  if (!columnNames.has("skill_id")) {
+    raw.exec(`ALTER TABLE cron_jobs ADD COLUMN skill_id TEXT`);
+  }
+  if (!columnNames.has("skill_version_hash")) {
+    raw.exec(`ALTER TABLE cron_jobs ADD COLUMN skill_version_hash TEXT`);
+  }
+}

package/src/persistence/migrations/352-drop-schedule-skill-script-handoff.test.ts

@@ -0,0 +1,83 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import * as schema from "../schema.js";
+import { migrateScheduleSkillScriptHandoff } from "./351-schedule-skill-script-handoff.js";
+import { migrateDropScheduleSkillScriptHandoff } from "./352-drop-schedule-skill-script-handoff.js";
+
+/** Minimal `cron_jobs`, trimmed to what these two migrations touch. */
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec(/*sql*/ `
+    CREATE TABLE cron_jobs (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      message TEXT NOT NULL,
+      next_run_at INTEGER NOT NULL,
+      created_by TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  return { sqlite, db: drizzle(sqlite, { schema }) };
+}
+
+function columnNames(sqlite: Database): string[] {
+  return (
+    sqlite.query("PRAGMA table_info(cron_jobs)").all() as Array<{
+      name: string;
+    }>
+  ).map((c) => c.name);
+}
+
+const REVERTED = ["then_execute", "skill_id", "skill_version_hash"];
+
+describe("migration 352 — drop reverted schedule columns", () => {
+  test("removes the columns 351 added", () => {
+    const { sqlite, db } = createTestDb();
+
+    migrateScheduleSkillScriptHandoff(db);
+    for (const column of REVERTED) {
+      expect(columnNames(sqlite)).toContain(column);
+    }
+
+    migrateDropScheduleSkillScriptHandoff(db);
+    for (const column of REVERTED) {
+      expect(columnNames(sqlite)).not.toContain(column);
+    }
+  });
+
+  test("leaves the surrounding columns intact", () => {
+    const { sqlite, db } = createTestDb();
+    const before = columnNames(sqlite);
+
+    migrateScheduleSkillScriptHandoff(db);
+    migrateDropScheduleSkillScriptHandoff(db);
+
+    // 351 + 352 net to nothing: the pair exists only so the already-recorded
+    // 351 can stay in the ledger.
+    expect(columnNames(sqlite)).toEqual(before);
+  });
+
+  test("is a no-op on a database that never ran 351", () => {
+    const { sqlite, db } = createTestDb();
+    const before = columnNames(sqlite);
+
+    expect(() => migrateDropScheduleSkillScriptHandoff(db)).not.toThrow();
+    expect(columnNames(sqlite)).toEqual(before);
+  });
+
+  test("is idempotent when re-run after a partial application", () => {
+    const { sqlite, db } = createTestDb();
+    migrateScheduleSkillScriptHandoff(db);
+    // Simulate a crash between column drops.
+    sqlite.exec("ALTER TABLE cron_jobs DROP COLUMN skill_id");
+
+    expect(() => migrateDropScheduleSkillScriptHandoff(db)).not.toThrow();
+    for (const column of REVERTED) {
+      expect(columnNames(sqlite)).not.toContain(column);
+    }
+  });
+});

package/src/persistence/migrations/352-drop-schedule-skill-script-handoff.ts

@@ -0,0 +1,36 @@
+import { getLogger } from "../../util/logger.js";
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+
+const log = getLogger("migration-352");
+
+/**
+ * Drops the script-handoff and skill-binding columns from `cron_jobs`.
+ *
+ * Migration 351 added `then_execute`, `skill_id`, and `skill_version_hash` for
+ * a feature that has since been reverted. 351 is deliberately left in place:
+ * it has already run on deployed assistants, and removing a migration the
+ * ledger has recorded would break migration-state validation. So the pair
+ * nets to nothing — 351 adds the columns, this drops them again.
+ *
+ * No data is carried over. The feature never shipped to users, so no schedule
+ * has meaningful values in these columns.
+ *
+ * Idempotent: each column is checked before it is dropped, so re-running after
+ * a partial application is a no-op.
+ */
+export function migrateDropScheduleSkillScriptHandoff(
+  database: DrizzleDb,
+): void {
+  const raw = getSqliteFrom(database);
+
+  const columns = raw.query(`PRAGMA table_info(cron_jobs)`).all() as Array<{
+    name: string;
+  }>;
+  const columnNames = new Set(columns.map((c) => c.name));
+
+  for (const column of ["then_execute", "skill_id", "skill_version_hash"]) {
+    if (!columnNames.has(column)) continue;
+    raw.exec(`ALTER TABLE cron_jobs DROP COLUMN ${column}`);
+    log.info({ column }, "Dropped reverted schedule column from cron_jobs");
+  }
+}

package/src/persistence/migrations/353-add-llm-usage-conversation-type.test.ts

@@ -0,0 +1,110 @@
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import * as schema from "../schema.js";
+import { migrateAddLlmUsageConversationType } from "./353-add-llm-usage-conversation-type.js";
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  // Pre-353 shape: only the columns the migration and tests touch.
+  sqlite.exec(/*sql*/ `
+    CREATE TABLE conversations (
+      id TEXT PRIMARY KEY,
+      conversation_type TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE TABLE llm_usage_events (
+      id TEXT PRIMARY KEY,
+      created_at INTEGER NOT NULL,
+      conversation_id TEXT,
+      provider TEXT NOT NULL,
+      model TEXT NOT NULL,
+      input_tokens INTEGER NOT NULL,
+      output_tokens INTEGER NOT NULL,
+      pricing_status TEXT NOT NULL
+    );
+  `);
+  return { sqlite, db: drizzle(sqlite, { schema }) };
+}
+
+function insertConversation(
+  sqlite: Database,
+  id: string,
+  conversationType: string,
+): void {
+  sqlite.run(
+    `INSERT INTO conversations (id, conversation_type, created_at, updated_at) VALUES (?, ?, 1000, 1000)`,
+    [id, conversationType],
+  );
+}
+
+function insertUsageEvent(
+  sqlite: Database,
+  id: string,
+  conversationId: string | null,
+): void {
+  sqlite.run(
+    `INSERT INTO llm_usage_events (id, created_at, conversation_id, provider, model, input_tokens, output_tokens, pricing_status)
+     VALUES (?, 1000, ?, 'anthropic', 'test-model', 1, 1, 'priced')`,
+    [id, conversationId],
+  );
+}
+
+function typeOf(sqlite: Database, eventId: string): unknown {
+  const row = sqlite
+    .query("SELECT conversation_type FROM llm_usage_events WHERE id = ?")
+    .get(eventId) as { conversation_type: unknown };
+  return row.conversation_type;
+}
+
+describe("migration 353: llm_usage_events.conversation_type", () => {
+  test("adds the nullable column", () => {
+    const { sqlite, db } = createTestDb();
+    migrateAddLlmUsageConversationType(db);
+
+    const columns = (
+      sqlite.query("PRAGMA table_info(llm_usage_events)").all() as Array<{
+        name: string;
+        notnull: number;
+      }>
+    ).filter((c) => c.name === "conversation_type");
+    expect(columns).toHaveLength(1);
+    expect(columns[0].notnull).toBe(0);
+  });
+
+  test("backfills existing rows from surviving parent conversations", () => {
+    const { sqlite, db } = createTestDb();
+    insertConversation(sqlite, "conv-bg", "background");
+    insertUsageEvent(sqlite, "evt-live-parent", "conv-bg");
+    // Parent already deleted before the upgrade — unrecoverable, stays NULL.
+    insertUsageEvent(sqlite, "evt-gone-parent", "conv-gone");
+    insertUsageEvent(sqlite, "evt-no-parent", null);
+
+    migrateAddLlmUsageConversationType(db);
+
+    expect(typeOf(sqlite, "evt-live-parent")).toBe("background");
+    expect(typeOf(sqlite, "evt-gone-parent")).toBeNull();
+    expect(typeOf(sqlite, "evt-no-parent")).toBeNull();
+  });
+
+  test("re-run never overwrites existing stamps", () => {
+    const { sqlite, db } = createTestDb();
+    insertConversation(sqlite, "conv-std", "standard");
+    insertUsageEvent(sqlite, "evt-1", "conv-std");
+
+    migrateAddLlmUsageConversationType(db);
+    expect(typeOf(sqlite, "evt-1")).toBe("standard");
+
+    // Simulate the parent's type having been recorded differently than the
+    // row now joined (the stamp is the record-time truth): a re-run must
+    // fill only NULLs and leave existing values alone.
+    sqlite.run(
+      `UPDATE llm_usage_events SET conversation_type = 'background' WHERE id = 'evt-1'`,
+    );
+    migrateAddLlmUsageConversationType(db);
+    expect(typeOf(sqlite, "evt-1")).toBe("background");
+  });
+});

package/src/persistence/migrations/353-add-llm-usage-conversation-type.ts

@@ -0,0 +1,49 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+
+const COLUMN_NAME = "conversation_type";
+const COLUMN_DEFINITION = "conversation_type TEXT";
+
+/**
+ * Add `conversation_type` column to the `llm_usage_events` table and
+ * backfill it from `conversations` for existing rows.
+ *
+ * The column captures the parent conversation's `conversation_type`
+ * (`"standard"` / `"background"` / `"scheduled"`) at the moment the usage
+ * event is RECORDED. The telemetry reporter previously derived the type
+ * exclusively via a flush-time LEFT JOIN to `conversations`, but usage rows
+ * outlive conversation rows — memory-retrospective forks are GC'd once a
+ * newer run supersedes them (or deleted immediately on wake failure), and
+ * users can delete conversations — so any row flushed after its parent
+ * conversation's deletion reported a null `conversation_type` despite
+ * carrying a `conversation_id`.
+ *
+ * The backfill stamps every existing row whose parent conversation still
+ * exists, so usage rows pending flush at upgrade time (delayed or offline
+ * telemetry) keep their type even if the parent conversation is deleted
+ * before the next successful flush. Rows whose parents are already gone
+ * stay NULL — their type is unrecoverable. The telemetry read path
+ * (`queryUnreportedUsageEvents`) COALESCEs the stored value with the JOIN
+ * as a final fallback.
+ *
+ * Idempotent: the ALTER is guarded with `tableHasColumn` so a crash between
+ * the `ALTER TABLE` and the checkpoint write doesn't cause a
+ * duplicate-column error on the next boot, and the backfill only fills NULL
+ * values so a re-run never overwrites record-time stamps.
+ */
+export function migrateAddLlmUsageConversationType(database: DrizzleDb): void {
+  if (!tableHasColumn(database, "llm_usage_events", COLUMN_NAME)) {
+    database.run(
+      `ALTER TABLE llm_usage_events ADD COLUMN ${COLUMN_DEFINITION}`,
+    );
+  }
+  database.run(
+    `UPDATE llm_usage_events
+     SET conversation_type = (
+       SELECT c.conversation_type FROM conversations AS c
+       WHERE c.id = llm_usage_events.conversation_id
+     )
+     WHERE conversation_id IS NOT NULL
+       AND conversation_type IS NULL`,
+  );
+}

package/src/persistence/schema/infrastructure.ts

@@ -275,6 +275,17 @@ export const llmUsageEvents = sqliteTable(
      * persisted before migration 267 ran.
      */
     assistantVersion: text("assistant_version"),
+    /**
+     * `conversations.conversation_type` of the parent conversation
+     * (`"standard"` / `"background"` / `"scheduled"`), captured at RECORD
+     * time. The parent conversation can be deleted before the telemetry
+     * flush joins against it (memory-retrospective forks are GC'd once
+     * superseded; users delete conversations), so a flush-time JOIN alone
+     * under-labels usage rows. Null when the call has no parent
+     * conversation and for rows persisted before migration 353 ran (the
+     * telemetry read path falls back to the JOIN for those).
+     */
+    conversationType: text("conversation_type"),
   },
   (table) => [
     index("idx_llm_usage_events_conversation_id").on(table.conversationId),

package/src/persistence/steps.ts

@@ -9,7 +9,7 @@
 
 import { backfillAppConversationIds } from "../apps/app-store.js";
 // Forward migration + down function imports
-import { migrateToolCreatedItems } from "../plugins/defaults/memory/graph/bootstrap.js";
+import { migrateToolCreatedItems } from "../plugins/defaults/memory/v1/graph/bootstrap.js";
 import { migrateCoreTables } from "./migrations/000-core-tables.js";
 import {
   downJobDeferrals,
@@ -458,6 +458,9 @@ import { migrateDeleteStrayGreetingConversation } from "./migrations/347-delete-
 import { migrateMemorySummariesScopeUpdatedIndex } from "./migrations/348-memory-summaries-scope-updated-index.js";
 import { migrateMoveMemoryGraphTablesToMemoryDb } from "./migrations/349-move-memory-graph-tables-to-memory-db.js";
 import { migrateConversationsTotalInputTokensNullable } from "./migrations/350-conversations-total-input-tokens-nullable.js";
+import { migrateScheduleSkillScriptHandoff } from "./migrations/351-schedule-skill-script-handoff.js";
+import { migrateDropScheduleSkillScriptHandoff } from "./migrations/352-drop-schedule-skill-script-handoff.js";
+import { migrateAddLlmUsageConversationType } from "./migrations/353-add-llm-usage-conversation-type.js";
 import type { MigrationStep } from "./migrations/run-migrations.js";
 
 export const migrationSteps: MigrationStep[] = [
@@ -1473,4 +1476,7 @@ export const migrationSteps: MigrationStep[] = [
     ],
   },
   migrateConversationsTotalInputTokensNullable,
+  migrateScheduleSkillScriptHandoff,
+  migrateDropScheduleSkillScriptHandoff,
+  migrateAddLlmUsageConversationType,
 ];

package/src/plugin-api/__tests__/publish-event-forwarding.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Tests the daemon-vs-side-process routing in the event-hub facade (exercised
+ * through {@link publishEvent}).
+ *
+ * In the daemon the event publishes on the local hub; in a side process (where
+ * seq stamping is disabled) the local hub reaches no SSE subscriber, so the
+ * event is forwarded to the daemon over IPC instead. The `host_*` guard must
+ * run before either path. The process-role signal and the IPC forward are
+ * mocked so the test controls the branch without spawning a subprocess.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { AssistantEventEnvelope } from "../../api/index.js";
+
+let sideProcess = false;
+const forwardCalls: Array<{
+  event: AssistantEventEnvelope;
+  options: unknown;
+}> = [];
+
+mock.module("../../runtime/process-role.js", () => ({
+  isMainDaemonProcess: () => !sideProcess,
+  markCurrentProcessAsMainDaemon: () => {},
+}));
+
+mock.module("../../ipc/events-publish-client.js", () => ({
+  EVENTS_PUBLISH_IPC_METHOD: "/events/publish",
+  forwardEventPublishToDaemon: async (
+    event: AssistantEventEnvelope,
+    options: unknown,
+  ) => {
+    forwardCalls.push({ event, options });
+  },
+}));
+
+const { assistantEventHub } =
+  await import("../../runtime/assistant-event-hub.js");
+const { publishEvent } = await import("../publish-event.js");
+
+function syncEvent(): AssistantEventEnvelope {
+  return {
+    id: "evt-1",
+    conversationId: "conv-1",
+    emittedAt: "2026-01-01T00:00:00.000Z",
+    message: {
+      type: "sync_changed",
+      tags: ["my-app:items"],
+    } as unknown as AssistantEventEnvelope["message"],
+  };
+}
+
+function collectLocalDeliveries(): {
+  received: AssistantEventEnvelope[];
+  dispose: () => void;
+} {
+  const received: AssistantEventEnvelope[] = [];
+  const sub = assistantEventHub.subscribe({
+    type: "process",
+    callback: (event) => {
+      received.push(event);
+    },
+  });
+  return { received, dispose: () => sub.dispose() };
+}
+
+beforeEach(() => {
+  sideProcess = false;
+  forwardCalls.length = 0;
+});
+
+describe("publishEvent — daemon vs side-process routing", () => {
+  test("in the daemon, publishes on the local hub (no IPC forward)", async () => {
+    sideProcess = false;
+    const local = collectLocalDeliveries();
+    try {
+      await publishEvent(syncEvent());
+    } finally {
+      local.dispose();
+    }
+    expect(local.received).toHaveLength(1);
+    expect(local.received[0].message.type).toBe("sync_changed");
+    expect(forwardCalls).toHaveLength(0);
+  });
+
+  test("in a side process, forwards to the daemon (no local publish)", async () => {
+    sideProcess = true;
+    const local = collectLocalDeliveries();
+    try {
+      await publishEvent(syncEvent());
+    } finally {
+      local.dispose();
+    }
+    expect(forwardCalls).toHaveLength(1);
+    expect(forwardCalls[0].event.message.type).toBe("sync_changed");
+    // The local hub reaches no SSE subscriber in a side process, so nothing is
+    // delivered locally.
+    expect(local.received).toHaveLength(0);
+  });
+
+  test("rejects a host-proxy event before forwarding, even in a side process", async () => {
+    sideProcess = true;
+    const hostEvent: AssistantEventEnvelope = {
+      id: "evt-2",
+      emittedAt: "2026-01-01T00:00:00.000Z",
+      message: {
+        type: "host_bash_request",
+      } as unknown as AssistantEventEnvelope["message"],
+    };
+    await expect(publishEvent(hostEvent)).rejects.toThrow(/host-proxy/);
+    expect(forwardCalls).toHaveLength(0);
+  });
+});

package/src/plugin-api/__tests__/publish-event.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Tests for the plugin-facing {@link publishEvent} helper. It is a thin wrapper
+ * over the capability-restricted event-hub facade, so these assert the two
+ * behaviours a caller relies on: a plain event reaches hub subscribers, and a
+ * host-proxy control event is rejected.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import type { AssistantEventEnvelope } from "../../api/index.js";
+import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
+import { publishEvent } from "../publish-event.js";
+
+// A test process defaults to "main daemon" (set by the test preload), so the
+// hub publishes locally here rather than forwarding.
+
+function syncEvent(): AssistantEventEnvelope {
+  return {
+    id: "evt-1",
+    conversationId: "conv-1",
+    emittedAt: "2026-01-01T00:00:00.000Z",
+    message: {
+      type: "sync_changed",
+      tags: ["my-app:items"],
+    } as unknown as AssistantEventEnvelope["message"],
+  };
+}
+
+describe("publishEvent", () => {
+  test("delivers a plain event to hub subscribers", async () => {
+    const received: AssistantEventEnvelope[] = [];
+    const sub = assistantEventHub.subscribe({
+      type: "process",
+      callback: (event) => {
+        received.push(event);
+      },
+    });
+    try {
+      await publishEvent(syncEvent());
+    } finally {
+      sub.dispose();
+    }
+    expect(received).toHaveLength(1);
+    expect(received[0].message.type).toBe("sync_changed");
+  });
+
+  test("rejects a host-proxy control event", async () => {
+    const hostEvent: AssistantEventEnvelope = {
+      id: "evt-2",
+      emittedAt: "2026-01-01T00:00:00.000Z",
+      message: {
+        type: "host_bash_request",
+      } as unknown as AssistantEventEnvelope["message"],
+    };
+    await expect(publishEvent(hostEvent)).rejects.toThrow(/host-proxy/);
+  });
+});

package/src/plugin-api/conversation-turn.ts

@@ -13,8 +13,8 @@
  * context management.
  */
 
+import type { AssistantEvent } from "../api/index.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
 import type { UserMessageAttachment } from "../daemon/message-types/shared.js";
 import type { ContentBlock, MediaSource } from "../providers/types.js";
 
@@ -144,9 +144,9 @@ export async function runConversationTurn(
   const { resolveMediaSourceData } =
     await import("../providers/media-resolve.js");
   const { getConversation, getMessageById, getMessages } =
-      await import("../persistence/conversation-crud.js");
+    await import("../persistence/conversation-crud.js");
   const { publishConversationListAndMetadataChanged } =
-      await import("../runtime/sync/resource-sync-events.js");
+    await import("../runtime/sync/resource-sync-events.js");
 
   // Plugin-driven turns run as the guardian: plugins are installed by the
   // guardian, so their conversations inherit guardian trust. This lets the
@@ -193,7 +193,7 @@ export async function runConversationTurn(
   // buildEventEmitter pattern from process-message.ts so plugin-driven
   // turns reach the same subscribers as HTTP-driven turns.
   let assistantMessageId: string | undefined;
-  const onEvent = (msg: ServerMessage): void => {
+  const onEvent = (msg: AssistantEvent): void => {
     broadcastMessage(msg, conversationId);
     if (msg.type === "message_complete" && msg.messageId) {
       assistantMessageId = msg.messageId;

package/src/plugin-api/event-hub-facade.ts

@@ -40,7 +40,7 @@
  * mid-fanout (the hub delivers one object to every subscriber in turn).
  */
 
-import type { AssistantEvent } from "../runtime/assistant-event.js";
+import type { AssistantEventEnvelope } from "../api/index.js";
 import {
   type AssistantEventFilter,
   type AssistantEventHub,
@@ -86,8 +86,12 @@ function wireSnapshot<T>(value: T): T {
  * client receives it.
  */
 function deepFreeze<T>(value: T, seen: WeakSet<object> = new WeakSet()): T {
-  if (value === null || typeof value !== "object") return value;
-  if (seen.has(value)) return value;
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (seen.has(value)) {
+    return value;
+  }
   seen.add(value);
   for (const key of Object.keys(value)) {
     deepFreeze((value as Record<string, unknown>)[key], seen);
@@ -105,7 +109,9 @@ const startsWith = Function.prototype.call.bind(
 ) as (str: string, search: string) => boolean;
 
 /** The blocked event type if `event` is a host-proxy control event, else `undefined`. */
-function hostControlEventType(event: AssistantEvent): string | undefined {
+function hostControlEventType(
+  event: AssistantEventEnvelope,
+): string | undefined {
   const type: unknown = event.message?.type;
   return typeof type === "string" &&
     startsWith(type, HOST_CONTROL_EVENT_TYPE_PREFIX)
@@ -134,7 +140,7 @@ export const pluginAssistantEventHub: PluginEventHub = Object.freeze({
       type: "process",
       filter,
       callback: (event) => {
-        let isolated: AssistantEvent;
+        let isolated: AssistantEventEnvelope;
         try {
           isolated = deepFreeze(wireSnapshot(event));
         } catch {
@@ -146,7 +152,7 @@ export const pluginAssistantEventHub: PluginEventHub = Object.freeze({
   },
 
   publish: async (event, options) => {
-    let snapshot: AssistantEvent;
+    let snapshot: AssistantEventEnvelope;
     let snapshotOptions: Parameters<AssistantEventHub["publish"]>[1];
     try {
       snapshot = deepFreeze(wireSnapshot(event));
@@ -160,6 +166,9 @@ export const pluginAssistantEventHub: PluginEventHub = Object.freeze({
         `Plugins may not publish daemon-to-client host-proxy control events (type "${blockedType}").`,
       );
     }
+    // `assistantEventHub.publish` forwards to the daemon when this is not the
+    // main process, so the guarded snapshot reaches real subscribers whether
+    // published here or from a sidecar worker.
     return assistantEventHub.publish(snapshot, snapshotOptions);
   },
 

package/src/plugin-api/index.ts

@@ -127,7 +127,7 @@ export { RiskLevel } from "./types.js";
 // Workspace-local plugins resolve these via the boot-time shim, which
 // re-binds each from the assistant's globalThis-parked namespace so they
 // share module identity with the assistant's own singletons.
-export type { AssistantEvent } from "../runtime/assistant-event.js";
+export type { AssistantEvent, AssistantEventEnvelope } from "../api/index.js";
 export type {
   AssistantEventCallback,
   AssistantEventFilter,
@@ -144,12 +144,18 @@ export type {
 export type { PluginEventHub } from "./event-hub-facade.js";
 /**
  * @deprecated Direct hub access is being replaced by narrower, purpose-built
- * importable helpers (e.g. a plugin-driven publish wrapper) so plugins don't
- * hold the general publish/subscribe surface. Avoid new usage; prefer the
- * scoped helpers as they land.
+ * importable helpers so plugins don't hold the general publish/subscribe
+ * surface. To emit an event, prefer {@link publishEvent}; avoid new usage of
+ * the raw hub.
  */
 export { pluginAssistantEventHub as assistantEventHub } from "./event-hub-facade.js";
 export { getModelProfiles } from "./model-profiles.js";
+// Purpose-built publish wrapper: emit a runtime event to the assistant's event
+// hub without holding the general hub handle. Route/hook authors surfacing a UI
+// invalidation (e.g. `sync_changed`) import this. Delegates to the same
+// capability-restricted facade, so host-proxy control events stay rejected.
+export type { AssistantEventPublishOptions } from "../runtime/assistant-event-publish-options.js";
+export { publishEvent } from "./publish-event.js";
 // Check whether a model or profile can process image input. Accepts a concrete
 // model id, a profile key, or a `ModelProfileInfo`; a bare string is resolved
 // as a model id first and then as a profile key. Profile resolution merges over