@lumavox/client 0.14.0 → 0.15.1

package/README.md

@@ -91,7 +91,7 @@ key, dials, authenticates, and from then on:
 
 | Handler | Frame |
 |---|---|
-| `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 |
+| `onReady` `onTurnStart` `onHeard` `onHeardPartial` `onKnowledge` `onMood` `onThought` `onText` `onChunk` `onToolStart` `onToolEnd` `onToolConfirm` `onUsage` `onMuted` `onAudioStart` `onAudioEnd` `onTranscript` `onCompacted` `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` |

package/dist/client.d.ts

@@ -80,7 +80,8 @@ export interface Sessions {
 export interface FactListParams {
     /**
      * Also the facts a later conversation replaced or removed, each with
-     * `replaced_at`, until they are deleted 30 days later.
+     * `replaced_at`, until they are deleted — the platform's
+     * `agents.memory.facts.replaced_kept_days` later (its Limits page).
      */
     include_replaced?: boolean;
 }

package/dist/conversation.d.ts

@@ -157,6 +157,8 @@ export interface ConversationHandlers {
     onInterrupted?: On<"interrupted">;
     /** The relationship, from `ready` and when it moves: each change once. */
     onRelation?: (relation: RelationInfo) => void;
+    /** The conversation was compacted, after a reply: its transcript is unchanged. */
+    onCompacted?: On<"compacted">;
     onError?: On<"error">;
     onState?: (state: ConversationState) => void;
     /** Only when it will **not** reconnect. */

package/dist/conversation.js

@@ -33,6 +33,7 @@ const HANDLER = {
     "audio.start": "onAudioStart",
     "audio.end": "onAudioEnd",
     transcript: "onTranscript",
+    compacted: "onCompacted",
     "turn.done": "onDone",
     interrupted: "onInterrupted",
     error: "onError",

package/dist/events.d.ts

@@ -142,7 +142,10 @@ export interface ToolCall {
     name: string;
     kind: "webhook" | "app";
     arguments: Record<string, unknown>;
-    /** What it answered, as the model read it (16 KB at most); `null` for none. */
+    /**
+     * What it answered, as the model read it — at most the platform's
+     * `agents.tools.result_max_bytes` (its Limits page); `null` for none.
+     */
     result: unknown;
     ok: boolean;
     /** What failed, as the model was told; `null` when nothing did. */
@@ -179,6 +182,18 @@ export interface MutedFrame extends Frame<"muted">, InTurn {
 /** The relationship moved on this turn: its new fields. */
 export interface RelationFrame extends Frame<"relation">, InTurn, RelationInfo {
 }
+/**
+ * The conversation was compacted — the agent's own past its threshold, a
+ * pass of a long one, or one asked for — after a reply, never in one: its
+ * next turn starts from a summary through `after_seq`, then the messages
+ * after it word for word. Not part of any turn.
+ */
+export interface CompactedFrame extends Frame<"compacted"> {
+    session_id: string;
+    /** The last message the summary covers. */
+    after_seq: number;
+    trigger: "automatic" | "manual";
+}
 export interface UsageFrame extends Frame<"usage">, InTurn {
     model: string;
     input_tokens: number;
@@ -279,6 +294,7 @@ export type ServerFrames = Exhaustive<{
     "audio.end": AudioEndFrame;
     muted: MutedFrame;
     relation: RelationFrame;
+    compacted: CompactedFrame;
     usage: UsageFrame;
     "turn.done": TurnDoneFrame;
     interrupted: InterruptedFrame;

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

@@ -146,7 +146,7 @@ export type MessageToolCall = {
         [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.
+     * What it answered, as the model read it — its JSON, or its text, cut at the platform's `agents.tools.result_max_bytes` (`GET /v1/platform/limits`). Null when it answered nothing.
      */
     result?: unknown;
     /**
@@ -235,7 +235,7 @@ export type SessionCreateRequest = {
     /**
      * Whether to continue this person's most recent conversation with this agent instead of starting a new one.
      *
-     * **Unset is the useful default**: it resumes when this person has a conversation with this agent from the last 7 days to continue, and starts a new one otherwise. That matches what 'open a conversation with this person' usually means, and it stops an integration that opens a session per page load from scattering somebody's history across a dozen fragments.
+     * **Unset is the useful default**: it resumes when this person has a conversation with this agent young enough to continue — within the organisation's `resume_max_age_days`, else the platform's `agents.sessions.resume_max_age_days` (`GET /v1/platform/limits`) — and starts a new one otherwise. That matches what 'open a conversation with this person' usually means, and it stops an integration that opens a session per page load from scattering somebody's history across a dozen fragments.
      *
      * `false` always starts a new conversation — this is what a 'new chat' button should send. `true` is the same as leaving it unset; it exists so the intent can be stated rather than implied.
      *
@@ -270,7 +270,7 @@ export type SessionInfo = {
 };
 export type CompactionInfo = {
     /**
-     * The last message this summary covers. Anything after it is still sent to the model verbatim.
+     * The last message this summary covers. Anything after it — the last few exchanges, kept word for word, then whatever is said next — is still sent to the model verbatim.
      */
     after_seq: number;
     /**
@@ -289,7 +289,7 @@ export type CompactionInfo = {
      */
     summary: string;
     /**
-     * `manual` (a client asked), `automatic` (a turn reached the agent's threshold) or `idle` (the conversation went quiet and its facts were extracted).
+     * `manual` (a client asked) or `automatic` (a turn reached the agent's threshold, or a long compaction's next pass). `idle` is no longer written: it marks compactions made when a quiet conversation's facts were read, before facts were read on their own.
      */
     trigger: 'manual' | 'automatic' | 'idle';
 };
@@ -553,6 +553,10 @@ export type CompactSessionErrors = {
      * Missing or invalid credentials
      */
     401: ErrorResponse;
+    /**
+     * The key has spent its credit — mint another; nothing was charged
+     */
+    402: ErrorResponse;
     /**
      * The key is valid but its scopes do not cover this capability
      */
@@ -566,7 +570,7 @@ export type CompactSessionErrors = {
      */
     409: ErrorResponse;
     /**
-     * The request failed validation
+     * Nothing new to compact since the last compaction, or the model's summary was empty or no shorter than what it would replace; nothing was charged
      */
     422: ErrorResponse;
     /**
@@ -603,6 +607,10 @@ export type ExtractSessionFactsErrors = {
      * Missing or invalid credentials
      */
     401: ErrorResponse;
+    /**
+     * The key has spent its credit — mint another; nothing was charged
+     */
+    402: ErrorResponse;
     /**
      * The key is valid but its scopes do not cover this capability
      */
@@ -616,7 +624,7 @@ export type ExtractSessionFactsErrors = {
      */
     409: ErrorResponse;
     /**
-     * The request failed validation
+     * Nothing new to compact since the last compaction, or the model's summary was empty or no shorter than what it would replace; nothing was charged
      */
     422: ErrorResponse;
     /**
@@ -686,7 +694,7 @@ export type ListFactsData = {
          */
         end_user_id?: string;
         /**
-         * Also list the facts a later conversation replaced or removed, until they are deleted 30 days later.
+         * Also list the facts a later conversation replaced or removed, until they are deleted, the platform's `agents.memory.facts.replaced_kept_days` later (`GET /v1/platform/limits`).
          */
         include_replaced?: boolean;
         /**

package/dist/protocol.gen.d.ts

@@ -4,7 +4,7 @@ export declare const PROTOCOL = "ino.v2";
 export declare const CLIENT_VERBS: readonly ["auth", "user_message", "user_audio.start", "user_audio.end", "cancel", "mute", "ping", "tool.confirmed", "tool.result"];
 export type ClientVerb = (typeof CLIENT_VERBS)[number];
 /** Every event the edge sends. */
-export declare const SERVER_EVENTS: readonly ["ready", "turn.start", "heard", "heard.partial", "barge_in", "transcript", "mood", "text.delta", "text.chunk", "thought.delta", "tool.start", "tool.end", "tool.call", "tool.confirm", "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", "barge_in", "transcript", "mood", "text.delta", "text.chunk", "thought.delta", "tool.start", "tool.end", "tool.call", "tool.confirm", "knowledge", "audio.start", "audio.end", "muted", "relation", "compacted", "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"];

package/dist/protocol.gen.js

@@ -7,7 +7,7 @@ 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", "tool.confirmed", "tool.result"];
 /** Every event the edge sends. */
-export const SERVER_EVENTS = ["ready", "turn.start", "heard", "heard.partial", "barge_in", "transcript", "mood", "text.delta", "text.chunk", "thought.delta", "tool.start", "tool.end", "tool.call", "tool.confirm", "knowledge", "audio.start", "audio.end", "muted", "relation", "usage", "turn.done", "interrupted", "error", "pong"];
+export const SERVER_EVENTS = ["ready", "turn.start", "heard", "heard.partial", "barge_in", "transcript", "mood", "text.delta", "text.chunk", "thought.delta", "tool.start", "tool.end", "tool.call", "tool.confirm", "knowledge", "audio.start", "audio.end", "muted", "relation", "compacted", "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`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumavox/client",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "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",