@camelai/run 0.0.0 → 0.11.0

package/dist/clients/chat.js

@@ -0,0 +1,633 @@
+/**
+ * A chat with one agent, for any UI framework: the agent's messages as simple typed parts, its status,
+ * the input it waits on, and the actions (send, answer, stop, loadOlder), over your server's agent
+ * handler (`createAgentHandler`) and the browser watcher. No dependencies and no Node APIs.
+ *
+ *   const chat = createAgentChat({ endpoint: "/api/agent" });
+ *   chat.subscribe(() => render(chat.getSnapshot()));
+ *   await chat.send("Where is my order?");
+ *
+ * The snapshot is immutable, and a message or part that did not change is the same object from one
+ * snapshot to the next, so a UI re-renders only what changed (and keys rows by `id`: a sent message
+ * keeps its id when the agent's copy of it arrives).
+ */
+import { watchAgent } from "./watch.js";
+// ---------------------------------------------------------------------------------------------
+// Answers
+/** An answer to `input` from a plain value (see InputValue). */
+export function answerValue(input, value) {
+    switch (input.kind) {
+        case "approval":
+        case "url":
+            if (typeof value !== "boolean")
+                throw new Error(`Answer ${input.kind === "approval" ? "an approval" : "a url step"} with true or false`);
+            return { action: value ? "accept" : "decline" };
+        case "question": {
+            const questions = (input.detail?.questions ?? []);
+            if (typeof value === "string" || Array.isArray(value)) {
+                if (questions.length !== 1)
+                    throw new Error(`This input asks ${questions.length} questions: answer with { "<question>": "<answer>" } for each`);
+                return { action: "accept", content: { answers: { [questions[0].question]: value } } };
+            }
+            if (typeof value !== "object" || value === null)
+                throw new Error("Answer a question with the label chosen, or a map of question to answer");
+            return { action: "accept", content: { answers: value } };
+        }
+        case "form":
+            if (typeof value !== "object" || value === null || Array.isArray(value))
+                throw new Error("Answer a form with its fields, as an object");
+            return { action: "accept", content: value };
+        default:
+            throw new Error(`Unknown input kind: ${String(input.kind)}`);
+    }
+}
+const isAnswer = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && ["accept", "decline", "cancel"].includes(value.action) && Object.keys(value).every(key => key === "action" || key === "content");
+const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const same = (a, b) => a.length === b.length && a.every((value, at) => value === b[at]);
+const textOfContent = (content) => typeof content === "string" ? content
+    : Array.isArray(content) ? content.map(part => part?.type === "text" && typeof part.text === "string" ? part.text : "").join("") : "";
+/** A tool result that stands in while its call waits on a person: the call is not done. */
+const isInputPlaceholder = (result) => isRecord(result?.details) && !!result.details.inputRequired;
+/** Whether a turn's last message hands off to tools (the turn goes on) rather than ending it. */
+const continuesTurn = (message) => message?.role === "toolResult" || (message?.role === "assistant" && message.stopReason === "toolUse");
+const isPresentFile = (name) => name === "present_file" || name.endsWith("__present_file");
+const baseName = (path) => path.split("/").filter(Boolean).pop() ?? path;
+function parseJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed || !"{[\"".includes(trimmed[0]) && !/^(true|false|null|-?\d)/.test(trimmed))
+        return undefined;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return undefined;
+    }
+}
+function progressOf(update) {
+    if (update === undefined)
+        return undefined;
+    const details = isRecord(update) && isRecord(update.details) ? update.details : undefined;
+    const text = isRecord(update) ? textOfContent(update.content) : typeof update === "string" ? update : "";
+    const out = {};
+    if (details?.type === "progress") {
+        if (typeof details.progress === "number")
+            out.progress = details.progress;
+        if (typeof details.total === "number")
+            out.total = details.total;
+        if (typeof details.message === "string")
+            out.message = details.message;
+    }
+    if (text)
+        out.text = text;
+    return out;
+}
+/** Reuse `previous` when `next` has the same fields (compared with ===, arrays element by element). */
+function reuse(previous, next) {
+    if (!previous)
+        return next;
+    const a = previous, b = next;
+    const keys = Object.keys(b);
+    if (keys.length !== Object.keys(a).length)
+        return next;
+    for (const key of keys) {
+        const x = a[key], y = b[key];
+        if (x === y)
+            continue;
+        if (Array.isArray(x) && Array.isArray(y) && same(x, y))
+            continue;
+        return next;
+    }
+    return previous;
+}
+/**
+ * The chat's messages from the agent's (a watcher's view) and the ones sent from here:
+ * - a user message is one message, with the id it was sent with (its `requestId`), so the bubble
+ *   shown when it was sent is the same row once it arrives;
+ * - everything the agent did between two user messages is one assistant message, each tool result
+ *   folded into its call's part;
+ * - a running turn continues the last one only when that one called tools; otherwise it is a new
+ *   message at the index its first message will take, from its first token (never an empty row);
+ * - a message or part whose sources did not change is the same object as last time (`memo`).
+ */
+export function projectMessages(input, memo = new Map()) {
+    const { messages, indexes } = input;
+    const results = new Map();
+    for (const message of messages)
+        if (message.role === "toolResult")
+            results.set(message.toolCallId, message);
+    const inputs = new Map();
+    for (const pending of input.inputs ?? [])
+        inputs.set(pending.toolCallId, pending);
+    const echoed = new Set();
+    for (const message of messages)
+        if (message.role === "user" && typeof message.requestId === "string")
+            echoed.add(message.requestId);
+    const local = (input.local ?? []).filter(send => !echoed.has(send.id));
+    const groups = [];
+    let open = null;
+    messages.forEach((message, position) => {
+        const index = indexes[position] ?? position;
+        if (message.role === "user") {
+            open = null;
+            groups.push({ kind: "user", index, message });
+            return;
+        }
+        if (message.role !== "assistant")
+            return;
+        if (!open) {
+            open = { kind: "turn", index, assistants: [] };
+            groups.push(open);
+        }
+        open.assistants.push(message);
+    });
+    // The turn streaming now (see above). Sends of ours still on their way come first.
+    const pendingSends = local.filter(send => send.status !== "failed").length;
+    let streaming = null;
+    if (input.partial || input.running) {
+        const last = groups.at(-1);
+        if (last?.kind === "turn" && continuesTurn(messages.at(-1)) && (input.partial || !pendingSends))
+            streaming = last;
+        // A run with nothing streaming yet gets no row: an empty one would flash (after a finished answer,
+        // before the run ends) or land above a message still on its way.
+        else if (input.partial) {
+            const next = (indexes.length ? indexes[indexes.length - 1] + 1 : 0) + pendingSends;
+            streaming = { kind: "turn", index: next, assistants: [] };
+            groups.push(streaming);
+        }
+    }
+    const out = [];
+    const nextMemo = new Map();
+    // Each value is kept with what it was built from, and the values built inside it (a message's
+    // parts), which a message reused as a whole carries forward.
+    let collector = null;
+    const carry = (id, entry) => {
+        nextMemo.set(id, entry);
+        for (const child of entry.children) {
+            const kept = memo.get(child);
+            if (kept)
+                carry(child, kept);
+        }
+    };
+    const remember = (id, sources, build) => {
+        collector?.push(id);
+        const previous = memo.get(id);
+        if (previous && same(previous.sources, sources)) {
+            carry(id, previous);
+            return previous.value;
+        }
+        const outer = collector, children = [];
+        collector = children;
+        let built;
+        try {
+            built = build();
+        }
+        finally {
+            collector = outer;
+        }
+        const value = reuse(previous?.value, built);
+        nextMemo.set(id, { sources, value, children });
+        return value;
+    };
+    for (const group of groups) {
+        if (group.kind === "user") {
+            const message = group.message;
+            const id = typeof message.requestId === "string" && message.requestId ? message.requestId : `m:${group.index}`;
+            out.push(remember(id, [message, group.index], () => userMessage(id, message, group.index)));
+            continue;
+        }
+        const id = `t:${group.index}`;
+        const isStreaming = group === streaming;
+        const partial = isStreaming ? input.partial : null;
+        // What the turn is built from: its messages, their calls' results, inputs, progress and file links.
+        const sources = [isStreaming, partial, ...group.assistants];
+        for (const assistant of [...group.assistants, ...(partial ? [partial] : [])]) {
+            for (const block of assistant.content) {
+                if (block?.type !== "toolCall")
+                    continue;
+                sources.push(results.get(block.id), inputs.get(block.id), input.progress?.get(block.id));
+                if (isPresentFile(block.name) && typeof block.arguments?.path === "string")
+                    sources.push(input.files?.get(block.arguments.path));
+            }
+        }
+        out.push(remember(id, sources, () => {
+            const parts = [];
+            let ordinal = 0;
+            const all = [...group.assistants, ...(partial ? [partial] : [])];
+            for (const assistant of all) {
+                const live = assistant === partial;
+                const count = assistant.content.length;
+                assistant.content.forEach((block, at) => {
+                    if (!block)
+                        return;
+                    const position = ordinal++;
+                    // Only the last block of the message streaming now is still being written.
+                    const writing = live && at === count - 1;
+                    const partId = `${id}:${position}`;
+                    if (block.type === "text") {
+                        if (block.text)
+                            parts.push(remember(partId, [block, writing], () => ({ type: "text", id: partId, text: block.text, streaming: writing })));
+                    }
+                    else if (block.type === "thinking") {
+                        if (block.redacted)
+                            parts.push(remember(partId, [block, writing], () => ({ type: "reasoning", id: partId, text: "", streaming: writing, redacted: true })));
+                        else if (block.thinking)
+                            parts.push(remember(partId, [block, writing], () => ({ type: "reasoning", id: partId, text: block.thinking, streaming: writing })));
+                    }
+                    else if (block.type === "toolCall") {
+                        const callId = typeof block.id === "string" && block.id ? block.id : partId;
+                        const result = results.get(callId);
+                        const pending = inputs.get(callId);
+                        const progress = input.progress?.get(callId);
+                        const name = String(block.name ?? "");
+                        const args = isRecord(block.arguments) ? block.arguments : {};
+                        if (isPresentFile(name) && typeof args.path === "string" && result && !result.isError && !isInputPlaceholder(result)) {
+                            const url = input.files?.get(args.path);
+                            parts.push(remember(`${id}:${callId}:file`, [block, result, url], () => fileAt(callId, args, result, url)));
+                            return;
+                        }
+                        parts.push(remember(`${id}:${callId}`, [block, result, pending, progress, writing], () => toolAt(callId, name, args, result, pending, progress, writing)));
+                    }
+                });
+            }
+            const last = group.assistants.at(-1);
+            const message = { id, role: "assistant", parts, createdAt: group.assistants[0]?.timestamp ?? partial?.timestamp ?? 0, streaming: isStreaming };
+            if (!isStreaming && last) {
+                if (last.stopReason === "aborted")
+                    message.stopReason = "aborted";
+                else if (last.stopReason === "error") {
+                    message.stopReason = "error";
+                    if (last.errorMessage)
+                        message.error = last.errorMessage;
+                }
+                else
+                    message.stopReason = "stop";
+            }
+            return message;
+        }));
+    }
+    for (const send of local) {
+        out.push(remember(send.id, [send], () => ({
+            id: send.id, role: "user", parts: [{ type: "text", id: `${send.id}:0`, text: send.text, streaming: false }], text: send.text,
+            createdAt: send.createdAt, status: send.status, ...(send.error ? { error: send.error } : {}),
+        })));
+    }
+    memo.clear();
+    for (const [key, value] of nextMemo)
+        memo.set(key, value);
+    return out;
+}
+function userMessage(id, message, index) {
+    const parts = [];
+    const content = message.content;
+    if (typeof content === "string") {
+        if (content)
+            parts.push({ type: "text", id: `${id}:0`, text: content, streaming: false });
+    }
+    else
+        content.forEach((block, at) => {
+            if (block.type === "text" && block.text)
+                parts.push({ type: "text", id: `${id}:${at}`, text: block.text, streaming: false });
+            else if (block.type === "image")
+                parts.push({ type: "image", id: `${id}:${at}`, url: `data:${block.mimeType};base64,${block.data}`, mimeType: block.mimeType });
+        });
+    return {
+        id, role: "user", parts, text: textOfContent(content), createdAt: message.timestamp ?? 0, status: "sent", index,
+        ...(message.from ? { from: message.from } : {}), ...(message.metadata ? { metadata: message.metadata } : {}),
+    };
+}
+function toolAt(id, name, args, result, pending, progress, writing) {
+    const part = { type: "tool", id, name, args, state: "running" };
+    if (result && !isInputPlaceholder(result)) {
+        const text = textOfContent(result.content);
+        const data = parseJson(text);
+        part.state = result.isError ? "error" : "done";
+        part.result = { text, content: result.content, ...(result.details !== undefined ? { details: result.details } : {}), ...(data !== undefined ? { data } : {}) };
+        return part;
+    }
+    if (pending) {
+        part.state = "input_required";
+        part.input = pending;
+    }
+    else if (result)
+        part.state = "input_required";
+    else if (writing)
+        part.state = "input_streaming";
+    const shown = progressOf(progress);
+    if (shown)
+        part.progress = shown;
+    return part;
+}
+function fileAt(callId, args, result, url) {
+    const data = parseJson(textOfContent(result.content));
+    const path = typeof data?.path === "string" ? data.path : args.path;
+    return {
+        type: "file", id: `${callId}:file`, toolCallId: callId, path, name: baseName(path),
+        ...(typeof data?.contentType === "string" ? { contentType: data.contentType } : {}),
+        ...(typeof data?.size === "number" ? { size: data.size } : {}),
+        ...(typeof args.caption === "string" ? { caption: args.caption } : {}),
+        ...(url ? { url } : {}),
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// The store
+/**
+ * Where the watcher reads the agent: the runtime (with the browser token), or, when the handler proxies
+ * reads, the handler itself (under the thread's path), with the chat's own headers and credentials.
+ */
+export function readsFrom(minted, endpoint, thread, doFetch, headers, credentials) {
+    if (!minted.proxy)
+        return { url: minted.url, fetch: doFetch };
+    const base = `${endpoint.replace(/\/+$/, "")}${thread ? `/threads/${encodeURIComponent(thread)}` : ""}`;
+    return {
+        url: base,
+        fetch: async (input, init = {}) => {
+            const own = typeof headers === "function" ? await headers() : headers ?? {};
+            // The watcher's Authorization is a placeholder here: the handler adds the real token, and yours goes instead.
+            const merged = { ...init.headers, ...own };
+            if (!own.Authorization && !own.authorization)
+                delete merged.Authorization;
+            return doFetch(input, { ...init, headers: merged, credentials: credentials ?? "same-origin" });
+        },
+    };
+}
+const newId = () => `cm_${globalThis.crypto.randomUUID().replace(/-/g, "")}`;
+const EMPTY = { status: "connecting", messages: [], inputs: [], error: null, hasOlder: false, connected: false, agentId: null };
+/** A chat with the user's agent, through your agent handler: see `AgentChatOptions` and `ChatSnapshot`. */
+export function createAgentChat(options) {
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const listeners = new Set();
+    let snapshot = EMPTY;
+    let view = null;
+    let watcher = null;
+    let generation = 0;
+    let agentId = null;
+    let error = null;
+    let fatal = false;
+    let destroyed = false;
+    let local = [];
+    const answering = new Map();
+    const files = new Map();
+    let fileUrls = new Map();
+    const memo = new Map();
+    let scheduled = false;
+    function toError(value, fallback = "request_failed") {
+        if (isRecord(value) && typeof value.code === "string" && typeof value.message === "string")
+            return value;
+        return { code: fallback, message: value instanceof Error ? value.message : String(value) };
+    }
+    function report(value) { error = value; options.onError?.(value); schedule(); }
+    /** A call to the handler: its JSON, or a ChatError. */
+    async function call(action, body = {}) {
+        const extra = typeof options.headers === "function" ? await options.headers() : options.headers ?? {};
+        let response;
+        try {
+            response = await doFetch(options.endpoint, {
+                method: "POST", credentials: options.credentials ?? "same-origin",
+                headers: { "Content-Type": "application/json", ...extra },
+                body: JSON.stringify({ action, ...(options.thread !== undefined ? { thread: options.thread } : {}), ...body }),
+            });
+        }
+        catch (cause) {
+            throw { code: "network_error", message: `Could not reach ${options.endpoint}: ${cause.message}` };
+        }
+        const value = await response.json().catch(() => ({}));
+        if (!response.ok) {
+            const failure = typeof value.error === "object" ? value.error : { message: typeof value.error === "string" ? value.error : undefined };
+            throw { code: failure?.code ?? `http_${response.status}`, message: failure?.message ?? `${options.endpoint}: HTTP ${response.status}`, status: response.status };
+        }
+        return value;
+    }
+    function compute() {
+        const inputs = (view?.pendingInputs ?? []).map(input => {
+            const state = answering.get(input.id);
+            return state === undefined ? { ...input, answering: false } : { ...input, answering: state === null, ...(state ? { error: state } : {}) };
+        });
+        // Keep input objects stable while nothing about them changed.
+        const previousInputs = new Map(snapshot.inputs.map(input => [input.id, input]));
+        const stableInputs = inputs.map(input => reuse(previousInputs.get(input.id), input));
+        const now = Date.now();
+        const links = new Map();
+        for (const [path, link] of files)
+            if (!link.expiresAt || link.expiresAt > now + 30_000)
+                links.set(path, link.url);
+        if (links.size !== fileUrls.size || [...links].some(([path, url]) => fileUrls.get(path) !== url))
+            fileUrls = links;
+        const messages = projectMessages({
+            messages: view?.messages ?? [], indexes: view?.indexes ?? [], partial: view?.partial ?? null, progress: view?.progress,
+            running: view?.running ?? false, inputs: stableInputs, local, files: fileUrls,
+        }, memo);
+        const waiting = local.some(send => send.status !== "failed");
+        // A run whose answer just ended is still finishing: not a new wait.
+        const last = messages.at(-1);
+        const streaming = messages.some(message => message.role === "assistant" && message.streaming) || (!!view?.running && !waiting && last?.role === "assistant");
+        const status = fatal ? "error"
+            : streaming ? "streaming"
+                : waiting || view?.running ? "submitted"
+                    : stableInputs.some(input => !input.answering) ? "input_required"
+                        : !view?.transport ? "connecting"
+                            : "ready";
+        const next = { status, messages, inputs: stableInputs, error, hasOlder: view?.hasOlder ?? false, connected: view?.connected ?? false, agentId };
+        return reuse(snapshot, next);
+    }
+    function emit() {
+        scheduled = false;
+        const next = compute();
+        if (next === snapshot)
+            return;
+        snapshot = next;
+        for (const listener of [...listeners])
+            listener();
+    }
+    function schedule() {
+        if (scheduled)
+            return;
+        scheduled = true;
+        queueMicrotask(emit);
+    }
+    /** The generation whose token is being fetched, so a second connect() meanwhile does not start another. */
+    let connecting = null;
+    function connect() {
+        if (destroyed || watcher || connecting === generation)
+            return;
+        const mine = ++generation;
+        connecting = mine;
+        fatal = false;
+        void (async () => {
+            let minted;
+            // A refusal (not signed in, not allowed) stops here; anything else is tried again, backing off.
+            for (let backoff = 1000;; backoff = Math.min(backoff * 2, 30_000)) {
+                try {
+                    minted = await call("token");
+                    break;
+                }
+                catch (cause) {
+                    if (mine !== generation)
+                        return;
+                    const failure = toError(cause);
+                    if (failure.status && failure.status < 500 && failure.status !== 429) {
+                        fatal = true;
+                        connecting = null;
+                        report(failure);
+                        return;
+                    }
+                    report(failure);
+                    await new Promise(resolve => setTimeout(resolve, backoff));
+                    if (mine !== generation)
+                        return;
+                }
+            }
+            // Disconnected (or destroyed) while the token was on its way, or superseded by a later connect: stop here.
+            if (mine !== generation || destroyed)
+                return;
+            connecting = null;
+            try {
+                agentId = minted.agentId;
+                watcher?.close();
+                watcher = watchAgent({
+                    ...options.watch, ...readsFrom(minted, options.endpoint, options.thread, doFetch, options.headers, options.credentials),
+                    agentId: minted.agentId, token: minted.token, expiresAt: minted.expiresAt,
+                    getToken: async () => { const renewed = await call("token"); return { token: renewed.token, expiresAt: renewed.expiresAt }; },
+                    onChange: state => {
+                        if (mine !== generation)
+                            return;
+                        view = state;
+                        if (state.expired)
+                            fatal = true;
+                        else if (state.connected && error?.code === "stream_error")
+                            error = null;
+                        // Messages of ours the agent now has are done with.
+                        if (local.length) {
+                            const echoed = new Set(state.messages.flatMap(message => message.role === "user" && typeof message.requestId === "string" ? [message.requestId] : []));
+                            if (local.some(send => echoed.has(send.id)))
+                                local = local.filter(send => !echoed.has(send.id));
+                        }
+                        for (const id of answering.keys())
+                            if (!state.pendingInputs.some(input => input.id === id))
+                                answering.delete(id);
+                        schedule();
+                    },
+                    onEvent: event => {
+                        if (event.type === "file_presented" && event.url)
+                            files.set(event.file.path, { url: event.url, ...(event.expiresAt ? { expiresAt: event.expiresAt } : {}) });
+                        options.onEvent?.(event);
+                    },
+                    onError: cause => { if (mine === generation)
+                        report({ code: "stream_error", message: cause.message }); },
+                });
+                view = watcher.state;
+                schedule();
+            }
+            catch (cause) {
+                if (mine !== generation)
+                    return;
+                fatal = true;
+                report(toError(cause));
+            }
+        })();
+    }
+    function disconnect() {
+        generation++;
+        connecting = null;
+        watcher?.close();
+        watcher = null;
+        if (view) {
+            view = { ...view, connected: false };
+            schedule();
+        }
+    }
+    async function deliver(send) {
+        try {
+            await call("send", { text: send.text, clientId: send.id, ...(send.data !== undefined ? { data: send.data } : {}), ...(send.whileRunning ? { whileRunning: send.whileRunning } : {}) });
+            local = local.map(item => item.id === send.id ? { ...item, status: "sent" } : item);
+            if (error && error.code !== "stream_error")
+                error = null;
+        }
+        catch (cause) {
+            const failure = toError(cause);
+            local = local.map(item => item.id === send.id ? { ...item, status: "failed", error: failure } : item);
+            report(failure);
+        }
+        schedule();
+    }
+    const inputOf = (input) => typeof input === "string" ? snapshot.inputs.find(item => item.id === input) : input;
+    const chat = {
+        getSnapshot: () => snapshot,
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        async send(text, sendOptions = {}) {
+            if (!text.trim())
+                throw new Error("Send some text");
+            const send = {
+                id: newId(), text, createdAt: Date.now(), status: "sending",
+                ...(sendOptions.data !== undefined ? { data: sendOptions.data } : {}),
+                ...(sendOptions.whileRunning ?? options.whileRunning ? { whileRunning: sendOptions.whileRunning ?? options.whileRunning } : {}),
+            };
+            local = [...local, send];
+            emit();
+            await deliver(send);
+            return { id: send.id };
+        },
+        async retry(messageId) {
+            const send = local.find(item => item.id === messageId && item.status === "failed");
+            if (!send)
+                return;
+            const again = { ...send, status: "sending" };
+            delete again.error;
+            local = local.map(item => item.id === messageId ? again : item);
+            emit();
+            await deliver(again);
+        },
+        async answer(target, value) {
+            const input = inputOf(target);
+            if (!input)
+                throw new Error("No such input is pending");
+            const answer = isAnswer(value) ? value : answerValue(input, value);
+            answering.set(input.id, null);
+            emit();
+            try {
+                await call("answer", { inputId: input.id, answer });
+            }
+            catch (cause) {
+                const failure = toError(cause);
+                answering.set(input.id, failure);
+                report(failure);
+                return;
+            }
+            schedule();
+        },
+        decline(target) { return chat.answer(target, { action: "decline" }); },
+        async stop() {
+            try {
+                await call("stop");
+            }
+            catch (cause) {
+                report(toError(cause));
+            }
+        },
+        async loadOlder() {
+            if (!watcher)
+                return false;
+            try {
+                return await watcher.loadOlder();
+            }
+            catch (cause) {
+                report(toError(cause));
+                return false;
+            }
+        },
+        async fileUrl(path) {
+            const known = files.get(path);
+            if (known && (!known.expiresAt || known.expiresAt > Date.now() + 30_000))
+                return known.url;
+            const link = await call("link", { path });
+            files.set(path, { url: link.url, ...(link.expiresAt ? { expiresAt: link.expiresAt } : {}) });
+            schedule();
+            return link.url;
+        },
+        connect,
+        disconnect,
+        destroy() { destroyed = true; disconnect(); listeners.clear(); },
+    };
+    if (options.autoConnect !== false)
+        connect();
+    return chat;
+}