@lumavox/client 0.2.0 → 0.5.0

package/README.md

@@ -80,15 +80,16 @@ 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)`.
 
 | Handler | Frame |
 |---|---|
-| `onReady` `onTurnStart` `onHeard` `onHeardPartial` `onKnowledge` `onMood` `onThought` `onText` `onChunk` `onToolStart` `onToolEnd` `onUsage` `onMuted` `onAudioStart` `onAudioEnd` `onTranscript` `onDone` `onInterrupted` `onError` | the wire's frame, as it is |
+| `onReady` `onTurnStart` `onHeard` `onHeardPartial` `onKnowledge` `onMood` `onThought` `onText` `onChunk` `onToolStart` `onToolEnd` `onToolConfirm` `onUsage` `onMuted` `onAudioStart` `onAudioEnd` `onTranscript` `onDone` `onInterrupted` `onError` | the wire's frame, as it is |
 | `onAudio` | `{ pcm, chunk, turn, sample_rate, channels }`: raw 16-bit PCM, never copied |
 | `onRelation` | the relationship, each change once |
 | `onState` | `connecting` `ready` `busy` `reconnecting` `dormant` `closed` |
@@ -100,6 +101,10 @@ key, dials, authenticates, and from then on:
 With no `onAudio` handler every turn asks for no speech, so nothing pays
 for audio nobody hears; `connect`'s `{ speech }` overrides that.
 
+A tool marked "ask first" sends `tool.confirm` and does not run:
+`confirmTool(callId, yes)` answers with the person's tap — a turn of
+theirs, queued as `send` is, which runs the tool first on a yes.
+
 ### Speaking
 
 ```ts

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.
  *
