@haikit/server 0.20.0 → 0.20.2

package/src/routes.ts

@@ -1,11 +1,12 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { isConversationBusy, isStaleLease } from "@haikit/core";
 import type { Emit, NoticeRecord, WireEvent } from "@haikit/core";
-import type { Hai } from "./runtime.js";
+import type { Hai, WakeOutcome } from "./runtime.js";
 
 /**
  * Node http handler for the three routes, and a fourth when the app sends
- * notices. Returns true if it handled the request.
+ * notices. Returns true if it handled the request. It never rejects: a request
+ * that fails is answered, ended and logged (see `failed`).
  *
  * The three POST routes stream SSE: chat and interact because both can resume
  * the agent loop, start because the init tool it runs can render surfaces.
@@ -18,92 +19,139 @@ import type { Hai } from "./runtime.js";
  */
 export function nodeHandler(hai: Hai, basePath = "/hai") {
   return async function handle(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
-    const url = new URL(req.url ?? "/", "http://localhost");
+    let url: URL;
+    try {
+      url = new URL(req.url ?? "/", "http://localhost");
+    } catch {
+      // Node accepts targets a URL can't parse, such as `//[`. None is under
+      // a base path, which a URL always parses, so it's not ours: the app's.
+      return false;
+    }
     if (!url.pathname.startsWith(basePath)) return false;
     const route = url.pathname.slice(basePath.length);
 
     if (req.method === "GET" && route === "/events" && hai.streamsEvents) {
-      await streamNotices(hai, req, res, url);
+      try {
+        await streamNotices(hai, req, res, url);
+      } catch (err) {
+        failed(res, err);
+      }
       return true;
     }
 
     if (req.method !== "POST") return false;
     if (route !== "/chat" && route !== "/interact" && route !== "/start") return false;
 
-    const body = await readJson(req);
-
-    // Nothing to run before the first message: answer with an empty stream and
-    // create no conversation, so an app without init doesn't get one for every
-    // page view. Its first message starts the conversation, as it always has.
-    if (route === "/start" && !hai.config.init) {
-      openSSE(res);
-      res.end();
-      return true;
-    }
-
-    // Before the SSE stream opens, because a rejected load has no stream to
-    // report into — and an uncaught throw here would take down the request.
-    let conversation;
     try {
-      conversation = await hai.config.store.loadConversation(body.conversationId);
+      await respond(hai, route, req, res);
     } catch (err) {
-      if (!isConversationBusy(err)) throw err;
-      res.writeHead(409, { "content-type": "application/json" });
-      res.end(JSON.stringify({ error: (err as Error).message }));
-      return true;
+      failed(res, err);
     }
+    return true;
+  };
+}
 
-    const emit = openSSE(res);
-    if (route === "/chat" || route === "/start") {
-      emit({
-        type: "hello",
-        conversationId: conversation.id,
-        model: hai.config.model.id,
-        ...(hai.streamsEvents ? { events: true as const } : {}),
-      });
-    }
+/**
+ * A request that failed in a way the route has no event for, such as a store
+ * error: the browser is told, the response ends, and the error is logged. It
+ * is never thrown on to the server, where an unhandled rejection would take
+ * the process down and leave the response open.
+ */
+function failed(res: ServerResponse, err: unknown) {
+  console.error("[haikit] request failed:", err);
+  const message = err instanceof Error ? err.message : String(err);
+  if (!res.headersSent) {
+    res.writeHead(500, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: message }));
+  } else if (!res.writableEnded) {
+    res.write(`data: ${JSON.stringify({ type: "error", message } satisfies WireEvent)}\n\n`);
+    res.end();
+  }
+}
 
