@vellumai/assistant 0.8.0 → 0.8.1

package/src/ipc/cli-client.ts

@@ -9,9 +9,10 @@
  * deterministic fallback for long AF_UNIX paths.
  */
 
-import { connect, type Socket } from "node:net";
+import { Socket } from "node:net";
 
 import { getLogger } from "../util/logger.js";
+import { IpcFrameReader, writeMessage } from "./ipc-framing.js";
 import { getAssistantSocketPath } from "./socket-path.js";
 
 const log = getLogger("cli-ipc-client");
@@ -20,12 +21,6 @@ const log = getLogger("cli-ipc-client");
 // Types (mirror cli-server.ts protocol)
 // ---------------------------------------------------------------------------
 
-type IpcRequest = {
-  id: string;
-  method: string;
-  params?: Record<string, unknown>;
-};
-
 type IpcResponse = {
   id: string;
   result?: unknown;
@@ -74,10 +69,15 @@ export interface CliIpcCallResult<T = unknown> {
 export async function cliIpcCall<T = unknown>(
   method: string,
   params?: Record<string, unknown>,
-  options?: { timeoutMs?: number },
+  options?: { timeoutMs?: number; signal?: AbortSignal },
 ): Promise<CliIpcCallResult<T>> {
+  if (options?.signal?.aborted) {
+    throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+  }
+
   const socketPath = getAssistantSocketPath();
   const callTimeoutMs = options?.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+  const opts = options; // alias used in the Promise callback below
 
   return new Promise<CliIpcCallResult<T>>((resolve) => {
     let settled = false;
@@ -99,20 +99,65 @@ export async function cliIpcCall<T = unknown>(
       );
       finish({
         ok: false,
-        error: "Could not connect to assistant daemon. Is it running?",
+        error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`,
       });
     }, CONNECT_TIMEOUT_MS);
 
-    const socket: Socket = connect(socketPath);
+    // Create the socket without connecting first so error/close handlers are
+    // registered before initiating the connection. In Bun, socket errors can
+    // fire synchronously during connect(), before listeners added afterward.
+    const socket = new Socket();
     socket.unref();
 
-    let buffer = "";
+    socket.on("error", (err) => {
+      const code = (err as NodeJS.ErrnoException).code;
+      log.debug({ err, code, method, socketPath }, "CLI IPC socket error");
+      finish({
+        ok: false,
+        error:
+          code === "ENOENT" || code === "ECONNREFUSED"
+            ? `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`
+            : `Connection error: ${code ?? err.message}`,
+      });
+    });
+
+    socket.on("close", (hadError) => {
+      if (!settled) {
+        finish({
+          ok: false,
+          // hadError is true when close follows a socket error (e.g. ENOENT).
+          error: hadError
+            ? `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`
+            : "Connection closed before response",
+        });
+      }
+    });
+
     const reqId = crypto.randomUUID();
 
+    opts?.signal?.addEventListener("abort", () => {
+      finish({ ok: false, error: "Request aborted" });
+    }, { once: true });
+
+    const reader = new IpcFrameReader(
+      (envelope) => {
+        if (envelope.id !== reqId) return;
+        const msg = envelope as IpcResponse;
+        if (msg.error) {
+          finish({ ok: false, error: msg.error,
+            ...(msg.statusCode != null && { statusCode: msg.statusCode }),
+            ...(msg.errorCode != null && { errorCode: msg.errorCode }),
+            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }) });
+        } else {
+          finish({ ok: true, result: msg.result as T });
+        }
+      },
+      (err) => finish({ ok: false, error: err.message }),
+    );
+
     socket.on("connect", () => {
       clearTimeout(connectTimer);
-      const req: IpcRequest = { id: reqId, method, params };
-      socket.write(JSON.stringify(req) + "\n");
+      writeMessage(socket, { id: reqId, method, params });
 
       callTimer = setTimeout(() => {
         log.debug(
@@ -123,61 +168,336 @@ export async function cliIpcCall<T = unknown>(
       }, callTimeoutMs);
 
       socket.on("data", (chunk) => {
-        buffer += chunk.toString();
-        let newlineIdx: number;
-        while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
-          const line = buffer.slice(0, newlineIdx).trim();
-          buffer = buffer.slice(newlineIdx + 1);
-          if (!line) continue;
-
-          try {
-            const msg = JSON.parse(line) as IpcResponse;
-            if (msg.id === reqId) {
-              if (msg.error) {
-                finish({
-                  ok: false,
-                  error: msg.error,
-                  ...(msg.statusCode !== undefined && {
-                    statusCode: msg.statusCode,
-                  }),
-                  ...(msg.errorCode !== undefined && {
-                    errorCode: msg.errorCode,
-                  }),
-                  ...(msg.errorDetails !== undefined && {
-                    errorDetails: msg.errorDetails,
-                  }),
-                });
-              } else {
-                finish({ ok: true, result: msg.result as T });
-              }
-              return;
-            }
-          } catch {
-            // Ignore malformed lines
-          }
-        }
+        reader.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
       });
     });
 
+    socket.connect(socketPath);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Binary one-shot client
+// ---------------------------------------------------------------------------
+
+const DEFAULT_BINARY_TIMEOUT_MS = 60_000;
+
+/**
+ * One-shot IPC call that expects a single binary frame response.
+ *
+ * Use when the route returns an IpcBinaryResponse (content-length header
+ * + one binary data frame). Returns the headers and raw bytes.
+ *
+ * @example
+ * const r = await cliIpcCallBinary("export_file", { id: "abc" });
+ * if (!r.ok) return exitFromIpcResult(r, cmd);
+ * fs.writeFileSync("out.bin", Buffer.from(r.bytes));
+ */
+export async function cliIpcCallBinary(
+  method: string,
+  params?: Record<string, unknown>,
+  opts?: { timeoutMs?: number; signal?: AbortSignal },
+): Promise<
+  | { ok: true; headers: Record<string, string>; bytes: Uint8Array }
+  | { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown }
+> {
+  if (opts?.signal?.aborted) {
+    throw opts.signal.reason ?? new DOMException("Aborted", "AbortError");
+  }
+
+  const socketPath = getAssistantSocketPath();
+  const callTimeoutMs = opts?.timeoutMs ?? DEFAULT_BINARY_TIMEOUT_MS;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let callTimer: ReturnType<typeof setTimeout> | undefined;
+
+    const finish = (
+      result:
+        | { ok: true; headers: Record<string, string>; bytes: Uint8Array }
+        | { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown },
+    ) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      if (callTimer) clearTimeout(callTimer);
+      socket.destroy();
+      resolve(result);
+    };
+
+    const connectTimer = setTimeout(() => {
+      log.debug({ method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS }, "CLI IPC binary connect timed out");
+      finish({ ok: false, error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.` });
+    }, CONNECT_TIMEOUT_MS);
+
+    const socket = new Socket();
+    socket.unref();
+
     socket.on("error", (err) => {
       const code = (err as NodeJS.ErrnoException).code;
-      log.debug({ err, code, method, socketPath }, "CLI IPC socket error");
+      log.debug({ err, code, method, socketPath }, "CLI IPC binary socket error");
       finish({
         ok: false,
         error:
           code === "ENOENT" || code === "ECONNREFUSED"
-            ? "Could not connect to assistant daemon. Is it running?"
+            ? `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`
             : `Connection error: ${code ?? err.message}`,
       });
     });
 
-    socket.on("close", () => {
+    socket.on("close", (hadError) => {
       if (!settled) {
         finish({
           ok: false,
-          error: "Connection closed before response",
+          error: hadError
+            ? `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`
+            : "Connection closed before response",
         });
       }
     });
+
+    const reqId = crypto.randomUUID();
+
+    opts?.signal?.addEventListener("abort", () => {
+      finish({ ok: false, error: "Request aborted" });
+    }, { once: true });
+
+    const reader = new IpcFrameReader(
+      (envelope, binary) => {
+        if (envelope.id !== reqId) return;
+        const msg = envelope as IpcResponse;
+        if (msg.error) {
+          finish({ ok: false, error: msg.error,
+            ...(msg.statusCode != null && { statusCode: msg.statusCode }),
+            ...(msg.errorCode != null && { errorCode: msg.errorCode }),
+            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }) });
+        } else if (binary === undefined) {
+          finish({ ok: false, error: "Expected binary frame but received JSON-only response" });
+        } else {
+          finish({ ok: true, headers: (envelope.headers ?? {}) as Record<string, string>, bytes: binary });
+        }
+      },
+      (err) => finish({ ok: false, error: err.message }),
+    );
+
+    socket.on("connect", () => {
+      clearTimeout(connectTimer);
+      writeMessage(socket, { id: reqId, method, params });
+
+      callTimer = setTimeout(() => {
+        log.debug({ method, socketPath, timeoutMs: callTimeoutMs }, "CLI IPC binary call timed out");
+        finish({ ok: false, error: "Request timed out" });
+      }, callTimeoutMs);
+
+      socket.on("data", (chunk) => {
+        reader.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+    });
+
+    socket.connect(socketPath);
   });
 }
+
+// ---------------------------------------------------------------------------
+// Streaming client
+// ---------------------------------------------------------------------------
+
+const DEFAULT_FIRST_BYTE_TIMEOUT_MS = 30_000;
+
+/**
+ * Streaming IPC call. Returns a ReadableStream of binary chunks.
+ *
+ * The promise resolves once the opening envelope arrives (or fails). The
+ * stream body is delivered asynchronously afterward. Call abort() to
+ * cancel mid-stream — this sends a $cancel envelope to the server.
+ *
+ * No total timeout. Only a first-byte timeout (default 30s).
+ *
+ * @example
+ * const r = await cliIpcCallStream("export_stream", { id: "abc" });
+ * if (!r.ok) return exitFromIpcResult(r, cmd);
+ * for await (const chunk of r.body) process.stdout.write(chunk);
+ */
+export async function cliIpcCallStream(
+  method: string,
+  params?: Record<string, unknown>,
+  opts?: { firstByteTimeoutMs?: number; signal?: AbortSignal },
+): Promise<
+  | { ok: true; headers: Record<string, string>; body: ReadableStream<Uint8Array>; abort: () => void }
+  | { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown }
+> {
+  if (opts?.signal?.aborted) {
+    throw opts.signal.reason ?? new DOMException("Aborted", "AbortError");
+  }
+
+  const socketPath = getAssistantSocketPath();
+  const firstByteTimeoutMs = opts?.firstByteTimeoutMs ?? DEFAULT_FIRST_BYTE_TIMEOUT_MS;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let firstByteTimer: ReturnType<typeof setTimeout> | undefined;
+    let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+
+    const finishError = (
+      result: { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown },
+    ) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      clearTimeout(firstByteTimer);
+      socket.destroy();
+      resolve(result);
+    };
+
+    const abort = () => {
+      if (settled && streamController) {
+        streamController.error(new DOMException("Aborted", "AbortError"));
+        streamController = undefined;
+      }
+      if (!socket.destroyed) {
+        writeMessage(socket, {
+          id: crypto.randomUUID(),
+          method: "$cancel",
+          params: { targetId: reqId },
+        });
+        // Use end() not destroy() so the $cancel frame flushes before the FIN.
+        socket.end();
+      }
+    };
+
+    const connectTimer = setTimeout(() => {
+      log.debug({ method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS }, "CLI IPC stream connect timed out");
+      finishError({ ok: false, error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.` });
+    }, CONNECT_TIMEOUT_MS);
+
+    const socket = new Socket();
+    socket.unref();
+
+    socket.on("error", (err) => {
+      const code = (err as NodeJS.ErrnoException).code;
+      log.debug({ err, code, method, socketPath }, "CLI IPC stream socket error");
+      if (!settled) {
+        finishError({
+          ok: false,
+          error:
+            code === "ENOENT" || code === "ECONNREFUSED"
+              ? `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`
+              : `Connection error: ${code ?? err.message}`,
+        });
+      } else {
+        streamController?.error(err);
+        streamController = undefined;
+      }
+    });
+
+    socket.on("close", (hadError) => {
+      if (!settled) {
+        finishError({
+          ok: false,
+          error: hadError
+            ? `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`
+            : "Connection closed before response",
+        });
+      } else if (streamController) {
+        streamController.error(new Error("Connection closed before stream ended"));
+        streamController = undefined;
+      }
+    });
+
+    const reqId = crypto.randomUUID();
+
+    opts?.signal?.addEventListener("abort", () => { abort(); }, { once: true });
+
+    const reader = new IpcFrameReader(
+      (envelope) => {
+        // Non-streaming envelope with error (e.g. method not found, auth failure)
+        if (envelope.id !== reqId) return;
+        const msg = envelope as IpcResponse;
+        finishError({ ok: false, error: msg.error ?? "Unexpected non-streaming response",
+          ...(msg.statusCode != null && { statusCode: msg.statusCode }),
+          ...(msg.errorCode != null && { errorCode: msg.errorCode }),
+          ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }) });
+      },
+      (err) => finishError({ ok: false, error: err.message }),
+      {
+        onStreamStart: (envelope) => {
+          if (envelope.id !== reqId) return;
+          clearTimeout(firstByteTimer);
+          const body = new ReadableStream<Uint8Array>({
+            start(ctrl) {
+              streamController = ctrl;
+            },
+            cancel() {
+              // Consumer cancelled (reader.cancel(), for-await break, pipe abort).
+              // Clear the controller reference first so abort() skips the
+              // already-closing stream's error() call, then send $cancel.
+              streamController = undefined;
+              abort();
+            },
+          });
+          settled = true;
+          clearTimeout(connectTimer);
+          resolve({ ok: true, headers: (envelope.headers ?? {}) as Record<string, string>, body, abort });
+        },
+        onStreamChunk: (chunk) => {
+          streamController?.enqueue(chunk);
+        },
+        onStreamEnd: () => {
+          streamController?.close();
+          streamController = undefined;
+          socket.destroy();
+        },
+      },
+    );
+
+    socket.on("connect", () => {
+      clearTimeout(connectTimer);
+      writeMessage(socket, { id: reqId, method, params });
+
+      firstByteTimer = setTimeout(() => {
+        log.debug({ method, socketPath, timeoutMs: firstByteTimeoutMs }, "CLI IPC stream first-byte timeout");
+        finishError({ ok: false, error: "Stream timed out waiting for first byte" });
+      }, firstByteTimeoutMs);
+
+      socket.on("data", (chunk) => {
+        reader.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+    });
+
+    socket.connect(socketPath);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Exit helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Map an IPC error result to a process exit code and terminate.
+ *
+ * Exit code matrix (DESIGN.md §3.6):
+ *   0  — success (not reached via this helper; call process.exit(0) directly)
+ *   1  — generic CLI error (fallback for unexpected status codes)
+ *   2  — daemon returned 4xx (bad params, not found, unauthorized)
+ *   3  — daemon returned 5xx (server-side error)
+ *   10 — IPC transport error (can't connect, timeout, closed before response)
+ *
+ * @example
+ * const r = await cliIpcCall<FooResponse>("foo", params);
+ * if (!r.ok) return exitFromIpcResult(r, cmd);
+ */
+export function exitFromIpcResult(
+  r: { ok: boolean; error?: string; statusCode?: number },
+  _cmd?: unknown,
+): never {
+  process.stderr.write((r.error ?? "Unknown error") + "\n");
+  if (r.statusCode === undefined) {
+    process.exit(10);
+  } else if (r.statusCode >= 500) {
+    process.exit(3);
+  } else if (r.statusCode >= 400) {
+    process.exit(2);
+  } else {
+    process.exit(1);
+  }
+}

package/src/ipc/routes/db-proxy-transaction.ts

@@ -0,0 +1,151 @@
+/**
+ * ⚠️  TEMPORARY HACK — DO NOT EXTEND ⚠️
+ *
+ * IPC route that lets the gateway execute multiple write statements against
+ * the assistant's SQLite database inside a single atomic transaction.
+ *
+ * Companion to db-proxy.ts. Exists because some gateway-orchestrated writes
+ * (e.g. invite redemption: upsert contact channel + record invite use) must
+ * be all-or-nothing. With the contacts/guardian/invite tables still living
+ * in the assistant DB, the gateway needs a way to commit several writes
+ * atomically there.
+ *
+ * Each step is a write (INSERT/UPDATE/DELETE). All steps run inside a
+ * BEGIN IMMEDIATE transaction. If any step throws — including a step whose
+ * `requireChanges` constraint is unmet — the entire transaction rolls back.
+ *
+ * Read-modify-write across steps is not supported (the IPC is one-shot;
+ * later steps cannot react to earlier step results except via SQL conditions
+ * embedded in the WHERE clause and the optional `requireChanges` guard).
+ *
+ * This route is intentionally NOT in the shared ROUTES array — it is a
+ * private implementation detail between the gateway and assistant IPC
+ * servers and must not be discoverable by clients or the OpenAPI spec.
+ *
+ * Remove once contacts/guardian/invite logic is fully migrated to the
+ * gateway's own database.
+ */
+
+import { getSqlite } from "../../memory/db-connection.js";
+import { RouteError } from "../../runtime/routes/errors.js";
+import { getLogger } from "../../util/logger.js";
+
+const log = getLogger("db-proxy-transaction");
+
+/** Column value types that SQLite can return. */
+type SqliteValue = string | number | null | Uint8Array;
+
+export interface DbProxyTransactionStep {
+  /** The SQL write statement to execute. */
+  sql: string;
+  /** Positional bind parameters. */
+  bind?: SqliteValue[];
+  /**
+   * If set, abort the transaction (rollback) when this step's row-change
+   * count is below this threshold. Used for stale-write detection — e.g.
+   * "increment use_count only if status = 'active' AND use_count < max_uses",
+   * with `requireChanges: 1` to abort when no rows match.
+   */
+  requireChanges?: number;
+}
+
+export interface DbProxyTransactionParams {
+  steps: DbProxyTransactionStep[];
+}
+
+export type DbProxyTransactionResult =
+  | {
+      ok: true;
+      results: Array<{ changes: number; lastInsertRowid: number }>;
+    }
+  | {
+      ok: false;
+      reason: "require_changes_failed";
+      failedStep: number;
+      actualChanges: number;
+      requiredChanges: number;
+    };
+
+export function handleDbProxyTransaction(
+  params: DbProxyTransactionParams,
+): DbProxyTransactionResult {
+  const db = getSqlite();
+
+  if (!Array.isArray(params.steps) || params.steps.length === 0) {
+    throw new RouteError(
+      "db_proxy_transaction requires at least one step",
+      "INVALID_PARAMS",
+      400,
+    );
+  }
+
+  // Sentinel used to abort the transaction without leaking through as a generic
+  // SQL error. Better-sqlite3 rolls back when the inner function throws.
+  class RequireChangesFailure extends Error {
+    constructor(
+      public failedStep: number,
+      public actualChanges: number,
+      public requiredChanges: number,
+    ) {
+      super(
+        `Step ${failedStep} affected ${actualChanges} rows, requires ${requiredChanges}`,
+      );
+    }
+  }
+
+  const results: Array<{ changes: number; lastInsertRowid: number }> = [];
+
+  try {
+    db.transaction(() => {
+      for (let i = 0; i < params.steps.length; i++) {
+        const step = params.steps[i];
+        const stmt = db.prepare(step.sql);
+        const result = step.bind ? stmt.run(...step.bind) : stmt.run();
+        const changes = result.changes;
+        results.push({
+          changes,
+          lastInsertRowid: Number(result.lastInsertRowid),
+        });
+
+        if (
+          step.requireChanges !== undefined &&
+          changes < step.requireChanges
+        ) {
+          throw new RequireChangesFailure(i, changes, step.requireChanges);
+        }
+      }
+    }).immediate();
+  } catch (err) {
+    if (err instanceof RequireChangesFailure) {
+      log.debug(
+        {
+          failedStep: err.failedStep,
+          actualChanges: err.actualChanges,
+          requiredChanges: err.requiredChanges,
+        },
+        "db-proxy-transaction aborted by requireChanges guard",
+      );
+      return {
+        ok: false,
+        reason: "require_changes_failed",
+        failedStep: err.failedStep,
+        actualChanges: err.actualChanges,
+        requiredChanges: err.requiredChanges,
+      };
+    }
+    // Wrap raw SQL/runtime errors in RouteError so the IPC envelope carries
+    // a statusCode + errorCode. Without this, the gateway-side strict caller
+    // sees a structureless `msg.error` and misclassifies it as a transport
+    // failure ("assistant may not be ready"), masking the real SQL error
+    // and breaking debuggability + retry decisions.
+    const message = err instanceof Error ? err.message : String(err);
+    log.warn({ err }, "db-proxy-transaction execution failed");
+    throw new RouteError(message, "DB_PROXY_TRANSACTION_FAILED", 500);
+  }
+
+  log.debug(
+    { stepCount: params.steps.length },
+    "db-proxy-transaction committed",
+  );
+  return { ok: true, results };
+}

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

@@ -192,6 +192,66 @@ describe("host.events.publish", () => {
 
     client.close();
   });
+
+  test.each([
+    "host_bash_request",
+    "host_bash_cancel",
+    "host_file_request",
+    "host_file_cancel",
+    "host_browser_request",
+    "host_browser_cancel",
+    "host_cu_request",
+    "host_transfer_request",
+    "confirmation_request",
+    "secret_request",
+  ])("rejects blocked event type: %s", async (blockedType) => {
+    const client = await openClient();
+    const event = {
+      id: "evt-blocked",
+      emittedAt: new Date().toISOString(),
+      message: { type: blockedType },
+    };
+    client.send({
+      id: "req-blocked",
+      method: "host.events.publish",
+      params: { event },
+    });
+
+    const frame = await client.nextFrame();
+    expect("error" in frame && frame.error).toContain("cannot publish");
+
+    client.close();
+  });
+
+  test("allows non-blocked event types through", async () => {
+    const received: AssistantEvent[] = [];
+    const subscription = assistantEventHub.subscribe({
+      type: "process",
+      callback: (evt) => { received.push(evt); },
+    });
+
+    try {
+      const client = await openClient();
+      const event = {
+        id: "evt-ok",
+        emittedAt: new Date().toISOString(),
+        message: { type: "skill_custom_event", data: "hello" },
+      };
+      client.send({
+        id: "req-ok",
+        method: "host.events.publish",
+        params: { event },
+      });
+
+      const frame = await client.nextFrame();
+      expect("result" in frame && frame.result).toEqual({ published: true });
+      expect(received).toHaveLength(1);
+
+      client.close();
+    } finally {
+      subscription.dispose();
+    }
+  });
 });
 
 describe("host.events.buildEvent", () => {