fauna-api 0.0.0-stage → 1.0.679

package/dist/src/parrot/room.d.ts

@@ -0,0 +1,225 @@
+import { Credentials, ApiKey, Profile } from "../authentification.js";
+import { Function, Role, Tool } from "./generative.js";
+import { Room, Presence, Authorization } from "../shared/server.js";
+import { ChatTarget, AppendResult, Attachment } from "./share.js";
+import type { Repository } from "../termite/versioning.js";
+import type { Group } from "../groups.js";
+export { Attachment } from "./share.js";
+/**
+ * One durable message in a room transcript. Parts keep their file refs as
+ * streaming `FaunaFile`s (no bytes over the socket) — `download()` them when you
+ * need the bytes. `author` is the sender's public Profile (USER turns only).
+ */
+export type RoomMessage = {
+    id: string;
+    position: number;
+    role: Role;
+    parts: any[];
+    author?: Profile;
+    replyTo?: string;
+    /** LLM id that produced a MODEL turn (for UI avatar / rehydrate). */
+    model?: string;
+    created: number;
+    /** The name of the API key an agent posted this with, for its author. */
+    via?: string;
+};
+/**
+ * One buffered send in the shared room queue. When a member sends while the
+ * model is replying, it lands here (visible to all members) instead of the
+ * transcript, and drains FIFO into the transcript as replies complete. `id` is
+ * the stable per-row key used for unqueue/steer targeting and orders the queue.
+ */
+export type RoomQueueItem = {
+    id: string;
+    role: Role;
+    parts: any[];
+    author?: Profile;
+    model?: string;
+    reasoning?: string;
+    replyTo?: string;
+    created: number;
+};
+export type RoomToolState = {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    status: "running" | "success" | "error";
+    result?: string;
+    /** What a running tool is waiting on, like the machine starting. */
+    progress?: string;
+    /** The live room the tool opened, to watch it: a browser, or a machine's desktop, by access code. */
+    session?: {
+        kind: "browser" | "desktop";
+        code: string;
+        url?: string;
+    };
+};
+export type RoomHooks = Partial<{
+    /** A new message landed (any member's send, or the server's model reply). */
+    onMessage(room: ChatRoom, message: RoomMessage): void;
+    /** The shared queue changed (an item was buffered, released, or unqueued). */
+    onQueue(room: ChatRoom): void;
+    /** The room's model reply started (true) or finished (false). */
+    onThinking(room: ChatRoom, thinking: boolean): void;
+    /** The room's model reply is streaming. `text` is the full reply so far;
+     *  `delta` is the new portion since the last call. Fires as the reply grows.
+     *  When the turn finishes, the finished reply also arrives via `onMessage` (a
+     *  durable row). `aborted` is true on the terminal call — the streamed turn
+     *  finalized or was cancelled; drop the partial and rely on `onMessage`.
+     *  `files` are what the reply attached so far. */
+    onDelta(room: ChatRoom, turn: string, delta: string, text: string, aborted: boolean, tools: RoomToolState[], files: Attachment[]): void;
+    /** Originator-only client tool call (evaluate locally, then sendToolResult). */
+    onToolCall(room: ChatRoom, call: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+        turn?: string;
+    }): void;
+    /** The chat was renamed. */
+    onRenamed(room: ChatRoom, name: string): void;
+    /** The chat's repository was attached, swapped or detached. */
+    onRepository(room: ChatRoom): void;
+    /** The reply pointed everyone to a file (Parrot's `open`): show it. */
+    onOpenFile(room: ChatRoom, attachment: Attachment): void;
+    /** The chat was deleted/closed by its owner (or the host disconnected). */
+    onClosed(room: ChatRoom): void;
+    /** The roster changed (someone joined/left or updated presence/status). */
+    onPresence(room: ChatRoom): void;
+}>;
+export declare class ChatRoom extends Room {
+    private messages;
+    private queue;
+    private _thinking;
+    private clientTools;
+    private _name;
+    private _systemPrompt;
+    private _human;
+    private _repository;
+    private _owner;
+    private _reference;
+    private hooks;
+    private target;
+    private _hasMore;
+    private streaming;
+    constructor(ws: WebSocket, authorization: Authorization, id: string, target: ChatTarget, hooks: RoomHooks);
+    /** The currently-loaded transcript window, in order. */
+    getMessages(): RoomMessage[];
+    /** The current shared queue (buffered sends), in FIFO order. */
+    getQueue(): RoomQueueItem[];
+    /** The chat's name. */
+    getName(): string;
+    /** Room system prompt (not a transcript row). Empty when unset. */
+    getSystemPrompt(): string;
+    /** True for a people only chat: no model ever replies, so sends never queue. */
+    isHuman(): boolean;
+    /** The chat's repository, by id. Kept current for everyone in the room. */
+    get repository(): number | null;
+    /** The saved chat this room is bound to, by id, or null for an unbound room. */
+    get chatId(): string | null;
+    /** Who owns the chat: `credentials:{id}`, `group:{id}`, `friend:{id}` or `partnership:{id}`. Empty for an unbound room. */
+    get owner(): string;
+    /** The group that owns the chat, whose repositories it takes; undefined for anyone else's. */
+    get group(): Group | undefined;
+    /** Attach a repository, or null to detach. Everyone in the room sees the change. */
+    setRepository(repository: Repository | null): Promise<void>;
+    private readonly repositoryWatchers;
+    /** Hear about every repository change, from anyone in the room. Returns a function that stops listening. */
+    watchRepository(listener: (repository: number | null) => void): () => void;
+    /** Every file in the chat, newest first: what people attached and what Parrot opened. */
+    attachments(): Promise<Attachment[]>;
+    /** True while the server is streaming the room's model reply. */
+    isThinking(): boolean;
+    /** True while older transcript pages remain to be loaded (scroll-up). */
+    hasMore(): boolean;
+    /** The in-progress streamed model reply, or null when none is streaming. */
+    streamingReply(): {
+        turn: string;
+        text: string;
+        tools: RoomToolState[];
+        files: Attachment[];
+    } | null;
+    /**
+     * Send the reply under way (thinking, and the streamed turn so far) to the hooks
+     * again, for a UI that sets its hooks after connecting in the middle of a reply.
+     */
+    replayReply(): void;
+    /**
+     * Load one older page of transcript messages and merge it into the window by
+     * position. The cursor is how many messages are already loaded, counted from
+     * the newest, so live messages that arrived since connect keep it correct.
+     * File parts stream lazily via their `FaunaFile`s.
+     */
+    loadOlder(): Promise<RoomMessage[]>;
+    /**
+     * Append a message to the shared transcript. USER sends are attributed to
+     * the caller and nudge the server's debounced model reply. If the room is
+     * currently replying the server buffers the send into the shared queue
+     * instead (drained FIFO when the reply finishes); the result says which
+     * happened. File parts stream their bytes with the message. `model`
+     * (optional) is the sender's selected model — the reply uses the last
+     * sender's choice.
+     */
+    sendMessage(role: Role, parts: any[], options?: {
+        replyTo?: string;
+        model?: string;
+        reasoning?: string;
+        /** Function schemas (array = available; singular = force that tool). */
+        tools?: Function | Function[];
+    }): Promise<AppendResult>;
+    /**
+     * React to the message at transcript `position`. A reaction is its own USER
+     * message (so in a chat with a model it prompts a reply like any send);
+     * `on: false` takes it back.
+     */
+    react(position: number, emoji: string, on?: boolean): Promise<AppendResult>;
+    /** Reply to a client tool_call addressed to this originator. */
+    sendToolResult(callId: string, result: string): void;
+    /**
+     * Register Tool.evaluate handlers for originator-only room tool calls.
+     * When a chat-tool-call arrives, matching tools auto-evaluate and reply.
+     */
+    setClientTools(tools: Tool[] | Tool | undefined): void;
+    /**
+     * Remove one of your buffered messages from the shared queue. It never
+     * entered the transcript, so this is not an unsend — the server just drops
+     * the queue row and it fans out to every member.
+     */
+    unqueue(queueId: string): Promise<void>;
+    /**
+     * Steer the room: stop the in-progress model reply now and have the server
+     * re-answer after the normal debounce window. Any member may steer.
+     * `queueId` releases just that one queued row into the transcript first
+     * (per-item steer); `all` flushes the whole queue in FIFO order (steer-all).
+     * Released rows behave like idle sends — the model does NOT reply immediately.
+     * `stop` cancels the current reply without scheduling a new one.
+     */
+    steer(options?: {
+        queueId?: string;
+        all?: boolean;
+        stop?: boolean;
+        model?: string;
+        reasoning?: string;
+    }): Promise<void>;
+    /** Replace/merge the room's event hooks after connection (e.g. once the UI
+     *  that owns rendering is ready). Later hooks override earlier ones. */
+    setHooks(hooks: RoomHooks): void;
+    /** Fire onClosed using the latest hooks (setHooks), not the connect-time snapshot. */
+    emitClosed(): void;
+    /** Broadcast this member's typing state to the room (presence status). */
+    setTyping(self: Presence, typing: boolean): void;
+    /** Members currently marked as typing (excludes the given self presence). */
+    typingPresences(self?: Presence): Presence[];
+    hydrate(state: any): void;
+    handleEvent(packet: any): boolean;
+}
+/**
+ * Connect to a live room as a `ChatRoom`. `target` is an access code or a room
+ * reference (`parrot:chat:{chatId}` / `parrot:room:{uuid}`). Resolves with the
+ * room and the caller's own `Presence` (use it to broadcast typing + position).
+ * The connection snapshot carries only the last transcript window; scroll-up
+ * backfill goes through `room.loadOlder()`.
+ */
+export declare function connectRoom(authorization: Credentials | ApiKey, target: ChatTarget, hooks?: RoomHooks): Promise<{
+    room: ChatRoom;
+    self: Presence;
+}>;