-    let superseded = false;
+/** One of the three POST routes, once the request is known to be one. */
+async function respond(hai: Hai, route: string, req: IncomingMessage, res: ServerResponse) {
+  let body: Record<string, any>;
+  try {
+    body = await readJson(req);
+  } catch {
+    res.writeHead(400, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "the request body must be a JSON object" }));
+    return;
+  }
+
+  // Nothing to run before the first message: answer with an empty stream and
+  // create no conversation, so an app without init doesn't get one for every
+  // page view. Its first message starts the conversation, as it always has.
+  if (route === "/start" && !hai.config.init) {
+    openSSE(res);
+    res.end();
+    return;
+  }
+
+  // Before the SSE stream opens, because a rejected load has no stream to
+  // report into: busy is a 409, and anything else a 500 (see `failed`).
+  let conversation;
+  try {
+    conversation = await hai.config.store.loadConversation(body.conversationId);
+  } catch (err) {
+    if (!isConversationBusy(err)) throw err;
+    res.writeHead(409, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: (err as Error).message }));
+    return;
+  }
+
+  const emit = openSSE(res);
+  if (route === "/chat" || route === "/start") {
+    emit({
+      type: "hello",
+      conversationId: conversation.id,
+      model: hai.config.model.id,
+      ...(hai.streamsEvents ? { events: true as const } : {}),
+    });
+  }
+
+  let superseded = false;
+  try {
+    if (route === "/chat") {
+      await hai.send(conversation, String(body.message ?? ""), emit);
+    } else if (route === "/start") {
+      await hai.start(conversation, emit);
+    } else {
+      await hai.interact(
+        conversation,
+        { handle: body.handle, action: body.action, value: body.value },
+        emit,
+      );
+    }
+  } catch (err) {
+    if (isStaleLease(err)) superseded = true;
+    emit({ type: "error", message: (err as Error).message });
+  } finally {
+    // The lease lives exactly as long as the request. Releasing it any
+    // earlier — when a turn parks, say — lets the client's next interaction
+    // arrive before this request has finished writing, and the two turns
+    // interleave on one conversation.
+    //
+    // Only the expiry is cleared. The token has to survive so the save below
+    // can still prove this request is the rightful holder.
+    conversation.leaseUntil = null;
     try {
-      if (route === "/chat") {
-        await hai.send(conversation, String(body.message ?? ""), emit);
-      } else if (route === "/start") {
-        await hai.start(conversation, emit);
-      } else {
-        await hai.interact(
-          conversation,
-          { handle: body.handle, action: body.action, value: body.value },
-          emit,
-        );
-      }
+      // A turn that already hit a fence knows its save would be rejected too;
+      // attempting it only repeats the same error to the client.
+      if (!superseded) await hai.config.store.saveConversation(conversation);
     } catch (err) {
-      if (isStaleLease(err)) superseded = true;
+      // Overtaken while we were slow: another turn already wrote newer state
+      // under a fresh token. Dropping this write is the correct outcome, but
+      // the client asked for something it is not getting, so say so. Any
+      // other failure goes to `failed`, which says so too, ends the response
+      // and logs it: the conversation stays held until its lease lapses.
+      if (!isStaleLease(err)) throw err;
       emit({ type: "error", message: (err as Error).message });
-    } finally {
-      // The lease lives exactly as long as the request. Releasing it any
-      // earlier — when a turn parks, say — lets the client's next interaction
-      // arrive before this request has finished writing, and the two turns
-      // interleave on one conversation.
-      //
-      // Only the expiry is cleared. The token has to survive so the save below
-      // can still prove this request is the rightful holder.
-      conversation.leaseUntil = null;
-      try {
-        // A turn that already hit a fence knows its save would be rejected too;
-        // attempting it only repeats the same error to the client.
-        if (!superseded) await hai.config.store.saveConversation(conversation);
-      } catch (err) {
-        // Overtaken while we were slow: another turn already wrote newer state
-        // under a fresh token. Dropping this write is the correct outcome, but
-        // the client asked for something it is not getting, so say so.
-        if (!isStaleLease(err)) throw err;
-        emit({ type: "error", message: (err as Error).message });
-      }
     }
+  }
 
