akanjs 3.0.0-alpha.43 → 3.0.0-alpha.45

package/fetch/client/fetchClient.ts

@@ -81,6 +81,7 @@ export class FetchClient {
   readonly handler: Record<string, FetchHandler>;
   readonly slice: Record<string, SliceMeta> = {};
   readonly sortKeyMap = new Map<string, string[]>();
+  readonly #originWs = new Map<string, WsClient>();
   readonly #handlerStore: Record<string, FetchHandler> = {};
   readonly #handlerFactory = new Map<string, FetchHandlerFactory>();
   #sharedRegistryAppliedVersion = 0;
@@ -95,8 +96,7 @@ export class FetchClient {
   ) {
     this.origin = origin;
     this.http = new HttpClient(origin, ErrorCls);
-    const wsUri = `${origin.replace("http://", "ws://").replace("https://", "wss://")}/ws`;
-    this.ws = new WsClient(wsUri, ErrorCls);
+    this.ws = new WsClient(FetchClient.#makeWsUri(origin), ErrorCls);
     Object.assign(this.#handlerStore, handler);
     this.handler = this.#makeHandlerProxy();
     this.applySignal(serializedSignal);
@@ -158,6 +158,7 @@ export class FetchClient {
     this.ErrorCls = ErrorCls;
     this.http.setErrorConstructor(ErrorCls);
     this.ws.setErrorConstructor(ErrorCls);
+    for (const ws of this.#originWs.values()) ws.setErrorConstructor(ErrorCls);
   }
   applySignal(serializedSignal: { [key: string]: SerializedSignal }, { share = true }: { share?: boolean } = {}) {
     if (share && Object.keys(serializedSignal).length > 0) {
@@ -232,6 +233,8 @@ export class FetchClient {
   }
   disconnect() {
     this.ws.destroy();
+    for (const ws of this.#originWs.values()) ws.destroy();
+    this.#originWs.clear();
   }
   clone({ origin, connect = true, jwt }: { origin?: string; connect?: boolean; jwt?: string } = {}) {
     const instance = new FetchClient(origin ?? this.origin, {}, this.serializedSignal, this.ErrorCls);
@@ -245,6 +248,20 @@ export class FetchClient {
   setJwt(jwt: string | null) {
     this.jwt = jwt;
     this.ws.setJwt(jwt);
+    for (const ws of this.#originWs.values()) ws.setJwt(jwt);
+  }
+
+  #resolveWs(origin?: string) {
+    if (!origin) return this.ws;
+    const target = origin.replace(/\/+$/, "");
+    if (target === this.origin.replace(/\/+$/, "")) return this.ws;
+    const cached = this.#originWs.get(target);
+    if (cached) return cached;
+    const ws = new WsClient(FetchClient.#makeWsUri(target), this.ErrorCls);
+    this.#originWs.set(target, ws);
+    ws.setJwt(this.jwt);
+    ws.connect();
+    return ws;
   }
   #makeAuthHeaders(option?: FetchPolicy): Record<string, string> {
     if (option?.token) return { Authorization: `Bearer ${option.token}` };
@@ -338,13 +355,13 @@ export class FetchClient {
               handleEvent(parsedReturn);
             };
             wrappedListeners.set(handleEvent, wrapped);
-            this.ws.subscribe({
+            const ws = this.#resolveWs(fetchPolicy?.origin);
+            ws.subscribe({
               key,
               data,
               handleEvent: wrapped,
             });
-            return () =>
-              this.ws.unsubscribe({ key, data, handleEvent: wrappedListeners.get(handleEvent) ?? handleEvent });
+            return () => ws.unsubscribe({ key, data, handleEvent: wrappedListeners.get(handleEvent) ?? handleEvent });
           };
         });
         return;
@@ -356,8 +373,9 @@ export class FetchClient {
           const serializerMap = this.#makeArgSerializer(endpoint.args);
           return (...argData: unknown[]) => {
             const args = argData.slice(0, msgArgLength);
+            const fetchPolicy = argData[msgArgLength] as FetchPolicy | undefined;
             const data = msgArgs.map((arg, idx) => serializerMap.get(arg.name)?.(args[idx]) ?? null);
-            this.ws.emit(key, data);
+            this.#resolveWs(fetchPolicy?.origin).emit(key, data);
           };
         });
         this.#setHandlerFactory(`listen${capitalize(key)}`, () => {
@@ -369,8 +387,9 @@ export class FetchClient {
               handleEvent(parsedReturn);
             };
             wrappedListeners.set(handleEvent, wrapped);
-            this.ws.on(key, wrapped);
-            return () => this.ws.off(key, wrappedListeners.get(handleEvent) ?? handleEvent);
+            const ws = this.#resolveWs(fetchPolicy.origin);
+            ws.on(key, wrapped);
+            return () => ws.off(key, wrappedListeners.get(handleEvent) ?? handleEvent);
           }) as FetchHandler;
         });
         return;
@@ -380,6 +399,10 @@ export class FetchClient {
         break;
     }
   }
+  static #makeWsUri(origin: string) {
+    return `${origin.replace("http://", "ws://").replace("https://", "wss://")}/ws`;
+  }
+
   static paginationArgs: SerializedArg[] = [
     { type: "search", name: "skip", refName: "Int" },
     { type: "search", name: "limit", refName: "Int" },

package/fetch/client/wsClient.ts

@@ -41,6 +41,7 @@ export class WsClient {
   #listenerMap = new Map<string, Set<Listener>>();
   #destroyed = false;
   #connectRequested = false;
+  #outbox: string[] = [];
   #unconnectedWarnTimers = new Map<string, ReturnType<typeof setTimeout>>();
   #jwt: string | null = null;
   connected = false;
@@ -94,6 +95,9 @@ export class WsClient {
         const data: WebsocketReqData = { key: option.key, data: option.data, subscribe: true };
         this.#ws?.send(JSON.stringify(data));
       });
+      const queued = this.#outbox;
+      this.#outbox = [];
+      for (const frame of queued) this.#ws?.send(frame);
     };
     this.#ws.onmessage = (e) => {
       try {
@@ -197,6 +201,7 @@ export class WsClient {
     }
     for (const timer of this.#unconnectedWarnTimers.values()) clearTimeout(timer);
     this.#unconnectedWarnTimers.clear();
+    this.#outbox = [];
     this.#ws?.close();
     this.#ws = null;
   }
@@ -240,28 +245,31 @@ export class WsClient {
       `[akanjs] WebSocket is not connected. Call fetch.instance.connect(), or drop the root layout "wsConnect = false", before ${action} "${key}".`,
     );
   }
-  #warnUnconnectedSubscribe(key: string) {
-    if (this.#connectRequested || this.#unconnectedWarnTimers.has(key)) return;
+  #warnUnconnected(action: "emit" | "subscribe", key: string) {
+    const timerKey = `${action}:${key}`;
+    if (this.#connectRequested || this.#unconnectedWarnTimers.has(timerKey)) return;
     const timer = setTimeout(() => {
-      this.#unconnectedWarnTimers.delete(key);
+      this.#unconnectedWarnTimers.delete(timerKey);
       if (this.#connectRequested || this.#destroyed) return;
-      this.#warnNotConnected("subscribe", key);
+      this.#warnNotConnected(action, key);
     }, 0);
-    this.#unconnectedWarnTimers.set(key, timer);
+    this.#unconnectedWarnTimers.set(timerKey, timer);
   }
   emit(key: string, data: WsRequestPayload) {
+    const payload: WebsocketReqData = { key, data: Array.isArray(data) ? data : [data] };
+    const frame = JSON.stringify(payload);
+
     if (this.#ws?.readyState !== WebSocket.OPEN) {
-      this.logger.warn("WebSocket not connected");
-      this.#warnNotConnected("emit", key);
+      this.#outbox.push(frame);
+      this.#warnUnconnected("emit", key);
       return this;
     }
-    const payload: WebsocketReqData = { key, data: Array.isArray(data) ? data : [data] };
-    this.#ws.send(JSON.stringify(payload));
+    this.#ws.send(frame);
     return this;
   }
   subscribe(option: { key: string; data: unknown[]; handleEvent: (data: unknown) => void }) {
     const roomId = WsClient.makeRoomId(option.key, option.data);
-    if (!this.#ws) this.#warnUnconnectedSubscribe(option.key);
+    if (!this.#ws) this.#warnUnconnected("subscribe", option.key);
     if (!this.#roomSubscribeMap.has(roomId)) {
       this.#roomSubscribeMap.set(roomId, { key: option.key, data: option.data, listener: new Set() });
       if (this.#ws?.readyState === WebSocket.OPEN) {

package/fetch/fetchType/endpointFetch.type.ts

@@ -44,7 +44,7 @@ type QueryOrMutationFetchFn<E, SlceCls extends SliceCls | never> = (
 /** Typed off `PromptResult` rather than the endpoint's return ref, which is the `Any` carrier a prompt rides on. */
 type PromptFetchFn<E> = (...args: [...EndpInfoArgs<E>, fetchPolicy?: FetchPolicy]) => Promise<PromptMessage[]>;
 
-type MessageEmitFn<E> = (...args: EndpInfoArgs<E>) => void;
+type MessageEmitFn<E> = (...args: [...EndpInfoArgs<E>, fetchPolicy?: FetchPolicy]) => void;
 
 type MessageListenFn<E, SlceCls extends SliceCls | never> = (
   handleEvent: (data: EndpInfoReturns<E, SlceCls>) => PromiseOrObject<void>,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.43",
+  "version": "3.0.0-alpha.45",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/service/predefinedAdaptor/database.adaptor.ts

@@ -18,6 +18,7 @@ import {
   type DocumentUpdateOptions,
   documentQueryHelper,
   encodeDocumentValue,
+  isDocumentId,
   isDocumentUpdateNode,
   NoDocumentError,
   resolveDocumentUpdate,
@@ -1033,6 +1034,7 @@ export class SqlDocumentStore {
   async create(data: DocumentRecord, { runSaveHooks = true }: WriteHookOptions = {}) {
     const now = Date.now();
     const id = data.id ?? createDocumentId(now);
+    if (!isDocumentId(id)) throw new Error(`Invalid ID value: ${id}`);
     const doc = this.hydrate(
       this.prepareDocument({
         ...data,

package/store/agent/StoreSurfaceSource.ts

@@ -4,7 +4,6 @@ import { AgentBridge } from "./AgentBridge";
 import { ScreenReader } from "./ScreenReader";
 import { ScreenSettle } from "./ScreenSettle";
 import { ScreenTarget } from "./ScreenTarget";
-import { StateWait } from "./StateWait";
 
 /**
  * The tools every akan screen has whatever it declares: where it can go, what it is rendering, what one of the
@@ -39,7 +38,6 @@ export class StoreSurfaceSource implements SurfaceSource {
         StoreSurfaceSource.#goBack(),
         StoreSurfaceSource.#readScreen(viewKey),
         this.#readState(viewKey),
-        this.#waitFor(viewKey),
         StoreSurfaceSource.#highlight(viewKey),
       ];
       this.#builtins.set(viewKey, builtins);
@@ -192,65 +190,6 @@ export class StoreSurfaceSource implements SurfaceSource {
     };
   }
 
-  /**
-   * The wait that costs no model turns.
-   *
-   * An agent that started something slow has one way to learn it finished: ask again, and again, a full round trip
-   * per look. That burns the turn budget in seconds and reads to the user as a loop. This parks the call instead —
-   * the session already awaits `run`, so the turn simply takes as long as the work does, and the change report
-   * that follows carries whatever landed while it waited.
-   *
-   * It watches a published state key rather than sleeping for a fixed span. A bare sleep would only make the
-   * polling slower, and a screen that can report progress at all reports it into the store; a screen that reports
-   * none publishes a key with `st.expose`, which is worth doing anyway, since the key is then readable too.
-   */
-  #waitFor(viewKey: string): ToolEntry {
-    return {
-      name: "waitFor",
-      description:
-        "Wait here until one of this page's state keys settles, instead of asking again and again. Use it after starting something slow — a generation, an upload, a long job — whenever a state key reports how it is going: the turn pauses with no model round trip and resumes the moment the key moves. Keys are listed in the state context block. Returns what the key holds when the wait ends.",
-      parameters: {
-        type: "object",
-        properties: {
-          key: { type: "string", description: "The state key to watch, spelled as the state context block lists it." },
-          equals: {
-            type: "string",
-            description:
-              "Wait until the key reads exactly this, compared as text. Omit to wait until it changes from whatever it holds now.",
-          },
-          timeoutSeconds: {
-            type: "number",
-            description: `How long to wait before answering with the key's current value. Default ${StateWait.defaultSeconds}, maximum ${StateWait.maxSeconds}. Running out is not a failure — call waitFor again to keep waiting.`,
-          },
-        },
-        required: ["key"],
-        additionalProperties: false,
-      },
-
-      effect: "state",
-      run: async (args) => {
-        this.#bridge ??= AgentBridge.of();
-        const key = typeof args.key === "string" ? args.key.trim() : "";
-        if (!key) throw new Error("waitFor needs a key to watch.");
-        const live = this.#bridge.readableKeys(viewKey);
-        if (!live.includes(key))
-          throw new Error(
-            `No state key named ${key} is read by this screen. ${
-              live.length
-                ? `Keys here: ${live.join(", ")}.`
-                : "This screen reads no state keys, so there is nothing to wait for."
-            }`,
-          );
-        return await new StateWait(this.#bridge, {
-          key,
-          viewKey,
-          equals: typeof args.equals === "string" ? args.equals : null,
-          seconds: args.timeoutSeconds,
-        }).run();
-      },
-    };
-  }
-
   /**
    * The ring goes on once the scroll lands, not when it starts: a smooth scroll across a long page takes most of a
    * second, and a flash begun at the top is already fading by the time the user's eye arrives. Settles on the

package/store/agent/index.ts

@@ -7,7 +7,6 @@ export * from "./AgentPrompts";
 export * from "./ScreenReader";
 export * from "./ScreenSettle";
 export * from "./ScreenTarget";
-export * from "./StateWait";
 export * from "./StoreCatalogue";
 export * from "./StoreSurfaceSource";
 export * from "./storeSurface";

package/types/fetch/fetchType/endpointFetch.type.d.ts

@@ -7,7 +7,7 @@ type EndpInfoReturns<E, SlceCls extends SliceCls | never> = EndpointClientReturn
 type QueryOrMutationFetchFn<E, SlceCls extends SliceCls | never> = (...args: [...EndpInfoArgs<E>, fetchPolicy?: FetchPolicy]) => Promise<EndpInfoReturns<E, SlceCls>>;
 /** Typed off `PromptResult` rather than the endpoint's return ref, which is the `Any` carrier a prompt rides on. */
 type PromptFetchFn<E> = (...args: [...EndpInfoArgs<E>, fetchPolicy?: FetchPolicy]) => Promise<PromptMessage[]>;
-type MessageEmitFn<E> = (...args: EndpInfoArgs<E>) => void;
+type MessageEmitFn<E> = (...args: [...EndpInfoArgs<E>, fetchPolicy?: FetchPolicy]) => void;
 type MessageListenFn<E, SlceCls extends SliceCls | never> = (handleEvent: (data: EndpInfoReturns<E, SlceCls>) => PromiseOrObject<void>, options?: FetchPolicy) => () => void;
 type PubsubSubscribeFn<E, SlceCls extends SliceCls | never> = (...args: [
     ...EndpInfoArgs<E>,

package/types/store/agent/index.d.ts

@@ -5,7 +5,6 @@ export * from "./AgentPrompts.d.ts";
 export * from "./ScreenReader.d.ts";
 export * from "./ScreenSettle.d.ts";
 export * from "./ScreenTarget.d.ts";
-export * from "./StateWait.d.ts";
 export * from "./StoreCatalogue.d.ts";
 export * from "./StoreSurfaceSource.d.ts";
 export * from "./storeSurface.d.ts";

package/ui/Agent/useDraftRecall.ts

@@ -18,8 +18,8 @@ const asked = (messages: readonly ChatMessage[], cap: number) =>
 export const useDraftRecall = (messages: readonly ChatMessage[]) => {
   const cap = 30;
   const sent = useRef<string[] | null>(null);
-  
-  const walked = (sent.current ??= asked(messages, cap));
+  if (!sent.current) sent.current = asked(messages, cap);
+  const walked = sent.current;
   const stashed = useRef("");
   const [at, setAt] = useState(0);
   return {

package/store/agent/StateWait.ts

@@ -1,139 +0,0 @@
-import { AgentAbort, AgentProgress } from "../../vendor/use-agentic";
-
-/** The reading half of the store an in-page wait needs. `AgentBridge` is one; a test can be another. */
-export interface StateSource {
-  read(key: string, viewKey?: string): unknown;
-  subscribe(listener: () => void): () => void;
-}
-
-export interface StateWaitOptions {
-  key: string;
-  viewKey?: string;
-  /** Settle when the key reads exactly this. Null waits for it to change from whatever it holds now. */
-  equals?: string | null;
-  /** Straight off the tool argument, so it may be anything; `StateWait.seconds` is what makes it a number. */
-  seconds?: unknown;
-}
-
-/**
- * One `waitFor` call: park until a published state key settles, or until the timeout says how it is going.
- *
- * Two clocks, because neither covers the other. The store's own subscription catches the value changing, which is
- * the whole point of the tool and has to land immediately. The tick catches what the store never announces —
- * `retainLive` / `releaseLive` mutate the live-key map without notifying any listener, so a page navigated away
- * from mid-wait would otherwise hold the turn until the timeout — and the countdown row needs a tick anyway.
- *
- * Nothing here throws on a wait that ran out. A key still reading `generating` after two minutes is an answer, not
- * a failure, and the model is the one that decides whether to wait again.
- */
-export class StateWait {
-  static readonly tickMs = 1000;
-  static readonly defaultSeconds = 120;
-  static readonly maxSeconds = 600;
-
-  /** Clamped rather than refused: a model that asks for an hour gets the longest wait on offer and reads how long. */
-  static seconds(value: unknown): number {
-    if (typeof value !== "number" || !Number.isFinite(value)) return StateWait.defaultSeconds;
-    return Math.min(Math.max(Math.round(value), 1), StateWait.maxSeconds);
-  }
-
-  /** A string is itself; everything else is JSON, so a number, a boolean and null each compare as they are written. */
-  static print(value: unknown): string {
-    if (typeof value === "string") return value;
-    try {
-      return JSON.stringify(value) ?? String(value);
-    } catch {
-      return String(value);
-    }
-  }
-
-  readonly #source: StateSource;
-  readonly #key: string;
-  readonly #viewKey: string;
-  readonly #equals: string | null;
-  readonly #seconds: number;
-  #was = "";
-  #now = "";
-  #elapsed = 0;
-  #settled: boolean = false;
-  #ticker: ReturnType<typeof setInterval> | undefined;
-  #unsubscribe: (() => void) | undefined;
-  #signal: AbortSignal | null = null;
-  #resolve: ((message: string) => void) | null = null;
-  #reject: ((error: Error) => void) | null = null;
-
-  constructor(source: StateSource, { key, viewKey = "", equals = null, seconds }: StateWaitOptions) {
-    this.#source = source;
-    this.#key = key;
-    this.#viewKey = viewKey;
-    this.#equals = equals;
-    this.#seconds = StateWait.seconds(seconds);
-  }
-
-  run(): Promise<string> {
-    this.#was = StateWait.print(this.#source.read(this.#key, this.#viewKey));
-    this.#now = this.#was;
-    if (this.#equals !== null && this.#was === this.#equals)
-      return Promise.resolve(`${this.#key} is already ${this.#was}.`);
-    return new Promise<string>((resolve, reject) => {
-      this.#resolve = resolve;
-      this.#reject = reject;
-      this.#signal = AgentAbort.current;
-      if (this.#signal?.aborted) {
-        this.#abort();
-        return;
-      }
-      this.#signal?.addEventListener("abort", this.#abort);
-      this.#unsubscribe = this.#source.subscribe(this.#check);
-      this.#ticker = setInterval(this.#tick, StateWait.tickMs);
-      AgentProgress.report("", { done: 0, total: this.#seconds });
-    });
-  }
-
-  /** The session races every call against the same signal; honouring it here is what stops the timer. */
-  #abort = () => {
-    this.#stop();
-    this.#reject?.(new Error("The user aborted the turn."));
-  };
-
-  #check = () => {
-    if (this.#settled) return;
-    let now: string;
-    try {
-      now = StateWait.print(this.#source.read(this.#key, this.#viewKey));
-    } catch (error) {
-      
-      this.#end(`Stopped waiting: ${error instanceof Error ? error.message : String(error)}`);
-      return;
-    }
-    this.#now = now;
-    if (this.#equals === null ? now !== this.#was : now === this.#equals) this.#end(`${this.#key} is now ${now}.`);
-  };
-
-  #tick = () => {
-    this.#check();
-    if (this.#settled) return;
-    this.#elapsed += 1;
-    if (this.#elapsed >= this.#seconds) {
-      this.#end(
-        `${this.#key} is still ${this.#now} after ${this.#seconds}s. Call waitFor again to keep waiting, or tell the user it is taking longer than expected.`,
-      );
-      return;
-    }
-    AgentProgress.report("", { done: this.#elapsed, total: this.#seconds });
-  };
-
-  #end(message: string) {
-    this.#stop();
-    this.#resolve?.(message);
-  }
-
-  #stop() {
-    this.#settled = true;
-    clearInterval(this.#ticker);
-    this.#ticker = undefined;
-    this.#unsubscribe?.();
-    this.#unsubscribe = undefined;
-    this.#signal?.removeEventListener("abort", this.#abort);
-  }
-}

package/types/store/agent/StateWait.d.ts

@@ -1,36 +0,0 @@
-/** The reading half of the store an in-page wait needs. `AgentBridge` is one; a test can be another. */
-export interface StateSource {
-    read(key: string, viewKey?: string): unknown;
-    subscribe(listener: () => void): () => void;
-}
-export interface StateWaitOptions {
-    key: string;
-    viewKey?: string;
-    /** Settle when the key reads exactly this. Null waits for it to change from whatever it holds now. */
-    equals?: string | null;
-    /** Straight off the tool argument, so it may be anything; `StateWait.seconds` is what makes it a number. */
-    seconds?: unknown;
-}
-/**
- * One `waitFor` call: park until a published state key settles, or until the timeout says how it is going.
- *
- * Two clocks, because neither covers the other. The store's own subscription catches the value changing, which is
- * the whole point of the tool and has to land immediately. The tick catches what the store never announces —
- * `retainLive` / `releaseLive` mutate the live-key map without notifying any listener, so a page navigated away
- * from mid-wait would otherwise hold the turn until the timeout — and the countdown row needs a tick anyway.
- *
- * Nothing here throws on a wait that ran out. A key still reading `generating` after two minutes is an answer, not
- * a failure, and the model is the one that decides whether to wait again.
- */
-export declare class StateWait {
-    #private;
-    static readonly tickMs = 1000;
-    static readonly defaultSeconds = 120;
-    static readonly maxSeconds = 600;
-    /** Clamped rather than refused: a model that asks for an hour gets the longest wait on offer and reads how long. */
-    static seconds(value: unknown): number;
-    /** A string is itself; everything else is JSON, so a number, a boolean and null each compare as they are written. */
-    static print(value: unknown): string;
-    constructor(source: StateSource, { key, viewKey, equals, seconds }: StateWaitOptions);
-    run(): Promise<string>;
-}