@vellumai/assistant 0.8.0 → 0.8.1

package/src/ipc/__tests__/streaming-client.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Smoke tests for cliIpcCallBinary and cliIpcCallStream.
+ *
+ * Uses a real AssistantIpcServer with fixture routes injected via module mocks.
+ * Pattern mirrors cli-ipc.test.ts.
+ */
+
+import { Socket } from "node:net";
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+// Ensure tests use a workspace-based socket path rather than any pre-existing
+// system socket (e.g. stale root-owned /run/assistant-ipc/assistant.sock).
+delete process.env.ASSISTANT_IPC_SOCKET_DIR;
+
+import { AssistantIpcServer } from "../assistant-server.js";
+import { cliIpcCallBinary, cliIpcCallStream } from "../cli-client.js";
+import { writeMessage } from "../ipc-framing.js";
+
+// ---------------------------------------------------------------------------
+// Fixture routes
+// ---------------------------------------------------------------------------
+
+const STREAM_FIXTURE_ROUTE = {
+  operationId: "stream_fixture",
+  endpoint: "/stream-fixture",
+  method: "GET" as const,
+  handler: async () => ({
+    stream: new ReadableStream<Uint8Array>({
+      start(ctrl) {
+        ctrl.enqueue(new TextEncoder().encode("chunk1"));
+        ctrl.enqueue(new TextEncoder().encode("chunk2"));
+        ctrl.close();
+      },
+    }),
+    headers: { "x-fixture": "streaming" },
+  }),
+};
+
+const BINARY_FIXTURE_ROUTE = {
+  operationId: "binary_fixture",
+  endpoint: "/binary-fixture",
+  method: "GET" as const,
+  handler: async () => ({
+    binary: new TextEncoder().encode("hello"),
+    headers: { "content-type": "application/octet-stream" },
+  }),
+};
+
+let slowStreamAborted = false;
+const SLOW_STREAM_FIXTURE_ROUTE = {
+  operationId: "slow_stream_fixture",
+  endpoint: "/slow-stream-fixture",
+  method: "GET" as const,
+  // Delays 50 ms before returning the stream so the test can destroy the
+  // socket first, exercising the sendStreamingResponse early-return path.
+  handler: async (params: Record<string, unknown> | undefined) => {
+    slowStreamAborted = false;
+    const signal = (params as { abortSignal?: AbortSignal })?.abortSignal;
+    signal?.addEventListener("abort", () => { slowStreamAborted = true; }, { once: true });
+    await new Promise((r) => setTimeout(r, 50));
+    return {
+      stream: new ReadableStream<Uint8Array>({ start(ctrl) { ctrl.close(); } }),
+      headers: {} as Record<string, string>,
+    };
+  },
+};
+
+let cancelAborted = false;
+const CANCEL_FIXTURE_ROUTE = {
+  operationId: "cancel_fixture",
+  endpoint: "/cancel-fixture",
+  method: "GET" as const,
+  // Returns a stream immediately that holds open until the abortSignal fires.
+  // This lets cliIpcCallStream resolve (opening envelope arrives), then the
+  // test can call abort() and verify the signal is delivered to the handler.
+  handler: async (params: Record<string, unknown> | undefined) => {
+    cancelAborted = false;
+    const signal = (params as { abortSignal?: AbortSignal })?.abortSignal;
+    return {
+      stream: new ReadableStream<Uint8Array>({
+        start(ctrl) {
+          if (signal?.aborted) {
+            cancelAborted = true;
+            ctrl.error(new DOMException("Aborted", "AbortError"));
+            return;
+          }
+          signal?.addEventListener("abort", () => {
+            cancelAborted = true;
+            ctrl.error(new DOMException("Aborted", "AbortError"));
+          }, { once: true });
+          // Hold open — no close() until aborted
+        },
+      }),
+      headers: {} as Record<string, string>,
+    };
+  },
+};
+
+mock.module("../../runtime/routes/index.js", () => ({
+  ROUTES: [STREAM_FIXTURE_ROUTE, BINARY_FIXTURE_ROUTE, CANCEL_FIXTURE_ROUTE, SLOW_STREAM_FIXTURE_ROUTE],
+}));
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+let server: AssistantIpcServer | null = null;
+
+async function startServer(): Promise<void> {
+  server = new AssistantIpcServer({ watchdogIntervalMs: 0 });
+  await server.start();
+  await new Promise((r) => setTimeout(r, 50));
+}
+
+afterEach(() => {
+  server?.stop();
+  server = null;
+  cancelAborted = false;
+  slowStreamAborted = false;
+});
+
+// ---------------------------------------------------------------------------
+// cliIpcCallStream tests
+// ---------------------------------------------------------------------------
+
+describe("cliIpcCallStream", () => {
+  test("resolves ok with correct headers", async () => {
+    await startServer();
+    const r = await cliIpcCallStream("stream_fixture");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.headers["x-fixture"]).toBe("streaming");
+    // Drain the body to avoid resource leaks
+    const reader = r.body.getReader();
+    while (true) {
+      const { done } = await reader.read();
+      if (done) break;
+    }
+  });
+
+  test("chunks arrive in order", async () => {
+    await startServer();
+    const r = await cliIpcCallStream("stream_fixture");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+
+    const chunks: string[] = [];
+    const reader = r.body.getReader();
+    const dec = new TextDecoder();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(dec.decode(value));
+    }
+    expect(chunks.join("")).toBe("chunk1chunk2");
+  });
+
+  test("abort() cancels mid-stream", async () => {
+    await startServer();
+    const r = await cliIpcCallStream("cancel_fixture");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+
+    const bodyReader = r.body.getReader();
+    r.abort();
+
+    // The stream should error after abort — either DOMException or connection close
+    try {
+      await bodyReader.read();
+    } catch (err) {
+      expect(err).toBeDefined();
+    }
+
+    // Give the server a tick to process the $cancel envelope
+    await new Promise((res) => setTimeout(res, 200));
+    expect(cancelAborted).toBe(true);
+  });
+
+  test("returns ok: false when no server", async () => {
+    const r = await cliIpcCallStream("stream_fixture");
+    expect(r.ok).toBe(false);
+  });
+
+  test("body.cancel() sends $cancel to server (Fix F)", async () => {
+    await startServer();
+    const r = await cliIpcCallStream("cancel_fixture");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+
+    // Cancel the ReadableStream body — the cancel() callback should call abort()
+    // which sends $cancel on the wire and ends the socket.
+    await r.body.cancel();
+
+    // Give the server a tick to process the $cancel envelope
+    await new Promise((res) => setTimeout(res, 200));
+    expect(cancelAborted).toBe(true);
+  });
+
+  test("abortController cleaned up when socket destroyed before stream starts (Fix E)", async () => {
+    await startServer();
+    const socketPath = server!.getSocketPath();
+
+    // Use a raw socket so we can destroy it immediately after sending the
+    // request, before slow_stream_fixture's 50ms handler delay expires.
+    const rawSocket = new Socket();
+    await new Promise<void>((res) => rawSocket.connect(socketPath, res));
+    writeMessage(rawSocket, { id: crypto.randomUUID(), method: "slow_stream_fixture", params: {} });
+    rawSocket.destroy();
+
+    // Wait for the handler to complete and sendStreamingResponse to run
+    await new Promise((res) => setTimeout(res, 200));
+
+    // Handler's abortSignal fired → confirms abort+delete ran in the
+    // sendStreamingResponse early-return (socket already destroyed) path.
+    expect(slowStreamAborted).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// cliIpcCallBinary tests
+// ---------------------------------------------------------------------------
+
+describe("cliIpcCallBinary", () => {
+  test("returns bytes from binary route", async () => {
+    await startServer();
+    const r = await cliIpcCallBinary("binary_fixture");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(new TextDecoder().decode(r.bytes)).toBe("hello");
+    expect(r.headers["content-type"]).toBe("application/octet-stream");
+  });
+
+  test("returns ok: false when no server", async () => {
+    const r = await cliIpcCallBinary("binary_fixture");
+    expect(r.ok).toBe(false);
+  });
+});

package/src/ipc/__tests__/streaming-framing.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Unit tests for IpcFrameReader — pure in-memory, no network.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { IpcFrameReader, type StreamCallbacks } from "../ipc-framing.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Build a single length-prefixed frame: 4-byte big-endian length + payload. */
+function buildFrame(payload: Uint8Array | Buffer): Buffer {
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(payload.length, 0);
+  return Buffer.concat([header, Buffer.from(payload)]);
+}
+
+/** Build a zero-length terminator frame (4 bytes of 0x00). */
+function buildTerminator(): Buffer {
+  return Buffer.alloc(4);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("IpcFrameReader", () => {
+  test("parses JSON-only envelope", () => {
+    const envelope = { id: "req-1", result: { foo: "bar" } };
+    const json = Buffer.from(JSON.stringify(envelope), "utf-8");
+    const frame = buildFrame(json);
+
+    const received: Array<{ envelope: unknown; binary: Uint8Array | undefined }> = [];
+
+    const reader = new IpcFrameReader((env, binary) => {
+      received.push({ envelope: env, binary });
+    });
+
+    reader.push(frame);
+
+    expect(received).toHaveLength(1);
+    expect(received[0].envelope).toEqual(envelope);
+    expect(received[0].binary).toBeUndefined();
+  });
+
+  test("parses envelope + binary frame (content-length)", () => {
+    const binaryData = new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05]);
+
+    const envelope = {
+      id: "req-2",
+      result: "ok",
+      headers: { "content-length": "5" },
+    };
+    const jsonFrame = buildFrame(Buffer.from(JSON.stringify(envelope), "utf-8"));
+    const binaryFrame = buildFrame(Buffer.from(binaryData));
+
+    const allData = Buffer.concat([jsonFrame, binaryFrame]);
+
+    const received: Array<{ envelope: unknown; binary: Uint8Array | undefined }> = [];
+
+    const reader = new IpcFrameReader((env, binary) => {
+      received.push({ envelope: env, binary });
+    });
+
+    reader.push(allData);
+
+    expect(received).toHaveLength(1);
+    expect(received[0].envelope).toEqual(envelope);
+    expect(received[0].binary).toBeInstanceOf(Uint8Array);
+    expect(received[0].binary).toHaveLength(5);
+    expect(Array.from(received[0].binary!)).toEqual([0x01, 0x02, 0x03, 0x04, 0x05]);
+  });
+
+  test("parses chunked stream (transfer-encoding: chunked)", () => {
+    const chunk1 = new Uint8Array([0x61, 0x62]); // "ab"
+    const chunk2 = new Uint8Array([0x63, 0x64, 0x65]); // "cde"
+
+    const envelope = {
+      id: "req-3",
+      headers: { "transfer-encoding": "chunked" },
+    };
+    const jsonFrame = buildFrame(Buffer.from(JSON.stringify(envelope), "utf-8"));
+    const chunk1Frame = buildFrame(Buffer.from(chunk1));
+    const chunk2Frame = buildFrame(Buffer.from(chunk2));
+    const terminator = buildTerminator();
+
+    const allData = Buffer.concat([jsonFrame, chunk1Frame, chunk2Frame, terminator]);
+
+    const events: string[] = [];
+    let startEnvelope: unknown = null;
+    const chunks: Uint8Array[] = [];
+
+    const streamCallbacks: StreamCallbacks = {
+      onStreamStart: (env) => {
+        events.push("start");
+        startEnvelope = env;
+      },
+      onStreamChunk: (chunk) => {
+        events.push("chunk");
+        chunks.push(chunk);
+      },
+      onStreamEnd: () => {
+        events.push("end");
+      },
+    };
+
+    const reader = new IpcFrameReader(
+      (_env, _binary) => {
+        events.push("message");
+      },
+      undefined,
+      streamCallbacks,
+    );
+
+    reader.push(allData);
+
+    expect(events).toEqual(["start", "chunk", "chunk", "end"]);
+    expect(startEnvelope).toEqual(envelope);
+    expect(chunks).toHaveLength(2);
+    expect(Array.from(chunks[0])).toEqual([0x61, 0x62]);
+    expect(Array.from(chunks[1])).toEqual([0x63, 0x64, 0x65]);
+  });
+
+  test("detects legacy newline-JSON", () => {
+    const legacyPayload = JSON.stringify({ id: "x", result: 1 }) + "\n";
+    const buf = Buffer.from(legacyPayload, "utf-8");
+
+    const received: Array<{ envelope: unknown; binary: Uint8Array | undefined }> = [];
+
+    const reader = new IpcFrameReader((env, binary) => {
+      received.push({ envelope: env, binary });
+    });
+
+    reader.push(buf);
+
+    expect(received).toHaveLength(1);
+    expect(received[0].envelope).toEqual({ id: "x", result: 1 });
+    expect(reader.isLegacy).toBe(true);
+  });
+});

package/src/ipc/assistant-server.ts

@@ -53,6 +53,10 @@ import {
   writeStreamEnd,
 } from "./ipc-framing.js";
 import { type DbProxyParams, handleDbProxy } from "./routes/db-proxy.js";
+import {
+  type DbProxyTransactionParams,
+  handleDbProxyTransaction,
+} from "./routes/db-proxy-transaction.js";
 import { routeDefinitionsToIpcMethods } from "./routes/route-adapter.js";
 import { ensureSocketPathFree } from "./socket-cleanup.js";
 import { resolveIpcSocketPath } from "./socket-path.js";
@@ -155,6 +159,7 @@ export class AssistantIpcServer {
    * their accept loops drain.
    */
   private legacyServers = new Set<Server>();
+  private abortControllers = new Map<string, AbortController>();
 
   constructor(options?: AssistantIpcServerOptions) {
     const resolution = resolveIpcSocketPath("assistant");
@@ -167,13 +172,23 @@ export class AssistantIpcServer {
       this.methods.set(route.operationId, route.handler);
     }
 
-    // ⚠️  TEMPORARY — gateway→assistant DB proxy (see ipc/routes/db-proxy.ts).
-    // This is the ONLY route defined directly here; all other routes go in ROUTES.
-    // Remove once contacts/guardian-binding logic is fully migrated to the
-    // gateway's own database.
+    // ⚠️  TEMPORARY — gateway→assistant DB proxies (see ipc/routes/db-proxy.ts
+    // and ipc/routes/db-proxy-transaction.ts). These are the ONLY routes
+    // defined directly here; all other routes go in ROUTES. Remove once
+    // contacts/guardian-binding logic is fully migrated to the gateway's
+    // own database.
     this.methods.set("db_proxy", (params) =>
       handleDbProxy(params as unknown as DbProxyParams),
     );
+    this.methods.set("db_proxy_transaction", (params) =>
+      handleDbProxyTransaction(params as unknown as DbProxyTransactionParams),
+    );
+
+    this.methods.set("$cancel", (params) => {
+      const targetId = (params as { targetId?: string }).targetId;
+      if (targetId) this.abortControllers.get(targetId)?.abort();
+      return null;
+    });
 
     this.watchdog = new SocketWatchdog({
       socketPath: this.socketPath,
@@ -213,6 +228,9 @@ export class AssistantIpcServer {
   stop(): void {
     this.watchdog.stop();
 
+    for (const ctrl of this.abortControllers.values()) ctrl.abort();
+    this.abortControllers.clear();
+
     for (const client of this.clients) {
       if (!client.destroyed) client.destroy();
     }
@@ -316,16 +334,33 @@ export class AssistantIpcServer {
 
     void binary;
 
+    // Skip AbortController for the $cancel meta-method itself
+    const needsAbortTracking = req.method !== "$cancel";
+    let abortController: AbortController | undefined;
+    if (needsAbortTracking) {
+      abortController = new AbortController();
+      this.abortControllers.set(req.id, abortController);
+    }
+
     try {
-      const handlerArgs = injectLocalActorHeader(req.params);
+      const handlerArgs = {
+        ...injectLocalActorHeader(req.params),
+        ...(abortController && { abortSignal: abortController.signal }),
+      };
       const result = handler(handlerArgs);
 
       if (result instanceof Promise) {
         result
           .then((value) => {
+            // For streaming responses, keep the AbortController alive until the
+            // stream ends — sendStreamingResponse deletes it on completion/error.
+            if (!isIpcStreamingResponse(value)) {
+              this.abortControllers.delete(req.id);
+            }
             this.sendResult(socket, reader, req.id, value);
           })
           .catch((err) => {
+            this.abortControllers.delete(req.id);
             log.warn({ err, method: req.method }, "IPC handler error");
             this.sendResponse(
               socket,
@@ -334,9 +369,13 @@ export class AssistantIpcServer {
             );
           });
       } else {
+        if (!isIpcStreamingResponse(result)) {
+          this.abortControllers.delete(req.id);
+        }
         this.sendResult(socket, reader, req.id, result);
       }
     } catch (err) {
+      this.abortControllers.delete(req.id);
       log.warn({ err, method: req.method }, "IPC handler error");
       this.sendResponse(socket, reader, this.buildErrorResponse(req.id, err));
     }
@@ -402,7 +441,11 @@ export class AssistantIpcServer {
     requestId: string,
     response: IpcStreamingResponse,
   ): void {
-    if (socket.destroyed) return;
+    if (socket.destroyed) {
+      this.abortControllers.get(requestId)?.abort();
+      this.abortControllers.delete(requestId);
+      return;
+    }
 
     // Legacy clients can't handle chunked streaming — fall back to
     // buffering the full stream and sending as a single binary response.
@@ -426,10 +469,13 @@ export class AssistantIpcServer {
         .read()
         .then(({ done, value }) => {
           if (socket.destroyed) {
+            this.abortControllers.get(requestId)?.abort();
+            this.abortControllers.delete(requestId);
             streamReader.cancel().catch(() => {});
             return;
           }
           if (done) {
+            this.abortControllers.delete(requestId);
             writeStreamEnd(socket);
             return;
           }
@@ -437,6 +483,7 @@ export class AssistantIpcServer {
           pump();
         })
         .catch((err) => {
+          this.abortControllers.delete(requestId);
           log.warn({ err }, "IPC stream read error");
           if (!socket.destroyed) {
             writeStreamEnd(socket);
@@ -464,6 +511,7 @@ export class AssistantIpcServer {
         .read()
         .then(({ done, value }) => {
           if (done) {
+            this.abortControllers.delete(requestId);
             const totalLength = chunks.reduce(
               (sum, c) => sum + c.byteLength,
               0,
@@ -488,6 +536,7 @@ export class AssistantIpcServer {
           pump();
         })
         .catch((err) => {
+          this.abortControllers.delete(requestId);
           log.warn({ err }, "IPC legacy stream buffer error");
           this.sendResponse(socket, reader, {
             id: requestId,