-    res.end();
-    return true;
-  };
+  res.end();
 }
 
 /**
@@ -306,10 +354,18 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
   // turn, nor behind the retries while another request holds the
   // conversation. One attempt at a time; a wake notice that lands meanwhile
   // asks for another once it is done.
+  //
+  // An attempt takes the conversation's lease and saves it, even when it
+  // finds nothing to do, and a request that arrives meanwhile is turned away
+  // busy. So it is made only when there may be something new: a wake notice,
+  // read from the store by any stream here, past the last one an attempt here
+  // settled. A polling browser opens a stream several times a minute; each
+  // would otherwise take the lease.
   let waking: Promise<void> | null = null;
   let again = false;
   const wake = () => {
     if (!hai.wakes || signal.aborted) return;
+    if (watchers.wakeRead <= watchers.wakeSettled) return;
     if (waking) {
       again = true;
       return;
@@ -317,12 +373,22 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
     waking = (async () => {
       do {
         again = false;
+        // every wake notice read here so far: what the attempt settles, unless it fails
+        const through = watchers.wakeRead;
         let wait = WAKE_RETRY_MS;
-        while (!signal.aborted && (await hai.wake(conversationId, watchers.turn())) === "busy") {
+        let outcome: WakeOutcome = "busy";
+        while (!signal.aborted && (outcome = await hai.wake(conversationId, watchers.turn())) === "busy") {
           await pause(wait, signal);
           wait = Math.min(wait * 2, WAKE_RETRY_MAX_MS);
+          // Another stream here may have been the one holding it, with a turn
+          // that settled these notices: taking the lease again finds nothing.
+          if (through <= watchers.wakeSettled) break;
         }
-      } while (again && !signal.aborted);
+        // A failed turn gives its notices back to wake again, so it settles
+        // nothing: the next stream to open tries once more.
+        if (outcome !== "busy" && outcome !== "failed") watchers.wakeSettled = Math.max(watchers.wakeSettled, through);
+        // asked again meanwhile: only if a notice came that this one didn't settle
+      } while (again && !signal.aborted && watchers.wakeRead > watchers.wakeSettled);
     })()
       .catch((err) => emit({ type: "error", message: (err as Error).message }))
       .finally(() => {
@@ -374,7 +440,10 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
           await sendRevision(n.handle, n.replaces, n.seq);
           after = n.seq;
           markFresh();
-          woken ||= n.kind === "wake";
+          if (n.kind === "wake") {
+            woken = true;
+            watchers.wakeRead = Math.max(watchers.wakeRead, n.seq);
+          }
           continue;
         }
         const event: WireEvent = {
@@ -388,7 +457,10 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
         await write(`id: ${n.seq}\ndata: ${JSON.stringify(event)}\n\n`);
         after = n.seq;
         markFresh();
-        woken ||= n.kind === "wake";
+        if (n.kind === "wake") {
+          woken = true;
+          watchers.wakeRead = Math.max(watchers.wakeRead, n.seq);
+        }
       }
       if (records.length < PAGE || signal.aborted) break;
       page = null;
@@ -432,7 +504,8 @@ async function streamNotices(hai: Hai, req: IncomingMessage, res: ServerResponse
       freshened.then(() => new Promise<void>((resolve) => setTimeout(resolve, POLL_GATHER_MS))),
       new Promise<void>((resolve) => (hold = setTimeout(resolve, holdMs))),
     ]);
-    void run().catch(() => {});
+    // a read that fails ends nothing early: the poll answers at its hold
+    void run().catch((err) => console.error("[haikit] events poll failed:", err));
     await done;
     clearTimeout(hold);
   } finally {
@@ -486,6 +559,21 @@ interface Watchers {
   leave: () => void;
   /** Settles once this process is listening for other processes' turns. */
   ready: Promise<void>;
+  /**
+   * The highest seq of a wake notice any stream here has read from the store,
+   * whether or not an attempt has settled it yet: a stream that resumes past
+   * it, reading nothing, still knows it's there. 0 until one is read.
+   */
+  wakeRead: number;
+  /**
+   * The highest wake notice seq a wake attempt here has settled: it woke,
+   * found nothing to do, or was held back by `maxWakes`. A stream makes an
+   * attempt only while `wakeRead` is past it. -1 until the first, so the first
+   * stream this process opens for the conversation looks once, for an update
+   * notice a revision still owes. Both come from the store, never from what a
+   * browser says it has seen, since every stream here shares them.
+   */
+  wakeSettled: number;
 }
 
 /** Fold a wake turn's frame into what it has shown so far. */
