@lumavox/client 0.2.0 → 0.4.0

package/README.md

@@ -80,8 +80,9 @@ key, dials, authenticates, and from then on:
   connection limit, 0.5 s for anything else, ±20 % jitter, final after
   five in a row — and **rests** after the edge hangs up on a quiet
   connection (4007), dialling again on the next `send`;
-- **watches**: 60 s with nothing from the edge is a dead socket, dropped
-  and dialled again;
+- **watches**: it pings after 30 s with nothing from the edge, and a
+  minute with nothing — no `pong` — is a dead socket, dropped and dialled
+  again;
 - publishes `snapshot` — `state`, `ready`, the `turn` (its text, chunks,
   mood, tool, knowledge), `caption`, `relation`, `queued` — with
   `subscribe(fn)`.

package/dist/client.d.ts

@@ -78,14 +78,13 @@ export interface Sessions {
     extract(id: string, options?: RequestOptions): Promise<CompactionInfo>;
 }
 export interface Facts {
+    /** Everything remembered about the person, oldest first, 200 a page. */
+    list(options?: RequestOptions): AsyncGenerator<FactInfo, void, undefined>;
     /**
-     * Everything remembered about the person, oldest first — the newest 100
-     * for now, in one page (left-overs #109); read on by cursor the day the
-     * route pages.
+     * One page of them, 100 by default; `cursor` is the `next_cursor` of the
+     * page before.
      */
-    list(options?: RequestOptions): AsyncGenerator<FactInfo, void, undefined>;
-    /** One page of them, as the route answers it. */
-    page(options?: RequestOptions): Promise<FactPage>;
+    page(options?: RequestOptions, cursor?: string): Promise<FactPage>;
     /** Forget one: `true`, or `false` when it is already gone. */
     delete(id: string, options?: RequestOptions): Promise<boolean>;
     /** Forget everything about the person: how many facts went. Their conversations stay. */

package/dist/client.js

@@ -76,7 +76,7 @@ export function createClient(options) {
     /** One page of the list at `path`. */
     const read = (path, params = {}, request) => send({ method: "GET", path, query: { ...params } }, request);
     const page = (params = {}, request) => read("/v1/agent/sessions", params, request);
-    const factPage = (request, cursor) => read("/v1/agent/facts", { cursor }, request);
+    const factPage = (request, cursor, limit) => read("/v1/agent/facts", { limit, cursor }, request);
     const relationPage = (params = {}, request) => read("/v1/agent/relations", params, request);
     const get = (id, params = {}, request) => send({ method: "GET", path: sessionPath(id), query: { ...params } }, request);
     return {
@@ -102,7 +102,7 @@ export function createClient(options) {
             extract: (id, request) => send({ method: "POST", path: sessionPath(id, "/extract") }, request),
         },
         facts: {
-            list: (request) => pages((cursor) => factPage(request, cursor)),
+            list: (request) => pages((cursor) => factPage(request, cursor, PAGE)),
             page: factPage,
             delete: (id, request) => done(send({ method: "DELETE", path: `/v1/agent/facts/${segment(id)}` }, request)),
             deleteAll: (request) => send({ method: "DELETE", path: "/v1/agent/facts" }, request),

package/dist/conversation.d.ts

@@ -22,10 +22,12 @@
  *   had it — audio sent for it would close the socket (4011).
  * - **Speech is not paid for unheard**: with no `onAudio` handler every
  *   turn says `speech: false`, unless `connect`'s options say otherwise.
- * - **A watchdog, no pings**: the edge sends `pong` after 30 s of client
- *   silence, so 60 s with nothing from it, and nothing said for as long,
- *   is a dead socket (half-open, after a phone changed networks): it is
- *   dropped and dialled again. A ping never resets the edge's idle timer.
+ * - **A watchdog that pings**: after 30 s with nothing from the edge it
+ *   sends `ping` (`KEEPALIVE_PING`, which the edge's runtime answers with
+ *   its object asleep), and past a minute with nothing at all — no `pong`
+ *   to two pings — the socket is dead (half-open, after a phone changed
+ *   networks): it is dropped and dialled again. A ping never resets the
+ *   edge's idle timer.
  * - **The app's handlers cannot break it**: one that throws is rethrown on
  *   its own (`call`), after the state it was told about is in place.
  *
@@ -236,7 +238,6 @@ export declare class Conversation {
     private deadline;
     private watchdog;
     private heardAt;
-    private saidAt;
     constructor(setup: Setup);
     /** What is known now. A new object on every change: compare by identity. */
     get snapshot(): Snapshot;
@@ -277,7 +278,7 @@ export declare class Conversation {
     cancel(): void;
     /** Stop speaking, and let the turn finish: the rest of the reply is never spoken, nor billed. */
     mute(): void;
-    /** Liveness only: answered with `pong`, and never counted as activity. Not needed — the SDK's watchdog listens for the edge's own. */
+    /** Liveness only: answered with `pong`, and never counted as activity. Not needed — the SDK pings after 30 s of silence itself. */
     ping(): void;
     /**
      * Dial now: the app came to the foreground, the network came back. A

package/dist/conversation.js

@@ -106,7 +106,6 @@ export class Conversation {
         this.deadline = null;
         this.watchdog = null;
         this.heardAt = 0;
-        this.saidAt = 0;
         this.sessionId = setup.sessionId;
         this.setup = setup;
         this.speech =
@@ -204,7 +203,6 @@ export class Conversation {
             recording.held.push(data.slice(0));
         else if (recording.socket === this.generation && this.socket) {
             this.socket.sendBinary(data);
-            this.saidAt = Date.now();
         }
         return true;
     }
@@ -251,7 +249,7 @@ export class Conversation {
     mute() {
         this.socket?.send({ type: "mute" });
     }
-    /** Liveness only: answered with `pong`, and never counted as activity. Not needed — the SDK's watchdog listens for the edge's own. */
+    /** Liveness only: answered with `pong`, and never counted as activity. Not needed — the SDK pings after 30 s of silence itself. */
     ping() {
         this.socket?.send({ type: "ping" });
     }
@@ -324,14 +322,16 @@ export class Conversation {
             this.finish(0, "The socket could not be opened.", true, error);
             return;
         }
-        this.heardAt = this.saidAt = Date.now();
+        this.heardAt = Date.now();
         this.socketReady = false;
         this.deadline = setTimeout(() => this.drop(generation, "The connection never became ready."), READY_DEADLINE_MS);
         this.watchdog = setInterval(() => {
-            const quiet = Date.now() - Math.max(this.heardAt, this.saidAt);
+            const quiet = Date.now() - this.heardAt;
             if (quiet > 2 * KEEPALIVE_SECONDS * 1000) {
                 this.drop(generation, "Nothing came from the edge for a minute.");
             }
+            else if (quiet >= KEEPALIVE_SECONDS * 1000)
+                this.ping();
         }, KEEPALIVE_SECONDS * 500);
     }
     /** A socket given up on from this side: lost as a dropped network is (1006). */
@@ -693,7 +693,6 @@ export class Conversation {
             this.inFlight = next;
             next.sent += 1;
             this.socket.send(next.frame);
-            this.saidAt = Date.now();
             this.emit({ turn: FRESH });
         }
         this.emit({ queued: this.queue.length });
@@ -719,7 +718,6 @@ export class Conversation {
     }
     said(recording) {
         recording.socket = this.generation;
-        this.saidAt = Date.now();
     }
     /** A recording's words are still to come: a partial is a caption. */
     listening() {

package/dist/events.d.ts

@@ -186,8 +186,9 @@ export interface ErrorFrame extends Frame<"error"> {
     /** The recording it refused or failed. */
     recording_id: string | null;
 }
-/** The answer to `ping`, and sent unprompted after 30 s of client silence. */
-export interface PongFrame extends Frame<"pong"> {
+/** The answer to `ping`, from the edge's runtime: the one frame with no `seq`. */
+export interface PongFrame {
+    type: "pong";
 }
 /**
  * Every event, by name. **Exhaustive**: a name in the vocabulary with no

package/dist/gen/types.gen.d.ts

@@ -597,6 +597,14 @@ export type ListFactsData = {
          * Optional, and only ever the key's own end user — their `eu_...` id or your own id for them. Anybody else is a 403.
          */
         end_user_id?: string;
+        /**
+         * How many to answer, 1 to 200.
+         */
+        limit?: number;
+        /**
+         * The `next_cursor` of the page before.
+         */
+        cursor?: string;
     };
     url: '/v1/agent/facts';
 };

package/dist/protocol.gen.d.ts

@@ -8,6 +8,9 @@ export declare const SERVER_EVENTS: readonly ["ready", "turn.start", "heard", "h
 export type ServerEventName = (typeof SERVER_EVENTS)[number];
 /** The events that end a turn: exactly one of them ends every turn. */
 export declare const TERMINAL_EVENTS: readonly ["turn.done", "interrupted"];
+/** A `ping` of exactly this text is answered by the edge's runtime with `KEEPALIVE_PONG`, which has no `seq`. */
+export declare const KEEPALIVE_PING = "{\"type\":\"ping\"}";
+export declare const KEEPALIVE_PONG = "{\"type\":\"pong\"}";
 /** The edge's close codes by name: `CLOSE.auth_timeout === 4001`. */
 export declare const CLOSE: {
     readonly auth_timeout: 4001;

package/dist/protocol.gen.js

@@ -10,6 +10,9 @@ export const CLIENT_VERBS = ["auth", "user_message", "user_audio.start", "user_a
 export const SERVER_EVENTS = ["ready", "turn.start", "heard", "heard.partial", "transcript", "mood", "text.delta", "text.chunk", "thought.delta", "tool.start", "tool.end", "knowledge", "audio.start", "audio.end", "muted", "relation", "usage", "turn.done", "interrupted", "error", "pong"];
 /** The events that end a turn: exactly one of them ends every turn. */
 export const TERMINAL_EVENTS = ["turn.done", "interrupted"];
+/** A `ping` of exactly this text is answered by the edge's runtime with `KEEPALIVE_PONG`, which has no `seq`. */
+export const KEEPALIVE_PING = "{\"type\":\"ping\"}";
+export const KEEPALIVE_PONG = "{\"type\":\"pong\"}";
 /** The edge's close codes by name: `CLOSE.auth_timeout === 4001`. */
 export const CLOSE = {
     auth_timeout: 4001,

package/dist/socket.js

@@ -52,15 +52,13 @@ export function dial(options) {
             options.onWarning({ type: "unreadable", what: "text" });
             return;
         }
-        if (typeof frame.seq === "number") {
-            if (lastSeq !== null && frame.seq !== lastSeq + 1) {
-                options.onWarning({
-                    type: "gap",
-                    expected: lastSeq + 1,
-                    got: frame.seq,
-                });
+        // Every frame is numbered but `pong`, the edge's runtime's.
+        const { seq } = frame;
+        if (typeof seq === "number") {
+            if (lastSeq !== null && seq !== lastSeq + 1) {
+                options.onWarning({ type: "gap", expected: lastSeq + 1, got: seq });
             }
-            lastSeq = frame.seq;
+            lastSeq = seq;
         }
         if (frame.type === "audio.start")
             window = frame;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumavox/client",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Talk to Lumavox agents from a browser, a React Native app or Node, with an end user's ephemeral key: conversations on the agent's socket, sessions, memory and relations. Zero dependencies.",
   "license": "MIT",
   "type": "module",