@@ -140,6 +142,8 @@ export interface ConversationHandlers {
     onChunk?: On<"text.chunk">;
     onToolStart?: On<"tool.start">;
     onToolEnd?: On<"tool.end">;
+    /** A tool that asks first waits for the person: answer with `confirmTool`. */
+    onToolConfirm?: On<"tool.confirm">;
     onUsage?: On<"usage">;
     onMuted?: On<"muted">;
     onAudioStart?: On<"audio.start">;
@@ -236,7 +240,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;
@@ -249,6 +252,12 @@ export declare class Conversation {
      * 1 to 32,000 characters, or it is `dropped: refused` here.
      */
     send(text: string, options?: TurnOptions): Promise<TurnOutcome>;
+    /**
+     * Answer a `tool.confirm` with the person's tap: a turn of theirs — "Yes."
+     * or "No." in the transcript — which runs the tool first on a yes.
+     * Queued as `send` is; never rejects.
+     */
+    confirmTool(callId: string, yes: boolean, options?: TurnOptions): Promise<TurnOutcome>;
     /**
      * Open a recording at `rate`, which must be one of `RECORDING_RATES`.
      * Answers its id. A recording already open is abandoned, as the edge
@@ -277,7 +286,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

@@ -26,6 +26,7 @@ const HANDLER = {
     "text.chunk": "onChunk",
     "tool.start": "onToolStart",
     "tool.end": "onToolEnd",
+    "tool.confirm": "onToolConfirm",
     usage: "onUsage",
     muted: "onMuted",
     "audio.start": "onAudioStart",
@@ -106,7 +107,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 =
@@ -139,6 +139,14 @@ export class Conversation {
         }
         return this.enqueue({ type: "user_message", text }, options);
     }
+    /**
+     * Answer a `tool.confirm` with the person's tap: a turn of theirs — "Yes."
+     * or "No." in the transcript — which runs the tool first on a yes.
+     * Queued as `send` is; never rejects.
+     */
+    confirmTool(callId, yes, options = {}) {
+        return this.enqueue({ type: "tool.confirmed", call_id: callId, yes }, options);
+    }
     /**
      * Open a recording at `rate`, which must be one of `RECORDING_RATES`.
      * Answers its id. A recording already open is abandoned, as the edge
@@ -204,7 +212,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 +258,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 +331,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). */
@@ -686,14 +695,14 @@ export class Conversation {
                 next.resolve(dropped(recording.dropped ?? "closed"));
                 continue;
             }
-            // A message abandons an open recording, at the edge and here.
-            if (next.frame.type === "user_message" && this.open) {
+            // A message or a tap — a turn with no recording of its own — abandons
+            // an open recording, at the edge and here.
+            if (!recording && this.open) {
                 this.abandon("cancelled");
             }
             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 +728,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

@@ -85,11 +85,46 @@ export interface TextChunkFrame extends Frame<"text.chunk">, InTurn {
 export interface ThoughtDeltaFrame extends Frame<"thought.delta">, InTurn {
     text: string;
 }
+/** Who runs a tool: the platform's own, your server's, or your app's. */
+export type ToolKind = "platform" | "webhook" | "app";
+/** The model called a tool; its `tool.end` follows. */
 export interface ToolStartFrame extends Frame<"tool.start">, InTurn {
     name: string;
+    kind: ToolKind;
+    /** Your tool's call, `call_…`; `null` for the platform's own. */
+    call_id: string | null;
 }
+/** A tool's call is over: whether it answered, and how long it took. */
 export interface ToolEndFrame extends Frame<"tool.end">, InTurn {
     name: string;
+    kind: ToolKind;
+    call_id: string | null;
+    ok: boolean;
+    ms: number;
+}
+/**
+ * A tool marked "ask first" waits for the person's yes: the agent asks in
+ * its own words, and `confirmTool(call_id, yes)` answers with a tap.
+ */
+export interface ToolConfirmFrame extends Frame<"tool.confirm">, InTurn {
+    call_id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** One call of your tool in a turn, as `turn.done` and the transcript keep it. */
+export interface ToolCall {
+    call_id: string;
+    name: string;
+    kind: "webhook" | "app";
+    arguments: Record<string, unknown>;
+    /** What it answered, as the model read it (16 KB at most); `null` for none. */
+    result: unknown;
+    ok: boolean;
+    /** What failed, as the model was told; `null` when nothing did. */
+    error: string | null;
+    ms: number;
+    /** Which of the reply's rounds, 1 to 3; 0 for a call the person confirmed with a tap. */
+    round: number;
 }
 export interface KnowledgeEntry {
     entry_id: string;
@@ -157,6 +192,8 @@ export interface TurnDoneFrame extends Frame<"turn.done">, InTurn {
     chunks_spoken: number;
     heard: string | null;
     heard_seconds: number | null;
+    /** Your tools it called, in order. */
+    tool_calls: ToolCall[];
     timings: TurnTimings;
 }
 /** The turn ended early; what was written before it stopped still stands. */
@@ -186,8 +223,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
@@ -206,6 +244,7 @@ export type ServerFrames = Exhaustive<{
     "thought.delta": ThoughtDeltaFrame;
     "tool.start": ToolStartFrame;
     "tool.end": ToolEndFrame;
+    "tool.confirm": ToolConfirmFrame;
     knowledge: KnowledgeFrame;
     "audio.start": AudioStartFrame;
     "audio.end": AudioEndFrame;

package/dist/gen/index.d.ts

@@ -1 +1 @@
-export type { ClientOptions, CompactionInfo, CompactRequest, CompactSessionData, CompactSessionError, CompactSessionErrors, CompactSessionResponse, CompactSessionResponses, CreateSessionData, CreateSessionError, CreateSessionErrors, CreateSessionResponse, CreateSessionResponses, DeleteAllFactsData, DeleteAllFactsError, DeleteAllFactsErrors, DeleteAllFactsResponse, DeleteAllFactsResponses, DeleteFactData, DeleteFactError, DeleteFactErrors, DeleteFactResponse, DeleteFactResponses, DeleteSessionData, DeleteSessionError, DeleteSessionErrors, DeleteSessionResponse, DeleteSessionResponses, ErrorCode, ErrorInfo, ErrorResponse, ExtractSessionFactsData, ExtractSessionFactsError, ExtractSessionFactsErrors, ExtractSessionFactsResponse, ExtractSessionFactsResponses, FactInfo, FactPage, FactsDeleted, GetSessionData, GetSessionError, GetSessionErrors, GetSessionResponse, GetSessionResponses, KnowledgeCitation, KnowledgeLookupInfo, ListFactsData, ListFactsError, ListFactsErrors, ListFactsResponse, ListFactsResponses, ListRelationsData, ListRelationsError, ListRelationsErrors, ListRelationsResponse, ListRelationsResponses, ListSessionsData, ListSessionsError, ListSessionsErrors, ListSessionsResponse, ListSessionsResponses, MessageInfo, MessageKnowledge, MessagePage, RelationInfo, RelationPage, SessionCreateRequest, SessionDetail, SessionInfo, SessionPage, ValidationIssue } from './types.gen.js';
+export type { ClientOptions, CompactionInfo, CompactRequest, CompactSessionData, CompactSessionError, CompactSessionErrors, CompactSessionResponse, CompactSessionResponses, CreateSessionData, CreateSessionError, CreateSessionErrors, CreateSessionResponse, CreateSessionResponses, DeleteAllFactsData, DeleteAllFactsError, DeleteAllFactsErrors, DeleteAllFactsResponse, DeleteAllFactsResponses, DeleteFactData, DeleteFactError, DeleteFactErrors, DeleteFactResponse, DeleteFactResponses, DeleteSessionData, DeleteSessionError, DeleteSessionErrors, DeleteSessionResponse, DeleteSessionResponses, ErrorCode, ErrorInfo, ErrorResponse, ExtractSessionFactsData, ExtractSessionFactsError, ExtractSessionFactsErrors, ExtractSessionFactsResponse, ExtractSessionFactsResponses, FactInfo, FactPage, FactsDeleted, GetSessionData, GetSessionError, GetSessionErrors, GetSessionResponse, GetSessionResponses, KnowledgeCitation, KnowledgeLookupInfo, ListFactsData, ListFactsError, ListFactsErrors, ListFactsResponse, ListFactsResponses, ListRelationsData, ListRelationsError, ListRelationsErrors, ListRelationsResponse, ListRelationsResponses, ListSessionsData, ListSessionsError, ListSessionsErrors, ListSessionsResponse, ListSessionsResponses, MessageInfo, MessageKnowledge, MessagePage, MessageToolCall, RelationInfo, RelationPage, SessionCreateRequest, SessionDetail, SessionInfo, SessionPage, ValidationIssue } from './types.gen.js';

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

@@ -89,6 +89,10 @@ export type MessageInfo = {
      */
     mood_intensity: number | null;
     role: 'user' | 'assistant';
+    /**
+     * On a reply: the calls of your tools it made, in order, each with its arguments and what it answered. Empty when it called none, and on the person's messages.
+     */
+    tool_calls: Array<MessageToolCall>;
 };
 export type MessageKnowledge = {
     lookups: Array<KnowledgeLookupInfo>;
@@ -114,6 +118,40 @@ export type KnowledgeCitation = {
     score: number;
     title: string;
 };
+export type MessageToolCall = {
+    /**
+     * The call's id, `call_…`: what your server or app was sent.
+     */
+    call_id: string;
+    name: string;
+    kind: 'webhook' | 'app';
+    /**
+     * What the model called it with.
+     */
+    arguments: {
+        [key: string]: unknown;
+    };
+    /**
+     * What it answered, as the model read it — its JSON, or its text, cut at 16 KB. Null when it answered nothing.
+     */
+    result?: unknown;
+    /**
+     * It answered in time, with a 2xx or a result.
+     */
+    ok: boolean;
+    /**
+     * What failed, as the model was told — or, for a tool that asks first, that it waited for the person's yes. Null when nothing did.
+     */
+    error: string | null;
+    /**
+     * How long it took.
+     */
+    ms: number;
+    /**
+     * Which of the reply's rounds of calls, 1 to 3; 0 for a call the person confirmed with a tap.
+     */
+    round: number;
+};
 export type RelationInfo = {
     agent_id: string;
     /**
@@ -597,6 +635,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

@@ -1,13 +1,16 @@
 /** The protocol, sent as the WebSocket subprotocol and echoed on `ready`. */
 export declare const PROTOCOL = "ino.v2";
 /** Every frame a client may send; the edge closes on any other (4009). */
-export declare const CLIENT_VERBS: readonly ["auth", "user_message", "user_audio.start", "user_audio.end", "cancel", "mute", "ping"];
+export declare const CLIENT_VERBS: readonly ["auth", "user_message", "user_audio.start", "user_audio.end", "cancel", "mute", "ping", "tool.confirmed"];
 export type ClientVerb = (typeof CLIENT_VERBS)[number];
 /** Every event the edge sends. */
-export declare const SERVER_EVENTS: readonly ["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"];
+export declare const SERVER_EVENTS: readonly ["ready", "turn.start", "heard", "heard.partial", "transcript", "mood", "text.delta", "text.chunk", "thought.delta", "tool.start", "tool.end", "tool.confirm", "knowledge", "audio.start", "audio.end", "muted", "relation", "usage", "turn.done", "interrupted", "error", "pong"];
 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

@@ -5,11 +5,14 @@
 /** The protocol, sent as the WebSocket subprotocol and echoed on `ready`. */
 export const PROTOCOL = "ino.v2";
 /** Every frame a client may send; the edge closes on any other (4009). */
-export const CLIENT_VERBS = ["auth", "user_message", "user_audio.start", "user_audio.end", "cancel", "mute", "ping"];
+export const CLIENT_VERBS = ["auth", "user_message", "user_audio.start", "user_audio.end", "cancel", "mute", "ping", "tool.confirmed"];
 /** Every event the edge sends. */
-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"];
+export const SERVER_EVENTS = ["ready", "turn.start", "heard", "heard.partial", "transcript", "mood", "text.delta", "text.chunk", "thought.delta", "tool.start", "tool.end", "tool.confirm", "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.5.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",