@@ -637,6 +725,8 @@ function watchersOf(hai: Hai, conversationId: string): Watchers {
         lingering.unref?.();
       },
       ready: Promise.resolve(),
+      wakeRead: 0,
+      wakeSettled: -1,
       // A wake turn running here: its frames to this process's streams, and,
       // through the store, to every other process's. All but `context`, the
       // whole history, which another tab gets with its own next request.
@@ -752,8 +842,11 @@ function openSSE(res: ServerResponse): Emit {
   };
 }
 
-async function readJson(req: IncomingMessage): Promise<any> {
+/** The request body, as a JSON object; anything else, or a body that fails to arrive, throws. */
+async function readJson(req: IncomingMessage): Promise<Record<string, any>> {
   const chunks: Buffer[] = [];
   for await (const chunk of req) chunks.push(chunk as Buffer);
-  return JSON.parse(Buffer.concat(chunks).toString() || "{}");
+  const body: unknown = JSON.parse(Buffer.concat(chunks).toString() || "{}");
+  if (!body || typeof body !== "object" || Array.isArray(body)) throw new TypeError("not a JSON object");
+  return body as Record<string, any>;
 }

package/src/runtime.ts

@@ -201,6 +201,13 @@ export class Hai {
   private readonly surfaceNames = new Map<string, Map<string, string>>();
   /** What the model gets as its system prompt: the app's, then the scope. */
   readonly system: string;
+  /**
+   * Block ids: this Hai's own random part, then a count. The browser matches
+   * blocks by id for a whole conversation, across POST responses and the
+   * events stream, which another server, or this one restarted, may have
+   * sent: a count alone would repeat there, and a new block overwrite an old.
+   */
+  private readonly blockIds = globalThis.crypto.randomUUID().replaceAll("-", "");
   private seq = 0;
 
   constructor(config: HaiConfig) {
@@ -770,7 +777,7 @@ export class Hai {
   }
 
   private nid(prefix: string) {
-    return `${prefix}_${++this.seq}`;
+    return `${prefix}_${this.blockIds}_${++this.seq}`;
   }
 
   // ───────────────────────────────────────────────── derived tool

package/src/store.ts

@@ -9,6 +9,28 @@ import {
 
 const LEASE_MS = 120_000;
 
+/**
+ * Postgres refuses U+0000 anywhere in text or jsonb, and a lone UTF-16
+ * surrogate in jsonb, so pgStore makes them storable as it saves. This store
+ * does the same, so development sees what production would store. Each
+ * becomes U+FFFD, the replacement character, in strings and object keys
+ * alike.
+ */
+const UNSTORABLE = /\u0000|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+const MAYBE_UNSTORABLE = /[\u0000\uD800-\uDFFF]/;
+const storable = (s: string): string => (MAYBE_UNSTORABLE.test(s) ? s.replace(UNSTORABLE, "\uFFFD") : s);
+/** A `JSON.stringify` replacer that makes every string and key storable. */
+function storableJson(_key: string, value: unknown): unknown {
+  if (typeof value === "string") return storable(value);
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const keys = Object.keys(value);
+    if (keys.some((k) => MAYBE_UNSTORABLE.test(k))) {
+      return Object.fromEntries(keys.map((k) => [storable(k), (value as Record<string, unknown>)[k]]));
+    }
+  }
+  return value;
+}
+
 export interface MemoryStoreOptions {
   /**
    * Turn lease TTL. A process that dies mid-turn strands the conversation for
@@ -60,7 +82,8 @@ export function memoryStore(options: MemoryStoreOptions = {}): StoreAdapter {
   let convSeq = 0;
   let handleSeq = 0;
 
-  const copy = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T;
+  // and anything Postgres can't store comes back as pgStore would return it
+  const copy = <T>(value: T): T => JSON.parse(JSON.stringify(value, storableJson)) as T;
   const newToken = () => globalThis.crypto.randomUUID();
 
   /** Every durable mutation presents the token it was issued. A holder that has