package/dist/src/parrot/room.js

@@ -0,0 +1,466 @@
+import { Role } from "./generative.js";
+import { Room, Presence, connect } from "../shared/server.js";
+import { Parrot } from "./index.js";
+import { appendRoomMessage, steerRoom, unqueueRoomMessage, pageMessages, setRoomRepository, listRoomAttachments, Attachment, } from "./share.js";
+export { Attachment } from "./share.js";
+/**
+ * A live, domain-agnostic chat room. `ChatRoom extends Room` and owns everything
+ * chat-transcript-specific: a WINDOWED transcript (the last page hydrated on
+ * connect), `loadOlder()` pagination for scroll-up backfill, the shared
+ * queue, and the streamed model reply. It is NOT tied to a durable "chat" —
+ * Parrot, Extensions.Web, and Marmot's chat side all reuse it. The generic
+ * `Room` stays domain-agnostic (presence + deltas) for non-chat rooms.
+ *
+ * Sends go through the append edge (so file parts stream) and the server owns
+ * turn-taking — once the room goes quiet it streams one model reply over the
+ * whole transcript, billed to the room's host principal.
+ */
+const OLDER_PAGE = 20;
+export class ChatRoom extends Room {
+    constructor(ws, authorization, id, target, hooks) {
+        // generateAccessCode → POST `${endpoint}/access-code` (mountRoom base).
+        super(`${Parrot.getURL()}/chat/live`, ws, authorization, id);
+        Object.defineProperty(this, "messages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "_thinking", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "clientTools", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "_name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ""
+        });
+        Object.defineProperty(this, "_systemPrompt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ""
+        });
+        Object.defineProperty(this, "_human", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "_repository", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "_owner", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ""
+        });
+        Object.defineProperty(this, "_reference", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ""
+        });
+        Object.defineProperty(this, "hooks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "target", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_hasMore", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        // The current streamed model turn so far (by turn id).
+        Object.defineProperty(this, "streaming", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "repositoryWatchers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        this.target = target;
+        this.hooks = hooks;
+    }
+    /** The currently-loaded transcript window, in order. */
+    getMessages() {
+        return this.messages;
+    }
+    /** The current shared queue (buffered sends), in FIFO order. */
+    getQueue() {
+        return this.queue;
+    }
+    /** The chat's name. */
+    getName() {
+        return this._name;
+    }
+    /** Room system prompt (not a transcript row). Empty when unset. */
+    getSystemPrompt() {
+        return this._systemPrompt;
+    }
+    /** True for a people only chat: no model ever replies, so sends never queue. */
+    isHuman() {
+        return this._human;
+    }
+    /** The chat's repository, by id. Kept current for everyone in the room. */
+    get repository() {
+        return this._repository;
+    }
+    /** The saved chat this room is bound to, by id, or null for an unbound room. */
+    get chatId() {
+        const match = /^parrot:chat:(\d+)$/.exec(this._reference);
+        return match ? match[1] : null;
+    }
+    /** Who owns the chat: `credentials:{id}`, `group:{id}`, `friend:{id}` or `partnership:{id}`. Empty for an unbound room. */
+    get owner() {
+        return this._owner;
+    }
+    /** The group that owns the chat, whose repositories it takes; undefined for anyone else's. */
+    get group() {
+        const match = /^group:(\d+)$/.exec(this._owner);
+        return match ? { id: match[1] } : undefined;
+    }
+    /** Attach a repository, or null to detach. Everyone in the room sees the change. */
+    async setRepository(repository) {
+        await setRoomRepository(this.getAuthorization(), this.target, repository ? repository.id : null);
+    }
+    /** Hear about every repository change, from anyone in the room. Returns a function that stops listening. */
+    watchRepository(listener) {
+        this.repositoryWatchers.add(listener);
+        return () => { this.repositoryWatchers.delete(listener); };
+    }
+    /** Every file in the chat, newest first: what people attached and what Parrot opened. */
+    async attachments() {
+        return await listRoomAttachments(this.getAuthorization(), this.target);
+    }
+    /** True while the server is streaming the room's model reply. */
+    isThinking() {
+        return this._thinking;
+    }
+    /** True while older transcript pages remain to be loaded (scroll-up). */
+    hasMore() {
+        return this._hasMore;
+    }
+    /** The in-progress streamed model reply, or null when none is streaming. */
+    streamingReply() {
+        return this.streaming;
+    }
+    /**
+     * Send the reply under way (thinking, and the streamed turn so far) to the hooks
+     * again, for a UI that sets its hooks after connecting in the middle of a reply.
+     */
+    replayReply() {
+        if (this._thinking)
+            this.hooks.onThinking?.(this, true);
+        const s = this.streaming;
+        if (s)
+            this.hooks.onDelta?.(this, s.turn, s.text, s.text, false, s.tools, s.files);
+    }
+    /**
+     * Load one older page of transcript messages and merge it into the window by
+     * position. The cursor is how many messages are already loaded, counted from
+     * the newest, so live messages that arrived since connect keep it correct.
+     * File parts stream lazily via their `FaunaFile`s.
+     */
+    async loadOlder() {
+        const page = await pageMessages(this.getAuthorization(), this.target, { cursor: this.messages.length, max: OLDER_PAGE });
+        const known = new Set(this.messages.map((m) => m.position));
+        const older = page
+            .filter((m) => !known.has(m.position))
+            .map((m) => ({
+            id: m.id,
+            position: m.position,
+            role: m.role,
+            parts: m.parts,
+            author: m.author,
+            replyTo: m.replyTo,
+            model: m.model,
+            created: m.created,
+            ...(m.via ? { via: m.via } : {}),
+        }));
+        this.messages = [...older, ...this.messages].sort((a, b) => a.position - b.position);
+        this._hasMore = page.length === OLDER_PAGE;
+        return older;
+    }
+    /**
+     * Append a message to the shared transcript. USER sends are attributed to
+     * the caller and nudge the server's debounced model reply. If the room is
+     * currently replying the server buffers the send into the shared queue
+     * instead (drained FIFO when the reply finishes); the result says which
+     * happened. File parts stream their bytes with the message. `model`
+     * (optional) is the sender's selected model — the reply uses the last
+     * sender's choice.
+     */
+    async sendMessage(role, parts, options = {}) {
+        return await appendRoomMessage(this.getAuthorization(), this.target, { role, parts, createdAt: new Date() }, options);
+    }
+    /**
+     * React to the message at transcript `position`. A reaction is its own USER
+     * message (so in a chat with a model it prompts a reply like any send);
+     * `on: false` takes it back.
+     */
+    async react(position, emoji, on = true) {
+        const reaction = { type: 'REACTION', emoji, position, on };
+        return await this.sendMessage(Role.USER, [reaction]);
+    }
+    /** Reply to a client tool_call addressed to this originator. */
+    sendToolResult(callId, result) {
+        this.post({ event: "tool-result", id: callId, result });
+    }
+    /**
+     * Register Tool.evaluate handlers for originator-only room tool calls.
+     * When a chat-tool-call arrives, matching tools auto-evaluate and reply.
+     */
+    setClientTools(tools) {
+        this.clientTools = !tools ? [] : Array.isArray(tools) ? tools : [tools];
+    }
+    /**
+     * Remove one of your buffered messages from the shared queue. It never
+     * entered the transcript, so this is not an unsend — the server just drops
+     * the queue row and it fans out to every member.
+     */
+    async unqueue(queueId) {
+        await unqueueRoomMessage(this.getAuthorization(), this.target, queueId);
+    }
+    /**
+     * Steer the room: stop the in-progress model reply now and have the server
+     * re-answer after the normal debounce window. Any member may steer.
+     * `queueId` releases just that one queued row into the transcript first
+     * (per-item steer); `all` flushes the whole queue in FIFO order (steer-all).
+     * Released rows behave like idle sends — the model does NOT reply immediately.
+     * `stop` cancels the current reply without scheduling a new one.
+     */
+    async steer(options = {}) {
+        await steerRoom(this.getAuthorization(), this.target, options);
+    }
+    /** Replace/merge the room's event hooks after connection (e.g. once the UI
+     *  that owns rendering is ready). Later hooks override earlier ones. */
+    setHooks(hooks) {
+        this.hooks = { ...this.hooks, ...hooks };
+    }
+    /** Fire onClosed using the latest hooks (setHooks), not the connect-time snapshot. */
+    emitClosed() {
+        // Drop local roster so a remounted widget cannot paint stale peers.
+        this.presences.length = 0;
+        this.hooks.onClosed?.(this);
+    }
+    /** Broadcast this member's typing state to the room (presence status). */
+    setTyping(self, typing) {
+        self.setStatus(typing ? "typing" : "");
+    }
+    /** Members currently marked as typing (excludes the given self presence). */
+    typingPresences(self) {
+        return this.presences.filter((p) => p !== self && p.status === "typing");
+    }
+    // ── internal: hydration + event routing (called by connectRoom) ──────────
+    hydrate(state) {
+        this._name = state?.chat?.name ?? "";
+        this._systemPrompt = typeof state?.chat?.systemPrompt === "string" ? state.chat.systemPrompt : "";
+        this._human = state?.chat?.human === true;
+        this._repository = typeof state?.chat?.repository === "number" && state.chat.repository > 0 ? state.chat.repository : null;
+        this._owner = typeof state?.chat?.owner === "string" ? state.chat.owner : "";
+        this._reference = typeof state?.room?.reference === "string" ? state.room.reference : "";
+        this.messages = Array.isArray(state?.messages) ? [...state.messages] : [];
+        this.queue = Array.isArray(state?.queue) ? [...state.queue] : [];
+        this._hasMore = Boolean(state?.hasMore);
+        this._thinking = state?.thinking === true;
+        const stream = state?.stream;
+        this.streaming = stream && typeof stream.turn === "string" && stream.turn
+            ? {
+                turn: stream.turn,
+                text: String(stream.text ?? ""),
+                tools: Array.isArray(stream.tools) ? stream.tools : [],
+                files: (Array.isArray(stream.files) ? stream.files : []).map((raw) => Attachment.fromJSON(raw, this.getAuthorization())),
+            }
+            : null;
+    }
+    handleEvent(packet) {
+        switch (packet.event) {
+            case "chat-message": {
+                const message = packet.data?.message;
+                if (!message)
+                    return true;
+                if (!this.messages.some((m) => m.id === message.id)) {
+                    this.messages.push(message);
+                    this.messages.sort((a, b) => a.position - b.position);
+                }
+                // A MODEL row finalizes any in-progress streamed turn.
+                if (message.role === Role.MODEL)
+                    this.streaming = null;
+                this.hooks.onMessage?.(this, message);
+                return true;
+            }
+            case "chat-queue-add": {
+                const item = packet.data?.item;
+                if (!item)
+                    return true;
+                if (!this.queue.some((q) => q.id === item.id)) {
+                    this.queue.push(item);
+                    this.queue.sort((a, b) => Number(BigInt(a.id) - BigInt(b.id)));
+                }
+                this.hooks.onQueue?.(this);
+                return true;
+            }
+            case "chat-queue-remove": {
+                const id = String(packet.data?.id ?? "");
+                if (!id)
+                    return true;
+                this.queue = this.queue.filter((q) => q.id !== id);
+                this.hooks.onQueue?.(this);
+                return true;
+            }
+            case "chat-delta": {
+                // The server streams the in-progress reply as full text (fans out
+                // to every replica). Compute the delta against what we last saw so
+                // callers can append incrementally.
+                const turn = String(packet.data?.turn ?? "");
+                const text = String(packet.data?.text ?? "");
+                if (!turn)
+                    return true;
+                if (!this.streaming || this.streaming.turn !== turn) {
+                    this.streaming = { turn, text: "", tools: [], files: [] };
+                }
+                const prev = this.streaming.text;
+                const delta = text.startsWith(prev) ? text.slice(prev.length) : text;
+                const tools = Array.isArray(packet.data?.tools) ? packet.data.tools : [];
+                const files = (Array.isArray(packet.data?.files) ? packet.data.files : [])
+                    .map((raw) => Attachment.fromJSON(raw, this.getAuthorization()));
+                this.streaming = { turn, text, tools, files };
+                this.hooks.onDelta?.(this, turn, delta, text, false, tools, files);
+                return true;
+            }
+            case "chat-delta-done": {
+                // The stream row was cleared: the turn finalized (a durable
+                // chat-message follows) or aborted. Either way, drop the partial —
+                // the transcript's MODEL row (if any) is authoritative.
+                const turn = String(packet.data?.turn ?? "");
+                if (this.streaming && (!turn || this.streaming.turn === turn)) {
+                    const text = this.streaming.text;
+                    const doneTurn = this.streaming.turn;
+                    this.streaming = null;
+                    this.hooks.onDelta?.(this, doneTurn, "", text, true, [], []);
+                }
+                return true;
+            }
+            case "chat-status": {
+                this._thinking = Boolean(packet.data?.thinking);
+                this.hooks.onThinking?.(this, this._thinking);
+                return true;
+            }
+            case "chat-renamed": {
+                this._name = packet.data?.name ?? this._name;
+                this.hooks.onRenamed?.(this, this._name);
+                return true;
+            }
+            case "chat-repository": {
+                const name = typeof packet.data?.name === "string" ? packet.data.name : this._name;
+                if (name !== this._name) {
+                    this._name = name;
+                    this.hooks.onRenamed?.(this, name);
+                }
+                const raw = packet.data?.repository;
+                const repository = typeof raw === "number" && raw > 0 ? raw : null;
+                if (repository !== this._repository) {
+                    this._repository = repository;
+                    this.hooks.onRepository?.(this);
+                    for (const listener of this.repositoryWatchers)
+                        listener(repository);
+                }
+                return true;
+            }
+            case "chat-open-file": {
+                const raw = packet.data?.attachment;
+                if (raw)
+                    this.hooks.onOpenFile?.(this, Attachment.fromJSON(raw, this.getAuthorization()));
+                return true;
+            }
+            case "chat-tool-call": {
+                const id = String(packet.data?.id ?? packet.id ?? "");
+                const name = String(packet.data?.name ?? packet.name ?? "");
+                const args = (packet.data?.args ?? packet.args ?? {});
+                const turn = packet.data?.turn ? String(packet.data.turn) : undefined;
+                if (!id || !name)
+                    return true;
+                const tool = this.clientTools.find((t) => t.function.name === name);
+                if (tool) {
+                    void tool.evaluate(args).then((result) => this.sendToolResult(id, result), (err) => {
+                        console.error("[chat] tool failed", name, err);
+                        this.sendToolResult(id, `Error: ${err?.message ?? String(err)}`);
+                    });
+                }
+                else {
+                    this.hooks.onToolCall?.(this, { id, name, args, turn });
+                }
+                return true;
+            }
+            case "chat-closed":
+            case "server-closed": {
+                this.emitClosed();
+                return true;
+            }
+            default:
+                return false;
+        }
+    }
+}
+/**
+ * Connect to a live room as a `ChatRoom`. `target` is an access code or a room
+ * reference (`parrot:chat:{chatId}` / `parrot:room:{uuid}`). Resolves with the
+ * room and the caller's own `Presence` (use it to broadcast typing + position).
+ * The connection snapshot carries only the last transcript window; scroll-up
+ * backfill goes through `room.loadOlder()`.
+ */
+export async function connectRoom(authorization, target, hooks = {}) {
+    const auth = "code" in target
+        ? { authorization, accessCode: target.code }
+        : { authorization, server: target.reference };
+    let created;
+    const self = await connect(auth, `${Parrot.getURL()}/chat/live`, {
+        createRoom: (_endpoint, ws, a, id) => {
+            created = new ChatRoom(ws, a, id, target, hooks);
+            return created;
+        },
+        onConnection: (room, state) => {
+            room.hydrate(state);
+        },
+        onEvent: (room, packet) => room.handleEvent(packet),
+        // Use ChatRoom.emitClosed so setHooks(onClosed) after UI mount is honored.
+        onClosed: (room) => room.emitClosed(),
+        createPresence: (room, data) => new Presence(room, data.id, data.profile),
+        onPresence: (room) => hooks.onPresence?.(room),
+    });
+    hooks.onPresence?.(created);
+    return { room: created, self };
+}