@mihe-dev/js 0.0.0-stage → 0.2.0

package/dist/client.js

@@ -0,0 +1,358 @@
+/**
+ * The WebSocket client (doc 02).
+ *
+ * One persistent socket per session carries chat, commands, and
+ * confirmations. Two properties drive the design:
+ *
+ * - A frontend action is a tool call that round-trips through the browser, so
+ *   the runtime pushes a command and blocks until this client acks it. Every
+ *   command MUST be answered, including on failure — an unanswered command
+ *   stalls the assistant's turn until the runtime's timeout fires.
+ * - Confirming an action needs server-to-client push, which is why this is a
+ *   socket rather than a request per message.
+ *
+ * The client owns transport only. It never decides what a command means; the
+ * provider does that and hands back a result.
+ */
+import { PROTOCOL_VERSION, } from "@mihe-dev/protocol";
+const MAX_RECONNECT_DELAY_MS = 30_000;
+export class AssistantClient {
+    options;
+    socket = null;
+    state = "idle";
+    attempt = 0;
+    reconnectTimer = null;
+    heartbeatTimer = null;
+    /** Set when the caller closed deliberately, so we do not reconnect. */
+    stopped = false;
+    conversationId = null;
+    /** Re-sent after every reconnect, so the runtime is never blind to context. */
+    lastScreen = null;
+    constructor(options) {
+        this.options = options;
+    }
+    get connectionState() {
+        return this.state;
+    }
+    async connect() {
+        if (this.state === "connecting" || this.state === "open")
+            return;
+        this.stopped = false;
+        await this.open();
+    }
+    close() {
+        this.stopped = true;
+        this.clearTimers();
+        this.socket?.close();
+        this.socket = null;
+        this.setState("closed");
+    }
+    /** Send a user message. Silently dropped when offline — the widget shows the state. */
+    sendMessage(text, clientMsgId) {
+        this.send({ type: "message", data: { text, clientMsgId } });
+    }
+    /**
+     * Publish the current screen. Idempotent: a full snapshot that replaces
+     * whatever the runtime held.
+     */
+    /**
+     * Tell the runtime where the user is, or that they are somewhere it does not
+     * know about.
+     *
+     * `null` matters as much as a screen. The host app registers the screens it
+     * chooses to; every other page is one the runtime must be told it cannot
+     * see. Left unsaid, the runtime keeps the last screen it heard about, and
+     * the assistant names a page the user left — which is worse than admitting
+     * it does not know, and quietly keeps that screen's scoped actions callable.
+     */
+    updateScreen(screen) {
+        this.lastScreen = screen;
+        this.send({ type: "screen_update", data: { screen } });
+    }
+    /**
+     * Answer a command. Must be called for every command received, including
+     * failures — the runtime is blocking a turn on this.
+     */
+    ackCommand(commandId, ok, result, error) {
+        this.send({
+            type: "command_result",
+            data: {
+                commandId,
+                ok,
+                result: (result ?? null),
+                error: error ?? null,
+            },
+        });
+    }
+    confirmAction(proposalId, confirmed, editedInput) {
+        this.send({
+            type: "action_confirm",
+            data: {
+                proposalId,
+                confirmed,
+                editedInput: (editedInput ?? null),
+            },
+        });
+    }
+    cancelTurn(turnId) {
+        this.send({ type: "cancel", data: { turnId } });
+    }
+    /**
+     * Ask for a permit to open the voice socket.
+     *
+     * Requested on the chat socket rather than fetched over HTTP because this
+     * session is what the permit is scoped to: the runtime hands back a token
+     * bound to the very session actor holding this connection, so the voice
+     * socket joins the conversation already in progress instead of starting a
+     * second one beside it.
+     *
+     * Answered by a `voice_token` event, or by an `error` when voice is not
+     * available for this app — which is the signal to hide the microphone
+     * rather than offer one that fails on the first press.
+     */
+    requestVoiceToken() {
+        this.send({ type: "voice_token_request" });
+    }
+    // ------------------------------------------------------------- internals
+    async open() {
+        this.setState(this.attempt === 0 ? "connecting" : "reconnecting");
+        let token;
+        try {
+            token = await this.options.getUserToken();
+        }
+        catch (cause) {
+            if (this.stopped)
+                return;
+            // The host app's token endpoint is down. Retrying is right — this is
+            // usually transient — but the user should be told why it is quiet.
+            this.emit({
+                type: "error",
+                code: "user_token_unavailable",
+                message: "Could not get a session token from the app.",
+                recoverable: true,
+            });
+            this.scheduleReconnect();
+            return;
+        }
+        // Closed while the token was on its way. Opening anyway left a socket
+        // nothing would ever close: a second live session, which React's
+        // StrictMode made on every development mount by connecting, closing and
+        // connecting again.
+        if (this.stopped)
+            return;
+        const factory = this.options.socketFactory ??
+            ((url) => new WebSocket(url));
+        const socket = factory(this.options.url);
+        this.socket = socket;
+        socket.onopen = () => {
+            const auth = {
+                type: "auth",
+                data: {
+                    publicKey: this.options.publicKey,
+                    userToken: token,
+                    sdkVersion: this.options.sdkVersion,
+                    protocolVersion: PROTOCOL_VERSION,
+                    conversationId: this.conversationId,
+                    ...(this.options.debug ? { debug: true } : {}),
+                },
+            };
+            socket.send(JSON.stringify(auth));
+        };
+        socket.onmessage = (event) => {
+            if (typeof event.data !== "string")
+                return;
+            let message;
+            try {
+                message = JSON.parse(event.data);
+            }
+            catch {
+                return;
+            }
+            this.handle(message);
+        };
+        socket.onclose = () => {
+            this.clearTimers();
+            if (this.stopped) {
+                this.setState("closed");
+                return;
+            }
+            this.scheduleReconnect();
+        };
+        socket.onerror = () => {
+            // `onclose` always follows, and that is where reconnect is handled.
+        };
+    }
+    handle(message) {
+        switch (message.type) {
+            case "auth_ok": {
+                this.attempt = 0;
+                this.conversationId = message.data.conversationId;
+                this.emit({
+                    type: "voice_available",
+                    available: message.data.voiceAvailable ?? false,
+                });
+                // Only when the runtime actually sent one. An older runtime omits the
+                // field, and overwriting a good name with "" would rename the panel to
+                // nothing — worse than leaving the SDK's own default in place.
+                if (message.data.assistantName) {
+                    this.emit({ type: "assistant_name", name: message.data.assistantName });
+                }
+                this.emit({
+                    type: "launcher_icon",
+                    url: message.data.launcherIconUrl ?? null,
+                });
+                this.emit({ type: "widget_settings", settings: message.data.widget ?? null });
+                this.setState("open");
+                this.startHeartbeat(message.data.heartbeatIntervalMs);
+                // The runtime replays nothing, so re-publish context immediately.
+                if (this.lastScreen)
+                    this.updateScreen(this.lastScreen);
+                break;
+            }
+            case "auth_error": {
+                this.emit({
+                    type: "error",
+                    code: message.data.code,
+                    message: message.data.message,
+                    // A bad key or an unsupported protocol version will not fix itself.
+                    recoverable: false,
+                });
+                this.stopped = true;
+                break;
+            }
+            case "auth_expired": {
+                // Re-authenticate in place rather than tearing down the socket.
+                void this.options
+                    .getUserToken()
+                    .then((token) => this.send({
+                    type: "auth",
+                    data: {
+                        publicKey: this.options.publicKey,
+                        userToken: token,
+                        sdkVersion: this.options.sdkVersion,
+                        protocolVersion: PROTOCOL_VERSION,
+                        conversationId: this.conversationId,
+                        ...(this.options.debug ? { debug: true } : {}),
+                    },
+                }))
+                    .catch(() => this.socket?.close());
+                break;
+            }
+            case "turn_start":
+                this.emit({ type: "turn_start", turnId: message.data.turnId });
+                break;
+            case "delta":
+                this.emit({
+                    type: "delta",
+                    turnId: message.data.turnId,
+                    text: message.data.text,
+                });
+                break;
+            case "complete":
+                this.emit({
+                    type: "complete",
+                    turnId: message.data.turnId,
+                    message: message.data.message,
+                    sources: message.data.sources ?? [],
+                });
+                break;
+            case "command":
+                this.emit({
+                    type: "command",
+                    commandId: message.data.commandId,
+                    command: message.data.command,
+                });
+                break;
+            case "action_proposal":
+                this.emit({
+                    type: "proposal",
+                    proposal: message.data,
+                });
+                break;
+            case "action_status":
+                this.emit({
+                    type: "action_status",
+                    proposalId: message.data.proposalId,
+                    status: message.data.status,
+                    result: message.data.result ?? undefined,
+                    error: message.data.error ?? undefined,
+                });
+                break;
+            case "error":
+                this.emit({
+                    type: "error",
+                    code: message.data.code,
+                    message: message.data.message,
+                    recoverable: message.data.recoverable,
+                });
+                break;
+            case "voice_token":
+                this.emit({
+                    type: "voice_token",
+                    token: message.data.token,
+                    expiresAt: message.data.expiresAt,
+                });
+                break;
+            case "context_report":
+                this.emit({ type: "context_report", report: message.data });
+                break;
+            case "pong":
+                break;
+        }
+    }
+    send(message) {
+        if (this.state !== "open" && message.type !== "auth")
+            return;
+        try {
+            this.socket?.send(JSON.stringify(message));
+        }
+        catch {
+            // A send on a closing socket throws; `onclose` handles recovery.
+        }
+    }
+    scheduleReconnect() {
+        this.setState("reconnecting");
+        const delay = this.options.reconnectDelay?.(this.attempt) ?? backoff(this.attempt);
+        this.attempt += 1;
+        this.reconnectTimer = setTimeout(() => void this.open(), delay);
+    }
+    startHeartbeat(intervalMs) {
+        this.clearHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            this.send({ type: "ping" });
+        }, intervalMs);
+    }
+    clearHeartbeat() {
+        if (this.heartbeatTimer !== null) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    clearTimers() {
+        this.clearHeartbeat();
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    setState(state) {
+        if (this.state === state)
+            return;
+        this.state = state;
+        this.emit({ type: "state", state });
+    }
+    emit(event) {
+        this.options.onEvent(event);
+    }
+}
+/**
+ * Exponential backoff with jitter, capped.
+ *
+ * Jitter matters more than it looks: without it, every tab of every customer
+ * reconnects in lockstep after a runtime restart and stampedes it.
+ */
+function backoff(attempt) {
+    const base = Math.min(1000 * 2 ** attempt, MAX_RECONNECT_DELAY_MS);
+    return base / 2 + Math.random() * (base / 2);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../js/src/client.ts"],"names":[],"mappings":"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"}

package/dist/commands.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Executing the commands the runtime sends.
+ *
+ * Every command names a registered target — a route the runtime resolved from
+ * its screen catalogue, or a component key the app declared. Nothing here
+ * takes a CSS selector or a coordinate, so there is no path by which the model
+ * drives the UI directly (spec §5.2).
+ *
+ * Every branch returns a result, including failures, because the runtime is
+ * blocking a turn on the ack and the model needs to learn the truth. Reporting
+ * "the element was not on screen" is far better than reporting nothing.
+ */
+import type { AssistantCommand } from "@mihe-dev/protocol";
+import type { HighlightEngine } from "./highlight.js";
+import type { AssistantStore, QueryParamDeclaration } from "./store.js";
+/** When a frontend action is warned about as slow. */
+export declare const ACTION_SLOW_MS = 5000;
+/**
+ * How long the runtime waits for a command's answer (`COMMAND_ACK_TIMEOUT`
+ * in the runtime's session.rs). Past it, the assistant is told the command
+ * failed.
+ */
+export declare const RUNTIME_ACK_WAIT_MS = 10000;
+export interface CommandResult {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+export interface CommandContext {
+    store: AssistantStore;
+    highlighter: HighlightEngine;
+    /**
+     * How the host app changes route. Supplied by the customer, because only
+     * they know whether that is Next.js's router, React Router, or something
+     * else. Defaults to a full page load, which works everywhere and is
+     * noticeably worse — the docs should push people to wire this up.
+     */
+    navigate: (route: string) => void;
+    /**
+     * Resolves once the screen at `route` has published its context to the
+     * runtime, or `false` if it has not done so within the timeout.
+     *
+     * Navigating is the one command whose effects are not finished when the
+     * function returns: the router swaps the tree, React mounts the destination,
+     * its hooks register, and only then does the new context travel. The runtime
+     * re-reads the screen after every tool call to decide what the next step may
+     * do, so acking before that lands would tell it the user is still on the
+     * screen they just left — and the action they navigated *for* would be
+     * filtered out as off-screen.
+     *
+     * Optional so a hand-built context still works; the provider always supplies
+     * it.
+     */
+    screenPublished?: (route: string, options?: {
+        fresh?: boolean;
+    }) => Promise<boolean>;
+    /**
+     * Resolves once a published screen shows `controlKey` set to `value`, or
+     * `false` if none does within the timeout. A switch is acked only then, for
+     * `screenPublished`'s reason: the runtime's next step reads the screen.
+     */
+    viewPublished?: (controlKey: string, value: string) => Promise<boolean>;
+    /** Opens a registered modal, when the host app has modals to open. */
+    /** Return `false` when the key is not one this app can open. */
+    openModal?: (modalKey: string) => void | boolean;
+}
+/** Why a set of search parameters is not what the table declared, or null. */
+export declare function checkQueryParams(declared: QueryParamDeclaration[], params: Record<string, string>): string | null;
+export declare function executeCommand(command: AssistantCommand, ctx: CommandContext): Promise<CommandResult>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../js/src/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAY,MAAM,SAAS,CAAC;AAE/E,sDAAsD;AACtD,eAAO,MAAM,cAAc,OAAQ,CAAC;AAEpC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,eAAe,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrF;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,sEAAsE;IACtE,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC;CAClD;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,qBAAqB,EAAE,EACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,GAAG,IAAI,CAgBf;AAqBD,wBAAsB,cAAc,CAClC,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,aAAa,CAAC,CAgPxB"}