@getfamiliar/plugin-web-chat 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# Web chat plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Chat with familiar in the web UI. The page opens as the start page of the web UI (menu entry "Chat", weight -100) and runs on the chat channel `web`.
+
+Until its first npm release the plugin is `private` and not `familiar.bundled`; enable it by adding `@getfamiliar/plugin-web-chat` to `config/plugins`. It needs the web UI (`web-ui` plugin, `webserver.enabled: true`).
+
+## Features
+
+On par with `familiar cli-chat`, plus what a browser does better:
+
+- **Messages** go to the handler `chat/web.md` (topic `chat:web`, shipped as a workspace template). They run `privileged`, because only logins in `webserver.auth.users` get in.
+- **Direct handler calls**: `/topic/sub …` runs that handler exactly (`/mail/draft to the dentist`). Typing `/` suggests the handlers of your workspace: ↑/↓ to pick, Tab or Enter to complete, Esc to close. An unknown path is refused before anything is sent. A call whose handler writes no chat reply gets its result text as the reply, as in cli-chat.
+- **Live progress** of every message you send, like cli-chat's spinner lines: agentruns (topic, model, state, subagents), each finished step with reasoning, intermediate text and every tool call with its arguments and result. While it runs the trace is open; afterwards it collapses into "Done in N steps, M tool calls" and can be expanded again. Progress is kept for a few minutes, so a reload still shows a turn in flight.
+- **Proactive messages** (`send_chat`, cron handlers) show up live when `core.defaultChatChannel` is `web`. Messages that arrived while no tab was open are part of the history.
+- **Failures** arrive as a chat message ("Something went wrong processing the chat message: …"), and the trace turns red.
+- **History** of the `web` channel with "Earlier messages" paging. Replies are rendered as GitHub-flavored markdown with highlighted, copyable code blocks.
+- **Files in both directions.**
+  - Drop files anywhere on the chat, paste them, or pick them with the paperclip. They show as removable thumbnails above the input and go with the next message, at most 20 files and 50 MB per message.
+  - They land in the event's scratch folder (`/scratch/<event-id>/`), where the assistant reads them. The message text records them as `[Attached: …]`, so the chat history keeps them.
+  - Every file the assistant writes directly into that folder is offered as a download under its reply. Files the user attached are shown with their message instead.
+  - Hidden files (leading `.`, e.g. spilled tool results) are never offered.
+  - The handler `chat/web.md` tells the assistant about this.
+- `/clear` hides the transcript in this view. The assistant keeps its history, as in cli-chat. ↑/↓ on a single-line input walks through your earlier messages. Several tabs stay in sync.
+
+Not (yet) possible:
+- **No stopping a reply.** The core has no cancel for a running event yet.
+- **No voice input.**
+- **No streaming.** A reply appears when it is complete; the progress is visible meanwhile.
+
+## How it works
+
+- `src/host/ChatHub.ts` holds the one chat-bus subscription for the channel `web` and fans it out to every browser tab. The bus marks a message delivered once, so tabs must not subscribe individually. It also sends your input as events (same rules as cli-chat) and tracks their agentruns and steps.
+- `src/host/ChatController.ts` is mounted by the core at `/plugins/web-chat`, behind the web UI authentication:
+  - `GET /api/messages?before=&limit=` returns a history page (`ctx.chat.listMessages`);
+  - `POST /api/messages {text}` sends a line and answers `{ eventId }`, or 400 `{ error }`;
+  - `GET /api/handlers` returns the slash paths for autocompletion;
+  - `POST /api/messages` also takes `multipart/form-data` (`text` plus `files`), checked against the limits;
+  - `GET /api/files/:eventId/:name` downloads a visible scratch file. Only raster images go out inline; everything else is an attachment as `application/octet-stream`, with `nosniff` and a sandboxing CSP, so an uploaded or generated HTML/SVG file can never run as a page of the web UI's origin;
+  - `GET /api/events` is the server-sent events stream (`snapshot`, `message`, `turn`, `files`), with a keep-alive every 25 s;
+  - `GET /page/*` serves the built page module.
+- `src/host/ChatProtocol.ts` holds the wire types, which the page imports type-only.
+- `src/host/ChatFiles.ts` sanitizes upload names and keeps track of which files were uploads: the hidden manifest `.web-chat-uploads.json` in the scratch folder lists them.
+- `src/page.tsx` is the page module the web UI mounts (`mount(container, context)`). Its stylesheet is scoped to the page container with `@scope` (`src/lib/scoped-style.ts`). The web UI and the page each bring a Tailwind build, and unscoped, the page's utilities would override the web UI's (e.g. `.hidden` beating the sidebar's `md:block`). For the same reason the page renders no portals: no Radix tooltips/popovers, use `title` or inline elements instead. The UI is built from the shadcn chatbot template's primitives in `src/components/ui/` (`message`, `message-scroller`, `bubble`, `trace`, `input-group`, `code-block`, `empty`, `alert`; generated by shadcn, excluded from Biome together with `lib/highlighter.tsx` and `hooks/use-highlighted-code.ts`). Our own components live in `src/components/`, the data in `src/hooks/use-chat.ts`.
+
+## Development
+
+In a dev run (`npm run dev -- start`) the web UI loads `src/page.tsx` from source through its Vite server, so edits show up through hot module replacement without losing the chat state. Keep component files free of non-component exports (helpers go to `src/lib/`), or an edit falls back to a full reload. Host-side changes (`src/host/`) need a daemon restart.
+
+`npm run build` compiles the host side to `build/` and bundles the page into `build/page/page.js` (React included; shiki grammars as lazily loaded chunks).

package/build/ChatController.d.ts

@@ -0,0 +1,25 @@
+import { type WebUiEnv } from "@getfamiliar/shared";
+import { type Context, Hono } from "hono";
+import { type ChatHub } from "./ChatHub.js";
+/** Serves the built page module (`build/page`). */
+export interface PageAssetHandler {
+    handle(c: Context): Promise<Response>;
+}
+/**
+ * The web-chat controller, mounted by the core at `/plugins/web-chat`
+ * behind its authentication. Concrete routes only — the page's browser
+ * routes (`/plugins/web-chat`) fall through to the web UI.
+ *
+ * - `GET  /api/messages?before=<id>&limit=<n>` — history page of the web channel
+ * - `POST /api/messages` — send a line: JSON `{ text }`, or `multipart/form-data`
+ *   with `text` and any number of `files` (`{ eventId }`, or 400 / 413 `{ error }`)
+ * - `GET  /api/files/:eventId/:name` — download a file of an event's scratch folder
+ * - `GET  /api/handlers` — slash paths for autocompletion
+ * - `GET  /api/events` — server-sent events (`snapshot`, `message`, `turn`)
+ * - `GET  /page/*` — the page module
+ *
+ * @param hub The chat hub (resolved per request, so a restart swaps it).
+ * @param page Static handler for the built page.
+ * @returns The controller.
+ */
+export declare function buildChatController(hub: () => ChatHub, page: PageAssetHandler): Hono<WebUiEnv>;

package/build/ChatController.js

@@ -0,0 +1,170 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { contentTypeForFile } from "@getfamiliar/shared";
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { streamSSE } from "hono/streaming";
+import { ChatInputError, MAX_HISTORY_PAGE } from "./ChatHub.js";
+import { MAX_UPLOAD_BYTES } from "./ChatProtocol.js";
+/** Room for the multipart framing and the text on top of the attachments. */
+const BODY_OVERHEAD_BYTES = 1024 * 1024;
+/** Default history page size. */
+const DEFAULT_HISTORY_PAGE = 50;
+/** Interval of SSE keep-alive comments (proxies drop idle connections). */
+const KEEP_ALIVE_MS = 25_000;
+/**
+ * The web-chat controller, mounted by the core at `/plugins/web-chat`
+ * behind its authentication. Concrete routes only — the page's browser
+ * routes (`/plugins/web-chat`) fall through to the web UI.
+ *
+ * - `GET  /api/messages?before=<id>&limit=<n>` — history page of the web channel
+ * - `POST /api/messages` — send a line: JSON `{ text }`, or `multipart/form-data`
+ *   with `text` and any number of `files` (`{ eventId }`, or 400 / 413 `{ error }`)
+ * - `GET  /api/files/:eventId/:name` — download a file of an event's scratch folder
+ * - `GET  /api/handlers` — slash paths for autocompletion
+ * - `GET  /api/events` — server-sent events (`snapshot`, `message`, `turn`)
+ * - `GET  /page/*` — the page module
+ *
+ * @param hub The chat hub (resolved per request, so a restart swaps it).
+ * @param page Static handler for the built page.
+ * @returns The controller.
+ */
+export function buildChatController(hub, page) {
+    const app = new Hono();
+    app.get("/api/messages", async (c) => {
+        const before = c.req.query("before");
+        const limit = Number(c.req.query("limit") ?? DEFAULT_HISTORY_PAGE);
+        if (before !== undefined && !/^\d+$/.test(before)) {
+            return c.json({ error: "before must be a message id" }, 400);
+        }
+        if (!Number.isInteger(limit) || limit < 1 || limit > MAX_HISTORY_PAGE) {
+            return c.json({ error: `limit must be between 1 and ${MAX_HISTORY_PAGE}` }, 400);
+        }
+        return c.json(await hub().history(before, limit));
+    });
+    app.post("/api/messages", bodyLimit({
+        maxSize: MAX_UPLOAD_BYTES + BODY_OVERHEAD_BYTES,
+        onError: (c) => c.json({
+            error: `the message is too large; at most ${MAX_UPLOAD_BYTES / 1024 / 1024} MB of attachments`,
+        }, 413),
+    }), async (c) => {
+        const input = await readSendInput(c);
+        if ("error" in input) {
+            return c.json({ error: input.error }, 400);
+        }
+        try {
+            return c.json({ eventId: await hub().send(input.text, input.uploads) }, 202);
+        }
+        catch (err) {
+            if (err instanceof ChatInputError) {
+                return c.json({ error: err.message }, 400);
+            }
+            throw err;
+        }
+    });
+    app.get("/api/files/:eventId/:name", async (c) => {
+        const file = await hub().download(c.req.param("eventId"), c.req.param("name"));
+        if (file === null) {
+            return c.json({ error: "no such file" }, 404);
+        }
+        return sendDownload(file);
+    });
+    app.get("/api/handlers", async (c) => c.json(await hub().handlerPaths()));
+    app.get("/api/events", (c) => streamSSE(c, async (stream) => {
+        // Serialize writes: hub events and keep-alives must not interleave.
+        let queue = Promise.resolve();
+        const send = (event) => {
+            queue = queue
+                .then(() => stream.writeSSE({ event: event.type, data: JSON.stringify(event) }))
+                .catch(() => stream.abort());
+        };
+        const disconnect = hub().addClient(send);
+        stream.onAbort(disconnect);
+        while (!stream.aborted && !stream.closed) {
+            await stream.sleep(KEEP_ALIVE_MS);
+            queue = queue
+                .then(() => stream.write(": keep-alive\n\n"))
+                .then(() => undefined, () => stream.abort());
+        }
+        disconnect();
+    }));
+    app.get("/page/*", (c) => page.handle(c));
+    return app;
+}
+/**
+ * Read the text and attachments of a send request (JSON or multipart).
+ *
+ * @param c Request context.
+ * @returns The input, or an error message for a malformed request.
+ */
+async function readSendInput(c) {
+    const contentType = c.req.header("content-type") ?? "";
+    if (contentType.startsWith("multipart/form-data")) {
+        let body;
+        try {
+            body = await c.req.parseBody({ all: true });
+        }
+        catch {
+            return { error: "malformed multipart body" };
+        }
+        const text = typeof body.text === "string" ? body.text : "";
+        const rawFiles = body.files === undefined ? [] : [body.files].flat();
+        const uploads = [];
+        for (const file of rawFiles) {
+            if (!(file instanceof File)) {
+                return { error: "files must be file parts" };
+            }
+            uploads.push({ name: file.name, contents: Buffer.from(await file.arrayBuffer()) });
+        }
+        return { text, uploads };
+    }
+    let text;
+    try {
+        text = (await c.req.json()).text;
+    }
+    catch {
+        return { error: "expected a JSON body { text } or multipart/form-data" };
+    }
+    if (typeof text !== "string") {
+        return { error: "text must be a string" };
+    }
+    return { text, uploads: [] };
+}
+/**
+ * Stream a scratch file. Only raster images are shown inline; everything
+ * else is a download, served with `nosniff` and a sandboxing CSP, so a
+ * file the assistant or the user put there (HTML, SVG, …) can never run
+ * as a page of this origin.
+ *
+ * @param file The file.
+ * @returns The response (404 when it vanished meanwhile).
+ */
+async function sendDownload(file) {
+    let size;
+    try {
+        size = (await stat(file.path)).size;
+    }
+    catch {
+        return new Response(JSON.stringify({ error: "no such file" }), {
+            status: 404,
+            headers: { "content-type": "application/json" },
+        });
+    }
+    const disposition = file.isInline ? "inline" : "attachment";
+    const asciiName = file.name.replace(/[^\x20-\x7e]|["\\]/g, "_");
+    const stream = Readable.toWeb(createReadStream(file.path));
+    return new Response(stream, {
+        status: 200,
+        headers: {
+            "content-type": file.isInline
+                ? contentTypeForFile(file.name)
+                : "application/octet-stream",
+            "content-length": String(size),
+            "content-disposition": `${disposition}; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(file.name)}`,
+            "x-content-type-options": "nosniff",
+            "content-security-policy": "default-src 'none'; sandbox",
+            "cache-control": "private, max-age=3600",
+        },
+    });
+}

package/build/ChatFiles.d.ts

@@ -0,0 +1,60 @@
+import { type EventFile, type HostContext } from "@getfamiliar/shared";
+import type { ChatFileDto } from "./ChatProtocol.js";
+/**
+ * Bookkeeping file in an event's scratch folder: which files the user
+ * attached (hidden, so neither the model's file listing nor the downloads
+ * show it).
+ */
+export declare const UPLOAD_MANIFEST = ".web-chat-uploads.json";
+/** A file the user attached to a message. */
+export interface ChatUpload {
+    readonly name: string;
+    readonly contents: Buffer;
+}
+/**
+ * Turn a browser-supplied file name into a safe scratch basename: no
+ * path separators or control characters, no leading dots (those are
+ * internal files), at most {@link MAX_NAME_LENGTH} characters with the
+ * extension kept.
+ *
+ * @param raw Name from the upload.
+ * @returns A non-empty basename.
+ */
+export declare function sanitizeUploadName(raw: string): string;
+/**
+ * The event files for a message's uploads: sanitized, de-duplicated names
+ * (`photo.jpg`, `photo-2.jpg`) plus the upload manifest.
+ *
+ * @param uploads The attached files.
+ * @returns Files for `NewEvent.files` and the final names (in input order).
+ */
+export declare function buildUploadFiles(uploads: readonly ChatUpload[]): {
+    files: EventFile[];
+    names: string[];
+};
+/**
+ * Whether a file may be shown inline in the browser.
+ *
+ * @param name File name.
+ * @returns True for raster images.
+ */
+export declare function isInlineImage(name: string): boolean;
+/**
+ * Download URL of an event file.
+ *
+ * @param apiBase Mount of the chat API (`/plugins/web-chat/api`).
+ * @param eventId Event id.
+ * @param name File name.
+ * @returns The URL.
+ */
+export declare function fileUrl(apiBase: string, eventId: string, name: string): string;
+/**
+ * The files of an event for the chat: every visible file of its scratch
+ * folder, marked as upload when the manifest lists it.
+ *
+ * @param scratch Host scratch API.
+ * @param apiBase Mount of the chat API, for the download URLs.
+ * @param eventId Event id.
+ * @returns The files, uploads first, each group by name.
+ */
+export declare function listChatFiles(scratch: Pick<HostContext["scratch"], "listFiles" | "resolveFile">, apiBase: string, eventId: string): Promise<ChatFileDto[]>;

package/build/ChatFiles.js

@@ -0,0 +1,146 @@
+import { readFile } from "node:fs/promises";
+import { isHiddenScratchFile } from "@getfamiliar/shared";
+/**
+ * Bookkeeping file in an event's scratch folder: which files the user
+ * attached (hidden, so neither the model's file listing nor the downloads
+ * show it).
+ */
+export const UPLOAD_MANIFEST = ".web-chat-uploads.json";
+/** Longest file name kept (characters, extension included). */
+const MAX_NAME_LENGTH = 120;
+/** Extensions the browser may show inline (raster images only — no SVG, it can carry script). */
+const INLINE_IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif"]);
+/**
+ * Turn a browser-supplied file name into a safe scratch basename: no
+ * path separators or control characters, no leading dots (those are
+ * internal files), at most {@link MAX_NAME_LENGTH} characters with the
+ * extension kept.
+ *
+ * @param raw Name from the upload.
+ * @returns A non-empty basename.
+ */
+export function sanitizeUploadName(raw) {
+    const base = raw.split(/[/\\]/).pop() ?? "";
+    let name = [...base]
+        .filter((char) => !isControlCharacter(char))
+        .join("")
+        .trim()
+        .replace(/^\.+/, "");
+    if (name === "") {
+        name = "file";
+    }
+    if (name.length > MAX_NAME_LENGTH) {
+        const dot = name.lastIndexOf(".");
+        const extension = dot > 0 && name.length - dot <= 16 ? name.slice(dot) : "";
+        name = name.slice(0, MAX_NAME_LENGTH - extension.length) + extension;
+    }
+    return name;
+}
+/**
+ * Whether a character is an ASCII control character (C0 or DEL).
+ *
+ * @param char One character.
+ * @returns True for control characters.
+ */
+function isControlCharacter(char) {
+    const code = char.codePointAt(0) ?? 0;
+    return code < 0x20 || code === 0x7f;
+}
+/**
+ * The event files for a message's uploads: sanitized, de-duplicated names
+ * (`photo.jpg`, `photo-2.jpg`) plus the upload manifest.
+ *
+ * @param uploads The attached files.
+ * @returns Files for `NewEvent.files` and the final names (in input order).
+ */
+export function buildUploadFiles(uploads) {
+    const taken = new Set();
+    const names = uploads.map((upload) => {
+        const name = sanitizeUploadName(upload.name);
+        let unique = name;
+        for (let counter = 2; taken.has(unique.toLowerCase()); counter++) {
+            const dot = name.lastIndexOf(".");
+            unique =
+                dot > 0
+                    ? `${name.slice(0, dot)}-${counter}${name.slice(dot)}`
+                    : `${name}-${counter}`;
+        }
+        taken.add(unique.toLowerCase());
+        return unique;
+    });
+    if (uploads.length === 0) {
+        return { files: [], names };
+    }
+    const files = uploads.map((upload, index) => ({
+        name: names[index],
+        contents: upload.contents,
+    }));
+    files.push({
+        name: UPLOAD_MANIFEST,
+        contents: Buffer.from(JSON.stringify({ uploads: names })),
+    });
+    return { files, names };
+}
+/**
+ * Whether a file may be shown inline in the browser.
+ *
+ * @param name File name.
+ * @returns True for raster images.
+ */
+export function isInlineImage(name) {
+    const dot = name.lastIndexOf(".");
+    return dot > 0 && INLINE_IMAGE_EXTENSIONS.has(name.slice(dot).toLowerCase());
+}
+/**
+ * Download URL of an event file.
+ *
+ * @param apiBase Mount of the chat API (`/plugins/web-chat/api`).
+ * @param eventId Event id.
+ * @param name File name.
+ * @returns The URL.
+ */
+export function fileUrl(apiBase, eventId, name) {
+    return `${apiBase}/files/${eventId}/${encodeURIComponent(name)}`;
+}
+/**
+ * The files of an event for the chat: every visible file of its scratch
+ * folder, marked as upload when the manifest lists it.
+ *
+ * @param scratch Host scratch API.
+ * @param apiBase Mount of the chat API, for the download URLs.
+ * @param eventId Event id.
+ * @returns The files, uploads first, each group by name.
+ */
+export async function listChatFiles(scratch, apiBase, eventId) {
+    const all = await scratch.listFiles(eventId);
+    const uploads = all.some((file) => file.name === UPLOAD_MANIFEST)
+        ? await readManifest(scratch.resolveFile(eventId, UPLOAD_MANIFEST))
+        : new Set();
+    return all
+        .filter((file) => !isHiddenScratchFile(file.name))
+        .map((file) => ({
+        name: file.name,
+        size: file.size,
+        url: fileUrl(apiBase, eventId, file.name),
+        isImage: isInlineImage(file.name),
+        isUpload: uploads.has(file.name),
+    }))
+        .sort((a, b) => Number(b.isUpload) - Number(a.isUpload) || a.name.localeCompare(b.name));
+}
+/**
+ * Read the upload manifest.
+ *
+ * @param file Host path of the manifest.
+ * @returns The uploaded names (empty for a missing or malformed manifest).
+ */
+async function readManifest(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        return new Set(Array.isArray(parsed.uploads)
+            ? parsed.uploads.filter((name) => typeof name === "string")
+            : []);
+    }
+    catch {
+        return new Set();
+    }
+}

package/build/ChatHub.d.ts

@@ -0,0 +1,205 @@
+import { type HostContext, type Logger, type NewEvent, type ParsedChatInput } from "@getfamiliar/shared";
+import { type ChatUpload } from "./ChatFiles.js";
+import { type ChatFileDto, type ChatHistoryDto, type ChatServerEvent } from "./ChatProtocol.js";
+/** Largest history page the API serves. */
+export declare const MAX_HISTORY_PAGE = 100;
+/** The handler catalog operations the hub needs (`HandlerCatalog` from shared). */
+export interface ChatHandlerCatalog {
+    list(): Promise<readonly {
+        readonly slashPath: string;
+    }[]>;
+    resolve(topic: string, options: {
+        readonly isExactTopic: boolean;
+    }): Promise<unknown | null>;
+}
+/** What the hub needs from the host. */
+export interface ChatHubDeps {
+    readonly chat: HostContext["chat"];
+    readonly events: HostContext["events"];
+    readonly handlers: ChatHandlerCatalog;
+    readonly scratch: Pick<HostContext["scratch"], "listFiles" | "resolveFile">;
+    /** Mount of the chat API (`/plugins/web-chat/api`), for download URLs. */
+    readonly apiBase: string;
+    readonly log: Logger;
+}
+/** A file to stream to the browser. */
+export interface ChatDownload {
+    /** Host path. */
+    readonly path: string;
+    readonly name: string;
+    /** Whether it may be shown inline (raster image). */
+    readonly isInline: boolean;
+}
+/** A browser connection receiving server events. */
+export type ChatClient = (event: ChatServerEvent) => void;
+/** A user input the hub refuses (answered with 400). */
+export declare class ChatInputError extends Error {
+    constructor(message: string);
+}
+/**
+ * The web chat's server side: one subscription to the chat bus for the
+ * `web` channel, fanned out to every connected browser tab (the bus marks
+ * a row delivered once, so tabs must not subscribe individually), plus
+ * sending user input as events and tracking their progress.
+ *
+ * Mirrors cli-chat: plain messages go to `chat:web`, `/topic/sub …` lines
+ * are direct handler calls (validated against the workspace), events are
+ * `privileged` (only allowlisted users reach the web UI), failures are
+ * written to the chat, and a direct call that produced no chat reply gets
+ * its result text appended as the reply.
+ *
+ * Files: attachments of a message are staged into the event's scratch
+ * folder (with a hidden manifest marking them as uploads); every visible
+ * file in that folder is offered for download in the chat — the
+ * attachments at the user's message, everything else under the reply.
+ */
+export declare class ChatHub {
+    private readonly deps;
+    private readonly clients;
+    private readonly turns;
+    /** Events of in-flight turns that already got an assistant message. */
+    private readonly answeredEvents;
+    private readonly retentionTimers;
+    private unsubscribe;
+    /**
+     * @param deps Host services.
+     */
+    constructor(deps: ChatHubDeps);
+    /**
+     * Subscribe to the `web` channel. Undelivered messages replayed by the
+     * bus are broadcast like live ones (there is nobody to show them to
+     * yet, so assistant messages stay undelivered until a tab is open).
+     */
+    start(): Promise<void>;
+    /** Drop the subscription, the turns and every client. */
+    stop(): Promise<void>;
+    /**
+     * Connect a browser tab. It first receives a snapshot of the turns in
+     * flight, then every event.
+     *
+     * @param client Event sink of the connection.
+     * @returns Disconnect function.
+     */
+    addClient(client: ChatClient): () => void;
+    /**
+     * One page of the web channel's history.
+     *
+     * @param beforeId Cursor (message id) or undefined for the newest page.
+     * @param limit Page size, 1 … {@link MAX_HISTORY_PAGE}.
+     * @returns The page and whether older messages exist.
+     */
+    history(beforeId: string | undefined, limit: number): Promise<ChatHistoryDto>;
+    /**
+     * Slash paths for autocompletion.
+     *
+     * @returns Handler paths and the page's builtins.
+     */
+    handlerPaths(): Promise<{
+        handlers: string[];
+        builtins: string[];
+    }>;
+    /**
+     * Send one typed line, with optional attachments, as an event.
+     *
+     * @param text The line (may be empty when files are attached).
+     * @param uploads Attached files, staged into the event's scratch folder.
+     * @returns The event id.
+     * @throws {ChatInputError} For an empty message, a builtin (handled by
+     *   the page), an unknown handler path or too many / too large files.
+     */
+    send(text: string, uploads?: readonly ChatUpload[]): Promise<string>;
+    /**
+     * The visible files of an event (see {@link listChatFiles}).
+     *
+     * @param eventId Event id.
+     * @returns The files; empty when listing fails (logged).
+     */
+    filesOf(eventId: string): Promise<ChatFileDto[]>;
+    /**
+     * Locate a visible file of an event for download.
+     *
+     * @param eventId Event id (digits).
+     * @param name File name.
+     * @returns The file, or null when it is unknown, hidden or not a file.
+     */
+    download(eventId: string, name: string): Promise<ChatDownload | null>;
+    /**
+     * List an event's files and broadcast them (after a reply or when its
+     * turn finished — the assistant may have produced files).
+     *
+     * @param eventId Event id.
+     */
+    private broadcastFiles;
+    /**
+     * Bus handler: broadcast the message. User rows count as delivered
+     * (they came from the user); assistant rows only when a tab shows them.
+     *
+     * @param message The stored message.
+     * @returns Whether to mark it delivered.
+     */
+    private onChatMessage;
+    /**
+     * Record an agentrun state change of a turn.
+     *
+     * @param turn The turn.
+     * @param row The agentrun row.
+     */
+    private onAgentRun;
+    /**
+     * Record a finished step of a turn.
+     *
+     * @param turn The turn.
+     * @param step The step row.
+     */
+    private onStep;
+    /**
+     * The event finished: append the result text as the reply when the
+     * run produced no chat message (direct calls to non-chat handlers).
+     *
+     * @param turn The turn.
+     * @param resultText Result text of the last agentrun.
+     */
+    private onSettled;
+    /**
+     * The event failed (the host already wrote the failure to the chat).
+     *
+     * @param turn The turn.
+     * @param err The rejection.
+     */
+    private onFailed;
+    /**
+     * Mark a turn finished, broadcast it, and drop it after the retention time.
+     *
+     * @param turn The turn.
+     * @param state Final state.
+     * @param error Failure text or null.
+     */
+    private finishTurn;
+    /**
+     * Broadcast a turn's full state (once its event id is known).
+     *
+     * @param turn The turn.
+     */
+    private broadcastTurn;
+    /**
+     * Send an event to every connected tab. A failing client is dropped.
+     *
+     * @param event The event.
+     */
+    private broadcast;
+}
+/**
+ * The event for one typed line, as cli-chat builds it: plain messages are
+ * chat events on `chat:web`; direct handler calls are exact-topic runs
+ * whose typed line is stored as the user message.
+ *
+ * Attachments are named in the text, so the transcript (and the model's
+ * chat history) records them even when the line itself is empty.
+ *
+ * @param parsed The parsed line.
+ * @param attachmentNames Names of the attached files (staged separately).
+ * @returns The event (without `files`).
+ */
+export declare function buildNewEvent(parsed: Extract<ParsedChatInput, {
+    kind: "handler";
+}>, attachmentNames?: readonly string[]): NewEvent;